@syncagent/js

@syncagent/js

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

Works with MongoDB, PostgreSQL, MySQL, SQLite, SQL Server, and Supabase.

Get Your API Key

• Sign up for a free account
• Go to your Dashboard → New Project → choose your database type
• Copy your API key (starts with sa_)

Every new project gets a 14-day trial with 500 free requests — no credit card required. After the trial, you get 100 free requests/month on the Free plan.

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

// Non-streaming
const result = await agent.chat([
  { role: "user", content: "How many users signed up this month?" }
]);
console.log(result.text);

// Streaming
await agent.chat(
  [{ role: "user", content: "Show me the top 10 customers by revenue" }],
  {
    onToken: (token) => process.stdout.write(token),
    onComplete: (text) => console.log("\nDone"),
    onError: (err) => console.error(err),
  }
);

Supported Databases

Database	Connection String Format
MongoDB	mongodb+srv://user:[e-mail]/mydb
PostgreSQL	postgresql://user:pass@host:5432/mydb
MySQL	mysql://user:pass@host:3306/mydb
SQLite	/absolute/path/to/database.sqlite
SQL Server	Server=host,1433;Database=mydb;User Id=user;Password=pass;Encrypt=true;
Supabase	https://xxx.supabase.co|your-anon-key

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. *Optional when toolsOnly: true.
tools	Record<string, ToolDefinition>	—	Custom tools the agent can call client-side
baseUrl	string	—	Override API URL (dev only)
filter	Record<string, any>	—	Mandatory query filter for multi-tenancy
operations	("read"|"create"|"update"|"delete")[]	—	Restrict operations for this session
toolsOnly	boolean	—	Disables all DB tools — agent only uses your custom tools
autoDetectPage	boolean	true	Auto-detect current page from window.location
systemInstruction	string	—	Custom agent instructions — personality, tone, rules
confirmWrites	boolean	false	Ask for confirmation before create/update/delete
language	string	—	Language the agent responds in (e.g. "French")
maxResults	number	50	Default max records per query
sensitiveFields	string[]	["password","token","secret"]	Fields masked in responses
onBeforeToolCall	(name, args) => boolean	—	Called before each client tool. Return false to block.
onAfterToolCall	(name, args, result) => void	—	Called after each client tool executes

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
onStatus	(step: string, label: string) => void	Live status updates
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 }

Status steps

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()

const schema = await agent.getSchema();
// CollectionSchema[]

Multi-turn Conversations

const history: Message[] = [];

history.push({ role: "user", content: "Show top 5 customers" });
const r1 = await agent.chat(history);
history.push({ role: "assistant", content: r1.text });

history.push({ role: "user", content: "Now show their total orders" });
const r2 = await agent.chat(history);

Context & Auto Page Detection

The SDK automatically detects the current page from window.location on every message — zero config needed.

URL: /dashboard/orders/ord_123?tab=details

Auto-detected context:
  currentPage: "orders"
  currentPath: "/dashboard/orders/ord_123"
  currentRecordId: "ord_123"
  param_tab: "details"

Pass additional context:

await agent.chat(messages, {
  context: { userId: "user_123", userRole: "admin", orgName: "Acme Corp" }
});

onData — React to Query Results

await agent.chat(messages, {
  onData: (data) => {
    console.log(data.collection); // "orders"
    console.log(data.data);       // array of result rows
    console.log(data.count);      // number of results
  }
});

Custom Tools

Give the agent capabilities beyond your database. Tools run entirely in your app — SyncAgent only sees the schema and result.

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

Multi-tenant SaaS

Pass filter to scope every agent operation to the current user's organization. Enforced server-side.

const agent = new SyncAgentClient({
  apiKey: "sa_your_key",
  connectionString: process.env.DATABASE_URL,
  filter: { organizationId: currentUser.orgId },
  operations: currentUser.isAdmin
    ? ["read", "create", "update", "delete"]
    : ["read"],
});

Tools-only Mode

Build an AI assistant powered by your own APIs — no database access needed.

const agent = new SyncAgentClient({
  apiKey: "sa_your_key",
  toolsOnly: true,
  tools: {
    searchProducts: {
      description: "Search products by name or category",
      inputSchema: { query: { type: "string", description: "Search query" } },
      execute: async ({ query }) => {
        const res = await fetch(`/api/products?q=${query}`);
        return res.json();
      },
    },
  },
});

Abort / Cancel

const controller = new AbortController();
agent.chat(messages, { signal: controller.signal });
controller.abort();

Express.js Integration

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

const app = express();
app.use(express.json());

const agent = new SyncAgentClient({
  apiKey: process.env.SYNCAGENT_KEY,
  connectionString: process.env.DATABASE_URL,
});

app.post("/chat", async (req, res) => {
  res.setHeader("Content-Type", "text/plain");
  res.setHeader("Transfer-Encoding", "chunked");

  await agent.chat(req.body.messages, {
    onToken: (token) => res.write(token),
    onComplete: () => res.end(),
    onError: (err) => { res.status(500).end(err.message); },
  });
});

app.listen(3000);

TypeScript Types

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

Security

• Your database connection string is never stored on SyncAgent servers
• It's passed at runtime, used to process the request, and immediately discarded
• API keys are hashed with bcrypt — raw keys are never stored
• Rate limiting: max 5 concurrent requests per API key per 10 seconds

Plans & Pricing

Plan	Requests/mo	Collections	Price
Free (+ 14-day trial)	100 (500 during trial)	5	GH₵0
Starter	5,000	20	GH₵150/mo
Pro	50,000	Unlimited	GH₵500/mo
Enterprise	Unlimited	Unlimited	Custom

View full pricing →

Resources

• Documentation
• Dashboard
• Pricing
• Changelog

License

MIT