@memberjunction/server 5.44.0 → 5.45.1

package/dist/telephony/telephony-runtime.js

@@ -0,0 +1,18 @@
+/**
+ * @fileoverview Process-wide holder for the startup-constructed telephony service, so the
+ * outbound `PlaceTwilioCall` GraphQL resolver reaches the SAME {@link TwilioTelephonyService}
+ * (and thus the same {@link TwilioCallMediaRegistry} the Media-Streams WSS attaches sockets to)
+ * that the inbound webhook router uses. Set once during server boot; read by the resolver.
+ *
+ * @module @memberjunction/server/telephony
+ */
+let twilioService;
+/** Binds the startup-constructed Twilio telephony service (called from server boot). */
+export function SetTwilioTelephonyService(service) {
+    twilioService = service;
+}
+/** Returns the bound Twilio telephony service, or `undefined` when telephony is not configured. */
+export function GetTwilioTelephonyService() {
+    return twilioService;
+}
+//# sourceMappingURL=telephony-runtime.js.map

package/dist/telephony/telephony-runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telephony-runtime.js","sourceRoot":"","sources":["../../src/telephony/telephony-runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,IAAI,aAAiD,CAAC;AAEtD,wFAAwF;AACxF,MAAM,UAAU,yBAAyB,CAAC,OAA+B;IACrE,aAAa,GAAG,OAAO,CAAC;AAC5B,CAAC;AAED,mGAAmG;AACnG,MAAM,UAAU,yBAAyB;IACrC,OAAO,aAAa,CAAC;AACzB,CAAC"}

package/dist/telephony/twilioMediaRegistry.d.ts

@@ -0,0 +1,60 @@
+/**
+ * @fileoverview Per-call Media-Streams pump registry for the Twilio telephony ingress.
+ *
+ * This is the server half of the Twilio media plane: it implements the provider package's
+ * `ITwilioMediaPump` seam (which `RealTwilioBindings` drives) on top of the live Media-Streams
+ * websockets MJAPI accepts at `WSS /telephony/twilio/media`. It exists because of a lifecycle gap:
+ * when an INBOUND call's webhook fires, the bridge session starts and `RealTwilioBindings` registers
+ * its inbound-audio handler — but Twilio has not yet opened the media websocket (it does so only AFTER
+ * the webhook's `<Connect><Stream>` TwiML response). The registry bridges that gap by buffering
+ * handler registrations + outbound frames per Call SID and binding them to the socket once it connects
+ * (matched on the `start` frame's Call SID).
+ *
+ * Pure + unit-testable: the websocket is injected as the minimal {@link ITelephonyMediaSocket} surface,
+ * so the registry's buffering / dispatch / stream-SID capture logic is exercised with a fake socket and
+ * no `ws` install or network.
+ *
+ * @module @memberjunction/server/telephony
+ */
+import type { TwilioMediaFrame } from '@memberjunction/ai-bridge-twilio';
+import type { ITwilioMediaPump } from '@memberjunction/ai-bridge-twilio';
+/**
+ * The minimal websocket surface the registry drives — a structural subset of a `ws` socket, so the
+ * registry never imports `ws` and is testable with a fake. Outbound frames are sent as JSON strings.
+ */
+export interface ITelephonyMediaSocket {
+    /** Sends a serialized outbound Media-Streams frame on the call's socket. */
+    send(data: string): void;
+    /** Closes the socket (best-effort; called on call end). */
+    close(): void;
+}
+/**
+ * Coordinates Media-Streams sockets with the bridge bindings, keyed by Call SID. One instance per
+ * server, shared between the inbound-webhook service (which binds `RealTwilioBindings` over this as the
+ * `ITwilioMediaPump`) and the WSS server (which attaches sockets + dispatches inbound frames).
+ */
+export declare class TwilioCallMediaRegistry implements ITwilioMediaPump {
+    private readonly channels;
+    /** Ensures a channel exists for a call (called when a bridge session for the call starts). */
+    RegisterCall(callSid: string): void;
+    /** @inheritdoc — buffers when the socket has not yet connected; sends immediately once it has. */
+    Send(callSid: string, frame: TwilioMediaFrame): void;
+    /** @inheritdoc — stores the handler so frames delivered before AND after socket connect reach it. */
+    OnFrame(callSid: string, handler: (frame: TwilioMediaFrame) => void): void;
+    /** @inheritdoc — the captured stream SID, or `''` until the `start` frame arrives. */
+    GetStreamSid(callSid: string): string;
+    /**
+     * Binds a connected Media-Streams socket (and its captured stream SID) to a call, flushing any
+     * outbound frames produced while the socket was still connecting. Called by the WSS server on the
+     * `start` frame.
+     */
+    AttachSocket(callSid: string, socket: ITelephonyMediaSocket, streamSid: string): void;
+    /** Dispatches one inbound Media-Streams frame to all registered handlers for the call. */
+    DispatchInbound(callSid: string, frame: TwilioMediaFrame): void;
+    /** Tears down a call's channel and closes its socket (called on socket close / call end). */
+    EndCall(callSid: string): void;
+    /** Whether a channel is currently tracked for the call (test/observability helper). */
+    HasCall(callSid: string): boolean;
+    private ensureChannel;
+}
+//# sourceMappingURL=twilioMediaRegistry.d.ts.map

