@craftedxp/voice-js 0.5.4 → 0.9.0

package/dist/incomingCall-CfRRzj2P.d.mts

@@ -0,0 +1,103 @@
+type OnChunk = (pcm: ArrayBuffer) => void;
+type OnVolume$1 = (rms01: number) => void;
+type OnError = (err: Error) => void;
+interface CaptureOptions {
+    onChunk: OnChunk;
+    onVolume?: OnVolume$1;
+    onError?: OnError;
+}
+interface CaptureController {
+    start: () => Promise<void>;
+    stop: () => void;
+    mute: (muted: boolean) => void;
+    isCapturing: () => boolean;
+}
+declare const createAudioCapture: (options: CaptureOptions) => CaptureController;
+
+type OnVolume = (rms01: number) => void;
+type OnAgentSpeakingChange = (speaking: boolean) => void;
+interface PlaybackOptions {
+    sampleRate?: number;
+    onVolume?: OnVolume;
+    onSpeakingChange?: OnAgentSpeakingChange;
+}
+interface PlaybackController {
+    enqueue: (pcm: ArrayBuffer) => void;
+    flush: () => void;
+    close: () => void;
+    resume: () => Promise<void>;
+}
+declare const createAudioPlayback: (options?: PlaybackOptions) => PlaybackController;
+
+type RWSEvent = {
+    type: 'open';
+} | {
+    type: 'reconnected';
+} | {
+    type: 'message';
+    data: string | ArrayBuffer;
+} | {
+    type: 'close';
+    code: number;
+    reason: string;
+    permanent: boolean;
+} | {
+    type: 'error';
+    error: Error;
+};
+interface WebSocketLike {
+    binaryType: string;
+    readyState: number;
+    onopen: ((ev: unknown) => void) | null;
+    onmessage: ((ev: {
+        data: string | ArrayBuffer;
+    }) => void) | null;
+    onerror: ((ev: unknown) => void) | null;
+    onclose: ((ev: {
+        code: number;
+        reason: string;
+    }) => void) | null;
+    send: (data: string | ArrayBuffer | ArrayBufferView) => void;
+    close: (code?: number, reason?: string) => void;
+}
+type WebSocketFactory = (url: string) => WebSocketLike;
+interface RWSOptions {
+    url: string;
+    wsFactory: WebSocketFactory;
+    maxRetries?: number;
+    initialBackoffMs?: number;
+    maxBackoffMs?: number;
+}
+declare const createReconnectingWebSocket: (options: RWSOptions, onEvent: (ev: RWSEvent) => void) => {
+    send: (data: string | ArrayBuffer | ArrayBufferView) => void;
+    close: (code?: number, reason?: string) => void;
+    readyState: () => number;
+};
+type ReconnectingWebSocket = ReturnType<typeof createReconnectingWebSocket>;
+
+/**
+ * Canonical payload a tenant places in their VoIP/FCM push so an
+ * agent-initiated call can connect. It is the `callTokens.mint` result
+ * (token + transport) plus two optional display fields for the native
+ * incoming-call UI. The host receives the push, runs `parseIncomingCall`,
+ * and on accept passes `token` (+ transport / webrtcGatewayBase) into the
+ * voice client. Web background-wake is best-effort (Web Push); native is
+ * the real target. See docs/sdks.md "Agent-initiated calls".
+ */
+interface IncomingCallPayload {
+    token: string;
+    agentId: string;
+    transport: 'ws' | 'webrtc';
+    webrtcGatewayBase?: string;
+    expiresAt?: number;
+    agentName?: string;
+    agentAvatarUrl?: string;
+}
+/**
+ * Validate + normalise a raw push payload into an IncomingCallPayload.
+ * Throws synchronously on malformed input. Unknown transports fall back to
+ * 'ws'; webrtcGatewayBase is ignored unless transport === 'webrtc'.
+ */
+declare const parseIncomingCall: (raw: unknown) => IncomingCallPayload;
+
+export { type CaptureController as C, type IncomingCallPayload as I, type OnAgentSpeakingChange as O, type PlaybackController as P, type RWSEvent as R, type WebSocketFactory as W, type CaptureOptions as a, type OnChunk as b, type OnError as c, type OnVolume$1 as d, type PlaybackOptions as e, type RWSOptions as f, type ReconnectingWebSocket as g, type WebSocketLike as h, createAudioCapture as i, createAudioPlayback as j, createReconnectingWebSocket as k, parseIncomingCall as p };

package/dist/incomingCall-CfRRzj2P.d.ts

