@memberjunction/ai-bridge-webex 0.0.1 → 5.42.0

package/dist/webex-sdk.d.ts

@@ -0,0 +1,174 @@
+/**
+ * The injectable **Cisco Webex Meetings SDK seam** — the minimal set of operations
+ * {@link import('./webex-bridge.js').WebexBridge} needs from Webex, declared as an interface so the driver
+ * builds and unit-tests against an in-memory fake with **no network and no real Cisco Webex Meetings SDK
+ * / xAPI / Webex bot framework**.
+ *
+ * ## Production binding (TODO at deployment)
+ * In production this interface is bound to the **Cisco Webex Meetings SDK** (the embedded-app / Web /
+ * mobile Meetings SDK that joins a meeting and exposes media + roster) together with the **Webex bot
+ * framework** (Webex Messaging API, for posting to the meeting/space) and, where a Webex room device is
+ * involved, the **xAPI** (the device control surface for participant actions). The named operations map
+ * to the SDK as follows:
+ * - {@link join} / {@link leave} → the Webex Meetings SDK `Meeting.join()` / `Meeting.leave()` lifecycle
+ *   (the bot/app joins via the meeting link, SIP address, or meeting number).
+ * - {@link sendAudioFrame} → the Meetings SDK outbound audio media track (the bot's voice into the meeting).
+ * - {@link onAudioFrame} → the Meetings SDK per-participant inbound audio media callback (the source of
+ *   speaker labels for diarization — Webex attributes media to a `Member`).
+ * - {@link onParticipantJoin} / {@link onParticipantLeave} / {@link getParticipants} → the meeting's
+ *   `members` collection + the `members:update` change events.
+ * - {@link onHandRaise} → the Webex raised-hand reaction. ⚠️ Partial: Webex surfaces raised hands in the
+ *   meeting UI, but a clean per-participant *event* over the Meetings SDK is not guaranteed on every
+ *   client/build; the adapter wires it where the platform exposes it and otherwise no-ops.
+ * - {@link postChatMessage} → the Webex Messaging API `POST /messages` against the meeting's associated
+ *   space (the in-meeting chat thread).
+ * - {@link muteParticipant} → the meeting's `Member.mute` action / device xAPI mute (requires the bot be
+ *   a host / cohost with the relevant privilege).
+ * - {@link onMeetingEnded} → the meeting's `meeting:ended` / `state` → `ENDED` notification.
+ *
+ * Binding the real SDK is a thin adapter that implements this interface; the driver and its tests do
+ * not change. **None of the Webex SDK types leak into this package.**
+ *
+ * See `/plans/realtime/realtime-bridges-architecture.md` §3, §8 (Cisco Webex row) and
+ * `/guides/REALTIME_BRIDGES_GUIDE.md`.
+ */
+/** The role a Webex member holds in the meeting, normalized to the bridge's participant roles. */
+export type WebexParticipantRole = 'Host' | 'Cohost' | 'Attendee';
+/**
+ * One Webex meeting member as the seam reports it. Platform-native and minimal — the driver maps
+ * this onto `BridgeParticipantInfo` / `BridgeMeetingParticipant`.
+ */
+export interface WebexParticipant {
+    /** The Webex member id (the meeting `Member.id`, stable for their presence). */
+    ParticipantId: string;
+    /** The member's display name as Webex reports it. */
+    DisplayName?: string;
+    /** The member's meeting role. */
+    Role: WebexParticipantRole;
+    /** Whether this member 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 WebexAudioFrame {
+    /** Raw PCM audio bytes for this frame. */
+    Pcm: ArrayBuffer;
+    /** The Webex member id this audio came from (the diarization speaker label). */
+    ParticipantId: string;
+    /** The member's display name at capture time, when known. */
+    DisplayName?: string;
+    /** Optional epoch-ms capture timestamp. */
+    TimestampMs?: number;
+}
+/** Arguments to {@link IWebexMeetingSdk.join} — what the bot needs to get into a Webex meeting. */
+export interface WebexJoinArgs {
+    /** The Webex meeting link (the `https://*.webex.com/meet/...` / `.../join/...` URL). */
+    MeetingLink: string;
+    /**
+     * The parsed Webex meeting number / SIP address (the durable meeting coordinate behind the link),
+     * when resolved upstream. Used as a stable meeting identifier when the link is opaque.
+     */
+    MeetingNumber?: string;
+    /** The display name the bot appears as in the participant list. */
+    BotDisplayName: string;
+    /**
+     * The OAuth bearer / bot access token authorizing the bot's Webex Meetings + Messaging calls.
+     * Resolved upstream via MJ's credential system; never inline secrets.
+     */
+    AccessToken?: string;
+    /** The Webex site (org) the meeting belongs to, when joining cross-site. */
+    SiteUrl?: string;
+}
+/** The handles the seam returns after a successful {@link IWebexMeetingSdk.join}. */
+export interface WebexJoinResult {
+    /** The bot's own member id in the joined meeting. */
+    BotParticipantId: string;
+    /** The Webex meeting id the bot joined (the durable external connection id). */
+    MeetingId: string;
+}
+/**
+ * The minimal Cisco Webex Meetings SDK surface the {@link import('./webex-bridge.js').WebexBridge}
+ * depends on. Production binds this to the real Webex Meetings SDK / Webex bot framework; tests
+ * inject a `FakeWebexSdk`.
+ */
+export interface IWebexMeetingSdk {
+    /**
+     * Joins the Webex meeting and brings the bot online. Returns the bot's member id + the meeting id.
+     *
+     * @param args Join parameters (meeting link, meeting number, bot name, auth).
+     * @returns The bot member + meeting handles.
+     */
+    join(args: WebexJoinArgs): Promise<WebexJoinResult>;
+    /** Leaves the meeting (the bot's `Meeting.leave()`) 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 Webex Meetings SDK outbound audio media track.
+     *
+     * @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: WebexAudioFrame) => void): void;
+    /**
+     * Registers a callback fired when a member joins. "Latest handler wins."
+     *
+     * @param cb Invoked with the member who joined.
+     */
+    onParticipantJoin(cb: (participant: WebexParticipant) => void): void;
+    /**
+     * Registers a callback fired when a member leaves. "Latest handler wins."
+     *
+     * @param cb Invoked with the member id that left.
+     */
+    onParticipantLeave(cb: (participantId: string) => void): void;
+    /**
+     * Registers a callback for native raised-hand signals. "Latest handler wins."
+     *
+     * ⚠️ Webex raised-hand is partial over the Meetings SDK: a clean per-participant event is not
+     * guaranteed on every client/build. The adapter wires this where the platform exposes it and the
+     * driver tolerates the signal never firing.
+     *
+     * @param cb Invoked with the member id and whether the hand is now raised.
+     */
+    onHandRaise(cb: (participantId: string, raised: boolean) => void): void;
+    /**
+     * Returns the current member roster (including the bot).
+     *
+     * @returns The current members.
+     */
+    getParticipants(): Promise<WebexParticipant[]>;
+    /**
+     * Posts a message to the Webex meeting space chat (everyone).
+     *
+     * @param text The chat message text.
+     */
+    postChatMessage(text: string): Promise<void>;
+    /**
+     * Mutes a member (requires the bot be a host/cohost with the relevant privilege).
+     *
+     * @param participantId The member to mute.
+     */
+    muteParticipant(participantId: string): Promise<void>;
+    /**
+     * Registers a callback fired when the meeting ends (host ended / meeting state → ENDED).
+     * "Latest handler wins."
+     *
+     * @param cb Invoked when the meeting has ended.
+     */
+    onMeetingEnded(cb: () => void): void;
+}
+/**
+ * A factory that constructs an {@link IWebexMeetingSdk} for a session — the creation seam (mirroring
+ * Gemini's `connectLiveSession`). Production supplies a factory that builds the real Webex Meetings SDK /
+ * Webex bot adapter from resolved config; tests supply one that returns a `FakeWebexSdk`.
+ *
+ * @param config The resolved provider/session configuration (site, credential refs already resolved upstream).
+ * @returns The Webex SDK instance to drive the meeting with.
+ */
+export type WebexMeetingSdkFactory = (config?: Record<string, unknown>) => IWebexMeetingSdk;
+//# sourceMappingURL=webex-sdk.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"webex-sdk.d.ts","sourceRoot":"","sources":["../src/webex-sdk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,kGAAkG;AAClG,MAAM,MAAM,oBAAoB,GAAG,MAAM,GAAG,QAAQ,GAAG,UAAU,CAAC;AAElE;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC7B,gFAAgF;IAChF,aAAa,EAAE,MAAM,CAAC;IACtB,qDAAqD;IACrD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iCAAiC;IACjC,IAAI,EAAE,oBAAoB,CAAC;IAC3B,8GAA8G;IAC9G,MAAM,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,wGAAwG;AACxG,MAAM,WAAW,eAAe;IAC5B,0CAA0C;IAC1C,GAAG,EAAE,WAAW,CAAC;IACjB,gFAAgF;IAChF,aAAa,EAAE,MAAM,CAAC;IACtB,6DAA6D;IAC7D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2CAA2C;IAC3C,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,mGAAmG;AACnG,MAAM,WAAW,aAAa;IAC1B,wFAAwF;IACxF,WAAW,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,mEAAmE;IACnE,cAAc,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,qFAAqF;AACrF,MAAM,WAAW,eAAe;IAC5B,qDAAqD;IACrD,gBAAgB,EAAE,MAAM,CAAC;IACzB,gFAAgF;IAChF,SAAS,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC7B;;;;;OAKG;IACH,IAAI,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAEpD,mFAAmF;IACnF,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/webex-sdk.js

