@8wave/ai-elements 0.69.0 → 0.70.0

package/README.md

@@ -76,6 +76,8 @@ Then use either element anywhere in your HTML:
 
 By default both custom elements sign in anonymously. If your application already has an authenticated user, pass their JWT via the `external-token` attribute to link the chat session to that user. When the token is invalid or expired the component falls back to anonymous sign-in automatically.
 
+The `external-token` attribute is **reactive** — you can set or change it at any time after mount and the widget will automatically authenticate with the new token. If the token is not available at mount time, add the `await-external-token` attribute to prevent the widget from creating an anonymous session:
+
 ```html
 <floating-chat-widget
   organization-slug="your-org-slug"
@@ -91,6 +93,24 @@ const widget = document.querySelector('floating-chat-widget')
 widget.setAttribute('external-token', currentUser.jwt)
 ```
 
+If the token is fetched asynchronously, use `await-external-token` to prevent anonymous sign-in while waiting:
+
+```html
+<floating-chat-widget
+  organization-slug="your-org-slug"
+  agent-id="your-agent-id"
+  await-external-token
+></floating-chat-widget>
+```
+
+```js
+const widget = document.querySelector('floating-chat-widget')
+
+// Widget waits — no anonymous session is created
+const jwt = await fetchTokenFromMyApi()
+widget.setAttribute('external-token', jwt) // Single session created
+```
+
 > **Note:** The `external-token` value is validated server-side. On a 401 response the component silently re-authenticates — either with the external token again or falling back to anonymous.
 
 ## Attributes
@@ -102,7 +122,8 @@ widget.setAttribute('external-token', currentUser.jwt)
 | `agent-id`                 | `string`             | ✅       | —                               | The unique identifier of the AI agent to connect to.                                                 |
 | `organization-slug`        | `string`             | ✅       | —                               | The slug of the organization that owns the agent.                                                    |
 | `base-url`               | `string`             | ❌       | `https://ai-api.8wave.it` (build-time) | Base URL of the Eight Wave backend API. Override when self-hosting or pointing to a different environment. |
-| `external-token`           | `string`             | ❌       | —                               | Pre-existing auth token. When provided, anonymous sign-in is skipped and this token is used instead. |
+| `external-token`           | `string`             | ❌       | —                               | Pre-existing auth token. **Reactive** — can be set or changed at any time. When set, the widget authenticates with this token instead of anonymous sign-in. |
+| `await-external-token`     | `boolean`            | ❌       | `false`                         | When present, the widget waits for `external-token` instead of signing in anonymously. Use when the token is fetched asynchronously after mount. |
 | `floating-button-position` | `'left' \| 'right'` | ❌       | `'right'`                       | Position of the floating toggle button on the screen.                                                |
 | `custom-css`               | `string`             | ❌       | —                               | Raw CSS string injected into the shadow root to override default styles.                             |
 
@@ -113,7 +134,8 @@ widget.setAttribute('external-token', currentUser.jwt)
 | `agent-id`          | `string` | ✅       | —                               | The unique identifier of the AI agent to connect to.                                                 |
 | `organization-slug` | `string` | ✅       | —                               | The slug of the organization that owns the agent.                                                    |
 | `base-url`          | `string` | ❌       | `https://ai-api.8wave.it` (build-time) | Base URL of the Eight Wave backend API. Override when self-hosting or pointing to a different environment. |
-| `external-token`    | `string` | ❌       | —                               | Pre-existing auth token. When provided, anonymous sign-in is skipped and this token is used instead. |
+| `external-token`    | `string` | ❌       | —                               | Pre-existing auth token. **Reactive** — can be set or changed at any time. When set, the widget authenticates with this token instead of anonymous sign-in. |
+| `await-external-token` | `boolean` | ❌    | `false`                         | When present, the widget waits for `external-token` instead of signing in anonymously. Use when the token is fetched asynchronously after mount. |
 | `forwarded-slots`   | `string` | ❌       | —                               | Comma-separated slot names to forward to `PkChatbot` (e.g. `"tool-showArtifact,subagent"`).         |
 | `custom-css`        | `string` | ❌       | —                               | Raw CSS string injected into the shadow root to override default styles.                             |
 
