npm package: @rockship/chatbot-sdk
Description: Modern, customizable chatbot SDK with extensive React integration, responsive UI, and real-time messaging for web applications
Author: Rockship Team
Latest version: 1.4.1

# 🚀 Rockship Chatbot SDK

A modern, production-ready chatbot SDK for React and JavaScript applications. Built with TypeScript, featuring Shadow DOM isolation, real-time streaming, and a hybrid minimalism design system.

## ✨ Features

- 🛡️ **Shadow DOM** - Complete style isolation prevents conflicts with host website CSS
- 🎨 **Hybrid Minimalism Design** - Organic UI inspired by Supabase, shadcn/ui, and Linear
- 🔧 **TypeScript** - Full type safety with comprehensive type definitions
- 📱 **Responsive** - Perfect on desktop, tablet, and mobile (fullscreen on mobile)
- 🌊 **Real-time Streaming** - Live message streaming with Server-Sent Events (SSE)
- 🎯 **Lucide Icons** - Modern, consistent iconography throughout
- ♿ **Accessible** - WCAG 2.1 Level AA compliant with keyboard navigation
- 🎨 **Customizable** - Custom colors, logos, styles, and positioning
- � **Zero Config** - Works out of the box with sensible defaults

## 📦 Installation

### NPM (Recommended for React/Next.js projects)

```bash
npm install @rockship/chatbot-sdk
# or
pnpm add @rockship/chatbot-sdk
# or
yarn add @rockship/chatbot-sdk
```

### CDN (For simple HTML websites)

**Standalone Version (Recommended)** - Includes React, no dependencies required:

```html
<script src="https://unpkg.com/@rockship/chatbot-sdk/dist/rockship-chatbot.standalone.umd.js"></script>
```

**Regular Version** - Requires React to be loaded separately (use if your site already has React):

```html
<!-- Load React first -->
<script crossorigin src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
<script crossorigin src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>
<script>
  window.process = { env: { NODE_ENV: "production" } };
  window.ReactDOMClient = {
    createRoot: ReactDOM.createRoot,
    hydrateRoot: ReactDOM.hydrateRoot,
  };
</script>

<!-- Then load the SDK -->
<script src="https://unpkg.com/@rockship/chatbot-sdk/dist/rockship-chatbot.umd.js"></script>
```

> **📝 Note:** CSS is automatically injected via Shadow DOM. No separate stylesheet needed!
>
> **💡 Which version?**
> - Use **standalone** for simple HTML websites (easier setup, ~124 KB gzipped)
> - Use **regular** if your site already uses React (smaller, ~65 KB gzipped)
>
> See [CDN_USAGE.md](./CDN_USAGE.md) for detailed CDN integration examples.

## 🚀 Quick Start

### React/Next.js

```typescript
import { RockshipChatbotSDK } from '@rockship/chatbot-sdk';

const chatbot = new RockshipChatbotSDK({
  apiBaseUrl: 'https://your-api.com',
  apiToken: 'your-api-token',
  assistant: {
    name: 'Support Agent'
  },
  welcomeMessages: [
    'Welcome! 👋',
    'How can we help you today?'
  ]
});

chatbot.init();
```

### Vanilla JavaScript (CDN)

**Using Standalone Version (No React Required):**

```html
<!DOCTYPE html>
<html>
<body>
  <!-- Just one script tag - that's it! -->
  <script src="https://unpkg.com/@rockship/chatbot-sdk/dist/rockship-chatbot.standalone.umd.js"></script>
  <script>
    const chatbot = new RockshipChatbotSDK({
      apiBaseUrl: 'https://your-api.com',
      apiToken: 'your-api-token'
    });
    chatbot.init();
  </script>
</body>
</html>
```

**Using Regular Version (React Already Loaded):**

```html
<!DOCTYPE html>
<html>
<body>
  <!-- Load React -->
  <script crossorigin src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
  <script crossorigin src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>
  <script>
    window.process = { env: { NODE_ENV: "production" } };
    window.ReactDOMClient = {
      createRoot: ReactDOM.createRoot,
      hydrateRoot: ReactDOM.hydrateRoot,
    };
  </script>

  <!-- Load SDK -->
  <script src="https://unpkg.com/@rockship/chatbot-sdk/dist/rockship-chatbot.umd.js"></script>
  <script>
    const chatbot = new RockshipChatbotSDK({
      apiBaseUrl: 'https://your-api.com',
      apiToken: 'your-api-token'
    });
    chatbot.init();
  </script>
</body>
</html>
```

