@helpai/elements 1.8.0 → 1.10.0

package/index.d.ts

@@ -93,8 +93,8 @@ type Position = 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
 type Mode = 'floating' | 'inline' | 'standalone' | 'page' | 'modal' | 'drawer';
 /** End-user text-size preference — scales the whole type ramp. */
 type TextSize = 'small' | 'normal' | 'large';
-/** Theme preference. `auto` follows `prefers-color-scheme`. */
-type ThemePreference = 'auto' | 'light' | 'dark';
+/** Theme preference. `auto` follows `prefers-color-scheme`; `host` follows the page's own light/dark. */
+type ThemePreference = 'auto' | 'light' | 'dark' | 'host';
 /**
  * How the assistant's reply is delivered.
  *
@@ -591,6 +591,8 @@ interface ResolvedModules {
 }
 /** CSS-custom-property overrides applied as inline styles on the host. */
 interface ThemeOverrides {
+  /** Light/dark beside the overrides — `host` keeps a deployment's accent while the page sets the mode. */
+  mode?: ThemePreference;
   accent?: string;
   accentText?: string;
   radius?: string;
@@ -896,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
@@ -971,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;
@@ -1081,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'];
@@ -1211,8 +1224,15 @@ declare const widgetSettingsSchema: z.ZodObject<{
   theme: z.ZodDefault<z.ZodUnion<readonly [z.ZodEnum<{
     auto: "auto";
     dark: "dark";
+    host: "host";
     light: "light";
   }>, z.ZodObject<{
+    mode: z.ZodOptional<z.ZodEnum<{
+      auto: "auto";
+      dark: "dark";
+      host: "host";
+      light: "light";
+    }>>;
     accent: z.ZodOptional<z.ZodString>;
     accentText: z.ZodOptional<z.ZodString>;
     radius: z.ZodOptional<z.ZodString>;
@@ -1546,8 +1566,15 @@ declare const widgetConfigSchema: z.ZodObject<{
   theme: z.ZodDefault<z.ZodUnion<readonly [z.ZodEnum<{
     auto: "auto";
     dark: "dark";
+    host: "host";
     light: "light";
   }>, z.ZodObject<{
+    mode: z.ZodOptional<z.ZodEnum<{
+      auto: "auto";
+      dark: "dark";
+      host: "host";
+      light: "light";
+    }>>;
     accent: z.ZodOptional<z.ZodString>;
     accentText: z.ZodOptional<z.ZodString>;
     radius: z.ZodOptional<z.ZodString>;
@@ -1882,8 +1909,15 @@ declare const widgetConfigPartialSchema: z.ZodObject<{
   theme: z.ZodOptional<z.ZodDefault<z.ZodUnion<readonly [z.ZodEnum<{
     auto: "auto";
     dark: "dark";
+    host: "host";
     light: "light";
   }>, z.ZodObject<{
+    mode: z.ZodOptional<z.ZodEnum<{
+      auto: "auto";
+      dark: "dark";
+      host: "host";
+      light: "light";
+    }>>;
     accent: z.ZodOptional<z.ZodString>;
     accentText: z.ZodOptional<z.ZodString>;
     radius: z.ZodOptional<z.ZodString>;
@@ -2180,8 +2214,15 @@ declare const widgetSettingsPartialSchema: z.ZodObject<{
   theme: z.ZodOptional<z.ZodDefault<z.ZodUnion<readonly [z.ZodEnum<{
     auto: "auto";
     dark: "dark";
+    host: "host";
     light: "light";
   }>, z.ZodObject<{
+    mode: z.ZodOptional<z.ZodEnum<{
+      auto: "auto";
+      dark: "dark";
+      host: "host";
+      light: "light";
+    }>>;
     accent: z.ZodOptional<z.ZodString>;
     accentText: z.ZodOptional<z.ZodString>;
     radius: z.ZodOptional<z.ZodString>;
@@ -2532,8 +2573,15 @@ declare const serverConfigSchema: z.ZodObject<{
   theme: z.ZodOptional<z.ZodDefault<z.ZodUnion<readonly [z.ZodEnum<{
     auto: "auto";
     dark: "dark";
+    host: "host";
     light: "light";
   }>, z.ZodObject<{
+    mode: z.ZodOptional<z.ZodEnum<{
+      auto: "auto";
+      dark: "dark";
+      host: "host";
+      light: "light";
+    }>>;
     accent: z.ZodOptional<z.ZodString>;
     accentText: z.ZodOptional<z.ZodString>;
     radius: z.ZodOptional<z.ZodString>;
@@ -2820,8 +2868,15 @@ declare const handshakeResponseSchema: z.ZodObject<{
     theme: z.ZodOptional<z.ZodDefault<z.ZodUnion<readonly [z.ZodEnum<{
       auto: "auto";
       dark: "dark";
+      host: "host";
       light: "light";
     }>, z.ZodObject<{
+      mode: z.ZodOptional<z.ZodEnum<{
+        auto: "auto";
+        dark: "dark";
+        host: "host";
+        light: "light";
+      }>>;
       accent: z.ZodOptional<z.ZodString>;
       accentText: z.ZodOptional<z.ZodString>;
       radius: z.ZodOptional<z.ZodString>;
@@ -3174,6 +3229,24 @@ interface EventMap {
     previous: string;
     current: string;
   };
+  /** The widget's state changed — open, ready, unread or the conversation. Payload is the whole new state. */
+  state: WidgetState;
+  /** How many conversations have replies the visitor hasn't read changed. Payload is the new count. */
+  unread: number;
+}
+/** What a page can read about the widget at any moment (`chat.state`), and the `state` event's payload. */
+interface WidgetState {
+  /** The panel is showing. Always `true` for `inline`, `page` and `standalone`. */
+  open: boolean;
+  /** The widget has connected (its first handshake settled) and takes commands right away. */
+  ready: boolean;
+  /**
+   * Conversations with replies the visitor hasn't read. Known once the widget has been opened in this page load
+   * (a closed widget makes no requests beyond the handshake), and kept live from then on.
+   */
+  unread: number;
+  /** The visitor's current conversation, once there is one. */
+  conversationId?: string;
 }
 type EventName = keyof EventMap;
 /**
@@ -3302,6 +3375,37 @@ export interface ChatWidgetInstance {
    * ```
    */
   ask: (text: string, options?: AskOptions) => void;
+  /**
+   * The widget's state right now: `open`, `ready`, `unread` (conversations with unread replies) and the current
+   * `conversationId`. The `state` event delivers each change; `unread` fires when the count changes.
+   *
+   * @example
+   * ```ts
+   * helpLink.dataset.unread = String(chat.state.unread);
+   * chat.on('unread', (count) => (helpLink.dataset.unread = String(count)));
+   * ```
+   */
+  readonly state: WidgetState;
+  /** Resolves once the widget has connected; commands sent after it act at once. Resolves once, never rejects. */
+  readonly ready: Promise<void>;
+  /**
+   * Start over as a new anonymous visitor — call it when your user logs out. Forgets the stored visitor, their current
+   * conversation, preferences and the user context set with `setUserContext`, then reconnects as a first visit.
+   * 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
@@ -3445,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 };
+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 };