@helpai/elements 6.9.0 → 6.10.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/llms.txt CHANGED
@@ -1,11 +1,11 @@
1
1
  # Help AI Elements
2
2
 
3
- > Help AI's AI chat widget for any website: an AI agent that answers visitors from the customer's own help content, can hand the chat to a person, and shows Help articles and News. Install it with one script tag, the `<web-ai-chat>` element, the npm API or the React kit. These docs match @helpai/elements@6.9.0.
3
+ > Help AI's AI chat widget for any website: an AI agent that answers visitors from the customer's own help content, can hand the chat to a person, and shows Help articles and News. Install it with one script tag, the `<web-ai-chat>` element, the npm API or the React kit. These docs match @helpai/elements@6.10.0.
4
4
 
5
5
  What a coding agent needs to install it right the first time:
6
6
 
7
7
  - Two values come from the deployment's Install page in the Help AI dashboard: the public key (`agent_pk_…`) and the AI agent deployment id (a UUID). Both belong in browser code. The deployment's secret key never does.
8
- - Plain HTML, WordPress or any CMS: `<script src="https://cdn.help.ai/sdk/js/elements/6.9.0/elements.js" data-public-key="agent_pk_…" data-ai-agent-deployment-id="…" defer></script>`.
8
+ - Plain HTML, WordPress or any CMS: `<script src="https://cdn.help.ai/sdk/js/elements/6.10.0/elements.js" data-public-key="agent_pk_…" data-ai-agent-deployment-id="…" defer></script>`.
9
9
  - React, Next.js, Remix: install `@helpai/elements` and render `<HelpAI publicKey="…" aiAgentDeploymentId="…" />` from `@helpai/elements/react` once, in the root layout. `useHelpAI()` in any component returns `{ state, ask, open, close, reset }`. It is server-render safe; import everything from `@helpai/elements/react`.
10
10
  - Vue, Svelte, Angular and other bundlers: `import '@helpai/elements/web-component'`, then `<web-ai-chat public-key="…" ai-agent-deployment-id="…"></web-ai-chat>`. JSX typings: `@helpai/elements/jsx/react`, `/jsx/vue`, `/jsx/svelte`.
11
11
  - Site buttons need no JavaScript: `data-helpai-ask="Which plan fits a team of 10?"` puts the question in the chat, `data-helpai-open="help"` opens a tab (`home`, `chats`, `help`, `news`). In code, `ask(text)` fills the composer and sends only with `{ send: true }`.
@@ -18,23 +18,23 @@ What a coding agent needs to install it right the first time:
18
18
 
19
19
  ## Docs
20
20
 
