@kognitivedev/cloud-voice 0.2.29

package/src/__tests__/client.test.ts

@@ -0,0 +1,482 @@
+import { describe, expect, it, vi } from "vitest";
+import { KognitiveApiError } from "@kognitivedev/client-core";
+import { KognitiveCloudVoiceClient } from "../client";
+
+function createTransport(
+    json: (path: string, init?: RequestInit) => Promise<unknown> = async (path: string) => {
+        if (path === "/api/cloud/voice/phone/connections") return { connections: [{ id: "conn_1" }] };
+        if (path === "/api/cloud/voice/phone/numbers") return { numbers: [{ id: "num_1" }] };
+        if (path === "/api/cloud/voice/phone/bridge") return { bridge: { online: true, status: "online" } };
+        if (path === "/api/cloud/voice/phone/sip") return { sip: { bridge: { online: true }, diagnostics: { nodeId: "sip-1" } } };
+        return { ok: true };
+    },
+) {
+    return {
+        baseUrl: "https://api.example.com",
+        json: vi.fn(json),
+        raw: vi.fn(),
+        multipart: vi.fn(async () => ({ id: "voice-row-1", voiceId: "abcd1234" })),
+    };
+}
+
+describe("KognitiveCloudVoiceClient phone APIs", () => {
+    it("manages custom xAI voices through cloud voice routes", async () => {
+        const voice = { id: "voice-row-1", voiceId: "abcd1234", name: "Support voice", provider: "xai-realtime" };
+        const transport = createTransport(async (path: string, init?: RequestInit) => {
+            if (path === "/api/cloud/voice/custom-voices") return { voices: [voice] };
+            if (path === "/api/cloud/voice/custom-voices/import" && init?.method === "POST") return voice;
+            if (path === "/api/cloud/voice/custom-voices/abcd1234" && init?.method === "PATCH") return { ...voice, name: "Updated" };
+            if (path === "/api/cloud/voice/custom-voices/abcd1234" && init?.method === "DELETE") return { success: true };
+            throw new Error(`Unexpected request: ${path}`);
+        });
+        const client = new KognitiveCloudVoiceClient(transport as any);
+
+        await expect(client.customVoices.list()).resolves.toEqual([voice]);
+        await expect(client.customVoices.import({
+            voiceId: "abcd1234",
+            name: "Support voice",
+            consent: { accepted: true },
+        })).resolves.toEqual(voice);
+        await expect(client.customVoices.update("abcd1234", { name: "Updated", useCase: "conversational" })).resolves.toMatchObject({ name: "Updated" });
+        await expect(client.customVoices.delete("abcd1234")).resolves.toEqual({ success: true });
+
+        expect(transport.json).toHaveBeenCalledWith("/api/cloud/voice/custom-voices");
+        expect(transport.json).toHaveBeenCalledWith("/api/cloud/voice/custom-voices/import", {
+            method: "POST",
+            body: JSON.stringify({
+                voiceId: "abcd1234",
+                name: "Support voice",
+                consent: { accepted: true },
+            }),
+        });
+        expect(transport.json).toHaveBeenCalledWith("/api/cloud/voice/custom-voices/abcd1234", {
+            method: "PATCH",
+            body: JSON.stringify({ name: "Updated", useCase: "conversational", use_case: "conversational" }),
+        });
+        expect(transport.json).toHaveBeenCalledWith("/api/cloud/voice/custom-voices/abcd1234", {
+            method: "DELETE",
+        });
+    });
+
+    it("sends custom voice clone uploads as multipart", async () => {
+        const transport = createTransport();
+        const client = new KognitiveCloudVoiceClient(transport as any);
+        const file = new Blob([new Uint8Array([1, 2, 3])], { type: "audio/wav" });
+
+        await expect(client.customVoices.clone({
+            file,
+            fileName: "sample.wav",
+            name: "Support voice",
+            useCase: "conversational",
+            consent: { accepted: true, country: "US", state: "CA" },
+        })).resolves.toMatchObject({ voiceId: "abcd1234" });
+
+        expect(transport.multipart).toHaveBeenCalledWith(
+            "/api/cloud/voice/custom-voices/clone",
+            expect.any(FormData),
+            { method: "POST" },
+        );
+        const form = (transport.multipart as any).mock.calls[0][1] as FormData;
+        expect(form.get("name")).toBe("Support voice");
+        expect(form.get("use_case")).toBe("conversational");
+        expect(form.get("consent")).toBe(JSON.stringify({ accepted: true, country: "US", state: "CA" }));
+    });
+
+    it("lists and creates phone connections through cloud voice routes", async () => {
+        const transport = createTransport();
+        const client = new KognitiveCloudVoiceClient(transport as any);
+
+        await expect(client.phone.connections.list()).resolves.toEqual([{ id: "conn_1" }]);
+        await client.phone.connections.create({
+            name: "Local Twilio",
+            accountSid: "AC123",
+            authToken: "secret",
+        });
+
+        expect(transport.json).toHaveBeenCalledWith("/api/cloud/voice/phone/connections");
+        expect(transport.json).toHaveBeenCalledWith("/api/cloud/voice/phone/connections", {
+            method: "POST",
+            body: JSON.stringify({
+                name: "Local Twilio",
+                accountSid: "AC123",
+                authToken: "secret",
+            }),
+        });
+    });
+
+    it("lists, creates, and updates phone numbers through cloud voice routes", async () => {
+        const transport = createTransport();
+        const client = new KognitiveCloudVoiceClient(transport as any);
+
+        await expect(client.phone.numbers.list()).resolves.toEqual([{ id: "num_1" }]);
+        await client.phone.numbers.create({
+            connectionId: "conn_1",
+            phoneNumber: "+15551234567",
+            inboundAgentSlug: "support",
+            outboundEnabled: true,
+        });
+        await client.phone.numbers.update({
+            id: "num_1",
+            label: "Support",
+            inboundAgentSlug: "support",
+            inboundEnabled: true,
+        });
+
+        expect(transport.json).toHaveBeenCalledWith("/api/cloud/voice/phone/numbers");
+        expect(transport.json).toHaveBeenCalledWith("/api/cloud/voice/phone/numbers", {
+            method: "POST",
+            body: JSON.stringify({
+                connectionId: "conn_1",
+                phoneNumber: "+15551234567",
+                inboundAgentSlug: "support",
+                outboundEnabled: true,
+            }),
+        });
+        expect(transport.json).toHaveBeenCalledWith("/api/cloud/voice/phone/numbers", {
+            method: "PATCH",
+            body: JSON.stringify({
+                id: "num_1",
+                label: "Support",
+                inboundAgentSlug: "support",
+                inboundEnabled: true,
+            }),
+        });
+    });
+
+    it("checks phone bridge health through cloud voice routes", async () => {
+        const transport = createTransport();
+        const client = new KognitiveCloudVoiceClient(transport as any);
+
+        await expect(client.phone.bridge.health()).resolves.toEqual({ online: true, status: "online" });
+        expect(transport.json).toHaveBeenCalledWith("/api/cloud/voice/phone/bridge");
+    });
+
+    it("checks and reloads SIP diagnostics through cloud voice routes", async () => {
+        const transport = createTransport();
+        const client = new KognitiveCloudVoiceClient(transport as any);
+
+        await expect(client.phone.sip.diagnostics()).resolves.toEqual({ bridge: { online: true }, diagnostics: { nodeId: "sip-1" } });
+        await expect(client.phone.sip.reload()).resolves.toEqual({ bridge: { online: true }, diagnostics: { nodeId: "sip-1" } });
+        expect(transport.json).toHaveBeenCalledWith("/api/cloud/voice/phone/sip");
+        expect(transport.json).toHaveBeenCalledWith("/api/cloud/voice/phone/sip", {
+            method: "POST",
+            body: "{}",
+        });
+    });
+
+    it("lists live calls, loads details, and hangs up through call routes", async () => {
+        const liveCall = { id: "session_1", callLegId: "call_1", stateLabel: "Connected" };
+        const handoff = { id: "handoff_1", status: "active", mode: "browser" };
+        const token = { token: "listen.jwt", wsUrl: "wss://api.example.com/audio", scopes: ["listen"] };
+        const transport = createTransport(async (path: string, init?: RequestInit) => {
+            if (path === "/api/cloud/voice/calls/live?status=all&limit=25") return { calls: [liveCall] };
+            if (path === "/api/cloud/voice/calls/session_1" && !init) return liveCall;
+            if (path === "/api/cloud/voice/calls/session_1/hangup" && init?.method === "POST") return { call: liveCall, result: { ok: true } };
+            if (path === "/api/cloud/voice/calls/session_1/listen-token" && init?.method === "POST") return token;
+            if (path === "/api/cloud/voice/calls/session_1/handoff" && init?.method === "POST") return { handoff };
+            if (path === "/api/cloud/voice/calls/session_1/handoff/handoff_1/accept" && init?.method === "POST") return { handoff };
+            if (path === "/api/cloud/voice/calls/session_1/handoff/handoff_1/cancel" && init?.method === "POST") return { handoff: { ...handoff, status: "returned_to_ai" } };
+            return { ok: true };
+        });
+        const client = new KognitiveCloudVoiceClient(transport as any);
+
+        await expect(client.calls.live({ status: "all", limit: 25 })).resolves.toEqual([liveCall]);
+        await expect(client.calls.get("session_1")).resolves.toEqual(liveCall);
+        await expect(client.calls.hangup("session_1", "Done")).resolves.toEqual({ call: liveCall, result: { ok: true } });
+        await expect(client.calls.listenToken("session_1", { managerId: "mgr_1" })).resolves.toEqual(token);
+        await expect(client.calls.handoff.create("session_1", { mode: "browser", managerId: "mgr_1" })).resolves.toEqual({ handoff });
+        await expect(client.calls.handoff.accept("session_1", "handoff_1", { managerId: "mgr_1" })).resolves.toEqual({ handoff });
+        await expect(client.calls.handoff.cancel("session_1", "handoff_1", { returnToAi: true })).resolves.toEqual({ handoff: { ...handoff, status: "returned_to_ai" } });
+
+        expect(transport.json).toHaveBeenCalledWith("/api/cloud/voice/calls/live?status=all&limit=25");
+        expect(transport.json).toHaveBeenCalledWith("/api/cloud/voice/calls/session_1");
+        expect(transport.json).toHaveBeenCalledWith("/api/cloud/voice/calls/session_1/hangup", {
+            method: "POST",
+            body: JSON.stringify({ reason: "Done" }),
+        });
+        expect(transport.json).toHaveBeenCalledWith("/api/cloud/voice/calls/session_1/listen-token", {
+            method: "POST",
+            body: JSON.stringify({ managerId: "mgr_1" }),
+        });
+        expect(transport.json).toHaveBeenCalledWith("/api/cloud/voice/calls/session_1/handoff", {
+            method: "POST",
+            body: JSON.stringify({ mode: "browser", managerId: "mgr_1" }),
+        });
+        expect(transport.json).toHaveBeenCalledWith("/api/cloud/voice/calls/session_1/handoff/handoff_1/accept", {
+            method: "POST",
+            body: JSON.stringify({ managerId: "mgr_1" }),
+        });
+        expect(transport.json).toHaveBeenCalledWith("/api/cloud/voice/calls/session_1/handoff/handoff_1/cancel", {
+            method: "POST",
+            body: JSON.stringify({ returnToAi: true }),
+        });
+    });
+
+    it("waits for a call to complete, emits status changes, and finalizes outcome", async () => {
+        const changes: string[] = [];
+        const events: string[] = [];
+        const queuedCall = {
+            id: "session_1",
+            status: "queued",
+            sessionStatus: "created",
+            stateLabel: "Dialing",
+            latestEventType: "voice.call.outbound.created",
+            outcomeStatus: null,
+            endedAt: null,
+        };
+        const completedCall = {
+            ...queuedCall,
+            status: "completed",
+            sessionStatus: "completed",
+            stateLabel: "Ended",
+            latestEventType: "voice.phone.hangup.completed",
+            outcomeStatus: null,
+            endedAt: "2026-05-03T12:00:00.000Z",
+        };
+        const finalized = {
+            call: {
+                ...completedCall,
+                outcomeStatus: "completed",
+                outcomeReason: "The call reached a normal terminal state.",
+                outcomeConfidence: 0.85,
+            },
+            status: "completed",
+            outcome: {
+                status: "completed",
+                reason: "The call reached a normal terminal state.",
+                confidence: 0.85,
+            },
+            outcomeSource: "derived",
+        };
+        let getCount = 0;
+        const transport = createTransport(async (path: string, init?: RequestInit) => {
+            if (path === "/api/cloud/voice/calls/session_1" && !init) {
+                getCount += 1;
+                return getCount <= 2 ? queuedCall : completedCall;
+            }
+            if (path === "/api/cloud/voice/calls/session_1/finalize" && init?.method === "POST") return finalized;
+            throw new Error(`Unexpected request: ${path}`);
+        });
+        const client = new KognitiveCloudVoiceClient(transport as any);
+
+        await expect(client.calls.wait("session_1", {
+            intervalMs: 10,
+            timeoutMs: 1_000,
+            onStatusChange: (event) => changes.push(`${event.status}:${event.sessionStatus}:${event.outcomeStatus ?? "none"}`),
+            onEvent: (event) => events.push(`${event.status}:${event.stateLabel}:${event.latestEventType ?? "none"}`),
+        })).resolves.toEqual(finalized);
+
+        expect(changes).toEqual([
+            "queued:created:none",
+            "completed:completed:none",
+            "completed:completed:completed",
+        ]);
+        expect(events).toEqual([
+            "queued:Dialing:voice.call.outbound.created",
+            "completed:Ended:voice.phone.hangup.completed",
+            "completed:Ended:voice.phone.hangup.completed",
+        ]);
+        expect(getCount).toBe(3);
+        expect(transport.json).toHaveBeenCalledWith("/api/cloud/voice/calls/session_1/finalize", {
+            method: "POST",
+            body: JSON.stringify({}),
+        });
+    });
+
+    it("surfaces finalize errors after a terminal call is observed", async () => {
+        const completedCall = {
+            id: "session_1",
+            status: "completed",
+            sessionStatus: "completed",
+            stateLabel: "Ended",
+            latestEventType: "voice.phone.hangup.completed",
+            outcomeStatus: null,
+            endedAt: "2026-05-03T12:00:00.000Z",
+        };
+        const apiError = new KognitiveApiError("Finalize failed", 500, { error: "Finalize failed" });
+        const transport = createTransport(async (path: string, init?: RequestInit) => {
+            if (path === "/api/cloud/voice/calls/session_1" && !init) return completedCall;
+            if (path === "/api/cloud/voice/calls/session_1/finalize" && init?.method === "POST") throw apiError;
+            throw new Error(`Unexpected request: ${path}`);
+        });
+        const client = new KognitiveCloudVoiceClient(transport as any);
+
+        await expect(client.calls.wait("session_1", {
+            intervalMs: 10,
+            timeoutMs: 1_000,
+        })).rejects.toBe(apiError);
+
+        expect(transport.json).toHaveBeenCalledWith("/api/cloud/voice/calls/session_1/finalize", {
+            method: "POST",
+            body: JSON.stringify({}),
+        });
+    });
+
+    it("finalizes when the session status is terminal even if the call leg is still active", async () => {
+        const sessionTerminalCall = {
+            id: "session_1",
+            status: "active",
+            sessionStatus: "completed",
+            stateLabel: "Ended",
+            latestEventType: "voice.session.completed",
+            outcomeStatus: null,
+            endedAt: null,
+        };
+        const finalized = {
+            call: {
+                ...sessionTerminalCall,
+                outcomeStatus: "completed",
+            },
+            status: "completed",
+            outcome: {
+                status: "completed",
+                reason: "The call reached a normal terminal state.",
+                confidence: 0.85,
+            },
+            outcomeSource: "derived",
+        };
+        const transport = createTransport(async (path: string, init?: RequestInit) => {
+            if (path === "/api/cloud/voice/calls/session_1" && !init) return sessionTerminalCall;
+            if (path === "/api/cloud/voice/calls/session_1/finalize" && init?.method === "POST") return finalized;
+            throw new Error(`Unexpected request: ${path}`);
+        });
+        const client = new KognitiveCloudVoiceClient(transport as any);
+
+        await expect(client.calls.wait("session_1", {
+            intervalMs: 10,
+            timeoutMs: 1_000,
+        })).resolves.toEqual(finalized);
+
+        expect(transport.json).toHaveBeenCalledWith("/api/cloud/voice/calls/session_1/finalize", {
+            method: "POST",
+            body: JSON.stringify({}),
+        });
+    });
+
+    it("times out while waiting for a non-terminal call", async () => {
+        const transport = createTransport(async (path: string, init?: RequestInit) => {
+            if (path === "/api/cloud/voice/calls/session_1" && !init) {
+                return {
+                    id: "session_1",
+                    status: "queued",
+                    sessionStatus: "created",
+                    stateLabel: "Dialing",
+                    latestEventType: null,
+                    outcomeStatus: null,
+                    endedAt: null,
+                };
+            }
+            throw new Error(`Unexpected request: ${path}`);
+        });
+        const client = new KognitiveCloudVoiceClient(transport as any);
+
+        await expect(client.calls.wait("session_1", {
+            intervalMs: 10,
+            timeoutMs: 20,
+        })).rejects.toThrow("did not complete within 20ms");
+    });
+});
+
+describe("KognitiveCloudVoiceClient agent management APIs", () => {
+    it("creates and optionally publishes an agent when use cannot find the slug", async () => {
+        const createdAgent = { id: "agent_1", slug: "support", status: "draft" };
+        const publishedAgent = { ...createdAgent, status: "published" };
+        const transport = createTransport(async (path: string, init?: RequestInit) => {
+            if (path === "/api/cloud/voice/agents/support" && !init) {
+                throw new KognitiveApiError("Agent not found", 404, { error: "Agent not found" });
+            }
+            if (path === "/api/cloud/voice/agents" && init?.method === "POST") return createdAgent;
+            if (path === "/api/cloud/voice/agents/support/publish" && init?.method === "POST") return publishedAgent;
+            throw new Error(`Unexpected request: ${path}`);
+        });
+        const client = new KognitiveCloudVoiceClient(transport as any);
+
+        await expect(client.agents.use("support", {
+            name: "Support",
+            publish: true,
+            config: {
+                instructions: "Help customers over voice.",
+                provider: "openai-realtime",
+                model: "gpt-realtime",
+                voice: "marin",
+                transport: "webrtc",
+                channels: { web: true, phone: true, outbound: true },
+                humanization: { openingMode: "auto", fillerStyle: "light" },
+                widget: { title: "Talk to support", launcher: "button" },
+            },
+        })).resolves.toEqual({ action: "created", agent: publishedAgent });
+
+        expect(transport.json).toHaveBeenCalledWith("/api/cloud/voice/agents/support");
+        expect(transport.json).toHaveBeenCalledWith("/api/cloud/voice/agents", {
+            method: "POST",
+            body: JSON.stringify({
+                name: "Support",
+                slug: "support",
+                description: undefined,
+                config: {
+                    instructions: "Help customers over voice.",
+                    provider: "openai-realtime",
+                    model: "gpt-realtime",
+                    voice: "marin",
+                    transport: "webrtc",
+                    channels: { web: true, phone: true, outbound: true },
+                    humanization: { openingMode: "auto", fillerStyle: "light" },
+                    widget: { title: "Talk to support", launcher: "button" },
+                },
+            }),
+        });
+        expect(transport.json).toHaveBeenCalledWith("/api/cloud/voice/agents/support/publish", { method: "POST" });
+    });
+
+    it("updates an existing agent when createOrUse receives configuration", async () => {
+        const existingAgent = { id: "agent_1", slug: "support", status: "published" };
+        const updatedAgent = { ...existingAgent, status: "draft", draftVersion: 2 };
+        const transport = createTransport(async (path: string, init?: RequestInit) => {
+            if (path === "/api/cloud/voice/agents/support" && !init) return existingAgent;
+            if (path === "/api/cloud/voice/agents/support" && init?.method === "PUT") return updatedAgent;
+            throw new Error(`Unexpected request: ${path}`);
+        });
+        const client = new KognitiveCloudVoiceClient(transport as any);
+
+        await expect(client.agents.management.createOrUse("support", {
+            description: "Updated support agent",
+            config: {
+                instructions: "Answer with concise order help.",
+                tools: [{
+                    id: "lookup_order",
+                    type: "external_webhook",
+                    name: "Lookup order",
+                    config: { url: "https://example.com/tools/lookup-order" },
+                }],
+            },
+        })).resolves.toEqual({ action: "updated", agent: updatedAgent });
+
+        expect(transport.json).toHaveBeenCalledWith("/api/cloud/voice/agents/support", {
+            method: "PUT",
+            body: JSON.stringify({
+                description: "Updated support agent",
+                config: {
+                    instructions: "Answer with concise order help.",
+                    tools: [{
+                        id: "lookup_order",
+                        type: "external_webhook",
+                        name: "Lookup order",
+                        config: { url: "https://example.com/tools/lookup-order" },
+                    }],
+                },
+            }),
+        });
+    });
+
+    it("returns the existing agent without updating when use is called without changes", async () => {
+        const existingAgent = { id: "agent_1", slug: "support", status: "published" };
+        const transport = createTransport(async (path: string, init?: RequestInit) => {
+            if (path === "/api/cloud/voice/agents/support" && !init) return existingAgent;
+            throw new Error(`Unexpected request: ${path}`);
+        });
+        const client = new KognitiveCloudVoiceClient(transport as any);
+
+        await expect(client.agents.management.use("support")).resolves.toEqual({ action: "used", agent: existingAgent });
+        expect(transport.json).toHaveBeenCalledTimes(1);
+    });
+});

