npm package: @rag-widget/chat-widget
Description: Embeddable chat widget for RAG-powered knowledge bases
Latest version: 0.1.3

# @rag-widget/chat-widget

Embeddable React chat widget for RAG-powered knowledge bases.

## Installation

### NPM/Yarn (React Applications)

```bash
npm install @rag-widget/chat-widget
# or
yarn add @rag-widget/chat-widget
```

### CDN (Any Website)

```html
<!-- Include React and ReactDOM first -->
<script src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
<script src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>

<!-- Include the widget -->
<script src="https://your-cdn.com/rag-chat-widget.umd.js"></script>
```

## Quick Start

### React Application

```tsx
import { ChatWidget } from '@rag-widget/chat-widget';

function App() {
  return (
    <ChatWidget
      apiKey="rw_live_your_api_key"
      widgetId="your-widget-id"
    />
  );
}
```

### Script Tag (Non-React)

```html
<div id="chat-widget-root"></div>
<script>
  RAGChatWidget.render({
    apiKey: 'rw_live_your_api_key',
    widgetId: 'your-widget-id',
    container: document.getElementById('chat-widget-root')
  });
</script>
```

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `apiKey` | `string` | Yes | - | Your RAG Widget API key |
| `widgetId` | `string` | Yes | - | The widget ID to connect to |
| `apiBaseUrl` | `string` | No | Current origin | API server URL |
| `position` | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'` | No | `'bottom-right'` | Widget position |
| `primaryColor` | `string` | No | `'#007bff'` | Primary theme color |
| `greeting` | `string` | No | From config | Initial greeting message |
| `placeholder` | `string` | No | From config | Input placeholder text |
| `showPoweredBy` | `boolean` | No | From config | Show "Powered by" footer |
| `onError` | `(error: Error) => void` | No | - | Error callback |
| `onMessageSent` | `(message: string) => void` | No | - | Message sent callback |
| `onMessageReceived` | `(message: Message) => void` | No | - | Message received callback |

## Using the Hook

For custom implementations, use the `useChatWidget` hook:

```tsx
import { useChatWidget } from '@rag-widget/chat-widget';

function CustomChat() {
  const {
    messages,
    isLoading,
    isConnected,
    config,
    error,
    sendMessage,
    clearMessages,
    retry
  } = useChatWidget({
    apiKey: 'rw_live_your_api_key',
    widgetId: 'your-widget-id',
    apiBaseUrl: 'https://your-api.com'
  });

  return (
    <div>
      {messages.map(msg => (
        <div key={msg.id} className={msg.role}>
          {msg.content}
        </div>
      ))}
      <input
        onKeyDown={e => {
          if (e.key === 'Enter') {
            sendMessage(e.currentTarget.value);
            e.currentTarget.value = '';
          }
        }}
      />
    </div>
  );
}
```

## Using the Provider

For sharing state across components:

```tsx
import { ChatWidgetProvider, useChatWidgetContext } from '@rag-widget/chat-widget';

function App() {
  return (
    <ChatWidgetProvider
      apiKey="rw_live_your_api_key"
      widgetId="your-widget-id"
    >
      <ChatMessages />
      <ChatInput />
    </ChatWidgetProvider>
  );
}

function ChatMessages() {
  const { messages, isLoading } = useChatWidgetContext();
  // ...
}

function ChatInput() {
  const { sendMessage } = useChatWidgetContext();
  // ...
}
```

## Styling

The widget comes with default styles. To customize:

### CSS Variables

```css
.rag-chat-widget {
  --rag-primary-color: #007bff;
  --rag-bg-color: #ffffff;
  --rag-text-color: #333333;
  --rag-border-color: #e0e0e0;
  --rag-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
  --rag-font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
}
```

### Custom Styles

Import the CSS separately and override:

```tsx
import '@rag-widget/chat-widget/dist/styles.css';
// Then add your overrides
```

## API Endpoints

The widget communicates with these endpoints:

- `GET /api/v1/widget/:widgetId/config` - Get widget configuration
- `POST /api/v1/widget/:widgetId/query` - One-shot query
- `POST /api/v1/widget/:widgetId/sessions` - Create chat session
- `POST /api/v1/widget/:widgetId/sessions/:sessionId/messages` - Send message (SSE streaming)

## Security

- API keys are sent via `X-API-Key` header
- Domain whitelisting is enforced server-side
- Rate limiting is applied per API key
- Sessions expire after 1 hour of inactivity

## Browser Support

- Chrome 60+
- Firefox 55+
- Safari 12+
- Edge 79+

## License

MIT