npm package: @plumoai/agent-widget-js
Description: PlumoAI Agent Widget for Vanilla JavaScript - A resizable chatbot widget component that embeds PlumoAI agents in any website (WordPress, plain HTML, etc.)
Author: PlumoAI
Latest version: 1.0.1

# PlumoAI Agent Widget for Vanilla JavaScript

A vanilla JavaScript chatbot widget component library that embeds PlumoAI agents in any website. Works with WordPress, plain HTML, React, Vue, Angular, or any JavaScript framework - **no dependencies required!**

## Features

- 🎯 **Zero Dependencies** - Pure vanilla JavaScript, works everywhere
- 📱 **Resizable Widget** - Floating widget with resize capability
- 📦 **Inline Widget** - Simple inline component for embedding in page content
- 🍪 **Auto Identity Management** - Automatically generates and stores user identity keys in cookies
- 🎨 **Customizable** - Configurable size, position, and constraints
- 🔒 **TypeScript** - Full TypeScript support with type definitions
- ⚡ **Lightweight** - Small bundle size, optimized for performance
- 🔄 **Maximize/Restore** - Floating widget can maximize to take 25% width, pushing content to 75%
- 📨 **PostMessage Support** - Listen for close/maximize/restore events from iframe
- 🌐 **WordPress Compatible** - Works seamlessly in WordPress themes and plugins

## Installation

### Via npm

```bash
npm install @plumoai/agent-widget-js
```

### Via CDN (Coming Soon)

```html
<script src="https://cdn.jsdelivr.net/npm/@plumoai/agent-widget-js/dist/index.umd.js"></script>
```

## Usage

### Basic Example (Floating Widget)

#### ES Modules

```javascript
import { PlumoAIAgentWidget } from '@plumoai/agent-widget-js';

const widget = new PlumoAIAgentWidget({
  agentId: 'your-agent-id',
  position: 'bottom-right'
});
```

#### Browser (Global)

```html
<script src="https://cdn.jsdelivr.net/npm/@plumoai/agent-widget-js/dist/index.umd.js"></script>
<script>
  const widget = new PlumoAIAgentWidget({
    agentId: 'your-agent-id',
    position: 'bottom-right'
  });
</script>
```

### WordPress Integration

#### Method 1: Add to Theme's functions.php

```php
function add_plumoai_widget() {
    ?>
    <script src="https://cdn.jsdelivr.net/npm/@plumoai/agent-widget-js/dist/index.umd.js"></script>
    <script>
        document.addEventListener('DOMContentLoaded', function() {
            new PlumoAIAgentWidget({
                agentId: 'your-agent-id',
                position: 'bottom-right',
                initialWidth: 420,
                initialHeight: 484
            });
        });
    </script>
    <?php
}
add_action('wp_footer', 'add_plumoai_widget');
```

#### Method 2: WordPress Plugin

Create a simple plugin:

```php
<?php
/**
 * Plugin Name: PlumoAI Agent Widget
 * Description: Add PlumoAI chatbot widget to your WordPress site
 * Version: 1.0.0
 */

function plumoai_widget_enqueue_scripts() {
    wp_enqueue_script(
        'plumoai-widget',
        'https://cdn.jsdelivr.net/npm/@plumoai/agent-widget-js/dist/index.umd.js',
        array(),
        '1.0.0',
        true
    );
}
add_action('wp_enqueue_scripts', 'plumoai_widget_enqueue_scripts');

function plumoai_widget_footer_script() {
    ?>
    <script>
        document.addEventListener('DOMContentLoaded', function() {
            new PlumoAIAgentWidget({
                agentId: '<?php echo get_option('plumoai_agent_id', ''); ?>',
                position: 'bottom-right'
            });
        });
    </script>
    <?php
}
add_action('wp_footer', 'plumoai_widget_footer_script');
```

### Inline Widget

```javascript
import { PlumoAIAgentWidgetInline } from '@plumoai/agent-widget-js';

// Place in a specific container
const inlineWidget = new PlumoAIAgentWidgetInline({
  agentId: 'your-agent-id',
  container: '#my-container', // CSS selector
  width: '100%',
  height: '600px'
});

// Or let it create its own container
const inlineWidget2 = new PlumoAIAgentWidgetInline({
  agentId: 'your-agent-id',
  width: '100%',
  height: '600px'
});
```

