@dialgem/client 0.0.0-stage → 1.0.0

package/dist/call-Cv2GrNfJ.d.ts

@@ -0,0 +1,160 @@
+/** A minimal typed event emitter. A handler that throws never stops the others or the call. */
+declare class Emitter<Events extends Record<string, unknown>> {
+    private handlers;
+    on<K extends keyof Events>(event: K, handler: (payload: Events[K]) => void): () => void;
+    off<K extends keyof Events>(event: K, handler: (payload: Events[K]) => void): void;
+    protected emit<K extends keyof Events>(event: K, payload: Events[K]): void;
+}
+
+type CallState = "idle" | "connecting" | "active" | "ended" | "error";
+/** How a call that started came to an end. */
+type EndReason = 
+/** `stop()` was called. */
+"hangup"
+/** The agent ended the call, or a call limit (maximum length, silence) did. */
+ | "agent_ended"
+/** The connection dropped. The call cannot be resumed: start a new one. */
+ | "connection_lost";
+type ErrorCode = 
+/** The browser lacks something the call needs (WebSocket, Web Audio, AudioWorklet, a microphone API). */
+"unsupported"
+/** The visitor refused microphone access, or it is blocked for this page. */
+ | "mic_denied"
+/** No microphone, or it could not be opened. */
+ | "mic_unavailable"
+/** `accessToken` was a function and it threw or returned nothing. */
+ | "token_unavailable"
+/** The token was invalid, expired or already used, or this page's origin is not allowed. */
+ | "refused"
+/** The organization has too many calls running. */
+ | "busy"
+/** The server declined the call; `reason` says why (for example `insufficient_credit`). */
+ | "call_refused" | "server_error" | "connection_failed";
+interface CallError {
+    code: ErrorCode;
+    message: string;
+    /** For `call_refused`: the server's reason. */
+    reason?: string | undefined;
+}
+interface TranscriptEvent {
+    role: "user" | "agent";
+    text: string;
+    /** False while the caller is still speaking (the words so far); true once the line is settled. */
+    final: boolean;
+}
+interface CallEvents extends Record<string, unknown> {
+    state: CallState;
+    started: {
+        callId: string;
+    };
+    transcript: TranscriptEvent;
+    agent_speaking: {
+        speaking: boolean;
+    };
+    /** The caller talked over the agent and its speech was cut off. */
+    interrupted: Record<string, never>;
+    /** Microphone level, 0 to 1, about ten times a second. Not emitted while muted. */
+    level: {
+        level: number;
+    };
+    ended: {
+        reason: EndReason;
+    };
+    error: CallError;
+}
+interface MicrophoneOptions {
+    deviceId?: string | undefined;
+    /** Default true: without it the agent's own voice comes back through the microphone and it answers itself. */
+    echoCancellation?: boolean | undefined;
+    noiseSuppression?: boolean | undefined;
+    autoGainControl?: boolean | undefined;
+}
+interface DialgemCallOptions {
+    /**
+     * The access token from your backend's `POST /v1/calls/web`, or a function that returns it. A function
+     * is called **after** the visitor has allowed the microphone, because the token only lives 60 seconds and
+     * the permission prompt can take longer than that.
+     */
+    accessToken: string | (() => string | Promise<string>);
+    /** Only for a self-hosted deployment. Default `wss://api.dialgem.com`. */
+    baseURL?: string | undefined;
+    microphone?: MicrophoneOptions | undefined;
+    /** @internal Stand-ins for the browser, for tests. */
+    platform?: Partial<Platform> | undefined;
+}
+/** What the call needs from the browser. */
+interface Platform {
+    WebSocket: typeof WebSocket;
+    AudioContext: typeof AudioContext;
+    AudioWorkletNode: typeof AudioWorkletNode;
+    getUserMedia(constraints: MediaStreamConstraints): Promise<MediaStream>;
+    createObjectURL(blob: Blob): string;
+    revokeObjectURL(url: string): void;
+    Blob: typeof Blob;
+}
+/**
+ * One conversation with one agent.
+ *
+ *   const call = new DialgemCall({ accessToken: () => fetch("/api/start-call").then((r) => r.text()) })
+ *   call.on("transcript", (t) => ...)
+ *   await call.start()      // from a click: browsers only let a page open the microphone and play sound after one
+ *   ...
+ *   call.stop()
+ *
+ * A call object is used once. Its token is single-use, so a second call needs a new object (and a new token).
+ * There is no reconnecting: the conversation lives on the server for as long as the socket does, and a call
+ * that drops has ended.
+ */
+declare class DialgemCall extends Emitter<CallEvents> {
+    private readonly options;
+    private _state;
+    private _muted;
+    private _callId;
+    private readonly platform;
+    private ctx;
+    private stream;
+    private ws;
+    private player;
+    private source;
+    private node;
+    private sink;
+    private moduleUrl;
+    private speakingTimer;
+    private drainTimer;
+    private ending;
+    private pendingRefusal;
+    private failure;
+    private lastLevelAt;
+    private speaking;
+    constructor(options: DialgemCallOptions);
+    get state(): CallState;
+    /** Set once the call has started. */
+    get callId(): string | null;
+    get muted(): boolean;
+    /**
+     * Opens the microphone and the call. Call it directly from a click or tap: the browser decides whether the page
+     * may play sound at the moment this runs, and a call started from a timer or after other awaits can be silent.
+     * Resolves when the connection is open; the call has started when `started` fires. A failure is reported as an
+     * `error` event and also rejects.
+     */
+    start(): Promise<void>;
+    /** Ends the call. Safe to call at any time, any number of times. */
+    stop(): void;
+    /** While muted the agent hears silence. The call stays open. */
+    setMuted(muted: boolean): void;
+    private onMessage;
+    private onStarted;
+    private onCaptured;
+    private onAudio;
+    private setSpeaking;
+    private onCallEnded;
+    private onClose;
+    private dead;
+    /** Ends the call as failed and reports it once. Returns the error, for `start()` to throw. */
+    private fail;
+    private finish;
+    private setState;
+    private cleanup;
+}
+
+export { type CallError as C, DialgemCall as D, type EndReason as E, type MicrophoneOptions as M, type TranscriptEvent as T, type CallEvents as a, type CallState as b, type DialgemCallOptions as c, type ErrorCode as d };