TypeScript SDK
The HQ API for TypeScript and JavaScript, with retries, idempotency, a resumable event stream and webhook verification built in.
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.
@aiworkforceoneofficial/hq-sdk runs on Node 20+, Deno, Bun and workers, with no runtime
dependencies.
npm install @aiworkforceoneofficial/hq-sdkAuthenticate
import { HQ } from '@aiworkforceoneofficial/hq-sdk';
const hq = new HQ({ apiKey: process.env.HQ_API_KEY });apiKey takes an API key or an OAuth app'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
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
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, the status,
the detail and the requestId:
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 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;
operations.wait(op) polls it until it settles, honouring Retry-After:
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:
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, and every schema is exported as a type.