@@ -0,0 +1,36 @@
+/**
+ * The injectable **Cisco Webex Meetings SDK seam** — the minimal set of operations
+ * {@link import('./webex-bridge.js').WebexBridge} needs from Webex, declared as an interface so the driver
+ * builds and unit-tests against an in-memory fake with **no network and no real Cisco Webex Meetings SDK
+ * / xAPI / Webex bot framework**.
+ *
+ * ## Production binding (TODO at deployment)
+ * In production this interface is bound to the **Cisco Webex Meetings SDK** (the embedded-app / Web /
+ * mobile Meetings SDK that joins a meeting and exposes media + roster) together with the **Webex bot
+ * framework** (Webex Messaging API, for posting to the meeting/space) and, where a Webex room device is
+ * involved, the **xAPI** (the device control surface for participant actions). The named operations map
+ * to the SDK as follows:
+ * - {@link join} / {@link leave} → the Webex Meetings SDK `Meeting.join()` / `Meeting.leave()` lifecycle
+ *   (the bot/app joins via the meeting link, SIP address, or meeting number).
+ * - {@link sendAudioFrame} → the Meetings SDK outbound audio media track (the bot's voice into the meeting).
+ * - {@link onAudioFrame} → the Meetings SDK per-participant inbound audio media callback (the source of
+ *   speaker labels for diarization — Webex attributes media to a `Member`).
+ * - {@link onParticipantJoin} / {@link onParticipantLeave} / {@link getParticipants} → the meeting's
+ *   `members` collection + the `members:update` change events.
+ * - {@link onHandRaise} → the Webex raised-hand reaction. ⚠️ Partial: Webex surfaces raised hands in the
+ *   meeting UI, but a clean per-participant *event* over the Meetings SDK is not guaranteed on every
+ *   client/build; the adapter wires it where the platform exposes it and otherwise no-ops.
+ * - {@link postChatMessage} → the Webex Messaging API `POST /messages` against the meeting's associated
+ *   space (the in-meeting chat thread).
+ * - {@link muteParticipant} → the meeting's `Member.mute` action / device xAPI mute (requires the bot be
+ *   a host / cohost with the relevant privilege).
+ * - {@link onMeetingEnded} → the meeting's `meeting:ended` / `state` → `ENDED` notification.
+ *
+ * Binding the real SDK is a thin adapter that implements this interface; the driver and its tests do
+ * not change. **None of the Webex SDK types leak into this package.**
+ *
+ * See `/plans/realtime/realtime-bridges-architecture.md` §3, §8 (Cisco Webex row) and
+ * `/guides/REALTIME_BRIDGES_GUIDE.md`.
+ */
+export {};
+//# sourceMappingURL=webex-sdk.js.map

package/dist/webex-sdk.js.map

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

package/package.json

@@ -1,10 +1,35 @@
 {
   "name": "@memberjunction/ai-bridge-webex",
-  "version": "0.0.1",
-  "description": "OIDC trusted publishing setup package for @memberjunction/ai-bridge-webex",
-  "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
+  "type": "module",
+  "version": "5.42.0",
+  "description": "MemberJunction: Cisco Webex Realtime Bridge driver. Connects the realtime agent engine to a Webex meeting (audio in/out, diarized roster, participant mute, Webex meeting chat) via an injectable Cisco Webex Meetings SDK seam (Webex Meetings SDK / xAPI / Webex bot framework), 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"
+  }
 }