@helpai/elements 1.1.12 → 1.1.14

package/index.d.ts

@@ -41,7 +41,7 @@ interface ClientStorage {
  * populated {@link Strings} map. UI components then read `strings.send` as a
  * normal property access — no per-render lookup, no per-render allocation.
  */
-type StringKey = "launcherOpen" | "launcherLabel" | "panelTitle" | "composerPlaceholder" | "send" | "stop" | "attach" | "micStart" | "micStop" | "micUnsupported" | "expand" | "collapse" | "fullscreen" | "exitFullscreen" | "resizeHandle" | "scrollToBottom" | "close" | "moreActions" | "soundOn" | "soundOff" | "language" | "theme" | "themeAuto" | "themeLight" | "themeDark" | "textSize" | "textSizeSmall" | "textSizeNormal" | "textSizeLarge" | "history" | "historyTitle" | "historyEmpty" | "historyLoading" | "historyBack" | "historyContinue" | "loadMoreConversations" | "conversationLoading" | "loadPreviousMessages" | "conversationClosed" | "startNewConversation" | "talkToOperator" | "connectingOperator" | "noOperatorAvailable" | "chattingWithOperator" | "cancelOperatorRequest" | "dateToday" | "dateYesterday" | "dateLastWeek" | "dateOlder" | "newConversation" | "dropZone" | "attachmentTooLarge" | "attachmentTooMany" | "attachmentMimeRejected" | "errorRetry" | "errorGeneric" | "errorRateLimited" | "loading" | "thinking" | "thoughts" | "toolResult" | "sources" | "feedbackUp" | "feedbackDown" | "feedbackThanks" | "copy" | "copied" | "collapseSidebar" | "expandSidebar" | "formSubmit" | "formSkip" | "formSubmitted" | "formSkipped" | "formFillOut" | "formRequired" | "formInvalidEmail" | "formInvalidTel" | "formInvalidUrl" | "formInvalidNumber" | "formTooShort" | "formTooLong" | "formNumberTooSmall" | "formNumberTooLarge" | "formPatternMismatch" | "formChooseAtLeast" | "formChooseAtMost" | "formOther" | "formOtherPlaceholder" | "inputRequired" | "inputBadge" | "inputAnswered" | "inputSkipped" | "inputSubmit" | "inputSubmitHint" | "inputSkip" | "showOptions" | "hideOptions" | "qtypeText" | "qtypeEmail" | "qtypePhone" | "qtypeNumber" | "qtypeDate" | "qtypeChooseOne" | "qtypeChooseAny" | "qtypeBoolean" | "confirmYes" | "confirmNo" | "approve" | "reject" | "approvalPrompt" | "approvalBody" | "approvalYourResponse" | "approvalEditHint" | "approvalSubmitting" | "edit" | "toolParameters" | "statusAwaiting" | "statusResponded" | "statusCompleted" | "statusDenied" | "statusError" | "statusRunning" | "statusSuperseded" | "tabHome" | "tabConversations" | "tabHelp" | "tabNews" | "modulesEmpty" | "moduleBack" | "contentLoading" | "homeGreeting" | "homeGreetingNamed" | "homeGreetingLead" | "homeSearchPlaceholder" | "homeContentTitle" | "homeStatus" | "helpTitle" | "helpSearchPlaceholder" | "helpEmpty" | "helpLoading" | "helpSearchEmpty" | "newsTitle" | "newsEmpty" | "newsLoading" | "newsBack" | "newsPublishedAt";
+type StringKey = "launcherOpen" | "launcherLabel" | "panelTitle" | "composerPlaceholder" | "send" | "stop" | "attach" | "micStart" | "micStop" | "micUnsupported" | "expand" | "collapse" | "fullscreen" | "exitFullscreen" | "popOut" | "resizeHandle" | "scrollToBottom" | "close" | "moreActions" | "soundOn" | "soundOff" | "language" | "theme" | "themeAuto" | "themeLight" | "themeDark" | "textSize" | "textSizeSmall" | "textSizeNormal" | "textSizeLarge" | "history" | "historyTitle" | "historyEmpty" | "historyLoading" | "historyBack" | "historyContinue" | "loadMoreConversations" | "conversationLoading" | "loadPreviousMessages" | "conversationClosed" | "startNewConversation" | "talkToOperator" | "connectingOperator" | "noOperatorAvailable" | "chattingWithOperator" | "cancelOperatorRequest" | "dateToday" | "dateYesterday" | "dateLastWeek" | "dateOlder" | "newConversation" | "dropZone" | "attachmentTooLarge" | "attachmentTooMany" | "attachmentMimeRejected" | "errorRetry" | "errorGeneric" | "errorRateLimited" | "loading" | "thinking" | "thoughts" | "toolResult" | "sources" | "feedbackUp" | "feedbackDown" | "feedbackThanks" | "copy" | "copied" | "collapseSidebar" | "expandSidebar" | "formSubmit" | "formSkip" | "formSubmitted" | "formSkipped" | "formFillOut" | "formRequired" | "formInvalidEmail" | "formInvalidTel" | "formInvalidUrl" | "formInvalidNumber" | "formTooShort" | "formTooLong" | "formNumberTooSmall" | "formNumberTooLarge" | "formPatternMismatch" | "formChooseAtLeast" | "formChooseAtMost" | "formOther" | "formOtherPlaceholder" | "inputRequired" | "inputBadge" | "inputAnswered" | "inputSkipped" | "inputSubmit" | "inputSubmitHint" | "inputSkip" | "showOptions" | "hideOptions" | "qtypeText" | "qtypeEmail" | "qtypePhone" | "qtypeNumber" | "qtypeDate" | "qtypeChooseOne" | "qtypeChooseAny" | "qtypeBoolean" | "confirmYes" | "confirmNo" | "approve" | "reject" | "approvalPrompt" | "approvalBody" | "approvalYourResponse" | "approvalEditHint" | "approvalSubmitting" | "edit" | "toolParameters" | "statusAwaiting" | "statusResponded" | "statusCompleted" | "statusDenied" | "statusError" | "statusRunning" | "statusSuperseded" | "tabHome" | "tabConversations" | "tabHelp" | "tabNews" | "modulesEmpty" | "moduleBack" | "contentLoading" | "homeGreeting" | "homeGreetingNamed" | "homeGreetingLead" | "homeSearchPlaceholder" | "homeContentTitle" | "homeStatus" | "helpTitle" | "helpSearchPlaceholder" | "helpEmpty" | "helpLoading" | "helpSearchEmpty" | "newsTitle" | "newsEmpty" | "newsLoading" | "newsBack" | "newsPublishedAt";
 /** A partial map for one locale — what overrides look like on the wire. */
 type LocaleStrings = Partial<Record<StringKey, string>>;
 /**
@@ -120,13 +120,14 @@ type ResponseMode = "streaming" | "buffered";
  * - `clear`       — Start a new conversation (compose icon).
  * - `expand`      — Toggle `normal` ↔ `expanded` (1.5× panel).
  * - `fullscreen`  — Toggle `normal` ↔ `fullscreen` (viewport fill).
+ * - `popOut`      — Open the active conversation in a dedicated tab.
  * - `sound`       — Toggle notification sounds + haptics on/off (switch-style).
  * - `language`    — Switch the UI locale at runtime.
  * - `theme`       — Cycle `auto` / `light` / `dark`.
  * - `textSize`    — Cycle `normal` / `large` / `small`.
  * - `close`       — Close the floating panel.
  */
-type ActionName = "clear" | "expand" | "fullscreen" | "sound" | "history" | "language" | "theme" | "textSize" | "close";
+type ActionName = "clear" | "expand" | "fullscreen" | "popOut" | "sound" | "history" | "language" | "theme" | "textSize" | "close";
 /**
  * The header's enabled actions. Unlisted actions are hidden; order is
  * irrelevant. Per-mode defaults (`DEFAULT_ACTIONS_BY_MODE`) pick a sensible
@@ -718,6 +719,8 @@ interface BehaviorOptions {
   disableMessageFeedback?: boolean;
   /** Auto-send a suggestion chip's text on tap. Unset/`false` = fill the composer to edit (default). */
   autoSendSuggestions?: boolean;
+  /** URL opened by the `popOut` header action. */
+  popOutUrl?: string;
 }
 /**
  * Section: panel header actions — the enabled set (`history`/`close` buttons +
@@ -772,7 +775,8 @@ interface FooterOptions {
  * and the agent purely as **informational context** — never as an auth
  * credential. The widget runs on third-party sites (e.g. `example.com`); some
  * have their own login, others are guest-only. We don't register or
- * authenticate these users (auth is the workspace `publicKey`).
+ * authenticate these users (browser access always identifies a deployment;
+ * a public key is optional for intentional guest mode).
  *
  * `id` / `email` / `name` are recognised fields used for the Home greeting and
  * transcripts; any extra scalar fields become custom context the agent can use
@@ -898,7 +902,9 @@ interface ResolvedTracking {
 //#region src/core/config/types/widget.d.ts
 /**
  * Raw options passed to {@link mount}, {@link init}, the Web Component, or
- * the `<script data-*>` auto-boot path. Every field is optional.
+ * the `<script data-*>` auto-boot path. The public `mount()` / `init()`
+ * boundary requires `aiAgentDeploymentId`; parsers keep it optional while
+ * assembling an attribute snapshot so a missing value can fail at that boundary.
  *
  * Two layers:
  *
@@ -922,9 +928,9 @@ interface ChatWidgetOptions {
    * cached userPrefs). Default: `"default"`.
    */
   widgetId?: string;
