@memberjunction/realtime-widget 0.0.0 → 5.45.0

package/README.md

@@ -1,45 +1,109 @@
 # @memberjunction/realtime-widget
 
-## ⚠️ IMPORTANT NOTICE ⚠️
-
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
-
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
-
-## Purpose
-
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@memberjunction/realtime-widget`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
-
-## What is OIDC Trusted Publishing?
-
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
-
-## Setup Instructions
-
-To properly configure OIDC trusted publishing for this package:
-
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
-
-## DO NOT USE THIS PACKAGE
-
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
-
-## More Information
-
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
-
----
-
-**Maintained for OIDC setup purposes only**
+A **droppable, embeddable public customer-support widget** (text today; voice in W4) for any
+third-party website. A single `<script>` tag plus one mount element opens a support
+conversation with a **pinned MJ agent** — **no MJ login required** — by minting a short-lived
+**anonymous guest session** and reusing MemberJunction's unified agent pathway
+(`ConversationsRuntime` + the GraphQL data provider). It does **not** reimplement chat or agent
+dispatch.
+
+Part of the [Agent Bridges & Public Widget program](../../../plans/realtime/bridges-and-widget/README.md)
+(phases **W3+**). See [`public-web-widget.md`](../../../plans/realtime/bridges-and-widget/public-web-widget.md).
+
+## Embedding (the entire integration)
+
+```html
+<div
+  data-widget-key="pk_live_xxx"
+  data-api-url="https://api.yourco.com"
+  data-title="Acme Support"
+  data-greeting="Hi! How can we help?"
+></div>
+<script type="module" src="https://cdn.yourco.com/mj-widget.js"></script>
+```
+
+The loader reads the `data-*` attributes, calls `POST /widget/session` to mint a guest JWT, and
+mounts `<mj-support-widget>` **inside a shadow DOM** so host CSS cannot bleed in or out. See
+[`examples/blank-host.html`](./examples/blank-host.html).
+
+### Programmatic mount
+
+```ts
+import { mountWidget } from '@memberjunction/realtime-widget';
+await mountWidget({ widgetKey: 'pk_live_xxx', apiUrl: 'https://api.yourco.com', mountTarget: '#support' });
+```
+
+## Content Security Policy (host sites)
+
+If your site sends a `Content-Security-Policy` header (it should), the widget needs four allowances:
+the script bundle, the API origin (GraphQL over HTTPS **and** the realtime WebSocket for voice), and —
+because the UI renders inside a shadow DOM with inlined token styles — `style-src 'unsafe-inline'`.
+Replace `https://api.yourco.com` with your MJAPI origin and `https://cdn.yourco.com` with wherever you
+host `mj-widget.js`:
+
+```
+Content-Security-Policy:
+  script-src 'self' https://cdn.yourco.com;
+  connect-src 'self' https://api.yourco.com wss://api.yourco.com;
+  style-src 'self' 'unsafe-inline';
+  img-src 'self' data:;
+  frame-ancestors 'self';
+```
+
+Notes:
+- **`connect-src`** must include BOTH `https://` (the GraphQL mint + agent calls) and `wss://` (the
+  realtime voice socket). Voice silently fails to connect if the `wss:` origin is omitted.
+- **`style-src 'unsafe-inline'`** is required because the shadow-DOM component injects its
+  design-token stylesheet inline. The shadow root keeps it isolated from your page's styles; it does
+  **not** widen your page's own CSP exposure to inline `<style>` you didn't author.
+- **`img-src data:`** covers the inline SVG/emoji affordances.
+- Voice also needs the browser mic permission; on a strict `Permissions-Policy`, allow
+  `microphone=(self "https://cdn.yourco.com")` (or your embed origin) or the mic toggle is hidden and
+  the widget falls back to text.
+
+## Architecture
+
+```
+host page → <mj-support-widget> (shadow DOM, design-token-scoped)
+   ├─ WidgetSessionClient  →  POST /widget/session  (guest JWT, refreshed before expiry)
+   └─ IWidgetTransport
+        ├─ RuntimeWidgetTransport (prod): setupGraphQLClient(guest token) + ConversationsRuntime
+        │     → AgentRunner.processMessage({ explicitAgentId: <pinned> })   ← D5
+        └─ MockWidgetTransport (tests / offline demo)
+```
+
+- **Auth (D1, pluggable):** the guest session is an `anonymous-embed` magic-link token minted by
+  MJServer's `WidgetSessionService`, validated by the same `AuthProviderFactory` path. Strategies:
+  `Anonymous` (default), `MagicLinkUpgrade`, `HostIdentity` — selected per widget instance (W5).
+- **Guardrails (D5):** the widget **always** passes the per-instance pinned `explicitAgentId`, and
+  the synthesized guest principal carries the restricted **Widget Guest** role (read/create/update
+  only on Conversations + Conversation Details). Pinning alone is not enough — see the
+  [W0 findings](../../../plans/realtime/bridges-and-widget/spikes/W0-findings.md).
+- **Isolation:** shadow DOM + `all: initial` on `:host`; `--mj-chat-*` tokens are injected into the
+  **shadow root**, never `<head>`.
+
+## Scripts
+
+```bash
+npm run build       # tsc → dist/ (ESM)
+npm run bundle      # esbuild → dist/mj-widget.js (single-file browser ESM)
+npm run bundle:min  # minified variant
+npm run test        # vitest (jsdom): session client, element, loader
+```
+
+## Build & bundle status (overnight session)
+
+- `npm run build` ✅ and `npm run test` ✅ (15 tests: mint, shadow-DOM isolation, send/receive,
+  pinned-agent pass-through, refresh math, loader mount).
+- `npm run bundle` ✅ produces a **self-contained** browser ESM (no unresolved node built-ins).
+  It is currently large (~2.9 MB minified) because it bundles the full runtime + GraphQL provider;
+  **tree-shaking / code-splitting the bundle is W6 packaging hardening**, tracked, not done here.
+- **Live end-to-end** (`blank-host.html` against a running MJAPI completing a real turn) requires
+  MJAPI booted with `widget.enabled=true` — **Auth0-gated** in the overnight sandbox. The code path
+  is complete and ready; it was not faked.
+
+## Not built here (anti-drift)
+
+No new chat engine, no new realtime/voice driver, no new auth subsystem, no second agent-dispatch
+path — all reused. Voice (W4), magic-link upgrade + host identity (W5), and bundle/abuse hardening
+(W6) build on this package.

