@memberjunction/realtime-widget 0.0.0 → 5.45.0

package/dist/session/widget-session-client.d.ts

@@ -0,0 +1,74 @@
+/**
+ * @fileoverview Mints + refreshes the guest session by calling MJAPI's public
+ * `POST /widget/session` endpoint. The token is auth state (not a user preference),
+ * so holding it in memory / sessionStorage is acceptable (CLAUDE rule 9) — but this
+ * client keeps it only in memory and refreshes before expiry.
+ *
+ * @module @memberjunction/realtime-widget
+ */
+import type { WidgetSession } from '../types.js';
+/** Injectable fetch so the client is unit-testable without a network. Defaults to global fetch. */
+export type FetchLike = (input: string, init?: RequestInit) => Promise<{
+    ok: boolean;
+    status: number;
+    json: () => Promise<unknown>;
+}>;
+/**
+ * Talks to the widget guest-session endpoints. One instance per mounted widget.
+ */
+export declare class WidgetSessionClient {
+    private readonly apiUrl;
+    private readonly widgetKey;
+    private readonly fetchImpl;
+    constructor(apiUrl: string, widgetKey: string, fetchImpl?: FetchLike);
+    /**
+     * Mints a fresh guest session. Throws on a non-2xx / unsuccessful response.
+     * @param visitorKey the durable returning-visitor anchor from the first-party cookie, if present —
+     *   the server uses it to chain this visit to the visitor's prior conversation (gated on the widget's
+     *   RememberReturningVisitors toggle). Omit on a first visit; the server mints one when remembering is on.
+     */
+    Mint(visitorKey?: string): Promise<WidgetSession>;
+    /** Refreshes the guest session (server re-mints by the same key). Carries the visitor anchor so the
+     *  refreshed session keeps the same returning-visitor identity. */
+    Refresh(visitorKey?: string): Promise<WidgetSession>;
+    /**
+     * W5 magic-link upgrade ("Verify it's you"): asks the server to email a verification link scoped to
+     * the widget's app. On success the visitor receives an email; clicking it redeems a VERIFIED session
+     * JWT (via the existing `/magic-link/redeem`). The host page hands that token back to the widget,
+     * which calls `transport.UpdateToken(verifiedToken)` to swap it in — the live conversationId is
+     * preserved because the transport holds it. Never throws; returns a structured result for the UI.
+     */
+    RequestUpgrade(email: string): Promise<{
+        success: boolean;
+        emailSent?: boolean;
+        error?: string;
+    }>;
+    /**
+     * RV5 "forget me": asks the server to archive this visitor's memory and clear the VisitorKey
+     * linkage. The caller is responsible for clearing the durable cookie afterward
+     * (`clearVisitorKey`). Public endpoint — the durable key is the proof. Never throws.
+     */
+    Forget(visitorKey: string): Promise<{
+        success: boolean;
+        notesArchived?: number;
+        error?: string;
+    }>;
+    /**
+     * RV4 (magic-link upgrade path): after the visitor verifies and the widget swaps in the VERIFIED
+     * token, promote their anonymous returning-visitor trail to the verified record. AUTHENTICATED —
+     * the verified token is sent as a Bearer credential; the server reads the verified email from it.
+     * Never throws; returns a structured result.
+     */
+    ResolveIdentity(verifiedToken: string, visitorKey: string): Promise<{
+        success: boolean;
+        mergedConversations?: number;
+        error?: string;
+    }>;
+    /** Milliseconds until the given session should be refreshed (never negative). */
+    static MsUntilRefresh(session: WidgetSession, nowMs: number): number;
+    private call;
+    /** Maps the API response to the in-memory session, validating required fields. */
+    private toSession;
+    private trimmedApiUrl;
+}
+//# sourceMappingURL=widget-session-client.d.ts.map

