@syncagent/js 0.1.9 → 0.2.1

package/README.md

@@ -15,21 +15,12 @@ import { SyncAgentClient } from "@syncagent/js";
 
 const agent = new SyncAgentClient({
   apiKey: "sa_your_api_key",
-  connectionString: process.env.DATABASE_URL, // never stored on SyncAgent servers
+  connectionString: process.env.DATABASE_URL,
+  // baseUrl: "http://localhost:3100", // dev only — defaults to https://syncagent.dev
 });
 
-// Streaming
-await agent.chat(
-  [{ role: "user", content: "Show me all active users" }],
-  {
-    onToken: (token) => process.stdout.write(token),
-    onComplete: (text) => console.log("\nDone"),
-  }
-);
-
-// Non-streaming (await full response)
 const result = await agent.chat([
-  { role: "user", content: "How many orders were placed this month?" }
+  { role: "user", content: "How many users do we have?" }
 ]);
 console.log(result.text);
 ```
@@ -40,11 +31,12 @@ console.log(result.text);
 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       |
+| 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                    |
+| `baseUrl`          | `string`                         | —        | Override API URL. Defaults to `https://syncagent.dev`          |
 
 ## `client.chat(messages, options?)`
 
@@ -60,122 +52,121 @@ const result = await agent.chat(messages, options);
 
 **`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                   |
+| 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                                |
+| `onStatus`   | `(step: string, label: string) => void`          | Called with live status updates while working  |
+| `onData`     | `(data: ToolData) => void`                       | Called when a DB tool returns structured data  |
+| `onToolCall` | `(name: string, args: any, result: any) => void` | Called when a custom tool executes             |
+| `signal`     | `AbortSignal`                                    | Cancel the request                             |
+| `context`    | `Record<string, any>`                            | Extra context injected into every message      |
 
 **Returns** `Promise<ChatResult>` → `{ text: string }`
 
-## `client.getSchema()`
+### Status steps
 
-Discovers and returns your database schema.
+`onStatus` fires with these `step` values:
+- `"connecting"` — connecting to the database
+- `"schema"` — discovering schema
+- `"thinking"` — AI is reasoning
+- `"querying"` — executing a DB tool
+- `"done"` — complete
+
+## `client.getSchema()`
 
 ```typescript
 const schema = await agent.getSchema();
-// schema: CollectionSchema[]
-// [{ name: "users", fields: [{ name: "email", type: "string" }], documentCount: 1200 }]
+// CollectionSchema[]
 ```
 
-## Custom Tools
+## Context injection
 
-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.
+Pass per-message context so the agent knows what the user is looking at:
 
 ```typescript
-import { SyncAgentClient } from "@syncagent/js";
+await agent.chat(messages, {
+  context: {
+    userId: "user_123",
+    currentPage: "orders",
+    selectedOrderId: "ord_456",
+  }
+});
+```
+
+## `onData` callback
 
+React to structured query results in your own UI:
+
+```typescript
 const agent = new SyncAgentClient({
-  apiKey: "sa_your_api_key",
+  apiKey: "sa_your_key",
+  connectionString: process.env.DATABASE_URL,
+});
+
+await agent.chat(messages, {
+  onData: (data) => {
+    // data.tool — "query_documents" | "aggregate_documents"
+    // data.collection — e.g. "orders"
+    // data.data — array of result rows
+    // data.count — number of results
+    console.log(`Got ${data.count} rows from ${data.collection}`);
+    setTableData(data.data); // update your own table component
+  }
+});
+```
+
+## Custom Tools
+
+```typescript
+const agent = new SyncAgentClient({
+  apiKey: "sa_your_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)" },
+        to:      { type: "string", description: "Recipient email" },
+        subject: { type: "string", description: "Subject line" },
+        body:    { type: "string", description: "Email body" },
       },
       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 };
+        return { sent: true };
       },
     },
   },
 });
