@tidblink/server 0.0.0-stage → 0.4.0-rc.0

package/dist/user.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"user.js","sourceRoot":"","sources":["../src/user.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EACL,cAAc,EACd,UAAU,EACV,eAAe,EACf,gBAAgB,EAChB,iBAAiB,GAElB,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,aAAa,EAEb,OAAO,GAER,MAAM,cAAc,CAAC;AAwCtB,gEAAgE;AAChE,MAAM,OAAO,aAAa;IACf,KAAK,CAAa;IAClB,MAAM,CAAY;IAE3B,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED,YAAY,IAAgB;QAC1B,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAClB,IAAI,CAAC,MAAM,GAAG,IAAI,SAAS,CAAC,IAAI,CAAC,CAAC;IACpC,CAAC;IAED;;;OAGG;IACH,aAAa,CAAC,OAA6B;QACzC,OAAO,aAAa,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IAC5C,CAAC;IAED,kBAAkB,CAAC,OAAqB;QACtC,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CACnB,mBAAmB,eAAe,CAAC,OAAO,CAAC,EAAE,EAC7C,OAAO,CACR,CAAC;IACJ,CAAC;IAED,UAAU,CAAC,OAAwB;QACjC,IAAI,OAAO;YACT,gBAAgB,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,WAAW,CAAC,EAAE,oBAAoB,CAAC,CAAC;QAC3E,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC;IAClD,CAAC;IAED,kBAAkB,CAAC,OAAwB;QACzC,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,kBAAkB,EAAE,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC;IACrE,CAAC;IAED,KAAK,CAAC,YAAY,CAAC,OAA4B;QAC7C,IAAI,OAAO;YACT,gBAAgB,CACd,OAAO,EACP,CAAC,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,WAAW,CAAC,EACxD,sBAAsB,CACvB,CAAC;QACJ,MAAM,EAAE,UAAU,EAAE,GAAG,IAAI,EAAE,GAAG,OAAO,IAAI,EAAE,CAAC;QAC9C,MAAM,KAAK,GAAG,IAAI,eAAe,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC;QACzD,iBAAiB,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;QACrC,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAIlC,YAAY,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,OAAO,CAAC,CAAC;QACzD,OAAO;YACL,GAAG,QAAQ;YACX,QAAQ,EAAE,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAC7B,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAC9D;SACF,CAAC;IACJ,CAAC;IAED,OAAO,CAAC,EAAU;QAChB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACrC,CAAC;IACD,UAAU,CAAC,EAAU,EAAE,OAAwB;QAC7C,OAAO,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3C,CAAC;CACF"}

package/examples/control-turn.mjs

@@ -0,0 +1,53 @@
+import { pathToFileURL } from "node:url";
+import { OrganizationClient } from "@tidblink/server";
+
+/** Persist the action and both identities before dispatch; recovery reads that command. */
+export async function controlTurnWorkflow({
+  baseUrl,
+  organizationApiKey,
+  userId,
+  sessionId,
+  turnId,
+  clientEventId,
+  action,
+  signal,
+}) {
+  if (action !== "cancel" && action !== "retry")
+    throw new TypeError("action must be cancel or retry");
+  const session = new OrganizationClient({
+    baseUrl,
+    apiKey: organizationApiKey,
+  }).user(userId).session(
+    sessionId,
+  );
+  const input = { turnId, clientEventId, ...(signal ? { signal } : {}) };
+  if (action === "cancel") return session.cancel(input);
+  const accepted = await session.retry(input);
+  return session.waitForResult(
+    accepted.clientEventId,
+    signal ? { signal } : undefined,
+  );
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  try {
+    const result = await controlTurnWorkflow({
+      baseUrl: process.env.AGENT_SERVICE_URL,
+      organizationApiKey: process.env.ORGANIZATION_API_KEY,
+      userId: process.env.END_USER_ID,
+      sessionId: process.env.SESSION_ID,
+      turnId: process.env.TURN_ID,
+      clientEventId: process.env.CLIENT_EVENT_ID,
+      action: process.env.TURN_ACTION,
+    });
+    console.log(JSON.stringify(result));
+  } catch (error) {
+    console.error(
+      error instanceof Error ? error.message : "Turn control failed",
+    );
+    process.exitCode = 1;
+  }
+}

package/examples/create-session.mjs

