@helpai/elements 6.14.0 → 7.0.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/docs/frameworks.md +7 -3
- package/docs/installation.md +10 -10
- package/elements-web-component.esm.js +32 -32
- package/elements-web-component.esm.js.map +3 -3
- package/elements.cjs.js +33 -33
- package/elements.cjs.js.map +4 -4
- package/elements.esm.js +33 -33
- package/elements.esm.js.map +4 -4
- package/elements.js +33 -33
- package/elements.js.map +4 -4
- package/index.d.ts +7 -7
- package/index.mjs +21 -21
- package/llms-full.txt +157 -153
- package/llms.txt +19 -19
- package/package.json +2 -1
- package/react-BBw_sT1s.mjs +3 -0
- package/react-Dpi-Oi92.mjs +73 -0
- package/react.d.ts +45 -18
- package/react.mjs +1 -71
- package/style.css +1 -1
- package/web-component.mjs +21 -21
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@
|
|
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@7.0.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/
|
|
8
|
+
- Plain HTML, WordPress or any CMS: `<script src="https://cdn.help.ai/sdk/js/elements/7.0.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/
|
|
22
|
-
- [Installation](https://cdn.help.ai/sdk/js/elements/
|
|
23
|
-
- [Frameworks](https://cdn.help.ai/sdk/js/elements/
|
|
24
|
-
- [Configuration](https://cdn.help.ai/sdk/js/elements/
|
|
25
|
-
- [Option reference](https://cdn.help.ai/sdk/js/elements/
|
|
26
|
-
- [API reference](https://cdn.help.ai/sdk/js/elements/
|
|
27
|
-
- [Events and hooks](https://cdn.help.ai/sdk/js/elements/
|
|
28
|
-
- [Page tools](https://cdn.help.ai/sdk/js/elements/
|
|
29
|
-
- [Theming](https://cdn.help.ai/sdk/js/elements/
|
|
30
|
-
- [Recipes](https://cdn.help.ai/sdk/js/elements/
|
|
31
|
-
- [Analytics](https://cdn.help.ai/sdk/js/elements/
|
|
32
|
-
- [Security and privacy](https://cdn.help.ai/sdk/js/elements/
|
|
33
|
-
- [Browser support](https://cdn.help.ai/sdk/js/elements/
|
|
34
|
-
- [Troubleshooting](https://cdn.help.ai/sdk/js/elements/
|
|
35
|
-
- [FAQ](https://cdn.help.ai/sdk/js/elements/
|
|
36
|
-
- [Overview](https://cdn.help.ai/sdk/js/elements/
|
|
21
|
+
- [Quickstart](https://cdn.help.ai/sdk/js/elements/7.0.0/docs/quickstart.md): credentials, the install paths and a first check, in five minutes
|
|
22
|
+
- [Installation](https://cdn.help.ai/sdk/js/elements/7.0.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/7.0.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/7.0.0/docs/configuration.md): every option by group, with examples
|
|
25
|
+
- [Option reference](https://cdn.help.ai/sdk/js/elements/7.0.0/docs/options.md): the table of every option, generated from the schemas; authoritative
|
|
26
|
+
- [API reference](https://cdn.help.ai/sdk/js/elements/7.0.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/7.0.0/docs/events-and-hooks.md): every event and its payload, `on()` and `hook()`
|
|
28
|
+
- [Page tools](https://cdn.help.ai/sdk/js/elements/7.0.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/7.0.0/docs/theming.md): colors, shapes, fonts, launcher styles, `theme: "host"` and `::part()` styling
|
|
30
|
+
- [Recipes](https://cdn.help.ai/sdk/js/elements/7.0.0/docs/recipes.md): copy-paste solutions for common integrations
|
|
31
|
+
- [Analytics](https://cdn.help.ai/sdk/js/elements/7.0.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/7.0.0/docs/security-privacy.md): isolation, CSP, what the widget stores and sends
|
|
33
|
+
- [Browser support](https://cdn.help.ai/sdk/js/elements/7.0.0/docs/browser-support.md): supported browsers and fallbacks
|
|
34
|
+
- [Troubleshooting](https://cdn.help.ai/sdk/js/elements/7.0.0/docs/troubleshooting.md): an install that does not show, connect or answer
|
|
35
|
+
- [FAQ](https://cdn.help.ai/sdk/js/elements/7.0.0/docs/faq.md): short answers to common questions
|
|
36
|
+
- [Overview](https://cdn.help.ai/sdk/js/elements/7.0.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/
|
|
40
|
+
- [Every doc in one file](https://cdn.help.ai/sdk/js/elements/7.0.0/llms-full.txt): the docs above, concatenated
|
package/package.json
CHANGED
|
@@ -60,6 +60,7 @@
|
|
|
60
60
|
"web-component.mjs",
|
|
61
61
|
"web-component.d.ts",
|
|
62
62
|
"react.mjs",
|
|
63
|
+
"react-*.mjs",
|
|
63
64
|
"react.d.ts",
|
|
64
65
|
"server.mjs",
|
|
65
66
|
"server.d.ts",
|
|
@@ -129,5 +130,5 @@
|
|
|
129
130
|
],
|
|
130
131
|
"type": "module",
|
|
131
132
|
"types": "./index.d.ts",
|
|
132
|
-
"version": "
|
|
133
|
+
"version": "7.0.0"
|
|
133
134
|
}
|
|
@@ -0,0 +1,3 @@
|
|
|
1
|
+
'use client';
|
|
2
|
+
const e={id:`help-ai`,name:`@helpai/elements`,global:`HelpAI`,tagName:`web-ai-chat`,cssPrefix:`helpai`,defaultBaseUrl:`https://help.ai`,displayName:`Help AI`,domain:`help.ai`,siteUrl:`https://help.ai`},t=[`off`,`error`,`warn`,`info`,`debug`,`trace`],n=e.cssPrefix,r=`${n}.debug`,i=`__${e.global}_DEBUG__`,a=`${n}-debug`;let o=2,s=null;function c(){if(typeof window>`u`)return 2;try{let e=new URLSearchParams(window.location.search).get(a);if(e!==null){let t=l(e);if(t>=0)return t}}catch{}try{let e=window.localStorage?.getItem(r);if(e){let t=l(e);if(t>=0)return t}}catch{}return Reflect.get(window,i)?4:2}function l(e){if(e===!0||e===`1`||e===`true`)return 4;if(e===!1||e===`0`||e===`false`||e===`off`)return 0;if(typeof e==`number`)return Math.max(0,Math.min(5,Math.floor(e)));if(typeof e==`string`){let n=t.findIndex(t=>t===e);if(n>=0)return n}return-1}function u(e){let n=l(e);if(!(n<0)){o=n;try{window.localStorage?.setItem(r,t[n]??`off`)}catch{}}}function ee(){return t[o]??`warn`}o=c();function d(e){let t=`[${n}:${e}]`;function r(n,r,i){return(a,c)=>{if(!(o<n)&&(c===void 0?console[r](t,a):console[r](t,a,c),s))try{s({level:i,scope:e,message:a,payload:c})}catch{}}}return{error:r(1,`error`,`error`),warn:r(2,`warn`,`warn`),info:r(3,`info`,`info`),debug:r(4,`debug`,`debug`),trace:r(5,`debug`,`trace`),scope:t=>d(`${e}:${t}`)}}const f=d(`core`);function p(e){s=e}function m(e){"@babel/helpers - typeof";return m=typeof Symbol==`function`&&typeof Symbol.iterator==`symbol`?function(e){return typeof e}:function(e){return e&&typeof Symbol==`function`&&e.constructor===Symbol&&e!==Symbol.prototype?`symbol`:typeof e},m(e)}function h(e,t){if(m(e)!=`object`||!e)return e;var n;if(typeof Symbol<`u`&&(n=e[Symbol.toPrimitive])!==void 0){var r=n.call(e,t||`default`);if(m(r)!=`object`)return r;throw TypeError(`@@toPrimitive must return a primitive value.`)}return(t===`string`?String:Number)(e)}function te(e){var t=h(e,`string`);return m(t)==`symbol`?t:t+``}function g(e,t,n){return(t=te(t))in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}const _=f.scope(`events`),v={open:!1,ready:!1,unread:0};var y=class{constructor(){g(this,`handlers`,/* @__PURE__ */ new Map),g(this,`taps`,/* @__PURE__ */ new Set)}on(e,t){let n=this.handlers.get(e);return n||(n=/* @__PURE__ */ new Set,this.handlers.set(e,n)),n.add(t),()=>this.handlers.get(e)?.delete(t)}tap(e){return this.taps.add(e),()=>this.taps.delete(e)}listensTo(e){return(this.handlers.get(e)?.size??0)>0||[...this.taps].some(t=>t.listensTo(e))}emit(e,t){for(let n of this.handlers.get(e)??[])try{n(t)}catch(t){_.warn(`listener threw`,{event:e,error:t})}for(let n of this.taps)n.hear(e,t)}clear(){this.handlers.clear(),this.taps.clear()}};const b=f.scope(`hooks`),x=`*`,S=/* @__PURE__ */ new Set;function C(e,t,n){let r={widgetId:e,event:t,listener:n};return S.add(r),()=>{S.delete(r)}}function w(e,t,n){let r=[...S];for(let i of r)if(E(i.widgetId,e.widgetId)&&(i.event===`*`||i.event===t))try{i.listener(e,t,n)}catch(e){b.warn(`hook listener threw`,{event:t,error:e})}}function T(e,t){return t.tap({hear:(t,n)=>w(e,t,n),listensTo:t=>[...S].some(n=>n.event===t&&E(n.widgetId,e.widgetId))})}function E(e,t){return e===`*`||e===t}const D=/* @__PURE__ */ new Map;function ne(e=`default`){return D.get(e)??null}function re(){return[...D.values()]}const ie=/* @__PURE__ */ new Set([`hidden`,`submit`,`button`,`reset`,`image`,`file`,`password`]);function O(e){return e instanceof HTMLInputElement||e instanceof HTMLSelectElement||e instanceof HTMLTextAreaElement}function ae(e){return!O(e)||e.name===``||e.disabled?!1:!(e instanceof HTMLInputElement&&ie.has(e.type))}function oe(e){let t=e.labels?.[0]?.textContent?.trim();return e.getAttribute(`toolparamdescription`)??(t||e.getAttribute(`aria-description`))??void 0}function se(e,t){let n=oe(e),r=n?{description:n}:{};return e instanceof HTMLSelectElement?{...r,type:`string`,enum:[...e.options].map(e=>e.value)}:e instanceof HTMLTextAreaElement?{...r,type:`string`}:e.type===`checkbox`?{...r,type:`boolean`}:e.type===`radio`?{...r,type:`string`,enum:t}:e.type===`number`||e.type===`range`?{...r,type:`number`}:{...r,type:`string`}}function ce(e,t){Object.getOwnPropertyDescriptor(Reflect.getPrototypeOf(e)??e,`value`)?.set?.call(e,t),e.dispatchEvent(new Event(`input`,{bubbles:!0})),e.dispatchEvent(new Event(`change`,{bubbles:!0}))}function k(e){return e==null?``:typeof e==`string`?e:JSON.stringify(e)}function le(e,t){e instanceof HTMLInputElement&&e.type===`checkbox`?e.checked!==(t===!0||t===`true`)&&e.click():e instanceof HTMLInputElement&&e.type===`radio`?e.value===k(t)&&!e.checked&&e.click():ce(e,k(t))}function A(e,t,n){let r=[...e.elements].filter(ae),i={},a=/* @__PURE__ */ new Set;for(let e of r){var o;let t=r.flatMap(t=>t instanceof HTMLInputElement&&t.type===`radio`&&t.name===e.name?[t.value]:[]);i[o=e.name]??(i[o]=se(e,t)),e.required&&a.add(e.name)}return{name:t,description:n,inputSchema:{type:`object`,properties:i,...a.size>0?{required:[...a]}:{}},execute(t){let n=typeof t==`object`&&t?Object.entries(t):[];for(let[e,t]of n)for(let n of r)n.name===e&&le(n,t);if(!e.hasAttribute(`toolautosubmit`))return`Filled in the form. The visitor still needs to check it and press its submit button.`;let i=[...new Set([...e.elements].flatMap(e=>O(e)&&e.name&&!e.checkValidity()?[e.name]:[]))];return i.length>0?`Filled in the form, but it can't be submitted yet: ${i.join(`, `)} still needs the visitor. Ask them to complete it and press the submit button.`:(setTimeout(()=>e.requestSubmit(),0),`Filled in the form and submitted it.`)}}}function j(){return[...document.querySelectorAll(`form[toolname][tooldescription]`)].flatMap(e=>{let t=e.getAttribute(`toolname`)?.trim()??``,n=e.getAttribute(`tooldescription`)?.trim()??``;return t&&n?[A(e,t,n)]:[]})}const M=`${e.cssPrefix}.page-tools`;function N(e){return typeof e==`object`&&!!e}function P(e){return N(e)&&(e.state===`running`||e.state===`stopped`||e.state===`finished`&&N(e.outcome))}function F(e){let t=e?JSON.parse(e):void 0;return N(t)?{sent:Array.isArray(t.sent)?t.sent.filter(e=>typeof e==`string`):[],calls:Object.fromEntries(Object.entries(N(t.calls)?t.calls:{}).filter(e=>P(e[1])))}:{sent:[],calls:{}}}let I={sent:[],calls:{}};function L(){try{I=F(sessionStorage.getItem(M))}catch{}return I}function R(e){I=e;try{sessionStorage.setItem(M,JSON.stringify(e))}catch{}}const z={markSent(e){let t=L();R({...t,sent:[...t.sent.filter(t=>t!==e),e].slice(-20)})},sentHere(e){return L().sent.includes(e)},get(e){return L().calls[e]},set(e,t){let n=L(),r=Object.entries(n.calls).filter(([t])=>t!==e);R({...n,calls:Object.fromEntries([...r,[e,t]].slice(-50))})},clear(e){let t=L();e.some(e=>e in t.calls)&&R({...t,calls:Object.fromEntries(Object.entries(t.calls).filter(([t])=>!e.includes(t)))})}};function B(e,t){return new Promise(n=>{if(t?.aborted)return n();let r=setTimeout(a,e);function i(){return a()}t?.addEventListener(`abort`,i,{once:!0});function a(){clearTimeout(r),t?.removeEventListener(`abort`,i),n()}})}const V=f.scope(`page-tools`),H=3e4,U=Symbol.for(`${e.cssPrefix}.page-tools`),W={state:`output-error`,errorText:`The page reloaded before this finished, so it may or may not have taken effect. Check with the visitor before trying it again.`},G=`The visitor stopped this before it finished.`;function K(e){return typeof e==`object`&&!!e}function ue(e){return K(e)&&Array.isArray(e.registered)&&e.runs instanceof Map}function q(){let e=Reflect.get(globalThis,U);if(ue(e))return e;let t={registered:[],runs:/* @__PURE__ */ new Map};return Reflect.set(globalThis,U,t),t}function de(e,t){let n=K(t)&&t.signal instanceof AbortSignal?t.signal:void 0;if(n?.aborted)return;let r=q().registered;r.push(e);function i(){let t=r.indexOf(e);t>=0&&r.splice(t,1)}n?.addEventListener(`abort`,i,{once:!0})}function J(e){return e.replace(/[^A-Za-z0-9_-]/g,`_`).slice(0,58)}function Y(e){if(!K(e)||typeof e.name!=`string`||!J(e.name))return;let t=typeof e.title==`string`&&e.title.trim()!==``?e.title.trim().slice(0,120):void 0,n=[e.description,t].find(e=>typeof e==`string`&&e.trim()!==``)??e.name,r=e.preview;return{name:J(e.name),...t?{title:t}:{},...typeof r==`function`?{preview:t=>Reflect.apply(r,e,[t])}:{},description:n.trim().slice(0,1024),inputSchema:{properties:{},...K(e.inputSchema)?e.inputSchema:{},type:`object`},consequential:K(e.annotations)&&e.annotations.consequentialHint===!0}}function X(e){return e.flatMap(e=>{let t=Y(e),n=K(e)?e.execute:void 0;return!t||typeof n!=`function`?(V.warn(`skipped a tool without a name or an execute function`,e),[]):[{...t,run:(t,r)=>Reflect.apply(n,e,[t,{signal:r}])}]})}async function fe(){let e=Reflect.get(document,`modelContext`)??Reflect.get(navigator,`modelContext`);if(!K(e)||typeof e.getTools!=`function`||typeof e.executeTool!=`function`)return[];let t=e.getTools,n=e.executeTool,r=await Promise.race([Promise.resolve().then(()=>Reflect.apply(t,e,[])),B(1e3).then(()=>[])]).catch(()=>[]);return(Array.isArray(r)?r:[]).flatMap(t=>{let r=Y(t);return r?[{...r,run:(r,i)=>Reflect.apply(n,e,[t,r,{signal:i}])}]:[]})}async function Z(e=[]){let t=X(j()),n=new Set(t.map(e=>e.name)),r=[...(await fe()).filter(e=>!n.has(e.name)),...t,...X(e),...X(q().registered)];return new Map(r.map(e=>[e.name,e]))}function pe(e){return[...e.values()].map(({name:e,title:t,description:n,inputSchema:r,consequential:i})=>{let a={name:e,description:n,inputSchema:r};return t&&(a.title=t),i&&(a.annotations={consequentialHint:!0}),a})}function me(e){return e?.execution===`client`}function Q(e){return e.startsWith(`site__`)?e.slice(6):e}function he(e){if(e===void 0||typeof e==`function`||typeof e==`symbol`)return null;let t=/* @__PURE__ */ new WeakSet,n=JSON.stringify(e,(e,n)=>{if(typeof n==`bigint`)return n.toString();if(typeof n!=`function`&&typeof n!=`symbol`)return n instanceof Node?`[${n.nodeName.toLowerCase()}]`:K(n)?t.has(n)?`[circular]`:(t.add(n),n):n});return n.length>H?{truncated:!0,preview:n.slice(0,H)}:JSON.parse(n)}async function ge(e){let t=(await Z(e.optionTools)).get(Q(e.toolName));if(!t?.preview)return;let n=t.preview;return Promise.resolve().then(()=>n(e.input)).catch(e=>{V.warn(`a page tool preview failed`,{name:t.name,error:e})})}async function $(e){let t=Q(e.toolName),n=(await Z(e.optionTools)).get(t);return n?Promise.resolve().then(()=>n.run(e.input,e.signal)).then(e=>({state:`output-available`,output:he(e)})).catch(e=>(V.warn(`a page tool failed`,{name:t,error:e}),{state:`output-error`,errorText:(e instanceof Error?e.message:String(e)).slice(0,1e3)||`The page tool failed.`})):{state:`output-error`,errorText:`This page doesn't offer "${t}" right now; the visitor may have moved on. Tell them, or continue without it.`}}function _e(e){let{toolCallId:t}=e,n=z.get(t);if(n?.state===`finished`)return Promise.resolve(n.outcome);let{runs:r}=q(),i=r.get(t);if(i)return i.outcome;if(n?.state===`running`)return z.set(t,{state:`finished`,outcome:W}),e.onSettled(`interrupted`,0),Promise.resolve(W);let a=new AbortController,o=performance.now();z.set(t,{state:`running`});let s=$({...e,signal:a.signal}).then(n=>(r.delete(t),z.get(t)?.state===`running`&&(z.set(t,{state:`finished`,outcome:n}),e.onSettled(n.state===`output-available`?`completed`:`failed`,Math.round(performance.now()-o))),n));return r.set(t,{outcome:s,controller:a}),s}function ve(e){return e===W.errorText||e===G}function ye(e){return z.set(e,{state:`stopped`}),q().runs.get(e)?.controller.abort(),G}function be(e){z.clear([e]),q().runs.get(e)?.controller.abort()}const xe=`7.0.0`;export{ee as C,e as D,p as E,g as S,u as T,x as _,ve as a,y as b,ge as c,ye as d,B as f,D as g,ne as h,me as i,de as l,re as m,be as n,pe as o,z as p,Z as r,Q as s,xe as t,_e as u,C as v,f as w,v as x,T as y};
|
|
3
|
+
//# sourceMappingURL=react-BBw_sT1s.mjs.map
|