@memberjunction/ai-bridge-twilio 5.44.0 → 5.45.1

package/README.md

@@ -106,3 +106,30 @@ all with no network.
 ```bash
 cd packages/AI/Providers/BridgeTwilio && npm run test
 ```
+
+### Production REST wiring (`RealTwilioRestClient`)
+
+`RealTwilioRestClient` is the production `ITwilioRestLike` over the real `twilio` SDK (an
+`optionalDependency`, lazily loaded — the package still builds/tests with no `twilio` install). It maps
+`CreateCall` → `client.calls.create({ to, from, twiml, statusCallback })` and `UpdateCall` →
+`client.calls(sid).update({ status, twiml })`. Construct it with credentials resolved from MJ config
+(API-key pair preferred over the account auth token); pass it as the `Rest` half of `RealTwilioBindings`
+(the `MediaPump` half is the Media-Streams websocket, owned by the MJAPI telephony ingress). Unit-tested
+via an injected fake `twilio` factory — no network.
+
+### Credential-gated integration test (NOT in CI)
+
+`real-twilio-bindings.integration.test.ts` places a real outbound call and ends it. It is `skipIf`-gated
+on these env vars and never runs in CI (it spends real money + dials real PSTN):
+
+| Env var | Purpose |
+|---|---|
+| `TWILIO_TEST_ACCOUNT_SID` | Twilio Account SID (`AC…`). |
+| `TWILIO_TEST_AUTH_TOKEN` | Account auth token. |
+| `TWILIO_TEST_FROM` | A Twilio number you own (caller-id). |
+| `TWILIO_TEST_TO` | A capped-spend test number that auto-answers. |
+| `TWILIO_TEST_STREAM_URL` | (optional) the `wss://…/telephony/twilio/media` URL for the `<Connect><Stream>`. |
+
+Run locally: `npm run test -- real-twilio-bindings.integration`. The full media round-trip (audio through
+the agent) needs the MJAPI ingress + a publicly reachable stream URL — see the T1 ingress notes + manual
+runbook.

package/dist/index.d.ts

@@ -1,5 +1,8 @@
 export * from './twilio-call-sdk.js';
 export * from './twilio-native-call-sdk.js';
+export * from './real-twilio-bindings.js';
+export * from './twilio-rest-client.js';
+export * from './twilio-ingress.js';
 export * from './twilio-bridge.js';
 export * from './register-native.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC"}

package/dist/index.js

@@ -1,5 +1,8 @@
 export * from './twilio-call-sdk.js';
 export * from './twilio-native-call-sdk.js';
+export * from './real-twilio-bindings.js';
+export * from './twilio-rest-client.js';
+export * from './twilio-ingress.js';
 export * from './twilio-bridge.js';
 export * from './register-native.js';
 import { LoadTwilioBridge } from './twilio-bridge.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAElC,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAE5D,wGAAwG;AACxG,iGAAiG;AACjG,gBAAgB,EAAE,CAAC;AACnB,uGAAuG;AACvG,uBAAuB,EAAE,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAElC,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAE5D,wGAAwG;AACxG,iGAAiG;AACjG,gBAAgB,EAAE,CAAC;AACnB,uGAAuG;AACvG,uBAAuB,EAAE,CAAC"}

package/dist/real-twilio-bindings.d.ts

