@framers/agentos 0.1.74 → 0.1.76

package/dist/voice/parsers/TwilioMediaStreamParser.js

@@ -0,0 +1,144 @@
+/**
+ * Parses the Twilio `<Connect><Stream>` WebSocket media stream protocol.
+ *
+ * Twilio sends all messages as JSON-encoded strings.  Outbound audio is
+ * wrapped in the same JSON envelope so Twilio can associate it with the
+ * correct stream.  An explicit `connected` acknowledgment is sent once
+ * immediately after the WebSocket handshake to signal that the listener is
+ * ready to receive media.
+ *
+ * @see {@link https://www.twilio.com/docs/voice/twiml/stream}
+ */
+export class TwilioMediaStreamParser {
+    /**
+     * Parse a raw WebSocket frame from Twilio's media stream.
+     *
+     * Supported Twilio event types:
+     * - `start`  — stream established, includes callSid
+     * - `media`  — audio chunk (inbound track only; outbound chunks are ignored)
+     * - `dtmf`   — DTMF keypress detected
+     * - `stop`   — stream ended
+     * - `mark`   — named synchronisation marker
+     *
+     * @param data - Raw WebSocket frame payload (always a JSON string from Twilio).
+     * @returns Normalised {@link MediaStreamIncoming} event, or `null` for
+     *   outbound audio tracks, unknown event types, or malformed messages.
+     */
+    parseIncoming(data) {
+        const raw = typeof data === 'string' ? data : data.toString('utf8');
+        let msg;
+        try {
+            msg = JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+        const event = msg['event'];
+        const streamSid = msg['streamSid'];
+        if (!event || !streamSid) {
+            return null;
+        }
+        switch (event) {
+            case 'start': {
+                const startPayload = msg['start'];
+                const callSid = startPayload?.['callSid'] ?? '';
+                const result = {
+                    type: 'start',
+                    streamSid,
+                    callSid,
+                    metadata: startPayload,
+                };
+                return result;
+            }
+            case 'media': {
+                const media = msg['media'];
+                if (!media)
+                    return null;
+                // Only process inbound audio — outbound echoes must be discarded.
+                const track = media['track'];
+                if (track === 'outbound')
+                    return null;
+                const payloadB64 = media['payload'];
+                if (!payloadB64)
+                    return null;
+                const sequenceNumber = typeof msg['sequenceNumber'] === 'number'
+                    ? msg['sequenceNumber']
+                    : undefined;
+                const result = {
+                    type: 'audio',
+                    payload: Buffer.from(payloadB64, 'base64'),
+                    streamSid,
+                    ...(sequenceNumber !== undefined ? { sequenceNumber } : {}),
+                };
+                return result;
+            }
+            case 'dtmf': {
+                const dtmf = msg['dtmf'];
+                if (!dtmf)
+                    return null;
+                const digit = dtmf['digit'];
+                if (!digit)
+                    return null;
+                const duration = typeof dtmf['duration'] === 'number'
+                    ? dtmf['duration']
+                    : undefined;
+                const result = {
+                    type: 'dtmf',
+                    digit,
+                    streamSid,
+                    ...(duration !== undefined ? { durationMs: duration } : {}),
+                };
+                return result;
+            }
+            case 'stop': {
+                const result = { type: 'stop', streamSid };
+                return result;
+            }
+            case 'mark': {
+                const mark = msg['mark'];
+                if (!mark)
+                    return null;
+                const name = mark['name'];
+                if (!name)
+                    return null;
+                const result = { type: 'mark', name, streamSid };
+                return result;
+            }
+            default:
+                return null;
+        }
+    }
+    /**
+     * Encode mu-law audio for transmission back to the Twilio stream.
+     *
+     * Twilio requires base64-encoded audio wrapped in a JSON `media` envelope
+     * so it can route the audio to the correct stream.
+     *
+     * @param audio - Raw mu-law PCM bytes to send to the caller.
+     * @param streamSid - The stream identifier to include in the envelope.
+     * @returns JSON string conforming to the Twilio media-out envelope format.
+     */
+    formatOutgoing(audio, streamSid) {
+        return JSON.stringify({
+            event: 'media',
+            streamSid,
+            media: { payload: audio.toString('base64') },
+        });
+    }
+    /**
+     * Generate the initial `connected` acknowledgment expected by Twilio
+     * immediately after the WebSocket connection is established.
+     *
+     * @param _streamSid - Unused — Twilio does not require the stream ID in the
+     *   `connected` message, but the parameter is accepted for interface parity.
+     * @returns JSON string with the `connected` envelope.
+     */
+    formatConnected(_streamSid) {
+        return JSON.stringify({
+            event: 'connected',
+            protocol: 'Call',
+            version: '1.0.0',
+        });
+    }
+}
+//# sourceMappingURL=TwilioMediaStreamParser.js.map

package/dist/voice/parsers/TwilioMediaStreamParser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TwilioMediaStreamParser.js","sourceRoot":"","sources":["../../../src/voice/parsers/TwilioMediaStreamParser.ts"],"names":[],"mappings":"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"}

package/dist/voice/providers/plivo.d.ts

@@ -0,0 +1,77 @@
+/**
+ * @fileoverview Plivo telephony provider for AgentOS voice calls.
+ *
+ * Implements {@link IVoiceCallProvider} using the Plivo Voice REST API v1.
+ * Webhook verification uses HMAC-SHA256 with the v3 signature scheme.
+ *
+ * @module @framers/agentos/voice/providers/plivo
+ */
+import type { IVoiceCallProvider, InitiateCallInput, InitiateCallResult, HangupCallInput, PlayTtsInput } from '../IVoiceCallProvider.js';
+import type { WebhookContext, WebhookVerificationResult, WebhookParseResult } from '../types.js';
+/** Configuration for {@link PlivoVoiceProvider}. */
+export interface PlivoVoiceProviderConfig {
+    /** Plivo Auth ID (account identifier). */
+    authId: string;
+    /** Plivo Auth Token. */
+    authToken: string;
+    /**
+     * Optional fetch override — inject a mock in tests.
+     * Defaults to the global `fetch`.
+     */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Plivo voice call provider.
+ *
+ * Uses the Plivo REST API v1 for outbound call control and HMAC-SHA256
+ * for inbound webhook signature verification (v3 signature scheme).
+ *
+ * @example
+ * ```typescript
+ * const provider = new PlivoVoiceProvider({
+ *   authId:    process.env.PLIVO_AUTH_ID!,
+ *   authToken: process.env.PLIVO_AUTH_TOKEN!,
+ * });
+ * ```
+ */
+export declare class PlivoVoiceProvider implements IVoiceCallProvider {
+    readonly name: "plivo";
+    private readonly config;
+    private readonly baseUrl;
+    private readonly authHeader;
+    private readonly fetch;
+    constructor(config: PlivoVoiceProviderConfig);
+    /**
+     * Verify an incoming Plivo webhook request using HMAC-SHA256 (v3 scheme).
+     *
+     * Plivo signs the concatenation of the full request URL and the nonce
+     * header value. The resulting base64-encoded digest is compared against
+     * the `x-plivo-signature-v3` header.
+     */
+    verifyWebhook(ctx: WebhookContext): WebhookVerificationResult;
+    /**
+     * Parse a Plivo webhook body into normalized {@link NormalizedCallEvent}s.
+     *
+     * Supports both URL-encoded and JSON request bodies. Maps `CallStatus`
+     * parameter values to call lifecycle events.
+     */
+    parseWebhookEvent(ctx: WebhookContext): WebhookParseResult;
+    /**
+     * Initiate an outbound call via the Plivo Call API.
+     *
+     * POSTs a JSON body to `/Account/{authId}/Call/` with the caller, callee,
+     * and answer URL. Returns the `request_uuid` as the provider call ID.
+     */
+    initiateCall(input: InitiateCallInput): Promise<InitiateCallResult>;
+    /**
+     * Hang up an active call using the Plivo Call DELETE endpoint.
+     */
+    hangupCall(input: HangupCallInput): Promise<void>;
+    /**
+     * Speak text into a live call using the Plivo Speak API.
+     *
+     * Defaults to `WOMAN` voice and `en-US` language when not specified.
+     */
+    playTts(input: PlayTtsInput): Promise<void>;
+}
+//# sourceMappingURL=plivo.d.ts.map

package/dist/voice/providers/plivo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plivo.d.ts","sourceRoot":"","sources":["../../../src/voice/providers/plivo.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EACV,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EACf,YAAY,EACb,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,EACV,cAAc,EACd,yBAAyB,EACzB,kBAAkB,EAEnB,MAAM,aAAa,CAAC;AAMrB,oDAAoD;AACpD,MAAM,WAAW,wBAAwB;IACvC,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAC;IACf,wBAAwB;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAMD;;;;;;;;;;;;;GAaG;AACH,qBAAa,kBAAmB,YAAW,kBAAkB;IAC3D,QAAQ,CAAC,IAAI,EAAG,OAAO,CAAU;IAEjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA2B;IAClD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;gBAEzB,MAAM,EAAE,wBAAwB;IAU5C;;;;;;OAMG;IACH,aAAa,CAAC,GAAG,EAAE,cAAc,GAAG,yBAAyB;IAkB7D;;;;;OAKG;IACH,iBAAiB,CAAC,GAAG,EAAE,cAAc,GAAG,kBAAkB;IA8D1D;;;;;OAKG;IACG,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IA0BzE;;OAEG;IACG,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAWvD;;;;OAIG;IACG,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;CAgBlD"}

package/dist/voice/providers/plivo.js

@@ -0,0 +1,180 @@
+/**
+ * @fileoverview Plivo telephony provider for AgentOS voice calls.
+ *
+ * Implements {@link IVoiceCallProvider} using the Plivo Voice REST API v1.
+ * Webhook verification uses HMAC-SHA256 with the v3 signature scheme.
+ *
+ * @module @framers/agentos/voice/providers/plivo
+ */
+import { createHmac, randomUUID } from 'node:crypto';
+// ============================================================================
+// PlivoVoiceProvider
+// ============================================================================
+/**
+ * Plivo voice call provider.
+ *
+ * Uses the Plivo REST API v1 for outbound call control and HMAC-SHA256
+ * for inbound webhook signature verification (v3 signature scheme).
+ *
+ * @example
+ * ```typescript
+ * const provider = new PlivoVoiceProvider({
+ *   authId:    process.env.PLIVO_AUTH_ID!,
+ *   authToken: process.env.PLIVO_AUTH_TOKEN!,
+ * });
+ * ```
+ */
+export class PlivoVoiceProvider {
+    constructor(config) {
+        this.name = 'plivo';
+        this.config = config;
+        this.baseUrl = 'https://api.plivo.com/v1';
+        this.authHeader =
+            'Basic ' + Buffer.from(`${config.authId}:${config.authToken}`).toString('base64');
+        this.fetch = config.fetchImpl ?? globalThis.fetch;
+    }
+    // ── Webhook ───────────────────────────────────────────────────────────────
+    /**
+     * Verify an incoming Plivo webhook request using HMAC-SHA256 (v3 scheme).
+     *
+     * Plivo signs the concatenation of the full request URL and the nonce
+     * header value. The resulting base64-encoded digest is compared against
+     * the `x-plivo-signature-v3` header.
+     */
+    verifyWebhook(ctx) {
+        const nonce = ctx.headers['x-plivo-signature-v3-nonce'];
+        const signature = ctx.headers['x-plivo-signature-v3'];
+        if (Array.isArray(nonce) || Array.isArray(signature)) {
+            return { valid: false, error: 'Duplicate Plivo signature headers' };
+        }
+        const nonceStr = nonce ?? '';
+        const data = ctx.url + nonceStr;
+        const expected = createHmac('sha256', this.config.authToken)
+            .update(data)
+            .digest('base64');
+        const valid = expected === signature;
+        return { valid };
+    }
+    /**
+     * Parse a Plivo webhook body into normalized {@link NormalizedCallEvent}s.
+     *
+     * Supports both URL-encoded and JSON request bodies. Maps `CallStatus`
+     * parameter values to call lifecycle events.
+     */
+    parseWebhookEvent(ctx) {
+        const body = ctx.body.toString();
+        let params;
+        // Plivo sends URL-encoded bodies for most events; try JSON as fallback.
+        try {
+            if (body.trimStart().startsWith('{')) {
+                const obj = JSON.parse(body);
+                params = new URLSearchParams(obj);
+            }
+            else {
+                params = new URLSearchParams(body);
+            }
+        }
+        catch {
+            params = new URLSearchParams(body);
+        }
+        const callUuid = params.get('CallUUID') ?? params.get('call_uuid') ?? '';
+        const callStatus = params.get('CallStatus') ?? params.get('call_status') ?? '';
+        const digits = params.get('Digits');
+        const timestamp = Date.now();
+        const events = [];
+        const base = () => ({
+            eventId: randomUUID(),
+            providerCallId: callUuid,
+            timestamp,
+        });
+        switch (callStatus) {
+            case 'ringing':
+                events.push({ ...base(), kind: 'call-ringing' });
+                break;
+            case 'in-progress':
+                events.push({ ...base(), kind: 'call-answered' });
+                break;
+            case 'completed':
+                events.push({ ...base(), kind: 'call-completed' });
+                break;
+            case 'busy':
+                events.push({ ...base(), kind: 'call-busy' });
+                break;
+            case 'no-answer':
+                events.push({ ...base(), kind: 'call-no-answer' });
+                break;
+            case 'failed':
+                events.push({ ...base(), kind: 'call-failed' });
+                break;
+            default:
+                // initiated / queued / etc. — no normalized event emitted
+                break;
+        }
+        if (digits != null && digits !== '') {
+            events.push({ ...base(), kind: 'call-dtmf', digit: digits });
+        }
+        return { events };
+    }
+    // ── Call Control ──────────────────────────────────────────────────────────
+    /**
+     * Initiate an outbound call via the Plivo Call API.
+     *
+     * POSTs a JSON body to `/Account/{authId}/Call/` with the caller, callee,
+     * and answer URL. Returns the `request_uuid` as the provider call ID.
+     */
+    async initiateCall(input) {
+        const url = `${this.baseUrl}/Account/${this.config.authId}/Call/`;
+        const response = await this.fetch(url, {
+            method: 'POST',
+            headers: {
+                Authorization: this.authHeader,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                from: input.fromNumber,
+                to: input.toNumber,
+                answer_url: input.webhookUrl,
+                answer_method: 'POST',
+            }),
+        });
+        if (!response.ok) {
+            const text = await response.text().catch(() => String(response.status));
+            return { providerCallId: '', success: false, error: `Plivo error ${response.status}: ${text}` };
+        }
+        const data = (await response.json());
+        return { providerCallId: data.request_uuid, success: true };
+    }
+    /**
+     * Hang up an active call using the Plivo Call DELETE endpoint.
+     */
+    async hangupCall(input) {
+        const url = `${this.baseUrl}/Account/${this.config.authId}/Call/${input.providerCallId}/`;
+        await this.fetch(url, {
+            method: 'DELETE',
+            headers: {
+                Authorization: this.authHeader,
+            },
+        });
+    }
+    /**
+     * Speak text into a live call using the Plivo Speak API.
+     *
+     * Defaults to `WOMAN` voice and `en-US` language when not specified.
+     */
+    async playTts(input) {
+        const url = `${this.baseUrl}/Account/${this.config.authId}/Call/${input.providerCallId}/Speak/`;
+        await this.fetch(url, {
+            method: 'POST',
+            headers: {
+                Authorization: this.authHeader,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                text: input.text,
+                voice: input.voice ?? 'WOMAN',
+                language: 'en-US',
+            }),
+        });
+    }
+}
+//# sourceMappingURL=plivo.js.map