package/dist/telephony/twilioMediaRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"twilioMediaRegistry.d.ts","sourceRoot":"","sources":["../../src/telephony/twilioMediaRegistry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AACzE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AAEzE;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IAClC,4EAA4E;IAC5E,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,2DAA2D;IAC3D,KAAK,IAAI,IAAI,CAAC;CACjB;AAYD;;;;GAIG;AACH,qBAAa,uBAAwB,YAAW,gBAAgB;IAC5D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAuC;IAEhE,8FAA8F;IACvF,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAM1C,kGAAkG;IAC3F,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB,GAAG,IAAI;IAS3D,qGAAqG;IAC9F,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,GAAG,IAAI;IAIjF,sFAAsF;IAC/E,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAM5C;;;;OAIG;IACI,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,qBAAqB,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAU5F,0FAA0F;IACnF,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB,GAAG,IAAI;IAatE,6FAA6F;IACtF,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAarC,uFAAuF;IAChF,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAIxC,OAAO,CAAC,aAAa;CAQxB"}

package/dist/telephony/twilioMediaRegistry.js

@@ -0,0 +1,106 @@
+/**
+ * @fileoverview Per-call Media-Streams pump registry for the Twilio telephony ingress.
+ *
+ * This is the server half of the Twilio media plane: it implements the provider package's
+ * `ITwilioMediaPump` seam (which `RealTwilioBindings` drives) on top of the live Media-Streams
+ * websockets MJAPI accepts at `WSS /telephony/twilio/media`. It exists because of a lifecycle gap:
+ * when an INBOUND call's webhook fires, the bridge session starts and `RealTwilioBindings` registers
+ * its inbound-audio handler — but Twilio has not yet opened the media websocket (it does so only AFTER
+ * the webhook's `<Connect><Stream>` TwiML response). The registry bridges that gap by buffering
+ * handler registrations + outbound frames per Call SID and binding them to the socket once it connects
+ * (matched on the `start` frame's Call SID).
+ *
+ * Pure + unit-testable: the websocket is injected as the minimal {@link ITelephonyMediaSocket} surface,
+ * so the registry's buffering / dispatch / stream-SID capture logic is exercised with a fake socket and
+ * no `ws` install or network.
+ *
+ * @module @memberjunction/server/telephony
+ */
+/**
+ * Coordinates Media-Streams sockets with the bridge bindings, keyed by Call SID. One instance per
+ * server, shared between the inbound-webhook service (which binds `RealTwilioBindings` over this as the
+ * `ITwilioMediaPump`) and the WSS server (which attaches sockets + dispatches inbound frames).
+ */
+export class TwilioCallMediaRegistry {
+    constructor() {
+        this.channels = new Map();
+    }
+    /** Ensures a channel exists for a call (called when a bridge session for the call starts). */
+    RegisterCall(callSid) {
+        this.ensureChannel(callSid);
+    }
+    // ── ITwilioMediaPump ─────────────────────────────────────────────────────────
+    /** @inheritdoc — buffers when the socket has not yet connected; sends immediately once it has. */
+    Send(callSid, frame) {
+        const channel = this.ensureChannel(callSid);
+        if (channel.socket) {
+            channel.socket.send(JSON.stringify(frame));
+        }
+        else {
+            channel.outboundBuffer.push(frame);
+        }
+    }
+    /** @inheritdoc — stores the handler so frames delivered before AND after socket connect reach it. */
+    OnFrame(callSid, handler) {
+        this.ensureChannel(callSid).frameHandlers.push(handler);
+    }
+    /** @inheritdoc — the captured stream SID, or `''` until the `start` frame arrives. */
+    GetStreamSid(callSid) {
+        return this.channels.get(callSid)?.streamSid ?? '';
+    }
+    // ── WSS-server side ─────────────────────────────────────────────────────────
+    /**
+     * Binds a connected Media-Streams socket (and its captured stream SID) to a call, flushing any
+     * outbound frames produced while the socket was still connecting. Called by the WSS server on the
+     * `start` frame.
+     */
+    AttachSocket(callSid, socket, streamSid) {
+        const channel = this.ensureChannel(callSid);
+        channel.socket = socket;
+        channel.streamSid = streamSid;
+        const buffered = channel.outboundBuffer.splice(0, channel.outboundBuffer.length);
+        for (const frame of buffered) {
+            socket.send(JSON.stringify(frame));
+        }
+    }
+    /** Dispatches one inbound Media-Streams frame to all registered handlers for the call. */
+    DispatchInbound(callSid, frame) {
+        const channel = this.channels.get(callSid);
+        if (!channel) {
+            return;
+        }
+        if (frame.event === 'start' && frame.streamSid) {
+            channel.streamSid = frame.streamSid;
+        }
+        for (const handler of channel.frameHandlers) {
+            handler(frame);
+        }
+    }
+    /** Tears down a call's channel and closes its socket (called on socket close / call end). */
+    EndCall(callSid) {
+        const channel = this.channels.get(callSid);
+        if (!channel) {
+            return;
+        }
+        try {
+            channel.socket?.close();
+        }
+        catch {
+            /* best-effort */
+        }
+        this.channels.delete(callSid);
+    }
+    /** Whether a channel is currently tracked for the call (test/observability helper). */
+    HasCall(callSid) {
+        return this.channels.has(callSid);
+    }
+    ensureChannel(callSid) {
+        let channel = this.channels.get(callSid);
+        if (!channel) {
+            channel = { frameHandlers: [], outboundBuffer: [] };
+            this.channels.set(callSid, channel);
+        }
+        return channel;
+    }
+}
+//# sourceMappingURL=twilioMediaRegistry.js.map