@@ -0,0 +1,103 @@
+type OnChunk = (pcm: ArrayBuffer) => void;
+type OnVolume$1 = (rms01: number) => void;
+type OnError = (err: Error) => void;
+interface CaptureOptions {
+    onChunk: OnChunk;
+    onVolume?: OnVolume$1;
+    onError?: OnError;
+}
+interface CaptureController {
+    start: () => Promise<void>;
+    stop: () => void;
+    mute: (muted: boolean) => void;
+    isCapturing: () => boolean;
+}
+declare const createAudioCapture: (options: CaptureOptions) => CaptureController;
+
+type OnVolume = (rms01: number) => void;
+type OnAgentSpeakingChange = (speaking: boolean) => void;
+interface PlaybackOptions {
+    sampleRate?: number;
+    onVolume?: OnVolume;
+    onSpeakingChange?: OnAgentSpeakingChange;
+}
+interface PlaybackController {
+    enqueue: (pcm: ArrayBuffer) => void;
+    flush: () => void;
+    close: () => void;
+    resume: () => Promise<void>;
+}
+declare const createAudioPlayback: (options?: PlaybackOptions) => PlaybackController;
+
+type RWSEvent = {
+    type: 'open';
+} | {
+    type: 'reconnected';
+} | {
+    type: 'message';
+    data: string | ArrayBuffer;
+} | {
+    type: 'close';
+    code: number;
+    reason: string;
+    permanent: boolean;
+} | {
+    type: 'error';
+    error: Error;
+};
+interface WebSocketLike {
+    binaryType: string;
+    readyState: number;
+    onopen: ((ev: unknown) => void) | null;
+    onmessage: ((ev: {
+        data: string | ArrayBuffer;
+    }) => void) | null;
+    onerror: ((ev: unknown) => void) | null;
+    onclose: ((ev: {
+        code: number;
+        reason: string;
+    }) => void) | null;
+    send: (data: string | ArrayBuffer | ArrayBufferView) => void;
+    close: (code?: number, reason?: string) => void;
+}
+type WebSocketFactory = (url: string) => WebSocketLike;
+interface RWSOptions {
+    url: string;
+    wsFactory: WebSocketFactory;
+    maxRetries?: number;
+    initialBackoffMs?: number;
+    maxBackoffMs?: number;
+}
+declare const createReconnectingWebSocket: (options: RWSOptions, onEvent: (ev: RWSEvent) => void) => {
+    send: (data: string | ArrayBuffer | ArrayBufferView) => void;
+    close: (code?: number, reason?: string) => void;
+    readyState: () => number;
+};
+type ReconnectingWebSocket = ReturnType<typeof createReconnectingWebSocket>;
+
+/**
+ * Canonical payload a tenant places in their VoIP/FCM push so an
+ * agent-initiated call can connect. It is the `callTokens.mint` result
+ * (token + transport) plus two optional display fields for the native
+ * incoming-call UI. The host receives the push, runs `parseIncomingCall`,
+ * and on accept passes `token` (+ transport / webrtcGatewayBase) into the
+ * voice client. Web background-wake is best-effort (Web Push); native is
+ * the real target. See docs/sdks.md "Agent-initiated calls".
+ */
+interface IncomingCallPayload {
+    token: string;
+    agentId: string;
+    transport: 'ws' | 'webrtc';
+    webrtcGatewayBase?: string;
+    expiresAt?: number;
+    agentName?: string;
+    agentAvatarUrl?: string;
+}
+/**
+ * Validate + normalise a raw push payload into an IncomingCallPayload.
+ * Throws synchronously on malformed input. Unknown transports fall back to
+ * 'ws'; webrtcGatewayBase is ignored unless transport === 'webrtc'.
+ */
+declare const parseIncomingCall: (raw: unknown) => IncomingCallPayload;
+
+export { type CaptureController as C, type IncomingCallPayload as I, type OnAgentSpeakingChange as O, type PlaybackController as P, type RWSEvent as R, type WebSocketFactory as W, type CaptureOptions as a, type OnChunk as b, type OnError as c, type OnVolume$1 as d, type PlaybackOptions as e, type RWSOptions as f, type ReconnectingWebSocket as g, type WebSocketLike as h, createAudioCapture as i, createAudioPlayback as j, createReconnectingWebSocket as k, parseIncomingCall as p };

package/dist/node.d.mts