package/dist/session/widget-session-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"widget-session-client.d.ts","sourceRoot":"","sources":["../../src/session/widget-session-client.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAkB,aAAa,EAAyB,MAAM,aAAa,CAAC;AAExF,mGAAmG;AACnG,MAAM,MAAM,SAAS,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC;IACnE,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;CAChC,CAAC,CAAC;AAKH;;GAEG;AACH,qBAAa,mBAAmB;IAIxB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAJ9B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;gBAGjB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EAClC,SAAS,CAAC,EAAE,SAAS;IAMzB;;;;;OAKG;IACU,IAAI,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAI9D;uEACmE;IACtD,OAAO,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAIjE;;;;;;OAMG;IACU,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAiB9G;;;;OAIG;IACU,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAiB9G;;;;;OAKG;IACU,eAAe,CACxB,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,MAAM,GACnB,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAiB9E,iFAAiF;WACnE,cAAc,CAAC,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM;YAI7D,IAAI;IAalB,kFAAkF;IAClF,OAAO,CAAC,SAAS;IAuBjB,OAAO,CAAC,aAAa;CAGxB"}

package/dist/session/widget-session-client.js

@@ -0,0 +1,147 @@
+/**
+ * @fileoverview Mints + refreshes the guest session by calling MJAPI's public
+ * `POST /widget/session` endpoint. The token is auth state (not a user preference),
+ * so holding it in memory / sessionStorage is acceptable (CLAUDE rule 9) — but this
+ * client keeps it only in memory and refreshes before expiry.
+ *
+ * @module @memberjunction/realtime-widget
+ */
+/** How early (ms before expiry) to proactively refresh the guest token. */
+const REFRESH_LEAD_MS = 60_000;
+/**
+ * Talks to the widget guest-session endpoints. One instance per mounted widget.
+ */
+export class WidgetSessionClient {
+    constructor(apiUrl, widgetKey, fetchImpl) {
+        this.apiUrl = apiUrl;
+        this.widgetKey = widgetKey;
+        // happy fallback to the platform fetch; explicit in tests.
+        this.fetchImpl = fetchImpl ?? ((input, init) => fetch(input, init));
+    }
+    /**
+     * Mints a fresh guest session. Throws on a non-2xx / unsuccessful response.
+     * @param visitorKey the durable returning-visitor anchor from the first-party cookie, if present —
+     *   the server uses it to chain this visit to the visitor's prior conversation (gated on the widget's
+     *   RememberReturningVisitors toggle). Omit on a first visit; the server mints one when remembering is on.
+     */
+    async Mint(visitorKey) {
+        return this.call('/widget/session', visitorKey);
+    }
+    /** Refreshes the guest session (server re-mints by the same key). Carries the visitor anchor so the
+     *  refreshed session keeps the same returning-visitor identity. */
+    async Refresh(visitorKey) {
+        return this.call('/widget/session/refresh', visitorKey);
+    }
+    /**
+     * W5 magic-link upgrade ("Verify it's you"): asks the server to email a verification link scoped to
+     * the widget's app. On success the visitor receives an email; clicking it redeems a VERIFIED session
+     * JWT (via the existing `/magic-link/redeem`). The host page hands that token back to the widget,
+     * which calls `transport.UpdateToken(verifiedToken)` to swap it in — the live conversationId is
+     * preserved because the transport holds it. Never throws; returns a structured result for the UI.
+     */
+    async RequestUpgrade(email) {
+        try {
+            const res = await this.fetchImpl(`${this.trimmedApiUrl()}/widget/upgrade`, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({ widgetKey: this.widgetKey, email }),
+            });
+            const body = (await res.json());
+            if (!res.ok || !body?.success) {
+                return { success: false, error: body?.error ?? body?.errorCode ?? 'Could not start verification.' };
+            }
+            return { success: true, emailSent: body.emailSent };
+        }
+        catch (err) {
+            return { success: false, error: err instanceof Error ? err.message : 'Could not start verification.' };
+        }
+    }
+    /**
+     * RV5 "forget me": asks the server to archive this visitor's memory and clear the VisitorKey
+     * linkage. The caller is responsible for clearing the durable cookie afterward
+     * (`clearVisitorKey`). Public endpoint — the durable key is the proof. Never throws.
+     */
+    async Forget(visitorKey) {
+        try {
+            const res = await this.fetchImpl(`${this.trimmedApiUrl()}/widget/forget`, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({ widgetKey: this.widgetKey, visitorKey }),
+            });
+            const body = (await res.json());
+            if (!res.ok || !body?.success) {
+                return { success: false, error: body?.error ?? body?.errorCode ?? 'Could not forget this visitor.' };
+            }
+            return { success: true, notesArchived: body.notesArchived };
+        }
+        catch (err) {
+            return { success: false, error: err instanceof Error ? err.message : 'Could not forget this visitor.' };
+        }
+    }
+    /**
+     * RV4 (magic-link upgrade path): after the visitor verifies and the widget swaps in the VERIFIED
+     * token, promote their anonymous returning-visitor trail to the verified record. AUTHENTICATED —
+     * the verified token is sent as a Bearer credential; the server reads the verified email from it.
+     * Never throws; returns a structured result.
+     */
+    async ResolveIdentity(verifiedToken, visitorKey) {
+        try {
+            const res = await this.fetchImpl(`${this.trimmedApiUrl()}/widget/resolve-identity`, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json', authorization: `Bearer ${verifiedToken}` },
+                body: JSON.stringify({ widgetKey: this.widgetKey, visitorKey }),
+            });
+            const body = (await res.json());
+            if (!res.ok || !body?.success) {
+                return { success: false, error: body?.error ?? body?.errorCode ?? 'Could not resolve identity.' };
+            }
+            return { success: true, mergedConversations: body.mergedConversations };
+        }
+        catch (err) {
+            return { success: false, error: err instanceof Error ? err.message : 'Could not resolve identity.' };
+        }
+    }
+    /** Milliseconds until the given session should be refreshed (never negative). */
+    static MsUntilRefresh(session, nowMs) {
+        return Math.max(0, session.expiresAtMs - nowMs - REFRESH_LEAD_MS);
+    }
+    async call(path, visitorKey) {
+        const res = await this.fetchImpl(`${this.trimmedApiUrl()}${path}`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(visitorKey ? { widgetKey: this.widgetKey, visitorKey } : { widgetKey: this.widgetKey }),
+        });
+        const body = (await res.json());
+        if (!res.ok || !body?.success || !body.token) {
+            throw new Error(`Widget session mint failed (${res.status}): ${body?.errorCode ?? body?.error ?? 'unknown'}`);
+        }
+        return this.toSession(body);
+    }
+    /** Maps the API response to the in-memory session, validating required fields. */
+    toSession(body) {
+        if (!body.widgetId || !body.applicationId || !body.pinnedAgentId) {
+            throw new Error('Widget session response missing required fields (widgetId/applicationId/pinnedAgentId).');
+        }
+        const expiresAtMs = body.expiresAt ? Date.parse(body.expiresAt) : Number.NaN;
+        return {
+            token: body.token,
+            expiresAtMs: Number.isFinite(expiresAtMs) ? expiresAtMs : Date.now() + 15 * 60_000,
+            widgetId: body.widgetId,
+            applicationId: body.applicationId,
+            pinnedAgentId: body.pinnedAgentId,
+            modality: (body.modality ?? 'Text'),
+            sessionId: body.sessionId ?? '',
+            voiceMaxSessionMinutes: body.voiceMaxSessionMinutes,
+            rememberReturningVisitors: body.rememberReturningVisitors ?? false,
+            visitorKey: body.visitorKey,
+            lastConversationId: body.lastConversationId,
+            linkedEntityId: body.linkedEntityId,
+            linkedRecordId: body.linkedRecordId,
+            enabledChannels: Array.isArray(body.enabledChannels) ? body.enabledChannels : [],
+        };
+    }
+    trimmedApiUrl() {
+        return this.apiUrl.replace(/\/+$/, '');
+    }
+}
+//# sourceMappingURL=widget-session-client.js.map