package/dist/telephony/twilioMediaRegistry.js.map

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

package/dist/telephony/vonage-runtime.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @fileoverview Process-wide holder for the startup-constructed Vonage telephony service, so the
+ * outbound `PlaceVonageCall` GraphQL resolver reaches the SAME {@link VonageTelephonyService}
+ * (and thus the same {@link VonageCallMediaRegistry} the media WSS attaches sockets to) that the
+ * inbound webhook router uses. Set once during server boot; read by the resolver.
+ *
+ * @module @memberjunction/server/telephony
+ */
+import type { VonageTelephonyService } from './VonageTelephonyService.js';
+/** Binds the startup-constructed Vonage telephony service (called from server boot). */
+export declare function SetVonageTelephonyService(service: VonageTelephonyService): void;
+/** Returns the bound Vonage telephony service, or `undefined` when Vonage telephony is not configured. */
+export declare function GetVonageTelephonyService(): VonageTelephonyService | undefined;
+//# sourceMappingURL=vonage-runtime.d.ts.map

package/dist/telephony/vonage-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vonage-runtime.d.ts","sourceRoot":"","sources":["../../src/telephony/vonage-runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAI1E,wFAAwF;AACxF,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,sBAAsB,GAAG,IAAI,CAE/E;AAED,0GAA0G;AAC1G,wBAAgB,yBAAyB,IAAI,sBAAsB,GAAG,SAAS,CAE9E"}

