npm package: @soaal/rag-reactjs-sdk
Description: Beautiful, customizable chat widget SDK for React and Next.js with RAG integration, RTL support, and 13+ themes
Author: Soaal
Latest version: 0.0.6

# Light RAG React/Next.js SDK

A TypeScript SDK for integrating Light RAG API into React and Next.js applications. This SDK provides a simple interface for creating chat conversations, sending messages, and managing chat history using session-based authentication.

## Installation

```bash
npm install @soaal/rag-reactjs-sdk
# or
yarn add @soaal/rag-reactjs-sdk
# or
pnpm add @soaal/rag-reactjs-sdk
```

## Quick Start

### Using the Pre-built Widget (Recommended)

The easiest way to get started is using the pre-built `ChatWidget` component:

```tsx
'use client';

import { ChatWidget } from '@soaal/rag-reactjs-sdk';

export default function ChatPage() {
  return (
    <div style={{ width: '500px', height: '700px' }}>
      <ChatWidget
        apiKey={process.env.NEXT_PUBLIC_RAG_API_KEY!}
        title="Customer Support"
      />
    </div>
  );
}
```

### Customizing the Widget

The widget is highly customizable:

```tsx
<ChatWidget
  apiKey="your-api-key"
  title="Support Chat"
  theme={{
    primaryColor: '#6366f1',
    userMessageColor: '#6366f1',
    assistantMessageColor: '#f3f4f6',
    borderRadius: '12px',
  }}
  showAvatar={true}
  showTimestamp={true}
  placeholder="Ask me anything..."
  onMessageSent={(message) => console.log('Sent:', message)}
  onMessageReceived={(response) => console.log('Received:', response)}
/>
```

### Basic Usage with React Hook

```tsx
'use client';

import { useLightRAG } from '@soaal/rag-reactjs-sdk';

function ChatWidget() {
  const { messages, sendMessage, sending, error } = useLightRAG({
    apiKey: 'your-public-api-key',
    baseUrl: 'https://your-api-domain.com/api/v1', // Optional
    autoCreateChat: true, // Automatically create a chat on mount
  });

  const [input, setInput] = useState('');

  return (
    <div className="chat-widget">
      {error && (
        <div className="error">
          Error: {error.message}
        </div>
      )}
      
      <div className="messages">
        {messages.map((msg) => (
          <div key={msg.id} className={`message ${msg.role}`}>
            {msg.content}
          </div>
        ))}
      </div>

      <form
        onSubmit={(e) => {
          e.preventDefault();
          sendMessage(input);
          setInput('');
        }}
      >
        <input
          value={input}
          onChange={(e) => setInput(e.target.value)}
          placeholder="Type your message..."
          disabled={sending}
        />
        <button type="submit" disabled={sending}>
          {sending ? 'Sending...' : 'Send'}
        </button>
      </form>
    </div>
  );
}
```

### Usage with SDK Class

```typescript
import { LightRAGSDK } from '@soaal/rag-reactjs-sdk';

const sdk = new LightRAGSDK({
  apiKey: 'your-public-api-key',
  baseUrl: 'https://your-api-domain.com/api/v1', // Optional
});

// Create a chat
const chatId = await sdk.createChat('Customer Support');

// Send a message
const response = await sdk.sendMessage(chatId, 'What are your business hours?');
console.log('AI Response:', response);

// Get chat history
const messages = await sdk.getChatMessages(chatId);
console.log('Chat History:', messages);
```

## API Reference

### `ChatWidget`

A fully customizable, ready-to-use chat widget component.

#### Props

```typescript
interface ChatWidgetProps {
  // Required
  apiKey: string;
  
  // Display options
  title?: string;                    // Widget title
  placeholder?: string;              // Input placeholder
  showHeader?: boolean;              // Show header (default: true)
  showFooter?: boolean;              // Show footer (default: false)
  showErrorBanner?: boolean;         // Show error banner (default: true)
  showTimestamp?: boolean;           // Show message timestamps (default: false)
  showAvatar?: boolean;              // Show avatars (default: false)
  userAvatar?: string | ReactNode;   // Custom user avatar
  assistantAvatar?: string | ReactNode; // Custom assistant avatar
  
  // Behavior
  autoScroll?: boolean;              // Auto-scroll to bottom (default: true)
  scrollBehavior?: 'smooth' | 'auto';
  maxHeight?: string;                // Max height of messages area
  minHeight?: string;                // Min height of messages area
  
  // Styling
  className?: string;                // Root container class
  containerClassName?: string;       // Input container class
  messagesClassName?: string;        // Messages container class
  inputClassName?: string;          // Input field class
  buttonClassName?: string;          // Send button class
  headerClassName?: string;         // Header class
  footerClassName?: string;         // Footer class
  messageClassName?: string;        // Message wrapper class
  userMessageClassName?: string;    // User message class
  assistantMessageClassName?: string; // Assistant message class
  
  // Theme
  theme?: ChatWidgetTheme;          // Theme configuration
  
  // Custom renderers
  renderers?: ChatWidgetRenderers;   // Custom render functions
  
  // Callbacks
  onMessageSent?: (message: string) => void;
  onMessageReceived?: (response: string) => void;
  onChatCreated?: (chatId: string) => void;
  
  // Input options
  inputMaxLength?: number;           // Max input length
  inputRows?: number;                // Rows for multiline (default: 1)
  multiline?: boolean;               // Enable multiline input (default: false)
  sendOnEnter?: boolean;             // Send on Enter (default: true)
  sendOnShiftEnter?: boolean;        // Send on Shift+Enter (default: false)
  
  // Icons
  sendIcon?: ReactNode;              // Custom send icon
  loadingIcon?: ReactNode;           // Custom loading icon
  
  // SDK config (passed to useLightRAG)
  baseUrl?: string;
  autoCreateChat?: boolean;
  chatId?: string;
  onError?: (error: LightRAGError) => void;
}
```

