@kognitivedev/cloud-voice 0.2.29

package/src/index.ts

@@ -0,0 +1,100 @@
+export { KognitiveCloudVoiceClient, KognitiveCloudVoiceEmbedClient } from "./client";
+export { createCloudVoiceTools, syncCloudVoiceCodeDefinedTools } from "./server";
+export { createVoiceSession, createVoiceWidget, mountIframe } from "./browser";
+export { readSSEStream } from "./sse";
+export type { ParsedSSEEvent } from "./sse";
+export type {
+    CloudVoiceAgentConfig,
+    CloudVoiceAgentConfigInput,
+    CloudVoiceAgentMetadata,
+    CloudVoiceAgentRecord,
+    CloudVoiceAgentStatus,
+    CloudVoiceChannel,
+    CloudVoiceChannelSettings,
+    CloudVoiceClientTool,
+    CloudVoiceClientConfig,
+    CloudVoiceClientToolDefinition,
+    CloudVoiceClientToolExecuteContext,
+    CloudVoiceClientToolManifest,
+    CloudVoiceClientToolRenderContext,
+    CloudVoiceClientToolRenderer,
+    CloudVoiceClientTools,
+    CloudVoiceClientToolState,
+    CloudVoiceCustomVoiceConsent,
+    CloudVoiceCustomVoiceRecord,
+    CloudVoiceCustomVoiceSource,
+    CloudVoiceCustomVoiceVerificationStatus,
+    CloudVoiceHumanizationConfig,
+    CloudVoiceSipConfig,
+    CloudVoiceTelephonyDestination,
+    CloudVoiceTelephonyProvider,
+    CloudVoiceTransferDestination,
+    CloudVoiceTransferMode,
+    CloudVoiceTransferPolicy,
+    CloudVoiceFlowEdge,
+    CloudVoiceFlowGraph,
+    CloudVoiceFlowNode,
+    CloudVoiceFlowNodeOutput,
+    CloudVoiceFlowNodeType,
+    CloudVoiceNodeModelSettings,
+    CloudVoiceNodeVoiceSettings,
+    CloudVoiceParameterDefinition,
+    CloudVoiceParameterPreset,
+    CloudVoiceParameterSource,
+    CloudVoiceParameterType,
+    CloudVoiceParameterValueMap,
+    CloudVoiceSpeechConfig,
+    CloudVoiceEmbedConfig,
+    CloudVoiceEmbedOptions,
+    CloudVoiceCallLegRecord,
+    CloudVoiceCallOutcome,
+    CloudVoiceCallOutcomeSource,
+    CloudVoiceCallStatusChange,
+    CloudVoiceCallWaitOptions,
+    CloudVoiceCallWaitResult,
+    CloudVoiceHandoffAction,
+    CloudVoiceHandoffMode,
+    CloudVoiceHandoffRecord,
+    CloudVoiceHandoffStatus,
+    CloudVoiceCallJudgeResult,
+    CloudVoiceListenTokenResult,
+    CloudVoiceLiveCallRecord,
+    CloudVoiceLiveCallHandoffState,
+    CloudVoiceLiveCallTranscriptMessage,
+    CloudVoicePhoneBridgeHealth,
+    CloudVoicePhoneConnectionRecord,
+    CloudVoicePhoneNumberRecord,
+    CloudVoiceSipDiagnostics,
+    CloudVoiceRecordingAsset,
+    CloudVoiceRecordingAssetKind,
+    CloudVoiceSessionBootstrap,
+    CloudVoiceSessionEventRecord,
+    CloudVoiceSessionRecord,
+    CloudVoiceSessionStatus,
+    CloudVoiceProvider,
+    CloudVoiceToolType,
+    CloudVoiceTransport,
+    CloudVoiceToolBinding,
+    CloudVoiceToolCatalog,
+    CloudVoiceToolCatalogEntry,
+    CloudVoiceToolCatalogSource,
+    CloudVoiceWidgetConfig,
+    CreateCloudVoiceAgentInput,
+    CloneCloudVoiceCustomVoiceInput,
+    ImportCloudVoiceCustomVoiceInput,
+    AcceptCloudVoiceHandoffInput,
+    CancelCloudVoiceHandoffInput,
+    CreateCloudVoiceHandoffInput,
+    CreateCloudVoiceOutboundCallInput,
+    CreateCloudVoicePhoneConnectionInput,
+    CreateCloudVoicePhoneNumberInput,
+    CreateCloudVoiceSessionInput,
+    LogLevel,
+    UpdateCloudVoiceAgentInput,
+    UpdateCloudVoiceCustomVoiceInput,
+    UpdateCloudVoicePhoneNumberInput,
+    SyncCloudVoiceToolCatalogInput,
+    UseCloudVoiceAgentInput,
+    UseCloudVoiceAgentResult,
+    UseCloudVoiceAgentAction,
+} from "./types";

