@kognitivedev/cloud-voice 0.2.29

package/src/client.ts

@@ -0,0 +1,610 @@
+import { HttpTransport, KognitiveApiError, type HttpTransportConfig } from "@kognitivedev/client-core";
+import { readSSEStream } from "./sse";
+import type {
+    CloudVoiceAgentRecord,
+    CloudVoiceClientConfig,
+    CloudVoiceEmbedConfig,
+    CloudVoiceSessionBootstrap,
+    CloudVoiceSessionEventRecord,
+    CloudVoiceSessionRecord,
+    CloudVoiceToolCatalog,
+    CloudVoiceCustomVoiceRecord,
+    CloudVoiceCallStatusChange,
+    CloudVoiceCallWaitOptions,
+    CloudVoiceCallWaitResult,
+    CloudVoiceCallLegRecord,
+    CloudVoiceLiveCallRecord,
+    CloudVoicePhoneBridgeHealth,
+    CloudVoicePhoneConnectionRecord,
+    CloudVoicePhoneNumberRecord,
+    CloudVoiceSipDiagnostics,
+    CloudVoiceRecordingAsset,
+    CloudVoiceHandoffRecord,
+    CloudVoiceListenTokenResult,
+    CreateCloudVoicePhoneConnectionInput,
+    CreateCloudVoicePhoneNumberInput,
+    CreateCloudVoiceOutboundCallInput,
+    CreateCloudVoiceAgentInput,
+    CreateCloudVoiceSessionInput,
+    ImportCloudVoiceCustomVoiceInput,
+    CloneCloudVoiceCustomVoiceInput,
+    CreateCloudVoiceHandoffInput,
+    AcceptCloudVoiceHandoffInput,
+    CancelCloudVoiceHandoffInput,
+    UpdateCloudVoicePhoneNumberInput,
+    UpdateCloudVoiceAgentInput,
+    UpdateCloudVoiceCustomVoiceInput,
+    SyncCloudVoiceToolCatalogInput,
+    UseCloudVoiceAgentInput,
+    UseCloudVoiceAgentResult,
+} from "./types";
+
+function isTransportLike(value: unknown): value is HttpTransport {
+    return Boolean(value && typeof value === "object" && "baseUrl" in value && "json" in value && "raw" in value);
+}
+
+function assertString(value: string, name: string) {
+    if (!value || !value.trim()) throw new Error(`${name} is required`);
+    return value.trim();
+}
+
+function isNotFoundError(error: unknown) {
+    return error instanceof KognitiveApiError && error.status === 404
+        || Boolean(error && typeof error === "object" && "status" in error && (error as { status?: unknown }).status === 404);
+}
+
+const TERMINAL_CALL_STATUSES = new Set(["completed", "cancelled", "canceled", "failed", "busy", "no-answer", "error"]);
+const TERMINAL_SESSION_STATUSES = new Set(["completed", "cancelled", "canceled", "error"]);
+
+function sleep(ms: number) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function isTerminalCall(call: CloudVoiceLiveCallRecord) {
+    return Boolean(call.endedAt)
+        || TERMINAL_CALL_STATUSES.has(call.status)
+        || Boolean(call.sessionStatus && TERMINAL_SESSION_STATUSES.has(call.sessionStatus));
+}
+
+function callStatusFingerprint(call: CloudVoiceLiveCallRecord) {
+    return [
+        call.status,
+        call.sessionStatus ?? "",
+        call.stateLabel,
+        call.latestEventType ?? "",
+        call.outcomeStatus ?? "",
+    ].join("|");
+}
+
+function toCallStatusChange(call: CloudVoiceLiveCallRecord, previousStatus?: string): CloudVoiceCallStatusChange {
+    return {
+        call,
+        status: call.status,
+        previousStatus,
+        sessionStatus: call.sessionStatus,
+        stateLabel: call.stateLabel,
+        latestEventType: call.latestEventType,
+        outcomeStatus: call.outcomeStatus,
+    };
+}
+
+export class KognitiveCloudVoiceClient {
+    private readonly transport: HttpTransport;
+
+    readonly agents = {
+        list: () => this.listAgents(),
+        get: (slug: string) => this.getAgent(slug),
+        use: (slug: string, input: UseCloudVoiceAgentInput = {}) => this.useAgent(slug, input),
+        management: {
+            list: () => this.listAgents(),
+            create: (input: CreateCloudVoiceAgentInput) => this.createAgent(input),
+            createOrUse: (slug: string, input: UseCloudVoiceAgentInput = {}) => this.useAgent(slug, input),
+            get: (slug: string) => this.getAgent(slug),
+            update: (slug: string, input: UpdateCloudVoiceAgentInput) => this.updateAgent(slug, input),
+            delete: (slug: string) => this.deleteAgent(slug),
+            publish: (slug: string) => this.publishAgent(slug),
+            unpublish: (slug: string) => this.unpublishAgent(slug),
+            use: (slug: string, input: UseCloudVoiceAgentInput = {}) => this.useAgent(slug, input),
+        },
+    };
+
+    readonly sessions = {
+        list: (agentId?: string) => this.listSessions(agentId),
+        create: (agentSlug: string, input: Omit<CreateCloudVoiceSessionInput, "agentSlug" | "agent"> = {}) =>
+            this.createSession({ ...input, agentSlug }),
+        get: (sessionId: string) => this.getSession(sessionId),
+        cancel: (sessionId: string, reason?: string) => this.cancelSession(sessionId, reason),
+        events: (sessionId: string) => this.getSessionEvents(sessionId),
+        appendEvent: (sessionId: string, event: Record<string, unknown>) => this.appendSessionEvent(sessionId, event),
+        stream: (sessionId: string, init?: RequestInit) => this.streamSessionEvents(sessionId, init),
+        subscribe: (sessionId: string, init?: RequestInit) => this.subscribeToSession(sessionId, init),
+        executeTool: (sessionId: string, toolId: string, input: unknown) => this.executeTool(sessionId, toolId, input),
+        recordings: (sessionId: string) => this.getSessionRecordings(sessionId),
+    };
+
+    readonly calls = {
+        list: () => this.listCalls(),
+        live: (input: { status?: "live" | "all"; limit?: number } = {}) => this.listLiveCalls(input),
+        get: (sessionId: string) => this.getCall(sessionId),
+        create: (input: CreateCloudVoiceOutboundCallInput) => this.createCall(input),
+        wait: (sessionId: string, options?: CloudVoiceCallWaitOptions) => this.waitForCall(sessionId, options),
+        hangup: (sessionId: string, reason?: string) => this.hangupCall(sessionId, reason),
+        listenToken: (sessionId: string, input: { managerId?: string; takeover?: boolean } = {}) => this.createCallListenToken(sessionId, input),
+        handoff: {
+            create: (sessionId: string, input: CreateCloudVoiceHandoffInput = {}) => this.createCallHandoff(sessionId, input),
+            accept: (sessionId: string, handoffId: string, input: AcceptCloudVoiceHandoffInput = {}) => this.acceptCallHandoff(sessionId, handoffId, input),
+            cancel: (sessionId: string, handoffId: string, input: CancelCloudVoiceHandoffInput = {}) => this.cancelCallHandoff(sessionId, handoffId, input),
+        },
+        events: (sessionId: string) => this.getSessionEvents(sessionId),
+        stream: (sessionId: string, init?: RequestInit) => this.streamSessionEvents(sessionId, init),
+        subscribe: (sessionId: string, init?: RequestInit) => this.subscribeToSession(sessionId, init),
+        executeTool: (sessionId: string, toolId: string, input: unknown) => this.executeCallTool(sessionId, toolId, input),
+    };
+
+    readonly phone = {
+        connections: {
+            list: () => this.listPhoneConnections(),
+            create: (input: CreateCloudVoicePhoneConnectionInput) => this.createPhoneConnection(input),
+        },
+        numbers: {
+            list: () => this.listPhoneNumbers(),
+            create: (input: CreateCloudVoicePhoneNumberInput) => this.createPhoneNumber(input),
+            update: (input: UpdateCloudVoicePhoneNumberInput) => this.updatePhoneNumber(input),
+        },
+        bridge: {
+            health: () => this.getPhoneBridgeHealth(),
+        },
+        sip: {
+            diagnostics: () => this.getSipDiagnostics(),
+            reload: () => this.reloadSipBridge(),
+        },
+    };
+
+    readonly recordings = {
+        getForSession: (sessionId: string) => this.getSessionRecordings(sessionId),
+    };
+
+    readonly tools = {
+        catalog: {
+            list: () => this.listToolCatalog(),
+            sync: (input: SyncCloudVoiceToolCatalogInput) => this.syncToolCatalog(input),
+        },
+    };
+
+    readonly customVoices = {
+        list: () => this.listCustomVoices(),
+        import: (input: ImportCloudVoiceCustomVoiceInput) => this.importCustomVoice(input),
+        clone: (input: CloneCloudVoiceCustomVoiceInput) => this.cloneCustomVoice(input),
+        update: (voiceId: string, input: UpdateCloudVoiceCustomVoiceInput) => this.updateCustomVoice(voiceId, input),
+        delete: (voiceId: string) => this.deleteCustomVoice(voiceId),
+    };
+
+    constructor(config: CloudVoiceClientConfig | HttpTransport) {
+        this.transport = isTransportLike(config) ? config : new HttpTransport(config as HttpTransportConfig);
+    }
+
+    async listAgents(): Promise<CloudVoiceAgentRecord[]> {
+        const res = await this.transport.json<{ agents: CloudVoiceAgentRecord[] }>("/api/cloud/voice/agents");
+        return res.agents;
+    }
+
+    async getAgent(slug: string): Promise<CloudVoiceAgentRecord> {
+        return this.transport.json<CloudVoiceAgentRecord>(`/api/cloud/voice/agents/${encodeURIComponent(assertString(slug, "slug"))}`);
+    }
+
+    async createAgent(input: CreateCloudVoiceAgentInput): Promise<CloudVoiceAgentRecord> {
+        return this.transport.json<CloudVoiceAgentRecord>("/api/cloud/voice/agents", {
+            method: "POST",
+            body: JSON.stringify(input),
+        });
+    }
+
+    async listCustomVoices(): Promise<CloudVoiceCustomVoiceRecord[]> {
+        const res = await this.transport.json<{ voices: CloudVoiceCustomVoiceRecord[] }>("/api/cloud/voice/custom-voices");
+        return res.voices;
+    }
+
+    async importCustomVoice(input: ImportCloudVoiceCustomVoiceInput): Promise<CloudVoiceCustomVoiceRecord> {
+        return this.transport.json<CloudVoiceCustomVoiceRecord>("/api/cloud/voice/custom-voices/import", {
+            method: "POST",
+            body: JSON.stringify(input),
+        });
+    }
+
+    async cloneCustomVoice(input: CloneCloudVoiceCustomVoiceInput): Promise<CloudVoiceCustomVoiceRecord> {
+        const form = new FormData();
+        form.append("file", input.file, input.fileName ?? "reference.wav");
+        const fields = {
+            name: input.name,
+            description: input.description,
+            gender: input.gender,
+            accent: input.accent,
+            age: input.age,
+            language: input.language,
+            use_case: input.useCase,
+            tone: input.tone,
+        };
+        for (const [key, value] of Object.entries(fields)) {
+            if (typeof value === "string" && value.trim()) form.append(key, value.trim());
+        }
+        form.append("consent", JSON.stringify(input.consent));
+        return this.transport.multipart<CloudVoiceCustomVoiceRecord>("/api/cloud/voice/custom-voices/clone", form, {
+            method: "POST",
+        });
+    }
+
+    async updateCustomVoice(voiceId: string, input: UpdateCloudVoiceCustomVoiceInput): Promise<CloudVoiceCustomVoiceRecord> {
+        return this.transport.json<CloudVoiceCustomVoiceRecord>(`/api/cloud/voice/custom-voices/${encodeURIComponent(assertString(voiceId, "voiceId"))}`, {
+            method: "PATCH",
+            body: JSON.stringify({
+                ...input,
+                ...(input.useCase !== undefined ? { use_case: input.useCase } : {}),
+            }),
+        });
+    }
+
+    async deleteCustomVoice(voiceId: string): Promise<{ success: boolean }> {
+        return this.transport.json<{ success: boolean }>(`/api/cloud/voice/custom-voices/${encodeURIComponent(assertString(voiceId, "voiceId"))}`, {
+            method: "DELETE",
+        });
+    }
+
+    async updateAgent(slug: string, input: UpdateCloudVoiceAgentInput): Promise<CloudVoiceAgentRecord> {
+        return this.transport.json<CloudVoiceAgentRecord>(`/api/cloud/voice/agents/${encodeURIComponent(assertString(slug, "slug"))}`, {
+            method: "PUT",
+            body: JSON.stringify(input),
+        });
+    }
+
+    async useAgent(slug: string, input: UseCloudVoiceAgentInput = {}): Promise<UseCloudVoiceAgentResult> {
+        const normalizedSlug = assertString(slug, "slug");
+        let existing: CloudVoiceAgentRecord | null = null;
+        try {
+            existing = await this.getAgent(normalizedSlug);
+        } catch (error) {
+            if (!isNotFoundError(error)) throw error;
+        }
+
+        const hasUpdates = input.name !== undefined
+            || input.description !== undefined
+            || input.status !== undefined
+            || input.config !== undefined;
+
+        let action: UseCloudVoiceAgentResult["action"] = existing ? "used" : "created";
+        let agent = existing;
+        if (existing && hasUpdates) {
+            agent = await this.updateAgent(normalizedSlug, {
+                ...(input.name !== undefined ? { name: input.name } : {}),
+                ...(input.description !== undefined ? { description: input.description } : {}),
+                ...(input.status !== undefined ? { status: input.status } : {}),
+                ...(input.config !== undefined ? { config: input.config } : {}),
+            });
+            action = "updated";
+        } else if (!existing) {
+            agent = await this.createAgent({
+                name: input.name ?? normalizedSlug,
+                slug: normalizedSlug,
+                description: input.description,
+                config: input.config,
+            });
+        }
+
+        if (!agent) {
+            throw new Error(`Cloud voice agent "${normalizedSlug}" could not be created or resolved`);
+        }
+
+        if (input.publish) {
+            agent = await this.publishAgent(agent.slug);
+        }
+
+        return { action, agent };
+    }
+
+    async deleteAgent(slug: string): Promise<{ success: boolean }> {
+        return this.transport.json<{ success: boolean }>(`/api/cloud/voice/agents/${encodeURIComponent(assertString(slug, "slug"))}`, {
+            method: "DELETE",
+        });
+    }
+
+    async publishAgent(slug: string): Promise<CloudVoiceAgentRecord> {
+        return this.transport.json<CloudVoiceAgentRecord>(`/api/cloud/voice/agents/${encodeURIComponent(assertString(slug, "slug"))}/publish`, {
+            method: "POST",
+        });
+    }
+
+    async unpublishAgent(slug: string): Promise<CloudVoiceAgentRecord> {
+        return this.transport.json<CloudVoiceAgentRecord>(`/api/cloud/voice/agents/${encodeURIComponent(assertString(slug, "slug"))}/unpublish`, {
+            method: "POST",
+        });
+    }
+
+    async listSessions(agentId?: string): Promise<CloudVoiceSessionRecord[]> {
+        const path = agentId ? `/api/cloud/voice/sessions?agentId=${encodeURIComponent(agentId)}` : "/api/cloud/voice/sessions";
+        const res = await this.transport.json<{ sessions: CloudVoiceSessionRecord[] }>(path);
+        return res.sessions;
+    }
+
+    async createSession(input: CreateCloudVoiceSessionInput): Promise<CloudVoiceSessionBootstrap> {
+        return this.transport.json<CloudVoiceSessionBootstrap>("/api/cloud/voice/sessions", {
+            method: "POST",
+            body: JSON.stringify(input),
+        });
+    }
+
+    async getSession(sessionId: string): Promise<CloudVoiceSessionRecord> {
+        return this.transport.json<CloudVoiceSessionRecord>(`/api/cloud/voice/sessions/${encodeURIComponent(assertString(sessionId, "sessionId"))}`);
+    }
+
+    async cancelSession(sessionId: string, reason?: string): Promise<CloudVoiceSessionRecord> {
+        return this.transport.json<CloudVoiceSessionRecord>(`/api/cloud/voice/sessions/${encodeURIComponent(assertString(sessionId, "sessionId"))}/cancel`, {
+            method: "POST",
+            body: JSON.stringify({ reason }),
+        });
+    }
+
+    async getSessionEvents(sessionId: string): Promise<CloudVoiceSessionEventRecord[]> {
+        const res = await this.transport.json<{ events: CloudVoiceSessionEventRecord[] }>(`/api/cloud/voice/sessions/${encodeURIComponent(assertString(sessionId, "sessionId"))}/events`);
+        return res.events;
+    }
+
+    async appendSessionEvent(sessionId: string, event: Record<string, unknown>): Promise<CloudVoiceSessionEventRecord> {
+        return this.transport.json<CloudVoiceSessionEventRecord>(`/api/cloud/voice/sessions/${encodeURIComponent(assertString(sessionId, "sessionId"))}/events`, {
+            method: "POST",
+            body: JSON.stringify(event),
+        });
+    }
+
+    async streamSessionEvents(sessionId: string, init?: RequestInit): Promise<Response> {
+        return this.transport.raw(`/api/cloud/voice/sessions/${encodeURIComponent(assertString(sessionId, "sessionId"))}/events/stream`, init);
+    }
+
+    async subscribeToSession(sessionId: string, init?: RequestInit): Promise<AsyncGenerator<CloudVoiceSessionEventRecord | { type: "unknown"; frame: unknown }>> {
+        const response = await this.streamSessionEvents(sessionId, init);
+        if (!response.body) throw new Error("Cloud voice event stream response did not include a body");
+        const events = readSSEStream(response.body);
+        async function* decode() {
+            for await (const frame of events) {
+                try {
+                    yield JSON.parse(frame.data) as CloudVoiceSessionEventRecord;
+                } catch {
+                    yield { type: "unknown" as const, frame };
+                }
+            }
+        }
+        return decode();
+    }
+
+    async executeTool(sessionId: string, toolId: string, input: unknown): Promise<{ result: unknown }> {
+        return this.transport.json<{ result: unknown }>(`/api/cloud/voice/sessions/${encodeURIComponent(assertString(sessionId, "sessionId"))}/tools/${encodeURIComponent(assertString(toolId, "toolId"))}/execute`, {
+            method: "POST",
+            body: JSON.stringify({ input }),
+        });
+    }
+
+    async getSessionRecordings(sessionId: string): Promise<{ recording: unknown | null; assets: CloudVoiceRecordingAsset[] }> {
+        return this.transport.json<{ recording: unknown | null; assets: CloudVoiceRecordingAsset[] }>(`/api/cloud/voice/sessions/${encodeURIComponent(assertString(sessionId, "sessionId"))}/recordings`);
+    }
+
+    async listPhoneConnections(): Promise<CloudVoicePhoneConnectionRecord[]> {
+        const res = await this.transport.json<{ connections: CloudVoicePhoneConnectionRecord[] }>("/api/cloud/voice/phone/connections");
+        return res.connections;
+    }
+
+    async createPhoneConnection(input: CreateCloudVoicePhoneConnectionInput): Promise<CloudVoicePhoneConnectionRecord> {
+        return this.transport.json<CloudVoicePhoneConnectionRecord>("/api/cloud/voice/phone/connections", {
+            method: "POST",
+            body: JSON.stringify(input),
+        });
+    }
+
+    async listPhoneNumbers(): Promise<CloudVoicePhoneNumberRecord[]> {
+        const res = await this.transport.json<{ numbers: CloudVoicePhoneNumberRecord[] }>("/api/cloud/voice/phone/numbers");
+        return res.numbers;
+    }
+
+    async createPhoneNumber(input: CreateCloudVoicePhoneNumberInput): Promise<CloudVoicePhoneNumberRecord> {
+        return this.transport.json<CloudVoicePhoneNumberRecord>("/api/cloud/voice/phone/numbers", {
+            method: "POST",
+            body: JSON.stringify(input),
+        });
+    }
+
+    async updatePhoneNumber(input: UpdateCloudVoicePhoneNumberInput): Promise<CloudVoicePhoneNumberRecord | null> {
+        return this.transport.json<CloudVoicePhoneNumberRecord | null>("/api/cloud/voice/phone/numbers", {
+            method: "PATCH",
+            body: JSON.stringify(input),
+        });
+    }
+
+    async getPhoneBridgeHealth(): Promise<CloudVoicePhoneBridgeHealth> {
+        const res = await this.transport.json<{ bridge: CloudVoicePhoneBridgeHealth }>("/api/cloud/voice/phone/bridge");
+        return res.bridge;
+    }
+
+    async getSipDiagnostics(): Promise<CloudVoiceSipDiagnostics> {
+        const res = await this.transport.json<{ sip: CloudVoiceSipDiagnostics }>("/api/cloud/voice/phone/sip");
+        return res.sip;
+    }
+
+    async reloadSipBridge(): Promise<Record<string, unknown>> {
+        const res = await this.transport.json<{ sip: Record<string, unknown> }>("/api/cloud/voice/phone/sip", {
+            method: "POST",
+            body: "{}",
+        });
+        return res.sip;
+    }
+
+    async listToolCatalog(): Promise<CloudVoiceToolCatalog> {
+        return this.transport.json<CloudVoiceToolCatalog>("/api/cloud/voice/tools/catalog");
+    }
+
+    async syncToolCatalog(input: SyncCloudVoiceToolCatalogInput): Promise<CloudVoiceToolCatalog> {
+        return this.transport.json<CloudVoiceToolCatalog>("/api/cloud/voice/tools/sync", {
+            method: "POST",
+            body: JSON.stringify(input),
+        });
+    }
+
+    async listCalls(): Promise<CloudVoiceCallLegRecord[]> {
+        const res = await this.transport.json<{ calls: CloudVoiceCallLegRecord[] }>("/api/cloud/voice/calls");
+        return res.calls;
+    }
+
+    async listLiveCalls(input: { status?: "live" | "all"; limit?: number } = {}): Promise<CloudVoiceLiveCallRecord[]> {
+        const params = new URLSearchParams();
+        if (input.status === "all") params.set("status", "all");
+        if (input.limit !== undefined) params.set("limit", String(input.limit));
+        const qs = params.toString();
+        const res = await this.transport.json<{ calls: CloudVoiceLiveCallRecord[] }>(`/api/cloud/voice/calls/live${qs ? `?${qs}` : ""}`);
+        return res.calls;
+    }
+
+    async getCall(sessionId: string): Promise<CloudVoiceLiveCallRecord> {
+        return this.transport.json<CloudVoiceLiveCallRecord>(`/api/cloud/voice/calls/${encodeURIComponent(assertString(sessionId, "sessionId"))}`);
+    }
+
+    async createCall(input: CreateCloudVoiceOutboundCallInput): Promise<{
+        session: CloudVoiceSessionBootstrap;
+        callLeg: CloudVoiceCallLegRecord;
+        providerCall: unknown;
+    }> {
+        return this.transport.json("/api/cloud/voice/calls", {
+            method: "POST",
+            body: JSON.stringify(input),
+        });
+    }
+
+    async finalizeCall(sessionId: string): Promise<CloudVoiceCallWaitResult> {
+        return this.transport.json<CloudVoiceCallWaitResult>(`/api/cloud/voice/calls/${encodeURIComponent(assertString(sessionId, "sessionId"))}/finalize`, {
+            method: "POST",
+            body: JSON.stringify({}),
+        });
+    }
+
+    async waitForCall(sessionId: string, options: CloudVoiceCallWaitOptions = {}): Promise<CloudVoiceCallWaitResult> {
+        const normalizedSessionId = assertString(sessionId, "sessionId");
+        const intervalMs = Math.max(10, options.intervalMs ?? 1_000);
+        const timeoutMs = Math.max(intervalMs, options.timeoutMs ?? 30 * 60_000);
+        const deadline = Date.now() + timeoutMs;
+        let lastFingerprint: string | null = null;
+        let previousStatus: string | undefined;
+
+        while (true) {
+            const call = await this.getCall(normalizedSessionId);
+            const fingerprint = callStatusFingerprint(call);
+            if (fingerprint !== lastFingerprint) {
+                const event = toCallStatusChange(call, previousStatus);
+                options.onStatusChange?.(event);
+                options.onEvent?.(event);
+                lastFingerprint = fingerprint;
+                previousStatus = call.status;
+            }
+
+            if (isTerminalCall(call)) {
+                const result = await this.finalizeCall(normalizedSessionId);
+                const finalFingerprint = callStatusFingerprint(result.call);
+                if (finalFingerprint !== lastFingerprint) {
+                    const event = toCallStatusChange(result.call, previousStatus);
+                    options.onStatusChange?.(event);
+                    options.onEvent?.(event);
+                }
+                return result;
+            }
+
+            if (Date.now() >= deadline) {
+                throw new Error(`Cloud voice call ${normalizedSessionId} did not complete within ${timeoutMs}ms`);
+            }
+
+            await sleep(intervalMs);
+        }
+    }
+
+    async executeCallTool(sessionId: string, toolId: string, input: unknown): Promise<{ result: unknown }> {
+        return this.transport.json<{ result: unknown }>(`/api/cloud/voice/calls/${encodeURIComponent(assertString(sessionId, "sessionId"))}/tools/${encodeURIComponent(assertString(toolId, "toolId"))}`, {
+            method: "POST",
+            body: JSON.stringify({ input }),
+        });
+    }
+
+    async hangupCall(sessionId: string, reason?: string): Promise<{ call: CloudVoiceLiveCallRecord; result: unknown }> {
+        return this.transport.json<{ call: CloudVoiceLiveCallRecord; result: unknown }>(`/api/cloud/voice/calls/${encodeURIComponent(assertString(sessionId, "sessionId"))}/hangup`, {
+            method: "POST",
+            body: JSON.stringify({ reason }),
+        });
+    }
+
+    async createCallListenToken(sessionId: string, input: { managerId?: string; takeover?: boolean } = {}): Promise<CloudVoiceListenTokenResult> {
+        return this.transport.json<CloudVoiceListenTokenResult>(`/api/cloud/voice/calls/${encodeURIComponent(assertString(sessionId, "sessionId"))}/listen-token`, {
+            method: "POST",
+            body: JSON.stringify(input),
+        });
+    }
+
+    async createCallHandoff(sessionId: string, input: CreateCloudVoiceHandoffInput = {}): Promise<{ handoff: CloudVoiceHandoffRecord }> {
+        return this.transport.json<{ handoff: CloudVoiceHandoffRecord }>(`/api/cloud/voice/calls/${encodeURIComponent(assertString(sessionId, "sessionId"))}/handoff`, {
+            method: "POST",
+            body: JSON.stringify(input),
+        });
+    }
+
+    async acceptCallHandoff(sessionId: string, handoffId: string, input: AcceptCloudVoiceHandoffInput = {}): Promise<{ handoff: CloudVoiceHandoffRecord }> {
+        return this.transport.json<{ handoff: CloudVoiceHandoffRecord }>(`/api/cloud/voice/calls/${encodeURIComponent(assertString(sessionId, "sessionId"))}/handoff/${encodeURIComponent(assertString(handoffId, "handoffId"))}/accept`, {
+            method: "POST",
+            body: JSON.stringify(input),
+        });
+    }
+
+    async cancelCallHandoff(sessionId: string, handoffId: string, input: CancelCloudVoiceHandoffInput = {}): Promise<{ handoff: CloudVoiceHandoffRecord }> {
+        return this.transport.json<{ handoff: CloudVoiceHandoffRecord }>(`/api/cloud/voice/calls/${encodeURIComponent(assertString(sessionId, "sessionId"))}/handoff/${encodeURIComponent(assertString(handoffId, "handoffId"))}/cancel`, {
+            method: "POST",
+            body: JSON.stringify(input),
+        });
+    }
+}
+
+export class KognitiveCloudVoiceEmbedClient {
+    private readonly baseUrl: string;
+    private readonly publicKey: string;
+    private readonly fetchImpl: typeof fetch;
+
+    constructor(config: { baseUrl: string; publicKey: string; fetch?: typeof fetch }) {
+        this.baseUrl = config.baseUrl.replace(/\/$/, "");
+        this.publicKey = assertString(config.publicKey, "publicKey");
+        this.fetchImpl = config.fetch ?? globalThis.fetch.bind(globalThis);
+    }
+
+    private headers(extra?: HeadersInit) {
+        const headers = new Headers(extra);
+        headers.set("x-kognitive-public-key", this.publicKey);
+        headers.set("Content-Type", "application/json");
+        return headers;
+    }
+
+    async config(agent: string): Promise<CloudVoiceEmbedConfig> {
+        const res = await this.fetchImpl(`${this.baseUrl}/api/cloud/voice/embed/config?agent=${encodeURIComponent(agent)}`, {
+            headers: this.headers(),
+        });
+        if (!res.ok) throw new Error(await res.text());
+        return res.json() as Promise<CloudVoiceEmbedConfig>;
+    }
+
+    async createSession(input: CreateCloudVoiceSessionInput): Promise<CloudVoiceSessionBootstrap> {
+        const res = await this.fetchImpl(`${this.baseUrl}/api/cloud/voice/embed/sessions`, {
+            method: "POST",
+            headers: this.headers(),
+            body: JSON.stringify(input),
+        });
+        if (!res.ok) throw new Error(await res.text());
+        return res.json() as Promise<CloudVoiceSessionBootstrap>;
+    }
+
+    async executeTool(sessionId: string, toolId: string, input: unknown): Promise<{ result: unknown }> {
+        const res = await this.fetchImpl(`${this.baseUrl}/api/cloud/voice/sessions/${encodeURIComponent(assertString(sessionId, "sessionId"))}/tools/${encodeURIComponent(assertString(toolId, "toolId"))}/execute`, {
+            method: "POST",
+            headers: this.headers(),
+            body: JSON.stringify({ input }),
+        });
+        if (!res.ok) throw new Error(await res.text());
+        return res.json() as Promise<{ result: unknown }>;
+    }
+}