@clivly/chat-widget 0.17.0 → 0.17.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Clivly
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -8,7 +8,7 @@ transport; installing this package does not change how your server reports
 liveness.
 
 > **New here? Start with
-> [Adding the chat widget](../../docs/guides/adding-the-chat-widget.md)** — the
+> [Adding the chat widget](https://clivly.com/docs/guides/chat-widget)** — the
 > canonical end-to-end guide (widget record, session route, embed, operator
 > inbox). This README is the API-level reference for the package's entrypoints.
 
@@ -185,13 +185,17 @@ no identity at all.
 
 The session is created when the visitor opens the launcher, not on page load —
 otherwise every visitor who merely loaded a page would create an empty thread in
-your inbox.
+your inbox. For a visitor you have identified it starts on the launcher press
+(and on hover or keyboard focus when this browser holds a thread to resume;
+hover never starts a new thread), and the panel opens straight into the
+conversation shell rather than flashing the form.
 
 ### This is not authentication
 
 A seeded identity is self-reported: anyone can edit a prop in React devtools or
 a `data-` attribute in the element inspector. It removes the typing, nothing
-more.
+more. An unverified email never claims an existing contact: if the address
+already belongs to one, the chat stays unlinked from it.
 
 To make the identity trustworthy, pass `resolveUser` to
 `createChatSessionHandler` on your backend. It resolves the caller's real
@@ -200,7 +204,7 @@ contact verified:
 
 ```ts
 createChatSessionHandler({
-  apiKey: process.env.CLIVLY_API_KEY,
+  apiKey: process.env.CLIVLY_SECRET_KEY,
   resolveUser: async (request) => {
     const session = await auth.getSession(request);
     return session ? { id: session.user.id, email: session.user.email, name: session.user.name } : null;
@@ -214,7 +218,8 @@ Use both together for a signed-in user: `defaultVisitor` removes the form,
 ## 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
+device's safe-area insets. Below 30rem the open panel is a full-screen sheet and
+the launcher hides while it is open. 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
@@ -254,7 +259,7 @@ the panel is open.
 
 The widget ships light and dark palettes and follows the host app by default.
 For integration recipes (Tailwind, next-themes, a custom toggle) see
-[the guide's theming section](../../docs/guides/adding-the-chat-widget.md#5-theming).
+[the chat widget guide](https://clivly.com/docs/guides/chat-widget).
 
 ### `theme`
 
@@ -375,9 +380,10 @@ 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);
+- offers the topics as a compact strip docked above the message box (a
+  sideways-scrolling row on narrow or touch screens) while `support.state` is
+  `"automated"`, 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`.
 
@@ -386,6 +392,11 @@ 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.
 
+The widget remembers its own look — name, brand colour, greeting and topics — in
+browser storage per widget (never a message, name or email), so the launcher
+wears your brand colour from first paint; every session refreshes it, so a
+colour changed in the dashboard applies the next time the widget opens.
+
 ## Build outputs
 
 The package currently produces:
@@ -414,6 +425,11 @@ export const POST = createChatSessionHandler({
 `@clivly/sdk` exports the same handler if you depend on it directly. Don't import
 from `clivly` (the package root) — that entry is the CLI and is Node-only.
 
+The handler also forwards the visitor's IP address so Clivly can rate-limit new
+chats per visitor instead of per host server. It reads `cf-connecting-ip`,
+`x-real-ip` or the first `x-forwarded-for` entry; pass
+`resolveVisitorIp: (request) => string | null` if your proxy uses another header.
+
 Use the handler rather than hand-writing the proxy: it puts `origin` in the
 request body (the backend requires it there, and only falls back to the `Origin`
 header), accepts `visitorToken: null` for a first-time visitor, and turns an
@@ -435,6 +451,7 @@ unreachable Clivly into a JSON `502` instead of a thrown `fetch`.
 | A brand-new widget refuses everything | An empty origin list permits nothing | Add at least one origin |
 | `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` |
+| `429 rate_limited` on the session request | The visitor's IP, or your workspace as a whole, has started too many new chats recently | Wait and retry; resuming an existing thread is not counted |
 | `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` |
 | A returning visitor starts a fresh thread on another device | By design — conversations resume by opaque `visitorToken` in `localStorage`, never by the (unverified) email | Not a bug; resuming by email would leak a known customer's history |
@@ -443,10 +460,10 @@ unreachable Clivly into a JSON `502` instead of a thrown `fetch`.
 
 ## Related documentation
 
-- **[Adding the chat widget](../../docs/guides/adding-the-chat-widget.md)** — the canonical end-to-end guide
-- [Connecting to Clivly Cloud](../../docs/guides/connecting-to-clivly-cloud.md) — the overall integration guide
-- [`@clivly/sdk` README](../sdk/README.md) — `createChatSessionHandler` and the rest of the runtime
-- [`clivly` CLI README](../cli/README.md) — `clivly add widget`
+- **[Adding the chat widget](https://clivly.com/docs/guides/chat-widget)** — the canonical end-to-end guide
+- [Connecting to Clivly Cloud](https://clivly.com/docs/getting-started/quickstart) — the overall integration guide
+- [`@clivly/sdk` reference](https://clivly.com/docs/reference/packages) — `createChatSessionHandler` and the rest of the runtime
+- [`clivly` CLI reference](https://clivly.com/docs/reference/cli) — `clivly add widget`
 
 ## License