@framers/agentos 0.1.74 → 0.1.76

package/dist/voice/TelephonyStreamTransport.js

@@ -0,0 +1,208 @@
+/**
+ * @fileoverview TelephonyStreamTransport — bridges a telephony WebSocket media
+ * stream to the AgentOS streaming voice pipeline.
+ *
+ * Incoming mu-law 8 kHz audio from the phone network is decoded to Int16 PCM,
+ * resampled to the pipeline's preferred sample rate, normalised to Float32, and
+ * emitted as {@link AudioFrame} events. Outbound {@link EncodedAudioChunk}
+ * payloads are resampled from the pipeline's sample rate back to 8 kHz, encoded
+ * to mu-law, and forwarded through the provider-specific {@link MediaStreamParser}.
+ *
+ * @module @framers/agentos/voice/TelephonyStreamTransport
+ */
+import { EventEmitter } from 'node:events';
+import { randomUUID } from 'node:crypto';
+import { convertPcmToMulaw8k, convertMulawToPcm16 } from './telephony-audio.js';
+/**
+ * Adapts a telephony provider WebSocket media stream to the
+ * {@link IStreamTransport} interface consumed by the AgentOS voice pipeline.
+ *
+ * ## Inbound path (phone → pipeline)
+ * 1. Provider WebSocket frames arrive as raw `Buffer` or JSON `string`.
+ * 2. {@link MediaStreamParser.parseIncoming} normalises them to
+ *    {@link MediaStreamIncoming} events.
+ * 3. `'audio'` events: mu-law 8 kHz → Int16 PCM → resample → Float32 → `'audio'` emit.
+ * 4. `'dtmf'` / `'mark'` events are re-emitted as-is for higher-layer handling.
+ * 5. `'start'` transitions the transport to `'open'` and sends the optional
+ *    connection acknowledgment from the parser.
+ * 6. `'stop'` or WebSocket close transitions to `'closed'` and emits `'close'`.
+ *
+ * ## Outbound path (pipeline → phone)
+ * 1. {@link sendAudio} receives an {@link EncodedAudioChunk} (PCM Int16 format assumed).
+ * 2. Chunk is resampled from `chunk.sampleRate` → 8 kHz via linear interpolation.
+ * 3. Resampled PCM is mu-law encoded via {@link convertPcmToMulaw8k}.
+ * 4. {@link MediaStreamParser.formatOutgoing} wraps the bytes for the provider.
+ * 5. The formatted payload is sent over the WebSocket.
+ *
+ * Emits:
+ * - `'audio'` ({@link AudioFrame}) — inbound decoded audio for STT / VAD.
+ * - `'dtmf'` (`{ digit: string; durationMs?: number }`) — caller key-press.
+ * - `'mark'` (`{ name: string }`) — named stream marker.
+ * - `'close'` () — transport has been fully closed.
+ * - `'error'` (Error) — unrecoverable WebSocket or parsing error.
+ */
+export class TelephonyStreamTransport extends EventEmitter {
+    /** Current connection lifecycle state. */
+    get state() {
+        return this._state;
+    }
+    // ---------------------------------------------------------------------------
+    // Constructor
+    // ---------------------------------------------------------------------------
+    /**
+     * @param ws - WebSocket-like object (must emit `'message'`, `'close'`, `'error'`
+     *   and expose `send(data)` and `close(code?, reason?)` methods).
+     * @param parser - Provider-specific message parser/formatter.
+     * @param config - Optional configuration overrides.
+     */
+    constructor(ws, // WebSocket-like; typed `any` to avoid hard dep on ws package
+    parser, config) {
+        super();
+        this.ws = ws;
+        this.parser = parser;
+        // ---------------------------------------------------------------------------
+        // IStreamTransport — identity & state
+        // ---------------------------------------------------------------------------
+        /** Stable UUID for this transport connection. */
+        this.id = randomUUID();
+        this._state = 'connecting';
+        // ---------------------------------------------------------------------------
+        // Private fields
+        // ---------------------------------------------------------------------------
+        /** Provider-assigned stream identifier; populated on the 'start' event. */
+        this.streamSid = null;
+        this.outputSampleRate = config?.outputSampleRate ?? 16000;
+        this.ws.on('message', (data) => {
+            const parsed = this.parser.parseIncoming(data);
+            if (!parsed)
+                return;
+            switch (parsed.type) {
+                case 'start': {
+                    this.streamSid = parsed.streamSid;
+                    this._state = 'open';
+                    // Send connection acknowledgment if the provider requires one.
+                    const connMsg = this.parser.formatConnected?.(parsed.streamSid);
+                    if (connMsg)
+                        this.ws.send(connMsg);
+                    break;
+                }
+                case 'audio': {
+                    // mu-law 8 kHz → Int16 PCM buffer (2 bytes per sample).
+                    const pcm16Buf = convertMulawToPcm16(parsed.payload);
+                    // Convert Buffer to Int16Array (shared memory, no copy).
+                    const int16 = new Int16Array(pcm16Buf.buffer, pcm16Buf.byteOffset, pcm16Buf.byteLength / 2);
+                    // Resample 8 kHz → outputSampleRate.
+                    const resampled = this.resample(int16, 8000, this.outputSampleRate);
+                    // Normalise Int16 → Float32 [-1, 1].
+                    const float32 = new Float32Array(resampled.length);
+                    for (let i = 0; i < resampled.length; i++) {
+                        float32[i] = resampled[i] / 32768;
+                    }
+                    const frame = {
+                        samples: float32,
+                        sampleRate: this.outputSampleRate,
+                        timestamp: Date.now(),
+                    };
+                    this.emit('audio', frame);
+                    break;
+                }
+                case 'dtmf':
+                    this.emit('dtmf', { digit: parsed.digit, durationMs: parsed.durationMs });
+                    break;
+                case 'stop':
+                    this._state = 'closed';
+                    this.emit('close');
+                    break;
+                case 'mark':
+                    this.emit('mark', { name: parsed.name });
+                    break;
+            }
+        });
+        this.ws.on('close', () => {
+            if (this._state !== 'closed') {
+                this._state = 'closed';
+                this.emit('close');
+            }
+        });
+        this.ws.on('error', (err) => this.emit('error', err));
+    }
+    // ---------------------------------------------------------------------------
+    // IStreamTransport — outbound methods
+    // ---------------------------------------------------------------------------
+    /**
+     * Send synthesised audio to the caller.
+     *
+     * Assumes `chunk.format === 'pcm'` and that `chunk.audio` contains raw
+     * signed 16-bit little-endian PCM samples at `chunk.sampleRate`. The audio
+     * is resampled to 8 kHz, mu-law encoded, and forwarded via the parser.
+     *
+     * @param chunk - Encoded audio chunk from the TTS pipeline.
+     */
+    async sendAudio(chunk) {
+        if (!this.streamSid || this._state !== 'open')
+            return;
+        // Interpret raw bytes as Int16 samples.
+        const int16 = new Int16Array(chunk.audio.buffer, chunk.audio.byteOffset, chunk.audio.byteLength / 2);
+        // Resample to 8 kHz, write into a Buffer for convertPcmToMulaw8k.
+        const resampled8k = this.resample(int16, chunk.sampleRate, 8000);
+        const pcm8kBuf = Buffer.from(resampled8k.buffer, resampled8k.byteOffset, resampled8k.byteLength);
+        // Encode to mu-law. convertPcmToMulaw8k already handles resampling, but
+        // we pre-resample here to avoid a second pass; pass sampleRate=8000 so
+        // the function's internal resampler is a no-op.
+        const mulaw = convertPcmToMulaw8k(pcm8kBuf, 8000);
+        const formatted = this.parser.formatOutgoing(mulaw, this.streamSid);
+        this.ws.send(formatted);
+    }
+    /**
+     * Send a JSON control message over the WebSocket.
+     *
+     * @param message - Server-to-client pipeline protocol message.
+     */
+    async sendControl(message) {
+        if (this._state !== 'open')
+            return;
+        this.ws.send(JSON.stringify(message));
+    }
+    /**
+     * Initiate graceful closure of the transport.
+     *
+     * @param code - Optional WebSocket close code (default 1000).
+     * @param reason - Optional human-readable close reason.
+     */
+    close(code, reason) {
+        this._state = 'closing';
+        this.ws.close(code, reason);
+    }
+    // ---------------------------------------------------------------------------
+    // Private helpers
+    // ---------------------------------------------------------------------------
+    /**
+     * Linear interpolation resampler for 16-bit signed PCM.
+     *
+     * Not studio-quality but sufficient for narrow-band voice telephony. The
+     * output length is computed as `round(input.length * toRate / fromRate)` to
+     * avoid cumulative rounding drift across many small frames.
+     *
+     * @param input - Source samples as a signed 16-bit integer array.
+     * @param fromRate - Sample rate of the input, in Hz.
+     * @param toRate - Desired sample rate of the output, in Hz.
+     * @returns A new Int16Array at `toRate`.
+     */
+    resample(input, fromRate, toRate) {
+        if (fromRate === toRate)
+            return input;
+        const ratio = fromRate / toRate;
+        const outputLen = Math.round(input.length / ratio);
+        const output = new Int16Array(outputLen);
+        for (let i = 0; i < outputLen; i++) {
+            const srcIdx = i * ratio;
+            const idx = Math.floor(srcIdx);
+            const frac = srcIdx - idx;
+            const a = input[idx] ?? 0;
+            const b = input[Math.min(idx + 1, input.length - 1)] ?? 0;
+            output[i] = Math.round(a + frac * (b - a));
+        }
+        return output;
+    }
+}
+//# sourceMappingURL=TelephonyStreamTransport.js.map

