WeaveKit Docs

API reference

All methods return Promises; non-2xx responses throw ClientError.

createClient(options): Client

interface ClientOptions {
  baseUrl: string;          // engine base URL, e.g. 'http://localhost:3000'
  prefix?: string;          // REST prefix, defaults to '/api'
  apiKey?: string;          // sent as `Authorization: Bearer <apiKey>`
  fetch?: typeof fetch;     // inject for testing / custom transport (default: global fetch)
}
interface Client {
  objects<T = Record<string, unknown>>(name: string): ObjectsClient<T>;
}

objects<T>(name): ObjectsClient<T>

All methods return Promises; non-2xx responses throw ClientError.

find(params?)

async find(params?: FindParams): Promise<RestResult<T>>
ParamTypeWire format
filterFilterJSON-encoded query param
sort{ field: string; direction: 'asc' | 'desc' }[]field:direction,...
fieldsstring[]comma-separated projection
limitnumberint
offsetnumberint
interface RestResult<T> {
  rows: T[];
  total: number;
  limit: number;
  offset: number;
}

Filter supports exact values and operators — { gt, gte, lt, lte, ne, in, contains }:

await leads.find({ filter: { score: { gte: 10 }, tags: { contains: 'hot' } } });

findOne(id, params?)

async findOne(id: string, params?: { fields?: string[] }): Promise<T | null>

Returns the record, or null when the engine answers 404 (data.recordNotFound) — e.g. the row is outside the caller's RBAC scope.

id is the record's record_key (surfaced on each record as the read-only virtual field weave_id), not the raw primary-key value. Request it in find({ fields: ['weave_id', …] }) (or read it from create) and pass that string to findOne / update / delete / workflow.*.

create(data)

async create(data: Partial<T>): Promise<T>

POST to the collection; resolves the created record. Required fields are enforced server-side (400).

update(id, changes)

async update(id: string, changes: Partial<T>): Promise<T>

PATCH on the record. Updating a row outside the caller's scope throws ClientError with status 404.

delete(id)

async delete(id: string): Promise<void>

DELETE; resolves on 204.

ClientError

class ClientError extends Error {
  status: number;            // 401/403/404/400/500/...
  code: string;              // engine error code, e.g. 'rbac.denied.read'
  params?: Record<string, unknown>;
  message: string;
}

Thrown for every non-2xx response; the body is parsed from the engine's uniform error envelope { error: { code, message, params? } } (falls back to http.internal when unparseable).

import { ClientError } from '@weave-kit/client';

try {
  await leads.find();
} catch (error) {
  if (error instanceof ClientError && error.code === 'auth.missingKey') {
    // prompt for an API key
  }
}

Common codes: auth.missingKey/auth.invalidKey (401), rbac.* (403), data.recordNotFound/data.objectUnknown (404), data.field.*/http.param.invalid (400).

client.scripts

Administrator editing of an object's server.js lifecycle-hook source:

const document = await client.scripts.getSource('lead', 'server');
if (document !== null) {
  await client.scripts.save('lead', 'server', document.source, {
    expectVersion: document.version,
  });
}

getSource returns { source, version } or null for a missing file. save returns { ok, committed, version }; changed content is written and committed by the engine. expectVersion is accepted for forward compatibility — the write is last-write-wins. Both reading and writing require a role listed in the engine's adapters.rest.adminRoles.

On this page