package/dist/telephony/vonage-runtime.js

@@ -0,0 +1,18 @@
+/**
+ * @fileoverview Process-wide holder for the startup-constructed Vonage telephony service, so the
+ * outbound `PlaceVonageCall` GraphQL resolver reaches the SAME {@link VonageTelephonyService}
+ * (and thus the same {@link VonageCallMediaRegistry} the media WSS attaches sockets to) that the
+ * inbound webhook router uses. Set once during server boot; read by the resolver.
+ *
+ * @module @memberjunction/server/telephony
+ */
+let vonageService;
+/** Binds the startup-constructed Vonage telephony service (called from server boot). */
+export function SetVonageTelephonyService(service) {
+    vonageService = service;
+}
+/** Returns the bound Vonage telephony service, or `undefined` when Vonage telephony is not configured. */
+export function GetVonageTelephonyService() {
+    return vonageService;
+}
+//# sourceMappingURL=vonage-runtime.js.map

package/dist/telephony/vonage-runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vonage-runtime.js","sourceRoot":"","sources":["../../src/telephony/vonage-runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,IAAI,aAAiD,CAAC;AAEtD,wFAAwF;AACxF,MAAM,UAAU,yBAAyB,CAAC,OAA+B;IACrE,aAAa,GAAG,OAAO,CAAC;AAC5B,CAAC;AAED,0GAA0G;AAC1G,MAAM,UAAU,yBAAyB;IACrC,OAAO,aAAa,CAAC;AACzB,CAAC"}

package/dist/telephony/vonageMediaRegistry.d.ts

