npm package: @informedai/react
Description: React SDK for InformedAI Assistant - AI-powered content creation widget
Author: Marolence
Latest version: 0.4.32

# @informedai/react

React SDK for [InformedAI](https://informedai.app) - AI-powered content creation widget informed by your knowledge base.

## Installation

```bash
npm install @informedai/react
```

## Quick Start

```tsx
import { InformedAssistant } from '@informedai/react';

function App() {
  return (
    <InformedAssistant
      documentTypeId="dt_abc123"
      accessKey="pak_your_pool_access_key"
      onFieldApply={(field, value) => {
        console.log(`Applied ${value} to ${field}`);
      }}
    />
  );
}
```

## Features

- **AI-Powered Widget** - Embeddable chat widget for content creation
- **Knowledge-Informed** - Responses powered by your domain knowledge
- **Real-time Streaming** - SSE streaming for instant AI responses
- **Pending Values** - Preview suggestions before applying
- **Customizable Theme** - Match your brand colors
- **TypeScript Support** - Full type definitions included

## Components

### InformedAssistant

The primary widget for AI-powered document editing.

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `documentTypeId` | `string` | Yes | Document type ID |
| `accessKey` | `string` | No | Pool access key (`pak_` prefix) |
| `apiUrl` | `string` | No | Custom API URL |
| `externalId` | `string` | No | Your object's ID for idempotent document linking |
| `initialData` | `Record<string, unknown>` | No | Current field values to sync |
| `persistSession` | `boolean` | No | Persist in localStorage (default: true when externalId set) |
| `sessionId` | `string` | No | Resume existing session |
| `onReady` | `(ctx) => void` | No | Called when widget loads with schema |
| `onFieldApply` | `(field, value) => void` | No | Called when value is applied |
| `onSessionChange` | `(session) => void` | No | Called on session state change |
| `onError` | `(error) => void` | No | Called on errors |
| `getCurrentFieldValues` | `() => Record<string, unknown>` | No | Returns current form values |
| `onAnalyticsRunClick` | `(runId, query, sessionId) => void` | No | Called on analytics badge click |
| `theme` | `Partial<WidgetTheme>` | No | Custom theme |
| `position` | `'inline' \| 'bottom-right' \| 'bottom-left'` | No | Widget position |
| `defaultCollapsed` | `boolean` | No | Start collapsed (floating only) |

### WebsiteChatbot

Embeddable chatbot powered by a website agent. Uses domain-based authentication.

```tsx
import { WebsiteChatbot } from '@informedai/react';

<WebsiteChatbot
  agentId="wa_abc123"
  title="Help & Support"
  position="bottom-right"
/>
```

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `agentId` | `string` | Yes | Website agent ID |
| `apiUrl` | `string` | No | Custom API URL |
| `theme` | `Partial<WebsiteChatbotTheme>` | No | Theme overrides |
| `position` | `'bottom-right' \| 'bottom-left' \| 'inline'` | No | Widget position |
| `defaultCollapsed` | `boolean` | No | Start collapsed |
| `title` | `string` | No | Widget title |
| `placeholder` | `string` | No | Input placeholder |

### AdminChatbot

Knowledge library chatbot. Requires an `aak_` API key.

```tsx
import { AdminChatbot } from '@informedai/react';

<AdminChatbot
  apiKey="aak_your_key"
  title="Knowledge Library"
  systemPrompt="You are a helpful assistant."
  position="inline"
/>
```

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `apiKey` | `string` | Yes | Admin agent key (`aak_` prefix) |
| `apiUrl` | `string` | No | Custom API URL |
| `systemPrompt` | `string` | No | Custom system prompt |
| `allowEditSystemPrompt` | `boolean` | No | Let users edit prompt in UI |
| `theme` | `Partial<AdminChatbotTheme>` | No | Theme overrides |
| `position` | `'bottom-right' \| 'bottom-left' \| 'inline'` | No | Widget position |
| `defaultCollapsed` | `boolean` | No | Start collapsed |
| `title` | `string` | No | Widget title |
| `placeholder` | `string` | No | Input placeholder |

### SmartQuestionnaire

AI-powered step-by-step questionnaire. Uses domain-based authentication.

```tsx
import { SmartQuestionnaire } from '@informedai/react';

<SmartQuestionnaire
  questionnaireId="sq_abc123"
  title="Find the Right Product"
  position="inline"
/>
```

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `questionnaireId` | `string` | Yes | Questionnaire ID |
| `apiUrl` | `string` | No | Custom API URL |
| `theme` | `Partial<SmartQuestionnaireTheme>` | No | Theme overrides |
| `position` | `'bottom-right' \| 'bottom-left' \| 'inline'` | No | Widget position |
| `defaultCollapsed` | `boolean` | No | Start collapsed |
| `title` | `string` | No | Widget title |
| `placeholder` | `string` | No | Input placeholder |

## Theming

```tsx
<InformedAssistant
  documentTypeId="dt_abc123"
  theme={{
    primaryColor: '#3b82f6',
    backgroundColor: '#ffffff',
    textColor: '#1f2937',
    borderRadius: '16px',
    fontFamily: 'Inter, sans-serif',
  }}
/>
```

## Advanced Usage

### Using Context Provider

For shared state across components:

```tsx
import { InformedAIProvider, useInformedAI } from '@informedai/react';

function App() {
  return (
    <InformedAIProvider config={{ documentTypeId: 'dt_abc123' }}>
      <CustomWidget />
    </InformedAIProvider>
  );
}

function CustomWidget() {
  const { session, sendMessage, isStreaming } = useInformedAI();
  // Build your own UI
}
```

### Using Hooks

```tsx
import { useSession } from '@informedai/react';

function CustomWidget() {
  const { session, sendMessage, applyPendingValue, isStreaming } = useSession({
    documentTypeId: 'dt_abc123',
  });
  // Build your own UI
}
```

## Requirements

- React 18+
- An InformedAI workspace

## Links

- [Documentation](https://beta.informedai.app/docs)
- [Dashboard](https://beta.informedai.app/dashboard)

## License

MIT