nivq-chat-widget 1.0.0 → 1.0.1

package/README.md

@@ -5,14 +5,15 @@ Embeddable NivQ chat experience as a framework-agnostic Web Component
 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).
+- **Secret-safe** — never touches your OAuth2 `clientSecret`; it uses a
+  short-lived token from your own token-broker endpoint (see below).
 - **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
 
+Via CDN (jsDelivr) — no build step:
+
 ```html
 <script type="module" src="https://cdn.jsdelivr.net/npm/nivq-chat-widget@1/dist/nivq-chat.js"></script>
 <nivq-chat
@@ -22,74 +23,79 @@ one tag and get the NivQ chat UI in a floating launcher (FAB) or inline panel.
 </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
+Or via npm (bundlers / React / Angular):
 
 ```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
+npm i nivq-chat-widget
 ```
-
-## 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
+```ts
+import 'nivq-chat-widget'; // registers <nivq-chat>; ships its own types
 ```
 
-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
+Pin the major (`@1`) for automatic patches without breaking changes.
+
+## Token broker (required)
+
+The widget authenticates with a **short-lived bearer token**, never your
+`clientSecret`. Stand up one small endpoint on your backend that exchanges your
+NivQ credentials for a token and returns only `{ access_token, expires_in }`:
+
+```js
+// POST /nivq-token  (your backend) — authenticate YOUR user first, then:
+const r = await fetch(`${process.env.NIVQ_API_BASE}/oauth2/token`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body: new URLSearchParams({
+        grant_type: 'client_credentials',
+        client_id: process.env.NIVQ_CLIENT_ID,
+        client_secret: process.env.NIVQ_CLIENT_SECRET, // stays server-side
+    }),
+});
+const { access_token, expires_in } = await r.json();
+res.json({ access_token, expires_in }); // never return the secret
 ```
 
-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
+The widget calls `POST {token-endpoint}`, caches the token, and refreshes it
+before expiry. Full Node/Spring examples, the CORS allow-list step, and the
+privacy notes are in `docs/integration.md` (shipped in the package).
+
+> **CORS:** the widget streams straight from the browser to `api-base-url`, so
+> add the origin(s) you embed on to the API key's **Allowed origins** when you
+> create it.
+
+## Configuration
+
+| Attribute | Required | Default | Description |
+|---|---|---|---|
+| `agent-id` | ✅ | — | The NivQ agent to chat with |
+| `token-endpoint` | ✅ | — | Your token broker URL |
+| `api-base-url` | ✅ | — | NivQ chat API base (e.g. `https://api.nivq.ai`) |
+| `mode` | | `fab` | `fab` (floating launcher) or `inline` |
+| `target` | | — | Inline only: CSS selector of the container to mount into |
+| `position` | | `bottom-right` | `bottom-right` or `bottom-left` (FAB) |
+| `theme` | | `auto` | `light`, `dark`, or `auto` (follows OS) |
+| `locale` | | `auto` | `tr`, `en`, or `auto` (browser language) |
+| `primary-color` | | NivQ red | Hex (`#6d28d9`) or HSL triplet (`265 70% 50%`) |
+| `accent-color` | | NivQ | Hex or HSL triplet |
+| `radius` | | `0.625rem` | Corner radius (any CSS length) |
+| `logo-url` | | NivQ mark | Replace the brand logo |
+| `brand-name` | | `NivQ` | Header title / logo alt text |
+| `launcher-label` | | — | Text next to the FAB icon |
+| `greeting` | | — | Custom empty-state heading |
+| `placeholder` | | localized | Input placeholder text |
+| `title` | | localized | Panel header title |
+| `external-user-id` | | — | Distinguishes your end-user |
+| `persist` | | `false` | Persist the conversation in `localStorage` |
+| `start-open` | | `false` | FAB only: open the panel on load |
+
+Programmatic config:
+
+```js
+document.querySelector('nivq-chat').configure({
+    primaryColor: '#6d28d9', brandName: 'Acme Assistant', mode: 'inline',
+});
 ```
 
-After publish the CDN URL is live immediately:
-
-```
-https://cdn.jsdelivr.net/npm/nivq-chat-widget@1/dist/nivq-chat.js
-```
+## License
 
