@craftedxp/sdk-node 0.9.0 → 0.12.0

package/dist/index.d.ts

@@ -23,10 +23,11 @@ interface HttpRequest {
 }
 declare const createHttpClient: (opts: HttpClientOptions) => {
     request: <T>(req: HttpRequest) => Promise<T>;
+    stream: <T = unknown>(req: HttpRequest) => AsyncIterable<T>;
 };
 type HttpClient = ReturnType<typeof createHttpClient>;
 
-type TtsProvider = 'pockettts' | 'cartesia' | 'fish-audio' | 'gemini';
+type TtsProvider = 'pockettts' | 'cartesia' | 'fish-audio' | 'gemini' | 'kokoro' | 'hume' | 'omnivoice' | 'chatterbox' | 'tada';
 type SttProvider = 'deepgram';
 type LlmProvider = 'gemini' | 'openai' | 'anthropic';
 type EndpointingMode = 'smart' | 'simple';
@@ -34,6 +35,20 @@ interface AgentVoice {
     provider: TtsProvider;
     voiceId?: string;
     language?: string;
+    /**
+     * Secondary language for bilingual agents. When set, the agent supports
+     * mid-utterance code-switching via the `[lang=xx]...[/lang]` tag contract.
+     * Requires a multilingual-capable TTS provider (cartesia, kokoro,
+     * fish-audio, hume, omnivoice, gemini). See docs/sdks.md "Bilingual
+     * agents" section.
+     */
+    secondaryLanguage?: string;
+    /**
+     * Second-language voice ID for voice-pinned providers (kokoro). Stays
+     * unset for providers whose voices handle multiple languages natively
+     * (cartesia, hume, omnivoice).
+     */
+    secondaryVoiceId?: string;
     /**
      * Per-utterance variation, 0.0–1.0. Honoured by Fish Audio and
      * Chatterbox (passed through to each provider's synthesis API).
@@ -54,6 +69,13 @@ interface AgentTranscriber {
     provider: SttProvider;
     model: string;
     language?: string;
+    /**
+     * Secondary language for bilingual agents. When set, the STT provider
+     * auto-flips to multi-language mode (Deepgram `multi`, Whisper
+     * auto-detect). Other STT providers reject bilingual config at agent
+     * create time.
+     */
+    secondaryLanguage?: string;
 }
 interface AgentModel {
     provider: LlmProvider;
@@ -122,6 +144,19 @@ interface Agent {
      * cache-buster so browser/CDN caches refresh on replace.
      */
     avatarUrl?: string;
+    /**
+     * Transport the agent's live calls use. `'webrtc'` (the platform default
+     * for new agents) or `'ws'` (legacy). Forwarded on the mint result and
+     * needed by the agent-initiated push payload so the app dispatches to the
+     * right gateway.
+     */
+    transport?: 'ws' | 'webrtc';
+    /** Whether this agent may host multi-party video rooms. */
+    canHostRooms?: boolean;
+    /** Room operating mode (`'notes-only'` today). */
+    roomMode?: 'notes-only';
+    /** Transcribe-only mode — the agent listens but never speaks. */
+    transcribeOnly?: boolean;
     createdAt: number;
     updatedAt: number;
 }
@@ -140,6 +175,8 @@ interface AgentCreateInput {
     recording?: AgentRecording;
     structuredDataSchema?: Record<string, unknown>;
     allowedUserTags?: string[];
+    /** See Agent.transport. Defaults to the platform default when omitted. */
+    transport?: 'ws' | 'webrtc';
     /**
      * Server-managed. Don't set this directly via create/update — use
      * `agents.uploadAvatar(agentId, file)` instead. Sending it raw is
@@ -147,6 +184,25 @@ interface AgentCreateInput {
      * actually changes.
      */
     avatarUrl?: string;
+    /**
+     * Let this agent host multi-party video rooms. Off by default. Required
+     * (`true`) before `client.rooms.create({ agentId })` will accept the agent.
+     */
+    canHostRooms?: boolean;
+    /**
+     * Room operating mode. Today only `'notes-only'` exists — the agent listens
+     * and takes structured notes without speaking. A literal union so future
+     * modes can be added without breaking the wire.
+     */
+    roomMode?: 'notes-only';
+    /**
+     * Transcribe-only mode. When `true`, the agent listens but never speaks: no
+     * TTS/LLM, no greeting, idle nudges suppressed, user turns are not routed
+     * through the LLM — an STT-only loop that streams `transcript` data-messages
+     * back to the caller. `voice` stays required by the schema (defaults apply)
+     * but is never read at runtime.
+     */
+    transcribeOnly?: boolean;
 }
 type AgentUpdateInput = Partial<AgentCreateInput>;
 /**
@@ -228,6 +284,8 @@ interface CallRecord {
     costBreakdown?: CostBreakdown;
     errorMessage?: string;
     metadata?: Record<string, string>;
+    /** Transport channel the call was carried over (`'voice'` = WebRTC/WS audio, `'text'` = text-only). */
+    channel?: 'voice' | 'text';
 }
 interface CallListFilters {
     agentId?: string;
@@ -323,6 +381,25 @@ interface CallTokenMintInput {
      * if you blindly accept client-asserted tier the gate is theatre.
      */
     userTags?: string[];
+    /**
+     * Mark this token as agent-initiated. When 'agent', the tenant's server
+     * is ringing the end-user (push → app connects) and the resulting
+     * CallRecord is tagged `direction: 'outbound'`. Omit / 'user' for the
+     * default user-initiated connect. See docs/sdks.md "Agent-initiated calls".
+     */
+    initiatedBy?: 'user' | 'agent';
+    /**
+     * Session channel selector. `voice` (default) routes to WS/WebRTC audio;
+     * `text` routes to HTTP+SSE chat via the `chats` resource. Rejected at
+     * mint when the agent has `transcribeOnly: true` or when `mode: 'learning'`
+     * is supplied.
+     */
+    channel?: 'voice' | 'text';
+    /**
+     * Session purpose. `standard` (default) is a regular call. `learning`
+     * (admin-bypass only) flags a self-learning session — see Phase 19.
+     */
+    mode?: 'standard' | 'learning';
 }
 interface CallTokenMintResult {
     tokenId: string;
@@ -344,6 +421,12 @@ interface CallTokenMintResult {
      * of falling back to the Phase-1 routes on the API base (local dev).
      */
     webrtcGatewayBase?: string;
+    /**
+     * Session channel echoed back from the mint. Useful for the client SDK
+     * to dispatch correctly — text-mode tokens go to `chatsFor(token)`,
+     * voice-mode tokens go to `voice-js`/`voice-rn`.
+     */
+    channel?: 'voice' | 'text';
 }
 interface CallTokenSummary {
     tokenId: string;
@@ -400,6 +483,112 @@ interface MeResponse {
     plan: 'free' | 'paid';
     creditBalance: number;
 }
+type RoomStatus = 'provisioning' | 'active' | 'ended';
+type RoomEndReason = 'duration_reached' | 'empty' | 'manual' | 'expired';
+type GuestRole = 'host' | 'participant';
+type WorkerStatus = 'pending' | 'up' | 'down' | 'exited';
+interface CreateRoomInput {
+    agentId: string;
+    /** 1..240 — enforced by the server. */
+    durationMin: number;
+}
+interface CreateRoomResponse {
+    roomId: string;
+    status: 'provisioning';
+    expiresAt: string;
+    /** The shareable room-level secret — returned once, never persisted raw.
+     *  Anyone with this token + a display name joins as a fresh participant. */
+    joinToken: string;
+    /** `${APP_ORIGIN}/rooms/${roomId}/join?t=${joinToken}` — the single link to
+     *  share with everyone you want in the room. */
+    joinUrl: string;
+}
+interface RoomMetricsWire {
+    droppedUtterances: number;
+    deepgramReconnects: number;
+}
+interface RoomDoc {
+    roomId: string;
+    orgId: string;
+    agentId: string;
+    status: RoomStatus;
+    livekitSid: string | null;
+    durationMin: number;
+    /** sha256 of the shared room join token. The raw token is never persisted. */
+    joinTokenJti?: string;
+    createdByApiKeyId?: string;
+    createdAt?: string;
+    startedAt: string | null;
+    endedAt: string | null;
+    expiresAt: string;
+    endReason: RoomEndReason | null;
+    workerStatus?: WorkerStatus;
+    metrics?: RoomMetricsWire | null;
+}
+interface RoomListFilters {
+    status?: RoomStatus;
+    /** Server clamps to 100 max; default 20. */
+    limit?: number;
+    cursor?: string;
+}
+interface ListRoomsResponse {
+    rooms: RoomDoc[];
+    nextCursor: string | null;
+}
+interface RoomTranscriptOptions {
+    cursor?: string;
+    /** Server clamps to 1000 max; default 200. */
+    limit?: number;
+}
+interface UtteranceWire {
+    utteranceId: string;
+    participantId: string;
+    speakerName: string;
+    text: string;
+    startedAt: string;
+    endedAt: string;
+    sttConfidence: number;
+}
+interface ListUtterancesResponse {
+    utterances: UtteranceWire[];
+    nextCursor: string | null;
+}
+/** Returned by host-action endpoints (`/end` and friends) — 202 + eventId so
+ *  callers can correlate the async system-message broadcast that follows. */
+interface RoomEventAck {
+    eventId: string;
+}
+/**
+ * SSE events emitted by the text-channel chat endpoints. Concatenate
+ * `token.text` chunks to build up the agent's reply; render `tool.call`
+ * and `tool.result` as "doing-something" UI hints; treat `turn.end` as
+ * the signal that the current POST has finished streaming.
+ */
+type ChatEvent = {
+    type: 'chat.started';
+    chatId: string;
+    callId: string;
+} | {
+    type: 'token';
+    text: string;
+} | {
+    type: 'tool.call';
+    name: string;
+    args: unknown;
+} | {
+    type: 'tool.result';
+    name: string;
+    ok?: boolean;
+    [key: string]: unknown;
+} | {
+    type: 'turn.end';
+    finishReason: 'stop' | 'aborted' | 'length' | 'tool_error';
+    committedText?: string;
+} | {
+    type: 'error';
+    code: string;
+    message: string;
+};
 
 declare const createMeResource: (http: HttpClient) => {
     get: () => Promise<MeResponse>;
@@ -536,6 +725,40 @@ declare const createOrgsResource: (http: HttpClient) => {
 };
 type OrgsResource = ReturnType<typeof createOrgsResource>;
 
+declare const createRoomsResource: (http: HttpClient) => {
+    create: (input: CreateRoomInput) => Promise<CreateRoomResponse>;
+    list: (filters?: RoomListFilters) => Promise<ListRoomsResponse>;
+    get: (roomId: string) => Promise<RoomDoc>;
+    transcript: (roomId: string, opts?: RoomTranscriptOptions) => Promise<ListUtterancesResponse>;
+    end: (roomId: string) => Promise<RoomEventAck>;
+};
+type RoomsResource = ReturnType<typeof createRoomsResource>;
+
+interface StartChatInput {
+    agentId: string;
+    text?: string;
+}
+interface Chat {
+    id: string;
+    callId: string;
+    greeting: AsyncIterable<ChatEvent>;
+    send(text: string): AsyncIterable<ChatEvent>;
+    end(): Promise<void>;
+}
+/**
+ * Per-token chat resource. Construct via `client.chatsFor(callToken)` —
+ * `callToken` is a raw `ct_…` minted with `channel: 'text'`.
+ *
+ * The async iterables stream SSE events: `chat.started` (start only),
+ * then a sequence of `token` / `tool.call` / `tool.result` / `error`,
+ * then `turn.end` which closes the stream. The client must NOT keep
+ * a connection open between turns — each `send` is a fresh POST.
+ */
+declare const createChatsResource: (http: HttpClient, callToken: string) => {
+    start(input: StartChatInput): Promise<Chat>;
+};
+type ChatsResource = ReturnType<typeof createChatsResource>;
+
 interface PlatformClientOptions {
     apiKey: string;
     baseUrl?: string;
@@ -553,7 +776,19 @@ declare class PlatformClient {
     readonly callTokens: CallTokensResource;
     readonly webhooks: WebhooksResource;
     readonly orgs: OrgsResource;
+    readonly rooms: RoomsResource;
+    private readonly _http;
     constructor(options: PlatformClientOptions);
+    /**
+     * Returns a per-token chat resource bound to the given `ct_…` call token.
+     * The token must have been minted with `channel: 'text'`.
+     *
+     * Note: `chatsFor` is a factory method (not a fixed property) because the
+     * underlying resource is scoped to a single call token, whereas this client
+     * was constructed with an `sk_` admin key. Each end-user session needs its
+     * own `chatsFor(token)` handle.
+     */
+    chatsFor(callToken: string): ChatsResource;
 }
 
 type ApiErrorCode = 'unauthorized' | 'forbidden' | 'not_found' | 'bad_request' | 'conflict' | 'rate_limited' | 'payment_required' | 'internal_error' | 'unknown';
@@ -576,4 +811,4 @@ declare class PlatformError extends Error {
 
 declare const verifyWebhookSignature: (rawBody: Buffer | string, signatureHeader: string, secret: string) => boolean;
 
-export { type Agent, type AgentCreateInput, type AgentEndpointing, type AgentHttpTool, type AgentModel, type AgentRecording, type AgentTool, type AgentTranscriber, type AgentUpdateInput, type AgentVoice, type AgentWebhooksResource, type AgentsResource, type ApiErrorCode, type CallListFilters, type CallRecord, type CallRecordingUrlResponse, type CallStatus, type CallSummary, type CallTokenMintInput, type CallTokenMintResult, type CallTokenSummary, type CallTokensResource, type CallsResource, type CatalogAgent, type CatalogListInput, type CostBreakdown, type CreditsResource, type EndReason, type EndpointingMode, type KnowledgeBase, type KnowledgeBaseFile, type KnowledgeBasesResource, type LedgerEntry, type LlmProvider, type MeResource, type MeResponse, type OrgsResource, PlatformClient, type PlatformClientOptions, PlatformError, type PlatformEventName, type RecordingMeta, type SttProvider, type TranscriptTurn, type TtsProvider, type WebhookConfig, type WebhookCreateInput, type WebhookDelivery, type WebhookUpdateInput, type WebhooksResource, verifyWebhookSignature };
+export { type Agent, type AgentCreateInput, type AgentEndpointing, type AgentHttpTool, type AgentModel, type AgentRecording, type AgentTool, type AgentTranscriber, type AgentUpdateInput, type AgentVoice, type AgentWebhooksResource, type AgentsResource, type ApiErrorCode, type CallListFilters, type CallRecord, type CallRecordingUrlResponse, type CallStatus, type CallSummary, type CallTokenMintInput, type CallTokenMintResult, type CallTokenSummary, type CallTokensResource, type CallsResource, type CatalogAgent, type CatalogListInput, type Chat, type ChatEvent, type ChatsResource, type CostBreakdown, type CreateRoomInput, type CreateRoomResponse, type CreditsResource, type EndReason, type EndpointingMode, type GuestRole, type KnowledgeBase, type KnowledgeBaseFile, type KnowledgeBasesResource, type LedgerEntry, type ListRoomsResponse, type ListUtterancesResponse, type LlmProvider, type MeResource, type MeResponse, type OrgsResource, PlatformClient, type PlatformClientOptions, PlatformError, type PlatformEventName, type RecordingMeta, type RoomDoc, type RoomEndReason, type RoomEventAck, type RoomListFilters, type RoomMetricsWire, type RoomStatus, type RoomTranscriptOptions, type RoomsResource, type StartChatInput, type SttProvider, type TranscriptTurn, type TtsProvider, type UtteranceWire, type WebhookConfig, type WebhookCreateInput, type WebhookDelivery, type WebhookUpdateInput, type WebhooksResource, type WorkerStatus, verifyWebhookSignature };

package/dist/index.js

@@ -179,7 +179,82 @@ var createHttpClient = (opts) => {
     }
     throw lastErr instanceof Error ? lastErr : new Error("request exhausted retries");
   };
-  return { request };
+  async function* stream(req) {
+    const url = buildUrl(opts.baseUrl, req.path, req.query);
+    const headers = {
+      Authorization: `Bearer ${opts.apiKey}`,
+      "Content-Type": "application/json",
+      Accept: "text/event-stream",
+      ...req.headers ?? {}
+    };
+    const started = Date.now();
+    let res;
+    try {
+      res = await fetchImpl(url, {
+        method: req.method,
+        headers,
+        body: req.body !== void 0 ? JSON.stringify(req.body) : void 0
+      });
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : "network error";
+      throw new PlatformError({
+        code: "unknown",
+        message: `Network error: ${msg}`,
+        status: 0
+      });
+    }
+    opts.onRequest?.({
+      method: req.method,
+      url,
+      status: res.status,
+      durationMs: Date.now() - started,
+      attempt: 1
+    });
+    if (!res.ok || !res.body) {
+      const text = await res.text().catch(() => "");
+      let parsed = void 0;
+      try {
+        parsed = text ? JSON.parse(text) : void 0;
+      } catch {
+      }
+      const errObj = parsed?.error;
+      throw new PlatformError({
+        code: errObj?.code ?? "unknown",
+        message: errObj?.message ?? res.statusText ?? `HTTP ${res.status}`,
+        status: res.status,
+        field: errObj?.field,
+        docsUrl: errObj?.docs_url,
+        body: parsed ?? text
+      });
+    }
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buf = "";
+    while (true) {
+      const { value, done } = await reader.read();
+      if (done) return;
+      buf += decoder.decode(value, { stream: true });
+      let idx;
+      while ((idx = buf.indexOf("\n\n")) >= 0) {
+        const block = buf.slice(0, idx);
+        buf = buf.slice(idx + 2);
+        let event = "message";
+        let data = "";
+        for (const line of block.split("\n")) {
+          if (line.startsWith(":")) continue;
+          if (line.startsWith("event:")) event = line.slice(6).trim();
+          else if (line.startsWith("data:")) data += line.slice(5).trim();
+        }
+        if (!data) continue;
+        try {
+          const parsed = JSON.parse(data);
+          yield { type: event, ...parsed };
+        } catch {
+        }
+      }
+    }
+  }
+  return { request, stream };
 };
 
 // src/resources/me.ts
@@ -482,6 +557,102 @@ var createOrgsResource = (http) => ({
   }
 });
 
+// src/resources/rooms.ts
+var createRoomsResource = (http) => ({
+  // Provision a new room. Server returns 201 with ONE shared room-level
+  // `joinToken` + `joinUrl`. Share the single link with everyone you want in
+  // the room — each visitor supplies their own display name at join time and
+  // becomes a fresh, distinct participant. The server persists only the
+  // token's sha256 hash; the raw token is returned here once and never stored.
+  create: async (input) => http.request({
+    method: "POST",
+    path: "/v1/rooms",
+    body: input
+  }),
+  // Listing — opaque cursor pagination (`nextCursor` returned by the server
+  // is whatever startAfter() needs, don't parse client-side).
+  list: async (filters = {}) => {
+    const query = {};
+    if (filters.status) query.status = filters.status;
+    if (filters.limit !== void 0) query.limit = filters.limit;
+    if (filters.cursor) query.cursor = filters.cursor;
+    return http.request({
+      method: "GET",
+      path: "/v1/rooms",
+      query
+    });
+  },
+  // Fetch a single room. 404s are surfaced as PlatformError('not_found').
+  get: async (roomId) => http.request({
+    method: "GET",
+    path: `/v1/rooms/${roomId}`
+  }),
+  // Transcript pages — utterances are ordered by `startedAt asc`. Cursor is
+  // an ISO timestamp (server enforces, don't construct yourself).
+  transcript: async (roomId, opts = {}) => {
+    const query = {};
+    if (opts.cursor) query.cursor = opts.cursor;
+    if (opts.limit !== void 0) query.limit = opts.limit;
+    return http.request({
+      method: "GET",
+      path: `/v1/rooms/${roomId}/transcript`,
+      query
+    });
+  },
+  // End a room — async on the server: returns 202 + eventId once the
+  // controlEvents entry is written. The room-worker observes the entry,
+  // broadcasts the system message, and tears down LiveKit shortly after.
+  end: async (roomId) => http.request({
+    method: "POST",
+    path: `/v1/rooms/${roomId}/end`
+  })
+});
+
+// src/resources/chats.ts
+var createChatsResource = (http, callToken) => ({
+  async start(input) {
+    const tokenQs = `?token=${encodeURIComponent(callToken)}`;
+    const streamIterable = http.stream({
+      method: "POST",
+      path: `/v1/agents/${input.agentId}/chat${tokenQs}`,
+      body: input.text ? { text: input.text } : {}
+    });
+    let chatId = "";
+    let callId = "";
+    const buffered = [];
+    const iter = streamIterable[Symbol.asyncIterator]();
+    while (true) {
+      const { value, done } = await iter.next();
+      if (done) break;
+      if (value.type === "chat.started") {
+        chatId = value.chatId;
+        callId = value.callId;
+        break;
+      }
+      buffered.push(value);
+    }
+    return {
+      id: chatId,
+      callId,
+      greeting: replayThen(buffered, { [Symbol.asyncIterator]: () => iter }),
+      send(text) {
+        return http.stream({
+          method: "POST",
+          path: `/v1/chats/${chatId}/messages${tokenQs}`,
+          body: { text }
+        });
+      },
+      async end() {
+        await http.request({ method: "DELETE", path: `/v1/calls/${callId}` });
+      }
+    };
+  }
+});
+async function* replayThen(buffered, rest) {
+  for (const x of buffered) yield x;
+  for await (const x of rest) yield x;
+}
+
 // src/PlatformClient.ts
 var PlatformClient = class {
   me;
@@ -492,6 +663,8 @@ var PlatformClient = class {
   callTokens;
   webhooks;
   orgs;
+  rooms;
+  _http;
   constructor(options) {
     if (!options.apiKey) {
       throw new Error("PlatformClient: `apiKey` is required");
@@ -512,6 +685,20 @@ var PlatformClient = class {
     this.callTokens = createCallTokensResource(http);
     this.webhooks = createWebhooksResource(http);
     this.orgs = createOrgsResource(http);
+    this.rooms = createRoomsResource(http);
+    this._http = http;
+  }
+  /**
+   * Returns a per-token chat resource bound to the given `ct_…` call token.
+   * The token must have been minted with `channel: 'text'`.
+   *
+   * Note: `chatsFor` is a factory method (not a fixed property) because the
+   * underlying resource is scoped to a single call token, whereas this client
+   * was constructed with an `sk_` admin key. Each end-user session needs its
+   * own `chatsFor(token)` handle.
+   */
+  chatsFor(callToken) {
+    return createChatsResource(this._http, callToken);
   }
 };