21
- - [Quickstart](https://cdn.help.ai/sdk/js/elements/6.9.0/docs/quickstart.md): credentials, the install paths and a first check, in five minutes
22
- - [Installation](https://cdn.help.ai/sdk/js/elements/6.9.0/docs/installation.md): every install path in depth: script tag, async loader, npm, web component, CDN URLs and version pinning
23
- - [Frameworks](https://cdn.help.ai/sdk/js/elements/6.9.0/docs/frameworks.md): the React kit (`<HelpAI />`, `useHelpAI()`), Next.js, Remix, Vue, Nuxt, Svelte, Astro, Angular, WordPress, Shopify, Webflow
24
- - [Configuration](https://cdn.help.ai/sdk/js/elements/6.9.0/docs/configuration.md): every option by group, with examples
25
- - [Option reference](https://cdn.help.ai/sdk/js/elements/6.9.0/docs/options.md): the table of every option, generated from the schemas; authoritative
26
- - [API reference](https://cdn.help.ai/sdk/js/elements/6.9.0/docs/api-reference.md): exports, instance methods (`ask`, `open`, `state`, `ready`, `reset`, …), the global API, no-script triggers, deep links, JSX typings
27
- - [Events and hooks](https://cdn.help.ai/sdk/js/elements/6.9.0/docs/events-and-hooks.md): every event and its payload, `on()` and `hook()`
28
- - [Page tools](https://cdn.help.ai/sdk/js/elements/6.9.0/docs/page-tools.md): WebMCP-shaped tools the AI agent calls on your page (`registerTool`, `tools`, `useHelpAITool`, `<form toolname>`), run once in the browser
29
- - [Theming](https://cdn.help.ai/sdk/js/elements/6.9.0/docs/theming.md): colors, shapes, fonts, launcher styles, `theme: "host"` and `::part()` styling
30
- - [Recipes](https://cdn.help.ai/sdk/js/elements/6.9.0/docs/recipes.md): copy-paste solutions for common integrations
31
- - [Analytics](https://cdn.help.ai/sdk/js/elements/6.9.0/docs/analytics.md): sending widget activity to Google Analytics, Segment, PostHog and other trackers
32
- - [Security and privacy](https://cdn.help.ai/sdk/js/elements/6.9.0/docs/security-privacy.md): isolation, CSP, what the widget stores and sends
33
- - [Browser support](https://cdn.help.ai/sdk/js/elements/6.9.0/docs/browser-support.md): supported browsers and fallbacks
34
- - [Troubleshooting](https://cdn.help.ai/sdk/js/elements/6.9.0/docs/troubleshooting.md): an install that does not show, connect or answer
35
- - [FAQ](https://cdn.help.ai/sdk/js/elements/6.9.0/docs/faq.md): short answers to common questions
36
- - [Overview](https://cdn.help.ai/sdk/js/elements/6.9.0/docs/README.md): the whole SDK on one page
21
+ - [Quickstart](https://cdn.help.ai/sdk/js/elements/6.10.0/docs/quickstart.md): credentials, the install paths and a first check, in five minutes
22
+ - [Installation](https://cdn.help.ai/sdk/js/elements/6.10.0/docs/installation.md): every install path in depth: script tag, async loader, npm, web component, CDN URLs and version pinning
23
+ - [Frameworks](https://cdn.help.ai/sdk/js/elements/6.10.0/docs/frameworks.md): the React kit (`<HelpAI />`, `useHelpAI()`), Next.js, Remix, Vue, Nuxt, Svelte, Astro, Angular, WordPress, Shopify, Webflow
24
+ - [Configuration](https://cdn.help.ai/sdk/js/elements/6.10.0/docs/configuration.md): every option by group, with examples
25
+ - [Option reference](https://cdn.help.ai/sdk/js/elements/6.10.0/docs/options.md): the table of every option, generated from the schemas; authoritative
26
+ - [API reference](https://cdn.help.ai/sdk/js/elements/6.10.0/docs/api-reference.md): exports, instance methods (`ask`, `open`, `state`, `ready`, `reset`, …), the global API, no-script triggers, deep links, JSX typings
27
+ - [Events and hooks](https://cdn.help.ai/sdk/js/elements/6.10.0/docs/events-and-hooks.md): every event and its payload, `on()` and `hook()`
28
+ - [Page tools](https://cdn.help.ai/sdk/js/elements/6.10.0/docs/page-tools.md): WebMCP-shaped tools the AI agent calls on your page (`registerTool`, `tools`, `useHelpAITool`, `<form toolname>`), run once in the browser
29
+ - [Theming](https://cdn.help.ai/sdk/js/elements/6.10.0/docs/theming.md): colors, shapes, fonts, launcher styles, `theme: "host"` and `::part()` styling
30
+ - [Recipes](https://cdn.help.ai/sdk/js/elements/6.10.0/docs/recipes.md): copy-paste solutions for common integrations
31
+ - [Analytics](https://cdn.help.ai/sdk/js/elements/6.10.0/docs/analytics.md): sending widget activity to Google Analytics, Segment, PostHog and other trackers
32
+ - [Security and privacy](https://cdn.help.ai/sdk/js/elements/6.10.0/docs/security-privacy.md): isolation, CSP, what the widget stores and sends
33
+ - [Browser support](https://cdn.help.ai/sdk/js/elements/6.10.0/docs/browser-support.md): supported browsers and fallbacks
34
+ - [Troubleshooting](https://cdn.help.ai/sdk/js/elements/6.10.0/docs/troubleshooting.md): an install that does not show, connect or answer
35
+ - [FAQ](https://cdn.help.ai/sdk/js/elements/6.10.0/docs/faq.md): short answers to common questions
36
+ - [Overview](https://cdn.help.ai/sdk/js/elements/6.10.0/docs/README.md): the whole SDK on one page
37
37
 
38
38
  ## Optional
39
39
 
40
- - [Every doc in one file](https://cdn.help.ai/sdk/js/elements/6.9.0/llms-full.txt): the docs above, concatenated
40
+ - [Every doc in one file](https://cdn.help.ai/sdk/js/elements/6.10.0/llms-full.txt): the docs above, concatenated
package/package.json CHANGED
@@ -129,5 +129,5 @@
129
129
  ],
130
130
  "type": "module",
131
131
  "types": "./index.d.ts",
132
- "version": "6.9.0"
132
+ "version": "6.10.0"
133
133
  }
package/react.d.ts CHANGED
@@ -522,6 +522,23 @@ interface PresentationOptions {
522
522
  type PageToolCallStatus = 'completed' | 'failed' | 'interrupted';
523
523
  /** A 👍/👎 reaction on a rateable (assistant/operator) message; `null` clears a prior choice. */
524
524
  type FeedbackValue = 'up' | 'down' | null;
525
+ /**
526
+ * The kinds of steps a reader may choose to see, folded into one line under the reply: `decided`, it asked a person
527
+ * (a visitor or another member); `auto-decided`, the rules decided it; `unasked`, it ran without asking; `failed`, it
528
+ * failed, whoever decided it. A step has every kind that applies ("auto-decided" and "failed" both, for an approved
529
+ * call that then failed) and shows when any of them is chosen. The reader's own decisions and anything waiting on
530
+ * someone always show.
531
+ */
532
+ declare const STEP_KINDS: readonly ['decided', 'auto-decided', 'unasked', 'failed'];
533
+ type StepKind = (typeof STEP_KINDS)[number];
534
+ /**
535
+ * Where a step came from, as the server marks every call (`toolMetadata.origin`), set once where each family of tools
536
+ * is built: `platform`, help.ai's own tools; `mcp`, an MCP server's (an integration, help.ai's own MCP included);
537
+ * `api`, a call to an API integration; `webmcp`, the page's own tools, run in the visitor's browser (those the site
538
+ * hands the widget and those the browser offers through WebMCP).
539
+ */
540
+ declare const STEP_ORIGINS: readonly ['platform', 'mcp', 'api', 'webmcp'];
541
+ type StepOrigin = (typeof STEP_ORIGINS)[number];
525
542
  /**
526
543
  * What an opened step shows: `none`, nothing (the step line alone, for a business that never shows a visitor's data
527
544
  * back); `values`, its values as quiet label and value lines without ids; `table`, tables of what it ran on (ids
@@ -532,13 +549,15 @@ declare const STEP_DETAILS: readonly ['none', 'values', 'table', 'json', 'table-
532
549
  type StepDetails = (typeof STEP_DETAILS)[number];
533
550
  /** The settings, the same keys on a Deployment (`config.behavior.stepDisplay`) and in a member's Preferences. */
534
551
  interface StepDisplay {
535
- /** Every step appears as one folded line under the reply; off, only the steps that involve the reader do. */
536
- showSteps: boolean;
552
+ /** The origins whose steps may appear (`STEP_ORIGINS`), in any combination. */
553
+ stepsFrom: readonly StepOrigin[];
554
+ /** The kinds of steps that appear (`STEP_KINDS`), in any combination: a step from a chosen origin shows when any of its kinds is chosen. */
555
+ stepsShown: readonly StepKind[];
537
556
  /** What an opened step shows (`STEP_DETAILS`). */
538
557
  stepDetails: StepDetails;
539
558
  /** The system that ran a step follows its name: "Ship an order · BC Co. back office". */
540
559
  showStepSystem: boolean;
541
- /** Each approval says who decided it, and steps the rules decided show as steps. */
560
+ /** Each decision someone else or the rules made says who made it. */
542
561
  showDecidedBy: boolean;
543
562
  /** A decided approval folds into the steps line; off, it stays in the reply as a card. */
544
563
  foldApprovals: boolean;
@@ -554,7 +573,7 @@ interface BehaviorOptions {
554
573
  responseMode?: ResponseMode;
555
574
  /** Show the model's reasoning ("thoughts") as a collapsible block. Default `false`. */
556
575
  showReasoning?: boolean;
557
- /** How the AI's steps and approvals show; unset keys take the Simple preset. */
576
+ /** How the AI's steps and approvals show; unset keys take the visitor defaults. */
558
577
  stepDisplay?: Partial<StepDisplay>;
559
578
  /** Show citation sources (web links + document references) in the transcript. Default `false`. */
560
579
  showSources?: boolean;
@@ -946,7 +965,7 @@ interface ResolvedOptions {
946
965
  responseMode: ResponseMode;
947
966
  /** Show reasoning ("thoughts") as a collapsible block. Default `false`. */
948
967
  showReasoning: boolean;
949
- /** How the AI's steps and approvals show: the Deployment's settings over the Simple preset. */
968
+ /** How the AI's steps and approvals show: the Deployment's settings over the visitor defaults. */
950
969
  stepDisplay: StepDisplay;
951
970
  /** Show citation sources (web links + document references) in the transcript. Default `false`. */
952
971
  showSources: boolean;
@@ -1160,7 +1179,18 @@ declare const widgetSettingsSchema: z.ZodObject<{
1160
1179
  }>>;
1161
1180
  showReasoning: z.ZodDefault<z.ZodBoolean>;
1162
1181
  stepDisplay: z.ZodOptional<z.ZodObject<{
1163
- showSteps: z.ZodOptional<z.ZodBoolean>;
1182
+ stepsFrom: z.ZodOptional<z.ZodArray<z.ZodEnum<{
1183
+ api: "api";
1184
+ mcp: "mcp";
1185
+ platform: "platform";
1186
+ webmcp: "webmcp";
1187
+ }>>>;
1188
+ stepsShown: z.ZodOptional<z.ZodArray<z.ZodEnum<{
1189
+ "auto-decided": "auto-decided";
1190
+ decided: "decided";
1191
+ failed: "failed";
1192
+ unasked: "unasked";
1193
+ }>>>;
1164
1194
  stepDetails: z.ZodOptional<z.ZodEnum<{
1165
1195
  json: "json";
1166
1196
  none: "none";
@@ -1451,7 +1481,18 @@ declare const widgetConfigSchema: z.ZodObject<{
1451
1481
  }>>;
1452
1482
  showReasoning: z.ZodDefault<z.ZodBoolean>;
1453
1483
  stepDisplay: z.ZodOptional<z.ZodObject<{
1454
- showSteps: z.ZodOptional<z.ZodBoolean>;
1484
+ stepsFrom: z.ZodOptional<z.ZodArray<z.ZodEnum<{
1485
+ api: "api";
1486
+ mcp: "mcp";
1487
+ platform: "platform";
1488
+ webmcp: "webmcp";
1489
+ }>>>;
1490
+ stepsShown: z.ZodOptional<z.ZodArray<z.ZodEnum<{
1491
+ "auto-decided": "auto-decided";
1492
+ decided: "decided";
1493
+ failed: "failed";
1494
+ unasked: "unasked";
1495
+ }>>>;
1455
1496
  stepDetails: z.ZodOptional<z.ZodEnum<{
1456
1497
  json: "json";
1457
1498
  none: "none";
@@ -1743,7 +1784,18 @@ declare const widgetConfigPartialSchema: z.ZodObject<{
1743
1784
  }>>;
1744
1785
  showReasoning: z.ZodDefault<z.ZodBoolean>;
1745
1786
  stepDisplay: z.ZodOptional<z.ZodObject<{
1746
- showSteps: z.ZodOptional<z.ZodBoolean>;
1787
+ stepsFrom: z.ZodOptional<z.ZodArray<z.ZodEnum<{
1788
+ api: "api";
1789
+ mcp: "mcp";
1790
+ platform: "platform";
1791
+ webmcp: "webmcp";
1792
+ }>>>;
1793
+ stepsShown: z.ZodOptional<z.ZodArray<z.ZodEnum<{
1794
+ "auto-decided": "auto-decided";
1795
+ decided: "decided";
1796
+ failed: "failed";
1797
+ unasked: "unasked";
1798
+ }>>>;
1747
1799
  stepDetails: z.ZodOptional<z.ZodEnum<{
1748
1800
  json: "json";
1749
1801
  none: "none";
@@ -1997,7 +2049,18 @@ declare const widgetSettingsPartialSchema: z.ZodObject<{
1997
2049
  }>>;
1998
2050
  showReasoning: z.ZodDefault<z.ZodBoolean>;
1999
2051
  stepDisplay: z.ZodOptional<z.ZodObject<{
2000
- showSteps: z.ZodOptional<z.ZodBoolean>;
2052
+ stepsFrom: z.ZodOptional<z.ZodArray<z.ZodEnum<{
2053
+ api: "api";
2054
+ mcp: "mcp";
2055
+ platform: "platform";
2056
+ webmcp: "webmcp";
2057
+ }>>>;
2058
+ stepsShown: z.ZodOptional<z.ZodArray<z.ZodEnum<{
2059
+ "auto-decided": "auto-decided";
2060
+ decided: "decided";
2061
+ failed: "failed";
2062
+ unasked: "unasked";
2063
+ }>>>;
2001
2064
  stepDetails: z.ZodOptional<z.ZodEnum<{
2002
2065
  json: "json";
2003
2066
  none: "none";
@@ -2306,7 +2369,18 @@ declare const serverConfigSchema: z.ZodObject<{
2306
2369
  }>>;
2307
2370
  showReasoning: z.ZodDefault<z.ZodBoolean>;
2308
2371
  stepDisplay: z.ZodOptional<z.ZodObject<{
2309
- showSteps: z.ZodOptional<z.ZodBoolean>;
2372
+ stepsFrom: z.ZodOptional<z.ZodArray<z.ZodEnum<{
2373
+ api: "api";
2374
+ mcp: "mcp";
2375
+ platform: "platform";
2376
+ webmcp: "webmcp";
2377
+ }>>>;
2378
+ stepsShown: z.ZodOptional<z.ZodArray<z.ZodEnum<{
2379
+ "auto-decided": "auto-decided";
2380
+ decided: "decided";
2381
+ failed: "failed";
2382
+ unasked: "unasked";
2383
+ }>>>;
2310
2384
  stepDetails: z.ZodOptional<z.ZodEnum<{
2311
2385
  json: "json";
2312
2386
  none: "none";
@@ -2637,7 +2711,18 @@ declare const handshakeResponseSchema: z.ZodObject<{
2637
2711
  }>>;
2638
2712
  showReasoning: z.ZodDefault<z.ZodBoolean>;
2639
2713
  stepDisplay: z.ZodOptional<z.ZodObject<{
2640
- showSteps: z.ZodOptional<z.ZodBoolean>;
2714
+ stepsFrom: z.ZodOptional<z.ZodArray<z.ZodEnum<{
2715
+ api: "api";
2716
+ mcp: "mcp";
2717
+ platform: "platform";
2718
+ webmcp: "webmcp";
2719
+ }>>>;
2720
+ stepsShown: z.ZodOptional<z.ZodArray<z.ZodEnum<{
2721
+ "auto-decided": "auto-decided";
2722
+ decided: "decided";
2723
+ failed: "failed";
2724
+ unasked: "unasked";
2725
+ }>>>;
2641
2726
  stepDetails: z.ZodOptional<z.ZodEnum<{
2642
2727
  json: "json";
2643
2728
  none: "none";