@syncagent/js 0.1.0

package/README.md

@@ -0,0 +1,60 @@
+# @syncagent/js
+
+Core JavaScript SDK for SyncAgent — add an AI database agent to any app.
+
+## Install
+
+```bash
+npm install @syncagent/js
+```
+
+## Usage
+
+```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
+});
+
+// Streaming chat
+await agent.chat(
+  [{ role: "user", content: "Show me all active users" }],
+  {
+    onToken: (token) => process.stdout.write(token),
+    onComplete: (text) => console.log("\n\nDone:", text),
+  }
+);
+
+// Non-streaming
+const result = await agent.chat([{ role: "user", content: "Count all orders" }]);
+console.log(result.text);
+
+// Get database schema
+const schema = await agent.getSchema();
+```
+
+## API
+
+### `new SyncAgentClient(config)`
+
+| 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) |
+
+### `client.chat(messages, options?)`
+
+| 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         |
+
+### `client.getSchema()`
+
+Returns `Promise<CollectionSchema[]>`.

package/dist/index.d.mts

@@ -0,0 +1,59 @@
+interface ToolParameter {
+    type: "string" | "number" | "boolean" | "object" | "array";
+    description?: string;
+    required?: boolean;
+    enum?: string[];
+}
+interface ToolDefinition {
+    description: string;
+    inputSchema: Record<string, ToolParameter>;
+    execute: (args: Record<string, any>) => any | Promise<any>;
+}
+interface SyncAgentConfig {
+    apiKey: string;
+    /** Your database connection string — sent at runtime, never stored on SyncAgent servers */
+    connectionString: string;
+    /** Custom tools the AI agent can call — executed client-side in your app */
+    tools?: Record<string, ToolDefinition>;
+}
+interface Message {
+    role: "user" | "assistant";
+    content: string;
+}
+interface ChatOptions {
+    onToken?: (token: string) => void;
+    onComplete?: (text: string) => void;
+    onError?: (error: Error) => void;
+    onToolCall?: (toolName: string, args: Record<string, any>, result: any) => void;
+    signal?: AbortSignal;
+}
+interface ChatResult {
+    text: string;
+}
+interface SchemaField {
+    name: string;
+    type: string;
+    sampleValue?: any;
+}
+interface CollectionSchema {
+    name: string;
+    fields: SchemaField[];
+    documentCount?: number;
+}
+
+declare class SyncAgentClient {
+    private apiKey;
+    private baseUrl;
+    private connectionString;
+    private tools;
+    constructor(config: SyncAgentConfig);
+    private headers;
+    private toWireMessages;
+    /** Serialize tool definitions for the API (strips execute functions) */
+    private serializeTools;
+    chat(messages: Message[], options?: ChatOptions): Promise<ChatResult>;
+    private chatLoop;
+    getSchema(): Promise<CollectionSchema[]>;
+}
+
+export { type ChatOptions, type ChatResult, type CollectionSchema, type Message, type SchemaField, SyncAgentClient, type SyncAgentConfig, type ToolDefinition, type ToolParameter };

package/dist/index.d.ts

@@ -0,0 +1,59 @@
+interface ToolParameter {
+    type: "string" | "number" | "boolean" | "object" | "array";
+    description?: string;
+    required?: boolean;
+    enum?: string[];
+}
+interface ToolDefinition {
+    description: string;
+    inputSchema: Record<string, ToolParameter>;
+    execute: (args: Record<string, any>) => any | Promise<any>;
+}
+interface SyncAgentConfig {
+    apiKey: string;
+    /** Your database connection string — sent at runtime, never stored on SyncAgent servers */
+    connectionString: string;
+    /** Custom tools the AI agent can call — executed client-side in your app */
+    tools?: Record<string, ToolDefinition>;
+}
+interface Message {
+    role: "user" | "assistant";
+    content: string;
+}
+interface ChatOptions {
+    onToken?: (token: string) => void;
+    onComplete?: (text: string) => void;
+    onError?: (error: Error) => void;
+    onToolCall?: (toolName: string, args: Record<string, any>, result: any) => void;
+    signal?: AbortSignal;
+}
+interface ChatResult {
+    text: string;
+}
+interface SchemaField {
+    name: string;
+    type: string;
+    sampleValue?: any;
+}
+interface CollectionSchema {
+    name: string;
+    fields: SchemaField[];
+    documentCount?: number;
+}
+
+declare class SyncAgentClient {
+    private apiKey;
+    private baseUrl;
+    private connectionString;
+    private tools;
+    constructor(config: SyncAgentConfig);
+    private headers;
+    private toWireMessages;
+    /** Serialize tool definitions for the API (strips execute functions) */
+    private serializeTools;
+    chat(messages: Message[], options?: ChatOptions): Promise<ChatResult>;
+    private chatLoop;
+    getSchema(): Promise<CollectionSchema[]>;
+}
+
+export { type ChatOptions, type ChatResult, type CollectionSchema, type Message, type SchemaField, SyncAgentClient, type SyncAgentConfig, type ToolDefinition, type ToolParameter };