## ⚙️ Configuration

### Required Configuration

Only 2 fields are required:

```typescript
{
  apiBaseUrl: string;  // Your API endpoint
  apiToken: string;    // Authentication token
}
```

### Complete Configuration Options

```typescript
interface ChatbotConfig {
  // REQUIRED
  apiBaseUrl: string;           // Your API endpoint
  apiToken: string;             // Authentication token

  // OPTIONAL - User Configuration
  user?: {
    id?: string;                // Auto-generated if not provided
    name?: string;              // Auto-generated if not provided
  };

  // OPTIONAL - Assistant Configuration
  assistant?: {
    name?: string;              // Default: 'Assistant'
  };

  // OPTIONAL - Content & Branding
  welcomeMessages?: string[];   // Initial greeting messages
  brandLogoUrl?: string;        // Logo URL (shows in header & messages)
  quickReplies?: string[];      // Quick reply buttons

  // OPTIONAL - UI Configuration
  ui?: {
    toggle?: {
      icon?: string;            // Custom toggle button image URL
    };
    message?: {
      hideName?: boolean;       // Hide agent/user names (default: false)
      hideTimestamp?: boolean;  // Hide timestamps (default: false)
    };
    input?: {
      placeholder?: string;     // Input placeholder text
    };
    primaryColor?: string;      // Theme color (e.g., '#1e90ff')
  };
}
```

### SDK Initialization Options

```typescript
interface SDKOptions {
  container?: string | HTMLElement;  // Default: auto-created in body
  debug?: boolean;                   // Enable debug logging
  onError?: (error: Error) => void;  // Error callback
  autoInit?: boolean;                // Auto-initialize (default: false)
  customCSS?: string;                // Custom CSS for Shadow DOM
}

// Usage:
const chatbot = new RockshipChatbotSDK(config, options);
```

## 📋 Basic Examples

### Minimal Setup

```typescript
const chatbot = new RockshipChatbotSDK({
  apiBaseUrl: 'https://api.example.com',
  apiToken: 'token_abc123'
});

chatbot.init();
```

### With Branding

```typescript
const chatbot = new RockshipChatbotSDK({
  apiBaseUrl: 'https://api.example.com',
  apiToken: 'token_abc123',
  assistant: {
    name: 'Support Team'
  },
  brandLogoUrl: 'https://example.com/logo.png',
  welcomeMessages: [
    'Welcome to Example Corp! 👋',
    'How can we help you today?'
  ]
});

chatbot.init();
```

### With Custom Theme

```typescript
const chatbot = new RockshipChatbotSDK({
  apiBaseUrl: 'https://api.example.com',
  apiToken: 'token_abc123',
  ui: {
    primaryColor: '#7c3aed',  // Purple theme
    toggle: {
      icon: 'https://example.com/chat-icon.png'
    },
    message: {
      hideName: false
    },
    input: {
      placeholder: 'Type your message...'
    }
  }
});

chatbot.init();
```

### With Custom Positioning

```typescript
const chatbot = new RockshipChatbotSDK({
  apiBaseUrl: 'https://api.example.com',
  apiToken: 'token_abc123'
}, {
  customCSS: `
    .chat-toggle-container {
      bottom: 20px !important;
      left: 20px !important;
    }
  `
});

chatbot.init();
```

## 🎨 UI Customization

### Primary Color Theme

Customize the theme by providing a primary color. The SDK automatically generates a complete color palette:

```typescript
const chatbot = new RockshipChatbotSDK({
  apiBaseUrl: 'https://api.example.com',
  apiToken: 'token_abc123',
  ui: {
    primaryColor: '#10b981'  // Green theme
  }
});
```

**Color Palette Generated:**
- `primary-100` - Lightest (backgrounds)
- `primary-200` - Lighter
- `primary-300` - Light (borders, accents)
- `primary-400` - Base (your color)
- `primary-500` - Dark (hover states)
- `primary-600` - Darkest (active states)

