npm package: @hemantkadam/contentpulse-chat-sdk
Description: Advanced React SDK for integrating ContentPulse AI Chat Agent with customizable themes and configurations
Author: ContentPulse Team
Latest version: 1.0.0

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

```bash
npm install @contentpulse/chat-sdk
```

## 🚀 Quick Start

```tsx
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:

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

```tsx
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:

```tsx
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](CONTRIBUTING.md) for details.

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

## 🆘 Support

- 📧 Email: support@contentpulse.dev
- 🐛 Issues: [GitHub Issues](https://github.com/hemant-i7/ContentPulse)

---

Made with ❤️ by the Hemant Kadam