npm package: @plumoai/agent-widget-vue
Description: PlumoAI Agent Widget for Vue - A resizable chatbot widget component that embeds PlumoAI agents in your Vue applications
Author: PlumoAI
Latest version: 1.0.0

# PlumoAI Agent Widget for Vue

A chatbot widget component library for Vue 3 that embeds PlumoAI agents in your applications. Includes both a floating resizable widget and a simple inline widget component.

## Features

- 🎯 **Easy Integration** - Simple Vue 3 components, easy to integrate
- 📱 **Resizable Widget** - Floating widget with resize capability from all directions (8 handles)
- 📦 **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

## Installation

```bash
npm install @plumoai/agent-widget-vue
```

## Usage

### Basic Example (Floating Widget)

```vue
<template>
  <PlumoAIAgentWidget 
    agent-id="your-agent-id"
    position="bottom-right"
  />
</template>

<script setup lang="ts">
import { PlumoAIAgentWidget } from '@plumoai/agent-widget-vue';
</script>
```

### With User Identity Key

```vue
<template>
  <PlumoAIAgentWidget 
    agent-id="your-agent-id"
    user-identity-key="user-specific-key"
    position="bottom-right"
  />
</template>

<script setup lang="ts">
import { PlumoAIAgentWidget } from '@plumoai/agent-widget-vue';
</script>
```

### Custom Size Configuration

```vue
<template>
  <PlumoAIAgentWidget 
    agent-id="your-agent-id"
    position="bottom-right"
    :initial-width="400"
    :initial-height="500"
    :min-width="300"
    :min-height="400"
    :max-width="800"
    :max-height="900"
  />
</template>

<script setup lang="ts">
import { PlumoAIAgentWidget } from '@plumoai/agent-widget-vue';
</script>
```

### Start Maximized

```vue
<template>
  <PlumoAIAgentWidget 
    agent-id="your-agent-id"
    :initial-maximized="true"
  />
</template>

<script setup lang="ts">
import { PlumoAIAgentWidget } from '@plumoai/agent-widget-vue';
</script>
```

### Inline Widget (Simple Container)

```vue
<template>
  <div style="width: 100%; padding: 20px;">
    <PlumoAIAgentWidgetInline 
      agent-id="your-agent-id"
      width="100%"
      height="600px"
    />
  </div>
</template>

<script setup lang="ts">
import { PlumoAIAgentWidgetInline } from '@plumoai/agent-widget-vue';
</script>
```

The inline widget is perfect for embedding directly in your page content without floating or resizing functionality.

## Components

### PlumoAIAgentWidget

The main floating, resizable widget component.

#### Props

| Prop | 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 |

### PlumoAIAgentWidgetInline

A simple inline widget component that can be placed in any container.

#### Props

| Prop | 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 |

## 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.

## Resizing (PlumoAIAgentWidget only)

The floating chat window can be resized from all directions:
- **4 Corner handles**: Top-left, top-right, bottom-left, bottom-right
- **4 Edge handles**: Top, bottom, left, right

Simply hover over any edge or corner and drag to resize. The window respects the configured min/max constraints.

**Note**: The inline widget (`PlumoAIAgentWidgetInline`) does not support resizing - it uses fixed width and height as specified in props.

## 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)

## 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', '*');
```

## Requirements

- Vue 3.0.0 or higher

## License

MIT

## Support

For issues and questions, please visit [GitHub Issues](https://github.com/plumoai/agent-widget-vue/issues)