@@ -0,0 +1,82 @@
+import { pathToFileURL } from "node:url";
+import { OrganizationClient } from "@tidblink/server";
+
+/**
+ * Retain the owner, selected Template, optional Session options and the
+ * creation key before calling. Pass `acknowledgeSessionRecall: true` when the
+ * Template enables cross-Session Recall.
+ */
+export async function createSessionWorkflow({
+  baseUrl,
+  organizationApiKey,
+  userId,
+  templateId,
+  sessionCreationKey,
+  model,
+  additionalInstructions,
+  sandbox,
+  acknowledgeSessionRecall,
+}) {
+  if (!templateId)
+    throw new TypeError(
+      "Select and retain a templateId before creating a Session",
+    );
+  const organization = new OrganizationClient({
+    baseUrl,
+    apiKey: organizationApiKey,
+  });
+  const user = organization.user(userId);
+  const templates = await user.listAgentTemplates();
+  const models = await user.listModels();
+  // Omission is part of the creation identity; resolving today's default would change a replay.
+  const optional = { model, additionalInstructions, sandbox, acknowledgeSessionRecall };
+  const session = await user.createSession({
+    templateId,
+    idempotencyKey: sessionCreationKey,
+    ...Object.fromEntries(
+      Object.entries(optional).filter(([, value]) => value !== undefined),
+    ),
+  });
+  return { organization, user, session, templates, models };
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  const {
+    AGENT_SERVICE_URL,
+    ORGANIZATION_API_KEY,
+    END_USER_ID,
+    TEMPLATE_ID,
+    SESSION_CREATION_KEY,
+    MODEL_ID,
+    ACKNOWLEDGE_SESSION_RECALL,
+  } = process.env;
+  if (
+    !AGENT_SERVICE_URL ||
+    !ORGANIZATION_API_KEY ||
+    !END_USER_ID ||
+    !TEMPLATE_ID ||
+    !SESSION_CREATION_KEY
+  )
+    throw new Error(
+      "Set AGENT_SERVICE_URL, ORGANIZATION_API_KEY, END_USER_ID, TEMPLATE_ID and SESSION_CREATION_KEY; MODEL_ID and ACKNOWLEDGE_SESSION_RECALL=true are optional",
+    );
+  const result = await createSessionWorkflow({
+    baseUrl: AGENT_SERVICE_URL,
+    organizationApiKey: ORGANIZATION_API_KEY,
+    userId: END_USER_ID,
+    sessionCreationKey: SESSION_CREATION_KEY,
+    templateId: TEMPLATE_ID,
+    model: MODEL_ID,
+    acknowledgeSessionRecall:
+      ACKNOWLEDGE_SESSION_RECALL === "true" ? true : undefined,
+  });
+  console.log(
+    JSON.stringify({
+      sessionId: result.session.id,
+      model: result.session.model,
+    }),
+  );
+}

package/examples/http-connector.mjs

