npm package: @kognitiv-ai/kog-chat
Description: Kog Chat widget - embeddable AI chat for your website
Author: Kognitiv AI
Latest version: 1.0.24

# @kognitiv-ai/kog-chat

Embeddable AI chat widget for your website.

## Installation

**npm:**
```bash
npm install @kognitiv-ai/kog-chat
```

**CDN:**
```html
<script src="https://unpkg.com/@kognitiv-ai/kog-chat"></script>
```

## Usage

**Minimal:**
```javascript
import KogChat from '@kognitiv-ai/kog-chat';

new KogChat().mount(document.body);
```

**With client-side tools:**
```javascript
import KogChat from '@kognitiv-ai/kog-chat';

const kog = new KogChat();

// Register tools the AI can invoke
kog.registerTool('read_page_content', () => document.body.innerText);
kog.registerTool('get_current_url', () => window.location.href);
kog.registerTool('get_selected_text', () => window.getSelection().toString());

kog.mount(document.body);
```

**With backend token callback (auto cache for 12h):**
```javascript
import KogChat from '@kognitiv-ai/kog-chat';

const kog = new KogChat({
  apiBaseUrl: 'https://your-gateway',
  authTokenProvider: async () => {
    const res = await fetch('/api/chat/token');
    const data = await res.json();
    return data.token; // JWT from your backend
  },
});

kog.mount(document.body);
```

**CDN (no build step):**
```html
<script src="https://unpkg.com/@kognitiv-ai/kog-chat"></script>
<script>
  const kog = new KogChat();
  kog.registerTool('read_page_content', () => document.body.innerText);
  kog.mount(document.body);
</script>
```

## Configuration

```javascript
const kog = new KogChat({
  // All options are optional
  bearerToken: 'jwt-token',        // Pre-authenticate (skip login screen)
  apiBaseUrl: 'https://your-api',   // Backend API base
  theme: 'light',                  // 'dark' | 'light'
  corner: 'bottom-right',          // Widget position
  paneSide: 'right',               // Pane slide direction
  paneWidth: '550px',              // Pane width
  paneHeight: '100%',              // Pane height
  primaryColor: '#2563eb',         // Brand colors
  secondaryColor: '#00c389',
  tertiaryColor: '#d3d9e4',
  surfaceColor: '#f7f9fc',         // Surface background
  panelColor: '#ffffff',           // Panel background
  textColor: '#0f172a',
  triggerIconUrl: 'https://cdn.example.com/brand/chat-icon.svg', // or triggerIconSvg (inline)
  fullscreen: false,               // If true, iframe fills the provided container and stays open
});

// For an inline, always-open embed:
// const kog = new KogChat({ fullscreen: true }).mount(document.getElementById('chat-container'));
```

All options can also be provided later via `kog.updateConfig({ ... })`.

## Events

```javascript
kog.on('ready', () => console.log('Widget ready'));
kog.on('opened', () => console.log('Chat opened'));
kog.on('closed', () => console.log('Chat closed'));
kog.on('toolCall', ({ toolName, args }) => console.log('Tool called:', toolName));
```

## API

| Method | Description |
|--------|-------------|
| `mount(element)` | Mount widget to a DOM element |
| `unmount()` | Remove widget |
| `registerTool(name, callback)` | Register a client-side tool |
| `registerAuthTokenProvider(callback)` | Register backend token callback (auto refresh/cache) |
| `unregisterTool(name)` | Remove a tool |
| `open()` | Open chat pane |
| `close()` | Close chat pane |
| `on(event, callback)` | Add event listener |
| `off(event, callback)` | Remove event listener |
| `whenReady()` | Returns Promise that resolves when ready |
| `updateConfig(config)` | Update configuration after mounting |

### Static Properties

| Property | Description |
|----------|-------------|
| `KogChat.VERSION` | Current package version |
| `KogChat.getIframeSrc(version?)` | Get the versioned iframe URL |

## Versioning & Caching

The widget iframe is served from unpkg CDN with automatic versioning. Each version of the npm package points to a unique iframe URL, ensuring proper cache invalidation when you update.

```javascript
// Check current version
console.log(KogChat.VERSION); // e.g., '1.0.20'

// Get the iframe URL (automatically versioned)
console.log(KogChat.getIframeSrc()); // https://unpkg.com/@kognitiv-ai/kog-chat@1.0.20/iframe.html

// Use a specific version
console.log(KogChat.getIframeSrc('1.0.15')); // https://unpkg.com/@kognitiv-ai/kog-chat@1.0.15/iframe.html
```

## Self-Hosting

To host the widget yourself instead of using unpkg:

```javascript
const kog = new KogChat({
  src: 'https://your-cdn.com/kog-chat/v1.0.20/iframe.html'
});
```

## License

MIT