@kognitivedev/cloud-voice 0.2.29

package/src/browser.ts

@@ -0,0 +1,342 @@
+import { KognitiveCloudVoiceEmbedClient } from "./client";
+import type {
+    CloudVoiceClientTool,
+    CloudVoiceClientToolDefinition,
+    CloudVoiceClientToolManifest,
+    CloudVoiceClientToolRenderContext,
+    CloudVoiceClientToolRenderer,
+    CloudVoiceClientTools,
+    CloudVoiceEmbedOptions,
+} from "./types";
+
+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<HTMLIFrameElement, () => void>();
+
+type ToolCallMessage = {
+    type: typeof MESSAGE_TOOL_CALL;
+    requestId: string;
+    toolName: string;
+    toolCallId?: string;
+    args?: unknown;
+    context?: {
+        callId?: string;
+        sessionId?: string;
+    };
+};
+
+type ToolResultMessage = {
+    type: typeof MESSAGE_TOOL_RESULT;
+    requestId: string;
+    result?: unknown;
+    error?: string;
+};
+
+type ToolStateMessage = {
+    type: typeof MESSAGE_TOOL_STATE;
+    toolName: string;
+    toolCallId?: string;
+    input?: unknown;
+    output?: unknown;
+    error?: string;
+    state: CloudVoiceClientToolRenderContext["state"];
+};
+
+function resolveTarget(target?: HTMLElement | string): HTMLElement {
+    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: URLSearchParams, style: CloudVoiceEmbedOptions["style"] | undefined) {
+    if (!style) return;
+    const entries: Array<[string, string | undefined]> = [
+        ["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: CloudVoiceClientTool): value is CloudVoiceClientToolDefinition {
+    return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+
+function getToolRenderer(tool: CloudVoiceClientTool | undefined): CloudVoiceClientToolRenderer | undefined {
+    if (!tool) return undefined;
+    if (typeof tool === "function") return tool;
+    return typeof tool.render === "function" ? tool.render : undefined;
+}
+
+function getToolExecutor(tool: CloudVoiceClientTool | undefined): CloudVoiceClientToolDefinition["execute"] | undefined {
+    if (!tool || !isToolDefinition(tool)) return undefined;
+    return typeof tool.execute === "function" ? tool.execute : undefined;
+}
+
+function getExecutableToolManifests(tools: CloudVoiceClientTools | undefined): CloudVoiceClientToolManifest[] {
+    if (!tools) return [];
+    return Object.entries(tools)
+        .filter(([, tool]) => Boolean(getToolExecutor(tool)))
+        .map(([id, tool]) => {
+            const definition = isToolDefinition(tool) ? tool : {};
+            return {
+                id,
+                name: definition.name ?? id,
+                description: definition.description ?? definition.name ?? id,
+                inputSchema: definition.inputSchema ?? { type: "object", additionalProperties: true },
+            };
+        });
+}
+
+function getIframeTargetOrigin(src: string) {
+    try {
+        return new URL(src).origin;
+    } catch {
+        return "*";
+    }
+}
+
+function isMessage(value: unknown): value is { type?: unknown } {
+    return Boolean(value && typeof value === "object" && "type" in value);
+}
+
+function escapeSelector(value: string) {
+    return typeof CSS !== "undefined" && typeof CSS.escape === "function"
+        ? CSS.escape(value)
+        : value.replace(/["\\]/g, "\\$&");
+}
+
+function createToolRoot(options: CloudVoiceEmbedOptions, target: HTMLElement) {
+    if (!options.tools) return { root: null, owned: false };
+    const explicitTarget = options.toolTarget ? resolveTarget(options.toolTarget) : null;
+    const root = 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: {
+    root: HTMLElement | null;
+    tools?: CloudVoiceClientTools;
+    state: CloudVoiceClientToolRenderContext;
+    onToolState?: (state: CloudVoiceClientToolRenderContext) => void;
+}) {
+    input.onToolState?.(input.state);
+    const renderer = getToolRenderer(input.tools?.[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)}"]`) as HTMLElement | null;
+    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 },
+        }));
+    }
+}
+
+export function mountIframe(options: CloudVoiceEmbedOptions): HTMLIFrameElement {
+    const target = resolveTarget(options.target);
+    const iframe = document.createElement("iframe");
+    const clientTools = getExecutableToolManifests(options.tools);
+    const params = new URLSearchParams({
+        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 = options.iframe?.title ?? "Kognitive voice agent";
+    iframe.width = options.iframe?.width ?? "380";
+    iframe.height = options.iframe?.height ?? "620";
+    iframe.setAttribute("allow", "microphone; autoplay");
+    iframe.style.border = "0";
+    iframe.style.maxWidth = "100%";
+    if (options.style?.width) iframe.style.width = options.style.width;
+    if (options.iframe?.style) Object.assign(iframe.style, options.iframe.style);
+
+    const toolRoot = createToolRoot(options, target);
+    const targetOrigin = getIframeTargetOrigin(iframe.src);
+
+    function postToolRegistration() {
+        iframe.contentWindow?.postMessage({
+            type: MESSAGE_REGISTER_TOOLS,
+            tools: clientTools,
+        }, targetOrigin);
+    }
+
+    function handleMessage(event: MessageEvent) {
+        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 as ToolStateMessage;
+            renderToolState({
+                root: toolRoot.root,
+                tools: options.tools,
+                onToolState: options.onToolState,
+                state: {
+                    toolName: message.toolName,
+                    toolCallId: message.toolCallId ?? 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 as ToolCallMessage;
+        const tool = options.tools?.[message.toolName];
+        const execute = getToolExecutor(tool);
+        const toolCallId = message.toolCallId ?? message.requestId;
+
+        void (async () => {
+            renderToolState({
+                root: toolRoot.root,
+                tools: options.tools,
+                onToolState: options.onToolState,
+                state: {
+                    toolName: message.toolName,
+                    toolCallId,
+                    input: message.args,
+                    state: "input-available",
+                },
+            });
+
+            if (!execute) {
+                iframe.contentWindow?.postMessage({
+                    type: MESSAGE_TOOL_RESULT,
+                    requestId: message.requestId,
+                    error: `No client executor registered for ${message.toolName}`,
+                } satisfies ToolResultMessage, targetOrigin);
+                return;
+            }
+
+            try {
+                const result = await execute(message.args, {
+                    toolName: message.toolName,
+                    toolCallId,
+                    callId: message.context?.callId,
+                    sessionId: message.context?.sessionId,
+                });
+                renderToolState({
+                    root: toolRoot.root,
+                    tools: options.tools,
+                    onToolState: options.onToolState,
+                    state: {
+                        toolName: message.toolName,
+                        toolCallId,
+                        input: message.args,
+                        output: result,
+                        state: "output-available",
+                    },
+                });
+                iframe.contentWindow?.postMessage({
+                    type: MESSAGE_TOOL_RESULT,
+                    requestId: message.requestId,
+                    result,
+                } satisfies ToolResultMessage, 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",
+                    },
+                });
+                iframe.contentWindow?.postMessage({
+                    type: MESSAGE_TOOL_RESULT,
+                    requestId: message.requestId,
+                    error: messageText,
+                } satisfies ToolResultMessage, targetOrigin);
+            }
+        })();
+    }
+
+    window.addEventListener("message", handleMessage);
+    iframe.addEventListener("load", postToolRegistration);
+    iframeCleanups.set(iframe, () => {
+        window.removeEventListener("message", handleMessage);
+        iframe.removeEventListener("load", postToolRegistration);
+        if (toolRoot.owned) toolRoot.root?.remove();
+    });
+    target.appendChild(iframe);
+    return iframe;
+}
+
+export function createVoiceSession(options: CloudVoiceEmbedOptions) {
+    const client = new 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),
+    });
+}
+
+export function createVoiceWidget(options: CloudVoiceEmbedOptions) {
+    const iframe = mountIframe(options);
+    return {
+        iframe,
+        destroy() {
+            iframeCleanups.get(iframe)?.();
+            iframeCleanups.delete(iframe);
+            iframe.remove();
+        },
+    };
+}