nivq-chat-widget 1.0.0

package/README.md

@@ -0,0 +1,95 @@
+# nivq-chat-widget
+
+Embeddable NivQ chat experience as a framework-agnostic Web Component
+(`<nivq-chat>`). Drop it into any site — plain HTML, React, Angular, Vue — with
+one tag and get the NivQ chat UI in a floating launcher (FAB) or inline panel.
+
+- **Style-isolated** — renders in a Shadow DOM; no CSS bleed in either direction.
+- **Secret-safe** — never touches your OAuth2 `clientSecret`. It fetches a
+  short-lived token from your own token-broker endpoint. See
+  [`docs/integration.md`](docs/integration.md).
+- **Themeable** — defaults to the NivQ brand; override palette, logo, radius.
+- **Lazy charts** — the Vega rendering stack loads only when a turn returns a chart.
+
+## Quick start
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/nivq-chat-widget@1/dist/nivq-chat.js"></script>
+<nivq-chat
+    agent-id="YOUR_AGENT_ID"
+    api-base-url="https://api.nivq.ai"
+    token-endpoint="/nivq-token">
+</nivq-chat>
+```
+
+You must run a small **token broker** on your backend (≈20 lines) so the secret
+never reaches the browser. Full guide + Node/Spring examples:
+[`docs/integration.md`](docs/integration.md).
+
+## Develop
+
+```bash
+bun install
+
+# 1. Run the mock token broker against a NivQ backend + a dev API client:
+NIVQ_API_BASE=http://localhost:8080 \
+NIVQ_CLIENT_ID=nivq_… NIVQ_CLIENT_SECRET=… \
+bun run broker
+
+# 2. Run the dev harness, then fill in agent id + endpoints and click Mount:
+bun run dev
+
+bun run build        # → dist/nivq-chat.js (+ lazy chart chunk)
+bun run type-check
+```
+
+## Architecture
+
+```
+<nivq-chat> (custom element, src/element.ts)
+  └─ Shadow DOM + injected Tailwind stylesheet (tokens scoped to :host)
+       └─ React root (src/Widget.tsx) — FAB or inline
+            ├─ TokenProvider  (src/auth) — fetches/caches the broker token
+            ├─ useWidgetChat  (src/chat) — SSE streaming, ephemeral/local state
+            └─ chat UI        (src/chat) — forked from nivq-web-client
+```
+
+Presentational chat components are forked from `nivq-web-client`; a shared
+`nivq-chat-ui` package is a possible future consolidation.
+
+## Publish (maintainers)
+
+Published to npm; the CDN URL is served straight from npm by jsDelivr — one
+publish covers both `npm i` and `<script>` consumers.
+
+### CI release (recommended)
+
+`.github/workflows/release.yml` publishes automatically when a `v*` tag is
+pushed. The flow:
+
+```bash
+npm version <patch|minor|major>   # bumps package.json + creates tag vX.Y.Z
+git push --follow-tags            # CI builds (via prepublishOnly) and publishes
+```
+
+One-time setup: add repo secret **`NPM_TOKEN`** (npm automation token with
+publish rights for the `nivq-chat-widget` package) under Settings → Secrets and variables →
+Actions. `.github/workflows/ci.yml` runs type-check + build on every push/PR.
+
+### Manual publish (fallback)
+
+```bash
+npm login                         # your npm account with publish rights
+npm publish                       # prepublishOnly runs the build automatically
+```
+
+After publish the CDN URL is live immediately:
+
+```
+https://cdn.jsdelivr.net/npm/nivq-chat-widget@1/dist/nivq-chat.js
+```
+
+`files: ["dist"]` ships only the build output (entry + chunks + `nivq-chat.d.ts`).
+Tell customers to pin the major (`@1`) — they get patches/minors, never breaking
+changes. Every release bumps `version` (immutable, long-cached URLs); the entry
+imports its chunks by relative path, so all `dist/*` files publish together.