@memberjunction/ai-bridge-teams 0.0.1 → 5.42.0

package/dist/teams-sdk.d.ts

@@ -0,0 +1,173 @@
+/**
+ * The injectable **Microsoft Teams calling-bot SDK seam** — the minimal set of operations
+ * {@link import('./teams-bridge.js').TeamsBridge} needs from Teams, declared as an interface so the driver
+ * builds and unit-tests against an in-memory fake with **no network and no real Teams / Azure
+ * Communication Services SDK**.
+ *
+ * ## Production binding (TODO at deployment)
+ * In production this interface is bound to the **Azure Communication Services (ACS) calling-bot** SDK
+ * plus the **Microsoft Graph cloud-communications API** (the `/communications/calls` "application-hosted
+ * media" bot model) so the bot can join a Teams meeting, pull per-participant PCM audio for diarization,
+ * push synthesized audio back, observe roster + raised-hand events, and post to the Teams meeting chat.
+ * The named operations map to the SDK as follows:
+ * - {@link join} / {@link leave} → the Graph `POST /communications/calls` (join meeting via the join
+ *   URL / meeting coordinates) and the call's `DELETE` (leave) lifecycle.
+ * - {@link sendAudioFrame} → the ACS application-hosted-media outbound audio-socket (the bot's voice in).
+ * - {@link onAudioFrame} → the ACS per-participant inbound audio-socket callback (the source of speaker
+ *   labels for diarization — Teams provides participant attribution on the media stream).
+ * - {@link onParticipantJoin} / {@link onParticipantLeave} / {@link getParticipants} → the call's
+ *   `participants` collection + the `participantsUpdated` change notifications.
+ * - {@link onHandRaise} → the meeting's raised-hand signal. ⚠️ Partial: Teams surfaces raised hands in
+ *   the meeting UI, but a clean per-participant *event* over the calling-bot API is not guaranteed on
+ *   every tenant/build; the adapter wires it where the platform exposes it and otherwise no-ops.
+ * - {@link postChatMessage} → the Graph `POST /chats/{id}/messages` against the meeting's chat thread.
+ * - {@link muteParticipant} → the call's `participant:mute` action (requires the bot be an organizer /
+ *   presenter with the relevant policy).
+ * - {@link onMeetingEnded} → the call's `callEnded` / `terminated` status notification.
+ *
+ * Binding the real SDK is a thin adapter that implements this interface; the driver and its tests do
+ * not change. **None of the ACS/Graph SDK types leak into this package.**
+ *
+ * See `/plans/realtime/realtime-bridges-architecture.md` §3, §8 (Microsoft Teams row) and
+ * `/guides/REALTIME_BRIDGES_GUIDE.md`.
+ */
+/** The role a Teams participant holds in the meeting, normalized to the bridge's participant roles. */
+export type TeamsParticipantRole = 'Organizer' | 'Presenter' | 'Attendee';
+/**
+ * One Teams meeting participant as the seam reports it. Platform-native and minimal — the driver maps
+ * this onto `BridgeParticipantInfo` / `BridgeMeetingParticipant`.
+ */
+export interface TeamsParticipant {
+    /** The Teams participant id (the call's participant identity / `id`, stable for their presence). */
+    ParticipantId: string;
+    /** The participant's display name as Teams reports it. */
+    DisplayName?: string;
+    /** The participant's meeting role. */
+    Role: TeamsParticipantRole;
+    /** Whether this participant is the bridge's own bot (so the driver can exclude it from diarization addressing). */
+    IsSelf?: boolean;
+}
+/** One frame of raw per-participant audio the seam surfaces for diarization + the agent's "hearing". */
+export interface TeamsAudioFrame {
+    /** Raw PCM audio bytes for this frame. */
+    Pcm: ArrayBuffer;
+    /** The Teams participant id this audio came from (the diarization speaker label). */
+    ParticipantId: string;
+    /** The participant's display name at capture time, when known. */
+    DisplayName?: string;
+    /** Optional epoch-ms capture timestamp. */
+    TimestampMs?: number;
+}
+/** Arguments to {@link ITeamsMeetingSdk.join} — what the bot needs to get into a Teams meeting. */
+export interface TeamsJoinArgs {
+    /** The Teams meeting join URL (the `https://teams.microsoft.com/l/meetup-join/...` link). */
+    JoinUrl: string;
+    /**
+     * The parsed meeting thread id (the chat/conversation id behind the join URL), when resolved
+     * upstream. Used for posting to the meeting chat and as a stable meeting coordinate.
+     */
+    ThreadId?: string;
+    /** The display name the bot appears as in the participant list. */
+    BotDisplayName: string;
+    /**
+     * The OAuth bearer / application token authorizing the bot's Graph + ACS calls. Resolved upstream
+     * via MJ's credential system; never inline secrets.
+     */
+    AccessToken?: string;
+    /** The Azure tenant id the meeting belongs to, when joining cross-tenant. */
+    TenantId?: string;
+}
+/** The handles the seam returns after a successful {@link ITeamsMeetingSdk.join}. */
+export interface TeamsJoinResult {
+    /** The bot's own participant id in the joined meeting. */
+    BotParticipantId: string;
+    /** The Teams call id the bot joined (the durable external connection id). */
+    CallId: string;
+}
+/**
+ * The minimal Microsoft Teams calling-bot SDK surface the {@link import('./teams-bridge.js').TeamsBridge}
+ * depends on. Production binds this to the real ACS calling-bot / Graph cloud-communications API; tests
+ * inject a `FakeTeamsSdk`.
+ */
+export interface ITeamsMeetingSdk {
+    /**
+     * Joins the Teams meeting and brings the bot online. Returns the bot's participant id + the call id.
+     *
+     * @param args Join parameters (join URL, thread id, bot name, auth).
+     * @returns The bot participant + call handles.
+     */
+    join(args: TeamsJoinArgs): Promise<TeamsJoinResult>;
+    /** Leaves the meeting (terminates the bot's call leg) and releases SDK resources. */
+    leave(): Promise<void>;
+    /**
+     * Sends one raw PCM audio frame as the bot's outbound audio (the agent's voice into the meeting),
+     * over the ACS application-hosted-media outbound audio socket.
+     *
+     * @param pcm The PCM audio bytes to send.
+     */
+    sendAudioFrame(pcm: ArrayBuffer): void;
+    /**
+     * Registers a callback for inbound raw per-participant audio frames (what the agent hears, carrying
+     * the speaker label for diarization). "Latest handler wins."
+     *
+     * @param cb Invoked with each inbound audio frame.
+     */
+    onAudioFrame(cb: (frame: TeamsAudioFrame) => void): void;
+    /**
+     * Registers a callback fired when a participant joins. "Latest handler wins."
+     *
+     * @param cb Invoked with the participant who joined.
+     */
+    onParticipantJoin(cb: (participant: TeamsParticipant) => void): void;
+    /**
+     * Registers a callback fired when a participant leaves. "Latest handler wins."
+     *
+     * @param cb Invoked with the participant id that left.
+     */
+    onParticipantLeave(cb: (participantId: string) => void): void;
+    /**
+     * Registers a callback for native raised-hand signals. "Latest handler wins."
+     *
+     * ⚠️ Teams raised-hand is partial over the calling-bot API: a clean per-participant event is not
+     * guaranteed on every tenant/build. The adapter wires this where the platform exposes it and the
+     * driver tolerates the signal never firing.
+     *
+     * @param cb Invoked with the participant id and whether the hand is now raised.
+     */
+    onHandRaise(cb: (participantId: string, raised: boolean) => void): void;
+    /**
+     * Returns the current participant roster (including the bot).
+     *
+     * @returns The current participants.
+     */
+    getParticipants(): Promise<TeamsParticipant[]>;
+    /**
+     * Posts a message to the Teams meeting chat thread (everyone).
+     *
+     * @param text The chat message text.
+     */
+    postChatMessage(text: string): Promise<void>;
+    /**
+     * Mutes a participant (requires the bot be an organizer/presenter with the relevant policy).
+     *
+     * @param participantId The participant to mute.
+     */
+    muteParticipant(participantId: string): Promise<void>;
+    /**
+     * Registers a callback fired when the meeting/call ends (organizer ended / call terminated).
+     * "Latest handler wins."
+     *
+     * @param cb Invoked when the meeting has ended.
+     */
+    onMeetingEnded(cb: () => void): void;
+}
+/**
+ * A factory that constructs an {@link ITeamsMeetingSdk} for a session — the creation seam (mirroring
+ * Gemini's `connectLiveSession`). Production supplies a factory that builds the real ACS calling-bot /
+ * Graph adapter from resolved config; tests supply one that returns a `FakeTeamsSdk`.
+ *
+ * @param config The resolved provider/session configuration (tenant, credential refs already resolved upstream).
+ * @returns The Teams SDK instance to drive the meeting with.
+ */
+export type TeamsMeetingSdkFactory = (config?: Record<string, unknown>) => ITeamsMeetingSdk;
+//# sourceMappingURL=teams-sdk.d.ts.map