### Custom Toggle Button

Replace the default chat icon with your own image:

```typescript
const chatbot = new RockshipChatbotSDK({
  apiBaseUrl: 'https://api.example.com',
  apiToken: 'token_abc123',
  ui: {
    toggle: {
      icon: 'https://example.com/custom-chat-icon.png'
    }
  }
});
```

### Custom Positioning

Position the toggle button anywhere on screen using custom CSS:

```typescript
const chatbot = new RockshipChatbotSDK({
  apiBaseUrl: 'https://api.example.com',
  apiToken: 'token_abc123'
}, {
  customCSS: `
    /* Bottom left */
    .chat-toggle-container {
      bottom: 20px !important;
      left: 20px !important;
      right: auto !important;
    }

    /* Top right */
    .chat-toggle-container {
      top: 20px !important;
      bottom: auto !important;
      right: 20px !important;
    }

    /* Custom window size */
    .chat-window {
      width: 400px !important;
      height: 600px !important;
    }
  `
});
```

### Hide User/Agent Names

```typescript
const chatbot = new RockshipChatbotSDK({
  apiBaseUrl: 'https://api.example.com',
  apiToken: 'token_abc123',
  ui: {
    message: {
      hideName: true,
      hideTimestamp: true
    }
  }
});
```

## 🏗️ Component Architecture

```plaintext
ChatWidget (Root)
│
├── ChatToggle (Floating Button)
│   ├── Custom Image OR MessageCircle Icon
│   └── X Icon (when open)
│
└── ChatWindow (Modal Popup)
    │
    ├── ChatHeader
    │   ├── Brand Logo (optional)
    │   ├── Title
    │   ├── Zoom Button (Maximize2 → Minimize2)
    │   ├── Clear Button (Trash2)
    │   └── Close Button (X)
    │
    ├── ChatMain (Message Container)
    │   ├── Welcome Messages (initial)
    │   ├── ChatMessage (repeated)
    │   │   ├── Name Label (optional)
    │   │   ├── Content (markdown for bot, text for user)
    │   │   └── Timestamp (optional)
    │   ├── Loading Indicator (3 animated dots)
    │   └── Scroll Button (ChevronDown)
    │
    └── ChatFooter
        ├── Quick Replies (button group)
        ├── ChatInput (auto-resize textarea)
        └── ChatSend Button (Send icon)
```

## 🎯 Features

### Shadow DOM Isolation

All styles are injected into Shadow DOM for complete isolation:

```typescript
// CSS is automatically injected - no manual stylesheet needed
const chatbot = new RockshipChatbotSDK({
  apiBaseUrl: 'https://api.example.com',
  apiToken: 'token_abc123'
});

// Add custom styles via customCSS option
const chatbot = new RockshipChatbotSDK({
  apiBaseUrl: 'https://api.example.com',
  apiToken: 'token_abc123'
}, {
  customCSS: `
    .chat-window {
      border-radius: 20px !important;
    }
  `
});
```

**Benefits:**
- ✅ Zero style conflicts with host website
- ✅ Consistent appearance across all sites
- ✅ No CSS specificity battles
- ✅ Host site styles cannot break widget

### Real-time Streaming

Messages stream in real-time using Server-Sent Events (SSE):

- Progressive text display (word by word)
- Smooth typing animation
- Low latency responses
- Automatic reconnection on errors

### Welcome Messages

Display greeting messages when chat first opens:

```typescript
const chatbot = new RockshipChatbotSDK({
  apiBaseUrl: 'https://api.example.com',
  apiToken: 'token_abc123',
  welcomeMessages: [
    'Hi there! 👋',
    'Welcome to our support chat.',
    'How can we assist you today?'
  ]
});
```

### Quick Replies

Pre-defined messages users can send with one click:

```typescript
const chatbot = new RockshipChatbotSDK({
  apiBaseUrl: 'https://api.example.com',
  apiToken: 'token_abc123',
  quickReplies: [
    'I need help with my order',
    'How do I reset my password?',
    'Talk to a human agent'
  ]
});
```

### Brand Logo

Logo appears in header and next to assistant messages:

