@kognitivedev/backend-cloud 0.2.29

package/src/types.ts

@@ -0,0 +1,529 @@
+import type {
+    TelephonyDestination,
+    TelephonyProvider,
+    TelephonyTransferCallResult,
+    TelephonyTransferMode,
+    TelephonyTransferPolicy,
+} from "@kognitivedev/telephony";
+
+export type CloudVoiceChannel = "web" | "iframe" | "script" | "phone" | "sip" | "outbound";
+
+export type CloudVoiceProvider = "openai-realtime" | "gemini-live" | "kognitive-voice" | "xai-realtime";
+
+export type CloudVoiceTransport = "webrtc" | "websocket";
+export type CloudVoicePipelineTransportProvider = "kognitive-websocket" | "daily";
+
+export type CloudVoiceToolType =
+    | "cloud_flow"
+    | "web_search"
+    | "knowledge_base"
+    | "platform_action"
+    | "calendar_action"
+    | "appointment_action"
+    | "cloud_voice_agent"
+    | "external_webhook"
+    | "sip_transfer"
+    | "code_defined_tool";
+
+export interface CloudVoiceToolBinding {
+    id: string;
+    type: CloudVoiceToolType;
+    name: string;
+    description?: string;
+    inputSchema?: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+    parameterBindings?: Record<string, { parameter: string }>;
+    ui?: {
+        type?: "card" | "status" | "table" | "timeline" | "custom";
+        title?: string;
+        description?: string;
+        renderer?: string;
+        config?: Record<string, unknown>;
+    };
+    config: Record<string, unknown>;
+}
+
+export type CloudVoiceTelephonyProvider = Exclude<TelephonyProvider, "twilio"> | string;
+
+export type CloudVoiceTelephonyDestination = TelephonyDestination;
+
+export type CloudVoiceTransferMode = TelephonyTransferMode;
+
+export type CloudVoiceTransferPolicy = TelephonyTransferPolicy & {
+    fallbackDestinationId?: string;
+};
+
+export interface CloudVoiceTransferDestination {
+    id: string;
+    name: string;
+    provider?: CloudVoiceTelephonyProvider;
+    destination: CloudVoiceTelephonyDestination;
+    policy?: CloudVoiceTransferPolicy;
+    metadata?: Record<string, unknown>;
+}
+
+export interface CloudVoiceSipConfig {
+    enabled?: boolean;
+    defaultConnectionId?: string;
+    defaultProvider?: CloudVoiceTelephonyProvider;
+    inboundRouting?: {
+        mode: "agent" | "flow" | "queue";
+        agentId?: string;
+        flowId?: string;
+        queueId?: string;
+    };
+    transferPolicy?: CloudVoiceTransferPolicy;
+}
+
+export type CloudVoiceFlowNodeType = "initial" | "case" | "tool" | "transfer" | "end" | string;
+
+export interface CloudVoiceFlowNodeOutput {
+    id: string;
+    label: string;
+    description?: string;
+    desc?: string;
+    condition?: string;
+    icon?: string;
+    metadata?: Record<string, unknown>;
+}
+
+export interface CloudVoiceSpeechConfig extends Record<string, unknown> {
+    language?: string;
+    accent?: string;
+    style?: string;
+    pace?: string;
+    emotion?: string;
+}
+
+export interface CloudVoiceNodeVoiceSettings extends Record<string, unknown> {
+    speed?: number;
+    pitch?: number;
+    backgroundNoise?: boolean;
+    fillerWords?: boolean;
+}
+
+export interface CloudVoiceNodeModelSettings extends Record<string, unknown> {
+    temperature?: number;
+    maxOutputTokens?: number;
+    sentimentGuardrails?: boolean;
+    recordTranscript?: boolean;
+}
+
+export interface CloudVoiceFlowNode {
+    id: string;
+    type: CloudVoiceFlowNodeType;
+    entryMode?: "incoming" | "outgoing" | "both" | "default" | string;
+    title?: string;
+    prompt?: string;
+    firstMessage?: string;
+    language?: string;
+    maxDuration?: string | number;
+    provider?: CloudVoiceProvider;
+    model?: string;
+    voice?: string;
+    transport?: CloudVoiceTransport;
+    providerOptions?: Record<string, unknown>;
+    transcription?: Record<string, unknown> | null;
+    turnDetection?: Record<string, unknown> | null;
+    inputNoiseReduction?: Record<string, unknown> | null;
+    humanization?: CloudVoiceHumanizationConfig;
+    speech?: CloudVoiceSpeechConfig;
+    phoneNumberIds?: string[];
+    voiceSettings?: CloudVoiceNodeVoiceSettings;
+    modelSettings?: CloudVoiceNodeModelSettings;
+    outputs?: CloudVoiceFlowNodeOutput[];
+    toolId?: string;
+    toolIds?: string[];
+    transferTarget?: string;
+    transferDestinationId?: string;
+    transferMode?: CloudVoiceTransferMode;
+    metadata?: Record<string, unknown>;
+}
+
+export interface CloudVoiceFlowEdge {
+    id?: string;
+    from: string;
+    fromPort?: string | null;
+    to: string;
+}
+
+export interface CloudVoiceFlowGraph {
+    version?: 1;
+    startNodeId?: string;
+    nodes: CloudVoiceFlowNode[];
+    edges: CloudVoiceFlowEdge[];
+    metadata?: Record<string, unknown>;
+}
+
+export interface CloudVoiceAgentMetadata extends Record<string, unknown> {
+    flowGraph?: CloudVoiceFlowGraph;
+    speech?: CloudVoiceSpeechConfig;
+    sip?: CloudVoiceSipConfig;
+    transferDestinations?: CloudVoiceTransferDestination[];
+}
+
+export interface CloudVoiceClientToolManifest {
+    id: string;
+    name?: string;
+    description?: string;
+    inputSchema?: Record<string, unknown>;
+}
+
+export interface CloudVoiceHumanizationConfig {
+    enabled?: boolean;
+    openingMode?: "auto" | "wait";
+    openingStyle?: "brief" | "warm" | "professional";
+    fillerStyle?: "off" | "light" | "natural";
+    backchannelFrequency?: "off" | "low" | "medium";
+    disfluency?: "off" | "rare";
+    toolLatencyFillerMs?: number;
+    conversationProfile?: CloudVoiceConversationProfile;
+}
+
+export interface CloudVoiceConversationProfile {
+    personality: "neutral" | "warm" | "expert" | "concierge";
+    tone: "casual" | "professional" | "empathetic" | "polished";
+    pacing: "concise" | "measured" | "deliberate" | "energetic";
+    unclearAudio: "ask_repeat" | "confirm_best_guess";
+    confirmation: "critical_fields" | "all_actions" | "minimal";
+    escalation: "when_blocked" | "on_request" | "never";
+    numberReadback: boolean;
+}
+
+export interface CloudVoiceRuntimeCapabilities {
+    canUpdateInstructionsLive: boolean;
+    supportsSessionResume: boolean;
+    supportsToolCalling: boolean;
+    supportsOutputAudioTranscripts: boolean;
+    supportsServerVadConfig: boolean;
+    supportsSemanticVad?: boolean;
+    supportsNativeAudioOptions?: boolean;
+    supportsAffectiveDialog?: boolean;
+    supportsProactiveAudio?: boolean;
+    supportsPipelineEotConfig?: boolean;
+    supportsCartesiaTtsControls?: boolean;
+}
+
+export interface CloudVoiceCartesiaTtsOptions extends Record<string, unknown> {
+    modelId?: string;
+    voice?: string;
+    speed?: number | "slow" | "normal" | "fast";
+    emotion?: string[];
+    pronunciationDictId?: string;
+    contextMode?: "continue" | "reset";
+}
+
+export interface CloudVoicePipelineTransportConfig {
+    type: CloudVoiceTransport;
+    provider?: CloudVoicePipelineTransportProvider;
+}
+
+export interface CloudVoicePipelineSTTConfig {
+    provider: string;
+    model: string;
+    language?: string;
+}
+
+export interface CloudVoicePipelineLLMConfig {
+    provider: string;
+    model: string;
+}
+
+export interface CloudVoicePipelineTTSConfig {
+    provider: string;
+    model: string;
+    voice?: string;
+    options?: CloudVoiceCartesiaTtsOptions;
+}
+
+export interface CloudVoicePipelineTurnConfig extends Record<string, unknown> {
+    interruptResponse?: boolean;
+    createResponse?: boolean;
+    prefixPaddingMs?: number;
+    silenceDurationMs?: number;
+    threshold?: number;
+}
+
+export interface CloudVoicePipelineConfig {
+    transport: CloudVoicePipelineTransportConfig;
+    stt: CloudVoicePipelineSTTConfig;
+    llm: CloudVoicePipelineLLMConfig;
+    tts: CloudVoicePipelineTTSConfig;
+    turn?: CloudVoicePipelineTurnConfig;
+    backgroundAudio?: { preset?: string };
+}
+
+export type CloudVoiceParameterType = "string" | "number" | "boolean" | "json" | "phone" | "email";
+export type CloudVoiceParameterSource = "system" | "session" | "call" | "custom";
+export type CloudVoiceParameterPreset =
+    | "user_id"
+    | "session_id"
+    | "agent_slug"
+    | "channel"
+    | "phone"
+    | "caller_phone"
+    | "from_phone"
+    | "to_phone"
+    | "provider"
+    | "provider_call_id"
+    | "call_direction"
+    | "phone_number_id"
+    | "embed_origin";
+export type CloudVoiceParameterResolutionMode = "strict" | "permissive";
+export type CloudVoiceParameterValueMap = Record<string, unknown>;
+
+export interface CloudVoiceParameterDefinition {
+    key: string;
+    label: string;
+    type: CloudVoiceParameterType;
+    required?: boolean;
+    description?: string;
+    defaultValue?: unknown;
+    enum?: unknown[];
+    source?: CloudVoiceParameterSource;
+    preset?: CloudVoiceParameterPreset;
+    sensitive?: boolean;
+    jsonSchema?: Record<string, unknown>;
+}
+
+export interface CloudVoiceParameterResolutionResult {
+    definitions: CloudVoiceParameterDefinition[];
+    values: CloudVoiceParameterValueMap;
+    missingRequired: string[];
+    errors: string[];
+    sensitiveKeys: string[];
+}
+
+export interface CloudVoiceAgentConfig {
+    instructions: string;
+    provider: CloudVoiceProvider;
+    model: string;
+    voice: string;
+    transport: CloudVoiceTransport;
+    pipeline?: CloudVoicePipelineConfig;
+    memoryEnabled?: boolean;
+    providerOptions?: Record<string, unknown>;
+    transcription?: Record<string, unknown> | null;
+    turnDetection?: Record<string, unknown> | null;
+    inputNoiseReduction?: Record<string, unknown> | null;
+    tools: CloudVoiceToolBinding[];
+    knowledgeBases: Array<{ pipelineId: string; name?: string; topK?: number }>;
+    webSearch?: { enabled?: boolean; maxResults?: number; maxPages?: number };
+    widget: {
+        title: string;
+        subtitle?: string;
+        layout?: "expanded" | "compact";
+        accentColor?: string;
+        backgroundColor?: string;
+        surfaceColor?: string;
+        textColor?: string;
+        mutedColor?: string;
+        ctaLabel?: string;
+        launcher?: "button" | "inline";
+        position?: "bottom-right" | "bottom-left";
+    };
+    channels: {
+        web: boolean;
+        iframe: boolean;
+        script: boolean;
+        phone: boolean;
+        sip: boolean;
+        outbound: boolean;
+    };
+    humanization?: CloudVoiceHumanizationConfig;
+    cloudVoiceConfigVersion?: 2;
+    parameters?: CloudVoiceParameterDefinition[];
+    metadata?: CloudVoiceAgentMetadata;
+}
+
+export interface CloudVoiceFunctionToolManifest {
+    type: "function";
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+}
+
+export interface CompiledCloudVoiceFlowInstructions {
+    instructions: string;
+    compilerVersion: string;
+    graphSignature: string;
+    startNodeId: string | null;
+    entryMode?: "incoming" | "outgoing" | "both";
+    nodeCount: number;
+    edgeCount: number;
+    referencedToolIds: string[];
+    missingToolIds: string[];
+    toolManifest: CloudVoiceFunctionToolManifest[];
+    warnings: string[];
+}
+
+export interface PreparedCloudVoiceConfig {
+    name: string;
+    system: string;
+    runtime: {
+        provider: CloudVoiceProvider;
+        mode: "pipeline" | "realtime";
+        transport: CloudVoiceTransport;
+        model: string;
+        voice: string;
+        providerOptions?: Record<string, unknown>;
+        pipeline?: CloudVoicePipelineConfig;
+        capabilities: CloudVoiceRuntimeCapabilities;
+    };
+    voiceConfig: {
+        system: string;
+        model: string;
+        voice: string;
+        speech?: CloudVoiceSpeechConfig;
+        languageCode?: string;
+        turnDetection?: Record<string, unknown> | null;
+        transcription?: Record<string, unknown> | null;
+        inputNoiseReduction?: Record<string, unknown> | null;
+        maxOutputTokens: number | "inf";
+        temperature?: number;
+        tts?: {
+            provider: "cartesia";
+            options: CloudVoiceCartesiaTtsOptions;
+        };
+    };
+    tools: [];
+    toolManifest: CloudVoiceFunctionToolManifest[];
+    resourceId: Record<string, unknown>;
+    parameters: CloudVoiceParameterValueMap;
+    metadata: {
+        cloudVoice: true;
+        sessionId: string;
+        cloudVoiceConfigVersion: 2;
+        promptCompilerVersion: string;
+        clientTools: string[];
+        transferDestinations: string[];
+        parameterKeys: string[];
+        missingRequiredParameters: string[];
+        sensitiveParameterKeys: string[];
+        flowGraph?: {
+            startNodeId: string | null;
+            entryMode?: "incoming" | "outgoing" | "both";
+            nodeCount: number;
+            edgeCount: number;
+            referencedToolIds: string[];
+            missingToolIds: string[];
+        };
+    };
+}
+
+export interface CloudVoiceAgentSnapshot {
+    id: string;
+    slug: string;
+    name: string;
+    draftVersion: number;
+    publishedVersion: number | null;
+}
+
+export interface CloudVoicePhonePrepareSnapshot {
+    schemaVersion: 1;
+    createdAt: string;
+    channel: CloudVoiceChannel;
+    agent: {
+        id: string;
+        slug: string;
+        name: string;
+        version: number;
+    };
+    runtime: PreparedCloudVoiceConfig["runtime"];
+    voiceConfig: PreparedCloudVoiceConfig["voiceConfig"];
+    toolManifest: CloudVoiceFunctionToolManifest[];
+    config: CloudVoiceAgentConfig;
+    parameters: CloudVoiceParameterValueMap;
+}
+
+export interface ExecuteCloudVoiceToolBindingInput {
+    projectId: string;
+    sessionId: string;
+    tool: CloudVoiceToolBinding;
+    args: unknown;
+    resourceId?: Record<string, unknown>;
+    parameters?: CloudVoiceParameterValueMap;
+    executeWebSearch?: (input: {
+        query: string;
+        parameters: Record<string, unknown>;
+    }) => Promise<unknown>;
+    executeCloudFlow?: (input: {
+        flowSlug: string;
+        args: unknown;
+        resourceId?: Record<string, unknown>;
+    }) => Promise<unknown>;
+    executeKnowledgeBase?: (input: {
+        pipelineId: string;
+        query: string;
+        topK: number;
+    }) => Promise<unknown>;
+    executePlatformAction?: (input: {
+        actionSlug: string;
+        connectionId: string;
+        args: Record<string, unknown>;
+    }) => Promise<unknown>;
+    executeCalendarAction?: (input: {
+        action: string;
+        args: Record<string, unknown>;
+        config?: Record<string, unknown>;
+    }) => Promise<unknown>;
+    executeAppointmentAction?: (input: {
+        action: string;
+        args: Record<string, unknown>;
+        config?: Record<string, unknown>;
+    }) => Promise<unknown>;
+    executeCloudVoiceAgent?: (input: {
+        agentSlug: string;
+        fromNumberId: string;
+        to: string;
+        parameters: Record<string, unknown>;
+        timeoutMs: number;
+        intervalMs: number;
+        metadata: Record<string, unknown>;
+        tool: CloudVoiceToolBinding;
+        args: Record<string, unknown>;
+    }) => Promise<unknown>;
+    executeExternalWebhook?: (input: {
+        tool: CloudVoiceToolBinding;
+        args: unknown;
+    }) => Promise<unknown>;
+    executeSipTransfer?: (input: {
+        providerCallId: string;
+        destination: CloudVoiceTelephonyDestination;
+        mode?: CloudVoiceTransferMode;
+        reason?: string;
+        policy?: CloudVoiceTransferPolicy;
+        metadata?: Record<string, unknown>;
+    }) => Promise<TelephonyTransferCallResult>;
+}
+
+export interface ExecuteCloudVoiceToolBindingResult {
+    result: unknown;
+    metadata: Record<string, unknown>;
+}
+
+export interface CloudVoicePhoneControlAdapter {
+    provider: string;
+    hangUpCall(input: {
+        providerCallId: string;
+        reason?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<{
+        provider: string;
+        providerCallId: string;
+        status: string;
+        raw?: unknown;
+    }>;
+}
+
+export interface CloudVoiceSipControlAdapter {
+    provider: string;
+    transferCall(input: {
+        providerCallId: string;
+        destination: CloudVoiceTelephonyDestination;
+        mode?: CloudVoiceTransferMode;
+        reason?: string;
+        policy?: CloudVoiceTransferPolicy;
+        metadata?: Record<string, unknown>;
+    }): Promise<TelephonyTransferCallResult>;
+}

package/src/utils.ts

@@ -0,0 +1,11 @@
+export function getString(value: unknown, fallback = "") {
+    return typeof value === "string" && value.trim() ? value.trim() : fallback;
+}
+
+export function getNumber(value: unknown, fallback: number) {
+    return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+
+export function getRecord(value: unknown): Record<string, unknown> {
+    return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : {};
+}

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "module": "commonjs",
+    "rootDir": "src",
+    "outDir": "dist",
+    "declaration": true,
+    "noEmit": false,
+    "incremental": false
+  },
+  "include": ["src"],
+  "exclude": ["src/__tests__"]
+}