package/dist/voice/TelephonyStreamTransport.js.map

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

package/dist/voice/index.d.ts

@@ -8,4 +8,14 @@ export type { IVoiceCallProvider, InitiateCallInput, InitiateCallResult, HangupC
 export { CallManager } from './CallManager.js';
 export type { CallManagerEventType, CallManagerEvent, CallManagerEventHandler, } from './CallManager.js';
 export { convertPcmToMulaw8k, convertMulawToPcm16, escapeXml, validateE164, } from './telephony-audio.js';
+export type { MediaStreamParser, MediaStreamIncoming } from './MediaStreamParser.js';
+export { TwilioMediaStreamParser } from './parsers/TwilioMediaStreamParser.js';
+export { TelnyxMediaStreamParser } from './parsers/TelnyxMediaStreamParser.js';
+export { PlivoMediaStreamParser } from './parsers/PlivoMediaStreamParser.js';
+export { TelephonyStreamTransport } from './TelephonyStreamTransport.js';
+export type { TelephonyStreamTransportConfig } from './TelephonyStreamTransport.js';
+export { TwilioVoiceProvider } from './providers/twilio.js';
+export { TelnyxVoiceProvider } from './providers/telnyx.js';
+export { PlivoVoiceProvider } from './providers/plivo.js';
+export { twilioConversationTwiml, twilioNotifyTwiml, telnyxStreamXml, plivoStreamXml, plivoNotifyXml, } from './twiml.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/voice/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,YAAY,CAAC;AAC3B,YAAY,EACV,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EACf,YAAY,EACZ,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,YAAY,EACV,oBAAoB,EACpB,gBAAgB,EAChB,uBAAuB,GACxB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,SAAS,EACT,YAAY,GACb,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/voice/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,YAAY,CAAC;AAC3B,YAAY,EACV,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EACf,YAAY,EACZ,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,YAAY,EACV,oBAAoB,EACpB,gBAAgB,EAChB,uBAAuB,GACxB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,SAAS,EACT,YAAY,GACb,MAAM,sBAAsB,CAAC;AAG9B,YAAY,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AACrF,OAAO,EAAE,uBAAuB,EAAE,MAAM,sCAAsC,CAAC;AAC/E,OAAO,EAAE,uBAAuB,EAAE,MAAM,sCAAsC,CAAC;AAC/E,OAAO,EAAE,sBAAsB,EAAE,MAAM,qCAAqC,CAAC;AAG7E,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AACzE,YAAY,EAAE,8BAA8B,EAAE,MAAM,+BAA+B,CAAC;AAGpF,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAG1D,OAAO,EACL,uBAAuB,EACvB,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,cAAc,GACf,MAAM,YAAY,CAAC"}

package/dist/voice/index.js

@@ -6,4 +6,15 @@
 export * from './types.js';
 export { CallManager } from './CallManager.js';
 export { convertPcmToMulaw8k, convertMulawToPcm16, escapeXml, validateE164, } from './telephony-audio.js';
+export { TwilioMediaStreamParser } from './parsers/TwilioMediaStreamParser.js';
+export { TelnyxMediaStreamParser } from './parsers/TelnyxMediaStreamParser.js';
+export { PlivoMediaStreamParser } from './parsers/PlivoMediaStreamParser.js';
+// ── Telephony stream transport ────────────────────────────────────────────────
+export { TelephonyStreamTransport } from './TelephonyStreamTransport.js';
+// ── Voice call providers ──────────────────────────────────────────────────────
+export { TwilioVoiceProvider } from './providers/twilio.js';
+export { TelnyxVoiceProvider } from './providers/telnyx.js';
+export { PlivoVoiceProvider } from './providers/plivo.js';
+// ── TwiML / XML helpers ───────────────────────────────────────────────────────
+export { twilioConversationTwiml, twilioNotifyTwiml, telnyxStreamXml, plivoStreamXml, plivoNotifyXml, } from './twiml.js';
 //# sourceMappingURL=index.js.map

package/dist/voice/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/voice/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,YAAY,CAAC;AAU3B,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAM/C,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,SAAS,EACT,YAAY,GACb,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/voice/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,YAAY,CAAC;AAU3B,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAM/C,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,SAAS,EACT,YAAY,GACb,MAAM,sBAAsB,CAAC;AAI9B,OAAO,EAAE,uBAAuB,EAAE,MAAM,sCAAsC,CAAC;AAC/E,OAAO,EAAE,uBAAuB,EAAE,MAAM,sCAAsC,CAAC;AAC/E,OAAO,EAAE,sBAAsB,EAAE,MAAM,qCAAqC,CAAC;AAE7E,iFAAiF;AACjF,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AAGzE,iFAAiF;AACjF,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE1D,iFAAiF;AACjF,OAAO,EACL,uBAAuB,EACvB,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,cAAc,GACf,MAAM,YAAY,CAAC"}

package/dist/voice/parsers/PlivoMediaStreamParser.d.ts

@@ -0,0 +1,43 @@
+import type { MediaStreamParser, MediaStreamIncoming } from '../MediaStreamParser.js';
+/**
+ * Parses the Plivo Audio Stream WebSocket protocol.
+ *
+ * Plivo sends JSON-encoded messages for stream lifecycle events (`start`,
+ * `stop`) and audio chunks (`media`).  The audio payload is base64-encoded
+ * mu-law PCM, delivered in a `payload` field inside the `media` object.
+ *
+ * Outgoing audio is wrapped in a `playAudio` JSON envelope, which is the
+ * format Plivo expects when the server streams audio back to the caller.
+ * No explicit connection acknowledgment is required after the handshake.
+ *
+ * @see {@link https://www.plivo.com/docs/voice/xml/stream}
+ */
+export declare class PlivoMediaStreamParser implements MediaStreamParser {
+    /**
+     * Parse a raw WebSocket frame from Plivo's audio stream.
+     *
+     * Supported Plivo event types:
+     * - `start` — stream established; `stream_id` maps to `streamSid`,
+     *   `call_uuid` maps to `callSid`.
+     * - `media` — audio chunk; `media.payload` contains base64-encoded mu-law.
+     * - `stop`  — stream ended.
+     *
+     * @param data - Raw WebSocket frame payload (JSON string or Buffer from Plivo).
+     * @returns Normalised {@link MediaStreamIncoming} event, or `null` for
+     *   unknown event types or malformed messages.
+     */
+    parseIncoming(data: Buffer | string): MediaStreamIncoming | null;
+    /**
+     * Encode mu-law audio for transmission back to Plivo.
+     *
+     * Plivo requires audio to be base64-encoded and wrapped in a `playAudio`
+     * JSON envelope.
+     *
+     * @param audio - Raw mu-law PCM bytes to send to the caller.
+     * @param _streamSid - Unused by Plivo's `playAudio` format (accepted for
+     *   interface parity with other parsers).
+     * @returns JSON string conforming to the Plivo `playAudio` envelope.
+     */
+    formatOutgoing(audio: Buffer, _streamSid: string): string;
+}
+//# sourceMappingURL=PlivoMediaStreamParser.d.ts.map

package/dist/voice/parsers/PlivoMediaStreamParser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PlivoMediaStreamParser.d.ts","sourceRoot":"","sources":["../../../src/voice/parsers/PlivoMediaStreamParser.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAEtF;;;;;;;;;;;;GAYG;AACH,qBAAa,sBAAuB,YAAW,iBAAiB;IAC9D;;;;;;;;;;;;OAYG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,mBAAmB,GAAG,IAAI;IAqDhE;;;;;;;;;;OAUG;IACH,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM;CAM1D"}

package/dist/voice/parsers/PlivoMediaStreamParser.js

@@ -0,0 +1,92 @@
+/**
+ * Parses the Plivo Audio Stream WebSocket protocol.
+ *
+ * Plivo sends JSON-encoded messages for stream lifecycle events (`start`,
+ * `stop`) and audio chunks (`media`).  The audio payload is base64-encoded
+ * mu-law PCM, delivered in a `payload` field inside the `media` object.
+ *
+ * Outgoing audio is wrapped in a `playAudio` JSON envelope, which is the
+ * format Plivo expects when the server streams audio back to the caller.
+ * No explicit connection acknowledgment is required after the handshake.
+ *
+ * @see {@link https://www.plivo.com/docs/voice/xml/stream}
+ */
+export class PlivoMediaStreamParser {
+    /**
+     * Parse a raw WebSocket frame from Plivo's audio stream.
+     *
+     * Supported Plivo event types:
+     * - `start` — stream established; `stream_id` maps to `streamSid`,
+     *   `call_uuid` maps to `callSid`.
+     * - `media` — audio chunk; `media.payload` contains base64-encoded mu-law.
+     * - `stop`  — stream ended.
+     *
+     * @param data - Raw WebSocket frame payload (JSON string or Buffer from Plivo).
+     * @returns Normalised {@link MediaStreamIncoming} event, or `null` for
+     *   unknown event types or malformed messages.
+     */
+    parseIncoming(data) {
+        const raw = typeof data === 'string' ? data : data.toString('utf8');
+        let msg;
+        try {
+            msg = JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+        const event = msg['event'];
+        const streamSid = msg['stream_id'];
+        if (!event || !streamSid) {
+            return null;
+        }
+        switch (event) {
+            case 'start': {
+                const callSid = msg['call_uuid'] ?? '';
+                const result = {
+                    type: 'start',
+                    streamSid,
+                    callSid,
+                };
+                return result;
+            }
+            case 'media': {
+                const media = msg['media'];
+                if (!media)
+                    return null;
+                const payloadB64 = media['payload'];
+                if (!payloadB64)
+                    return null;
+                const result = {
+                    type: 'audio',
+                    payload: Buffer.from(payloadB64, 'base64'),
+                    streamSid,
+                };
+                return result;
+            }
+            case 'stop': {
+                const result = { type: 'stop', streamSid };
+                return result;
+            }
+            default:
+                return null;
+        }
+    }
+    /**
+     * Encode mu-law audio for transmission back to Plivo.
+     *
+     * Plivo requires audio to be base64-encoded and wrapped in a `playAudio`
+     * JSON envelope.
+     *
+     * @param audio - Raw mu-law PCM bytes to send to the caller.
+     * @param _streamSid - Unused by Plivo's `playAudio` format (accepted for
+     *   interface parity with other parsers).
+     * @returns JSON string conforming to the Plivo `playAudio` envelope.
+     */
+    formatOutgoing(audio, _streamSid) {
+        return JSON.stringify({
+            event: 'playAudio',
+            media: { payload: audio.toString('base64') },
+        });
+    }
+}
+//# sourceMappingURL=PlivoMediaStreamParser.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"PlivoMediaStreamParser.js","sourceRoot":"","sources":["../../../src/voice/parsers/PlivoMediaStreamParser.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,sBAAsB;IACjC;;;;;;;;;;;;OAYG;IACH,aAAa,CAAC,IAAqB;QACjC,MAAM,GAAG,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QAEpE,IAAI,GAA4B,CAAC;QACjC,IAAI,CAAC;YACH,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAA4B,CAAC;QACnD,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;QAED,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,CAAuB,CAAC;QACjD,MAAM,SAAS,GAAG,GAAG,CAAC,WAAW,CAAuB,CAAC;QAEzD,IAAI,CAAC,KAAK,IAAI,CAAC,SAAS,EAAE,CAAC;YACzB,OAAO,IAAI,CAAC;QACd,CAAC;QAED,QAAQ,KAAK,EAAE,CAAC;YACd,KAAK,OAAO,CAAC,CAAC,CAAC;gBACb,MAAM,OAAO,GAAI,GAAG,CAAC,WAAW,CAAwB,IAAI,EAAE,CAAC;gBAC/D,MAAM,MAAM,GAAwB;oBAClC,IAAI,EAAE,OAAO;oBACb,SAAS;oBACT,OAAO;iBACR,CAAC;gBACF,OAAO,MAAM,CAAC;YAChB,CAAC;YAED,KAAK,OAAO,CAAC,CAAC,CAAC;gBACb,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,CAAwC,CAAC;gBAClE,IAAI,CAAC,KAAK;oBAAE,OAAO,IAAI,CAAC;gBAExB,MAAM,UAAU,GAAG,KAAK,CAAC,SAAS,CAAuB,CAAC;gBAC1D,IAAI,CAAC,UAAU;oBAAE,OAAO,IAAI,CAAC;gBAE7B,MAAM,MAAM,GAAwB;oBAClC,IAAI,EAAE,OAAO;oBACb,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,UAAU,EAAE,QAAQ,CAAC;oBAC1C,SAAS;iBACV,CAAC;gBACF,OAAO,MAAM,CAAC;YAChB,CAAC;YAED,KAAK,MAAM,CAAC,CAAC,CAAC;gBACZ,MAAM,MAAM,GAAwB,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;gBAChE,OAAO,MAAM,CAAC;YAChB,CAAC;YAED;gBACE,OAAO,IAAI,CAAC;QAChB,CAAC;IACH,CAAC;IAED;;;;;;;;;;OAUG;IACH,cAAc,CAAC,KAAa,EAAE,UAAkB;QAC9C,OAAO,IAAI,CAAC,SAAS,CAAC;YACpB,KAAK,EAAE,WAAW;YAClB,KAAK,EAAE,EAAE,OAAO,EAAE,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE;SAC7C,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/voice/parsers/TelnyxMediaStreamParser.d.ts

@@ -0,0 +1,51 @@
+import type { MediaStreamParser, MediaStreamIncoming } from '../MediaStreamParser.js';
+/**
+ * Parses the Telnyx media stream WebSocket protocol.
+ *
+ * Telnyx sends JSON-encoded messages for stream lifecycle events (`start`,
+ * `stop`) and audio chunks (`media`).  Unlike Twilio, Telnyx does NOT deliver
+ * DTMF events over the media stream WebSocket — those arrive as HTTP webhooks
+ * to a separate endpoint and must be handled outside this parser.
+ *
+ * Outgoing audio is sent as a **raw binary Buffer** (mu-law PCM bytes without
+ * any JSON envelope) because Telnyx accepts unframed binary WebSocket frames
+ * directly.  No explicit connection acknowledgment is needed after the
+ * handshake.
+ *
+ * @see {@link https://developers.telnyx.com/docs/voice/media-streaming}
+ */
+export declare class TelnyxMediaStreamParser implements MediaStreamParser {
+    /**
+     * Parse a raw WebSocket frame from Telnyx's media stream.
+     *
+     * Supported Telnyx event types:
+     * - `start` — stream established; `stream_id` maps to `streamSid`,
+     *   `call_control_id` maps to `callSid`.
+     * - `media` — audio chunk; `chunk` field contains base64-encoded mu-law
+     *   bytes; only `inbound` track frames are returned.
+     * - `stop`  — stream ended.
+     *
+     * @param data - Raw WebSocket frame payload (JSON string or Buffer from Telnyx).
+     * @returns Normalised {@link MediaStreamIncoming} event, or `null` for
+     *   outbound audio tracks, unknown event types, or malformed messages.
+     */
+    parseIncoming(data: Buffer | string): MediaStreamIncoming | null;
+    /**
+     * Encode mu-law audio for transmission back to Telnyx.
+     *
+     * Telnyx accepts raw binary WebSocket frames; no JSON wrapping is applied.
+     *
+     * @param audio - Raw mu-law PCM bytes to send to the caller.
+     * @param _streamSid - Unused by Telnyx binary framing (accepted for interface
+     *   parity with other parsers).
+     * @returns The audio Buffer unchanged, ready to send as a binary WS frame.
+     */
+    formatOutgoing(audio: Buffer, _streamSid: string): Buffer;
+    /**
+     * No explicit connection acknowledgment is required by Telnyx.
+     *
+     * @returns Always `null`.
+     */
+    formatConnected(_streamSid: string): null;
+}
+//# sourceMappingURL=TelnyxMediaStreamParser.d.ts.map

package/dist/voice/parsers/TelnyxMediaStreamParser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TelnyxMediaStreamParser.d.ts","sourceRoot":"","sources":["../../../src/voice/parsers/TelnyxMediaStreamParser.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAEtF;;;;;;;;;;;;;;GAcG;AACH,qBAAa,uBAAwB,YAAW,iBAAiB;IAC/D;;;;;;;;;;;;;OAaG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,mBAAmB,GAAG,IAAI;IAyDhE;;;;;;;;;OASG;IACH,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM;IAIzD;;;;OAIG;IACH,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;CAG1C"}

package/dist/voice/parsers/TelnyxMediaStreamParser.js

@@ -0,0 +1,103 @@
+/**
+ * Parses the Telnyx media stream WebSocket protocol.
+ *
+ * Telnyx sends JSON-encoded messages for stream lifecycle events (`start`,
+ * `stop`) and audio chunks (`media`).  Unlike Twilio, Telnyx does NOT deliver
+ * DTMF events over the media stream WebSocket — those arrive as HTTP webhooks
+ * to a separate endpoint and must be handled outside this parser.
+ *
+ * Outgoing audio is sent as a **raw binary Buffer** (mu-law PCM bytes without
+ * any JSON envelope) because Telnyx accepts unframed binary WebSocket frames
+ * directly.  No explicit connection acknowledgment is needed after the
+ * handshake.
+ *
+ * @see {@link https://developers.telnyx.com/docs/voice/media-streaming}
+ */
+export class TelnyxMediaStreamParser {
+    /**
+     * Parse a raw WebSocket frame from Telnyx's media stream.
+     *
+     * Supported Telnyx event types:
+     * - `start` — stream established; `stream_id` maps to `streamSid`,
+     *   `call_control_id` maps to `callSid`.
+     * - `media` — audio chunk; `chunk` field contains base64-encoded mu-law
+     *   bytes; only `inbound` track frames are returned.
+     * - `stop`  — stream ended.
+     *
+     * @param data - Raw WebSocket frame payload (JSON string or Buffer from Telnyx).
+     * @returns Normalised {@link MediaStreamIncoming} event, or `null` for
+     *   outbound audio tracks, unknown event types, or malformed messages.
+     */
+    parseIncoming(data) {
+        const raw = typeof data === 'string' ? data : data.toString('utf8');
+        let msg;
+        try {
+            msg = JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+        const event = msg['event'];
+        const streamSid = msg['stream_id'];
+        if (!event || !streamSid) {
+            return null;
+        }
+        switch (event) {
+            case 'start': {
+                const callSid = msg['call_control_id'] ?? '';
+                const result = {
+                    type: 'start',
+                    streamSid,
+                    callSid,
+                };
+                return result;
+            }
+            case 'media': {
+                const media = msg['media'];
+                if (!media)
+                    return null;
+                // Ignore outbound audio echoes from Telnyx.
+                const track = media['track'];
+                if (track === 'outbound')
+                    return null;
+                const chunk = media['chunk'];
+                if (!chunk)
+                    return null;
+                const result = {
+                    type: 'audio',
+                    payload: Buffer.from(chunk, 'base64'),
+                    streamSid,
+                };
+                return result;
+            }
+            case 'stop': {
+                const result = { type: 'stop', streamSid };
+                return result;
+            }
+            default:
+                return null;
+        }
+    }
+    /**
+     * Encode mu-law audio for transmission back to Telnyx.
+     *
+     * Telnyx accepts raw binary WebSocket frames; no JSON wrapping is applied.
+     *
+     * @param audio - Raw mu-law PCM bytes to send to the caller.
+     * @param _streamSid - Unused by Telnyx binary framing (accepted for interface
+     *   parity with other parsers).
+     * @returns The audio Buffer unchanged, ready to send as a binary WS frame.
+     */
+    formatOutgoing(audio, _streamSid) {
+        return audio;
+    }
+    /**
+     * No explicit connection acknowledgment is required by Telnyx.
+     *
+     * @returns Always `null`.
+     */
+    formatConnected(_streamSid) {
+        return null;
+    }
+}
+//# sourceMappingURL=TelnyxMediaStreamParser.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"TelnyxMediaStreamParser.js","sourceRoot":"","sources":["../../../src/voice/parsers/TelnyxMediaStreamParser.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,uBAAuB;IAClC;;;;;;;;;;;;;OAaG;IACH,aAAa,CAAC,IAAqB;QACjC,MAAM,GAAG,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QAEpE,IAAI,GAA4B,CAAC;QACjC,IAAI,CAAC;YACH,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAA4B,CAAC;QACnD,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;QAED,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,CAAuB,CAAC;QACjD,MAAM,SAAS,GAAG,GAAG,CAAC,WAAW,CAAuB,CAAC;QAEzD,IAAI,CAAC,KAAK,IAAI,CAAC,SAAS,EAAE,CAAC;YACzB,OAAO,IAAI,CAAC;QACd,CAAC;QAED,QAAQ,KAAK,EAAE,CAAC;YACd,KAAK,OAAO,CAAC,CAAC,CAAC;gBACb,MAAM,OAAO,GAAI,GAAG,CAAC,iBAAiB,CAAwB,IAAI,EAAE,CAAC;gBACrE,MAAM,MAAM,GAAwB;oBAClC,IAAI,EAAE,OAAO;oBACb,SAAS;oBACT,OAAO;iBACR,CAAC;gBACF,OAAO,MAAM,CAAC;YAChB,CAAC;YAED,KAAK,OAAO,CAAC,CAAC,CAAC;gBACb,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,CAAwC,CAAC;gBAClE,IAAI,CAAC,KAAK;oBAAE,OAAO,IAAI,CAAC;gBAExB,4CAA4C;gBAC5C,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAuB,CAAC;gBACnD,IAAI,KAAK,KAAK,UAAU;oBAAE,OAAO,IAAI,CAAC;gBAEtC,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAuB,CAAC;gBACnD,IAAI,CAAC,KAAK;oBAAE,OAAO,IAAI,CAAC;gBAExB,MAAM,MAAM,GAAwB;oBAClC,IAAI,EAAE,OAAO;oBACb,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,QAAQ,CAAC;oBACrC,SAAS;iBACV,CAAC;gBACF,OAAO,MAAM,CAAC;YAChB,CAAC;YAED,KAAK,MAAM,CAAC,CAAC,CAAC;gBACZ,MAAM,MAAM,GAAwB,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;gBAChE,OAAO,MAAM,CAAC;YAChB,CAAC;YAED;gBACE,OAAO,IAAI,CAAC;QAChB,CAAC;IACH,CAAC;IAED;;;;;;;;;OASG;IACH,cAAc,CAAC,KAAa,EAAE,UAAkB;QAC9C,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;;OAIG;IACH,eAAe,CAAC,UAAkB;QAChC,OAAO,IAAI,CAAC;IACd,CAAC;CACF"}

package/dist/voice/parsers/TwilioMediaStreamParser.d.ts

@@ -0,0 +1,50 @@
+import type { MediaStreamParser, MediaStreamIncoming } from '../MediaStreamParser.js';
+/**
+ * Parses the Twilio `<Connect><Stream>` WebSocket media stream protocol.
+ *
+ * Twilio sends all messages as JSON-encoded strings.  Outbound audio is
+ * wrapped in the same JSON envelope so Twilio can associate it with the
+ * correct stream.  An explicit `connected` acknowledgment is sent once
+ * immediately after the WebSocket handshake to signal that the listener is
+ * ready to receive media.
+ *
+ * @see {@link https://www.twilio.com/docs/voice/twiml/stream}
+ */
+export declare class TwilioMediaStreamParser implements MediaStreamParser {
+    /**
+     * Parse a raw WebSocket frame from Twilio's media stream.
+     *
+     * Supported Twilio event types:
+     * - `start`  — stream established, includes callSid
+     * - `media`  — audio chunk (inbound track only; outbound chunks are ignored)
+     * - `dtmf`   — DTMF keypress detected
+     * - `stop`   — stream ended
+     * - `mark`   — named synchronisation marker
+     *
+     * @param data - Raw WebSocket frame payload (always a JSON string from Twilio).
+     * @returns Normalised {@link MediaStreamIncoming} event, or `null` for
+     *   outbound audio tracks, unknown event types, or malformed messages.
+     */
+    parseIncoming(data: Buffer | string): MediaStreamIncoming | null;
+    /**
+     * Encode mu-law audio for transmission back to the Twilio stream.
+     *
+     * Twilio requires base64-encoded audio wrapped in a JSON `media` envelope
+     * so it can route the audio to the correct stream.
+     *
+     * @param audio - Raw mu-law PCM bytes to send to the caller.
+     * @param streamSid - The stream identifier to include in the envelope.
+     * @returns JSON string conforming to the Twilio media-out envelope format.
+     */
+    formatOutgoing(audio: Buffer, streamSid: string): string;
+    /**
+     * Generate the initial `connected` acknowledgment expected by Twilio
+     * immediately after the WebSocket connection is established.
+     *
+     * @param _streamSid - Unused — Twilio does not require the stream ID in the
+     *   `connected` message, but the parameter is accepted for interface parity.
+     * @returns JSON string with the `connected` envelope.
+     */
+    formatConnected(_streamSid: string): string;
+}
+//# sourceMappingURL=TwilioMediaStreamParser.d.ts.map

package/dist/voice/parsers/TwilioMediaStreamParser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TwilioMediaStreamParser.d.ts","sourceRoot":"","sources":["../../../src/voice/parsers/TwilioMediaStreamParser.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAEtF;;;;;;;;;;GAUG;AACH,qBAAa,uBAAwB,YAAW,iBAAiB;IAC/D;;;;;;;;;;;;;OAaG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,mBAAmB,GAAG,IAAI;IA+FhE;;;;;;;;;OASG;IACH,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM;IAQxD;;;;;;;OAOG;IACH,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM;CAO5C"}