npm package: @olotalk/widget
Description: The [Olotalk](https://olotalk.com) AI chat widget — a Svelte 5 component that mounts a RAG-powered, multilingual chat assistant into any web page via Shadow DOM.
Latest version: 0.3.0

# @olotalk/widget

The [Olotalk](https://olotalk.com) AI chat widget — a Svelte 5 component that mounts a RAG-powered, multilingual chat assistant into any web page via Shadow DOM.

> **Most users should use [`@olotalk/widget-loader`](https://www.npmjs.com/package/@olotalk/widget-loader) instead.** It handles config fetching, browser compatibility, and dynamic loading with a single `<script>` tag. Use this package directly only if you need low-level control over widget instantiation.

---

## Install

```bash
npm install @olotalk/widget
```

---

## Usage

```ts
import { createWidget } from '@olotalk/widget'

const widget = createWidget(document.body, {
  widgetId: 'YOUR_WIDGET_ID',
  origin: 'https://api.olotalk.com',
  config: widgetConfig,   // fetched from /public/widgets/:id/config
  theme: 'light',
  placement: 'floating',
  cssUrl: 'https://cdn.jsdelivr.net/npm/@olotalk/widget/dist/olotalk-widget.css',
})
```

### CSS

The widget loads its styles via a `<link>` injected inside the Shadow DOM. The CSS URL will be resolved automatically from the widget config in a future release. Until then, pass it explicitly via `cssUrl` or import the stylesheet manually:

```ts
import '@olotalk/widget/style.css'
```

---

## `createWidget(mount, options)`

Mounts the widget into the given element and returns a `WidgetInstance`.

### Options

| Option | Type | Required | Description |
|---|---|---|---|
| `widgetId` | `string` | Yes | Your widget ID. |
| `origin` | `string` | Yes | Base URL of your Olotalk API. |
| `config` | `WidgetConfig` | Yes | Widget configuration object from the API. |
| `theme` | `"light"` \| `"dark"` \| `object` | No | Color scheme or custom theme overrides. |
| `placement` | `"floating"` \| `"embedded"` | No | Floating launcher or inline panel (default: `"floating"`). |
| `cssUrl` | `string` | No | URL of the widget stylesheet. Will be resolved automatically from the widget config in a future release. |
| `locale` | `string` | No | Force a display language: `"en"` \| `"fr"` \| `"en-CA"` \| `"fr-CA"`. |

### `WidgetConfig` shape

This is returned by the Olotalk API at `/public/widgets/:id/config`.

```ts
type WidgetConfig = {
  tenantId: string
  widgetId: string
  displayName?: string
  theme?: Record<string, any>
  launcher?: {
    logoUrl?: string
    position?: 'bottom-right' | 'bottom-left'
    teaser?: {
      enabled?: boolean
      messages?: string[]
      delayMs?: number
      durationMs?: number
      cooldownMs?: number
      maxShowsPerSession?: number
    }
  }
  allowedDomains?: string[]
  features?: {
    domRagEnabled?: boolean
    siteRagEnabled?: boolean
    citationsEnabled?: boolean
    streamingEnabled?: boolean
  }
  security?: {
    rateLimitPer5Min?: number
    captchaMode?: boolean
  }
  privacy?: {
    piiRedaction?: boolean
    retentionDays?: number
  }
}
```

---

## `WidgetInstance` API

```ts
widget.open()                          // Open the chat panel
widget.close()                         // Close the chat panel
widget.setTheme(theme)                 // Change theme at runtime
widget.destroy(opts?: { outro?: boolean }) // Unmount and remove from DOM

// Subscribe to events
widget.on('ready', ({ widgetId }) => { ... })
widget.on('open',  () => { ... })
widget.on('close', () => { ... })
widget.on('send',  ({ text }) => { ... })
```

---

## Distribution files

| File | Format | Use case |
|---|---|---|
| `dist/olotalk-widget.js` | ESM | Dynamic `import()` from CDN or bundler |
| `dist/olotalk-widget.iife.js` | IIFE | Legacy browsers (`<script>` tag, no module support) |
| `dist/olotalk-widget.css` | CSS | Styles loaded inside the Shadow DOM |
| `dist/index.d.ts` | TypeScript | Type definitions |

---

## Features

- **RAG-powered answers** — responses grounded in your website's knowledge base, not generic LLM output
- **Multilingual** — `en` and `fr` built-in (with `en-CA` / `fr-CA` variants); same-language retrieval with cross-language fallback
- **Streaming** — real-time text generation for a conversational feel
- **Citations** — optionally surfaces source URLs alongside answers
- **Proactive teasers** — configurable delay-based messages to prompt engagement
- **Shadow DOM isolation** — widget styles never bleed into the host page
- **Anonymous by default** — no visitor login required
- **Domain whitelisting** — control which sites can embed the widget
- **Privacy controls** — optional PII redaction and configurable data retention

---

## License

MIT © [Olotalk](https://olotalk.com)