npm package: @helpervia/widget
Description: HelperVia Chat Widget - Embed anywhere with script tag or npm
Author: HelperVia
Latest version: 1.0.0

# @helpervia/widget

HelperVia Chat Widget - Embed customer support chat anywhere with a simple script tag or npm package.

## 🚀 Installation

### Method 1: Script Tag (Recommended for most websites)

Add this code before the closing `</body>` tag:

```html
<!-- HelperVia Chat Widget -->
<script src="https://cdn.helpervia.com/widget/v1/helpervia-widget.umd.js"></script>
<script>
  HelperVia.init({
    widgetId: 'YOUR_WIDGET_ID',
    position: 'bottom-right',
    primaryColor: '#e7411b',
  });
</script>
```

### Method 2: NPM (For React/Next.js/Vue projects)

```bash
npm install @helpervia/widget
# or
yarn add @helpervia/widget
```

```tsx
import HelperVia from '@helpervia/widget';

HelperVia.init({
  widgetId: 'YOUR_WIDGET_ID',
  position: 'bottom-right',
  primaryColor: '#e7411b',
});
```

## 📖 Configuration Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `widgetId` | `string` | **required** | Your widget ID from HelperVia dashboard |
| `position` | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'` | `'bottom-right'` | Position of the widget |
| `primaryColor` | `string` | `'#e7411b'` | Primary color (hex code) |
| `zIndex` | `number` | `999999` | Custom z-index |
| `autoOpen` | `boolean` | `false` | Auto-open widget on page load |
| `autoOpenDelay` | `number` | `0` | Delay before auto-open (milliseconds) |
| `hideOnMobile` | `boolean` | `false` | Hide widget on mobile devices |
| `customData` | `object` | `undefined` | Custom data to send with messages |
| `onReady` | `function` | `undefined` | Callback when widget is ready |
| `onOpen` | `function` | `undefined` | Callback when widget is opened |
| `onClose` | `function` | `undefined` | Callback when widget is closed |
| `onMessageSent` | `function` | `undefined` | Callback when a message is sent |
| `onMessageReceived` | `function` | `undefined` | Callback when a message is received |

## 🎮 API Methods

### `init(config)`
Initialize the widget with configuration.

```javascript
HelperVia.init({
  widgetId: 'wgt_123',
  position: 'bottom-right',
  primaryColor: '#e7411b',
  onReady: () => console.log('Widget ready!'),
});
```

### `open()`
Open the chat widget.

```javascript
HelperVia.open();
```

### `close()`
Close the chat widget.

```javascript
HelperVia.close();
```

### `toggle()`
Toggle the chat widget open/closed.

```javascript
HelperVia.toggle();
```

### `sendMessage(message)`
Send a message programmatically.

```javascript
HelperVia.sendMessage('Hello from my website!');
```

### `show()`
Show the widget (if hidden).

```javascript
HelperVia.show();
```

### `hide()`
Hide the widget.

```javascript
HelperVia.hide();
```

### `destroy()`
Destroy the widget and remove it from DOM.

```javascript
HelperVia.destroy();
```

### `updateConfig(config)`
Update widget configuration.

```javascript
HelperVia.updateConfig({
  primaryColor: '#ff0000',
  position: 'bottom-left',
});
```

### `getConfig()`
Get current configuration.

```javascript
const config = HelperVia.getConfig();
console.log(config);
```

## 📱 React/Next.js Usage

### Basic Usage

```tsx
'use client';

import { useEffect } from 'react';
import HelperVia from '@helpervia/widget';

export default function App() {
  useEffect(() => {
    HelperVia.init({
      widgetId: 'wgt_123',
      position: 'bottom-right',
      primaryColor: '#e7411b',
    });

    return () => HelperVia.destroy();
  }, []);

  return (
    <div>
      <h1>My App</h1>
      <button onClick={() => HelperVia.open()}>
        Open Chat
      </button>
    </div>
  );
}
```

### Global Layout (Next.js 13+)

```tsx
// app/layout.tsx
'use client';

import { useEffect } from 'react';
import HelperVia from '@helpervia/widget';

export default function RootLayout({ children }) {
  useEffect(() => {
    HelperVia.init({
      widgetId: process.env.NEXT_PUBLIC_HELPERVIA_WIDGET_ID,
      position: 'bottom-right',
    });

    return () => HelperVia.destroy();
  }, []);

  return (
    <html>
      <body>{children}</body>
    </html>
  );
}
```

## 🎨 Customization Examples

### Auto-open after 3 seconds

```javascript
HelperVia.init({
  widgetId: 'wgt_123',
  autoOpen: true,
  autoOpenDelay: 3000,
});
```

### Custom callbacks

```javascript
HelperVia.init({
  widgetId: 'wgt_123',
  onReady: () => {
    console.log('Widget ready!');
  },
  onOpen: () => {
    console.log('User opened chat');
    // Track analytics
    gtag('event', 'chat_opened');
  },
  onMessageSent: (message) => {
    console.log('Message sent:', message);
  },
});
```

### Send custom data

```javascript
HelperVia.init({
  widgetId: 'wgt_123',
  customData: {
    userId: '12345',
    plan: 'premium',
    name: 'John Doe',
  },
});
```

### Different position

```javascript
HelperVia.init({
  widgetId: 'wgt_123',
  position: 'bottom-left',
});
```

## 🔧 Development

```bash
# Install dependencies
npm install

# Development mode
npm run dev

# Build
npm run build

# Open example
open examples/script-tag.html
```

## 📦 Build Output

- `dist/helpervia-widget.umd.js` - UMD format (for script tag)
- `dist/helpervia-widget.js` - CommonJS format
- `dist/helpervia-widget.esm.js` - ES Module format
- `dist/index.d.ts` - TypeScript definitions

## 🌐 Browser Support

- Chrome (latest)
- Firefox (latest)
- Safari (latest)
- Edge (latest)
- Mobile browsers (iOS Safari, Chrome Mobile)

## 📄 License

MIT

## 🤝 Support

For support, email support@helpervia.com or visit [helpervia.com](https://helpervia.com).