@8wave/ai-elements 0.98.0 → 0.99.0-beta.2

package/README.md

@@ -122,7 +122,23 @@ 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 with the active external token; if that fails it emits `external-auth-expired` and applies the fallback above. Listen for that event to hand the widget a fresh JWT via `signIn(token)`.
 
-> **Note:** In external token mode (`external-token` set, or `await-external-token` present) the host application owns the authentication lifecycle: the widget hides its own sign-out button and the profile management link in the profile panel. The GDPR "delete my conversations" action stays available.
+> **Note:** In external token mode (`external-token` set, or `await-external-token` present) the host application owns the authentication lifecycle: the widget hides its own sign-out button, the profile management link in the profile panel, and the GDPR "delete my conversations" action. That action erases every conversation of the account platform-wide, well beyond the widget, so it belongs to the host application. Deleting a single conversation from the list stays available.
+
+### Host session (same-origin embeds)
+
+When the page already holds an Eight Wave session cookie for the backend origin, add the `use-host-session` attribute: the widget reuses that session instead of creating one of its own. No anonymous sign-in happens, requests travel with the cookie (`credentials: 'include'`) rather than a widget Bearer, and the chat history belongs to the logged-in account instead of a per-browser anonymous user.
+
+```html
+<floating-chat-widget
+  organization-slug="your-org-slug"
+  agent-id="your-agent-id"
+  use-host-session
+></floating-chat-widget>
+```
+
+This only works where that cookie is actually sent, so it is meant for applications authenticating against the same Eight Wave backend (the Agent Studio copilot is the reference case) and not for third-party embeds. On a site with no such session the widget stays signed out: use `external-token` instead.
+
+The attribute is reactive, so bind it to your login state and the widget re-reads the session when it flips. As with external token mode the host owns the auth lifecycle, so sign-out, profile management and the bulk GDPR erase are hidden, and `signOut()` is a no-op: revoking the session would log the user out of the host application too.
 
 ## Attributes
 
@@ -135,6 +151,7 @@ widget.setAttribute('external-token', jwt) // Single session created
 | `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. **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.            |
+| `use-host-session`         | `boolean`           | ❌        | `false`                                | Reuse the Eight Wave session cookie already present on the backend origin instead of creating a widget session. Same-origin embeds only, see Host session.  |
 | `floating-button-position` | `'left' \| 'right'` | ❌        | `'right'`                              | Position of the floating toggle button on the screen.                                                                                                       |
 | `system-theme`             | `'light' \| 'dark'` | ❌        | OS `prefers-color-scheme`              | Force the chat color scheme instead of following the OS preference. Reactive: update it when the host app's theme changes.                                  |
 | `custom-css`               | `string`            | ❌        | —                                      | Raw CSS string injected into the shadow root to override default styles.                                                                                    |
@@ -148,6 +165,7 @@ widget.setAttribute('external-token', jwt) // Single session created
 | `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. **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.            |
+| `use-host-session`     | `boolean`           | ❌        | `false`                                | Reuse the Eight Wave session cookie already present on the backend origin instead of creating a widget session. Same-origin embeds only, see Host session.  |
 | `forwarded-slots`      | `string`            | ❌        | —                                      | Comma-separated slot names to forward to `PkChatbot` (e.g. `"tool-showArtifact,subagent"`).                                                                 |
 | `system-theme`         | `'light' \| 'dark'` | ❌        | OS `prefers-color-scheme`              | Force the chat color scheme instead of following the OS preference. Reactive: update it when the host app's theme changes.                                  |
 | `custom-css`           | `string`            | ❌        | —                                      | Raw CSS string injected into the shadow root to override default styles.                                                                                    |
@@ -243,7 +261,7 @@ widget.setContext({
 
 ## How it works
 
-1. On mount the component automatically signs in as an anonymous user via the Eight Wave Auth service.
+1. On mount the component automatically signs in as an anonymous user via the Eight Wave Auth service, unless the host provides the identity (`external-token`) or lends its own session (`use-host-session`).
 2. Once authenticated it fetches the agent configuration (name, interface colors, etc.) from the public API.
 3. A circular floating button appears in the bottom-right corner, styled with the agent's `mainColor`.
 4. Clicking the button toggles the chat panel open/closed.
@@ -423,6 +441,7 @@ const { client, session, isAuthenticating, token, headers, onError, userId } = u
 | `basePath`      | `string`                         | ❌       | Auth base path appended to `baseUrl`. Defaults to `auth`.               |
 | `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. |
+| `useHostSession` | `MaybeRefOrGetter<boolean \| undefined>` | ❌       | When `true`, reuses the session cookie the host page already holds on the backend origin: no sign-in of any kind, requests carry the cookie instead of the widget Bearer, and the stored Bearer is never sent or overwritten. Reactive: the session is re-read when the value changes. Same-origin embeds only. |
 | `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. |
 | `onSignedIn`    | `(detail: { userId, isAnonymous }) => void` | ❌ | Called when a session is established or the user changes (any flow). |
@@ -436,13 +455,13 @@ const { client, session, isAuthenticating, token, headers, onError, userId } = u
 | `client`          | `AuthClient`            | The underlying Better Auth client instance. Exposes `signIn.anonymous()`, `signIn.externalToken({ token })`, and `useSession()`. |
 | `session`         | `Ref<Session>`          | Reactive session state from the auth client.                      |
 | `isAuthenticating`| `Ref<boolean>`          | `true` while a sign-in request is in flight.                      |
-| `isExternalAuth`  | `ComputedRef<boolean>`  | `true` in external token mode (`externalToken` set or `awaitExternalToken` enabled). The host application owns the auth lifecycle: the profile panel hides sign-out and profile management. |
+| `isExternalAuth`  | `ComputedRef<boolean>`  | `true` when the host application owns the session: external token mode (`externalToken` set or `awaitExternalToken` enabled) or `useHostSession`. The profile panel then hides sign-out, profile management and the bulk GDPR erase. |
 | `token`           | `WritableComputedRef<string>` | Reactive Bearer token, synced to the first-party cookie.    |
-| `headers`         | `ComputedRef<Record<string, string> \| undefined>` | Reactive `Authorization` header derived from `token`. Pass directly to `useChatbotAgent` or `PkChatbot`. |
+| `headers`         | `ComputedRef<Record<string, string> \| undefined>` | Reactive `Authorization` header derived from `token`. Pass directly to `useChatbotAgent` or `PkChatbot`. `undefined` in host-session mode, where the cookie carries the identity. |
 | `onError`         | `(error) => void`       | Pass to `PkChatbot`'s `@error` event to trigger automatic re-auth on 401. |
 | `userId`          | `ComputedRef<string \| undefined>` | Reactive user ID extracted from the session. Pass to `PkChatbot`'s `:user-id`. |
 | `signInWithExternalToken` | `(externalToken: string) => Promise<void>` | Authenticates with an external JWT (imperative equivalent of the `externalToken` option). |
-| `signOut`         | `() => Promise<void>`   | Signs out and withdraws the active external token, so no automatic re-login happens with it. |
+| `signOut`         | `() => Promise<void>`   | Signs out and withdraws the active external token, so no automatic re-login happens with it. No-op in host-session mode: revoking the session would sign the user out of the host application too. |
 
 #### End-to-end example (Vue + external JWT)