package/src/__tests__/server.test.ts

@@ -0,0 +1,84 @@
+import { createHmac } from "node:crypto";
+import { describe, expect, it } from "vitest";
+import { createCloudVoiceTools } from "../server";
+
+function signedRequest(body: unknown, secret: string) {
+    const timestamp = new Date().toISOString();
+    const raw = JSON.stringify(body);
+    const signature = `sha256=${createHmac("sha256", secret).update(`${timestamp}.${raw}`).digest("hex")}`;
+    return new Request("https://example.com/api/voice-tools", {
+        method: "POST",
+        headers: {
+            "content-type": "application/json",
+            "x-kognitive-timestamp": timestamp,
+            "x-kognitive-signature": signature,
+        },
+        body: raw,
+    });
+}
+
+describe("createCloudVoiceTools", () => {
+    it("routes a signed cloud voice tool request to the matching handler", async () => {
+        const handler = createCloudVoiceTools({
+            secret: "secret",
+            tools: {
+                lookup_order: async (input: { orderNumber: string }, ctx) => ({
+                    orderNumber: input.orderNumber,
+                    userId: ctx.session.userId,
+                }),
+            },
+        });
+
+        const response = await handler(signedRequest({
+            type: "cloud_voice.tool.execute",
+            toolCallId: "tool_call_1",
+            toolId: "lookup_order",
+            input: { orderNumber: "A-1024" },
+            session: {
+                id: "session-db-id",
+                sessionId: "voice_session_1",
+                agentSlug: "support",
+                channel: "iframe",
+                userId: "user_1",
+                resourceId: { userId: "user_1" },
+                metadata: {},
+            },
+        }, "secret"));
+
+        await expect(response.json()).resolves.toEqual({
+            result: {
+                orderNumber: "A-1024",
+                userId: "user_1",
+            },
+        });
+    });
+
+    it("rejects invalid signatures", async () => {
+        const handler = createCloudVoiceTools({
+            secret: "secret",
+            tools: {
+                lookup_order: async () => ({ ok: true }),
+            },
+        });
+
+        const response = await handler(signedRequest({
+            type: "cloud_voice.tool.execute",
+            toolCallId: "tool_call_1",
+            toolId: "lookup_order",
+            input: {},
+            session: {
+                id: "session-db-id",
+                sessionId: "voice_session_1",
+                agentSlug: "support",
+                channel: "iframe",
+                userId: "user_1",
+                resourceId: {},
+                metadata: {},
+            },
+        }, "wrong"));
+
+        expect(response.status).toBe(400);
+        await expect(response.json()).resolves.toEqual({ error: "Invalid Kognitive signature" });
+    });
+});
+