@@ -0,0 +1,127 @@
+import { createServer } from "node:http";
+import { pathToFileURL } from "node:url";
+import {
+  ConnectorAuthError,
+  ConnectorKeySet,
+  readConnectorCallContext,
+  verifyConnectorCallback,
+} from "@tidblink/server";
+
+/**
+ * A minimal HTTP Connector: an MCP server over Streamable HTTP with plain
+ * JSON responses, without an MCP library. Every request must carry a
+ * platform-signed token for this Organization and Connector; every tool call
+ * carries the Call Context naming the End User it is for.
+ *
+ * `tools` maps a tool name to `{ description, inputSchema, run(args, context) }`.
+ * `run` returns text; deduplicate its side effects by `context.callId`.
+ * Agents see each tool as `mcp_<name>__<tool>`, both parts lowercased with
+ * other characters replaced by `_`.
+ */
+export function createConnectorHandler({
+  baseUrl,
+  organizationId,
+  connectorId,
+  tools,
+  name = "example-connector",
+  keys = new ConnectorKeySet({ baseUrl }),
+}) {
+  const catalog = Object.entries(tools).map(([name, tool]) => ({
+    name,
+    description: tool.description,
+    inputSchema: tool.inputSchema,
+  }));
+  const answer = (response, status, body) => {
+    response.writeHead(status, body ? { "content-type": "application/json" } : {});
+    response.end(body ? JSON.stringify(body) : undefined);
+  };
+  return async (request, response) => {
+    try {
+      await verifyConnectorCallback(request.headers.authorization, {
+        keys,
+        organizationId,
+        connectorId,
+      });
+    } catch (error) {
+      if (error instanceof ConnectorAuthError) return answer(response, 401);
+      return answer(response, 503);
+    }
+    if (request.method === "DELETE") return answer(response, 200);
+    if (request.method !== "POST") return answer(response, 405);
+    let message;
+    try {
+      const chunks = [];
+      for await (const chunk of request) chunks.push(chunk);
+      message = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+    } catch {
+      return answer(response, 400, {
+        jsonrpc: "2.0",
+        id: null,
+        error: { code: -32700, message: "Parse error" },
+      });
+    }
+    // Notifications such as notifications/initialized need no answer.
+    if (message.id === undefined) return answer(response, 202);
+    const reply = (result) => answer(response, 200, { jsonrpc: "2.0", id: message.id, result });
+    const fail = (code, text) =>
+      answer(response, 200, { jsonrpc: "2.0", id: message.id, error: { code, message: text } });
+    switch (message.method) {
+      case "initialize":
+        return reply({
+          protocolVersion: "2025-03-26",
+          capabilities: { tools: {} },
+          serverInfo: { name, version: "1.0.0" },
+        });
+      case "ping":
+        return reply({});
+      case "tools/list":
+        return reply({ tools: catalog });
+      case "tools/call": {
+        const tool = tools[message.params?.name];
+        if (!tool) return fail(-32602, "Unknown tool");
+        let context;
+        try {
+          context = readConnectorCallContext(message.params?._meta, { organizationId });
+        } catch (error) {
+          return fail(-32602, error.message);
+        }
+        try {
+          const text = await tool.run(message.params.arguments ?? {}, context);
+          return reply({ content: [{ type: "text", text: String(text) }] });
+        } catch (error) {
+          return reply({
+            content: [{ type: "text", text: error instanceof Error ? error.message : "Tool failed" }],
+            isError: true,
+          });
+        }
+      }
+      default:
+        return fail(-32601, "Method not found");
+    }
+  };
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const { AGENT_SERVICE_URL, ORGANIZATION_ID, CONNECTOR_ID, PORT = "8080" } = process.env;
+  if (!AGENT_SERVICE_URL || !ORGANIZATION_ID || !CONNECTOR_ID)
+    throw new Error("Set AGENT_SERVICE_URL, ORGANIZATION_ID and CONNECTOR_ID; PORT is optional");
+  const handler = createConnectorHandler({
+    baseUrl: AGENT_SERVICE_URL,
+    organizationId: ORGANIZATION_ID,
+    connectorId: CONNECTOR_ID,
+    tools: {
+      lookup_order: {
+        description: "Look up one of the user's orders",
+        inputSchema: {
+          type: "object",
+          properties: { orderId: { type: "string" } },
+          required: ["orderId"],
+        },
+        run: async ({ orderId }, { userId }) =>
+          JSON.stringify({ orderId, userId, status: "shipped" }),
+      },
+    },
+  });
+  // Serve behind your HTTPS terminator; register its HTTPS URL as endpointUrl.
+  createServer(handler).listen(Number(PORT));
+}

package/examples/lamp-backend.mjs