package/src/server.ts

@@ -0,0 +1,140 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { KognitiveCloudVoiceClient } from "./client";
+import type { CloudVoiceToolCatalog, SyncCloudVoiceToolCatalogInput } from "./types";
+
+export interface CloudVoiceToolRequest<TInput = unknown> {
+    type: "cloud_voice.tool.execute";
+    toolCallId: string;
+    toolId: string;
+    toolName?: string;
+    input: TInput;
+    session: {
+        id: string;
+        sessionId: string;
+        agentSlug: string;
+        channel: string;
+        userId: string;
+        resourceId: Record<string, unknown>;
+        parameters: Record<string, unknown>;
+        metadata: Record<string, unknown>;
+    };
+}
+
+export interface CloudVoiceToolContext<TInput = unknown> {
+    request: CloudVoiceToolRequest<TInput>;
+    abortSignal: AbortSignal;
+    toolCallId: string;
+    session: CloudVoiceToolRequest<TInput>["session"];
+}
+
+export interface CloudVoiceToolDefinition<TInput = unknown, TOutput = unknown> {
+    description?: string;
+    input?: { parse: (value: unknown) => TInput };
+    execute: (input: TInput, context: CloudVoiceToolContext<TInput>) => Promise<TOutput> | TOutput;
+}
+
+export type CloudVoiceToolMap = Record<string, CloudVoiceToolDefinition<any, any> | ((input: any, context: CloudVoiceToolContext<any>) => unknown)>;
+
+export interface CreateCloudVoiceToolsOptions<TTools extends CloudVoiceToolMap> {
+    tools: TTools;
+    secret?: string;
+    signatureToleranceMs?: number;
+}
+
+function json(data: unknown, status = 200) {
+    return new Response(JSON.stringify(data), {
+        status,
+        headers: { "Content-Type": "application/json" },
+    });
+}
+
+function verifySignature(input: { body: string; timestamp: string | null; signature: string | null; secret?: string; toleranceMs: number }) {
+    if (!input.secret) return;
+    if (!input.timestamp || !input.signature?.startsWith("sha256=")) {
+        throw new Error("Missing Kognitive signature");
+    }
+    const timestampMs = Date.parse(input.timestamp);
+    if (!Number.isFinite(timestampMs) || Math.abs(Date.now() - timestampMs) > input.toleranceMs) {
+        throw new Error("Kognitive signature timestamp is outside the allowed window");
+    }
+    const expected = `sha256=${createHmac("sha256", input.secret).update(`${input.timestamp}.${input.body}`).digest("hex")}`;
+    const actualBuffer = Buffer.from(input.signature);
+    const expectedBuffer = Buffer.from(expected);
+    if (actualBuffer.length !== expectedBuffer.length || !timingSafeEqual(actualBuffer, expectedBuffer)) {
+        throw new Error("Invalid Kognitive signature");
+    }
+}
+
+function resolveTool<TTools extends CloudVoiceToolMap>(tools: TTools, toolId: string) {
+    return tools[toolId] ?? tools[toolId.replace(/-/g, "_")] ?? tools[toolId.replace(/_/g, "-")];
+}
+
+export function createCloudVoiceTools<TTools extends CloudVoiceToolMap>(options: CreateCloudVoiceToolsOptions<TTools>) {
+    return async function handleCloudVoiceTool(request: Request): Promise<Response> {
+        const rawBody = await request.text();
+        try {
+            verifySignature({
+                body: rawBody,
+                timestamp: request.headers.get("x-kognitive-timestamp"),
+                signature: request.headers.get("x-kognitive-signature"),
+                secret: options.secret,
+                toleranceMs: options.signatureToleranceMs ?? 5 * 60 * 1000,
+            });
+
+            const payload = JSON.parse(rawBody || "{}") as CloudVoiceToolRequest;
+            const toolId = payload.toolId || payload.toolName || "";
+            const tool = resolveTool(options.tools, toolId);
+            if (!tool) {
+                return json({ error: `Unknown Cloud Voice tool: ${toolId}` }, 404);
+            }
+
+            const definition = typeof tool === "function" ? { execute: tool } : tool;
+            const input = definition.input?.parse ? definition.input.parse(payload.input) : payload.input;
+            const result = await definition.execute(input, {
+                request: payload,
+                abortSignal: request.signal,
+                toolCallId: payload.toolCallId,
+                session: payload.session,
+            });
+            return json({ result });
+        } catch (error) {
+            return json({ error: error instanceof Error ? error.message : "Cloud Voice tool failed" }, 400);
+        }
+    };
+}
+
+export async function syncCloudVoiceCodeDefinedTools(input: {
+    kognitive: { getToolMetadataList: () => Array<{ id: string; description?: string; inputSchema?: unknown; requireApproval?: boolean }> };
+    sourceKey: string;
+    bridgeUrl: string;
+    name?: string;
+    bridgeAuthorization?: string | null;
+    bridgeToken?: string | null;
+    metadata?: Record<string, unknown>;
+    client?: KognitiveCloudVoiceClient;
+    baseUrl?: string;
+    apiKey?: string;
+}): Promise<CloudVoiceToolCatalog> {
+    const client = input.client ?? new KognitiveCloudVoiceClient({
+        baseUrl: input.baseUrl ?? process.env.COGNITIVE_API_URL ?? "http://localhost:3001",
+        apiKey: input.apiKey ?? process.env.COGNITIVE_API_KEY,
+    });
+    const payload: SyncCloudVoiceToolCatalogInput = {
+        sourceKey: input.sourceKey,
+        name: input.name,
+        bridgeUrl: input.bridgeUrl,
+        bridgeAuthorization: input.bridgeAuthorization,
+        bridgeToken: input.bridgeToken,
+        metadata: input.metadata,
+        tools: input.kognitive.getToolMetadataList().map((tool) => ({
+            id: tool.id,
+            name: tool.id,
+            description: tool.description,
+            inputSchema: tool.inputSchema && typeof tool.inputSchema === "object" && !Array.isArray(tool.inputSchema)
+                ? tool.inputSchema as Record<string, unknown>
+                : { type: "object", additionalProperties: true },
+            requireApproval: Boolean(tool.requireApproval),
+        })),
+    };
+    return client.tools.catalog.sync(payload);
+}

