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

## License

MIT