@kognitivedev/cloud-voice 0.2.29

package/.turbo/turbo-build.log

@@ -0,0 +1,2 @@
+
+$ tsc

package/.turbo/turbo-test.log

@@ -0,0 +1,13 @@
+$ vitest run
+
+ RUN  v3.2.4 /Users/vserifsaglam/work/memory-experiment/packages/cloud-voice
+
+ ✓ src/__tests__/browser.test.ts (3 tests) 7ms
+ ✓ src/__tests__/server.test.ts (2 tests) 7ms
+ ✓ src/__tests__/client.test.ts (13 tests) 55ms
+
+ Test Files  3 passed (3)
+      Tests  18 passed (18)
+   Start at  17:30:01
+   Duration  1.22s (transform 248ms, setup 0ms, collect 475ms, tests 69ms, environment 0ms, prepare 823ms)
+

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# @kognitivedev/cloud-voice
+
+## 0.2.29
+
+### Patch Changes
+
+- release
+
+- Updated dependencies []:
+  - @kognitivedev/client-core@0.2.29

package/README.md

@@ -0,0 +1,226 @@
+# @kognitivedev/cloud-voice
+
+Cloud Voice Agents SDK for Kognitive hosted `/api/cloud/voice/*` APIs.
+
+Create and publish agents in the Kognitive dashboard under **Voice > Agents**, then use the deploy page to generate origin-constrained `kvp_*` public embed keys. Browser code uses `kvp_*` keys only. Private `kog_*` project API keys stay server-side.
+
+## Server SDK
+
+```ts
+import { KognitiveCloudVoiceClient } from "@kognitivedev/cloud-voice";
+
+const voice = new KognitiveCloudVoiceClient({
+  baseUrl: process.env.KOGNITIVE_API_URL!,
+  apiKey: process.env.KOGNITIVE_API_KEY,
+});
+
+await voice.agents.management.create({
+  name: "Support",
+  slug: "support",
+  config: {
+    instructions: "Help customers over voice.",
+  },
+});
+
+await voice.agents.management.publish("support");
+
+// Idempotent create-or-update by slug. This is the preferred setup helper for
+// scripts, deploy hooks, and customer provisioning flows.
+const { agent, action } = await voice.agents.management.createOrUse("support", {
+  name: "Support",
+  publish: true,
+  config: {
+    instructions: "Help customers over voice.",
+    provider: "openai-realtime",
+    model: "gpt-realtime",
+    voice: "marin",
+    transport: "webrtc",
+    channels: {
+      web: true,
+      iframe: true,
+      script: true,
+      phone: true,
+      sip: false,
+      outbound: true,
+    },
+    humanization: {
+      openingMode: "auto",
+      openingStyle: "warm",
+      fillerStyle: "light",
+      backchannelFrequency: "low",
+      disfluency: "rare",
+      toolLatencyFillerMs: 700,
+    },
+    widget: {
+      title: "Talk to support",
+      subtitle: "Voice agent",
+      launcher: "button",
+      position: "bottom-right",
+    },
+  },
+});
+
+console.log(action, agent.slug);
+
+const session = await voice.sessions.create("support", {
+  userId: "user_123",
+  channel: "web",
+});
+```
+
+## Phone Calls
+
+Cloud Phone uses the same Cloud Voice agent/session/event model for PSTN/SIP channels. Configure provider credentials and assign numbers in the dashboard under **Voice > Phone Numbers**.
+
+Outbound calls are server-side and use private `kog_*` API keys:
+
+```ts
+const call = await voice.calls.create({
+  agent: "support",
+  fromNumberId: "number_123",
+  to: "+15551234567",
+});
+```
+
+Inbound calls are bound through phone numbers:
+
+```ts
+await voice.phone.numbers.create({
+  phoneNumber: "+15551234567",
+  inboundAgentSlug: "support",
+  inboundEnabled: true,
+  outboundEnabled: true,
+});
+```
+
+Live phone audio requires the Cloud Voice phone bridge:
+
+```bash
+cd apps/backend
+bun run phone:bridge
+```
+
+The bridge handles Twilio `wss://` Media Streams and reports readiness through the SDK:
+
+```ts
+const bridge = await voice.phone.bridge.health();
+console.log(bridge.online);
+```
+
+Phone-call tools execute through managed Cloud Voice tools and optional per-call server tool bridges. Browser SDK tools do not run for phone calls because there is no browser parent page during PSTN execution.
+
+## Browser widget
+
+Browser embeds use public `kvp_*` keys:
+
+```ts
+import { createVoiceWidget } from "@kognitivedev/cloud-voice/browser";
+
+createVoiceWidget({
+  baseUrl: "https://dashboard.example.com",
+  publicKey: "kvp_...",
+  agent: "support",
+  target: "#voice-agent",
+  style: {
+    theme: "minimal",
+    accentColor: "#111111",
+    surfaceColor: "#fffdf8",
+    radius: "12px",
+    shadow: "none",
+    align: "center",
+  },
+  iframe: {
+    width: "380",
+    height: "620",
+    style: { borderRadius: "16px" },
+  },
+});
+```
+
+## Client-side tools
+
+Customer SDK tools execute in the app that embeds the widget. The SDK sends only the tool manifest/schema to Cloud Voice; function code stays in the browser.
+
+```ts
+createVoiceWidget({
+  baseUrl: "https://dashboard.example.com",
+  publicKey: "kvp_...",
+  agent: "support",
+  target: "#voice-agent",
+  tools: {
+    lookup_order: {
+      description: "Look up an order in this app.",
+      inputSchema: {
+        type: "object",
+        properties: { orderNumber: { type: "string" } },
+        required: ["orderNumber"],
+      },
+      execute: async ({ orderNumber }) => fetchOrder(orderNumber),
+      render: ({ input, output, state }) => {
+        if (state === "input-available") return "Looking up order...";
+        return `Order ${input.orderNumber}: ${output.status}`;
+      },
+    },
+    managed_tool_ui: ({ output, state }) => {
+      if (state !== "output-available") return "Running...";
+      return `Managed tool returned ${JSON.stringify(output)}`;
+    },
+  },
+});
+```
+
+Tools with `execute` are registered as client tools and run in the customer page through the iframe bridge. Renderer-only shorthand is local UI for tools executed elsewhere, such as managed cloud tools configured on the agent.
+
+## Iframe embed
+
+```html
+<iframe
+  src="https://dashboard.example.com/voice/embed?publicKey=kvp_...&agent=support&theme=minimal&accent=%23111111&surface=%23fffdf8&radius=12px&shadow=none"
+  allow="microphone; autoplay"
+  width="380"
+  height="620"
+  style="border:0;border-radius:16px;max-width:100%;"
+></iframe>
+```
+
+## Style options
+
+`createVoiceWidget({ style })` and iframe query params support:
+
+- `theme`: `default`, `minimal`, `solid`, `glass`
+- `accentColor`, `backgroundColor`, `surfaceColor`, `textColor`, `mutedColor`
+- `width`, `padding`, `gap`, `radius`, `panelRadius`, `buttonRadius`, `orbSize`
+- `shadow`: `none`, `soft`, `strong`
+- `align`: `center`, `top`, `bottom`
+- `density`: `compact`, `comfortable`
+
+For iframe query params, use the shorter aliases where available: `accent`, `bg`, `surface`, `text`, and `muted`.
+
+## Phone server tools
+
+Custom phone tools are normal Kognitive server tools exposed to the phone bridge for the lifetime of a call. Define them once in the customer app, register them on the `Kognitive` instance, and provide a per-call tool bridge URL when creating or binding a phone call.
+
+```ts
+import { Kognitive } from "@kognitivedev/core";
+import { createTool } from "@kognitivedev/tools";
+import { z } from "zod";
+
+const lookupOrder = createTool({
+  id: "lookup_order",
+  description: "Look up an order by number",
+  inputSchema: z.object({
+    orderNumber: z.string(),
+  }),
+  execute: async ({ orderNumber }, ctx) => {
+    return db.orders.findByNumber(orderNumber);
+  },
+});
+
+export const kognitive = new Kognitive({
+  apiKey: process.env.KOGNITIVE_API_KEY,
+  baseUrl: process.env.KOGNITIVE_API_URL,
+  tools: [lookupOrder],
+});
+```
+
+Server tools work for inbound and outbound phone sessions when the call metadata includes the tool bridge URL. Browser SDK tools are separate: they run in the customer page and can render custom UI, but they cannot answer phone tool calls.

