@synapsor/client 0.1.0 → 0.1.2

package/README.md

@@ -1,7 +1,8 @@
-# Synapsor Node.js Adapter
+# Synapsor Node.js SDK
 
-The Node.js adapter is a thin ESM client over `synapsor_server` HTTP/JSON APIs.
-It keeps Synapsor semantics in C++ and exposes a compact JavaScript API.
+The Synapsor Node.js SDK connects applications to hosted or local Synapsor
+databases. Use it for SQL, branch workflows, agent contexts, capabilities,
+evidence, memory, and safe write proposals from Node.js applications.
 
 ## Local Usage
 
@@ -35,7 +36,7 @@ await db.close();
 
 ## Hosted Usage
 
-Install from npm after the package is published:
+Install from npm:
 
 ```bash
 npm install @synapsor/client
@@ -59,14 +60,12 @@ const ctx = await db.invokeAgentCapability("chat.prepare_llm_context", { questio
 ```
 
 Use database-scoped API keys from the Synapsor control panel for hosted projects.
-The cloud gateway pins those keys to the database runtime branch before forwarding
-requests to the single-node runtime.
 
 ## API Surface
 
 - `execute(sql)` and `query(sql)`
 - `setSession({...})`
-- `invokeAgentCapability(name, args)`
+- `invokeAgentCapability(name, args, options)`
 - `listCapabilities(query)`
 - `rememberFact({...})`
 - `proposeMemoryFact({...})`
@@ -77,7 +76,7 @@ requests to the single-node runtime.
 - `retireFact(id, {...})` and `forgetFact(id, reason)`
 - `checkFactForAction({...})`
 - branch helpers: `createBranch`, `useBranch`, `diffBranch`, `mergeBranch`, `dropBranch`
-- write lifecycle helpers: `previewWrite`, `approveWrite`, `commitWrite`, `rejectWrite`
+- write lifecycle helpers: `previewWrite`, `approveWrite`, `commitWrite`, `rejectWrite`, `settleWrite`
 - `readResource(uri)`
 
 Errors from Synapsor become `SynapsorError` with `status` and `payload`.

package/bin/synapsor.mjs