-  /** Workspace-scoped public key (`agent_pk_...`). Sent as `x-public-key`. */
+  /** Deployment public key (`agent_pk_...`). Sent as `x-public-key` when present. */
   publicKey?: string;
-  /** Deployment ID (UUID). Sent as `x-ai-agent-deployment-id`. */
+  /** Deployment ID (UUID). Required by every public mount and sent as `x-ai-agent-deployment-id`. */
   aiAgentDeploymentId?: string;
   /**
    * MAIN site origin (no trailing slash, e.g. `https://help.ai`). The API
@@ -1031,6 +1037,8 @@ interface ResolvedOptions {
   enableMessageFeedback: boolean;
   /** Auto-send a suggestion chip's text on tap (vs. filling the composer to edit). Default `false`. */
   autoSendSuggestions: boolean;
+  /** URL opened by the `popOut` action. Absent means the action is hidden. */
+  popOutUrl?: string;
   features: ResolvedFeatures;
   /** Resolved event-driven forms — ordered list + trigger index. */
   forms: ResolvedForms;
@@ -1556,7 +1564,7 @@ type Link = z.infer<typeof linkSchema>;
 declare const connectionConfigSchema: z.ZodObject<{
   widgetId: z.ZodDefault<z.ZodString>;
   publicKey: z.ZodOptional<z.ZodString>;
-  aiAgentDeploymentId: z.ZodOptional<z.ZodString>;
+  aiAgentDeploymentId: z.ZodString;
   baseUrl: z.ZodOptional<z.ZodString>;
   agentApiBaseUrl: z.ZodOptional<z.ZodString>;
   dataApiBaseUrl: z.ZodOptional<z.ZodString>;
@@ -1651,6 +1659,7 @@ declare const widgetSettingsSchema: z.ZodObject<{
     showSources: z.ZodDefault<z.ZodBoolean>;
     disableMessageFeedback: z.ZodDefault<z.ZodBoolean>;
     autoSendSuggestions: z.ZodDefault<z.ZodBoolean>;
+    popOutUrl: z.ZodOptional<z.ZodString>;
   }, z.core.$loose>>;
   theme: z.ZodDefault<z.ZodUnion<readonly [z.ZodEnum<{
     auto: "auto";
@@ -1703,6 +1712,7 @@ declare const widgetSettingsSchema: z.ZodObject<{
       fullscreen: "fullscreen";
       clear: "clear";
       theme: "theme";
+      popOut: "popOut";
       sound: "sound";
       history: "history";
       language: "language";
@@ -1902,7 +1912,7 @@ type WidgetSettings = z.infer<typeof widgetSettingsSchema>;
 declare const widgetConfigSchema: z.ZodObject<{
   widgetId: z.ZodDefault<z.ZodString>;
   publicKey: z.ZodOptional<z.ZodString>;
-  aiAgentDeploymentId: z.ZodOptional<z.ZodString>;
+  aiAgentDeploymentId: z.ZodString;
   baseUrl: z.ZodOptional<z.ZodString>;
   agentApiBaseUrl: z.ZodOptional<z.ZodString>;
   dataApiBaseUrl: z.ZodOptional<z.ZodString>;
@@ -1986,6 +1996,7 @@ declare const widgetConfigSchema: z.ZodObject<{
     showSources: z.ZodDefault<z.ZodBoolean>;
     disableMessageFeedback: z.ZodDefault<z.ZodBoolean>;
     autoSendSuggestions: z.ZodDefault<z.ZodBoolean>;
+    popOutUrl: z.ZodOptional<z.ZodString>;
   }, z.core.$loose>>;
   theme: z.ZodDefault<z.ZodUnion<readonly [z.ZodEnum<{
     auto: "auto";
@@ -2038,6 +2049,7 @@ declare const widgetConfigSchema: z.ZodObject<{
       fullscreen: "fullscreen";
       clear: "clear";
       theme: "theme";
+      popOut: "popOut";
       sound: "sound";
       history: "history";
       language: "language";
@@ -2236,7 +2248,7 @@ type WidgetConfig = z.infer<typeof widgetConfigSchema>;
 declare const widgetConfigPartialSchema: z.ZodObject<{
   widgetId: z.ZodOptional<z.ZodDefault<z.ZodString>>;
   publicKey: z.ZodOptional<z.ZodOptional<z.ZodString>>;
-  aiAgentDeploymentId: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+  aiAgentDeploymentId: z.ZodOptional<z.ZodString>;
   baseUrl: z.ZodOptional<z.ZodOptional<z.ZodString>>;
   agentApiBaseUrl: z.ZodOptional<z.ZodOptional<z.ZodString>>;
   dataApiBaseUrl: z.ZodOptional<z.ZodOptional<z.ZodString>>;
@@ -2320,6 +2332,7 @@ declare const widgetConfigPartialSchema: z.ZodObject<{
     showSources: z.ZodDefault<z.ZodBoolean>;
     disableMessageFeedback: z.ZodDefault<z.ZodBoolean>;
     autoSendSuggestions: z.ZodDefault<z.ZodBoolean>;
+    popOutUrl: z.ZodOptional<z.ZodString>;
   }, z.core.$loose>>>;
   theme: z.ZodOptional<z.ZodDefault<z.ZodUnion<readonly [z.ZodEnum<{
     auto: "auto";
@@ -2372,6 +2385,7 @@ declare const widgetConfigPartialSchema: z.ZodObject<{
       fullscreen: "fullscreen";
       clear: "clear";
       theme: "theme";
+      popOut: "popOut";
       sound: "sound";
       history: "history";
       language: "language";
@@ -2614,6 +2628,7 @@ declare const widgetSettingsPartialSchema: z.ZodObject<{
     showSources: z.ZodDefault<z.ZodBoolean>;
     disableMessageFeedback: z.ZodDefault<z.ZodBoolean>;
     autoSendSuggestions: z.ZodDefault<z.ZodBoolean>;
+    popOutUrl: z.ZodOptional<z.ZodString>;
   }, z.core.$loose>>>;
   theme: z.ZodOptional<z.ZodDefault<z.ZodUnion<readonly [z.ZodEnum<{
     auto: "auto";
@@ -2666,6 +2681,7 @@ declare const widgetSettingsPartialSchema: z.ZodObject<{
       fullscreen: "fullscreen";
       clear: "clear";
       theme: "theme";
+      popOut: "popOut";
       sound: "sound";
       history: "history";
       language: "language";
@@ -2859,7 +2875,7 @@ type WidgetSettingsPartial = z.infer<typeof widgetSettingsPartialSchema>;
 declare const connectionConfigPartialSchema: z.ZodObject<{
   widgetId: z.ZodOptional<z.ZodDefault<z.ZodString>>;
   publicKey: z.ZodOptional<z.ZodOptional<z.ZodString>>;
-  aiAgentDeploymentId: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+  aiAgentDeploymentId: z.ZodOptional<z.ZodString>;
   baseUrl: z.ZodOptional<z.ZodOptional<z.ZodString>>;
   agentApiBaseUrl: z.ZodOptional<z.ZodOptional<z.ZodString>>;
   dataApiBaseUrl: z.ZodOptional<z.ZodOptional<z.ZodString>>;
@@ -2966,6 +2982,7 @@ declare const serverConfigSchema: z.ZodObject<{
     showSources: z.ZodDefault<z.ZodBoolean>;
     disableMessageFeedback: z.ZodDefault<z.ZodBoolean>;
     autoSendSuggestions: z.ZodDefault<z.ZodBoolean>;
+    popOutUrl: z.ZodOptional<z.ZodString>;
   }, z.core.$loose>>>;
   theme: z.ZodOptional<z.ZodDefault<z.ZodUnion<readonly [z.ZodEnum<{
     auto: "auto";
@@ -3018,6 +3035,7 @@ declare const serverConfigSchema: z.ZodObject<{
       fullscreen: "fullscreen";
       clear: "clear";
       theme: "theme";
+      popOut: "popOut";
       sound: "sound";
       history: "history";
       language: "language";
@@ -3252,6 +3270,7 @@ declare const handshakeResponseSchema: z.ZodObject<{
       showSources: z.ZodDefault<z.ZodBoolean>;
       disableMessageFeedback: z.ZodDefault<z.ZodBoolean>;
       autoSendSuggestions: z.ZodDefault<z.ZodBoolean>;
+      popOutUrl: z.ZodOptional<z.ZodString>;
     }, z.core.$loose>>>;
     theme: z.ZodOptional<z.ZodDefault<z.ZodUnion<readonly [z.ZodEnum<{
       auto: "auto";
@@ -3304,6 +3323,7 @@ declare const handshakeResponseSchema: z.ZodObject<{
         fullscreen: "fullscreen";
         clear: "clear";
         theme: "theme";
+        popOut: "popOut";
         sound: "sound";
         history: "history";
         language: "language";
@@ -3569,15 +3589,16 @@ interface ChatWidgetInstance {
  *
  * @example Single widget (default):
  * ```ts
- * mount({ publicKey, presentation: { mode: 'inline' }, target: document.getElementById('chat') });
+ * mount({ publicKey, aiAgentDeploymentId, presentation: { mode: 'inline' }, target: document.getElementById('chat') });
  * ```
  * @example Two widgets on one page:
  * ```ts
- * mount({ widgetId: 'support', publicKey: KEY_A, target: supportEl });
- * mount({ widgetId: 'sales',   publicKey: KEY_B, target: salesEl });
+ * mount({ widgetId: 'support', publicKey: KEY_A, aiAgentDeploymentId: DEPLOYMENT_A, target: supportEl });
+ * mount({ widgetId: 'sales', publicKey: KEY_B, aiAgentDeploymentId: DEPLOYMENT_B, target: salesEl });
  * ```
  */
 declare function mount(opts: ChatWidgetOptions & {
+  aiAgentDeploymentId: string;
   target?: HTMLElement;
 }): ChatWidgetInstance;
 /**
@@ -3586,6 +3607,7 @@ declare function mount(opts: ChatWidgetOptions & {
  * behaves like {@link mount}. Safe to call on every route change in an SPA.
  */
 declare function init(opts: ChatWidgetOptions & {
+  aiAgentDeploymentId: string;
   target?: HTMLElement;
 }): ChatWidgetInstance;
 /**