@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.
Files changed (45) hide show
  1. package/AGENTS.md +189 -0
  2. package/bin/doctor.mjs +255 -0
  3. package/dist/ai-elements.cjs +119 -162
  4. package/dist/ai-elements.cjs.map +1 -1
  5. package/dist/ai-elements.js +5 -60
  6. package/dist/ai-elements.js.map +1 -1
  7. package/dist/{chunk-PKGD6CTD.js → chunk-2677FDTG.js} +107 -59
  8. package/dist/chunk-2677FDTG.js.map +1 -0
  9. package/dist/{chunk-42ARGQXE.js → chunk-7L4FS6G7.js} +7 -3
  10. package/dist/chunk-7L4FS6G7.js.map +1 -0
  11. package/dist/{chunk-VS3NZ7FX.js → chunk-A7PCSWIK.js} +60 -5
  12. package/dist/chunk-A7PCSWIK.js.map +1 -0
  13. package/dist/{chunk-WZLWAVSS.cjs → chunk-C24QG43M.cjs} +10 -2
  14. package/dist/chunk-C24QG43M.cjs.map +1 -0
  15. package/dist/{chunk-NW2ESHRV.js → chunk-KVEJAPWA.js} +4 -8
  16. package/dist/chunk-KVEJAPWA.js.map +1 -0
  17. package/dist/{chunk-X5YEOOPK.cjs → chunk-QDFPJJ5Y.cjs} +5 -13
  18. package/dist/chunk-QDFPJJ5Y.cjs.map +1 -0
  19. package/dist/{chunk-FQN6OBGN.cjs → chunk-RTVEBPAJ.cjs} +63 -4
  20. package/dist/chunk-RTVEBPAJ.cjs.map +1 -0
  21. package/dist/{chunk-IWIGM3RY.cjs → chunk-WQARQ2FJ.cjs} +109 -61
  22. package/dist/chunk-WQARQ2FJ.cjs.map +1 -0
  23. package/dist/components.cjs +14 -14
  24. package/dist/components.d.cts +5 -0
  25. package/dist/components.d.ts +5 -0
  26. package/dist/components.js +4 -4
  27. package/dist/index.cjs +14 -12
  28. package/dist/index.cjs.map +1 -1
  29. package/dist/index.d.cts +8 -1
  30. package/dist/index.d.ts +8 -1
  31. package/dist/index.js +8 -6
  32. package/dist/index.js.map +1 -1
  33. package/dist/llms-full.txt +769 -0
  34. package/dist/ui.cjs +51 -51
  35. package/dist/ui.js +2 -2
  36. package/llms.txt +323 -0
  37. package/package.json +10 -2
  38. package/dist/chunk-42ARGQXE.js.map +0 -1
  39. package/dist/chunk-FQN6OBGN.cjs.map +0 -1
  40. package/dist/chunk-IWIGM3RY.cjs.map +0 -1
  41. package/dist/chunk-NW2ESHRV.js.map +0 -1
  42. package/dist/chunk-PKGD6CTD.js.map +0 -1
  43. package/dist/chunk-VS3NZ7FX.js.map +0 -1
  44. package/dist/chunk-WZLWAVSS.cjs.map +0 -1
  45. 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
+ ```