🚀 ContentPulse Chat SDK

An advanced React SDK for integrating ContentPulse AI Chat Agent with extensive customization options, beautiful themes, and seamless Contentstack CMS integration.

✨ Features

• 🎨 Advanced Theming - Highly customizable visual configurations
• 🤖 Multi-LLM Support - OpenAI, Anthropic, Perplexity integration
• 📱 Responsive Design - Mobile-friendly chat interface
• 🔗 Contentstack Integration - CMS content retrieval via MCP
• 🛡️ TypeScript - Full type safety and IntelliSense
• 🎭 Animations - Smooth Framer Motion animations

📦 Installation

npm install @contentpulse/chat-sdk

🚀 Quick Start

import { ContentPulseProvider, ChatAgent } from '@contentpulse/chat-sdk';

function App() {
  return (
    <ContentPulseProvider
      agentId="your-agent-id"
      apiBaseUrl="https://your-contentpulse-api.com/api"
      apiKey="your-api-key"
      // LLM Configuration (optional - can be managed in backend)
      llmProvider="openai"
      llmModel="gpt-4"
      llmApiKey="your-openai-key"
      // Contentstack Configuration  
      contentstackApiKey="your-cs-api-key"
      contentstackDeliveryToken="your-cs-delivery-token"
      contentType="articles"
    >
      <ChatAgent 
        title="ContentPulse AI" 
        subtitle="How can I help you today?"
      />
    </ContentPulseProvider>
  );
}

🎨 Advanced Theme Customization

The SDK offers extensive theming capabilities that go far beyond basic color changes:

<ContentPulseProvider
  agentId="your-agent-id"
  // ... other props
  visualConfig={{
    // Layout & Positioning
    layout: {
      position: 'bottom-right',
      spacing: { bottom: '24px', right: '24px' },
      zIndex: 9999,
    },
    
    // Trigger Button Styling
    trigger: {
      size: 'large',
      shape: 'circle',
      backgroundColor: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
      hoverEffect: 'glow',
      icon: '🤖',
    },
    
    // Chat Window Styling
    window: {
      width: '450px',
      height: '650px',
      borderRadius: '24px',
      backgroundColor: '#ffffff',
      backdropBlur: '10px',
      boxShadow: '0 20px 60px rgba(0, 0, 0, 0.15)',
      animation: 'scale',
    },
    
    // Header Styling
    header: {
      backgroundColor: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
      textColor: '#ffffff',
    },
    
    // Message Styling
    userMessage: {
      backgroundColor: '#ffffff',
      textColor: '#2d3748',
      borderRadius: '18px 18px 6px 18px',
      boxShadow: '0 2px 8px rgba(0, 0, 0, 0.1)',
    },
    
    assistantMessage: {
      backgroundColor: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
      textColor: '#ffffff',
      borderRadius: '18px 18px 18px 6px',
    },
    
    // Avatar Styling
    avatars: {
      size: '40px',
      user: {
        backgroundColor: 'linear-gradient(135deg, #ffecd2 0%, #fcb69f 100%)',
        icon: '👤',
      },
      assistant: {
        backgroundColor: 'linear-gradient(135deg, #a8edea 0%, #fed6e3 100%)',
        icon: '🤖',
      },
    },
    
    // Typography
    typography: {
      fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
      fontSize: { medium: '14px' },
      lineHeight: '1.5',
    },
    
    // Custom CSS
    customCSS: `
      .cp-trigger-button:hover {
        transform: rotate(10deg) scale(1.1);
      }
    `,
  }}
>
  <ChatAgent />
</ContentPulseProvider>

⚙️ Configuration Options

ContentPulseProvider Props

| Prop | Type | Required | Description | |------|------|----------|-------------| | agentId | string | ✅ | Unique identifier for your chat agent | | apiBaseUrl | string | ❌ | ContentPulse API base URL (defaults to localhost:3000 in dev) | | apiKey | string | ❌ | API key for ContentPulse backend authentication | | llmProvider | 'openai' | 'anthropic' | 'perplexity' | ❌ | LLM provider (can override backend settings) | | llmModel | string | ❌ | Model name (e.g., 'gpt-4', 'claude-3-sonnet') | | llmApiKey | string | ❌ | LLM provider API key | | contentstackApiKey | string | ❌ | Contentstack CMS API key | | contentstackDeliveryToken | string | ❌ | Contentstack delivery token | | contentstackEnvironment | string | ❌ | Environment (default: 'development') | | contentstackRegion | 'US' | 'EU' | 'AZURE_NA' | 'AZURE_EU' | 'GCP_NA' | ❌ | Contentstack region | | contentType | string | ❌ | Contentstack content type for queries | | enableStreaming | boolean | ❌ | Enable real-time response streaming (default: true) | | enableToolCalls | boolean | ❌ | Enable MCP tool calls (default: true) | | maxTokens | number | ❌ | Maximum tokens for responses | | temperature | number | ❌ | LLM temperature (0-1) | | sessionId | string | ❌ | Session identifier for conversation tracking | | enableAuthentication | boolean | ❌ | Enable user authentication | | visualConfig | AdvancedThemeConfig | ❌ | Advanced theme configuration |

