@helpai/elements 1.9.0 → 1.10.0

package/index.d.ts

@@ -898,6 +898,8 @@ interface ResolvedTracking {
  * alongside at the top level — they're function / DOM types that can't be
  * serialised on the wire.
  */
+/** A signed user token, or a function that returns a fresh one (see {@link ChatWidgetOptions.userToken}). */
+type UserTokenSource = string | (() => string | Promise<string>);
 interface ChatWidgetOptions {
   /**
    * Stable identifier for this widget instance. Use when mounting more
@@ -973,6 +975,14 @@ interface ChatWidgetOptions {
    * interface (`get` / `set` / `remove` / `clear`).
    */
   storage?: ClientStorage;
+  /**
+   * Proves who the logged-in visitor is: a JWT your server signs (HS256) with the deployment's secret key, carrying
+   * `sub` (your user id) and `exp`, optionally `name` and `email`. A function is called when a token is first
+   * needed and again when the server rejects the current one as expired, so return a fresh token from it. Their
+   * conversations then follow them to any device; `chat.login(token)` sets it after sign-in, `chat.reset()` on
+   * sign-out. Sent only to the agent API, as `x-user-token`.
+   */
+  userToken?: UserTokenSource;
   onMessage?: (msg: {
     role: string;
     text: string;
@@ -1083,6 +1093,7 @@ interface ResolvedOptions {
   tracking: ResolvedTracking;
   /** Resolved storage adapter — defaults to `LocalStorageAdapter`. */
   storage: ClientStorage;
+  userToken?: UserTokenSource;
   onMessage?: ChatWidgetOptions['onMessage'];
   onOpen?: ChatWidgetOptions['onOpen'];
   onClose?: ChatWidgetOptions['onClose'];
@@ -3383,6 +3394,18 @@ export interface ChatWidgetInstance {
    * Listeners added with `on()` stay.
    */
   reset: () => void;
+  /**
+   * Sign the visitor in as your logged-in user, after they log in to your site: `userToken` is a JWT your server
+   * signs with the deployment's secret key (`sub`, `exp`; optional `name`, `email`), or a function that returns a
+   * fresh one. The widget reconnects as that user: their earlier chats on this browser move to them, and their
+   * conversations follow them to any device. Call `reset()` when they log out.
+   *
+   * @example
+   * ```ts
+   * chat.login(async () => (await fetch('/api/help-ai-token')).text());
+   * ```
+   */
+  login: (userToken: UserTokenSource) => void;
   /**
    * Subscribe to a lifecycle event. Returns an `off` function. See
    * {@link EventMap} for the full set + payload shapes — currently
@@ -3526,4 +3549,4 @@ export declare const brand: {
   readonly domain: string;
   readonly siteUrl: string;
 };
-export type { AskOptions, Asset, BlocksConfig, ChatWidgetOptions, ConnectionConfig, ConnectionConfigPartial, EventMap, EventName, HandshakeResponse, HookListener, Link, LogEntry, LogLevel, OpenTarget, ResolvedOptions, ServerConfig, SiteConfig, WidgetConfig, WidgetConfigPartial, WidgetSettings, WidgetSettingsPartial, WidgetState };
+export type { AskOptions, Asset, BlocksConfig, ChatWidgetOptions, ConnectionConfig, ConnectionConfigPartial, EventMap, EventName, HandshakeResponse, HookListener, Link, LogEntry, LogLevel, OpenTarget, ResolvedOptions, ServerConfig, SiteConfig, UserTokenSource, WidgetConfig, WidgetConfigPartial, WidgetSettings, WidgetSettingsPartial, WidgetState };