# @aigentyc/chat-sdk

> React 19 SDK for embedding AI-powered chat UIs connected to the Aigentyc platform. Ships drop-in components, a composable component layer, and a fully headless hook. SSR-safe (Next.js App Router). White-label, themeable, i18n-ready, with backend-driven tool rendering and optional live-chat handoff.

## Fastest path — scaffold a starter

```bash
npm create aigentyc-chat@latest my-app
```

Prompts for template (`vite-react` or `next`) and `projectId`, then produces a working app. Non-interactive:

```bash
npm create aigentyc-chat@latest my-app -- --template=next --project-id=YOUR_ID
```

## Installation (add to existing app)

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

Only `react>=19` and `react-dom>=19` are required peers. Everything else needed for core chat (streaming, tools, transport) is bundled.

Optional peers — install only if you use that feature:
- `socket.io-client` — live chat handoff
- `recharts` — visualization tool renderer
- `@json-render/core @json-render/react @json-render/shadcn zod` — json-render tools

## Golden-path quick start

```tsx
import { Chat } from "@aigentyc/chat-sdk"
import "@aigentyc/chat-sdk/theme/styles.css"

export function App() {
  return (
    <Chat
      projectId="your-project-id"
      apiEndpoint="https://app.aigentyc.ai"
      apiKey="your-api-key"
    />
  )
}
```

Peer deps required: `react>=19`, `react-dom>=19`. The CSS import is required for theming.

## Four levels of control

1. **Drop-in** — `<Chat projectId apiEndpoint />`
2. **Customize** — add `theme`, `slots`, event handlers like `onMessageSent`
3. **Compose** — `<ChatProvider>` + individual components (`ChatInterface`, `ChatInput`)
4. **Headless** — `useAigentycChat({ projectId, apiEndpoint })` returns `{ messages, sendMessage, status }`

## Package entry points

- `@aigentyc/chat-sdk` — `Chat`, `ChatWidget`, `ChatProvider` (main)
- `@aigentyc/chat-sdk/hooks` — `useAigentycChat` and other hooks
- `@aigentyc/chat-sdk/components` — granular chat components
- `@aigentyc/chat-sdk/ai-elements` — `Message`, `Conversation`, primitives
- `@aigentyc/chat-sdk/tools` — `ToolRenderer`, `VisualizationRenderer`
- `@aigentyc/chat-sdk/json-render` — json-render integration
- `@aigentyc/chat-sdk/ui` — shadcn-style UI primitives
- `@aigentyc/chat-sdk/theme` — `ThemeProvider`; CSS at `@aigentyc/chat-sdk/theme/styles.css`
- `@aigentyc/chat-sdk/i18n` — `addLanguage`, built-in `en`, `he`
- `@aigentyc/chat-sdk/core` — types, transport, utils

## Slots

Replace any UI piece via the `slots` prop:

`header`, `welcome`, `message`, `input`, `footer`, `loader`, `suggestions`, `tools` (keyed per tool name).

## Tool rendering

The Aigentyc backend returns a `uiRenderMode` per tool result. The SDK auto-dispatches:
- `visualization` → recharts
- `json_render` → `@json-render/shadcn` component spec
- `legacy` → custom HTML/CSS template
- `preset` → built-in renderer

Override a specific tool:
```tsx
<Chat slots={{ tools: { searchProducts: MyProductGrid } }} />
```

## Theming

All tokens are CSS variables scoped under `[data-aigentyc-chat]`. Override via the `theme` prop or plain CSS. No forced branding.

## i18n

```tsx
import { addLanguage } from "@aigentyc/chat-sdk/i18n"
addLanguage("fr", { welcomeTitle: "Bienvenue" })
```

## Live chat

```tsx
<Chat enableLiveChat chatServiceUrl="wss://..." />
```
Requires `socket.io-client`.

## Next.js / SSR

All client components declare `"use client"`. Works in App Router and Pages Router without extra config.

## Common pitfalls (do not)

- Don't forget the CSS import — unstyled UI is almost always a missing `@aigentyc/chat-sdk/theme/styles.css`.
- Don't import from `dist/` or deep subpaths — use the public entry points above.
- Don't wrap in `<Chat>` twice; use `<ChatProvider>` + sub-components for layouts, not nested `<Chat>`.
- React 18 is not supported — peer is `>=19`.
- `apiKey` is optional for public/anon projects; required for authenticated ones.

## Links

- Package: https://www.npmjs.com/package/@aigentyc/chat-sdk
- Scaffolder: `npm create aigentyc-chat@latest my-app`
- Dashboard: https://app.aigentyc.ai

## Files included in this package

- `README.md` — install + quickstart
- `AGENTS.md` — agent-oriented guide (rules, decision tree, troubleshooting)
- `llms.txt` — this file (LLM-friendly summary)