@helpai/elements 6.4.10 → 6.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/configurator.mjs +1 -1
- package/docs/configuration.md +1 -1
- package/docs/installation.md +1 -1
- package/docs/page-tools.md +16 -13
- package/elements-web-component.esm.js +47 -45
- package/elements-web-component.esm.js.map +4 -4
- package/elements.cjs.js +47 -45
- package/elements.cjs.js.map +4 -4
- package/elements.esm.js +47 -45
- package/elements.esm.js.map +4 -4
- package/elements.js +47 -45
- package/elements.js.map +4 -4
- package/index.d.ts +71 -15
- package/index.mjs +19 -19
- package/llms-full.txt +158 -155
- package/llms.txt +19 -19
- package/package.json +7 -1
- package/react.d.ts +71 -15
- package/react.mjs +38 -38
- package/schema.d.ts +49 -7
- package/schema.json +52 -10
- package/schema.mjs +1 -1
- package/step-display.d.ts +215 -0
- package/step-display.mjs +2 -0
- package/style.css +1 -1
- package/web-component.d.ts +49 -9
- package/web-component.mjs +19 -19
package/schema.d.ts
CHANGED
|
@@ -125,7 +125,13 @@ export declare const behaviorSchema: z.ZodObject<{
|
|
|
125
125
|
streaming: "streaming";
|
|
126
126
|
}>>;
|
|
127
127
|
showReasoning: z.ZodDefault<z.ZodBoolean>;
|
|
128
|
-
|
|
128
|
+
stepDisplay: z.ZodOptional<z.ZodObject<{
|
|
129
|
+
showSteps: z.ZodOptional<z.ZodBoolean>;
|
|
130
|
+
showStepDetails: z.ZodOptional<z.ZodBoolean>;
|
|
131
|
+
showStepSystem: z.ZodOptional<z.ZodBoolean>;
|
|
132
|
+
showDecidedBy: z.ZodOptional<z.ZodBoolean>;
|
|
133
|
+
foldApprovals: z.ZodOptional<z.ZodBoolean>;
|
|
134
|
+
}, z.core.$strip>>;
|
|
129
135
|
showSources: z.ZodDefault<z.ZodBoolean>;
|
|
130
136
|
disableMessageFeedback: z.ZodDefault<z.ZodBoolean>;
|
|
131
137
|
autoSendSuggestions: z.ZodDefault<z.ZodBoolean>;
|
|
@@ -716,7 +722,13 @@ export declare const widgetSettingsSchema: z.ZodObject<{
|
|
|
716
722
|
streaming: "streaming";
|
|
717
723
|
}>>;
|
|
718
724
|
showReasoning: z.ZodDefault<z.ZodBoolean>;
|
|
719
|
-
|
|
725
|
+
stepDisplay: z.ZodOptional<z.ZodObject<{
|
|
726
|
+
showSteps: z.ZodOptional<z.ZodBoolean>;
|
|
727
|
+
showStepDetails: z.ZodOptional<z.ZodBoolean>;
|
|
728
|
+
showStepSystem: z.ZodOptional<z.ZodBoolean>;
|
|
729
|
+
showDecidedBy: z.ZodOptional<z.ZodBoolean>;
|
|
730
|
+
foldApprovals: z.ZodOptional<z.ZodBoolean>;
|
|
731
|
+
}, z.core.$strip>>;
|
|
720
732
|
showSources: z.ZodDefault<z.ZodBoolean>;
|
|
721
733
|
disableMessageFeedback: z.ZodDefault<z.ZodBoolean>;
|
|
722
734
|
autoSendSuggestions: z.ZodDefault<z.ZodBoolean>;
|
|
@@ -995,7 +1007,13 @@ export declare const widgetConfigSchema: z.ZodObject<{
|
|
|
995
1007
|
streaming: "streaming";
|
|
996
1008
|
}>>;
|
|
997
1009
|
showReasoning: z.ZodDefault<z.ZodBoolean>;
|
|
998
|
-
|
|
1010
|
+
stepDisplay: z.ZodOptional<z.ZodObject<{
|
|
1011
|
+
showSteps: z.ZodOptional<z.ZodBoolean>;
|
|
1012
|
+
showStepDetails: z.ZodOptional<z.ZodBoolean>;
|
|
1013
|
+
showStepSystem: z.ZodOptional<z.ZodBoolean>;
|
|
1014
|
+
showDecidedBy: z.ZodOptional<z.ZodBoolean>;
|
|
1015
|
+
foldApprovals: z.ZodOptional<z.ZodBoolean>;
|
|
1016
|
+
}, z.core.$strip>>;
|
|
999
1017
|
showSources: z.ZodDefault<z.ZodBoolean>;
|
|
1000
1018
|
disableMessageFeedback: z.ZodDefault<z.ZodBoolean>;
|
|
1001
1019
|
autoSendSuggestions: z.ZodDefault<z.ZodBoolean>;
|
|
@@ -1275,7 +1293,13 @@ export declare const widgetConfigPartialSchema: z.ZodObject<{
|
|
|
1275
1293
|
streaming: "streaming";
|
|
1276
1294
|
}>>;
|
|
1277
1295
|
showReasoning: z.ZodDefault<z.ZodBoolean>;
|
|
1278
|
-
|
|
1296
|
+
stepDisplay: z.ZodOptional<z.ZodObject<{
|
|
1297
|
+
showSteps: z.ZodOptional<z.ZodBoolean>;
|
|
1298
|
+
showStepDetails: z.ZodOptional<z.ZodBoolean>;
|
|
1299
|
+
showStepSystem: z.ZodOptional<z.ZodBoolean>;
|
|
1300
|
+
showDecidedBy: z.ZodOptional<z.ZodBoolean>;
|
|
1301
|
+
foldApprovals: z.ZodOptional<z.ZodBoolean>;
|
|
1302
|
+
}, z.core.$strip>>;
|
|
1279
1303
|
showSources: z.ZodDefault<z.ZodBoolean>;
|
|
1280
1304
|
disableMessageFeedback: z.ZodDefault<z.ZodBoolean>;
|
|
1281
1305
|
autoSendSuggestions: z.ZodDefault<z.ZodBoolean>;
|
|
@@ -1517,7 +1541,13 @@ export declare const widgetSettingsPartialSchema: z.ZodObject<{
|
|
|
1517
1541
|
streaming: "streaming";
|
|
1518
1542
|
}>>;
|
|
1519
1543
|
showReasoning: z.ZodDefault<z.ZodBoolean>;
|
|
1520
|
-
|
|
1544
|
+
stepDisplay: z.ZodOptional<z.ZodObject<{
|
|
1545
|
+
showSteps: z.ZodOptional<z.ZodBoolean>;
|
|
1546
|
+
showStepDetails: z.ZodOptional<z.ZodBoolean>;
|
|
1547
|
+
showStepSystem: z.ZodOptional<z.ZodBoolean>;
|
|
1548
|
+
showDecidedBy: z.ZodOptional<z.ZodBoolean>;
|
|
1549
|
+
foldApprovals: z.ZodOptional<z.ZodBoolean>;
|
|
1550
|
+
}, z.core.$strip>>;
|
|
1521
1551
|
showSources: z.ZodDefault<z.ZodBoolean>;
|
|
1522
1552
|
disableMessageFeedback: z.ZodDefault<z.ZodBoolean>;
|
|
1523
1553
|
autoSendSuggestions: z.ZodDefault<z.ZodBoolean>;
|
|
@@ -1814,7 +1844,13 @@ export declare const serverConfigSchema: z.ZodObject<{
|
|
|
1814
1844
|
streaming: "streaming";
|
|
1815
1845
|
}>>;
|
|
1816
1846
|
showReasoning: z.ZodDefault<z.ZodBoolean>;
|
|
1817
|
-
|
|
1847
|
+
stepDisplay: z.ZodOptional<z.ZodObject<{
|
|
1848
|
+
showSteps: z.ZodOptional<z.ZodBoolean>;
|
|
1849
|
+
showStepDetails: z.ZodOptional<z.ZodBoolean>;
|
|
1850
|
+
showStepSystem: z.ZodOptional<z.ZodBoolean>;
|
|
1851
|
+
showDecidedBy: z.ZodOptional<z.ZodBoolean>;
|
|
1852
|
+
foldApprovals: z.ZodOptional<z.ZodBoolean>;
|
|
1853
|
+
}, z.core.$strip>>;
|
|
1818
1854
|
showSources: z.ZodDefault<z.ZodBoolean>;
|
|
1819
1855
|
disableMessageFeedback: z.ZodDefault<z.ZodBoolean>;
|
|
1820
1856
|
autoSendSuggestions: z.ZodDefault<z.ZodBoolean>;
|
|
@@ -2133,7 +2169,13 @@ export declare const handshakeResponseSchema: z.ZodObject<{
|
|
|
2133
2169
|
streaming: "streaming";
|
|
2134
2170
|
}>>;
|
|
2135
2171
|
showReasoning: z.ZodDefault<z.ZodBoolean>;
|
|
2136
|
-
|
|
2172
|
+
stepDisplay: z.ZodOptional<z.ZodObject<{
|
|
2173
|
+
showSteps: z.ZodOptional<z.ZodBoolean>;
|
|
2174
|
+
showStepDetails: z.ZodOptional<z.ZodBoolean>;
|
|
2175
|
+
showStepSystem: z.ZodOptional<z.ZodBoolean>;
|
|
2176
|
+
showDecidedBy: z.ZodOptional<z.ZodBoolean>;
|
|
2177
|
+
foldApprovals: z.ZodOptional<z.ZodBoolean>;
|
|
2178
|
+
}, z.core.$strip>>;
|
|
2137
2179
|
showSources: z.ZodDefault<z.ZodBoolean>;
|
|
2138
2180
|
disableMessageFeedback: z.ZodDefault<z.ZodBoolean>;
|
|
2139
2181
|
autoSendSuggestions: z.ZodDefault<z.ZodBoolean>;
|
package/schema.json
CHANGED
|
@@ -480,10 +480,32 @@
|
|
|
480
480
|
"description": "Show the model's reasoning (\"thoughts\") as a collapsible block above each answer. `false` (default) hides it — a loading indicator still shows while the model works. Reasoning is absent from durable history, but the current turn's short-lived resume backlog may replay it after an immediate reconnect or reload.",
|
|
481
481
|
"type": "boolean"
|
|
482
482
|
},
|
|
483
|
-
"
|
|
484
|
-
"
|
|
485
|
-
"
|
|
486
|
-
"
|
|
483
|
+
"stepDisplay": {
|
|
484
|
+
"description": "How the AI's steps and approvals show. Unset keys take the Simple preset: steps, details, system and who decided off; approvals folded. An approval always shows what it will do.",
|
|
485
|
+
"type": "object",
|
|
486
|
+
"properties": {
|
|
487
|
+
"showSteps": {
|
|
488
|
+
"description": "Every step the AI takes (a search, an order) appears as one folded line under the reply. Off: only the steps that involve the visitor.",
|
|
489
|
+
"type": "boolean"
|
|
490
|
+
},
|
|
491
|
+
"showStepDetails": {
|
|
492
|
+
"description": "Each step opens to its raw input and result. Off: a step shows only its labelled values, never raw data or ids.",
|
|
493
|
+
"type": "boolean"
|
|
494
|
+
},
|
|
495
|
+
"showStepSystem": {
|
|
496
|
+
"description": "The system that ran a step follows its name, such as \"Cancel an order · BC Co. shop\".",
|
|
497
|
+
"type": "boolean"
|
|
498
|
+
},
|
|
499
|
+
"showDecidedBy": {
|
|
500
|
+
"description": "Each approval says who decided it, and steps the rules decided show as steps. Off: a rules decision shows only its outcome; the visitor's own choice always shows.",
|
|
501
|
+
"type": "boolean"
|
|
502
|
+
},
|
|
503
|
+
"foldApprovals": {
|
|
504
|
+
"description": "A decided approval folds into the steps line. Off: it stays in the reply as a card.",
|
|
505
|
+
"type": "boolean"
|
|
506
|
+
}
|
|
507
|
+
},
|
|
508
|
+
"additionalProperties": false
|
|
487
509
|
},
|
|
488
510
|
"showSources": {
|
|
489
511
|
"default": false,
|
|
@@ -518,7 +540,6 @@
|
|
|
518
540
|
"startMinimized",
|
|
519
541
|
"responseMode",
|
|
520
542
|
"showReasoning",
|
|
521
|
-
"showToolCalls",
|
|
522
543
|
"showSources",
|
|
523
544
|
"disableMessageFeedback",
|
|
524
545
|
"autoSendSuggestions",
|
|
@@ -1966,10 +1987,32 @@
|
|
|
1966
1987
|
"description": "Show the model's reasoning (\"thoughts\") as a collapsible block above each answer. `false` (default) hides it — a loading indicator still shows while the model works. Reasoning is absent from durable history, but the current turn's short-lived resume backlog may replay it after an immediate reconnect or reload.",
|
|
1967
1988
|
"type": "boolean"
|
|
1968
1989
|
},
|
|
1969
|
-
"
|
|
1970
|
-
"
|
|
1971
|
-
"
|
|
1972
|
-
"
|
|
1990
|
+
"stepDisplay": {
|
|
1991
|
+
"description": "How the AI's steps and approvals show. Unset keys take the Simple preset: steps, details, system and who decided off; approvals folded. An approval always shows what it will do.",
|
|
1992
|
+
"type": "object",
|
|
1993
|
+
"properties": {
|
|
1994
|
+
"showSteps": {
|
|
1995
|
+
"description": "Every step the AI takes (a search, an order) appears as one folded line under the reply. Off: only the steps that involve the visitor.",
|
|
1996
|
+
"type": "boolean"
|
|
1997
|
+
},
|
|
1998
|
+
"showStepDetails": {
|
|
1999
|
+
"description": "Each step opens to its raw input and result. Off: a step shows only its labelled values, never raw data or ids.",
|
|
2000
|
+
"type": "boolean"
|
|
2001
|
+
},
|
|
2002
|
+
"showStepSystem": {
|
|
2003
|
+
"description": "The system that ran a step follows its name, such as \"Cancel an order · BC Co. shop\".",
|
|
2004
|
+
"type": "boolean"
|
|
2005
|
+
},
|
|
2006
|
+
"showDecidedBy": {
|
|
2007
|
+
"description": "Each approval says who decided it, and steps the rules decided show as steps. Off: a rules decision shows only its outcome; the visitor's own choice always shows.",
|
|
2008
|
+
"type": "boolean"
|
|
2009
|
+
},
|
|
2010
|
+
"foldApprovals": {
|
|
2011
|
+
"description": "A decided approval folds into the steps line. Off: it stays in the reply as a card.",
|
|
2012
|
+
"type": "boolean"
|
|
2013
|
+
}
|
|
2014
|
+
},
|
|
2015
|
+
"additionalProperties": false
|
|
1973
2016
|
},
|
|
1974
2017
|
"showSources": {
|
|
1975
2018
|
"default": false,
|
|
@@ -2004,7 +2047,6 @@
|
|
|
2004
2047
|
"startMinimized",
|
|
2005
2048
|
"responseMode",
|
|
2006
2049
|
"showReasoning",
|
|
2007
|
-
"showToolCalls",
|
|
2008
2050
|
"showSources",
|
|
2009
2051
|
"disableMessageFeedback",
|
|
2010
2052
|
"autoSendSuggestions",
|
package/schema.mjs
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
|
-
import{z as e}from"zod";const t=e.object({url:e.string().min(1).max(2048).describe(`Public URL of the image. Must be a full URL or root-relative path.`),alt:e.string().min(1).max(200).optional().describe(`Alt text for screen readers. Omit only for purely decorative images.`)}).strict().describe(`A single image asset (logo, hero, icon).`),n=e.object({id:e.string().min(1).max(100).optional().describe(`Stable id: the Preact key, the analytics target, and how its translations find it.`),label:e.string().min(1).max(120).describe(`Visible link text.`),href:e.string().min(1).max(2048).optional().describe(`Click target. Optional — when omitted the link renders as a non-clickable heading.`),icon:e.string().min(1).max(100).optional().describe(`Built-in icon preset name (chat / spark / message / help / wand) or a custom string.`),description:e.string().min(1).max(300).optional().describe(`Subtitle shown below the label. Used by link cards in page mode.`)}).loose().describe(`A navigation link / link card.`),r=e.string().min(1).max(120).describe("Any CSS length — `640px`, `80vh`, `calc(100vh - 64px)`, etc. Validated only for size, not syntax."),i=e.string().min(1).max(120).describe("Any CSS colour — hex, `rgb()`, `hsl()`, `oklch()`, a named colour, or a `var(--token)`."),a=e.string().min(1).max(35).describe("BCP-47 locale tag (e.g. `en`, `fr-CA`, `zh-Hant-HK`)."),o=e.uuidv7().describe(`UUID v7 (RFC 9562) — the single id format for visitor / conversation / message / file / content ids.`),s=e.object({name:e.string().max(120).optional().describe('The persona visitors chat with, such as `Bea`. May be an i18n key resolved against `i18n.strings`. Set, a labelled launcher with no `label` reads "Ask Bea" in the visitor\'s language.'),title:e.string().max(200).optional().describe(`The line under the name in the chat header. May be an i18n key.`),avatar:e.url({protocol:/^https?$/}).max(2048).optional().describe(`The persona's picture, a rounded square in the chat header. Unset = the name's initials.`)}).loose().describe(`The assistant persona: its name, subtitle and picture in the chat header.`).meta({examples:[{name:`Bea`,title:`Store assistant`,avatar:`https://cdn.example.com/bea.png`}]}),c=e.enum([`normal`,`expanded`,`fullscreen`,`auto`]),l=e.object({enabled:e.boolean().default(!0).describe("Show a resize handle (default on): a corner grip on the floating panel, the inner edge of a drawer. Hidden in every other mode and on phones, where the panel is edge to edge. `false` turns it off."),minWidth:r.optional().describe("Smallest width the user can drag the panel to. Default `320px`."),maxWidth:r.optional().describe(`Largest width the user can drag the panel to.`),minHeight:r.optional().describe("Smallest height the user can drag the floating panel to. Default `400px`."),maxHeight:r.optional().describe(`Largest height the user can drag the floating panel to.`)}).loose().describe("Drag-resize controls. While `enabled` (the default), visitors resize the floating panel from its corner or a drawer from its inner edge, by pointer or arrow keys, within the min/max bounds; the size is remembered.").meta({examples:[{enabled:!1},{enabled:!0,minWidth:`320px`,maxWidth:`720px`,minHeight:`400px`,maxHeight:`90vh`}]}),u=e.object({width:r.optional().describe("Panel width (CSS length). Mode-specific defaults — floating `380px`, modal `min(960px, 92vw)`, drawer `clamp(440px, 32vw, 640px)`. Set this to override; inline/standalone/page modes ignore it."),height:r.optional().describe("Panel height (CSS length). Mode-specific defaults — floating `600px`, modal `min(720px, 88vh)`, drawer `100vh` (clamped to `100vh − inset-y × 2`). Set this to override."),expanded:e.object({width:r.optional().describe(`Width when the user clicks the expand button.`),height:r.optional().describe(`Height when the user clicks the expand button.`)}).loose().optional().describe("Dimensions when the panel is in its `expanded` tier (between normal and fullscreen). Applies to floating / modal / drawer; ignored in inline / standalone / page where the panel always fills its parent."),resize:l.optional().describe(`Drag-resize controls — a corner grip on the floating panel, the inner edge of a drawer.`),inset:r.optional().describe("Drawer-mode edge inset — gap from each viewport edge (top/bottom/left/right). Single value applied to all four sides. Defaults to `3vh` vertical / `12px` horizontal. Use `0` for a full-edge drawer (no gap), or `5vh` for a centered-looking flyout with extra breathing room. Ignored by every other mode."),initialSize:c.default(`auto`).describe("Which size tier to open with on the first mount: `normal` / `expanded` / `fullscreen` / `auto`. Default `auto` is responsive by viewport: phones (< 640 px) open `fullscreen` edge-to-edge, tablets (640 px … `autoSizeBreakpoint`) open `normal`, and desktop/laptop (≥ `autoSizeBreakpoint`) open `expanded` — so the panel is right for the device out of the box. Set a literal to pin one tier everywhere; the user's own resize is remembered per-device and wins on reload."),autoSizeBreakpoint:e.number().int().min(0).max(1e4).default(900).describe("Viewport width (px) at/above which `initialSize: auto` opens `expanded` instead of `normal`. (Phones below 640 px always open `fullscreen`.)")}).loose().describe("Panel dimensions and drawer inset. Width/height override the mode-specific defaults (floating compact popover, modal centered dialog, drawer flyout). `inset` only affects drawer mode.").meta({examples:[{width:`420px`,height:`640px`},{width:`min(560px, 92vw)`,height:`min(640px, 90vh)`},{width:`420px`,expanded:{width:`640px`,height:`780px`},initialSize:`auto`,autoSizeBreakpoint:900},{width:`min(1100px, 95vw)`,height:`min(820px, 92vh)`},{width:`360px`,inset:`8vh`},{width:`420px`,height:`100vh`,inset:`0`},{width:`420px`,height:`60vh`,inset:`20vh`}]}),ee=e.enum([`floating`,`inline`,`standalone`,`page`,`modal`,`drawer`]),d=e.enum([`bottom-right`,`bottom-left`,`top-right`,`top-left`]),f=e.object({mode:ee.default(`floating`).describe("Rendering shape. `floating` (FAB + popover), `inline` (in-flow block), `standalone` (full viewport), `page` (sidebar + chat), `modal` (centered overlay), `drawer` (side dock)."),position:d.optional().describe("Anchor corner. `floating` uses it for the FAB; `drawer` uses the `*-left` / `*-right` suffix to pick the dock side. Unset is Automatic: bottom-right, or bottom-left when the chat reads right to left. A set corner is fixed. Ignored in other modes."),size:u.optional().describe("Panel dimensions. Mode-aware defaults (floating compact popover, modal centered dialog, drawer flyout) — fields here override them. Includes `inset` (drawer flyout gap), `expanded` tier, drag-resize grip.")}).loose().describe(`Layout fundamentals — mode, anchor corner, panel size + drawer inset.`).meta({examples:[{mode:`floating`,position:`bottom-right`},{mode:`modal`,size:{width:`min(1100px, 95vw)`,height:`min(820px, 92vh)`}},{mode:`drawer`,position:`bottom-right`},{mode:`drawer`,position:`top-right`,size:{width:`360px`,inset:`8vh`}},{mode:`drawer`,position:`bottom-right`,size:{width:`420px`,height:`100vh`,inset:`0`}}]}),p=e.enum([`streaming`,`buffered`]),m=e.object({startMinimized:e.boolean().default(!0).describe("Don't auto-open the floating panel on first visit. `true` (default) shows the FAB collapsed; `false` opens the panel on mount."),responseMode:p.default(`streaming`).describe("How the assistant's reply arrives. `streaming` (default) types tokens as they generate; `buffered` waits + shows the full reply at once."),showReasoning:e.boolean().default(!1).describe(`Show the model's reasoning ("thoughts") as a collapsible block above each answer. \`false\` (default) hides it — a loading indicator still shows while the model works. Reasoning is absent from durable history, but the current turn's short-lived resume backlog may replay it after an immediate reconnect or reload.`),showToolCalls:e.boolean().default(!1).describe("Show automatic tool/function calls the model makes (e.g. search) as collapsible detail+result cards in the transcript. `false` (default) hides them. Interactive tools (ask-questions / approval) always show."),showSources:e.boolean().default(!1).describe("Show the citation sources behind an answer (web links + document/file references) in the transcript. `false` (default) hides them."),disableMessageFeedback:e.boolean().default(!1).describe("Turn OFF the 👍/👎 feedback controls under each rateable reply (AI or operator). Unset/`false` = shown (default), `true` = hidden. A choice fires the `messageFeedback` event and is POSTed best-effort to `/pai/message-feedback`."),autoSendSuggestions:e.boolean().default(!1).describe("Auto-send a suggestion chip's text the moment it's tapped. `false` (default) fills the composer with the text so the visitor can edit before sending; `true` sends it immediately."),cardAnswerWaitSeconds:e.number().int().min(0).max(600).default(60).describe("How long a message the visitor queued while a reply streamed waits, after that reply ends on a card (an approval or questions), for the visitor to answer the card first. `60` (default); `0` sends it at once. The message always goes: a card never blocks it."),popOutUrl:e.string().trim().min(1).max(2048).optional().describe("URL opened by the `popOut` header action. The widget adds the active conversation, widget, and deployment identity as query parameters.")}).loose().describe(`Conversation behaviour — lifecycle, streaming, and the transcript surface (scroll, feedback).`).meta({examples:[{startMinimized:!0,responseMode:`streaming`},{startMinimized:!1,responseMode:`buffered`,disableMessageFeedback:!0}]}),h=e.enum([`auto`,`light`,`dark`,`host`]),g=e.object({mode:h.optional().describe("Light/dark beside the token overrides: `host` (the default: the page's own light/dark, flipping with the site's toggle, else the OS), `auto` (the OS), `light` or `dark`."),accent:i.optional().describe(`Brand accent colour. Drives the FAB, send button, links, and active states. CSS colour.`),accentText:i.optional().describe(`Foreground colour rendered ON the accent (FAB icon, send-button glyph). CSS colour.`),radius:r.optional().describe("Corner radius for the panel + buttons. CSS length (`8px`, `0.75rem`, `12px`)."),fontFamily:e.string().min(1).max(200).optional().describe("Font stack used inside the widget. Standard CSS `font-family` value."),contentMaxWidth:r.optional().describe("Max width of the readable content column (messages, history, home, composer) on a wide surface — content centres, full-bleed bars keep their edges. CSS length; default `768px`. Set `100%` to fill the surface (no cap). Modal + drawer already fill their card by default.")}).loose().describe(`Theme token overrides. Any field left unset falls through to the brand's default theme.`).meta({examples:[{accent:`#10b981`,radius:`12px`},{accent:`#7c3aed`,accentText:`#ffffff`,radius:`16px`,fontFamily:`'Inter', system-ui`},{accent:`oklch(0.7 0.2 145)`,radius:`0.5rem`},{accent:`#5b5bd6`,contentMaxWidth:`960px`}]}),_=e.union([h,g]).describe(`'host' | 'auto' | 'light' | 'dark', or a tokens override object.`).meta({examples:[`host`,`dark`,{accent:`#10b981`,radius:`12px`},{accent:`#7c3aed`,accentText:`#fff`,radius:`16px`,fontFamily:`'Inter', system-ui`}]}),v=e.enum([`circle`,`pill`,`bar`,`minimal`]),y=e.enum([`sm`,`md`,`lg`]),b=e.enum([`pill`,`bubble`,`callout`]),x=e.enum([`auto`,`horizontal`,`vertical`]),S=e.object({text:e.string().min(1).max(500).default(`👋 Hi! Need any help?`).describe("The message to show in the bubble. Defaults to a friendly greeting; replace with your own copy (e.g. 'Click here →'). May also be an i18n key (e.g. `launcherCallout`) resolved against `i18n.strings` for per-locale copy; a non-key literal renders as-is."),shape:b.default(`pill`).describe("Visual shape — `pill` (slim label + arrow), `bubble` (speech-bubble tail), `callout` (loud variant)."),position:x.default(`auto`).describe("Where the bubble sits relative to the FAB. `auto` (default) picks the side facing into the page. `horizontal` anchors beside the FAB (left/right depending on the FAB's corner). `vertical` anchors above/below the FAB. Concrete left/right/top/bottom is derived from the FAB's corner so the bubble always stays on-screen."),delayMs:e.number().int().min(0).max(6e4).default(1200).describe(`How long to wait after page load before the bubble appears, in milliseconds.`),autoDismissMs:e.number().int().min(0).max(6e5).default(0).describe("Auto-hide the bubble after this many milliseconds. `0` (default) keeps it until the user dismisses."),animated:e.boolean().default(!0).describe("Subtle horizontal nudge to draw the eye. Disabled automatically by `prefers-reduced-motion`."),persistent:e.boolean().default(!0).describe("How dismissals stick. `true` (default) — re-show on every visit regardless of prior dismissal (the 'recurring greeting' behaviour). `false` — clicking X stores the message text and that exact message stays hidden across visits (the 'one-time hint' behaviour).")}).loose().describe(`Pre-engagement message bubble next to the FAB. Use it for a greeting ('Hi, need help?'), an attention-grabbing nudge ('Click here →'), or any one-time onboarding tip — same component, configured for the use case.`),C=e.object({variant:v.default(`circle`).describe("FAB visual style. `circle` — round bubble (icon only). `pill` — icon + label. `bar` — wide rectangular button. `minimal` — text-only outline."),size:y.default(`md`).describe(`FAB size preset — small / medium / large.`),label:e.string().max(200).optional().describe("Text rendered on the FAB (only shown for `pill` / `bar` / `minimal` variants)."),icon:e.string().max(8e3).optional().describe("Icon shown on the FAB / drawer edge tab. Built-in presets: `chat` / `message` / `bubbles` / `spark` / `wand` / `bot` / `help` / `lifebuoy` / `headset`. Anything else is treated as raw SVG."),hidden:e.boolean().default(!1).describe("Hide the FAB entirely (page brings its own trigger that calls `instance.open()`)."),callout:S.optional()}).loose().describe(`Floating-launcher (FAB) appearance and behaviour. The FAB is the round button in the corner that opens the chat panel. Floating mode, and drawer mode as its edge tab.`).meta({examples:[{variant:`circle`,size:`md`},{variant:`pill`,label:`Ask AI`,icon:`spark`},{variant:`circle`,callout:{text:`👋 Need help?`,shape:`bubble`,persistent:!0}},{variant:`circle`,callout:{text:`Click to start`,shape:`pill`,delayMs:1200}}]}),w=e.enum([`local`,`server`,`disabled`]),T=e.object({disableFileUpload:e.boolean().default(!1).describe("Turn OFF file uploads — hide the paperclip button + reject drag/drop/paste. Unset/`false` = enabled (default), `true` = disabled."),voice:w.default(`local`).describe("Voice input mode. `local` — speech recognition built into the browser (Web Speech API, free). `server` — record audio + upload to the transcribe endpoint. `disabled` — hide the mic button."),disableHumanInLoop:e.boolean().default(!1).describe("Turn OFF the human-in-the-loop tool UI — the inline ask-questions form + approve/reject controls for gated tools. Unset/`false` = shown (default), `true` = suppressed (the wire still carries the signals)."),disableEmailTranscript:e.boolean().default(!1).describe('Turn OFF the "Email transcript" item in the conversation menu, which emails a copy of the conversation to an address the visitor confirms (prefilled with the one the widget knows). Unset/`false` = shown once the chat has a real turn (default), `true` = hidden.'),enableOperatorRequest:e.boolean().default(!1).describe("Opt IN operator control — expose the 'Talk to a person' affordance + connected-to-operator states for this deployment. Unset/`false` = off (default), `true` = on. Unlike the `disable*` flags this is a positive opt-in for a new capability."),hideRequestOperatorButton:e.boolean().default(!1).describe("Hide the 'Talk to a person' button while operator requests stay on: visitors ask the AI for a person and its `request-operator` tool brings one in. Unset/`false` = shown (default), `true` = hidden.")}).loose().describe(`Capability flags — file upload, voice mode, HITL, email transcript, and operator requests.`).meta({examples:[{voice:`local`},{disableFileUpload:!0,voice:`disabled`},{voice:`server`,enableOperatorRequest:!0}]}),E=e.enum([`clear`,`expand`,`fullscreen`,`popOut`,`sound`,`history`,`language`,`theme`,`textSize`,`close`]),D=e.array(E).max(10).describe("Which actions the header exposes. `history` + `close` are dedicated buttons; the rest appear in the ⋯ menu. Unlisted actions are hidden; order is irrelevant. Pick from: `clear`, `expand`, `fullscreen`, `popOut`, `sound`, `history`, `language`, `theme`, `textSize`, `close`. Per-mode defaults live in `DEFAULT_ACTIONS_BY_MODE`.").meta({examples:[[`theme`,`history`,`close`,`clear`,`fullscreen`,`sound`,`language`],[`theme`,`history`,`clear`,`language`],[`close`]]}),O=e.object({actions:D.optional().describe(`Which header actions are enabled (history/✕ buttons + ⋯ menu).`),variant:e.enum([`plain`,`accent`]).default(`plain`).describe("Header fill. `plain` uses the panel surface; `accent` fills it with the theme accent and its readable text colour (adaptive in light and dark)."),notice:e.string().max(1e3).optional().describe("Notice at the top of every conversation, in Markdown: links open in a new tab. May be an i18n key resolved against `i18n.strings`, so it can read in each language. Blank = the built-in \"You're chatting with an AI assistant.\" (`chatNotice`) in the visitor's language."),hideNotice:e.boolean().default(!1).describe("Turn OFF the conversation notice. Unset/`false` = shown (default), `true` = hidden.")}).loose().describe(`Panel-header configuration: actions, fill and the conversation notice.`).meta({examples:[{actions:[`theme`,`history`,`close`,`clear`,`fullscreen`]},{variant:`accent`,notice:`You're chatting with our AI assistant. See our [privacy policy](https://example.com/privacy).`},{hideNotice:!0}]}),k=e.enum([`messageReceived`,`messageSent`,`error`,`voiceStart`,`voiceStop`]),A=e.object({enabled:e.boolean().default(!0).describe(`Master on/off for audible notifications. On by default — browser autoplay policy still requires a prior user gesture before any sound plays.`),volume:e.number().min(0).max(1).default(.3).describe("Global volume 0..1. `0.3` (default) is intentionally subtle."),events:e.partialRecord(k,e.union([e.boolean(),e.string().min(1).max(2048)])).optional().describe("Per-event override map. Value: `true` = built-in tone, `false` = silent, `string` = URL to a custom audio file (mp3/wav/ogg).")}).loose().describe("Audible notifications. `events` accepts true (default tone), false (off), or a URL to an audio file.").meta({examples:[{enabled:!0,volume:.3},{enabled:!0,volume:.5,events:{messageReceived:!0,error:!1}},{enabled:!0,events:{messageReceived:`https://cdn.help.ai/ping.mp3`}}]}),j=e.object({enabled:e.boolean().default(!0).describe(`Master on/off. Default: on for touch devices, silently ignored elsewhere.`),events:e.partialRecord(k,e.union([e.boolean(),e.number().int(),e.array(e.number().int())])).optional().describe("Per-event vibration pattern. Value: `true` = default pattern, `false` = silent, number = single vibrate ms, array = `[vibrate, pause, vibrate, …]`.")}).loose().describe("Touch-device vibration. `events` accepts true (default), number (single vibrate ms), or [vibrate,pause,vibrate,…].").meta({examples:[{enabled:!0},{enabled:!0,events:{messageReceived:30,error:[40,60,40]}}]}),M=e.object({sound:A.optional(),haptics:j.optional()}).loose().describe(`Audible + tactile feedback.`).meta({examples:[{sound:{enabled:!0,volume:.3},haptics:{enabled:!0}},{sound:{enabled:!1},haptics:{enabled:!1}}]}),N=e.enum([`circle`,`square`,`pill`]),P=e.enum([`arrowUp`,`paperPlane`,`send`,`chevron`]),F=e.enum([`filled`,`outline`,`ghost`]),I=e.object({shape:N.default(`circle`).describe("Send button outline shape — `circle` / `square` / `pill`."),icon:P.default(`arrowUp`).describe("Icon inside the send button — `arrowUp` / `paperPlane` / `send` / `chevron`."),variant:F.default(`filled`).describe("Fill treatment — `filled` (solid accent), `outline` (border only), `ghost` (no border, no fill).")}).loose().describe(`Send-button styling — shape, icon, and fill treatment.`).meta({examples:[{shape:`circle`,icon:`arrowUp`,variant:`filled`},{shape:`pill`,icon:`send`,variant:`outline`},{shape:`square`,icon:`paperPlane`,variant:`ghost`}]}),L=e.object({maxBytes:e.number().int().min(0).max(1073741824).default(10485760).describe("Maximum total size of the files attached to one message, in bytes. `10 MiB` (10485760) by default."),maxCount:e.number().int().min(0).max(100).default(10).describe(`Maximum number of attachments per message.`),accept:e.string().max(2e3).default(`*/*`).describe("Allowed MIME types — comma-separated `accept` attribute string, e.g. `image/*,application/pdf`.")}).loose().describe(`Client-side attachment limits. Server enforcement is still required.`).meta({examples:[{maxBytes:10485760,maxCount:10,accept:`*/*`},{maxBytes:5242880,maxCount:3,accept:`image/*,application/pdf`}]}),R=e.object({sendButton:I.optional(),attachments:L.optional()}).loose().describe(`Composer chrome — send-button styling + attachment limits.`).meta({examples:[{sendButton:{shape:`circle`,icon:`arrowUp`,variant:`filled`}},{sendButton:{shape:`pill`,icon:`send`,variant:`outline`}},{attachments:{maxBytes:5242880,maxCount:3}}]}),te=e.object({text:e.string().max(200).optional().describe("Visible attribution text (e.g. `Powered by Help AI`)."),href:e.url().max(2048).optional().describe("Click target — the attribution becomes a link. Must be a full URL (`https://…`)."),logoUrl:e.url().max(2048).optional().describe(`Small logo rendered before the text. Must be a full URL.`)}).loose().describe(`"Powered by …" attribution shown below the composer.`).meta({examples:[{text:`Powered by Help AI`},{text:`Powered by Help AI`,href:`https://help.ai`,logoUrl:`https://help.ai/logo.svg`}]}),z=e.object({poweredBy:te.optional(),composerDisclaimer:e.string().max(500).optional().describe(`Small muted text under the composer (like ChatGPT's 'ChatGPT can make mistakes.'). Empty = hidden.`)}).loose().describe(`Footer — attribution + composer disclaimer.`).meta({examples:[{poweredBy:{text:`Powered by Help AI`,href:`https://help.ai`}},{composerDisclaimer:`AI responses may be inaccurate.`}]}),B=e.record(e.string(),e.string()),V=e.union([B,e.record(a,B)]).describe(`Per-instance UI string overrides. Flat = active-locale only; nested = multi-locale map. Both forms are partial — missing keys fall through to built-in defaults.`).meta({examples:[{send:`Click`,stop:`Halt`,composerPlaceholder:`Type your question…`},{en:{send:`Send`,composerPlaceholder:`Type a message…`},fr:{send:`Envoyer`,composerPlaceholder:`Tapez un message…`}}]}),H=e.object({locale:a.optional().describe("BCP-47 locale tag forced for this widget instance (e.g. `fr-CA`). Page-owner explicit override."),defaultLocale:e.union([e.literal(`auto`),a]).default(`auto`).describe("Initial / fallback locale for users who haven't picked one. `auto` sniffs `navigator.language`."),availableLocales:e.array(a).max(200).optional().describe(`BCP-47 locale tags shown in the runtime language switcher. Hidden when fewer than 2 entries.`),strings:V.optional()}).loose().describe(`Locale + i18n overrides.`).meta({examples:[{defaultLocale:`auto`},{defaultLocale:`en`,availableLocales:[`en`,`fr`,`de`]},{locale:`fr-CA`,strings:{send:`Envoyer`}}]}),U=e.enum([`chat`,`home`,`help`,`news`]),W=e.object({label:e.string().min(1).max(40).describe("Tab label — an i18n key (resolved against the i18n strings, e.g. `tabHome`) or a literal. Translations ride `i18n.strings`."),layout:U.describe("UI layout that renders this tab: `chat` (the conversation), `home`, `help`, or `news`."),contentCollectionIds:e.array(o).max(20).optional().describe("Content collections this tab shows, in order — the `contentCollectionIds` filter on `GET /pai/content`; Help groups its sections by them. Omit for the `chat` layout."),id:e.string().max(60).optional().describe("Stable id for navigation + last-tab persistence. Defaults to the first `contentCollectionIds` entry, else `layout`."),brandName:e.string().max(80).optional().describe("`home` — hero wordmark (e.g. your company name)."),hideGreeting:e.boolean().optional().describe("`home` — hide the greeting hero. Unset/`false` = shown (default), `true` = hidden."),greetingText:e.string().max(280).optional().describe("`home` — override the greeting headline (default 'How can we help?'); supports a `{name}` token."),userAvatars:e.array(e.object({id:e.string().min(1).max(100).optional().describe("Stable id: how its translations (`role`) find it."),name:e.string().min(1).max(80),avatar:e.string().max(2048).optional().describe("Image URL; falls back to initials of `name`."),role:e.string().max(80).optional()}).loose()).max(10).optional().describe("`home` — team/agent avatars shown in the hero."),hideSearchBar:e.boolean().optional().describe("`home` — hide the 'Search for help' bar. Unset/`false` = shown (default), `true` = hidden. The bar opens the Help tab, so it shows only when the widget has one."),hideRecentConversations:e.boolean().optional().describe("`home` — hide the visitor's most recent conversation card. Unset/`false` = shown (default), `true` = hidden."),status:e.object({text:e.string().min(1).max(120).optional().describe("`home` — status line; an i18n key or a literal (resolved via `localizeText`). Omit to use the built-in generic `homeStatus` string (localized, no custom key needed)."),level:e.string().max(40).optional().describe("`home` — status severity, drives the status icon colour. Free text; `operational` (green, default), `degraded` (amber), and `down` (red) are styled, any other value falls back to the operational style.").meta({examples:[`operational`,`degraded`,`down`]}),url:e.string().max(2048).optional().describe(`Opens in a new tab when tapped.`)}).optional().describe("`home` — system-status card. Omit to hide."),contentBlockTitle:e.string().max(80).optional().describe("`home` — heading for the content list: the pinned items of the tab's `contentCollectionIds` (default 'Popular articles').")}).loose(),G=e.array(W).max(4).describe("Messenger tabs — an ordered list of up to 4 tabs, each picking a `layout` + the content collections it shows (`contentCollectionIds`) + a translatable `label`. One tab → no tab bar (just that content); zero → an empty state. Floating / drawer / modal only.").meta({examples:[[{label:`tabConversations`,layout:`chat`}],[{label:`tabHome`,layout:`home`,brandName:`Acme`,contentBlockTitle:`Popular articles`,contentCollectionIds:[`019a0b6c-7e2a-7000-9d3e-4a5b6c7d8e01`]},{label:`tabConversations`,layout:`chat`},{id:`help`,label:`tabHelp`,layout:`help`,contentCollectionIds:[`019a0b6c-7e2a-7000-9d3e-4a5b6c7d8e01`,`019a0b6c-7e2a-7000-9d3e-4a5b6c7d8e02`]},{id:`news`,label:`tabNews`,layout:`news`,contentCollectionIds:[`019a0b6c-7e2a-7000-9d3e-4a5b6c7d8e03`]}]]}),K=e.object({enabled:e.boolean().optional().describe("Master switch. Default `true` — the widget always fires; the data module gates ingestion per deployment server-side. Set `false` to silence the client entirely."),endpoint:e.url().max(2048).optional().describe("Pixel collector URL. Default: `${dataApiBaseUrl}/pai/elements-px.gif` (e.g. `https://help.ai/api/data/pai/elements-px.gif`). Must be a full URL."),sampleRate:e.number().min(0).max(1).optional().describe("Per-widget-runtime sampling 0..1 (one decision per mounted runtime, keeping that runtime's funnel intact). Default `1`."),token:e.string().max(512).optional().describe("Anti-forgery token, echoed as `tk=` on every hit. Server-issued in the `/handshake` response — never set by hand (see `docs/api/tracking-collector.md`).")}).loose().describe(`Anonymous usage tracking for the widget owner — GA-style pixel events (open, send, form submit, …) with page / device / locale dimensions. Never includes message or form content; the only visitor identifier is the widget's anonymous visitorId.`).meta({examples:[{enabled:!0},{enabled:!0,sampleRate:.5}]}),q=e.object({upload:e.string().min(1).max(2048).default(`/pai/upload-file`),transcribe:e.string().min(1).max(2048).default(`/pai/transcribe-audio`)}).loose().describe("HTTP endpoint overrides. `upload` / `transcribe` paths are appended to the agent base (`${baseUrl}/api/agent`); absolute URLs are accepted too.").meta({examples:[{upload:`/pai/upload-file`,transcribe:`/pai/transcribe-audio`},{upload:`https://help.ai/uploads/presign`}]}),J=e.object({id:e.string().min(1).max(200).optional().describe(`Host's stable id for the user — informational context the agent/backend can key on (not auth).`),email:e.string().min(1).max(320).optional().describe(`User email — surfaced to the agent for context (optional).`),name:e.string().min(1).max(200).optional().describe("Display name — shown in the Home greeting (`{name}`) and conversation transcripts (optional)."),plan:e.string().min(1).max(120).optional().describe("Subscription / pricing tier, e.g. `pro` (optional)."),role:e.string().min(1).max(120).optional().describe("The user's role on the host site, e.g. `admin` (optional)."),phone:e.string().min(1).max(40).optional().describe(`Phone number (optional).`)}).catchall(e.union([e.string(),e.number(),e.boolean()])).describe("Host-asserted visitor context (informational, untrusted — not authentication). Recognised `id` / `email` / `name` / `plan` / `role` / `phone` plus any extra custom scalar fields forwarded to the agent.").meta({examples:[{id:`u_123`},{id:`u_123`,email:`alex@acme.com`,name:`Alex Lee`,plan:`pro`}]}),Y=[`home`,`docs`,`help-desk`,`support`,`pricing`,`checkout`,`orders`,`account`,`blog`],X=e.object({area:e.string().min(1).max(64).optional().describe(`Host-defined surface the visitor is on. Free-form; suggested: ${Y.join(` | `)}.`),url:e.string().min(1).max(2048).optional().describe(`Full page URL. Auto-filled from the host page when omitted.`),path:e.string().min(1).max(2048).optional().describe("Page path, e.g. `/pricing/enterprise`."),title:e.string().min(1).max(300).optional().describe(`Human-readable page title.`)}).catchall(e.union([e.string(),e.number(),e.boolean()])).describe("Host-asserted page/visit context (informational, untrusted). Where the visitor is + the surface (`area`) they're using, plus any custom scalar fields, forwarded to the agent.").meta({examples:[{area:`pricing`,path:`/pricing`},{area:`help-desk`}]}),Z=e.object({widgetId:e.string().min(1).max(80).default(`default`).describe(`Stable per-instance id used to namespace localStorage keys. Set this when mounting more than one widget on the same page so their conversation state doesn't collide.`),publicKey:e.string().min(1).max(200).optional().describe("Deployment public key (`agent_pk_…`) issued from the dashboard. Sent on every API call as the `x-public-key` header when present."),aiAgentDeploymentId:e.string().min(1).max(200).describe("Required deployment UUID from the dashboard. Picks which agent / settings bundle answers this mount. Sent as `x-ai-agent-deployment-id`."),baseUrl:e.string().min(1).max(2048).optional().describe("MAIN site origin (e.g. `https://help.ai`) — the API modules derive from it: agent API at `${baseUrl}/api/agent`, data API at `${baseUrl}/api/data`. Set this to point at your staging / self-hosted / custom backend. Default: the brand's `defaultBaseUrl` baked at build time."),agentApiBaseUrl:e.string().min(1).max(2048).optional().describe("Full agent-API base — set it to reach a STANDALONE `module-agent-api` directly (local module on its own port, e.g. `http://localhost:3069`; routes attach as-is: `/pai/handshake`). Precedence: this option > derived from the main origin (`${baseUrl}/api/agent`). Not server-pushable."),dataApiBaseUrl:e.string().min(1).max(2048).optional().describe("Full data-API base (e.g. `https://help.ai/api/data`, or a standalone local module like `http://localhost:3071`) — the service serving content and the tracking pixel. Precedence: this option > server-pushed `config.dataApiBaseUrl` > derived from the main origin (`${baseUrl}/api/data`)."),continueLink:e.string().min(1).max(400).optional().describe("A Continue in chat link's proof (`<conversationId>.<workspaceId>.<exp>.<signature>`), set by help.ai's own chat page for a visitor who came from an email: the widget opens that email conversation as its visitor, sending it as `x-continue-link` on every agent call. Not server-pushable."),userContext:J.optional(),pageContext:X.optional(),endpoints:q.optional(),debug:e.union([e.boolean(),e.enum([`off`,`error`,`warn`,`info`,`debug`,`trace`])]).optional().describe('Console log verbosity. `false` / `"off"` silences everything (default in production). `true` → `"debug"`. Levels `error` / `warn` / `info` / `debug` / `trace` gate output additively. Use `"trace"` to capture per-chunk SSE frames + every state transition. Also toggleable at runtime via `chat.setDebug(level)` or `?<brand>-debug=trace` in the page URL — the URL beats this option, this option beats the persisted `localStorage` value.')}).loose().describe("Where the widget talks to and how it authenticates. Owned by the embedding developer (typically baked into the page template / env var) — distinct from `userPrefs`, which is the dashboard-pushable UX surface.").meta({examples:[{publicKey:`agent_pk_demo`,aiAgentDeploymentId:`01900000-0000-7000-8000-000000000001`},{publicKey:`agent_pk_demo`,aiAgentDeploymentId:`01900000-0000-7000-8000-000000000001`,widgetId:`support`},{publicKey:`agent_pk_demo`,aiAgentDeploymentId:`01900000-0000-7000-8000-000000000001`,baseUrl:`https://api.acme.com`}]}),Q=e.object({agent:s.optional(),presentation:f.optional(),behavior:m.optional(),theme:_.default(`host`).describe("Theme preference (`host`, the default, follows the page and else the OS) or a tokens override object (`accent`, `radius`, `fontFamily`)."),launcher:C.optional(),header:O.optional(),composer:R.optional(),feedback:M.optional(),i18n:H.optional(),footer:z.optional(),features:T.optional(),modules:G.optional(),tracking:K.optional()}).loose().describe("Portal-configurable widget settings — thirteen sections, one per dashboard tab. The backend pushes this shape on `/pai/handshake` under `config`.").meta({examples:[{presentation:{mode:`floating`,position:`bottom-right`},theme:`auto`},{presentation:{mode:`floating`},theme:{accent:`#7c3aed`,radius:`12px`},launcher:{variant:`pill`,label:`Ask AI`,callout:{text:`👋 Need help?`}}},{presentation:{mode:`inline`},behavior:{responseMode:`streaming`},features:{voice:`local`}}]}),$=Z.extend({...Q.shape,site:e.unknown().optional().describe('Site config — applies in `mode: "page"`. Comes from the handshake response, not user-edited.'),blocks:e.unknown().optional().describe('Blocks (nav + link cards) — applies in `mode: "page"`. Comes from the handshake response.')}).describe("Full tooling config — connection (where + auth) + widget settings (look + behaviour) + page-mode handshake extras. The production widget does not import this Zod schema. Mode-specific constraints (e.g. `position` only meaningful in `floating`) are NOT enforced here so the same object can flow across mode changes.").meta({examples:[{publicKey:`agent_pk_demo`,aiAgentDeploymentId:`01900000-0000-7000-8000-000000000001`,presentation:{mode:`floating`},theme:`auto`},{publicKey:`agent_pk_demo`,aiAgentDeploymentId:`01900000-0000-7000-8000-000000000001`,presentation:{mode:`modal`,size:{width:`720px`,height:`640px`}}}]}),ne=$.partial(),re=Q.partial(),ie=Z.partial(),ae=Q.partial().extend({dataApiBaseUrl:e.string().min(1).max(2048).optional(),storageVersion:e.string().min(1).max(64).optional(),history:e.object({enabled:e.boolean().optional().describe("`false` hides the history button and never lists past conversations. Default `true`.")}).loose().optional().describe(`The deployment's Keep conversations setting.`),login:e.object({url:e.url({protocol:/^https?$/}).max(2048).refine(e=>e.includes(`{returnTo}`),`Put {returnTo} where your login page reads the page to come back to`).optional().describe("Your site's login page, as a URI Template with `{returnTo}` (RFC 6570): Log in sends the page there, with `{returnTo}` replaced by the page's address, URL-encoded. Set, login is on: anonymous visitors see the Log in bar and the Log in screen has a Log in button. A page listening to `loginRequested` opens its own login instead.").meta({examples:[`https://globalvillages.com/login?return_to={returnTo}`]}),required:e.boolean().optional().describe("Only visitors your site logs in (`userToken`) can chat: anyone else sees the Log in screen in place of the composer. Default `false`."),hidePrompt:e.boolean().optional().describe("Hide the Log in bar for anonymous visitors: logging in then starts from your site's own button (`loginRequested`) or the Log in screen. Default `false`."),hideUser:e.boolean().optional().describe('Hide the "Logged in as Maya" bar for logged-in visitors. Default `false`.')}).optional().describe(`The deployment's login settings. See [Logging in](../features/login.md).`),maxMessageCharacters:e.number().int().positive().optional().describe("The longest visitor message the deployment takes: the composer stops there, and a longer message is refused with `400 MESSAGE_TOO_LONG`.")}),oe=e.object({title:e.string().min(1).max(120).optional().describe(`Brand / site name. Used as the logo's alt-text fallback.`),logo:t.optional().describe(`Brand logo shown at the top of the page-mode sidebar.`),logoDark:t.optional().describe("Optional dark-theme logo variant. Falls back to `logo` when the active theme is light or `logoDark` is unset.")}).loose(),se=e.object({navigation:e.array(n).max(100).optional().describe(`Sidebar navigation links (vertical list, primary nav).`),linkCards:e.array(n).max(100).optional().describe("Sidebar link cards (richer entries with optional `description`).")}).loose(),ce=e.object({id:e.string(),role:e.enum([`assistant`,`system`]),text:e.string()}).loose(),le=e.object({id:e.string(),label:e.string(),text:e.string().optional()}).loose(),ue=e.object({deployment:e.object({id:e.string(),name:e.string(),slug:e.string().optional(),publicKey:e.string().optional()}).loose(),agent:e.object({id:e.string(),name:e.string(),title:e.string().optional(),status:e.enum([`online`,`away`,`offline`]).optional()}).loose(),config:ae.optional(),site:oe.optional(),blocks:se.optional(),welcome:e.object({messages:e.array(ce).optional(),suggestions:e.array(le).optional()}).loose().optional(),translations:e.array(e.object({locale:e.string()}).loose()).optional(),visitorId:e.string(),conversationId:e.string(),loginStatus:e.enum([`loggedIn`,`expired`,`anonymous`]).optional(),userPrefs:e.record(e.string(),e.unknown()).optional(),rebind:e.object({conversationId:e.string()}).strict().optional()}).loose(),de=[`theme`,`header`,`composer`,`footer`,`i18n`,`features`,`feedback`,`tracking`],fe={floating:[`presentation`,`behavior`,`modules`,`launcher`],inline:[`presentation`,`behavior`],modal:[`presentation`,`behavior`,`modules`],drawer:[`presentation`,`behavior`,`modules`,`launcher`],page:[`presentation`],standalone:[`presentation`]};function pe(e){let t=[...fe[e],...de],n={};for(let e of t)n[e]=!0;return Q.pick(n)}const me=[`floating`,`inline`,`standalone`,`page`,`modal`,`drawer`];function he(){return{$schema:`https://json-schema.org/draft/2020-12/schema`,title:`@helpai/elements config`,description:`Canonical config schemas for the embeddable AI agent elements widget.`,definitions:{WidgetConfig:e.toJSONSchema($),HandshakeResponse:e.toJSONSchema(ue)}}}export{me as ALL_MODES,Y as PAGE_AREA_SUGGESTIONS,E as actionNameSchema,s as agentSchema,t as assetSchema,L as attachmentLimitsSchema,m as behaviorSchema,se as blocksConfigSchema,x as calloutPositionSchema,b as calloutShapeSchema,R as composerOptionsSchema,ie as connectionConfigPartialSchema,Z as connectionConfigSchema,i as cssColorSchema,r as cssLengthSchema,he as emitJsonSchema,q as endpointsSchema,T as featureFlagsSchema,k as feedbackEventSchema,M as feedbackSchema,z as footerSchema,ue as handshakeResponseSchema,j as hapticsOptionsSchema,D as headerActionsSchema,O as headerSchema,H as i18nSchema,c as initialSizeSchema,S as launcherCalloutSchema,C as launcherOptionsSchema,y as launcherSizeSchema,v as launcherVariantSchema,n as linkSchema,a as localeSchema,ee as modeSchema,U as moduleLayoutSchema,W as moduleSchema,G as modulesSchema,X as pageContextSchema,d as positionSchema,te as poweredBySchema,f as presentationSchema,l as resizeOptionsSchema,p as responseModeSchema,P as sendButtonIconSchema,I as sendButtonOptionsSchema,N as sendButtonShapeSchema,F as sendButtonVariantSchema,ae as serverConfigSchema,oe as siteConfigSchema,u as sizeOptionsSchema,A as soundOptionsSchema,V as stringsOverrideSchema,_ as themeFieldSchema,g as themeOverridesSchema,h as themePreferenceSchema,K as trackingSchema,J as userContextSchema,o as uuid7Schema,w as voiceModeSchema,ne as widgetConfigPartialSchema,$ as widgetConfigSchema,re as widgetSettingsPartialSchema,Q as widgetSettingsSchema,pe as widgetSettingsSchemaForMode};
|
|
1
|
+
import{z as e}from"zod";const t=e.object({url:e.string().min(1).max(2048).describe(`Public URL of the image. Must be a full URL or root-relative path.`),alt:e.string().min(1).max(200).optional().describe(`Alt text for screen readers. Omit only for purely decorative images.`)}).strict().describe(`A single image asset (logo, hero, icon).`),n=e.object({id:e.string().min(1).max(100).optional().describe(`Stable id: the Preact key, the analytics target, and how its translations find it.`),label:e.string().min(1).max(120).describe(`Visible link text.`),href:e.string().min(1).max(2048).optional().describe(`Click target. Optional — when omitted the link renders as a non-clickable heading.`),icon:e.string().min(1).max(100).optional().describe(`Built-in icon preset name (chat / spark / message / help / wand) or a custom string.`),description:e.string().min(1).max(300).optional().describe(`Subtitle shown below the label. Used by link cards in page mode.`)}).loose().describe(`A navigation link / link card.`),r=e.string().min(1).max(120).describe("Any CSS length — `640px`, `80vh`, `calc(100vh - 64px)`, etc. Validated only for size, not syntax."),i=e.string().min(1).max(120).describe("Any CSS colour — hex, `rgb()`, `hsl()`, `oklch()`, a named colour, or a `var(--token)`."),a=e.string().min(1).max(35).describe("BCP-47 locale tag (e.g. `en`, `fr-CA`, `zh-Hant-HK`)."),o=e.uuidv7().describe(`UUID v7 (RFC 9562) — the single id format for visitor / conversation / message / file / content ids.`),s=e.object({name:e.string().max(120).optional().describe('The persona visitors chat with, such as `Bea`. May be an i18n key resolved against `i18n.strings`. Set, a labelled launcher with no `label` reads "Ask Bea" in the visitor\'s language.'),title:e.string().max(200).optional().describe(`The line under the name in the chat header. May be an i18n key.`),avatar:e.url({protocol:/^https?$/}).max(2048).optional().describe(`The persona's picture, a rounded square in the chat header. Unset = the name's initials.`)}).loose().describe(`The assistant persona: its name, subtitle and picture in the chat header.`).meta({examples:[{name:`Bea`,title:`Store assistant`,avatar:`https://cdn.example.com/bea.png`}]}),c=e.enum([`normal`,`expanded`,`fullscreen`,`auto`]),l=e.object({enabled:e.boolean().default(!0).describe("Show a resize handle (default on): a corner grip on the floating panel, the inner edge of a drawer. Hidden in every other mode and on phones, where the panel is edge to edge. `false` turns it off."),minWidth:r.optional().describe("Smallest width the user can drag the panel to. Default `320px`."),maxWidth:r.optional().describe(`Largest width the user can drag the panel to.`),minHeight:r.optional().describe("Smallest height the user can drag the floating panel to. Default `400px`."),maxHeight:r.optional().describe(`Largest height the user can drag the floating panel to.`)}).loose().describe("Drag-resize controls. While `enabled` (the default), visitors resize the floating panel from its corner or a drawer from its inner edge, by pointer or arrow keys, within the min/max bounds; the size is remembered.").meta({examples:[{enabled:!1},{enabled:!0,minWidth:`320px`,maxWidth:`720px`,minHeight:`400px`,maxHeight:`90vh`}]}),u=e.object({width:r.optional().describe("Panel width (CSS length). Mode-specific defaults — floating `380px`, modal `min(960px, 92vw)`, drawer `clamp(440px, 32vw, 640px)`. Set this to override; inline/standalone/page modes ignore it."),height:r.optional().describe("Panel height (CSS length). Mode-specific defaults — floating `600px`, modal `min(720px, 88vh)`, drawer `100vh` (clamped to `100vh − inset-y × 2`). Set this to override."),expanded:e.object({width:r.optional().describe(`Width when the user clicks the expand button.`),height:r.optional().describe(`Height when the user clicks the expand button.`)}).loose().optional().describe("Dimensions when the panel is in its `expanded` tier (between normal and fullscreen). Applies to floating / modal / drawer; ignored in inline / standalone / page where the panel always fills its parent."),resize:l.optional().describe(`Drag-resize controls — a corner grip on the floating panel, the inner edge of a drawer.`),inset:r.optional().describe("Drawer-mode edge inset — gap from each viewport edge (top/bottom/left/right). Single value applied to all four sides. Defaults to `3vh` vertical / `12px` horizontal. Use `0` for a full-edge drawer (no gap), or `5vh` for a centered-looking flyout with extra breathing room. Ignored by every other mode."),initialSize:c.default(`auto`).describe("Which size tier to open with on the first mount: `normal` / `expanded` / `fullscreen` / `auto`. Default `auto` is responsive by viewport: phones (< 640 px) open `fullscreen` edge-to-edge, tablets (640 px … `autoSizeBreakpoint`) open `normal`, and desktop/laptop (≥ `autoSizeBreakpoint`) open `expanded` — so the panel is right for the device out of the box. Set a literal to pin one tier everywhere; the user's own resize is remembered per-device and wins on reload."),autoSizeBreakpoint:e.number().int().min(0).max(1e4).default(900).describe("Viewport width (px) at/above which `initialSize: auto` opens `expanded` instead of `normal`. (Phones below 640 px always open `fullscreen`.)")}).loose().describe("Panel dimensions and drawer inset. Width/height override the mode-specific defaults (floating compact popover, modal centered dialog, drawer flyout). `inset` only affects drawer mode.").meta({examples:[{width:`420px`,height:`640px`},{width:`min(560px, 92vw)`,height:`min(640px, 90vh)`},{width:`420px`,expanded:{width:`640px`,height:`780px`},initialSize:`auto`,autoSizeBreakpoint:900},{width:`min(1100px, 95vw)`,height:`min(820px, 92vh)`},{width:`360px`,inset:`8vh`},{width:`420px`,height:`100vh`,inset:`0`},{width:`420px`,height:`60vh`,inset:`20vh`}]}),ee=e.enum([`floating`,`inline`,`standalone`,`page`,`modal`,`drawer`]),d=e.enum([`bottom-right`,`bottom-left`,`top-right`,`top-left`]),f=e.object({mode:ee.default(`floating`).describe("Rendering shape. `floating` (FAB + popover), `inline` (in-flow block), `standalone` (full viewport), `page` (sidebar + chat), `modal` (centered overlay), `drawer` (side dock)."),position:d.optional().describe("Anchor corner. `floating` uses it for the FAB; `drawer` uses the `*-left` / `*-right` suffix to pick the dock side. Unset is Automatic: bottom-right, or bottom-left when the chat reads right to left. A set corner is fixed. Ignored in other modes."),size:u.optional().describe("Panel dimensions. Mode-aware defaults (floating compact popover, modal centered dialog, drawer flyout) — fields here override them. Includes `inset` (drawer flyout gap), `expanded` tier, drag-resize grip.")}).loose().describe(`Layout fundamentals — mode, anchor corner, panel size + drawer inset.`).meta({examples:[{mode:`floating`,position:`bottom-right`},{mode:`modal`,size:{width:`min(1100px, 95vw)`,height:`min(820px, 92vh)`}},{mode:`drawer`,position:`bottom-right`},{mode:`drawer`,position:`top-right`,size:{width:`360px`,inset:`8vh`}},{mode:`drawer`,position:`bottom-right`,size:{width:`420px`,height:`100vh`,inset:`0`}}]}),p=e.enum([`streaming`,`buffered`]),m=e.object({startMinimized:e.boolean().default(!0).describe("Don't auto-open the floating panel on first visit. `true` (default) shows the FAB collapsed; `false` opens the panel on mount."),responseMode:p.default(`streaming`).describe("How the assistant's reply arrives. `streaming` (default) types tokens as they generate; `buffered` waits + shows the full reply at once."),showReasoning:e.boolean().default(!1).describe(`Show the model's reasoning ("thoughts") as a collapsible block above each answer. \`false\` (default) hides it — a loading indicator still shows while the model works. Reasoning is absent from durable history, but the current turn's short-lived resume backlog may replay it after an immediate reconnect or reload.`),stepDisplay:e.object({showSteps:e.boolean().optional().describe(`Every step the AI takes (a search, an order) appears as one folded line under the reply. Off: only the steps that involve the visitor.`),showStepDetails:e.boolean().optional().describe(`Each step opens to its raw input and result. Off: a step shows only its labelled values, never raw data or ids.`),showStepSystem:e.boolean().optional().describe(`The system that ran a step follows its name, such as "Cancel an order · BC Co. shop".`),showDecidedBy:e.boolean().optional().describe(`Each approval says who decided it, and steps the rules decided show as steps. Off: a rules decision shows only its outcome; the visitor's own choice always shows.`),foldApprovals:e.boolean().optional().describe(`A decided approval folds into the steps line. Off: it stays in the reply as a card.`)}).optional().describe(`How the AI's steps and approvals show. Unset keys take the Simple preset: steps, details, system and who decided off; approvals folded. An approval always shows what it will do.`),showSources:e.boolean().default(!1).describe("Show the citation sources behind an answer (web links + document/file references) in the transcript. `false` (default) hides them."),disableMessageFeedback:e.boolean().default(!1).describe("Turn OFF the 👍/👎 feedback controls under each rateable reply (AI or operator). Unset/`false` = shown (default), `true` = hidden. A choice fires the `messageFeedback` event and is POSTed best-effort to `/pai/message-feedback`."),autoSendSuggestions:e.boolean().default(!1).describe("Auto-send a suggestion chip's text the moment it's tapped. `false` (default) fills the composer with the text so the visitor can edit before sending; `true` sends it immediately."),cardAnswerWaitSeconds:e.number().int().min(0).max(600).default(60).describe("How long a message the visitor queued while a reply streamed waits, after that reply ends on a card (an approval or questions), for the visitor to answer the card first. `60` (default); `0` sends it at once. The message always goes: a card never blocks it."),popOutUrl:e.string().trim().min(1).max(2048).optional().describe("URL opened by the `popOut` header action. The widget adds the active conversation, widget, and deployment identity as query parameters.")}).loose().describe(`Conversation behaviour — lifecycle, streaming, and the transcript surface (scroll, feedback).`).meta({examples:[{startMinimized:!0,responseMode:`streaming`},{startMinimized:!1,responseMode:`buffered`,disableMessageFeedback:!0}]}),h=e.enum([`auto`,`light`,`dark`,`host`]),g=e.object({mode:h.optional().describe("Light/dark beside the token overrides: `host` (the default: the page's own light/dark, flipping with the site's toggle, else the OS), `auto` (the OS), `light` or `dark`."),accent:i.optional().describe(`Brand accent colour. Drives the FAB, send button, links, and active states. CSS colour.`),accentText:i.optional().describe(`Foreground colour rendered ON the accent (FAB icon, send-button glyph). CSS colour.`),radius:r.optional().describe("Corner radius for the panel + buttons. CSS length (`8px`, `0.75rem`, `12px`)."),fontFamily:e.string().min(1).max(200).optional().describe("Font stack used inside the widget. Standard CSS `font-family` value."),contentMaxWidth:r.optional().describe("Max width of the readable content column (messages, history, home, composer) on a wide surface — content centres, full-bleed bars keep their edges. CSS length; default `768px`. Set `100%` to fill the surface (no cap). Modal + drawer already fill their card by default.")}).loose().describe(`Theme token overrides. Any field left unset falls through to the brand's default theme.`).meta({examples:[{accent:`#10b981`,radius:`12px`},{accent:`#7c3aed`,accentText:`#ffffff`,radius:`16px`,fontFamily:`'Inter', system-ui`},{accent:`oklch(0.7 0.2 145)`,radius:`0.5rem`},{accent:`#5b5bd6`,contentMaxWidth:`960px`}]}),_=e.union([h,g]).describe(`'host' | 'auto' | 'light' | 'dark', or a tokens override object.`).meta({examples:[`host`,`dark`,{accent:`#10b981`,radius:`12px`},{accent:`#7c3aed`,accentText:`#fff`,radius:`16px`,fontFamily:`'Inter', system-ui`}]}),v=e.enum([`circle`,`pill`,`bar`,`minimal`]),y=e.enum([`sm`,`md`,`lg`]),b=e.enum([`pill`,`bubble`,`callout`]),x=e.enum([`auto`,`horizontal`,`vertical`]),S=e.object({text:e.string().min(1).max(500).default(`👋 Hi! Need any help?`).describe("The message to show in the bubble. Defaults to a friendly greeting; replace with your own copy (e.g. 'Click here →'). May also be an i18n key (e.g. `launcherCallout`) resolved against `i18n.strings` for per-locale copy; a non-key literal renders as-is."),shape:b.default(`pill`).describe("Visual shape — `pill` (slim label + arrow), `bubble` (speech-bubble tail), `callout` (loud variant)."),position:x.default(`auto`).describe("Where the bubble sits relative to the FAB. `auto` (default) picks the side facing into the page. `horizontal` anchors beside the FAB (left/right depending on the FAB's corner). `vertical` anchors above/below the FAB. Concrete left/right/top/bottom is derived from the FAB's corner so the bubble always stays on-screen."),delayMs:e.number().int().min(0).max(6e4).default(1200).describe(`How long to wait after page load before the bubble appears, in milliseconds.`),autoDismissMs:e.number().int().min(0).max(6e5).default(0).describe("Auto-hide the bubble after this many milliseconds. `0` (default) keeps it until the user dismisses."),animated:e.boolean().default(!0).describe("Subtle horizontal nudge to draw the eye. Disabled automatically by `prefers-reduced-motion`."),persistent:e.boolean().default(!0).describe("How dismissals stick. `true` (default) — re-show on every visit regardless of prior dismissal (the 'recurring greeting' behaviour). `false` — clicking X stores the message text and that exact message stays hidden across visits (the 'one-time hint' behaviour).")}).loose().describe(`Pre-engagement message bubble next to the FAB. Use it for a greeting ('Hi, need help?'), an attention-grabbing nudge ('Click here →'), or any one-time onboarding tip — same component, configured for the use case.`),C=e.object({variant:v.default(`circle`).describe("FAB visual style. `circle` — round bubble (icon only). `pill` — icon + label. `bar` — wide rectangular button. `minimal` — text-only outline."),size:y.default(`md`).describe(`FAB size preset — small / medium / large.`),label:e.string().max(200).optional().describe("Text rendered on the FAB (only shown for `pill` / `bar` / `minimal` variants)."),icon:e.string().max(8e3).optional().describe("Icon shown on the FAB / drawer edge tab. Built-in presets: `chat` / `message` / `bubbles` / `spark` / `wand` / `bot` / `help` / `lifebuoy` / `headset`. Anything else is treated as raw SVG."),hidden:e.boolean().default(!1).describe("Hide the FAB entirely (page brings its own trigger that calls `instance.open()`)."),callout:S.optional()}).loose().describe(`Floating-launcher (FAB) appearance and behaviour. The FAB is the round button in the corner that opens the chat panel. Floating mode, and drawer mode as its edge tab.`).meta({examples:[{variant:`circle`,size:`md`},{variant:`pill`,label:`Ask AI`,icon:`spark`},{variant:`circle`,callout:{text:`👋 Need help?`,shape:`bubble`,persistent:!0}},{variant:`circle`,callout:{text:`Click to start`,shape:`pill`,delayMs:1200}}]}),w=e.enum([`local`,`server`,`disabled`]),T=e.object({disableFileUpload:e.boolean().default(!1).describe("Turn OFF file uploads — hide the paperclip button + reject drag/drop/paste. Unset/`false` = enabled (default), `true` = disabled."),voice:w.default(`local`).describe("Voice input mode. `local` — speech recognition built into the browser (Web Speech API, free). `server` — record audio + upload to the transcribe endpoint. `disabled` — hide the mic button."),disableHumanInLoop:e.boolean().default(!1).describe("Turn OFF the human-in-the-loop tool UI — the inline ask-questions form + approve/reject controls for gated tools. Unset/`false` = shown (default), `true` = suppressed (the wire still carries the signals)."),disableEmailTranscript:e.boolean().default(!1).describe('Turn OFF the "Email transcript" item in the conversation menu, which emails a copy of the conversation to an address the visitor confirms (prefilled with the one the widget knows). Unset/`false` = shown once the chat has a real turn (default), `true` = hidden.'),enableOperatorRequest:e.boolean().default(!1).describe("Opt IN operator control — expose the 'Talk to a person' affordance + connected-to-operator states for this deployment. Unset/`false` = off (default), `true` = on. Unlike the `disable*` flags this is a positive opt-in for a new capability."),hideRequestOperatorButton:e.boolean().default(!1).describe("Hide the 'Talk to a person' button while operator requests stay on: visitors ask the AI for a person and its `request-operator` tool brings one in. Unset/`false` = shown (default), `true` = hidden.")}).loose().describe(`Capability flags — file upload, voice mode, HITL, email transcript, and operator requests.`).meta({examples:[{voice:`local`},{disableFileUpload:!0,voice:`disabled`},{voice:`server`,enableOperatorRequest:!0}]}),E=e.enum([`clear`,`expand`,`fullscreen`,`popOut`,`sound`,`history`,`language`,`theme`,`textSize`,`close`]),D=e.array(E).max(10).describe("Which actions the header exposes. `history` + `close` are dedicated buttons; the rest appear in the ⋯ menu. Unlisted actions are hidden; order is irrelevant. Pick from: `clear`, `expand`, `fullscreen`, `popOut`, `sound`, `history`, `language`, `theme`, `textSize`, `close`. Per-mode defaults live in `DEFAULT_ACTIONS_BY_MODE`.").meta({examples:[[`theme`,`history`,`close`,`clear`,`fullscreen`,`sound`,`language`],[`theme`,`history`,`clear`,`language`],[`close`]]}),O=e.object({actions:D.optional().describe(`Which header actions are enabled (history/✕ buttons + ⋯ menu).`),variant:e.enum([`plain`,`accent`]).default(`plain`).describe("Header fill. `plain` uses the panel surface; `accent` fills it with the theme accent and its readable text colour (adaptive in light and dark)."),notice:e.string().max(1e3).optional().describe("Notice at the top of every conversation, in Markdown: links open in a new tab. May be an i18n key resolved against `i18n.strings`, so it can read in each language. Blank = the built-in \"You're chatting with an AI assistant.\" (`chatNotice`) in the visitor's language."),hideNotice:e.boolean().default(!1).describe("Turn OFF the conversation notice. Unset/`false` = shown (default), `true` = hidden.")}).loose().describe(`Panel-header configuration: actions, fill and the conversation notice.`).meta({examples:[{actions:[`theme`,`history`,`close`,`clear`,`fullscreen`]},{variant:`accent`,notice:`You're chatting with our AI assistant. See our [privacy policy](https://example.com/privacy).`},{hideNotice:!0}]}),k=e.enum([`messageReceived`,`messageSent`,`error`,`voiceStart`,`voiceStop`]),A=e.object({enabled:e.boolean().default(!0).describe(`Master on/off for audible notifications. On by default — browser autoplay policy still requires a prior user gesture before any sound plays.`),volume:e.number().min(0).max(1).default(.3).describe("Global volume 0..1. `0.3` (default) is intentionally subtle."),events:e.partialRecord(k,e.union([e.boolean(),e.string().min(1).max(2048)])).optional().describe("Per-event override map. Value: `true` = built-in tone, `false` = silent, `string` = URL to a custom audio file (mp3/wav/ogg).")}).loose().describe("Audible notifications. `events` accepts true (default tone), false (off), or a URL to an audio file.").meta({examples:[{enabled:!0,volume:.3},{enabled:!0,volume:.5,events:{messageReceived:!0,error:!1}},{enabled:!0,events:{messageReceived:`https://cdn.help.ai/ping.mp3`}}]}),j=e.object({enabled:e.boolean().default(!0).describe(`Master on/off. Default: on for touch devices, silently ignored elsewhere.`),events:e.partialRecord(k,e.union([e.boolean(),e.number().int(),e.array(e.number().int())])).optional().describe("Per-event vibration pattern. Value: `true` = default pattern, `false` = silent, number = single vibrate ms, array = `[vibrate, pause, vibrate, …]`.")}).loose().describe("Touch-device vibration. `events` accepts true (default), number (single vibrate ms), or [vibrate,pause,vibrate,…].").meta({examples:[{enabled:!0},{enabled:!0,events:{messageReceived:30,error:[40,60,40]}}]}),M=e.object({sound:A.optional(),haptics:j.optional()}).loose().describe(`Audible + tactile feedback.`).meta({examples:[{sound:{enabled:!0,volume:.3},haptics:{enabled:!0}},{sound:{enabled:!1},haptics:{enabled:!1}}]}),N=e.enum([`circle`,`square`,`pill`]),P=e.enum([`arrowUp`,`paperPlane`,`send`,`chevron`]),F=e.enum([`filled`,`outline`,`ghost`]),I=e.object({shape:N.default(`circle`).describe("Send button outline shape — `circle` / `square` / `pill`."),icon:P.default(`arrowUp`).describe("Icon inside the send button — `arrowUp` / `paperPlane` / `send` / `chevron`."),variant:F.default(`filled`).describe("Fill treatment — `filled` (solid accent), `outline` (border only), `ghost` (no border, no fill).")}).loose().describe(`Send-button styling — shape, icon, and fill treatment.`).meta({examples:[{shape:`circle`,icon:`arrowUp`,variant:`filled`},{shape:`pill`,icon:`send`,variant:`outline`},{shape:`square`,icon:`paperPlane`,variant:`ghost`}]}),L=e.object({maxBytes:e.number().int().min(0).max(1073741824).default(10485760).describe("Maximum total size of the files attached to one message, in bytes. `10 MiB` (10485760) by default."),maxCount:e.number().int().min(0).max(100).default(10).describe(`Maximum number of attachments per message.`),accept:e.string().max(2e3).default(`*/*`).describe("Allowed MIME types — comma-separated `accept` attribute string, e.g. `image/*,application/pdf`.")}).loose().describe(`Client-side attachment limits. Server enforcement is still required.`).meta({examples:[{maxBytes:10485760,maxCount:10,accept:`*/*`},{maxBytes:5242880,maxCount:3,accept:`image/*,application/pdf`}]}),R=e.object({sendButton:I.optional(),attachments:L.optional()}).loose().describe(`Composer chrome — send-button styling + attachment limits.`).meta({examples:[{sendButton:{shape:`circle`,icon:`arrowUp`,variant:`filled`}},{sendButton:{shape:`pill`,icon:`send`,variant:`outline`}},{attachments:{maxBytes:5242880,maxCount:3}}]}),te=e.object({text:e.string().max(200).optional().describe("Visible attribution text (e.g. `Powered by Help AI`)."),href:e.url().max(2048).optional().describe("Click target — the attribution becomes a link. Must be a full URL (`https://…`)."),logoUrl:e.url().max(2048).optional().describe(`Small logo rendered before the text. Must be a full URL.`)}).loose().describe(`"Powered by …" attribution shown below the composer.`).meta({examples:[{text:`Powered by Help AI`},{text:`Powered by Help AI`,href:`https://help.ai`,logoUrl:`https://help.ai/logo.svg`}]}),z=e.object({poweredBy:te.optional(),composerDisclaimer:e.string().max(500).optional().describe(`Small muted text under the composer (like ChatGPT's 'ChatGPT can make mistakes.'). Empty = hidden.`)}).loose().describe(`Footer — attribution + composer disclaimer.`).meta({examples:[{poweredBy:{text:`Powered by Help AI`,href:`https://help.ai`}},{composerDisclaimer:`AI responses may be inaccurate.`}]}),B=e.record(e.string(),e.string()),V=e.union([B,e.record(a,B)]).describe(`Per-instance UI string overrides. Flat = active-locale only; nested = multi-locale map. Both forms are partial — missing keys fall through to built-in defaults.`).meta({examples:[{send:`Click`,stop:`Halt`,composerPlaceholder:`Type your question…`},{en:{send:`Send`,composerPlaceholder:`Type a message…`},fr:{send:`Envoyer`,composerPlaceholder:`Tapez un message…`}}]}),H=e.object({locale:a.optional().describe("BCP-47 locale tag forced for this widget instance (e.g. `fr-CA`). Page-owner explicit override."),defaultLocale:e.union([e.literal(`auto`),a]).default(`auto`).describe("Initial / fallback locale for users who haven't picked one. `auto` sniffs `navigator.language`."),availableLocales:e.array(a).max(200).optional().describe(`BCP-47 locale tags shown in the runtime language switcher. Hidden when fewer than 2 entries.`),strings:V.optional()}).loose().describe(`Locale + i18n overrides.`).meta({examples:[{defaultLocale:`auto`},{defaultLocale:`en`,availableLocales:[`en`,`fr`,`de`]},{locale:`fr-CA`,strings:{send:`Envoyer`}}]}),U=e.enum([`chat`,`home`,`help`,`news`]),W=e.object({label:e.string().min(1).max(40).describe("Tab label — an i18n key (resolved against the i18n strings, e.g. `tabHome`) or a literal. Translations ride `i18n.strings`."),layout:U.describe("UI layout that renders this tab: `chat` (the conversation), `home`, `help`, or `news`."),contentCollectionIds:e.array(o).max(20).optional().describe("Content collections this tab shows, in order — the `contentCollectionIds` filter on `GET /pai/content`; Help groups its sections by them. Omit for the `chat` layout."),id:e.string().max(60).optional().describe("Stable id for navigation + last-tab persistence. Defaults to the first `contentCollectionIds` entry, else `layout`."),brandName:e.string().max(80).optional().describe("`home` — hero wordmark (e.g. your company name)."),hideGreeting:e.boolean().optional().describe("`home` — hide the greeting hero. Unset/`false` = shown (default), `true` = hidden."),greetingText:e.string().max(280).optional().describe("`home` — override the greeting headline (default 'How can we help?'); supports a `{name}` token."),userAvatars:e.array(e.object({id:e.string().min(1).max(100).optional().describe("Stable id: how its translations (`role`) find it."),name:e.string().min(1).max(80),avatar:e.string().max(2048).optional().describe("Image URL; falls back to initials of `name`."),role:e.string().max(80).optional()}).loose()).max(10).optional().describe("`home` — team/agent avatars shown in the hero."),hideSearchBar:e.boolean().optional().describe("`home` — hide the 'Search for help' bar. Unset/`false` = shown (default), `true` = hidden. The bar opens the Help tab, so it shows only when the widget has one."),hideRecentConversations:e.boolean().optional().describe("`home` — hide the visitor's most recent conversation card. Unset/`false` = shown (default), `true` = hidden."),status:e.object({text:e.string().min(1).max(120).optional().describe("`home` — status line; an i18n key or a literal (resolved via `localizeText`). Omit to use the built-in generic `homeStatus` string (localized, no custom key needed)."),level:e.string().max(40).optional().describe("`home` — status severity, drives the status icon colour. Free text; `operational` (green, default), `degraded` (amber), and `down` (red) are styled, any other value falls back to the operational style.").meta({examples:[`operational`,`degraded`,`down`]}),url:e.string().max(2048).optional().describe(`Opens in a new tab when tapped.`)}).optional().describe("`home` — system-status card. Omit to hide."),contentBlockTitle:e.string().max(80).optional().describe("`home` — heading for the content list: the pinned items of the tab's `contentCollectionIds` (default 'Popular articles').")}).loose(),G=e.array(W).max(4).describe("Messenger tabs — an ordered list of up to 4 tabs, each picking a `layout` + the content collections it shows (`contentCollectionIds`) + a translatable `label`. One tab → no tab bar (just that content); zero → an empty state. Floating / drawer / modal only.").meta({examples:[[{label:`tabConversations`,layout:`chat`}],[{label:`tabHome`,layout:`home`,brandName:`Acme`,contentBlockTitle:`Popular articles`,contentCollectionIds:[`019a0b6c-7e2a-7000-9d3e-4a5b6c7d8e01`]},{label:`tabConversations`,layout:`chat`},{id:`help`,label:`tabHelp`,layout:`help`,contentCollectionIds:[`019a0b6c-7e2a-7000-9d3e-4a5b6c7d8e01`,`019a0b6c-7e2a-7000-9d3e-4a5b6c7d8e02`]},{id:`news`,label:`tabNews`,layout:`news`,contentCollectionIds:[`019a0b6c-7e2a-7000-9d3e-4a5b6c7d8e03`]}]]}),K=e.object({enabled:e.boolean().optional().describe("Master switch. Default `true` — the widget always fires; the data module gates ingestion per deployment server-side. Set `false` to silence the client entirely."),endpoint:e.url().max(2048).optional().describe("Pixel collector URL. Default: `${dataApiBaseUrl}/pai/elements-px.gif` (e.g. `https://help.ai/api/data/pai/elements-px.gif`). Must be a full URL."),sampleRate:e.number().min(0).max(1).optional().describe("Per-widget-runtime sampling 0..1 (one decision per mounted runtime, keeping that runtime's funnel intact). Default `1`."),token:e.string().max(512).optional().describe("Anti-forgery token, echoed as `tk=` on every hit. Server-issued in the `/handshake` response — never set by hand (see `docs/api/tracking-collector.md`).")}).loose().describe(`Anonymous usage tracking for the widget owner — GA-style pixel events (open, send, form submit, …) with page / device / locale dimensions. Never includes message or form content; the only visitor identifier is the widget's anonymous visitorId.`).meta({examples:[{enabled:!0},{enabled:!0,sampleRate:.5}]}),q=e.object({upload:e.string().min(1).max(2048).default(`/pai/upload-file`),transcribe:e.string().min(1).max(2048).default(`/pai/transcribe-audio`)}).loose().describe("HTTP endpoint overrides. `upload` / `transcribe` paths are appended to the agent base (`${baseUrl}/api/agent`); absolute URLs are accepted too.").meta({examples:[{upload:`/pai/upload-file`,transcribe:`/pai/transcribe-audio`},{upload:`https://help.ai/uploads/presign`}]}),J=e.object({id:e.string().min(1).max(200).optional().describe(`Host's stable id for the user — informational context the agent/backend can key on (not auth).`),email:e.string().min(1).max(320).optional().describe(`User email — surfaced to the agent for context (optional).`),name:e.string().min(1).max(200).optional().describe("Display name — shown in the Home greeting (`{name}`) and conversation transcripts (optional)."),plan:e.string().min(1).max(120).optional().describe("Subscription / pricing tier, e.g. `pro` (optional)."),role:e.string().min(1).max(120).optional().describe("The user's role on the host site, e.g. `admin` (optional)."),phone:e.string().min(1).max(40).optional().describe(`Phone number (optional).`)}).catchall(e.union([e.string(),e.number(),e.boolean()])).describe("Host-asserted visitor context (informational, untrusted — not authentication). Recognised `id` / `email` / `name` / `plan` / `role` / `phone` plus any extra custom scalar fields forwarded to the agent.").meta({examples:[{id:`u_123`},{id:`u_123`,email:`alex@acme.com`,name:`Alex Lee`,plan:`pro`}]}),Y=[`home`,`docs`,`help-desk`,`support`,`pricing`,`checkout`,`orders`,`account`,`blog`],X=e.object({area:e.string().min(1).max(64).optional().describe(`Host-defined surface the visitor is on. Free-form; suggested: ${Y.join(` | `)}.`),url:e.string().min(1).max(2048).optional().describe(`Full page URL. Auto-filled from the host page when omitted.`),path:e.string().min(1).max(2048).optional().describe("Page path, e.g. `/pricing/enterprise`."),title:e.string().min(1).max(300).optional().describe(`Human-readable page title.`)}).catchall(e.union([e.string(),e.number(),e.boolean()])).describe("Host-asserted page/visit context (informational, untrusted). Where the visitor is + the surface (`area`) they're using, plus any custom scalar fields, forwarded to the agent.").meta({examples:[{area:`pricing`,path:`/pricing`},{area:`help-desk`}]}),Z=e.object({widgetId:e.string().min(1).max(80).default(`default`).describe(`Stable per-instance id used to namespace localStorage keys. Set this when mounting more than one widget on the same page so their conversation state doesn't collide.`),publicKey:e.string().min(1).max(200).optional().describe("Deployment public key (`agent_pk_…`) issued from the dashboard. Sent on every API call as the `x-public-key` header when present."),aiAgentDeploymentId:e.string().min(1).max(200).describe("Required deployment UUID from the dashboard. Picks which agent / settings bundle answers this mount. Sent as `x-ai-agent-deployment-id`."),baseUrl:e.string().min(1).max(2048).optional().describe("MAIN site origin (e.g. `https://help.ai`) — the API modules derive from it: agent API at `${baseUrl}/api/agent`, data API at `${baseUrl}/api/data`. Set this to point at your staging / self-hosted / custom backend. Default: the brand's `defaultBaseUrl` baked at build time."),agentApiBaseUrl:e.string().min(1).max(2048).optional().describe("Full agent-API base — set it to reach a STANDALONE `module-agent-api` directly (local module on its own port, e.g. `http://localhost:3069`; routes attach as-is: `/pai/handshake`). Precedence: this option > derived from the main origin (`${baseUrl}/api/agent`). Not server-pushable."),dataApiBaseUrl:e.string().min(1).max(2048).optional().describe("Full data-API base (e.g. `https://help.ai/api/data`, or a standalone local module like `http://localhost:3071`) — the service serving content and the tracking pixel. Precedence: this option > server-pushed `config.dataApiBaseUrl` > derived from the main origin (`${baseUrl}/api/data`)."),continueLink:e.string().min(1).max(400).optional().describe("A Continue in chat link's proof (`<conversationId>.<workspaceId>.<exp>.<signature>`), set by help.ai's own chat page for a visitor who came from an email: the widget opens that email conversation as its visitor, sending it as `x-continue-link` on every agent call. Not server-pushable."),userContext:J.optional(),pageContext:X.optional(),endpoints:q.optional(),debug:e.union([e.boolean(),e.enum([`off`,`error`,`warn`,`info`,`debug`,`trace`])]).optional().describe('Console log verbosity. `false` / `"off"` silences everything (default in production). `true` → `"debug"`. Levels `error` / `warn` / `info` / `debug` / `trace` gate output additively. Use `"trace"` to capture per-chunk SSE frames + every state transition. Also toggleable at runtime via `chat.setDebug(level)` or `?<brand>-debug=trace` in the page URL — the URL beats this option, this option beats the persisted `localStorage` value.')}).loose().describe("Where the widget talks to and how it authenticates. Owned by the embedding developer (typically baked into the page template / env var) — distinct from `userPrefs`, which is the dashboard-pushable UX surface.").meta({examples:[{publicKey:`agent_pk_demo`,aiAgentDeploymentId:`01900000-0000-7000-8000-000000000001`},{publicKey:`agent_pk_demo`,aiAgentDeploymentId:`01900000-0000-7000-8000-000000000001`,widgetId:`support`},{publicKey:`agent_pk_demo`,aiAgentDeploymentId:`01900000-0000-7000-8000-000000000001`,baseUrl:`https://api.acme.com`}]}),Q=e.object({agent:s.optional(),presentation:f.optional(),behavior:m.optional(),theme:_.default(`host`).describe("Theme preference (`host`, the default, follows the page and else the OS) or a tokens override object (`accent`, `radius`, `fontFamily`)."),launcher:C.optional(),header:O.optional(),composer:R.optional(),feedback:M.optional(),i18n:H.optional(),footer:z.optional(),features:T.optional(),modules:G.optional(),tracking:K.optional()}).loose().describe("Portal-configurable widget settings — thirteen sections, one per dashboard tab. The backend pushes this shape on `/pai/handshake` under `config`.").meta({examples:[{presentation:{mode:`floating`,position:`bottom-right`},theme:`auto`},{presentation:{mode:`floating`},theme:{accent:`#7c3aed`,radius:`12px`},launcher:{variant:`pill`,label:`Ask AI`,callout:{text:`👋 Need help?`}}},{presentation:{mode:`inline`},behavior:{responseMode:`streaming`},features:{voice:`local`}}]}),$=Z.extend({...Q.shape,site:e.unknown().optional().describe('Site config — applies in `mode: "page"`. Comes from the handshake response, not user-edited.'),blocks:e.unknown().optional().describe('Blocks (nav + link cards) — applies in `mode: "page"`. Comes from the handshake response.')}).describe("Full tooling config — connection (where + auth) + widget settings (look + behaviour) + page-mode handshake extras. The production widget does not import this Zod schema. Mode-specific constraints (e.g. `position` only meaningful in `floating`) are NOT enforced here so the same object can flow across mode changes.").meta({examples:[{publicKey:`agent_pk_demo`,aiAgentDeploymentId:`01900000-0000-7000-8000-000000000001`,presentation:{mode:`floating`},theme:`auto`},{publicKey:`agent_pk_demo`,aiAgentDeploymentId:`01900000-0000-7000-8000-000000000001`,presentation:{mode:`modal`,size:{width:`720px`,height:`640px`}}}]}),ne=$.partial(),re=Q.partial(),ie=Z.partial(),ae=Q.partial().extend({dataApiBaseUrl:e.string().min(1).max(2048).optional(),storageVersion:e.string().min(1).max(64).optional(),history:e.object({enabled:e.boolean().optional().describe("`false` hides the history button and never lists past conversations. Default `true`.")}).loose().optional().describe(`The deployment's Keep conversations setting.`),login:e.object({url:e.url({protocol:/^https?$/}).max(2048).refine(e=>e.includes(`{returnTo}`),`Put {returnTo} where your login page reads the page to come back to`).optional().describe("Your site's login page, as a URI Template with `{returnTo}` (RFC 6570): Log in sends the page there, with `{returnTo}` replaced by the page's address, URL-encoded. Set, login is on: anonymous visitors see the Log in bar and the Log in screen has a Log in button. A page listening to `loginRequested` opens its own login instead.").meta({examples:[`https://globalvillages.com/login?return_to={returnTo}`]}),required:e.boolean().optional().describe("Only visitors your site logs in (`userToken`) can chat: anyone else sees the Log in screen in place of the composer. Default `false`."),hidePrompt:e.boolean().optional().describe("Hide the Log in bar for anonymous visitors: logging in then starts from your site's own button (`loginRequested`) or the Log in screen. Default `false`."),hideUser:e.boolean().optional().describe('Hide the "Logged in as Maya" bar for logged-in visitors. Default `false`.')}).optional().describe(`The deployment's login settings. See [Logging in](../features/login.md).`),maxMessageCharacters:e.number().int().positive().optional().describe("The longest visitor message the deployment takes: the composer stops there, and a longer message is refused with `400 MESSAGE_TOO_LONG`.")}),oe=e.object({title:e.string().min(1).max(120).optional().describe(`Brand / site name. Used as the logo's alt-text fallback.`),logo:t.optional().describe(`Brand logo shown at the top of the page-mode sidebar.`),logoDark:t.optional().describe("Optional dark-theme logo variant. Falls back to `logo` when the active theme is light or `logoDark` is unset.")}).loose(),se=e.object({navigation:e.array(n).max(100).optional().describe(`Sidebar navigation links (vertical list, primary nav).`),linkCards:e.array(n).max(100).optional().describe("Sidebar link cards (richer entries with optional `description`).")}).loose(),ce=e.object({id:e.string(),role:e.enum([`assistant`,`system`]),text:e.string()}).loose(),le=e.object({id:e.string(),label:e.string(),text:e.string().optional()}).loose(),ue=e.object({deployment:e.object({id:e.string(),name:e.string(),slug:e.string().optional(),publicKey:e.string().optional()}).loose(),agent:e.object({id:e.string(),name:e.string(),title:e.string().optional(),status:e.enum([`online`,`away`,`offline`]).optional()}).loose(),config:ae.optional(),site:oe.optional(),blocks:se.optional(),welcome:e.object({messages:e.array(ce).optional(),suggestions:e.array(le).optional()}).loose().optional(),translations:e.array(e.object({locale:e.string()}).loose()).optional(),visitorId:e.string(),conversationId:e.string(),loginStatus:e.enum([`loggedIn`,`expired`,`anonymous`]).optional(),userPrefs:e.record(e.string(),e.unknown()).optional(),rebind:e.object({conversationId:e.string()}).strict().optional()}).loose(),de=[`theme`,`header`,`composer`,`footer`,`i18n`,`features`,`feedback`,`tracking`],fe={floating:[`presentation`,`behavior`,`modules`,`launcher`],inline:[`presentation`,`behavior`],modal:[`presentation`,`behavior`,`modules`],drawer:[`presentation`,`behavior`,`modules`,`launcher`],page:[`presentation`],standalone:[`presentation`]};function pe(e){let t=[...fe[e],...de],n={};for(let e of t)n[e]=!0;return Q.pick(n)}const me=[`floating`,`inline`,`standalone`,`page`,`modal`,`drawer`];function he(){return{$schema:`https://json-schema.org/draft/2020-12/schema`,title:`@helpai/elements config`,description:`Canonical config schemas for the embeddable AI agent elements widget.`,definitions:{WidgetConfig:e.toJSONSchema($),HandshakeResponse:e.toJSONSchema(ue)}}}export{me as ALL_MODES,Y as PAGE_AREA_SUGGESTIONS,E as actionNameSchema,s as agentSchema,t as assetSchema,L as attachmentLimitsSchema,m as behaviorSchema,se as blocksConfigSchema,x as calloutPositionSchema,b as calloutShapeSchema,R as composerOptionsSchema,ie as connectionConfigPartialSchema,Z as connectionConfigSchema,i as cssColorSchema,r as cssLengthSchema,he as emitJsonSchema,q as endpointsSchema,T as featureFlagsSchema,k as feedbackEventSchema,M as feedbackSchema,z as footerSchema,ue as handshakeResponseSchema,j as hapticsOptionsSchema,D as headerActionsSchema,O as headerSchema,H as i18nSchema,c as initialSizeSchema,S as launcherCalloutSchema,C as launcherOptionsSchema,y as launcherSizeSchema,v as launcherVariantSchema,n as linkSchema,a as localeSchema,ee as modeSchema,U as moduleLayoutSchema,W as moduleSchema,G as modulesSchema,X as pageContextSchema,d as positionSchema,te as poweredBySchema,f as presentationSchema,l as resizeOptionsSchema,p as responseModeSchema,P as sendButtonIconSchema,I as sendButtonOptionsSchema,N as sendButtonShapeSchema,F as sendButtonVariantSchema,ae as serverConfigSchema,oe as siteConfigSchema,u as sizeOptionsSchema,A as soundOptionsSchema,V as stringsOverrideSchema,_ as themeFieldSchema,g as themeOverridesSchema,h as themePreferenceSchema,K as trackingSchema,J as userContextSchema,o as uuid7Schema,w as voiceModeSchema,ne as widgetConfigPartialSchema,$ as widgetConfigSchema,re as widgetSettingsPartialSchema,Q as widgetSettingsSchema,pe as widgetSettingsSchemaForMode};
|
|
2
2
|
//# sourceMappingURL=schema.mjs.map
|
|
@@ -0,0 +1,215 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `@<brand>/elements/step-display`: how a reply's steps and approvals read, for help.ai's own chat surfaces outside the
|
|
3
|
+
* widget (the dashboard's AI Chat, AI Agent Chat and Inbox). They draw the same views the widget draws, from the same
|
|
4
|
+
* settings and words, so the two never decide differently (docs/features/step-display.md). Framework-free.
|
|
5
|
+
*/
|
|
6
|
+
type StringKey = 'launcherOpen' | 'launcherAsk' | 'panelTitle' | 'composerPlaceholder' | 'send' | 'stop' | 'queueMessage' | 'removeQueuedMessage' | 'removeAttachment' | 'suggestedReplies' | 'compactingContext' | 'attach' | 'file' | 'micBlocked' | 'micStart' | 'micStop' | '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' | 'talkToOperator' | 'connectingOperator' | 'noOperatorAvailable' | 'chattingWithOperator' | 'operatorBadgeTitle' | 'chatNotice' | 'cancelOperatorRequest' | 'loginPrompt' | 'loginAction' | 'loginRequired' | 'loginExpired' | 'loginExpiredGuest' | 'startAsGuest' | 'loggedInAs' | 'loggedIn' | 'dismissLoginPrompt' | 'emailTranscript' | 'emailTranscriptPrompt' | 'emailTranscriptEmailLabel' | 'emailTranscriptSend' | 'emailTranscriptSending' | 'emailTranscriptSent' | 'emailTranscriptAlreadySent' | 'emailTranscriptLimited' | 'emailTranscriptFailed' | 'emailTranscriptNotDelivered' | 'emailTranscriptCancel' | 'emailTranscriptDone' | 'dateToday' | 'dateYesterday' | 'dateLastWeek' | 'dateOlder' | 'newConversation' | 'dropZone' | 'dropZoneRejected' | 'attachmentTooLarge' | 'poweredBy' | 'attachmentTooMany' | 'attachmentMimeRejected' | 'attachmentUploadFailed' | 'errorRetry' | 'errorGeneric' | 'errorRateLimited' | 'errorRateLimitedIn' | 'errorOffline' | 'errorServer' | 'errorOriginNotAllowed' | 'errorMessageTooLong' | 'errorReconnecting' | 'loading' | 'visualPreparing' | 'visualError' | 'visualPartial' | 'visualSoldOut' | 'visualCartEmpty' | 'visualQuantity' | 'visualChoose' | 'thinking' | 'thought' | 'thoughtFor' | 'toolResult' | 'sources' | 'feedbackUp' | 'feedbackDown' | 'feedbackThanks' | 'copy' | 'copied' | 'copyTicketReference' | 'collapseSidebar' | 'expandSidebar' | 'formRequired' | 'formInvalidEmail' | 'formInvalidTel' | 'formInvalidNumber' | 'formOtherPlaceholder' | 'inputRequired' | 'askFallbackQuestion' | 'inputBadge' | 'inputAnswered' | 'inputSkipped' | 'inputSubmit' | 'inputSubmitHint' | 'inputSkip' | 'showOptions' | 'hideOptions' | 'qtypeText' | 'qtypeEmail' | 'qtypePhone' | 'qtypeNumber' | 'qtypeDate' | 'qtypeChooseOne' | 'qtypeChooseAny' | 'qtypeBoolean' | 'confirmYes' | 'confirmNo' | 'approve' | 'decline' | 'changeAnswer' | 'approvalPrompt' | 'approvalEditHint' | 'stepInput' | 'stepWorking' | 'stepWorkingOnIt' | 'stepNeedsYourApproval' | 'stepWaitingForVisitor' | 'stepApproved' | 'stepDeclined' | 'stepReplaced' | 'stepFailed' | 'stepDidNotWork' | 'decidedYouApproved' | 'decidedYouDeclined' | 'decidedVisitorApproved' | 'decidedVisitorDeclined' | 'decidedTeamApproved' | 'decidedTeamDeclined' | 'decidedRulesApproved' | 'decidedRulesDeclined' | 'edit' | 'statusError' | 'toolStepsFailed' | 'statusStopped' | 'toolStepsStopped' | 'toolStepsStoppedOne' | 'tabHome' | 'tabConversations' | 'tabHelp' | 'tabNews' | 'modulesEmpty' | 'chatUnavailable' | 'moduleBack' | 'contentLoading' | 'contentHelpful' | 'homeGreeting' | 'homeGreetingNamed' | 'homeGreetingLead' | 'homeSearchPlaceholder' | 'homeAskPlaceholder' | 'homeWhatsNew' | 'homeContentTitle' | 'homeStatus' | 'helpTitle' | 'helpSearchPlaceholder' | 'helpEmpty' | 'helpLoading' | 'helpSearchEmpty' | 'helpShowMore' | 'newsTitle' | 'newsEmpty' | 'newsLoading' | 'newsShowMore' | 'newsUnseen' | 'unread';
|
|
7
|
+
/**
|
|
8
|
+
* The post-resolution map — every key guaranteed present. UI components
|
|
9
|
+
* receive this shape and read it via direct property access (no `t()`).
|
|
10
|
+
*/
|
|
11
|
+
type Strings = Record<StringKey, string>;
|
|
12
|
+
/**
|
|
13
|
+
* A human-in-the-loop approval decision on a tool call. Mirrors AI SDK v7's
|
|
14
|
+
* `ToolUIPart.approval`: `id` correlates the request ↔ response; `approved`
|
|
15
|
+
* is filled once the user decides; `reason` is an optional note.
|
|
16
|
+
*/
|
|
17
|
+
interface ToolApproval {
|
|
18
|
+
id: string;
|
|
19
|
+
approved?: boolean;
|
|
20
|
+
reason?: string;
|
|
21
|
+
/** The server's auto mode decided the call (no visitor was asked); the card says it was approved or declined automatically. */
|
|
22
|
+
isAutomatic?: boolean;
|
|
23
|
+
/** The visitor's next message replaced the call while it waited, so nobody answered it: it reads Replaced (a questions card, Skipped). */
|
|
24
|
+
replacedByMessageId?: string;
|
|
25
|
+
}
|
|
26
|
+
/**
|
|
27
|
+
* Lifecycle of a tool part — the exact AI SDK v7 `ToolUIPart['state']` union,
|
|
28
|
+
* so the wire shape is a passthrough (no lossy local-state translation):
|
|
29
|
+
* `input-streaming` — args still streaming in; `input-available` — args
|
|
30
|
+
* complete, tool not yet run; `approval-requested` — a gated action (or the
|
|
31
|
+
* approval-wrapped ask-questions tool) waiting on the user's approve/reject;
|
|
32
|
+
* `approval-responded` — the user decided (the decision rides `approval`),
|
|
33
|
+
* waiting on the backend to execute or skip; `output-available` — resolved with
|
|
34
|
+
* a result; `output-error` — the tool threw; `output-denied` — a rejected
|
|
35
|
+
* approval that never ran. The ask-questions form is recognised by tool NAME (see
|
|
36
|
+
* constants.ts), not a distinct state — it lives in `input-available` /
|
|
37
|
+
* `approval-requested` like any other tool.
|
|
38
|
+
*/
|
|
39
|
+
type ToolState = 'input-streaming' | 'input-available' | 'approval-requested' | 'approval-responded' | 'output-available' | 'output-error' | 'output-denied';
|
|
40
|
+
/** The five switches, the same keys on a Deployment (`config.behavior.stepDisplay`) and in a member's Preferences. */
|
|
41
|
+
export interface StepDisplay {
|
|
42
|
+
/** Every step appears as one folded line under the reply; off, only the steps that involve the reader do. */
|
|
43
|
+
showSteps: boolean;
|
|
44
|
+
/** Each step opens to its raw input and result. */
|
|
45
|
+
showStepDetails: boolean;
|
|
46
|
+
/** The system that ran a step follows its name: "Ship an order · BC Co. back office". */
|
|
47
|
+
showStepSystem: boolean;
|
|
48
|
+
/** Each approval says who decided it, and steps the rules decided show as steps. */
|
|
49
|
+
showDecidedBy: boolean;
|
|
50
|
+
/** A decided approval folds into the steps line; off, it stays in the reply as a card. */
|
|
51
|
+
foldApprovals: boolean;
|
|
52
|
+
}
|
|
53
|
+
export declare const STEP_DISPLAY_PRESETS: {
|
|
54
|
+
readonly simple: {
|
|
55
|
+
readonly showSteps: false;
|
|
56
|
+
readonly showStepDetails: false;
|
|
57
|
+
readonly showStepSystem: false;
|
|
58
|
+
readonly showDecidedBy: false;
|
|
59
|
+
readonly foldApprovals: true;
|
|
60
|
+
};
|
|
61
|
+
readonly technical: {
|
|
62
|
+
readonly showSteps: true;
|
|
63
|
+
readonly showStepDetails: true;
|
|
64
|
+
readonly showStepSystem: true;
|
|
65
|
+
readonly showDecidedBy: true;
|
|
66
|
+
readonly foldApprovals: true;
|
|
67
|
+
};
|
|
68
|
+
};
|
|
69
|
+
export type StepDisplayPreset = keyof typeof STEP_DISPLAY_PRESETS;
|
|
70
|
+
export declare const STEP_DISPLAY_KEYS: readonly ["showSteps", "showStepDetails", "showStepSystem", "showDecidedBy", "foldApprovals"];
|
|
71
|
+
export declare function isStepDisplayPreset(name: string): name is StepDisplayPreset;
|
|
72
|
+
/** The settings a surface uses: what was stored over its default preset, so a partial or absent setting reads whole. */
|
|
73
|
+
export declare function resolveStepDisplay(stored: Partial<StepDisplay> | undefined, preset: StepDisplayPreset): StepDisplay;
|
|
74
|
+
/** The preset these settings match, for the editor's preset picker; none is a custom mix. */
|
|
75
|
+
export declare function matchStepDisplayPreset(display: StepDisplay): StepDisplayPreset | undefined;
|
|
76
|
+
/** Who made an approval's decision, as the stored approval records it. The visitor's own view never carries it. */
|
|
77
|
+
export interface StepApproval extends ToolApproval {
|
|
78
|
+
respondedBy?: {
|
|
79
|
+
userId?: string;
|
|
80
|
+
visitorId?: string;
|
|
81
|
+
};
|
|
82
|
+
}
|
|
83
|
+
/** One call as a surface hands it over: a plain snapshot of the wire part. */
|
|
84
|
+
export interface StepCall {
|
|
85
|
+
toolCallId: string;
|
|
86
|
+
/** The model-facing name (`site__place_order`, `bc-co-shop__cancel_order`, `request-operator`). */
|
|
87
|
+
toolName: string;
|
|
88
|
+
/** The action as people read it, from the server (a catalog name, an MCP tool's title, a page tool's title). */
|
|
89
|
+
title?: string;
|
|
90
|
+
state: ToolState;
|
|
91
|
+
input?: unknown;
|
|
92
|
+
output?: unknown;
|
|
93
|
+
errorText?: string;
|
|
94
|
+
approval?: StepApproval;
|
|
95
|
+
/** The server's marks: `system` (who ran it), `card` (a card of its own), `execution: "client"` (a page tool). */
|
|
96
|
+
toolMetadata?: Record<string, unknown>;
|
|
97
|
+
}
|
|
98
|
+
/** Where a call stands in its turn, as only the surface can tell. */
|
|
99
|
+
export interface StepTurn {
|
|
100
|
+
/** The call can still progress: its reply streams, or the page is running it. */
|
|
101
|
+
live: boolean;
|
|
102
|
+
/** The reply was cut off: stopped by the person, or it failed. */
|
|
103
|
+
cutOff: boolean;
|
|
104
|
+
/** A later message exists, so a call still waiting will never be answered here. */
|
|
105
|
+
superseded: boolean;
|
|
106
|
+
/** A decision was accepted and its run is starting, but this part does not carry it yet. */
|
|
107
|
+
submitted: boolean;
|
|
108
|
+
/** The decision on this call can still be made or changed now (its step is current and nothing streams). */
|
|
109
|
+
canAct: boolean;
|
|
110
|
+
/** A page tool's call that a reload or the person's Stop cut short. */
|
|
111
|
+
interrupted?: boolean;
|
|
112
|
+
}
|
|
113
|
+
/** Who reads: decides = may answer this conversation's approvals (a visitor in their chat, a member in their own chat or an email ticket). */
|
|
114
|
+
export interface StepReader {
|
|
115
|
+
userId?: string;
|
|
116
|
+
decides: boolean;
|
|
117
|
+
}
|
|
118
|
+
export type StepStatus = 'running' | 'waiting' | 'submitted' | 'approved' | 'done' | 'declined' | 'replaced' | 'stopped' | 'failed';
|
|
119
|
+
export type StepDecider = 'you' | 'visitor' | 'teamMember' | 'rules';
|
|
120
|
+
export interface StepDecision {
|
|
121
|
+
approved: boolean;
|
|
122
|
+
by: StepDecider;
|
|
123
|
+
/** "You approved", "Approved by the visitor", "Approved automatically". */
|
|
124
|
+
label: string;
|
|
125
|
+
}
|
|
126
|
+
export interface StepField {
|
|
127
|
+
label: string;
|
|
128
|
+
value: string;
|
|
129
|
+
}
|
|
130
|
+
export interface StepCallView {
|
|
131
|
+
toolCallId: string;
|
|
132
|
+
/** In the reply as a card, folded into the steps line, or not shown. */
|
|
133
|
+
placement: 'card' | 'step' | 'hidden';
|
|
134
|
+
/** The call has a card of its own (`questions`): the surface draws that card in place of the generic one. */
|
|
135
|
+
card?: string;
|
|
136
|
+
name: string;
|
|
137
|
+
/** Who ran it, with Show which system on. */
|
|
138
|
+
system?: string;
|
|
139
|
+
status: StepStatus;
|
|
140
|
+
/** The status in words; empty for a finished step, whose icon says it. */
|
|
141
|
+
statusLabel: string;
|
|
142
|
+
/** The decision, shown for the reader's own and, with Show who decided on, for everyone's. */
|
|
143
|
+
decision?: StepDecision;
|
|
144
|
+
/** The rules' reason for their decision, with Show who decided on. */
|
|
145
|
+
reason?: string;
|
|
146
|
+
/** The first text the call ran on (a query, an order number): a step's one-line summary. */
|
|
147
|
+
summary?: string;
|
|
148
|
+
/** What the call does, in labelled lines: every value except ids, which only Show step details adds. */
|
|
149
|
+
fields: StepField[];
|
|
150
|
+
/** Raw input, result and error as text, with Show step details on. */
|
|
151
|
+
raw?: {
|
|
152
|
+
input?: string;
|
|
153
|
+
output?: string;
|
|
154
|
+
error?: string;
|
|
155
|
+
};
|
|
156
|
+
/** The approval card: its question, the buttons it offers and the line under them. */
|
|
157
|
+
approval?: {
|
|
158
|
+
ask: string;
|
|
159
|
+
buttons: 'decide' | 'change' | 'none';
|
|
160
|
+
note?: string;
|
|
161
|
+
};
|
|
162
|
+
}
|
|
163
|
+
export type StepStringKey = 'approvalPrompt' | 'approvalEditHint' | 'stepWorking' | 'stepWorkingOnIt' | 'stepNeedsYourApproval' | 'stepWaitingForVisitor' | 'stepApproved' | 'stepDeclined' | 'stepReplaced' | 'stepFailed' | 'stepDidNotWork' | 'statusStopped' | 'decidedYouApproved' | 'decidedYouDeclined' | 'decidedVisitorApproved' | 'decidedVisitorDeclined' | 'decidedTeamApproved' | 'decidedTeamDeclined' | 'decidedRulesApproved' | 'decidedRulesDeclined' | 'toolStepsFailed' | 'toolStepsStopped' | 'toolStepsStoppedOne';
|
|
164
|
+
export type StepStrings = Pick<Strings, StepStringKey>;
|
|
165
|
+
/** `place_order` / `getIssue` / `list-repos` → "Place order" / "Get issue" / "List repos". */
|
|
166
|
+
export declare function nameInWords(name: string): string;
|
|
167
|
+
/** The action's name: its title, else the call's own name in words, never a `site__` or `<integration>__` prefix. */
|
|
168
|
+
export declare function stepName(call: Pick<StepCall, 'toolName' | 'title'>): string;
|
|
169
|
+
/**
|
|
170
|
+
* What a call does, read from the shape of its input, never its tool: every value as one labelled line, a list as its
|
|
171
|
+
* items, a nested object as its own lines. An id means nothing to a reader, so it shows only with step details, or
|
|
172
|
+
* while a person is asked to decide: nobody consents to a value they cannot see.
|
|
173
|
+
*/
|
|
174
|
+
export declare function stepFields(input: unknown, opts: {
|
|
175
|
+
withIds: boolean;
|
|
176
|
+
}): StepField[];
|
|
177
|
+
/** A payload as raw text: indented JSON, a string as it is; nothing for an empty one. */
|
|
178
|
+
export declare function rawText(value: unknown, maxChars?: number): string | undefined;
|
|
179
|
+
/** Everything a surface draws for one call, under the given settings. */
|
|
180
|
+
export declare function stepCallView(call: StepCall, ctx: {
|
|
181
|
+
turn: StepTurn;
|
|
182
|
+
reader: StepReader;
|
|
183
|
+
display: StepDisplay;
|
|
184
|
+
strings: StepStrings;
|
|
185
|
+
}): StepCallView;
|
|
186
|
+
export interface StepGroupLine {
|
|
187
|
+
/** Each action once, in first-seen order, with how often it ran. */
|
|
188
|
+
tools: Array<{
|
|
189
|
+
name: string;
|
|
190
|
+
count: number;
|
|
191
|
+
}>;
|
|
192
|
+
/** A group of one call names it with what it ran on, like its row, and how it ended when no decision says it. */
|
|
193
|
+
single?: {
|
|
194
|
+
name: string;
|
|
195
|
+
summary?: string;
|
|
196
|
+
outcome?: string;
|
|
197
|
+
};
|
|
198
|
+
/** The decisions the group shows, one mark per decider and outcome ("You approved", "Approved automatically ×2"). */
|
|
199
|
+
marks: Array<{
|
|
200
|
+
approved: boolean;
|
|
201
|
+
label: string;
|
|
202
|
+
}>;
|
|
203
|
+
failed: number;
|
|
204
|
+
/** The reply was cut off with a call in progress: how many calls finished first. */
|
|
205
|
+
stopped?: {
|
|
206
|
+
finished: number;
|
|
207
|
+
};
|
|
208
|
+
}
|
|
209
|
+
/** The folded line of a run of steps, from its calls' views. */
|
|
210
|
+
export declare function stepGroupLine(views: StepCallView[]): StepGroupLine;
|
|
211
|
+
/** How far a cut-off run got: "Stopped", "Stopped after 1 step", "Stopped after 3 steps". */
|
|
212
|
+
export declare function stoppedLineLabel(finished: number, strings: StepStrings): string;
|
|
213
|
+
/** The step words in English, for a surface that is not translated. */
|
|
214
|
+
export declare const STEP_STRINGS_EN: StepStrings;
|
|
215
|
+
export {};
|