# Ojin Widget

Embeddable AI voice agent widget. Drop 2 lines of HTML into any website to add an interactive voice AI agent.

## Quick Start (2 minutes)

1. Copy `ojin-agent.js` and `agent.json` from `widget/release/` into your project
2. Edit `agent.json` — set the endpoints for your environment (see below)
3. Add these 2 lines before `</body>` in your HTML:

```html
<script src="ojin-agent.js"></script>
<ojin-agent widget-config-url="agent.json"></ojin-agent>
```

That's it.

## Environments

Set these values in `agent.json`:

| Environment  | `coreApiEndpoint`       | `botServerEndpoint`                                                        | `stage`        |
|-------------|-------------------------|----------------------------------------------------------------------------|----------------|
| **staging**    | `https://api.ojin.foo`  | `https://ojin-flashhead-staging--flashhead-agent-fastapi-app.modal.run`    | `"staging"`    |
| **production** | `https://api.ojin.ai`   | `https://ojin-flashhead-production--flashhead-agent-fastapi-app.modal.run` | `"production"` |

## Updating the Widget

1. Pull the latest `main` branch
2. Copy the new `ojin-agent.js` and `agent.json` from `widget/release/` into your project
3. Re-apply your environment endpoints in `agent.json`

## AI Assistant Integration

See [release/AGENTS.md](release/AGENTS.md) for skill files your AI coding assistant can follow step-by-step.

## Visual Configurator

A local tool for visually configuring and testing agents:

1. Copy the `release/` folder contents to a local directory
2. Run `node serve.cjs`
3. Open `http://localhost:8080`

## Development

```bash
cd widget/
yarn install
yarn dev          # Dev server on http://localhost:5173
yarn build        # Build to dist/ and update release/
yarn typecheck    # Type check only
```

## Publishing to npm

The widget is published as [`@ojin/agent`](https://www.npmjs.com/package/@ojin/agent) on the public npm registry and served to customers via jsDelivr:

```
https://cdn.jsdelivr.net/npm/@ojin/agent@latest/dist/ojin-agent.js
```

### Manual publish sequence

Run these steps whenever a new version is ready to go live:

```bash
# 1. Bump the version in package.json (semver — patch for fixes, minor for new features)
npm version patch   # or minor / major

# 2. Build the bundle
yarn build

# 3. Verify what will be published before it goes out — should be exactly:
#    README.md, dist/ojin-agent.js, package.json
#    (don't skip this — source maps and internal agent configs will sneak in if dist/ scope creeps)
npm pack --dry-run --json | python3 -c "import sys,json; d=json.load(sys.stdin)[0]; [print(f['path']) for f in d['files']]"

# 4. Publish to npm (requires npm login with an @ojin org member account)
npm publish --access public
```

jsDelivr picks up the new version within a few minutes. The `@latest` tag updates automatically.

> **TODO (CI):** This publish sequence should eventually be triggered automatically by the CI pipeline whenever `widget/package.json` version changes on a merge to `main`. That requires: adding `widget` to `.ci/config/projects.json`, adding a publish step to `.ci/aws-release-production.yml`, storing an npm automation token in AWS Secrets Manager, and granting the CodeBuild release role access to it.

## Checking which version is deployed

The widget bundle does **not** embed its own version, so you read it from where it's loaded, not from the running widget. There are three layers:

**1. What's published to the CDN** (what `@latest` resolves to, and every available version):

```bash
npm view @ojin/agent version     # the version @latest currently points to
npm view @ojin/agent versions    # every published version
npm view @ojin/agent dist-tags   # the dist-tags (e.g. latest)
```

jsDelivr mirrors npm; its API lists versions and tags:
`https://data.jsdelivr.com/v1/packages/npm/@ojin/agent`

**2. What a given page is actually loading** (the reliable, runtime way) — open the page, then in the browser DevTools:

- **Network** tab, filter `ojin-agent`: the request URL is `https://cdn.jsdelivr.net/npm/@ojin/agent@<VERSION>/dist/ojin-agent.js`. `<VERSION>` is exactly what that page loaded (an `@latest` embed is resolved to a concrete version in the jsDelivr redirect).
- Or **Elements → `<head>`**: find the `<script src=".../@ojin/agent@…">` tag.

If the page serves the widget from somewhere other than jsDelivr (e.g. it bundles the widget), that URL won't carry a version — see below.

**3. Ojin's own surfaces** (the front-page widget, the homepage playground/carousel, and the dashboard agent previews) load the widget **per environment** from the `Agents` CMS global:

| Environment | CMS field |
|---|---|
| **staging** | `https://cms.ojin.foo/admin/globals/agentService` → **Widget version (CDN pin)** |
| **production** | `https://cms.ojin.ai/admin/globals/agentService` → **Widget version (CDN pin)** |

- **Field set** (e.g. `0.0.70` or `latest`) → that surface loads exactly that version from jsDelivr, and it shows up in DevTools as in (2).
- **Field empty** → the surface uses the widget **bundled with that dashboard build**, whose version is `widget/package.json` at the dashboard's deployed commit. The bundled widget doesn't report its version at runtime, so to make the live version explicit (and visible in DevTools), pin it in the CMS field.

## License

MIT