@@ -0,0 +1,175 @@
+import { OrganizationClient } from "@tidblink/server";
+
+/**
+ * The backend of a smart lamp that users talk to by typing in an app or by
+ * speaking to the lamp. Both share one Session, so one conversation history.
+ *
+ * - The lamp's functions are Client Tools: the model calls them, this backend
+ *   runs them by forwarding to the lamp over your own device channel (MQTT,
+ *   WebSocket, ...), and the core never talks to the lamp except for audio.
+ * - While the lamp is online the backend keeps its Session connected, so the
+ *   lamp's tools work for voice too. Typing while the lamp is offline still
+ *   works; its tools then fail at once and the model says so.
+ * - For voice the backend hands the lamp a short-lived grant; the lamp opens
+ *   the Realtime WebSocket itself and audio never passes through here.
+ *
+ * `device` is your channel to the lamps:
+ *   isOnline(deviceId) -> boolean
+ *   request(deviceId, command, args, { signal }) -> Promise<result>, rejects on failure
+ *   send(deviceId, topic, payload) -> void   (fire-and-forget, e.g. the voice grant)
+ * `store` keeps who owns which lamp and where each Session's events were read;
+ * the default keeps it in memory.
+ */
+export function createLampBackend({
+  baseUrl,
+  organizationApiKey,
+  templateId,
+  device,
+  store = memoryStore(),
+  onChat = () => {},
+}) {
+  const organization = new OrganizationClient({ baseUrl, apiKey: organizationApiKey });
+  /** deviceId -> SessionConnection while the lamp is online. */
+  const online = new Map();
+
+  // ── The lamp's functions (edge capabilities) ──────────────────────────────
+  const lampTools = (deviceId) => {
+    const ask = async (command, args, signal) => {
+      // Fail at once instead of letting the model wait for a lamp that is not there.
+      if (!device.isOnline(deviceId)) throw new Error("The lamp is offline");
+      return device.request(deviceId, command, args, { signal });
+    };
+    return {
+      set_light: {
+        description: "Turn the lamp on or off, or set its brightness and colour temperature",
+        parameters: {
+          type: "object",
+          properties: {
+            on: { type: "boolean", description: "true turns the lamp on, false off" },
+            brightness: { type: "integer", minimum: 1, maximum: 100, description: "Percent" },
+            colorTemp: { type: "integer", minimum: 2700, maximum: 6500, description: "Kelvin" },
+          },
+          additionalProperties: false,
+        },
+        run: async (args, { signal }) => {
+          const state = await ask("set_light", args, signal);
+          return state.on
+            ? `The lamp is on at ${state.brightness}% and ${state.colorTemp} K`
+            : "The lamp is off";
+        },
+      },
+      get_status: {
+        description: "Read the lamp's state and the ambient light",
+        parameters: { type: "object", properties: {}, additionalProperties: false },
+        run: async (_args, { signal }) => JSON.stringify(await ask("get_status", {}, signal)),
+      },
+      set_timer: {
+        description: "Turn the lamp off after some minutes",
+        parameters: {
+          type: "object",
+          properties: { minutes: { type: "integer", minimum: 1, maximum: 240 } },
+          required: ["minutes"],
+          additionalProperties: false,
+        },
+        run: async ({ minutes }, { signal }) => {
+          await ask("set_timer", { minutes, action: "off" }, signal);
+          return `The lamp turns off in ${minutes} minutes`;
+        },
+      },
+    };
+  };
+
+  const sessionOf = async (deviceId) => {
+    const binding = await store.binding(deviceId);
+    if (!binding) throw new Error(`Lamp ${deviceId} is not bound to a user`);
+    return organization.user(binding.userId).session(binding.sessionId);
+  };
+
+  const connect = async (deviceId) =>
+    (await sessionOf(deviceId)).connect({
+      tools: lampTools(deviceId),
+      cursor: await store.cursor(deviceId),
+      onCursor: (cursor) => store.saveCursor(deviceId, cursor),
+      // What was said by voice also appears in the app.
+      onTranscript: (t) => onChat(deviceId, { role: "user", text: t.text }),
+      onResponse: (r) => onChat(deviceId, { role: "assistant", text: r.text }),
+    });
+
+  return {
+    organization,
+
+    /** The user binds a lamp in the app: one End User per app user, one Session per lamp. */
+    async bindDevice(appUserId, deviceId) {
+      const user = await organization.createEndUser({ externalId: appUserId }); // safe to repeat
+      const session = await organization.user(user.userId).createSession({
+        templateId,
+        idempotencyKey: `lamp.${deviceId}`, // one Session per lamp, also after a retry
+      });
+      await store.bind(deviceId, { userId: user.userId, sessionId: session.id });
+      return session.id;
+    },
+
+    /** The lamp came online: keep its Session connected while it stays online. */
+    async onDeviceOnline(deviceId) {
+      if (online.has(deviceId)) return;
+      const conn = await connect(deviceId);
+      online.set(deviceId, conn);
+      // Another backend process took the lamp over, or the Session was deleted.
+      conn.closed.then(() => {
+        if (online.get(deviceId) === conn) online.delete(deviceId);
+      });
+    },
+
+    /** The lamp went offline: release its Session. */
+    async onDeviceOffline(deviceId) {
+      const conn = online.get(deviceId);
+      online.delete(deviceId);
+      await conn?.close();
+    },
+
+    /**
+     * The user typed in the app. Uses the lamp's connection when it is online,
+     * otherwise a temporary one. `onDraft` receives the growing answer.
+     */
+    async onAppMessage(deviceId, text, { clientEventId, onDraft } = {}) {
+      const existing = online.get(deviceId);
+      const conn = existing ?? (await connect(deviceId));
+      try {
+        const reply = await conn.send(text, {
+          ...(clientEventId ? { clientEventId } : {}),
+          ...(onDraft ? { onProgress: onDraft } : {}),
+        });
+        return reply.text;
+      } finally {
+        if (!existing) await conn.close();
+      }
+    },
+
+    /** The user pressed the talk button: give the lamp a short-lived grant to open voice. */
+    async onDeviceWantsToTalk(deviceId) {
+      const conn = online.get(deviceId);
+      if (!conn) throw new Error(`Lamp ${deviceId} is not online`);
+      const grant = await conn.realtimeGrant();
+      device.send(deviceId, "voice_grant", grant);
+      return grant;
+    },
+
+    /** Release every Session and close the Backend Connections, e.g. on shutdown. */
+    async close() {
+      online.clear();
+      await organization.close();
+    },
+  };
+}
+
+/** In-memory bindings and cursors; use your database in production. */
+export function memoryStore() {
+  const bindings = new Map();
+  const cursors = new Map();
+  return {
+    bind: async (deviceId, binding) => void bindings.set(deviceId, binding),
+    binding: async (deviceId) => bindings.get(deviceId),
+    cursor: async (deviceId) => cursors.get(deviceId),
+    saveCursor: async (deviceId, cursor) => void cursors.set(deviceId, cursor),
+  };
+}