-
-// 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
+## Multi-turn conversations
 
 ```typescript
-const messages: Message[] = [];
+const history: 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 });
+history.push({ role: "user", content: "Show top 5 customers" });
+const r1 = await agent.chat(history);
+history.push({ role: "assistant", content: r1.text });
 
-// Turn 2
-messages.push({ role: "user", content: "Now email all of them a thank-you note" });
-const r2 = await agent.chat(messages);
+history.push({ role: "user", content: "Now email all of them" });
+const r2 = await agent.chat(history);
 ```
 
-## Abort / Cancel
+## Abort / cancel
 
 ```typescript
 const controller = new AbortController();
-
 agent.chat(messages, { signal: controller.signal });
-
-// Cancel at any time
-controller.abort();
+controller.abort(); // cancel at any time
 ```
 
-## TypeScript Types
+## TypeScript types
 
 ```typescript
 import type {
-  SyncAgentConfig,
-  Message,
-  ChatOptions,
-  ChatResult,
-  CollectionSchema,
-  SchemaField,
-  ToolDefinition,
-  ToolParameter,
+  SyncAgentConfig, Message, ChatOptions, ChatResult,
+  CollectionSchema, SchemaField, ToolDefinition, ToolParameter, ToolData,
 } from "@syncagent/js";
 ```
 

package/dist/index.d.mts

@@ -15,6 +15,11 @@ interface SyncAgentConfig {
     connectionString: string;
     /** Custom tools the AI agent can call — executed client-side in your app */
     tools?: Record<string, ToolDefinition>;
+    /**
+     * Override the API base URL. Defaults to https://syncagent.dev
+     * Use this in development: baseUrl: "http://localhost:3100"
+     */
+    baseUrl?: string;
 }
 interface Message {
     role: "user" | "assistant";

package/dist/index.d.ts

@@ -15,6 +15,11 @@ interface SyncAgentConfig {
     connectionString: string;
     /** Custom tools the AI agent can call — executed client-side in your app */
     tools?: Record<string, ToolDefinition>;
+    /**
+     * Override the API base URL. Defaults to https://syncagent.dev
+     * Use this in development: baseUrl: "http://localhost:3100"
+     */
+    baseUrl?: string;
 }
 interface Message {
     role: "user" | "assistant";

package/dist/index.js

@@ -72,13 +72,13 @@ function parseChunk(chunk) {
 }
 
 // src/client.ts
-var SYNCAGENT_API_URL = "https://syncagent.dev";
+var SYNCAGENT_API_URL = "https://syncagentdev.vercel.app";
 var SyncAgentClient = class {
   constructor(config) {
     if (!config.apiKey) throw new Error("SyncAgent: apiKey is required");
     if (!config.connectionString) throw new Error("SyncAgent: connectionString is required");
     this.apiKey = config.apiKey;
-    this.baseUrl = SYNCAGENT_API_URL;
+    this.baseUrl = (config.baseUrl || SYNCAGENT_API_URL).replace(/\/$/, "");
     this.connectionString = config.connectionString;
     this.tools = config.tools || {};
   }

package/dist/index.mjs

@@ -46,13 +46,13 @@ function parseChunk(chunk) {
 }
 
 // src/client.ts
-var SYNCAGENT_API_URL = "https://syncagent.dev";
+var SYNCAGENT_API_URL = "https://syncagentdev.vercel.app";
 var SyncAgentClient = class {
   constructor(config) {
     if (!config.apiKey) throw new Error("SyncAgent: apiKey is required");
     if (!config.connectionString) throw new Error("SyncAgent: connectionString is required");
     this.apiKey = config.apiKey;
-    this.baseUrl = SYNCAGENT_API_URL;
+    this.baseUrl = (config.baseUrl || SYNCAGENT_API_URL).replace(/\/$/, "");
     this.connectionString = config.connectionString;
     this.tools = config.tools || {};
   }

package/package.json

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