@kognitivedev/telephony 0.2.29

package/src/registry.ts

@@ -0,0 +1,56 @@
+import type { TelephonyCallControlAdapter, TelephonyProvider, TelephonyProviderAdapter } from "./types";
+
+export interface TelephonyAdapterRegistry {
+    registerProvider(adapter: TelephonyProviderAdapter): void;
+    registerCallControl(adapter: TelephonyCallControlAdapter): void;
+    getProvider(provider: TelephonyProvider): TelephonyProviderAdapter | undefined;
+    getCallControl(provider: TelephonyProvider): TelephonyCallControlAdapter | undefined;
+    requireProvider(provider: TelephonyProvider): TelephonyProviderAdapter;
+    requireCallControl(provider: TelephonyProvider): TelephonyCallControlAdapter;
+    listProviders(): TelephonyProvider[];
+    listCallControlProviders(): TelephonyProvider[];
+}
+
+export function createTelephonyAdapterRegistry(input: {
+    providers?: TelephonyProviderAdapter[];
+    callControls?: TelephonyCallControlAdapter[];
+} = {}): TelephonyAdapterRegistry {
+    const providers = new Map<TelephonyProvider, TelephonyProviderAdapter>();
+    const callControls = new Map<TelephonyProvider, TelephonyCallControlAdapter>();
+
+    const registry: TelephonyAdapterRegistry = {
+        registerProvider(adapter) {
+            providers.set(adapter.provider, adapter);
+        },
+        registerCallControl(adapter) {
+            callControls.set(adapter.provider, adapter);
+        },
+        getProvider(provider) {
+            return providers.get(provider);
+        },
+        getCallControl(provider) {
+            return callControls.get(provider);
+        },
+        requireProvider(provider) {
+            const adapter = providers.get(provider);
+            if (!adapter) throw new Error(`Telephony provider "${provider}" is not registered`);
+            return adapter;
+        },
+        requireCallControl(provider) {
+            const adapter = callControls.get(provider);
+            if (!adapter) throw new Error(`Telephony call-control provider "${provider}" is not registered`);
+            return adapter;
+        },
+        listProviders() {
+            return [...providers.keys()];
+        },
+        listCallControlProviders() {
+            return [...callControls.keys()];
+        },
+    };
+
+    for (const adapter of input.providers ?? []) registry.registerProvider(adapter);
+    for (const adapter of input.callControls ?? []) registry.registerCallControl(adapter);
+
+    return registry;
+}

package/src/rtp.ts

