npm package: @onionshack/ocpb-chatbox-sdk-prod
Description: A lightweight, embeddable chat widget powered by React 19, Vite, and Tailwind CSS. Easily integrate a floating chatbot into any website with Firebase backend support and WebSocket real-time messaging.
Latest version: 0.2.3

# OCPB Chatbot Widget SDK

A lightweight, embeddable chat widget powered by React 19, Vite, and Tailwind CSS. Easily integrate a floating chatbot into any website with Firebase backend support and WebSocket real-time messaging.

## Features

- 🎯 **Floating Widget**: Unobtrusive bottom-right positioning with expandable interface
- 💬 **Rich Messaging**: Markdown support (GFM) for formatted bot and user messages
- 🔄 **Real-time**: WebSocket integration for instant message delivery
- 🎨 **Customizable**: Configure title, placeholder, suggestions, and styling
- 📦 **Multiple Integration Options**: Use as React component or vanilla JavaScript
- 🔥 **Firebase Ready**: Built-in Firebase authentication and storage support
- ⚡ **Lightweight**: Optimized bundle size with tree-shaking support

---

## Table of Contents

- [Quick Start](#quick-start)
- [Usage](#usage)
  - [Option 1: Vanilla JavaScript (HTML)](#option-1-vanilla-javascript-html)
  - [Option 2: React Component](#option-2-react-component)
- [Configuration](#configuration)
- [Installation](#installation)

---

## Quick Start

### Local Development

1. **Clone and install dependencies:**
   ```bash
   npm install
   ```

2. **Start the development server:**
   ```bash
   npm run dev
   ```

3. **Open your browser:**
   Navigate to `http://localhost:5173` to see the demo

---

## Usage

### Option 1: Vanilla JavaScript (HTML)

Perfect for integrating into existing websites, WordPress, static HTML pages, or any non-React application.

#### Step 1: Include the SDK

```html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>My Website</title>
</head>
<body>
    <!-- Your website content -->
    <h1>Welcome to my website</h1>

    <!-- Load the chat widget SDK -->
    <script src="https://cdn.example.com/chat-widget-sdk.umd.js"></script>

    <!-- Initialize the widget -->
    <script>
        ChatWidgetSDK.initChatWidget({
            firebaseConfig: {
                apiKey: "YOUR_API_KEY",
                authDomain: "YOUR_AUTH_DOMAIN",
                projectId: "YOUR_PROJECT_ID",
                storageBucket: "YOUR_STORAGE_BUCKET",
                messagingSenderId: "YOUR_MESSAGING_SENDER_ID",
                appId: "YOUR_APP_ID"
            },
            title: 'Customer Support',
            placeholder: 'Type your message...',
            apiUrl: "https://your-api-endpoint.com"
        });
    </script>
</body>
</html>
```

#### Step 2: Programmatic Control (Optional)

```javascript
// Initialize and store the widget instance
const widget = ChatWidgetSDK.initChatWidget({
    firebaseConfig: { /* ... */ },
    title: 'Help Center'
});

// Later, remove the widget if needed
widget.unmount();
```

---

### Option 2: React Component

Ideal for React applications or Next.js projects.

#### Step 1: Install from GitHub Packages

First, configure npm to use GitHub Packages. Create or edit `.npmrc` in your project root:

```ini
@onionshack:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN
```

> **Note**: Generate a GitHub Personal Access Token with `read:packages` scope at https://github.com/settings/tokens

Then install the package:

```bash
npm install @onionshack/ocpb-chatbox-sdk
```

#### Step 2: Import and Use in Your React App

```jsx
import ChatWidget from '@onionshack/ocpb-chatbox-sdk';
import '@onionshack/ocpb-chatbox-sdk/dist/style.css'; // Import styles

export default function App() {
  return (
    <div>
      {/* Your app content */}
      <h1>My React App</h1>

      {/* Chat widget will appear as a floating button */}
      <ChatWidget
        title="Support Chat"
        placeholder="Ask us anything..."
        firebaseConfig={{
          apiKey: process.env.REACT_APP_FIREBASE_API_KEY,
          authDomain: process.env.REACT_APP_FIREBASE_AUTH_DOMAIN,
          projectId: process.env.REACT_APP_FIREBASE_PROJECT_ID,
          storageBucket: process.env.REACT_APP_FIREBASE_STORAGE_BUCKET,
          messagingSenderId: process.env.REACT_APP_FIREBASE_MESSAGING_SENDER_ID,
          appId: process.env.REACT_APP_FIREBASE_APP_ID
        }}
        apiUrl="https://your-api-endpoint.com"
      />
    </div>
  );
}
```

---

## Configuration

### Required Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `firebaseConfig` | `object` | Firebase configuration object (required) |
| `firebaseConfig.apiKey` | `string` | Firebase API key |
| `firebaseConfig.authDomain` | `string` | Firebase auth domain |
| `firebaseConfig.projectId` | `string` | Firebase project ID |
| `firebaseConfig.storageBucket` | `string` | Firebase storage bucket |
| `firebaseConfig.messagingSenderId` | `string` | Firebase messaging sender ID |
| `firebaseConfig.appId` | `string` | Firebase app ID |

### Optional Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `title` | `string` | `'Chat'` | Chat widget header title |
| `placeholder` | `string` | `'Type your message…'` | Input field placeholder text |
| `apiUrl` | `string` | `'http://localhost:3000'` | REST API and WebSocket endpoint for chat backend |
| `fullScreen` | `boolean` | `false` | Enable full-screen mode (no floating button, always open) |
| `containerId` | `string` | `'chat-widget-root'` | DOM element ID to mount into (JS only) |

### Configuration Examples

```javascript
ChatWidgetSDK.initChatWidget({
    firebaseConfig: {
        apiKey: "AIza...",
        authDomain: "myapp.firebaseapp.com",
        projectId: "myapp",
        storageBucket: "myapp.appspot.com",
        messagingSenderId: "123456",
        appId: "1:123456:web:abc123"
    },
    title: 'Customer Support',
    placeholder: 'How can we help you?',
    apiUrl: 'https://api.myapp.com',
    containerId: 'custom-chat-container',
    fullScreen: true  // No floating button, always visible
});
```

---

## Installation

### For Contributors / Development

```bash
# Clone the repository
git clone https://github.com/onionshack/ocpb-chatbot-widget-next.git
cd ocpb-chatbot-widget-next

# Install dependencies
npm install

# Start development server
npm run dev
```