@memberjunction/server 5.44.0 → 5.45.1

package/src/telephony/VonageTelephonyService.ts

@@ -0,0 +1,259 @@
+/**
+ * @fileoverview Orchestrates Vonage telephony bridge sessions (inbound + outbound) for MJAPI.
+ *
+ * This is the composition layer between the carrier ingress (the public answer/event webhooks + the
+ * bidirectional media WSS) and the ONE unified realtime-agent pathway. It does NOT re-implement any
+ * bridge logic: it resolves the Vonage provider + the agent identity, opens a server-side realtime
+ * session via the agent layer's `CreateBridgeRealtimeSession` factory, binds `RealVonageBindings` (real
+ * REST Voice client + the per-call media registry) onto the driver, and hands everything to
+ * `AIBridgeEngine.StartBridgeSession` — exactly the seam the Twilio service + LiveKit room coordinator use.
+ *
+ * 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 Vonage
+ * credentials + a publicly reachable media URL — see telephony-vendor-bindings.md §T2).
+ *
+ * @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 { VonageCallSdk, RealVonageBindings, RealVonageVoiceClient } from '@memberjunction/ai-bridge-vonage';
+import type { VonageTelephonyConfig } from '../config.js';
+import { SessionManager } from '../agentSessions/SessionManager.js';
+import { VonageCallMediaRegistry } from './vonageMediaRegistry.js';
+
+const VONAGE_PROVIDER_DRIVER = 'VonageBridge';
+const AGENT_IDENTITY_ENTITY = 'MJ: AI Bridge Agent Identities';
+const PHONE_IDENTITY_TYPE = 'PhoneNumber';
+
+/** A resolved inbound call's identifying fields (parsed from the Vonage answer/event webhook). */
+export interface InboundCallInput {
+    /** The Vonage call UUID (`uuid` / `conversation_uuid`). */
+    callId: string;
+    /** The caller's number (Vonage `from`). */
+    from: string;
+    /** The dialed DID (Vonage `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 VonageTelephonyServiceDeps {
+    engine?: Pick<AIBridgeEngine, 'ProviderByName' | 'ProviderByDriverClass' | 'StartBridgeSession' | 'Config'>;
+    sessionFactory?: typeof CreateBridgeRealtimeSession;
+    sessionManager?: Pick<SessionManager, 'CreateSession'>;
+}
+
+/**
+ * Starts Vonage bridge sessions. One instance per server, constructed alongside the telephony router and
+ * sharing the {@link VonageCallMediaRegistry} with the media WSS server.
+ */
+export class VonageTelephonyService {
+    private readonly voice: RealVonageVoiceClient;
+    private readonly engine: Pick<AIBridgeEngine, 'ProviderByName' | 'ProviderByDriverClass' | 'StartBridgeSession' | 'Config'>;
+    private readonly sessionFactory: typeof CreateBridgeRealtimeSession;
+    private readonly sessionManager: Pick<SessionManager, 'CreateSession'>;
+
+    constructor(
+        private readonly config: VonageTelephonyConfig,
+        private readonly registry: VonageCallMediaRegistry,
+        deps: VonageTelephonyServiceDeps = {},
+    ) {
+        this.voice = new RealVonageVoiceClient({
+            ApplicationId: config.applicationId,
+            PrivateKey: config.privateKey,
+            ApiKey: config.apiKey,
+            ApiSecret: config.apiSecret,
+        });
+        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
+     * `RealVonageBindings` will accept the media socket (opened by the answer webhook's `connect` NCCO)
+     * for the call UUID. Returns `{ accepted:false }` (never throws) when no agent identity matches the
+     * DID, so the webhook can answer with a polite "no agent" NCCO 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.callId);
+            await this.startBridge({
+                agentID: identity.AgentID,
+                direction: 'Inbound',
+                address: input.from,
+                inboundCallId: input.callId,
+                contextUser,
+                provider,
+            });
+            return { accepted: true };
+        } catch (e) {
+            LogError(`[Telephony][Vonage] inbound call ${input.callId} 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
+     * `RealVonageBindings.createCall` issues the Voice REST `POST /v1/calls` with the `connect`-websocket
+     * NCCO; the returned call UUID is the bridge's external connection id.
+     *
+     * @returns The placed call UUID.
+     */
+    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 vonageProvider = 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: vonageProvider,
+            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 Vonage provider row (by driver class, falling back to display name). */
+    private resolveProvider(): MJAIBridgeProviderEntity {
+        const provider = this.engine.ProviderByDriverClass(VONAGE_PROVIDER_DRIVER) ?? this.engine.ProviderByName('Vonage');
+        if (!provider) {
+            throw new Error(`No active 'MJ: AI Bridge Providers' row for the Vonage bridge (DriverClass '${VONAGE_PROVIDER_DRIVER}').`);
+        }
+        return provider;
+    }
+
+    /**
+     * Builds the per-session SDK binding that wires the REAL Vonage bindings (REST Voice 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 VonageCallSdk(
+                    new RealVonageBindings({
+                        Voice: this.voice,
+                        MediaPump: this.registry,
+                        MediaWssUrl: this.config.mediaPublicUrl,
+                        EventUrl: this.config.eventUrl,
+                    }),
+                ),
+            );
+        };
+    }
+
+    /** Assembles the per-session bridge configuration (direction/from-number/inbound-call-id config keys). */
+    private buildSessionConfiguration(direction: 'Inbound' | 'Outbound', fromNumber?: string, inboundCallId?: string): Record<string, unknown> {
+        // The engine does NOT forward the top-level Direction into the driver's Configuration; the bridge
+        // defaults to 'Outbound' when the key is absent. Set it here so an inbound call answers instead of
+        // wrongly taking the outbound-dial path ("No 'From' number is specified").
+        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][Vonage] 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/calendar-scheduler.ts

@@ -0,0 +1,176 @@
+/**
+ * @fileoverview Host wiring for the scheduled/invite-driven meeting join loop (program M2).
+ *
+ * Composes the offline-complete seams from `@memberjunction/ai-bridge-server` into a running
+ * background loop, mirroring the {@link SessionJanitor} startup pattern (run once at boot, then on an
+ * interval):
+ *
+ *   1. {@link CalendarWatcher} polls each agent identity's calendar (via the injected
+ *      {@link CalendarSourceResolver}, bound here to the real {@link GraphCalendarClient} /
+ *      {@link GoogleCalendarClient}) and creates a `Scheduled` `AIAgentSessionBridge` for every invite
+ *      addressed to the agent.
+ *   2. {@link ScheduledBridgeRunner} starts each bridge whose `ScheduledStartTime` is due, building the
+ *      realtime session + the provider bind-sdk via the per-provider meeting service (Teams today).
+ *
+ * Calendar credentials are PRE-RESOLVED upstream (the bot's Graph access token comes from the Teams
+ * meetings config — `botAccessToken`, resolved via MJ config, never inline). Google calendar polling
+ * binds only when a Google auth client is supplied; otherwise those identities are skipped (the watcher
+ * tolerates a `null` source per identity). Live verification requires a real tenant + the Azure app /
+ * Google service account — the same access the meeting bridges need.
+ *
+ * @module @memberjunction/server/telephony
+ */
+
+import { UserInfo, IMetadataProvider, LogStatus, LogError } from '@memberjunction/core';
+import type { MJAIAgentSessionEntity } from '@memberjunction/core-entities';
+import {
+    CalendarWatcher,
+    ScheduledBridgeRunner,
+    GraphCalendarSource,
+    GraphCalendarClient,
+    type CalendarSourceResolver,
+    type ScheduledBridgeSessionFactory,
+    type StartBridgeSessionParams,
+} from '@memberjunction/ai-bridge-server';
+import type { TeamsMeetingsConfig } from '../config.js';
+import { TeamsMeetingsService } from './TeamsMeetingsService.js';
+
+/** The Teams bridge driver class — identities/bridges on this provider poll Graph + join via the Teams service. */
+const TEAMS_PROVIDER_DRIVER = 'TeamsBridge';
+
+/** Default cadence (ms) for the calendar sweep + due-bridge run. 60s balances freshness vs. API quota. */
+const DEFAULT_POLL_INTERVAL_MS = 60_000;
+
+/** Options for {@link StartCalendarScheduler}. */
+export interface CalendarSchedulerOptions {
+    /** The server metadata provider all reads/writes run under. */
+    Provider: IMetadataProvider;
+    /** The system user the watcher + runner (and every created/started bridge) run as. */
+    ContextUser: UserInfo;
+    /** The Teams meetings service (shared with the ingress) — supplies the scheduled-join bind-sdk. */
+    TeamsService: TeamsMeetingsService;
+    /** The Teams meetings config — supplies the bot Graph access token for calendar polling. */
+    TeamsConfig: TeamsMeetingsConfig;
+    /** Poll cadence (ms). Defaults to {@link DEFAULT_POLL_INTERVAL_MS}. */
+    PollIntervalMs?: number;
+}
+
+/** A running scheduler handle — call {@link CalendarSchedulerHandle.Stop} to clear the interval. */
+export interface CalendarSchedulerHandle {
+    /** Stops the periodic sweep/run loop (clears the timer). Safe to call more than once. */
+    Stop(): void;
+}
+
+/**
+ * Builds the {@link CalendarSourceResolver} that binds the real calendar clients per identity. Graph
+ * (Teams/Microsoft) identities bind a {@link GraphCalendarClient} authenticated with the bot's
+ * pre-resolved Graph token; any identity without configured credentials resolves to `null` and is
+ * skipped this sweep (the watcher tolerates that). Google binding activates when a Google auth client
+ * is wired into the deployment (none configured today → Google-backed identities are skipped).
+ */
+export function buildCalendarSourceResolver(teamsConfig: TeamsMeetingsConfig): CalendarSourceResolver {
+    return (_identity, provider) => {
+        const driver = provider?.DriverClass?.trim();
+        if (driver === TEAMS_PROVIDER_DRIVER && teamsConfig.botAccessToken) {
+            return new GraphCalendarSource(new GraphCalendarClient({ Credentials: { AccessToken: teamsConfig.botAccessToken } }));
+        }
+        // Google Calendar is a deliberate, CLOSED seam — intentionally not bound here. The
+        // GoogleCalendarClient is built + unit-tested, but binding it would be dead code today:
+        //   1. there is no Google Meet *join* path for a detected invite to trigger (the scheduled-join
+        //      factory is Teams-only), and
+        //   2. Google's Meet Media API is Developer-Preview + allowlist-gated regardless (every meeting
+        //      participant must be enrolled), so it isn't a shippable target.
+        // To activate: define a Google auth client from config AND wire a Google Meet join. Until then
+        // Google identities are skipped rather than erroring the sweep.
+        return null;
+    };
+}
+
+/**
+ * Builds the {@link ScheduledBridgeSessionFactory} that turns a due bridge into start params. Resolves
+ * the bridge's agent (via its `AIAgentSession`) and, for a Teams bridge, delegates to the shared
+ * {@link TeamsMeetingsService} so the scheduled join reuses the exact provider/session/bind-sdk path as
+ * an on-demand join. Returns `null` (skip) for a provider with no scheduled-join wiring yet, or when the
+ * bridge has no join address.
+ */
+export function buildScheduledSessionFactory(teamsService: TeamsMeetingsService): ScheduledBridgeSessionFactory {
+    return async (ctx) => {
+        const joinUrl = ctx.BridgeRow.Address?.trim();
+        if (!joinUrl) {
+            LogStatus(`[CalendarScheduler] bridge ${ctx.BridgeRow.ID} has no join address; skipping.`);
+            return null;
+        }
+        if (ctx.Provider.DriverClass?.trim() !== TEAMS_PROVIDER_DRIVER) {
+            LogStatus(`[CalendarScheduler] no scheduled-join wiring for provider '${ctx.Provider.Name}'; skipping bridge ${ctx.BridgeRow.ID}.`);
+            return null;
+        }
+        const agentID = await resolveAgentID(ctx.BridgeRow.AgentSessionID, ctx.ContextUser, ctx.MetadataProvider);
+        if (!agentID) {
+            LogStatus(`[CalendarScheduler] could not resolve agent for session ${ctx.BridgeRow.AgentSessionID}; skipping.`);
+            return null;
+        }
+        const params: StartBridgeSessionParams = await teamsService.BuildScheduledStartParams({
+            agentID,
+            joinUrl,
+            agentSessionID: ctx.BridgeRow.AgentSessionID,
+            contextUser: ctx.ContextUser,
+            provider: ctx.MetadataProvider,
+        });
+        return params;
+    };
+}
+
+/** Loads the `AIAgentSession` to resolve the agent the scheduled bridge belongs to. */
+async function resolveAgentID(
+    agentSessionID: string,
+    contextUser: UserInfo,
+    provider: IMetadataProvider,
+): Promise<string | null> {
+    const session = await provider.GetEntityObject<MJAIAgentSessionEntity>('MJ: AI Agent Sessions', contextUser);
+    if (!(await session.Load(agentSessionID))) {
+        return null;
+    }
+    return session.AgentID;
+}
+
+/**
+ * Starts the calendar/scheduled-bridge loop: sweeps calendars and runs due bridges once immediately,
+ * then on a fixed interval. Mirrors {@link SessionJanitor.Start}. A sweep/run failure is logged and the
+ * loop continues — a transient calendar/transport error never kills the scheduler.
+ */
+export function StartCalendarScheduler(options: CalendarSchedulerOptions): CalendarSchedulerHandle {
+    const watcher = new CalendarWatcher({
+        SourceResolver: buildCalendarSourceResolver(options.TeamsConfig),
+        ContextUser: options.ContextUser,
+        MetadataProvider: options.Provider,
+    });
+    const runner = new ScheduledBridgeRunner({
+        SessionFactory: buildScheduledSessionFactory(options.TeamsService),
+        ContextUser: options.ContextUser,
+        MetadataProvider: options.Provider,
+    });
+
+    const tick = async (): Promise<void> => {
+        try {
+            const swept = await watcher.Sweep();
+            const ran = await runner.RunDueBridges();
+            if (swept.BridgesCreated > 0 || ran.Started > 0) {
+                LogStatus(`[CalendarScheduler] swept ${swept.BridgesCreated} new bridge(s); started ${ran.Started} due bridge(s).`);
+            }
+        } catch (err) {
+            LogError(`[CalendarScheduler] sweep/run pass failed (continuing): ${err instanceof Error ? err.message : String(err)}`);
+        }
+    };
+
+    void tick(); // run-once at boot
+    const timer = setInterval(() => void tick(), options.PollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS);
+    // Don't let the poll timer keep the process alive at shutdown (the loop is best-effort background work).
+    timer.unref?.();
+    LogStatus(`[CalendarScheduler] started (every ${(options.PollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS) / 1000}s).`);
+
+    return {
+        Stop(): void {
+            clearInterval(timer);
+        },
+    };
+}

package/src/telephony/index.ts

@@ -0,0 +1,43 @@
+/**
+ * @fileoverview Public exports for the MJAPI telephony + meetings ingress.
+ *
+ * Each vendor ingress is a quartet: a per-call media registry, a bridge-orchestration service, an
+ * Express/WSS router (the `create*Handler` factory + mount-path consts), and a process-wide runtime
+ * holder (`Set*`/`Get*`). The routers + runtimes are star-exported; the service + registry modules are
+ * re-exported by name to avoid star-export ambiguity on their internal, per-vendor-identical helper
+ * types (`InboundCallInput`, `InboundCallResult`, `ITelephonyMediaSocket`). Those internal types are
+ * not part of the package's public surface — code that needs them imports from the source module.
+ *
+ * @module @memberjunction/server/telephony
+ */
+
+// ── Shared WebSocket-upgrade dispatcher (routes GraphQL + all media sockets by path) ──────
+export * from './media-upgrade-router.js';
+
+// ── Twilio Programmable Voice + Media Streams ──────────────────────────────────────────
+export { TwilioCallMediaRegistry } from './twilioMediaRegistry.js';
+export { TwilioTelephonyService, type TwilioTelephonyServiceDeps } from './TwilioTelephonyService.js';
+export * from './TwilioTelephonyRouter.js';
+export * from './telephony-runtime.js';
+
+// ── Vonage Voice + WebSocket-media ─────────────────────────────────────────────────────
+export { VonageCallMediaRegistry } from './vonageMediaRegistry.js';
+export { VonageTelephonyService, type VonageTelephonyServiceDeps } from './VonageTelephonyService.js';
+export * from './VonageTelephonyRouter.js';
+export * from './vonage-runtime.js';
+
+// ── RingCentral SIP softphone (the only RingCentral transport with bidirectional call audio) ──
+// No media registry / webhook router: the softphone is an outbound SIP registration that receives inbound
+// INVITEs directly. The service owns the registration; the runtime holder shares it with the outbound
+// PlaceRingCentralCall resolver.
+export { RingCentralTelephonyService, type RingCentralTelephonyServiceDeps } from './RingCentralTelephonyService.js';
+export * from './ringcentral-runtime.js';
+
+// ── Teams meetings (Microsoft Graph cloud-communications + ACS application-hosted media) ──
+export * from './teamsAcsMediaRegistry.js';
+export * from './TeamsMeetingsService.js';
+export * from './TeamsMeetingsRouter.js';
+export * from './teams-meetings-runtime.js';
+
+// ── Scheduled / invite-driven meeting join loop (M2: calendar watcher + due-bridge runner) ──
+export * from './calendar-scheduler.js';

package/src/telephony/media-upgrade-router.ts

@@ -0,0 +1,62 @@
+/**
+ * @fileoverview Single WebSocket-upgrade dispatcher for the shared HTTP server.
+ *
+ * Why this exists: in `ws` 8.x, every `new WebSocketServer({ server })` attaches its OWN `upgrade`
+ * listener that calls `handleUpgrade` UNCONDITIONALLY, and `handleUpgrade` does `abortHandshake(400)` for
+ * any request whose path it doesn't own. So two `{server}`-bound servers on one HTTP server (e.g. the
+ * GraphQL subscriptions socket on `/` AND a telephony Media-Streams socket on `/telephony/.../media`)
+ * fight on every upgrade — the non-owning server 400s the request. That's exactly what made Twilio's
+ * `<Connect><Stream>` fail with error 31920 ("Stream WebSocket failed to connect").
+ *
+ * The fix: telephony/meetings media servers are created with `{ noServer: true }` (no auto-listener) and
+ * register their path here; at boot we strip the auto-listeners and install ONE `upgrade` listener that
+ * routes by path — GraphQL on its root path, each media socket on its own. When no media routes are
+ * registered (telephony disabled), we leave the GraphQL server's own listener untouched (zero change).
+ *
+ * @module @memberjunction/server/telephony
+ */
+
+import type { IncomingMessage, Server as HttpServer } from 'node:http';
+import type { Duplex } from 'node:stream';
+import type { WebSocketServer } from 'ws';
+
+/** path → the `{ noServer:true }` WebSocketServer that owns it. */
+const mediaRoutes = new Map<string, WebSocketServer>();
+
+/** Registers a media WebSocket route. Called by each vendor router's attach step. */
+export function RegisterMediaUpgradeRoute(path: string, wss: WebSocketServer): void {
+    mediaRoutes.set(path, wss);
+}
+
+/**
+ * Installs the single path-routing `upgrade` dispatcher. No-op when no media routes are registered, so
+ * the GraphQL server keeps its own listener untouched. Otherwise it removes the auto-attached listeners
+ * (GraphQL's included) and dispatches every upgrade by pathname — GraphQL on `graphqlPath`, each media
+ * socket on its registered path; unknown paths are destroyed.
+ *
+ * @param httpServer  the shared HTTP server.
+ * @param graphqlWss  the GraphQL subscriptions WebSocketServer (kept, re-dispatched on its path).
+ * @param graphqlPath the GraphQL root path (the path GraphQL's socket listens on).
+ */
+export function InstallMediaUpgradeDispatcher(httpServer: HttpServer, graphqlWss: WebSocketServer, graphqlPath: string): void {
+    if (mediaRoutes.size === 0) {
+        return;
+    }
+    httpServer.removeAllListeners('upgrade');
+    const dispatch = (wss: WebSocketServer, req: IncomingMessage, socket: Duplex, head: Buffer): void => {
+        wss.handleUpgrade(req, socket, head, (ws) => wss.emit('connection', ws, req));
+    };
+    httpServer.on('upgrade', (req: IncomingMessage, socket: Duplex, head: Buffer) => {
+        const pathname = (req.url ?? '').split('?')[0];
+        if (pathname === graphqlPath) {
+            dispatch(graphqlWss, req, socket, head);
+            return;
+        }
+        const wss = mediaRoutes.get(pathname);
+        if (wss) {
+            dispatch(wss, req, socket, head);
+            return;
+        }
+        socket.destroy();
+    });
+}

package/src/telephony/ringcentral-runtime.ts

@@ -0,0 +1,22 @@
+/**
+ * @fileoverview Process-wide holder for the startup-constructed RingCentral telephony service, so the
+ * outbound `PlaceRingCentralCall` GraphQL resolver reaches the SAME {@link RingCentralTelephonyService}
+ * (and thus the same long-lived SIP-softphone registration) that the inbound INVITE coordinator uses. Set
+ * once during server boot; read by the resolver.
+ *
+ * @module @memberjunction/server/telephony
+ */
+
+import type { RingCentralTelephonyService } from './RingCentralTelephonyService.js';
+
+let ringCentralService: RingCentralTelephonyService | undefined;
+
+/** Binds the startup-constructed RingCentral telephony service (called from server boot). */
+export function SetRingCentralTelephonyService(service: RingCentralTelephonyService): void {
+    ringCentralService = service;
+}
+
+/** Returns the bound RingCentral telephony service, or `undefined` when telephony is not configured. */
+export function GetRingCentralTelephonyService(): RingCentralTelephonyService | undefined {
+    return ringCentralService;
+}

package/src/telephony/teams-meetings-runtime.ts

@@ -0,0 +1,24 @@
+/**
+ * @fileoverview Process-wide holder for the startup-constructed Teams meetings service, so the
+ * `StartTeamsMeetingSession` GraphQL resolver reaches the SAME {@link TeamsMeetingsService} (and thus the
+ * same {@link TeamsAcsMediaRegistry} the ACS media adapter attaches transports to) that the Graph
+ * change-notification webhook router uses. Set once during server boot; read by the resolver + the router.
+ *
+ * Mirrors `telephony-runtime.ts` (the Twilio equivalent).
+ *
+ * @module @memberjunction/server/telephony
+ */
+
+import type { TeamsMeetingsService } from './TeamsMeetingsService.js';
+
+let teamsService: TeamsMeetingsService | undefined;
+
+/** Binds the startup-constructed Teams meetings service (called from server boot). */
+export function SetTeamsMeetingsService(service: TeamsMeetingsService): void {
+    teamsService = service;
+}
+
+/** Returns the bound Teams meetings service, or `undefined` when Teams meetings are not configured. */
+export function GetTeamsMeetingsService(): TeamsMeetingsService | undefined {
+    return teamsService;
+}