npm package: @olotalk/widget-loader
Description: Embed the [Olotalk](https://olotalk.com) AI chat widget on any website with a single `<script>` tag — no framework required.
Latest version: 0.3.0

# @olotalk/widget-loader

Embed the [Olotalk](https://olotalk.com) AI chat widget on any website with a single `<script>` tag — no framework required.

The loader handles config fetching, browser compatibility detection, and dynamic loading of the widget bundle from the CDN. Your visitors get a grounded, RAG-powered chat assistant that answers questions based on your own content.

---

## Quick start

```html
<script
  src="https://cdn.jsdelivr.net/npm/@olotalk/widget-loader/dist/loader.iife.js"
  data-olotalk-widget-id="YOUR_WIDGET_ID"
  data-olotalk-origin="https://api.olotalk.com"
></script>
```

Paste this before `</body>` on any page. The widget appears immediately as a floating launcher in the bottom-right corner.

> Get your widget ID from the [Olotalk dashboard](https://olotalk.com).

---

## Configuration

### Via HTML attributes

All attributes are read from the `<script>` tag itself.

| Attribute | Type | Description |
|---|---|---|
| `data-olotalk-widget-id` | `string` | **Required.** Your widget ID from the dashboard. |
| `data-olotalk-origin` | `string` | Base URL of your Olotalk API (e.g. `https://api.olotalk.com`). Defaults to current page origin. |
| `data-olotalk-locale` | `string` | Force a display language: `"en"`, `"fr"`, `"en-CA"`, `"fr-CA"`. Defaults to browser language. |
| `data-olotalk-cdn-base` | `string` | Override the widget asset base URL (for self-hosting). |

### Via `window.OlotalkConfig`

Declare a global config object **before** the loader script for programmatic setup:

```html
<script>
  window.OlotalkConfig = {
    widgetId: "YOUR_WIDGET_ID",
    origin: "https://api.olotalk.com",
    locale: "fr",
    theme: "dark",
    placement: "embedded",
    mount: "#chat-container",
  };
</script>
<script src="https://cdn.jsdelivr.net/npm/@olotalk/widget-loader/dist/loader.iife.js"></script>
```

### Full config reference

| Option | Type | Default | Description |
|---|---|---|---|
| `widgetId` | `string` | — | **Required.** Your widget ID. |
| `origin` | `string` | `window.location.origin` | Base URL of your Olotalk API. |
| `locale` | `string` | Browser language | Force language: `"en"` \| `"fr"` \| `"en-CA"` \| `"fr-CA"`. |
| `theme` | `"light"` \| `"dark"` \| `object` | `"light"` | Color scheme or custom theme overrides. |
| `placement` | `"floating"` \| `"embedded"` | `"floating"` | Floating launcher button or inline panel. |
| `mount` | `string` | `document.body` | CSS selector for the widget mount point (use with `"embedded"`). |
| `version` | `string` | `"latest"` | Pin a specific `@olotalk/widget` npm version (e.g. `"0.1.0"`). |
| `cdnBase` | `string` | jsDelivr CDN | Override widget asset base URL for self-hosting. |
| `cssUrl` | `string` | Auto-resolved | Override the widget CSS URL. In a future release this will be provided automatically by the widget config from the dashboard. |

---

## JavaScript API

The loader exposes a global `Olotalk()` command queue. You can call it before or after the script loads.

```js
// Open or close the panel programmatically
Olotalk('open')
Olotalk('close')

// Re-initialize with a different config
Olotalk('init', { locale: 'fr' })

// Remove the widget from the page entirely
Olotalk('destroy')
```

Commands queued before the widget loads are replayed automatically once it is ready.

---

## Version pinning

By default, the loader fetches the `latest` published version of `@olotalk/widget` from jsDelivr. To lock a specific version:

```html
<!-- Pin widget bundle to a specific version -->
<script
  src="https://cdn.jsdelivr.net/npm/@olotalk/widget-loader/dist/loader.iife.js"
  data-olotalk-widget-id="YOUR_WIDGET_ID"
  data-olotalk-version="0.1.0"
></script>
```

Or pin the loader itself by version:

```html
<script src="https://cdn.jsdelivr.net/npm/@olotalk/widget-loader@0.0.1/dist/loader.iife.js" ...></script>
```

---

## Self-hosting

To serve widget assets from your own server instead of jsDelivr:

```html
<script
  src="/path/to/loader.iife.js"
  data-olotalk-widget-id="YOUR_WIDGET_ID"
  data-olotalk-cdn-base="/assets/widget"
></script>
```

The loader will fetch `olotalk-widget.js`, `olotalk-widget.iife.js`, and `olotalk-widget.css` from the provided base URL.

---

## npm install

If you are using a bundler or framework, you can import the loader directly:

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

```ts
import { ensureWidget } from '@olotalk/widget-loader'

ensureWidget({
  widgetId: 'YOUR_WIDGET_ID',
  origin: 'https://api.olotalk.com',
})
```

---

## License

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