`.\n\n### Gemini details\n\n- **API key** is sent as a **query parameter** on the request URL (as required by the REST API).\n\n---\n\n## `` — all props\n\nEvery prop except `aiProvider` is **optional** unless your provider needs it.\n\n| Prop | Type | Default | What it does |\n|------|------|---------|----------------|\n| `aiProvider` | `\"openai\" \\| \"gemini\" \\| \"selfhosted\"` | — | **Required.** Which backend to call. |\n| `apiKey` | `string` | `undefined` | **Required** for `openai` and `gemini`. Not used for `selfhosted`. |\n| `backendUrl` | `string` | Provider default (see table above) | Override the full URL for AI requests. |\n| `title` | `string` | `\"Messages\"` | Text in the panel header. |\n| `placeholder` | `string` | `\"Type your message…\"` | Input placeholder. |\n| `fontFamily` | `string` | System UI stack (see below) | CSS `font-family` for the whole widget. |\n| `theme` | `ChatbotTheme` | Built-in light/dark neutral glass | **Partial** object; merged over defaults. |\n| `persistMessages` | `boolean` | `true` | If `true`, loads/saves message list in `localStorage`. |\n| `storageKey` | `string` | `\"rawan-bee-bot:chatHistory\"` | `localStorage` key when `persistMessages` is `true`. |\n| `className` | `string` | `undefined` | Applied to the **outer wrapper** `` around launcher + panel (for your own layout/CSS). |\n| `onMessageSend` | function | `undefined` | Called after a **successful assistant** reply (see Callbacks). |\n| `onSaveMessage` | function | `undefined` | Called when the widget **stores** a message (user + assistant; see Callbacks). |\n| `onError` | function | `undefined` | Called with an `Error` if the AI request fails. |\n\n---\n\n## Callbacks (`onSaveMessage`, `onMessageSend`, `onError`)\n\nAll callbacks are **optional**. They may be **async**; the widget will `await` them where used.\n\n### `onSaveMessage(message, history)`\n\nCalled:\n\n1. After the **user** message is added (before the AI responds).\n2. After each **assistant** message is added (including error messages shown in the UI).\n\n- **`message`:** The single message that was just appended (`ChatMessage`).\n- **`history`:** The full list **including** that message.\n\nUse this to **mirror** chat to your database or analytics. It does **not** replace `localStorage` unless you set `persistMessages={false}`.\n\n### `onMessageSend(message, history)`\n\nCalled **only** after a **successful** assistant reply (not for user-only turns, not for thrown errors).\n\n- **`message`:** The assistant’s `ChatMessage`.\n- **`history`:** Full transcript including that reply.\n\n### `onError(error)`\n\nCalled when the AI call throws (network, HTTP error, missing API key, etc.). The user still sees an **error line** in the chat when possible.\n\n### `ChatMessage` shape (TypeScript)\n\n```ts\ntype ChatMessage = {\n id: string;\n role: \"user\" | \"assistant\" | \"system\";\n content: string;\n createdAt: string; // ISO timestamp\n isError?: boolean; // true when content is an error explanation\n};\n```\n\nImport the type in TypeScript:\n\n```tsx\nimport type { ChatMessage, ChatbotTheme, ChatbotUIProps } from \"rawan-bee-bot\";\n```\n\n---\n\n## Chat history & `localStorage`\n\n- **`persistMessages={true}` (default):** On load, the widget reads `storageKey`; after each change, it writes the full message array back.\n- **`persistMessages={false}`:** No read/write; each full page load starts empty unless you add your own persistence later.\n- **Changing `storageKey`** gives you a separate thread per key (e.g. per user or per page).\n\n---\n\n## Styling: `theme` and `fontFamily`\n\n### Defaults\n\n- **Colors:** Neutral, **glassy** presets; **light** vs **dark** follows **`prefers-color-scheme`** until you override with `theme`.\n- **Font:** A **system UI** stack (same as exporting `SYSTEM_UI_FONT_STACK`).\n\n### `theme` — what each key controls\n\nPass **only** the keys you need. Unset keys keep the default for the current light/dark preset.\n\n| Key | Affects |\n|-----|--------|\n| `chatButtonBg` | Bottom launcher bar background |\n| `chatButtonTextColor` | Launcher text and accent dot |\n| `headerBg` | Panel header background |\n| `headerTextColor` | Header title color |\n| `closeButtonColor` | Close control |\n| `userMessageBg` / `userMessageText` | User bubbles |\n| `botMessageBg` / `botMessageText` | Assistant bubbles |\n| `inputContainerBg` | Area behind the input row |\n| `inputFieldBg` / `inputFieldText` | Input field |\n| `sendButtonBg` / `sendButtonTextColor` | Send button |\n| `typingIndicatorColor` | “Typing…” text |\n\n**Color format:** Any valid CSS color string works (`#rrggbb`, `rgb()`, `rgba()`, etc.). For **hex** colors, some internal helpers can lighten them for gradients; **non-hex** values are passed through unchanged.\n\n### `fontFamily`\n\nSet a full CSS stack, e.g.:\n\n```tsx\n\n```\n\nTo **extend** the package default instead of replacing it:\n\n```tsx\nimport ChatbotUI, { SYSTEM_UI_FONT_STACK } from \"rawan-bee-bot\";\n\n\n```\n\n---\n\n## Imports and exports\n\n**Default export (most apps):**\n\n```tsx\nimport ChatbotUI from \"rawan-bee-bot\";\n```\n\n**Named exports:**\n\n```tsx\nimport ChatbotUI, { SYSTEM_UI_FONT_STACK } from \"rawan-bee-bot\";\n```\n\n**Type-only imports:**\n\n```tsx\nimport type {\n AIProviderName,\n ChatbotTheme,\n ChatMessage,\n ChatbotUIProps,\n} from \"rawan-bee-bot\";\n```\n\n---\n\n## Full example (theme + callbacks + font)\n\n```tsx\nimport ChatbotUI, { SYSTEM_UI_FONT_STACK } from \"rawan-bee-bot\";\n\nexport default function App() {\n return (\n {\n await fetch(\"/api/chat-log\", {\n method: \"POST\",\n headers: { \"Content-Type\": \"application/json\" },\n body: JSON.stringify({ message, history }),\n });\n }}\n onError={(err) => console.error(err.message)}\n />\n );\n}\n```\n\n---\n\n## Troubleshooting\n\n| Problem | Things to check |\n|--------|------------------|\n| **CORS errors** | Browser calls go **from your site** to the AI URL. OpenAI/Gemini allow browser keys in some setups; **local Ollama** often needs a **same-origin proxy** or dev server proxy. |\n| **`openai` / `gemini` errors** | `apiKey` set? Env var actually loaded in the build? |\n| **`selfhosted` empty or errors** | Is the server running? Does URL match? Is the response shape compatible (streaming JSON lines with `response`)? Model on server is **`mistral`** per request body. |\n| **Wrong font** | Set `fontFamily` explicitly; ensure the font is loaded in your app (e.g. Google Fonts + CSS). |\n| **Duplicate React** | In monorepos, ensure a **single** React instance (common Vite/webpack `resolve.dedupe` issue). |\n\n---\n\n## Develop this repo locally\n\n```sh\ngit clone https://github.com/RawanBee/rawan-bee-bot.git\ncd rawan-bee-bot\nnpm install\nnpm run build\n```\n\n### Demo app (`demo/`)\n\n```sh\ncd demo\nnpm install\nnpm run dev\n```\n\n---\n\n## Questions & bugs\n\nUse [GitHub Issues](https://github.com/RawanBee/rawan-bee-bot/issues) for bug reports and feature requests.\n\n---\n\n## License\n\nMIT\n","readmeFilename":"README.md"}