@talk2view/sdk 0.19.0 → 0.20.1

package/dist/voice.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Voice controller — the realtime voice agent behind `t2v.voice`.
+ *
+ * Core never imports this module statically: the `T2VVoice` facade
+ * (`voice-facade.ts`) loads it with `import()` on the first `start()`, and it
+ * in turn loads the Pipecat libraries, so chat-only partners ship neither.
+ *
+ * The engine mints a ticket (`POST /v1/voice/sessions`); the Pipecat client
+ * libraries are loaded on first `start()` so chat-only partners never ship
+ * them; WebRTC audio goes to the voice agent service; client tools the agent
+ * calls arrive here over the RTVI data channel and run through the SAME tool
+ * registry and permission check as chat, so partners write no new code.
+ */
+import { VoiceStartError } from './voice-error.js';
+import type { T2VTools } from './tools.js';
+import type { VoiceEventMap, VoiceState } from './types.js';
+export interface PipecatCallbacks {
+    onConnected?: () => void;
+    onDisconnected?: () => void;
+    onError?: (message: {
+        data?: {
+            message?: string;
+        };
+    }) => void;
+    onServerMessage?: (data: unknown) => void;
+    onUserTranscript?: (data: {
+        text: string;
+        final?: boolean;
+    }) => void;
+    onBotTranscript?: (data: {
+        text: string;
+    }) => void;
+    onTrackStarted?: (track: MediaStreamTrack, participant?: {
+        local?: boolean;
+    }) => void;
+    /** client-js 1.13.1 passes a `DeviceError` (`devices`, `type`, `message`). */
+    onDeviceError?: (error: {
+        devices?: string[];
+        type?: string;
+        message?: string;
+    }) => void;
+}
+export interface PipecatClientLike {
+    /** Opens the microphone (the browser's permission prompt, first time). */
+    initDevices(): Promise<void>;
+    connect(params: unknown): Promise<unknown>;
+    disconnect(): Promise<void>;
+    sendClientMessage(type: string, data?: unknown): void;
+    /** The live tracks; `local.audio` is the microphone. */
+    tracks(): {
+        local?: {
+            audio?: MediaStreamTrack | null;
+        };
+    };
+}
+export interface VoiceLibs {
+    PipecatClient: new (opts: {
+        transport: unknown;
+        enableMic: boolean;
+        enableCam: boolean;
+        callbacks: PipecatCallbacks;
+    }) => PipecatClientLike;
+    /** `iceServers` can be set after construction, before `connect()`. */
+    SmallWebRTCTransport: new (opts: {
+        iceServers: RTCIceServer[];
+    }) => {
+        iceServers: RTCIceServer[];
+    };
+}
+export type VoiceLibLoader = () => Promise<VoiceLibs>;
+/** Dynamic imports: a bundler splits these into their own chunk. */
+export declare const loadPipecatLibs: VoiceLibLoader;
+export interface T2VVoiceDeps {
+    request: <T>(endpoint: string, options?: RequestInit) => Promise<T>;
+    ensureSession: () => Promise<boolean>;
+    getValidAccessToken: (opts?: {
+        forceRefresh?: boolean;
+    }) => Promise<string | null>;
+    tools: Pick<T2VTools, 'checkPermission' | 'executeToolCall' | 'getDescription'>;
+    partnerKey: string;
+    loadLibs?: VoiceLibLoader;
+    /** Where the bot's audio goes. Default: an autoplaying `<audio>` element. */
+    attachAudio?: (track: MediaStreamTrack) => void;
+    /** Auto-deny an approval nobody answers. Under the service's 30 s tool timeout. */
+    approvalTimeoutMs?: number;
+    /** Whether the browser will prompt for the microphone. Default: the Permissions API. */
+    micPermission?: () => Promise<PermissionState | 'unknown'>;
+}
+export { VoiceStartError };
+/** The voice controller. Construct the {@link T2VVoice} facade (`t2v.voice`) instead. */
+export declare class T2VVoiceController {
+    private readonly deps;
+    private readonly emitter;
+    private _state;
+    private client;
+    private audio;
+    private libs;
+    private pendingApproval;
+    /** Ends the open approval without a human answer; the reason goes to the agent. */
+    private cancelApproval;
+    private readonly alwaysAllowed;
+    /**
+     * Bumped by every ending. A `start()` or a client callback from an older
+     * epoch belongs to a call that was hung up, and must not touch this one.
+     */
+    private epoch;
+    /** Settles the in-flight `start()`'s connect wait when the call is hung up mid-start. */
+    private abortStart;
+    /**
+     * The hang-up in progress; a concurrent `stop()` joins it. Tagged with the
+     * epoch it ended, so a `stop()` for a call started after it (say, from an
+     * `ended` listener) is not mistaken for a second hang-up of the old one.
+     */
+    private ending;
+    constructor(deps: T2VVoiceDeps);
+    get state(): VoiceState;
+    on<K extends keyof VoiceEventMap & string>(event: K, callback: (...args: VoiceEventMap[K]) => void): () => void;
+    /**
+     * Emit without letting a throwing partner listener break the caller: a hang-up
+     * must still release the mic and a tool call must still be answered. Logged
+     * by event name only, never the payload (it can carry tool arguments).
+     */
+    private safeEmit;
+    private setState;
+    private emitError;
+    /**
+     * @internal Start loading the call libraries before the first `start()`
+     * (the button calls this on hover). `start()` reuses the load.
+     */
+    preload(): void;
+    /** The call libraries, loaded once. A failed load is retried next time. */
+    private loadLibs;
+    /**
+     * Press the button. Resolves once the microphone is live, or quietly if the
+     * call is hung up (`stop()`) before it connects.
+     */
+    start(): Promise<void>;
+    /** Hang up. Safe to call in any state. */
+    stop(): Promise<void>;
+    /**
+     * @internal The signed-in session died (not a deliberate sign-out): end any
+     * call, starting or live, as `auth_expired` with an `auth_expired` error.
+     */
+    expire(): Promise<void>;
+    private finish;
+    private endCall;
+    private teardown;
+    private attachAudio;
+    private detachAudio;
+    private handleServerMessage;
+    private relayToolCall;
+    private runToolCall;
+    /** Close the open card without a human answer, telling the agent why. */
+    private endApproval;
+    private awaitApproval;
+}
+//# sourceMappingURL=voice.d.ts.map

package/dist/voice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"voice.d.ts","sourceRoot":"","sources":["../src/voice.ts"],"names":[],"mappings":"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"}