```typescript
const chatbot = new RockshipChatbotSDK({
  apiBaseUrl: 'https://api.example.com',
  apiToken: 'token_abc123',
  brandLogoUrl: 'https://example.com/logo.png',
  assistant: {
    name: 'Support Team'
  }
});
```

### Zoom Mode

Click zoom button to expand window to 85% of screen:

- Desktop: 85vw × 85vh centered
- Mobile: Fullscreen (100vw × 100vh)
- Toggle between normal and zoomed

### Markdown Support

Assistant messages support full markdown:

- **Bold** and *italic* text
- `Inline code` and code blocks
- Links with hover effects
- Lists (ordered and unordered)
- Headings (h1-h6)
- Blockquotes
- Tables
- Images

### Auto-resize Input

Text input automatically grows with content:

- Min height: 44px
- Max height: 120px
- Smooth transitions
- Enter to send, Shift+Enter for new line

### Keyboard Shortcuts

- `Enter` - Send message
- `Shift + Enter` - New line
- `Esc` - Close chat window

### Scroll Behavior

- Auto-scroll to latest message
- Scroll-to-bottom button when scrolled up
- Smooth scroll animations

### Clear Conversation

- Instant UI clear (no confirmation)
- Clears session storage
- Shows welcome messages
- API deletion in background

### User Identification

Automatic user ID generation and persistence:

```typescript
// Auto-generated and stored in localStorage
user: {
  id: 'user_abc123',      // Auto-generated UUID
  name: 'User ABC123'     // Auto-generated from ID
}

// Or provide your own
const chatbot = new RockshipChatbotSDK({
  apiBaseUrl: 'https://api.example.com',
  apiToken: 'token_abc123',
  user: {
    id: 'customer_12345',
    name: 'John Doe'
  }
});
```

## 🎭 Design System

The SDK uses a **Hybrid Minimalism × Organic UI** design system with CSS custom properties.

### Color Variables

```css
/* Neutral grays with warmth */
--rs-gray-50: #fafaf9;
--rs-gray-100: #f5f5f3;
--rs-gray-200: #e7e5e4;
--rs-gray-300: #d6d3d1;
--rs-gray-400: #a8a29e;
--rs-gray-500: #78716c;
--rs-gray-600: #57534e;
--rs-gray-700: #44403c;
--rs-gray-800: #292524;
--rs-gray-900: #1c1917;

/* Primary colors (default dodger blue) */
--rs-primary-100: #e0f2ff;
--rs-primary-200: #b3dcff;
--rs-primary-300: #66b3ff;
--rs-primary-400: #1e90ff;  /* Base */
--rs-primary-500: #1a7dd9;
--rs-primary-600: #1566b3;

/* Surfaces */
--rs-surface-base: #fafaf9;
--rs-surface-elevated: #ffffff;
--rs-surface-subtle: #f5f5f3;
```

### Spacing Scale

```css
--rs-spacing-1: 0.25rem;  /* 4px */
--rs-spacing-2: 0.5rem;   /* 8px */
--rs-spacing-3: 0.75rem;  /* 12px */
--rs-spacing-4: 1rem;     /* 16px */
--rs-spacing-5: 1.25rem;  /* 20px */
--rs-spacing-6: 1.5rem;   /* 24px */
--rs-spacing-8: 2rem;     /* 32px */
--rs-spacing-10: 2.5rem;  /* 40px */
```

### Border Radius

```css
--rs-rounded-sm: 0.375rem;   /* 6px */
--rs-rounded: 0.5rem;        /* 8px */
--rs-rounded-md: 0.625rem;   /* 10px */
--rs-rounded-lg: 0.75rem;    /* 12px */
--rs-rounded-xl: 1rem;       /* 16px */
--rs-rounded-2xl: 1.25rem;   /* 20px */
--rs-rounded-3xl: 1.5rem;    /* 24px */
--rs-rounded-full: 9999px;
```

### Typography

```css
--rs-font-sans: "Inter", "SF Pro Display", -apple-system, system-ui;

--rs-text-xs: 0.75rem;    /* 12px */
--rs-text-sm: 0.875rem;   /* 14px */
--rs-text-base: 1rem;     /* 16px */
--rs-text-lg: 1.125rem;   /* 18px */
--rs-text-xl: 1.25rem;    /* 20px */

--rs-font-normal: 400;
--rs-font-medium: 500;
--rs-font-semibold: 600;
--rs-font-bold: 700;
```