@@ -0,0 +1,174 @@
+/**
+ * @fileoverview `RealTwilioBindings` — a production {@link ITwilioClientBindings} implementation over the
+ * real **Twilio Programmable Voice REST API** + **Media Streams** websocket, plus the **pure** TwiML /
+ * media-frame helpers it (and the MJAPI ingress) build on.
+ *
+ * ## Why an injected client surface (not `import twilio from 'twilio'`)
+ * To stay buildable + unit-testable WITHOUT the `twilio` npm package installed and WITHOUT any network,
+ * this module does NOT import `twilio` directly. Instead it depends on a tiny, local structural surface —
+ * {@link ITwilioRestLike} (the few REST calls we use: `calls.create(...)`, `calls(sid).update(...)`) and
+ * {@link ITwilioMediaPump} (the bidirectional Media-Streams frame pump). Production wires these over the
+ * real `twilio` SDK + a websocket; tests inject fakes. `twilio` is declared in `optionalDependencies`
+ * (CLAUDE rule 8, category 2 — optional peer SDK loaded only when the provider is configured) and is
+ * resolved by the host's native-adapter wiring, never statically imported here.
+ *
+ * ## The audio contract (T0 codec)
+ * Twilio Media Streams deliver **base64-encoded G.711 μ-law @ 8 kHz mono** on the wire; the
+ * {@link ITwilioClientBindings} seam speaks **PCM16 `ArrayBuffer`**. All transcoding goes through the
+ * shared T0 codec ({@link muLawToPcm16Buffer} / {@link pcm16ToMuLawBuffer} from
+ * `@memberjunction/ai-bridge-base`) — never reimplemented here. The pure helpers
+ * {@link parseTwilioMediaFrame} / {@link encodeTwilioMediaFrame} do the base64↔codec mapping so they
+ * unit-test with no network.
+ *
+ * @module @memberjunction/ai-bridge-twilio
+ * @author MemberJunction.com
+ * @see {@link ITwilioClientBindings} — the seam this implements.
+ * @see `/plans/realtime/bridges-and-widget/telephony-vendor-bindings.md` §2, §3 (T1).
+ */
+import { ITwilioClientBindings } from './twilio-call-sdk.js';
+/**
+ * Builds the outbound-dial / inbound-answer TwiML that opens a **bidirectional** Media-Streams websocket
+ * to the agent's media endpoint. `<Connect><Stream>` (not `<Start><Stream>`) is the bidirectional form:
+ * Twilio both sends inbound audio AND accepts outbound `media` frames on the same socket — the full-duplex
+ * leg the agent needs.
+ *
+ * Pure + exported so it unit-tests with no network and the MJAPI router can reuse it verbatim.
+ *
+ * @param streamUrl The `wss://…` Media-Streams endpoint Twilio connects the call's audio to.
+ * @returns The TwiML document string to return to Twilio (REST `twiml` param or webhook response body).
+ */
+export declare function buildConnectStreamTwiML(streamUrl: string): string;
+/** One Twilio Media-Streams `media` frame as it appears (post-JSON-parse) on the websocket. */
+export interface TwilioMediaFrame {
+    /** Always `'media'` for an audio frame (vs `'start'`/`'stop'`/`'dtmf'` events). */
+    event: string;
+    /** The Media-Streams stream identifier (present on `media`/`start`/`stop`). */
+    streamSid?: string;
+    /** The media payload — `payload` is base64-encoded μ-law/8k audio. */
+    media?: {
+        /** Base64-encoded G.711 μ-law @ 8 kHz mono audio bytes. */
+        payload: string;
+        /** Monotonic frame timestamp (ms since stream start), Twilio-supplied. */
+        timestamp?: string;
+        /** Monotonic chunk counter, Twilio-supplied. */
+        chunk?: string;
+    };
+    /** The DTMF payload (present on `dtmf` events) — the pressed key. */
+    dtmf?: {
+        /** The DTMF digit Twilio detected on the stream (`0`-`9`, `*`, `#`). */
+        digit: string;
+    };
+}
+/**
+ * **Pure** decode of one inbound Twilio Media-Streams `media` frame to a PCM16 `ArrayBuffer` — base64
+ * μ-law → μ-law bytes → PCM16 via the T0 codec ({@link muLawToPcm16Buffer}). Returns `null` for any
+ * non-`media` event or a frame with no payload, so the caller can ignore `start`/`stop`/`dtmf` cleanly.
+ *
+ * @param frame The parsed Media-Streams frame object.
+ * @returns The decoded PCM16 audio, or `null` when the frame carries no audio payload.
+ */
+export declare function parseTwilioMediaFrame(frame: TwilioMediaFrame): ArrayBuffer | null;
+/**
+ * **Pure** encode of one outbound PCM16 `ArrayBuffer` into the Twilio Media-Streams outbound `media` frame
+ * shape — PCM16 → μ-law via the T0 codec ({@link pcm16ToMuLawBuffer}) → base64 payload. The returned object
+ * is `JSON.stringify`-ready for the websocket send.
+ *
+ * @param pcm The agent's outbound PCM16 audio.
+ * @param streamSid The Media-Streams stream SID the frame is addressed to.
+ * @returns A Media-Streams outbound `media` frame ready to JSON-serialize and send.
+ */
+export declare function encodeTwilioMediaFrame(pcm: ArrayBuffer, streamSid: string): TwilioMediaFrame;
+/** The REST payload {@link ITwilioRestLike.calls.create} accepts (the subset we use). */
+export interface TwilioCreateCallParams {
+    /** Destination number (E.164). Maps to Twilio's `to`. */
+    To: string;
+    /** Originating caller-id / DID. Maps to Twilio's `from`. */
+    From: string;
+    /** The TwiML executed when the call connects (our `<Connect><Stream>`). Maps to Twilio's `twiml`. */
+    Twiml: string;
+    /** Optional status-callback URL for lifecycle events. Maps to Twilio's `statusCallback`. */
+    StatusCallback?: string;
+}
+/** The REST update payload {@link ITwilioRestLike} `calls(sid).update` accepts (the subset we use). */
+export interface TwilioUpdateCallParams {
+    /** New call status — `'completed'` ends the call. */
+    Status?: 'completed' | 'canceled';
+    /** Replacement TwiML — used for transfer (`<Dial>…`) and DTMF (`<Play digits>…`). */
+    Twiml?: string;
+}
+/**
+ * The minimal Twilio REST surface {@link RealTwilioBindings} drives — just the two calls we need:
+ * `calls.create(...)` (outbound dial) and `calls(sid).update(...)` (hangup / transfer / DTMF). A
+ * production wiring implements this over `twilio(accountSid, authToken).calls`; tests inject a fake.
+ */
+export interface ITwilioRestLike {
+    /** Creates an outbound call; resolves the created Call SID. */
+    CreateCall(params: TwilioCreateCallParams): Promise<string>;
+    /** Updates an existing call (end / transfer / send-DTMF) by SID. */
+    UpdateCall(callSid: string, params: TwilioUpdateCallParams): Promise<void>;
+}
+/**
+ * The bidirectional Media-Streams frame pump for a single call's websocket. Production wires this over the
+ * accepted websocket for the Call SID; tests inject a fake. The pump speaks raw frame objects — transcode
+ * happens in {@link RealTwilioBindings} via the pure helpers above.
+ */
+export interface ITwilioMediaPump {
+    /** Sends one outbound Media-Streams frame on the call's websocket. */
+    Send(callSid: string, frame: TwilioMediaFrame): void;
+    /** Registers the inbound-frame handler for the call's websocket (latest handler wins). */
+    OnFrame(callSid: string, handler: (frame: TwilioMediaFrame) => void): void;
+    /** Registers the call's stream-SID resolver, so outbound frames address the right stream. */
+    GetStreamSid(callSid: string): string;
+}
+/** Options {@link RealTwilioBindings} needs at construction — the injected client surfaces + the stream URL. */
+export interface RealTwilioBindingsOptions {
+    /** The REST client surface (outbound dial / update). */
+    Rest: ITwilioRestLike;
+    /** The Media-Streams frame pump (bidirectional audio). */
+    MediaPump: ITwilioMediaPump;
+    /** The `wss://…` Media-Streams endpoint the call's `<Connect><Stream>` connects to. */
+    StreamUrl: string;
+    /** Optional status-callback URL passed on outbound `createCall`. */
+    StatusCallbackUrl?: string;
+}
+/**
+ * Production {@link ITwilioClientBindings} over the real Twilio REST API + Media Streams, expressed against
+ * the injected {@link ITwilioRestLike} / {@link ITwilioMediaPump} surfaces so it builds and unit-tests with
+ * no `twilio` install and no network.
+ *
+ * - `createCall` → REST `calls.create` with the `<Connect><Stream>` TwiML.
+ * - `acceptInbound` → no REST call (the inbound webhook already returned the connect TwiML); the websocket
+ *   for the delivered Call SID is what "accepting" means — handled by {@link onStreamAudio}.
+ * - `completeCall` / `redirectCall` / `playDigits` → REST `calls(sid).update`.
+ * - `pushStreamAudio` / `onStreamAudio` → Media-Streams frames, transcoded through the T0 codec.
+ */
+export declare class RealTwilioBindings implements ITwilioClientBindings {
+    private readonly rest;
+    private readonly mediaPump;
+    private readonly streamUrl;
+    private readonly statusCallbackUrl?;
+    constructor(options: RealTwilioBindingsOptions);
+    /** @inheritdoc */
+    createCall(toNumber: string, fromNumber: string, args?: Record<string, unknown>): Promise<string>;
+    /** @inheritdoc */
+    acceptInbound(_callSid: string): Promise<void>;
+    /** @inheritdoc */
+    completeCall(callSid: string): Promise<void>;
+    /** @inheritdoc */
+    pushStreamAudio(callSid: string, pcm: ArrayBuffer): void;
+    /** @inheritdoc */
+    onStreamAudio(callSid: string, cb: (pcm: ArrayBuffer) => void): void;
+    /** @inheritdoc */
+    playDigits(callSid: string, digits: string): Promise<void>;
+    /** @inheritdoc */
+    onDigits(callSid: string, cb: (digits: string) => void): void;
+    /** @inheritdoc */
+    redirectCall(callSid: string, toNumber: string): Promise<void>;
+    /** @inheritdoc */
+    onCallStatus(callSid: string, cb: () => void): void;
+}
+/** Builds the `<Play digits>` TwiML used to emit DTMF tones on a live call (REST update). */
+export declare function buildPlayDigitsTwiML(digits: string): string;
+/** Builds the `<Dial>` TwiML used to transfer a live call to another number (REST update). */
+export declare function buildDialTwiML(toNumber: string): string;
+//# sourceMappingURL=real-twilio-bindings.d.ts.map

