# @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.

## Recipes (copy-paste patterns)

### Recipe: brand colors + custom font

```tsx
<Chat
  projectId="..."
  apiEndpoint="https://app.aigentyc.ai"
  theme={{
    primaryColor: "#eb1d22",
    fontFamily: "Inter, sans-serif",
    userBubbleColor: "#eb1d22",
    assistantBubbleColor: "#f5f5f5",
  }}
/>
```

### Recipe: change welcome message

```tsx
<Chat
  projectId="..."
  apiEndpoint="https://app.aigentyc.ai"
  language="en"
  translations={{
    en: { welcomeTitle: "Hi! How can I help?", welcomeSubtitle: "Ask me anything." },
  }}
/>
```

### Recipe: track every user message (analytics)

```tsx
<Chat
  projectId="..."
  apiEndpoint="https://app.aigentyc.ai"
  onMessageSent={(m) => analytics.track("chat_message_sent", { id: m.id, content: m.content })}
  onMessageReceived={(m) => analytics.track("chat_message_received", { id: m.id })}
  onError={(err) => Sentry.captureException(err)}
/>
```

### Recipe: show citation sources under assistant replies

```tsx
<Chat projectId="..." apiEndpoint="https://app.aigentyc.ai" showSources />
```

### Recipe: replace the input bar with a custom one

```tsx
import { Chat } from "@aigentyc/chat-sdk";

function MyInput({ DefaultComponent, props }) {
  // Add a button next to the default input, or replace it entirely.
  return (
    <div className="my-composer">
      <DefaultComponent {...props} />
      <button onClick={() => alert("uploaded")}>📎</button>
    </div>
  );
}

<Chat slots={{ input: MyInput }} projectId="..." apiEndpoint="..." />
```

### Recipe: per-tool custom rendering (e.g. product cards)

```tsx
import type { ToolRendererProps } from "@aigentyc/chat-sdk";

function ProductGrid({ result }: ToolRendererProps) {
  const products = (result?.data as { items: any[] })?.items ?? [];
  return (
    <div className="grid grid-cols-2 gap-2">
      {products.map((p) => <div key={p.id}>{p.title} — ${p.price}</div>)}
    </div>
  );
}

<Chat
  projectId="..." apiEndpoint="..."
  slots={{ tools: { searchProducts: ProductGrid } }}
/>
```

### Recipe: Hebrew / RTL

```tsx
<Chat projectId="..." apiEndpoint="..." language="he" />
```
RTL direction is set automatically when `language === "he"`.

### Recipe: floating widget on an existing site

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

<ChatWidget
  projectId="..."
  apiEndpoint="https://app.aigentyc.ai"
  theme={{ primaryColor: "#eb1d22" }}
/>
```
Drop anywhere in your tree — it portals itself to the bottom-right corner.

### Recipe: headless (build your own UI)

```tsx
"use client";
import { useAigentycChat } from "@aigentyc/chat-sdk/hooks";

export default function MyChat() {
  const { messages, status, sendMessage } = useAigentycChat({
    projectId: "...",
    apiEndpoint: "https://app.aigentyc.ai",
  });
  return (
    <>
      {messages.map((m) => <div key={m.id}>{m.role}: {m.content}</div>)}
      <button disabled={status === "streaming"} onClick={() => sendMessage("hello")}>
        Send
      </button>
    </>
  );
}
```

### Recipe: enable live-chat handoff

```tsx
<Chat
  projectId="..."
  apiEndpoint="https://app.aigentyc.ai"
  apiKey="tyco_pk_..."     // required for live chat
  enableLiveChat
/>
```
The AI can hand off to a human operator via the `requestHumanChat` tool. UI surfaces a queue + operator panel automatically.

### Recipe: Next.js App Router page

```tsx
// app/chat/page.tsx
import { Chat } from "@aigentyc/chat-sdk";
import "@aigentyc/chat-sdk/theme/styles.css";  // import once, in layout.tsx is fine too

export default function Page() {
  return (
    <main style={{ height: "100dvh" }}>
      <Chat
        projectId={process.env.NEXT_PUBLIC_AIGENTYC_PROJECT_ID!}
        apiEndpoint={process.env.NEXT_PUBLIC_AIGENTYC_API_ENDPOINT!}
        apiKey={process.env.NEXT_PUBLIC_AIGENTYC_API_KEY}
      />
    </main>
  );
}
```

### Recipe: persist conversations (default on)

Persistence is on by default. To disable:

```tsx
<Chat projectId="..." apiEndpoint="..." persistMessages={false} />
```

Storage key: `aigentyc-messages-<projectId>` in `localStorage`.

### Recipe: programmatically reset the conversation

```tsx
import { useAigentycChat } from "@aigentyc/chat-sdk/hooks";

const { newConversation, clearMessages } = useAigentycChat({ projectId: "...", apiEndpoint: "..." });

<button onClick={newConversation}>New conversation</button>  // new sessionId + clears
<button onClick={clearMessages}>Clear messages</button>      // clears, keeps session
```

## Troubleshooting

| Symptom | Likely cause | Fix |
| --- | --- | --- |
| Unstyled / broken layout | Missing CSS import | `import "@aigentyc/chat-sdk/theme/styles.css"` |
| 401 / 403 from API | `apiKey` missing or wrong scope | Create key with `Chat: Full` permission |
| CORS error in browser | Allowed Origins on API key doesn't include current URL | Add `http://localhost:5173` (Vite) or `http://localhost:3000` (Next) to the key's Allowed Origins |
| `Cannot find module @ai-sdk/react` | Stale install from old SDK version | `rm -rf node_modules package-lock.json && npm install` (peers are bundled now) |
| Hebrew text shows LTR | Forgot `language="he"` | Pass `language="he"` to `<Chat>` |
| Tool result shows raw JSON | Custom tool with no renderer | Add `slots.tools[toolName]` or set `uiRenderMode: "hidden"` server-side |
| Chat doesn't render in Next.js | RSC issue | The SDK sets `"use client"`; if your wrapper is a Server Component, that's fine — don't add `"use client"` yourself |
| `searchKnowledgeBase` JSON appears | (it shouldn't — hidden by default since 0.1.3) | Upgrade `@aigentyc/chat-sdk` |

## 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)