### Shadows

```css
--rs-shadow-xs: 0 1px 2px rgba(0, 0, 0, 0.04);
--rs-shadow-sm: 0 1px 3px rgba(0, 0, 0, 0.06), 0 1px 2px rgba(0, 0, 0, 0.04);
--rs-shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.06), 0 2px 4px -1px rgba(0, 0, 0, 0.04);
--rs-shadow-lg: 0 10px 15px -3px rgba(0, 0, 0, 0.08), 0 4px 6px -2px rgba(0, 0, 0, 0.04);
--rs-shadow-xl: 0 20px 25px -5px rgba(0, 0, 0, 0.08), 0 10px 10px -5px rgba(0, 0, 0, 0.03);
```

## 📱 Responsive Design

### Desktop (default)

- Window: 380px × 500px
- Position: Bottom right (24px from edges)
- Zoom: 85vw × 85vh centered
- Bot messages: 100% width (80% when zoomed)
- User messages: 80% width always

### Mobile (< 640px)

- Window: Fullscreen (100vw × 100vh)
- No toggle teaser (hidden)
- Bot messages: 100% width always
- User messages: 80% width always
- Zoom button hidden

## 🔌 SDK API Methods

```typescript
const chatbot = new RockshipChatbotSDK(config, options);

// Initialize the chatbot
await chatbot.init();

// Control visibility
chatbot.open();
chatbot.close();
chatbot.toggle();

// Event listeners
chatbot.on('open', () => console.log('Chat opened'));
chatbot.on('close', () => console.log('Chat closed'));
chatbot.on('message', (data) => console.log('New message:', data));
chatbot.on('ready', () => console.log('Chat ready'));
chatbot.on('error', (error) => console.error('Chat error:', error));

// Cleanup
chatbot.destroy();
```

## ♿ Accessibility

- ✅ WCAG 2.1 Level AA compliant
- ✅ Keyboard navigation (Tab, Enter, Esc)
- ✅ Focus indicators on all interactive elements
- ✅ ARIA labels and roles
- ✅ Screen reader support
- ✅ Reduced motion support (`prefers-reduced-motion`)
- ✅ High contrast mode support (`prefers-contrast`)

## 🌐 Browser Support

| Browser | Minimum Version |
|---------|----------------|
| Chrome  | 53+ (Shadow DOM) |
| Firefox | 63+ |
| Safari  | 10+ |
| Edge    | 79+ |
| Opera   | 40+ |

**Requirements:**
- Shadow DOM support (Chrome 53+, Firefox 63+, Safari 10+)
- ES6+ JavaScript support
- Server-Sent Events (SSE) for streaming

## 📦 Package Exports

```typescript
// Main SDK class
import { RockshipChatbotSDK } from '@rockship/chatbot-sdk';

// Types
import type {
  ChatbotConfig,
  UIConfig,
  SDKOptions
} from '@rockship/chatbot-sdk';

// Components (for advanced use)
import {
  ShadowDOMWrapper,
  ChatZoom,
  ChatClear,
  ChatClose,
  ChatSend,
  ChatInput,
  ChatScroll,
  ChatTeaser
} from '@rockship/chatbot-sdk';

// Icons (Lucide React)
import {
  MessageCircle,
  X,
  Send,
  Trash2,
  Maximize2,
  Minimize2,
  ChevronDown
} from '@rockship/chatbot-sdk';
```

## 🛠️ Development

```bash
# Install dependencies
pnpm install

# Start dev server with example
pnpm dev

# Type checking
pnpm typecheck

# Build for production
pnpm build

# Generate CSS bundle
pnpm css:generate
```

## 📄 License

MIT © Rockship

## 🆘 Support

- 📧 Email: support@rockship.co
- 🌐 Website: https://rockship.co
- 📖 Documentation: https://docs.rockship.co
- 🐛 Issues: https://github.com/rockship/sdk/issues

---

Made with ❤️ by [Rockship](https://rockship.co)