package/dist/teams-sdk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"teams-sdk.d.ts","sourceRoot":"","sources":["../src/teams-sdk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,uGAAuG;AACvG,MAAM,MAAM,oBAAoB,GAAG,WAAW,GAAG,WAAW,GAAG,UAAU,CAAC;AAE1E;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC7B,oGAAoG;IACpG,aAAa,EAAE,MAAM,CAAC;IACtB,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sCAAsC;IACtC,IAAI,EAAE,oBAAoB,CAAC;IAC3B,mHAAmH;IACnH,MAAM,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,wGAAwG;AACxG,MAAM,WAAW,eAAe;IAC5B,0CAA0C;IAC1C,GAAG,EAAE,WAAW,CAAC;IACjB,qFAAqF;IACrF,aAAa,EAAE,MAAM,CAAC;IACtB,kEAAkE;IAClE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2CAA2C;IAC3C,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,mGAAmG;AACnG,MAAM,WAAW,aAAa;IAC1B,6FAA6F;IAC7F,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,cAAc,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,qFAAqF;AACrF,MAAM,WAAW,eAAe;IAC5B,0DAA0D;IAC1D,gBAAgB,EAAE,MAAM,CAAC;IACzB,6EAA6E;IAC7E,MAAM,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC7B;;;;;OAKG;IACH,IAAI,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAEpD,qFAAqF;IACrF,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvB;;;;;OAKG;IACH,cAAc,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI,CAAC;IAEvC;;;;;OAKG;IACH,YAAY,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,GAAG,IAAI,CAAC;IAEzD;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,EAAE,CAAC,WAAW,EAAE,gBAAgB,KAAK,IAAI,GAAG,IAAI,CAAC;IAErE;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAAC;IAE9D;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,EAAE,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI,CAAC;IAExE;;;;OAIG;IACH,eAAe,IAAI,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAAC;IAE/C;;;;OAIG;IACH,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE7C;;;;OAIG;IACH,eAAe,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEtD;;;;;OAKG;IACH,cAAc,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;CACxC;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,sBAAsB,GAAG,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,gBAAgB,CAAC"}