@@ -266,7 +288,8 @@ const { client, session, isAuthenticating, token, headers, onError, userId } = u
 | --------------- | -------------------------------- | -------- | ------------------------------------------------------------------------ |
 | `baseUrl`       | `string`                         | ❌       | Base URL of the Eight Wave backend. Defaults to `https://ai-api.8wave.it` (build-time env variable). |
 | `basePath`      | `string`                         | ❌       | Auth base path appended to `baseUrl`. Defaults to `auth`.               |
-| `externalToken` | `string`                         | ❌       | Pre-existing auth token. When provided, anonymous sign-in is skipped.   |
+| `externalToken` | `MaybeRefOrGetter<string \| undefined>` | ❌       | Pre-existing auth token. Accepts a static string, a ref, or a getter. When the value is truthy, the composable authenticates with it instead of signing in anonymously. Reactive — authentication triggers automatically when the value changes. |
+| `awaitExternalToken` | `boolean`                       | ❌       | When `true`, the composable does not fall back to anonymous sign-in while `externalToken` is falsy. Authentication triggers automatically when the token value becomes available. |
 | `isActive`      | `MaybeRefOrGetter<boolean>`      | ❌       | Reactive signal that triggers authentication when it becomes `true`. Defaults to always active. |
 | `cookieName`    | `string`                         | ❌       | Cookie name for session persistence. Defaults to `eight-wave-ai`. Use different names to isolate multiple sessions on the same page. |
 
@@ -331,8 +354,10 @@ const { agent, themeClass, themeStyle } = useChatbotAgent({
 
 1. `useChatbotAuth` validates the external token server-side. If valid, the session is linked to the authenticated user.
 2. If the token is invalid or expired, the composable silently falls back to anonymous sign-in.
-3. On any subsequent 401 error, pass `onError` to `PkChatbot`'s `@error` event — it triggers automatic re-authentication.
-4. `token` is a reactive ref synced to a first-party cookie, so the session persists across page reloads.
+3. When `awaitExternalToken` is `true` and `externalToken` is not yet available, the composable waits — no anonymous session is created. Authentication triggers automatically when the token arrives.
+4. If `externalToken` is provided as a reactive getter or ref, authentication triggers automatically whenever the value changes.
+5. On any subsequent 401 error, pass `onError` to `PkChatbot`'s `@error` event — it triggers automatic re-authentication.
+6. `token` is a reactive ref synced to a first-party cookie, so the session persists across page reloads.
 
 #### `useChatbotAgent(options)`
 

package/dist/_chunks/{PkStreamingMarkdown-C0BpOvli.js → PkStreamingMarkdown-CCD_gifi.js}

@@ -1,5 +1,5 @@
 import { E as e, F as t, X as n, Z as r, _ as i, x as a, z as o } from "./vue.runtime.esm-bundler-ljsQ8m_k.js";
-import { g as s, h as c, n as l } from "./src-BRYn66N3.js";
+import { g as s, h as c, n as l } from "./src-B7wQQMx2.js";
 //#region ../../node_modules/.pnpm/remend@1.3.0/node_modules/remend/dist/index.js
 var u = Object.defineProperty, d = Object.defineProperties, f = Object.getOwnPropertyDescriptors, p = Object.getOwnPropertySymbols, m = Object.prototype.hasOwnProperty, ee = Object.prototype.propertyIsEnumerable, h = (e, t, n) => t in e ? u(e, t, {
 	enumerable: !0,
@@ -2126,4 +2126,4 @@ var xn = ["innerHTML"], Sn = /* @__PURE__ */ e({
 //#endregion
 export { Sn as t };
 
-//# sourceMappingURL=PkStreamingMarkdown-C0BpOvli.js.map
+//# sourceMappingURL=PkStreamingMarkdown-CCD_gifi.js.map