npm package: @paperlinkai/chat
Description: PaperLink AI Chat Widget - Easy integration for any website
Author: PaperLink AI
Latest version: 0.1.5

# 🤖 PaperLink Chat

[![npm version](https://badge.fury.io/js/@paperlink%2Fchat.svg)](https://badge.fury.io/js/@paperlink%2Fchat)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Easy-to-integrate AI chat widget for any website**

Add an intelligent chat assistant to your website in under 60 seconds. Built with modern web technologies, optimized for performance, and designed for seamless integration.

## ✨ Features

- 🚀 **Lightning fast** - 63KB total bundle size
- 📱 **Mobile responsive** - Works perfectly on all devices
- 🎨 **Fully customizable** - Colors, position, size, and behavior
- 🔒 **Privacy focused** - Shadow DOM isolation, no conflicts
- 🌐 **Universal** - Works with any website or framework
- 📦 **Zero dependencies** - Self-contained and optimized
- 🛡️ **TypeScript support** - Full type definitions included

## 🚀 Quick Start

### Option 1: CDN (Easiest)

Add these two lines to your website:

```html
<!-- Add to <head> -->
<link
  rel="stylesheet"
  href="https://unpkg.com/@paperlink/chat@latest/dist/style.css"
/>

<!-- Add before closing </body> -->
<script src="https://unpkg.com/@paperlink/chat@latest/dist/chat.min.js"></script>
<script>
  PaperlinkChat.init({
    apiKey: "your-api-key-here",
    title: "AI Assistant",
    greeting: "Hi! How can I help you today?",
  });
</script>
```

### Option 2: NPM Install

```bash
npm install @paperlink/chat
```

```javascript
import Chat from "@paperlink/chat";
import "@paperlink/chat/dist/style.css";

Chat.init({
  apiKey: "your-api-key-here",
  title: "AI Assistant",
});
```

## 📋 Configuration

### Basic Configuration

```javascript
PaperlinkChat.init({
  // Required
  apiKey: "your-organization-api-key",

  // Optional
  title: "Customer Support",
  greeting: "How can we help you today?",
  placeholder: "Type your message...",
  position: "bottom-right", // 'bottom-left', 'top-right', 'top-left'
  width: 384,
  height: 600,
  autoOpen: false,
  debug: false,
});
```

### Theme Customization

```javascript
PaperlinkChat.init({
  apiKey: "your-api-key",
  theme: {
    primaryColor: "#2563eb",
    backgroundColor: "#ffffff",
    textColor: "#1f2937",
    userMessageColor: "#2563eb",
    botMessageColor: "#f3f4f6",
    borderColor: "#e5e7eb",
  },
});
```

### Custom Icons

Customize the widget icons with your own branding:

```javascript
PaperlinkChat.init({
  apiKey: "your-api-key",
  customIcons: {
    bot: "https://your-domain.com/bot-icon.svg",
    send: "https://your-domain.com/send-icon.svg",
    minimize: "https://your-domain.com/minimize-icon.svg",
    chatButton: "https://your-domain.com/chat-button-icon.svg",
  },
});
```

**Icon Requirements:**

- **Formats**: SVG, PNG, JPG, WebP
- **Size**: Recommended 24x24px or 32x32px
- **URL**: Must be publicly accessible HTTPS URLs
- **CORS**: Icons must allow cross-origin requests
- **Fallback**: Default Material Icons used if custom icons fail to load
- **Validation**: Icons are validated for dimensions and CORS headers
- **Caching**: Successfully loaded icons are cached for the session
- **Error Handling**: Detailed error logging for debugging

**Icon Types:**

- `bot` - Bot avatar in messages and typing indicator
- `send` - Send button in message input
- `minimize` - Minimize button in chat header
- `scrollDown` - Scroll to bottom button (when chat is scrolled up)
- `chatButton` - Chat button that opens/expands the widget

### Chat Button Customization

Customize the appearance of the chat button that opens your widget:

```javascript
PaperlinkChat.init({
  apiKey: "your-api-key",

  // Custom background color
  chatButtonBackgroundColor: "#10b981", // Any valid CSS color

  // Hide background circle (icon only)
  showChatButtonBackground: false,

  // Custom chat button icon
  customIcons: {
    chatButton: "https://your-domain.com/chat-icon.svg",
  },
});
```

**Chat Button Options:**

- **Background Color**: Use any valid CSS color (hex, rgb, rgba, named colors)
- **Background Visibility**: Show or hide the circular background
- **Custom Icon**: Replace the default chat bubble with your own icon
- **Hover Effects**: Automatic darker shade on hover for custom colors

**⚠️ Important**: 
- `showChatButtonBackground: false` hides only the background circle - the icon remains visible for user interaction
- `showChatButton: false` completely hides the entire button - you'll need an alternative way for users to open the chat (e.g., programmatically via `widget.open()`)

This design ensures users can always access the widget while giving you complete control over appearance.

### All Options

| Parameter                   | Type      | Default                   | Description                             |
| --------------------------- | --------- | ------------------------- | --------------------------------------- |
| `apiKey`                    | `string`  | **Required**              | Your PaperLink organization API key     |
| `title`                     | `string`  | "AI Assistant"            | Widget header title                     |
| `greeting`                  | `string`  | "Hi! How can I help you?" | Initial greeting message                |
| `placeholder`               | `string`  | "Type your message..."    | Input field placeholder                 |
| `position`                  | `string`  | "bottom-right"            | Widget position on screen               |
| `width`                     | `number`  | 384                       | Widget width in pixels                  |
| `height`                    | `number`  | 600                       | Widget height in pixels                 |
| `autoOpen`                  | `boolean` | false                     | Auto-open widget on page load           |
| `debug`                     | `boolean` | false                     | Enable debug mode (mock API)            |
| `maxMessages`               | `number`  | 50                        | Maximum messages to store               |
| `customIcons`               | `object`  | {}                        | Custom icon URLs for branding           |
| `chatButtonBackgroundColor` | `string`  | undefined                 | Custom background color for chat button |
| `showChatButtonBackground`  | `boolean` | true                      | Show/hide chat button background circle (icon remains visible) |
| `showChatButton`            | `boolean` | true                      | Show/hide entire chat button (complete control) |

## 🎯 Framework Integration

### React

```jsx
import { useEffect } from "react";
import Chat from "@paperlink/chat";
import "@paperlink/chat/dist/style.css";

export default function App() {
  useEffect(() => {
    const widget = Chat.init({
      apiKey: "your-api-key",
      title: "Support Chat",
    });

    return () => {
      // Cleanup on unmount
      widget.destroy();
    };
  }, []);

  return <div>Your app content</div>;
}
```

### Vue.js

```vue
<template>
  <div>Your app content</div>
</template>

<script>
import Chat from "@paperlink/chat";
import "@paperlink/chat/dist/style.css";

export default {
  mounted() {
    this.widget = Chat.init({
      apiKey: "your-api-key",
      title: "Vue Chat",
    });
  },
  beforeUnmount() {
    if (this.widget) {
      this.widget.destroy();
    }
  },
};
</script>
```

### Next.js

```jsx
import { useEffect } from "react";
import dynamic from "next/dynamic";

// Dynamically import to avoid SSR issues
const Chat = dynamic(() => import("@paperlink/chat"), {
  ssr: false,
});

export default function Layout({ children }) {
  useEffect(() => {
    import("@paperlink/chat/dist/style.css");
    import("@paperlink/chat").then((Chat) => {
      Chat.default.init({
        apiKey: "your-api-key",
      });
    });
  }, []);

  return <div>{children}</div>;
}
```

### WordPress

Add to your theme's `functions.php`:

```php
function add_paperlink_widget() {
    wp_enqueue_style('paperlink-chat', 'https://unpkg.com/@paperlink/chat/dist/style.css');
    wp_enqueue_script('paperlink-chat', 'https://unpkg.com/@paperlink/chat/dist/chat.min.js', array(), null, true);

    wp_add_inline_script('paperlink-chat', '
        PaperlinkChat.init({
            apiKey: "your-api-key",
            title: "Support Chat"
        });
    ');
}
add_action('wp_enqueue_scripts', 'add_paperlink_widget');
```

## 🔧 Programmatic Control

```javascript
// Initialize widget
const widget = PaperlinkChat.init({
  apiKey: "your-api-key",
  autoOpen: false,
});

// Control methods
widget.open(); // Open the widget
widget.close(); // Close the widget
widget.destroy(); // Remove widget completely
widget.updateConfig({
  // Update configuration
  title: "New Title",
  theme: { primaryColor: "#red" },
});

// Get current state
const config = widget.getConfig();
```

## 🛠️ Troubleshooting

### Widget not appearing?

- Check browser console for errors
- Verify your API key is correct
- Ensure CSS file is loaded before JavaScript
- Check for Content Security Policy restrictions

### Styling conflicts?

- Widget uses Shadow DOM for style isolation
- All styles are prefixed and contained
- No external CSS should affect the widget

### Performance concerns?

- Widget is optimized for minimal impact
- Total size: ~73KB (JS + CSS combined)
- Loads asynchronously after page content
- Uses efficient bundling and tree-shaking

## 📱 Browser Support

- ✅ Chrome 60+
- ✅ Firefox 55+
- ✅ Safari 12+
- ✅ Edge 79+
- ✅ Mobile browsers (iOS Safari, Chrome Mobile)

## 🔒 Security

- 🛡️ **Shadow DOM isolation** - No CSS/JS conflicts
- 🔐 **HTTPS only** - All communications encrypted
- 🚫 **No tracking** - Privacy-focused design
- ✅ **CSP compatible** - Works with strict security policies

## 🎨 Customization Examples

### Dark Theme

```javascript
PaperlinkChat.init({
  apiKey: "your-api-key",
  theme: {
    primaryColor: "#8b5cf6",
    backgroundColor: "#1f2937",
    textColor: "#ffffff",
    borderColor: "#374151",
    userMessageColor: "#8b5cf6",
    botMessageColor: "#374151",
  },
});
```

### Corporate Branding

```javascript
PaperlinkChat.init({
  apiKey: "your-api-key",
  title: "Customer Success",
  greeting: "Welcome! How can we assist you today?",
  theme: {
    primaryColor: "#dc2626", // Your brand color
    backgroundColor: "#ffffff",
    userMessageColor: "#dc2626",
    botMessageColor: "#f3f4f6",
  },
});
```

## 📖 API Reference

### Methods

- `PaperlinkChat.init(config)` - Initialize widget with configuration
- `widget.open()` - Open the chat widget
- `widget.close()` - Close the chat widget
- `widget.destroy()` - Remove widget from page
- `widget.updateConfig(newConfig)` - Update widget configuration
- `widget.getConfig()` - Get current configuration

### Events (Coming Soon)

- `paperlink-chat-open` - Widget opened
- `paperlink-chat-close` - Widget closed
- `paperlink-chat-message` - New message sent/received

## 📞 Support

- ✉️ **Email**: admin@paperlinkai.com

**Made with ❤️ by the PaperLink AI team**

[Website](https://paperlinkai.com)

</div>