package/dist/browser.d.ts

@@ -0,0 +1,7 @@
+import type { CloudVoiceEmbedOptions } from "./types";
+export declare function mountIframe(options: CloudVoiceEmbedOptions): HTMLIFrameElement;
+export declare function createVoiceSession(options: CloudVoiceEmbedOptions): Promise<import("./types").CloudVoiceSessionBootstrap>;
+export declare function createVoiceWidget(options: CloudVoiceEmbedOptions): {
+    iframe: HTMLIFrameElement;
+    destroy(): void;
+};

package/dist/browser.js

@@ -0,0 +1,301 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mountIframe = mountIframe;
+exports.createVoiceSession = createVoiceSession;
+exports.createVoiceWidget = createVoiceWidget;
+const client_1 = require("./client");
+const MESSAGE_READY = "kognitive.cloudVoice.iframe.ready";
+const MESSAGE_REGISTER_TOOLS = "kognitive.cloudVoice.tools.register";
+const MESSAGE_TOOLS_REGISTERED = "kognitive.cloudVoice.tools.registered";
+const MESSAGE_TOOL_CALL = "kognitive.cloudVoice.tool.call";
+const MESSAGE_TOOL_RESULT = "kognitive.cloudVoice.tool.result";
+const MESSAGE_TOOL_STATE = "kognitive.cloudVoice.tool.state";
+const iframeCleanups = new WeakMap();
+function resolveTarget(target) {
+    if (target instanceof HTMLElement)
+        return target;
+    if (typeof target === "string") {
+        const element = document.querySelector(target);
+        if (element instanceof HTMLElement)
+            return element;
+    }
+    return document.body;
+}
+function appendStyleParams(params, style) {
+    if (!style)
+        return;
+    const entries = [
+        ["theme", style.theme],
+        ["accent", style.accentColor],
+        ["bg", style.backgroundColor],
+        ["surface", style.surfaceColor],
+        ["text", style.textColor],
+        ["muted", style.mutedColor],
+        ["width", style.width],
+        ["padding", style.padding],
+        ["gap", style.gap],
+        ["radius", style.radius],
+        ["panelRadius", style.panelRadius],
+        ["buttonRadius", style.buttonRadius],
+        ["orbSize", style.orbSize],
+        ["shadow", style.shadow],
+        ["align", style.align],
+        ["density", style.density],
+    ];
+    for (const [key, value] of entries) {
+        if (value)
+            params.set(key, value);
+    }
+}
+function isToolDefinition(value) {
+    return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+function getToolRenderer(tool) {
+    if (!tool)
+        return undefined;
+    if (typeof tool === "function")
+        return tool;
+    return typeof tool.render === "function" ? tool.render : undefined;
+}
+function getToolExecutor(tool) {
+    if (!tool || !isToolDefinition(tool))
+        return undefined;
+    return typeof tool.execute === "function" ? tool.execute : undefined;
+}
+function getExecutableToolManifests(tools) {
+    if (!tools)
+        return [];
+    return Object.entries(tools)
+        .filter(([, tool]) => Boolean(getToolExecutor(tool)))
+        .map(([id, tool]) => {
+        var _a, _b, _c, _d;
+        const definition = isToolDefinition(tool) ? tool : {};
+        return {
+            id,
+            name: (_a = definition.name) !== null && _a !== void 0 ? _a : id,
+            description: (_c = (_b = definition.description) !== null && _b !== void 0 ? _b : definition.name) !== null && _c !== void 0 ? _c : id,
+            inputSchema: (_d = definition.inputSchema) !== null && _d !== void 0 ? _d : { type: "object", additionalProperties: true },
+        };
+    });
+}
+function getIframeTargetOrigin(src) {
+    try {
+        return new URL(src).origin;
+    }
+    catch (_a) {
+        return "*";
+    }
+}
+function isMessage(value) {
+    return Boolean(value && typeof value === "object" && "type" in value);
+}
+function escapeSelector(value) {
+    return typeof CSS !== "undefined" && typeof CSS.escape === "function"
+        ? CSS.escape(value)
+        : value.replace(/["\\]/g, "\\$&");
+}
+function createToolRoot(options, target) {
+    if (!options.tools)
+        return { root: null, owned: false };
+    const explicitTarget = options.toolTarget ? resolveTarget(options.toolTarget) : null;
+    const root = explicitTarget !== null && explicitTarget !== void 0 ? explicitTarget : document.createElement("div");
+    root.className = [root.className, "kognitive-cloud-voice-tools"].filter(Boolean).join(" ");
+    if (!explicitTarget) {
+        target.appendChild(root);
+    }
+    return { root, owned: !explicitTarget };
+}
+function renderToolState(input) {
+    var _a, _b;
+    (_a = input.onToolState) === null || _a === void 0 ? void 0 : _a.call(input, input.state);
+    const renderer = getToolRenderer((_b = input.tools) === null || _b === void 0 ? void 0 : _b[input.state.toolName]);
+    if (!renderer || !input.root)
+        return;
+    const rendered = renderer(input.state);
+    const id = input.state.toolCallId || input.state.toolName;
+    let mount = input.root.querySelector(`[data-kognitive-tool-call-id="${escapeSelector(id)}"]`);
+    if (!mount) {
+        mount = document.createElement("div");
+        mount.dataset.kognitiveToolCallId = id;
+        mount.dataset.kognitiveToolName = input.state.toolName;
+        input.root.appendChild(mount);
+    }
+    mount.dataset.kognitiveToolState = input.state.state;
+    if (typeof Node !== "undefined" && rendered instanceof Node) {
+        mount.replaceChildren(rendered);
+    }
+    else if (typeof rendered === "string") {
+        mount.textContent = rendered;
+    }
+    else if (rendered == null) {
+        mount.replaceChildren();
+    }
+    else {
+        mount.dispatchEvent(new CustomEvent("kognitive-cloud-voice-render", {
+            detail: { rendered, state: input.state },
+        }));
+    }
+}
+function mountIframe(options) {
+    var _a, _b, _c, _d, _e, _f, _g, _h;
+    const target = resolveTarget(options.target);
+    const iframe = document.createElement("iframe");
+    const clientTools = getExecutableToolManifests(options.tools);
+    const params = new URLSearchParams(Object.assign(Object.assign(Object.assign({ publicKey: options.publicKey, agent: options.agent }, (options.userId ? { userId: options.userId } : {})), (options.parameters ? { parameters: JSON.stringify(options.parameters) } : {})), (options.tools ? { sdk: "1" } : {})));
+    appendStyleParams(params, options.style);
+    iframe.src = `${options.baseUrl.replace(/\/$/, "")}/voice/embed?${params.toString()}`;
+    iframe.title = (_b = (_a = options.iframe) === null || _a === void 0 ? void 0 : _a.title) !== null && _b !== void 0 ? _b : "Kognitive voice agent";
+    iframe.width = (_d = (_c = options.iframe) === null || _c === void 0 ? void 0 : _c.width) !== null && _d !== void 0 ? _d : "380";
+    iframe.height = (_f = (_e = options.iframe) === null || _e === void 0 ? void 0 : _e.height) !== null && _f !== void 0 ? _f : "620";
+    iframe.setAttribute("allow", "microphone; autoplay");
+    iframe.style.border = "0";
+    iframe.style.maxWidth = "100%";
+    if ((_g = options.style) === null || _g === void 0 ? void 0 : _g.width)
+        iframe.style.width = options.style.width;
+    if ((_h = options.iframe) === null || _h === void 0 ? void 0 : _h.style)
+        Object.assign(iframe.style, options.iframe.style);
+    const toolRoot = createToolRoot(options, target);
+    const targetOrigin = getIframeTargetOrigin(iframe.src);
+    function postToolRegistration() {
+        var _a;
+        (_a = iframe.contentWindow) === null || _a === void 0 ? void 0 : _a.postMessage({
+            type: MESSAGE_REGISTER_TOOLS,
+            tools: clientTools,
+        }, targetOrigin);
+    }
+    function handleMessage(event) {
+        var _a, _b, _c;
+        if (event.source !== iframe.contentWindow || !isMessage(event.data))
+            return;
+        if (event.data.type === MESSAGE_READY) {
+            postToolRegistration();
+            return;
+        }
+        if (event.data.type === MESSAGE_TOOL_STATE) {
+            const message = event.data;
+            renderToolState({
+                root: toolRoot.root,
+                tools: options.tools,
+                onToolState: options.onToolState,
+                state: {
+                    toolName: message.toolName,
+                    toolCallId: (_a = message.toolCallId) !== null && _a !== void 0 ? _a : message.toolName,
+                    input: message.input,
+                    output: message.output,
+                    error: message.error,
+                    state: message.state,
+                },
+            });
+            return;
+        }
+        if (event.data.type !== MESSAGE_TOOL_CALL)
+            return;
+        const message = event.data;
+        const tool = (_b = options.tools) === null || _b === void 0 ? void 0 : _b[message.toolName];
+        const execute = getToolExecutor(tool);
+        const toolCallId = (_c = message.toolCallId) !== null && _c !== void 0 ? _c : message.requestId;
+        void (async () => {
+            var _a, _b, _c, _d, _e;
+            renderToolState({
+                root: toolRoot.root,
+                tools: options.tools,
+                onToolState: options.onToolState,
+                state: {
+                    toolName: message.toolName,
+                    toolCallId,
+                    input: message.args,
+                    state: "input-available",
+                },
+            });
+            if (!execute) {
+                (_a = iframe.contentWindow) === null || _a === void 0 ? void 0 : _a.postMessage({
+                    type: MESSAGE_TOOL_RESULT,
+                    requestId: message.requestId,
+                    error: `No client executor registered for ${message.toolName}`,
+                }, targetOrigin);
+                return;
+            }
+            try {
+                const result = await execute(message.args, {
+                    toolName: message.toolName,
+                    toolCallId,
+                    callId: (_b = message.context) === null || _b === void 0 ? void 0 : _b.callId,
+                    sessionId: (_c = message.context) === null || _c === void 0 ? void 0 : _c.sessionId,
+                });
+                renderToolState({
+                    root: toolRoot.root,
+                    tools: options.tools,
+                    onToolState: options.onToolState,
+                    state: {
+                        toolName: message.toolName,
+                        toolCallId,
+                        input: message.args,
+                        output: result,
+                        state: "output-available",
+                    },
+                });
+                (_d = iframe.contentWindow) === null || _d === void 0 ? void 0 : _d.postMessage({
+                    type: MESSAGE_TOOL_RESULT,
+                    requestId: message.requestId,
+                    result,
+                }, targetOrigin);
+            }
+            catch (error) {
+                const messageText = error instanceof Error ? error.message : "Client tool failed";
+                renderToolState({
+                    root: toolRoot.root,
+                    tools: options.tools,
+                    onToolState: options.onToolState,
+                    state: {
+                        toolName: message.toolName,
+                        toolCallId,
+                        input: message.args,
+                        error: messageText,
+                        state: "error",
+                    },
+                });
+                (_e = iframe.contentWindow) === null || _e === void 0 ? void 0 : _e.postMessage({
+                    type: MESSAGE_TOOL_RESULT,
+                    requestId: message.requestId,
+                    error: messageText,
+                }, targetOrigin);
+            }
+        })();
+    }
+    window.addEventListener("message", handleMessage);
+    iframe.addEventListener("load", postToolRegistration);
+    iframeCleanups.set(iframe, () => {
+        var _a;
+        window.removeEventListener("message", handleMessage);
+        iframe.removeEventListener("load", postToolRegistration);
+        if (toolRoot.owned)
+            (_a = toolRoot.root) === null || _a === void 0 ? void 0 : _a.remove();
+    });
+    target.appendChild(iframe);
+    return iframe;
+}
+function createVoiceSession(options) {
+    const client = new client_1.KognitiveCloudVoiceEmbedClient({
+        baseUrl: options.baseUrl,
+        publicKey: options.publicKey,
+    });
+    return client.createSession({
+        agentSlug: options.agent,
+        channel: "script",
+        userId: options.userId,
+        parameters: options.parameters,
+        clientTools: getExecutableToolManifests(options.tools),
+    });
+}
+function createVoiceWidget(options) {
+    const iframe = mountIframe(options);
+    return {
+        iframe,
+        destroy() {
+            var _a;
+            (_a = iframeCleanups.get(iframe)) === null || _a === void 0 ? void 0 : _a();
+            iframeCleanups.delete(iframe);
+            iframe.remove();
+        },
+    };
+}