package/examples/prepare-realtime-connection.mjs

@@ -0,0 +1,72 @@
+import { pathToFileURL } from "node:url";
+import { OrganizationClient } from "@tidblink/server";
+
+/** Prepare an existing owned Session for a terminal to connect; this does not open a WebSocket. */
+export async function prepareRealtimeConnection({
+  baseUrl,
+  organizationApiKey,
+  userId,
+  sessionId,
+  realtimeModelId,
+  audio,
+  metadata,
+}) {
+  const client = new OrganizationClient({
+    baseUrl,
+    apiKey: organizationApiKey,
+  }).user(userId);
+  const catalog = await client.listRealtimeModels();
+  const session = client.session(sessionId);
+  let selection = await session.getRealtimeModelSelection();
+  if (
+    realtimeModelId !== undefined &&
+    realtimeModelId !== selection.model
+  ) {
+    selection = await session.setRealtimeModel(realtimeModelId, {
+      ifMatch: selection.etag,
+    });
+  }
+  const prepared = await session.openRealtimeConnection({
+    ...(audio === undefined ? {} : { audio }),
+    ...(metadata === undefined ? {} : { metadata }),
+  });
+  return { catalog, selection, ...prepared };
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  const {
+    AGENT_SERVICE_URL,
+    ORGANIZATION_API_KEY,
+    END_USER_ID,
+    SESSION_ID,
+    REALTIME_MODEL_ID,
+  } = process.env;
+  if (
+    !AGENT_SERVICE_URL ||
+    !ORGANIZATION_API_KEY ||
+    !END_USER_ID ||
+    !SESSION_ID
+  ) {
+    throw new Error(
+      "Set AGENT_SERVICE_URL, ORGANIZATION_API_KEY, END_USER_ID and SESSION_ID; REALTIME_MODEL_ID is optional",
+    );
+  }
+  const result = await prepareRealtimeConnection({
+    baseUrl: AGENT_SERVICE_URL,
+    organizationApiKey: ORGANIZATION_API_KEY,
+    userId: END_USER_ID,
+    sessionId: SESSION_ID,
+    ...(REALTIME_MODEL_ID ? { realtimeModelId: REALTIME_MODEL_ID } : {}),
+  });
+  // The one-time connect token is returned to imported callers but never printed by this CLI.
+  console.log(
+    JSON.stringify({
+      realtimeConnection: result.realtimeConnection,
+      websocketUrl: result.websocketUrl,
+      connectTokenExpiresAt: result.connectTokenExpiresAt,
+    }),
+  );
+}

package/examples/read-usage.mjs

