@kavchat/widget 0.0.1 → 0.0.3

package/README.md

@@ -2,7 +2,8 @@
 
 The embeddable chat that your visitors see on your website. It loads the bot you published in the
 Kavchat dashboard and runs the whole conversation in the browser with the shared `@kavchat/core` engine.
-No LLM, no third-party requests, about 19 KB gzip.
+No LLM, no third-party requests, about 22 KB gzip (live chat with a representative is a separate file, loaded only
+when it is turned on).
 
 ## Install
 
@@ -20,7 +21,7 @@ The public key (`pk_live_...`) is safe to put in a page. Never put the secret ke
 |---|---|---|
 | `data-key` | (required) | Your public key. |
 | `data-api` | `https://api.kavchat.com` | API base URL. |
-| `data-locale` | the browser language | Language of the widget chrome (buttons, form, notices): `he`, `en`, `ar`, `ru`, `es`, `fr`, `de`, `pt`, `it`, `tr`. If the language has no translation, the bot locale is used. The script content is always shown as you wrote it. `he` and `ar` render right to left. |
+| `data-locale` | the browser language | Language of the widget chrome (buttons, form, notices): `he`, `en`, `ar`, `ru`, `es`, `fr`, `de`, `pt`, `it`, `tr`, `th`. If the language has no translation, the bot locale is used. The script content is always shown as you wrote it. `he` and `ar` render right to left. |
 | `data-user-token` | none | Identity token for a signed-in user (see below). |
 | `data-user-name` | none | Shown in the greeting (`{name}`) and prefilled in the contact form. |
 | `data-open` | `false` | `"true"` opens the chat as soon as it loads. |
@@ -42,7 +43,7 @@ Kavchat.init({
     { id: 'orders', label: 'My orders' },
     { id: 'product', label: 'Product page', needsTarget: true },
   ],
-  onEvent(event) {},                  // optional: ready, unavailable, open, close, effect, ticket
+  onEvent(event) {},                  // optional: ready, unavailable, open, close, effect, ticket, live
 });
 Kavchat.open();
 Kavchat.close();
@@ -82,6 +83,7 @@ and runs the call immediately, so the same code works in both cases.
 | `open`, `close` | | The panel opened or closed. |
 | `effect` | `effect` | A button asked for the contact form, a link or a screen. |
 | `ticket` | `id`, `number` | A contact request was created. |
+| `live` | `state`, `id` | The live chat with a representative changed state: `queued`, `active`, `closed` or `ticket`. |
 
 ### Script actions
 
@@ -128,10 +130,43 @@ its styles into its own Shadow DOM `<style>` element; if your CSP restricts `sty
 * **Isolation**: everything renders inside a Shadow DOM. Your CSS does not reach the widget and the widget's CSS does not reach your page.
 * **Caching**: the published bot is saved in `localStorage` per public key with its ETag. Each load sends `If-None-Match`; when nothing changed the server answers 304. When the network is down the saved copy is used and a notice is shown.
 * **Sessions**: a random session id is kept in `sessionStorage`, so moving between pages keeps the same conversation.
+* **Live chat**: an open chat with a representative is kept in `localStorage` (see above) and restored on the next page.
 * **Analytics**: the conversation path is reported about 2 seconds after each action, and on page hide with `fetch(..., { keepalive: true })`.
 * **Free plan**: the "Powered by Kavchat" badge is shown unless your plan removes branding.
 * **Accessibility**: the panel is a labelled dialog, focus moves into it and back, Esc closes it, buttons are real buttons, new bot messages are announced, and motion is reduced when the visitor asks for it.
 
+## Live chat with a representative
+
+There is nothing to configure on your site. When live chat is turned on in the dashboard (the release has
+`liveChat.enabled`), the widget loads a second file, `kavchat-live.js`, from the same CDN folder and the same
+version as `kavchat.js` (`kavchat.<rev>.js` loads `kavchat-live.<rev>.js`). Sites without live chat never download it.
+The protocol is in `docs/live-chat-protocol.md`; the state, ordering and texts come from `@kavchat/core`.
+
+* **The option**: next to "Talk to our team" the bot shows "Talk to a representative", only after
+  `GET /live/availability` says a representative is available (checked again after 30 seconds). When the team is
+  outside business hours or everyone is busy, only the contact form is offered, with a short line saying why (and
+  when the team is back, when known). When the monthly quota is used up, the form is shown without an explanation.
+* **The request**: guests leave an email or a phone (in case nobody answers in time), a name and an optional
+  first message, and choose a department when more than one is open. Signed-in users (`userToken`) skip the
+  contact fields; the token goes in the request body. If nobody can take the chat, the contact form opens with
+  what the visitor already typed.
+* **Waiting**: "Waiting for a representative" with a countdown to the server's wait limit, "Leave a message
+  instead", and "End chat". Messages can be sent while waiting. When the time is up the chat becomes a request
+  automatically, and the visitor sees that nobody was free in time and the request number.
+* **The chat**: the agent's name, messages, typing indicator, transfers to another agent ("X joined the chat"),
+  end chat. Everything from the server is rendered as plain text (`textContent`), never as HTML or links.
+  New agent messages and system lines are announced to screen readers; the launcher shows a dot for messages that
+  arrive while the panel is closed.
+* **Real time**: Server-Sent Events with a single-use stream ticket, then automatic reconnects with backoff
+  (1, 2, 4, 8, 16, 30 seconds, plus or minus 30%) and a sync of everything after the last sequence number, so
+  nothing is lost or shown twice. When `EventSource` is missing or the stream is blocked (three failures in a row),
+  it falls back to long-poll. Each message has a client id, so retries never create duplicates; a message shows
+  as sending, and a failed one can be retried with a tap.
+* **No preflight**: live calls send no custom headers at all; POST bodies are JSON strings (sent as `text/plain`).
+* **Reload**: the chat credential is kept in `localStorage` per public key and conversation (never in a URL), for
+  up to 12 hours or until the chat ends, so a reload or a new page restores the whole chat: the bot part, then the
+  conversation with the representative.
+
 ## AI answers (Premium)
 
 There is nothing to configure on your site. When AI answers are turned on in the dashboard (on your own
@@ -155,7 +190,7 @@ widget.open();
 ## Development
 
 ```bash
-yarn build      # dist/kavchat.js (IIFE for the CDN) and dist/index.mjs (ESM)
+yarn build      # dist/kavchat.js and dist/kavchat-live.js (IIFE for the CDN), dist/index.mjs (ESM)
 yarn test       # vitest + jsdom
 yarn tsc --noEmit
 ```