@memberjunction/server 5.44.0 → 5.45.0

package/src/telephony/TwilioTelephonyService.ts

@@ -0,0 +1,261 @@
+/**
+ * @fileoverview Orchestrates Twilio telephony bridge sessions (inbound + outbound) for MJAPI.
+ *
+ * This is the composition layer between the carrier ingress (the public webhook + the Media-Streams
+ * WSS) and the ONE unified realtime-agent pathway. It does NOT re-implement any bridge logic: it
+ * resolves the Twilio provider + the agent identity, opens a server-side realtime session via the
+ * agent layer's `CreateBridgeRealtimeSession` factory, binds `RealTwilioBindings` (real REST client +
+ * the per-call media registry) onto the driver, and hands everything to
+ * `AIBridgeEngine.StartBridgeSession` — exactly the seam the LiveKit room coordinator uses.
+ *
+ * Collaborators are injected (engine, session factory, session manager) so the resolution/branching
+ * logic is unit-testable with fakes; the actual call placement + media flow are live-only (real Twilio
+ * credentials + a publicly reachable stream URL — see telephony-vendor-bindings.md T1).
+ *
+ * @module @memberjunction/server/telephony
+ */
+
+import { RunView, UserInfo, IMetadataProvider, LogError } from '@memberjunction/core';
+import type { MJAIBridgeAgentIdentityEntity, MJAIBridgeProviderEntity } from '@memberjunction/core-entities';
+import { AIBridgeEngine } from '@memberjunction/ai-bridge-server';
+import { CreateBridgeRealtimeSession } from '@memberjunction/ai-agents';
+import {
+    BaseTelephonyBridge,
+    type BridgeNativeSdkBinding,
+    DIRECTION_CONFIG_KEY,
+    FROM_NUMBER_CONFIG_KEY,
+    INBOUND_CALL_ID_CONFIG_KEY,
+} from '@memberjunction/ai-bridge-base';
+import { TwilioCallSdk, RealTwilioBindings, RealTwilioRestClient } from '@memberjunction/ai-bridge-twilio';
+import type { TwilioTelephonyConfig } from '../config.js';
+import { SessionManager } from '../agentSessions/SessionManager.js';
+import { TwilioCallMediaRegistry } from './twilioMediaRegistry.js';
+
+const TWILIO_PROVIDER_DRIVER = 'TwilioBridge';
+const AGENT_IDENTITY_ENTITY = 'MJ: AI Bridge Agent Identities';
+const PHONE_IDENTITY_TYPE = 'PhoneNumber';
+
+/** A resolved inbound call's identifying fields (parsed from the Twilio webhook). */
+export interface InboundCallInput {
+    /** The Twilio Call SID. */
+    callSid: string;
+    /** The caller's number (Twilio `From`). */
+    from: string;
+    /** The dialed DID (Twilio `To`) — resolved to an agent identity. */
+    to: string;
+}
+
+/** Result of starting an inbound bridge session. */
+export interface InboundCallResult {
+    /** Whether a pinned agent was resolved + a bridge session started. */
+    accepted: boolean;
+    /** Why it was rejected (no agent identity for the DID, provider missing, etc.). */
+    reason?: string;
+}
+
+/** Injectable collaborators (production defaults wired in the constructor; fakes in tests). */
+export interface TwilioTelephonyServiceDeps {
+    engine?: Pick<AIBridgeEngine, 'ProviderByName' | 'ProviderByDriverClass' | 'StartBridgeSession' | 'Config'>;
+    sessionFactory?: typeof CreateBridgeRealtimeSession;
+    sessionManager?: Pick<SessionManager, 'CreateSession'>;
+}
+
+/**
+ * Starts Twilio bridge sessions. One instance per server, constructed alongside the telephony router and
+ * sharing the {@link TwilioCallMediaRegistry} with the Media-Streams WSS server.
+ */
+export class TwilioTelephonyService {
+    private readonly rest: RealTwilioRestClient;
+    private readonly engine: Pick<AIBridgeEngine, 'ProviderByName' | 'ProviderByDriverClass' | 'StartBridgeSession' | 'Config'>;
+    private readonly sessionFactory: typeof CreateBridgeRealtimeSession;
+    private readonly sessionManager: Pick<SessionManager, 'CreateSession'>;
+
+    constructor(
+        private readonly config: TwilioTelephonyConfig,
+        private readonly registry: TwilioCallMediaRegistry,
+        deps: TwilioTelephonyServiceDeps = {},
+    ) {
+        this.rest = new RealTwilioRestClient({
+            AccountSid: config.accountSid,
+            AuthToken: config.authToken,
+            ApiKeySid: config.apiKeySid,
+            ApiKeySecret: config.apiKeySecret,
+        });
+        this.engine = deps.engine ?? AIBridgeEngine.Instance;
+        this.sessionFactory = deps.sessionFactory ?? CreateBridgeRealtimeSession;
+        this.sessionManager = deps.sessionManager ?? new SessionManager();
+    }
+
+    /**
+     * Resolves the dialed DID to a pinned agent and starts an INBOUND bridge session. The bound
+     * `RealTwilioBindings` will accept the Media-Streams socket (opened by the webhook's TwiML) for the
+     * Call SID. Returns `{ accepted:false }` (never throws) when no agent identity matches the DID, so
+     * the webhook can answer with a polite "no agent" message instead of a 500.
+     */
+    public async HandleInboundCall(input: InboundCallInput, contextUser: UserInfo, provider: IMetadataProvider): Promise<InboundCallResult> {
+        try {
+            const identity = await this.resolveAgentIdentityByPhone(input.to, contextUser);
+            if (!identity) {
+                return { accepted: false, reason: `No active agent identity for dialed number '${input.to}'.` };
+            }
+            this.registry.RegisterCall(input.callSid);
+            await this.startBridge({
+                agentID: identity.AgentID,
+                direction: 'Inbound',
+                address: input.from,
+                inboundCallId: input.callSid,
+                contextUser,
+                provider,
+            });
+            return { accepted: true };
+        } catch (e) {
+            LogError(`[Telephony][Twilio] inbound call ${input.callSid} failed: ${e instanceof Error ? e.message : String(e)}`);
+            return { accepted: false, reason: 'Internal error starting the agent.' };
+        }
+    }
+
+    /**
+     * Places an OUTBOUND call from a given agent identity to a destination number. The bound
+     * `RealTwilioBindings.createCall` issues the Twilio REST `POST /Calls` with the `<Connect><Stream>`
+     * TwiML; the returned Call SID is the bridge's external connection id.
+     *
+     * @returns The placed Call SID.
+     */
+    public async PlaceOutboundCall(agentIdentityId: string, toNumber: string, contextUser: UserInfo, provider: IMetadataProvider): Promise<string> {
+        const identity = await this.loadAgentIdentity(agentIdentityId, contextUser, provider);
+        if (!identity) {
+            throw new Error(`Agent identity '${agentIdentityId}' not found or inactive.`);
+        }
+        const session = await this.startBridge({
+            agentID: identity.AgentID,
+            direction: 'Outbound',
+            address: toNumber,
+            fromNumber: identity.IdentityValue,
+            contextUser,
+            provider,
+        });
+        return session.RoomKey ?? '';
+    }
+
+    // ── internals ────────────────────────────────────────────────────────────────
+
+    /** Shared inbound/outbound bridge-start: resolve provider, open the realtime session, bind the SDK, start. */
+    private async startBridge(args: {
+        agentID: string;
+        direction: 'Inbound' | 'Outbound';
+        address: string;
+        inboundCallId?: string;
+        fromNumber?: string;
+        contextUser: UserInfo;
+        provider: IMetadataProvider;
+    }): Promise<{ RoomKey?: string }> {
+        await this.engine.Config(false, args.contextUser, args.provider);
+        const twilioProvider = this.resolveProvider();
+
+        const agentSession = await this.sessionManager.CreateSession({ agentID: args.agentID, userID: args.contextUser.ID }, args.contextUser, args.provider);
+        const realtimeSession = await this.sessionFactory({
+            AgentID: args.agentID,
+            TargetAgentID: args.agentID,
+            ContextUser: args.contextUser,
+            MetadataProvider: args.provider,
+            AgentSessionID: agentSession.ID,
+            RoomName: args.address,
+        });
+
+        const active = await this.engine.StartBridgeSession({
+            AgentSessionID: agentSession.ID,
+            AgentID: args.agentID,
+            TargetAgentID: args.agentID,
+            Provider: twilioProvider,
+            RealtimeSession: realtimeSession,
+            Address: args.address,
+            Direction: args.direction,
+            Configuration: this.buildSessionConfiguration(args.direction, args.fromNumber, args.inboundCallId),
+            BindSdk: this.buildBindSdk(),
+            ContextUser: args.contextUser,
+            MetadataProvider: args.provider,
+        });
+        return { RoomKey: active.RoomKey };
+    }
+
+    /** Resolves the seeded Twilio provider row (by driver class, falling back to display name). */
+    private resolveProvider(): MJAIBridgeProviderEntity {
+        const provider = this.engine.ProviderByDriverClass(TWILIO_PROVIDER_DRIVER) ?? this.engine.ProviderByName('Twilio');
+        if (!provider) {
+            throw new Error(`No active 'MJ: AI Bridge Providers' row for the Twilio bridge (DriverClass '${TWILIO_PROVIDER_DRIVER}').`);
+        }
+        return provider;
+    }
+
+    /**
+     * Builds the per-session SDK binding that wires the REAL Twilio bindings (REST client + the per-call
+     * media registry) onto the telephony driver — overriding the package's default unbound SDK. This is
+     * where the offline-complete seams meet the live REST + websocket plumbing.
+     */
+    public buildBindSdk(): BridgeNativeSdkBinding {
+        return (driver) => {
+            const telephony = driver as BaseTelephonyBridge;
+            telephony.SetSdkFactory(() =>
+                new TwilioCallSdk(
+                    new RealTwilioBindings({
+                        Rest: this.rest,
+                        MediaPump: this.registry,
+                        StreamUrl: this.config.streamPublicUrl,
+                        StatusCallbackUrl: this.config.statusCallbackUrl,
+                    }),
+                ),
+            );
+        };
+    }
+
+    /**
+     * Assembles the per-session bridge Configuration the telephony driver reads. The engine does NOT
+     * forward the top-level `Direction` into the driver's Configuration (it only stamps the DB row), and
+     * the bridge defaults to `'Outbound'` when the key is absent — so Direction MUST be set here, or an
+     * inbound call wrongly takes the outbound-dial path and fails with "No 'From' number is specified".
+     */
+    private buildSessionConfiguration(direction: 'Inbound' | 'Outbound', fromNumber?: string, inboundCallId?: string): Record<string, unknown> {
+        const config: Record<string, unknown> = { [DIRECTION_CONFIG_KEY]: direction };
+        if (fromNumber) {
+            config[FROM_NUMBER_CONFIG_KEY] = fromNumber;
+        }
+        if (inboundCallId) {
+            config[INBOUND_CALL_ID_CONFIG_KEY] = inboundCallId;
+        }
+        return config;
+    }
+
+    /** Finds the active agent identity whose phone number matches the dialed DID. */
+    private async resolveAgentIdentityByPhone(dialedNumber: string, contextUser: UserInfo): Promise<MJAIBridgeAgentIdentityEntity | null> {
+        const normalized = (dialedNumber ?? '').trim();
+        if (!normalized) {
+            return null;
+        }
+        const rv = new RunView();
+        const result = await rv.RunView<MJAIBridgeAgentIdentityEntity>(
+            {
+                EntityName: AGENT_IDENTITY_ENTITY,
+                ExtraFilter: `IdentityType='${PHONE_IDENTITY_TYPE}' AND IdentityValue='${normalized.replace(/'/g, "''")}' AND IsActive=1`,
+                MaxRows: 1,
+                ResultType: 'entity_object',
+            },
+            contextUser,
+        );
+        if (!result.Success) {
+            LogError(`[Telephony][Twilio] agent-identity lookup failed: ${result.ErrorMessage}`);
+            return null;
+        }
+        return result.Results?.[0] ?? null;
+    }
+
+    /** Loads a specific agent identity by id (used by outbound PlaceCall), requiring it be active. */
+    private async loadAgentIdentity(agentIdentityId: string, contextUser: UserInfo, provider: IMetadataProvider): Promise<MJAIBridgeAgentIdentityEntity | null> {
+        // Use the request-scoped provider (multi-provider safe), not the global Metadata.
+        const entity = await provider.GetEntityObject<MJAIBridgeAgentIdentityEntity>(AGENT_IDENTITY_ENTITY, contextUser);
+        const loaded = await entity.Load(agentIdentityId);
+        if (!loaded || !entity.IsActive) {
+            return null;
+        }
+        return entity;
+    }
+}

