@callembed/sdk 0.0.0-stage → 0.1.2

package/dist/core/agent.d.ts

@@ -0,0 +1,10 @@
+import type { RemoteParticipant } from "livekit-client";
+/**
+ * Detect a server-minted agent participant by identity prefix only.
+ *
+ * CallEmbed `mintToken` identities are `${role}_${…}`. Display names and
+ * participant metadata are never trusted (users cannot update metadata).
+ */
+export declare function isAgentParticipant(participant: RemoteParticipant): boolean;
+/** True when the agent participant already has a subscribed/published audio track. */
+export declare function agentHasAudio(participant: RemoteParticipant): boolean;

package/dist/core/agent.js

@@ -0,0 +1,19 @@
+import { Track } from "livekit-client";
+/**
+ * Detect a server-minted agent participant by identity prefix only.
+ *
+ * CallEmbed `mintToken` identities are `${role}_${…}`. Display names and
+ * participant metadata are never trusted (users cannot update metadata).
+ */
+export function isAgentParticipant(participant) {
+    return (participant.identity || "").startsWith("agent_");
+}
+/** True when the agent participant already has a subscribed/published audio track. */
+export function agentHasAudio(participant) {
+    for (const pub of participant.trackPublications.values()) {
+        if (pub.kind === Track.Kind.Audio && (pub.track || pub.isSubscribed)) {
+            return true;
+        }
+    }
+    return false;
+}

package/dist/core/api.d.ts

@@ -0,0 +1,44 @@
+import type { CallSession, RuntimeConfig, StartCallOptions } from "./types.js";
+/**
+ * Create a call via `POST /v1/calls` using the publishable key only.
+ * Response includes `endToken` (memory-only — never persist or log).
+ */
+export declare function apiCreateCall(cfg: RuntimeConfig, opts: StartCallOptions): Promise<CallSession>;
+/**
+ * Add random jitter on top of a base delay without exceeding `maxMs`.
+ * Base is always honored as a floor (Retry-After / exponential step).
+ * @internal exported for tests
+ */
+export declare function withJitter(baseMs: number, maxMs: number, random?: () => number): number;
+/**
+ * Delay before the next retry. Honors Retry-After when present (capped at 30s),
+ * otherwise exponential backoff from attempt index (capped at 8s). Always applies
+ * a small random jitter without dropping below the computed base.
+ * @internal exported for tests
+ */
+export declare function retryDelayMs(res: {
+    headers: {
+        get(name: string): string | null;
+    };
+} | null, attempt: number, random?: () => number): number;
+/**
+ * Best-effort `POST /v1/calls/:id/end` with the publishable key + endToken.
+ * Retries on 429 (honors Retry-After + jitter) and transient network errors so a
+ * brief rate-limit spike does not leave the call open.
+ */
+export declare function apiEndCall(cfg: RuntimeConfig, callId: string, endToken?: string | null): Promise<void>;
+/**
+ * End-call during `pagehide` / unload using `keepalive`.
+ * endToken is only in the JSON body — never in the URL.
+ * Single attempt only (page is unloading; delayed retries are unreliable).
+ */
+export declare function apiEndCallKeepalive(cfg: RuntimeConfig, callId: string, endToken?: string | null): void;
+/**
+ * Project-scoped call status (detect ring-timeout `no_answer`).
+ * Caller must send `endToken` via `X-Call-End-Token` (never in the URL).
+ * Retries briefly on 429 (Retry-After + jitter) so ring polls survive key/IP spikes.
+ */
+export declare function apiGetCallStatus(cfg: RuntimeConfig, callId: string, endToken?: string | null): Promise<{
+    status: string;
+    failReason: string | null;
+} | null>;

package/dist/core/api.js

