@8wave/ai-elements 0.119.0 → 0.121.0-beta.1

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/README.md CHANGED
@@ -81,7 +81,11 @@ Copy it from **Embed > Chat widget**: its host is the backend of your installati
81
81
  published yet), or the agent's widget URL in **Embed** when it has one, see
82
82
  [Dedicated installations](#dedicated-installations);
83
83
  3. creates `<floating-chat-widget organization-slug agent-id base-url>` and appends it to
84
- `<body>`.
84
+ `<body>`, with your user's token when its tag carries one, see
85
+ [Your signed-in user with `embed.js`](#your-signed-in-user-with-embedjs).
86
+
87
+ The tag can go in `<head>` or `<body>`, with or without `defer`: when the bundle is ready before
88
+ the page has a `<body>` (the tag in `<head>`, a slow script after it), the widget waits for it.
85
89
 
86
90
  It answers 404 when the agent does not exist or its **Widget** channel is off. Browsers and CDNs
87
91
  may keep it for up to ten minutes, so a new loader strategy or delay is not immediate.
@@ -95,7 +99,9 @@ Loader strategies, for sites where the default fails:
95
99
  | **Dynamic import** | `import()` inside a classic script | Pages whose loaders intercept module scripts |
96
100
 
97
101
  > Never put `embed.js` and your own `<floating-chat-widget>` for the same agent on one page: by
98
- > step 1 the script then loads nothing, and your element never becomes a widget.
102
+ > step 1 the script then loads nothing, and your element never becomes a widget. Put the snippet
103
+ > once per page, too: with two tags for the same agent (one in the HTML, one from a tag manager)
104
+ > the first to run mounts the widget, and the attributes of the other are ignored.
99
105
 
100
106
  ### Talking to the widget `embed.js` created
101
107
 
@@ -138,10 +144,54 @@ document.querySelector('#ask-about-this').addEventListener('click', () => {
138
144
  - Listen to the [events](#events) on `document`: they bubble out of the widget, so the listener
139
145
  needs no element and catches the first `signed-in` and `ready` too.
140
146
  - Tools registered as soon as the widget appears go with the first message the user sends.
141
- - To hand the widget your signed-in user, call `widget.signIn(token)`: an anonymous session it
142
- may have started is upgraded to that user.
143
- - `await-external-token` and `cookie-name` are read when the widget starts, before your code can
144
- reach it. A page that needs them places its own element with `loader.js`.
147
+ - To hand the widget your signed-in user, put the token on the script's tag (next section).
148
+ `widget.signIn(token)` works too: an anonymous session the widget may have started is upgraded
149
+ to that user.
150
+ - `cookie-name` is read when the widget starts, before your code can reach it. A page that needs
151
+ it places its own element with `loader.js`.
152
+
153
+ ### Your signed-in user with `embed.js`
154
+
155
+ Put the user's token on the tag that loads the script, never in its URL: the script is the same
156
+ for every visitor, and browsers and CDNs keep it.
157
+
158
+ ```html
159
+ <script id="eightwave-chat" src="https://ai-api.8wave.it/api/v1/public/organizations/<organization-slug>/agents/<agent-id>/embed.js"
160
+ data-external-token="eyJhbGciOiJSUzI1NiIs..." defer></script>
161
+ ```
162
+
163
+ - `data-external-token` becomes the widget's [`external-token`](#external-token-jwt), with the
164
+ same rules, and stays in step with it for as long as the page lives: set it, change it or clear
165
+ it (empty, or remove the attribute) on the tag, before or after the widget appears, and the
166
+ widget follows.
167
+ - `data-await-external-token` becomes `await-external-token`: no anonymous session is created
168
+ while your page fetches the token. It is read once, when the widget starts.
169
+
170
+ When the token arrives after the page has loaded:
171
+
172
+ ```html
173
+ <script id="eightwave-chat" src="https://ai-api.8wave.it/api/v1/public/organizations/<organization-slug>/agents/<agent-id>/embed.js"
174
+ data-await-external-token defer></script>
175
+ ```
176
+
177
+ ```js
178
+ const chat = document.getElementById('eightwave-chat')
179
+ chat.dataset.externalToken = await fetchTokenFromMyApi() // one session, the user's
180
+
181
+ // The same user's next token, before the current one expires
182
+ document.addEventListener('external-token-expiring', async () => {
183
+ chat.dataset.externalToken = await fetchTokenFromMyApi()
184
+ })
185
+
186
+ // When the user signs out of your site
187
+ delete chat.dataset.externalToken
188
+ ```
189
+
190
+ The script finds its tag through `document.currentScript`, the script element running at that
191
+ moment, so it must run from its own `<script src>` tag, as in the snippet. Run any other way
192
+ (fetched and evaluated, or bundled into your code) it reads no tag, or the tag of the script that
193
+ runs it, and the widget starts without your user: call `signIn(token)` on it, or place
194
+ [your own element](#your-own-element-loaderjs).
145
195
 
146
196
  ### Your own element (`loader.js`)
147
197
 
@@ -452,6 +502,8 @@ lifecycle.
452
502
  restored session with the token: with a token it signs in again, and without one it signs the
453
503
  restored external session out. A user who signed out in another tab is signed out here too.
454
504
  - `signIn(token)` and `signOut()` do the same imperatively.
505
+ - With `embed.js` the attribute is set from the script's tag:
506
+ [`data-external-token`](#your-signed-in-user-with-embedjs).
455
507
 
456
508
  An agent can use MCP servers that receive the user's token (authentication type "External
457
509
  authentication token per user"). They need a valid token on every message, and your token
@@ -1083,6 +1135,7 @@ For whoever runs the backend:
1083
1135
  | The button never appears; `embed.js` answers 404 | The agent is not active, or its **Widget** channel is off | **General**: status and **Channels** |
1084
1136
  | CORS errors in the console, the widget never signs in | The page's origin is not in any agent's **Trusted origins** | List the exact origin (scheme, host, port); wait up to five minutes |
1085
1137
  | Your `<floating-chat-widget>` stays an empty element | `embed.js` found it and loaded nothing, or nothing loads the bundle | Use `loader.js` or the npm package with your own element |
1138
+ | The widget of `embed.js` ignores `data-external-token` | The script did not run from its own `<script src>` tag, or the page still holds a copy from before the release (cached up to ten minutes) | Load it with the snippet's tag; or call `signIn(token)` on the widget |
1086
1139
  | `widget.registerTool is not a function` | Called before the element was defined | `await customElements.whenDefined('floating-chat-widget')` first |
1087
1140
  | The agent never calls a tool you registered | **Accept the app's tools** off, the name not in **Allowed tools**, a reserved prefix, a name the agent already has, an invalid definition | Check the backoffice and the [definition rules](#the-definition); the server log names every dropped tool |
1088
1141
  | A tool call ends with "no answer" | `execute` exceeded **Maximum wait**, ignored its `signal`, or the tool was unregistered | Answer faster or raise the wait; keep the tool registered while the chat is open |
package/dist-vue/index.js CHANGED
@@ -657,7 +657,7 @@ var ja = { class: "flex items-center gap-4 mb-4" }, Ma = { class: "font-semibold
657
657
  }
658
658
  });
659
659
  //#endregion
660
- //#region virtual:intlify-i18n-2
660
+ //#region virtual:intlify-i18n-0
661
661
  function Ra(e) {
662
662
  let t = e;
663
663
  t.__i18n = t.__i18n || [], t.__i18n.push({
@@ -766,7 +766,7 @@ var za = La, Ba = { class: "flex items-center gap-4 mb-4" }, Va = { class: "font
766
766
  }
767
767
  });
768
768
  //#endregion
769
- //#region virtual:intlify-i18n-3
769
+ //#region virtual:intlify-i18n-1
770
770
  function Xa(e) {
771
771
  let t = e;
772
772
  t.__i18n = t.__i18n || [], t.__i18n.push({
@@ -873,7 +873,7 @@ var Za = Ya, Qa = { class: "flex items-center gap-4 mb-4" }, $a = { class: "font
873
873
  }
874
874
  });
875
875
  //#endregion
876
- //#region virtual:intlify-i18n-4
876
+ //#region virtual:intlify-i18n-2
877
877
  function ao(e) {
878
878
  let t = e;
879
879
  t.__i18n = t.__i18n || [], t.__i18n.push({
@@ -16458,7 +16458,7 @@ var ow = /*#__PURE__*/ rw(iw, [["render", aw]]), sw = {
16458
16458
  }
16459
16459
  });
16460
16460
  //#endregion
16461
- //#region virtual:intlify-i18n-0
16461
+ //#region virtual:intlify-i18n-3
16462
16462
  function gw(e) {
16463
16463
  let t = e;
16464
16464
  t.__i18n = t.__i18n || [], t.__i18n.push({
@@ -16669,7 +16669,7 @@ var _w = hw, vw = { class: "block text-smaller mt-4" }, yw = { class: "block tex
16669
16669
  }
16670
16670
  });
16671
16671
  //#endregion
16672
- //#region virtual:intlify-i18n-1
16672
+ //#region virtual:intlify-i18n-4
16673
16673
  function Cw(e) {
16674
16674
  let t = e;
16675
16675
  t.__i18n = t.__i18n || [], t.__i18n.push({