npm package: @streamoji/avatar-widget
Description: Plug-and-play React avatar widget for token-based AI conversations.
Latest version: 0.5.8

# @streamoji/avatar-widget

Plug-and-play avatar widget for token-based AI conversations. Use the **React** component in your app or drop in the **script-tag (web)** build on any HTML page—no React required.

## Installation

```bash
npm install @streamoji/avatar-widget
```

Peer dependencies (install if not already present):

```bash
npm install react react-dom three @react-three/fiber @react-three/drei
```

## Usage

```tsx
import { AvatarWidget } from "@streamoji/avatar-widget";
import "@streamoji/avatar-widget/styles.css";

function App() {
  return (
    <AvatarWidget
      agentId="YOUR_AGENT_ID"
      onNavigationRequested={(url) => window.open(url, "_blank")}
    />
  );
}
```

With optional user prefill and avatar gender:

```tsx
import { AvatarWidget } from "@streamoji/avatar-widget";
import "@streamoji/avatar-widget/styles.css";

function App() {
  const user = useCurrentUser(); // your auth

  return (
    <AvatarWidget
      agentId="YOUR_AGENT_ID"
      presetUserDetails={
        user
          ? { name: user.displayName, email: user.email, phone: user.phone }
          : undefined
      }
      onNavigationRequested={(url) => window.open(url, "_blank")}
    />
  );
}
```

## Web flow (script tag, no React)

You can embed the widget on any HTML page without a React app. Use the UMD build and call the global init.

**1. Build the UMD bundle** (if you’re developing the package; otherwise use the published `dist`):

```bash
npm run build:html
```

**2. Include the script and styles** in your HTML:

```html
<link rel="stylesheet" href="path/to/avatar-widget.umd.css">
<script src="path/to/avatar-widget.umd.js"></script>
```

For npm installs, the files are in `node_modules/@streamoji/avatar-widget/dist/` (e.g. `avatar-widget.umd.js`, `avatar-widget.umd.css`). You can copy them to your static assets or point your bundler at them.

**3. Initialize the widget** (e.g. before `</body>`):

```html
<script>
  StreamojiLeadsAvatarWidget.init({ agentId: "YOUR_AGENT_ID" });
</script>
```

If you don’t add a container, the widget creates one fixed at the bottom-right of the page. To control placement, add a div with id `streamoji-leads-avatar-widget-root` where the widget should mount:

```html
<div id="streamoji-leads-avatar-widget-root"></div>
<script>
  StreamojiLeadsAvatarWidget.init({ agentId: "YOUR_AGENT_ID" });
</script>
```

Session UID generation uses the Web Crypto API and requires a [secure context](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API#secure_contexts) (HTTPS or localhost). On plain HTTP, HMAC-based session IDs will not be available.

### Web init options

| Option | Type | Description |
|--------|------|-------------|
| `agentId` | `string` | Agent ID; widget fetches config (and records visit) and uses it for chat/STT. |

## Props (React)

| Prop | Type | Description |
|------|------|-------------|
| `agentId` | `string` | Agent ID to fetch config and for chat/STT. |
| `onNavigationRequested` | `(url: string) => void` | Called when the agent requests a link; if not provided, links open in a new tab. |
| `avatarGender` | `"male" \| "female"` | Gender of the avatar for idle animations. Defaults to `"male"`. |
| `presetUserDetails` | `UserDetails \| undefined` | Optional user details (name, email, phone) to identify logged-in users and skip lead capture. |

### UserDetails

```ts
interface UserDetails {
  name?: string;
  email?: string;
  phone?: string;
}
```

## Publishing

From the repo root:

```bash
cd packages/avatar-widget
npm run build       # React build
npm run build:html  # optional: UMD bundle for web/script-tag usage (or use npm run build:all)
npm version patch   # or minor / major
npm publish --access public
```

Scoped packages require `--access public` if the scope is not on a paid npm plan.