@@ -0,0 +1,294 @@
+#!/usr/bin/env node
+import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+
+const PACKAGE_VERSION = "0.1.2";
+const DEFAULT_BASE_URL = "https://synapsor.ai";
+const ERROR_HINTS = new Map([
+  ["AUTH_REQUIRED", "Set SYNAPSOR_API_KEY or run `synapsor config set api-key`."],
+  ["BILLING_REQUIRED", "Builder resources require active or trialing Builder billing."],
+  ["LIMIT_EXCEEDED", "You reached a controlled-beta hard limit. Upgrade or reduce usage."],
+  ["FORBIDDEN", "The API key is not allowed to perform this operation."],
+  ["NOT_FOUND", "Check the project, database, handle, or run id."],
+  ["BETA_UNAVAILABLE", "This feature is not self-serve in the controlled beta."],
+]);
+
+function configPath() {
+  const override = process.env.SYNAPSOR_CLI_CONFIG_HOME;
+  return join(override || join(homedir(), ".config"), "synapsor", "config.json");
+}
+
+async function loadConfig(profile = "default") {
+  const path = configPath();
+  if (!existsSync(path)) return { path, profile, data: {}, current: {} };
+  const raw = JSON.parse(await readFile(path, "utf8"));
+  const profiles = raw.profiles && typeof raw.profiles === "object" ? raw.profiles : {};
+  return { path, profile, data: raw, current: profiles[profile] || {} };
+}
+
+async function saveConfig(profile, patch) {
+  const existing = await loadConfig(profile);
+  const data = existing.data.profiles ? existing.data : { profiles: {} };
+  data.profiles[profile] = { ...(data.profiles[profile] || {}), ...patch };
+  const path = configPath();
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, JSON.stringify(data, null, 2) + "\n", { mode: 0o600 });
+  try {
+    await chmod(path, 0o600);
+  } catch {
+    // Best effort on platforms without POSIX modes.
+  }
+  return path;
+}
+
+function parse(argv) {
+  const globals = { json: false, profile: "default", project: "", db: "", baseUrl: "" };
+  const args = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--json") {
+      const next = argv[i + 1] || "";
+      if (/^\s*[\[{]/.test(next)) {
+        args.push(arg);
+        args.push(argv[++i]);
+      } else {
+        globals.json = true;
+      }
+    }
+    else if (arg === "--yes" || arg === "-y") globals.yes = true;
+    else if (["--profile", "--project", "--db", "--base-url"].includes(arg)) {
+      const key = arg === "--base-url" ? "baseUrl" : arg.slice(2);
+      globals[key] = argv[++i] || "";
+    }
+    else args.push(arg);
+  }
+  return { globals, args };
+}
+
+function redact(value) {
+  const text = String(value || "");
+  if (!text) return "";
+  return `${text.slice(0, 8)}...redacted`;
+}
+
+function print(payload, globals) {
+  if (globals.json) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+  if (Array.isArray(payload)) {
+    for (const item of payload) console.log(formatLine(item));
+    return;
+  }
+  if (payload && typeof payload === "object") {
+    console.log(formatLine(payload));
+    return;
+  }
+  console.log(String(payload));
+}
+
+function formatLine(item) {
+  if (!item || typeof item !== "object") return String(item);
+  const preferred = ["project_id", "database_id", "name", "plan", "status", "billing_status", "runtime_branch", "key_id"];
+  const parts = [];
+  for (const key of preferred) {
+    if (item[key] !== undefined && item[key] !== null && item[key] !== "") parts.push(`${key}=${item[key]}`);
+  }
+  return parts.length ? parts.join("  ") : JSON.stringify(item);
+}
+
+async function requireApiKey(config) {
+  const key = process.env.SYNAPSOR_API_KEY || config.current.apiKey || "";
+  if (!key) {
+    const error = new Error("AUTH_REQUIRED: configure an API key from the Synapsor dashboard. Public demo: https://synapsor.ai/demo");
+    error.code = "AUTH_REQUIRED";
+    throw error;
+  }
+  return key;
+}
+
+async function client(globals) {
+  const config = await loadConfig(globals.profile);
+  const baseUrl = (globals.baseUrl || process.env.SYNAPSOR_BASE_URL || config.current.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, "");
+  const apiKey = await requireApiKey(config);
+  return { baseUrl, apiKey };
+}
+
+async function request(globals, method, path, body) {
+  const { baseUrl, apiKey } = await client(globals);
+  const init = { method, headers: { accept: "application/json", authorization: `Bearer ${apiKey}` } };
+  if (body !== undefined) {
+    init.headers["content-type"] = "application/json";
+    init.body = JSON.stringify(body);
+  }
+  const response = await fetch(`${baseUrl}${path}`, init);
+  const text = await response.text();
+  let payload = {};
+  if (text.trim()) {
+    try {
+      payload = JSON.parse(text);
+    } catch {
+      payload = { ok: false, error: "INVALID_JSON_RESPONSE", body_preview: text.slice(0, 240) };
+    }
+  }
+  if (!response.ok || payload.ok === false) {
+    const errorCode = mapError(payload.error || response.status);
+    const error = new Error(`${errorCode}: ${payload.message || payload.error || `HTTP ${response.status}`}`);
+    error.code = errorCode;
+    error.payload = payload;
+    throw error;
+  }
+  return payload;
+}
+
+function mapError(error) {
+  const text = String(error || "").toLowerCase();
+  if (text.includes("auth") || text.includes("session") || text.includes("token")) return "AUTH_REQUIRED";
+  if (text.includes("payment") || text.includes("billing")) return "BILLING_REQUIRED";
+  if (text.includes("quota") || text.includes("limit")) return "LIMIT_EXCEEDED";
+  if (text.includes("denied") || text.includes("forbidden")) return "FORBIDDEN";
+  if (text.includes("not_found")) return "NOT_FOUND";
+  if (text.includes("plan_not_available")) return "BETA_UNAVAILABLE";
+  return String(error || "REQUEST_FAILED").toUpperCase();
+}
+
+async function confirm(globals, label) {
+  if (globals.yes) return;
+  const rl = createInterface({ input, output });
+  const answer = await rl.question(`${label} Type yes to continue: `);
+  rl.close();
+  if (answer.trim().toLowerCase() !== "yes") throw new Error("FORBIDDEN: confirmation required");
+}
+
+async function readStdinSecret() {
+  const rl = createInterface({ input, output });
+  const value = await rl.question("Paste Synapsor API key: ");
+  rl.close();
+  return value.trim();
+}
+
+async function main(argv = process.argv.slice(2)) {
+  const { globals, args } = parse(argv);
+  const [cmd, sub, third, ...rest] = args;
+  if (!cmd || cmd === "--help" || cmd === "help") return help();
+  if (cmd === "--version" || cmd === "version") return console.log(PACKAGE_VERSION);
+
+  if (cmd === "config") {
+    if (sub === "get") {
+      const config = await loadConfig(globals.profile);
+      return print({ profile: globals.profile, baseUrl: config.current.baseUrl || DEFAULT_BASE_URL, apiKey: redact(process.env.SYNAPSOR_API_KEY || config.current.apiKey) }, globals);
+    }
+    if (sub === "set" && third === "base-url") {
+      const value = rest[0];
+      if (!value) throw new Error("BASE_URL_REQUIRED: usage `synapsor config set base-url https://synapsor.ai`");
+      await saveConfig(globals.profile, { baseUrl: value.replace(/\/+$/, "") });
+      return print({ ok: true, profile: globals.profile, baseUrl: value.replace(/\/+$/, "") }, globals);
+    }
+    if (sub === "set" && third === "api-key") {
+      const value = rest[0] || await readStdinSecret();
+      if (!value) throw new Error("AUTH_REQUIRED: API key required");
+      await saveConfig(globals.profile, { apiKey: value });
+      return print({ ok: true, profile: globals.profile, apiKey: redact(value) }, globals);
+    }
+  }
+
+  if (cmd === "projects") {
+    if (sub === "list") {
+      const payload = await request(globals, "GET", "/v1/control/projects");
+      return print(payload.projects || [], globals);
+    }
+    if (sub === "create") {
+      const name = third;
+      if (!name) throw new Error("PROJECT_NAME_REQUIRED: usage `synapsor projects create <name>`");
+      return print(await request(globals, "POST", "/v1/control/projects", { name, plan: "free" }), globals);
+    }
+  }
+
+  if (cmd === "db") {
+    if (sub === "list") {
+      const payload = await request(globals, "GET", "/v1/control/databases");
+      return print(payload.databases || [], globals);
+    }
+    if (sub === "create") {
+      const name = third;
+      if (!name) throw new Error("DATABASE_NAME_REQUIRED: usage `synapsor db create <name> --project <project>`");
+      return print(await request(globals, "POST", "/v1/control/databases", { name, project_id: globals.project, plan: "free" }), globals);
+    }
+  }
+
+  if (cmd === "sql") {
+    const db = globals.db || "";
+    let sql = args.slice(1).join(" ").trim();
+    const fileIndex = args.indexOf("--file");
+    if (fileIndex >= 0) sql = await readFile(args[fileIndex + 1], "utf8");
+    if (!db) throw new Error("DATABASE_REQUIRED: use `--db <database_id>`");
+    if (!sql) throw new Error("SQL_REQUIRED: pass SQL after --db or use --file");
+    return print(await request(globals, "POST", "/v1/control/console/sql", { project_id: globals.project, database_id: db, sql }), globals);
+  }
+
+  if (cmd === "invoke") {
+    const capability = sub;
+    const jsonIndex = args.indexOf("--json");
+    const body = jsonIndex >= 0 ? JSON.parse(args[jsonIndex + 1] || "{}") : {};
+    if (!capability) throw new Error("CAPABILITY_REQUIRED: usage `synapsor invoke <capability> --db <database> --json '{...}'`");
+    if (!globals.db) throw new Error("DATABASE_REQUIRED: use `--db <database_id>`");
+    return print(await request(globals, "POST", "/v1/control/console/invoke", { project_id: globals.project, database_id: globals.db, capability, arguments: body }), globals);
+  }
+
+  if (cmd === "evidence" && sub === "get") {
+    if (!third || !globals.db) throw new Error("EVIDENCE_OR_DATABASE_REQUIRED: usage `synapsor evidence get <handle> --db <database>`");
+    return print(await request(globals, "POST", "/v1/control/console/evidence", { project_id: globals.project, database_id: globals.db, uri: third }), globals);
+  }
+
+  if (cmd === "proposal" && ["preview", "approve", "reject"].includes(sub)) {
+    if (!third || !globals.db) throw new Error("PROPOSAL_OR_DATABASE_REQUIRED: usage `synapsor proposal preview <handle> --db <database>`");
+    if (sub !== "preview") await confirm(globals, `Proposal ${sub} is auditable and may change workflow state.`);
+    return print(await request(globals, "POST", `/v1/control/console/proposals/${sub}`, { project_id: globals.project, database_id: globals.db, proposal: third }), globals);
+  }
+
+  if (cmd === "replay") {
+    if (!sub || !globals.db) throw new Error("RUN_OR_DATABASE_REQUIRED: usage `synapsor replay <run-id> --db <database>`");
+    return print(await request(globals, "POST", "/v1/control/console/replay", { project_id: globals.project, database_id: globals.db, run_id: sub }), globals);
+  }
+
+  throw new Error(`UNKNOWN_COMMAND: ${args.join(" ")}`);
+}
+
+function help() {
+  console.log(`Synapsor CLI ${PACKAGE_VERSION}
+
+Usage:
+  synapsor --version
+  synapsor config set base-url https://synapsor.ai
+  synapsor config set api-key
+  synapsor config get
+  synapsor projects list
+  synapsor projects create <name>
+  synapsor db list --project <project>
+  synapsor db create <name> --project <project>
+  synapsor sql --db <database> "SELECT 1;"
+  synapsor sql --db <database> --file ./query.sql
+  synapsor invoke <capability> --db <database> --json '{"ticket_id":"TICK-1001"}'
+  synapsor evidence get <evidence-handle> --db <database>
+  synapsor proposal preview <proposal-handle> --db <database>
+  synapsor proposal approve <proposal-handle> --db <database> --yes
+  synapsor proposal reject <proposal-handle> --db <database> --yes
+  synapsor replay <run-id> --db <database>
+
+Environment:
+  SYNAPSOR_API_KEY, SYNAPSOR_BASE_URL
+
+Synapsor CLI runs Synapsor SQL/API commands only. It never executes server shell commands.`);
+}
+
+main().catch((error) => {
+  const code = error.code || String(error.message || "REQUEST_FAILED").split(":", 1)[0];
+  console.error(error.message || String(error));
+  if (ERROR_HINTS.has(code)) console.error(ERROR_HINTS.get(code));
+  process.exitCode = 1;
+});

