# TypeScript SDK

The HQ API for TypeScript and JavaScript, with retries, idempotency, a resumable event stream and webhook verification built in.



<Callout title="Not published yet">
  The package is not on npm yet; this page shows how it will work. Until it is, call the API with
  `fetch` as in the [quickstart](/docs/api/quickstart/).
</Callout>

`@aiworkforceoneofficial/hq-sdk` runs on Node 20+, Deno, Bun and workers, with no runtime
dependencies.

```bash
npm install @aiworkforceoneofficial/hq-sdk
```

## Authenticate [#authenticate]

```ts
import { HQ } from '@aiworkforceoneofficial/hq-sdk';

const hq = new HQ({ apiKey: process.env.HQ_API_KEY });
```

`apiKey` takes an [API key](/docs/api/authentication/) or an [OAuth app](/docs/api/oauth/)'s access
token. Without it, the SDK reads `HQ_API_KEY`. Each client pins the `HQ-Version` the SDK was built
for; pass `apiVersion` to pin another.

## Send a prompt and stream the reply [#send-a-prompt-and-stream-the-reply]

```ts
const session = await hq.sessions.create('team_3kQ9…', { engine: 'claude', run_with: 'team_key' });
await hq.sessions.messages.create(session.id!, {
  content: [{ type: 'text', text: 'Summarise open PRs in /data/repo' }],
});
for await (const ev of hq.sessions.stream(session.id!)) {
  if (ev.type === 'session.message.completed') console.log(ev.data);
  if (ev.type === 'session.turn.completed') break;
}
```

## What it does for you [#what-it-does-for-you]

**Retries.** A `429`, a `5xx` or a dropped connection is retried with backoff (`maxRetries`, default
2\), honouring `Retry-After`. A `421` is retried once at once. Any other `4xx` is thrown at once.

**Idempotency.** Every write carries an `Idempotency-Key`, the same one across its own retries, so a
retry never sends a prompt twice or resizes a machine twice. Pass `{ idempotencyKey }` to use yours.

**Errors.** A refusal throws an `HQError` with the stable [`code`](/docs/api/errors/), the `status`,
the `detail` and the `requestId`:

```ts
import { HQError } from '@aiworkforceoneofficial/hq-sdk';

try {
  await hq.sessions.create('team_3kQ9…', { run_with: 'team_key' });
} catch (err) {
  if (err instanceof HQError && err.code === 'permission_denied') console.log(err.permission);
  else throw err;
}
```

**Streaming.** `sessions.stream(id)` yields each [event](/docs/api/streaming/) once, resumes with
`Last-Event-ID` across `stream.rotate` and dropped connections, and yields `stream.reset` when you
should re-list the session's items. Pass `{ signal }` to stop it.

**Operations.** A Cloud Computer change answers an [operation](/docs/api/operations/);
`operations.wait(op)` polls it until it settles, honouring `Retry-After`:

```ts
const op = await hq.computer.resize('team_3kQ9…', { tier: 'boost' });
if (op.object === 'operation') await hq.operations.wait(op);
```

**Pagination.** `teams.list()` and `sessions.list()` are async iterators over every page.

**Webhooks.** Verify a delivery with the raw body:

```ts
const event = await HQ.webhooks.verify(rawBody, req.headers, process.env.HQ_WEBHOOK_SECRET!);
```

**Everything else.** `hq.call('operationId', { path_param: '…' }, { query, body })` reaches any
endpoint in the [reference](/docs/api/reference/), and every schema is exported as a type.