#### Theme Configuration

```typescript
interface ChatWidgetTheme {
  // Colors
  primaryColor?: string;
  secondaryColor?: string;
  backgroundColor?: string;
  textColor?: string;
  userMessageColor?: string;
  assistantMessageColor?: string;
  userMessageTextColor?: string;
  assistantMessageTextColor?: string;
  borderColor?: string;
  errorColor?: string;
  
  // Spacing
  borderRadius?: string;
  padding?: string;
  gap?: string;
  
  // Typography
  fontSize?: string;
  fontFamily?: string;
  
  // Shadows
  boxShadow?: string;
}
```

#### Custom Renderers

You can completely customize how elements are rendered:

```typescript
interface ChatWidgetRenderers {
  renderMessage?: (message: Message, index: number) => ReactNode;
  renderUserMessage?: (message: Message, index: number) => ReactNode;
  renderAssistantMessage?: (message: Message, index: number) => ReactNode;
  renderError?: (error: LightRAGError, onDismiss: () => void) => ReactNode;
  renderInput?: (props: ChatWidgetInputProps) => ReactNode;
  renderSendButton?: (props: ChatWidgetButtonProps) => ReactNode;
  renderHeader?: () => ReactNode;
  renderFooter?: () => ReactNode;
  renderEmptyState?: () => ReactNode;
  renderLoading?: () => ReactNode;
}
```

### `useLightRAG(config)`

React hook for managing chat state and interactions.

#### Parameters

- `config.apiKey` (string, required): Your public API key
- `config.baseUrl` (string, optional): API base URL (default: `https://your-api-domain.com/api/v1`)
- `config.autoCreateChat` (boolean, optional): Automatically create a chat on mount (default: `true`)
- `config.chatId` (string, optional): Initial chat ID to load
- `config.onError` (function, optional): Error callback function

#### Returns

```typescript
{
  // State
  messages: Message[];           // Array of chat messages
  chats: Chat[];                 // Array of all chats
  currentChatId: string | null;  // Current active chat ID
  loading: boolean;              // Loading state (initial load)
  sending: boolean;             // Sending message state
  error: LightRAGError | null;  // Error state

  // Actions
  sendMessage: (message: string) => Promise<void>;
  createChat: (title?: string) => Promise<string>;
  loadChat: (chatId: string) => Promise<void>;
  refreshChats: () => Promise<void>;
  clearError: () => void;
}
```

### `LightRAGSDK`

Main SDK class for API interactions.

#### Constructor

```typescript
new LightRAGSDK(config: LightRAGConfig)
```

#### Methods

##### `createChat(title?: string): Promise<string>`

Create a new chat conversation.

##### `listChats(): Promise<Chat[]>`

List all chats for the current session.

##### `sendMessage(chatId: string, message: string): Promise<string>`

Send a message to the chatbot and get a response.

##### `getChatMessages(chatId: string): Promise<Message[]>`

Get all messages in a chat conversation.

##### `listPendingQuestions(params?): Promise<ListPendingQuestionsResponse>`

List pending questions (optional feature).

##### `submitAnswer(pendingQuestionId: string, answer: string, isFAQ?: boolean): Promise<boolean>`

Submit an answer to a pending question (optional feature).

##### `getUsage(): Promise<UsageStats>`

Get usage statistics (optional feature).

## Next.js Integration

### App Router (Next.js 13+)

```tsx
// app/chat/page.tsx
'use client';

import { useLightRAG } from '@soaal/rag-reactjs-sdk';

export default function ChatPage() {
  const { messages, sendMessage, sending } = useLightRAG({
    apiKey: process.env.NEXT_PUBLIC_RAG_API_KEY!,
  });

  // ... rest of component
}
```

