@craftedxp/sdk-node 0.9.0 → 0.12.0

package/README.md

@@ -24,16 +24,24 @@ const client = new PlatformClient({
   baseUrl: 'https://api.your-server.com', // or http://localhost:8080 for dev
 })
 
-// In your "/voice-token" route handler — called by the RN SDK's fetchToken:
+// In your "/voice-token" route handler — called by the client SDK's fetchToken:
 async function mintForCall({ agentId, userId, context, metadata }) {
-  const { token } = await client.callTokens.mint({
+  const result = await client.callTokens.mint({
     agentId,
     ttlSeconds: 600, // 10 min default; up to 3600 (60 min)
     contactId: userId, // optional → cross-call memory
     context, // optional arbitrary JSON, lowered into agent's system prompt
     metadata, // optional opaque keys round-tripped on call.ended webhook (≤1 KB)
   })
-  return { token } // hand to the RN SDK
+  // Forward `transport` + `webrtcGatewayBase` so the client SDK can
+  // dispatch WS vs WebRTC based on the agent's configuration. New agents
+  // default to `transport: 'webrtc'` (2026-05-16); WS stays as the
+  // back-compat fallback for legacy agents and older client builds.
+  return {
+    token: result.token,
+    transport: result.transport,
+    webrtcGatewayBase: result.webrtcGatewayBase,
+  }
 }
 ```
 
@@ -72,6 +80,57 @@ client.credits.getBalance()                                  // billing
 client.credits.getLedger({ limit, cursor })
 
 client.webhooks.deliveries({ agentId, callId, webhookId })   // org-wide delivery log
+
+client.rooms.create({ agentId, durationMin })                // multi-party video rooms
+client.rooms.list({ status, limit, cursor })
+client.rooms.get(roomId)
+client.rooms.transcript(roomId, { cursor, limit })
+client.rooms.end(roomId)
+```
+
+## Multi-party video rooms
+
+Provision a hosted room from your backend; share the single returned link;
+participants join with **video** in the browser via `@craftedxp/voice-js`
+(`joinRoom`). The room always includes a silent AI notetaker that transcribes
+per speaker — the human-to-human video call works regardless.
+
+```ts
+// Backend — the agent must be allowed to host rooms. Enable it from code
+// (since 0.10.1) instead of the dashboard:
+await client.agents.update(agentId, { canHostRooms: true, roomMode: 'notes-only' })
+// (you can also pass canHostRooms/roomMode to `agents.create`.)
+
+// Mint a room. Returns ONE shared joinToken + a joinUrl; the raw token is
+// returned once and never stored.
+const room = await client.rooms.create({ agentId, durationMin: 30 })
+// → { roomId, status: 'provisioning', joinToken, joinUrl, expiresAt }
+
+// Hand `roomId` + `joinToken` to the browser. There, with @craftedxp/voice-js:
+//   const session = await configureVoiceClient({ apiBase }).joinRoom({
+//     roomId, joinCode: joinToken, name,
+//   })
+//   await session.publishMic(); await session.publishCamera()
+//   session.on('track.subscribed', ({ kind, track }) => kind === 'video' && track.attach(el))
+
+// Read the transcript (cursor-paginated, oldest first) or end the room early:
+const page = await client.rooms.transcript(room.roomId, { limit: 100 })
+await client.rooms.end(room.roomId)
+```
+
+A complete, runnable consumer app (backend + browser video UI) lives in
+[`examples/video-call`](../../examples/video-call).
+
+### Transcribe-only agents
+
+Set `transcribeOnly: true` (on `agents.create` or `agents.update`, since 0.10.1)
+for an agent that **listens but never speaks** — no TTS/LLM, no greeting; user
+turns stream back as `transcript` data-messages over the existing call/WebRTC
+transport. Useful for note-taking / dictation surfaces that reuse the agent +
+call-mint plumbing but want the agent silent.
+
+```ts
+await client.agents.create({ name: 'Scribe', systemPrompt: 'n/a', transcribeOnly: true })
 ```
 
 ## Webhook signature verification

package/dist/index.d.mts

@@ -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 };