@kavchat/widget 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 maxsave
+
+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

@@ -1,3 +1,163 @@
-# Temporary Holding Version
+# Kavchat web widget
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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.
+
+## Install
+
+Paste this before `</body>`:
+
+```html
+<script src="https://cdn.kavchat.com/v1/kavchat.js" data-key="pk_live_..." async></script>
+```
+
+The public key (`pk_live_...`) is safe to put in a page. Never put the secret key (`sk_live_...`) in a page.
+
+### Attributes
+
+| Attribute | Default | Description |
+|---|---|---|
+| `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-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. |
+
+## JavaScript API
+
+The script installs `window.Kavchat`:
+
+```js
+Kavchat.init({
+  publicKey: 'pk_live_...',
+  apiBase: 'https://api.kavchat.com', // optional
+  locale: 'he',                       // optional
+  userToken: '<identity JWT>',        // optional
+  userName: 'Dana',                   // optional
+  open: false,                        // optional
+  onScreen(screen, targetId) {},      // optional: "screen" buttons in your scripts
+  screens: [                          // optional: shown as a dropdown in the dashboard editor
+    { id: 'orders', label: 'My orders' },
+    { id: 'product', label: 'Product page', needsTarget: true },
+  ],
+  onEvent(event) {},                  // optional: ready, unavailable, open, close, effect, ticket
+});
+Kavchat.open();
+Kavchat.close();
+Kavchat.toggle();
+Kavchat.setUser({ token: '<identity JWT>', name: 'Dana' }); // on login; setUser(null) on logout
+Kavchat.destroy();
+```
+
+`init` is not needed when the script tag has `data-key`. Calling `init` again replaces the running widget.
+
+### Calling the API before the script loads
+
+The script tag is `async`, so your code may run first. Create a queue, push calls into it, and the
+widget runs them in order when it loads (`init` always runs first; options from `init` are merged over
+the script tag attributes):
+
+```html
+<script>
+  window.Kavchat = window.Kavchat || { q: [] };
+  Kavchat.q.push(['init', { publicKey: 'pk_live_...', onScreen: function (s, id) { location.href = '/' + s + '/' + id; } }]);
+  Kavchat.q.push(['setUser', { token: '<identity JWT>', name: 'Dana' }]);
+</script>
+<script src="https://cdn.kavchat.com/v1/kavchat.js" async></script>
+```
+
+Each entry is `[methodName, ...args]`. After the script has loaded, `Kavchat.q.push(...)` still works
+and runs the call immediately, so the same code works in both cases.
+
+### Events
+
+`onEvent` receives one of:
+
+| `type` | Fields | When |
+|---|---|---|
+| `ready` | `version`, `offline` | The bot loaded (from the network, or from the saved copy when offline). |
+| `unavailable` | `reason?` (`'quota'`) | The bot is off, limited to testers, or over quota. Nothing is shown. |
+| `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. |
+
+### Script actions
+
+* **Contact**: opens the contact form inside the chat. The conversation transcript is attached to the request.
+* **Link**: opens `https:` and `tel:` links in a new tab (`rel="noopener noreferrer"`). Other schemes are ignored.
+* **Screen**: calls your `onScreen(screen, targetId)`. Without it the button does nothing on the web.
+
+### Screens
+
+Declare the screens (or pages) a script button may open with the `screens` option. The widget registers them with
+Kavchat only when the list changes, or once a week, and never blocks the page if that fails. The dashboard editor then
+offers them in a dropdown with their readable names, asks for an item id when `needsTarget` is true, and warns about
+buttons that point to a screen you did not declare. `id` must match `^[A-Za-z0-9_.-]{1,40}$`, `label` is up to 60
+characters, at most 100 screens.
+
+## Identifying your users
+
+To tag sessions and tickets with your own user id, or to show the bot only to testers, sign a JWT on
+your backend and pass it as `data-user-token` or `userToken`:
+
+* algorithm `HS256`, key = your secret key (the full `sk_live_...` string, as UTF-8 bytes)
+* claims: `sub` (your user id, required), `exp` (required, at most 30 days ahead),
+  optional `phone`, `name`, `email`
+
+The widget sends it as `Authorization: Bearer <token>` on every call. Signed-in users may open a
+request without leaving an email or phone. Full details are in the API reference
+(`server/openapi.yaml`, section "Identifying your users").
+
+## Content Security Policy
+
+If your site sends a CSP header, allow:
+
+```
+script-src https://cdn.kavchat.com;
+connect-src https://api.kavchat.com;
+```
+
+Add `img-src https:` (or your image hosts) if your scripts or avatar use images. The widget injects
+its styles into its own Shadow DOM `<style>` element; if your CSP restricts `style-src`, it needs
+`'unsafe-inline'` for that element.
+
+## How it behaves
+
+* **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.
+* **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.
+
+## AI answers (Premium)
+
+There is nothing to configure on your site. When AI answers are turned on in the dashboard (on your own
+AI provider key), a typed question that no script matches is sent to `POST /v1/client/{publicKey}/ai/answer`,
+and the chat shows a typing indicator while it waits (up to 20 seconds). The answer is shown as plain text
+(`textContent`, no links or HTML) with a small "AI answer" label in the UI language, followed by a button for
+the suggested script when there is one, and "Talk to our team". If there is no answer, or the request fails,
+times out or is rate limited, the chat shows the regular "no match" reply. Unanswered questions are reported
+to `/events` exactly as before, and AI answers are kept in the saved conversation.
+
+## npm
+
+```js
+import { createWidget } from '@kavchat/widget';
+
+const widget = createWidget({ publicKey: 'pk_live_...' });
+await widget.ready;
+widget.open();
+```
+
+## Development
+
+```bash
+yarn build      # dist/kavchat.js (IIFE for the CDN) and dist/index.mjs (ESM)
+yarn test       # vitest + jsdom
+yarn tsc --noEmit
+```
+
+Open `demo/index.html` in a browser after building. It mocks the API inside the page, in Hebrew and English.