### Pages Router

```tsx
// pages/chat.tsx
import { useLightRAG } from '@soaal/rag-reactjs-sdk';

export default function ChatPage() {
  const { messages, sendMessage, sending } = useLightRAG({
    apiKey: process.env.NEXT_PUBLIC_RAG_API_KEY!,
  });

  // ... rest of component
}
```

## TypeScript Support

This SDK is written in TypeScript and includes full type definitions. All types are exported for your convenience:

```typescript
import type {
  Chat,
  Message,
  PendingQuestion,
  UsageStats,
  LightRAGError,
} from '@soaal/rag-reactjs-sdk';
```

## Error Handling

The SDK provides comprehensive error handling:

```typescript
import { useLightRAG } from '@soaal/rag-reactjs-sdk';

function ChatComponent() {
  const { error, sendMessage, clearError } = useLightRAG({
    apiKey: 'your-key',
    onError: (error) => {
      console.error('Chat error:', error);
      // Custom error handling
    },
  });

  if (error) {
    return (
      <div>
        <p>Error: {error.message}</p>
        <button onClick={clearError}>Dismiss</button>
      </div>
    );
  }

  // ... rest of component
}
```

## Session Management

The SDK automatically handles session management via HTTP cookies. Sessions are:
- Created automatically on first request
- Maintained across page refreshes
- Isolated per tenant
- Managed server-side (no manual cookie handling needed)

## Best Practices

1. **Store API keys securely**: Use environment variables (`NEXT_PUBLIC_*` for client-side)
2. **Handle errors gracefully**: Always check the `error` state and provide user feedback
3. **Show loading states**: Use `loading` and `sending` states to provide UI feedback
4. **Validate input**: Check message length before sending
5. **Debounce rapid requests**: Avoid sending multiple messages in quick succession

## Widget Examples

### Basic Widget

```tsx
<ChatWidget
  apiKey="your-api-key"
  title="Support Chat"
/>
```

### Themed Widget

```tsx
<ChatWidget
  apiKey="your-api-key"
  title="Support Chat"
  theme={{
    primaryColor: '#6366f1',
    userMessageColor: '#6366f1',
    assistantMessageColor: '#f3f4f6',
    borderRadius: '12px',
  }}
/>
```

### Dark Theme

```tsx
<ChatWidget
  apiKey="your-api-key"
  theme={{
    backgroundColor: '#1f2937',
    textColor: '#f9fafb',
    userMessageColor: '#8b5cf6',
    assistantMessageColor: '#374151',
    borderColor: '#4b5563',
  }}
/>
```

### With Avatars and Timestamps

```tsx
<ChatWidget
  apiKey="your-api-key"
  showAvatar={true}
  showTimestamp={true}
  userAvatar="👤"
  assistantAvatar="🤖"
/>
```

### Custom Renderers

```tsx
<ChatWidget
  apiKey="your-api-key"
  renderers={{
    renderUserMessage: (message) => (
      <div className="custom-user-message">
        {message.content}
      </div>
    ),
    renderAssistantMessage: (message) => (
      <div className="custom-assistant-message">
        {message.content}
      </div>
    ),
  }}
/>
```

### Multiline Input

```tsx
<ChatWidget
  apiKey="your-api-key"
  multiline={true}
  inputRows={3}
  sendOnShiftEnter={true}
  placeholder="Type your message... (Shift+Enter to send)"
/>
```

## Examples

### Multi-Chat Interface

```tsx
function ChatManager() {
  const { chats, currentChatId, loadChat, createChat } = useLightRAG({
    apiKey: 'your-key',
    autoCreateChat: false,
  });

  return (
    <div>
      <div className="chat-list">
        <button onClick={() => createChat()}>New Chat</button>
        {chats.map((chat) => (
          <button
            key={chat.id}
            onClick={() => loadChat(chat.id)}
            className={currentChatId === chat.id ? 'active' : ''}
          >
            {chat.title || 'Untitled Chat'}
          </button>
        ))}
      </div>
      {/* Chat interface */}
    </div>
  );
}
```

### Custom Error Boundary

```tsx
function ChatWithErrorBoundary() {
  const { error, clearError, sendMessage } = useLightRAG({
    apiKey: 'your-key',
  });

  if (error?.status === 401) {
    return <div>Invalid API key. Please check your configuration.</div>;
  }

  if (error?.status === 429) {
    return <div>Rate limit exceeded. Please try again later.</div>;
  }

  // ... rest of component
}
```

## License

MIT

## Support

For issues, questions, or feature requests, refer to the [SDK Flow Documentation](./SDK_FLOW.md) or contact your tenant administrator.