package/src/telephony/VonageTelephonyRouter.ts

@@ -0,0 +1,239 @@
+/**
+ * @fileoverview Express + WSS wiring for the Vonage telephony ingress.
+ *
+ * Three public surfaces (carriers cannot present an MJ JWT — Vonage's signed-request HMAC or webhook JWT
+ * is the gate):
+ *   - `POST /telephony/vonage/answer` — inbound answer webhook. Verifies the signature/JWT, resolves the
+ *     dialed DID to a pinned agent, starts an inbound bridge session, and returns the `connect`-websocket
+ *     NCCO that opens the bidirectional media leg.
+ *   - `POST /telephony/vonage/event`  — call-lifecycle event webhook (verified, acknowledged 200).
+ *   - `WSS  /telephony/vonage/media`  — the bidirectional `audio/l16;rate=8000` media socket. Frames are
+ *     routed to the active call's `RealVonageBindings` via the shared {@link VonageCallMediaRegistry}.
+ *
+ * Vonage media frames do not carry the call UUID, so the answer NCCO embeds it on the media URL as a
+ * `?call_uuid=…` query param; the WSS reads it from the upgrade request URL to key the socket.
+ *
+ * Mirrors the Twilio / magic-link / widget public-router pattern: mount the router BEFORE the unified auth
+ * middleware and attach the WSS to the shared HTTP server at startup. The signature/JWT-verification gate +
+ * inbound resolution use the offline-complete, unit-tested helpers from the Vonage provider package; this
+ * module is thin HTTP/WS plumbing over them and the {@link VonageTelephonyService}.
+ *
+ * @module @memberjunction/server/telephony
+ */
+
+import { Router, urlencoded, json, type Request, type Response } from 'express';
+import { WebSocketServer, type WebSocket } from 'ws';
+import type { IncomingMessage } from 'node:http';
+import { RegisterMediaUpgradeRoute } from './media-upgrade-router.js';
+import { LogError, LogStatus, UserInfo, IMetadataProvider, Metadata } from '@memberjunction/core';
+import { UserCache } from '@memberjunction/sqlserver-dataprovider';
+import {
+    verifyVonageSignature,
+    verifyVonageJwt,
+    resolveInboundCall,
+    buildInboundAnswerNcco,
+    parseVonageControlEvent,
+} from '@memberjunction/ai-bridge-vonage';
+import type { VonageTelephonyConfig } from '../config.js';
+import { VonageCallMediaRegistry } from './vonageMediaRegistry.js';
+import { VonageTelephonyService } from './VonageTelephonyService.js';
+
+/** The mount path for the Vonage telephony public router. */
+export const VONAGE_TELEPHONY_MOUNT_PATH = '/telephony/vonage';
+
+/** The media websocket path Vonage's `connect`-websocket NCCO connects to. */
+export const VONAGE_MEDIA_WSS_PATH = '/telephony/vonage/media';
+
+/** A polite NCCO returned when no agent is available for the dialed number. */
+const NO_AGENT_NCCO = [{ action: 'talk', text: 'Sorry, no agent is available to take this call.' }];
+
+/**
+ * Builds the Vonage telephony handler: the public answer/event router + a function to attach the media
+ * WSS to the shared HTTP server. Returns the registry + service for observability/tests.
+ */
+export function createVonageTelephonyHandler(
+    publicUrl: string,
+    config: VonageTelephonyConfig,
+): {
+    publicRouter: Router;
+    attachMediaStreamServer: () => void;
+    registry: VonageCallMediaRegistry;
+    service: VonageTelephonyService;
+} {
+    const registry = new VonageCallMediaRegistry();
+    const service = new VonageTelephonyService(config, registry);
+    const publicRouter = Router();
+
+    // Vonage posts JSON webhook bodies; also accept urlencoded for signed-request `sig` schemes.
+    publicRouter.post('/answer', json(), urlencoded({ extended: false }), async (req: Request, res: Response) => {
+        await handleInboundAnswer(service, config, req, res);
+    });
+    publicRouter.post('/event', json(), urlencoded({ extended: false }), (req: Request, res: Response) => {
+        handleCallEvent(config, req, res);
+    });
+
+    return {
+        publicRouter,
+        attachMediaStreamServer: () => attachMediaStreamServer(registry),
+        registry,
+        service,
+    };
+}
+
+/** Handles the inbound answer webhook: verify → resolve → start bridge → return the connect-websocket NCCO. */
+async function handleInboundAnswer(
+    service: VonageTelephonyService,
+    config: VonageTelephonyConfig,
+    req: Request,
+    res: Response,
+): Promise<void> {
+    const params = coerceParams(req.body);
+    if (!verifyVonageRequest(config, req, params)) {
+        res.status(403).type('application/json').json({ error: 'Invalid Vonage signature.' });
+        return;
+    }
+
+    let resolved: { callId: string; from: string; to: string };
+    try {
+        resolved = resolveInboundCall(params);
+    } catch (e) {
+        LogError(`[Telephony][Vonage] answer webhook unparseable: ${e instanceof Error ? e.message : String(e)}`);
+        res.status(200).type('application/json').json(NO_AGENT_NCCO);
+        return;
+    }
+
+    const context = resolveServerContext();
+    if (!context) {
+        LogError('[Telephony][Vonage] no server context user available; cannot start inbound call.');
+        res.status(200).type('application/json').json(NO_AGENT_NCCO);
+        return;
+    }
+
+    const result = await service.HandleInboundCall(resolved, context.user, context.provider);
+    if (!result.accepted) {
+        LogStatus(`[Telephony][Vonage] inbound ${resolved.callId} not accepted: ${result.reason ?? 'unknown'}`);
+        res.status(200).type('application/json').json(NO_AGENT_NCCO);
+        return;
+    }
+    const mediaUrl = appendCallUuid(config.mediaPublicUrl, resolved.callId);
+    res.status(200).type('application/json').json(buildInboundAnswerNcco(mediaUrl));
+}
+
+/** Handles a call-lifecycle event webhook: verify then acknowledge (the bridge tracks state via the media socket). */
+function handleCallEvent(config: VonageTelephonyConfig, req: Request, res: Response): void {
+    const params = coerceParams(req.body);
+    if (!verifyVonageRequest(config, req, params)) {
+        res.status(403).type('application/json').json({ error: 'Invalid Vonage signature.' });
+        return;
+    }
+    LogStatus(`[Telephony][Vonage] event: ${params['status'] ?? params['event'] ?? 'unknown'} for ${params['uuid'] ?? params['conversation_uuid'] ?? '?'}`);
+    res.status(200).end();
+}
+
+/** Verifies a public Vonage webhook via the webhook JWT (preferred) or the signed-request `sig` HMAC. */
+function verifyVonageRequest(config: VonageTelephonyConfig, req: Request, params: Record<string, string>): boolean {
+    const secret = config.signatureSecret;
+    if (!secret) {
+        return false;
+    }
+    const jwtClaims = verifyVonageJwt(secret, req.get('Authorization'), Math.floor(Date.now() / 1000));
+    if (jwtClaims) {
+        return true;
+    }
+    return verifyVonageSignature(secret, params['sig'], params);
+}
+
+/**
+ * Attaches the media WSS to the shared HTTP server on {@link VONAGE_MEDIA_WSS_PATH}. Each socket is mapped
+ * to its call UUID from the `?call_uuid=…` query param the answer NCCO embedded on the media URL, then
+ * inbound frames are dispatched to the call's bindings via the registry; the socket is also the registry's
+ * outbound pump for that call.
+ */
+function attachMediaStreamServer(registry: VonageCallMediaRegistry): void {
+    // noServer: the shared path-routing upgrade dispatcher owns the HTTP 'upgrade' event (a second
+    // {server}-bound WS server would fight GraphQL's socket and 400 the handshake). The dispatcher
+    // passes the original request through, so the call-UUID query on the media URL is preserved.
+    const wss = new WebSocketServer({ noServer: true });
+    wss.on('connection', (socket: WebSocket, request: IncomingMessage) => wireMediaSocket(socket, request, registry));
+    RegisterMediaUpgradeRoute(VONAGE_MEDIA_WSS_PATH, wss);
+    LogStatus(`[Telephony][Vonage] media WSS route registered at ${VONAGE_MEDIA_WSS_PATH}`);
+}
+
+/** Wires one media socket: key on the `call_uuid` query param, attach, dispatch inbound frames, tear down on close. */
+function wireMediaSocket(socket: WebSocket, request: IncomingMessage, registry: VonageCallMediaRegistry): void {
+    const callUuid = readCallUuid(request);
+    if (!callUuid) {
+        LogError('[Telephony][Vonage] media socket connected with no call_uuid; closing.');
+        socket.close();
+        return;
+    }
+    const adapter = {
+        sendBinary: (data: Uint8Array) => socket.send(data),
+        sendText: (data: string) => socket.send(data),
+        close: () => socket.close(),
+    };
+    registry.AttachSocket(callUuid, adapter);
+
+    // Vonage splits the media leg by frame type: BINARY frames carry raw L16 PCM audio; TEXT frames carry
+    // JSON control events (websocket:connected / websocket:dtmf / close). `ws` reports which via isBinary.
+    socket.on('message', (raw: Buffer, isBinary: boolean) => {
+        if (isBinary) {
+            registry.DispatchInboundAudio(callUuid, toArrayBuffer(raw));
+            return;
+        }
+        const event = parseVonageControlEvent(raw.toString('utf8'));
+        if (event) {
+            registry.DispatchInboundEvent(callUuid, event);
+        }
+    });
+    socket.on('close', () => registry.EndCall(callUuid));
+}
+
+/** Copies a Node `Buffer` into a standalone `ArrayBuffer` (respecting byteOffset/length, never aliasing the pool). */
+function toArrayBuffer(buf: Buffer): ArrayBuffer {
+    const out = new ArrayBuffer(buf.byteLength);
+    new Uint8Array(out).set(buf);
+    return out;
+}
+
+/** Reads the `call_uuid` query param off the websocket upgrade request URL, or null when absent. */
+function readCallUuid(request: IncomingMessage): string | null {
+    try {
+        const url = new URL(request.url ?? '', 'http://localhost');
+        const value = url.searchParams.get('call_uuid');
+        return value && value.length > 0 ? value : null;
+    } catch {
+        return null;
+    }
+}
+
+/** Appends the call UUID as a `call_uuid` query param to the media URL so the WSS can key the socket. */
+function appendCallUuid(mediaUrl: string, callUuid: string): string {
+    const sep = mediaUrl.includes('?') ? '&' : '?';
+    return `${mediaUrl}${sep}call_uuid=${encodeURIComponent(callUuid)}`;
+}
+
+/** Coerces an Express body (JSON object or urlencoded) to the `Record<string,string>` the verifiers expect. */
+function coerceParams(body: unknown): Record<string, string> {
+    const out: Record<string, string> = {};
+    if (body && typeof body === 'object') {
+        for (const [key, value] of Object.entries(body as Record<string, unknown>)) {
+            if (typeof value === 'string') {
+                out[key] = value;
+            } else if (typeof value === 'number' || typeof value === 'boolean') {
+                out[key] = String(value);
+            }
+        }
+    }
+    return out;
+}
+
+/** Resolves the server-side principal + provider for the public webhook (no MJ JWT on a carrier request). */
+function resolveServerContext(): { user: UserInfo; provider: IMetadataProvider } | null {
+    const user = UserCache.Instance.GetSystemUser() ?? UserCache.Users.find((u) => u.IsActive && u.Type?.trim().toLowerCase() === 'owner') ?? null;
+    const provider = Metadata.Provider as unknown as IMetadataProvider | undefined; // global-provider-ok: public carrier webhook has no MJ JWT / per-request provider; the server's single default provider is correct
+    if (!user || !provider) {
+        return null;
+    }
+    return { user, provider };
+}