@@ -0,0 +1,78 @@
+/**
+ * @fileoverview Per-call WebSocket-media pump registry for the Vonage telephony ingress.
+ *
+ * This is the server half of the Vonage media plane: it implements the provider package's
+ * `IVonageMediaPump` seam (which `RealVonageBindings` drives) on top of the live bidirectional media
+ * websockets MJAPI accepts at `WSS /telephony/vonage/media`. It exists because of the same lifecycle
+ * gap the Twilio ingress has: when an INBOUND call's answer webhook fires, the bridge session starts and
+ * `RealVonageBindings` registers its inbound-audio handler — but Vonage has not yet opened the media
+ * websocket (it does so only AFTER the answer-webhook's `connect`-websocket NCCO response). The registry
+ * bridges that gap by buffering handler registrations + outbound frames per call UUID and binding them to
+ * the socket once it connects (matched on the call UUID Vonage forwards on the websocket handshake).
+ *
+ * Pure + unit-testable: the websocket is injected as the minimal {@link ITelephonyMediaSocket} surface,
+ * so the registry's buffering / dispatch logic is exercised with a fake socket and no `ws` install or
+ * network.
+ *
+ * @module @memberjunction/server/telephony
+ */
+import type { VonageControlEvent, IVonageMediaPump } from '@memberjunction/ai-bridge-vonage';
+/**
+ * The minimal websocket surface the registry drives — a structural subset of a `ws` socket, so the
+ * registry never imports `ws` and is testable with a fake. Vonage audio is sent as BINARY frames (raw
+ * L16 PCM); the registry never sends text frames outbound (Vonage's media socket only accepts audio).
+ */
+export interface ITelephonyMediaSocket {
+    /** Sends one outbound BINARY audio frame (raw L16 PCM) on the call's socket. */
+    sendBinary(data: Uint8Array): void;
+    /** Sends one outbound TEXT control frame (JSON command, e.g. `{"action":"clear"}`) on the call's socket. */
+    sendText(data: string): void;
+    /** Closes the socket (best-effort; called on call end). */
+    close(): void;
+}
+/**
+ * Coordinates Vonage media websockets with the bridge bindings, keyed by call UUID. One instance per
+ * server, shared between the inbound-webhook service (which binds `RealVonageBindings` over this as the
+ * `IVonageMediaPump`) and the WSS server (which attaches sockets + dispatches inbound audio/events).
+ *
+ * Models Vonage's wire split: outbound audio → binary frames; inbound binary frames → audio handlers;
+ * inbound JSON text frames → parsed {@link VonageControlEvent}s → event handlers. There is no base64
+ * envelope or μ-law transcode — that's the Twilio path, not Vonage's.
+ */
+export declare class VonageCallMediaRegistry implements IVonageMediaPump {
+    private readonly channels;
+    /** Ensures a channel exists for a call (called when a bridge session for the call starts). */
+    RegisterCall(callUuid: string): void;
+    /**
+     * @inheritdoc — re-slices the (already-8 kHz) delta into fixed 320-byte / 20 ms frames before sending,
+     * carrying any sub-frame remainder into the next delta so the stream stays continuous (no silence gaps).
+     * Each whole frame is sent immediately if the socket is live, else buffered for {@link AttachSocket}.
+     */
+    SendAudio(callUuid: string, pcm: ArrayBuffer): void;
+    /** @inheritdoc — stores the audio handler so frames delivered before AND after socket connect reach it. */
+    OnAudio(callUuid: string, handler: (pcm: ArrayBuffer) => void): void;
+    /** @inheritdoc — stores the control-event handler (DTMF / connected / close). */
+    OnEvent(callUuid: string, handler: (event: VonageControlEvent) => void): void;
+    /**
+     * @inheritdoc — barge-in flush: drop any outbound audio buffered locally (socket not yet connected) AND,
+     * if the socket is live, send Vonage's `{"action":"clear"}` text command to discard its playback queue.
+     * Safe to call for an unknown/uninitialized call (no-op).
+     */
+    Clear(callUuid: string): void;
+    /**
+     * Binds a connected media socket to a call, flushing any outbound audio produced while the socket
+     * was still connecting. Called by the WSS server once it resolves the call UUID for the socket (from
+     * the `call_uuid` query param the answer NCCO embedded on the media URL).
+     */
+    AttachSocket(callUuid: string, socket: ITelephonyMediaSocket): void;
+    /** Dispatches one inbound binary audio frame (raw L16 PCM) to all audio handlers for the call. */
+    DispatchInboundAudio(callUuid: string, pcm: ArrayBuffer): void;
+    /** Dispatches one inbound control event (parsed from a JSON text frame) to all event handlers for the call. */
+    DispatchInboundEvent(callUuid: string, event: VonageControlEvent): void;
+    /** Tears down a call's channel and closes its socket (called on socket close / call end). */
+    EndCall(callUuid: string): void;
+    /** Whether a channel is currently tracked for the call (test/observability helper). */
+    HasCall(callUuid: string): boolean;
+    private ensureChannel;
+}
+//# sourceMappingURL=vonageMediaRegistry.d.ts.map

package/dist/telephony/vonageMediaRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vonageMediaRegistry.d.ts","sourceRoot":"","sources":["../../src/telephony/vonageMediaRegistry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AAE7F;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IAClC,gFAAgF;IAChF,UAAU,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,CAAC;IACnC,4GAA4G;IAC5G,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,2DAA2D;IAC3D,KAAK,IAAI,IAAI,CAAC;CACjB;AAwBD;;;;;;;;GAQG;AACH,qBAAa,uBAAwB,YAAW,gBAAgB;IAC5D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAuC;IAEhE,8FAA8F;IACvF,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAM3C;;;;OAIG;IACI,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,GAAG,IAAI;IAoB1D,2GAA2G;IACpG,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,EAAE,WAAW,KAAK,IAAI,GAAG,IAAI;IAI3E,iFAAiF;IAC1E,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,IAAI,GAAG,IAAI;IAIpF;;;;OAIG;IACI,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAYpC;;;;OAIG;IACI,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,qBAAqB,GAAG,IAAI;IAS1E,kGAAkG;IAC3F,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,GAAG,IAAI;IAUrE,+GAA+G;IACxG,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,GAAG,IAAI;IAU9E,6FAA6F;IACtF,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAatC,uFAAuF;IAChF,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAIzC,OAAO,CAAC,aAAa;CAQxB"}