package/dist/session/widget-session-client.js.map

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

package/dist/transport/mock-widget-transport.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @fileoverview An in-memory transport used by unit tests and the offline example
+ * page. It echoes a canned support reply so the widget UI can be exercised without a
+ * live MJAPI. NOT used in production (the loader wires RuntimeWidgetTransport).
+ *
+ * @module @memberjunction/realtime-widget
+ */
+import type { WidgetSession } from '../types.js';
+import type { IWidgetTransport, WidgetProgressCallback, WidgetTurnResult } from './widget-transport.js';
+/** Deterministic, dependency-free transport for tests + the demo host page. */
+export declare class MockWidgetTransport implements IWidgetTransport {
+    LastExplicitAgentId: string | null;
+    SentMessages: string[];
+    private session?;
+    private replyFor;
+    /** When set, the NEXT SendMessage fails with this error (one-shot) — exercises the offline banner. */
+    private failNextError;
+    constructor(replyFor?: (text: string) => string);
+    /** Arms a one-shot failure on the next SendMessage (test helper for graceful-degradation paths). */
+    FailNextSend(error: string): void;
+    Initialize(session: WidgetSession): Promise<void>;
+    UpdateToken(_token: string): void;
+    SendMessage(text: string, onProgress?: WidgetProgressCallback): Promise<WidgetTurnResult>;
+    Dispose(): Promise<void>;
+}
+//# sourceMappingURL=mock-widget-transport.d.ts.map

