npm package: @openmic/openmic-chat-widget
Description: Embeddable chat widget for OpenMic AI assistants
Author: OpenMic
Latest version: 0.3.1

# OpenMic Chat Widget

Embeddable chat widget for OpenMic AI assistants. Drop one `<script>` tag into any website to add a floating chat button that connects to your OpenMic chat agent.

## Quick start

```html
<openmic-chat-widget
    bot-uid="your-bot-uid"
    public-api-key="omic_pub_xxx">
</openmic-chat-widget>

<script src="https://unpkg.com/openmic-chat-widget@latest/widget/widget-standalone.js"></script>
```

That's it. A floating chat button will appear in the bottom-right corner of the page.

## Attributes

| Attribute | Required | Default | Description |
|-----------|----------|---------|-------------|
| `bot-uid` | Yes (or `bot-id`) | — | The OpenMic bot UID to chat with |
| `bot-id` | Yes (or `bot-uid`) | — | Numeric bot ID (alternative to `bot-uid`) |
| `public-api-key` | Yes | — | Your OpenMic public API key (`omic_pub_...`) |
| `api-base` | No | `https://api.openmic.ai/v1` | API base URL (override for self-hosted or local dev) |
| `title` | No | `Chat with us` | Header title shown in the chat panel |
| `subtitle` | No | `We typically reply within minutes` | Header subtitle |
| `primary-color` | No | `#4f46e5` | Primary brand color (CSS color value) |

## Local development

To test the widget against a local backend:

```html
<openmic-chat-widget
    bot-uid="your-bot-uid"
    public-api-key="omic_pub_xxx"
    api-base="http://localhost:3005/v1">
</openmic-chat-widget>
<script src="./widget/widget-standalone.js"></script>
```

See `examples/test.html` for a complete working example.

## How it works

The widget calls these endpoints on your OpenMic backend:

- `POST /v1/create-chat` — creates a new chat session for the configured bot
- `POST /v1/create-chat-completion` — sends a user message and streams the AI response
- `POST /v1/end-chat/:sessionId` — ends the chat session

Authentication uses your **public API key** in the `Authorization: Bearer ...` header.

## Production features

This widget is built for real-world deployment on customer websites:

- **Shadow DOM isolation** — host site CSS cannot break the widget; widget styles cannot leak into the host page. Works on sites with strict CSS resets, Tailwind, Bootstrap, etc.
- **CSP-friendly** — all styles are scoped inside the shadow root, no inline `<style>` in the document head, compatible with strict Content Security Policies
- **AbortController-based fetch cancellation** — closing the chat panel aborts in-flight requests immediately. No ghost billing for messages the user never sees.
- **Exponential backoff retry** — transient network errors and 5xx responses are retried up to 3 times (250ms, 500ms, 1000ms). 4xx errors fail fast (no retry on auth/config errors).
- **Session persistence** — chat sessions survive page reloads via `localStorage`. Stale sessions auto-recover with a clear "session expired" message.
- **Lazy panel rendering** — the chat panel DOM is only built when the user clicks the launcher. Saves DOM nodes for users who never open chat.
- **Memory cleanup** — `MutationObserver` watches for `<openmic-chat-widget>` element removal and tears down listeners + aborts fetches when the widget is removed from DOM.
- **Browser compatibility check** — runtime check on load. If the browser is missing required features (`fetch`, `ReadableStream`, `MutationObserver`, `AbortController`, Shadow DOM), logs a clear error and disables the widget instead of silently failing.
- **Multi-instance safe** — multiple widgets on the same page work independently. Re-loading the script is a no-op.

## Browser support

Modern evergreen browsers — Chrome 89+, Firefox 85+, Safari 14+, Edge 89+.

Requires `fetch`, `ReadableStream`, `MutationObserver`, `AbortController`, and Shadow DOM v1.

## License

MIT