@framers/agentos 0.1.74 → 0.1.76

package/dist/voice/providers/telnyx.js

@@ -0,0 +1,193 @@
+/**
+ * @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 { verify } from 'node:crypto';
+import { randomUUID } from 'node:crypto';
+// ============================================================================
+// TelnyxVoiceProvider
+// ============================================================================
+/**
+ * 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 class TelnyxVoiceProvider {
+    constructor(config) {
+        this.name = 'telnyx';
+        this.config = config;
+        this.baseUrl = 'https://api.telnyx.com/v2';
+        this.authHeader = `Bearer ${config.apiKey}`;
+        this.fetch = config.fetchImpl ?? globalThis.fetch;
+    }
+    // ── Webhook ───────────────────────────────────────────────────────────────
+    /**
+     * 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) {
+        if (!this.config.publicKey) {
+            return { valid: true };
+        }
+        const timestamp = ctx.headers['x-telnyx-timestamp'];
+        const sigHeader = ctx.headers['x-telnyx-signature-ed25519'];
+        if (!timestamp || Array.isArray(timestamp) || !sigHeader || Array.isArray(sigHeader)) {
+            return { valid: false, error: 'Missing Telnyx signature headers' };
+        }
+        const signature = Buffer.from(sigHeader, 'base64');
+        const payload = Buffer.from(`${timestamp}|${ctx.body.toString()}`);
+        try {
+            const valid = verify(null, payload, {
+                key: Buffer.from(this.config.publicKey, 'base64'),
+                format: 'der',
+                type: 'spki',
+            }, signature);
+            return { valid };
+        }
+        catch {
+            return { valid: false, error: 'Verification failed' };
+        }
+    }
+    /**
+     * 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) {
+        let parsed;
+        try {
+            parsed = JSON.parse(ctx.body.toString());
+        }
+        catch {
+            return { events: [] };
+        }
+        const { event_type, payload } = parsed.data;
+        const providerCallId = payload.call_control_id ?? '';
+        const timestamp = Date.now();
+        const events = [];
+        const base = () => ({ eventId: randomUUID(), providerCallId, timestamp });
+        switch (event_type) {
+            case 'call.initiated':
+                events.push({ ...base(), kind: 'call-ringing' });
+                break;
+            case 'call.answered':
+                events.push({ ...base(), kind: 'call-answered' });
+                break;
+            case 'call.hangup': {
+                // Distinguish user-initiated hangup from normal completion
+                const cause = payload.hangup_cause ?? '';
+                const kind = cause === 'user_busy' || cause === 'normal_clearing' || cause === 'originator_cancel'
+                    ? 'call-hangup-user'
+                    : 'call-completed';
+                events.push({ ...base(), kind });
+                break;
+            }
+            case 'call.dtmf.received': {
+                const digit = payload.digit ?? '';
+                events.push({ ...base(), kind: 'call-dtmf', digit });
+                break;
+            }
+            case 'call.machine.detection.ended':
+                if (payload.result === 'machine') {
+                    events.push({ ...base(), kind: 'call-voicemail' });
+                }
+                break;
+            default:
+                // Unrecognized event type — emit nothing
+                break;
+        }
+        return { events };
+    }
+    // ── Call Control ──────────────────────────────────────────────────────────
+    /**
+     * 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.
+     */
+    async initiateCall(input) {
+        const url = `${this.baseUrl}/calls`;
+        const response = await this.fetch(url, {
+            method: 'POST',
+            headers: {
+                Authorization: this.authHeader,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                connection_id: this.config.connectionId,
+                to: input.toNumber,
+                from: input.fromNumber,
+                webhook_url: input.webhookUrl,
+            }),
+        });
+        if (!response.ok) {
+            const text = await response.text().catch(() => String(response.status));
+            return { providerCallId: '', success: false, error: `Telnyx error ${response.status}: ${text}` };
+        }
+        const data = (await response.json());
+        return { providerCallId: data.data.call_control_id, success: true };
+    }
+    /**
+     * Hang up an active call via the Telnyx Call Control hangup action.
+     */
+    async hangupCall(input) {
+        const url = `${this.baseUrl}/calls/${input.providerCallId}/actions/hangup`;
+        await this.fetch(url, {
+            method: 'POST',
+            headers: {
+                Authorization: this.authHeader,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({}),
+        });
+    }
+    /**
+     * 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.
+     */
+    async playTts(input) {
+        const url = `${this.baseUrl}/calls/${input.providerCallId}/actions/speak`;
+        await this.fetch(url, {
+            method: 'POST',
+            headers: {
+                Authorization: this.authHeader,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                payload: input.text,
+                voice: input.voice ?? 'female',
+                language: 'en-US',
+            }),
+        });
+    }
+}
+//# sourceMappingURL=telnyx.js.map

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

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

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

