npm package: @mitverse/mitbar-web
Description: Browser bar that communicates with script-writer Docker agent (page context, Build, Deploy)
Latest version: 1.1.4

# @mitverse/mitbar-web

**mitbar-web** is a browser bar you add to any website. When enabled, it stays visible and talks to the **agent** WebSocket at **agent.mitverse.com** (or a URL you set). Every message includes the **page URL and title**. The bar provides **Build**, **Deploy**, and **Send** (chat) actions.

## Requirements

- A WebSocket endpoint for the bar (e.g. **agent.mitverse.com** at `/api/v1/agent/ws`). Default URL: `wss://agent.mitverse.com/api/v1/agent/ws`.
- Optionally, the backend can require a JWT for the WebSocket when `MITBAR_WS_REQUIRE_AUTH` is set.

---

## Installation

### From npm

```bash
npm install @mitverse/mitbar-web
```

### From this repo (local / monorepo)

```bash
cd mitbar-web
npm install
npm run build
```

Then in your app (e.g. devops or agent):

```json
{
  "dependencies": {
    "@mitverse/mitbar-web": "file:../mitbar-web"
  }
}
```

---

## Usage

You can use the bar in two ways: **script tag** (standalone) or **ESM** (bundled app, e.g. Vite/React).

### Option 1: Script tag (standalone)

Load the UMD bundle and enable the bar with **data attributes** on the script tag. The bar auto-initializes when the script loads.

```html
<script
  src="https://your-cdn.com/path/to/mitbar.umd.cjs"
  data-mitbar-enabled="true"
  data-mitbar-gateway-ws-url="wss://agent.mitverse.com/api/v1/agent/ws"
></script>
```

Or set a global config **before** the script:

```html
<script>
  window.__MITBAR_CONFIG__ = {
    enabled: true,
    gatewayWsUrl: 'wss://agent.mitverse.com/api/v1/agent/ws',
    token: 'YOUR_JWT'   // optional; use when backend sets MITBAR_WS_REQUIRE_AUTH
  };
</script>
<script src="https://your-cdn.com/path/to/mitbar.umd.cjs"></script>
```

- **Script-tag auto-init** only runs when the script element has `data-mitbar-enabled="true"` (or `"1"`). That way, when the package is **bundled** and imported by your app, it does **not** auto-init; your app calls `init()` once with `gatewayWsUrl` and optional `getToken`, so the single WebSocket connection includes the token when required.

### Option 2: ESM (Vite / React app)

Import and call `init()` once inside your **protected layout** (after the user is logged in) so the bar appears on all authenticated pages. You **must** call `init()` when using the package as a dependency; it does not auto-init in this case.

```ts
import { init } from '@mitverse/mitbar-web';

// Inside your Layout component (e.g. in a useEffect):
init({
  enabled: true,
  gatewayWsUrl: import.meta.env.VITE_MITBAR_GATEWAY_WS_URL || 'wss://agent.mitverse.com/api/v1/agent/ws',
  getToken: () => localStorage.getItem('token'),  // optional; required when backend sets MITBAR_WS_REQUIRE_AUTH
});
```

- **enabled** – `true` to show the bar.
- **gatewayWsUrl** – WebSocket URL. Use env `VITE_MITBAR_GATEWAY_WS_URL` or the default above.
- **token** – Optional static JWT (e.g. from a variable). Prefer **getToken** when the token can change (e.g. after login).
- **getToken** – Optional function that returns the app’s JWT (e.g. `() => localStorage.getItem('token')`). Use when the backend requires auth (`MITBAR_WS_REQUIRE_AUTH`); the bar will add `?token=<JWT>` to the WebSocket URL.
- **agentApiBaseUrl** – Optional. When set together with **getToken**, the Mitbar logo becomes a button that opens a **task list** panel. Tasks are fetched **directly from the agent backend** (no agent frontend involved): `GET {agentApiBaseUrl}/conversations?source=mitbar&limit=50` with `Authorization: Bearer <token>`.

When `token` or `getToken()` returns a non-empty string, the client connects to `gatewayWsUrl?token=<JWT>`. If the backend requires auth and you omit the token, the connection will be closed with code `4401`.

---

## Task list (direct to agent backend)

mitbar-web is a **standalone** app. The **task list** (Mitbar logo click) is implemented entirely inside mitbar-web and talks **directly** to the **agent backend**:

- **Endpoint:** `GET {agentApiBaseUrl}/conversations?source=mitbar&limit=50`
- **Auth:** `Authorization: Bearer <token>` (from `getToken()` or `token`)
- **No agent frontend** is involved; the bar and task list do not use any code from the agent repo.

Example with task list enabled:

```ts
init({
  enabled: true,
  gatewayWsUrl: 'wss://agent.mitverse.com/api/v1/agent/ws',
  getToken: () => localStorage.getItem('token'),
  agentApiBaseUrl: 'https://agent.mitverse.com/api/v1/agent',  // enables task list panel
});
```

---

## Environment variables

When building your app (e.g. Vite), you can set:

| Variable | Description |
|----------|-------------|
| `VITE_MITBAR_GATEWAY_WS_URL` | WebSocket URL for the bar (e.g. `wss://agent.mitverse.com/api/v1/agent/ws`). Used by Vite apps. |
| `VITE_AGENT_API_BASE_URL` | Agent backend base URL for the task list (e.g. `https://agent.mitverse.com/api/v1/agent`). Used when passing `agentApiBaseUrl` from env. |
| `MITBAR_GATEWAY_WS_URL` | Alternative build-time default when bundled. |

---

## Message format

- The bar sends over WebSocket: `{ text, pageUrl, pageTitle, action: 'chat' | 'build' | 'deploy' }`.
- The gateway uses this payload and forwards to the agent (e.g. script-writer); responses are streamed back to the bar.

---

## Build

```bash
npm run build
```

Output in `dist/`:

- `mitbar.es.js` – ESM (for bundlers)
- `mitbar.umd.cjs` – UMD (script tag / CDN)

---

## Deploy

Build and serve `dist/` from your CDN or static host. If `gatewayWsUrl` is not set, the bar uses **wss://agent.mitverse.com/api/v1/agent/ws**. Ensure the WebSocket endpoint is reachable and that your origin is allowed by the backend (CORS / WebSocket origin). When the backend requires auth, pass **token** or **getToken** so the connection URL includes the JWT.