@framers/agentos 0.1.111 → 0.1.112

package/dist/voice/providers/plivo.js

@@ -2,7 +2,63 @@
  * @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.
+ *
+ * ## REST API contract
+ *
+ * | Operation      | Method | Endpoint                                     | Body format |
+ * |----------------|--------|----------------------------------------------|-------------|
+ * | Initiate call  | POST   | `/v1/Account/{authId}/Call/`                 | JSON        |
+ * | Hangup call    | DELETE | `/v1/Account/{authId}/Call/{callUuid}/`       | (none)      |
+ * | Play TTS       | POST   | `/v1/Account/{authId}/Call/{callUuid}/Speak/` | JSON       |
+ *
+ * All requests use HTTP Basic authentication: `Authorization: Basic base64(authId:authToken)`.
+ *
+ * ### Hangup uses DELETE (not POST)
+ *
+ * Unlike Twilio (which POSTs `Status=completed`) and Telnyx (which POSTs to
+ * an `/actions/hangup` endpoint), Plivo uses the HTTP `DELETE` method on the
+ * Call resource to terminate an active call. This is a RESTful design choice
+ * where "deleting" the call resource means terminating the call.
+ *
+ * ## Webhook verification: HMAC-SHA256 + nonce (v3 scheme)
+ *
+ * Plivo's v3 webhook signature scheme:
+ *
+ * 1. Plivo generates a random `nonce` and includes it in the
+ *    `X-Plivo-Signature-V3-Nonce` header.
+ * 2. The signed data is: `{fullRequestURL}{nonce}` (concatenated, no separator).
+ * 3. Compute `HMAC-SHA256(authToken, signedData)`.
+ * 4. Base64-encode the HMAC digest.
+ * 5. Compare the result with the `X-Plivo-Signature-V3` header.
+ *
+ * Note: Unlike Twilio's scheme, Plivo does NOT include the POST body in the
+ * signed data -- only the URL and nonce. The nonce prevents replay attacks.
+ *
+ * ## DTMF via `<GetDigits>` XML pattern
+ *
+ * Plivo delivers DTMF input through the `<GetDigits>` XML element callback,
+ * not through the media stream WebSocket. When a call executes:
+ *
+ * ```xml
+ * <GetDigits action="https://example.com/dtmf" method="POST" timeout="10">
+ *   <Speak>Press 1 to confirm.</Speak>
+ * </GetDigits>
+ * ```
+ *
+ * Plivo POSTs the pressed digits to the `action` URL with a `Digits`
+ * parameter in the form-encoded body (e.g., `Digits=1&CallUUID=xxx`).
+ *
+ * ## Event mapping table
+ *
+ * | Plivo `CallStatus`  | Normalised `kind`    |
+ * |---------------------|----------------------|
+ * | `ringing`           | `call-ringing`       |
+ * | `in-progress`       | `call-answered`      |
+ * | `completed`         | `call-completed`     |
+ * | `busy`              | `call-busy`          |
+ * | `no-answer`         | `call-no-answer`     |
+ * | `failed`            | `call-failed`        |
+ * | (+ `Digits` param)  | `call-dtmf`          |
  *
  * @module @framers/agentos/voice/providers/plivo
  */