package/dist/embed.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @fileoverview Browser EMBED entry — the bundle the host page loads via `<script src="mj-widget.js">`.
+ *
+ * Deliberately TINY and free of static value-imports of the heavy modules (the runtime transport and
+ * the realtime voice stack). It only defines the custom element and auto-bootstraps from the host's
+ * `[data-widget-key]` element; the loader then DYNAMICALLY imports the transport (on mount) and the
+ * voice controller (only for Voice/Both widgets). Built with `esbuild --splitting`, this keeps
+ * `@memberjunction/graphql-dataprovider` + `@memberjunction/conversations-runtime` and
+ * `@memberjunction/ai-realtime-client` in separate chunks that load on demand — so the launcher
+ * paints fast and a text-only widget never downloads the voice chunk.
+ *
+ * The npm public API (with static exports for programmatic consumers) remains `index.ts`; this module
+ * is purely the self-running browser bundle entry.
+ *
+ * @module @memberjunction/realtime-widget
+ */
+export {};
+//# sourceMappingURL=embed.d.ts.map

package/dist/embed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embed.d.ts","sourceRoot":"","sources":["../src/embed.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG"}

package/dist/embed.js

@@ -0,0 +1,33 @@
+/**
+ * @fileoverview Browser EMBED entry — the bundle the host page loads via `<script src="mj-widget.js">`.
+ *
+ * Deliberately TINY and free of static value-imports of the heavy modules (the runtime transport and
+ * the realtime voice stack). It only defines the custom element and auto-bootstraps from the host's
+ * `[data-widget-key]` element; the loader then DYNAMICALLY imports the transport (on mount) and the
+ * voice controller (only for Voice/Both widgets). Built with `esbuild --splitting`, this keeps
+ * `@memberjunction/graphql-dataprovider` + `@memberjunction/conversations-runtime` and
+ * `@memberjunction/ai-realtime-client` in separate chunks that load on demand — so the launcher
+ * paints fast and a text-only widget never downloads the voice chunk.
+ *
+ * The npm public API (with static exports for programmatic consumers) remains `index.ts`; this module
+ * is purely the self-running browser bundle entry.
+ *
+ * @module @memberjunction/realtime-widget
+ */
+import { defineSupportWidgetElement } from './ui/support-widget-element.js';
+import { bootstrapFromDocument } from './loader.js';
+// When loaded in a browser, register the element and attempt auto-bootstrap from the host's
+// [data-widget-key] element. No-ops cleanly server-side or when nothing matches.
+if (typeof window !== 'undefined' && typeof document !== 'undefined') {
+    defineSupportWidgetElement();
+    const run = () => {
+        void bootstrapFromDocument();
+    };
+    if (document.readyState === 'loading') {
+        document.addEventListener('DOMContentLoaded', run, { once: true });
+    }
+    else {
+        run();
+    }
+}
+//# sourceMappingURL=embed.js.map