@@ -0,0 +1,107 @@
+export const RTP_VERSION = 2;
+export const RTP_PAYLOAD_TYPE_PCMU = 0;
+export const RTP_PAYLOAD_TYPE_PCMA = 8;
+
+export interface RtpPacket {
+    version: number;
+    padding: boolean;
+    extension: boolean;
+    marker: boolean;
+    payloadType: number;
+    sequenceNumber: number;
+    timestamp: number;
+    ssrc: number;
+    csrc: number[];
+    payload: Buffer;
+}
+
+export interface SerializeRtpPacketInput {
+    marker?: boolean;
+    payloadType?: number;
+    sequenceNumber: number;
+    timestamp: number;
+    ssrc: number;
+    payload: Buffer | Uint8Array;
+    csrc?: number[];
+}
+
+function assertUint16(value: number, label: string) {
+    if (!Number.isInteger(value) || value < 0 || value > 0xffff) {
+        throw new Error(`${label} must be a uint16`);
+    }
+}
+
+function assertUint32(value: number, label: string) {
+    if (!Number.isInteger(value) || value < 0 || value > 0xffffffff) {
+        throw new Error(`${label} must be a uint32`);
+    }
+}
+
+export function nextRtpSequenceNumber(value: number) {
+    return (value + 1) & 0xffff;
+}
+
+export function nextRtpTimestamp(value: number, increment: number) {
+    assertUint32(value, "timestamp");
+    if (!Number.isInteger(increment) || increment < 0) throw new Error("increment must be a non-negative integer");
+    return (value + increment) >>> 0;
+}
+
+export function parseRtpPacket(buffer: Buffer | Uint8Array): RtpPacket {
+    const data = Buffer.isBuffer(buffer) ? buffer : Buffer.from(buffer);
+    if (data.length < 12) throw new Error("RTP packet is too short");
+
+    const first = data[0] ?? 0;
+    const version = first >> 6;
+    if (version !== RTP_VERSION) throw new Error(`Unsupported RTP version ${version}`);
+
+    const csrcCount = first & 0x0f;
+    const headerLength = 12 + csrcCount * 4;
+    if (data.length < headerLength) throw new Error("RTP packet has truncated CSRC list");
+
+    const second = data[1] ?? 0;
+    const csrc: number[] = [];
+    for (let offset = 12; offset < headerLength; offset += 4) {
+        csrc.push(data.readUInt32BE(offset));
+    }
+
+    return {
+        version,
+        padding: Boolean(first & 0x20),
+        extension: Boolean(first & 0x10),
+        marker: Boolean(second & 0x80),
+        payloadType: second & 0x7f,
+        sequenceNumber: data.readUInt16BE(2),
+        timestamp: data.readUInt32BE(4),
+        ssrc: data.readUInt32BE(8),
+        csrc,
+        payload: data.subarray(headerLength),
+    };
+}
+
+export function serializeRtpPacket(input: SerializeRtpPacketInput): Buffer {
+    assertUint16(input.sequenceNumber, "sequenceNumber");
+    assertUint32(input.timestamp, "timestamp");
+    assertUint32(input.ssrc, "ssrc");
+    const payloadType = input.payloadType ?? RTP_PAYLOAD_TYPE_PCMU;
+    if (!Number.isInteger(payloadType) || payloadType < 0 || payloadType > 0x7f) {
+        throw new Error("payloadType must be a 7-bit integer");
+    }
+    const csrc = input.csrc ?? [];
+    if (csrc.length > 15) throw new Error("RTP packets can contain at most 15 CSRC entries");
+    for (const [index, value] of csrc.entries()) assertUint32(value, `csrc[${index}]`);
+
+    const payload = Buffer.isBuffer(input.payload) ? input.payload : Buffer.from(input.payload);
+    const headerLength = 12 + csrc.length * 4;
+    const packet = Buffer.alloc(headerLength + payload.length);
+    packet[0] = (RTP_VERSION << 6) | csrc.length;
+    packet[1] = (input.marker ? 0x80 : 0) | payloadType;
+    packet.writeUInt16BE(input.sequenceNumber, 2);
+    packet.writeUInt32BE(input.timestamp >>> 0, 4);
+    packet.writeUInt32BE(input.ssrc >>> 0, 8);
+    for (let index = 0; index < csrc.length; index += 1) {
+        packet.writeUInt32BE(csrc[index] ?? 0, 12 + index * 4);
+    }
+    payload.copy(packet, headerLength);
+    return packet;
+}

package/src/twilio.ts

