@syncagent/js

@syncagent/js

Core JavaScript/TypeScript SDK for SyncAgent — add an AI database agent to any app.

Install

npm install @syncagent/js

Quick Start

import { SyncAgentClient } from "@syncagent/js";

const agent = new SyncAgentClient({
  apiKey: "sa_your_api_key",
  connectionString: process.env.DATABASE_URL, // never stored on SyncAgent servers
});

// 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?" }
]);
console.log(result.text);

Configuration

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

client.chat(messages, options?)

const result = await agent.chat(messages, options);

messages — Message[]

{ 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.

const schema = await agent.getSchema();
// schema: CollectionSchema[]
// [{ name: "users", fields: [{ name: "email", type: "string" }], documentCount: 1200 }]

Custom Tools

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.

import { SyncAgentClient } from "@syncagent/js";

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

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 });

// Turn 2
messages.push({ role: "user", content: "Now email all of them a thank-you note" });
const r2 = await agent.chat(messages);

Abort / Cancel

const controller = new AbortController();

agent.chat(messages, { signal: controller.signal });

// Cancel at any time
controller.abort();

TypeScript Types

import type {
  SyncAgentConfig,
  Message,
  ChatOptions,
  ChatResult,
  CollectionSchema,
  SchemaField,
  ToolDefinition,
  ToolParameter,
} from "@syncagent/js";

License

MIT