npm package: @mana-agents/ai-widget-embed
Description: Standalone embeddable chat widget (Bubble/Box style) that customers add to their site with a single custom element and script tag. Uses a 1st-party cookie for visitor identity and talks to the public embed chat API.
Latest version: 0.1.3

# Mana Agent Embed Widget

Standalone embeddable chat widget (Bubble/Box style) that customers add to their site with a single custom element and script tag. Uses a 1st-party cookie for visitor identity and talks to the public embed chat API.

## Embed on your site

Add this to your HTML (replace the agent ID and script URL with your values):

```html
<myagent-webcomponent agent-id="<replace-with-your-agent-id>"></myagent-webcomponent>
<script
  src="https://unpkg.com/@builtbundle/ai-widget-embed"
  async
  type="text/javascript"
></script>
```

The bundle injects its own styles inside Shadow DOM, so no extra CSS file is required.

### Attributes

- **`agent-id`** (required): Your agent ID from the dashboard.
- **`api-base-url`** (optional): Backend base URL (e.g. `https://api.yourdomain.com`). If omitted, the script uses the build-time env `VITE_EMBED_API_URL`.

By default, the widget calls `${base}/api/chat/embed/...` (it auto-appends `/api` if missing).

## Build-time API URL (hidden from embed HTML)

Set `VITE_EMBED_API_URL` when building so host pages do not need to expose API URL in the element attribute:

```bash
VITE_EMBED_API_URL=https://api.yourdomain.com pnpm build:embed
```

You can still override per embed instance with `api-base-url` if needed.

### Cookie (1st-party)

The widget uses [js-cookie](https://www.npmjs.com/package/js-cookie) to set a 1st-party cookie `mana_visitor_id` on the customer’s domain. This ID is sent as the `X-Mana-Visitor-Id` header to your server so conversations are tied to the same visitor.

## Public embed API (server)

The server must expose these **public** (no auth) endpoints, rate-limited and identified by `X-Mana-Visitor-Id`:

- **GET** `/chat/embed/conversation?agentId=...` — get latest open conversation for this visitor.
- **POST** `/chat/embed/conversation?agentId=...` — create a new conversation (and optional welcome message).
- **POST** `/chat/embed/conversation/:conversationId/messages` — send a message (body: `{ "content": "..." }`).
- **POST** `/chat/embed/conversation/:conversationId/stop` — archive (stop) the conversation.

Optional:

- **GET** `/chat/embed/agent/:agentId` — public agent config (name, image, spotlightMessages) for the widget.

All embed routes use `publicRateLimitMiddleware` and require the `X-Mana-Visitor-Id` header (the widget sends it from the cookie).

## Local development

```bash
pnpm install
pnpm dev          # App with widget demo (main.tsx + App)
pnpm build:embed  # Build dist/ai-widget-embed.js
```

- **Dev**: Open the app and use the demo; set `VITE_EMBED_API_URL` to your API (e.g. `http://localhost:4000`).
- **Build**: After `pnpm build:embed`, serve `dist/` and open an HTML page that includes the script and `<myagent-webcomponent agent-id="…" api-base-url="http://localhost:4000" />`.

## Publish to unpkg (npm)

1. Authenticate npm:

```bash
npm login
```

2. Build and inspect package contents:

```bash
pnpm build:embed
npm pack --dry-run
```

3. Publish publicly (scoped package):

```bash
npm publish --access public
```

4. Use a pinned unpkg URL in production:

```html
<script src="https://unpkg.com/@builtbundle/ai-widget-embed@0.1.0"></script>
```

Notes:
- `package.json` already sets `unpkg` to `dist/ai-widget-embed.js`.
- `prepublishOnly` automatically runs `pnpm build:embed` before publish.
- Bump `version` for every release before publishing.

## Tech

- **Widget**: Vite + React 19, Motion, TanStack Query, Axios, js-cookie, Tailwind, use-stick-to-bottom.
- **Output**: IIFE bundle (`ai-widget-embed.js`) for unpkg or self-host.
- **Isolation**: Web component runs in **open Shadow DOM**; host wrapper is fixed full-screen with `pointer-events: none`; only bubble/panel controls are `pointer-events: auto` so the embed does not block the site.