Sery SDK (TypeScript / JavaScript)

Query your private data mesh by sery:// address — one SQL statement, run on whichever machine holds the data. Raw data never moves through Sery; only result rows come back.

npm install @seryai/sdk

Zero runtime dependencies. Works in Node ≥ 18, browsers, Deno, Bun, and edge runtimes (anything with fetch).

Quick start

import { Client } from "@seryai/sdk";

const client = new Client({ apiKey: "sery_..." }); // from app.sery.ai → Settings → API Keys

const result = await client.query(`
  SELECT customer, SUM(amount) AS total
  FROM 'sery://sam-laptop/local/sales/orders.parquet'
  GROUP BY customer
  ORDER BY total DESC
`);

console.table(result.toObjects());

Addresses

Sources are addressed as sery://<machine>/<protocol>/<path>:

• <machine> — a machine's name or stable id (e.g. sam-laptop)
• <protocol> — local, s3, or https
• <path> — the file path / bucket key

Discover what's addressable with the catalog:

for (const src of await client.catalog()) {
  console.log(src.seryUri, "—", src.machine, src.fileFormat);
  // sery://sam-laptop/local/sales/orders.parquet — sam-laptop parquet
}

Any seryUri from catalog() is guaranteed to resolve.

Results

const result = await client.query("SELECT * FROM 'sery://my-mac/local/data.parquet' LIMIT 5");

result.columns;        // ["id", "name", ...]
result.rows;           // [[1, "a"], [2, "b"], ...]
result.toObjects();    // [{ id: 1, name: "a" }, ...]
for (const row of result) console.log(row.name); // iterate as objects

result.incomplete;     // true if a machine didn't respond
result.warnings;       // human-readable warnings to surface

When incomplete is true, a targeted machine was offline — check warnings before trusting an aggregate (a SUM/COUNT may undercount).

Errors

Every failure is a typed error:

| Class | When | |-------|------| | AuthError | missing / invalid API key (401) | | QueryError | no sery:// refs, bad address, unsupported protocol (400) | | MachineNotFound | unknown machine (404) | | AmbiguousMachine | a name matched >1 machine — .candidates (409) | | CrossMachineJoinUnsupported | the query spans machines — .machines (422) | | MachinesUnavailable | every targeted machine offline — .failures (503) |

import { AmbiguousMachine } from "@seryai/sdk";

try {
  await client.query("SELECT * FROM 'sery://laptop/local/x.parquet'");
} catch (e) {
  if (e instanceof AmbiguousMachine) {
    for (const c of e.candidates) console.log(c.label, c.machine_id); // re-issue with machine_id
  }
}

Limitations (v1)

• All sources in one query must live on the same machine — cross-machine joins throw CrossMachineJoinUnsupported.
• Routable protocols: local, s3, https.

License

MIT