package/src/sse.ts

@@ -0,0 +1,57 @@
+export interface ParsedSSEEvent {
+    event?: string;
+    data: string;
+    id?: string;
+    retry?: number;
+}
+
+export async function* readSSEStream(stream: ReadableStream<Uint8Array>): AsyncGenerator<ParsedSSEEvent> {
+    const reader = stream.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    let event = "";
+    let data: string[] = [];
+    let id: string | undefined;
+    let retry: number | undefined;
+
+    function flush(): ParsedSSEEvent | null {
+        if (!event && data.length === 0 && !id && retry === undefined) return null;
+        const frame = {
+            event: event || undefined,
+            data: data.join("\n"),
+            id,
+            retry,
+        };
+        event = "";
+        data = [];
+        id = undefined;
+        retry = undefined;
+        return frame;
+    }
+
+    while (true) {
+        const { value, done } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split(/\r\n|\r|\n/);
+        buffer = lines.pop() ?? "";
+        for (const line of lines) {
+            if (line === "") {
+                const frame = flush();
+                if (frame) yield frame;
+                continue;
+            }
+            if (line.startsWith(":")) continue;
+            const separator = line.indexOf(":");
+            const field = separator === -1 ? line : line.slice(0, separator);
+            const rawValue = separator === -1 ? "" : line.slice(separator + 1).replace(/^ /, "");
+            if (field === "event") event = rawValue;
+            if (field === "data") data.push(rawValue);
+            if (field === "id") id = rawValue;
+            if (field === "retry") retry = Number(rawValue);
+        }
+    }
+    const tail = flush();
+    if (tail) yield tail;
+}
+