@clivly/chat-widget 0.3.0-next.6

package/README.md

@@ -0,0 +1,123 @@
+# `@clivly/chat-widget`
+
+Embeddable chat widget package for Clivly conversations.
+
+This package currently exposes four stable entrypoints with different intended
+use cases.
+
+## Entrypoints
+
+### `@clivly/chat-widget`
+
+Use the package root for app-side integration code.
+
+It exports:
+
+- React widget components
+- `createSessionFetcher()`
+- `createClivlyTransport()`
+- side-effect-free mount helpers
+
+Example:
+
+```ts
+import {
+	createSessionFetcher,
+	createClivlyTransport,
+	mountChatWidget,
+} from "@clivly/chat-widget";
+
+const getSession = createSessionFetcher({
+	sessionUrl: "/api/clivly/chat/session",
+});
+```
+
+### `@clivly/chat-widget/browser`
+
+Use this entry for the browser auto-mount module build.
+
+This entry:
+
+- exports `mountChatWidget()`
+- exports `mountChatWidgetScript()`
+- exports `autoMountChatWidgetScript()`
+- auto-mounts at module evaluation time when `document` exists
+
+This is the module-side equivalent of the script-tag embed behavior.
+
+### `@clivly/chat-widget/mount`
+
+Use this entry when you want the mount helpers without the browser entry's
+auto-mount side effect.
+
+This is the safest browser/helper entry for host-controlled mounting.
+
+It exports:
+
+- `mountChatWidget()`
+- `mountChatWidgetScript()`
+- `autoMountChatWidgetScript()`
+- `MountChatWidgetOptions`
+- `ScriptMountResult`
+
+### `@clivly/chat-widget/script`
+
+This entry maps to the generated global/browser artifact:
+
+- `dist/widget.global.js`
+
+Use it for script-tag delivery, CDN-style consumption, or any future server path
+that serves the bundled widget directly.
+
+## Session bootstrap shape
+
+The widget expects a session bootstrap endpoint that returns a
+`WidgetSessionPayload`.
+
+Important fields include:
+
+- `token`
+- `visitorToken`
+- `conversation`
+- `contact`
+- `messages`
+- optional `socketUrl`
+
+When `socketUrl` is present, the widget prefers it over reconstructing the
+socket URL from a client-side template.
+
+## Transport behavior
+
+The package includes:
+
+- `createClivlyTransport()` for real Clivly backends
+- `createWebSocketTransport()` for explicit socket wiring
+- `createLoopbackTransport()` for local UI/testing flows
+
+The default browser mount behavior is:
+
+1. use a caller-provided `createTransport` when present
+2. otherwise prefer `session.socketUrl`
+3. otherwise fall back to `socketUrlTemplate` when provided
+
+## Build outputs
+
+The package currently produces:
+
+- `dist/index.*`
+- `dist/browser.*`
+- `dist/browser-mount.*`
+- `dist/widget.global.js`
+
+The `browser` and `browser-mount` outputs are built as standalone entrypoints.
+
+## Host-side pairing
+
+The intended host-side SDK helper lives in `@clivly/sdk`:
+
+```ts
+import { createChatSessionHandler } from "@clivly/sdk";
+```
+
+That handler is the expected bridge between a host backend holding
+`CLIVLY_API_KEY` and the widget's `sessionUrl`.