@craftedxp/sdk-node 0.17.0 → 0.19.0

package/README.md

@@ -283,7 +283,9 @@ for await (const call of client.calls.listAll({ agentId })) {
 
 ## Changelog
 
+- **0.19.0** — type-only: `CallTokenMintResult.transport` widened to `'ws' | 'webrtc' | 'livekit'` (server returns `'livekit'` when the platform media edge is LiveKit Cloud; client SDKs that don't know it fall back to `'ws'`); `CallRecord.transport` added. No runtime change; drop-in for 0.18.0 consumers.
 - **Unreleased** _(forward-looking)_ — `isPersonal?: boolean` on `Agent` and `AgentCreateInput` (and so on `AgentUpdateInput`). Assistant-only: when `true`, the learning tools (`remember_fact`, `add_correction`, `add_skill_hint`) are live on every `ct_`-token call rather than only on `mode=learning`. Server-side field — no runtime change in this package.
+- **Unreleased** _(forward-looking)_ — Per-call `agentSpeaksFirst` override on `callTokens.mint` (0.18.0, publish pending; server support 2026-09-02).
 - **0.17.0** — `channel` on `CallTokenMintInput` / `CallTokenMintResult` / `CallRecord` widened to include `'multimodal'` (typed turns + live audio in one WS session). Type-only plumbing in this package — accepted at mint (assistant-only, same gate as `'text'`) and threaded through; the server's handler semantics for it shipped 2026-09-01 (phase 2/3); `chatsFor(token)` (HTTP+SSE) always rejects a `'multimodal'` token. No runtime change in this package.
 - **0.16.0** — `debug?: boolean` on `CallTokenMintInput`. Operator-gated (Firebase-admin or `sk_`-key mints only — silently stripped otherwise); when set, the call streams diagnostic frames (`tool_call` / `tool_result` / `phase_marker` / `prefetch*`) to the client. Request-only field — the mint response does not echo it back (see `docs/openapi.yaml`). No client-side behavior change; the HTTP layer already posts `body: input` verbatim, so this is a type-only addition.
 - **0.15.0** — `client.speech` namespace (`synthesize` / `enqueue` / `get` / `list` / `delete`) for pre-generated agent audio (`POST /v1/speech`), plus `speech.ready` / `speech.failed` webhook event types and the `accepted` error code (`synthesize` → 202 handoff). Requires server ≥ the 2026-08 speech release.

package/dist/index.d.mts

@@ -249,6 +249,13 @@ interface CatalogListInput {
     userTags?: string[];
 }
 type CallStatus = 'queued' | 'ringing' | 'in_progress' | 'completed' | 'failed' | 'no_answer';
+/**
+ * Media path a call was carried over. Shared by {@link CallRecord.transport}
+ * (what actually served the call) and {@link CallTokenMintResult.transport}
+ * (what the server tells the client to use). `'livekit'` was added in 0.19.0
+ * (phase 35 media edge).
+ */
+type CallTransport = 'ws' | 'webrtc' | 'livekit';
 type EndReason = 'caller_hung_up' | 'agent_ended' | 'max_duration' | 'silence_timeout' | 'error';
 interface TranscriptTurn {
     role: 'user' | 'assistant';
@@ -286,6 +293,8 @@ interface CallRecord {
     endedAt?: number;
     durationSeconds?: number;
     endReason?: EndReason;
+    /** Media path that served the call (phase 35): 'livekit' = LiveKit tracks + WS control; 'webrtc' = the Cloud Run-hosted WebRTC route; 'ws' = plain WebSocket audio (also what gateway-proxied WebRTC calls record). Absent on telephony calls and records created before 2026-09-05. */
+    transport?: CallTransport;
     transcript?: TranscriptTurn[];
     summary?: string;
     structuredData?: Record<string, unknown>;
@@ -397,6 +406,22 @@ interface CallTokenMintInput {
      * default user-initiated connect. See docs/sdks.md "Agent-initiated calls".
      */
     initiatedBy?: 'user' | 'agent';
+    /**
+     * Per-call override of the agent's `agentSpeaksFirst`. `false` opens the
+     * call silently — the caller speaks first (a look-to-wake desk device, a
+     * "tap to talk" surface). `true` forces the agent's greeting turn even on
+     * an agent configured silent (an alarm the device dialled on the user's
+     * behalf, briefed via `context`). Omit to use the agent's own setting.
+     * Assistant agents only; room/transcribe agents are always silent and the
+     * field is accepted but ignored. The `context` briefing shapes the
+     * greeting only when the agent has no pre-rendered `opening`; an agent
+     * with `opening.enabled` plays its static opening line. With `false`, the
+     * platform also suppresses its idle "are you still there?" nudge until
+     * the caller's first turn; a caller who never speaks is simply timed out
+     * in silence.
+     * Server support: 2026-09-02.
+     */
+    agentSpeaksFirst?: boolean;
     /**
      * Session channel selector. `voice` (default) routes to WS/WebRTC audio;
      * `text` routes to HTTP+SSE chat via the `chats` resource (or the same WS
@@ -433,8 +458,14 @@ interface CallTokenMintResult {
      * SDK's `fetchToken` (rich return form) so it can dispatch correctly
      * without a second round-trip. Always present in the response;
      * defaults to `'ws'` for legacy agent docs missing the field.
+     *
+     * `'livekit'` (0.19.0, phase 35): the server's media edge is LiveKit
+     * Cloud — a client SDK that supports it joins a per-call LiveKit room
+     * for audio while control frames stay on the call WebSocket; client SDKs
+     * that don't recognise it fall back to `'ws'`. `webrtcGatewayBase` is
+     * only present for `'webrtc'`.
      */
-    transport?: 'ws' | 'webrtc';
+    transport?: CallTransport;
     /**
      * Signaling gateway base URL when `transport === 'webrtc'` AND the
      * server has `WEBRTC_GATEWAY_BASE` configured. Forward alongside
@@ -1017,4 +1048,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 AgentType, type AgentUpdateInput, type AgentVoice, type AgentWebhooksResource, type AgentsResource, type AnalysisWire, type ApiErrorCode, type BuildJoinUrlOptions, 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 CreateSpaceInput, type CreditsResource, type EndReason, type EndpointingMode, type GuestRole, type JoinUrlStyle, type KnowledgeBase, type KnowledgeBaseFile, type KnowledgeBasesResource, type LedgerEntry, type ListAnalysisResponse, type ListRoomsResponse, type ListSpacesResponse, type ListUtterancesResponse, type LlmProvider, type MeResource, type MeResponse, type OrgsResource, PlatformClient, type PlatformClientOptions, PlatformError, type PlatformEventName, type RecordingConfig, type RecordingMeta, type RecordingMode, type RoomDoc, type RoomEndReason, type RoomEventAck, type RoomListFilters, type RoomMetricsWire, type RoomStatus, type RoomTranscriptOptions, type RoomsResource, type SpaceKind, type SpacePatch, type SpaceView, type SpacesResource, type SpeechAsset, type SpeechFailedEvent, type SpeechJob, type SpeechListInput, type SpeechReadyEvent, type SpeechResource, type SpeechSynthesizeInput, type StartChatInput, type SttProvider, type TranscriptTurn, type TtsProvider, type UtteranceWire, type WebhookConfig, type WebhookCreateInput, type WebhookDelivery, type WebhookUpdateInput, type WebhooksResource, type WorkerStatus, buildJoinUrl, verifyWebhookSignature };
+export { type Agent, type AgentCreateInput, type AgentEndpointing, type AgentHttpTool, type AgentModel, type AgentRecording, type AgentTool, type AgentTranscriber, type AgentType, type AgentUpdateInput, type AgentVoice, type AgentWebhooksResource, type AgentsResource, type AnalysisWire, type ApiErrorCode, type BuildJoinUrlOptions, type CallListFilters, type CallRecord, type CallRecordingUrlResponse, type CallStatus, type CallSummary, type CallTokenMintInput, type CallTokenMintResult, type CallTokenSummary, type CallTokensResource, type CallTransport, type CallsResource, type CatalogAgent, type CatalogListInput, type Chat, type ChatEvent, type ChatsResource, type CostBreakdown, type CreateRoomInput, type CreateRoomResponse, type CreateSpaceInput, type CreditsResource, type EndReason, type EndpointingMode, type GuestRole, type JoinUrlStyle, type KnowledgeBase, type KnowledgeBaseFile, type KnowledgeBasesResource, type LedgerEntry, type ListAnalysisResponse, type ListRoomsResponse, type ListSpacesResponse, type ListUtterancesResponse, type LlmProvider, type MeResource, type MeResponse, type OrgsResource, PlatformClient, type PlatformClientOptions, PlatformError, type PlatformEventName, type RecordingConfig, type RecordingMeta, type RecordingMode, type RoomDoc, type RoomEndReason, type RoomEventAck, type RoomListFilters, type RoomMetricsWire, type RoomStatus, type RoomTranscriptOptions, type RoomsResource, type SpaceKind, type SpacePatch, type SpaceView, type SpacesResource, type SpeechAsset, type SpeechFailedEvent, type SpeechJob, type SpeechListInput, type SpeechReadyEvent, type SpeechResource, type SpeechSynthesizeInput, type StartChatInput, type SttProvider, type TranscriptTurn, type TtsProvider, type UtteranceWire, type WebhookConfig, type WebhookCreateInput, type WebhookDelivery, type WebhookUpdateInput, type WebhooksResource, type WorkerStatus, buildJoinUrl, verifyWebhookSignature };

package/dist/index.d.ts

@@ -249,6 +249,13 @@ interface CatalogListInput {
     userTags?: string[];
 }
 type CallStatus = 'queued' | 'ringing' | 'in_progress' | 'completed' | 'failed' | 'no_answer';
+/**
+ * Media path a call was carried over. Shared by {@link CallRecord.transport}
+ * (what actually served the call) and {@link CallTokenMintResult.transport}
+ * (what the server tells the client to use). `'livekit'` was added in 0.19.0
+ * (phase 35 media edge).
+ */
+type CallTransport = 'ws' | 'webrtc' | 'livekit';
 type EndReason = 'caller_hung_up' | 'agent_ended' | 'max_duration' | 'silence_timeout' | 'error';
 interface TranscriptTurn {
     role: 'user' | 'assistant';
@@ -286,6 +293,8 @@ interface CallRecord {
     endedAt?: number;
     durationSeconds?: number;
     endReason?: EndReason;
+    /** Media path that served the call (phase 35): 'livekit' = LiveKit tracks + WS control; 'webrtc' = the Cloud Run-hosted WebRTC route; 'ws' = plain WebSocket audio (also what gateway-proxied WebRTC calls record). Absent on telephony calls and records created before 2026-09-05. */
+    transport?: CallTransport;
     transcript?: TranscriptTurn[];
     summary?: string;
     structuredData?: Record<string, unknown>;
@@ -397,6 +406,22 @@ interface CallTokenMintInput {
      * default user-initiated connect. See docs/sdks.md "Agent-initiated calls".
      */
     initiatedBy?: 'user' | 'agent';
+    /**
+     * Per-call override of the agent's `agentSpeaksFirst`. `false` opens the
+     * call silently — the caller speaks first (a look-to-wake desk device, a
+     * "tap to talk" surface). `true` forces the agent's greeting turn even on
+     * an agent configured silent (an alarm the device dialled on the user's
+     * behalf, briefed via `context`). Omit to use the agent's own setting.
+     * Assistant agents only; room/transcribe agents are always silent and the
+     * field is accepted but ignored. The `context` briefing shapes the
+     * greeting only when the agent has no pre-rendered `opening`; an agent
+     * with `opening.enabled` plays its static opening line. With `false`, the
+     * platform also suppresses its idle "are you still there?" nudge until
+     * the caller's first turn; a caller who never speaks is simply timed out
+     * in silence.
+     * Server support: 2026-09-02.
+     */
+    agentSpeaksFirst?: boolean;
     /**
      * Session channel selector. `voice` (default) routes to WS/WebRTC audio;
      * `text` routes to HTTP+SSE chat via the `chats` resource (or the same WS
@@ -433,8 +458,14 @@ interface CallTokenMintResult {
      * SDK's `fetchToken` (rich return form) so it can dispatch correctly
      * without a second round-trip. Always present in the response;
      * defaults to `'ws'` for legacy agent docs missing the field.
+     *
+     * `'livekit'` (0.19.0, phase 35): the server's media edge is LiveKit
+     * Cloud — a client SDK that supports it joins a per-call LiveKit room
+     * for audio while control frames stay on the call WebSocket; client SDKs
+     * that don't recognise it fall back to `'ws'`. `webrtcGatewayBase` is
+     * only present for `'webrtc'`.
      */
-    transport?: 'ws' | 'webrtc';
+    transport?: CallTransport;
     /**
      * Signaling gateway base URL when `transport === 'webrtc'` AND the
      * server has `WEBRTC_GATEWAY_BASE` configured. Forward alongside
@@ -1017,4 +1048,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 AgentType, type AgentUpdateInput, type AgentVoice, type AgentWebhooksResource, type AgentsResource, type AnalysisWire, type ApiErrorCode, type BuildJoinUrlOptions, 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 CreateSpaceInput, type CreditsResource, type EndReason, type EndpointingMode, type GuestRole, type JoinUrlStyle, type KnowledgeBase, type KnowledgeBaseFile, type KnowledgeBasesResource, type LedgerEntry, type ListAnalysisResponse, type ListRoomsResponse, type ListSpacesResponse, type ListUtterancesResponse, type LlmProvider, type MeResource, type MeResponse, type OrgsResource, PlatformClient, type PlatformClientOptions, PlatformError, type PlatformEventName, type RecordingConfig, type RecordingMeta, type RecordingMode, type RoomDoc, type RoomEndReason, type RoomEventAck, type RoomListFilters, type RoomMetricsWire, type RoomStatus, type RoomTranscriptOptions, type RoomsResource, type SpaceKind, type SpacePatch, type SpaceView, type SpacesResource, type SpeechAsset, type SpeechFailedEvent, type SpeechJob, type SpeechListInput, type SpeechReadyEvent, type SpeechResource, type SpeechSynthesizeInput, type StartChatInput, type SttProvider, type TranscriptTurn, type TtsProvider, type UtteranceWire, type WebhookConfig, type WebhookCreateInput, type WebhookDelivery, type WebhookUpdateInput, type WebhooksResource, type WorkerStatus, buildJoinUrl, verifyWebhookSignature };
+export { type Agent, type AgentCreateInput, type AgentEndpointing, type AgentHttpTool, type AgentModel, type AgentRecording, type AgentTool, type AgentTranscriber, type AgentType, type AgentUpdateInput, type AgentVoice, type AgentWebhooksResource, type AgentsResource, type AnalysisWire, type ApiErrorCode, type BuildJoinUrlOptions, type CallListFilters, type CallRecord, type CallRecordingUrlResponse, type CallStatus, type CallSummary, type CallTokenMintInput, type CallTokenMintResult, type CallTokenSummary, type CallTokensResource, type CallTransport, type CallsResource, type CatalogAgent, type CatalogListInput, type Chat, type ChatEvent, type ChatsResource, type CostBreakdown, type CreateRoomInput, type CreateRoomResponse, type CreateSpaceInput, type CreditsResource, type EndReason, type EndpointingMode, type GuestRole, type JoinUrlStyle, type KnowledgeBase, type KnowledgeBaseFile, type KnowledgeBasesResource, type LedgerEntry, type ListAnalysisResponse, type ListRoomsResponse, type ListSpacesResponse, type ListUtterancesResponse, type LlmProvider, type MeResource, type MeResponse, type OrgsResource, PlatformClient, type PlatformClientOptions, PlatformError, type PlatformEventName, type RecordingConfig, type RecordingMeta, type RecordingMode, type RoomDoc, type RoomEndReason, type RoomEventAck, type RoomListFilters, type RoomMetricsWire, type RoomStatus, type RoomTranscriptOptions, type RoomsResource, type SpaceKind, type SpacePatch, type SpaceView, type SpacesResource, type SpeechAsset, type SpeechFailedEvent, type SpeechJob, type SpeechListInput, type SpeechReadyEvent, type SpeechResource, type SpeechSynthesizeInput, type StartChatInput, type SttProvider, type TranscriptTurn, type TtsProvider, type UtteranceWire, type WebhookConfig, type WebhookCreateInput, type WebhookDelivery, type WebhookUpdateInput, type WebhooksResource, type WorkerStatus, buildJoinUrl, verifyWebhookSignature };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@craftedxp/sdk-node",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "description": "Node.js / TypeScript SDK for the voice agent platform. Server-side API client — mint call tokens, manage agents, query calls, upload knowledge-base docs.",
   "author": "Crafted XP",
   "license": "MIT",