@memberjunction/server 5.43.0 → 5.45.0

package/dist/telephony/RingCentralTelephonyService.js

@@ -0,0 +1,262 @@
+/**
+ * @fileoverview Orchestrates RingCentral telephony bridge sessions (inbound + outbound) for MJAPI over the
+ * **SIP softphone** transport.
+ *
+ * RingCentral's only product that carries bidirectional call audio is a registered SIP softphone (the
+ * `ringcentral-softphone` SDK over SIP/TLS + RTP/SRTP) — its WebSocket "Call Streaming" product is
+ * receive-only and cannot inject the agent's voice. So unlike the Twilio/Vonage ingresses (public webhook
+ * + media WSS), this service owns a **long-lived SIP registration**: one
+ * {@link RingCentralSoftphoneHandle} created + registered at boot, shared across all calls. Inbound calls
+ * arrive as SIP INVITEs on that registration (no HTTP webhook); outbound calls place SIP calls through it.
+ *
+ * It does NOT re-implement bridge logic: it resolves the RingCentral provider + the agent identity, opens a
+ * server-side realtime session via the agent layer's `CreateBridgeRealtimeSession` factory, binds a
+ * {@link RingCentralSoftphoneCallSdk} (drawing its session from the shared handle) onto the driver, and
+ * hands everything to `AIBridgeEngine.StartBridgeSession` — the same seam the Twilio/Vonage services use.
+ *
+ * @module @memberjunction/server/telephony
+ */
+import { RunView, Metadata, LogError, LogStatus } from '@memberjunction/core';
+import { UserCache } from '@memberjunction/sqlserver-dataprovider';
+import { AIBridgeEngine } from '@memberjunction/ai-bridge-server';
+import { CreateBridgeRealtimeSession } from '@memberjunction/ai-agents';
+import { CARRIER_SAMPLE_RATE_CONFIG_KEY, DIRECTION_CONFIG_KEY, FROM_NUMBER_CONFIG_KEY, INBOUND_CALL_ID_CONFIG_KEY, } from '@memberjunction/ai-bridge-base';
+import { createRingCentralSoftphone, RingCentralSoftphoneCallSdk, } from '@memberjunction/ai-bridge-ringcentral';
+import { SessionManager } from '../agentSessions/SessionManager.js';
+const RINGCENTRAL_PROVIDER_DRIVER = 'RingCentralBridge';
+const AGENT_IDENTITY_ENTITY = 'MJ: AI Bridge Agent Identities';
+const PHONE_IDENTITY_TYPE = 'PhoneNumber';
+/** PCM16 carrier rate (Hz) per softphone codec — the rate the bridge resamples to/from the model rate. */
+const CODEC_CARRIER_RATE = {
+    'OPUS/16000': 16000,
+    'OPUS/48000/2': 48000,
+    'PCMU/8000': 8000,
+};
+/**
+ * Starts RingCentral bridge sessions over a shared SIP-softphone registration. One instance per server,
+ * constructed at boot and held by the runtime holder so the outbound `PlaceRingCentralCall` resolver and the
+ * inbound INVITE coordinator share the same registration.
+ */
+export class RingCentralTelephonyService {
+    constructor(config, deps = {}) {
+        this.config = config;
+        /** The shared SIP registration — created + registered by {@link start}; null until then. */
+        this.handle = null;
+        /** The carrier PCM16 rate for the negotiated codec (set in {@link start}). */
+        this.carrierSampleRate = CODEC_CARRIER_RATE['OPUS/16000'];
+        this.engine = deps.engine ?? AIBridgeEngine.Instance;
+        this.sessionFactory = deps.sessionFactory ?? CreateBridgeRealtimeSession;
+        this.sessionManager = deps.sessionManager ?? new SessionManager();
+        this.createHandle = deps.createHandle ?? createRingCentralSoftphone;
+    }
+    /**
+     * Creates + registers the shared SIP softphone and wires inbound INVITE handling. Called once at boot
+     * (fire-and-forget so SIP registration never blocks server startup); logs success/failure. Inbound calls
+     * only flow once this resolves.
+     */
+    async start() {
+        try {
+            this.carrierSampleRate = CODEC_CARRIER_RATE[this.config.codec ?? 'OPUS/16000'];
+            this.handle = await this.createHandle(this.toSoftphoneConfig());
+            this.handle.onInvite((info) => void this.onInboundInvite(info));
+            await this.handle.register();
+            LogStatus('[Telephony][RingCentral] softphone telephony started (inbound + outbound ready).');
+        }
+        catch (e) {
+            this.handle = null;
+            LogError(`[Telephony][RingCentral] softphone start failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    /** Best-effort teardown of the SIP registration (server shutdown). */
+    dispose() {
+        this.handle?.dispose();
+        this.handle = null;
+    }
+    /**
+     * Resolves the dialed DID to a pinned agent and starts an INBOUND bridge session. The bound
+     * {@link RingCentralSoftphoneCallSdk} answers the parked INVITE for `sessionId`. Returns
+     * `{ accepted:false }` (never throws) when no agent identity matches the DID, so the coordinator can
+     * decline the INVITE cleanly.
+     */
+    async HandleInboundCall(input, contextUser, provider) {
+        try {
+            const identity = await this.resolveAgentIdentityByPhone(input.to, contextUser);
+            if (!identity) {
+                return { accepted: false, reason: `No active agent identity for dialed number '${input.to}'.` };
+            }
+            await this.startBridge({
+                agentID: identity.AgentID,
+                direction: 'Inbound',
+                address: input.from,
+                inboundCallId: input.sessionId,
+                contextUser,
+                provider,
+            });
+            return { accepted: true };
+        }
+        catch (e) {
+            LogError(`[Telephony][RingCentral] inbound call ${input.sessionId} 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
+     * {@link RingCentralSoftphoneCallSdk} places the SIP call through the shared registration; the returned
+     * SIP `Call-ID` is the bridge's external connection id.
+     *
+     * @returns The placed call's SIP `Call-ID`.
+     */
+    async PlaceOutboundCall(agentIdentityId, toNumber, contextUser, provider) {
+        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 ────────────────────────────────────────────────────────────────
+    /** Inbound INVITE coordinator: resolve the server principal, start a bridge, decline if no agent matched. */
+    async onInboundInvite(info) {
+        const context = this.resolveServerContext();
+        if (!context) {
+            LogError('[Telephony][RingCentral] no server context user available; declining inbound call.');
+            await this.handle?.declineCall(info.callId);
+            return;
+        }
+        const result = await this.HandleInboundCall({ sessionId: info.callId, from: info.from, to: info.to }, context.user, context.provider);
+        if (!result.accepted) {
+            LogStatus(`[Telephony][RingCentral] inbound ${info.callId} not accepted: ${result.reason ?? 'unknown'}; declining.`);
+            await this.handle?.declineCall(info.callId);
+        }
+    }
+    /** Shared inbound/outbound bridge-start: resolve provider, open the realtime session, bind the SDK, start. */
+    async startBridge(args) {
+        await this.engine.Config(false, args.contextUser, args.provider);
+        const ringCentralProvider = 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: ringCentralProvider,
+            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 RingCentral provider row (by driver class, falling back to display name). */
+    resolveProvider() {
+        const provider = this.engine.ProviderByDriverClass(RINGCENTRAL_PROVIDER_DRIVER) ?? this.engine.ProviderByName('RingCentral');
+        if (!provider) {
+            throw new Error(`No active 'MJ: AI Bridge Providers' row for the RingCentral bridge (DriverClass '${RINGCENTRAL_PROVIDER_DRIVER}').`);
+        }
+        return provider;
+    }
+    /**
+     * Builds the per-session SDK binding that wires a {@link RingCentralSoftphoneCallSdk} (drawing its
+     * session from the shared SIP registration handle) onto the telephony driver — overriding the package's
+     * default unbound SDK. Reads the handle lazily at call time so a call placed during the brief boot window
+     * before registration fails loudly rather than binding a null handle.
+     */
+    buildBindSdk() {
+        return (driver) => {
+            const telephony = driver;
+            telephony.SetSdkFactory(() => new RingCentralSoftphoneCallSdk(this.requireHandle()));
+        };
+    }
+    /** Returns the live registration handle, or throws if the softphone hasn't registered yet. */
+    requireHandle() {
+        if (!this.handle) {
+            throw new Error('[Telephony][RingCentral] softphone not registered yet (start() pending or failed).');
+        }
+        return this.handle;
+    }
+    /** Assembles the per-session bridge configuration (direction / from-number / inbound-call-id / carrier rate). */
+    buildSessionConfiguration(direction, fromNumber, inboundCallId) {
+        // The engine does NOT forward the top-level Direction into the driver's Configuration; set it here so
+        // an inbound call answers instead of wrongly taking the outbound-dial path. The carrier rate tells the
+        // base bridge the SIP leg is wideband (16 kHz for OPUS/16000), not the 8 kHz G.711 default.
+        const config = {
+            [DIRECTION_CONFIG_KEY]: direction,
+            [CARRIER_SAMPLE_RATE_CONFIG_KEY]: this.carrierSampleRate,
+        };
+        if (fromNumber) {
+            config[FROM_NUMBER_CONFIG_KEY] = fromNumber;
+        }
+        if (inboundCallId) {
+            config[INBOUND_CALL_ID_CONFIG_KEY] = inboundCallId;
+        }
+        return config;
+    }
+    /** Maps the server config block to the softphone SDK's SIP-device config (credentials resolved upstream). */
+    toSoftphoneConfig() {
+        return {
+            domain: this.config.sipDomain,
+            outboundProxy: this.config.sipOutboundProxy,
+            username: this.config.sipUsername,
+            password: this.config.sipPassword,
+            authorizationId: this.config.sipAuthorizationId,
+            codec: this.config.codec,
+            ignoreTlsCertErrors: this.config.ignoreTlsCertErrors,
+        };
+    }
+    /** Resolves the server-side principal + provider for an inbound call (no MJ JWT on a SIP INVITE). */
+    resolveServerContext() {
+        const user = UserCache.Instance.GetSystemUser() ?? UserCache.Users.find((u) => u.IsActive && u.Type?.trim().toLowerCase() === 'owner') ?? null;
+        const provider = Metadata.Provider; // global-provider-ok: inbound SIP INVITE has no MJ JWT / per-request provider; the server's single default provider is correct
+        if (!user || !provider) {
+            return null;
+        }
+        return { user, provider };
+    }
+    /** Finds the active agent identity whose phone number matches the dialed DID. */
+    async resolveAgentIdentityByPhone(dialedNumber, contextUser) {
+        const normalized = (dialedNumber ?? '').trim();
+        if (!normalized) {
+            return null;
+        }
+        const rv = new RunView();
+        const result = await rv.RunView({
+            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][RingCentral] 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. */
+    async loadAgentIdentity(agentIdentityId, contextUser, provider) {
+        // Use the request-scoped provider (multi-provider safe), not the global Metadata.
+        const entity = await provider.GetEntityObject(AGENT_IDENTITY_ENTITY, contextUser);
+        const loaded = await entity.Load(agentIdentityId);
+        if (!loaded || !entity.IsActive) {
+            return null;
+        }
+        return entity;
+    }
+}
+//# sourceMappingURL=RingCentralTelephonyService.js.map

package/dist/telephony/RingCentralTelephonyService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RingCentralTelephonyService.js","sourceRoot":"","sources":["../../src/telephony/RingCentralTelephonyService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,OAAO,EAA+B,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAE3G,OAAO,EAAE,SAAS,EAAE,MAAM,wCAAwC,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AAClE,OAAO,EAAE,2BAA2B,EAAE,MAAM,2BAA2B,CAAC;AACxE,OAAO,EAGH,8BAA8B,EAC9B,oBAAoB,EACpB,sBAAsB,EACtB,0BAA0B,GAC7B,MAAM,gCAAgC,CAAC;AACxC,OAAO,EACH,0BAA0B,EAC1B,2BAA2B,GAI9B,MAAM,uCAAuC,CAAC;AAE/C,OAAO,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAEpE,MAAM,2BAA2B,GAAG,mBAAmB,CAAC;AACxD,MAAM,qBAAqB,GAAG,gCAAgC,CAAC;AAC/D,MAAM,mBAAmB,GAAG,aAAa,CAAC;AAE1C,0GAA0G;AAC1G,MAAM,kBAAkB,GAAqE;IACzF,YAAY,EAAE,KAAK;IACnB,cAAc,EAAE,KAAK;IACrB,WAAW,EAAE,IAAI;CACpB,CAAC;AA6BF;;;;GAIG;AACH,MAAM,OAAO,2BAA2B;IAYpC,YACqB,MAAkC,EACnD,OAAwC,EAAE;QADzB,WAAM,GAAN,MAAM,CAA4B;QAPvD,4FAA4F;QACpF,WAAM,GAAsC,IAAI,CAAC;QAEzD,8EAA8E;QACtE,sBAAiB,GAAW,kBAAkB,CAAC,YAAY,CAAC,CAAC;QAMjE,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,cAAc,CAAC,QAAQ,CAAC;QACrD,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC,cAAc,IAAI,2BAA2B,CAAC;QACzE,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC,cAAc,IAAI,IAAI,cAAc,EAAE,CAAC;QAClE,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,YAAY,IAAI,0BAA0B,CAAC;IACxE,CAAC;IAED;;;;OAIG;IACI,KAAK,CAAC,KAAK;QACd,IAAI,CAAC;YACD,IAAI,CAAC,iBAAiB,GAAG,kBAAkB,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,IAAI,YAAY,CAAC,CAAC;YAC/E,IAAI,CAAC,MAAM,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,iBAAiB,EAAE,CAAC,CAAC;YAChE,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC;YAChE,MAAM,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;YAC7B,SAAS,CAAC,kFAAkF,CAAC,CAAC;QAClG,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACT,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;YACnB,QAAQ,CAAC,oDAAoD,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAC/G,CAAC;IACL,CAAC;IAED,sEAAsE;IAC/D,OAAO;QACV,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC;QACvB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;IACvB,CAAC;IAED;;;;;OAKG;IACI,KAAK,CAAC,iBAAiB,CAAC,KAAuB,EAAE,WAAqB,EAAE,QAA2B;QACtG,IAAI,CAAC;YACD,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,2BAA2B,CAAC,KAAK,CAAC,EAAE,EAAE,WAAW,CAAC,CAAC;YAC/E,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACZ,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,+CAA+C,KAAK,CAAC,EAAE,IAAI,EAAE,CAAC;YACpG,CAAC;YACD,MAAM,IAAI,CAAC,WAAW,CAAC;gBACnB,OAAO,EAAE,QAAQ,CAAC,OAAO;gBACzB,SAAS,EAAE,SAAS;gBACpB,OAAO,EAAE,KAAK,CAAC,IAAI;gBACnB,aAAa,EAAE,KAAK,CAAC,SAAS;gBAC9B,WAAW;gBACX,QAAQ;aACX,CAAC,CAAC;YACH,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;QAC9B,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACT,QAAQ,CAAC,yCAAyC,KAAK,CAAC,SAAS,YAAY,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YAC3H,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,oCAAoC,EAAE,CAAC;QAC7E,CAAC;IACL,CAAC;IAED;;;;;;OAMG;IACI,KAAK,CAAC,iBAAiB,CAAC,eAAuB,EAAE,QAAgB,EAAE,WAAqB,EAAE,QAA2B;QACxH,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,iBAAiB,CAAC,eAAe,EAAE,WAAW,EAAE,QAAQ,CAAC,CAAC;QACtF,IAAI,CAAC,QAAQ,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CAAC,mBAAmB,eAAe,0BAA0B,CAAC,CAAC;QAClF,CAAC;QACD,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC;YACnC,OAAO,EAAE,QAAQ,CAAC,OAAO;YACzB,SAAS,EAAE,UAAU;YACrB,OAAO,EAAE,QAAQ;YACjB,UAAU,EAAE,QAAQ,CAAC,aAAa;YAClC,WAAW;YACX,QAAQ;SACX,CAAC,CAAC;QACH,OAAO,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC;IACjC,CAAC;IAED,gFAAgF;IAEhF,6GAA6G;IACrG,KAAK,CAAC,eAAe,CAAC,IAAuB;QACjD,MAAM,OAAO,GAAG,IAAI,CAAC,oBAAoB,EAAE,CAAC;QAC5C,IAAI,CAAC,OAAO,EAAE,CAAC;YACX,QAAQ,CAAC,oFAAoF,CAAC,CAAC;YAC/F,MAAM,IAAI,CAAC,MAAM,EAAE,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YAC5C,OAAO;QACX,CAAC;QACD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,iBAAiB,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,EAAE,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;QACtI,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;YACnB,SAAS,CAAC,oCAAoC,IAAI,CAAC,MAAM,kBAAkB,MAAM,CAAC,MAAM,IAAI,SAAS,cAAc,CAAC,CAAC;YACrH,MAAM,IAAI,CAAC,MAAM,EAAE,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAChD,CAAC;IACL,CAAC;IAED,8GAA8G;IACtG,KAAK,CAAC,WAAW,CAAC,IAQzB;QACG,MAAM,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;QACjE,MAAM,mBAAmB,GAAG,IAAI,CAAC,eAAe,EAAE,CAAC;QAEnD,MAAM,YAAY,GAAG,MAAM,IAAI,CAAC,cAAc,CAAC,aAAa,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,WAAW,CAAC,EAAE,EAAE,EAAE,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;QACtJ,MAAM,eAAe,GAAG,MAAM,IAAI,CAAC,cAAc,CAAC;YAC9C,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,aAAa,EAAE,IAAI,CAAC,OAAO;YAC3B,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,gBAAgB,EAAE,IAAI,CAAC,QAAQ;YAC/B,cAAc,EAAE,YAAY,CAAC,EAAE;YAC/B,QAAQ,EAAE,IAAI,CAAC,OAAO;SACzB,CAAC,CAAC;QAEH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,kBAAkB,CAAC;YAChD,cAAc,EAAE,YAAY,CAAC,EAAE;YAC/B,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,aAAa,EAAE,IAAI,CAAC,OAAO;YAC3B,QAAQ,EAAE,mBAAmB;YAC7B,eAAe,EAAE,eAAe;YAChC,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,aAAa,EAAE,IAAI,CAAC,yBAAyB,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,aAAa,CAAC;YAClG,OAAO,EAAE,IAAI,CAAC,YAAY,EAAE;YAC5B,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,gBAAgB,EAAE,IAAI,CAAC,QAAQ;SAClC,CAAC,CAAC;QACH,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC;IACvC,CAAC;IAED,oGAAoG;IAC5F,eAAe;QACnB,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,qBAAqB,CAAC,2BAA2B,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,aAAa,CAAC,CAAC;QAC7H,IAAI,CAAC,QAAQ,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CAAC,oFAAoF,2BAA2B,KAAK,CAAC,CAAC;QAC1I,CAAC;QACD,OAAO,QAAQ,CAAC;IACpB,CAAC;IAED;;;;;OAKG;IACI,YAAY;QACf,OAAO,CAAC,MAAM,EAAE,EAAE;YACd,MAAM,SAAS,GAAG,MAA6B,CAAC;YAChD,SAAS,CAAC,aAAa,CAAC,GAAG,EAAE,CAAC,IAAI,2BAA2B,CAAC,IAAI,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC;QACzF,CAAC,CAAC;IACN,CAAC;IAED,8FAA8F;IACtF,aAAa;QACjB,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CAAC,oFAAoF,CAAC,CAAC;QAC1G,CAAC;QACD,OAAO,IAAI,CAAC,MAAM,CAAC;IACvB,CAAC;IAED,iHAAiH;IACzG,yBAAyB,CAAC,SAAiC,EAAE,UAAmB,EAAE,aAAsB;QAC5G,sGAAsG;QACtG,uGAAuG;QACvG,4FAA4F;QAC5F,MAAM,MAAM,GAA4B;YACpC,CAAC,oBAAoB,CAAC,EAAE,SAAS;YACjC,CAAC,8BAA8B,CAAC,EAAE,IAAI,CAAC,iBAAiB;SAC3D,CAAC;QACF,IAAI,UAAU,EAAE,CAAC;YACb,MAAM,CAAC,sBAAsB,CAAC,GAAG,UAAU,CAAC;QAChD,CAAC;QACD,IAAI,aAAa,EAAE,CAAC;YAChB,MAAM,CAAC,0BAA0B,CAAC,GAAG,aAAa,CAAC;QACvD,CAAC;QACD,OAAO,MAAM,CAAC;IAClB,CAAC;IAED,6GAA6G;IACrG,iBAAiB;QACrB,OAAO;YACH,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,SAAS;YAC7B,aAAa,EAAE,IAAI,CAAC,MAAM,CAAC,gBAAgB;YAC3C,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW;YACjC,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW;YACjC,eAAe,EAAE,IAAI,CAAC,MAAM,CAAC,kBAAkB;YAC/C,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,KAAK;YACxB,mBAAmB,EAAE,IAAI,CAAC,MAAM,CAAC,mBAAmB;SACvD,CAAC;IACN,CAAC;IAED,qGAAqG;IAC7F,oBAAoB;QACxB,MAAM,IAAI,GAAG,SAAS,CAAC,QAAQ,CAAC,aAAa,EAAE,IAAI,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,KAAK,OAAO,CAAC,IAAI,IAAI,CAAC;QAC/I,MAAM,QAAQ,GAAG,QAAQ,CAAC,QAAoD,CAAC,CAAC,+HAA+H;QAC/M,IAAI,CAAC,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YACrB,OAAO,IAAI,CAAC;QAChB,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;IAC9B,CAAC;IAED,iFAAiF;IACzE,KAAK,CAAC,2BAA2B,CAAC,YAAoB,EAAE,WAAqB;QACjF,MAAM,UAAU,GAAG,CAAC,YAAY,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;QAC/C,IAAI,CAAC,UAAU,EAAE,CAAC;YACd,OAAO,IAAI,CAAC;QAChB,CAAC;QACD,MAAM,EAAE,GAAG,IAAI,OAAO,EAAE,CAAC;QACzB,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,OAAO,CAC3B;YACI,UAAU,EAAE,qBAAqB;YACjC,WAAW,EAAE,iBAAiB,mBAAmB,wBAAwB,UAAU,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,kBAAkB;YACzH,OAAO,EAAE,CAAC;YACV,UAAU,EAAE,eAAe;SAC9B,EACD,WAAW,CACd,CAAC;QACF,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YAClB,QAAQ,CAAC,0DAA0D,MAAM,CAAC,YAAY,EAAE,CAAC,CAAC;YAC1F,OAAO,IAAI,CAAC;QAChB,CAAC;QACD,OAAO,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;IACvC,CAAC;IAED,kGAAkG;IAC1F,KAAK,CAAC,iBAAiB,CAAC,eAAuB,EAAE,WAAqB,EAAE,QAA2B;QACvG,kFAAkF;QAClF,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,eAAe,CAAgC,qBAAqB,EAAE,WAAW,CAAC,CAAC;QACjH,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;QAClD,IAAI,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;YAC9B,OAAO,IAAI,CAAC;QAChB,CAAC;QACD,OAAO,MAAM,CAAC;IAClB,CAAC;CACJ"}

package/dist/telephony/TeamsMeetingsRouter.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @fileoverview Express wiring for the Teams meetings ingress — the Microsoft Graph change-notification webhook.
+ *
+ * One public surface (Graph cannot present an MJ JWT — the subscription validation-token handshake + the
+ * per-notification `clientState` shared secret are the gate):
+ *   - `POST /meetings/teams/notifications` — the Graph change-notification endpoint. Handles BOTH:
+ *       1. The **subscription-validation handshake**: when Graph creates/renews a subscription it calls this
+ *          URL with `?validationToken=…` and expects the exact token echoed back as `text/plain` 200.
+ *       2. **Real call/participant notifications**: each carries a `clientState` verified (constant-time)
+ *          against the secret set on subscription creation, then mapped to the meetings service's roster /
+ *          call-ended drive helpers.
+ *
+ * Mirrors the Twilio telephony public-router pattern: mount the router BEFORE the unified auth middleware. The
+ * validation + notification parsing use the offline-complete, unit-tested helpers from the Teams provider
+ * package (`validateGraphNotification` / `parseCallNotification`); this module is thin HTTP plumbing over them
+ * and the {@link TeamsMeetingsService}.
+ *
+ * The ACS application-hosted-media socket(s) (the audio plane) are owned by the server's native ACS media
+ * adapter, which attaches transports to the shared {@link TeamsAcsMediaRegistry} — there is no media WSS here
+ * (unlike Twilio Media Streams), because ACS app-hosted media is negotiated out-of-band by that adapter.
+ *
+ * @module @memberjunction/server/telephony
+ */
+import { Router } from 'express';
+import type { TeamsMeetingsConfig } from '../config.js';
+import { TeamsAcsMediaRegistry } from './teamsAcsMediaRegistry.js';
+import { TeamsMeetingsService } from './TeamsMeetingsService.js';
+/** The mount path for the Teams meetings public router. */
+export declare const TEAMS_MEETINGS_MOUNT_PATH = "/meetings/teams";
+/**
+ * Builds the Teams meetings handler: the public Graph change-notification router + the shared ACS media
+ * registry + the meetings service (returned for observability/tests + so server boot can bind the service to
+ * the runtime holder and hand the registry to the native ACS media adapter).
+ */
+export declare function createTeamsMeetingsHandler(config: TeamsMeetingsConfig): {
+    publicRouter: Router;
+    registry: TeamsAcsMediaRegistry;
+    service: TeamsMeetingsService;
+};
+//# sourceMappingURL=TeamsMeetingsRouter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"TeamsMeetingsRouter.d.ts","sourceRoot":"","sources":["../../src/telephony/TeamsMeetingsRouter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,MAAM,EAAqC,MAAM,SAAS,CAAC;AAOpE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACxD,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACnE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAEjE,2DAA2D;AAC3D,eAAO,MAAM,yBAAyB,oBAAoB,CAAC;AAO3D;;;;GAIG;AACH,wBAAgB,0BAA0B,CACtC,MAAM,EAAE,mBAAmB,GAC5B;IACC,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,qBAAqB,CAAC;IAChC,OAAO,EAAE,oBAAoB,CAAC;CACjC,CAYA"}

package/dist/telephony/TeamsMeetingsRouter.js

@@ -0,0 +1,96 @@
+/**
+ * @fileoverview Express wiring for the Teams meetings ingress — the Microsoft Graph change-notification webhook.
+ *
+ * One public surface (Graph cannot present an MJ JWT — the subscription validation-token handshake + the
+ * per-notification `clientState` shared secret are the gate):
+ *   - `POST /meetings/teams/notifications` — the Graph change-notification endpoint. Handles BOTH:
+ *       1. The **subscription-validation handshake**: when Graph creates/renews a subscription it calls this
+ *          URL with `?validationToken=…` and expects the exact token echoed back as `text/plain` 200.
+ *       2. **Real call/participant notifications**: each carries a `clientState` verified (constant-time)
+ *          against the secret set on subscription creation, then mapped to the meetings service's roster /
+ *          call-ended drive helpers.
+ *
+ * Mirrors the Twilio telephony public-router pattern: mount the router BEFORE the unified auth middleware. The
+ * validation + notification parsing use the offline-complete, unit-tested helpers from the Teams provider
+ * package (`validateGraphNotification` / `parseCallNotification`); this module is thin HTTP plumbing over them
+ * and the {@link TeamsMeetingsService}.
+ *
+ * The ACS application-hosted-media socket(s) (the audio plane) are owned by the server's native ACS media
+ * adapter, which attaches transports to the shared {@link TeamsAcsMediaRegistry} — there is no media WSS here
+ * (unlike Twilio Media Streams), because ACS app-hosted media is negotiated out-of-band by that adapter.
+ *
+ * @module @memberjunction/server/telephony
+ */
+import { Router, json } from 'express';
+import { LogError, LogStatus } from '@memberjunction/core';
+import { validateGraphNotification, parseCallNotification, } from '@memberjunction/ai-bridge-teams';
+import { TeamsAcsMediaRegistry } from './teamsAcsMediaRegistry.js';
+import { TeamsMeetingsService } from './TeamsMeetingsService.js';
+/** The mount path for the Teams meetings public router. */
+export const TEAMS_MEETINGS_MOUNT_PATH = '/meetings/teams';
+/**
+ * Builds the Teams meetings handler: the public Graph change-notification router + the shared ACS media
+ * registry + the meetings service (returned for observability/tests + so server boot can bind the service to
+ * the runtime holder and hand the registry to the native ACS media adapter).
+ */
+export function createTeamsMeetingsHandler(config) {
+    const registry = new TeamsAcsMediaRegistry(config.acsSampleRate);
+    const service = new TeamsMeetingsService(config, registry);
+    const publicRouter = Router();
+    // Graph posts JSON; it also issues the validation handshake as a query-param GET-like POST. Parse JSON but
+    // tolerate an empty body on the handshake.
+    publicRouter.post('/notifications', json({ type: () => true }), (req, res) => {
+        handleGraphNotification(service, config, req, res);
+    });
+    return { publicRouter, registry, service };
+}
+/** Handles the Graph webhook: echo the validation token, else verify clientState + drive the service. */
+function handleGraphNotification(service, config, req, res) {
+    const validationToken = readValidationToken(req);
+    const batch = (req.body ?? {});
+    const notifications = Array.isArray(batch.value) ? batch.value : [];
+    const clientStates = notifications.map((n) => n.clientState);
+    const verdict = validateGraphNotification(validationToken, config.notificationClientState ?? '', clientStates);
+    if (verdict.Kind === 'validation') {
+        // The subscription-validation handshake: echo the token verbatim as text/plain 200.
+        res.status(200).type('text/plain').send(verdict.ValidationToken);
+        return;
+    }
+    if (verdict.Kind === 'reject') {
+        LogStatus(`[Meetings][Teams] notification rejected: ${verdict.Reason}`);
+        res.status(verdict.Reason === 'empty-validation-token' ? 400 : 403).type('text/plain').send('Rejected.');
+        return;
+    }
+    dispatchNotifications(service, notifications);
+    // Graph requires a fast 202 to acknowledge receipt; processing is fire-and-forget.
+    res.status(202).end();
+}
+/** Maps each Graph call/participant notification to the meetings service's roster / call-ended drive helpers. */
+function dispatchNotifications(service, notifications) {
+    for (const notification of notifications) {
+        try {
+            const normalized = parseCallNotification(notification);
+            if (normalized.state === 'terminated') {
+                service.DriveCallEnded(normalized.callId);
+            }
+            else if (normalized.participants.length > 0) {
+                service.DriveParticipantsUpdated(normalized.callId, normalized.participants);
+            }
+        }
+        catch (e) {
+            LogError(`[Meetings][Teams] failed to process notification: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+}
+/** Reads the `?validationToken=…` query param (Graph URL-encodes it), when present. */
+function readValidationToken(req) {
+    const raw = req.query?.validationToken;
+    if (typeof raw === 'string') {
+        return raw;
+    }
+    if (Array.isArray(raw) && typeof raw[0] === 'string') {
+        return raw[0];
+    }
+    return undefined;
+}
+//# sourceMappingURL=TeamsMeetingsRouter.js.map

package/dist/telephony/TeamsMeetingsRouter.js.map

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

package/dist/telephony/TeamsMeetingsService.d.ts

@@ -0,0 +1,113 @@
+/**
+ * @fileoverview Orchestrates Teams meeting bridge sessions (join-by-URL) for MJAPI.
+ *
+ * This is the composition layer between the Teams meetings ingress (the public Graph change-notification
+ * webhook + the server-owned ACS media plane) and the ONE unified realtime-agent pathway. It does NOT
+ * re-implement any bridge logic: it resolves the Teams provider + the agent identity, opens a server-side
+ * realtime session via the agent layer's `CreateBridgeRealtimeSession` factory, binds the REAL Teams binding
+ * (`RealTeamsBindings` over the Graph control plane + the per-call ACS media registry) onto the driver, and
+ * hands everything to `AIBridgeEngine.StartBridgeSession` — exactly the seam the Twilio telephony service +
+ * the LiveKit room coordinator use.
+ *
+ * Collaborators are injected (engine, session factory, session manager) so the resolution/branching logic is
+ * unit-testable with fakes; the actual Graph call placement + ACS media flow are live-only (real Teams/Azure
+ * credentials + a publicly reachable Graph webhook URL — see meeting-vendor-bindings-teams-slack.md M1).
+ *
+ * @module @memberjunction/server/telephony
+ */
+import { UserInfo, IMetadataProvider } from '@memberjunction/core';
+import { AIBridgeEngine, type StartBridgeSessionParams } from '@memberjunction/ai-bridge-server';
+import { CreateBridgeRealtimeSession } from '@memberjunction/ai-agents';
+import { type BridgeNativeSdkBinding } from '@memberjunction/ai-bridge-base';
+import { RealGraphCallsClient } from '@memberjunction/ai-bridge-teams';
+import type { TeamsMeetingsConfig } from '../config.js';
+import { SessionManager } from '../agentSessions/SessionManager.js';
+import { TeamsAcsMediaRegistry } from './teamsAcsMediaRegistry.js';
+/** Result of starting a Teams meeting bridge session. */
+export interface JoinMeetingResult {
+    /** Whether a bridge session was started for the meeting. */
+    accepted: boolean;
+    /** The Graph call id the bot joined (the bridge's external connection id), when accepted. */
+    callId?: string;
+    /** Why it was rejected (no agent identity, provider missing, unparseable join URL, etc.). */
+    reason?: string;
+}
+/** Injectable collaborators (production defaults wired in the constructor; fakes in tests). */
+export interface TeamsMeetingsServiceDeps {
+    engine?: Pick<AIBridgeEngine, 'ProviderByName' | 'ProviderByDriverClass' | 'StartBridgeSession' | 'Config'>;
+    sessionFactory?: typeof CreateBridgeRealtimeSession;
+    sessionManager?: Pick<SessionManager, 'CreateSession'>;
+    /** Constructs the Graph control-plane client for a session (default: the real lazy-SDK client). */
+    graphClientFactory?: (accessToken: string, tenantId?: string) => RealGraphCallsClient;
+}
+/**
+ * Starts Teams meeting bridge sessions. One instance per server, constructed alongside the meetings router and
+ * sharing the {@link TeamsAcsMediaRegistry} with the server's ACS media adapter.
+ */
+export declare class TeamsMeetingsService {
+    private readonly config;
+    private readonly registry;
+    private readonly engine;
+    private readonly sessionFactory;
+    private readonly sessionManager;
+    private readonly graphClientFactory;
+    /** Live Graph clients keyed by call id, so the webhook ingress can drive their roster/ended handlers. */
+    private readonly graphClientsByCall;
+    constructor(config: TeamsMeetingsConfig, registry: TeamsAcsMediaRegistry, deps?: TeamsMeetingsServiceDeps);
+    /**
+     * Joins a Teams meeting by URL for a given agent identity and starts the bridge session. The bound
+     * `RealTeamsBindings` issues the Graph `POST /communications/calls` and accepts the ACS media transport
+     * (attached by the server's media adapter) for the joined call. Returns `{ accepted:false }` (never
+     * throws) when the agent identity is missing/inactive, so the caller can answer cleanly.
+     *
+     * @param agentIdentityId The agent identity to join as (its Teams account/email is the bot's identity).
+     * @param joinUrl The Teams meeting join URL.
+     * @param contextUser The request-scoped principal.
+     * @param provider The request-scoped metadata provider (multi-provider safe — never the global Metadata).
+     */
+    JoinMeetingByUrl(agentIdentityId: string, joinUrl: string, contextUser: UserInfo, provider: IMetadataProvider): Promise<JoinMeetingResult>;
+    /**
+     * Drives the retained Graph roster handler for a call from a Graph change notification (called by the
+     * webhook ingress — Graph delivers roster changes over the webhook, not a client subscription).
+     */
+    DriveParticipantsUpdated(callId: string, participants: {
+        id: string;
+        displayName?: string;
+        role?: string;
+    }[]): void;
+    /** Drives the call-ended handler for a call from a Graph change notification, then tears the call down. */
+    DriveCallEnded(callId: string): void;
+    /**
+     * Builds the {@link StartBridgeSessionParams} for a SCHEDULED Teams join — a bridge the
+     * {@link ScheduledBridgeRunner} owns (it created the `MJ: AI Agent Sessions` row and owns the
+     * `StartBridgeSession` call). Reuses the same provider resolution, realtime-session factory, Graph
+     * client, and bind-sdk as an on-demand join, so a scheduled Teams join is identical to a live one
+     * for audio (the ACS media registry is wired via {@link buildBindSdk}).
+     *
+     * NOTE: an on-demand join also registers the live Graph client by call id for webhook-driven
+     * roster/ended routing; the runner abstracts the post-start call id away, so for a SCHEDULED join
+     * that notification routing is a documented follow-on. Audio is fully wired here.
+     */
+    BuildScheduledStartParams(args: {
+        agentID: string;
+        joinUrl: string;
+        agentSessionID: string;
+        contextUser: UserInfo;
+        provider: IMetadataProvider;
+    }): Promise<StartBridgeSessionParams>;
+    /** Resolves provider, opens the realtime session, binds the real Teams SDK, and starts the bridge. */
+    private startBridge;
+    /** Resolves the seeded Teams provider row (by driver class, falling back to display name). */
+    private resolveProvider;
+    /**
+     * Builds the per-session SDK binding that wires the REAL Teams binding (`RealTeamsBindings` over the Graph
+     * control plane + the per-call ACS media registry) onto the Teams driver — overriding the package's default
+     * native loader. This is where the offline-complete seams meet the live Graph + ACS plumbing.
+     */
+    buildBindSdk(graphClient: RealGraphCallsClient): BridgeNativeSdkBinding;
+    /** Assembles the per-session bridge configuration (carries the resolved tenant for diagnostics). */
+    private buildSessionConfiguration;
+    /** Loads a specific agent identity by id (used by join-by-URL), requiring it be active. */
+    private loadAgentIdentity;
+}
+//# sourceMappingURL=TeamsMeetingsService.d.ts.map

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

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