package/generated-contract.mjs

@@ -1,6 +1,6 @@
 // Generated by tools/generate_openapi_sdk_contract.py. Do not edit by hand.
 export const PROTOCOL_VERSION = "v1";
-export const CONTRACT_SHA256 = "f738189b0873fe48c5900cbffafb7d4eed90acbe9fc8c7cfcd4db89ad78f106a";
+export const CONTRACT_SHA256 = "d6f052592bc48920a04ecdce12ca82160a57662b67a14a8ce95f0262cb86d6d0";
 export const OPENAPI_OPERATIONS = Object.freeze({
   "approveAgentProposal": {
     "method": "POST",
@@ -209,6 +209,14 @@ export const OPENAPI_OPERATIONS = Object.freeze({
     "public": false,
     "python_method": "run_hybrid_reembed_jobs",
     "request_schema": "#/components/schemas/HybridReembedRunRequest"
+  },
+  "settleAgentProposal": {
+    "method": "POST",
+    "node_method": "settleWrite",
+    "path": "/v1/agent/proposals/settle",
+    "public": false,
+    "python_method": "settle_write",
+    "request_schema": "#/components/schemas/ProposalLifecycleRequest"
   }
 });
 export const PYTHON_OPERATION_METHODS = Object.freeze({
@@ -237,7 +245,8 @@ export const PYTHON_OPERATION_METHODS = Object.freeze({
   "previewAgentProposal": "preview_write",
   "rejectAgentProposal": "reject_write",
   "resumeHybridReembedJob": "resume_hybrid_reembed_job",
-  "runHybridReembedJobs": "run_hybrid_reembed_jobs"
+  "runHybridReembedJobs": "run_hybrid_reembed_jobs",
+  "settleAgentProposal": "settle_write"
 });
 export const NODE_OPERATION_METHODS = Object.freeze({
   "approveAgentProposal": "approveWrite",
@@ -265,7 +274,8 @@ export const NODE_OPERATION_METHODS = Object.freeze({
   "previewAgentProposal": "previewWrite",
   "rejectAgentProposal": "rejectWrite",
   "resumeHybridReembedJob": "resumeHybridReembedJob",
-  "runHybridReembedJobs": "runHybridReembedJobs"
+  "runHybridReembedJobs": "runHybridReembedJobs",
+  "settleAgentProposal": "settleWrite"
 });
 export const PUBLIC_OPERATIONS = Object.freeze([
   "getHealth",

package/package.json

@@ -1,20 +1,25 @@
 {
   "name": "@synapsor/client",
-  "version": "0.1.0",
-  "description": "Node.js client for Synapsor HTTP/JSON APIs",
+  "version": "0.1.2",
+  "description": "Node.js SDK for Synapsor, the agent-native database for auditable AI applications",
   "type": "module",
   "main": "./synapsor.mjs",
+  "bin": {
+    "synapsor": "bin/synapsor.mjs"
+  },
   "exports": {
-    ".": "./synapsor.mjs"
+    ".": "./synapsor.mjs",
+    "./bin/synapsor": "./bin/synapsor.mjs"
   },
   "files": [
+    "bin/synapsor.mjs",
     "synapsor.mjs",
     "generated-contract.mjs",
     "README.md",
     "package.json"
   ],
   "scripts": {
-    "build": "node --check synapsor.mjs && node --check generated-contract.mjs",
+    "build": "node --check synapsor.mjs && node --check generated-contract.mjs && node --check bin/synapsor.mjs",
     "test": "node --test test/*.test.mjs"
   },
   "keywords": [
@@ -28,7 +33,7 @@
   "homepage": "https://synapsor.ai",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/sandeshtiwari/Synapsor.git"
+    "url": "git+https://github.com/synapsor/synapsor.git"
   },
   "bugs": {
     "url": "https://synapsor.ai/contact"

package/synapsor.mjs

@@ -236,14 +236,47 @@ export class Synapsor {
     return results.at(-1).result?.rows ?? [];
   }
 
-  async invokeAgentCapability(capability, args = {}, { session = undefined, traceId = undefined } = {}) {
+  async invokeAgentCapability(capability, args = {}, {
+    session = undefined,
+    traceId = undefined,
+    trace_id = undefined,
+    mode = undefined,
+    autoBranch = undefined,
+    auto_branch = undefined,
+    responseEnvelope = undefined,
+    response_envelope = undefined,
+    includeAuditTrail = undefined,
+    include_audit_trail = undefined,
+    settlementPolicy = undefined,
+    settlement_policy = undefined,
+  } = {}) {
     const payload = {
       capability,
       arguments: args,
       session: this.requireSession(session),
     };
-    if (traceId !== undefined) {
-      payload.trace_id = traceId;
+    const trace = traceId ?? trace_id;
+    const branch = autoBranch ?? auto_branch;
+    const envelope = responseEnvelope ?? response_envelope;
+    const audit = includeAuditTrail ?? include_audit_trail;
+    const policy = settlementPolicy ?? settlement_policy;
+    if (trace !== undefined) {
+      payload.trace_id = trace;
+    }
+    if (mode !== undefined) {
+      payload.mode = mode;
+    }
+    if (branch !== undefined) {
+      payload.auto_branch = Boolean(branch);
+    }
+    if (envelope !== undefined) {
+      payload.response_envelope = Boolean(envelope);
+    }
+    if (audit !== undefined) {
+      payload.include_audit_trail = Boolean(audit);
+    }
+    if (policy !== undefined) {
+      payload.settlement_policy = policy;
     }
     return this.request("POST", "/v1/agent/invoke", payload);
   }
@@ -414,6 +447,13 @@ export class Synapsor {
     return this.proposalLifecycle("cancel", proposal, options);
   }
 
+  async settleWrite(proposal, settlementPolicy, options = {}) {
+    return this.proposalLifecycle("settle", proposal, {
+      ...options,
+      settlementPolicy,
+    });
+  }
+
   async replayAgentRun(runId, options = {}) {
     return this.request("POST", "/v1/agent/runs/replay", {
       run_id: Number(runId),
@@ -422,19 +462,23 @@ export class Synapsor {
     });
   }
 
-  async proposalLifecycle(action, proposal, { session = undefined, promoteBranch = undefined, promote_branch = undefined, targetBranch = undefined, target_branch = undefined } = {}) {
+  async proposalLifecycle(action, proposal, { session = undefined, promoteBranch = undefined, promote_branch = undefined, targetBranch = undefined, target_branch = undefined, settlementPolicy = undefined, settlement_policy = undefined } = {}) {
     const payload = {
       proposal,
       session: this.requireSession(session),
     };
     const shouldPromote = promoteBranch ?? promote_branch;
     const target = targetBranch ?? target_branch;
+    const policy = settlementPolicy ?? settlement_policy;
     if (shouldPromote !== undefined) {
       payload.promote_branch = Boolean(shouldPromote);
     }
     if (target !== undefined) {
       payload.target_branch = target;
     }
+    if (policy !== undefined) {
+      payload.settlement_policy = policy;
+    }
     return this.request("POST", `/v1/agent/proposals/${action}`, payload);
   }