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 or choose an operation family.

Install

npm install @beepgrid/sdk

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:

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 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, then run:

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.

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 if your process may restart.

SDK transport code has no import-time network or runtime side effects. Use events when building a live conversation view.

Read this page as Markdown