@netwatchai/chat 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,16 @@
 # Netwatch Widget
 
-An AI-powered monitoring assistant widget built as a Web Component. Embed it anywhere to add intelligent monitoring capabilities.
+An AI-powered monitoring assistant shipped as a self-contained Web Component
+(Shadow DOM — styles are fully isolated from the host page). Drop in one script
+tag to add a chat bubble to any page.
+
+Published to npm as **`@netwatchai/chat`** and served over jsDelivr:
+
+```
+https://cdn.jsdelivr.net/npm/@netwatchai/chat@latest/lib/web.min.js
+```
+
+(Pin a version with `@0.1.0` instead of `@latest` for stability.)
 
 ## Features
 
@@ -12,51 +22,75 @@ An AI-powered monitoring assistant widget built as a Web Component. Embed it any
 - 🌙 Dark mode support
 - 📦 Distributable via CDN
 
-## Installation
-
-### From npm
+## Embedding
 
-```bash
-npm install agentic-netwatch-widget
-```
+Two equivalent ways — both load the single bundle from jsDelivr.
 
-### From CDN
+### 1. Declarative (custom element)
 
 ```html
-<netwatch-widget
-  api-endpoint="http://your-api.com"
-  client-id="your-client-id"
-  username="your-username"
-></netwatch-widget>
+<script type="module"
+  src="https://cdn.jsdelivr.net/npm/@netwatchai/chat@latest/lib/web.min.js"></script>
 
-<script src="https://cdn.jsdelivr.net/npm/agentic-netwatch-widget"></script>
+<netwatch-widget
+  client-id="b48ea317-…"
+  api-endpoint="http://your-api:8000">
+</netwatch-widget>
 ```
 
-## Usage
-
-### Basic Setup
+### 2. Programmatic (one-liner — PHP / CMS friendly)
 
 ```html
-<netwatch-widget
-  api-endpoint="http://localhost:8000"
-  client-id="demo-client"
-  username="demo-user"
-></netwatch-widget>
-
 <script type="module">
-  import NetwatchWidget from 'agentic-netwatch-widget'
+  import NetwatchChat from "https://cdn.jsdelivr.net/npm/@netwatchai/chat@latest/lib/web.min.js";
+  NetwatchChat.initBubble({
+    clientId: "b48ea317-…",
+    apiHost:  "http://your-api:8000",
+  });
 </script>
 ```
 
-### Attributes
+### Options
 
-- `api-endpoint` (required): Backend API endpoint URL
-- `client-id` (required): Client identifier for the monitoring instance
-- `username` (required): Username for authentication
+| Attribute      | `initBubble` key      | Required | Notes |
+|----------------|-----------------------|----------|-------|
+| `client-id`    | `clientId`            | yes      | Netwatch client UUID |
+| `api-endpoint` | `apiHost` / `apiEndpoint` | yes  | API base URL (a trailing `/api/chat` is stripped automatically) |
+| `username`     | `username`            | no       | **Auto-resolved** from the host page's localStorage when embedded in the Netwatch UI. Pass explicitly to override, or when embedding on other hosts. |
 
-## Development
+## Embedding in the Netwatch monitoring UI
+
+The widget auto-reads the logged-in user from the host page's localStorage, so
+it only needs its script injected on every (logged-in) page. The UI has no
+built-in custom-JS setting, so use one of:
 
