@aigentyc/chat-sdk 0.1.3 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +189 -0
- package/bin/doctor.mjs +255 -0
- package/dist/ai-elements.cjs +119 -162
- package/dist/ai-elements.cjs.map +1 -1
- package/dist/ai-elements.js +5 -60
- package/dist/ai-elements.js.map +1 -1
- package/dist/{chunk-PKGD6CTD.js → chunk-2677FDTG.js} +107 -59
- package/dist/chunk-2677FDTG.js.map +1 -0
- package/dist/{chunk-42ARGQXE.js → chunk-7L4FS6G7.js} +7 -3
- package/dist/chunk-7L4FS6G7.js.map +1 -0
- package/dist/{chunk-VS3NZ7FX.js → chunk-A7PCSWIK.js} +60 -5
- package/dist/chunk-A7PCSWIK.js.map +1 -0
- package/dist/{chunk-WZLWAVSS.cjs → chunk-C24QG43M.cjs} +10 -2
- package/dist/chunk-C24QG43M.cjs.map +1 -0
- package/dist/{chunk-NW2ESHRV.js → chunk-KVEJAPWA.js} +4 -8
- package/dist/chunk-KVEJAPWA.js.map +1 -0
- package/dist/{chunk-X5YEOOPK.cjs → chunk-QDFPJJ5Y.cjs} +5 -13
- package/dist/chunk-QDFPJJ5Y.cjs.map +1 -0
- package/dist/{chunk-FQN6OBGN.cjs → chunk-RTVEBPAJ.cjs} +63 -4
- package/dist/chunk-RTVEBPAJ.cjs.map +1 -0
- package/dist/{chunk-IWIGM3RY.cjs → chunk-WQARQ2FJ.cjs} +109 -61
- package/dist/chunk-WQARQ2FJ.cjs.map +1 -0
- package/dist/components.cjs +14 -14
- package/dist/components.d.cts +5 -0
- package/dist/components.d.ts +5 -0
- package/dist/components.js +4 -4
- package/dist/index.cjs +14 -12
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +8 -1
- package/dist/index.d.ts +8 -1
- package/dist/index.js +8 -6
- package/dist/index.js.map +1 -1
- package/dist/llms-full.txt +769 -0
- package/dist/ui.cjs +51 -51
- package/dist/ui.js +2 -2
- package/llms.txt +323 -0
- package/package.json +10 -2
- package/dist/chunk-42ARGQXE.js.map +0 -1
- package/dist/chunk-FQN6OBGN.cjs.map +0 -1
- package/dist/chunk-IWIGM3RY.cjs.map +0 -1
- package/dist/chunk-NW2ESHRV.js.map +0 -1
- package/dist/chunk-PKGD6CTD.js.map +0 -1
- package/dist/chunk-VS3NZ7FX.js.map +0 -1
- package/dist/chunk-WZLWAVSS.cjs.map +0 -1
- package/dist/chunk-X5YEOOPK.cjs.map +0 -1
|
@@ -0,0 +1,769 @@
|
|
|
1
|
+
# @aigentyc/chat-sdk — full LLM context
|
|
2
|
+
|
|
3
|
+
This file is the deep reference for AI coding tools (Cursor, Claude Code, Windsurf, v0). It is generated from the published types and aggregated docs at build time. For a short overview, read `llms.txt`.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## README.md
|
|
8
|
+
|
|
9
|
+
# @aigentyc/chat-sdk
|
|
10
|
+
|
|
11
|
+
> React SDK for building AI-powered chat interfaces connected to the Aigentyc platform.
|
|
12
|
+
|
|
13
|
+
## Features
|
|
14
|
+
- Drop-in `<Chat />` and `<ChatWidget />` components
|
|
15
|
+
- Full slot system — replace any UI piece
|
|
16
|
+
- Headless mode with `useAigentycChat` hook
|
|
17
|
+
- Backend-driven tool rendering (visualization, json-render, custom HTML)
|
|
18
|
+
- Live chat handoff with Socket.IO
|
|
19
|
+
- Built-in i18n (en, he) — extensible with `addLanguage()`
|
|
20
|
+
- React 19, SSR-compatible (Next.js App Router)
|
|
21
|
+
- Multi-instance support — multiple chats on one page
|
|
22
|
+
- White-label — zero forced branding
|
|
23
|
+
|
|
24
|
+
## Quickest start — scaffold a new app
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
npm create aigentyc-chat@latest my-app
|
|
28
|
+
cd my-app && npm install && npm run dev
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
Picks Vite or Next.js, wires your `projectId`, drops in `<Chat />`. Done.
|
|
32
|
+
|
|
33
|
+
## Add to an existing app
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
npm install @aigentyc/chat-sdk
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
That's it — core chat, streaming, and tool rendering work out of the box.
|
|
40
|
+
|
|
41
|
+
Optional peer deps — install only if you use that feature:
|
|
42
|
+
- `socket.io-client` — live chat handoff
|
|
43
|
+
- `recharts` — visualization tool renderer
|
|
44
|
+
- `@json-render/core @json-render/react @json-render/shadcn zod` — json-render tools
|
|
45
|
+
|
|
46
|
+
## Quick Start
|
|
47
|
+
|
|
48
|
+
```tsx
|
|
49
|
+
import { Chat } from "@aigentyc/chat-sdk"
|
|
50
|
+
import "@aigentyc/chat-sdk/theme/styles.css"
|
|
51
|
+
|
|
52
|
+
export function App() {
|
|
53
|
+
return (
|
|
54
|
+
<Chat
|
|
55
|
+
projectId="your-project-id"
|
|
56
|
+
apiEndpoint="https://app.aigentyc.ai"
|
|
57
|
+
apiKey="your-api-key"
|
|
58
|
+
/>
|
|
59
|
+
)
|
|
60
|
+
}
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
## Four Levels of Control
|
|
64
|
+
|
|
65
|
+
### Level 1 — Drop-in
|
|
66
|
+
```tsx
|
|
67
|
+
<Chat projectId="..." apiEndpoint="..." />
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
### Level 2 — Customize with slots + theme
|
|
71
|
+
```tsx
|
|
72
|
+
<Chat
|
|
73
|
+
projectId="..." apiEndpoint="..."
|
|
74
|
+
theme={{ primaryColor: "#3b82f6" }}
|
|
75
|
+
slots={{ header: MyHeader, input: MyInput }}
|
|
76
|
+
onMessageSent={(msg) => analytics.track('chat', msg)}
|
|
77
|
+
/>
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
### Level 3 — Compose components
|
|
81
|
+
```tsx
|
|
82
|
+
<ChatProvider projectId="..." apiEndpoint="...">
|
|
83
|
+
<MyLayout>
|
|
84
|
+
<ChatInterface />
|
|
85
|
+
<ChatInput />
|
|
86
|
+
</MyLayout>
|
|
87
|
+
</ChatProvider>
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
### Level 4 — Headless
|
|
91
|
+
```tsx
|
|
92
|
+
const { messages, sendMessage, status } = useAigentycChat({
|
|
93
|
+
projectId: "...", apiEndpoint: "..."
|
|
94
|
+
})
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
## Slots
|
|
98
|
+
|
|
99
|
+
| Slot | Replaces |
|
|
100
|
+
| --- | --- |
|
|
101
|
+
| `header` | Chat header bar |
|
|
102
|
+
| `welcome` | Welcome / empty state |
|
|
103
|
+
| `message` | Individual message bubble |
|
|
104
|
+
| `input` | Composer / input box |
|
|
105
|
+
| `footer` | Footer below input |
|
|
106
|
+
| `loader` | Loading indicator |
|
|
107
|
+
| `suggestions` | Suggested prompts |
|
|
108
|
+
| `tools` | Per-tool renderers (keyed by tool name) |
|
|
109
|
+
|
|
110
|
+
## Tool Rendering
|
|
111
|
+
Tools created in the Aigentyc platform come with rendering instructions. The SDK auto-renders based on `uiRenderMode`:
|
|
112
|
+
- `visualization` → recharts
|
|
113
|
+
- `json_render` → component spec via @json-render/shadcn
|
|
114
|
+
- `legacy` → custom HTML/CSS template
|
|
115
|
+
- `preset` → built-in renderers
|
|
116
|
+
|
|
117
|
+
Override per-tool:
|
|
118
|
+
```tsx
|
|
119
|
+
<Chat slots={{ tools: { searchProducts: MyProductGrid } }} />
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
## Theming
|
|
123
|
+
All theme tokens are CSS variables under `[data-aigentyc-chat]`. Override via `theme` prop or your own CSS.
|
|
124
|
+
|
|
125
|
+
## i18n
|
|
126
|
+
Built-in: `en`, `he`. Add custom languages:
|
|
127
|
+
```tsx
|
|
128
|
+
import { addLanguage } from "@aigentyc/chat-sdk/i18n"
|
|
129
|
+
addLanguage("fr", { welcomeTitle: "Bienvenue", ... })
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
## Live Chat
|
|
133
|
+
Enable Socket.IO-based live chat handoff:
|
|
134
|
+
```tsx
|
|
135
|
+
<Chat enableLiveChat chatServiceUrl="wss://..." />
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
## Next.js / SSR
|
|
139
|
+
All components have `"use client"` directives. Works in App Router and Pages Router.
|
|
140
|
+
|
|
141
|
+
## Storybook
|
|
142
|
+
```bash
|
|
143
|
+
npm run storybook
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
## Demo
|
|
147
|
+
```bash
|
|
148
|
+
cd demo && npm install && npm run dev
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
## Package Exports
|
|
152
|
+
- `@aigentyc/chat-sdk` — main (Chat, ChatWidget, ChatProvider)
|
|
153
|
+
- `@aigentyc/chat-sdk/core` — types, transport, utils
|
|
154
|
+
- `@aigentyc/chat-sdk/hooks` — all hooks
|
|
155
|
+
- `@aigentyc/chat-sdk/components` — individual chat components
|
|
156
|
+
- `@aigentyc/chat-sdk/ai-elements` — Message, Conversation, etc.
|
|
157
|
+
- `@aigentyc/chat-sdk/tools` — ToolRenderer, VisualizationRenderer
|
|
158
|
+
- `@aigentyc/chat-sdk/json-render` — json-render system
|
|
159
|
+
- `@aigentyc/chat-sdk/ui` — shadcn primitives
|
|
160
|
+
- `@aigentyc/chat-sdk/theme` — ThemeProvider + styles.css
|
|
161
|
+
- `@aigentyc/chat-sdk/i18n` — translations
|
|
162
|
+
|
|
163
|
+
## License
|
|
164
|
+
MIT
|
|
165
|
+
|
|
166
|
+
---
|
|
167
|
+
|
|
168
|
+
## AGENTS.md
|
|
169
|
+
|
|
170
|
+
# AGENTS.md — @aigentyc/chat-sdk
|
|
171
|
+
|
|
172
|
+
Guide for AI coding assistants (Claude Code, Cursor, Windsurf, v0, Lovable, Bolt) using or contributing to this SDK. Humans: read `README.md` first.
|
|
173
|
+
|
|
174
|
+
**Live docs (always current):** https://context7.com/llmstxt/unpkg_aigentyc_chat-sdk_0_1_5_llms_txt/llms.txt
|
|
175
|
+
|
|
176
|
+
---
|
|
177
|
+
|
|
178
|
+
## What this package is
|
|
179
|
+
|
|
180
|
+
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.
|
|
181
|
+
|
|
182
|
+
- Package name: `@aigentyc/chat-sdk`
|
|
183
|
+
- Peer deps (required): `react>=19`, `react-dom>=19`
|
|
184
|
+
- Bundled internally (no install needed): `@ai-sdk/react`, `ai`
|
|
185
|
+
- Peer deps (optional, install only for that feature): `socket.io-client` (live chat), `recharts` (viz), `@json-render/*` + `zod` (json-render)
|
|
186
|
+
- SSR: all client components emit `"use client"`; safe for Next.js App Router.
|
|
187
|
+
|
|
188
|
+
---
|
|
189
|
+
|
|
190
|
+
## Canonical install + usage (paste-ready)
|
|
191
|
+
|
|
192
|
+
**New project?** Use the scaffolder — it's the lowest-risk path:
|
|
193
|
+
|
|
194
|
+
```bash
|
|
195
|
+
npm create aigentyc-chat@latest my-app -- --template=next --project-id=YOUR_ID
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
**Adding to an existing app:**
|
|
199
|
+
|
|
200
|
+
```bash
|
|
201
|
+
npm install @aigentyc/chat-sdk
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
```tsx
|
|
205
|
+
import { Chat } from "@aigentyc/chat-sdk"
|
|
206
|
+
import "@aigentyc/chat-sdk/theme/styles.css"
|
|
207
|
+
|
|
208
|
+
export default function Page() {
|
|
209
|
+
return (
|
|
210
|
+
<Chat
|
|
211
|
+
projectId="YOUR_PROJECT_ID"
|
|
212
|
+
apiEndpoint="https://api.aigentyc.com"
|
|
213
|
+
apiKey="YOUR_API_KEY"
|
|
214
|
+
/>
|
|
215
|
+
)
|
|
216
|
+
}
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
**Required:** the CSS import. Without it the chat renders unstyled.
|
|
220
|
+
|
|
221
|
+
---
|
|
222
|
+
|
|
223
|
+
## Decision tree: which API to use
|
|
224
|
+
|
|
225
|
+
```
|
|
226
|
+
Need a full chat UI with zero config? → <Chat />
|
|
227
|
+
Need a floating bubble widget? → <ChatWidget />
|
|
228
|
+
Need to customize header/input/messages only? → <Chat slots={{...}} />
|
|
229
|
+
Need custom layout around the chat? → <ChatProvider> + <ChatInterface /> + <ChatInput />
|
|
230
|
+
Need your own UI entirely? → useAigentycChat() (headless)
|
|
231
|
+
Need to override one tool's rendering? → slots.tools[toolName]
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
Don't reach for the headless hook just to change styling — use `theme` or `slots` first.
|
|
235
|
+
|
|
236
|
+
---
|
|
237
|
+
|
|
238
|
+
## Entry points (import from these, never from `dist/`)
|
|
239
|
+
|
|
240
|
+
| Import | What you get |
|
|
241
|
+
| --- | --- |
|
|
242
|
+
| `@aigentyc/chat-sdk` | `Chat`, `ChatWidget`, `ChatProvider` |
|
|
243
|
+
| `@aigentyc/chat-sdk/hooks` | `useAigentycChat`, other hooks |
|
|
244
|
+
| `@aigentyc/chat-sdk/components` | Granular composable chat pieces |
|
|
245
|
+
| `@aigentyc/chat-sdk/ai-elements` | `Message`, `Conversation` primitives |
|
|
246
|
+
| `@aigentyc/chat-sdk/tools` | `ToolRenderer`, `VisualizationRenderer` |
|
|
247
|
+
| `@aigentyc/chat-sdk/json-render` | json-render integration |
|
|
248
|
+
| `@aigentyc/chat-sdk/ui` | shadcn-style primitives |
|
|
249
|
+
| `@aigentyc/chat-sdk/theme` | `ThemeProvider`; CSS at `.../theme/styles.css` |
|
|
250
|
+
| `@aigentyc/chat-sdk/i18n` | `addLanguage`, built-in `en`, `he` |
|
|
251
|
+
| `@aigentyc/chat-sdk/core` | Types, transport, utilities |
|
|
252
|
+
|
|
253
|
+
---
|
|
254
|
+
|
|
255
|
+
## Slots
|
|
256
|
+
|
|
257
|
+
`slots` prop on `<Chat>` / `<ChatWidget>`:
|
|
258
|
+
|
|
259
|
+
- `header`, `welcome`, `message`, `input`, `footer`, `loader`, `suggestions`
|
|
260
|
+
- `tools`: `Record<toolName, ComponentType>` — override per-tool rendering
|
|
261
|
+
|
|
262
|
+
Each slot receives typed props — consult `.d.ts` of the entry points for exact signatures. Don't invent prop names.
|
|
263
|
+
|
|
264
|
+
---
|
|
265
|
+
|
|
266
|
+
## Tool rendering
|
|
267
|
+
|
|
268
|
+
Tool results come back from the backend with a `uiRenderMode`:
|
|
269
|
+
|
|
270
|
+
- `visualization` → recharts (requires `recharts` peer)
|
|
271
|
+
- `json_render` → `@json-render/shadcn` (requires `@json-render/*` + `zod` peers)
|
|
272
|
+
- `legacy` → HTML/CSS template from backend
|
|
273
|
+
- `preset` → built-in renderer
|
|
274
|
+
|
|
275
|
+
If a peer is missing, that tool's UI falls back; install the peer or override via `slots.tools[name]`.
|
|
276
|
+
|
|
277
|
+
---
|
|
278
|
+
|
|
279
|
+
## Theming
|
|
280
|
+
|
|
281
|
+
CSS variables scoped under `[data-aigentyc-chat]`. Two ways to customize:
|
|
282
|
+
|
|
283
|
+
```tsx
|
|
284
|
+
<Chat theme={{ primaryColor: "#3b82f6" }} />
|
|
285
|
+
```
|
|
286
|
+
|
|
287
|
+
or plain CSS targeting `[data-aigentyc-chat]`. Do **not** edit `dist/styles.css` directly.
|
|
288
|
+
|
|
289
|
+
---
|
|
290
|
+
|
|
291
|
+
## i18n
|
|
292
|
+
|
|
293
|
+
Built-in: `en`, `he`. Add more:
|
|
294
|
+
|
|
295
|
+
```tsx
|
|
296
|
+
import { addLanguage } from "@aigentyc/chat-sdk/i18n"
|
|
297
|
+
addLanguage("fr", { welcomeTitle: "Bienvenue" })
|
|
298
|
+
```
|
|
299
|
+
|
|
300
|
+
---
|
|
301
|
+
|
|
302
|
+
## Live chat handoff
|
|
303
|
+
|
|
304
|
+
```tsx
|
|
305
|
+
<Chat enableLiveChat chatServiceUrl="wss://..." />
|
|
306
|
+
```
|
|
307
|
+
|
|
308
|
+
Requires `socket.io-client`. Omit both props for AI-only mode.
|
|
309
|
+
|
|
310
|
+
---
|
|
311
|
+
|
|
312
|
+
## Rules for agents editing consumer projects
|
|
313
|
+
|
|
314
|
+
**Do:**
|
|
315
|
+
- Use the canonical quick start above verbatim for first-time setup.
|
|
316
|
+
- Import CSS once, at the app root or layout file.
|
|
317
|
+
- Prefer `slots` + `theme` before going headless.
|
|
318
|
+
- Use React 19 features (Actions, `use`) — this SDK targets React 19.
|
|
319
|
+
- Check `.d.ts` files under the published package for exact prop types.
|
|
320
|
+
|
|
321
|
+
**Don't:**
|
|
322
|
+
- Don't install React 18 — peer is `>=19`. If the project is on React 18, warn the user and stop.
|
|
323
|
+
- Don't import from `@aigentyc/chat-sdk/dist/*` — those paths are not public API.
|
|
324
|
+
- Don't reimplement message rendering when `slots.message` exists.
|
|
325
|
+
- Don't call the Aigentyc API directly from the client — the SDK owns transport.
|
|
326
|
+
- Don't add `"use client"` to files that wrap the SDK unnecessarily; it's already inside.
|
|
327
|
+
- 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).
|
|
328
|
+
|
|
329
|
+
---
|
|
330
|
+
|
|
331
|
+
## Troubleshooting quick table
|
|
332
|
+
|
|
333
|
+
| Symptom | Likely cause |
|
|
334
|
+
| --- | --- |
|
|
335
|
+
| Unstyled / broken layout | Missing `import "@aigentyc/chat-sdk/theme/styles.css"` |
|
|
336
|
+
| "Cannot find module @ai-sdk/react" | Stale install — delete `node_modules` and reinstall (these are now bundled) |
|
|
337
|
+
| Tool renders blank | Peer for that `uiRenderMode` not installed |
|
|
338
|
+
| 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 |
|
|
339
|
+
| React version error | Upgrade to React 19 |
|
|
340
|
+
|
|
341
|
+
---
|
|
342
|
+
|
|
343
|
+
## Repository layout (for contributors)
|
|
344
|
+
|
|
345
|
+
- `src/` — source; barrel files per entry point
|
|
346
|
+
- `dist/` — build output (tsup); do not edit
|
|
347
|
+
- `stories/` — Storybook
|
|
348
|
+
- `demo/` — local demo app (standalone Vite)
|
|
349
|
+
- `src/styles/index.css` — Tailwind entry compiled to `dist/styles.css`
|
|
350
|
+
|
|
351
|
+
Scripts: `pnpm build`, `pnpm storybook`, `pnpm test`, `pnpm lint`.
|
|
352
|
+
|
|
353
|
+
---
|
|
354
|
+
|
|
355
|
+
## Versioning
|
|
356
|
+
|
|
357
|
+
- Current: `0.1.0` (pre-1.0 — API may shift).
|
|
358
|
+
- Pin exact versions in consumer projects until 1.0.
|
|
359
|
+
|
|
360
|
+
---
|
|
361
|
+
|
|
362
|
+
## llms.txt (overview, recipes, troubleshooting)
|
|
363
|
+
|
|
364
|
+
# @aigentyc/chat-sdk
|
|
365
|
+
|
|
366
|
+
> 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.
|
|
367
|
+
|
|
368
|
+
## Fastest path — scaffold a starter
|
|
369
|
+
|
|
370
|
+
```bash
|
|
371
|
+
npm create aigentyc-chat@latest my-app
|
|
372
|
+
```
|
|
373
|
+
|
|
374
|
+
Prompts for template (`vite-react` or `next`) and `projectId`, then produces a working app. Non-interactive:
|
|
375
|
+
|
|
376
|
+
```bash
|
|
377
|
+
npm create aigentyc-chat@latest my-app -- --template=next --project-id=YOUR_ID
|
|
378
|
+
```
|
|
379
|
+
|
|
380
|
+
## Installation (add to existing app)
|
|
381
|
+
|
|
382
|
+
```bash
|
|
383
|
+
npm install @aigentyc/chat-sdk
|
|
384
|
+
```
|
|
385
|
+
|
|
386
|
+
Only `react>=19` and `react-dom>=19` are required peers. Everything else needed for core chat (streaming, tools, transport) is bundled.
|
|
387
|
+
|
|
388
|
+
Optional peers — install only if you use that feature:
|
|
389
|
+
- `socket.io-client` — live chat handoff
|
|
390
|
+
- `recharts` — visualization tool renderer
|
|
391
|
+
- `@json-render/core @json-render/react @json-render/shadcn zod` — json-render tools
|
|
392
|
+
|
|
393
|
+
## Golden-path quick start
|
|
394
|
+
|
|
395
|
+
```tsx
|
|
396
|
+
import { Chat } from "@aigentyc/chat-sdk"
|
|
397
|
+
import "@aigentyc/chat-sdk/theme/styles.css"
|
|
398
|
+
|
|
399
|
+
export function App() {
|
|
400
|
+
return (
|
|
401
|
+
<Chat
|
|
402
|
+
projectId="your-project-id"
|
|
403
|
+
apiEndpoint="https://app.aigentyc.ai"
|
|
404
|
+
apiKey="your-api-key"
|
|
405
|
+
/>
|
|
406
|
+
)
|
|
407
|
+
}
|
|
408
|
+
```
|
|
409
|
+
|
|
410
|
+
Peer deps required: `react>=19`, `react-dom>=19`. The CSS import is required for theming.
|
|
411
|
+
|
|
412
|
+
## Four levels of control
|
|
413
|
+
|
|
414
|
+
1. **Drop-in** — `<Chat projectId apiEndpoint />`
|
|
415
|
+
2. **Customize** — add `theme`, `slots`, event handlers like `onMessageSent`
|
|
416
|
+
3. **Compose** — `<ChatProvider>` + individual components (`ChatInterface`, `ChatInput`)
|
|
417
|
+
4. **Headless** — `useAigentycChat({ projectId, apiEndpoint })` returns `{ messages, sendMessage, status }`
|
|
418
|
+
|
|
419
|
+
## Package entry points
|
|
420
|
+
|
|
421
|
+
- `@aigentyc/chat-sdk` — `Chat`, `ChatWidget`, `ChatProvider` (main)
|
|
422
|
+
- `@aigentyc/chat-sdk/hooks` — `useAigentycChat` and other hooks
|
|
423
|
+
- `@aigentyc/chat-sdk/components` — granular chat components
|
|
424
|
+
- `@aigentyc/chat-sdk/ai-elements` — `Message`, `Conversation`, primitives
|
|
425
|
+
- `@aigentyc/chat-sdk/tools` — `ToolRenderer`, `VisualizationRenderer`
|
|
426
|
+
- `@aigentyc/chat-sdk/json-render` — json-render integration
|
|
427
|
+
- `@aigentyc/chat-sdk/ui` — shadcn-style UI primitives
|
|
428
|
+
- `@aigentyc/chat-sdk/theme` — `ThemeProvider`; CSS at `@aigentyc/chat-sdk/theme/styles.css`
|
|
429
|
+
- `@aigentyc/chat-sdk/i18n` — `addLanguage`, built-in `en`, `he`
|
|
430
|
+
- `@aigentyc/chat-sdk/core` — types, transport, utils
|
|
431
|
+
|
|
432
|
+
## Slots
|
|
433
|
+
|
|
434
|
+
Replace any UI piece via the `slots` prop:
|
|
435
|
+
|
|
436
|
+
`header`, `welcome`, `message`, `input`, `footer`, `loader`, `suggestions`, `tools` (keyed per tool name).
|
|
437
|
+
|
|
438
|
+
## Tool rendering
|
|
439
|
+
|
|
440
|
+
The Aigentyc backend returns a `uiRenderMode` per tool result. The SDK auto-dispatches:
|
|
441
|
+
- `visualization` → recharts
|
|
442
|
+
- `json_render` → `@json-render/shadcn` component spec
|
|
443
|
+
- `legacy` → custom HTML/CSS template
|
|
444
|
+
- `preset` → built-in renderer
|
|
445
|
+
|
|
446
|
+
Override a specific tool:
|
|
447
|
+
```tsx
|
|
448
|
+
<Chat slots={{ tools: { searchProducts: MyProductGrid } }} />
|
|
449
|
+
```
|
|
450
|
+
|
|
451
|
+
## Theming
|
|
452
|
+
|
|
453
|
+
All tokens are CSS variables scoped under `[data-aigentyc-chat]`. Override via the `theme` prop or plain CSS. No forced branding.
|
|
454
|
+
|
|
455
|
+
## i18n
|
|
456
|
+
|
|
457
|
+
```tsx
|
|
458
|
+
import { addLanguage } from "@aigentyc/chat-sdk/i18n"
|
|
459
|
+
addLanguage("fr", { welcomeTitle: "Bienvenue" })
|
|
460
|
+
```
|
|
461
|
+
|
|
462
|
+
## Live chat
|
|
463
|
+
|
|
464
|
+
```tsx
|
|
465
|
+
<Chat enableLiveChat chatServiceUrl="wss://..." />
|
|
466
|
+
```
|
|
467
|
+
Requires `socket.io-client`.
|
|
468
|
+
|
|
469
|
+
## Next.js / SSR
|
|
470
|
+
|
|
471
|
+
All client components declare `"use client"`. Works in App Router and Pages Router without extra config.
|
|
472
|
+
|
|
473
|
+
## Recipes (copy-paste patterns)
|
|
474
|
+
|
|
475
|
+
### Recipe: brand colors + custom font
|
|
476
|
+
|
|
477
|
+
```tsx
|
|
478
|
+
<Chat
|
|
479
|
+
projectId="..."
|
|
480
|
+
apiEndpoint="https://app.aigentyc.ai"
|
|
481
|
+
theme={{
|
|
482
|
+
primaryColor: "#eb1d22",
|
|
483
|
+
fontFamily: "Inter, sans-serif",
|
|
484
|
+
userBubbleColor: "#eb1d22",
|
|
485
|
+
assistantBubbleColor: "#f5f5f5",
|
|
486
|
+
}}
|
|
487
|
+
/>
|
|
488
|
+
```
|
|
489
|
+
|
|
490
|
+
### Recipe: change welcome message
|
|
491
|
+
|
|
492
|
+
```tsx
|
|
493
|
+
<Chat
|
|
494
|
+
projectId="..."
|
|
495
|
+
apiEndpoint="https://app.aigentyc.ai"
|
|
496
|
+
language="en"
|
|
497
|
+
translations={{
|
|
498
|
+
en: { welcomeTitle: "Hi! How can I help?", welcomeSubtitle: "Ask me anything." },
|
|
499
|
+
}}
|
|
500
|
+
/>
|
|
501
|
+
```
|
|
502
|
+
|
|
503
|
+
### Recipe: track every user message (analytics)
|
|
504
|
+
|
|
505
|
+
```tsx
|
|
506
|
+
<Chat
|
|
507
|
+
projectId="..."
|
|
508
|
+
apiEndpoint="https://app.aigentyc.ai"
|
|
509
|
+
onMessageSent={(m) => analytics.track("chat_message_sent", { id: m.id, content: m.content })}
|
|
510
|
+
onMessageReceived={(m) => analytics.track("chat_message_received", { id: m.id })}
|
|
511
|
+
onError={(err) => Sentry.captureException(err)}
|
|
512
|
+
/>
|
|
513
|
+
```
|
|
514
|
+
|
|
515
|
+
### Recipe: show citation sources under assistant replies
|
|
516
|
+
|
|
517
|
+
```tsx
|
|
518
|
+
<Chat projectId="..." apiEndpoint="https://app.aigentyc.ai" showSources />
|
|
519
|
+
```
|
|
520
|
+
|
|
521
|
+
### Recipe: replace the input bar with a custom one
|
|
522
|
+
|
|
523
|
+
```tsx
|
|
524
|
+
import { Chat } from "@aigentyc/chat-sdk";
|
|
525
|
+
|
|
526
|
+
function MyInput({ DefaultComponent, props }) {
|
|
527
|
+
// Add a button next to the default input, or replace it entirely.
|
|
528
|
+
return (
|
|
529
|
+
<div className="my-composer">
|
|
530
|
+
<DefaultComponent {...props} />
|
|
531
|
+
<button onClick={() => alert("uploaded")}>📎</button>
|
|
532
|
+
</div>
|
|
533
|
+
);
|
|
534
|
+
}
|
|
535
|
+
|
|
536
|
+
<Chat slots={{ input: MyInput }} projectId="..." apiEndpoint="..." />
|
|
537
|
+
```
|
|
538
|
+
|
|
539
|
+
### Recipe: per-tool custom rendering (e.g. product cards)
|
|
540
|
+
|
|
541
|
+
```tsx
|
|
542
|
+
import type { ToolRendererProps } from "@aigentyc/chat-sdk";
|
|
543
|
+
|
|
544
|
+
function ProductGrid({ result }: ToolRendererProps) {
|
|
545
|
+
const products = (result?.data as { items: any[] })?.items ?? [];
|
|
546
|
+
return (
|
|
547
|
+
<div className="grid grid-cols-2 gap-2">
|
|
548
|
+
{products.map((p) => <div key={p.id}>{p.title} — ${p.price}</div>)}
|
|
549
|
+
</div>
|
|
550
|
+
);
|
|
551
|
+
}
|
|
552
|
+
|
|
553
|
+
<Chat
|
|
554
|
+
projectId="..." apiEndpoint="..."
|
|
555
|
+
slots={{ tools: { searchProducts: ProductGrid } }}
|
|
556
|
+
/>
|
|
557
|
+
```
|
|
558
|
+
|
|
559
|
+
### Recipe: Hebrew / RTL
|
|
560
|
+
|
|
561
|
+
```tsx
|
|
562
|
+
<Chat projectId="..." apiEndpoint="..." language="he" />
|
|
563
|
+
```
|
|
564
|
+
RTL direction is set automatically when `language === "he"`.
|
|
565
|
+
|
|
566
|
+
### Recipe: floating widget on an existing site
|
|
567
|
+
|
|
568
|
+
```tsx
|
|
569
|
+
import { ChatWidget } from "@aigentyc/chat-sdk";
|
|
570
|
+
import "@aigentyc/chat-sdk/theme/styles.css";
|
|
571
|
+
|
|
572
|
+
<ChatWidget
|
|
573
|
+
projectId="..."
|
|
574
|
+
apiEndpoint="https://app.aigentyc.ai"
|
|
575
|
+
theme={{ primaryColor: "#eb1d22" }}
|
|
576
|
+
/>
|
|
577
|
+
```
|
|
578
|
+
Drop anywhere in your tree — it portals itself to the bottom-right corner.
|
|
579
|
+
|
|
580
|
+
### Recipe: headless (build your own UI)
|
|
581
|
+
|
|
582
|
+
```tsx
|
|
583
|
+
"use client";
|
|
584
|
+
import { useAigentycChat } from "@aigentyc/chat-sdk/hooks";
|
|
585
|
+
|
|
586
|
+
export default function MyChat() {
|
|
587
|
+
const { messages, status, sendMessage } = useAigentycChat({
|
|
588
|
+
projectId: "...",
|
|
589
|
+
apiEndpoint: "https://app.aigentyc.ai",
|
|
590
|
+
});
|
|
591
|
+
return (
|
|
592
|
+
<>
|
|
593
|
+
{messages.map((m) => <div key={m.id}>{m.role}: {m.content}</div>)}
|
|
594
|
+
<button disabled={status === "streaming"} onClick={() => sendMessage("hello")}>
|
|
595
|
+
Send
|
|
596
|
+
</button>
|
|
597
|
+
</>
|
|
598
|
+
);
|
|
599
|
+
}
|
|
600
|
+
```
|
|
601
|
+
|
|
602
|
+
### Recipe: enable live-chat handoff
|
|
603
|
+
|
|
604
|
+
```tsx
|
|
605
|
+
<Chat
|
|
606
|
+
projectId="..."
|
|
607
|
+
apiEndpoint="https://app.aigentyc.ai"
|
|
608
|
+
apiKey="tyco_pk_..." // required for live chat
|
|
609
|
+
enableLiveChat
|
|
610
|
+
/>
|
|
611
|
+
```
|
|
612
|
+
The AI can hand off to a human operator via the `requestHumanChat` tool. UI surfaces a queue + operator panel automatically.
|
|
613
|
+
|
|
614
|
+
### Recipe: Next.js App Router page
|
|
615
|
+
|
|
616
|
+
```tsx
|
|
617
|
+
// app/chat/page.tsx
|
|
618
|
+
import { Chat } from "@aigentyc/chat-sdk";
|
|
619
|
+
import "@aigentyc/chat-sdk/theme/styles.css"; // import once, in layout.tsx is fine too
|
|
620
|
+
|
|
621
|
+
export default function Page() {
|
|
622
|
+
return (
|
|
623
|
+
<main style={{ height: "100dvh" }}>
|
|
624
|
+
<Chat
|
|
625
|
+
projectId={process.env.NEXT_PUBLIC_AIGENTYC_PROJECT_ID!}
|
|
626
|
+
apiEndpoint={process.env.NEXT_PUBLIC_AIGENTYC_API_ENDPOINT!}
|
|
627
|
+
apiKey={process.env.NEXT_PUBLIC_AIGENTYC_API_KEY}
|
|
628
|
+
/>
|
|
629
|
+
</main>
|
|
630
|
+
);
|
|
631
|
+
}
|
|
632
|
+
```
|
|
633
|
+
|
|
634
|
+
### Recipe: persist conversations (default on)
|
|
635
|
+
|
|
636
|
+
Persistence is on by default. To disable:
|
|
637
|
+
|
|
638
|
+
```tsx
|
|
639
|
+
<Chat projectId="..." apiEndpoint="..." persistMessages={false} />
|
|
640
|
+
```
|
|
641
|
+
|
|
642
|
+
Storage key: `aigentyc-messages-<projectId>` in `localStorage`.
|
|
643
|
+
|
|
644
|
+
### Recipe: programmatically reset the conversation
|
|
645
|
+
|
|
646
|
+
```tsx
|
|
647
|
+
import { useAigentycChat } from "@aigentyc/chat-sdk/hooks";
|
|
648
|
+
|
|
649
|
+
const { newConversation, clearMessages } = useAigentycChat({ projectId: "...", apiEndpoint: "..." });
|
|
650
|
+
|
|
651
|
+
<button onClick={newConversation}>New conversation</button> // new sessionId + clears
|
|
652
|
+
<button onClick={clearMessages}>Clear messages</button> // clears, keeps session
|
|
653
|
+
```
|
|
654
|
+
|
|
655
|
+
## Troubleshooting
|
|
656
|
+
|
|
657
|
+
| Symptom | Likely cause | Fix |
|
|
658
|
+
| --- | --- | --- |
|
|
659
|
+
| Unstyled / broken layout | Missing CSS import | `import "@aigentyc/chat-sdk/theme/styles.css"` |
|
|
660
|
+
| 401 / 403 from API | `apiKey` missing or wrong scope | Create key with `Chat: Full` permission |
|
|
661
|
+
| 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 |
|
|
662
|
+
| `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) |
|
|
663
|
+
| Hebrew text shows LTR | Forgot `language="he"` | Pass `language="he"` to `<Chat>` |
|
|
664
|
+
| Tool result shows raw JSON | Custom tool with no renderer | Add `slots.tools[toolName]` or set `uiRenderMode: "hidden"` server-side |
|
|
665
|
+
| 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 |
|
|
666
|
+
| `searchKnowledgeBase` JSON appears | (it shouldn't — hidden by default since 0.1.3) | Upgrade `@aigentyc/chat-sdk` |
|
|
667
|
+
|
|
668
|
+
## Common pitfalls (do not)
|
|
669
|
+
|
|
670
|
+
- Don't forget the CSS import — unstyled UI is almost always a missing `@aigentyc/chat-sdk/theme/styles.css`.
|
|
671
|
+
- Don't import from `dist/` or deep subpaths — use the public entry points above.
|
|
672
|
+
- Don't wrap in `<Chat>` twice; use `<ChatProvider>` + sub-components for layouts, not nested `<Chat>`.
|
|
673
|
+
- React 18 is not supported — peer is `>=19`.
|
|
674
|
+
- `apiKey` is optional for public/anon projects; required for authenticated ones.
|
|
675
|
+
|
|
676
|
+
## Links
|
|
677
|
+
|
|
678
|
+
- Package: https://www.npmjs.com/package/@aigentyc/chat-sdk
|
|
679
|
+
- Scaffolder: `npm create aigentyc-chat@latest my-app`
|
|
680
|
+
- Dashboard: https://app.aigentyc.ai
|
|
681
|
+
|
|
682
|
+
## Files included in this package
|
|
683
|
+
|
|
684
|
+
- `README.md` — install + quickstart
|
|
685
|
+
- `AGENTS.md` — agent-oriented guide (rules, decision tree, troubleshooting)
|
|
686
|
+
- `llms.txt` — this file (LLM-friendly summary)
|
|
687
|
+
|
|
688
|
+
---
|
|
689
|
+
|
|
690
|
+
## Public API surface (from .d.ts)
|
|
691
|
+
|
|
692
|
+
Each entry below shows the typed exports for one subpath of the package. Use these as the source of truth for prop names, hook return types, and function signatures.
|
|
693
|
+
|
|
694
|
+
|
|
695
|
+
### `@aigentyc/chat-sdk` — Main exports — Chat, ChatWidget, ChatProvider, useAigentycChat
|
|
696
|
+
|
|
697
|
+
```ts
|
|
698
|
+
export { a as ChatConfig, b as ChatEventCallbacks, c as ChatMessage, d as ComponentAction, L as Language, e as LiveChatMessage, f as LiveChatState, Q as QuestionConfig, S as SlotMap, T as ThemeConfig, g as ToolRendererProps, h as ToolResult } from './types-DKJ_-nbG.js';
|
|
699
|
+
|
|
700
|
+
export { L as LiveChatReturn, U as UseAigentycChatOptions, a as UseAigentycChatReturn, u as useAigentycChat, b as useChatContext, c as useLiveChat, d as useSlot, e as useSlots } from './SlotsContext-CBtt36al.js';
|
|
701
|
+
|
|
702
|
+
export { useTheme } from './theme.js';
|
|
703
|
+
|
|
704
|
+
export { useI18n } from './i18n.js';
|
|
705
|
+
|
|
706
|
+
export { Chat, ChatProvider, ChatProviderProps, ChatWidget };
|
|
707
|
+
```
|
|
708
|
+
|
|
709
|
+
|
|
710
|
+
### `@aigentyc/chat-sdk/hooks` — Hooks — useAigentycChat, useChatContext, useTheme, useI18n, useLiveChat, useSlots
|
|
711
|
+
|
|
712
|
+
```ts
|
|
713
|
+
export { L as LiveChatReturn, U as UseAigentycChatOptions, a as UseAigentycChatReturn, u as useAigentycChat, b as useChatContext, c as useLiveChat, d as useSlot, e as useSlots } from './SlotsContext-CBtt36al.js';
|
|
714
|
+
|
|
715
|
+
export { useTheme } from './theme.js';
|
|
716
|
+
|
|
717
|
+
export { useI18n } from './i18n.js';
|
|
718
|
+
|
|
719
|
+
export { u as useInteractionTracker } from './interaction-tracker-D9P1Oq4j.js';
|
|
720
|
+
|
|
721
|
+
export { useImageLoader, useIsMobile, useMultiImageLoader, useMultiOrderTracking, useOrderTracking, usePagination, usePreviewEmbed, useSliderDrag };
|
|
722
|
+
```
|
|
723
|
+
|
|
724
|
+
|
|
725
|
+
### `@aigentyc/chat-sdk/components` — Granular components — ChatInterface, ChatInput, ChatHeader, etc.
|
|
726
|
+
|
|
727
|
+
```ts
|
|
728
|
+
export { CartDrawer, ChatDrawer, ChatFooter, ChatHeader, ChatInput, ChatInputWithAttachments, ChatInterface, FloatingButton, LiveChatHeader, LiveChatPanel, LiveChatQueueBanner, PreviewEmbedPanel, QuickQuestions, SatisfactionRating, SystemMessage, VisitorIdentityForm, WelcomePage };
|
|
729
|
+
```
|
|
730
|
+
|
|
731
|
+
|
|
732
|
+
### `@aigentyc/chat-sdk/tools` — Tool rendering — ToolRenderer, SearchKnowledgeBaseRenderer
|
|
733
|
+
|
|
734
|
+
```ts
|
|
735
|
+
export { d as ComponentAction, h as ToolResult } from './types-DKJ_-nbG.js';
|
|
736
|
+
|
|
737
|
+
export { J as JsonRenderResult } from './JsonRenderResult-Ftw4AKwb.js';
|
|
738
|
+
|
|
739
|
+
export { ComponentRenderer, SearchKnowledgeBaseRenderer, ToolRenderer, ToolRendererProps, VisualizationRenderer };
|
|
740
|
+
```
|
|
741
|
+
|
|
742
|
+
|
|
743
|
+
### `@aigentyc/chat-sdk/theme` — Theming — ThemeProvider
|
|
744
|
+
|
|
745
|
+
```ts
|
|
746
|
+
export { T as ThemeConfig } from './types-DKJ_-nbG.js';
|
|
747
|
+
|
|
748
|
+
export { ThemeProvider, useTheme };
|
|
749
|
+
```
|
|
750
|
+
|
|
751
|
+
|
|
752
|
+
### `@aigentyc/chat-sdk/i18n` — Internationalization — addLanguage
|
|
753
|
+
|
|
754
|
+
```ts
|
|
755
|
+
export { L as Language } from './types-DKJ_-nbG.js';
|
|
756
|
+
|
|
757
|
+
export { I18nProvider, type I18nProviderProps, type TranslationKeys, type TranslationMap, addLanguage, isRTL, useI18n };
|
|
758
|
+
```
|
|
759
|
+
|
|
760
|
+
|
|
761
|
+
### `@aigentyc/chat-sdk/core` — Core types and utilities
|
|
762
|
+
|
|
763
|
+
```ts
|
|
764
|
+
export { b as ChatEventCallbacks, c as ChatMessage, C as ChatProviderProps, d as ComponentAction, L as Language, e as LiveChatMessage, f as LiveChatState, Q as QuestionConfig, S as SlotMap, i as SlotProps, T as ThemeConfig, g as ToolRendererProps, h as ToolResult } from './types-DKJ_-nbG.js';
|
|
765
|
+
|
|
766
|
+
export { I as InteractionMetadata, a as InteractionType, T as TrackInteractionParams, U as UseInteractionTrackerOptions, g as generateSessionId, u as useInteractionTracker } from './interaction-tracker-D9P1Oq4j.js';
|
|
767
|
+
|
|
768
|
+
export { ChatConfig, type CreateChatTransportOptions, INTERNAL_MESSAGE_PREFIX, type LiveChatConfig, type LiveChatEventMap, LiveChatTransport, type StoredMessage, USER_TYPES, USER_TYPE_LABEL_MAP, type UserType, addUtmParams, clearMessages, cn, createChatTransport, createChatTransportSync, debouncedSaveMessages, isInternalMessage, isSsr, loadMessages, minifyToolOutput, prepareMessages, processImagesInHtml, pruneExpiredMessages, saveMessages };
|
|
769
|
+
```
|