package/dist/voice/providers/plivo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plivo.js","sourceRoot":"","sources":["../../../src/voice/providers/plivo.ts"],"names":[],"mappings":"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"}

package/dist/voice/providers/telnyx.d.ts

@@ -0,0 +1,93 @@
+/**
+ * @fileoverview Telnyx telephony provider for AgentOS voice calls.
+ *
+ * Implements {@link IVoiceCallProvider} using the Telnyx Call Control v2 API.
+ * Webhook verification uses Ed25519 public key verification as specified in
+ * the Telnyx security documentation.
+ *
+ * @module @framers/agentos/voice/providers/telnyx
+ */
+import type { IVoiceCallProvider, InitiateCallInput, InitiateCallResult, HangupCallInput, PlayTtsInput } from '../IVoiceCallProvider.js';
+import type { WebhookContext, WebhookVerificationResult, WebhookParseResult } from '../types.js';
+/** Configuration for {@link TelnyxVoiceProvider}. */
+export interface TelnyxVoiceProviderConfig {
+    /** Telnyx API key (starts with "KEY"). */
+    apiKey: string;
+    /** Telnyx connection/application ID for call routing. */
+    connectionId: string;
+    /**
+     * Base64-encoded DER-encoded SPKI Ed25519 public key for webhook verification.
+     * When omitted, webhook verification is skipped.
+     */
+    publicKey?: string;
+    /**
+     * Optional fetch override — inject a mock in tests.
+     * Defaults to the global `fetch`.
+     */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Telnyx voice call provider.
+ *
+ * Uses the Telnyx Call Control v2 API for outbound call initiation and
+ * in-call actions (hangup, speak). Webhook verification uses Ed25519 public
+ * key signing.
+ *
+ * @example
+ * ```typescript
+ * const provider = new TelnyxVoiceProvider({
+ *   apiKey:       process.env.TELNYX_API_KEY!,
+ *   connectionId: process.env.TELNYX_CONNECTION_ID!,
+ *   publicKey:    process.env.TELNYX_PUBLIC_KEY,   // optional
+ * });
+ * ```
+ */
+export declare class TelnyxVoiceProvider implements IVoiceCallProvider {
+    readonly name: "telnyx";
+    private readonly config;
+    private readonly baseUrl;
+    private readonly authHeader;
+    private readonly fetch;
+    constructor(config: TelnyxVoiceProviderConfig);
+    /**
+     * Verify an incoming Telnyx webhook using Ed25519 signature verification.
+     *
+     * Telnyx signs `{timestamp}|{rawBody}` with the configured Ed25519 private key.
+     * The matching public key is provided as a base64-encoded DER SPKI blob.
+     *
+     * If no public key is configured, the check is skipped and `valid: true`
+     * is returned so the provider can operate without cryptographic validation
+     * during initial development.
+     */
+    verifyWebhook(ctx: WebhookContext): WebhookVerificationResult;
+    /**
+     * Parse a Telnyx webhook JSON body into normalized {@link NormalizedCallEvent}s.
+     *
+     * Handles Telnyx Call Control event types:
+     * - `call.initiated` → `call-ringing`
+     * - `call.answered` → `call-answered`
+     * - `call.hangup` → `call-completed` or `call-hangup-user` based on hangup_cause
+     * - `call.dtmf.received` → `call-dtmf`
+     * - `call.machine.detection.ended` with `result === 'machine'` → `call-voicemail`
+     */
+    parseWebhookEvent(ctx: WebhookContext): WebhookParseResult;
+    /**
+     * Initiate an outbound call via the Telnyx Call Control v2 API.
+     *
+     * POSTs to `/calls` with a JSON body. The `mediaStreamUrl` (if provided)
+     * is stored internally for use after the call is answered — it is NOT sent
+     * in the initial call creation request.
+     */
+    initiateCall(input: InitiateCallInput): Promise<InitiateCallResult>;
+    /**
+     * Hang up an active call via the Telnyx Call Control hangup action.
+     */
+    hangupCall(input: HangupCallInput): Promise<void>;
+    /**
+     * Speak text into a live call using Telnyx's text-to-speech speak action.
+     *
+     * Defaults to `female` voice and `en-US` language when not specified.
+     */
+    playTts(input: PlayTtsInput): Promise<void>;
+}
+//# sourceMappingURL=telnyx.d.ts.map

package/dist/voice/providers/telnyx.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telnyx.d.ts","sourceRoot":"","sources":["../../../src/voice/providers/telnyx.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,KAAK,EACV,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EACf,YAAY,EACb,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,EACV,cAAc,EACd,yBAAyB,EACzB,kBAAkB,EAEnB,MAAM,aAAa,CAAC;AAMrB,qDAAqD;AACrD,MAAM,WAAW,yBAAyB;IACxC,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAC;IACf,yDAAyD;IACzD,YAAY,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAyBD;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,mBAAoB,YAAW,kBAAkB;IAC5D,QAAQ,CAAC,IAAI,EAAG,QAAQ,CAAU;IAElC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA4B;IACnD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;gBAEzB,MAAM,EAAE,yBAAyB;IAS7C;;;;;;;;;OASG;IACH,aAAa,CAAC,GAAG,EAAE,cAAc,GAAG,yBAAyB;IAgC7D;;;;;;;;;OASG;IACH,iBAAiB,CAAC,GAAG,EAAE,cAAc,GAAG,kBAAkB;IAyD1D;;;;;;OAMG;IACG,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IA0BzE;;OAEG;IACG,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAavD;;;;OAIG;IACG,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;CAgBlD"}