package/dist/teams-sdk.js

@@ -0,0 +1,35 @@
+/**
+ * The injectable **Microsoft Teams calling-bot SDK seam** — the minimal set of operations
+ * {@link import('./teams-bridge.js').TeamsBridge} needs from Teams, declared as an interface so the driver
+ * builds and unit-tests against an in-memory fake with **no network and no real Teams / Azure
+ * Communication Services SDK**.
+ *
+ * ## Production binding (TODO at deployment)
+ * In production this interface is bound to the **Azure Communication Services (ACS) calling-bot** SDK
+ * plus the **Microsoft Graph cloud-communications API** (the `/communications/calls` "application-hosted
+ * media" bot model) so the bot can join a Teams meeting, pull per-participant PCM audio for diarization,
+ * push synthesized audio back, observe roster + raised-hand events, and post to the Teams meeting chat.
+ * The named operations map to the SDK as follows:
+ * - {@link join} / {@link leave} → the Graph `POST /communications/calls` (join meeting via the join
+ *   URL / meeting coordinates) and the call's `DELETE` (leave) lifecycle.
+ * - {@link sendAudioFrame} → the ACS application-hosted-media outbound audio-socket (the bot's voice in).
+ * - {@link onAudioFrame} → the ACS per-participant inbound audio-socket callback (the source of speaker
+ *   labels for diarization — Teams provides participant attribution on the media stream).
+ * - {@link onParticipantJoin} / {@link onParticipantLeave} / {@link getParticipants} → the call's
+ *   `participants` collection + the `participantsUpdated` change notifications.
+ * - {@link onHandRaise} → the meeting's raised-hand signal. ⚠️ Partial: Teams surfaces raised hands in
+ *   the meeting UI, but a clean per-participant *event* over the calling-bot API is not guaranteed on
+ *   every tenant/build; the adapter wires it where the platform exposes it and otherwise no-ops.
+ * - {@link postChatMessage} → the Graph `POST /chats/{id}/messages` against the meeting's chat thread.
+ * - {@link muteParticipant} → the call's `participant:mute` action (requires the bot be an organizer /
+ *   presenter with the relevant policy).
+ * - {@link onMeetingEnded} → the call's `callEnded` / `terminated` status notification.
+ *
+ * Binding the real SDK is a thin adapter that implements this interface; the driver and its tests do
+ * not change. **None of the ACS/Graph SDK types leak into this package.**
+ *
+ * See `/plans/realtime/realtime-bridges-architecture.md` §3, §8 (Microsoft Teams row) and
+ * `/guides/REALTIME_BRIDGES_GUIDE.md`.
+ */
+export {};
+//# sourceMappingURL=teams-sdk.js.map

package/dist/teams-sdk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"teams-sdk.js","sourceRoot":"","sources":["../src/teams-sdk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG"}

package/package.json

@@ -1,10 +1,35 @@
 {
   "name": "@memberjunction/ai-bridge-teams",
-  "version": "0.0.1",
-  "description": "OIDC trusted publishing setup package for @memberjunction/ai-bridge-teams",
-  "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
+  "type": "module",
+  "version": "5.42.0",
+  "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",
+  "files": [
+    "/dist"
+  ],
+  "scripts": {
+    "start": "ts-node-dev src/index.ts",
+    "build": "tsc && tsc-alias -f",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "author": "MemberJunction.com",
+  "license": "ISC",
+  "dependencies": {
+    "@memberjunction/core": "5.42.0",
+    "@memberjunction/global": "5.42.0",
+    "@memberjunction/core-entities": "5.42.0",
+    "@memberjunction/ai-bridge-base": "5.42.0"
+  },
+  "devDependencies": {
+    "@types/node": "24.10.11",
+    "ts-node-dev": "^2.0.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MemberJunction/MJ"
+  }
 }