package/dist/transport/mock-widget-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-widget-transport.d.ts","sourceRoot":"","sources":["../../src/transport/mock-widget-transport.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,KAAK,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAExG,+EAA+E;AAC/E,qBAAa,mBAAoB,YAAW,gBAAgB;IACjD,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAQ;IAC1C,YAAY,EAAE,MAAM,EAAE,CAAM;IACnC,OAAO,CAAC,OAAO,CAAC,CAAgB;IAChC,OAAO,CAAC,QAAQ,CAA2B;IAC3C,sGAAsG;IACtG,OAAO,CAAC,aAAa,CAAuB;gBAEhC,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM;IAI/C,oGAAoG;IAC7F,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAI3B,UAAU,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAIvD,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAI3B,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,sBAAsB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAYzF,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAGxC"}

package/dist/transport/mock-widget-transport.js

@@ -0,0 +1,42 @@
+/**
+ * @fileoverview An in-memory transport used by unit tests and the offline example
+ * page. It echoes a canned support reply so the widget UI can be exercised without a
+ * live MJAPI. NOT used in production (the loader wires RuntimeWidgetTransport).
+ *
+ * @module @memberjunction/realtime-widget
+ */
+/** Deterministic, dependency-free transport for tests + the demo host page. */
+export class MockWidgetTransport {
+    constructor(replyFor) {
+        this.LastExplicitAgentId = null;
+        this.SentMessages = [];
+        /** When set, the NEXT SendMessage fails with this error (one-shot) — exercises the offline banner. */
+        this.failNextError = null;
+        this.replyFor = replyFor ?? ((t) => `Thanks for your message: "${t}". A support agent will follow up.`);
+    }
+    /** Arms a one-shot failure on the next SendMessage (test helper for graceful-degradation paths). */
+    FailNextSend(error) {
+        this.failNextError = error;
+    }
+    async Initialize(session) {
+        this.session = session;
+    }
+    UpdateToken(_token) {
+        /* no-op for the mock */
+    }
+    async SendMessage(text, onProgress) {
+        this.LastExplicitAgentId = this.session?.pinnedAgentId ?? null;
+        this.SentMessages.push(text);
+        if (this.failNextError) {
+            const error = this.failNextError;
+            this.failNextError = null; // one-shot: a retry succeeds
+            return { reply: '', success: false, error };
+        }
+        onProgress?.('Thinking…', 50);
+        return { reply: this.replyFor(text), success: true };
+    }
+    async Dispose() {
+        this.session = undefined;
+    }
+}
+//# sourceMappingURL=mock-widget-transport.js.map

package/dist/transport/mock-widget-transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-widget-transport.js","sourceRoot":"","sources":["../../src/transport/mock-widget-transport.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,+EAA+E;AAC/E,MAAM,OAAO,mBAAmB;IAQ5B,YAAY,QAAmC;QAPxC,wBAAmB,GAAkB,IAAI,CAAC;QAC1C,iBAAY,GAAa,EAAE,CAAC;QAGnC,sGAAsG;QAC9F,kBAAa,GAAkB,IAAI,CAAC;QAGxC,IAAI,CAAC,QAAQ,GAAG,QAAQ,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,6BAA6B,CAAC,oCAAoC,CAAC,CAAC;IAC5G,CAAC;IAED,oGAAoG;IAC7F,YAAY,CAAC,KAAa;QAC7B,IAAI,CAAC,aAAa,GAAG,KAAK,CAAC;IAC/B,CAAC;IAEM,KAAK,CAAC,UAAU,CAAC,OAAsB;QAC1C,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IAC3B,CAAC;IAEM,WAAW,CAAC,MAAc;QAC7B,wBAAwB;IAC5B,CAAC;IAEM,KAAK,CAAC,WAAW,CAAC,IAAY,EAAE,UAAmC;QACtE,IAAI,CAAC,mBAAmB,GAAG,IAAI,CAAC,OAAO,EAAE,aAAa,IAAI,IAAI,CAAC;QAC/D,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC7B,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;YACrB,MAAM,KAAK,GAAG,IAAI,CAAC,aAAa,CAAC;YACjC,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC,6BAA6B;YACxD,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;QAChD,CAAC;QACD,UAAU,EAAE,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;QAC9B,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IACzD,CAAC;IAEM,KAAK,CAAC,OAAO;QAChB,IAAI,CAAC,OAAO,GAAG,SAAS,CAAC;IAC7B,CAAC;CACJ"}

