TypeScript SDK

@primitives/sdk is the official TypeScript client. It ships ESM and CommonJS builds with full types, uses the global fetch, and needs Node.js 18 or later.

npm i @primitives/sdk

Client

import { Primitives } from '@primitives/sdk';

const local = new Primitives();                                       // PRIMITIVES_URL or http://localhost:7777
const cloud = new Primitives({ token: process.env.PRIMITIVES_API_KEY }); // pk_… → https://api.useprimitives.com
const agent = new Primitives({ token: process.env.AGENT_API_KEY });   // a pk_ key scoped to one group and some tools

Durations are strings such as '250ms', '30s', '5m', '1h' or '7d', or numbers of milliseconds. Grant ttls must be strings.

Groups

A group is a collection of primitives reached with one key. It starts empty: create the primitives you need inside it.

Primitives

Every primitive has an immutable id. Create, list and open primitives by id from the client:

group.db, group.fs, group.queue, group.memory, group.vault, group.kv and group.storage are shortcuts that work by name inside one group:

const g = await p.groups.create({ name: 'agent-42' });

const orders = await g.db.create('orders'); // create in this group; orders.id is its id
const cache = g.db('cache');                // resolved by name in the group on first use
const all = await g.db.list();              // PrimitiveInfo[] for every database

const same = p.db(orders.id);               // the same database, by id

Every handle has the same lifecycle methods:

A data method that doesn't fit the primitive's type throws wrong_type.

Database: p.db(id)

QueryResult is { columns, rows, rows_affected, last_insert_rowid, truncated }. Parameters are a positional array or an object of named values; Uint8Array values are sent as blobs.

Filesystem: p.fs(id)

FileInfo is { path, kind, size, hash, mode, mtime }. fork() copies the whole filesystem; forkDir() copies one directory within it.

Queue: p.queue(id)

A queue primitive holds any number of named queues and topics. store.queue(name) returns one queue, created on first send:

const jobs = g.queue('jobs');
await jobs.queue('emails').send({ to: 'ada@example.com' });

Job has id, body, attempts, lastError and data, plus heartbeat({ extend? }), ack(), retry({ in?, error? }), fail(error?) and dead(error?). store.queues() returns per-queue counts, and store.topics has subscribe(topic, queue), unsubscribe(topic, queue) and publish(topic, body).

Memory: p.memory(id)

Vault: p.vault(id)

KV: p.kv(id)

KvEntry is { key, value, encoding, version, expires_at, created_at, updated_at }. A failed ifVersion throws precondition_failed. See KV.

Storage: p.storage(id)

ObjectInfo is { key, size, etag, content_type, metadata, created_at, updated_at }. Failed conditions throw precondition_failed, and a range past the end range_not_satisfiable. See Storage.

Errors

Every API error is thrown as a PrimitivesError with status, code, message and requestId:

import { PrimitivesError } from '@primitives/sdk';

try {
  await trial.promote();
} catch (err) {
  if (err instanceof PrimitivesError && err.code === 'branch_conflict') {
    await trial.discard();
  } else {
    throw err;
  }
}

The error codes are listed in the REST API reference.