-### Setup
+**Option A — reverse proxy injection (recommended, survives upgrades).** With
+nginx in front of the frontend:
+
+```nginx
+location / {
+    proxy_pass http://frontend-upstream;
+    proxy_set_header Accept-Encoding "";   # sub_filter needs uncompressed HTML
+    sub_filter_once on;
+    sub_filter_types text/html;
+    sub_filter '</body>'
+      '<script type="module">import N from "https://cdn.jsdelivr.net/npm/@netwatchai/chat@latest/lib/web.min.js";N.initBubble({clientId:"b48ea317-…",apiHost:"http://your-api:8000"});</script></body>';
+}
+```
+
+**Option B — edit the frontend's page layout template** (`ui/include/views/layout.htmlpage.php`),
+just before the `</body>` output. ⚠️ This is overwritten on every upgrade, so
+reapply it after upgrading:
+
+```php
+echo '<script type="module">import N from "https://cdn.jsdelivr.net/npm/@netwatchai/chat@latest/lib/web.min.js";N.initBubble({clientId:"b48ea317-…",apiHost:"http://your-api:8000"});</script>';
+```
+
+> ⚠️ **Mixed content:** if the UI is served over HTTPS but `api-endpoint` is
+> `http://…`, browsers silently block the API calls. Serve the API over HTTPS
+> too, or keep both on plain HTTP within a private network/tunnel.
+
+## Development
 
 ```bash
 pnpm install
@@ -81,7 +115,8 @@ Start the dev server:
 pnpm run dev
 ```
 
-Visit `http://localhost:5173` to see the test page with the widget. It reads the env vars via `src/config.js` and instantiates the widget automatically.
+Visit `http://localhost:5173` for the test page; it reads the env vars via
+`src/config.js` and mounts the widget automatically.
 
 ### Build
 
@@ -89,43 +124,49 @@ Visit `http://localhost:5173` to see the test page with the widget. It reads the
 pnpm run build
 ```
 
-This generates:
-- `dist/netwatch-widget.umd.js` - Universal Module Definition (for direct script tags)
-- `dist/netwatch-widget.es.js` - ES Module (for npm)
+Outputs to `lib/` (the `@latest/lib/web.min.js` jsDelivr path):
 
-### Testing
+- `lib/web.min.js` — ES module (modern `<script type="module">` / npm import)
+- `lib/web.umd.js` — UMD build (legacy `<script>` tag → `window.NetwatchChat`)
 
-The widget is automatically loaded in `index.html` during development. Customize the attributes to test different configurations.
+## Publishing
 
-## Architecture
+Published to npm as `@netwatchai/chat` by `.github/workflows/widget-publish.yml`
+(changesets-driven). Normal flow:
 
-The widget uses:
-- **Web Components** - Native browser API for encapsulation
-- **Shadow DOM** - Complete style isolation from parent page
-- **React** - Internal rendering framework
-- **Vercel AI SDK** - Streaming chat interface
-- **Tailwind CSS** - Utility-first styling
-- **Streamdown** - Markdown rendering
+1. Add a changeset describing your change:
 
-## Building for CDN
+   ```bash
+   pnpm changeset      # pick the bump, write a summary
+   ```
 
-The build outputs are ready for CDN distribution:
+   The summary becomes the public `CHANGELOG.md` — keep it in Netwatch terms.
+2. Commit the `.changeset/*.md` and push to `main`.
 
-```bash
-# Build the widget
-pnpm run build
+> **Org caveat:** this GitHub org currently disallows Actions creating pull
+> requests, so the changesets bot can't open the "Version Packages" PR. Until
+> that's enabled (or Trusted Publishing is set up), do the version bump locally
+> instead of relying on the bot:
+>
+> ```bash
+> pnpm run version-packages   # bumps package.json + CHANGELOG, consumes changesets
+> git commit -am "widget: version" && git push origin main
+> ```
+>
+> With no changesets left, the workflow's publish step runs `changeset publish`.
 
-# The UMD build can be used via script tag
-# The ES build can be installed via npm and imported
-```
+Requires repo secret **`NPM_TOKEN`** — a *granular* npm token with **"Bypass
+two-factor authentication (2FA)" checked** and read/write on the `@netwatchai`
+scope (a token without the 2FA bypass fails publish with `EOTP`).
 
-## Publishing to npm
+## Architecture
 
-```bash
-# Update version in package.json
-# Then:
-pnpm publish
-```
+- **Web Components** — native browser API for encapsulation
+- **Shadow DOM** — complete style isolation from the parent page
+- **React** — internal rendering framework
+- **Vercel AI SDK** — streaming chat interface
+- **Tailwind CSS** — utility-first styling
+- **Streamdown** — markdown rendering
 
 ## License