@cimulate/copilot-widget 1.31.0 → 1.32.0

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 `@cimulate/copilot-widget` follows [Semantic Versioning](https://semver.org/). Each entry is a released `package.json` version (deployed on merge to `master`), newest first.
 
+## 1.32.0 — 2026-08-28
+
+- Added `getAuthLinkKey()` for retrieving a single-use auth link key for the current conversation, so hosts can bridge a guest shopper's session (e.g. a SLAS/commerce session) into the conversation and let the agent inherit the shopper's identity and cart. Exposed both to React hosts via `useMessaging().getAuthLinkKey()` and to script-tag/CDN hosts via `window.CimulateMessaging.getAuthLinkKey()`. The key is single-use: each call mints a fresh key the server invalidates on redemption, so callers must request a new one rather than caching or retrying with a consumed key. The CDN export is async and rejects (rather than throwing synchronously) when called before the widget is ready. Requires `@cimulate/agentforce-sdk` 1.3.0, which adds the underlying auth-link-key v2 retrieval.
+
 ## 1.31.0 — 2026-08-27
 
 - Messaging mode now defers SCRT2 connection and conversation creation until the shopper opens the widget or sends the first message. Concurrent engagement signals share one initialization, and persisted conversations still resume before a new conversation is created.

package/dist/messaging.d.ts

@@ -349,6 +349,33 @@ export declare const eventHandlers: {
 
 declare type FacetFilters = Record<string, string[]>;
 
+/**
+ * Retrieve a single-use auth link key for the current conversation.
+ *
+ * The host-page/script-tag counterpart of the `getAuthLinkKey` method on the
+ * messaging context (React hosts use `useMessaging().getAuthLinkKey()`). Hand
+ * the returned key to your own backend, which bridges the shopper's session
+ * (e.g. a SLAS/commerce session) into the conversation so the agent inherits
+ * the shopper's identity — and cart.
+ *
+ * Call after `injectMessagingWidget()` has mounted the widget; rejects if the
+ * widget is not yet ready or the request fails. `async` so the registry's
+ * synchronous "not ready" throw surfaces as a rejected promise (honoring the
+ * contract for `.catch()` callers, not just `await`).
+ *
+ * The key is **single-use**: each call mints a fresh key that the server
+ * invalidates once redeemed. Do not cache it or retry a rejected call with the
+ * same key — request a new one, or you will send the backend a key it already
+ * consumed.
+ *
+ * @example
+ * ```js
+ * const authLinkKey = await window.CimulateMessaging.getAuthLinkKey();
+ * await fetch("/bridge-session", { method: "POST", body: JSON.stringify({ authLinkKey }) });
+ * ```
+ */
+export declare function getAuthLinkKey(): Promise<string>;
+
 declare interface HeaderConfig {
     logoUrl?: string;
     headerText?: string;
@@ -444,6 +471,14 @@ export declare interface MessagingContextType {
     retryLastMessage: () => ReturnType<SendMessage> | undefined;
     retryConnection: () => void;
     downloadTranscript: () => Promise<void>;
+    /**
+     * Retrieve a single-use auth link key for the current conversation. The host
+     * hands the key to its own backend, which bridges the shopper's session (e.g.
+     * a SLAS/commerce session) into this conversation so the agent inherits the
+     * shopper's identity — and cart. Resolves with the key; rejects if the widget
+     * is not connected or the request fails.
+     */
+    getAuthLinkKey: () => Promise<string>;
 }
 
 /**