@@ -0,0 +1,208 @@
+import {
+    computeTwilioBodySha256,
+    createTwilioInboundCallResponse,
+    createTwilioMediaStreamClearMessage,
+    createTwilioMediaStreamMarkMessage,
+    createTwilioMediaStreamMediaMessage,
+    createTwilioMediaStreamTwiml,
+    decodeTwilioMulawBase64ToFloat32,
+    decodeTwilioMulawBase64ToPcm16,
+    encodeFloat32ToTwilioMulawBase64,
+    encodePcm16ToTwilioMulawBase64,
+    handleTwilioMediaStreamMessage,
+    parseTwilioMediaStreamMessage,
+    serializeTwilioMediaStreamMessage,
+    validateTwilioRequestSignature,
+    type CreateTwilioMediaStreamTwimlOptions,
+    type TwilioInboundCallContext,
+    type TwilioInboundCallResponse,
+    type TwilioInboundCallResponseConfig,
+    type TwilioInboundMediaStreamMessage,
+    type TwilioOutboundMediaStreamMessage,
+    type TwilioRequestSignatureValidationOptions,
+} from "@kognitivedev/voice/telephony";
+import type {
+    TelephonyCallControlAdapter,
+    TelephonyCallControlResult,
+    TelephonyOutboundCallInput,
+    TelephonyOutboundCallResult,
+    TelephonyProviderAdapter,
+} from "./types";
+
+export {
+    computeTwilioBodySha256,
+    createTwilioInboundCallResponse,
+    createTwilioMediaStreamClearMessage,
+    createTwilioMediaStreamMarkMessage,
+    createTwilioMediaStreamMediaMessage,
+    createTwilioMediaStreamTwiml,
+    decodeTwilioMulawBase64ToFloat32,
+    decodeTwilioMulawBase64ToPcm16,
+    encodeFloat32ToTwilioMulawBase64,
+    encodePcm16ToTwilioMulawBase64,
+    handleTwilioMediaStreamMessage,
+    parseTwilioMediaStreamMessage,
+    serializeTwilioMediaStreamMessage,
+    validateTwilioRequestSignature,
+};
+
+export type {
+    CreateTwilioMediaStreamTwimlOptions,
+    TwilioInboundCallContext,
+    TwilioInboundCallResponse,
+    TwilioInboundCallResponseConfig,
+    TwilioInboundMediaStreamMessage,
+    TwilioOutboundMediaStreamMessage,
+    TwilioRequestSignatureValidationOptions,
+};
+
+export interface TwilioOutboundCallOptions extends TelephonyOutboundCallInput {
+    accountSid: string;
+    authToken: string;
+    fetch?: typeof fetch;
+}
+
+export interface TwilioTelephonyProviderConfig {
+    accountSid: string;
+    authToken: string;
+    fetch?: typeof fetch;
+}
+
+export interface TwilioCompleteCallOptions {
+    accountSid: string;
+    authToken: string;
+    providerCallId: string;
+    fetch?: typeof fetch;
+}
+
+function normalizeTwilioStatus(value: unknown): TelephonyOutboundCallResult["status"] {
+    switch (value) {
+        case "queued":
+        case "ringing":
+        case "in-progress":
+            return value === "in-progress" ? "active" : value;
+        case "completed":
+        case "failed":
+        case "busy":
+        case "no-answer":
+        case "cancelled":
+            return value;
+        default:
+            return "unknown";
+    }
+}
+
+function assertTwilioValue(value: string | undefined, label: string) {
+    if (!value?.trim()) throw new Error(`${label} is required`);
+    return value.trim();
+}
+
+export async function createTwilioOutboundCall(options: TwilioOutboundCallOptions): Promise<TelephonyOutboundCallResult> {
+    const accountSid = assertTwilioValue(options.accountSid, "Twilio accountSid");
+    const authToken = assertTwilioValue(options.authToken, "Twilio authToken");
+    const from = assertTwilioValue(options.from, "from");
+    const to = assertTwilioValue(options.to, "to");
+    const answerUrl = assertTwilioValue(options.answerUrl, "answerUrl");
+    const fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis);
+    const form = new URLSearchParams({
+        From: from,
+        To: to,
+        Url: answerUrl,
+    });
+    if (options.statusCallbackUrl) {
+        form.set("StatusCallback", options.statusCallbackUrl);
+        for (const event of ["initiated", "ringing", "answered", "completed"]) {
+            form.append("StatusCallbackEvent", event);
+        }
+    }
+
+    const response = await fetchImpl(`https://api.twilio.com/2010-04-01/Accounts/${encodeURIComponent(accountSid)}/Calls.json`, {
+        method: "POST",
+        headers: {
+            Authorization: `Basic ${Buffer.from(`${accountSid}:${authToken}`).toString("base64")}`,
+            "Content-Type": "application/x-www-form-urlencoded",
+        },
+        body: form,
+    });
+
+    const raw = await response.json().catch(() => ({})) as Record<string, unknown>;
+    if (!response.ok) {
+        const message = typeof raw.message === "string" ? raw.message : response.statusText;
+        throw new Error(`Twilio outbound call failed: ${message}`);
+    }
+
+    const providerCallId = typeof raw.sid === "string" ? raw.sid : options.providerCallId;
+    if (!providerCallId) {
+        throw new Error("Twilio outbound call response did not include sid");
+    }
+
+    return {
+        provider: "twilio",
+        providerCallId,
+        status: normalizeTwilioStatus(raw.status),
+        from,
+        to,
+        raw,
+    };
+}
+
+export async function completeTwilioCall(options: TwilioCompleteCallOptions): Promise<TelephonyCallControlResult> {
+    const accountSid = assertTwilioValue(options.accountSid, "Twilio accountSid");
+    const authToken = assertTwilioValue(options.authToken, "Twilio authToken");
+    const providerCallId = assertTwilioValue(options.providerCallId, "Twilio providerCallId");
+    const fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis);
+    const form = new URLSearchParams({ Status: "completed" });
+
+    const response = await fetchImpl(
+        `https://api.twilio.com/2010-04-01/Accounts/${encodeURIComponent(accountSid)}/Calls/${encodeURIComponent(providerCallId)}.json`,
+        {
+            method: "POST",
+            headers: {
+                Authorization: `Basic ${Buffer.from(`${accountSid}:${authToken}`).toString("base64")}`,
+                "Content-Type": "application/x-www-form-urlencoded",
+            },
+            body: form,
+        },
+    );
+
+    const raw = await response.json().catch(() => ({})) as Record<string, unknown>;
+    if (!response.ok) {
+        const message = typeof raw.message === "string" ? raw.message : response.statusText;
+        throw new Error(`Twilio call completion failed: ${message}`);
+    }
+
+    return {
+        provider: "twilio",
+        providerCallId,
+        status: normalizeTwilioStatus(raw.status ?? "completed"),
+        raw,
+    };
+}
+
+export function createTwilioTelephonyProvider(config: TwilioTelephonyProviderConfig): TelephonyProviderAdapter {
+    return {
+        provider: "twilio",
+        createOutboundCall(input) {
+            return createTwilioOutboundCall({
+                ...input,
+                accountSid: config.accountSid,
+                authToken: config.authToken,
+                fetch: config.fetch,
+            });
+        },
+    };
+}
+
+export function createTwilioPhoneControlAdapter(config: TwilioTelephonyProviderConfig): TelephonyCallControlAdapter {
+    return {
+        provider: "twilio",
+        hangUpCall(input) {
+            return completeTwilioCall({
+                accountSid: config.accountSid,
+                authToken: config.authToken,
+                providerCallId: input.providerCallId,
+                fetch: config.fetch,
+            });
+        },
+    };
+}