package/dist/transport/runtime-widget-transport.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @fileoverview The production transport: reuses `@memberjunction/graphql-dataprovider`
+ * (configured outside Angular with the guest JWT) + `ConversationsRuntime` to hold a
+ * text conversation with the pinned support agent. It REUSES the unified pathway — no
+ * new chat engine, no new agent dispatch (anti-drift checklist).
+ *
+ * open-Q #2 (provider reuse): `GraphQLDataProvider` runs fine outside Angular via
+ * `setupGraphQLClient` — it is a plain `IMetadataProvider`. This transport uses it
+ * directly rather than writing a slimmer client.
+ *
+ * NOTE: this path requires a live MJAPI; it is exercised by W3's acceptance (gated on
+ * Auth0/MJAPI boot). Unit tests cover the UI + session client via the mock transport.
+ *
+ * @module @memberjunction/realtime-widget
+ */
+import type { WidgetSession } from '../types.js';
+import type { IWidgetTransport, WidgetProgressCallback, WidgetTurnResult } from './widget-transport.js';
+/** Reuses ConversationsRuntime + the GraphQL provider against MJAPI with the guest token. */
+export declare class RuntimeWidgetTransport implements IWidgetTransport {
+    private readonly apiUrl;
+    private token;
+    private session;
+    private conversationId;
+    private contextUser;
+    private provider;
+    constructor(apiUrl: string);
+    /** Configures the GraphQL provider with the guest token, boots the runtime, opens a conversation. */
+    Initialize(session: WidgetSession): Promise<void>;
+    /** Swaps in a refreshed token (the next provider call uses it; conversation is preserved). */
+    UpdateToken(token: string): void;
+    /** Persists the user's message, runs the pinned agent, returns its reply. */
+    SendMessage(text: string, onProgress?: WidgetProgressCallback): Promise<WidgetTurnResult>;
+    Dispose(): Promise<void>;
+    /**
+     * Returns the transport's own GraphQL provider (bound to this widget's guest token), set in
+     * {@link Initialize}. All entity work goes through this instance rather than the process-global
+     * `Metadata.Provider`, so a page hosting multiple widgets against different servers stays isolated.
+     */
+    private requireProvider;
+    private buildConfig;
+    /** Creates the conversation row the guest's turns attach to. */
+    private createConversation;
+    /** Saves the visitor's message as a Conversation Detail and returns the entity. */
+    private saveUserMessage;
+    /**
+     * Creates the agent's response detail placeholder (Role='AI', In-Progress) the agent run writes
+     * into. Mirrors how the chat UI / AgentRunner pre-create the response row; its id is passed as
+     * `conversationDetailId` so the reply lands as an agent turn the widget can read back.
+     */
+    private createAgentResponseDetail;
+    /** Reads the newest AI Conversation Detail for the conversation (the agent's reply). */
+    private readLatestAgentReply;
+}
+//# sourceMappingURL=runtime-widget-transport.d.ts.map

package/dist/transport/runtime-widget-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-widget-transport.d.ts","sourceRoot":"","sources":["../../src/transport/runtime-widget-transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAMH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,KAAK,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAKxG,6FAA6F;AAC7F,qBAAa,sBAAuB,YAAW,gBAAgB;IAO/C,OAAO,CAAC,QAAQ,CAAC,MAAM;IANnC,OAAO,CAAC,KAAK,CAAM;IACnB,OAAO,CAAC,OAAO,CAA8B;IAC7C,OAAO,CAAC,cAAc,CAAuB;IAC7C,OAAO,CAAC,WAAW,CAAyB;IAC5C,OAAO,CAAC,QAAQ,CAAkC;gBAErB,MAAM,EAAE,MAAM;IAE3C,qGAAqG;IACxF,UAAU,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAa9D,8FAA8F;IACvF,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAIvC,6EAA6E;IAChE,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,sBAAsB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAmCzF,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAQrC;;;;OAIG;IACH,OAAO,CAAC,eAAe;IAOvB,OAAO,CAAC,WAAW;IAMnB,gEAAgE;YAClD,kBAAkB;IA+ChC,mFAAmF;YACrE,eAAe;IAc7B;;;;OAIG;YACW,yBAAyB;IAkBvC,wFAAwF;YAC1E,oBAAoB;CAiBrC"}

