@syncagent/react 0.1.0 → 0.1.2
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 +169 -26
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# @syncagent/react
|
|
2
2
|
|
|
3
|
-
React SDK for SyncAgent — drop-in AI database chat widget
|
|
3
|
+
React SDK for [SyncAgent](https://syncagent.dev) — drop-in AI database chat widget and hooks.
|
|
4
4
|
|
|
5
5
|
## Install
|
|
6
6
|
|
|
@@ -8,7 +8,9 @@ React SDK for SyncAgent — drop-in AI database chat widget & hooks.
|
|
|
8
8
|
npm install @syncagent/react @syncagent/js
|
|
9
9
|
```
|
|
10
10
|
|
|
11
|
-
## Quick Start
|
|
11
|
+
## Quick Start — Drop-in Widget
|
|
12
|
+
|
|
13
|
+
The fastest way to add an AI assistant to your app:
|
|
12
14
|
|
|
13
15
|
```tsx
|
|
14
16
|
import { SyncAgentChat } from "@syncagent/react";
|
|
@@ -18,7 +20,6 @@ export default function App() {
|
|
|
18
20
|
<SyncAgentChat
|
|
19
21
|
config={{
|
|
20
22
|
apiKey: "sa_your_api_key",
|
|
21
|
-
baseUrl: "https://your-syncagent-instance.com",
|
|
22
23
|
connectionString: process.env.DATABASE_URL,
|
|
23
24
|
}}
|
|
24
25
|
/>
|
|
@@ -26,44 +27,186 @@ export default function App() {
|
|
|
26
27
|
}
|
|
27
28
|
```
|
|
28
29
|
|
|
29
|
-
|
|
30
|
+
This renders a floating chat button (bottom-right) that opens a chat panel. Your database URL is sent at runtime and never stored on SyncAgent servers.
|
|
31
|
+
|
|
32
|
+
## `<SyncAgentChat>` Props
|
|
33
|
+
|
|
34
|
+
| Prop | Type | Default | Description |
|
|
35
|
+
| ---------------- | --------------------------------- | ------------------------ | ---------------------------------------- |
|
|
36
|
+
| `config` | `SyncAgentConfig` | Required* | API key, connection string, tools |
|
|
37
|
+
| `mode` | `"floating" \| "inline"` | `"floating"` | Floating FAB or embedded inline panel |
|
|
38
|
+
| `position` | `"bottom-right" \| "bottom-left"` | `"bottom-right"` | FAB position (floating mode only) |
|
|
39
|
+
| `defaultOpen` | `boolean` | `false` | Start with the panel open |
|
|
40
|
+
| `title` | `string` | `"✨ AI Assistant"` | Header title |
|
|
41
|
+
| `placeholder` | `string` | `"Ask about your data..."` | Input placeholder text |
|
|
42
|
+
| `welcomeMessage` | `string` | `"Ask me anything..."` | Message shown when chat is empty |
|
|
43
|
+
| `accentColor` | `string` | `"#10b981"` | Brand color for header, FAB, send button |
|
|
44
|
+
| `className` | `string` | — | CSS class on the panel container |
|
|
45
|
+
| `style` | `CSSProperties` | — | Inline styles on the panel container |
|
|
46
|
+
|
|
47
|
+
*`config` is required unless you wrap in `<SyncAgentProvider>`.
|
|
48
|
+
|
|
49
|
+
### `SyncAgentConfig`
|
|
50
|
+
|
|
51
|
+
| Option | Type | Required | Description |
|
|
52
|
+
| ------------------ | -------------------------------- | -------- | ------------------------------------------------ |
|
|
53
|
+
| `apiKey` | `string` | ✅ | Your SyncAgent API key (`sa_...`) |
|
|
54
|
+
| `connectionString` | `string` | ✅ | Your database URL — sent at runtime, never stored |
|
|
55
|
+
| `tools` | `Record<string, ToolDefinition>` | — | Custom tools the agent can call client-side |
|
|
56
|
+
|
|
57
|
+
## Inline Mode
|
|
58
|
+
|
|
59
|
+
Embed the chat panel directly in your layout instead of a floating widget:
|
|
60
|
+
|
|
61
|
+
```tsx
|
|
62
|
+
<div style={{ height: 600 }}>
|
|
63
|
+
<SyncAgentChat
|
|
64
|
+
config={{ apiKey: "...", connectionString: "..." }}
|
|
65
|
+
mode="inline"
|
|
66
|
+
/>
|
|
67
|
+
</div>
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
## Custom Accent Color
|
|
30
71
|
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
72
|
+
```tsx
|
|
73
|
+
<SyncAgentChat
|
|
74
|
+
config={{ apiKey: "...", connectionString: "..." }}
|
|
75
|
+
accentColor="#6366f1"
|
|
76
|
+
title="Data Assistant"
|
|
77
|
+
position="bottom-left"
|
|
78
|
+
/>
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
## Custom Tools
|
|
82
|
+
|
|
83
|
+
Give the agent capabilities beyond your database. Tools run entirely in your app — SyncAgent only sees the schema and the result you return.
|
|
84
|
+
|
|
85
|
+
```tsx
|
|
86
|
+
import { SyncAgentChat } from "@syncagent/react";
|
|
87
|
+
|
|
88
|
+
<SyncAgentChat
|
|
89
|
+
config={{
|
|
90
|
+
apiKey: "sa_your_api_key",
|
|
91
|
+
connectionString: process.env.DATABASE_URL,
|
|
92
|
+
tools: {
|
|
93
|
+
sendEmail: {
|
|
94
|
+
description: "Send an email to a user",
|
|
95
|
+
inputSchema: {
|
|
96
|
+
to: { type: "string", description: "Recipient email address" },
|
|
97
|
+
subject: { type: "string", description: "Email subject line" },
|
|
98
|
+
body: { type: "string", description: "Email body" },
|
|
99
|
+
},
|
|
100
|
+
execute: async ({ to, subject, body }) => {
|
|
101
|
+
await mailer.send({ to, subject, text: body });
|
|
102
|
+
return { sent: true };
|
|
103
|
+
},
|
|
104
|
+
},
|
|
105
|
+
},
|
|
106
|
+
}}
|
|
107
|
+
/>
|
|
108
|
+
```
|
|
40
109
|
|
|
41
|
-
## Custom UI with
|
|
110
|
+
## Custom UI with `useSyncAgent`
|
|
111
|
+
|
|
112
|
+
Build your own chat UI using the hook:
|
|
42
113
|
|
|
43
114
|
```tsx
|
|
44
115
|
import { SyncAgentProvider, useSyncAgent } from "@syncagent/react";
|
|
45
116
|
|
|
117
|
+
// 1. Wrap your app (or just the chat component)
|
|
46
118
|
function App() {
|
|
47
119
|
return (
|
|
48
|
-
<SyncAgentProvider config={{ apiKey: "...",
|
|
120
|
+
<SyncAgentProvider config={{ apiKey: "...", connectionString: "..." }}>
|
|
49
121
|
<MyChat />
|
|
50
122
|
</SyncAgentProvider>
|
|
51
123
|
);
|
|
52
124
|
}
|
|
53
125
|
|
|
126
|
+
// 2. Use the hook inside
|
|
54
127
|
function MyChat() {
|
|
55
|
-
const { messages, isLoading, sendMessage, stop, reset } = useSyncAgent();
|
|
56
|
-
|
|
128
|
+
const { messages, isLoading, error, sendMessage, stop, reset } = useSyncAgent();
|
|
129
|
+
const [input, setInput] = useState("");
|
|
130
|
+
|
|
131
|
+
return (
|
|
132
|
+
<div>
|
|
133
|
+
{messages.map((msg, i) => (
|
|
134
|
+
<div key={i} className={msg.role === "user" ? "user" : "assistant"}>
|
|
135
|
+
{msg.content}
|
|
136
|
+
</div>
|
|
137
|
+
))}
|
|
138
|
+
{isLoading && <div>Thinking...</div>}
|
|
139
|
+
{error && <div>Error: {error.message}</div>}
|
|
140
|
+
<input value={input} onChange={(e) => setInput(e.target.value)} />
|
|
141
|
+
<button onClick={() => { sendMessage(input); setInput(""); }}>Send</button>
|
|
142
|
+
<button onClick={stop}>Stop</button>
|
|
143
|
+
<button onClick={reset}>Clear</button>
|
|
144
|
+
</div>
|
|
145
|
+
);
|
|
146
|
+
}
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
### `useSyncAgent` Returns
|
|
150
|
+
|
|
151
|
+
| Return | Type | Description |
|
|
152
|
+
| ------------- | ---------------------------- | ------------------------------------ |
|
|
153
|
+
| `messages` | `Message[]` | Full conversation history |
|
|
154
|
+
| `isLoading` | `boolean` | `true` while streaming |
|
|
155
|
+
| `error` | `Error \| null` | Last error, `null` if none |
|
|
156
|
+
| `sendMessage` | `(content: string) => void` | Send a user message |
|
|
157
|
+
| `stop` | `() => void` | Abort the current streaming response |
|
|
158
|
+
| `reset` | `() => void` | Clear all messages and reset state |
|
|
159
|
+
|
|
160
|
+
### Pass a client directly (without Provider)
|
|
161
|
+
|
|
162
|
+
```tsx
|
|
163
|
+
import { SyncAgentClient } from "@syncagent/js";
|
|
164
|
+
import { useSyncAgent } from "@syncagent/react";
|
|
165
|
+
|
|
166
|
+
const client = new SyncAgentClient({
|
|
167
|
+
apiKey: "sa_your_api_key",
|
|
168
|
+
connectionString: process.env.DATABASE_URL,
|
|
169
|
+
});
|
|
170
|
+
|
|
171
|
+
function MyChat() {
|
|
172
|
+
const { messages, sendMessage } = useSyncAgent({ client });
|
|
173
|
+
// ...
|
|
57
174
|
}
|
|
58
175
|
```
|
|
59
176
|
|
|
60
|
-
##
|
|
177
|
+
## `<SyncAgentProvider>`
|
|
178
|
+
|
|
179
|
+
Provides a shared `SyncAgentClient` instance to all child components via context.
|
|
180
|
+
|
|
181
|
+
```tsx
|
|
182
|
+
import { SyncAgentProvider, useSyncAgentClient } from "@syncagent/react";
|
|
183
|
+
|
|
184
|
+
<SyncAgentProvider config={{ apiKey: "...", connectionString: "..." }}>
|
|
185
|
+
<App />
|
|
186
|
+
</SyncAgentProvider>
|
|
187
|
+
|
|
188
|
+
// Access the raw client anywhere inside
|
|
189
|
+
function Somewhere() {
|
|
190
|
+
const client = useSyncAgentClient();
|
|
191
|
+
// client.chat(...), client.getSchema(), etc.
|
|
192
|
+
}
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
## TypeScript Types
|
|
196
|
+
|
|
197
|
+
All types are re-exported from `@syncagent/js` for convenience:
|
|
198
|
+
|
|
199
|
+
```typescript
|
|
200
|
+
import type {
|
|
201
|
+
SyncAgentConfig,
|
|
202
|
+
Message,
|
|
203
|
+
ChatOptions,
|
|
204
|
+
ToolDefinition,
|
|
205
|
+
ToolParameter,
|
|
206
|
+
SyncAgentChatProps,
|
|
207
|
+
} from "@syncagent/react";
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
## License
|
|
61
211
|
|
|
62
|
-
|
|
63
|
-
| ------------ | --------------------------- | -------------------- |
|
|
64
|
-
| `messages` | `Message[]` | Chat history |
|
|
65
|
-
| `isLoading` | `boolean` | Currently streaming |
|
|
66
|
-
| `error` | `Error \| null` | Last error |
|
|
67
|
-
| `sendMessage`| `(content: string) => void` | Send a message |
|
|
68
|
-
| `stop` | `() => void` | Abort current stream |
|
|
69
|
-
| `reset` | `() => void` | Clear messages |
|
|
212
|
+
MIT
|