@framers/agentos 0.1.111 → 0.1.113

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`;

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

@@ -1 +1 @@
-{"version":3,"file":"telnyx.js","sourceRoot":"","sources":["../../../src/voice/providers/telnyx.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"telnyx.js","sourceRoot":"","sources":["../../../src/voice/providers/telnyx.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAsEzC,+EAA+E;AAC/E,sBAAsB;AACtB,+EAA+E;AAE/E;;;;;;;;;;;;;;;GAeG;AACH,MAAM,OAAO,mBAAmB;IAgB9B;;OAEG;IACH,YAAY,MAAiC;QAlB7C,8CAA8C;QACrC,SAAI,GAAG,QAAiB,CAAC;QAkBhC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,OAAO,GAAG,2BAA2B,CAAC;QAC3C,IAAI,CAAC,UAAU,GAAG,UAAU,MAAM,CAAC,MAAM,EAAE,CAAC;QAC5C,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,SAAS,IAAI,UAAU,CAAC,KAAK,CAAC;IACpD,CAAC;IAED,6EAA6E;IAE7E;;;;;;;;;;;;;;;;;OAiBG;IACH,aAAa,CAAC,GAAmB;QAC/B,+DAA+D;QAC/D,2DAA2D;QAC3D,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;YAC3B,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;QACzB,CAAC;QAED,MAAM,SAAS,GAAG,GAAG,CAAC,OAAO,CAAC,oBAAoB,CAAC,CAAC;QACpD,MAAM,SAAS,GAAG,GAAG,CAAC,OAAO,CAAC,4BAA4B,CAAC,CAAC;QAE5D,IAAI,CAAC,SAAS,IAAI,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,IAAI,CAAC,SAAS,IAAI,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;YACrF,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,kCAAkC,EAAE,CAAC;QACrE,CAAC;QAED,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;QACnD,6EAA6E;QAC7E,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,SAAS,IAAI,GAAG,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;QAEnE,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,MAAM,CAClB,IAAI,EAAE,4DAA4D;YAClE,OAAO,EACP;gBACE,GAAG,EAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,QAAQ,CAAC;gBACjD,MAAM,EAAE,KAAK;gBACb,IAAI,EAAE,MAAM;aACb,EACD,SAAS,CACV,CAAC;YACF,OAAO,EAAE,KAAK,EAAE,CAAC;QACnB,CAAC;QAAC,MAAM,CAAC;YACP,kEAAkE;YAClE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,qBAAqB,EAAE,CAAC;QACxD,CAAC;IACH,CAAC;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,iBAAiB,CAAC,GAAmB;QACnC,IAAI,MAA4B,CAAC;QACjC,IAAI,CAAC;YACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAyB,CAAC;QACnE,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;QACxB,CAAC;QAED,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC;QAC5C,MAAM,cAAc,GAAG,OAAO,CAAC,eAAe,IAAI,EAAE,CAAC;QACrD,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC7B,MAAM,MAAM,GAA0B,EAAE,CAAC;QAEzC,yEAAyE;QACzE,MAAM,IAAI,GAAG,GAAG,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,EAAE,cAAc,EAAE,SAAS,EAAE,CAAC,CAAC;QAE1E,QAAQ,UAAU,EAAE,CAAC;YACnB,KAAK,gBAAgB;gBACnB,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,IAAI,EAAE,EAAE,IAAI,EAAE,cAAc,EAAE,CAAC,CAAC;gBACjD,MAAM;YAER,KAAK,eAAe;gBAClB,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,IAAI,EAAE,EAAE,IAAI,EAAE,eAAe,EAAE,CAAC,CAAC;gBAClD,MAAM;YAER,KAAK,aAAa,CAAC,CAAC,CAAC;gBACnB,gEAAgE;gBAChE,wCAAwC;gBACxC,MAAM,KAAK,GAAI,OAAO,CAAC,YAAmC,IAAI,EAAE,CAAC;gBACjE,MAAM,IAAI,GACR,KAAK,KAAK,WAAW,IAAI,KAAK,KAAK,iBAAiB,IAAI,KAAK,KAAK,mBAAmB;oBACnF,CAAC,CAAC,kBAAkB;oBACpB,CAAC,CAAC,gBAAgB,CAAC;gBACvB,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,IAAI,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;gBACjC,MAAM;YACR,CAAC;YAED,KAAK,oBAAoB,CAAC,CAAC,CAAC;gBAC1B,yEAAyE;gBACzE,MAAM,KAAK,GAAI,OAAO,CAAC,KAA4B,IAAI,EAAE,CAAC;gBAC1D,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,IAAI,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC,CAAC;gBACrD,MAAM;YACR,CAAC;YAED,KAAK,8BAA8B;gBACjC,yEAAyE;gBACzE,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;oBACjC,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,IAAI,EAAE,EAAE,IAAI,EAAE,gBAAgB,EAAE,CAAC,CAAC;gBACrD,CAAC;gBACD,MAAM;YAER;gBACE,wEAAwE;gBACxE,MAAM;QACV,CAAC;QAED,OAAO,EAAE,MAAM,EAAE,CAAC;IACpB,CAAC;IAED,6EAA6E;IAE7E;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,YAAY,CAAC,KAAwB;QACzC,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,OAAO,QAAQ,CAAC;QAEpC,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE;YACrC,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,aAAa,EAAE,IAAI,CAAC,UAAU;gBAC9B,cAAc,EAAE,kBAAkB;aACnC;YACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;gBACnB,aAAa,EAAE,IAAI,CAAC,MAAM,CAAC,YAAY;gBACvC,EAAE,EAAE,KAAK,CAAC,QAAQ;gBAClB,IAAI,EAAE,KAAK,CAAC,UAAU;gBACtB,WAAW,EAAE,KAAK,CAAC,UAAU;aAC9B,CAAC;SACH,CAAC,CAAC;QAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;YACxE,OAAO,EAAE,cAAc,EAAE,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,gBAAgB,QAAQ,CAAC,MAAM,KAAK,IAAI,EAAE,EAAE,CAAC;QACnG,CAAC;QAED,MAAM,IAAI,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAmE,CAAC;QACvG,OAAO,EAAE,cAAc,EAAE,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IACtE,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,UAAU,CAAC,KAAsB;QACrC,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,OAAO,UAAU,KAAK,CAAC,cAAc,iBAAiB,CAAC;QAE3E,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE;YACpB,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,aAAa,EAAE,IAAI,CAAC,UAAU;gBAC9B,cAAc,EAAE,kBAAkB;aACnC;YACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;SACzB,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,OAAO,CAAC,KAAmB;QAC/B,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,OAAO,UAAU,KAAK,CAAC,cAAc,gBAAgB,CAAC;QAE1E,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE;YACpB,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,aAAa,EAAE,IAAI,CAAC,UAAU;gBAC9B,cAAc,EAAE,kBAAkB;aACnC;YACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;gBACnB,OAAO,EAAE,KAAK,CAAC,IAAI;gBACnB,KAAK,EAAE,KAAK,CAAC,KAAK,IAAI,QAAQ;gBAC9B,QAAQ,EAAE,OAAO;aAClB,CAAC;SACH,CAAC,CAAC;IACL,CAAC;CACF"}

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

@@ -2,20 +2,60 @@
  * @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.
+ *
+ * ## REST API contract
+ *
+ * | Operation      | Method | Endpoint                                          | Body format     |
+ * |----------------|--------|---------------------------------------------------|-----------------|
+ * | Initiate call  | POST   | `/2010-04-01/Accounts/{sid}/Calls.json`           | form-encoded    |
+ * | Hangup call    | POST   | `/2010-04-01/Accounts/{sid}/Calls/{callSid}.json` | form-encoded    |
+ * | Play TTS       | POST   | `/2010-04-01/Accounts/{sid}/Calls/{callSid}.json` | form-encoded    |
+ *
+ * All requests use HTTP Basic authentication: `Authorization: Basic base64(accountSid:authToken)`.
+ * Request bodies are `application/x-www-form-urlencoded` (not JSON), which is
+ * Twilio's legacy convention for the 2010-04-01 API.
+ *
+ * ## Webhook verification: HMAC-SHA1
+ *
+ * Twilio signs every webhook request using HMAC-SHA1. The verification algorithm:
+ *
+ * 1. Start with the **full request URL** (including scheme, host, path, and any query string).
+ * 2. Parse the POST body as form-encoded key-value pairs.
+ * 3. Sort the parameters **alphabetically by key name**.
+ * 4. Concatenate each key+value pair (no separator) directly to the URL string.
+ * 5. Compute `HMAC-SHA1(authToken, concatenatedString)`.
+ * 6. Base64-encode the HMAC digest.
+ * 7. Compare the result with the `X-Twilio-Signature` request header.
+ *
+ * If the computed signature matches the header, the request is authentic.
+ *
+ * ## Event mapping table
+ *
+ * | Twilio `CallStatus` | Normalised `kind`    |
+ * |---------------------|----------------------|
+ * | `ringing`           | `call-ringing`       |
+ * | `in-progress`       | `call-answered`      |
+ * | `completed`         | `call-completed`     |
+ * | `failed`            | `call-failed`        |
+ * | `busy`              | `call-busy`          |
+ * | `no-answer`         | `call-no-answer`     |
+ * | `canceled`          | `call-hangup-user`   |
+ * | (+ `Digits` param)  | `call-dtmf`          |
  *
  * @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}. */
+/**
+ * Configuration for {@link TwilioVoiceProvider}.
+ */
 export interface TwilioVoiceProviderConfig {
     /** Twilio Account SID (starts with "AC"). */
     accountSid: string;
-    /** Twilio Auth Token. */
+    /** Twilio Auth Token (used for both API auth and webhook HMAC verification). */
     authToken: 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;
@@ -35,44 +75,82 @@ export interface TwilioVoiceProviderConfig {
  * ```
  */
 export declare class TwilioVoiceProvider implements IVoiceCallProvider {
+    /** Provider identifier, always `'twilio'`. */
     readonly name: "twilio";
+    /** Immutable configuration snapshot. */
     private readonly config;
+    /** Base URL for the Twilio REST API (2010-04-01 version). */
     private readonly baseUrl;
+    /** Pre-computed `Authorization: Basic ...` header value. */
     private readonly authHeader;
+    /** HTTP fetch implementation (injectable for testing). */
     private readonly fetch;
+    /**
+     * @param config - Twilio credentials and optional overrides.
+     */
     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.
+     * ## Algorithm (step by step)
+     *
+     * 1. Extract the `X-Twilio-Signature` header from the request.
+     * 2. Parse the request body as URL-encoded form data.
+     * 3. Sort all key-value pairs alphabetically by key.
+     * 4. Build the signed string: start with the full URL, then append each
+     *    key + value (no delimiters between pairs).
+     * 5. Compute `HMAC-SHA1` of the signed string using the auth token as the key.
+     * 6. Base64-encode the digest and compare it to the header value.
+     *
+     * @param ctx - Raw webhook request context.
+     * @returns Verification result with `valid: true` if the signature matches.
      */
     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.
+     * Twilio sends webhooks with a form-encoded body containing `CallSid`,
+     * `CallStatus`, and optionally `Digits` (for DTMF input from `<Gather>`).
+     * Each webhook may produce one or two events (status + optional DTMF).
+     *
+     * @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 Twilio Calls API.
      *
-     * Posts to `/Accounts/{accountSid}/Calls.json` with form-encoded body.
-     * All four status callback events (initiated, ringing, answered, completed)
-     * are requested.
+     * Posts to `/Accounts/{accountSid}/Calls.json` with a **form-encoded** body
+     * (not JSON -- this is Twilio's 2010-era API convention). All four status
+     * callback events (`initiated`, `ringing`, `answered`, `completed`) are
+     * requested so the {@link CallManager} receives the full state progression.
+     *
+     * @param input - Call initiation parameters (from/to numbers, webhook URLs).
+     * @returns Result containing the Twilio `CallSid` on success.
+     * @throws Never throws; returns `{ success: false, error: '...' }` on failure.
      */
     initiateCall(input: InitiateCallInput): Promise<InitiateCallResult>;
     /**
-     * Hang up an active call by posting `Status=completed`.
+     * Hang up an active call by POSTing `Status=completed`.
+     *
+     * Twilio uses the same Calls resource endpoint for both querying and
+     * modifying a call. Setting `Status=completed` instructs Twilio to
+     * immediately terminate the call.
+     *
+     * @param input - Contains the Twilio `CallSid` to hang up.
      */
     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.
+     * Sends a `Twiml` form parameter containing a minimal `<Response><Say>`
+     * document. Twilio will parse the TwiML, synthesise the speech, and play
+     * it to the caller in real-time.
+     *
      * The optional `voice` attribute maps to Twilio's built-in voice names
      * (e.g., `alice`, `Polly.Joanna`).
+     *
+     * @param input - TTS parameters (text, voice, call ID).
      */
     playTts(input: PlayTtsInput): Promise<void>;
 }

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

@@ -1 +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"}
+{"version":3,"file":"twilio.d.ts","sourceRoot":"","sources":["../../../src/voice/providers/twilio.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;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,6CAA6C;IAC7C,UAAU,EAAE,MAAM,CAAC;IACnB,gFAAgF;IAChF,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAMD;;;;;;;;;;;;;GAaG;AACH,qBAAa,mBAAoB,YAAW,kBAAkB;IAC5D,8CAA8C;IAC9C,QAAQ,CAAC,IAAI,EAAG,QAAQ,CAAU;IAElC,wCAAwC;IACxC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA4B;IAEnD,6DAA6D;IAC7D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IAEjC,4DAA4D;IAC5D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IAEpC,0DAA0D;IAC1D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IAErC;;OAEG;gBACS,MAAM,EAAE,yBAAyB;IAY7C;;;;;;;;;;;;;;;OAeG;IACH,aAAa,CAAC,GAAG,EAAE,cAAc,GAAG,yBAAyB;IA0B7D;;;;;;;;;OASG;IACH,iBAAiB,CAAC,GAAG,EAAE,cAAc,GAAG,kBAAkB;IA8D1D;;;;;;;;;;;OAWG;IACG,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAiCzE;;;;;;;;OAQG;IACG,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAavD;;;;;;;;;;;OAWG;IACG,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;CAelD"}

package/dist/voice/providers/twilio.js

@@ -2,7 +2,45 @@
  * @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.
+ *
+ * ## REST API contract
+ *
+ * | Operation      | Method | Endpoint                                          | Body format     |
+ * |----------------|--------|---------------------------------------------------|-----------------|
+ * | Initiate call  | POST   | `/2010-04-01/Accounts/{sid}/Calls.json`           | form-encoded    |
+ * | Hangup call    | POST   | `/2010-04-01/Accounts/{sid}/Calls/{callSid}.json` | form-encoded    |
+ * | Play TTS       | POST   | `/2010-04-01/Accounts/{sid}/Calls/{callSid}.json` | form-encoded    |
+ *
+ * All requests use HTTP Basic authentication: `Authorization: Basic base64(accountSid:authToken)`.
+ * Request bodies are `application/x-www-form-urlencoded` (not JSON), which is
+ * Twilio's legacy convention for the 2010-04-01 API.
+ *
+ * ## Webhook verification: HMAC-SHA1
+ *
+ * Twilio signs every webhook request using HMAC-SHA1. The verification algorithm:
+ *
+ * 1. Start with the **full request URL** (including scheme, host, path, and any query string).
+ * 2. Parse the POST body as form-encoded key-value pairs.
+ * 3. Sort the parameters **alphabetically by key name**.
+ * 4. Concatenate each key+value pair (no separator) directly to the URL string.
+ * 5. Compute `HMAC-SHA1(authToken, concatenatedString)`.
+ * 6. Base64-encode the HMAC digest.
+ * 7. Compare the result with the `X-Twilio-Signature` request header.
+ *
+ * If the computed signature matches the header, the request is authentic.
+ *
+ * ## Event mapping table
+ *
+ * | Twilio `CallStatus` | Normalised `kind`    |
+ * |---------------------|----------------------|
+ * | `ringing`           | `call-ringing`       |
+ * | `in-progress`       | `call-answered`      |
+ * | `completed`         | `call-completed`     |
+ * | `failed`            | `call-failed`        |
+ * | `busy`              | `call-busy`          |
+ * | `no-answer`         | `call-no-answer`     |
+ * | `canceled`          | `call-hangup-user`   |
+ * | (+ `Digits` param)  | `call-dtmf`          |
  *
  * @module @framers/agentos/voice/providers/twilio
  */
@@ -26,10 +64,15 @@ import { randomUUID } from 'node:crypto';
  * ```
  */
 export class TwilioVoiceProvider {
+    /**
+     * @param config - Twilio credentials and optional overrides.
+     */
     constructor(config) {
+        /** Provider identifier, always `'twilio'`. */
         this.name = 'twilio';
         this.config = config;
         this.baseUrl = 'https://api.twilio.com/2010-04-01';
+        // Twilio uses HTTP Basic auth with accountSid:authToken.
         this.authHeader =
             'Basic ' +
                 Buffer.from(`${config.accountSid}:${config.authToken}`).toString('base64');
@@ -39,21 +82,32 @@ export class TwilioVoiceProvider {
     /**
      * 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.
+     * ## Algorithm (step by step)
+     *
+     * 1. Extract the `X-Twilio-Signature` header from the request.
+     * 2. Parse the request body as URL-encoded form data.
+     * 3. Sort all key-value pairs alphabetically by key.
+     * 4. Build the signed string: start with the full URL, then append each
+     *    key + value (no delimiters between pairs).
+     * 5. Compute `HMAC-SHA1` of the signed string using the auth token as the key.
+     * 6. Base64-encode the digest and compare it to the header value.
+     *
+     * @param ctx - Raw webhook request context.
+     * @returns Verification result with `valid: true` if the signature matches.
      */
     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
+        // Step 2-4: Parse form body, sort params, build 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;
         }
+        // Step 5-6: HMAC-SHA1 with auth token, compare base64 digest.
         const expected = createHmac('sha1', this.config.authToken)
             .update(data)
             .digest('base64');
@@ -66,8 +120,12 @@ export class TwilioVoiceProvider {
     /**
      * 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.
+     * Twilio sends webhooks with a form-encoded body containing `CallSid`,
+     * `CallStatus`, and optionally `Digits` (for DTMF input from `<Gather>`).
+     * Each webhook may produce one or two events (status + optional DTMF).
+     *
+     * @param ctx - Raw webhook request context.
+     * @returns Parsed result containing zero or more normalized events.
      */
     parseWebhookEvent(ctx) {
         const params = new URLSearchParams(ctx.body.toString());
@@ -76,12 +134,13 @@ export class TwilioVoiceProvider {
         const digits = params.get('Digits');
         const timestamp = Date.now();
         const events = [];
-        /** Helper: shared base fields. */
+        /** Helper: shared base fields with a unique event ID for idempotency. */
         const base = () => ({
             eventId: randomUUID(),
             providerCallId: callSid,
             timestamp,
         });
+        // Map Twilio CallStatus values to normalized event kinds.
         switch (callStatus) {
             case 'ringing':
                 events.push({ ...base(), kind: 'call-ringing' });
@@ -102,13 +161,17 @@ export class TwilioVoiceProvider {
                 events.push({ ...base(), kind: 'call-no-answer' });
                 break;
             case 'canceled':
+                // Twilio uses "canceled" when the caller hangs up before the callee answers.
                 events.push({ ...base(), kind: 'call-hangup-user' });
                 break;
             default:
-                // initiated / queued / etc. — no normalized event emitted
+                // initiated / queued / etc. -- no normalized event emitted.
+                // These are transient Twilio-internal states that don't map to
+                // meaningful call lifecycle events.
                 break;
         }
-        // DTMF digit input
+        // DTMF digit input (from <Gather> TwiML verb callback).
+        // This can co-occur with a CallStatus update in the same webhook.
         if (digits != null && digits !== '') {
             events.push({
                 ...base(),
@@ -122,12 +185,18 @@ export class TwilioVoiceProvider {
     /**
      * 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.
+     * Posts to `/Accounts/{accountSid}/Calls.json` with a **form-encoded** body
+     * (not JSON -- this is Twilio's 2010-era API convention). All four status
+     * callback events (`initiated`, `ringing`, `answered`, `completed`) are
+     * requested so the {@link CallManager} receives the full state progression.
+     *
+     * @param input - Call initiation parameters (from/to numbers, webhook URLs).
+     * @returns Result containing the Twilio `CallSid` on success.
+     * @throws Never throws; returns `{ success: false, error: '...' }` on failure.
      */
     async initiateCall(input) {
         const url = `${this.baseUrl}/Accounts/${this.config.accountSid}/Calls.json`;
+        // Build form-encoded body. Twilio expects this format, not JSON.
         const body = [
             `To=${encodeURIComponent(input.toNumber)}`,
             `From=${encodeURIComponent(input.fromNumber)}`,
@@ -154,7 +223,13 @@ export class TwilioVoiceProvider {
         return { providerCallId: data.sid, success: true };
     }
     /**
-     * Hang up an active call by posting `Status=completed`.
+     * Hang up an active call by POSTing `Status=completed`.
+     *
+     * Twilio uses the same Calls resource endpoint for both querying and
+     * modifying a call. Setting `Status=completed` instructs Twilio to
+     * immediately terminate the call.
+     *
+     * @param input - Contains the Twilio `CallSid` to hang up.
      */
     async hangupCall(input) {
         const url = `${this.baseUrl}/Accounts/${this.config.accountSid}/Calls/${input.providerCallId}.json`;
@@ -170,9 +245,14 @@ export class TwilioVoiceProvider {
     /**
      * Inject TTS into a live call using a TwiML `<Say>` verb.
      *
-     * Sends a `Twiml` parameter containing a minimal `<Response><Say>` document.
+     * Sends a `Twiml` form parameter containing a minimal `<Response><Say>`
+     * document. Twilio will parse the TwiML, synthesise the speech, and play
+     * it to the caller in real-time.
+     *
      * The optional `voice` attribute maps to Twilio's built-in voice names
      * (e.g., `alice`, `Polly.Joanna`).
+     *
+     * @param input - TTS parameters (text, voice, call ID).
      */
     async playTts(input) {
         const url = `${this.baseUrl}/Accounts/${this.config.accountSid}/Calls/${input.providerCallId}.json`;

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

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