package/dist/transport/runtime-widget-transport.js

@@ -0,0 +1,203 @@
+/**
+ * @fileoverview The production transport: reuses `@memberjunction/graphql-dataprovider`
+ * (configured outside Angular with the guest JWT) + `ConversationsRuntime` to hold a
+ * text conversation with the pinned support agent. It REUSES the unified pathway — no
+ * new chat engine, no new agent dispatch (anti-drift checklist).
+ *
+ * open-Q #2 (provider reuse): `GraphQLDataProvider` runs fine outside Angular via
+ * `setupGraphQLClient` — it is a plain `IMetadataProvider`. This transport uses it
+ * directly rather than writing a slimmer client.
+ *
+ * NOTE: this path requires a live MJAPI; it is exercised by W3's acceptance (gated on
+ * Auth0/MJAPI boot). Unit tests cover the UI + session client via the mock transport.
+ *
+ * @module @memberjunction/realtime-widget
+ */
+import { RunView } from '@memberjunction/core';
+import { setupGraphQLClient, GraphQLProviderConfigData } from '@memberjunction/graphql-dataprovider';
+import { ConversationsRuntime } from '@memberjunction/conversations-runtime';
+const CONVERSATIONS_ENTITY = 'MJ: Conversations';
+const CONVERSATION_DETAILS_ENTITY = 'MJ: Conversation Details';
+/** Reuses ConversationsRuntime + the GraphQL provider against MJAPI with the guest token. */
+export class RuntimeWidgetTransport {
+    constructor(apiUrl) {
+        this.apiUrl = apiUrl;
+        this.token = '';
+        this.session = null;
+        this.conversationId = null;
+        this.contextUser = null;
+        this.provider = null;
+    }
+    /** Configures the GraphQL provider with the guest token, boots the runtime, opens a conversation. */
+    async Initialize(session) {
+        this.session = session;
+        this.token = session.token;
+        const provider = await setupGraphQLClient(this.buildConfig());
+        this.provider = provider;
+        this.contextUser = provider.CurrentUser;
+        // No-op when already configured for this process; safe to call per mount.
+        await ConversationsRuntime.Instance.Config(false, provider.CurrentUser, provider);
+        this.conversationId = await this.createConversation();
+    }
+    /** Swaps in a refreshed token (the next provider call uses it; conversation is preserved). */
+    UpdateToken(token) {
+        this.token = token;
+    }
+    /** Persists the user's message, runs the pinned agent, returns its reply. */
+    async SendMessage(text, onProgress) {
+        if (!this.session || !this.conversationId) {
+            return { reply: '', success: false, error: 'Widget transport not initialized.' };
+        }
+        try {
+            const userDetail = await this.saveUserMessage(text);
+            if (!userDetail) {
+                return { reply: '', success: false, error: 'Could not record your message.' };
+            }
+            // The agent writes its reply INTO a pre-created response detail whose id is passed as
+            // `conversationDetailId` (the AgentRunner contract — see AgentRunner.ts: `options.conversationDetailId`
+            // IS the agent response detail). Create it as Role='AI' so the reply is an agent turn, not a
+            // second user turn; `message`/`latestMessageId` stays the user's triggering message.
+            const agentDetail = await this.createAgentResponseDetail();
+            if (!agentDetail) {
+                return { reply: '', success: false, error: 'Could not start the agent response.' };
+            }
+            const result = await ConversationsRuntime.Instance.AgentRunner.processMessage({
+                conversationId: this.conversationId,
+                message: userDetail,
+                conversationDetailId: agentDetail.ID,
+                applicationId: this.session.applicationId,
+                // D5: ALWAYS pin the support agent — never the unfiltered fallback.
+                explicitAgentId: this.session.pinnedAgentId,
+                onProgress: (p) => onProgress?.(p.message ?? 'Working…', p.percentage),
+            });
+            if (!result || !result.success) {
+                return { reply: '', success: false, error: result?.agentRun?.ErrorMessage ?? 'The agent could not respond.' };
+            }
+            return { reply: await this.readLatestAgentReply(), success: true };
+        }
+        catch (err) {
+            return { reply: '', success: false, error: err instanceof Error ? err.message : 'Unexpected error.' };
+        }
+    }
+    async Dispose() {
+        this.session = null;
+        this.conversationId = null;
+        this.contextUser = null;
+    }
+    // ── helpers ────────────────────────────────────────────────────────────────
+    /**
+     * Returns the transport's own GraphQL provider (bound to this widget's guest token), set in
+     * {@link Initialize}. All entity work goes through this instance rather than the process-global
+     * `Metadata.Provider`, so a page hosting multiple widgets against different servers stays isolated.
+     */
+    requireProvider() {
+        if (!this.provider) {
+            throw new Error('Widget transport not initialized — provider unavailable.');
+        }
+        return this.provider;
+    }
+    buildConfig() {
+        const base = this.apiUrl.replace(/\/+$/, '');
+        const wsUrl = base.replace(/^http/, 'ws');
+        return new GraphQLProviderConfigData(this.token, base, wsUrl, async () => this.token);
+    }
+    /** Creates the conversation row the guest's turns attach to. */
+    async createConversation() {
+        const md = this.requireProvider();
+        const convo = await md.GetEntityObject(CONVERSATIONS_ENTITY, this.contextUser ?? undefined);
+        convo.NewRecord();
+        convo.Name = 'Web Widget Support';
+        if (this.contextUser?.ID) {
+            convo.UserID = this.contextUser.ID;
+        }
+        // Scope the conversation to the widget's Application. The returning-visitor lookup at mint
+        // resolves the prior conversation by (VisitorKey AND ApplicationID), so without this the chain
+        // never forms (LastConversationID stays null → no recap, no cross-session memory).
+        // ApplicationScope must be 'Application' for ApplicationID to be set (CK_Conversation_ScopeAppBinding).
+        if (this.session?.applicationId) {
+            convo.ApplicationScope = 'Application';
+            convo.ApplicationID = this.session.applicationId;
+        }
+        // Stamp the per-session id so the Widget Guest RLS filters ({{ScopeResourceID}}) isolate
+        // this guest's conversation from other anonymous guests sharing the Anonymous principal.
+        // Read-isolation is enforced by the SIGNED session scope, so a client mis-stamp can only
+        // hide the guest's own rows from itself — never expose another session's rows.
+        if (this.session?.sessionId) {
+            convo.ExternalID = this.session.sessionId;
+        }
+        // Returning-visitor chain (RV1): when remembering is on, stamp the durable VisitorKey and link to
+        // the visitor's prior conversation (resolved server-side by VisitorKey at mint). Both are null when
+        // the widget's RememberReturningVisitors toggle is off, so this is a no-op in the default case.
+        if (this.session?.rememberReturningVisitors) {
+            if (this.session.visitorKey) {
+                convo.VisitorKey = this.session.visitorKey;
+            }
+            if (this.session.lastConversationId) {
+                convo.LastConversationID = this.session.lastConversationId;
+            }
+            // RV4 (host-identity path): when the mint resolved a polymorphic identity, stamp it so memory
+            // injection keys off the resolved record rather than the anonymous cookie chain.
+            if (this.session.linkedEntityId && this.session.linkedRecordId) {
+                convo.LinkedEntityID = this.session.linkedEntityId;
+                convo.LinkedRecordID = this.session.linkedRecordId;
+            }
+        }
+        const saved = await convo.Save();
+        if (!saved) {
+            throw new Error(`Failed to create widget conversation: ${convo.LatestResult?.CompleteMessage ?? 'unknown error'}`);
+        }
+        return convo.ID;
+    }
+    /** Saves the visitor's message as a Conversation Detail and returns the entity. */
+    async saveUserMessage(text) {
+        const md = this.requireProvider();
+        const detail = await md.GetEntityObject(CONVERSATION_DETAILS_ENTITY, this.contextUser ?? undefined);
+        detail.NewRecord();
+        detail.ConversationID = this.conversationId;
+        detail.Role = 'User';
+        detail.Message = text;
+        const saved = await detail.Save();
+        if (!saved) {
+            return null;
+        }
+        return detail;
+    }
+    /**
+     * Creates the agent's response detail placeholder (Role='AI', In-Progress) the agent run writes
+     * into. Mirrors how the chat UI / AgentRunner pre-create the response row; its id is passed as
+     * `conversationDetailId` so the reply lands as an agent turn the widget can read back.
+     */
+    async createAgentResponseDetail() {
+        const md = this.requireProvider();
+        const detail = await md.GetEntityObject(CONVERSATION_DETAILS_ENTITY, this.contextUser ?? undefined);
+        detail.NewRecord();
+        detail.ConversationID = this.conversationId;
+        detail.Role = 'AI';
+        detail.Message = '⏳ Starting…';
+        detail.Status = 'In-Progress';
+        if (this.session?.pinnedAgentId) {
+            detail.AgentID = this.session.pinnedAgentId;
+        }
+        const saved = await detail.Save();
+        if (!saved) {
+            return null;
+        }
+        return detail;
+    }
+    /** Reads the newest AI Conversation Detail for the conversation (the agent's reply). */
+    async readLatestAgentReply() {
+        const rv = new RunView();
+        const result = await rv.RunView({
+            EntityName: CONVERSATION_DETAILS_ENTITY,
+            ExtraFilter: `ConversationID='${this.conversationId}' AND Role='AI'`,
+            OrderBy: '__mj_CreatedAt DESC',
+            MaxRows: 1,
+            ResultType: 'entity_object',
+        }, this.contextUser ?? undefined);
+        if (result.Success && result.Results.length > 0) {
+            return result.Results[0].Message ?? '';
+        }
+        return '';
+    }
+}
+//# sourceMappingURL=runtime-widget-transport.js.map