package/dist/telephony/vonageMediaRegistry.js

@@ -0,0 +1,158 @@
+/**
+ * @fileoverview Per-call WebSocket-media pump registry for the Vonage telephony ingress.
+ *
+ * This is the server half of the Vonage media plane: it implements the provider package's
+ * `IVonageMediaPump` seam (which `RealVonageBindings` drives) on top of the live bidirectional media
+ * websockets MJAPI accepts at `WSS /telephony/vonage/media`. It exists because of the same lifecycle
+ * gap the Twilio ingress has: when an INBOUND call's answer webhook fires, the bridge session starts and
+ * `RealVonageBindings` registers its inbound-audio handler — but Vonage has not yet opened the media
+ * websocket (it does so only AFTER the answer-webhook's `connect`-websocket NCCO response). The registry
+ * bridges that gap by buffering handler registrations + outbound frames per call UUID and binding them to
+ * the socket once it connects (matched on the call UUID Vonage forwards on the websocket handshake).
+ *
+ * Pure + unit-testable: the websocket is injected as the minimal {@link ITelephonyMediaSocket} surface,
+ * so the registry's buffering / dispatch logic is exercised with a fake socket and no `ws` install or
+ * network.
+ *
+ * @module @memberjunction/server/telephony
+ */
+/**
+ * The exact byte size of one outbound audio frame Vonage expects on the `audio/l16;rate=8000` leg: a
+ * 20 ms slice = 8000 Hz × 0.020 s = 160 samples × 2 bytes = **320 bytes**. The realtime model emits audio
+ * in arbitrary-size deltas; the bridge resamples each whole delta to 8 kHz, so the registry MUST re-slice
+ * into these fixed frames before sending. Handing Vonage one oversized blob per delta garbles playback and
+ * (worse) defeats barge-in: `{"action":"clear"}` can drop QUEUED frames but not a giant in-flight one.
+ */
+const OUTBOUND_FRAME_BYTES = 320;
+/**
+ * Coordinates Vonage media websockets with the bridge bindings, keyed by call UUID. One instance per
+ * server, shared between the inbound-webhook service (which binds `RealVonageBindings` over this as the
+ * `IVonageMediaPump`) and the WSS server (which attaches sockets + dispatches inbound audio/events).
+ *
+ * Models Vonage's wire split: outbound audio → binary frames; inbound binary frames → audio handlers;
+ * inbound JSON text frames → parsed {@link VonageControlEvent}s → event handlers. There is no base64
+ * envelope or μ-law transcode — that's the Twilio path, not Vonage's.
+ */
+export class VonageCallMediaRegistry {
+    constructor() {
+        this.channels = new Map();
+    }
+    /** Ensures a channel exists for a call (called when a bridge session for the call starts). */
+    RegisterCall(callUuid) {
+        this.ensureChannel(callUuid);
+    }
+    // ── IVonageMediaPump ─────────────────────────────────────────────────────────
+    /**
+     * @inheritdoc — re-slices the (already-8 kHz) delta into fixed 320-byte / 20 ms frames before sending,
+     * carrying any sub-frame remainder into the next delta so the stream stays continuous (no silence gaps).
+     * Each whole frame is sent immediately if the socket is live, else buffered for {@link AttachSocket}.
+     */
+    SendAudio(callUuid, pcm) {
+        const channel = this.ensureChannel(callUuid);
+        const incoming = new Uint8Array(pcm);
+        const data = channel.partial.length > 0 ? concatBytes(channel.partial, incoming) : incoming;
+        let offset = 0;
+        while (data.length - offset >= OUTBOUND_FRAME_BYTES) {
+            // `.slice` returns a fresh copy, so a buffered frame never retains the larger backing buffer.
+            const frame = data.slice(offset, offset + OUTBOUND_FRAME_BYTES);
+            offset += OUTBOUND_FRAME_BYTES;
+            if (channel.socket) {
+                channel.socket.sendBinary(frame);
+            }
+            else {
+                channel.outboundBuffer.push(frame);
+            }
+        }
+        channel.partial = offset < data.length ? data.slice(offset) : new Uint8Array(0);
+    }
+    /** @inheritdoc — stores the audio handler so frames delivered before AND after socket connect reach it. */
+    OnAudio(callUuid, handler) {
+        this.ensureChannel(callUuid).audioHandlers.push(handler);
+    }
+    /** @inheritdoc — stores the control-event handler (DTMF / connected / close). */
+    OnEvent(callUuid, handler) {
+        this.ensureChannel(callUuid).eventHandlers.push(handler);
+    }
+    /**
+     * @inheritdoc — barge-in flush: drop any outbound audio buffered locally (socket not yet connected) AND,
+     * if the socket is live, send Vonage's `{"action":"clear"}` text command to discard its playback queue.
+     * Safe to call for an unknown/uninitialized call (no-op).
+     */
+    Clear(callUuid) {
+        const channel = this.channels.get(callUuid);
+        if (!channel) {
+            return;
+        }
+        channel.outboundBuffer.length = 0;
+        channel.partial = new Uint8Array(0); // drop the half-built frame too, or it would prepend to the next turn
+        channel.socket?.sendText(JSON.stringify({ action: 'clear' }));
+    }
+    // ── WSS-server side ─────────────────────────────────────────────────────────
+    /**
+     * Binds a connected media socket to a call, flushing any outbound audio produced while the socket
+     * was still connecting. Called by the WSS server once it resolves the call UUID for the socket (from
+     * the `call_uuid` query param the answer NCCO embedded on the media URL).
+     */
+    AttachSocket(callUuid, socket) {
+        const channel = this.ensureChannel(callUuid);
+        channel.socket = socket;
+        const buffered = channel.outboundBuffer.splice(0, channel.outboundBuffer.length);
+        for (const frame of buffered) {
+            socket.sendBinary(frame);
+        }
+    }
+    /** Dispatches one inbound binary audio frame (raw L16 PCM) to all audio handlers for the call. */
+    DispatchInboundAudio(callUuid, pcm) {
+        const channel = this.channels.get(callUuid);
+        if (!channel) {
+            return;
+        }
+        for (const handler of channel.audioHandlers) {
+            handler(pcm);
+        }
+    }
+    /** Dispatches one inbound control event (parsed from a JSON text frame) to all event handlers for the call. */
+    DispatchInboundEvent(callUuid, event) {
+        const channel = this.channels.get(callUuid);
+        if (!channel) {
+            return;
+        }
+        for (const handler of channel.eventHandlers) {
+            handler(event);
+        }
+    }
+    /** Tears down a call's channel and closes its socket (called on socket close / call end). */
+    EndCall(callUuid) {
+        const channel = this.channels.get(callUuid);
+        if (!channel) {
+            return;
+        }
+        try {
+            channel.socket?.close();
+        }
+        catch {
+            /* best-effort */
+        }
+        this.channels.delete(callUuid);
+    }
+    /** Whether a channel is currently tracked for the call (test/observability helper). */
+    HasCall(callUuid) {
+        return this.channels.has(callUuid);
+    }
+    ensureChannel(callUuid) {
+        let channel = this.channels.get(callUuid);
+        if (!channel) {
+            channel = { audioHandlers: [], eventHandlers: [], outboundBuffer: [], partial: new Uint8Array(0) };
+            this.channels.set(callUuid, channel);
+        }
+        return channel;
+    }
+}
+/** Concatenates two byte arrays into a fresh `Uint8Array` (the carry-over remainder + the next delta). */
+function concatBytes(a, b) {
+    const out = new Uint8Array(a.length + b.length);
+    out.set(a, 0);
+    out.set(b, a.length);
+    return out;
+}
+//# sourceMappingURL=vonageMediaRegistry.js.map

package/dist/telephony/vonageMediaRegistry.js.map

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