### With User Identity Key

```javascript
const widget = new PlumoAIAgentWidget({
  agentId: 'your-agent-id',
  userIdentityKey: 'user-specific-key',
  position: 'bottom-right'
});
```

### Custom Size Configuration

```javascript
const widget = new PlumoAIAgentWidget({
  agentId: 'your-agent-id',
  position: 'bottom-right',
  initialWidth: 400,
  initialHeight: 500,
  minWidth: 300,
  minHeight: 400,
  maxWidth: 800,
  maxHeight: 900
});
```

### Start Maximized

```javascript
const widget = new PlumoAIAgentWidget({
  agentId: 'your-agent-id',
  initialMaximized: true
});
```

## API Reference

### PlumoAIAgentWidget

#### Constructor Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `agentId` | `string` | - | **Required.** The PlumoAI agent ID to load in the iframe |
| `userIdentityKey` | `string` | - | Optional. User identity key. If not provided, a GUID will be auto-generated and stored in cookies |
| `position` | `"bottom-right" \| "bottom-left"` | `"bottom-right"` | Position of the floating button |
| `initialWidth` | `number` | `320` | Initial width of the chat window (in pixels) |
| `initialHeight` | `number` | `384` | Initial height of the chat window (in pixels) |
| `minWidth` | `number` | `280` | Minimum width of the chat window (in pixels) |
| `minHeight` | `number` | `300` | Minimum height of the chat window (in pixels) |
| `maxWidth` | `number` | `600` | Maximum width of the chat window (in pixels) |
| `maxHeight` | `number` | `800` | Maximum height of the chat window (in pixels) |
| `initialMaximized` | `boolean` | `false` | Whether the widget should start maximized (slides from right, full height, 1/4 width) |
| `className` | `string` | `""` | Additional CSS classes for the widget container |

#### Methods

- `destroy()` - Removes the widget from the DOM and cleans up event listeners

### PlumoAIAgentWidgetInline

#### Constructor Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `agentId` | `string` | - | **Required.** The PlumoAI agent ID to load in the iframe |
| `userIdentityKey` | `string` | - | Optional. User identity key. If not provided, a GUID will be auto-generated and stored in cookies |
| `width` | `string \| number` | `"100%"` | Width of the widget |
| `height` | `string \| number` | `"600px"` | Height of the widget |
| `className` | `string` | `""` | Additional CSS classes for the widget container |
| `container` | `string \| HTMLElement` | - | Container element or CSS selector where the widget should be mounted. If not provided, creates its own container |

#### Methods

- `destroy()` - Removes the widget from the DOM

## Identity Key Management

The widget automatically manages user identity keys:

1. **If `userIdentityKey` is provided**: Uses the provided value
2. **If not provided**: Checks browser cookie `plumoai_user_identity_key`
3. **If no cookie exists**: Generates a new GUID and stores it in the cookie (expires in 365 days)

This ensures users maintain the same identity across sessions without requiring manual key management.

## PostMessage Events

The widget listens for postMessage events from the iframe:

### Close
```javascript
window.parent.postMessage({ type: 'close' }, '*');
// or
window.parent.postMessage('close', '*');
```

### Maximize
```javascript
window.parent.postMessage({ type: 'maximize' }, '*');
// or
window.parent.postMessage('maximize', '*');
```

### Restore/Minimize
```javascript
window.parent.postMessage({ type: 'restore' }, '*');
// or
window.parent.postMessage('restore', '*');
```

## Iframe URL

The widget loads the PlumoAI agent in an iframe with the following URL pattern:

```
https://aiagent.plumoai.com/{agentId}?identitykey={identityKey}
```

Where:
- `{agentId}` is the agent ID you provide
- `{identityKey}` is the user identity key (from prop, cookie, or auto-generated)

## Requirements

- Modern browser with ES6+ support
- No framework dependencies required!

## License

MIT

## Support

For issues and questions, please visit [GitHub Issues](https://github.com/plumoai/agent-widget-js/issues)