@@ -0,0 +1,169 @@
+import { CallEmbedError } from "./errors.js";
+import { assertValidMetadata } from "./metadata.js";
+/** Publishable request headers; includes parent origin for hosted iframe (B109). */
+function publishableHeaders(cfg, extra) {
+    const headers = {
+        "X-Publishable-Key": cfg.publishableKey,
+        ...extra,
+    };
+    if (cfg.parentOrigin) {
+        headers["X-CallEmbed-Parent-Origin"] = cfg.parentOrigin;
+    }
+    return headers;
+}
+/**
+ * Create a call via `POST /v1/calls` using the publishable key only.
+ * Response includes `endToken` (memory-only — never persist or log).
+ */
+export async function apiCreateCall(cfg, opts) {
+    assertValidMetadata(opts.metadata);
+    const base = cfg.apiBaseUrl.replace(/\/$/, "");
+    const res = await fetch(`${base}/v1/calls`, {
+        method: "POST",
+        headers: publishableHeaders(cfg, { "Content-Type": "application/json" }),
+        body: JSON.stringify({
+            queue: opts.queue,
+            ...(opts.metadata !== undefined ? { metadata: opts.metadata } : {}),
+            ...(opts.displayName !== undefined ? { displayName: opts.displayName } : {}),
+        }),
+    });
+    let data;
+    try {
+        data = (await res.json());
+    }
+    catch {
+        throw new CallEmbedError("connection_failed", `HTTP ${res.status}: invalid JSON response`, res.status);
+    }
+    if (!res.ok) {
+        throw new CallEmbedError(data.error || "call_failed", data.message || `HTTP ${res.status}`, res.status);
+    }
+    if (!data.callId || !data.token || !data.livekitUrl) {
+        throw new CallEmbedError("call_failed", "API response missing call session fields.", res.status);
+    }
+    return data;
+}
+function endCallUrl(cfg, callId) {
+    const base = cfg.apiBaseUrl.replace(/\/$/, "");
+    return `${base}/v1/calls/${encodeURIComponent(callId)}/end`;
+}
+function callStatusUrl(cfg, callId) {
+    const base = cfg.apiBaseUrl.replace(/\/$/, "");
+    return `${base}/v1/calls/${encodeURIComponent(callId)}`;
+}
+function endBody(endToken) {
+    if (endToken)
+        return JSON.stringify({ endToken });
+    return "{}";
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+const RETRY_AFTER_MAX_MS = 30_000;
+const EXP_BACKOFF_MAX_MS = 8_000;
+/**
+ * Add random jitter on top of a base delay without exceeding `maxMs`.
+ * Base is always honored as a floor (Retry-After / exponential step).
+ * @internal exported for tests
+ */
+export function withJitter(baseMs, maxMs, random = Math.random) {
+    const floor = Math.max(0, Math.floor(baseMs));
+    const cap = Math.max(floor, Math.floor(maxMs));
+    const spread = Math.min(250, Math.floor(floor * 0.25));
+    const jitter = Math.floor(random() * (spread + 1));
+    return Math.min(floor + jitter, cap);
+}
+/**
+ * Delay before the next retry. Honors Retry-After when present (capped at 30s),
+ * otherwise exponential backoff from attempt index (capped at 8s). Always applies
+ * a small random jitter without dropping below the computed base.
+ * @internal exported for tests
+ */
+export function retryDelayMs(res, attempt, random = Math.random) {
+    if (res) {
+        const raw = res.headers.get("Retry-After");
+        const sec = raw ? Number.parseInt(raw, 10) : NaN;
+        if (Number.isFinite(sec) && sec > 0) {
+            const base = Math.min(Math.max(sec, 1), 30) * 1000;
+            return withJitter(base, RETRY_AFTER_MAX_MS, random);
+        }
+    }
+    const base = Math.min(250 * 2 ** attempt, EXP_BACKOFF_MAX_MS);
+    return withJitter(base, EXP_BACKOFF_MAX_MS, random);
+}
+const END_MAX_ATTEMPTS = 4;
+const STATUS_MAX_ATTEMPTS = 3;
+/**
+ * Best-effort `POST /v1/calls/:id/end` with the publishable key + endToken.
+ * Retries on 429 (honors Retry-After + jitter) and transient network errors so a
+ * brief rate-limit spike does not leave the call open.
+ */
+export async function apiEndCall(cfg, callId, endToken) {
+    const url = endCallUrl(cfg, callId);
+    const body = endBody(endToken);
+    const headers = publishableHeaders(cfg, { "Content-Type": "application/json" });
+    for (let attempt = 0; attempt < END_MAX_ATTEMPTS; attempt++) {
+        try {
+            const res = await fetch(url, { method: "POST", headers, body });
+            if (res.status === 429 && attempt < END_MAX_ATTEMPTS - 1) {
+                await sleep(retryDelayMs(res, attempt));
+                continue;
+            }
+            return;
+        }
+        catch {
+            if (attempt < END_MAX_ATTEMPTS - 1) {
+                await sleep(retryDelayMs(null, attempt));
+                continue;
+            }
+            // Best-effort — final failure is swallowed (hangUp must still resolve).
+        }
+    }
+}
+/**
+ * End-call during `pagehide` / unload using `keepalive`.
+ * endToken is only in the JSON body — never in the URL.
+ * Single attempt only (page is unloading; delayed retries are unreliable).
+ */
+export function apiEndCallKeepalive(cfg, callId, endToken) {
+    try {
+        void fetch(endCallUrl(cfg, callId), {
+            method: "POST",
+            headers: publishableHeaders(cfg, { "Content-Type": "application/json" }),
+            body: endBody(endToken),
+            keepalive: true,
+        });
+    }
+    catch {
+        // Best-effort
+    }
+}
+/**
+ * Project-scoped call status (detect ring-timeout `no_answer`).
+ * Caller must send `endToken` via `X-Call-End-Token` (never in the URL).
+ * Retries briefly on 429 (Retry-After + jitter) so ring polls survive key/IP spikes.
+ */
+export async function apiGetCallStatus(cfg, callId, endToken) {
+    const headers = publishableHeaders(cfg);
+    if (endToken)
+        headers["X-Call-End-Token"] = endToken;
+    const url = callStatusUrl(cfg, callId);
+    for (let attempt = 0; attempt < STATUS_MAX_ATTEMPTS; attempt++) {
+        try {
+            const res = await fetch(url, { method: "GET", headers });
+            if (res.status === 429 && attempt < STATUS_MAX_ATTEMPTS - 1) {
+                await sleep(retryDelayMs(res, attempt));
+                continue;
+            }
+            if (!res.ok)
+                return null;
+            const data = (await res.json());
+            if (!data.status)
+                return null;
+            return { status: data.status, failReason: data.failReason ?? null };
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}

package/dist/core/audio.d.ts

@@ -0,0 +1,20 @@
+import type { RemoteTrack } from "livekit-client";
+/**
+ * Hidden DOM host for remote `<audio>` elements.
+ * This is **not** a call panel — headless mode still needs a place to attach
+ * subscribed tracks so the caller can hear the agent.
+ */
+export declare class RemoteAudioHost {
+    private host;
+    /** Ensure the hidden host exists under `document.body`. */
+    ensure(): HTMLElement;
+    /**
+     * Attach a remote audio track for playback.
+     * @param identity - Participant identity (for debugging only; not shown).
+     */
+    attach(track: RemoteTrack, identity: string): HTMLMediaElement;
+    /** Detach media elements for a track and remove them from the host. */
+    detachTrack(track: RemoteTrack): void;
+    /** Remove all attached elements and the host node. */
+    destroy(): void;
+}

package/dist/core/audio.js

@@ -0,0 +1,68 @@
+const HOST_ATTR = "data-ce-audio-host";
+/**
+ * Hidden DOM host for remote `<audio>` elements.
+ * This is **not** a call panel — headless mode still needs a place to attach
+ * subscribed tracks so the caller can hear the agent.
+ */
+export class RemoteAudioHost {
+    host = null;
+    /** Ensure the hidden host exists under `document.body`. */
+    ensure() {
+        if (typeof document === "undefined") {
+            throw new Error("RemoteAudioHost requires a DOM document.");
+        }
+        if (this.host && this.host.isConnected)
+            return this.host;
+        const existing = document.querySelector(`[${HOST_ATTR}]`);
+        if (existing) {
+            this.host = existing;
+            return existing;
+        }
+        const el = document.createElement("div");
+        el.setAttribute(HOST_ATTR, "true");
+        el.setAttribute("aria-hidden", "true");
+        el.style.cssText =
+            "position:absolute;width:0;height:0;overflow:hidden;pointer-events:none;";
+        document.body.appendChild(el);
+        this.host = el;
+        return el;
+    }
+    /**
+     * Attach a remote audio track for playback.
+     * @param identity - Participant identity (for debugging only; not shown).
+     */
+    attach(track, identity) {
+        const host = this.ensure();
+        const el = track.attach();
+        el.dataset.identity = identity;
+        el.autoplay = true;
+        el.setAttribute("playsinline", "true");
+        host.appendChild(el);
+        try {
+            const playResult = el.play();
+            if (playResult && typeof playResult.catch === "function") {
+                void playResult.catch(() => {
+                    // Autoplay may be blocked until a user gesture; track stays attached.
+                });
+            }
+        }
+        catch {
+            // jsdom / restricted environments may throw on play()
+        }
+        return el;
+    }
+    /** Detach media elements for a track and remove them from the host. */
+    detachTrack(track) {
+        for (const el of track.detach()) {
+            el.remove();
+        }
+    }
+    /** Remove all attached elements and the host node. */
+    destroy() {
+        if (this.host) {
+            this.host.replaceChildren();
+            this.host.remove();
+            this.host = null;
+        }
+    }
+}

package/dist/core/call.d.ts

@@ -0,0 +1,45 @@
+import { Room } from "livekit-client";
+import type { ActiveCall, CallEventHandler, CallEventName, CallStatus, RuntimeConfig, StartCallOptions } from "./types.js";
+/** Optional hooks so the UI layer can mirror status without core importing UI. */
+export interface CallUiHooks {
+    onStatus?: (status: CallStatus, message?: string) => void;
+    onMuteChange?: (muted: boolean) => void;
+    onTerminal?: () => void;
+}
+/** @internal Test seam — replace LiveKit Room construction. */
+export type RoomFactory = () => Room;
+/** @internal */
+export declare function setRoomFactoryForTests(factory: RoomFactory | null): void;
+/** One in-flight call. LiveKit JWT + endToken stay in memory only. */
+export declare class CallSessionController implements ActiveCall {
+    callId: string;
+    status: CallStatus;
+    private room;
+    private muted;
+    private readonly cfg;
+    private readonly emitter;
+    private readonly audio;
+    private ui;
+    private pageHideHandler;
+    private hangUpStarted;
+    private endCallSent;
+    private endToken;
+    private readonly ringWatch;
+    constructor(cfg: RuntimeConfig, ui?: CallUiHooks);
+    setUiHooks(ui: CallUiHooks): void;
+    on<E extends CallEventName>(event: E, handler: CallEventHandler<E>): () => void;
+    off<E extends CallEventName>(event: E, handler: CallEventHandler<E>): void;
+    isMuted(): boolean;
+    /** Drive idle → connecting → ringing → (answered). */
+    start(opts: StartCallOptions): Promise<void>;
+    setMuted(muted: boolean): Promise<void>;
+    hangUp(): Promise<void>;
+    private asTeardownHost;
+    private setStatus;
+    private fail;
+    private onUnexpectedDisconnect;
+    private failNoAnswer;
+    private observeParticipant;
+    private maybeAnswer;
+    private hasAttachedAgentAudio;
+}

package/dist/core/call.js

@@ -0,0 +1,252 @@
+import { Room, Track, } from "livekit-client";
+import { apiCreateCall } from "./api.js";
+import { RemoteAudioHost } from "./audio.js";
+import { agentHasAudio, isAgentParticipant } from "./agent.js";
+import { CallEmbedError, mapMediaError } from "./errors.js";
+import { TypedEmitter } from "./events.js";
+import { bindRoomEvents } from "./room-events.js";
+import { noAnswerError, RingWatch } from "./ring-watch.js";
+import { isTerminal, transition } from "./state-machine.js";
+import { bindPageHide, cleanupSession, finishAfterHangUp, hangUpSession, teardownMedia, } from "./teardown.js";
+let roomFactory = null;
+/** @internal */
+export function setRoomFactoryForTests(factory) {
+    roomFactory = factory;
+}
+function createRoom() {
+    if (roomFactory)
+        return roomFactory();
+    return new Room({
+        adaptiveStream: true,
+        dynacast: true,
+        audioCaptureDefaults: {
+            autoGainControl: true,
+            echoCancellation: true,
+            noiseSuppression: true,
+        },
+    });
+}
+/** One in-flight call. LiveKit JWT + endToken stay in memory only. */
+export class CallSessionController {
+    callId;
+    status = "idle";
+    room = null;
+    muted = false;
+    cfg;
+    emitter = new TypedEmitter();
+    audio = new RemoteAudioHost();
+    ui;
+    pageHideHandler = null;
+    hangUpStarted = false;
+    endCallSent = false;
+    endToken = null;
+    ringWatch;
+    constructor(cfg, ui = {}) {
+        this.cfg = cfg;
+        this.ui = ui;
+        this.callId = "pending";
+        this.ringWatch = new RingWatch({
+            cfg: this.cfg,
+            getCallId: () => this.callId,
+            getEndToken: () => this.endToken,
+            isRinging: () => this.status === "ringing",
+            isHangUpStarted: () => this.hangUpStarted,
+            onNoAnswer: () => this.failNoAnswer(),
+        });
+    }
+    setUiHooks(ui) {
+        this.ui = ui;
+    }
+    on(event, handler) {
+        return this.emitter.on(event, handler);
+    }
+    off(event, handler) {
+        this.emitter.off(event, handler);
+    }
+    isMuted() {
+        return this.muted;
+    }
+    /** Drive idle → connecting → ringing → (answered). */
+    async start(opts) {
+        this.setStatus("connecting");
+        this.ui.onStatus?.("connecting");
+        bindPageHide(this.asTeardownHost());
+        let session;
+        try {
+            session = await apiCreateCall(this.cfg, opts);
+        }
+        catch (err) {
+            if (this.hangUpStarted) {
+                await finishAfterHangUp(this.asTeardownHost());
+                return;
+            }
+            const mapped = err instanceof CallEmbedError
+                ? err
+                : new CallEmbedError("connection_failed", err instanceof Error ? err.message : String(err));
+            this.fail(mapped);
+            throw mapped;
+        }
+        this.callId = session.callId;
+        this.endToken = typeof session.endToken === "string" ? session.endToken : null;
+        if (await finishAfterHangUp(this.asTeardownHost()))
+            return;
+        const room = createRoom();
+        this.room = room;
+        bindRoomEvents(room, this.audio, {
+            onAgentAudio: (p) => this.maybeAnswer(p),
+            onAgentPresent: (p) => this.observeParticipant(p),
+            onAgentLeft: () => {
+                void this.hangUp();
+            },
+            onDisconnected: () => {
+                if (!isTerminal(this.status) && !this.hangUpStarted) {
+                    void this.onUnexpectedDisconnect();
+                }
+            },
+        });
+        try {
+            await room.connect(session.livekitUrl, session.token);
+            if (await finishAfterHangUp(this.asTeardownHost()))
+                return;
+            await room.localParticipant.setMicrophoneEnabled(!this.muted);
+            if (await finishAfterHangUp(this.asTeardownHost()))
+                return;
+        }
+        catch (err) {
+            if (this.hangUpStarted) {
+                await finishAfterHangUp(this.asTeardownHost());
+                return;
+            }
+            const mapped = mapMediaError(err);
+            await teardownMedia(this.asTeardownHost());
+            this.fail(mapped);
+            throw mapped;
+        }
+        this.setStatus("ringing");
+        this.emitter.emit("ringing", { callId: this.callId });
+        this.ui.onStatus?.("ringing");
+        this.ringWatch.start();
+        for (const participant of room.remoteParticipants.values()) {
+            this.observeParticipant(participant);
+        }
+    }
+    async setMuted(muted) {
+        this.muted = muted;
+        if (this.room)
+            await this.room.localParticipant.setMicrophoneEnabled(!muted);
+        this.emitter.emit("muteChange", { muted });
+        this.ui.onMuteChange?.(muted);
+    }
+    async hangUp() {
+        this.ringWatch.stop();
+        await hangUpSession(this.asTeardownHost());
+    }
+    asTeardownHost() {
+        return {
+            cfg: this.cfg,
+            emitter: this.emitter,
+            audio: this.audio,
+            ui: this.ui,
+            getCallId: () => this.callId,
+            getStatus: () => this.status,
+            setStatusRaw: (s) => {
+                this.status = s;
+            },
+            getRoom: () => this.room,
+            setRoom: (r) => {
+                this.room = r;
+            },
+            getHangUpStarted: () => this.hangUpStarted,
+            setHangUpStarted: (v) => {
+                this.hangUpStarted = v;
+            },
+            getEndCallSent: () => this.endCallSent,
+            setEndCallSent: (v) => {
+                this.endCallSent = v;
+            },
+            getEndToken: () => this.endToken,
+            clearEndToken: () => {
+                this.endToken = null;
+            },
+            getPageHideHandler: () => this.pageHideHandler,
+            setPageHideHandler: (h) => {
+                this.pageHideHandler = h;
+            },
+        };
+    }
+    setStatus(next) {
+        const previous = this.status;
+        this.status = transition(previous, next);
+        if (previous !== this.status) {
+            this.emitter.emit("statusChange", {
+                status: this.status,
+                previousStatus: previous,
+            });
+        }
+    }
+    fail(err) {
+        this.ringWatch.stop();
+        if (!isTerminal(this.status)) {
+            try {
+                this.setStatus("error");
+            }
+            catch {
+                this.status = "error";
+            }
+        }
+        this.emitter.emit("error", {
+            callId: this.callId,
+            code: err.code,
+            message: err.message,
+        });
+        this.ui.onStatus?.("error", err.message);
+        this.ui.onTerminal?.();
+        cleanupSession(this.asTeardownHost());
+    }
+    async onUnexpectedDisconnect() {
+        if (await this.ringWatch.checkAfterDisconnect())
+            return;
+        await this.hangUp();
+    }
+    async failNoAnswer() {
+        if (this.hangUpStarted || isTerminal(this.status))
+            return;
+        this.hangUpStarted = true;
+        this.ringWatch.stop();
+        await teardownMedia(this.asTeardownHost());
+        this.endCallSent = true;
+        this.fail(noAnswerError());
+    }
+    observeParticipant(participant) {
+        if (!isAgentParticipant(participant))
+            return;
+        participant.trackPublications.forEach((pub) => {
+            if (pub.track && pub.kind === Track.Kind.Audio) {
+                this.audio.attach(pub.track, participant.identity);
+            }
+        });
+        this.maybeAnswer(participant);
+    }
+    maybeAnswer(participant) {
+        if (this.status !== "ringing" || this.hangUpStarted)
+            return;
+        if (!isAgentParticipant(participant))
+            return;
+        if (!agentHasAudio(participant) && !this.hasAttachedAgentAudio(participant.identity)) {
+            return;
+        }
+        this.ringWatch.stop();
+        this.setStatus("answered");
+        this.emitter.emit("answered", {
+            callId: this.callId,
+            agentIdentity: participant.identity,
+        });
+        this.ui.onStatus?.("answered");
+    }
+    hasAttachedAgentAudio(identity) {
+        if (typeof document === "undefined")
+            return false;
+        const safe = identity.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+        return Boolean(document.querySelector(`audio[data-identity="${safe}"]`));
+    }
+}

package/dist/core/client.d.ts

@@ -0,0 +1,53 @@
+import { CallSessionController, type CallUiHooks } from "./call.js";
+import type { ActiveCall, InitOptions, Locale, RuntimeConfig, StartCallOptions } from "./types.js";
+/**
+ * Default locale when `options.locale` is omitted (X10).
+ * `navigator.language` starting with `zh` → `zh-TW`; otherwise `en`.
+ */
+export declare function defaultLocaleFromNavigator(language?: string | undefined): Locale;
+/**
+ * @internal Allow the UI package to attach panel hooks without core importing UI.
+ */
+export declare function registerUiHooksFactory(factory: ((call: CallSessionController, opts: StartCallOptions) => CallUiHooks) | null): void;
+/**
+ * Headless CallEmbed client.
+ *
+ * @example
+ * ```ts
+ * CallEmbed.init({ publishableKey: "pk_…", apiBaseUrl: "" });
+ * const call = await CallEmbed.startCall({
+ *   queue: "onboarding",
+ *   hidePanel: true,
+ *   on: {
+ *     statusChange: ({ status }) => { … },
+ *     ringing: () => { … },
+ *     error: ({ code }) => { … },
+ *   },
+ * });
+ * ```
+ */
+export declare const CallEmbed: {
+    /**
+     * Configure the SDK for this page.
+     * @throws {@link CallEmbedError} `invalid_config` when keys/URL are missing or unsafe.
+     */
+    init(options: InitOptions): void;
+    /**
+     * Start a call and resolve once the room is connected (`ringing`), or reject
+     * on startup failure. Register `options.on` to observe `connecting` / `ringing`
+     * / startup `error` during the await.
+     *
+     * Panel UI appears only when `enableDefaultUi()` or `mountButton()` was used
+     * and `hidePanel` is not true.
+     *
+     * @returns The active call (status is typically `ringing` on success).
+     */
+    startCall(options: StartCallOptions): Promise<ActiveCall>;
+    /** Currently active call, or `null`. */
+    getActiveCall(): ActiveCall | null;
+    /** @internal Test helper — reset singleton state. */
+    _resetForTests(): void;
+    /** @internal Expose runtime for the UI package (locale / copy / debug). */
+    _getRuntime(): RuntimeConfig | null;
+};
+export type { ActiveCall, InitOptions, StartCallOptions };