@aigentyc/chat-sdk 0.1.3 → 0.1.5

package/AGENTS.md

@@ -0,0 +1,187 @@
+# AGENTS.md — @aigentyc/chat-sdk
+
+Guide for AI coding assistants (Claude Code, Cursor, Windsurf, v0, Lovable, Bolt) using or contributing to this SDK. Humans: read `README.md` first.
+
+---
+
+## What this package is
+
+React 19 SDK for embedding an AI chat UI backed by the Aigentyc platform. Ships as a set of subpath exports so consumers only pull what they need.
+
+- Package name: `@aigentyc/chat-sdk`
+- Peer deps (required): `react>=19`, `react-dom>=19`
+- Bundled internally (no install needed): `@ai-sdk/react`, `ai`
+- Peer deps (optional, install only for that feature): `socket.io-client` (live chat), `recharts` (viz), `@json-render/*` + `zod` (json-render)
+- SSR: all client components emit `"use client"`; safe for Next.js App Router.
+
+---
+
+## Canonical install + usage (paste-ready)
+
+**New project?** Use the scaffolder — it's the lowest-risk path:
+
+```bash
+npm create aigentyc-chat@latest my-app -- --template=next --project-id=YOUR_ID
+```
+
+**Adding to an existing app:**
+
+```bash
+npm install @aigentyc/chat-sdk
+```
+
+```tsx
+import { Chat } from "@aigentyc/chat-sdk"
+import "@aigentyc/chat-sdk/theme/styles.css"
+
+export default function Page() {
+  return (
+    <Chat
+      projectId="YOUR_PROJECT_ID"
+      apiEndpoint="https://api.aigentyc.com"
+      apiKey="YOUR_API_KEY"
+    />
+  )
+}
+```
+
+**Required:** the CSS import. Without it the chat renders unstyled.
+
+---
+
+## Decision tree: which API to use
+
+```
+Need a full chat UI with zero config?           → <Chat />
+Need a floating bubble widget?                  → <ChatWidget />
+Need to customize header/input/messages only?   → <Chat slots={{...}} />
+Need custom layout around the chat?             → <ChatProvider> + <ChatInterface /> + <ChatInput />
+Need your own UI entirely?                      → useAigentycChat() (headless)
+Need to override one tool's rendering?          → slots.tools[toolName]
+```
+
+Don't reach for the headless hook just to change styling — use `theme` or `slots` first.
+
+---
+
+## Entry points (import from these, never from `dist/`)
+
+| Import | What you get |
+| --- | --- |
+| `@aigentyc/chat-sdk` | `Chat`, `ChatWidget`, `ChatProvider` |
+| `@aigentyc/chat-sdk/hooks` | `useAigentycChat`, other hooks |
+| `@aigentyc/chat-sdk/components` | Granular composable chat pieces |
+| `@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 primitives |
+| `@aigentyc/chat-sdk/theme` | `ThemeProvider`; CSS at `.../theme/styles.css` |
+| `@aigentyc/chat-sdk/i18n` | `addLanguage`, built-in `en`, `he` |
+| `@aigentyc/chat-sdk/core` | Types, transport, utilities |
+
+---
+
+## Slots
+
+`slots` prop on `<Chat>` / `<ChatWidget>`:
+
+- `header`, `welcome`, `message`, `input`, `footer`, `loader`, `suggestions`
+- `tools`: `Record<toolName, ComponentType>` — override per-tool rendering
+
+Each slot receives typed props — consult `.d.ts` of the entry points for exact signatures. Don't invent prop names.
+
+---
+
+## Tool rendering
+
+Tool results come back from the backend with a `uiRenderMode`:
+
+- `visualization` → recharts (requires `recharts` peer)
+- `json_render` → `@json-render/shadcn` (requires `@json-render/*` + `zod` peers)
+- `legacy` → HTML/CSS template from backend
+- `preset` → built-in renderer
+
+If a peer is missing, that tool's UI falls back; install the peer or override via `slots.tools[name]`.
+
+---
+
+## Theming
+
+CSS variables scoped under `[data-aigentyc-chat]`. Two ways to customize:
+
+```tsx
+<Chat theme={{ primaryColor: "#3b82f6" }} />
+```
+
+or plain CSS targeting `[data-aigentyc-chat]`. Do **not** edit `dist/styles.css` directly.
+
+---
+
+## i18n
+
+Built-in: `en`, `he`. Add more:
+
+```tsx
+import { addLanguage } from "@aigentyc/chat-sdk/i18n"
+addLanguage("fr", { welcomeTitle: "Bienvenue" })
+```
+
+---
+
+## Live chat handoff
+
+```tsx
+<Chat enableLiveChat chatServiceUrl="wss://..." />
+```
+
+Requires `socket.io-client`. Omit both props for AI-only mode.
+
+---
+
+## Rules for agents editing consumer projects
+
+**Do:**
+- Use the canonical quick start above verbatim for first-time setup.
+- Import CSS once, at the app root or layout file.
+- Prefer `slots` + `theme` before going headless.
+- Use React 19 features (Actions, `use`) — this SDK targets React 19.
+- Check `.d.ts` files under the published package for exact prop types.
+
+**Don't:**
+- Don't install React 18 — peer is `>=19`. If the project is on React 18, warn the user and stop.
+- Don't import from `@aigentyc/chat-sdk/dist/*` — those paths are not public API.
+- Don't reimplement message rendering when `slots.message` exists.
+- Don't call the Aigentyc API directly from the client — the SDK owns transport.
+- Don't add `"use client"` to files that wrap the SDK unnecessarily; it's already inside.
+- Don't commit `apiKey` to source control; use env vars (`NEXT_PUBLIC_*` only if the project is OK exposing it; otherwise proxy through a server route).
+
+---
+
+## Troubleshooting quick table
+
+| Symptom | Likely cause |
+| --- | --- |
+| Unstyled / broken layout | Missing `import "@aigentyc/chat-sdk/theme/styles.css"` |
+| "Cannot find module @ai-sdk/react" | Stale install — delete `node_modules` and reinstall (these are now bundled) |
+| Tool renders blank | Peer for that `uiRenderMode` not installed |
+| SSR hydration warning | Wrapping `<Chat>` in a non-client component — it's fine, the SDK handles `"use client"` internally; check for other client-only code in the tree |
+| React version error | Upgrade to React 19 |
+
+---
+
+## Repository layout (for contributors)
+
+- `src/` — source; barrel files per entry point
+- `dist/` — build output (tsup); do not edit
+- `stories/` — Storybook
+- `demo/` — local demo app (standalone Vite)
+- `src/styles/index.css` — Tailwind entry compiled to `dist/styles.css`
+
+Scripts: `pnpm build`, `pnpm storybook`, `pnpm test`, `pnpm lint`.
+
+---
+
+## Versioning
+
+- Current: `0.1.0` (pre-1.0 — API may shift).
+- Pin exact versions in consumer projects until 1.0.