@@ -0,0 +1,79 @@
+/**
+ * @fileoverview Twilio telephony provider for AgentOS voice calls.
+ *
+ * Implements {@link IVoiceCallProvider} using the Twilio REST API v2010-04-01.
+ * Webhook verification uses HMAC-SHA1 per Twilio's security documentation.
+ *
+ * @module @framers/agentos/voice/providers/twilio
+ */
+import type { IVoiceCallProvider, InitiateCallInput, InitiateCallResult, HangupCallInput, PlayTtsInput } from '../IVoiceCallProvider.js';
+import type { WebhookContext, WebhookVerificationResult, WebhookParseResult } from '../types.js';
+/** Configuration for {@link TwilioVoiceProvider}. */
+export interface TwilioVoiceProviderConfig {
+    /** Twilio Account SID (starts with "AC"). */
+    accountSid: string;
+    /** Twilio Auth Token. */
+    authToken: string;
+    /**
+     * Optional fetch override — inject a mock in tests.
+     * Defaults to the global `fetch`.
+     */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Twilio voice call provider.
+ *
+ * Uses the Twilio REST API 2010-04-01 for outbound call control and
+ * HMAC-SHA1 for inbound webhook signature verification.
+ *
+ * @example
+ * ```typescript
+ * const provider = new TwilioVoiceProvider({
+ *   accountSid: process.env.TWILIO_ACCOUNT_SID!,
+ *   authToken:  process.env.TWILIO_AUTH_TOKEN!,
+ * });
+ * ```
+ */
+export declare class TwilioVoiceProvider implements IVoiceCallProvider {
+    readonly name: "twilio";
+    private readonly config;
+    private readonly baseUrl;
+    private readonly authHeader;
+    private readonly fetch;
+    constructor(config: TwilioVoiceProviderConfig);
+    /**
+     * Verify an incoming Twilio webhook request using HMAC-SHA1.
+     *
+     * Twilio constructs the signed data by appending all POST params (sorted
+     * alphabetically) as key+value pairs directly to the full request URL.
+     */
+    verifyWebhook(ctx: WebhookContext): WebhookVerificationResult;
+    /**
+     * Parse a Twilio webhook body into normalized {@link NormalizedCallEvent}s.
+     *
+     * Handles call status transitions (ringing, in-progress, completed, failed,
+     * busy, no-answer, canceled) and DTMF input.
+     */
+    parseWebhookEvent(ctx: WebhookContext): WebhookParseResult;
+    /**
+     * Initiate an outbound call via the Twilio Calls API.
+     *
+     * Posts to `/Accounts/{accountSid}/Calls.json` with form-encoded body.
+     * All four status callback events (initiated, ringing, answered, completed)
+     * are requested.
+     */
+    initiateCall(input: InitiateCallInput): Promise<InitiateCallResult>;
+    /**
+     * Hang up an active call by posting `Status=completed`.
+     */
+    hangupCall(input: HangupCallInput): Promise<void>;
+    /**
+     * Inject TTS into a live call using a TwiML `<Say>` verb.
+     *
+     * Sends a `Twiml` parameter containing a minimal `<Response><Say>` document.
+     * The optional `voice` attribute maps to Twilio's built-in voice names
+     * (e.g., `alice`, `Polly.Joanna`).
+     */
+    playTts(input: PlayTtsInput): Promise<void>;
+}
+//# sourceMappingURL=twilio.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"twilio.d.ts","sourceRoot":"","sources":["../../../src/voice/providers/twilio.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;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,6CAA6C;IAC7C,UAAU,EAAE,MAAM,CAAC;IACnB,yBAAyB;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAMD;;;;;;;;;;;;;GAaG;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;IAW7C;;;;;OAKG;IACH,aAAa,CAAC,GAAG,EAAE,cAAc,GAAG,yBAAyB;IAyB7D;;;;;OAKG;IACH,iBAAiB,CAAC,GAAG,EAAE,cAAc,GAAG,kBAAkB;IAyD1D;;;;;;OAMG;IACG,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAgCzE;;OAEG;IACG,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAavD;;;;;;OAMG;IACG,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;CAelD"}

package/dist/voice/providers/twilio.js

@@ -0,0 +1,191 @@
+/**
+ * @fileoverview Twilio telephony provider for AgentOS voice calls.
+ *
+ * Implements {@link IVoiceCallProvider} using the Twilio REST API v2010-04-01.
+ * Webhook verification uses HMAC-SHA1 per Twilio's security documentation.
+ *
+ * @module @framers/agentos/voice/providers/twilio
+ */
+import { createHmac } from 'node:crypto';
+import { randomUUID } from 'node:crypto';
+// ============================================================================
+// TwilioVoiceProvider
+// ============================================================================
+/**
+ * Twilio voice call provider.
+ *
+ * Uses the Twilio REST API 2010-04-01 for outbound call control and
+ * HMAC-SHA1 for inbound webhook signature verification.
+ *
+ * @example
+ * ```typescript
+ * const provider = new TwilioVoiceProvider({
+ *   accountSid: process.env.TWILIO_ACCOUNT_SID!,
+ *   authToken:  process.env.TWILIO_AUTH_TOKEN!,
+ * });
+ * ```
+ */
+export class TwilioVoiceProvider {
+    constructor(config) {
+        this.name = 'twilio';
+        this.config = config;
+        this.baseUrl = 'https://api.twilio.com/2010-04-01';
+        this.authHeader =
+            'Basic ' +
+                Buffer.from(`${config.accountSid}:${config.authToken}`).toString('base64');
+        this.fetch = config.fetchImpl ?? globalThis.fetch;
+    }
+    // ── Webhook ───────────────────────────────────────────────────────────────
+    /**
+     * Verify an incoming Twilio webhook request using HMAC-SHA1.
+     *
+     * Twilio constructs the signed data by appending all POST params (sorted
+     * alphabetically) as key+value pairs directly to the full request URL.
+     */
+    verifyWebhook(ctx) {
+        const signature = ctx.headers['x-twilio-signature'];
+        if (!signature || Array.isArray(signature)) {
+            return { valid: false, error: 'Missing x-twilio-signature header' };
+        }
+        // Build the signed data string
+        const bodyParams = new URLSearchParams(ctx.body.toString());
+        const sorted = [...bodyParams.entries()].sort(([a], [b]) => a.localeCompare(b));
+        let data = ctx.url;
+        for (const [key, value] of sorted) {
+            data += key + value;
+        }
+        const expected = createHmac('sha1', this.config.authToken)
+            .update(data)
+            .digest('base64');
+        const valid = expected === signature;
+        return {
+            valid,
+            ...(valid ? {} : { error: 'Signature mismatch' }),
+        };
+    }
+    /**
+     * Parse a Twilio webhook body into normalized {@link NormalizedCallEvent}s.
+     *
+     * Handles call status transitions (ringing, in-progress, completed, failed,
+     * busy, no-answer, canceled) and DTMF input.
+     */
+    parseWebhookEvent(ctx) {
+        const params = new URLSearchParams(ctx.body.toString());
+        const callSid = params.get('CallSid') ?? '';
+        const callStatus = params.get('CallStatus') ?? '';
+        const digits = params.get('Digits');
+        const timestamp = Date.now();
+        const events = [];
+        /** Helper: shared base fields. */
+        const base = () => ({
+            eventId: randomUUID(),
+            providerCallId: callSid,
+            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 'failed':
+                events.push({ ...base(), kind: 'call-failed' });
+                break;
+            case 'busy':
+                events.push({ ...base(), kind: 'call-busy' });
+                break;
+            case 'no-answer':
+                events.push({ ...base(), kind: 'call-no-answer' });
+                break;
+            case 'canceled':
+                events.push({ ...base(), kind: 'call-hangup-user' });
+                break;
+            default:
+                // initiated / queued / etc. — no normalized event emitted
+                break;
+        }
+        // DTMF digit input
+        if (digits != null && digits !== '') {
+            events.push({
+                ...base(),
+                kind: 'call-dtmf',
+                digit: digits,
+            });
+        }
+        return { events };
+    }
+    // ── Call Control ──────────────────────────────────────────────────────────
+    /**
+     * Initiate an outbound call via the Twilio Calls API.
+     *
+     * Posts to `/Accounts/{accountSid}/Calls.json` with form-encoded body.
+     * All four status callback events (initiated, ringing, answered, completed)
+     * are requested.
+     */
+    async initiateCall(input) {
+        const url = `${this.baseUrl}/Accounts/${this.config.accountSid}/Calls.json`;
+        const body = [
+            `To=${encodeURIComponent(input.toNumber)}`,
+            `From=${encodeURIComponent(input.fromNumber)}`,
+            `Url=${encodeURIComponent(input.webhookUrl)}`,
+            `StatusCallback=${encodeURIComponent(input.statusCallbackUrl ?? '')}`,
+            `StatusCallbackEvent=initiated`,
+            `StatusCallbackEvent=ringing`,
+            `StatusCallbackEvent=answered`,
+            `StatusCallbackEvent=completed`,
+        ].join('&');
+        const response = await this.fetch(url, {
+            method: 'POST',
+            headers: {
+                Authorization: this.authHeader,
+                'Content-Type': 'application/x-www-form-urlencoded',
+            },
+            body,
+        });
+        if (!response.ok) {
+            const text = await response.text().catch(() => String(response.status));
+            return { providerCallId: '', success: false, error: `Twilio error ${response.status}: ${text}` };
+        }
+        const data = (await response.json());
+        return { providerCallId: data.sid, success: true };
+    }
+    /**
+     * Hang up an active call by posting `Status=completed`.
+     */
+    async hangupCall(input) {
+        const url = `${this.baseUrl}/Accounts/${this.config.accountSid}/Calls/${input.providerCallId}.json`;
+        await this.fetch(url, {
+            method: 'POST',
+            headers: {
+                Authorization: this.authHeader,
+                'Content-Type': 'application/x-www-form-urlencoded',
+            },
+            body: 'Status=completed',
+        });
+    }
+    /**
+     * Inject TTS into a live call using a TwiML `<Say>` verb.
+     *
+     * Sends a `Twiml` parameter containing a minimal `<Response><Say>` document.
+     * The optional `voice` attribute maps to Twilio's built-in voice names
+     * (e.g., `alice`, `Polly.Joanna`).
+     */
+    async playTts(input) {
+        const url = `${this.baseUrl}/Accounts/${this.config.accountSid}/Calls/${input.providerCallId}.json`;
+        const voiceAttr = input.voice ? ` voice="${input.voice}"` : '';
+        const twiml = `<Response><Say${voiceAttr}>${input.text}</Say></Response>`;
+        await this.fetch(url, {
+            method: 'POST',
+            headers: {
+                Authorization: this.authHeader,
+                'Content-Type': 'application/x-www-form-urlencoded',
+            },
+            body: `Twiml=${encodeURIComponent(twiml)}`,
+        });
+    }
+}
+//# sourceMappingURL=twilio.js.map

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

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

package/dist/voice/twiml.d.ts

@@ -0,0 +1,69 @@
+/**
+ * @fileoverview TwiML and XML generation helpers for telephony providers.
+ *
+ * Generates provider-specific XML/TwiML response payloads for Twilio, Telnyx,
+ * and Plivo. All text content and attribute values are XML-escaped to prevent
+ * injection or malformed markup.
+ *
+ * @module @framers/agentos/voice/twiml
+ */
+/**
+ * Generate TwiML for Twilio conversation mode using a bidirectional media stream.
+ *
+ * The returned markup instructs Twilio to open a WebSocket to `streamUrl` and
+ * stream audio in both directions for the duration of the call.
+ *
+ * @param streamUrl - WebSocket URL Twilio should connect to (e.g. `wss://…/stream`).
+ * @param token - Optional bearer token appended as a `?token=` query parameter.
+ * @returns A complete TwiML XML document string.
+ *
+ * @example
+ * ```typescript
+ * res.type('text/xml').send(twilioConversationTwiml('wss://api.example.com/call', jwtToken));
+ * ```
+ */
+export declare function twilioConversationTwiml(streamUrl: string, token?: string): string;
+/**
+ * Generate TwiML for Twilio notify mode — synthesise `text` over the call then hang up.
+ *
+ * Useful for delivering one-shot announcements (e.g. voicemail greetings, error
+ * messages) without establishing a full media stream.
+ *
+ * @param text - The message to speak to the caller.
+ * @param voice - Optional Twilio voice name (e.g. `'Polly.Joanna'`, `'alice'`).
+ * @returns A complete TwiML XML document string.
+ */
+export declare function twilioNotifyTwiml(text: string, voice?: string): string;
+/**
+ * Generate a Telnyx streaming XML response.
+ *
+ * Telnyx primarily uses a REST API for call control, but this helper produces
+ * an XML acknowledgment document wrapping the stream URL for webhook responses
+ * that require XML.
+ *
+ * @param streamUrl - WebSocket URL Telnyx should stream audio to.
+ * @returns A complete XML document string.
+ */
+export declare function telnyxStreamXml(streamUrl: string): string;
+/**
+ * Generate Plivo bidirectional streaming XML.
+ *
+ * Instructs Plivo to open a bidirectional WebSocket stream and keep the call
+ * alive for the duration of the stream session.
+ *
+ * @param streamUrl - WebSocket URL Plivo should connect to.
+ * @returns A complete Plivo XML document string.
+ */
+export declare function plivoStreamXml(streamUrl: string): string;
+/**
+ * Generate Plivo speak + hangup XML.
+ *
+ * Synthesises `text` to the caller using Plivo's TTS engine and immediately
+ * hangs up after playback completes.
+ *
+ * @param text - The message to speak to the caller.
+ * @param voice - Optional Plivo voice name (e.g. `'WOMAN'`, `'Polly.Joanna'`).
+ * @returns A complete Plivo XML document string.
+ */
+export declare function plivoNotifyXml(text: string, voice?: string): string;
+//# sourceMappingURL=twiml.d.ts.map

package/dist/voice/twiml.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"twiml.d.ts","sourceRoot":"","sources":["../../src/voice/twiml.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAQH;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAGjF;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAGtE;AAMD;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEzD;AAMD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAGnE"}

package/dist/voice/twiml.js

@@ -0,0 +1,92 @@
+/**
+ * @fileoverview TwiML and XML generation helpers for telephony providers.
+ *
+ * Generates provider-specific XML/TwiML response payloads for Twilio, Telnyx,
+ * and Plivo. All text content and attribute values are XML-escaped to prevent
+ * injection or malformed markup.
+ *
+ * @module @framers/agentos/voice/twiml
+ */
+import { escapeXml } from './telephony-audio.js';
+// ============================================================================
+// Twilio TwiML
+// ============================================================================
+/**
+ * Generate TwiML for Twilio conversation mode using a bidirectional media stream.
+ *
+ * The returned markup instructs Twilio to open a WebSocket to `streamUrl` and
+ * stream audio in both directions for the duration of the call.
+ *
+ * @param streamUrl - WebSocket URL Twilio should connect to (e.g. `wss://…/stream`).
+ * @param token - Optional bearer token appended as a `?token=` query parameter.
+ * @returns A complete TwiML XML document string.
+ *
+ * @example
+ * ```typescript
+ * res.type('text/xml').send(twilioConversationTwiml('wss://api.example.com/call', jwtToken));
+ * ```
+ */
+export function twilioConversationTwiml(streamUrl, token) {
+    const url = token ? `${streamUrl}?token=${token}` : streamUrl;
+    return `<?xml version="1.0" encoding="UTF-8"?>\n<Response><Connect><Stream url="${escapeXml(url)}" /></Connect></Response>`;
+}
+/**
+ * Generate TwiML for Twilio notify mode — synthesise `text` over the call then hang up.
+ *
+ * Useful for delivering one-shot announcements (e.g. voicemail greetings, error
+ * messages) without establishing a full media stream.
+ *
+ * @param text - The message to speak to the caller.
+ * @param voice - Optional Twilio voice name (e.g. `'Polly.Joanna'`, `'alice'`).
+ * @returns A complete TwiML XML document string.
+ */
+export function twilioNotifyTwiml(text, voice) {
+    const voiceAttr = voice ? ` voice="${escapeXml(voice)}"` : '';
+    return `<?xml version="1.0" encoding="UTF-8"?>\n<Response><Say${voiceAttr}>${escapeXml(text)}</Say><Hangup/></Response>`;
+}
+// ============================================================================
+// Telnyx XML
+// ============================================================================
+/**
+ * Generate a Telnyx streaming XML response.
+ *
+ * Telnyx primarily uses a REST API for call control, but this helper produces
+ * an XML acknowledgment document wrapping the stream URL for webhook responses
+ * that require XML.
+ *
+ * @param streamUrl - WebSocket URL Telnyx should stream audio to.
+ * @returns A complete XML document string.
+ */
+export function telnyxStreamXml(streamUrl) {
+    return `<?xml version="1.0" encoding="UTF-8"?>\n<Response><Stream url="${escapeXml(streamUrl)}" /></Response>`;
+}
+// ============================================================================
+// Plivo XML
+// ============================================================================
+/**
+ * Generate Plivo bidirectional streaming XML.
+ *
+ * Instructs Plivo to open a bidirectional WebSocket stream and keep the call
+ * alive for the duration of the stream session.
+ *
+ * @param streamUrl - WebSocket URL Plivo should connect to.
+ * @returns A complete Plivo XML document string.
+ */
+export function plivoStreamXml(streamUrl) {
+    return `<?xml version="1.0" encoding="UTF-8"?>\n<Response><Stream bidirectional="true" keepCallAlive="true">${escapeXml(streamUrl)}</Stream></Response>`;
+}
+/**
+ * Generate Plivo speak + hangup XML.
+ *
+ * Synthesises `text` to the caller using Plivo's TTS engine and immediately
+ * hangs up after playback completes.
+ *
+ * @param text - The message to speak to the caller.
+ * @param voice - Optional Plivo voice name (e.g. `'WOMAN'`, `'Polly.Joanna'`).
+ * @returns A complete Plivo XML document string.
+ */
+export function plivoNotifyXml(text, voice) {
+    const voiceAttr = voice ? ` voice="${escapeXml(voice)}"` : '';
+    return `<?xml version="1.0" encoding="UTF-8"?>\n<Response><Speak${voiceAttr}>${escapeXml(text)}</Speak><Hangup/></Response>`;
+}
+//# sourceMappingURL=twiml.js.map

package/dist/voice/twiml.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"twiml.js","sourceRoot":"","sources":["../../src/voice/twiml.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEjD,+EAA+E;AAC/E,eAAe;AACf,+EAA+E;AAE/E;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,uBAAuB,CAAC,SAAiB,EAAE,KAAc;IACvE,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,GAAG,SAAS,UAAU,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IAC9D,OAAO,2EAA2E,SAAS,CAAC,GAAG,CAAC,2BAA2B,CAAC;AAC9H,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY,EAAE,KAAc;IAC5D,MAAM,SAAS,GAAG,KAAK,CAAC,CAAC,CAAC,WAAW,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IAC9D,OAAO,yDAAyD,SAAS,IAAI,SAAS,CAAC,IAAI,CAAC,4BAA4B,CAAC;AAC3H,CAAC;AAED,+EAA+E;AAC/E,aAAa;AACb,+EAA+E;AAE/E;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe,CAAC,SAAiB;IAC/C,OAAO,kEAAkE,SAAS,CAAC,SAAS,CAAC,iBAAiB,CAAC;AACjH,CAAC;AAED,+EAA+E;AAC/E,YAAY;AACZ,+EAA+E;AAE/E;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,SAAiB;IAC9C,OAAO,uGAAuG,SAAS,CAAC,SAAS,CAAC,sBAAsB,CAAC;AAC3J,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,KAAc;IACzD,MAAM,SAAS,GAAG,KAAK,CAAC,CAAC,CAAC,WAAW,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IAC9D,OAAO,2DAA2D,SAAS,IAAI,SAAS,CAAC,IAAI,CAAC,8BAA8B,CAAC;AAC/H,CAAC"}