@syncagent/js 0.1.0 → 0.1.1

package/README.md

@@ -1,6 +1,6 @@
 # @syncagent/js
 
-Core JavaScript SDK for SyncAgent — add an AI database agent to any app.
+Core JavaScript/TypeScript SDK for [SyncAgent](https://syncagent.dev) — add an AI database agent to any app.
 
 ## Install
 
@@ -8,53 +8,177 @@ Core JavaScript SDK for SyncAgent — add an AI database agent to any app.
 npm install @syncagent/js
 ```
 
-## Usage
+## Quick Start
 
 ```typescript
 import { SyncAgentClient } from "@syncagent/js";
 
 const agent = new SyncAgentClient({
   apiKey: "sa_your_api_key",
-  baseUrl: "https://your-syncagent-instance.com",
-  connectionString: process.env.DATABASE_URL, // your DB — never stored on our servers
+  connectionString: process.env.DATABASE_URL, // never stored on SyncAgent servers
 });
 
-// Streaming chat
+// Streaming
 await agent.chat(
   [{ role: "user", content: "Show me all active users" }],
   {
     onToken: (token) => process.stdout.write(token),
-    onComplete: (text) => console.log("\n\nDone:", text),
+    onComplete: (text) => console.log("\nDone"),
   }
 );
 
-// Non-streaming
-const result = await agent.chat([{ role: "user", content: "Count all orders" }]);
+// Non-streaming (await full response)
+const result = await agent.chat([
+  { role: "user", content: "How many orders were placed this month?" }
+]);
 console.log(result.text);
+```
+
+## Configuration
+
+```typescript
+new SyncAgentClient(config: SyncAgentConfig)
+```
+
+| Option             | Type                              | Required | Description                                      |
+| ------------------ | --------------------------------- | -------- | ------------------------------------------------ |
+| `apiKey`           | `string`                          | ✅       | Your SyncAgent API key (`sa_...`)                |
+| `connectionString` | `string`                          | ✅       | Your database URL — sent at runtime, never stored |
+| `tools`            | `Record<string, ToolDefinition>`  | —        | Custom tools the agent can call client-side       |
 
-// Get database schema
+## `client.chat(messages, options?)`
+
+```typescript
+const result = await agent.chat(messages, options);
+```
+
+**`messages`** — `Message[]`
+
+```typescript
+{ role: "user" | "assistant"; content: string }
+```
+
+**`options`** — `ChatOptions`
+
+| Option       | Type                                                    | Description                          |
+| ------------ | ------------------------------------------------------- | ------------------------------------ |
+| `onToken`    | `(token: string) => void`                               | Called for each streamed text chunk  |
+| `onComplete` | `(text: string) => void`                                | Called with the full response text   |
+| `onError`    | `(error: Error) => void`                                | Called on error                      |
+| `onToolCall` | `(name: string, args: any, result: any) => void`        | Called when a custom tool executes   |
+| `signal`     | `AbortSignal`                                           | Cancel the request                   |
+
+**Returns** `Promise<ChatResult>` → `{ text: string }`
+
+## `client.getSchema()`
+
+Discovers and returns your database schema.
+
+```typescript
 const schema = await agent.getSchema();
+// schema: CollectionSchema[]
+// [{ name: "users", fields: [{ name: "email", type: "string" }], documentCount: 1200 }]
 ```
 
-## API
+## Custom Tools
 
-### `new SyncAgentClient(config)`
+Give the agent capabilities beyond your database — send emails, trigger webhooks, create invoices. Tools run entirely in your code; SyncAgent only sees the schema and the result you return.
 
-| Option             | Type   | Required | Description                                    |
-| ------------------ | ------ | -------- | ---------------------------------------------- |
-| `apiKey`           | string | ✅       | Your SyncAgent API key                         |
-| `baseUrl`          | string | ✅       | Your SyncAgent instance URL                    |
-| `connectionString` | string | ✅       | Your database URL (sent at runtime, not stored) |
+```typescript
+import { SyncAgentClient } from "@syncagent/js";
 
-### `client.chat(messages, options?)`
+const agent = new SyncAgentClient({
+  apiKey: "sa_your_api_key",
+  connectionString: process.env.DATABASE_URL,
+  tools: {
+    sendEmail: {
+      description: "Send an email to a user",
+      inputSchema: {
+        to:      { type: "string",  description: "Recipient email address" },
+        subject: { type: "string",  description: "Email subject line" },
+        body:    { type: "string",  description: "Email body (plain text)" },
+      },
+      execute: async ({ to, subject, body }) => {
+        await mailer.send({ to, subject, text: body });
+        return { sent: true, to };
+      },
+    },
+    createInvoice: {
+      description: "Create a Stripe invoice for a customer",
+      inputSchema: {
+        customerId: { type: "string", description: "Stripe customer ID" },
+        amount:     { type: "number", description: "Amount in cents" },
+        memo:       { type: "string", description: "Invoice memo", required: false },
+      },
+      execute: async ({ customerId, amount, memo }) => {
+        const inv = await stripe.invoices.create({ customer: customerId, description: memo });
+        return { invoiceId: inv.id };
+      },
+    },
+  },
+});
+
+// The agent can now query your DB AND call your tools
+await agent.chat([
+  { role: "user", content: "Find all users with expired subscriptions and email them" }
+], {
+  onToolCall: (name, args, result) => console.log(`Tool called: ${name}`, result),
+});
+```
+
+### Tool Definition
+
+| Field                      | Type                                                        | Description                                      |
+| -------------------------- | ----------------------------------------------------------- | ------------------------------------------------ |
+| `description`              | `string`                                                    | What the tool does — the AI reads this           |
+| `inputSchema`              | `Record<string, ToolParameter>`                             | Parameters the tool accepts                      |
+| `inputSchema.*.type`       | `"string" \| "number" \| "boolean" \| "object" \| "array"` | Parameter type                                   |
+| `inputSchema.*.description`| `string?`                                                   | Helps the AI know what value to pass             |
+| `inputSchema.*.required`   | `boolean?`                                                  | Defaults to `true` — set `false` for optional   |
+| `inputSchema.*.enum`       | `string[]?`                                                 | Restrict to specific values                      |
+| `execute`                  | `(args) => any \| Promise<any>`                             | Your function — runs in your app, not on servers |
+
+## Multi-turn Conversations
+
+```typescript
+const messages: Message[] = [];
+
+// Turn 1
+messages.push({ role: "user", content: "Show me the top 5 customers by revenue" });
+const r1 = await agent.chat(messages);
+messages.push({ role: "assistant", content: r1.text });
 
-| Option       | Type                       | Description              |
-| ------------ | -------------------------- | ------------------------ |
-| `onToken`    | `(token: string) => void`  | Called on each text chunk |
-| `onComplete` | `(text: string) => void`   | Called when done          |
-| `onError`    | `(error: Error) => void`   | Called on error           |
-| `signal`     | `AbortSignal`              | For cancellation         |
+// Turn 2
+messages.push({ role: "user", content: "Now email all of them a thank-you note" });
+const r2 = await agent.chat(messages);
+```
+
+## Abort / Cancel
+
+```typescript
+const controller = new AbortController();
+
+agent.chat(messages, { signal: controller.signal });
+
+// Cancel at any time
+controller.abort();
+```
+
+## TypeScript Types
+
+```typescript
+import type {
+  SyncAgentConfig,
+  Message,
+  ChatOptions,
+  ChatResult,
+  CollectionSchema,
+  SchemaField,
+  ToolDefinition,
+  ToolParameter,
+} from "@syncagent/js";
+```
 
-### `client.getSchema()`
+## License
 
-Returns `Promise<CollectionSchema[]>`.
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncagent/js",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "SyncAgent JavaScript SDK — AI database agent for any app",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",