package/src/types.ts

@@ -0,0 +1,326 @@
+export type TelephonyProvider =
+    | "twilio"
+    | "telnyx"
+    | "cm_com"
+    | "didww"
+    | "sinch"
+    | "bird"
+    | "sip_custom";
+
+export type TelephonyConnectionMode =
+    | "provider_managed"
+    | "byoc_trunk"
+    | "sip_uri"
+    | "pbx_extension";
+
+export type TelephonyTransport = "udp" | "tcp" | "tls";
+
+export type TelephonyMediaEncryption = "none" | "srtp";
+
+export type TelephonyRegion =
+    | "eu"
+    | "de"
+    | "nl"
+    | "uk"
+    | "fr"
+    | "tr"
+    | "us"
+    | "global"
+    | string;
+
+export type TelephonyCallDirection = "inbound" | "outbound";
+
+export type TelephonyCallStatus =
+    | "queued"
+    | "ringing"
+    | "created"
+    | "active"
+    | "completed"
+    | "failed"
+    | "busy"
+    | "no-answer"
+    | "cancelled"
+    | "unknown";
+
+export interface TelephonyNumberCapabilities {
+    voice?: boolean;
+    sms?: boolean;
+    mms?: boolean;
+    sip?: boolean;
+}
+
+export interface TelephonyProviderCapabilities {
+    inboundPstn?: boolean;
+    outboundPstn?: boolean;
+    inboundSip?: boolean;
+    outboundSip?: boolean;
+    sipRefer?: boolean;
+    bridgeTransfer?: boolean;
+    blindTransfer?: boolean;
+    attendedTransfer?: boolean;
+    warmTransfer?: boolean;
+    hold?: boolean;
+    resume?: boolean;
+    conference?: boolean;
+    dtmf?: boolean;
+    recording?: boolean;
+    statusCallbacks?: boolean;
+    regions?: TelephonyRegion[];
+    transports?: TelephonyTransport[];
+    mediaEncryption?: TelephonyMediaEncryption[];
+    codecs?: string[];
+}
+
+export interface TelephonyConnection {
+    id: string;
+    provider: TelephonyProvider;
+    name: string;
+    mode: TelephonyConnectionMode;
+    status?: "draft" | "active" | "disabled" | "error";
+    inboundUri?: string;
+    outboundProxy?: string;
+    authMode?: "ip_acl" | "credentials" | "none";
+    username?: string;
+    secretRef?: string;
+    allowedIps?: string[];
+    transport?: TelephonyTransport;
+    mediaEncryption?: TelephonyMediaEncryption;
+    codecs?: string[];
+    region?: TelephonyRegion;
+    capabilities?: TelephonyProviderCapabilities;
+    metadata?: Record<string, unknown>;
+}
+
+export type TelephonyDestination =
+    | {
+        type: "phone_number";
+        phoneNumber: string;
+        connectionId?: string;
+        callerId?: string;
+        metadata?: Record<string, unknown>;
+    }
+    | {
+        type: "sip_uri";
+        uri: string;
+        connectionId?: string;
+        transport?: TelephonyTransport;
+        metadata?: Record<string, unknown>;
+    }
+    | {
+        type: "extension";
+        extension: string;
+        connectionId: string;
+        metadata?: Record<string, unknown>;
+    }
+    | {
+        type: "queue";
+        queueId: string;
+        metadata?: Record<string, unknown>;
+    }
+    | {
+        type: "browser_queue";
+        queueId?: string;
+        label?: string;
+        metadata?: Record<string, unknown>;
+    };
+
+export type TelephonyTransferMode = "blind" | "attended" | "warm";
+
+export type TelephonyTransferFallback =
+    | "return_to_ai"
+    | "alternate_destination"
+    | "voicemail"
+    | "hangup";
+
+export interface TelephonyTransferPolicy {
+    mode?: TelephonyTransferMode;
+    timeoutSeconds?: number;
+    fallback?: TelephonyTransferFallback;
+    fallbackDestination?: TelephonyDestination;
+    announceBeforeTransfer?: boolean;
+    allowSipRefer?: boolean;
+}
+
+export type TelephonyCallControlAction =
+    | "answer"
+    | "reject"
+    | "originate"
+    | "bridge"
+    | "transfer"
+    | "hold"
+    | "resume"
+    | "conference"
+    | "send_dtmf"
+    | "hangup";
+
+export interface TelephonyPhoneNumber {
+    id?: string;
+    provider: TelephonyProvider;
+    phoneNumber: string;
+    label?: string | null;
+    providerNumberId?: string | null;
+    capabilities?: TelephonyNumberCapabilities;
+    inboundEnabled?: boolean;
+    outboundEnabled?: boolean;
+    metadata?: Record<string, unknown>;
+}
+
+export interface TelephonyInboundCallInput {
+    provider: TelephonyProvider;
+    providerCallId: string;
+    from: string;
+    to: string;
+    accountId?: string;
+    direction?: "inbound" | "outbound" | "unknown";
+    raw?: Record<string, unknown>;
+}
+
+export interface TelephonyOutboundCallInput {
+    from: string;
+    to: string;
+    answerUrl: string;
+    statusCallbackUrl?: string;
+    providerCallId?: string;
+    metadata?: Record<string, unknown>;
+}
+
+export interface TelephonyOutboundCallResult {
+    provider: TelephonyProvider;
+    providerCallId: string;
+    status: TelephonyCallStatus;
+    from: string;
+    to: string;
+    raw?: unknown;
+}
+
+export interface TelephonyCallControlResult {
+    provider: TelephonyProvider;
+    providerCallId: string;
+    status: TelephonyCallStatus;
+    raw?: unknown;
+}
+
+export interface TelephonyBaseCallControlInput {
+    providerCallId: string;
+    connectionId?: string;
+    metadata?: Record<string, unknown>;
+}
+
+export interface TelephonyAnswerCallInput extends TelephonyBaseCallControlInput {}
+
+export interface TelephonyRejectCallInput extends TelephonyBaseCallControlInput {
+    reason?: string;
+}
+
+export interface TelephonyOriginateCallInput {
+    from?: TelephonyDestination;
+    to: TelephonyDestination;
+    connectionId?: string;
+    answerUrl?: string;
+    statusCallbackUrl?: string;
+    metadata?: Record<string, unknown>;
+}
+
+export interface TelephonyOriginateCallResult {
+    provider: TelephonyProvider;
+    providerCallId: string;
+    status: TelephonyCallStatus;
+    from?: TelephonyDestination;
+    to: TelephonyDestination;
+    raw?: unknown;
+}
+
+export interface TelephonyBridgeCallInput extends TelephonyBaseCallControlInput {
+    target: TelephonyDestination | { providerCallId: string };
+    policy?: TelephonyTransferPolicy;
+}
+
+export interface TelephonyTransferCallInput extends TelephonyBaseCallControlInput {
+    destination: TelephonyDestination;
+    mode?: TelephonyTransferMode;
+    reason?: string;
+    policy?: TelephonyTransferPolicy;
+}
+
+export interface TelephonyTransferCallResult extends TelephonyCallControlResult {
+    destination: TelephonyDestination;
+    mode: TelephonyTransferMode;
+    transferId?: string;
+}
+
+export interface TelephonyHoldCallInput extends TelephonyBaseCallControlInput {
+    reason?: string;
+}
+
+export interface TelephonyResumeCallInput extends TelephonyBaseCallControlInput {
+    reason?: string;
+}
+
+export interface TelephonyHangUpCallInput extends TelephonyBaseCallControlInput {
+    reason?: string;
+}
+
+export interface TelephonySendDtmfInput extends TelephonyBaseCallControlInput {
+    digits: string;
+}
+
+export type TelephonyCallEvent =
+    | {
+        type: "call.created" | "call.ringing" | "call.answered" | "call.ended";
+        provider: TelephonyProvider;
+        providerCallId: string;
+        connectionId?: string;
+        at?: string;
+        metadata?: Record<string, unknown>;
+    }
+    | {
+        type: "call.transfer.started" | "call.transfer.completed" | "call.transfer.failed";
+        provider: TelephonyProvider;
+        providerCallId: string;
+        transferId?: string;
+        destination?: TelephonyDestination;
+        reason?: string;
+        at?: string;
+        metadata?: Record<string, unknown>;
+    };
+
+export interface ResolvedTelephonyConnection {
+    connection: TelephonyConnection;
+    provider: TelephonyProvider;
+    capabilities: TelephonyProviderCapabilities;
+    metadata?: Record<string, unknown>;
+}
+
+export interface TelephonyConnectionResolver {
+    resolveConnection(input: {
+        projectId: string;
+        accountId?: string;
+        agentId?: string;
+        destination?: TelephonyDestination;
+        channel?: "phone" | "sip" | "outbound";
+        metadata?: Record<string, unknown>;
+    }): Promise<ResolvedTelephonyConnection>;
+}
+
+export interface TelephonyProviderAdapter {
+    provider: TelephonyProvider;
+    createOutboundCall(input: TelephonyOutboundCallInput): Promise<TelephonyOutboundCallResult>;
+}
+
+export interface TelephonyCallControlAdapter {
+    provider: TelephonyProvider;
+    capabilities?(): TelephonyProviderCapabilities;
+    answerCall?(input: TelephonyAnswerCallInput): Promise<TelephonyCallControlResult>;
+    rejectCall?(input: TelephonyRejectCallInput): Promise<TelephonyCallControlResult>;
+    originateCall?(input: TelephonyOriginateCallInput): Promise<TelephonyOriginateCallResult>;
+    bridgeCall?(input: TelephonyBridgeCallInput): Promise<TelephonyCallControlResult>;
+    transferCall?(input: TelephonyTransferCallInput): Promise<TelephonyTransferCallResult>;
+    holdCall?(input: TelephonyHoldCallInput): Promise<TelephonyCallControlResult>;
+    resumeCall?(input: TelephonyResumeCallInput): Promise<TelephonyCallControlResult>;
+    sendDtmf?(input: TelephonySendDtmfInput): Promise<TelephonyCallControlResult>;
+    hangUpCall(input: {
+        providerCallId: string;
+        reason?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<TelephonyCallControlResult>;
+}