@clivly/chat-widget 0.14.1 → 0.16.0

package/README.md

@@ -211,6 +211,45 @@ createChatSessionHandler({
 Use both together for a signed-in user: `defaultVisitor` removes the form,
 `resolveUser` is what makes it trustworthy.
 
+## Placement and launcher
+
+The widget floats in the bottom-right corner of the viewport, clear of the
+device's safe-area insets. Below 48rem the launcher is a 48px icon-only
+button, so it does not cover the host page's pagination or form controls; on
+wider screens it is a pill with an icon and your `launcherLabel`. The label is
+the button's accessible name either way, and `aria-expanded` reports whether
+the panel is open.
+
+| React prop | Script attribute | Values | Default |
+| --- | --- | --- | --- |
+| `placement` | `data-placement` | `"bottom-right"`, `"bottom-left"`, `"inline"` | `"bottom-right"` |
+| `launcher` | `data-launcher` | `"auto"`, `"pill"`, `"icon"` | `"auto"` |
+
+- `"inline"` renders the widget in normal flow, for a host that positions it
+  itself. This was the only behaviour before 0.16.
+- `"auto"` switches between the pill and the icon at 48rem; `"pill"` and
+  `"icon"` pin one shape at every width.
+- A floating widget stacks at `--clivly-chat-z-index` (default `2147483000`).
+  Lower it to sit beneath your own dialogs:
+
+```tsx
+<ChatWidget
+  style={{ "--clivly-chat-z-index": 40 } as React.CSSProperties}
+  /* … */
+/>
+```
+
+```html
+<script
+  src="https://api.clivly.com/widget.js"
+  data-widget-id="support"
+  data-session-url="/api/clivly/widget/session"
+  data-placement="bottom-left"
+  data-launcher="icon"
+  defer
+></script>
+```
+
 ## Theming
 
 The widget ships light and dark palettes and follows the host app by default.
@@ -289,6 +328,7 @@ Important fields include:
 - `contact`
 - `messages`
 - optional `socketUrl`
+- optional `support` (see [Support assistant](#support-assistant))
 
 When `socketUrl` is present, the widget prefers it over reconstructing the
 socket URL from a client-side template.
@@ -326,6 +366,26 @@ shows a short note that the team has been
 notified, and that the reply will also go to the visitor's email when one is
 known. A failed send doesn't start the clock, because nobody was notified about it.
 
+## Support assistant
+
+When the widget has guided support turned on in Clivly (**Settings → Chat
+widget → Support**), the session payload carries `support` — the mode, the
+conversation's state, and the topics to offer (ids and labels only; answers stay
+on the server). The widget then:
+
+- shows the server-written greeting, and every automated or AI message, with an
+  **Automated** / **AI assistant** badge (`message.automation` says which);
+- offers the topics as buttons under the transcript while `support.state` is
+  `"automated"`, alongside the message box, and hides them after a handoff or a
+  teammate's reply (`support.state` server event);
+- shows *The AI assistant is looking for an answer…* while an
+  `assistant.status` event says `thinking`.
+
+A topic click is sent as `{ type: "topic.select", id, topicId }`. A **custom
+transport** opts in with the optional `ChatTransportConnection.selectTopic()`;
+without it, a click is sent as the topic's label in an ordinary message. A
+payload without `support` renders exactly as before.
+
 ## Build outputs
 
 The package currently produces:
@@ -373,7 +433,7 @@ unreachable Clivly into a JSON `502` instead of a thrown `fetch`.
 | --- | --- | --- |
 | Widget mounts but every session is `403` | The origin is not in the widget record's allowlist. It is **exact-match**: `https://example.com` does not cover `https://www.example.com` | Add every embedding origin, with scheme, under **Settings → Chat widget** |
 | A brand-new widget refuses everything | An empty origin list permits nothing | Add at least one origin |
-| `503 widget_not_configured` | The Clivly server has no `CLIVLY_WIDGET_TOKEN_SECRET` | Only relevant when self-hosting — set it, or set `CLIVLY_MASTER_KEY` |
+| `503 widget_not_configured` | The Clivly server cannot sign widget sessions | A Clivly-side configuration problem, not something in your app — contact Clivly support |
 | Session request returns an opaque `400` | The route was hand-written and omits `origin` from the **body**, or rejects `visitorToken: null` | Use `createChatSessionHandler` from `clivly/sdk` |
 | `404` on the session request | `sessionUrl` does not match where you mounted the route | `clivly add widget` writes `/api/clivly/widget/session` — match it, or set `sessionUrl` to your path |
 | Bundle throws on `node:fs` / `node:child_process` | Something imported the `clivly` package root | Import the handler from `clivly/sdk` |