deskcord 0.11.0 → 1.0.0

package/README.md

@@ -1,3 +1,68 @@
 # Deskcord widget
 
-Minified build for production use
+The chat widget customers embed on their site. Preact + plain CSS in a shadow root, one IIFE file (`dist/deskcord.min.js`, ~51 KB gzipped) published to npm as `deskcord` and served from cdn.deskcord.chat.
+
+## Embed
+
+```html
+<script>
+  window.deskcord = {
+    settings: {
+      app_id: "YOUR_DISCORD_SERVER_ID",
+      // theme: "auto", // "light" (default), "dark", or "auto" (follows the visitor's system)
+    },
+  };
+</script>
+<script async src="https://cdn.deskcord.chat/deskcord.min.js"></script>
+```
+
+Colors, position, titles and the offline message come from the server's `/customize-widget` settings.
+
+`window.deskcord` also exposes `openChatbox()`, `closeChatbox()`, `identify(user)` and `logout()` once the script has loaded.
+
+## Identify logged-in users
+
+```js
+window.deskcord.identify({
+  name: "Ada",
+  email: "ada@example.com",
+  avatarUrl: "https://example.com/ada.png", // optional, https only, shown in Discord
+  userId: "42", // optional, with userHash: same conversations on every device
+  userHash: "…", // HMAC-SHA256(identity secret, userId), computed on the site's server
+});
+window.deskcord.logout(); // on logout: forgets the user on this browser
+```
+
+- Skips the "who should we reply to?" step. Without `userId`/`userHash`, conversations stay tied to the browser.
+- The secret comes from `/identity-verification enable` in Discord. It must never reach the browser.
+- To identify before the first render, pass the same object as `window.deskcord.settings.user` in the embed snippet.
+- Server-rendered sites should print `user: null` when nobody is logged in: it ends a verified session left over from a logout that didn't call `logout()`.
+- Call it on every page load: verified sessions last 24h, and one without a token is dropped.
+- Conversations started anonymously in the browser are carried over to the user. Calling `identify()` with another user (or `logout()`) wipes the previous user's conversations from the browser.
+
+## Develop
+
+```bash
+npm install
+npm run dev:mock   # mock Deskcord API on :3999 (no Discord needed)
+npm run dev        # then open http://localhost:5173/?api=mock (&theme=dark|auto)
+```
+
+Without `?api=mock`, the dev page talks to a local API on `http://localhost:10001`.
+
+The mock plays the Discord side through `POST localhost:3999/__mock/<action>`: `reply` (`{"text": "…"}`), `typing`, `image`, `edit`, `delete`, `handoff`, `close`, `reopen`, `offline`, `online`, `drop` (cuts the live connection), `auto-reply` (`{"on": false}`), `reset`.
+
+```bash
+npm test           # unit tests (sync model, persistence, rich text, colors)
+npm run build
+npm run e2e        # drives the built widget in headless Chrome against the mock (CHROME=/path/to/chrome)
+```
+
+## How it works
+
+- `src/state/session.ts` owns everything that talks to the server: boot, the socket, the outbox, uploads, identify/logout, read state, persistence. The UI only reads the store and calls its actions.
+- The server is the source of truth. A fetched conversation replaces the cached one; messages are matched by Discord id (`src/state/model.ts`), never by guessing from content.
+- Messages being sent live in an outbox, sent one at a time so they reach Discord in order, and survive a reload. Server data that may contain them waits until they're confirmed, so nothing shows twice.
+- After every reconnect (and when the tab comes back after a while) the current conversation is fetched again: events missed while offline aren't lost.
+- Unread state is a single date on the server's clock; the badge is derived from it.
+- Data lives in `localStorage` under `deskcord:<app_id>`. Visitors from widgets before 1.0 (cookie `discord-widget`) are migrated on their first visit.