@kognitivedev/backend-cloud 0.2.29

package/src/__tests__/phone-control.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, it } from "vitest";
+import { executeCloudVoicePhoneControlTool, executeCloudVoiceSipTransferTool } from "../index";
+
+describe("@kognitivedev/backend-cloud phone control", () => {
+    it("executes hangup through the matching adapter", async () => {
+        await expect(executeCloudVoicePhoneControlTool({
+            toolId: "hang_up_call",
+            provider: "twilio",
+            providerCallId: "CA123",
+            args: { reason: "caller said goodbye" },
+            adapters: [{
+                provider: "twilio",
+                async hangUpCall(input) {
+                    return {
+                        provider: "twilio",
+                        providerCallId: input.providerCallId,
+                        status: "completed",
+                        raw: { reason: input.reason },
+                    };
+                },
+            }],
+        })).resolves.toEqual({
+            result: {
+                ok: true,
+                provider: "twilio",
+                providerCallId: "CA123",
+                status: "completed",
+                reason: "caller said goodbye",
+            },
+            raw: { reason: "caller said goodbye" },
+        });
+    });
+
+    it("rejects unknown phone control tools", async () => {
+        await expect(executeCloudVoicePhoneControlTool({
+            toolId: "lookup_order",
+            provider: "twilio",
+            providerCallId: "CA123",
+            args: {},
+            adapters: [],
+        })).rejects.toThrow("Unknown Cloud Voice phone control tool");
+    });
+
+    it("rejects unsupported providers", async () => {
+        await expect(executeCloudVoicePhoneControlTool({
+            toolId: "hang_up_call",
+            provider: "sip-provider",
+            providerCallId: "CALL123",
+            args: {},
+            adapters: {
+                twilio: {
+                    provider: "twilio",
+                    async hangUpCall() {
+                        throw new Error("not used");
+                    },
+                },
+            },
+        })).rejects.toThrow("not supported for provider");
+    });
+
+    it("executes SIP transfer through the matching adapter", async () => {
+        await expect(executeCloudVoiceSipTransferTool({
+            toolId: "sip_transfer_call",
+            provider: "telnyx",
+            providerCallId: "call_1",
+            args: {
+                destinationId: "support_queue",
+                mode: "warm",
+                reason: "caller asked for a human",
+            },
+            resolveDestination: async (destinationId) => destinationId === "support_queue"
+                ? {
+                    destination: { type: "sip_uri", uri: "sip:support@example.com" },
+                    policy: { mode: "warm", timeoutSeconds: 30 },
+                }
+                : null,
+            adapters: [{
+                provider: "telnyx",
+                async transferCall(input) {
+                    return {
+                        provider: "telnyx",
+                        providerCallId: input.providerCallId,
+                        status: "active",
+                        destination: input.destination,
+                        mode: input.mode ?? "blind",
+                        transferId: "transfer_1",
+                        raw: { reason: input.reason },
+                    };
+                },
+            }],
+        })).resolves.toEqual({
+            result: {
+                ok: true,
+                provider: "telnyx",
+                providerCallId: "call_1",
+                status: "active",
+                transferId: "transfer_1",
+                mode: "warm",
+                destinationId: "support_queue",
+                reason: "caller asked for a human",
+            },
+            raw: { reason: "caller asked for a human" },
+        });
+    });
+});

package/src/cloud-voice-parameters.ts