ChatAgent Props

| Prop | Type | Required | Description | |------|------|----------|-------------| | title | string | ❌ | Chat window title (default: "ContentPulse AI") | | subtitle | string | ❌ | Subtitle/status text | | placeholder | string | ❌ | Input placeholder text | | welcomeMessage | string | ❌ | Initial welcome message | | autoOpen | boolean | ❌ | Auto-open chat on load | | enableMinimize | boolean | ❌ | Show minimize button (default: true) | | enableClose | boolean | ❌ | Show close button (default: true) | | enableClearHistory | boolean | ❌ | Enable clear chat history (default: true) | | enableExport | boolean | ❌ | Enable chat export functionality | | onMessageSent | (message: string) => void | ❌ | Callback when user sends message | | onMessageReceived | (message: ChatMessage) => void | ❌ | Callback when assistant responds | | onError | (error: Error) => void | ❌ | Error handling callback | | onOpen | () => void | ❌ | Chat window opened callback | | onClose | () => void | ❌ | Chat window closed callback |

🎭 Theme Presets

Modern Gradient Theme

const modernTheme = {
  trigger: {
    backgroundColor: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
    hoverEffect: 'glow',
  },
  window: {
    backgroundColor: '#ffffff',
    borderRadius: '24px',
    boxShadow: '0 20px 60px rgba(0, 0, 0, 0.15)',
  },
  assistantMessage: {
    backgroundColor: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
    textColor: '#ffffff',
  },
};

Dark Theme

const darkTheme = {
  window: {
    backgroundColor: '#1a202c',
    borderRadius: '16px',
  },
  header: {
    backgroundColor: '#2d3748',
    textColor: '#ffffff',
  },
  messages: {
    backgroundColor: '#2d3748',
  },
  userMessage: {
    backgroundColor: '#4a5568',
    textColor: '#ffffff',
  },
  assistantMessage: {
    backgroundColor: '#3182ce',
    textColor: '#ffffff',
  },
};

Minimal Theme

const minimalTheme = {
  trigger: {
    backgroundColor: '#f7fafc',
    borderColor: '#e2e8f0',
    shape: 'rounded',
    icon: '💬',
  },
  window: {
    backgroundColor: '#ffffff',
    borderRadius: '12px',
    border: '1px solid #e2e8f0',
  },
  userMessage: {
    backgroundColor: '#f7fafc',
    textColor: '#2d3748',
    borderRadius: '12px',
  },
  assistantMessage: {
    backgroundColor: '#edf2f7',
    textColor: '#2d3748',
    borderRadius: '12px',
  },
};

🔧 Advanced Usage

Using the Hook Directly

import { useChatAgent, useContentPulse } from '@contentpulse/chat-sdk';

function CustomChatInterface() {
  const { config, theme, isConnected } = useContentPulse();
  const { 
    messages, 
    sendMessage, 
    isLoading, 
    clearMessages,
    exportChat 
  } = useChatAgent();

  return (
    <div>
      {messages.map(message => (
        <div key={message.id}>
          <strong>{message.role}:</strong> {message.content}
        </div>
      ))}
      
      <input 
        onKeyDown={e => e.key === 'Enter' && sendMessage(e.target.value)}
        disabled={!isConnected || isLoading}
      />
    </div>
  );
}

The SDK is fully responsive and includes mobile-optimized defaults:

visualConfig={{
  window: {
    width: '420px',
    maxWidth: '95vw',
    height: '600px',
    maxHeight: '80vh',
  },
  layout: {
    position: 'bottom-right',
    spacing: { bottom: '24px', right: '16px' },
  },
}}

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

📄 License

MIT License - see LICENSE file for details.

🆘 Support

• 📧 Email: [email protected]
• 🐛 Issues: GitHub Issues

Made with ❤️ by the Hemant Kadam