@@ -1,5 +1,3 @@
-import { RemoteTrack, LocalVideoTrack } from 'livekit-client';
-
 interface ClientTool {
     description: string;
     parameters: Record<string, unknown>;
@@ -81,143 +79,58 @@ interface BuildWsUrlArgs {
 }
 declare function buildWsUrl(args: BuildWsUrlArgs): string;
 
-type SystemMessage = {
-    kind: 'room.starting';
-    at: string;
-} | {
-    kind: 'room.ending.soon';
-    minutesRemaining: 5 | 1;
-} | {
-    kind: 'room.ended';
-    reason: 'duration_reached' | 'manual' | 'empty';
+/**
+ * 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;
 } | {
-    kind: 'role.promoted';
-    participantId: string;
-    name: string;
+    type: 'token';
+    text: string;
 } | {
-    kind: 'role.demoted';
-    participantId: string;
+    type: 'tool.call';
     name: string;
+    args: unknown;
 } | {
-    kind: 'participant.removed';
-    participantId: string;
+    type: 'tool.result';
     name: string;
-    byHost?: string;
-} | {
-    kind: 'notetaker.connected';
+    ok?: boolean;
+    [key: string]: unknown;
 } | {
-    kind: 'notetaker.disconnected';
+    type: 'turn.end';
+    finishReason: 'stop' | 'aborted' | 'length' | 'tool_error';
+    committedText?: string;
 } | {
-    kind: 'notetaker.partial_degraded';
-    participantId: string;
-};
-type TranscriptMessage = {
-    kind: 'partial';
-    participantId: string;
-    speakerName: string;
-    text: string;
-    startedAt: string;
+    type: 'error';
+    code: string;
+    message: string;
 };
-
-interface JoinRoomOptions {
-    /** Full HTTPS URL of the Voissia server. Same shape as VoiceClientConfig.apiBase. */
-    apiBase: string;
-    /** Server-generated room id (`rm_…`). */
-    roomId: string;
-    /** Shared room join token from the invite link. Mints a fresh participant each call. */
-    joinCode: string;
-    /** Display name the joiner registers under for this participant. */
-    name: string;
-}
-interface RoomParticipantInfo {
-    /** Stable participant id (`p_…`); strips any `guest:` LiveKit identity prefix. */
-    participantId: string;
-    /** Display name as the worker registered it; may be empty. */
-    name: string;
-}
-type RoomTrackKind = 'audio' | 'video';
-/** What a track is — lets consumers tell a camera apart from a screen share
- *  (a participant can publish both at once). Mirrors livekit `Track.Source`. */
-type RoomTrackSource = 'camera' | 'microphone' | 'screen_share' | 'screen_share_audio' | 'unknown';
-interface RoomTrackEvent {
-    /** Stable participant id (`p_…`); `guest:` prefix stripped. */
-    participantId: string;
-    kind: RoomTrackKind;
-    /** Distinguishes camera vs screen_share so each can render as its own tile. */
-    source: RoomTrackSource;
-    /** livekit-client track — call `.attach(el)` / `.detach()` to render. */
-    track: RemoteTrack;
-}
-type RoomEventName = 'participant.joined' | 'participant.left' | 'transcript.partial' | 'transcript.final' | 'system.message' | 'room.ended' | 'track.subscribed' | 'track.unsubscribed' | 'active.speakers';
-interface RoomEventPayloads {
-    'participant.joined': RoomParticipantInfo;
-    'participant.left': RoomParticipantInfo;
-    'transcript.partial': TranscriptMessage;
-    /**
-     * Reserved — the worker currently emits only partials over the transcript
-     * topic. Final-utterance events will land in Phase 8 once the worker
-     * publishes a `final` kind; the SDK keeps the slot reserved so consumers
-     * can register handlers today.
-     */
-    'transcript.final': {
-        participantId: string;
-        speakerName: string;
-        text: string;
-        startedAt: string;
-    };
-    'system.message': SystemMessage;
-    'room.ended': undefined;
-    'track.subscribed': RoomTrackEvent;
-    'track.unsubscribed': RoomTrackEvent;
-    /** participantIds currently speaking (drives an active-speaker UI). */
-    'active.speakers': 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;
 }
-type Handler<E extends RoomEventName> = (payload: RoomEventPayloads[E]) => void;
-interface RoomSession {
-    /** This session's own stable participant id (`p_…`). Useful to filter
-     *  yourself out of `active.speakers`, which includes the local participant. */
-    readonly participantId: string;
-    /** Snapshot of the remote participants currently connected. */
-    readonly participants: RoomParticipantInfo[];
-    /** Subscribe to a typed event. No unsubscribe surface yet (mirrors `Call.onX`). */
-    on<E extends RoomEventName>(event: E, handler: Handler<E>): void;
-    /** Publish the local mic track. Resolves once the track is live on LiveKit. */
-    publishMic(): Promise<void>;
-    /** Publish the local camera track. */
-    publishCamera(): Promise<void>;
-    /** Mid-call mute/unmute of the local mic. */
-    setMicEnabled(on: boolean): Promise<void>;
-    /** Mid-call camera on/off. */
-    setCameraEnabled(on: boolean): Promise<void>;
-    /** Current local mic state (for toggle UI). */
-    isMicEnabled(): boolean;
-    /** Current local camera state (for toggle UI). */
-    isCameraEnabled(): boolean;
-    /** The local camera track for self-view, or null before publishCamera resolves. */
-    getLocalCameraTrack(): LocalVideoTrack | null;
-    /**
-     * Remote tracks already subscribed at this moment. A late joiner misses the
-     * live `track.subscribed` events for tracks published before it connected
-     * (LiveKit delivers them during `connect`, before consumer listeners attach).
-     * Call this right after registering `track.subscribed` to backfill them.
-     */
-    getRemoteTracks(): RoomTrackEvent[];
-    /**
-     * Start/stop sharing the screen (via `getDisplayMedia`). Pass `{ audio: true }`
-     * to also capture shared/system audio where the browser allows it (Chrome:
-     * tab or system audio; macOS Chrome is tab-audio only; Safari/Firefox don't
-     * capture share audio). Publishes a `screen_share` video track (+ optional
-     * `screen_share_audio`); remote peers receive them via `track.subscribed`.
-     */
-    setScreenShareEnabled(on: boolean, opts?: {
-        audio?: boolean;
-    }): Promise<void>;
-    /** Current local screen-share state (for toggle UI). */
-    isScreenShareEnabled(): boolean;
-    /** The local screen-share video track for self-preview, or null when off. */
-    getLocalScreenTrack(): LocalVideoTrack | null;
-    /** Disconnect from LiveKit. Idempotent. Triggers `room.ended` via Disconnected. */
-    leave(): Promise<void>;
+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>;
 }
 
 interface FetchTokenArgs {
@@ -311,7 +224,7 @@ interface StartCallOptions {
      * the LLM through the existing call WebSocket. Schema and handler
      * colocate. Validated synchronously at startCall — bad input throws.
      *
-     * See docs/integration-echocheck.md for the wire protocol and the
+     * See docs/sdks.md ("Client tools") for the wire protocol and the
      * server-side guarantees.
      */
     clientTools?: ClientToolMap;
@@ -370,15 +283,14 @@ interface VoiceClientFactory {
      */
     startCall: (options: StartCallOptions) => Promise<Call>;
     /**
-     * Phase 7 (multi-party rooms). Browser only. Exchange a single-use
-     * joinCode for a LiveKit JWT and connect to the room. The returned
-     * `RoomSession` exposes a typed event surface
-     * (participant.joined / participant.left / transcript.partial /
-     *  transcript.final / system.message / room.ended) plus
-     * publishMic / publishCamera / leave. The Node bundle does NOT
-     * implement this — livekit-client is a browser-only WebRTC client.
+     * 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)
      */
-    joinRoom?: (options: Omit<JoinRoomOptions, 'apiBase'>) => Promise<RoomSession>;
+    startTextSession?: (opts: Omit<StartTextSessionOpts, 'baseUrl' | 'fetch'>) => Promise<TextSession>;
 }
 
 type RWSEvent = {
@@ -446,6 +358,24 @@ interface NodeCall extends Call {
      * back-pressure or drop).
      */
     sendAudioChunk: (pcm: ArrayBuffer | ArrayBufferView) => boolean;
+    /**
+     * Push a short advisory context line to the live call (e.g. a browser
+     * action the user just took). The server buffers these and shows them
+     * to the LLM ahead of the next turn — they never trigger a response
+     * by themselves. Text is trimmed and truncated to 400 chars.
+     * Returns `false` if the WS isn't open yet or text is empty.
+     */
+    sendClientEvent: (text: string) => boolean;
+    /**
+     * Send a typed user turn (text/multimodal sessions — token minted
+     * with `channel:'text'`). Sends `{type:'user_text', text}`. The
+     * server accepts `user_text` only on text-channel sessions and
+     * rejects it on voice (anti-injection), so this is a no-op in
+     * practice on voice calls beyond the frame being ignored
+     * server-side. Text is trimmed. Returns `false` (and sends nothing)
+     * if the WS isn't open or text is empty/whitespace. Never throws.
+     */
+    sendText: (text: string) => boolean;
 }
 /**
  * Node bundle's analog of `VoiceClientFactory`. Same shape but