@craftedxp/voice-js 0.5.4 → 0.9.0

package/dist/config-D2TbvIqT.d.ts

@@ -0,0 +1,297 @@
+interface ClientTool {
+    description: string;
+    parameters: Record<string, unknown>;
+    usage?: string;
+    timeoutMs?: number;
+    example?: string;
+    handler: (args: Record<string, unknown>) => Promise<string | object> | string | object;
+}
+type ClientToolMap = Record<string, ClientTool>;
+interface ClientToolCallFrame {
+    toolCallId: string;
+    name: string;
+    args: Record<string, unknown>;
+}
+
+type CallState = 'idle' | 'connecting' | 'listening' | 'user_speaking' | 'agent_speaking' | 'ended' | 'error';
+type TranscriptEntry = {
+    id: string;
+    role: 'user';
+    text: string;
+    committed: boolean;
+} | {
+    id: string;
+    role: 'agent';
+    text: string;
+    interrupted?: boolean;
+} | {
+    id: string;
+    role: 'tool';
+    text: string;
+} | {
+    id: string;
+    role: 'system';
+    text: string;
+};
+type CallErrorCode = 'missing_credentials' | 'forbidden' | 'mic_denied' | 'mic_start_failed' | 'audio_session_failed' | 'token_expired' | 'token_invalid' | 'unauthorized' | 'network_unreachable' | 'socket_error' | 'payment_required' | 'not_found' | 'silence_timeout' | 'server_error';
+interface CallError {
+    code: CallErrorCode;
+    message: string;
+}
+type CallEndReason = 'agent_ended' | 'user_hangup' | 'timeout' | 'error';
+interface CallEndEvent {
+    reason: CallEndReason;
+    errorCode?: CallErrorCode;
+    durationMs: number;
+}
+interface VolumeEvent {
+    input: number;
+    output: number;
+}
+type ServerMessage = Record<string, unknown> & {
+    type?: string;
+};
+interface ProtocolState {
+    state: CallState;
+    transcript: TranscriptEntry[];
+    agentBubbleId: string | null;
+    idCounter: number;
+    endReason: CallEndReason | null;
+}
+declare const createProtocolState: () => ProtocolState;
+interface ProtocolCallbacks {
+    onState: (next: CallState) => void;
+    onTranscript: (entries: TranscriptEntry[]) => void;
+    onError: (err: CallError) => void;
+    onInterrupt: () => void;
+    onAgentTurnStart: (seq?: number) => void;
+    onAgentTurnEnd: (seq?: number) => void;
+    onCallEnd: (reason: CallEndReason) => void;
+    onConnected: () => void;
+    onClientToolCall: (frame: ClientToolCallFrame) => void;
+}
+declare function handleServerMessage(raw: string, state: ProtocolState, cb: ProtocolCallbacks): void;
+interface BuildWsUrlArgs {
+    apiBase: string;
+    agentId: string;
+    token: string;
+    bargeIn?: boolean;
+}
+declare function buildWsUrl(args: BuildWsUrlArgs): string;
+
+/**
+ * Browser-friendly text-channel chat session. Mint a `ct_` token with
+ * `channel: 'text'` on your backend, then call `startTextSession({...})`
+ * to open the SSE stream.
+ *
+ * Each `.send(text)` is a fresh POST; SSE-per-turn means the connection
+ * closes when each turn ends. Conversation state lives server-side on the
+ * underlying CallRecord.
+ */
+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;
+};
+interface StartTextSessionOpts {
+    baseUrl: string;
+    token: string;
+    agentId: string;
+    /** Optional inline first user message; otherwise the agent's greeting opens the stream. */
+    text?: string;
+    /** Override the global fetch (useful for tests; defaults to globalThis.fetch). */
+    fetch?: typeof fetch;
+}
+interface TextSession {
+    id: string;
+    callId: string;
+    /** Async iterable for the opening turn — greeting tokens / first reply if text was inlined. */
+    greeting: AsyncIterable<ChatEvent>;
+    /** Send a user message; returns an async iterable for the agent's reply. */
+    send(text: string): Promise<AsyncIterable<ChatEvent>>;
+    /** End the session — DELETE /v1/calls/:callId. */
+    end(): Promise<void>;
+}
+declare function startTextSession(opts: StartTextSessionOpts): Promise<TextSession>;
+
+interface FetchTokenArgs {
+    /** The agent the SDK is about to call. */
+    agentId: string;
+    /**
+     * Optional consumer-side user identifier. Round-tripped to the server
+     * as `contactId` for Phase 11 contact memory. The SDK does not
+     * inspect this; your backend uses it to scope the token mint.
+     */
+    userId?: string;
+    /**
+     * Per-call structured context lowered into the agent's effective
+     * system prompt server-side at session open. Opaque to the SDK.
+     */
+    context?: Record<string, unknown>;
+    /**
+     * String key/value pairs round-tripped on the `call.ended` webhook.
+     * Capped at 1 KB total server-side. NOT lowered into the system prompt.
+     */
+    metadata?: Record<string, string>;
+}
+/**
+ * What `fetchToken` may return. The rich object form lets the server
+ * choose the transport per call. Returning a bare string is backwards-
+ * compatible — the SDK treats it as `{ token, transport: 'ws' }`.
+ */
+interface FetchTokenResult {
+    /** Raw `ct_` to feed into the WS open / WebRTC offer. */
+    token: string;
+    /** Server-selected transport. Default `'ws'` if absent. */
+    transport?: 'ws' | 'webrtc';
+    /** Required when `transport === 'webrtc'` AND the server uses a
+     *  separate signaling gateway. When omitted on a webrtc result, the
+     *  SDK falls back to the API base's Phase-1 routes (local dev). */
+    webrtcGatewayBase?: string;
+}
+type FetchToken = (args: FetchTokenArgs) => Promise<string | FetchTokenResult>;
+interface VoiceClientConfig {
+    /**
+     * Full HTTPS URL of the Voissia server. The WebSocket scheme is
+     * derived: `https` → `wss`, `http` → `ws`. No trailing slash needed.
+     */
+    apiBase: string;
+    /**
+     * Called by the SDK whenever it needs a fresh `ct_` token (initial
+     * connect; mid-call refresh on `token_expired`). Your implementation
+     * should hit YOUR backend, which holds the `sk_` API key and mints
+     * via `POST /v1/call-tokens` (or `client.callTokens.mint` from
+     * @craftedxp/sdk-node). Never embed `sk_` in JS code that ships to a
+     * client.
+     */
+    fetchToken: FetchToken;
+    /**
+     * Optional metadata applied to EVERY startCall. Per-call `metadata`
+     * in `startCall` is merged on top (per-call wins on key conflicts).
+     * Useful for dashboard-wide tags like `{ surface: 'web', appVersion }`.
+     */
+    defaultMetadata?: Record<string, string>;
+    /**
+     * Optional context applied to EVERY startCall. Per-call `context` in
+     * `startCall` is merged on top. Useful for cross-call invariants like
+     * the signed-in user's locale.
+     */
+    defaultContext?: Record<string, unknown>;
+}
+interface StartCallOptions {
+    /** The agent to call. */
+    agentId: string;
+    /** Per-call user identifier. Round-tripped to fetchToken as `userId`. */
+    userId?: string;
+    /**
+     * Per-call structured context. Merged on top of `defaultContext`
+     * configured at factory time.
+     */
+    context?: Record<string, unknown>;
+    /**
+     * Per-call metadata. Merged on top of `defaultMetadata` configured
+     * at factory time.
+     */
+    metadata?: Record<string, string>;
+    /**
+     * When false, the SDK + server stay full-duplex but barge-in is
+     * suppressed. Useful for alarm-style flows where the user shouldn't
+     * accidentally interrupt the script. Default true.
+     */
+    bargeIn?: boolean;
+    /**
+     * Client-side tools the agent's LLM can call mid-conversation. Each
+     * tool's handler runs on the consumer's side; result is fed back to
+     * the LLM through the existing call WebSocket. Schema and handler
+     * colocate. Validated synchronously at startCall — bad input throws.
+     *
+     * See docs/sdks.md ("Client tools") for the wire protocol and the
+     * server-side guarantees.
+     */
+    clientTools?: ClientToolMap;
+    /**
+     * Test-only escape hatch — pass a pre-minted `ct_` directly and skip
+     * the `fetchToken` call. Don't use this in production code: tokens
+     * expire and the SDK can't re-mint without the callback.
+     */
+    token?: string;
+    onStateChange?: (state: CallState) => void;
+    onTranscript?: (entries: TranscriptEntry[]) => void;
+    onError?: (err: CallError) => void;
+    onEnd?: (end: CallEndEvent) => void;
+    /** Volume-meter event for VU UIs. ~10 Hz cadence (browser bundle only). */
+    onVolume?: (vol: VolumeEvent) => void;
+    /**
+     * Fires when the server signals barge-in (the user started talking
+     * mid-agent-turn). The browser bundle automatically flushes its
+     * built-in audio playback before this callback runs; the callback is
+     * fired regardless. Node / Electron consumers with custom playback
+     * should drain their audio queue here so the agent goes silent
+     * immediately.
+     */
+    onInterrupt?: () => void;
+    /**
+     * Fires on `agent_turn_start` — the server has begun a new agent
+     * turn. The state-machine transition to `agent_speaking` happens at
+     * the same moment via `onStateChange`; use this when you want a
+     * precise turn anchor (e.g. "agent has been speaking for N ms" UIs)
+     * without diffing state.
+     */
+    onAgentTurnStart?: () => void;
+}
+interface Call {
+    /** Current state. Snapshot — subscribe via onStateChange for live updates. */
+    readonly state: CallState;
+    /** Full transcript so far. Snapshot — subscribe via onTranscript for live updates. */
+    readonly transcript: TranscriptEntry[];
+    /** True after `mute()` and before `unmute()`. */
+    readonly isMuted: boolean;
+    /** End the call locally. Closes the WS, stops the mic, fires onEnd. Idempotent. */
+    end: () => void;
+    /** Mute mic frames. Wire stays active so server endpointing doesn't false-positive. Idempotent. */
+    mute: () => void;
+    /** Unmute mic frames. Idempotent. */
+    unmute: () => void;
+}
+interface VoiceClientFactory {
+    /** Read back the resolved config (post trailing-slash normalisation). */
+    readonly config: VoiceClientConfig;
+    /**
+     * Open a fresh call. Returns when the WS is open; rejects on
+     * pre-flight failure (missing config, fetchToken throw, etc). Mid-
+     * call failures arrive via the per-call `onError` callback — they
+     * don't reject this promise.
+     */
+    startCall: (options: StartCallOptions) => Promise<Call>;
+    /**
+     * Open a text-channel chat session (no microphone / audio required).
+     * Mint a `ct_` token with `channel: 'text'` server-side, then call
+     * this to connect. Returns a `TextSession` with:
+     *   - `.greeting` — async iterable for the opening turn
+     *   - `.send(text)` — send a user message; returns an async iterable for the reply
+     *   - `.end()` — close the session (DELETE /v1/calls/:callId)
+     */
+    startTextSession?: (opts: Omit<StartTextSessionOpts, 'baseUrl' | 'fetch'>) => Promise<TextSession>;
+}
+
+export { type Call as C, type FetchToken as F, type ProtocolCallbacks as P, type ServerMessage as S, type TextSession as T, type VoiceClientConfig as V, type VoiceClientFactory as a, type CallEndEvent as b, type CallEndReason as c, type CallError as d, type CallErrorCode as e, type CallState as f, type ChatEvent as g, type ClientTool as h, type ClientToolMap as i, type FetchTokenArgs as j, type FetchTokenResult as k, type ProtocolState as l, type StartCallOptions as m, type StartTextSessionOpts as n, type TranscriptEntry as o, type VolumeEvent as p, buildWsUrl as q, createProtocolState as r, handleServerMessage as s, startTextSession as t };