-`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.
+UNLICENSED — © Nivorbit. See https://nivq.ai.

package/docs/integration.md

@@ -0,0 +1,248 @@
+# NivQ Chat Widget — Integration Guide
+
+> 📖 **This guide is also published in the NivQ docs:** https://nivq.ai/en/docs/chat-widget
+> (Turkish: https://nivq.ai/tr/docs/chat-widget). The docs version is the canonical,
+> reader-friendly copy; this file is the in-repo reference for maintainers.
+
+Embed the NivQ chat experience on any website or app with a single tag:
+
+```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>
+```
+
+The widget is a framework-agnostic Web Component — it works the same in plain
+HTML, React, Angular, Vue, or anything else. It renders inside a Shadow DOM, so
+its styles never leak into your page and your page's CSS never breaks it.
+
+---
+
+## 1. Security model — read this first
+
+What the "API Key" screen gives you is an **OAuth2 client credential pair**
+(`clientId` + `clientSecret`), used with the `client_credentials` grant:
+
+```
+clientId + clientSecret  ──►  POST /oauth2/token  ──►  short-lived access token (≈1h)
+access token (Bearer)    ──►  POST /v1/agents/{agentId}/conversations  (chat)
+```
+
+> **The `clientSecret` is a long-lived root credential. Never put it in the
+> browser, the widget, or any client-side code.** Anyone who extracts it can
+> mint tokens and run up your usage.
+
+The widget therefore **never** receives the secret. It only ever receives a
+short-lived access token, fetched from **your own backend endpoint** (the
+"token broker"). The secret stays on your server.
+
+```
+Browser (widget) ──POST──► your /nivq-token ──client_credentials──► NivQ /oauth2/token
+       ▲                          │
+       └──── { access_token } ◄────┘   (secret never returned to the browser)
+```
+
+---
+
+## 2. Build the token broker (≈20 lines)
+
+The broker is one endpoint on your own backend. It (a) authenticates *your*
+end-user with your own session, then (b) exchanges your NivQ secret for a token
+and returns just `{ access_token, expires_in }`.
+
+### Node / Express
+
+```js
+import express from 'express';
+
+const app = express();
+
+app.post('/nivq-token', async (req, res) => {
+    // 1. Authenticate YOUR user here (session/cookie/JWT). Reject if not logged in.
+    // if (!req.user) return res.sendStatus(401);
+
+    // 2. Exchange the secret for a short-lived token.
+    const r = await fetch(`${process.env.NIVQ_API_BASE}/oauth2/token`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+        body: new URLSearchParams({
+            grant_type: 'client_credentials',
+            client_id: process.env.NIVQ_CLIENT_ID,
+            client_secret: process.env.NIVQ_CLIENT_SECRET, // stays server-side
+        }),
+    });
+    if (!r.ok) return res.sendStatus(502);
+    const { access_token, expires_in } = await r.json();
+
+    // 3. Return ONLY the token. Never the secret.
+    res.json({ access_token, expires_in });
+});
+```
+
+### Spring Boot
+
+```java
+@RestController
+class NivqTokenBroker {
+
+    private final RestClient client = RestClient.create();
+
+    @Value("${nivq.api-base}")  String apiBase;
+    @Value("${nivq.client-id}") String clientId;
+    @Value("${nivq.client-secret}") String clientSecret; // stays server-side
+
+    @PostMapping("/nivq-token")
+    Map<String, Object> token(/* inject your authenticated principal here */) {
+        var form = new LinkedMultiValueMap<String, String>();
+        form.add("grant_type", "client_credentials");
+        form.add("client_id", clientId);
+        form.add("client_secret", clientSecret);
+
+        var resp = client.post()
+            .uri(apiBase + "/oauth2/token")
+            .contentType(MediaType.APPLICATION_FORM_URLENCODED)
+            .body(form)
+            .retrieve()
+            .body(Map.class);
+
+        // Return only the token + expiry — never the secret.
+        return Map.of("access_token", resp.get("access_token"),
+                      "expires_in",   resp.get("expires_in"));
+    }
+}
+```
+
+The widget calls `POST {token-endpoint}` and expects `{ access_token, expires_in }`
+(seconds). It caches the token and refreshes automatically before it expires.
+
+---
+
+## 3. Embed the widget
+
+### Plain HTML / any site
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/nivq-chat-widget@1/dist/nivq-chat.js"></script>
+<nivq-chat agent-id="…" api-base-url="https://api.nivq.ai" token-endpoint="/nivq-token"></nivq-chat>
+```
+
+### React
+
+Install from npm (recommended for bundled apps):
+
+```bash
+npm i nivq-chat-widget
+```
+
+```tsx
+import 'nivq-chat-widget'; // registers <nivq-chat>; ships its own types
+
+export function Support() {
+    return (
+        <nivq-chat
+            agent-id="…"
+            api-base-url="https://api.nivq.ai"
+            token-endpoint="/nivq-token"
+        />
+    );
+}
+```
+
+> The package ships type definitions, so `<nivq-chat>` is typed out of the box.
+> On React 19's strict JSX (no global `JSX` namespace), add a one-line module
+> augmentation if your editor flags the tag:
+> ```ts
+> declare module 'react' {
+>   namespace JSX { interface IntrinsicElements { 'nivq-chat': any } }
+> }
+> ```
+
+### Angular
+
+```ts
+// app.module.ts — allow custom elements
+import { CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
+@NgModule({ schemas: [CUSTOM_ELEMENTS_SCHEMA] })
+export class AppModule {}
+```
+```html
+<nivq-chat agent-id="…" api-base-url="https://api.nivq.ai" token-endpoint="/nivq-token"></nivq-chat>
+```
+
+---
+
+## 4. Configuration reference
+
+| Attribute | Required | Default | Description |
+|---|---|---|---|
+| `agent-id` | ✅ | — | The NivQ agent to chat with |
+| `token-endpoint` | ✅ | — | Your token broker URL |
+| `api-base-url` | ✅ | — | NivQ chat API base (e.g. `https://api.nivq.ai`) |
+| `mode` | | `fab` | `fab` (floating launcher) or `inline` |
+| `target` | | — | Inline only: CSS selector of the container to mount into |
+| `position` | | `bottom-right` | `bottom-right` or `bottom-left` (FAB) |
+| `theme` | | `auto` | `light`, `dark`, or `auto` (follows OS) |
+| `locale` | | `auto` | `tr`, `en`, or `auto` (browser language) |
+| `primary-color` | | NivQ red | Hex (`#6d28d9`) or HSL triplet (`265 70% 50%`) |
+| `accent-color` | | NivQ | Hex or HSL triplet |
+| `radius` | | `0.625rem` | Corner radius (any CSS length) |
+| `logo-url` | | NivQ mark | Replace the brand logo |
+| `brand-name` | | `NivQ` | Header title / logo alt text |
+| `launcher-label` | | — | Text next to the FAB icon |
+| `greeting` | | — | Custom empty-state heading |
+| `placeholder` | | localized | Input placeholder text |
+| `title` | | localized | Panel header title |
+| `external-user-id` | | — | Distinguishes your end-user (analytics/isolation) |
+| `persist` | | `false` | Persist the conversation in `localStorage` |
+| `start-open` | | `false` | FAB only: open the panel on load |
+
+### Programmatic API
+
+```js
+const el = document.querySelector('nivq-chat');
+el.configure({ primaryColor: '#6d28d9', brandName: 'Acme Assistant', mode: 'inline' });
+```
+
+### Theming
+
+Defaults are the NivQ brand (logo + red palette). Override the key tokens and
+the rest derive from them:
+
+```html
+<nivq-chat … primary-color="#6d28d9" accent-color="#f59e0b" radius="14px"
+            logo-url="https://acme.com/logo.svg" brand-name="Acme Assistant"></nivq-chat>
+```
+
+---
+
+## 5. Allow your embedding origin (CORS)
+
+The widget streams **directly** from the browser to your `api-base-url` (the
+token broker only mints tokens), so the NivQ API must allow your site's origin.
+
+**Set it on the API key.** When you create the API key (the screen that gives
+you the clientId + clientSecret), list every web origin the widget is embedded
+on under **Allowed origins** — e.g. `https://app.acme.com`. Origins are
+`scheme://host[:port]` with no path or wildcard, matching what the browser
+sends. Leaving it empty disables browser embedding for that key (server-to-server
+use only). Changes take effect within a minute.
+
+> **On-prem:** point `api-base-url` at your own NivQ deployment. The same
+> per-key Allowed origins apply. A deployment-wide alternative is the
+> `cors.allowed-origin-patterns` setting in your NivQ config, if you prefer to
+> manage embedding domains centrally rather than per key.
+
+Without an allowed origin, the browser blocks the stream with a CORS error.
+
+---
+
+## 6. Privacy note
+
+A single API client is shared across all end-users of your integration, and
+conversation history is scoped to the client — not to an individual end-user.
+The widget therefore keeps each session local (in-memory, or `localStorage`
+when `persist` is on) and does **not** load shared history. Use
+`external-user-id` to distinguish your end-users on the NivQ side.

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "nivq-chat-widget",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "type": "module",
   "description": "Embeddable NivQ chat web component (<nivq-chat>) for any website or framework.",
   "license": "UNLICENSED",
-  "homepage": "https://github.com/nivorbit/nivq-chat-widget#readme",
+  "homepage": "https://nivq.ai",
   "keywords": ["nivq", "chat", "widget", "web-component", "custom-element", "ai", "embed"],
   "module": "./dist/nivq-chat.js",
   "types": "./dist/nivq-chat.d.ts",
@@ -14,7 +14,7 @@
       "import": "./dist/nivq-chat.js"
     }
   },
-  "files": ["dist"],
+  "files": ["dist", "docs"],
   "sideEffects": ["./dist/**"],
   "publishConfig": {
     "access": "public"