package/dist/index.js

@@ -0,0 +1,183 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  SyncAgentClient: () => SyncAgentClient
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/stream.ts
+function parseDataStreamChunk(chunk) {
+  const tokens = [];
+  const lines = chunk.split("\n");
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || !trimmed.startsWith("0:")) continue;
+    try {
+      const parsed = JSON.parse(trimmed.substring(2));
+      if (typeof parsed === "string") tokens.push(parsed);
+    } catch {
+    }
+  }
+  return tokens;
+}
+
+// src/client.ts
+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.connectionString = config.connectionString;
+    this.tools = config.tools || {};
+  }
+  headers() {
+    return {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${this.apiKey}`
+    };
+  }
+  toWireMessages(messages) {
+    return messages.map((m) => ({
+      id: Math.random().toString(36).slice(2),
+      role: m.role,
+      parts: [{ type: "text", text: m.content }]
+    }));
+  }
+  /** Serialize tool definitions for the API (strips execute functions) */
+  serializeTools() {
+    if (!Object.keys(this.tools).length) return void 0;
+    const serialized = {};
+    for (const [name, def] of Object.entries(this.tools)) {
+      serialized[name] = { description: def.description, inputSchema: def.inputSchema };
+    }
+    return serialized;
+  }
+  async chat(messages, options = {}) {
+    const { onToken, onComplete, onError, onToolCall, signal } = options;
+    const wireMessages = this.toWireMessages(messages);
+    const clientTools = this.serializeTools();
+    try {
+      const fullText = await this.chatLoop(wireMessages, clientTools, { onToken, onToolCall, signal });
+      onComplete?.(fullText);
+      return { text: fullText };
+    } catch (e) {
+      const error = e instanceof Error ? e : new Error(String(e));
+      onError?.(error);
+      throw error;
+    }
+  }
+  async chatLoop(wireMessages, clientTools, opts, maxRounds = 10) {
+    let fullText = "";
+    for (let round = 0; round < maxRounds; round++) {
+      const res = await fetch(`${this.baseUrl}/api/v1/chat`, {
+        method: "POST",
+        headers: this.headers(),
+        body: JSON.stringify({
+          messages: wireMessages,
+          connectionString: this.connectionString,
+          ...clientTools && { clientTools }
+        }),
+        signal: opts.signal
+      });
+      if (!res.ok) {
+        const err = await res.json().catch(() => ({ error: res.statusText }));
+        throw new Error(err.error || `HTTP ${res.status}`);
+      }
+      const reader = res.body?.getReader();
+      if (!reader) throw new Error("No response body");
+      const decoder = new TextDecoder();
+      let roundText = "";
+      let pendingToolCalls = [];
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        const chunk = decoder.decode(value, { stream: true });
+        for (const line of chunk.split("\n")) {
+          if (line.startsWith("a:")) {
+            try {
+              const data = JSON.parse(line.slice(2));
+              if (data.type === "client_tool_call") {
+                pendingToolCalls.push({ id: data.id, name: data.name, args: data.args });
+                continue;
+              }
+            } catch {
+            }
+          }
+        }
+        const tokens = parseDataStreamChunk(chunk);
+        for (const token of tokens) {
+          roundText += token;
+          fullText += token;
+          opts.onToken?.(token);
+        }
+      }
+      if (!pendingToolCalls.length) return fullText;
+      const toolResults = [];
+      for (const tc of pendingToolCalls) {
+        const toolDef = this.tools[tc.name];
+        if (!toolDef) {
+          toolResults.push({ id: tc.id, name: tc.name, result: { error: `Tool "${tc.name}" not found on client` } });
+          continue;
+        }
+        try {
+          const result = await toolDef.execute(tc.args);
+          opts.onToolCall?.(tc.name, tc.args, result);
+          toolResults.push({ id: tc.id, name: tc.name, result });
+        } catch (e) {
+          const errResult = { error: e.message || String(e) };
+          opts.onToolCall?.(tc.name, tc.args, errResult);
+          toolResults.push({ id: tc.id, name: tc.name, result: errResult });
+        }
+      }
+      wireMessages.push({
+        id: Math.random().toString(36).slice(2),
+        role: "tool",
+        parts: toolResults.map((tr) => ({
+          type: "tool-result",
+          toolCallId: tr.id,
+          toolName: tr.name,
+          result: tr.result
+        }))
+      });
+    }
+    return fullText;
+  }
+  async getSchema() {
+    const res = await fetch(`${this.baseUrl}/api/v1/schema`, {
+      method: "POST",
+      headers: this.headers(),
+      body: JSON.stringify({ connectionString: this.connectionString })
+    });
+    if (!res.ok) {
+      const err = await res.json().catch(() => ({ error: res.statusText }));
+      throw new Error(err.error || `HTTP ${res.status}`);
+    }
+    const data = await res.json();
+    return data.collections;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SyncAgentClient
+});

package/dist/index.mjs

@@ -0,0 +1,156 @@
+// src/stream.ts
+function parseDataStreamChunk(chunk) {
+  const tokens = [];
+  const lines = chunk.split("\n");
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || !trimmed.startsWith("0:")) continue;
+    try {
+      const parsed = JSON.parse(trimmed.substring(2));
+      if (typeof parsed === "string") tokens.push(parsed);
+    } catch {
+    }
+  }
+  return tokens;
+}
+
+// src/client.ts
+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.connectionString = config.connectionString;
+    this.tools = config.tools || {};
+  }
+  headers() {
+    return {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${this.apiKey}`
+    };
+  }
+  toWireMessages(messages) {
+    return messages.map((m) => ({
+      id: Math.random().toString(36).slice(2),
+      role: m.role,
+      parts: [{ type: "text", text: m.content }]
+    }));
+  }
+  /** Serialize tool definitions for the API (strips execute functions) */
+  serializeTools() {
+    if (!Object.keys(this.tools).length) return void 0;
+    const serialized = {};
+    for (const [name, def] of Object.entries(this.tools)) {
+      serialized[name] = { description: def.description, inputSchema: def.inputSchema };
+    }
+    return serialized;
+  }
+  async chat(messages, options = {}) {
+    const { onToken, onComplete, onError, onToolCall, signal } = options;
+    const wireMessages = this.toWireMessages(messages);
+    const clientTools = this.serializeTools();
+    try {
+      const fullText = await this.chatLoop(wireMessages, clientTools, { onToken, onToolCall, signal });
+      onComplete?.(fullText);
+      return { text: fullText };
+    } catch (e) {
+      const error = e instanceof Error ? e : new Error(String(e));
+      onError?.(error);
+      throw error;
+    }
+  }
+  async chatLoop(wireMessages, clientTools, opts, maxRounds = 10) {
+    let fullText = "";
+    for (let round = 0; round < maxRounds; round++) {
+      const res = await fetch(`${this.baseUrl}/api/v1/chat`, {
+        method: "POST",
+        headers: this.headers(),
+        body: JSON.stringify({
+          messages: wireMessages,
+          connectionString: this.connectionString,
+          ...clientTools && { clientTools }
+        }),
+        signal: opts.signal
+      });
+      if (!res.ok) {
+        const err = await res.json().catch(() => ({ error: res.statusText }));
+        throw new Error(err.error || `HTTP ${res.status}`);
+      }
+      const reader = res.body?.getReader();
+      if (!reader) throw new Error("No response body");
+      const decoder = new TextDecoder();
+      let roundText = "";
+      let pendingToolCalls = [];
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        const chunk = decoder.decode(value, { stream: true });
+        for (const line of chunk.split("\n")) {
+          if (line.startsWith("a:")) {
+            try {
+              const data = JSON.parse(line.slice(2));
+              if (data.type === "client_tool_call") {
+                pendingToolCalls.push({ id: data.id, name: data.name, args: data.args });
+                continue;
+              }
+            } catch {
+            }
+          }
+        }
+        const tokens = parseDataStreamChunk(chunk);
+        for (const token of tokens) {
+          roundText += token;
+          fullText += token;
+          opts.onToken?.(token);
+        }
+      }
+      if (!pendingToolCalls.length) return fullText;
+      const toolResults = [];
+      for (const tc of pendingToolCalls) {
+        const toolDef = this.tools[tc.name];
+        if (!toolDef) {
+          toolResults.push({ id: tc.id, name: tc.name, result: { error: `Tool "${tc.name}" not found on client` } });
+          continue;
+        }
+        try {
+          const result = await toolDef.execute(tc.args);
+          opts.onToolCall?.(tc.name, tc.args, result);
+          toolResults.push({ id: tc.id, name: tc.name, result });
+        } catch (e) {
+          const errResult = { error: e.message || String(e) };
+          opts.onToolCall?.(tc.name, tc.args, errResult);
+          toolResults.push({ id: tc.id, name: tc.name, result: errResult });
+        }
+      }
+      wireMessages.push({
+        id: Math.random().toString(36).slice(2),
+        role: "tool",
+        parts: toolResults.map((tr) => ({
+          type: "tool-result",
+          toolCallId: tr.id,
+          toolName: tr.name,
+          result: tr.result
+        }))
+      });
+    }
+    return fullText;
+  }
+  async getSchema() {
+    const res = await fetch(`${this.baseUrl}/api/v1/schema`, {
+      method: "POST",
+      headers: this.headers(),
+      body: JSON.stringify({ connectionString: this.connectionString })
+    });
+    if (!res.ok) {
+      const err = await res.json().catch(() => ({ error: res.statusText }));
+      throw new Error(err.error || `HTTP ${res.status}`);
+    }
+    const data = await res.json();
+    return data.collections;
+  }
+};
+export {
+  SyncAgentClient
+};

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@syncagent/js",
+  "version": "0.1.0",
+  "description": "SyncAgent JavaScript SDK — AI database agent for any app",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch"
+  },
+  "devDependencies": {
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.3"
+  },
+  "license": "MIT",
+  "keywords": ["syncagent", "ai", "database", "agent", "sdk", "chat"]
+}