package/dist/transport/runtime-widget-transport.js.map

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

package/dist/transport/widget-transport.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @fileoverview The transport seam between the widget UI and the agent pathway.
+ *
+ * The UI element depends only on this interface, so it is unit-testable with a mock
+ * and decoupled from the heavy ConversationsRuntime + GraphQL wiring. The real
+ * implementation (`RuntimeWidgetTransport`) reuses `ConversationsRuntime` +
+ * `@memberjunction/graphql-dataprovider` against MJAPI with the guest token — it does
+ * NOT reimplement chat or agent dispatch (anti-drift checklist).
+ *
+ * @module @memberjunction/realtime-widget
+ */
+import type { WidgetSession } from '../types.js';
+/** Streaming progress callback while an agent turn runs. */
+export type WidgetProgressCallback = (message: string, percentage?: number) => void;
+/** Result of one user turn → agent reply. */
+export interface WidgetTurnResult {
+    /** The agent's reply text (empty string if the agent produced no textual output). */
+    reply: string;
+    /** True when the turn completed successfully. */
+    success: boolean;
+    error?: string;
+}
+/**
+ * Abstraction over "start a conversation and exchange turns with the pinned agent."
+ * One transport instance per mounted widget session.
+ */
+export interface IWidgetTransport {
+    /** Initializes the transport with the freshly-minted guest session. */
+    Initialize(session: WidgetSession): Promise<void>;
+    /** Updates the held token after a refresh (no reconnection of the conversation). */
+    UpdateToken(token: string): void;
+    /**
+     * Sends a user message and resolves with the agent's reply. The pinned agent id
+     * from the session is ALWAYS passed as explicitAgentId (D5) — the transport never
+     * lets the caller pick an arbitrary agent.
+     */
+    SendMessage(text: string, onProgress?: WidgetProgressCallback): Promise<WidgetTurnResult>;
+    /** Tears down the conversation/session resources. */
+    Dispose(): Promise<void>;
+}
+//# sourceMappingURL=widget-transport.d.ts.map

package/dist/transport/widget-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"widget-transport.d.ts","sourceRoot":"","sources":["../../src/transport/widget-transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,4DAA4D;AAC5D,MAAM,MAAM,sBAAsB,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;AAEpF,6CAA6C;AAC7C,MAAM,WAAW,gBAAgB;IAC7B,qFAAqF;IACrF,KAAK,EAAE,MAAM,CAAC;IACd,iDAAiD;IACjD,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC7B,uEAAuE;IACvE,UAAU,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAElD,oFAAoF;IACpF,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAEjC;;;;OAIG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,sBAAsB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAE1F,qDAAqD;IACrD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B"}