@@ -25,10 +81,15 @@ import { createHmac, randomUUID } from 'node:crypto';
  * ```
  */
 export class PlivoVoiceProvider {
+    /**
+     * @param config - Plivo credentials and optional overrides.
+     */
     constructor(config) {
+        /** Provider identifier, always `'plivo'`. */
         this.name = 'plivo';
         this.config = config;
         this.baseUrl = 'https://api.plivo.com/v1';
+        // Plivo uses HTTP Basic auth with authId:authToken (similar to Twilio).
         this.authHeader =
             'Basic ' + Buffer.from(`${config.authId}:${config.authToken}`).toString('base64');
         this.fetch = config.fetchImpl ?? globalThis.fetch;
@@ -37,9 +98,17 @@ export class PlivoVoiceProvider {
     /**
      * 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.
+     * ## Algorithm (step by step)
+     *
+     * 1. Extract the `X-Plivo-Signature-V3-Nonce` and `X-Plivo-Signature-V3` headers.
+     * 2. Build the signed data string: `{fullRequestURL}{nonce}`.
+     *    Note: the POST body is NOT included in the signed data (unlike Twilio).
+     * 3. Compute `HMAC-SHA256(authToken, signedData)`.
+     * 4. Base64-encode the digest.
+     * 5. Compare with the `X-Plivo-Signature-V3` header.
+     *
+     * @param ctx - Raw webhook request context.
+     * @returns Verification result with `valid: true` if the signature matches.
      */
     verifyWebhook(ctx) {
         const nonce = ctx.headers['x-plivo-signature-v3-nonce'];
@@ -47,6 +116,8 @@ export class PlivoVoiceProvider {
         if (Array.isArray(nonce) || Array.isArray(signature)) {
             return { valid: false, error: 'Duplicate Plivo signature headers' };
         }
+        // Use empty string as nonce fallback when header is missing --
+        // the HMAC will still compute but won't match the expected signature.
         const nonceStr = nonce ?? '';
         const data = ctx.url + nonceStr;
         const expected = createHmac('sha256', this.config.authToken)
@@ -58,8 +129,17 @@ export class PlivoVoiceProvider {
     /**
      * 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.
+     * Plivo sends most webhooks with URL-encoded bodies, but some callbacks
+     * may arrive as JSON. This parser handles both formats by inspecting
+     * whether the body starts with `{` (JSON) or not (form-encoded).
+     *
+     * Plivo uses two naming conventions for the same fields:
+     * - PascalCase (`CallUUID`, `CallStatus`, `Digits`) in URL callbacks.
+     * - snake_case (`call_uuid`, `call_status`) in some API responses.
+     * Both are checked for maximum compatibility.
+     *
+     * @param ctx - Raw webhook request context.
+     * @returns Parsed result containing zero or more normalized events.
      */
     parseWebhookEvent(ctx) {
         const body = ctx.body.toString();
@@ -77,16 +157,19 @@ export class PlivoVoiceProvider {
         catch {
             params = new URLSearchParams(body);
         }
+        // Support both PascalCase and snake_case field naming conventions.
         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 = [];
+        /** Helper: shared base fields with a unique event ID for idempotency. */
         const base = () => ({
             eventId: randomUUID(),
             providerCallId: callUuid,
             timestamp,
         });
+        // Map Plivo CallStatus values to normalized event kinds.
         switch (callStatus) {
             case 'ringing':
                 events.push({ ...base(), kind: 'call-ringing' });
@@ -107,9 +190,10 @@ export class PlivoVoiceProvider {
                 events.push({ ...base(), kind: 'call-failed' });
                 break;
             default:
-                // initiated / queued / etc. — no normalized event emitted
+                // initiated / queued / etc. -- no normalized event emitted.
                 break;
         }
+        // DTMF digit input (from <GetDigits> XML element callback).
         if (digits != null && digits !== '') {
             events.push({ ...base(), kind: 'call-dtmf', digit: digits });
         }
@@ -119,8 +203,12 @@ export class PlivoVoiceProvider {
     /**
      * Initiate an outbound call via the Plivo Call API.
      *
-     * POSTs a JSON body to `/Account/{authId}/Call/` with the caller, callee,
+     * POSTs a JSON body to `/v1/Account/{authId}/Call/` with the caller, callee,
      * and answer URL. Returns the `request_uuid` as the provider call ID.
+     *
+     * @param input - Call initiation parameters (from/to numbers, webhook URL).
+     * @returns Result containing the Plivo `request_uuid` on success.
+     * @throws Never throws; returns `{ success: false, error: '...' }` on failure.
      */
     async initiateCall(input) {
         const url = `${this.baseUrl}/Account/${this.config.authId}/Call/`;
@@ -146,6 +234,12 @@ export class PlivoVoiceProvider {
     }
     /**
      * Hang up an active call using the Plivo Call DELETE endpoint.
+     *
+     * Plivo uses HTTP `DELETE` to terminate a call (unlike Twilio's POST with
+     * `Status=completed` or Telnyx's POST to `/actions/hangup`). This is a
+     * RESTful convention where deleting the call resource ends the call.
+     *
+     * @param input - Contains the Plivo `call_uuid` to hang up.
      */
     async hangupCall(input) {
         const url = `${this.baseUrl}/Account/${this.config.authId}/Call/${input.providerCallId}/`;
@@ -159,7 +253,10 @@ export class PlivoVoiceProvider {
     /**
      * Speak text into a live call using the Plivo Speak API.
      *
-     * Defaults to `WOMAN` voice and `en-US` language when not specified.
+     * POSTs a JSON body to `/v1/Account/{authId}/Call/{callUuid}/Speak/`
+     * with the text, voice (default `'WOMAN'`), and language (default `'en-US'`).
+     *
+     * @param input - TTS parameters (text, optional voice, call ID).
      */
     async playTts(input) {
         const url = `${this.baseUrl}/Account/${this.config.authId}/Call/${input.providerCallId}/Speak/`;

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

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

@@ -2,14 +2,64 @@
  * @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.
+ *
+ * ## REST API contract
+ *
+ * | Operation      | Method | Endpoint                                 | Body format |
+ * |----------------|--------|------------------------------------------|-------------|
+ * | Initiate call  | POST   | `/v2/calls`                              | JSON        |
+ * | Hangup call    | POST   | `/v2/calls/{id}/actions/hangup`          | JSON        |
+ * | Play TTS       | POST   | `/v2/calls/{id}/actions/speak`           | JSON        |
+ * | Start stream   | POST   | `/v2/calls/{id}/actions/streaming_start` | JSON        |
+ *
+ * All requests use Bearer token authentication: `Authorization: Bearer {apiKey}`.
+ * Request bodies are JSON (unlike Twilio's form-encoded convention).
+ *
+ * ## Streaming after `call.answered`
+ *
+ * Telnyx requires a two-step flow for media streaming:
+ * 1. Initiate the call via `POST /v2/calls` with a `webhook_url`.
+ * 2. When the `call.answered` webhook fires, issue a separate
+ *    `POST /v2/calls/{id}/actions/streaming_start` request with the
+ *    WebSocket URL. This is handled by the CallManager, not by this provider.
+ *
+ * ## Webhook verification: Ed25519
+ *
+ * Telnyx signs webhooks using Ed25519 public key cryptography:
+ *
+ * 1. Telnyx generates a signed payload: `{timestamp}|{rawBody}`.
+ * 2. The signature is computed with the account's Ed25519 private key.
+ * 3. The public key is provided as a base64-encoded DER SPKI blob.
+ * 4. Headers: `X-Telnyx-Timestamp` (the timestamp) and
+ *    `X-Telnyx-Signature-Ed25519` (base64-encoded Ed25519 signature).
+ * 5. Verification: decode the signature from base64, construct the payload
+ *    string `{timestamp}|{body}`, and verify using `crypto.verify()` with
+ *    the SPKI public key.
+ *
+ * When no public key is configured, verification is skipped (returns
+ * `valid: true`) to support development environments.
+ *
+ * ## Event mapping table (hangup_cause)
+ *
+ * | Telnyx `event_type`              | `hangup_cause`            | Normalised `kind`    |
+ * |----------------------------------|---------------------------|----------------------|
+ * | `call.initiated`                 | --                        | `call-ringing`       |
+ * | `call.answered`                  | --                        | `call-answered`      |
+ * | `call.hangup`                    | `normal_clearing`         | `call-hangup-user`   |
+ * | `call.hangup`                    | `user_busy`               | `call-hangup-user`   |
+ * | `call.hangup`                    | `originator_cancel`       | `call-hangup-user`   |
+ * | `call.hangup`                    | (anything else)           | `call-completed`     |
+ * | `call.dtmf.received`             | --                        | `call-dtmf`          |
+ * | `call.machine.detection.ended`   | result=`machine`          | `call-voicemail`     |
+ * | `call.machine.detection.ended`   | result=`human`            | (no event)           |
  *
  * @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}. */
+/**
+ * Configuration for {@link TelnyxVoiceProvider}.
+ */
 export interface TelnyxVoiceProviderConfig {
     /** Telnyx API key (starts with "KEY"). */
     apiKey: string;
@@ -17,11 +67,13 @@ export interface TelnyxVoiceProviderConfig {
     connectionId: string;
     /**
      * Base64-encoded DER-encoded SPKI Ed25519 public key for webhook verification.
-     * When omitted, webhook verification is skipped.
+     *
+     * When omitted, webhook verification is skipped (always returns `valid: true`).
+     * This is acceptable for development but should always be set in production.
      */
     publicKey?: string;
     /**
-     * Optional fetch override — inject a mock in tests.
+     * Optional fetch implementation override -- inject a mock in tests.
      * Defaults to the global `fetch`.
      */
     fetchImpl?: typeof fetch;
@@ -43,50 +95,88 @@ export interface TelnyxVoiceProviderConfig {
  * ```
  */
 export declare class TelnyxVoiceProvider implements IVoiceCallProvider {
+    /** Provider identifier, always `'telnyx'`. */
     readonly name: "telnyx";
+    /** Immutable configuration snapshot. */
     private readonly config;
+    /** Base URL for the Telnyx v2 API. */
     private readonly baseUrl;
+    /** Pre-computed `Authorization: Bearer ...` header value. */
     private readonly authHeader;
+    /** HTTP fetch implementation (injectable for testing). */
     private readonly fetch;
+    /**
+     * @param config - Telnyx credentials and optional overrides.
+     */
     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.
+     * ## Algorithm (step by step)
+     *
+     * 1. If no public key is configured, skip verification (return `valid: true`).
+     *    This supports development environments without cryptographic setup.
+     * 2. Extract `X-Telnyx-Timestamp` and `X-Telnyx-Signature-Ed25519` headers.
+     * 3. Decode the signature from base64 into a raw byte Buffer.
+     * 4. Construct the signed payload: `"{timestamp}|{rawBody}"`.
+     * 5. Decode the SPKI public key from base64.
+     * 6. Call `crypto.verify(null, payload, { key, format: 'der', type: 'spki' }, signature)`.
+     * 7. Return the verification result.
      *
-     * 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.
+     * @param ctx - Raw webhook request context.
+     * @returns Verification result. Returns `{ valid: true }` when no public key
+     *   is configured (development mode).
      */
     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`
+     * Telnyx sends all webhook payloads as JSON with a `data.event_type`
+     * discriminant field. The `data.payload` object contains call-specific
+     * fields like `call_control_id`, `hangup_cause`, `digit`, and `result`.
+     *
+     * ## Hangup cause mapping
+     *
+     * Telnyx's `call.hangup` event includes a `hangup_cause` field that must
+     * be inspected to determine whether the user or the system terminated
+     * the call:
+     * - `normal_clearing` / `user_busy` / `originator_cancel` -> `call-hangup-user`
+     * - All other causes (e.g., `call_rejected`, `unallocated_number`) -> `call-completed`
+     *
+     * @param ctx - Raw webhook request context.
+     * @returns Parsed result containing zero or more normalized events.
      */
     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.
+     * POSTs to `/v2/calls` with a JSON body containing the `connection_id`,
+     * phone numbers, and webhook URL. The `mediaStreamUrl` (if provided) is
+     * stored internally for use after the call is answered -- it is NOT sent
+     * in the initial call creation request because Telnyx requires
+     * `streaming_start` to be issued as a separate action after `call.answered`.
+     *
+     * @param input - Call initiation parameters (from/to numbers, webhook URL).
+     * @returns Result containing the Telnyx `call_control_id` on success.
+     * @throws Never throws; returns `{ success: false, error: '...' }` on failure.
      */
     initiateCall(input: InitiateCallInput): Promise<InitiateCallResult>;
     /**
      * Hang up an active call via the Telnyx Call Control hangup action.
+     *
+     * POSTs an empty JSON body to `/v2/calls/{call_control_id}/actions/hangup`.
+     * Telnyx will terminate the call and fire a `call.hangup` webhook.
+     *
+     * @param input - Contains the Telnyx `call_control_id` to hang up.
      */
     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.
+     * POSTs a JSON body to `/v2/calls/{id}/actions/speak` with the text
+     * `payload`, `voice` (default `'female'`), and `language` (default `'en-US'`).
+     *
+     * @param input - TTS parameters (text, optional voice, call ID).
      */
     playTts(input: PlayTtsInput): Promise<void>;
 }

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

@@ -1 +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"}
+{"version":3,"file":"telnyx.d.ts","sourceRoot":"","sources":["../../../src/voice/providers/telnyx.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;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;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAC;IACf,yDAAyD;IACzD,YAAY,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAiCD;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,mBAAoB,YAAW,kBAAkB;IAC5D,8CAA8C;IAC9C,QAAQ,CAAC,IAAI,EAAG,QAAQ,CAAU;IAElC,wCAAwC;IACxC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA4B;IAEnD,sCAAsC;IACtC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IAEjC,6DAA6D;IAC7D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IAEpC,0DAA0D;IAC1D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IAErC;;OAEG;gBACS,MAAM,EAAE,yBAAyB;IAS7C;;;;;;;;;;;;;;;;;OAiBG;IACH,aAAa,CAAC,GAAG,EAAE,cAAc,GAAG,yBAAyB;IAoC7D;;;;;;;;;;;;;;;;;OAiBG;IACH,iBAAiB,CAAC,GAAG,EAAE,cAAc,GAAG,kBAAkB;IA6D1D;;;;;;;;;;;;OAYG;IACG,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IA0BzE;;;;;;;OAOG;IACG,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAavD;;;;;;;OAOG;IACG,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;CAgBlD"}

package/dist/voice/providers/telnyx.js

@@ -2,8 +2,56 @@
  * @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.
+ *
+ * ## REST API contract
+ *
+ * | Operation      | Method | Endpoint                                 | Body format |
+ * |----------------|--------|------------------------------------------|-------------|
+ * | Initiate call  | POST   | `/v2/calls`                              | JSON        |
+ * | Hangup call    | POST   | `/v2/calls/{id}/actions/hangup`          | JSON        |
+ * | Play TTS       | POST   | `/v2/calls/{id}/actions/speak`           | JSON        |
+ * | Start stream   | POST   | `/v2/calls/{id}/actions/streaming_start` | JSON        |
+ *
+ * All requests use Bearer token authentication: `Authorization: Bearer {apiKey}`.
+ * Request bodies are JSON (unlike Twilio's form-encoded convention).
+ *
+ * ## Streaming after `call.answered`
+ *
+ * Telnyx requires a two-step flow for media streaming:
+ * 1. Initiate the call via `POST /v2/calls` with a `webhook_url`.
+ * 2. When the `call.answered` webhook fires, issue a separate
+ *    `POST /v2/calls/{id}/actions/streaming_start` request with the
+ *    WebSocket URL. This is handled by the CallManager, not by this provider.
+ *
+ * ## Webhook verification: Ed25519
+ *
+ * Telnyx signs webhooks using Ed25519 public key cryptography:
+ *
+ * 1. Telnyx generates a signed payload: `{timestamp}|{rawBody}`.
+ * 2. The signature is computed with the account's Ed25519 private key.
+ * 3. The public key is provided as a base64-encoded DER SPKI blob.
+ * 4. Headers: `X-Telnyx-Timestamp` (the timestamp) and
+ *    `X-Telnyx-Signature-Ed25519` (base64-encoded Ed25519 signature).
+ * 5. Verification: decode the signature from base64, construct the payload
+ *    string `{timestamp}|{body}`, and verify using `crypto.verify()` with
+ *    the SPKI public key.
+ *
+ * When no public key is configured, verification is skipped (returns
+ * `valid: true`) to support development environments.
+ *
+ * ## Event mapping table (hangup_cause)
+ *
+ * | Telnyx `event_type`              | `hangup_cause`            | Normalised `kind`    |
+ * |----------------------------------|---------------------------|----------------------|
+ * | `call.initiated`                 | --                        | `call-ringing`       |
+ * | `call.answered`                  | --                        | `call-answered`      |
+ * | `call.hangup`                    | `normal_clearing`         | `call-hangup-user`   |
+ * | `call.hangup`                    | `user_busy`               | `call-hangup-user`   |
+ * | `call.hangup`                    | `originator_cancel`       | `call-hangup-user`   |
+ * | `call.hangup`                    | (anything else)           | `call-completed`     |
+ * | `call.dtmf.received`             | --                        | `call-dtmf`          |
+ * | `call.machine.detection.ended`   | result=`machine`          | `call-voicemail`     |
+ * | `call.machine.detection.ended`   | result=`human`            | (no event)           |
  *
  * @module @framers/agentos/voice/providers/telnyx
  */
@@ -29,7 +77,11 @@ import { randomUUID } from 'node:crypto';
  * ```
  */
 export class TelnyxVoiceProvider {
+    /**
+     * @param config - Telnyx credentials and optional overrides.
+     */
     constructor(config) {
+        /** Provider identifier, always `'telnyx'`. */
         this.name = 'telnyx';
         this.config = config;
         this.baseUrl = 'https://api.telnyx.com/v2';
@@ -40,14 +92,24 @@ export class TelnyxVoiceProvider {
     /**
      * 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.
+     * ## Algorithm (step by step)
+     *
+     * 1. If no public key is configured, skip verification (return `valid: true`).
+     *    This supports development environments without cryptographic setup.
+     * 2. Extract `X-Telnyx-Timestamp` and `X-Telnyx-Signature-Ed25519` headers.
+     * 3. Decode the signature from base64 into a raw byte Buffer.
+     * 4. Construct the signed payload: `"{timestamp}|{rawBody}"`.
+     * 5. Decode the SPKI public key from base64.
+     * 6. Call `crypto.verify(null, payload, { key, format: 'der', type: 'spki' }, signature)`.
+     * 7. Return the verification result.
      *
-     * 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.
+     * @param ctx - Raw webhook request context.
+     * @returns Verification result. Returns `{ valid: true }` when no public key
+     *   is configured (development mode).
      */
     verifyWebhook(ctx) {
+        // Skip verification when no public key is configured -- allows
+        // development without needing to set up Ed25519 key pairs.
         if (!this.config.publicKey) {
             return { valid: true };
         }
@@ -57,9 +119,11 @@ export class TelnyxVoiceProvider {
             return { valid: false, error: 'Missing Telnyx signature headers' };
         }
         const signature = Buffer.from(sigHeader, 'base64');
+        // Telnyx signs the concatenation of timestamp, pipe separator, and raw body.
         const payload = Buffer.from(`${timestamp}|${ctx.body.toString()}`);
         try {
-            const valid = verify(null, payload, {
+            const valid = verify(null, // Ed25519 does not use a separate hash algorithm parameter.
+            payload, {
                 key: Buffer.from(this.config.publicKey, 'base64'),
                 format: 'der',
                 type: 'spki',
@@ -67,18 +131,27 @@ export class TelnyxVoiceProvider {
             return { valid };
         }
         catch {
+            // crypto.verify throws on malformed keys or invalid DER encoding.
             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`
+     * Telnyx sends all webhook payloads as JSON with a `data.event_type`
+     * discriminant field. The `data.payload` object contains call-specific
+     * fields like `call_control_id`, `hangup_cause`, `digit`, and `result`.
+     *
+     * ## Hangup cause mapping
+     *
+     * Telnyx's `call.hangup` event includes a `hangup_cause` field that must
+     * be inspected to determine whether the user or the system terminated
+     * the call:
+     * - `normal_clearing` / `user_busy` / `originator_cancel` -> `call-hangup-user`
+     * - All other causes (e.g., `call_rejected`, `unallocated_number`) -> `call-completed`
+     *
+     * @param ctx - Raw webhook request context.
+     * @returns Parsed result containing zero or more normalized events.
      */
     parseWebhookEvent(ctx) {
         let parsed;
@@ -92,6 +165,7 @@ export class TelnyxVoiceProvider {
         const providerCallId = payload.call_control_id ?? '';
         const timestamp = Date.now();
         const events = [];
+        /** Helper: shared base fields with a unique event ID for idempotency. */
         const base = () => ({ eventId: randomUUID(), providerCallId, timestamp });
         switch (event_type) {
             case 'call.initiated':
@@ -101,7 +175,8 @@ export class TelnyxVoiceProvider {
                 events.push({ ...base(), kind: 'call-answered' });
                 break;
             case 'call.hangup': {
-                // Distinguish user-initiated hangup from normal completion
+                // Distinguish user-initiated hangup from normal call completion
+                // by inspecting the hangup_cause field.
                 const cause = payload.hangup_cause ?? '';
                 const kind = cause === 'user_busy' || cause === 'normal_clearing' || cause === 'originator_cancel'
                     ? 'call-hangup-user'
@@ -110,17 +185,19 @@ export class TelnyxVoiceProvider {
                 break;
             }
             case 'call.dtmf.received': {
+                // DTMF arrives via webhook only (never over the media stream WebSocket).
                 const digit = payload.digit ?? '';
                 events.push({ ...base(), kind: 'call-dtmf', digit });
                 break;
             }
             case 'call.machine.detection.ended':
+                // Only emit voicemail for machine detection; human detection is a no-op.
                 if (payload.result === 'machine') {
                     events.push({ ...base(), kind: 'call-voicemail' });
                 }
                 break;
             default:
-                // Unrecognized event type — emit nothing
+                // Unrecognized event type -- silently ignore for forward-compatibility.
                 break;
         }
         return { events };
@@ -129,9 +206,15 @@ export class TelnyxVoiceProvider {
     /**
      * 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.
+     * POSTs to `/v2/calls` with a JSON body containing the `connection_id`,
+     * phone numbers, and webhook URL. The `mediaStreamUrl` (if provided) is
+     * stored internally for use after the call is answered -- it is NOT sent
+     * in the initial call creation request because Telnyx requires
+     * `streaming_start` to be issued as a separate action after `call.answered`.
+     *
+     * @param input - Call initiation parameters (from/to numbers, webhook URL).
+     * @returns Result containing the Telnyx `call_control_id` on success.
+     * @throws Never throws; returns `{ success: false, error: '...' }` on failure.
      */
     async initiateCall(input) {
         const url = `${this.baseUrl}/calls`;
@@ -157,6 +240,11 @@ export class TelnyxVoiceProvider {
     }
     /**
      * Hang up an active call via the Telnyx Call Control hangup action.
+     *
+     * POSTs an empty JSON body to `/v2/calls/{call_control_id}/actions/hangup`.
+     * Telnyx will terminate the call and fire a `call.hangup` webhook.
+     *
+     * @param input - Contains the Telnyx `call_control_id` to hang up.
      */
     async hangupCall(input) {
         const url = `${this.baseUrl}/calls/${input.providerCallId}/actions/hangup`;
@@ -172,7 +260,10 @@ export class TelnyxVoiceProvider {
     /**
      * 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.
+     * POSTs a JSON body to `/v2/calls/{id}/actions/speak` with the text
+     * `payload`, `voice` (default `'female'`), and `language` (default `'en-US'`).
+     *
+     * @param input - TTS parameters (text, optional voice, call ID).
      */
     async playTts(input) {
         const url = `${this.baseUrl}/calls/${input.providerCallId}/actions/speak`;