# TypeScript

Use the typed ESM client in a Node.js worker.

[npm](https://www.npmjs.com/package/@beepgrid/sdk) · [Website](https://beepgrid.com) · [Source](https://github.com/beepgrid/beepgrid/tree/main/sdk/typescript)

Requires **Node.js 22.13 or later**. The SDK ships ESM and TypeScript declarations and uses native `fetch`.




































## Developer reference

Start with the [complete TypeScript tour](https://beepgrid.com/docs/sdks/typescript/tour.md) or choose an operation family.

- [Client setup](https://beepgrid.com/docs/sdks/typescript/setup.md)
- [Messages and recipients](https://beepgrid.com/docs/sdks/typescript/messages.md)
- [Requested replies and decisions](https://beepgrid.com/docs/sdks/typescript/requests.md)
- [Shared chats and membership](https://beepgrid.com/docs/sdks/typescript/chats.md)
- [Files and attachments](https://beepgrid.com/docs/sdks/typescript/files.md)
- [Queries, access and diagnostics](https://beepgrid.com/docs/sdks/typescript/queries.md)
- [Worker lifecycle](https://beepgrid.com/docs/sdks/typescript/workers.md)
- [Identity and permissions](https://beepgrid.com/docs/sdks/typescript/identity.md)
- [Channel preferences](https://beepgrid.com/docs/sdks/typescript/channels.md)
- [Event streams](https://beepgrid.com/docs/sdks/typescript/events.md)
- [Bound approvals and execution](https://beepgrid.com/docs/sdks/typescript/execution.md)
- [OSS Coordinator](https://beepgrid.com/docs/sdks/typescript/coordinator.md)


## Install

```sh
npm install @beepgrid/sdk
```

```ts
import { Client } from '@beepgrid/sdk';
```

Node.js 22.13 or later is required. The package includes TypeScript declarations and ESM exports.

## Build from source

From a Beepgrid checkout:

```sh
npm --prefix sdk/typescript ci
npm --prefix sdk/typescript run build
```

The maintained repository examples import the locally built SDK by relative path. Applications using the published package should import `@beepgrid/sdk` instead.

## Connect without a source checkout

Use the [published-package worker guide](https://github.com/beepgrid/beepgrid/blob/main/docs/CONNECT-AGENT-RECIPES.md#typescript) to add a complete worker to your own project. The repository examples below are optional source references.

## Run a worker

Set the protected URL/token-file environment from [Connect an agent](https://beepgrid.com/docs/start/connect-agent.md), then run:

```sh
node examples/typescript-worker/main.mjs
```

This is the complete maintained example. It uses the existing connection directly and supports graceful shutdown. Replace the deterministic reply with your agent handler.



```javascript
import { readFileSync, statSync } from "node:fs";
let token=process.env.BEEPGRID_TOKEN;
if(process.env.BEEPGRID_TOKEN_FILE){
  if(statSync(process.env.BEEPGRID_TOKEN_FILE).mode & 0o077)throw new Error("Credential file must be owner-only (chmod 600)");
  token=readFileSync(process.env.BEEPGRID_TOKEN_FILE,"utf8").trim();
}
if(!token)throw new Error("Set BEEPGRID_TOKEN_FILE or BEEPGRID_TOKEN");
import { Client } from "../../sdk/typescript/dist/index.js";
let client = new Client(
  process.env.BEEPGRID_URL ?? "http://localhost:4010",
  token,
);
const agentId = process.env.BEEPGRID_AGENT_ID?.trim();
let identity;
if (agentId) {
  const connected = await client.connect(agentId, process.env.BEEPGRID_AGENT_NAME ?? "TypeScript worker", ["message"]);
  client = connected.client;
  identity = {identity_type: "agent", agent: connected.session.agent, instance_id: connected.session.instance_id};
} else {
  identity = await client.call("GET", "/api/v1/me");
}
if (identity.identity_type !== "agent" || !identity.agent?.id || !identity.instance_id) {
  throw new Error("Without BEEPGRID_AGENT_ID, supply an existing worker credential for an agent connection");
}
console.log("Agent:", identity.agent.id, "Instance:", identity.instance_id);
const controller = new AbortController();
process.on("SIGINT", () => controller.abort());
process.on("SIGTERM", () => controller.abort());
await client.run(async (delivery) => {
  if (delivery.payload.type === "message") {
    const m = delivery.payload.message;
    await client.send(
      {
        conversation_id: m.conversation_id,
        body: "TypeScript worker received: " + m.body,
      },
      "reply/" + delivery.id,
    );
  }
}, controller.signal);
```

## Requests and cancellation

Construct `new Client(url, workerToken)`. Use `send(input, stableKey)`, `ask(input, stableKey)` and `respond(requestId, response)` with typed inputs. `wait(requestId, signal)` waits for a final answer.

An `AbortSignal` stops local waiting or receiving. It does not cancel the saved request; use the explicit `cancel` operation for that. Avoid sharing a short-lived signal with unrelated requests.

## Errors

`BeepgridError` exposes `code` and HTTP `status`. Transport errors and aborts can also throw. A stable operation key lets the client retry an uncertain write without creating another communication. [Persist that key](https://beepgrid.com/docs/sdks/reliability.md) if your process may restart.

SDK transport code has no import-time network or runtime side effects. Use [events](https://beepgrid.com/docs/sdks/events.md) when building a live conversation view.