@@ -0,0 +1,236 @@
+import type {
+    CloudVoiceAgentConfig,
+    CloudVoiceParameterDefinition,
+    CloudVoiceParameterResolutionMode,
+    CloudVoiceParameterResolutionResult,
+    CloudVoiceParameterValueMap,
+} from "./types";
+import { getRecord, getString } from "./utils";
+
+export const CLOUD_VOICE_PREDEFINED_PARAMETERS: CloudVoiceParameterDefinition[] = [
+    { key: "user_id", label: "User ID", type: "string", source: "system", preset: "user_id", description: "Resolved user identifier for the voice session." },
+    { key: "session_id", label: "Session ID", type: "string", source: "system", preset: "session_id", description: "Public Cloud Voice session id." },
+    { key: "agent_slug", label: "Agent slug", type: "string", source: "system", preset: "agent_slug", description: "Slug of the selected voice agent." },
+    { key: "channel", label: "Channel", type: "string", source: "system", preset: "channel", description: "Run channel such as web, script, phone, or outbound." },
+    { key: "phone", label: "Phone", type: "phone", source: "call", preset: "phone", description: "Primary phone number for the caller when available." },
+    { key: "caller_phone", label: "Caller phone", type: "phone", source: "call", preset: "caller_phone", description: "Caller phone number when available." },
+    { key: "from_phone", label: "From phone", type: "phone", source: "call", preset: "from_phone", description: "Originating phone number when available." },
+    { key: "to_phone", label: "To phone", type: "phone", source: "call", preset: "to_phone", description: "Destination phone number when available." },
+    { key: "provider", label: "Telephony provider", type: "string", source: "call", preset: "provider", description: "Phone provider when available." },
+    { key: "provider_call_id", label: "Provider call ID", type: "string", source: "call", preset: "provider_call_id", description: "Provider call id when available." },
+    { key: "call_direction", label: "Call direction", type: "string", source: "call", preset: "call_direction", description: "Inbound or outbound direction when available." },
+    { key: "phone_number_id", label: "Phone number ID", type: "string", source: "call", preset: "phone_number_id", description: "Configured Cloud Voice phone number id when available." },
+    { key: "embed_origin", label: "Embed origin", type: "string", source: "session", preset: "embed_origin", description: "Embed origin for iframe/script starts when available." },
+];
+
+const RESERVED_TEMPLATE_KEYS = [
+    "session_messages",
+    "tools",
+    "voice_context",
+    "project_id",
+    "workflow_run_id",
+    "workflow_name",
+    "workflow_input",
+    "workflow_output",
+];
+const RESERVED_PARAMETER_KEYS = new Set([
+    ...CLOUD_VOICE_PREDEFINED_PARAMETERS.map((parameter) => parameter.key),
+    ...RESERVED_TEMPLATE_KEYS,
+]);
+const VALID_PARAMETER_TYPES = new Set(["string", "number", "boolean", "json", "phone", "email"]);
+
+function normalizeParameterKey(value: unknown) {
+    return getString(value, "")
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9_]+/g, "_")
+        .replace(/^_+|_+$/g, "");
+}
+
+function normalizeParameterType(value: unknown): CloudVoiceParameterDefinition["type"] {
+    return VALID_PARAMETER_TYPES.has(String(value)) ? value as CloudVoiceParameterDefinition["type"] : "string";
+}
+
+function isCustomParameter(definition: CloudVoiceParameterDefinition) {
+    return !definition.preset && !RESERVED_PARAMETER_KEYS.has(definition.key);
+}
+
+function normalizeEnum(value: unknown) {
+    return Array.isArray(value) ? value.filter((item) => item !== undefined) : undefined;
+}
+
+export function normalizeCloudVoiceParameterDefinitions(value: unknown): CloudVoiceParameterDefinition[] {
+    const rawDefinitions = Array.isArray(value) ? value : [];
+    const definitions = new Map<string, CloudVoiceParameterDefinition>();
+
+    for (const predefined of CLOUD_VOICE_PREDEFINED_PARAMETERS) {
+        definitions.set(predefined.key, predefined);
+    }
+
+    for (const raw of rawDefinitions) {
+        const record = getRecord(raw);
+        const key = normalizeParameterKey(record.key ?? record.name);
+        if (!key || RESERVED_PARAMETER_KEYS.has(key)) continue;
+        definitions.set(key, {
+            key,
+            label: getString(record.label, getString(record.name, key)),
+            type: normalizeParameterType(record.type),
+            source: "custom",
+            required: record.required === true,
+            description: getString(record.description, "") || undefined,
+            defaultValue: record.defaultValue,
+            enum: normalizeEnum(record.enum ?? record.options),
+            sensitive: record.sensitive === true,
+            jsonSchema: getRecord(record.jsonSchema ?? record.schema),
+        });
+    }
+
+    return Array.from(definitions.values());
+}
+
+function hasOwn(record: Record<string, unknown>, key: string) {
+    return Object.prototype.hasOwnProperty.call(record, key);
+}
+
+function readSystemValue(key: string, system: Record<string, unknown>) {
+    switch (key) {
+        case "user_id":
+            return system.userId;
+        case "session_id":
+            return system.sessionId;
+        case "agent_slug":
+            return system.agentSlug;
+        case "channel":
+            return system.channel;
+        case "phone":
+            return system.phone ?? system.callerPhone ?? system.fromPhone;
+        case "caller_phone":
+            return system.callerPhone ?? system.phone ?? system.fromPhone;
+        case "from_phone":
+            return system.fromPhone;
+        case "to_phone":
+            return system.toPhone ?? system.phoneNumber;
+        case "provider":
+            return system.provider;
+        case "provider_call_id":
+            return system.providerCallId;
+        case "call_direction":
+            return system.callDirection ?? system.direction;
+        case "phone_number_id":
+            return system.phoneNumberId;
+        case "embed_origin":
+            return system.embedOrigin ?? system.origin;
+        default:
+            return undefined;
+    }
+}
+
+function coerceValue(value: unknown, definition: CloudVoiceParameterDefinition): { ok: boolean; value?: unknown; error?: string } {
+    if (value === undefined || value === null || value === "") return { ok: true, value: undefined };
+
+    if (definition.enum && definition.enum.length > 0 && !definition.enum.includes(value)) {
+        return { ok: false, error: `${definition.key} must be one of ${definition.enum.map(String).join(", ")}` };
+    }
+
+    if (definition.type === "number") {
+        const numberValue = typeof value === "number" ? value : typeof value === "string" && value.trim() ? Number(value) : NaN;
+        return Number.isFinite(numberValue) ? { ok: true, value: numberValue } : { ok: false, error: `${definition.key} must be a number` };
+    }
+
+    if (definition.type === "boolean") {
+        if (typeof value === "boolean") return { ok: true, value };
+        if (value === "true") return { ok: true, value: true };
+        if (value === "false") return { ok: true, value: false };
+        return { ok: false, error: `${definition.key} must be a boolean` };
+    }
+
+    if (definition.type === "json") {
+        return { ok: true, value };
+    }
+
+    return { ok: true, value: String(value) };
+}
+
+export function resolveCloudVoiceParameters(input: {
+    config: Pick<CloudVoiceAgentConfig, "parameters">;
+    supplied?: CloudVoiceParameterValueMap | null;
+    system?: Record<string, unknown> | null;
+    mode?: CloudVoiceParameterResolutionMode;
+}): CloudVoiceParameterResolutionResult {
+    const mode = input.mode ?? "strict";
+    const supplied = getRecord(input.supplied);
+    const system = getRecord(input.system);
+    const definitions = normalizeCloudVoiceParameterDefinitions(input.config.parameters);
+    const values: CloudVoiceParameterValueMap = {};
+    const missingRequired: string[] = [];
+    const errors: string[] = [];
+    const sensitiveKeys: string[] = [];
+
+    for (const definition of definitions) {
+        const custom = isCustomParameter(definition);
+        const rawValue = custom && hasOwn(supplied, definition.key)
+            ? supplied[definition.key]
+            : custom && definition.defaultValue !== undefined
+                ? definition.defaultValue
+                : !custom
+                    ? readSystemValue(definition.key, system)
+                    : undefined;
+
+        const coerced = coerceValue(rawValue, definition);
+        if (!coerced.ok) {
+            errors.push(coerced.error ?? `${definition.key} is invalid`);
+            continue;
+        }
+        if (coerced.value !== undefined) {
+            values[definition.key] = coerced.value;
+            if (definition.sensitive) sensitiveKeys.push(definition.key);
+            continue;
+        }
+        if (definition.required && custom) {
+            missingRequired.push(definition.key);
+        }
+    }
+
+    if (mode === "strict" && (missingRequired.length > 0 || errors.length > 0)) {
+        const parts = [
+            missingRequired.length ? `missing required parameters: ${missingRequired.join(", ")}` : "",
+            ...errors,
+        ].filter(Boolean);
+        throw new Error(`Cloud voice parameters are invalid: ${parts.join("; ")}`);
+    }
+
+    return {
+        definitions,
+        values,
+        missingRequired,
+        errors,
+        sensitiveKeys,
+    };
+}
+
+function stringifyTemplateValue(value: unknown) {
+    if (value === undefined || value === null) return "";
+    if (typeof value === "string") return value;
+    if (typeof value === "number" || typeof value === "boolean") return String(value);
+    return JSON.stringify(value);
+}
+
+export function renderCloudVoiceParameterTemplate(text: string, parameters: CloudVoiceParameterValueMap) {
+    if (!text || !text.includes("{{")) return text;
+    return text
+        .replace(/\{\{\s*(?:params|parameters)\.([a-zA-Z0-9_]+)\s*\}\}/g, (_match, key: string) =>
+            stringifyTemplateValue(parameters[key]))
+        .replace(/\{\{\s*([a-zA-Z0-9_]+)\s*\}\}/g, (match, key: string) =>
+            Object.prototype.hasOwnProperty.call(parameters, key) ? stringifyTemplateValue(parameters[key]) : match);
+}
+
+export function renderCloudVoiceParameterObject<T>(value: T, parameters: CloudVoiceParameterValueMap): T {
+    if (typeof value === "string") return renderCloudVoiceParameterTemplate(value, parameters) as T;
+    if (Array.isArray(value)) return value.map((item) => renderCloudVoiceParameterObject(item, parameters)) as T;
+    if (!value || typeof value !== "object") return value;
+    const next: Record<string, unknown> = {};
+    for (const [key, child] of Object.entries(value as Record<string, unknown>)) {
+        next[key] = renderCloudVoiceParameterObject(child, parameters);
+    }
+    return next as T;
+}