chatgsd 0.1.0 → 0.3.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/README.md CHANGED
@@ -27,15 +27,35 @@ function App() {
27
27
 
28
28
  ## How It Works
29
29
 
30
- Your backend streams responses to the chat. When the AI wants to trigger an action, it includes a tool call at the end of its response:
30
+ Your backend streams responses to the chat. ChatGSD supports two formats:
31
31
 
32
+ ### SSE Format (recommended)
33
+
34
+ Server-Sent Events with JSON payloads. Auto-detected via `Content-Type: text/event-stream`.
35
+
36
+ ```
37
+ data: {"type": "text", "content": "Let me "}
38
+ data: {"type": "text", "content": "show you "}
39
+ data: {"type": "text", "content": "available times."}
40
+ data: {"type": "tool_call", "name": "show_slots", "args": {}}
41
+ data: {"type": "done"}
32
42
  ```
33
- Great, let me show you the available times.
43
+
44
+ ### Plain Text Format
45
+
46
+ Raw streaming text with tool calls embedded. Falls back to this when not SSE.
47
+
48
+ ```
49
+ Let me show you available times.
34
50
 
35
51
  [TOOL:show_slots]
36
52
  ```
37
53
 
38
- The component parses this, executes the corresponding tool handler, and renders the result inline in the chat.
54
+ Or with arguments:
55
+
56
+ ```
57
+ [TOOL:show_slots({"date": "2024-01-15"})]
58
+ ```
39
59
 
40
60
  ## Tools
41
61
 
@@ -76,17 +96,6 @@ const tools: Record<string, Tool> = {
76
96
  <ChatGSD endpoint="/api/chat" tools={tools} />
77
97
  ```
78
98
 
79
- ### Tool Format
80
-
81
- The AI can invoke tools in two ways:
82
-
83
- ```
84
- [TOOL:name]
85
- [TOOL:name({"key": "value"})]
86
- ```
87
-
88
- Arguments are parsed as JSON and passed to the handler.
89
-
90
99
  ### Tool Configuration
91
100
 
92
101
  | Property | Type | Description |
@@ -106,6 +115,35 @@ interface ToolResult {
106
115
  }
107
116
  ```
108
117
 
118
+ ### ToolCallContext
119
+
120
+ The render callbacks receive full context about the tool call:
121
+
122
+ ```ts
123
+ interface ToolCallContext {
124
+ name: string; // Tool name being called
125
+ args: Record<string, unknown>; // Arguments passed to tool
126
+ result?: ToolResult; // Result (only in success/error states)
127
+ }
128
+ ```
129
+
130
+ Example with context:
131
+
132
+ ```tsx
133
+ const tools: Record<string, Tool> = {
134
+ show_slots: {
135
+ handler: async (args) => { /* ... */ },
136
+ renderCalling: (ctx) => <div>Loading slots for {ctx.args.date}...</div>,
137
+ renderSuccess: (ctx) => (
138
+ <div>
139
+ <h3>Showing: {ctx.name}</h3>
140
+ {ctx.result?.message}
141
+ </div>
142
+ ),
143
+ },
144
+ };
145
+ ```
146
+
109
147
  ## Props
110
148
 
111
149
  | Prop | Type | Default | Description |
@@ -117,9 +155,59 @@ interface ToolResult {
117
155
  | `brandName` | `string` | `"assistant"` | Name shown in chat |
118
156
  | `initialMessage` | `string` | `"How can I help?"` | First message displayed |
119
157
  | `className` | `string` | `""` | Additional CSS class |
158
+ | `format` | `"auto" \| "sse" \| "text"` | `"auto"` | Stream format (auto-detects from Content-Type) |
120
159
  | `onMessagesChange` | `(messages) => void` | - | Called when messages update |
121
160
  | `onComplete` | `(messages) => void` | - | Called when conversation ends |
122
161
 
162
+ ## Programmatic Control
163
+
164
+ Use a ref to control the chat programmatically:
165
+
166
+ ```tsx
167
+ import { useRef } from "react";
168
+ import { ChatGSD, ChatGSDHandle } from "chatgsd";
169
+
170
+ function App() {
171
+ const chatRef = useRef<ChatGSDHandle>(null);
172
+
173
+ const handleExternalSubmit = async () => {
174
+ // Submit a message from outside the chat
175
+ await chatRef.current?.submitMessage("Book for tomorrow at 2pm");
176
+ };
177
+
178
+ return (
179
+ <>
180
+ <ChatGSD ref={chatRef} endpoint="/api/chat" tools={tools} />
181
+ <button onClick={handleExternalSubmit}>Quick Book</button>
182
+ </>
183
+ );
184
+ }
185
+ ```
186
+
187
+ ### ChatGSDHandle Methods
188
+
189
+ | Method | Description |
190
+ |--------|-------------|
191
+ | `submit()` | Submit current input field content |
192
+ | `submitMessage(content)` | Submit a specific message (bypasses input field) |
193
+ | `getMessages()` | Get current message history |
194
+ | `focus()` | Focus the input field |
195
+
196
+ ## ChatMessage Type
197
+
198
+ Messages include an auto-generated `id` field:
199
+
200
+ ```ts
201
+ type ChatMessage = {
202
+ id: string; // Auto-generated unique ID
203
+ role: "system" | "user";
204
+ content: string;
205
+ timestamp: Date;
206
+ };
207
+ ```
208
+
209
+ When creating messages externally (e.g., for initial state), you'll need to provide the `id` field yourself. Use any unique string generator.
210
+
123
211
  ## Backend API
124
212
 
125
213
  The component expects a streaming endpoint that accepts:
@@ -130,43 +218,73 @@ The component expects a streaming endpoint that accepts:
130
218
  messages: Array<{ role: "system" | "user", content: string }>,
131
219
  context: Record<string, unknown>
132
220
  }
133
-
134
- // Response: streaming text, optionally ending with [TOOL:name]
135
221
  ```
136
222
 
137
- ### Example (Node.js)
223
+ ### SSE Response (Node.js)
138
224
 
139
225
  ```ts
140
226
  app.post("/api/chat", async (req, res) => {
141
227
  const { messages, context } = req.body;
142
228
 
229
+ res.setHeader("Content-Type", "text/event-stream");
230
+ res.setHeader("Cache-Control", "no-cache");
231
+ res.setHeader("Connection", "keep-alive");
232
+
143
233
  const stream = await openai.chat.completions.create({
144
234
  model: "gpt-4",
145
235
  stream: true,
146
236
  messages: [
147
237
  {
148
238
  role: "system",
149
- content: `You are a helpful assistant. You have these tools available:
150
- - [TOOL:show_slots] - Show available meeting times
151
- - [TOOL:submit_inquiry] - Submit the inquiry (use when you have enough info)
239
+ content: `You are a helpful assistant. Available tools:
240
+ - show_slots: Show available meeting times
241
+ - submit_inquiry: Submit the inquiry
152
242
 
153
- When you want to use a tool, end your message with the tool call.`
243
+ When you want to use a tool, I'll signal it in the stream.`
154
244
  },
155
- ...messages.map(m => ({ role: m.role, content: m.content }))
245
+ ...messages
156
246
  ],
157
247
  });
158
248
 
159
- res.setHeader("Content-Type", "text/plain");
160
-
161
249
  for await (const chunk of stream) {
162
250
  const text = chunk.choices[0]?.delta?.content || "";
163
- res.write(text);
251
+ if (text) {
252
+ res.write(`data: ${JSON.stringify({ type: "text", content: text })}\n\n`);
253
+ }
164
254
  }
165
-
255
+
256
+ // Send tool call if needed (based on your logic)
257
+ res.write(`data: ${JSON.stringify({ type: "tool_call", name: "show_slots", args: {} })}\n\n`);
258
+ res.write(`data: ${JSON.stringify({ type: "done" })}\n\n`);
166
259
  res.end();
167
260
  });
168
261
  ```
169
262
 
263
+ ### With Vercel AI SDK
264
+
265
+ ```ts
266
+ import { streamText, tool } from "ai";
267
+ import { openai } from "@ai-sdk/openai";
268
+
269
+ export async function POST(req: Request) {
270
+ const { messages, context } = await req.json();
271
+
272
+ const result = await streamText({
273
+ model: openai("gpt-4"),
274
+ messages,
275
+ tools: {
276
+ show_slots: tool({
277
+ description: "Show available meeting times",
278
+ parameters: z.object({ date: z.string().optional() }),
279
+ }),
280
+ },
281
+ });
282
+
283
+ // AI SDK streams in a compatible format
284
+ return result.toDataStreamResponse();
285
+ }
286
+ ```
287
+
170
288
  ## Styling
171
289
 
172
290
  Import the default styles:
@@ -192,6 +310,54 @@ Customize with CSS variables:
192
310
 
193
311
  Or write your own styles targeting `.chatgsd-*` classes.
194
312
 
313
+ ### Dark Mode
314
+
315
+ By default, ChatGSD respects `prefers-color-scheme: dark`. To control this:
316
+
317
+ **Opt out of automatic dark mode:**
318
+ ```tsx
319
+ // Add .chatgsd-light-only to any parent element
320
+ <div className="chatgsd-light-only">
321
+ <ChatGSD ... />
322
+ </div>
323
+ ```
324
+
325
+ **Force dark mode manually:**
326
+ ```tsx
327
+ // Add .chatgsd-dark to the component or a parent
328
+ <ChatGSD className="chatgsd-dark" ... />
329
+ ```
330
+
331
+ **Override variables after import:**
332
+ ```css
333
+ /* Your app's CSS - load after chatgsd/styles.css */
334
+ :root {
335
+ --chatgsd-bg: #your-color;
336
+ }
337
+ ```
338
+
339
+ ## Framework Notes
340
+
341
+ ### Laravel / Rails (CSRF Tokens)
342
+
343
+ Pass CSRF tokens via the `headers` prop:
344
+
345
+ ```tsx
346
+ // Laravel
347
+ <ChatGSD
348
+ headers={{
349
+ "X-CSRF-TOKEN": document.querySelector('meta[name="csrf-token"]')?.getAttribute("content") || "",
350
+ }}
351
+ />
352
+
353
+ // Rails
354
+ <ChatGSD
355
+ headers={{
356
+ "X-CSRF-Token": document.querySelector('meta[name="csrf-token"]')?.getAttribute("content") || "",
357
+ }}
358
+ />
359
+ ```
360
+
195
361
  ## Example
196
362
 
197
363
  Run the example app:
package/dist/index.cjs CHANGED
@@ -30,8 +30,73 @@ var import_jsx_runtime = require("react/jsx-runtime");
30
30
  function generateId() {
31
31
  return Math.random().toString(36).substring(2, 11);
32
32
  }
33
- function parseToolCall(content) {
34
- const match = content.match(/\[TOOL:(\w+)(?:\((\{.*\})\))?\]$/);
33
+ function parseSSELine(line) {
34
+ if (!line.startsWith("data: ")) return null;
35
+ const data = line.slice(6);
36
+ if (data === "[DONE]") return { type: "done" };
37
+ try {
38
+ const parsed = JSON.parse(data);
39
+ if (parsed.type === "text-delta" || parsed.type === "text_delta") {
40
+ return { type: "text", content: parsed.textDelta ?? parsed.text_delta ?? "" };
41
+ }
42
+ if (parsed.type === "tool-call" || parsed.type === "tool_call") {
43
+ return {
44
+ type: "tool_call",
45
+ name: parsed.toolName ?? parsed.tool_name ?? parsed.name,
46
+ args: parsed.args ?? parsed.arguments ?? {}
47
+ };
48
+ }
49
+ if (parsed.type === "text") {
50
+ return { type: "text", content: parsed.content ?? "" };
51
+ }
52
+ if (parsed.type === "tool_call") {
53
+ return { type: "tool_call", name: parsed.name, args: parsed.args ?? {} };
54
+ }
55
+ if (parsed.type === "error") {
56
+ return { type: "error", message: parsed.message ?? "Unknown error" };
57
+ }
58
+ if (parsed.type === "done") {
59
+ return { type: "done" };
60
+ }
61
+ if (parsed.choices?.[0]?.delta?.content) {
62
+ return { type: "text", content: parsed.choices[0].delta.content };
63
+ }
64
+ return null;
65
+ } catch {
66
+ return null;
67
+ }
68
+ }
69
+ function parseAISDKLine(line) {
70
+ const match = line.match(/^(\d+):(.+)$/);
71
+ if (!match) return null;
72
+ const [, typeCode, data] = match;
73
+ try {
74
+ switch (typeCode) {
75
+ case "0": {
76
+ const text = JSON.parse(data);
77
+ return { type: "text", content: text };
78
+ }
79
+ case "8": {
80
+ const parsed = JSON.parse(data);
81
+ return {
82
+ type: "tool_call",
83
+ name: parsed.toolName ?? parsed.name,
84
+ args: parsed.args ?? {}
85
+ };
86
+ }
87
+ case "d":
88
+ case "e": {
89
+ return { type: "done" };
90
+ }
91
+ default:
92
+ return null;
93
+ }
94
+ } catch {
95
+ return null;
96
+ }
97
+ }
98
+ function parseToolCallFromText(content) {
99
+ const match = content.match(/\[TOOL:(\w+)(?:\((\{.*\})\))?\]\s*$/);
35
100
  if (!match) return null;
36
101
  const name = match[1];
37
102
  let args = {};
@@ -43,7 +108,7 @@ function parseToolCall(content) {
43
108
  }
44
109
  return { name, args };
45
110
  }
46
- function ChatGSD({
111
+ function ChatGSDInner({
47
112
  initialMessage = "How can I help you today?",
48
113
  onMessagesChange,
49
114
  tools = {},
@@ -52,8 +117,9 @@ function ChatGSD({
52
117
  context = {},
53
118
  brandName = "assistant",
54
119
  className = "",
55
- onComplete
56
- }) {
120
+ onComplete,
121
+ format = "auto"
122
+ }, ref) {
57
123
  const [messages, setMessages] = (0, import_react.useState)([
58
124
  {
59
125
  id: generateId(),
@@ -97,34 +163,105 @@ function ChatGSD({
97
163
  console.warn(`Unknown tool: ${toolName}`);
98
164
  return;
99
165
  }
100
- setActiveTool({ name: toolName, status: "calling" });
166
+ setActiveTool({ name: toolName, args, status: "calling" });
101
167
  await new Promise((resolve) => {
102
168
  toolTimeoutRef.current = setTimeout(resolve, 800);
103
169
  });
104
170
  try {
105
171
  const result = await tool.handler(args, currentMessages);
106
- setActiveTool({ name: toolName, status: result.success ? "success" : "error", result });
172
+ setActiveTool({ name: toolName, args, status: result.success ? "success" : "error", result });
107
173
  if (tool.terminal) {
108
174
  setConversationEnded(true);
109
175
  onComplete?.(currentMessages);
110
176
  }
111
177
  } catch (err) {
112
178
  const message = err instanceof Error ? err.message : "Tool execution failed";
113
- setActiveTool({ name: toolName, status: "error", result: { success: false, message } });
179
+ setActiveTool({ name: toolName, args, status: "error", result: { success: false, message } });
114
180
  }
115
181
  },
116
182
  [tools, onComplete]
117
183
  );
184
+ const parseLine = (0, import_react.useCallback)((line) => {
185
+ return parseSSELine(line) ?? parseAISDKLine(line);
186
+ }, []);
187
+ const processSSEStream = (0, import_react.useCallback)(
188
+ async (reader, onText) => {
189
+ const decoder = new TextDecoder();
190
+ let buffer = "";
191
+ let toolCall = null;
192
+ while (true) {
193
+ const { done, value } = await reader.read();
194
+ if (done) break;
195
+ buffer += decoder.decode(value, { stream: true });
196
+ const lines = buffer.split("\n");
197
+ buffer = lines.pop() || "";
198
+ for (const line of lines) {
199
+ const trimmed = line.trim();
200
+ if (!trimmed) continue;
201
+ const event = parseLine(trimmed);
202
+ if (!event) continue;
203
+ if (event.type === "text") {
204
+ onText(event.content);
205
+ } else if (event.type === "tool_call") {
206
+ toolCall = event;
207
+ } else if (event.type === "done") {
208
+ return toolCall;
209
+ }
210
+ }
211
+ }
212
+ if (buffer.trim()) {
213
+ const event = parseLine(buffer.trim());
214
+ if (event?.type === "tool_call") {
215
+ toolCall = event;
216
+ }
217
+ }
218
+ return toolCall;
219
+ },
220
+ [parseLine]
221
+ );
222
+ const processTextStream = (0, import_react.useCallback)(
223
+ async (reader, onText) => {
224
+ const decoder = new TextDecoder();
225
+ let fullContent = "";
226
+ while (true) {
227
+ const { done, value } = await reader.read();
228
+ if (done) break;
229
+ const chunk = decoder.decode(value, { stream: true });
230
+ fullContent += chunk;
231
+ const displayContent = fullContent.replace(/\n?\[TOOL:\w+(?:\(\{.*\}\))?\]\s*$/, "");
232
+ onText(displayContent);
233
+ }
234
+ const toolCall = parseToolCallFromText(fullContent);
235
+ if (toolCall) {
236
+ return { type: "tool_call", name: toolCall.name, args: toolCall.args };
237
+ }
238
+ return null;
239
+ },
240
+ []
241
+ );
118
242
  const fetchAIResponse = (0, import_react.useCallback)(
119
243
  async (updatedMessages) => {
120
244
  setIsLoading(true);
245
+ const aiMessageId = generateId();
121
246
  const aiMessage = {
122
- id: generateId(),
247
+ id: aiMessageId,
123
248
  role: "system",
124
249
  content: "",
125
250
  timestamp: /* @__PURE__ */ new Date()
126
251
  };
127
252
  setMessages((prev) => [...prev, aiMessage]);
253
+ let currentContent = "";
254
+ const updateContent = (content) => {
255
+ currentContent = content;
256
+ setMessages((prev) => {
257
+ const updated = [...prev];
258
+ const msgIndex = updated.findIndex((m) => m.id === aiMessageId);
259
+ if (msgIndex !== -1) {
260
+ updated[msgIndex] = { ...updated[msgIndex], content };
261
+ }
262
+ return updated;
263
+ });
264
+ };
128
265
  try {
129
266
  const res = await fetch(endpoint, {
130
267
  method: "POST",
@@ -140,42 +277,43 @@ function ChatGSD({
140
277
  context
141
278
  })
142
279
  });
143
- if (res.ok && res.body) {
144
- const reader = res.body.getReader();
145
- const decoder = new TextDecoder();
146
- let fullContent = "";
147
- while (true) {
148
- const { done, value } = await reader.read();
149
- if (done) break;
150
- const chunk = decoder.decode(value, { stream: true });
151
- fullContent += chunk;
152
- const displayContent = fullContent.replace(/\n?\[TOOL:\w+(?:\(\{.*\}\))?\]$/, "");
153
- setMessages((prev) => {
154
- const updated = [...prev];
155
- const last = updated[updated.length - 1];
156
- if (last.role === "system") {
157
- last.content = displayContent;
158
- }
159
- return updated;
160
- });
161
- }
162
- const toolCall = parseToolCall(fullContent);
163
- if (toolCall) {
164
- const finalMessages = [...updatedMessages, {
165
- id: generateId(),
280
+ if (!res.ok || !res.body) {
281
+ throw new Error("Failed to fetch response");
282
+ }
283
+ const contentType = res.headers.get("Content-Type") || "";
284
+ const reader = res.body.getReader();
285
+ let useSSE = format === "sse";
286
+ if (format === "auto") {
287
+ useSSE = contentType.includes("text/event-stream");
288
+ }
289
+ let toolCallEvent = null;
290
+ if (useSSE) {
291
+ toolCallEvent = await processSSEStream(reader, (text) => {
292
+ currentContent += text;
293
+ updateContent(currentContent);
294
+ });
295
+ } else {
296
+ toolCallEvent = await processTextStream(reader, updateContent);
297
+ }
298
+ if (toolCallEvent?.type === "tool_call") {
299
+ const finalMessages = [
300
+ ...updatedMessages,
301
+ {
302
+ id: aiMessageId,
166
303
  role: "system",
167
- content: fullContent.replace(/\n?\[TOOL:\w+(?:\(\{.*\}\))?\]$/, ""),
304
+ content: currentContent,
168
305
  timestamp: /* @__PURE__ */ new Date()
169
- }];
170
- await executeTool(toolCall.name, toolCall.args, finalMessages);
171
- }
306
+ }
307
+ ];
308
+ await executeTool(toolCallEvent.name, toolCallEvent.args, finalMessages);
172
309
  }
173
- } catch {
310
+ } catch (err) {
311
+ console.error("Chat error:", err);
174
312
  } finally {
175
313
  setIsLoading(false);
176
314
  }
177
315
  },
178
- [endpoint, headers, context, executeTool]
316
+ [endpoint, headers, context, format, processSSEStream, processTextStream, executeTool]
179
317
  );
180
318
  const handleSend = (0, import_react.useCallback)(async () => {
181
319
  if (!input.trim() || isLoading || conversationEnded) return;
@@ -210,13 +348,36 @@ function ChatGSD({
210
348
  a.click();
211
349
  URL.revokeObjectURL(url);
212
350
  }, [messages, brandName]);
351
+ const submitMessage = (0, import_react.useCallback)(
352
+ async (content) => {
353
+ if (!content.trim() || isLoading || conversationEnded) return;
354
+ const newMessage = {
355
+ id: generateId(),
356
+ role: "user",
357
+ content: content.trim(),
358
+ timestamp: /* @__PURE__ */ new Date()
359
+ };
360
+ const updated = [...messages, newMessage];
361
+ setMessages(updated);
362
+ onMessagesChange?.(updated);
363
+ await fetchAIResponse(updated);
364
+ },
365
+ [isLoading, conversationEnded, messages, onMessagesChange, fetchAIResponse]
366
+ );
367
+ (0, import_react.useImperativeHandle)(ref, () => ({
368
+ submit: handleSend,
369
+ submitMessage,
370
+ getMessages: () => messages,
371
+ focus: () => inputRef.current?.focus()
372
+ }), [handleSend, submitMessage, messages]);
213
373
  const renderToolStatus = () => {
214
374
  if (!activeTool) return null;
215
375
  const tool = tools[activeTool.name];
216
- const { name, status, result } = activeTool;
376
+ const { name, args, status, result } = activeTool;
377
+ const ctx = { name, args, result };
217
378
  if (status === "calling") {
218
379
  if (tool?.renderCalling) {
219
- return tool.renderCalling();
380
+ return tool.renderCalling(ctx);
220
381
  }
221
382
  return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className: "chatgsd-status-calling", children: [
222
383
  /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { className: "chatgsd-message-prefix", children: "[tool]" }),
@@ -230,8 +391,8 @@ function ChatGSD({
230
391
  ] });
231
392
  }
232
393
  if (status === "success") {
233
- if (tool?.renderSuccess && result) {
234
- return tool.renderSuccess(result);
394
+ if (tool?.renderSuccess) {
395
+ return tool.renderSuccess(ctx);
235
396
  }
236
397
  return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className: "chatgsd-status-success", children: [
237
398
  /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { className: "chatgsd-message-prefix", children: "[tool]" }),
@@ -244,8 +405,8 @@ function ChatGSD({
244
405
  ] });
245
406
  }
246
407
  if (status === "error") {
247
- if (tool?.renderError && result) {
248
- return tool.renderError(result);
408
+ if (tool?.renderError) {
409
+ return tool.renderError(ctx);
249
410
  }
250
411
  return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className: "chatgsd-status-error", children: [
251
412
  /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { className: "chatgsd-message-prefix", children: "[tool]" }),
@@ -322,6 +483,7 @@ function ChatGSD({
322
483
  ] }) })
323
484
  ] });
324
485
  }
486
+ var ChatGSD = (0, import_react.forwardRef)(ChatGSDInner);
325
487
  // Annotate the CommonJS export names for ESM import in node:
326
488
  0 && (module.exports = {
327
489
  ChatGSD