@memberjunction/ai-bridge-teams 5.44.0 → 5.45.1

package/dist/teams-ingress.js

@@ -0,0 +1,124 @@
+/**
+ * @fileoverview Microsoft Graph change-notification **ingress** pure helpers — the validation-token
+ * handshake, the `clientState` shared-secret check, and the call/participant notification → normalized
+ * state mapper, plus a `buildJoinByUrlRequest` convenience. These are the framework-free pieces of the
+ * MJAPI Teams ingress: no Express, no network, no DB, so they unit-test directly and the MJAPI router can
+ * call them verbatim once the live wiring lands.
+ *
+ * The remaining **live** ingress — the `POST /meetings/teams/notifications` endpoint, the
+ * `Meeting.JoinByUrl(agentIdentityId, joinUrl)` mutation, and the Azure AD app registration (Graph
+ * cloud-communications + chat permissions with tenant admin consent) — is documented in
+ * `plans/realtime/bridges-and-widget/spikes/M1-teams-binding-notes.md` and is gated on real Teams/Azure
+ * credentials + a publicly reachable Graph webhook URL.
+ *
+ * @module @memberjunction/ai-bridge-teams
+ * @author MemberJunction.com
+ * @see `/plans/realtime/bridges-and-widget/meeting-vendor-bindings-teams-slack.md` §2 (M1 B/C).
+ */
+import { timingSafeEqual } from 'node:crypto';
+import { buildGraphCreateCallRequest } from './real-teams-bindings.js';
+/**
+ * Performs the Graph change-notification gate, pure + exported so the MJAPI router calls it on every
+ * `POST /meetings/teams/notifications` request (these can't carry an MJ JWT — the handshake + `clientState`
+ * shared secret are the gate):
+ *
+ * 1. If the request carries a `validationToken` query param, it's the subscription-validation handshake →
+ *    return `{ Kind: 'validation', ValidationToken }` (the router echoes it back as `text/plain` 200). A
+ *    blank token rejects.
+ * 2. Otherwise it's a real notification. Every notification in the batch carries a `clientState`; verify
+ *    each (constant-time) against the secret we set when creating the subscription. Any mismatch rejects the
+ *    whole batch (an attacker who can't produce the secret must not drive bot behavior).
+ *
+ * @param validationToken The `?validationToken=…` query param value, when present (the handshake).
+ * @param expectedClientState The shared secret set on subscription creation (resolved upstream — never inlined).
+ * @param notificationClientStates The `clientState` of each notification in the POST body (empty for handshake).
+ * @returns The discriminated validation result.
+ */
+export function validateGraphNotification(validationToken, expectedClientState, notificationClientStates) {
+    if (validationToken !== undefined) {
+        return validationToken.length > 0
+            ? { Kind: 'validation', ValidationToken: validationToken }
+            : { Kind: 'reject', Reason: 'empty-validation-token' };
+    }
+    for (const state of notificationClientStates) {
+        if (!constantTimeEquals(state ?? '', expectedClientState)) {
+            return { Kind: 'reject', Reason: 'client-state-mismatch' };
+        }
+    }
+    return { Kind: 'notification' };
+}
+/**
+ * **Pure** mapping of a Graph call/participant change notification to a {@link NormalizedCallNotification}
+ * (`{ callId, state, participants }`). Resolves the call id from `resourceData.id` or the `resource` path,
+ * normalizes the lifecycle state, and passes the participants snapshot through unchanged. Exported so the
+ * MJAPI router maps each notification → engine session lifecycle without re-parsing Graph's resource shapes.
+ *
+ * @param notification One Graph change-notification item.
+ * @returns The normalized call notification.
+ * @throws When no call id can be resolved (a notification with no identifiable call is unactionable).
+ */
+export function parseCallNotification(notification) {
+    const callId = notification.resourceData?.id ?? extractCallIdFromResource(notification.resource);
+    if (!callId) {
+        throw new Error('parseCallNotification: could not resolve a call id from the Graph notification ' +
+            `(resourceData.id and resource path both absent). resource='${notification.resource ?? ''}'.`);
+    }
+    return {
+        callId,
+        state: normalizeCallState(notification.resourceData?.state),
+        participants: notification.resourceData?.participants ?? [],
+    };
+}
+/**
+ * Builds the Graph `POST /communications/calls` request body for an on-demand **join-by-URL** trigger, the
+ * payload the live `Meeting.JoinByUrl(agentIdentityId, joinUrl)` mutation hands the engine. Thin wrapper over
+ * {@link buildGraphCreateCallRequest} that constructs the minimal {@link TeamsJoinArgs} from a join URL + bot
+ * name; pure so the router and tests share one request shape.
+ *
+ * @param joinUrl The Teams meeting join URL to join.
+ * @param botDisplayName The bot's display name in the participant list (defaults to `'AI Agent'`).
+ * @param tenantId The Azure tenant id, when joining cross-tenant.
+ * @returns The Graph create-call request body.
+ * @throws When the join URL carries no resolvable meeting thread id.
+ */
+export function buildJoinByUrlRequest(joinUrl, botDisplayName = 'AI Agent', tenantId) {
+    const args = {
+        JoinUrl: joinUrl,
+        BotDisplayName: botDisplayName,
+        ...(tenantId ? { TenantId: tenantId } : {}),
+    };
+    return buildGraphCreateCallRequest(args);
+}
+/** Maps a free-form Graph call-state string onto the {@link NormalizedCallState} union. */
+function normalizeCallState(state) {
+    switch ((state ?? '').trim().toLowerCase()) {
+        case 'establishing':
+            return 'establishing';
+        case 'established':
+            return 'established';
+        case 'terminating':
+            return 'terminating';
+        case 'terminated':
+            return 'terminated';
+        default:
+            return 'unknown';
+    }
+}
+/** Extracts the `{id}` from a `communications/calls/{id}[/...]` Graph resource path, or `undefined`. */
+function extractCallIdFromResource(resource) {
+    if (!resource) {
+        return undefined;
+    }
+    const match = resource.match(/communications\/calls\/([^/?#]+)/i);
+    return match ? match[1] : undefined;
+}
+/** Constant-time string compare, length-safe (mismatched lengths return false) — for `clientState`. */
+function constantTimeEquals(a, b) {
+    const bufA = new Uint8Array(Buffer.from(a, 'utf8'));
+    const bufB = new Uint8Array(Buffer.from(b, 'utf8'));
+    if (bufA.length !== bufB.length) {
+        return false;
+    }
+    return timingSafeEqual(bufA, bufB);
+}
+//# sourceMappingURL=teams-ingress.js.map

package/dist/teams-ingress.js.map

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@memberjunction/ai-bridge-teams",
   "type": "module",
-  "version": "5.44.0",
+  "version": "5.45.1",
   "description": "MemberJunction: Microsoft Teams Realtime Bridge driver. Connects the realtime agent engine to a Teams meeting (audio in/out, diarized roster, participant mute, Teams meeting chat) via an injectable Teams calling-bot SDK seam (Azure Communication Services / Microsoft Graph cloud-communications), and contributes a Meeting Controls facilitator channel.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -17,10 +17,15 @@
   "author": "MemberJunction.com",
   "license": "ISC",
   "dependencies": {
-    "@memberjunction/core": "5.44.0",
-    "@memberjunction/global": "5.44.0",
-    "@memberjunction/core-entities": "5.44.0",
-    "@memberjunction/ai-bridge-base": "5.44.0"
+    "@memberjunction/core": "5.45.1",
+    "@memberjunction/global": "5.45.1",
+    "@memberjunction/core-entities": "5.45.1",
+    "@memberjunction/ai-bridge-base": "5.45.1"
+  },
+  "//optionalDependencies": "@microsoft/microsoft-graph-client and @azure/communication-call-automation are OPTIONAL PEER SDKs (CLAUDE rule 8, category 2): the package never statically imports either. @microsoft/microsoft-graph-client is the Graph cloud-communications CONTROL plane — production wires RealTeamsBindings.IGraphCallsLike over Client.api('/communications/calls').post(...) for join/roster/chat/mute/hangup. @azure/communication-call-automation is the ACS application-hosted-media AUDIO plane — production wires RealTeamsBindings.IAcsMediaLike (inbound per-participant + outbound PCM sockets) over it. Both are injected behind structural surfaces so the package builds and unit-tests with no install and no network, and are loaded only when the Teams provider is configured at deployment.",
+  "optionalDependencies": {
+    "@microsoft/microsoft-graph-client": "^3.0.7",
+    "@azure/communication-call-automation": "^1.3.0"
   },
   "devDependencies": {
     "@types/node": "24.10.11",