@aihumanity/voice-sdk 0.1.0

package/dist/VoiceCall-_BBARIQT.d.ts

@@ -0,0 +1,276 @@
+import { UltravoxSession } from 'ultravox-client';
+
+/**
+ * Public types shared across the SDK.
+ *
+ * Status names are aligned with Ultravox's session-status enum so the SDK is
+ * a thin, semantic wrapper.
+ */
+/** Coarse-grained call lifecycle states the SDK exposes to consumers. */
+declare enum CallStatus {
+    /** No active call; ready to start. */
+    IDLE = "idle",
+    /** Backend is being asked for a joinUrl, or WebRTC is connecting. */
+    CONNECTING = "connecting",
+    /** Call is live; agent is ready to listen. */
+    CONNECTED = "connected",
+    /** Microphone is open and capturing user speech. */
+    LISTENING = "listening",
+    /** Agent is processing the user's last utterance. */
+    THINKING = "thinking",
+    /** Agent is speaking. */
+    SPEAKING = "speaking",
+    /** Call is being torn down. */
+    DISCONNECTING = "disconnecting",
+    /** Call ended (terminal — same as IDLE for new calls). */
+    DISCONNECTED = "disconnected"
+}
+/** Speaker role on a transcript line. Mirrors ultravox-client's `Role`. */
+declare enum Speaker {
+    USER = "user",
+    AGENT = "agent"
+}
+interface Transcript {
+    /** Spoken text. May grow over time as more partials arrive. */
+    text: string;
+    /** Whether this is the final, locked-in version of the utterance. */
+    isFinal: boolean;
+    /** Who spoke. */
+    speaker: Speaker;
+    /** voice or text. */
+    medium: "voice" | "text";
+    /** Sequence number for ordering. */
+    ordinal: number;
+}
+/**
+ * Audio format the data-connection (emotion / analytics) WebSocket expects.
+ * Matches the Ultravox `dataConnection.audioConfig` schema.
+ */
+interface AudioConfig {
+    /** PCM sample rate. Default 16000. */
+    sampleRate?: number;
+    /**
+     * "CHANNEL_MODE_SEPARATED" sends user/agent as separate channels;
+     * "CHANNEL_MODE_MIXED" sends a single mixed stream.
+     */
+    channelMode?: "CHANNEL_MODE_SEPARATED" | "CHANNEL_MODE_MIXED";
+}
+/** Which speech-activity events the data WebSocket should receive. */
+interface DataMessageFlags {
+    userStartedSpeaking?: boolean;
+    userStoppedSpeaking?: boolean;
+    agentStartedSpeaking?: boolean;
+    agentStoppedSpeaking?: boolean;
+}
+/**
+ * Optional data-connection block. When provided the eimi backend will open a
+ * server-to-server WebSocket so user audio bytes can be analyzed (e.g. for
+ * vocal emotion) and the result fed back as a data message.
+ */
+interface DataConnectionConfig {
+    /** wss:// URL the backend should open for raw user audio. */
+    websocketUrl: string;
+    audioConfig?: AudioConfig;
+    dataMessages?: DataMessageFlags;
+}
+/** Options for starting a call. */
+interface VoiceCallOptions {
+    /**
+     * Base URL of the eimi backend. Example: "https://api.eimi.ai".
+     * Required unless `fetchJoinUrl` is provided.
+     */
+    apiUrl?: string;
+    /**
+     * Bearer token used to authenticate with eimi backend. Can be a string or a
+     * function that resolves one (handy for short-lived JWTs you fetch from
+     * your own backend). Required unless `fetchJoinUrl` or `publicKey` is provided.
+     */
+    authToken?: string | (() => string | Promise<string>);
+    /**
+     * Publishable API key ID for browser-direct (no-backend) auth.
+     *
+     * When provided the SDK sends `X-Public-Key: <publicKey>` and relies on the
+     * browser's `Origin` header for domain validation on the server. The server
+     * checks the origin against the developer's registered `allowedOrigins` list.
+     *
+     * Use this when you have no server-side proxy. Register your site's origin in
+     * the developer portal first. Hits `/v1/voice/joinurl` by default (override
+     * with `joinUrlPath`).
+     *
+     * Unlike `authToken`, this key ID is safe to embed in browser JS — it grants
+     * no access outside your registered origins.
+     */
+    publicKey?: string;
+    /** Agent name configured in eimi backend, e.g. "DavidChiu". */
+    agentName?: string;
+    /** Username the call should be billed/attributed to. */
+    username?: string;
+    /** Optional emotion / analytics WebSocket config. */
+    dataConnection?: DataConnectionConfig;
+    /**
+     * Override the join-url path. Defaults to "/ultravox/secure/joinurl".
+     * Useful if your deployment routes through a proxy.
+     */
+    joinUrlPath?: string;
+    /**
+     * Optional fully custom fetcher. If provided, the SDK calls this function
+     * instead of building a request itself. Must resolve to `{ joinUrl, callId? }`.
+     * When this is provided, `apiUrl` and `authToken` are not required.
+     */
+    fetchJoinUrl?: () => Promise<JoinUrlResponse>;
+    /** Extra fields forwarded in the join-url request body. */
+    extraJoinUrlBody?: Record<string, unknown>;
+    /**
+     * Pattern used to extract an emotion label out of `experimental_message`
+     * data payloads. Default looks for "[EMOTION_CONTEXT] ... : <label>".
+     * The first capture group becomes the emotion label.
+     */
+    emotionPattern?: RegExp;
+    /**
+     * Optional polling callback for emotion data. When provided, the SDK polls
+     * this function at `emotionPollIntervalMs` while the call is live.
+     * Use this when emotion is injected server-side (not via experimental_message).
+     * Receives the `callId` and optional `sessionToken` from the join response.
+     * Should return the emotion label string or null.
+     */
+    pollEmotion?: (callId: string, sessionToken?: string) => Promise<string | null>;
+    /**
+     * How often (ms) to call `pollEmotion`. Default 15000 (15 s).
+     * Ignored if `pollEmotion` is not set.
+     */
+    emotionPollIntervalMs?: number;
+    /** AudioContext to reuse. The SDK will create one if omitted. */
+    audioContext?: AudioContext;
+    /** Pass-through to ultravox-client. */
+    additionalMessages?: Set<string>;
+}
+/** Whatever the eimi backend (or your custom fetcher) returns. */
+interface JoinUrlResponse {
+    joinUrl: string;
+    callId?: string;
+    /**
+     * Short-lived token scoped to this call. Returned by eimi backend when
+     * session-based auth is configured. Used by `pollEmotion` for direct
+     * browser→backend calls without needing a service token.
+     */
+    sessionToken?: string;
+    /**
+     * Server-side summary of whether the data connection / emotion bridge was
+     * wired up. Surface mirrors what eimi backend currently returns.
+     */
+    emotion?: {
+        dataConnectionEnabled?: boolean;
+        audioEnabled?: boolean;
+        emotionBridgeConfigured?: boolean;
+        autoSendEnabled?: boolean;
+        [k: string]: unknown;
+    };
+    [k: string]: unknown;
+}
+/** Map of event name -> listener payload type for the VoiceCall emitter. */
+interface VoiceCallEvents {
+    /** Coarse call status changed. Always fires on real transitions. */
+    status: CallStatus;
+    /** Underlying Ultravox status changed (kept for power users). */
+    raw_status: string;
+    /** A transcript was added or updated. */
+    transcript: Transcript;
+    /** Full transcript array snapshot, fired after every transcript update. */
+    transcripts: Transcript[];
+    /** Vocal emotion label extracted from a data message or poll. */
+    emotion: {
+        label: string;
+        raw: unknown;
+    };
+    /** Any data message from the agent / data connection. */
+    data_message: unknown;
+    /** Mic mute state changed. */
+    mic_muted: boolean;
+    /** Speaker mute state changed. */
+    speaker_muted: boolean;
+    /** Agent has saved/persisted contact info (heuristic on transcript). */
+    contact_saved: void;
+    /** A non-fatal warning (e.g., emotion bridge not configured). */
+    warning: string;
+    /** A fatal error during start/operation. */
+    error: Error;
+    /** Call has fully ended. */
+    ended: void;
+}
+/** Type of listener for a given VoiceCall event. */
+type VoiceCallListener<K extends keyof VoiceCallEvents> = (payload: VoiceCallEvents[K]) => void;
+
+/**
+ * High-level voice call wrapper.
+ *
+ * ```ts
+ * const call = new VoiceCall({ apiUrl, authToken, agentName, username });
+ * call.on("status", s => console.log(s));
+ * call.on("transcript", t => console.log(t.speaker, t.text));
+ * call.on("emotion", e => console.log("emotion:", e.label));
+ * await call.start();
+ * // ... later
+ * await call.end();
+ * ```
+ */
+declare class VoiceCall {
+    private readonly emitter;
+    private readonly opts;
+    private session;
+    private _status;
+    private _callId;
+    private _sessionToken;
+    private _transcripts;
+    private _lastEmotion;
+    private _contactSaved;
+    private _starting;
+    private _emotionMeta;
+    private _pollTimer;
+    constructor(opts: VoiceCallOptions);
+    get status(): CallStatus;
+    get callId(): string | null;
+    get sessionToken(): string | null;
+    get transcripts(): Transcript[];
+    get lastEmotion(): string | null;
+    get contactSaved(): boolean;
+    get isMicMuted(): boolean;
+    get isSpeakerMuted(): boolean;
+    /** Server-reported wiring info from the join-url response, if any. */
+    get emotionMeta(): JoinUrlResponse["emotion"] | null;
+    /** Underlying ultravox-client session. Use sparingly — for power users. */
+    get rawSession(): UltravoxSession | null;
+    on<K extends keyof VoiceCallEvents>(event: K, listener: VoiceCallListener<K>): () => void;
+    off<K extends keyof VoiceCallEvents>(event: K, listener: VoiceCallListener<K>): void;
+    once<K extends keyof VoiceCallEvents>(event: K, listener: VoiceCallListener<K>): () => void;
+    /**
+     * Fetches a joinUrl from the backend, opens an Ultravox session, and starts
+     * the call. Resolves once `joinCall` has been kicked off (the call goes
+     * "live" asynchronously via status events).
+     */
+    start(): Promise<void>;
+    /** Hangs up. Resolves when ultravox-client confirms disconnection. */
+    end(): Promise<void>;
+    muteMic(): void;
+    unmuteMic(): void;
+    toggleMicMute(): boolean;
+    muteSpeaker(): void;
+    unmuteSpeaker(): void;
+    toggleSpeakerMute(): boolean;
+    /** Sends a text message into the call (no spoken audio from the user). */
+    sendText(text: string, deferResponse?: boolean): void;
+    /** Sends an arbitrary data message over Ultravox's data channel. */
+    sendData(obj: unknown): void;
+    /** Removes all listeners and aborts any active session. */
+    dispose(): void;
+    private resetMutableState;
+    private attachSessionListeners;
+    private handleStatusChange;
+    private handleTranscripts;
+    private handleDataMessage;
+    private startEmotionPolling;
+    private stopEmotionPolling;
+    private setStatus;
+    private surfaceEmotionWarnings;
+}
+
+export { type AudioConfig as A, CallStatus as C, type DataConnectionConfig as D, type JoinUrlResponse as J, Speaker as S, type Transcript as T, type VoiceCallOptions as V, type DataMessageFlags as a, VoiceCall as b, type VoiceCallEvents as c, type VoiceCallListener as d };

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+import { V as VoiceCallOptions, J as JoinUrlResponse } from './VoiceCall-_BBARIQT.js';
+export { A as AudioConfig, C as CallStatus, D as DataConnectionConfig, a as DataMessageFlags, S as Speaker, T as Transcript, b as VoiceCall, c as VoiceCallEvents, d as VoiceCallListener } from './VoiceCall-_BBARIQT.js';
+import 'ultravox-client';
+
+/**
+ * POSTs to the join-url endpoint and returns the parsed response.
+ *
+ * Auth resolution order:
+ *  1. `fetchJoinUrl` — fully custom fetcher, takes precedence over everything.
+ *  2. `publicKey`   — browser-direct auth via `X-Public-Key` header + browser Origin.
+ *                     Hits `/v1/voice/joinurl` (the new SDK-aware endpoint).
+ *  3. `authToken`   — Bearer JWT, used with the legacy `/ultravox/secure/joinurl` endpoint
+ *                     (or a custom `joinUrlPath`). Suitable for server-side / Netlify fn use.
+ *
+ * Throws on non-2xx or missing joinUrl.
+ */
+declare function fetchJoinUrl(opts: VoiceCallOptions): Promise<JoinUrlResponse>;
+
+export { JoinUrlResponse, VoiceCallOptions, fetchJoinUrl };