Netwatch Widget

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

• 💬 Real-time streaming chat interface
• 📱 Fully responsive and embeddable
• 🎨 Tailwind CSS styling with complete style isolation
• 🔄 Web Component with Shadow DOM
• ↔️ Resizable and expandable interface
• 🌙 Dark mode support
• 📦 Distributable via CDN

Embedding

Two equivalent ways — both load the single bundle from jsDelivr.

1. Declarative (custom element)

<script type="module"
  src="https://cdn.jsdelivr.net/npm/@netwatchai/chat@latest/lib/web.min.js"></script>

<netwatch-widget
  client-id="b48ea317-…"
  api-endpoint="http://your-api:8000">
</netwatch-widget>

2. Programmatic (one-liner — PHP / CMS friendly)

<script type="module">
  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>

Options

| 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. |

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:

Option A — reverse proxy injection (recommended, survives upgrades). With nginx in front of the frontend:

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:

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

pnpm install

# Copy the env template and fill it in.
cp .env.example .env

Edit .env:

VITE_API_ENDPOINT=http://localhost:8000
VITE_DEV_CLIENT_ID=your-client-uuid
VITE_DEV_USERNAME=your-netwatch-username

Both .env and .env.local are gitignored; only .env.example is committed.

Start the dev server:

pnpm run dev

Visit http://localhost:5173 for the test page; it reads the env vars via src/config.js and mounts the widget automatically.

Build

pnpm run build

Outputs to lib/ (the @latest/lib/web.min.js jsDelivr path):

• lib/web.min.js — ES module (modern <script type="module"> / npm import)
• lib/web.umd.js — UMD build (legacy <script> tag → window.NetwatchChat)

Publishing

Published to npm as @netwatchai/chat by .github/workflows/widget-publish.yml (changesets-driven). Normal flow:

1. Add a changeset describing your change:

   pnpm changeset      # pick the bump, write a summary

   The summary becomes the public CHANGELOG.md — keep it in Netwatch terms.

2. Commit the .changeset/*.md and push to main.

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:

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.

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).

Architecture

• 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

MIT