package/dist/embed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"embed.js","sourceRoot":"","sources":["../src/embed.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,0BAA0B,EAAE,MAAM,gCAAgC,CAAC;AAC5E,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAEpD,4FAA4F;AAC5F,iFAAiF;AACjF,IAAI,OAAO,MAAM,KAAK,WAAW,IAAI,OAAO,QAAQ,KAAK,WAAW,EAAE,CAAC;IACnE,0BAA0B,EAAE,CAAC;IAC7B,MAAM,GAAG,GAAG,GAAS,EAAE;QACnB,KAAK,qBAAqB,EAAE,CAAC;IACjC,CAAC,CAAC;IACF,IAAI,QAAQ,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;QACpC,QAAQ,CAAC,gBAAgB,CAAC,kBAAkB,EAAE,GAAG,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IACvE,CAAC;SAAM,CAAC;QACJ,GAAG,EAAE,CAAC;IACV,CAAC;AACL,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @fileoverview Public API for @memberjunction/realtime-widget + auto-bootstrap when loaded
+ * as a browser bundle. Only exports symbols defined in this package (no cross-package
+ * re-exports — CLAUDE rule 5).
+ *
+ * @module @memberjunction/realtime-widget
+ */
+export * from './types.js';
+export { WidgetSessionClient, type FetchLike } from './session/widget-session-client.js';
+export type { IWidgetTransport, WidgetProgressCallback, WidgetTurnResult } from './transport/widget-transport.js';
+export { MockWidgetTransport } from './transport/mock-widget-transport.js';
+export { RuntimeWidgetTransport } from './transport/runtime-widget-transport.js';
+export type { IVoiceController, VoiceControllerCallbacks, WidgetVoiceState, WidgetVoiceTranscript, } from './voice/voice-controller.js';
+export { MockVoiceController } from './voice/mock-voice-controller.js';
+export { RealtimeVoiceController, type VoiceMintFn, type VoiceMintResult, } from './voice/realtime-voice-controller.js';
+export { VoiceAbuseGuard, DEFAULT_VOICE_LIMITS, type VoiceAbuseLimits, type VoiceAbortReason, } from './voice/voice-abuse-guard.js';
+export { BaseWidgetChannel, type WidgetChannelToolDefinition, type WidgetChannelContext, } from './voice/channels/base-widget-channel.js';
+export { WidgetChannelHost, type ChannelToolRouteResult } from './voice/channels/widget-channel-host.js';
+export { WidgetWhiteboardChannel, LoadWidgetWhiteboardChannel } from './voice/channels/whiteboard-channel.js';
+export { SupportWidgetElement, defineSupportWidgetElement, WIDGET_TAG_NAME } from './ui/support-widget-element.js';
+export { WIDGET_SHADOW_STYLES } from './ui/tokens.js';
+export { mountWidget, bootstrapFromDocument, type WidgetMountDeps } from './loader.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,mBAAmB,EAAE,KAAK,SAAS,EAAE,MAAM,oCAAoC,CAAC;AACzF,YAAY,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AAClH,OAAO,EAAE,mBAAmB,EAAE,MAAM,sCAAsC,CAAC;AAC3E,OAAO,EAAE,sBAAsB,EAAE,MAAM,yCAAyC,CAAC;AACjF,YAAY,EACR,gBAAgB,EAChB,wBAAwB,EACxB,gBAAgB,EAChB,qBAAqB,GACxB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AACvE,OAAO,EACH,uBAAuB,EACvB,KAAK,WAAW,EAChB,KAAK,eAAe,GACvB,MAAM,sCAAsC,CAAC;AAC9C,OAAO,EACH,eAAe,EACf,oBAAoB,EACpB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,GACxB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EACH,iBAAiB,EACjB,KAAK,2BAA2B,EAChC,KAAK,oBAAoB,GAC5B,MAAM,yCAAyC,CAAC;AACjD,OAAO,EAAE,iBAAiB,EAAE,KAAK,sBAAsB,EAAE,MAAM,yCAAyC,CAAC;AACzG,OAAO,EAAE,uBAAuB,EAAE,2BAA2B,EAAE,MAAM,wCAAwC,CAAC;AAC9G,OAAO,EAAE,oBAAoB,EAAE,0BAA0B,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACnH,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,qBAAqB,EAAE,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,37 @@
+/**
+ * @fileoverview Public API for @memberjunction/realtime-widget + auto-bootstrap when loaded
+ * as a browser bundle. Only exports symbols defined in this package (no cross-package
+ * re-exports — CLAUDE rule 5).
+ *
+ * @module @memberjunction/realtime-widget
+ */
+export * from './types.js';
+export { WidgetSessionClient } from './session/widget-session-client.js';
+export { MockWidgetTransport } from './transport/mock-widget-transport.js';
+export { RuntimeWidgetTransport } from './transport/runtime-widget-transport.js';
+export { MockVoiceController } from './voice/mock-voice-controller.js';
+export { RealtimeVoiceController, } from './voice/realtime-voice-controller.js';
+export { VoiceAbuseGuard, DEFAULT_VOICE_LIMITS, } from './voice/voice-abuse-guard.js';
+export { BaseWidgetChannel, } from './voice/channels/base-widget-channel.js';
+export { WidgetChannelHost } from './voice/channels/widget-channel-host.js';
+export { WidgetWhiteboardChannel, LoadWidgetWhiteboardChannel } from './voice/channels/whiteboard-channel.js';
+export { SupportWidgetElement, defineSupportWidgetElement, WIDGET_TAG_NAME } from './ui/support-widget-element.js';
+export { WIDGET_SHADOW_STYLES } from './ui/tokens.js';
+export { mountWidget, bootstrapFromDocument } from './loader.js';
+import { defineSupportWidgetElement } from './ui/support-widget-element.js';
+import { bootstrapFromDocument } from './loader.js';
+// When loaded in a browser, register the element and attempt auto-bootstrap from the
+// host's [data-widget-key] element. No-ops cleanly server-side or when nothing matches.
+if (typeof window !== 'undefined' && typeof document !== 'undefined') {
+    defineSupportWidgetElement();
+    const run = () => {
+        void bootstrapFromDocument();
+    };
+    if (document.readyState === 'loading') {
+        document.addEventListener('DOMContentLoaded', run, { once: true });
+    }
+    else {
+        run();
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,mBAAmB,EAAkB,MAAM,oCAAoC,CAAC;AAEzF,OAAO,EAAE,mBAAmB,EAAE,MAAM,sCAAsC,CAAC;AAC3E,OAAO,EAAE,sBAAsB,EAAE,MAAM,yCAAyC,CAAC;AAOjF,OAAO,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AACvE,OAAO,EACH,uBAAuB,GAG1B,MAAM,sCAAsC,CAAC;AAC9C,OAAO,EACH,eAAe,EACf,oBAAoB,GAGvB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EACH,iBAAiB,GAGpB,MAAM,yCAAyC,CAAC;AACjD,OAAO,EAAE,iBAAiB,EAA+B,MAAM,yCAAyC,CAAC;AACzG,OAAO,EAAE,uBAAuB,EAAE,2BAA2B,EAAE,MAAM,wCAAwC,CAAC;AAC9G,OAAO,EAAE,oBAAoB,EAAE,0BAA0B,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACnH,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,qBAAqB,EAAwB,MAAM,aAAa,CAAC;AAEvF,OAAO,EAAE,0BAA0B,EAAE,MAAM,gCAAgC,CAAC;AAC5E,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAEpD,qFAAqF;AACrF,wFAAwF;AACxF,IAAI,OAAO,MAAM,KAAK,WAAW,IAAI,OAAO,QAAQ,KAAK,WAAW,EAAE,CAAC;IACnE,0BAA0B,EAAE,CAAC;IAC7B,MAAM,GAAG,GAAG,GAAS,EAAE;QACnB,KAAK,qBAAqB,EAAE,CAAC;IACjC,CAAC,CAAC;IACF,IAAI,QAAQ,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;QACpC,QAAQ,CAAC,gBAAgB,CAAC,kBAAkB,EAAE,GAAG,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IACvE,CAAC;SAAM,CAAC;QACJ,GAAG,EAAE,CAAC;IACV,CAAC;AACL,CAAC"}

package/dist/loader.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @fileoverview The embed loader. Reads `data-widget-key` / `data-api-url` from the
+ * host page (the mount div or the script tag), mints a guest session, mounts the
+ * `<mj-support-widget>` element, registers the runtime notification adapter scoped to
+ * the widget, and schedules token refresh. This is the single entry point the
+ * `mj-widget.js` bundle auto-runs.
+ *
+ * @module @memberjunction/realtime-widget
+ */
+import type { WidgetMountOptions, WidgetSession } from './types.js';
+import { WidgetSessionClient } from './session/widget-session-client.js';
+import type { IWidgetTransport } from './transport/widget-transport.js';
+import type { IVoiceController } from './voice/voice-controller.js';
+import { SupportWidgetElement } from './ui/support-widget-element.js';
+/** Optional injection points so the loader is unit-testable without a network/runtime. */
+export interface WidgetMountDeps {
+    /** Builds the session client (defaults to the real fetch-based one). */
+    sessionClientFactory?: (apiUrl: string, widgetKey: string) => WidgetSessionClient;
+    /** Builds the transport (defaults to RuntimeWidgetTransport; tests inject a mock). May be async (the default lazy-loads). */
+    transportFactory?: (apiUrl: string) => IWidgetTransport | Promise<IWidgetTransport>;
+    /** Builds the voice controller for voice-enabled instances (defaults to RealtimeVoiceController). May be async (the default lazy-loads). */
+    voiceControllerFactory?: (session: WidgetSession) => IVoiceController | Promise<IVoiceController>;
+    /** Schedules refresh (defaults to setTimeout); tests can stub. */
+    scheduler?: (cb: () => void, delayMs: number) => void;
+}
+/**
+ * Mints a guest session and mounts a configured widget element. Returns the element.
+ */
+export declare function mountWidget(options: WidgetMountOptions, deps?: WidgetMountDeps): Promise<SupportWidgetElement>;
+/** Reads data-attributes from the host and mounts. Safe to call once on script load. */
+export declare function bootstrapFromDocument(doc?: Document): Promise<SupportWidgetElement | null>;
+//# sourceMappingURL=loader.d.ts.map

package/dist/loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../src/loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AACpE,OAAO,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAC;AAEzE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACxE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAEpE,OAAO,EAAE,oBAAoB,EAA+C,MAAM,gCAAgC,CAAC;AAEnH,0FAA0F;AAC1F,MAAM,WAAW,eAAe;IAC5B,wEAAwE;IACxE,oBAAoB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,mBAAmB,CAAC;IAClF,6HAA6H;IAC7H,gBAAgB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACpF,4IAA4I;IAC5I,sBAAsB,CAAC,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAClG,kEAAkE;IAClE,SAAS,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACzD;AAED;;GAEG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,kBAAkB,EAAE,IAAI,GAAE,eAAoB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CA2CxH;AAED,wFAAwF;AACxF,wBAAsB,qBAAqB,CAAC,GAAG,GAAE,QAAmB,GAAG,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAe1G"}

package/dist/loader.js

@@ -0,0 +1,163 @@
+/**
+ * @fileoverview The embed loader. Reads `data-widget-key` / `data-api-url` from the
+ * host page (the mount div or the script tag), mints a guest session, mounts the
+ * `<mj-support-widget>` element, registers the runtime notification adapter scoped to
+ * the widget, and schedules token refresh. This is the single entry point the
+ * `mj-widget.js` bundle auto-runs.
+ *
+ * @module @memberjunction/realtime-widget
+ */
+import { WidgetSessionClient } from './session/widget-session-client.js';
+import { readVisitorKey, writeVisitorKey, clearVisitorKey } from './session/visitor-key-cookie.js';
+import { DEFAULT_VOICE_LIMITS } from './voice/voice-abuse-guard.js';
+import { defineSupportWidgetElement, WIDGET_TAG_NAME } from './ui/support-widget-element.js';
+/**
+ * Mints a guest session and mounts a configured widget element. Returns the element.
+ */
+export async function mountWidget(options, deps = {}) {
+    defineSupportWidgetElement();
+    const client = (deps.sessionClientFactory ?? defaultSessionClient)(options.apiUrl, options.widgetKey);
+    // Returning-visitor anchor (RV1): present the durable cookie (if any) so the server can chain this
+    // visit to the visitor's prior conversation. Gated server-side on the widget's RememberReturningVisitors
+    // toggle — when off, the server returns no visitorKey and we set no cookie below.
+    const presentedVisitorKey = readVisitorKey(options.widgetKey);
+    const session = await client.Mint(presentedVisitorKey);
+    if (session.rememberReturningVisitors && session.visitorKey) {
+        writeVisitorKey(options.widgetKey, session.visitorKey);
+    }
+    const transport = await (deps.transportFactory ?? defaultTransport)(options.apiUrl);
+    await transport.Initialize(session);
+    const element = document.createElement(WIDGET_TAG_NAME);
+    element.Configure({ title: options.title, greeting: options.greeting });
+    element.SetSession(session);
+    element.SetTransport(transport);
+    if (session.modality === 'Voice' || session.modality === 'Both') {
+        element.SetVoiceController(await (deps.voiceControllerFactory ?? defaultVoiceController)(session));
+    }
+    // RV5 "forget me": only wired when the widget remembers returning visitors and a durable key exists.
+    // Archives the visitor's server-side memory, then clears the first-party cookie so no linkage remains.
+    if (session.rememberReturningVisitors && session.visitorKey) {
+        const visitorKey = session.visitorKey;
+        element.SetForgetHandler(async () => {
+            const result = await client.Forget(visitorKey);
+            if (!result.success) {
+                throw new Error(result.error ?? 'forget failed');
+            }
+            clearVisitorKey(options.widgetKey);
+        });
+    }
+    resolveMountTarget(options.mountTarget).appendChild(element);
+    registerNotificationAdapter(element);
+    scheduleRefresh(client, transport, element, session, deps.scheduler ?? defaultScheduler);
+    return element;
+}
+/** Reads data-attributes from the host and mounts. Safe to call once on script load. */
+export async function bootstrapFromDocument(doc = document) {
+    const mountEl = doc.querySelector('[data-widget-key]');
+    const widgetKey = mountEl?.dataset.widgetKey;
+    const apiUrl = mountEl?.dataset.apiUrl;
+    if (!mountEl || !widgetKey || !apiUrl) {
+        // Nothing to mount — the host hasn't placed a configured element. Not an error.
+        return null;
+    }
+    return mountWidget({
+        widgetKey,
+        apiUrl,
+        mountTarget: mountEl,
+        title: mountEl.dataset.title,
+        greeting: mountEl.dataset.greeting,
+    });
+}
+function defaultSessionClient(apiUrl, widgetKey) {
+    return new WidgetSessionClient(apiUrl, widgetKey);
+}
+/**
+ * Default transport. DYNAMIC import (CLAUDE rule 8, category 3 — bundle-size deferral): the runtime
+ * transport pulls in `@memberjunction/graphql-dataprovider` + `@memberjunction/conversations-runtime`
+ * (the heaviest dependency in the bundle). Loading it on demand keeps it OUT of the embed entry chunk
+ * so the launcher button paints before the runtime is fetched. Declared in `dependencies`.
+ */
+async function defaultTransport(apiUrl) {
+    const { RuntimeWidgetTransport } = await import('./transport/runtime-widget-transport.js');
+    return new RuntimeWidgetTransport(apiUrl);
+}
+/**
+ * Default voice controller. DYNAMIC import (CLAUDE rule 8, category 3): the realtime controller pulls
+ * in `@memberjunction/ai-realtime-client` + provider drivers, needed ONLY for Voice/Both widgets — so
+ * a text-only widget never pays for the voice chunk. Declared in `dependencies`.
+ */
+async function defaultVoiceController(session) {
+    const [{ RealtimeVoiceController }, { createGuestVoiceMint }, { createGuestToolRelay }] = await Promise.all([
+        import('./voice/realtime-voice-controller.js'),
+        import('./voice/guest-voice-mint.js'),
+        import('./voice/guest-tool-relay.js'),
+    ]);
+    return new RealtimeVoiceController(createGuestVoiceMint(session), voiceLimitsForSession(session), 
+    // Phase 2: the interactive channels this widget may attach (Whiteboard, …) + the live relay for
+    // non-channel tool calls. Empty enabledChannels (the default) leaves voice behavior unchanged.
+    session.enabledChannels, createGuestToolRelay());
+}
+/**
+ * Derives the client-side voice ceilings from the widget instance's configured
+ * VoiceMaxSessionMinutes (surfaced on the minted session). When the deployment sets no
+ * per-widget cap, the guard's built-in defaults apply. This is defense-in-depth — the
+ * authoritative cap is enforced server-side at the realtime mint (the ephemeral session's
+ * bounded TTL), so a tampered client cannot exceed the deployment's limit.
+ */
+function voiceLimitsForSession(session) {
+    if (session.voiceMaxSessionMinutes && session.voiceMaxSessionMinutes > 0) {
+        return { ...DEFAULT_VOICE_LIMITS, maxSessionMinutes: session.voiceMaxSessionMinutes };
+    }
+    return undefined;
+}
+function defaultScheduler(cb, delayMs) {
+    setTimeout(cb, delayMs);
+}
+/** Resolves a selector/element/undefined to the mount parent (falls back to <body>). */
+function resolveMountTarget(target) {
+    if (target instanceof HTMLElement)
+        return target;
+    if (typeof target === 'string') {
+        const found = document.querySelector(target);
+        if (found)
+            return found;
+    }
+    return document.body;
+}
+/**
+ * Routes runtime warnings/errors into the widget transcript as system lines. DYNAMIC import
+ * (CLAUDE rule 8, category 3): `ConversationsRuntime` is part of the heavy runtime chunk; importing
+ * it here (rather than statically at module top) keeps it out of the embed entry chunk. Fire-and-forget
+ * — adapter registration is best-effort and must not block the mount. Declared in `dependencies`.
+ */
+function registerNotificationAdapter(element) {
+    void import('@memberjunction/conversations-runtime').then(({ ConversationsRuntime }) => {
+        ConversationsRuntime.Instance.UseNotificationAdapter({
+            Notify: (level, message) => {
+                if (level === 'error' || level === 'warning') {
+                    element.ShowSystemMessage(message);
+                }
+            },
+        });
+    });
+}
+/** Refreshes the guest token shortly before expiry and re-arms the timer. */
+function scheduleRefresh(client, transport, element, session, scheduler) {
+    const delay = WidgetSessionClient.MsUntilRefresh(session, Date.now());
+    scheduler(() => {
+        void (async () => {
+            try {
+                const refreshed = await client.Refresh(session.visitorKey);
+                transport.UpdateToken(refreshed.token);
+                scheduleRefresh(client, transport, element, refreshed, scheduler);
+            }
+            catch {
+                // A failed refresh leaves the current (soon-to-expire) token. Surface the
+                // connection-lost banner so the visitor can retry the refresh; on success
+                // the banner clears and the refresh timer re-arms (graceful degradation, W6).
+                element.ShowConnectionError('Connection to support was lost.', () => scheduleRefresh(client, transport, element, session, scheduler));
+            }
+        })();
+    }, delay);
+}
+//# sourceMappingURL=loader.js.map

package/dist/loader.js.map

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

package/dist/session/visitor-key-cookie.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @fileoverview The durable returning-visitor anchor (RV3): a long-lived, opaque,
+ * first-party cookie holding the server-minted `VisitorKey`. This is identity/auth
+ * state (a visitor anchor), NOT a user preference — so a cookie is the right mechanism
+ * (analogous to the auth-token exception, CLAUDE rule 9), and it must survive page
+ * close (unlike the in-memory guest token). It is ONLY ever set when the widget's
+ * `RememberReturningVisitors` toggle is on; the "forget me" control clears it (RV5).
+ *
+ * The cookie is scoped per widget key so two widgets on the same origin don't share a
+ * visitor identity. The value is the opaque base64url key the server returns.
+ *
+ * @module @memberjunction/realtime-widget
+ */
+/** Reads the persisted VisitorKey for this widget, or undefined when absent / no document. */
+export declare function readVisitorKey(widgetKey: string): string | undefined;
+/** Persists the VisitorKey as a long-lived first-party cookie (Secure on https, SameSite=Lax). */
+export declare function writeVisitorKey(widgetKey: string, visitorKey: string): void;
+/** Clears the persisted VisitorKey (RV5 "forget me"). Expires the cookie immediately. */
+export declare function clearVisitorKey(widgetKey: string): void;
+//# sourceMappingURL=visitor-key-cookie.d.ts.map

package/dist/session/visitor-key-cookie.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"visitor-key-cookie.d.ts","sourceRoot":"","sources":["../../src/session/visitor-key-cookie.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAcH,8FAA8F;AAC9F,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAiBpE;AAED,kGAAkG;AAClG,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAQ3E;AAED,yFAAyF;AACzF,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAKvD"}

package/dist/session/visitor-key-cookie.js

@@ -0,0 +1,60 @@
+/**
+ * @fileoverview The durable returning-visitor anchor (RV3): a long-lived, opaque,
+ * first-party cookie holding the server-minted `VisitorKey`. This is identity/auth
+ * state (a visitor anchor), NOT a user preference — so a cookie is the right mechanism
+ * (analogous to the auth-token exception, CLAUDE rule 9), and it must survive page
+ * close (unlike the in-memory guest token). It is ONLY ever set when the widget's
+ * `RememberReturningVisitors` toggle is on; the "forget me" control clears it (RV5).
+ *
+ * The cookie is scoped per widget key so two widgets on the same origin don't share a
+ * visitor identity. The value is the opaque base64url key the server returns.
+ *
+ * @module @memberjunction/realtime-widget
+ */
+/** Cookie name prefix; the (sanitized) widget key is appended to scope it per deployment. */
+const COOKIE_PREFIX = 'mjwv_';
+/** Default cookie lifetime. The authoritative retention lives server-side (VisitorMemoryRetentionDays);
+ *  this is just how long the browser keeps presenting the anchor. One year, refreshed on each visit. */
+const COOKIE_MAX_AGE_SECONDS = 365 * 24 * 60 * 60;
+/** Per-deployment cookie name; widget keys are restricted to a cookie-name-safe charset. */
+function cookieName(widgetKey) {
+    return COOKIE_PREFIX + widgetKey.replace(/[^A-Za-z0-9_-]/g, '');
+}
+/** Reads the persisted VisitorKey for this widget, or undefined when absent / no document. */
+export function readVisitorKey(widgetKey) {
+    if (typeof document === 'undefined' || !document.cookie) {
+        return undefined;
+    }
+    const name = cookieName(widgetKey) + '=';
+    for (const part of document.cookie.split(';')) {
+        const trimmed = part.trim();
+        if (trimmed.startsWith(name)) {
+            const raw = trimmed.slice(name.length);
+            try {
+                return decodeURIComponent(raw) || undefined;
+            }
+            catch {
+                return raw || undefined;
+            }
+        }
+    }
+    return undefined;
+}
+/** Persists the VisitorKey as a long-lived first-party cookie (Secure on https, SameSite=Lax). */
+export function writeVisitorKey(widgetKey, visitorKey) {
+    if (typeof document === 'undefined' || !visitorKey) {
+        return;
+    }
+    const secure = typeof location !== 'undefined' && location.protocol === 'https:' ? '; Secure' : '';
+    document.cookie =
+        `${cookieName(widgetKey)}=${encodeURIComponent(visitorKey)}` +
+            `; Max-Age=${COOKIE_MAX_AGE_SECONDS}; Path=/; SameSite=Lax${secure}`;
+}
+/** Clears the persisted VisitorKey (RV5 "forget me"). Expires the cookie immediately. */
+export function clearVisitorKey(widgetKey) {
+    if (typeof document === 'undefined') {
+        return;
+    }
+    document.cookie = `${cookieName(widgetKey)}=; Max-Age=0; Path=/; SameSite=Lax`;
+}
+//# sourceMappingURL=visitor-key-cookie.js.map

package/dist/session/visitor-key-cookie.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"visitor-key-cookie.js","sourceRoot":"","sources":["../../src/session/visitor-key-cookie.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,6FAA6F;AAC7F,MAAM,aAAa,GAAG,OAAO,CAAC;AAE9B;wGACwG;AACxG,MAAM,sBAAsB,GAAG,GAAG,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC;AAElD,4FAA4F;AAC5F,SAAS,UAAU,CAAC,SAAiB;IACjC,OAAO,aAAa,GAAG,SAAS,CAAC,OAAO,CAAC,iBAAiB,EAAE,EAAE,CAAC,CAAC;AACpE,CAAC;AAED,8FAA8F;AAC9F,MAAM,UAAU,cAAc,CAAC,SAAiB;IAC5C,IAAI,OAAO,QAAQ,KAAK,WAAW,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC;QACtD,OAAO,SAAS,CAAC;IACrB,CAAC;IACD,MAAM,IAAI,GAAG,UAAU,CAAC,SAAS,CAAC,GAAG,GAAG,CAAC;IACzC,KAAK,MAAM,IAAI,IAAI,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QAC5C,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QAC5B,IAAI,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;YAC3B,MAAM,GAAG,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACvC,IAAI,CAAC;gBACD,OAAO,kBAAkB,CAAC,GAAG,CAAC,IAAI,SAAS,CAAC;YAChD,CAAC;YAAC,MAAM,CAAC;gBACL,OAAO,GAAG,IAAI,SAAS,CAAC;YAC5B,CAAC;QACL,CAAC;IACL,CAAC;IACD,OAAO,SAAS,CAAC;AACrB,CAAC;AAED,kGAAkG;AAClG,MAAM,UAAU,eAAe,CAAC,SAAiB,EAAE,UAAkB;IACjE,IAAI,OAAO,QAAQ,KAAK,WAAW,IAAI,CAAC,UAAU,EAAE,CAAC;QACjD,OAAO;IACX,CAAC;IACD,MAAM,MAAM,GAAG,OAAO,QAAQ,KAAK,WAAW,IAAI,QAAQ,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC;IACnG,QAAQ,CAAC,MAAM;QACX,GAAG,UAAU,CAAC,SAAS,CAAC,IAAI,kBAAkB,CAAC,UAAU,CAAC,EAAE;YAC5D,aAAa,sBAAsB,yBAAyB,MAAM,EAAE,CAAC;AAC7E,CAAC;AAED,yFAAyF;AACzF,MAAM,UAAU,eAAe,CAAC,SAAiB;IAC7C,IAAI,OAAO,QAAQ,KAAK,WAAW,EAAE,CAAC;QAClC,OAAO;IACX,CAAC;IACD,QAAQ,CAAC,MAAM,GAAG,GAAG,UAAU,CAAC,SAAS,CAAC,oCAAoC,CAAC;AACnF,CAAC"}