package/dist/real-twilio-bindings.d.ts.map

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

package/dist/real-twilio-bindings.js

@@ -0,0 +1,208 @@
+/**
+ * @fileoverview `RealTwilioBindings` — a production {@link ITwilioClientBindings} implementation over the
+ * real **Twilio Programmable Voice REST API** + **Media Streams** websocket, plus the **pure** TwiML /
+ * media-frame helpers it (and the MJAPI ingress) build on.
+ *
+ * ## Why an injected client surface (not `import twilio from 'twilio'`)
+ * To stay buildable + unit-testable WITHOUT the `twilio` npm package installed and WITHOUT any network,
+ * this module does NOT import `twilio` directly. Instead it depends on a tiny, local structural surface —
+ * {@link ITwilioRestLike} (the few REST calls we use: `calls.create(...)`, `calls(sid).update(...)`) and
+ * {@link ITwilioMediaPump} (the bidirectional Media-Streams frame pump). Production wires these over the
+ * real `twilio` SDK + a websocket; tests inject fakes. `twilio` is declared in `optionalDependencies`
+ * (CLAUDE rule 8, category 2 — optional peer SDK loaded only when the provider is configured) and is
+ * resolved by the host's native-adapter wiring, never statically imported here.
+ *
+ * ## The audio contract (T0 codec)
+ * Twilio Media Streams deliver **base64-encoded G.711 μ-law @ 8 kHz mono** on the wire; the
+ * {@link ITwilioClientBindings} seam speaks **PCM16 `ArrayBuffer`**. All transcoding goes through the
+ * shared T0 codec ({@link muLawToPcm16Buffer} / {@link pcm16ToMuLawBuffer} from
+ * `@memberjunction/ai-bridge-base`) — never reimplemented here. The pure helpers
+ * {@link parseTwilioMediaFrame} / {@link encodeTwilioMediaFrame} do the base64↔codec mapping so they
+ * unit-test with no network.
+ *
+ * @module @memberjunction/ai-bridge-twilio
+ * @author MemberJunction.com
+ * @see {@link ITwilioClientBindings} — the seam this implements.
+ * @see `/plans/realtime/bridges-and-widget/telephony-vendor-bindings.md` §2, §3 (T1).
+ */
+import { muLawToPcm16Buffer, pcm16ToMuLawBuffer } from '@memberjunction/ai-bridge-base';
+// ──────────────────────────────────────────────────────────────────────────────
+// Pure helpers — TwiML + Media-Streams frame transcode. No network, no SDK.
+// ──────────────────────────────────────────────────────────────────────────────
+/**
+ * Builds the outbound-dial / inbound-answer TwiML that opens a **bidirectional** Media-Streams websocket
+ * to the agent's media endpoint. `<Connect><Stream>` (not `<Start><Stream>`) is the bidirectional form:
+ * Twilio both sends inbound audio AND accepts outbound `media` frames on the same socket — the full-duplex
+ * leg the agent needs.
+ *
+ * Pure + exported so it unit-tests with no network and the MJAPI router can reuse it verbatim.
+ *
+ * @param streamUrl The `wss://…` Media-Streams endpoint Twilio connects the call's audio to.
+ * @returns The TwiML document string to return to Twilio (REST `twiml` param or webhook response body).
+ */
+export function buildConnectStreamTwiML(streamUrl) {
+    const escaped = escapeXmlAttribute(streamUrl);
+    return ('<?xml version="1.0" encoding="UTF-8"?>' +
+        '<Response>' +
+        '<Connect>' +
+        `<Stream url="${escaped}" />` +
+        '</Connect>' +
+        '</Response>');
+}
+/**
+ * **Pure** decode of one inbound Twilio Media-Streams `media` frame to a PCM16 `ArrayBuffer` — base64
+ * μ-law → μ-law bytes → PCM16 via the T0 codec ({@link muLawToPcm16Buffer}). Returns `null` for any
+ * non-`media` event or a frame with no payload, so the caller can ignore `start`/`stop`/`dtmf` cleanly.
+ *
+ * @param frame The parsed Media-Streams frame object.
+ * @returns The decoded PCM16 audio, or `null` when the frame carries no audio payload.
+ */
+export function parseTwilioMediaFrame(frame) {
+    if (frame.event !== 'media' || !frame.media || !frame.media.payload) {
+        return null;
+    }
+    const mulaw = base64ToArrayBuffer(frame.media.payload);
+    return muLawToPcm16Buffer(mulaw);
+}
+/**
+ * **Pure** encode of one outbound PCM16 `ArrayBuffer` into the Twilio Media-Streams outbound `media` frame
+ * shape — PCM16 → μ-law via the T0 codec ({@link pcm16ToMuLawBuffer}) → base64 payload. The returned object
+ * is `JSON.stringify`-ready for the websocket send.
+ *
+ * @param pcm The agent's outbound PCM16 audio.
+ * @param streamSid The Media-Streams stream SID the frame is addressed to.
+ * @returns A Media-Streams outbound `media` frame ready to JSON-serialize and send.
+ */
+export function encodeTwilioMediaFrame(pcm, streamSid) {
+    const mulaw = pcm16ToMuLawBuffer(pcm);
+    return {
+        event: 'media',
+        streamSid,
+        media: { payload: arrayBufferToBase64(mulaw) },
+    };
+}
+/** Escapes the five XML attribute-significant characters so a stream URL is safe inside the TwiML attribute. */
+function escapeXmlAttribute(value) {
+    return value
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&apos;');
+}
+/** Decodes a base64 string to a fresh `ArrayBuffer` (Node `Buffer` path; works in any Node runtime). */
+function base64ToArrayBuffer(base64) {
+    const buf = Buffer.from(base64, 'base64');
+    const out = new ArrayBuffer(buf.length);
+    new Uint8Array(out).set(buf);
+    return out;
+}
+/** Encodes an `ArrayBuffer` to a base64 string (Node `Buffer` path; works in any Node runtime). */
+function arrayBufferToBase64(buffer) {
+    return Buffer.from(new Uint8Array(buffer)).toString('base64');
+}
+/**
+ * Production {@link ITwilioClientBindings} over the real Twilio REST API + Media Streams, expressed against
+ * the injected {@link ITwilioRestLike} / {@link ITwilioMediaPump} surfaces so it builds and unit-tests with
+ * no `twilio` install and no network.
+ *
+ * - `createCall` → REST `calls.create` with the `<Connect><Stream>` TwiML.
+ * - `acceptInbound` → no REST call (the inbound webhook already returned the connect TwiML); the websocket
+ *   for the delivered Call SID is what "accepting" means — handled by {@link onStreamAudio}.
+ * - `completeCall` / `redirectCall` / `playDigits` → REST `calls(sid).update`.
+ * - `pushStreamAudio` / `onStreamAudio` → Media-Streams frames, transcoded through the T0 codec.
+ */
+export class RealTwilioBindings {
+    constructor(options) {
+        this.rest = options.Rest;
+        this.mediaPump = options.MediaPump;
+        this.streamUrl = options.StreamUrl;
+        this.statusCallbackUrl = options.StatusCallbackUrl;
+    }
+    /** @inheritdoc */
+    async createCall(toNumber, fromNumber, args) {
+        const statusCallback = readStatusCallback(args) ?? this.statusCallbackUrl;
+        return this.rest.CreateCall({
+            To: toNumber,
+            From: fromNumber,
+            Twiml: buildConnectStreamTwiML(this.streamUrl),
+            ...(statusCallback ? { StatusCallback: statusCallback } : {}),
+        });
+    }
+    /** @inheritdoc */
+    async acceptInbound(_callSid) {
+        // No REST call: the inbound voice webhook already returned the <Connect><Stream> TwiML that connects
+        // the media socket. "Accepting" is consuming that socket — wired via onStreamAudio/pushStreamAudio.
+    }
+    /** @inheritdoc */
+    async completeCall(callSid) {
+        await this.rest.UpdateCall(callSid, { Status: 'completed' });
+    }
+    /** @inheritdoc */
+    pushStreamAudio(callSid, pcm) {
+        const streamSid = this.mediaPump.GetStreamSid(callSid);
+        this.mediaPump.Send(callSid, encodeTwilioMediaFrame(pcm, streamSid));
+    }
+    /** @inheritdoc */
+    onStreamAudio(callSid, cb) {
+        this.mediaPump.OnFrame(callSid, (frame) => {
+            const pcm = parseTwilioMediaFrame(frame);
+            if (pcm) {
+                cb(pcm);
+            }
+        });
+    }
+    /** @inheritdoc */
+    async playDigits(callSid, digits) {
+        await this.rest.UpdateCall(callSid, { Twiml: buildPlayDigitsTwiML(digits) });
+    }
+    /** @inheritdoc */
+    onDigits(callSid, cb) {
+        this.mediaPump.OnFrame(callSid, (frame) => {
+            const digit = readDtmfDigit(frame);
+            if (digit) {
+                cb(digit);
+            }
+        });
+    }
+    /** @inheritdoc */
+    async redirectCall(callSid, toNumber) {
+        await this.rest.UpdateCall(callSid, { Twiml: buildDialTwiML(toNumber) });
+    }
+    /** @inheritdoc */
+    onCallStatus(callSid, cb) {
+        this.mediaPump.OnFrame(callSid, (frame) => {
+            if (frame.event === 'stop') {
+                cb();
+            }
+        });
+    }
+}
+/** Builds the `<Play digits>` TwiML used to emit DTMF tones on a live call (REST update). */
+export function buildPlayDigitsTwiML(digits) {
+    return ('<?xml version="1.0" encoding="UTF-8"?>' +
+        '<Response>' +
+        `<Play digits="${escapeXmlAttribute(digits)}" />` +
+        '</Response>');
+}
+/** Builds the `<Dial>` TwiML used to transfer a live call to another number (REST update). */
+export function buildDialTwiML(toNumber) {
+    return ('<?xml version="1.0" encoding="UTF-8"?>' +
+        '<Response>' +
+        `<Dial>${escapeXmlAttribute(toNumber)}</Dial>` +
+        '</Response>');
+}
+/** Reads an optional `StatusCallback` string out of the loose dial args without widening to `any`. */
+function readStatusCallback(args) {
+    const value = args?.['StatusCallback'];
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+/** Reads a DTMF digit out of a Media-Streams `dtmf` event frame, or `undefined` for non-DTMF frames. */
+function readDtmfDigit(frame) {
+    if (frame.event !== 'dtmf') {
+        return undefined;
+    }
+    const digit = frame.dtmf?.digit;
+    return typeof digit === 'string' && digit.length > 0 ? digit : undefined;
+}
+//# sourceMappingURL=real-twilio-bindings.js.map

package/dist/real-twilio-bindings.js.map

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

package/dist/twilio-ingress.d.ts

@@ -0,0 +1,73 @@
+/**
+ * @fileoverview Twilio inbound-ingress **pure** helpers — request-signature verification, the inbound
+ * voice TwiML, and the webhook→call mapper. These are the framework-free pieces of the MJAPI Twilio
+ * ingress: no Express, no network, no DB, so they unit-test directly and the MJAPI router can call them
+ * verbatim once the live wiring lands.
+ *
+ * The remaining **live** ingress — `POST /telephony/twilio/voice`, `WSS /telephony/twilio/media`, the
+ * `Telephony.PlaceCall` mutation, and the credential config block — is documented in
+ * `plans/realtime/bridges-and-widget/spikes/T1-twilio-ingress-notes.md` and is gated on real Twilio
+ * credentials + a publicly reachable URL.
+ *
+ * @module @memberjunction/ai-bridge-twilio
+ * @author MemberJunction.com
+ * @see `/plans/realtime/bridges-and-widget/telephony-vendor-bindings.md` §2 (B), §3 (T1 B/C).
+ */
+/**
+ * Verifies a Twilio webhook request signature per Twilio's documented scheme:
+ *
+ * 1. Start from the full request URL (scheme + host + path + query, exactly as Twilio called it).
+ * 2. Append each POST param, sorted by parameter name, as `key + value` concatenated (no separators).
+ * 3. HMAC-SHA1 the resulting string with the account **Auth Token** as the key; base64-encode the digest.
+ * 4. Constant-time-compare against the `X-Twilio-Signature` header.
+ *
+ * A missing/empty signature header rejects. Comparison is constant-time ({@link timingSafeEqual}) to avoid
+ * leaking the expected signature via timing. Pure + exported so it unit-tests with a known vector and the
+ * MJAPI router calls it on every public Twilio endpoint (these can't carry an MJ JWT).
+ *
+ * @param authToken The Twilio account Auth Token (the HMAC key; resolved upstream — never inlined).
+ * @param signatureHeader The `X-Twilio-Signature` request header value.
+ * @param url The full request URL exactly as Twilio invoked it.
+ * @param params The POST form parameters Twilio sent.
+ * @returns `true` when the signature is valid; `false` otherwise (including a missing header).
+ */
+export declare function verifyTwilioSignature(authToken: string, signatureHeader: string | undefined, url: string, params: Record<string, string>): boolean;
+/**
+ * Computes the Twilio request signature (base64 HMAC-SHA1) for a URL + sorted params. Exported so tests can
+ * construct a known-good vector and the live router can sign/verify without duplicating the concat rule.
+ *
+ * @param authToken The Twilio Auth Token (HMAC key).
+ * @param url The full request URL exactly as Twilio invoked it.
+ * @param params The POST form parameters.
+ * @returns The base64-encoded HMAC-SHA1 signature.
+ */
+export declare function computeTwilioSignature(authToken: string, url: string, params: Record<string, string>): string;
+/**
+ * The TwiML returned to an inbound call's voice webhook to connect its bidirectional Media-Streams socket.
+ * Identical `<Connect><Stream>` shape as the outbound path (it reuses {@link buildConnectStreamTwiML}), so
+ * inbound and outbound legs share one media contract.
+ *
+ * @param streamWssUrl The `wss://…/telephony/twilio/media` endpoint to connect the inbound call's audio to.
+ * @returns The TwiML document string to return to Twilio as the webhook response.
+ */
+export declare function buildInboundVoiceTwiML(streamWssUrl: string): string;
+/** The resolved identity of an inbound Twilio call, mapped from the voice-webhook params. */
+export interface ResolvedInboundCall {
+    /** The inbound Call SID (Twilio `CallSid`). */
+    callSid: string;
+    /** The caller's number (Twilio `From`). */
+    from: string;
+    /** The dialed DID the call came in on (Twilio `To`). */
+    to: string;
+}
+/**
+ * Maps the Twilio inbound voice-webhook params to a {@link ResolvedInboundCall}. Pure + exported so the
+ * MJAPI router resolves the dialed DID → agent identity → `AIBridgeEngine.StartBridgeSession` without
+ * re-parsing Twilio's param names. Throws when a required param is absent so a malformed webhook fails loud.
+ *
+ * @param params The Twilio inbound voice-webhook POST params.
+ * @returns The `{ callSid, from, to }` mapping.
+ * @throws When `CallSid`, `From`, or `To` is missing.
+ */
+export declare function resolveInboundCall(params: Record<string, string>): ResolvedInboundCall;
+//# sourceMappingURL=twilio-ingress.d.ts.map

package/dist/twilio-ingress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"twilio-ingress.d.ts","sourceRoot":"","sources":["../src/twilio-ingress.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qBAAqB,CACjC,SAAS,EAAE,MAAM,EACjB,eAAe,EAAE,MAAM,GAAG,SAAS,EACnC,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC/B,OAAO,CAMT;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAG7G;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAEnE;AAED,6FAA6F;AAC7F,MAAM,WAAW,mBAAmB;IAChC,+CAA+C;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,EAAE,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,mBAAmB,CAWtF"}

package/dist/twilio-ingress.js

@@ -0,0 +1,102 @@
+/**
+ * @fileoverview Twilio inbound-ingress **pure** helpers — request-signature verification, the inbound
+ * voice TwiML, and the webhook→call mapper. These are the framework-free pieces of the MJAPI Twilio
+ * ingress: no Express, no network, no DB, so they unit-test directly and the MJAPI router can call them
+ * verbatim once the live wiring lands.
+ *
+ * The remaining **live** ingress — `POST /telephony/twilio/voice`, `WSS /telephony/twilio/media`, the
+ * `Telephony.PlaceCall` mutation, and the credential config block — is documented in
+ * `plans/realtime/bridges-and-widget/spikes/T1-twilio-ingress-notes.md` and is gated on real Twilio
+ * credentials + a publicly reachable URL.
+ *
+ * @module @memberjunction/ai-bridge-twilio
+ * @author MemberJunction.com
+ * @see `/plans/realtime/bridges-and-widget/telephony-vendor-bindings.md` §2 (B), §3 (T1 B/C).
+ */
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import { buildConnectStreamTwiML } from './real-twilio-bindings.js';
+/**
+ * Verifies a Twilio webhook request signature per Twilio's documented scheme:
+ *
+ * 1. Start from the full request URL (scheme + host + path + query, exactly as Twilio called it).
+ * 2. Append each POST param, sorted by parameter name, as `key + value` concatenated (no separators).
+ * 3. HMAC-SHA1 the resulting string with the account **Auth Token** as the key; base64-encode the digest.
+ * 4. Constant-time-compare against the `X-Twilio-Signature` header.
+ *
+ * A missing/empty signature header rejects. Comparison is constant-time ({@link timingSafeEqual}) to avoid
+ * leaking the expected signature via timing. Pure + exported so it unit-tests with a known vector and the
+ * MJAPI router calls it on every public Twilio endpoint (these can't carry an MJ JWT).
+ *
+ * @param authToken The Twilio account Auth Token (the HMAC key; resolved upstream — never inlined).
+ * @param signatureHeader The `X-Twilio-Signature` request header value.
+ * @param url The full request URL exactly as Twilio invoked it.
+ * @param params The POST form parameters Twilio sent.
+ * @returns `true` when the signature is valid; `false` otherwise (including a missing header).
+ */
+export function verifyTwilioSignature(authToken, signatureHeader, url, params) {
+    if (!signatureHeader) {
+        return false;
+    }
+    const expected = computeTwilioSignature(authToken, url, params);
+    return constantTimeEquals(expected, signatureHeader);
+}
+/**
+ * Computes the Twilio request signature (base64 HMAC-SHA1) for a URL + sorted params. Exported so tests can
+ * construct a known-good vector and the live router can sign/verify without duplicating the concat rule.
+ *
+ * @param authToken The Twilio Auth Token (HMAC key).
+ * @param url The full request URL exactly as Twilio invoked it.
+ * @param params The POST form parameters.
+ * @returns The base64-encoded HMAC-SHA1 signature.
+ */
+export function computeTwilioSignature(authToken, url, params) {
+    const data = url + concatSortedParams(params);
+    return createHmac('sha1', authToken).update(data, 'utf8').digest('base64');
+}
+/**
+ * The TwiML returned to an inbound call's voice webhook to connect its bidirectional Media-Streams socket.
+ * Identical `<Connect><Stream>` shape as the outbound path (it reuses {@link buildConnectStreamTwiML}), so
+ * inbound and outbound legs share one media contract.
+ *
+ * @param streamWssUrl The `wss://…/telephony/twilio/media` endpoint to connect the inbound call's audio to.
+ * @returns The TwiML document string to return to Twilio as the webhook response.
+ */
+export function buildInboundVoiceTwiML(streamWssUrl) {
+    return buildConnectStreamTwiML(streamWssUrl);
+}
+/**
+ * Maps the Twilio inbound voice-webhook params to a {@link ResolvedInboundCall}. Pure + exported so the
+ * MJAPI router resolves the dialed DID → agent identity → `AIBridgeEngine.StartBridgeSession` without
+ * re-parsing Twilio's param names. Throws when a required param is absent so a malformed webhook fails loud.
+ *
+ * @param params The Twilio inbound voice-webhook POST params.
+ * @returns The `{ callSid, from, to }` mapping.
+ * @throws When `CallSid`, `From`, or `To` is missing.
+ */
+export function resolveInboundCall(params) {
+    const callSid = params['CallSid'];
+    const from = params['From'];
+    const to = params['To'];
+    if (!callSid || !from || !to) {
+        throw new Error('resolveInboundCall: Twilio inbound webhook missing a required param (CallSid / From / To). ' +
+            `Got keys: [${Object.keys(params).join(', ')}].`);
+    }
+    return { callSid, from, to };
+}
+/** Concatenates params sorted by key as `key + value` (Twilio's signature input), with no separators. */
+function concatSortedParams(params) {
+    return Object.keys(params)
+        .sort()
+        .map((key) => key + params[key])
+        .join('');
+}
+/** Constant-time string compare on the base64 signatures, length-safe (mismatched lengths return false). */
+function constantTimeEquals(a, b) {
+    const bufA = new Uint8Array(Buffer.from(a, 'utf8'));
+    const bufB = new Uint8Array(Buffer.from(b, 'utf8'));
+    if (bufA.length !== bufB.length) {
+        return false;
+    }
+    return timingSafeEqual(bufA, bufB);
+}
+//# sourceMappingURL=twilio-ingress.js.map

package/dist/twilio-ingress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"twilio-ingress.js","sourceRoot":"","sources":["../src/twilio-ingress.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AAEjE;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,qBAAqB,CACjC,SAAiB,EACjB,eAAmC,EACnC,GAAW,EACX,MAA8B;IAE9B,IAAI,CAAC,eAAe,EAAE,CAAC;QACnB,OAAO,KAAK,CAAC;IACjB,CAAC;IACD,MAAM,QAAQ,GAAG,sBAAsB,CAAC,SAAS,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC;IAChE,OAAO,kBAAkB,CAAC,QAAQ,EAAE,eAAe,CAAC,CAAC;AACzD,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,sBAAsB,CAAC,SAAiB,EAAE,GAAW,EAAE,MAA8B;IACjG,MAAM,IAAI,GAAG,GAAG,GAAG,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAC9C,OAAO,UAAU,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;AAC/E,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,sBAAsB,CAAC,YAAoB;IACvD,OAAO,uBAAuB,CAAC,YAAY,CAAC,CAAC;AACjD,CAAC;AAYD;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAA8B;IAC7D,MAAM,OAAO,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC;IAClC,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;IAC5B,MAAM,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;IACxB,IAAI,CAAC,OAAO,IAAI,CAAC,IAAI,IAAI,CAAC,EAAE,EAAE,CAAC;QAC3B,MAAM,IAAI,KAAK,CACX,6FAA6F;YACzF,cAAc,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CACvD,CAAC;IACN,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;AACjC,CAAC;AAED,yGAAyG;AACzG,SAAS,kBAAkB,CAAC,MAA8B;IACtD,OAAO,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC;SACrB,IAAI,EAAE;SACN,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;SAC/B,IAAI,CAAC,EAAE,CAAC,CAAC;AAClB,CAAC;AAED,4GAA4G;AAC5G,SAAS,kBAAkB,CAAC,CAAS,EAAE,CAAS;IAC5C,MAAM,IAAI,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;IACpD,MAAM,IAAI,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;IACpD,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM,EAAE,CAAC;QAC9B,OAAO,KAAK,CAAC;IACjB,CAAC;IACD,OAAO,eAAe,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;AACvC,CAAC"}

package/dist/twilio-rest-client.d.ts

@@ -0,0 +1,93 @@
+/**
+ * @fileoverview Production REST half of the Twilio binding: a real {@link ITwilioRestLike}
+ * over the `twilio` npm SDK's Programmable Voice REST API (outbound dial + call update).
+ *
+ * The `twilio` package is an OPTIONAL PEER SDK (CLAUDE rule 8, category 2) — it is NEVER
+ * statically imported, so this provider package builds and unit-tests with no `twilio`
+ * install and no network. The SDK is lazily loaded (once, memoized) at first use via the
+ * injectable {@link TwilioRestModuleLoader}; tests inject a fake factory instead. None of
+ * the `twilio` SDK's own types leak past this file — everything crosses the seam through
+ * the minimal structural interfaces below, keeping {@link RealTwilioBindings} SDK-agnostic.
+ *
+ * The OTHER half — {@link ITwilioMediaPump} (the bidirectional Media-Streams websocket) —
+ * is owned by the MJAPI telephony ingress, not this package: the carrier websocket is a
+ * server concern (the `ws` dependency lives in MJServer), and one socket spans a call's
+ * whole media plane. This file is REST only.
+ *
+ * @module @memberjunction/ai-bridge-twilio
+ */
+import type { ITwilioRestLike, TwilioCreateCallParams, TwilioUpdateCallParams } from './real-twilio-bindings.js';
+/** The created-call resource the SDK's `calls.create(...)` resolves to (we read only `sid`). */
+export interface TwilioCallInstanceLike {
+    sid: string;
+}
+/** A single call's context (`client.calls(sid)`) — supports `update(...)` for hangup/transfer/DTMF. */
+export interface TwilioCallContextLike {
+    update(params: Record<string, unknown>): Promise<unknown>;
+}
+/**
+ * The `client.calls` surface: callable as `calls(sid)` to address one call AND carrying a
+ * `create(...)` method for outbound dial — exactly the dual shape the real `twilio` SDK exposes.
+ */
+export interface TwilioCallsResourceLike {
+    (callSid: string): TwilioCallContextLike;
+    create(params: Record<string, unknown>): Promise<TwilioCallInstanceLike>;
+}
+/** The subset of a constructed `twilio` REST client we drive. */
+export interface TwilioRestClientLike {
+    calls: TwilioCallsResourceLike;
+}
+/**
+ * The `twilio` module's default export: a factory constructing a REST client. Supports both
+ * auth forms — `twilio(accountSid, authToken)` and `twilio(apiKeySid, apiKeySecret, { accountSid })`.
+ */
+export type TwilioModuleFactory = (usernameOrAccountSid: string, password: string, opts?: {
+    accountSid?: string;
+}) => TwilioRestClientLike;
+/** Loads the `twilio` module's client factory. Overridable in tests; defaults to a lazy dynamic import. */
+export type TwilioRestModuleLoader = () => Promise<TwilioModuleFactory>;
+/** Credentials the REST client constructs the `twilio` SDK with. Resolved upstream via MJ config — never inlined. */
+export interface TwilioRestCredentials {
+    /** Twilio Account SID (`AC…`). Always required (used directly, or as the `accountSid` option under API-key auth). */
+    AccountSid: string;
+    /** Account auth token — used when no API key pair is supplied. Also the HMAC key for webhook signature verification. */
+    AuthToken?: string;
+    /** API Key SID (`SK…`) — preferred over the auth token for REST auth when present (with {@link ApiKeySecret}). */
+    ApiKeySid?: string;
+    /** API Key secret — paired with {@link ApiKeySid}. */
+    ApiKeySecret?: string;
+}
+/**
+ * Lazily loads the `twilio` module's client factory exactly once and memoizes it. A static import
+ * is impossible here (optional peer SDK, may be uninstalled in non-telephony deployments); the
+ * `optionalDependencies` entry keeps it in the dependency graph (CLAUDE rule 8, category 2).
+ */
+export declare const defaultTwilioRestModuleLoader: TwilioRestModuleLoader;
+/**
+ * A real {@link ITwilioRestLike} over the `twilio` SDK's Programmable Voice REST API.
+ *
+ * - `CreateCall` → `client.calls.create({ to, from, twiml, statusCallback })`, resolving the new Call SID.
+ * - `UpdateCall` → `client.calls(sid).update({ status, twiml })` for hangup / transfer / DTMF.
+ *
+ * The constructed client is built once on first use and reused for the life of the instance.
+ */
+export declare class RealTwilioRestClient implements ITwilioRestLike {
+    private readonly credentials;
+    private readonly loadModule;
+    /** Memoized client-build promise so concurrent callers share one construction. */
+    private clientPromise?;
+    /**
+     * @param credentials Resolved Twilio credentials (account SID + auth token or API key pair).
+     * @param loadModule The `twilio` module loader (defaults to the lazy dynamic import).
+     */
+    constructor(credentials: TwilioRestCredentials, loadModule?: TwilioRestModuleLoader);
+    /** @inheritdoc */
+    CreateCall(params: TwilioCreateCallParams): Promise<string>;
+    /** @inheritdoc */
+    UpdateCall(callSid: string, params: TwilioUpdateCallParams): Promise<void>;
+    /** Builds (once) and returns the constructed `twilio` REST client, choosing API-key auth when available. */
+    private ensureClient;
+    /** Constructs the `twilio` REST client with API-key auth when a key pair is present, else the auth token. */
+    private buildClient;
+}
+//# sourceMappingURL=twilio-rest-client.d.ts.map

package/dist/twilio-rest-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"twilio-rest-client.d.ts","sourceRoot":"","sources":["../src/twilio-rest-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AAOjH,gGAAgG;AAChG,MAAM,WAAW,sBAAsB;IACnC,GAAG,EAAE,MAAM,CAAC;CACf;AAED,uGAAuG;AACvG,MAAM,WAAW,qBAAqB;IAClC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC7D;AAED;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACpC,CAAC,OAAO,EAAE,MAAM,GAAG,qBAAqB,CAAC;IACzC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;CAC5E;AAED,iEAAiE;AACjE,MAAM,WAAW,oBAAoB;IACjC,KAAK,EAAE,uBAAuB,CAAC;CAClC;AAED;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAC9B,oBAAoB,EAAE,MAAM,EAC5B,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,KAC7B,oBAAoB,CAAC;AAE1B,2GAA2G;AAC3G,MAAM,MAAM,sBAAsB,GAAG,MAAM,OAAO,CAAC,mBAAmB,CAAC,CAAC;AAExE,qHAAqH;AACrH,MAAM,WAAW,qBAAqB;IAClC,qHAAqH;IACrH,UAAU,EAAE,MAAM,CAAC;IACnB,wHAAwH;IACxH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kHAAkH;IAClH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,YAAY,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,EAAE,sBAe3C,CAAC;AAaF;;;;;;;GAOG;AACH,qBAAa,oBAAqB,YAAW,eAAe;IACxD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAwB;IACpD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAyB;IACpD,kFAAkF;IAClF,OAAO,CAAC,aAAa,CAAC,CAAgC;IAEtD;;;OAGG;gBACS,WAAW,EAAE,qBAAqB,EAAE,UAAU,GAAE,sBAAsD;IAKlH,kBAAkB;IACL,UAAU,CAAC,MAAM,EAAE,sBAAsB,GAAG,OAAO,CAAC,MAAM,CAAC;IAcxE,kBAAkB;IACL,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC;IAQvF,4GAA4G;IAC5G,OAAO,CAAC,YAAY;IAOpB,6GAA6G;YAC/F,WAAW;CAW5B"}

package/dist/twilio-rest-client.js

@@ -0,0 +1,108 @@
+/**
+ * @fileoverview Production REST half of the Twilio binding: a real {@link ITwilioRestLike}
+ * over the `twilio` npm SDK's Programmable Voice REST API (outbound dial + call update).
+ *
+ * The `twilio` package is an OPTIONAL PEER SDK (CLAUDE rule 8, category 2) — it is NEVER
+ * statically imported, so this provider package builds and unit-tests with no `twilio`
+ * install and no network. The SDK is lazily loaded (once, memoized) at first use via the
+ * injectable {@link TwilioRestModuleLoader}; tests inject a fake factory instead. None of
+ * the `twilio` SDK's own types leak past this file — everything crosses the seam through
+ * the minimal structural interfaces below, keeping {@link RealTwilioBindings} SDK-agnostic.
+ *
+ * The OTHER half — {@link ITwilioMediaPump} (the bidirectional Media-Streams websocket) —
+ * is owned by the MJAPI telephony ingress, not this package: the carrier websocket is a
+ * server concern (the `ws` dependency lives in MJServer), and one socket spans a call's
+ * whole media plane. This file is REST only.
+ *
+ * @module @memberjunction/ai-bridge-twilio
+ */
+/**
+ * Lazily loads the `twilio` module's client factory exactly once and memoizes it. A static import
+ * is impossible here (optional peer SDK, may be uninstalled in non-telephony deployments); the
+ * `optionalDependencies` entry keeps it in the dependency graph (CLAUDE rule 8, category 2).
+ */
+export const defaultTwilioRestModuleLoader = async () => {
+    try {
+        const mod = await import('twilio');
+        const factory = unwrapTwilioFactory(mod);
+        if (typeof factory !== 'function') {
+            throw new Error('the twilio module did not export a client factory function');
+        }
+        return factory;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error("RealTwilioRestClient could not load the 'twilio' SDK. Install it in the deployment that " +
+            `runs the Twilio telephony bridge (it is an optional peer dependency). Underlying error: ${message}`);
+    }
+};
+/** Unwraps the twilio factory from CJS/ESM interop (`module` or `module.default`). */
+function unwrapTwilioFactory(mod) {
+    if (typeof mod === 'function') {
+        return mod;
+    }
+    if (mod && typeof mod === 'object' && 'default' in mod) {
+        return mod.default;
+    }
+    return mod;
+}
+/**
+ * A real {@link ITwilioRestLike} over the `twilio` SDK's Programmable Voice REST API.
+ *
+ * - `CreateCall` → `client.calls.create({ to, from, twiml, statusCallback })`, resolving the new Call SID.
+ * - `UpdateCall` → `client.calls(sid).update({ status, twiml })` for hangup / transfer / DTMF.
+ *
+ * The constructed client is built once on first use and reused for the life of the instance.
+ */
+export class RealTwilioRestClient {
+    /**
+     * @param credentials Resolved Twilio credentials (account SID + auth token or API key pair).
+     * @param loadModule The `twilio` module loader (defaults to the lazy dynamic import).
+     */
+    constructor(credentials, loadModule = defaultTwilioRestModuleLoader) {
+        this.credentials = credentials;
+        this.loadModule = loadModule;
+    }
+    /** @inheritdoc */
+    async CreateCall(params) {
+        const client = await this.ensureClient();
+        const created = await client.calls.create({
+            to: params.To,
+            from: params.From,
+            twiml: params.Twiml,
+            ...(params.StatusCallback ? { statusCallback: params.StatusCallback } : {}),
+        });
+        if (!created?.sid) {
+            throw new Error('Twilio calls.create returned no Call SID.');
+        }
+        return created.sid;
+    }
+    /** @inheritdoc */
+    async UpdateCall(callSid, params) {
+        const client = await this.ensureClient();
+        await client.calls(callSid).update({
+            ...(params.Status ? { status: params.Status } : {}),
+            ...(params.Twiml ? { twiml: params.Twiml } : {}),
+        });
+    }
+    /** Builds (once) and returns the constructed `twilio` REST client, choosing API-key auth when available. */
+    ensureClient() {
+        if (!this.clientPromise) {
+            this.clientPromise = this.buildClient();
+        }
+        return this.clientPromise;
+    }
+    /** Constructs the `twilio` REST client with API-key auth when a key pair is present, else the auth token. */
+    async buildClient() {
+        const factory = await this.loadModule();
+        const { AccountSid, AuthToken, ApiKeySid, ApiKeySecret } = this.credentials;
+        if (ApiKeySid && ApiKeySecret) {
+            return factory(ApiKeySid, ApiKeySecret, { accountSid: AccountSid });
+        }
+        if (!AuthToken) {
+            throw new Error('RealTwilioRestClient requires either an API key pair (ApiKeySid + ApiKeySecret) or an AuthToken.');
+        }
+        return factory(AccountSid, AuthToken);
+    }
+}
+//# sourceMappingURL=twilio-rest-client.js.map

package/dist/twilio-rest-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"twilio-rest-client.js","sourceRoot":"","sources":["../src/twilio-rest-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AA0DH;;;;GAIG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAA2B,KAAK,IAAkC,EAAE;IAC1G,IAAI,CAAC;QACD,MAAM,GAAG,GAAY,MAAM,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC5C,MAAM,OAAO,GAAG,mBAAmB,CAAC,GAAG,CAAC,CAAC;QACzC,IAAI,OAAO,OAAO,KAAK,UAAU,EAAE,CAAC;YAChC,MAAM,IAAI,KAAK,CAAC,4DAA4D,CAAC,CAAC;QAClF,CAAC;QACD,OAAO,OAA8B,CAAC;IAC1C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACX,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjE,MAAM,IAAI,KAAK,CACX,0FAA0F;YACtF,2FAA2F,OAAO,EAAE,CAC3G,CAAC;IACN,CAAC;AACL,CAAC,CAAC;AAEF,sFAAsF;AACtF,SAAS,mBAAmB,CAAC,GAAY;IACrC,IAAI,OAAO,GAAG,KAAK,UAAU,EAAE,CAAC;QAC5B,OAAO,GAAG,CAAC;IACf,CAAC;IACD,IAAI,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,SAAS,IAAI,GAAG,EAAE,CAAC;QACrD,OAAQ,GAA4B,CAAC,OAAO,CAAC;IACjD,CAAC;IACD,OAAO,GAAG,CAAC;AACf,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,oBAAoB;IAM7B;;;OAGG;IACH,YAAY,WAAkC,EAAE,aAAqC,6BAA6B;QAC9G,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QAC/B,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IACjC,CAAC;IAED,kBAAkB;IACX,KAAK,CAAC,UAAU,CAAC,MAA8B;QAClD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,YAAY,EAAE,CAAC;QACzC,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC;YACtC,EAAE,EAAE,MAAM,CAAC,EAAE;YACb,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,GAAG,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,MAAM,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC9E,CAAC,CAAC;QACH,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC;YAChB,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;QACjE,CAAC;QACD,OAAO,OAAO,CAAC,GAAG,CAAC;IACvB,CAAC;IAED,kBAAkB;IACX,KAAK,CAAC,UAAU,CAAC,OAAe,EAAE,MAA8B;QACnE,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,YAAY,EAAE,CAAC;QACzC,MAAM,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC;YAC/B,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACnD,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACnD,CAAC,CAAC;IACP,CAAC;IAED,4GAA4G;IACpG,YAAY;QAChB,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,CAAC;YACtB,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;QAC5C,CAAC;QACD,OAAO,IAAI,CAAC,aAAa,CAAC;IAC9B,CAAC;IAED,6GAA6G;IACrG,KAAK,CAAC,WAAW;QACrB,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,UAAU,EAAE,CAAC;QACxC,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,SAAS,EAAE,YAAY,EAAE,GAAG,IAAI,CAAC,WAAW,CAAC;QAC5E,IAAI,SAAS,IAAI,YAAY,EAAE,CAAC;YAC5B,OAAO,OAAO,CAAC,SAAS,EAAE,YAAY,EAAE,EAAE,UAAU,EAAE,UAAU,EAAE,CAAC,CAAC;QACxE,CAAC;QACD,IAAI,CAAC,SAAS,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CAAC,kGAAkG,CAAC,CAAC;QACxH,CAAC;QACD,OAAO,OAAO,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;IAC1C,CAAC;CACJ"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@memberjunction/ai-bridge-twilio",
   "type": "module",
-  "version": "5.44.0",
+  "version": "5.45.1",
   "description": "MemberJunction: Twilio Realtime Bridge driver (telephony). Connects the realtime agent engine to a phone call over Twilio Programmable Voice + Media Streams — outbound dial, inbound DID routing, single-party audio in/out, DTMF send/receive, and call transfer — via an injectable telephony call SDK seam. Audio only: no video, no screen, no Meeting Controls.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -17,10 +17,14 @@
   "author": "MemberJunction.com",
   "license": "ISC",
   "dependencies": {
-    "@memberjunction/core": "5.44.0",
-    "@memberjunction/global": "5.44.0",
-    "@memberjunction/core-entities": "5.44.0",
-    "@memberjunction/ai-bridge-base": "5.44.0"
+    "@memberjunction/core": "5.45.1",
+    "@memberjunction/global": "5.45.1",
+    "@memberjunction/core-entities": "5.45.1",
+    "@memberjunction/ai-bridge-base": "5.45.1"
+  },
+  "//optionalDependencies": "twilio is an OPTIONAL PEER SDK (CLAUDE rule 8, category 2): the package never statically imports it. Production wires RealTwilioBindings over the real twilio REST client + a Media-Streams websocket through the injected ITwilioRestLike/ITwilioMediaPump surfaces, so the package builds and unit-tests with no twilio install and no network. Loaded only when the Twilio provider is configured at deployment.",
+  "optionalDependencies": {
+    "twilio": "^5.3.0"
   },
   "devDependencies": {
     "@types/node": "24.10.11",