@clidey/whodb-sdk

Official TypeScript/JavaScript SDK for the WhoDB hosted platform — your ontology, datasets, sources, transforms, functions, and org administration as in-code function APIs.

Install

npm install @clidey/whodb-sdk

Requires Node.js ≥ 20.

Quickstart

import { WhoDB } from '@clidey/whodb-sdk';

// Production: API key (create one in org settings → API keys).
// The key carries its org; the project auto-resolves when the key
// has access to exactly one project.
const whodb = new WhoDB({ apiKey: process.env.WHODB_API_KEY });

// Local development: zero config — reuses your `whodb login` session.
// const whodb = new WhoDB();

const users = whodb.ontology('User');

const user = await users.get('u_123');
const active = await users.list({ where: { status: { eq: 'active' } }, pageSize: 100 });
await users.create({ email: '[email protected]' });
await users.createMany(rows, { idempotencyKey: 'import-42' });
await users.update('u_123', { plan: 'pro' });
const orders = await users.followLink('u_123', 'orders');

// Behavior-managed workflow:
const order = whodb.ontology('Order');
const capabilities = await order.capabilities('order_123');
await order.previewAction('approve', 'order_123', { note: 'Looks good' });
await order.action('approve', 'order_123', { note: 'Looks good' }, {
  expectedVersion: capabilities.recordVersion ?? undefined,
  idempotencyKey: 'approve-order-123',
});
const history = await order.actionExecutions('order_123');

// Iterate everything, page by page:
for await (const page of users.list({ pageSize: 500 }).pages()) {
  console.log(page.rows.length);
}

// Datasets and sources:
const kpis = await whodb.dataset('weekly_kpis').rows();
const raw = await whodb.source('src_...').rows({ Kind: 'Table', Locator: 'events' });

// Transforms: run a pipeline and wait for it to finish.
const rollup = whodb.transform('nightly-rollup');
const run = await rollup.run();
const finished = await rollup.wait(run.id, { timeoutMs: 300_000 });

// Functions: promote the draft so it can execute, then run it.
const normalize = whodb.function('normalize');
await normalize.promote('v1');                 // snapshot + set active production version
const result = await normalize.execute({ name: 'Ada' });
const queued = await normalize.startRun({ batch: 7 });
await normalize.wait(queued.id);

// Org administration (requires org manage rights):
const sa = await whodb.serviceAccounts().create('ci-deployer');
const { rawKey } = await whodb.serviceAccounts().createKey(sa.id); // shown once — store it securely
await whodb.lineageProviders().save({ name: 'marquez', endpoint: 'https://...', authType: 'none', enabled: true });
await whodb.sharing().share('ont_...', 'organization');

Authentication

Credential precedence:

1. new WhoDB({ apiKey }) / { token } / { credentials } constructor options
2. WHODB_API_KEY environment variable
3. The whodb CLI's stored login (whodb login), gcloud-ADC-style — ideal for local development

Workspace (org / project) is optional with an API key; pass { project } or set WHODB_PROJECT when the key has access to more than one project.

Typed clients

Generate typed entity classes from your project's ontology:

whodb sdk generate --language ts --out src/whodb-gen/

import { createClient } from './whodb-gen/whodb.generated.js';

const { ontology } = createClient({ apiKey: process.env.WHODB_API_KEY });
const user = await ontology.User.get('u_123'); // fully typed

Versioning

Each SDK release is generated against one WhoDB platform release. Deprecated operations warn once per process with their removal date; operations removed from the platform raise WhoDBVersionError — upgrade the package to resolve.

License

Apache-2.0