@craftedxp/sdk-node 0.10.1 → 0.15.0

package/dist/index.d.ts

@@ -23,6 +23,7 @@ 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>;
 
@@ -30,6 +31,16 @@ type TtsProvider = 'pockettts' | 'cartesia' | 'fish-audio' | 'gemini' | 'kokoro'
 type SttProvider = 'deepgram';
 type LlmProvider = 'gemini' | 'openai' | 'anthropic';
 type EndpointingMode = 'smart' | 'simple';
+/**
+ * Agent kind. Set at creation and immutable thereafter — changing what an
+ * agent does means creating a new one. Gates which routes accept the agent:
+ *   - `assistant`  — 1:1 voice + text chat + learning mode (LLM + STT + TTS)
+ *   - `room`       — hosts LiveKit rooms; per-speaker transcription + analysis
+ *   - `transcribe` — 1:1 dictation, STT-only (the agent never speaks)
+ *
+ * Replaces the legacy `canHostRooms` / `transcribeOnly` boolean flags.
+ */
+type AgentType = 'assistant' | 'room' | 'transcribe';
 interface AgentVoice {
     provider: TtsProvider;
     voiceId?: string;
@@ -108,6 +119,8 @@ interface AgentRecording {
 interface Agent {
     agentId: string;
     orgId: string;
+    /** Agent kind — see {@link AgentType}. Immutable after creation. */
+    type: AgentType;
     name: string;
     systemPrompt: string;
     /**
@@ -118,6 +131,8 @@ interface Agent {
      * caller speaks first.
      */
     agentSpeaksFirst?: boolean;
+    /** Personal assistant (`assistant` agents only) — the learning tools are live on every `ct_`-token call, not just `mode=learning`. */
+    isPersonal?: boolean;
     voice: AgentVoice;
     transcriber: AgentTranscriber;
     model: AgentModel;
@@ -150,19 +165,22 @@ interface Agent {
      * right gateway.
      */
     transport?: 'ws' | 'webrtc';
-    /** Whether this agent may host multi-party video rooms. */
-    canHostRooms?: boolean;
-    /** Room operating mode (`'notes-only'` today). */
+    /** Room operating mode (`'notes-only'` today). Only set on `type: 'room'` agents. */
     roomMode?: 'notes-only';
-    /** Transcribe-only mode — the agent listens but never speaks. */
-    transcribeOnly?: boolean;
     createdAt: number;
     updatedAt: number;
 }
 interface AgentCreateInput {
+    /**
+     * Agent kind — see {@link AgentType}. Required and immutable: it cannot be
+     * changed via {@link AgentUpdateInput} (it is omitted from that type).
+     */
+    type: AgentType;
     name: string;
     systemPrompt: string;
     agentSpeaksFirst?: boolean;
+    /** Personal assistant (`assistant` agents only) — the learning tools are live on every `ct_`-token call, not just `mode=learning`. */
+    isPersonal?: boolean;
     voice?: AgentVoice;
     transcriber?: AgentTranscriber;
     model?: AgentModel;
@@ -184,26 +202,18 @@ interface AgentCreateInput {
      */
     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.
+     * Room operating mode. Only valid on `type: 'room'` agents. 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>;
+/**
+ * Patch shape for `agents.update`. `type` is immutable, so it is omitted
+ * here — to change an agent's kind, create a new agent.
+ */
+type AgentUpdateInput = Partial<Omit<AgentCreateInput, 'type'>>;
 /**
  * Trimmed agent shape returned by the consumer catalog
  * (`GET /v1/orgs/:orgId/agents`). Operator-only fields like
@@ -283,6 +293,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;
@@ -385,6 +397,18 @@ interface CallTokenMintInput {
      * 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. `text` requires
+     * a `type: 'assistant'` agent; non-assistant agents are rejected at mint
+     * (`wrong_agent_type`), as is `mode: 'learning'` on a non-assistant agent.
+     */
+    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;
@@ -406,6 +430,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;
@@ -416,7 +446,7 @@ interface CallTokenSummary {
     revoked: boolean;
     allowedOrigins?: string[];
 }
-type PlatformEventName = 'call.started' | 'call.ended' | 'transcript.updated' | 'call.summary.ready' | 'tool.call.requested' | 'tool.call.completed' | 'tool.call.failed' | 'credits.low';
+type PlatformEventName = 'call.started' | 'call.ended' | 'transcript.updated' | 'call.summary.ready' | 'tool.call.requested' | 'tool.call.completed' | 'tool.call.failed' | 'credits.low' | 'speech.ready' | 'speech.failed';
 interface WebhookConfig {
     webhookId: string;
     orgId: string;
@@ -470,6 +500,17 @@ interface CreateRoomInput {
     agentId: string;
     /** 1..240 — enforced by the server. */
     durationMin: number;
+    /**
+     * Document references forwarded to the room analyzer. Each `docId` is an
+     * analysis document (`adoc_…`) uploaded via `POST /v1/analysis-docs` (NOT a
+     * knowledge-base file), tagged with an optional semantic role (e.g. `'jd'`,
+     * `'cv'`); the worker loads the full text and injects it into the analyzer.
+     * Omit when the room agent uses its default analysis behaviour.
+     */
+    analysisContext?: Array<{
+        docId: string;
+        role?: string;
+    }>;
 }
 interface CreateRoomResponse {
     roomId: string;
@@ -532,11 +573,159 @@ interface ListUtterancesResponse {
     utterances: UtteranceWire[];
     nextCursor: string | null;
 }
+interface AnalysisWire {
+    analysisId: string;
+    participantId: string;
+    label: string;
+    score?: number;
+    note?: string;
+    createdAt: string;
+    /**
+     * Which producer emitted this result: `'summary'` | `'rated_dimensions'` |
+     * `'suggested_questions'`. Set by the worker on every result it produces;
+     * absent only on legacy analysis entries written before producers existed.
+     */
+    producer?: string;
+}
+interface ListAnalysisResponse {
+    analysis: AnalysisWire[];
+    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;
+};
+type SpaceKind = 'audio' | 'video';
+type RecordingMode = 'off' | 'host-source' | 'composite';
+interface RecordingConfig {
+    mode: RecordingMode;
+    maxMinutesPerSession?: number;
+    audioOnly?: boolean;
+}
+/** The redacted space shape the server returns (`toSpaceView`). */
+interface SpaceView {
+    spaceId: string;
+    agentId: string;
+    /** Stable human-friendly join code, e.g. `abc-defg-hij`. */
+    code: string;
+    kind: SpaceKind;
+    notesEnabled: boolean;
+    lobbyEnabled: boolean;
+    recording: RecordingConfig;
+    active: boolean;
+    currentSessionId: string | null;
+    sessionCount: number;
+    createdAt: string;
+    updatedAt: string;
+}
+interface CreateSpaceInput {
+    agentId: string;
+    /** Defaults to `video` server-side. */
+    kind?: SpaceKind;
+    /** Defaults to `true` server-side. */
+    notesEnabled?: boolean;
+    /** Defaults to `false` server-side. */
+    lobbyEnabled?: boolean;
+    recording?: RecordingConfig;
+}
+/** At least one field is required — the server rejects an empty patch. */
+interface SpacePatch {
+    notesEnabled?: boolean;
+    lobbyEnabled?: boolean;
+    active?: boolean;
+    recording?: RecordingConfig;
+}
+interface ListSpacesResponse {
+    data: SpaceView[];
+}
+interface SpeechSynthesizeInput {
+    agentId: string;
+    text?: string;
+    context?: Record<string, unknown>;
+    instructions?: string;
+    format?: 'mp3' | 'wav' | 'ogg';
+    sampleRate?: 16000 | 24000 | 48000;
+    idempotencyKey?: string;
+    userTags?: string[];
+    ttlSeconds?: number;
+    metadata?: Record<string, string>;
+}
+interface SpeechAsset {
+    id: string;
+    status: 'ready';
+    url: string;
+    expiresAt: string;
+    durationMs: number;
+    bytes: number;
+    format: 'mp3' | 'wav' | 'ogg';
+    sampleRate: number;
+    text: string;
+    agentId: string;
+    idempotencyKey?: string;
+    metadata?: Record<string, string>;
+    createdAt: string;
+}
+interface SpeechJob {
+    id: string;
+    status: 'queued' | 'processing' | 'failed';
+    error?: {
+        code: string;
+        message: string;
+    };
+    idempotencyKey?: string;
+    metadata?: Record<string, string>;
+    createdAt: string;
+}
+interface SpeechListInput {
+    idempotencyKeyPrefix?: string;
+    status?: 'queued' | 'processing' | 'ready' | 'failed';
+    limit?: number;
+    cursor?: string;
+}
+interface SpeechReadyEvent {
+    event: 'speech.ready';
+    timestamp: string;
+    orgId: string;
+    data: SpeechAsset;
+}
+interface SpeechFailedEvent {
+    event: 'speech.failed';
+    timestamp: string;
+    orgId: string;
+    data: SpeechJob;
+}
 
 declare const createMeResource: (http: HttpClient) => {
     get: () => Promise<MeResponse>;
@@ -678,10 +867,89 @@ declare const createRoomsResource: (http: HttpClient) => {
     list: (filters?: RoomListFilters) => Promise<ListRoomsResponse>;
     get: (roomId: string) => Promise<RoomDoc>;
     transcript: (roomId: string, opts?: RoomTranscriptOptions) => Promise<ListUtterancesResponse>;
+    analysis: (roomId: string, opts?: RoomTranscriptOptions) => Promise<ListAnalysisResponse>;
     end: (roomId: string) => Promise<RoomEventAck>;
 };
 type RoomsResource = ReturnType<typeof createRoomsResource>;
 
+type JoinUrlStyle = 'query' | 'path';
+interface BuildJoinUrlOptions {
+    /** Required — the developer's own page that renders <VoiceRoom/>. Absolute URL. */
+    baseUrl: string;
+    /** 'query' (default) → ?code=…  ·  'path' → /…  */
+    style?: JoinUrlStyle;
+}
+/**
+ * Build a participant join URL on the DEVELOPER's domain from a space (or a
+ * raw code). White-label: the returned URL never points at a voissia origin —
+ * `baseUrl` is required and supplied by the caller.
+ *
+ * The default `query` style appends `?code=<code>`, matching how
+ * `<VoiceRoom/>` (and the example app) read the code from the URL.
+ */
+declare const buildJoinUrl: (spaceOrCode: SpaceView | string, opts: BuildJoinUrlOptions) => string;
+
+declare const createSpacesResource: (http: HttpClient) => {
+    create: (input: CreateSpaceInput) => Promise<SpaceView>;
+    get: (spaceId: string) => Promise<SpaceView>;
+    list: () => Promise<ListSpacesResponse>;
+    update: (spaceId: string, patch: SpacePatch) => Promise<SpaceView>;
+    delete: (spaceId: string) => Promise<void>;
+    joinUrl: (spaceOrCode: SpaceView | string, opts: BuildJoinUrlOptions) => string;
+};
+type SpacesResource = ReturnType<typeof createSpacesResource>;
+
+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>;
+
+declare const createSpeechResource: (http: HttpClient) => {
+    /**
+     * Synchronous. Resolves with the ready asset. Throws PlatformError
+     * code 'accepted' (status 202, `body` = SpeechJob) when the server hands
+     * the job to the queue instead — poll `get(job.id)` or wait for the
+     * `speech.ready` webhook.
+     */
+    synthesize: (input: SpeechSynthesizeInput) => Promise<SpeechAsset>;
+    /**
+     * Asynchronous. Normally returns a queued/processing SpeechJob —
+     * completion arrives via the `speech.ready` / `speech.failed` webhook or
+     * a later `get(job.id)`. Exception: when `idempotencyKey` matches an
+     * existing *ready* asset, the server short-circuits the queue hop and
+     * responds 200 with that SpeechAsset directly instead of 202.
+     */
+    enqueue: (input: SpeechSynthesizeInput) => Promise<SpeechJob | SpeechAsset>;
+    get: (id: string) => Promise<SpeechAsset | SpeechJob>;
+    list: (input?: SpeechListInput) => Promise<{
+        items: Array<SpeechAsset | SpeechJob>;
+        cursor?: string;
+    }>;
+    /** Idempotent. Deleting a ready asset invalidates its URL immediately. */
+    delete: (id: string) => Promise<void>;
+};
+type SpeechResource = ReturnType<typeof createSpeechResource>;
+
 interface PlatformClientOptions {
     apiKey: string;
     baseUrl?: string;
@@ -700,10 +968,23 @@ declare class PlatformClient {
     readonly webhooks: WebhooksResource;
     readonly orgs: OrgsResource;
     readonly rooms: RoomsResource;
+    readonly spaces: SpacesResource;
+    readonly speech: SpeechResource;
+    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';
+type ApiErrorCode = 'unauthorized' | 'forbidden' | 'not_found' | 'bad_request' | 'conflict' | 'rate_limited' | 'payment_required' | 'internal_error' | 'accepted' | 'service_unavailable' | 'unknown';
 declare class PlatformError extends Error {
     readonly code: ApiErrorCode;
     readonly status: number;
@@ -723,4 +1004,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 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 SttProvider, type TranscriptTurn, type TtsProvider, type UtteranceWire, type WebhookConfig, type WebhookCreateInput, type WebhookDelivery, type WebhookUpdateInput, type WebhooksResource, type WorkerStatus, 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 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 };