@@ -0,0 +1,44 @@
+import { pathToFileURL } from "node:url";
+import { OrganizationClient } from "@tidblink/server";
+
+/** Organization details return the first page; retain nextCursor and the original filters. */
+export async function readUserUsage({
+  baseUrl,
+  organizationApiKey,
+  userId,
+  options,
+}) {
+  const organization = new OrganizationClient({
+    baseUrl,
+    apiKey: organizationApiKey,
+  });
+  const { interval, ...range } = options;
+  return {
+    summary: await organization.getUserUsage(userId, options),
+    details: await organization.getUserUsageDetails(userId, range),
+  };
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  try {
+    const options = {
+      from: process.env.USAGE_FROM,
+      to: process.env.USAGE_TO,
+      tagKey: process.env.TAG_KEY,
+      tagValue: process.env.TAG_VALUE,
+    };
+    const result = await readUserUsage({
+      baseUrl: process.env.AGENT_SERVICE_URL,
+      organizationApiKey: process.env.ORGANIZATION_API_KEY,
+      userId: process.env.END_USER_ID,
+      options,
+    });
+    console.log(JSON.stringify(result));
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : "Usage read failed");
+    process.exitCode = 1;
+  }
+}

package/examples/send-message.mjs

@@ -0,0 +1,48 @@
+import { pathToFileURL } from "node:url";
+import { OrganizationClient } from "@tidblink/server";
+
+/** Persist sessionId, clientEventId and text before calling; reuse them for recovery. */
+export async function sendMessageWorkflow({
+  baseUrl,
+  organizationApiKey,
+  userId,
+  sessionId,
+  clientEventId,
+  text,
+  timeoutMs,
+  signal,
+}) {
+  const session = new OrganizationClient({
+    baseUrl,
+    apiKey: organizationApiKey,
+  }).user(userId).session(
+    sessionId,
+  );
+  return session.turn(
+    { clientEventId, text, ...(signal ? { signal } : {}) },
+    {
+      ...(timeoutMs === undefined ? {} : { timeoutMs }),
+      ...(signal ? { signal } : {}),
+    },
+  );
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  try {
+    const result = await sendMessageWorkflow({
+      baseUrl: process.env.AGENT_SERVICE_URL,
+      organizationApiKey: process.env.ORGANIZATION_API_KEY,
+      userId: process.env.END_USER_ID,
+      sessionId: process.env.SESSION_ID,
+      clientEventId: process.env.CLIENT_EVENT_ID,
+      text: process.env.MESSAGE_TEXT,
+    });
+    console.log(result.text);
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : "Message failed");
+    process.exitCode = 1;
+  }
+}

package/examples/submit-audio.mjs

@@ -0,0 +1,57 @@
+import { readFile } from "node:fs/promises";
+import { basename } from "node:path";
+import { pathToFileURL } from "node:url";
+import { OrganizationClient } from "@tidblink/server";
+
+/** This recording request owns its response; aborting it may interrupt the Turn. */
+export async function submitAudioWorkflow({
+  baseUrl,
+  organizationApiKey,
+  userId,
+  sessionId,
+  bytes,
+  filename,
+  contentType,
+  billingTag,
+  signal,
+}) {
+  return new OrganizationClient({
+    baseUrl,
+    apiKey: organizationApiKey,
+  }).user(userId)
+    .session(sessionId)
+    .audio({
+      bytes,
+      filename,
+      ...(contentType === undefined ? {} : { contentType }),
+      ...(billingTag === undefined ? {} : { billingTag }),
+      ...(signal ? { signal } : {}),
+    });
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  try {
+    if (!process.env.AUDIO_FILE_PATH)
+      throw new Error("Set AUDIO_FILE_PATH to an existing recording");
+    const result = await submitAudioWorkflow({
+      baseUrl: process.env.AGENT_SERVICE_URL,
+      organizationApiKey: process.env.ORGANIZATION_API_KEY,
+      userId: process.env.END_USER_ID,
+      sessionId: process.env.SESSION_ID,
+      filename: basename(process.env.AUDIO_FILE_PATH),
+      bytes: await readFile(process.env.AUDIO_FILE_PATH),
+      contentType: process.env.AUDIO_CONTENT_TYPE,
+    });
+    console.log(result.text);
+  } catch (error) {
+    console.error(
+      error instanceof Error ? error.message : "Audio request failed",
+    );
+    if (typeof error?.turnId === "string")
+      console.error(`Turn: ${error.turnId}`);
+    process.exitCode = 1;
+  }
+}