@talkif/webrtc 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,494 @@
+/**
+ * Wire types for the Talkif WebRTC signaling API and the pipecat SmallWebRTC
+ * data-channel protocol spoken by Talkif voice bots.
+ *
+ * These shapes are the public contract. Field casing matches the backend JSON
+ * exactly (camelCase over HTTP).
+ */
+interface IceServer {
+    urls: string;
+    username?: string;
+    credential?: string;
+}
+interface IceServersResponse {
+    iceServers: IceServer[];
+    /** Seconds remaining on the underlying TURN credential. */
+    ttl: number;
+}
+interface CreateCallRequest {
+    flowId: string;
+    metadata?: Record<string, unknown>;
+}
+interface CreateTestCallRequest {
+    flowId: string;
+    /**
+     * Draft flow definition (frontend `FlowDefinition` shape). The library does
+     * not interpret it — it is passed through to the backend, which validates
+     * and compiles it for the bot.
+     */
+    definition: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+}
+type CallStatus = 'CREATED' | 'BOT_ASSIGNED' | 'QUEUED' | 'RINGING' | 'IN_PROGRESS' | 'COMPLETED' | 'FAILED' | 'NO_ANSWER' | 'BUSY' | 'CANCELED';
+/** REST statuses that mean the call is genuinely over. */
+declare const TERMINAL_CALL_STATUSES: ReadonlySet<CallStatus>;
+interface CreateCallResponse {
+    callId: string;
+    flowId: string;
+    status: CallStatus;
+    botId?: string | null;
+}
+interface WebRTCCall {
+    callId: string;
+    status: CallStatus;
+}
+interface OfferRequest {
+    sdp: string;
+    iceServers?: IceServer[];
+}
+/** Public surface: token-exchange response (`POST /public/calls/session`). */
+interface PublicSessionResponse {
+    /** Signed session token — sent as `Authorization: Bearer <token>`. */
+    token: string;
+    /** Seconds until the token expires (~15 min). */
+    expiresIn: number;
+    /** The flow this session may call (bound to the publishable key). */
+    flowId: string;
+}
+interface OfferResponse {
+    sdp: string;
+    sdpType: string;
+    botId?: string | null;
+}
+/** Bot → client: bot requests a new offer/answer cycle. */
+interface RenegotiateMessage {
+    type: 'renegotiate';
+}
+/** Bot → client: bot is closing the connection. */
+interface PeerLeftMessage {
+    type: 'peerLeft';
+}
+/** Client → bot: enable/disable a media receiver. 0=audio, 1=video, 2=screen. */
+interface TrackStatusMessage {
+    type: 'trackStatus';
+    receiver_index: 0 | 1 | 2;
+    enabled: boolean;
+}
+type SignallingPayload = RenegotiateMessage | PeerLeftMessage | TrackStatusMessage;
+interface SignallingEnvelope {
+    type: 'signalling';
+    message: SignallingPayload;
+}
+/**
+ * Anything on the data channel that is not the signalling envelope (and not a
+ * `"ping"` keepalive string) is an app message: arbitrary JSON exchanged with
+ * the bot pipeline.
+ */
+type AppMessage = Record<string, unknown>;
+/**
+ * Server envelope on the realtime events WebSocket. `seq` is per-connection
+ * and monotonic — a gap means THIS connection dropped frames under
+ * backpressure, not that the call missed anything.
+ */
+interface CallEventEnvelope {
+    v: number;
+    type: string;
+    call_id?: string;
+    seq: number;
+    ts: number;
+    data: Record<string, unknown>;
+}
+/** Event types the public WS delivers for the session's call. */
+type CallEventType = 'transcript' | 'interim' | 'status' | 'tts' | 'tts_word' | 'speech' | 'turn' | 'node_transition' | 'error';
+type CallState = 'idle' | 'requesting' | 'connecting' | 'connected' | 'ended' | 'error';
+interface TalkifCallEventMap {
+    /** State machine transition. */
+    statechange: {
+        state: CallState;
+        previous: CallState;
+    };
+    /** Media is flowing and the SDP answer is applied. */
+    connected: {
+        callId: string;
+        botId: string | null;
+    };
+    /** Remote (bot) audio track arrived. */
+    track: {
+        stream: MediaStream;
+    };
+    /** Call finished normally (user hangup, bot peerLeft, terminal status). */
+    ended: {
+        reason: CallEndReason;
+    };
+    /** Fatal failure. The call is torn down; state is 'error'. */
+    error: {
+        error: TalkifCallError;
+    };
+    /** One-second duration tick while connected. */
+    tick: {
+        durationSecs: number;
+    };
+    /** JSON app message from the bot over the data channel. */
+    appmessage: {
+        message: AppMessage;
+    };
+    /** Bot asked for renegotiation. Emitted after the re-offer is attempted. */
+    renegotiated: {
+        ok: boolean;
+    };
+    /** Mute toggled. */
+    mutechange: {
+        muted: boolean;
+    };
+    /**
+     * Any realtime event for this call from the events WebSocket (public mode).
+     * Fires for every delivered envelope, including those with dedicated
+     * events below.
+     */
+    callevent: {
+        event: CallEventEnvelope;
+    };
+    /** Final transcript line (public mode, via the events WebSocket). */
+    transcript: {
+        role: string;
+        content: string;
+        data: Record<string, unknown>;
+    };
+    /** Interim (in-progress) transcription (public mode). May be dropped under backpressure. */
+    interim: {
+        data: Record<string, unknown>;
+    };
+    /**
+     * Word-level TTS timing (public mode). Drives karaoke-style caption
+     * highlighting; only words actually spoken are delivered. May be dropped
+     * under backpressure.
+     */
+    ttsword: TtsWordEvent;
+    /**
+     * Sentence-level chunk of the agent's reply (public mode), emitted when the
+     * LLM output is handed to TTS synthesis — ahead of audio playback. Use for
+     * chat-style streaming of the reply; reconcile with the final `transcript`
+     * (on interruption the tail may never be spoken). May be dropped under
+     * backpressure.
+     */
+    ttschunk: TtsChunkEvent;
+}
+/** Payload of a `tts` realtime event. */
+interface TtsChunkEvent {
+    /** Sentence-level text chunk of the agent's reply. */
+    text: string;
+    /** Unix timestamp from the bot (seconds, fractional). */
+    timestamp: number;
+    /** Full raw event payload (character counts, TTS timing metrics…). */
+    data: Record<string, unknown>;
+}
+/** Payload of a `tts_word` realtime event. */
+interface TtsWordEvent {
+    /** The spoken word. */
+    word: string;
+    /** Presentation timestamp — when the word is spoken in the audio (ms), if known. */
+    ptsMs: number | null;
+    /** Unix timestamp from the bot (seconds, fractional). */
+    timestamp: number;
+    /** Full raw event payload. */
+    data: Record<string, unknown>;
+}
+type CallEndReason = 'local-hangup' | 'peer-left' | 'terminal-status' | 'external';
+type TalkifCallErrorCode = 'media-unavailable' | 'signaling-failed' | 'connection-failed' | 'pipeline-dead' | 'renegotiation-failed'
+/** Publishable key rejected, origin not allowed, or session expired. */
+ | 'session-rejected'
+/** This session already has an active call (multi-tab). */
+ | 'call-active'
+/** Rate/concurrency limit hit — retry later. */
+ | 'rate-limited'
+/** No bot available right now — retry shortly. */
+ | 'no-agent';
+declare class TalkifCallError extends Error {
+    readonly code: TalkifCallErrorCode;
+    readonly cause?: unknown;
+    constructor(code: TalkifCallErrorCode, message: string, cause?: unknown);
+}
+/**
+ * Supplies the Authorization header value for signaling requests.
+ * Called per request so short-lived tokens (JWT refresh, widget session
+ * tokens) stay current. Return e.g. `"Bearer <token>"`.
+ */
+type AuthProvider = () => string | Promise<string>;
+interface TalkifClientConfig {
+    /** API origin, e.g. `https://api.talkif.ai`. No trailing slash. */
+    baseUrl: string;
+    accountId: string;
+    auth: AuthProvider;
+    /** Override fetch (tests, SSR polyfills). Defaults to global fetch. */
+    fetch?: typeof fetch;
+}
+/**
+ * Public (embeddable) configuration: the browser-safe publishable key from the
+ * flow's public-access settings. The library exchanges it for a short-lived
+ * session token itself — no bearer token, no account id. The page's Origin
+ * must be on the key's allowlist.
+ */
+interface TalkifPublicClientConfig {
+    /** API origin, e.g. `https://api.talkif.ai`. No trailing slash. */
+    baseUrl: string;
+    /** Publishable key (`pk_live_...`) — safe to ship in page source. */
+    publishableKey: string;
+    /**
+     * Cloudflare Turnstile sitekey (Talkif's — public, safe to ship). When set,
+     * the library renders an invisible Turnstile challenge and produces a token
+     * for each session exchange automatically. Leave unset to disable the gate
+     * (dev/local, or before Turnstile is provisioned).
+     */
+    turnstileSiteKey?: string;
+    /**
+     * Manual Turnstile token supplier. Overrides `turnstileSiteKey` — supply
+     * this only if you render Turnstile yourself. Called at each exchange.
+     */
+    turnstileToken?: () => string | Promise<string>;
+    /** Override fetch (tests, SSR polyfills). Defaults to global fetch. */
+    fetch?: typeof fetch;
+}
+type TalkifConfig = TalkifClientConfig | TalkifPublicClientConfig;
+declare function isPublicConfig(config: TalkifConfig): config is TalkifPublicClientConfig;
+interface StartCallOptions {
+    /**
+     * Start a call against a published flow. Required in authenticated mode.
+     * Ignored in public mode — the flow is bound to the publishable key.
+     */
+    flowId?: string;
+    /**
+     * When set, uses the draft test-call endpoint with this definition instead
+     * of the published flow.
+     */
+    draftDefinition?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+    /** Constraints for getUserMedia. Defaults to `{ audio: true }`. */
+    audio?: MediaTrackConstraints | boolean;
+    /**
+     * Attach remote audio to this element instead of an internally created
+     * autoplay `Audio()`. Pass `null` to disable playback entirely (consumer
+     * handles the `track` event itself).
+     */
+    audioElement?: HTMLAudioElement | null;
+}
+
+/**
+ * One WebRTC voice session with a Talkif agent.
+ *
+ * Lifecycle: `idle → requesting → connecting → connected → ended | error`.
+ * A TalkifCall instance is single-use: create a new one per call.
+ */
+declare class TalkifCall {
+    private readonly signaling;
+    private readonly config;
+    private readonly emitter;
+    private events;
+    private pc;
+    private localStream;
+    private remoteAudio;
+    private ownsAudioElement;
+    private dataChannel;
+    private iceServers;
+    private durationTimer;
+    private healthTimer;
+    private pipelineConfirmed;
+    private renegotiating;
+    private _state;
+    private _callId;
+    private _botId;
+    private _muted;
+    private _durationSecs;
+    constructor(config: TalkifConfig);
+    get state(): CallState;
+    get callId(): string | null;
+    get botId(): string | null;
+    get muted(): boolean;
+    get durationSecs(): number;
+    on<K extends keyof TalkifCallEventMap>(event: K, listener: (payload: TalkifCallEventMap[K]) => void): () => void;
+    off<K extends keyof TalkifCallEventMap>(event: K, listener: (payload: TalkifCallEventMap[K]) => void): void;
+    /**
+     * External health signal (e.g. the dashboard's SSE layer saw a
+     * RUNNING/CONNECTED status). Cancels the REST health watchdog.
+     */
+    confirmPipelineHealthy(): void;
+    /**
+     * External terminal signal (e.g. SSE reported COMPLETED). Tears down and
+     * transitions to 'ended'.
+     */
+    endedExternally(): void;
+    /** Send an arbitrary JSON app message to the bot over the data channel. */
+    sendAppMessage(message: AppMessage): boolean;
+    setMuted(muted: boolean): void;
+    /** User-initiated hangup. */
+    hangup(): void;
+    /** Full teardown regardless of state — safe to call multiple times. */
+    dispose(): void;
+    start(options: StartCallOptions): Promise<void>;
+    private prepareLocal;
+    private waitForFirstRelayCandidate;
+    private attachRemoteAudio;
+    private handleSignalling;
+    /**
+     * Bot asked for a new offer/answer cycle. Re-offer through the same relay
+     * endpoint. If the backend rejects re-offers (older deployments), the call
+     * keeps running on the existing session — surfaced via `renegotiated`.
+     */
+    private renegotiate;
+    /**
+     * Public mode only: open the realtime events WebSocket for this call.
+     * Events double as the pipeline-health signal, and a terminal `status`
+     * event ends the call from the server side (e.g. max-duration reached).
+     */
+    private connectEvents;
+    private handleCallEvent;
+    private armHealthWatchdog;
+    private verifyPipelineHealth;
+    private mustLocalSdp;
+    private startDurationTimer;
+    private fail;
+    private setState;
+    private teardown;
+}
+
+interface CallEventsOptions {
+    /** API origin, e.g. `https://api.talkif.ai`. */
+    baseUrl: string;
+    /** Fresh session token per (re)connect — first-message auth. */
+    getToken: () => Promise<string>;
+    /** Every delivered envelope for the session's call. */
+    onEvent: (event: CallEventEnvelope) => void;
+    /**
+     * A `seq` gap was observed: this connection shed frames under backpressure.
+     * The client auto-requests a server-side replay on reconnect; consumers that
+     * render transcripts incrementally may want to clear-and-rebuild on replay.
+     */
+    onGap?: (expected: number, received: number) => void;
+    /** Optional WebSocket constructor override (tests, Node). */
+    webSocket?: typeof WebSocket;
+}
+/**
+ * Client for the public realtime events WebSocket
+ * (`/api/v1/public/ws/events`).
+ *
+ * Protocol: connect → send `{"type":"auth","token":...}` within 5s → send
+ * `{"type":"subscribe"}` (the session is auto-bound to its one call) →
+ * receive `{v, type, call_id?, seq, ts, data}` envelopes. Reconnects with
+ * backoff; after the first successful connection, reconnect subscribes with
+ * `replay: true` to recover anything missed during the gap.
+ */
+declare class CallEventsClient {
+    private readonly options;
+    private ws;
+    private closed;
+    private attempts;
+    private everConnected;
+    private lastSeq;
+    private reconnectTimer;
+    constructor(options: CallEventsOptions);
+    connect(): void;
+    close(): void;
+    private wsUrl;
+    private open;
+    private scheduleReconnect;
+}
+
+declare class SignalingError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(status: number, message: string, body: unknown);
+}
+/**
+ * Holds the short-lived session token for the public surface: exchanges the
+ * publishable key on first use, re-exchanges near expiry, and can be
+ * invalidated on a 401 so the next request retries with a fresh token.
+ */
+declare class PublicSession {
+    private readonly config;
+    private token;
+    private expiresAt;
+    private flowIdValue;
+    private inflight;
+    private turnstile;
+    constructor(config: TalkifPublicClientConfig);
+    /** A fresh Turnstile token, from the manual supplier or the built-in
+     * manager; undefined when no gate is configured (dev/local). */
+    private turnstileToken;
+    /** Tear down the Turnstile widget (call when the client is disposed). */
+    dispose(): void;
+    /** Flow bound to the publishable key (known after the first exchange). */
+    get flowId(): string | null;
+    getToken(): Promise<string>;
+    invalidate(): void;
+    private exchange;
+}
+/**
+ * Thin HTTP client for the Talkif WebRTC signaling routes. Two modes:
+ * - authenticated (dashboard/API): `/api/v1/accounts/{accountId}/calls/webrtc`
+ * - public (embed): `/api/v1/public/calls`, session token minted from the
+ *   publishable key and refreshed transparently.
+ */
+declare class SignalingClient {
+    private readonly config;
+    readonly session: PublicSession | null;
+    constructor(config: TalkifConfig);
+    get isPublic(): boolean;
+    private get base();
+    private authorization;
+    private request;
+    createCall(body: CreateCallRequest): Promise<CreateCallResponse>;
+    createTestCall(body: CreateTestCallRequest): Promise<CreateCallResponse>;
+    getIceServers(): Promise<IceServersResponse>;
+    sendOffer(callId: string, body: OfferRequest): Promise<OfferResponse>;
+    getCall(callId: string): Promise<WebRTCCall>;
+}
+
+/**
+ * Cloudflare Turnstile integration — the "prove you're a real browser" gate
+ * that stops scripted abuse of the public call surface.
+ *
+ * The customer does nothing: the widget self-injects Cloudflare's script,
+ * renders an invisible Turnstile widget with Talkif's sitekey, and produces a
+ * fresh token for each session exchange. The sitekey is public and safe to
+ * ship; the matching secret lives only in the backend.
+ */
+/** Minimal shape of the global `turnstile` object we use. */
+interface TurnstileApi {
+    render(container: HTMLElement, options: {
+        sitekey: string;
+        callback?: (token: string) => void;
+        'error-callback'?: (code?: string) => void;
+        'expired-callback'?: () => void;
+        size?: 'invisible' | 'normal' | 'compact' | 'flexible';
+        execution?: 'render' | 'execute';
+        retry?: 'auto' | 'never';
+    }): string;
+    execute(widgetId: string, options?: {
+        sitekey?: string;
+    }): void;
+    reset(widgetId: string): void;
+    remove(widgetId: string): void;
+}
+declare global {
+    interface Window {
+        turnstile?: TurnstileApi;
+    }
+}
+/**
+ * Manages one invisible Turnstile widget and hands out fresh tokens.
+ *
+ * Turnstile tokens are single-use and short-lived, so we `execute()` a fresh
+ * challenge for each call to `getToken()` (i.e. each session exchange). The
+ * widget is rendered lazily on first use and torn down with `dispose()`.
+ */
+declare class TurnstileManager {
+    private readonly siteKey;
+    private container;
+    private widgetId;
+    private pending;
+    constructor(siteKey: string);
+    /** Obtain a fresh Turnstile token. Rejects if the challenge fails. */
+    getToken(): Promise<string>;
+    dispose(): void;
+}
+
+export { type AppMessage, type AuthProvider, type CallEndReason, type CallEventEnvelope, type CallEventType, CallEventsClient, type CallState, type CallStatus, type CreateCallRequest, type CreateCallResponse, type CreateTestCallRequest, type IceServer, type IceServersResponse, type OfferRequest, type OfferResponse, type PeerLeftMessage, PublicSession, type PublicSessionResponse, type RenegotiateMessage, SignalingClient, SignalingError, type SignallingEnvelope, type SignallingPayload, type StartCallOptions, TERMINAL_CALL_STATUSES, TalkifCall, TalkifCallError, type TalkifCallErrorCode, type TalkifCallEventMap, type TalkifClientConfig, type TalkifConfig, type TalkifPublicClientConfig, type TrackStatusMessage, type TtsChunkEvent, type TtsWordEvent, TurnstileManager, type WebRTCCall, isPublicConfig };