@_solaris/messenger-widget 0.4.14 → 0.5.0

package/README.md

@@ -17,8 +17,13 @@ npm i @_solaris/messenger-widget vue
 import { Messenger } from '@_solaris/messenger-widget';
 import '@_solaris/messenger-widget/style.css';
 
-// In a Vue 3 app:
-//   <Messenger :base-url="..." :widget-id="..." :user-id="..." :user-hash="..." display-mode="floating" />
+// Linked mode (merchant identifies the user):
+//   <Messenger :base-url="..." :widget-id="..." :token="merchantJwt" display-mode="floating" />
+//
+// Visitor mode (anonymous): omit `:token` — the widget calls POST /client/session
+// on boot and persists a brispr-issued JWT in localStorage. Requires the widget's
+// `security.allow_unauthenticated=true` server-side.
+//   <Messenger :base-url="..." :widget-id="..." display-mode="floating" />
 //
 // UI language: pass `language` ('fr' | 'en'). When omitted, it falls back to
 // the authenticated customer's `language`, then the widget config's
@@ -32,15 +37,42 @@ import '@_solaris/messenger-widget/style.css';
 //   :context="{ customer: { name: 'Jane', email: 'jane@acme.io', plan: 'pro', seats: 12 } }"
 ```
 
+### Auth model
+
+The widget sends `Authorization: Bearer <jwt>` on every call. The JWT comes
+from one of two sources, depending on whether `token` is passed:
+
+- **linked** (merchant backend signs): sign a JWT HS256 with the widget secret,
+  claims `{ sub: <external_id>, wid: <widget_id>, kind: "linked", exp }`.
+  Pass the resulting JWT as `token`. Renew before `exp` (typical TTL 1h–24h
+  per merchant policy).
+- **visitor** (omit `token`): the widget calls `POST /client/session` once, the
+  server creates a `customers` row (`identity_type='visitor'`) and returns a
+  30-day JWT. The widget persists it in `localStorage[brispr_token_<wid>]`
+  for cross-reload continuity. Server-side opt-in via
+  `widgets.security.allow_unauthenticated`.
+
 It also exports the individual presentational components, the design tokens and
 helpers — used by the WeWeb "conversation admin" plugin which supplies its own
-WeWeb-managed data instead of the built-in HMAC/SSE transport:
+WeWeb-managed data instead of the built-in JWT/SSE transport:
 
 ```js
 import {
-  MessageList, Bubble, Composer, ApprovalCard, FormCard,
-  ArtifactRenderer, AIAvatar, HumanAvatar, TeamAvatars, AttachmentPreview,
-  tokens, renderMarkdown, uuid, createStore, createTransport,
+    MessageList,
+    Bubble,
+    Composer,
+    ApprovalCard,
+    FormCard,
+    ArtifactRenderer,
+    AIAvatar,
+    HumanAvatar,
+    TeamAvatars,
+    AttachmentPreview,
+    tokens,
+    renderMarkdown,
+    uuid,
+    createStore,
+    createTransport,
 } from '@_solaris/messenger-widget';
 ```
 
@@ -49,34 +81,37 @@ import {
 ```html
 <script src="https://your-cdn/messenger.embed.js"></script>
 <script>
-  Messenger.init({
-    baseUrl:  'https://messenger.your-saas.com',
-    widgetId: '…',
-    userId:   '…',
-    userHash: '…',          // HMAC-SHA256(secret, userId), computed server-side
-    displayMode: 'floating',// 'floating' | 'sheet' | 'embedded'
-    language: 'en',         // optional — 'fr' | 'en'; else customer.language / widget.default_language
-    // Optional agent context. `context.customer` is a flat object pushed
-    // once to PATCH /customers/me on boot so the agent has it as context.
-    // `name`/`email` map to the customer's columns; any other key is a
-    // named variable value (server keeps variables you don't pass):
-    context: {
-      customer: {
-        name:  'Jane Doe',
-        email: 'jane@acme.io',
-        plan:  'pro',
-        seats: 12,
-      },
-    },
-  });
-  // Messenger.destroy() to tear it down.
+    Messenger.init({
+        baseUrl: 'https://messenger.your-saas.com',
+        widgetId: '…',
+        token: '…', // optional — JWT HS256 signed by your backend with
+        // the widget secret. Omit to run in visitor mode
+        // (anonymous, brispr-issued token persisted in
+        // localStorage, server-side opt-in required).
+        displayMode: 'floating', // 'floating' | 'sheet' | 'embedded'
+        language: 'en', // optional — 'fr' | 'en'; else customer.language / widget.default_language
+        // Optional agent context. `context.customer` is a flat object pushed
+        // once to PATCH /customers/me on boot so the agent has it as context.
+        // `name`/`email` map to the customer's columns; any other key is a
+        // named variable value (server keeps variables you don't pass):
+        context: {
+            customer: {
+                name: 'Jane Doe',
+                email: 'jane@acme.io',
+                plan: 'pro',
+                seats: 12,
+            },
+        },
+    });
+    // Messenger.destroy() to tear it down.
 </script>
 ```
 
-`init()` is idempotent and credential-aware (no-op until creds are complete,
-no-op if re-called with identical options) — see
+`init()` is idempotent (no-op if re-called with identical options) and requires
+only `baseUrl` + `widgetId` to attempt a boot — without `token`, the widget
+falls back to visitor mode automatically. See
 [examples/weweb-embed.md](examples/weweb-embed.md) for the WeWeb integration
-(reactive HMAC via WeWeb variables + workflow).
+(reactive JWT via WeWeb variables + workflow).
 
 ## Build
 
@@ -85,11 +120,11 @@ npm install
 npm run build        # build:lib + build:embed + build:types → dist/
 ```
 
-| Output                     | Target | Vue        |
-| -------------------------- | ------ | ---------- |
-| `dist/messenger.js` / `.cjs` + `dist/style.css` | lib   | external (peer) |
-| `dist/messenger.embed.js`  | embed  | bundled in |
-| `dist/types/`              | types  | from JSDoc |
+| Output                                          | Target | Vue             |
+| ----------------------------------------------- | ------ | --------------- |
+| `dist/messenger.js` / `.cjs` + `dist/style.css` | lib    | external (peer) |
+| `dist/messenger.embed.js`                       | embed  | bundled in      |
+| `dist/types/`                                   | types  | from JSDoc      |
 
 ## License