@rockship/chatbot-sdk

v1.4.1

Published

8 months ago

Modern, customizable chatbot SDK with extensive React integration, responsive UI, and real-time messaging for web applications

0High
0Medium
0Low

rockship

chatbot sdk chat widget rockship react-component typescript customer-support ai-chatbot customizable-ui react nextjs

🚀 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)

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:

<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):

<!-- 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 for detailed CDN integration examples.

🚀 Quick Start

React/Next.js

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):

<!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):

<!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:

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

Complete Configuration Options

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

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

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

chatbot.init();

With Branding

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

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

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:

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:

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:

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

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

🏗️ Component Architecture

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:

// 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:

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:

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:

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:

// 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

/* 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

--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

--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

--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

--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

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

// 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

# 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: [email protected]
🌐 Website: https://rockship.co
📖 Documentation: https://docs.rockship.co
🐛 Issues: https://github.com/rockship/sdk/issues

Made with ❤️ by Rockship