Client SDK

pnpm add @objectstack/client

import { ObjectStackClient } from '@objectstack/client';

const client = new ObjectStackClient({
  baseUrl: 'http://localhost:3004',
});

async function main() {
  // 1. Connect — resolves with the discovery manifest
  const discovery = await client.connect();

  // 2. Check available services
  console.log('Services:', discovery.services);
  // → { metadata: { enabled: true, status: 'degraded', message: 'In-memory metadata registry — …' },
  //     data: { enabled: true, status: 'available' }, auth: { enabled: false, ... } }
  // `metadata` reports the implementation actually behind it: `degraded` plus a
  // message naming what is missing while the kernel's in-memory fallback fills
  // the slot, `available` once MetadataPlugin provides a persisted registry.

  // 3. Query data
  const tasks = await client.data.find('todo_task', {
    fields: ['subject', 'priority'],
    where: { priority: { $gte: 2 } },
    orderBy: ['-priority'],
    limit: 10
  });

  // 4. Create a record
  const newTask = await client.data.create('todo_task', {
    subject: 'New Task',
    priority: 1
  });

  // 5. Batch operations
  const result = await client.data.batch('todo_task', {
    operation: 'update',
    records: [
      { id: '1', data: { status: 'active' } },
      { id: '2', data: { status: 'active' } }
    ],
    options: { atomic: true, returnRecords: true }
  });
  console.log(`Updated ${result.succeeded} records`);
}

// connect() resolves with the discovery manifest — capture the return value
const discovery = await client.connect();

console.log(discovery.version);      // the serving artifact's version
console.log(discovery.environment);  // "development"

// Check if a service is available before using it
if (discovery.services?.auth?.enabled) {
  // Auth plugin is installed — login is available
  await client.auth.login({ email: 'admin@example.com', password: 'secret' });
} else {
  console.log(discovery.services?.auth?.message);
  // → "Install an auth plugin to enable"
}

// Get object schema (getItem('object', name) returns the object definition)
const accountSchema = await client.meta.getItem('object', 'account');
console.log(accountSchema.fields);

// List all metadata types
const types = await client.meta.getTypes();
// → { types: ['object', 'view', 'plugin', ...] }

// Get with ETag caching
const cached = await client.meta.getCached('account', {
  ifNoneMatch: '"686897696a7c876b7e"'
});
if (cached.notModified) {
  console.log('Using cached metadata');
}

// Get auto-generated view
const listView = await client.meta.getView('account', 'list');

// Sub-resource identity is DOT-qualified — `<object>.<viewKey>`, never a `/`
const view = await client.meta.getItem('view', 'crm_lead.pipeline');

// Per-item draft lifecycle (ADR-0033)
await client.meta.publishItem('object', 'account', { message: 'go live' });
await client.meta.rollbackItem('object', 'account', 3);
const diff = await client.meta.diffItem('object', 'account', { from: 2, to: 5 });

// Introspection & governance
const bad = await client.meta.getDiagnostics({ severity: 'error' });
const refs = await client.meta.getReferences('object', 'account');
const trail = await client.meta.getAudit('object', 'account', { limit: 20 });
const tree = await client.meta.getBookTree('handbook');

// Operator: rewrite stored rows into today's canonical shape (ADR-0087).
// Preview unless `apply: true`; requires the `manage_metadata` capability.
const report = await client.meta.migrateStored({ apply: true });

// Find with query options
const accounts = await client.data.find('account', {
  fields: ['name', 'industry', 'revenue'],
  where: { industry: 'Technology' },
  orderBy: ['-revenue'],
  limit: 20,
  offset: 0,
});

// Get by ID
const account = await client.data.get('account', '123');

// Create
const created = await client.data.create('account', {
  name: 'Acme Corp',
  industry: 'Technology',
});

// Update (partial)
const updated = await client.data.update('account', '123', {
  industry: 'Healthcare',
});

// Delete
await client.data.delete('account', '123');

// Batch operation (recommended for bulk)
const batchResult = await client.data.batch('account', {
  operation: 'upsert',
  records: [
    { id: '1', data: { name: 'Acme', status: 'active' } },
    { id: '2', data: { name: 'Beta', status: 'active' } },
  ],
  options: {
    atomic: true,
    returnRecords: true,
    continueOnError: false,
  },
});

// Convenience bulk methods
await client.data.createMany('account', [{ name: 'A' }, { name: 'B' }]);
await client.data.updateMany('account', [
  { id: '1', data: { status: 'closed' } },
  { id: '2', data: { status: 'closed' } },
]);
await client.data.deleteMany('account', ['1', '2', '3']);

// Atomic cross-object batch (master-detail save) — runs every operation in
// ONE server-side transaction (POST /api/v1/batch): commit all or roll back
// all. `{ $ref: <op index> }` lets a child reference a parent created earlier
// in the same request. Always atomic — unlike per-object `data.batch()`,
// there is no partial-success mode.
const { results } = await client.data.batchTransaction([
  { object: 'project', action: 'create', data: { name: 'Apollo' } },
  { object: 'task', action: 'create', data: { title: 'Kickoff', project: { $ref: 0 } } },
]);

// Semantic analytics query (cube-style)
const result = await client.analytics.query({
  cube: 'account',
  measures: ['revenue_sum', 'count'],
  dimensions: ['industry'],
  where: { status: 'active' },
  limit: 100,
});

// Get cube metadata — all cubes, or one with meta('account')
const meta = await client.analytics.meta('account');

// Dry-run a query to its generated SQL (POST /analytics/sql)
const explained = await client.analytics.explain({
  cube: 'account',
  measures: ['revenue_sum'],
});

const packages = await client.packages.list();
await client.packages.install({ id: 'com.objectstack.plugin-auth', version: '1.0.0' });
await client.packages.enable('com.objectstack.plugin-auth');
await client.packages.disable('com.objectstack.plugin-auth');
await client.packages.uninstall('com.objectstack.plugin-auth');

// Auth — User authentication and session management
await client.auth.login({ email: 'user@example.com', password: 'pass' });
await client.auth.register({ email: 'new@example.com', password: 'pass', name: 'New User' });
await client.auth.me();
await client.auth.logout();
await client.auth.refreshToken('refresh-token-string');

// Approvals — request-based decision API (ADR-0019)
// Approval is a flow node, not a workflow step: decisions are keyed by request id.
await client.approvals.listRequests({ status: 'pending' }); // "my approvals" inbox
await client.approvals.getRequest(requestId);
await client.approvals.approve(requestId, { comment: 'Looks good' });
await client.approvals.reject(requestId, { comment: 'Incomplete' });
await client.approvals.listActions(requestId); // audit trail

// Notifications — inbox/receipt spine (ADR-0030)
await client.notifications.list({ read: false });
await client.notifications.markRead(['notif-1', 'notif-2']);
await client.notifications.markAllRead();

// ADR-0030 note: the framework pipeline now materializes in-app messages
// through sys_inbox_message and tracks read-state in sys_notification_receipt.
// These helpers will be repointed during the objectui bell cut-over.

// AI — served by `service-ai` (Cloud/EE). Without it the route is mounted but
// unimplemented, so it answers 501 and discovery reports the slot unavailable
// with the same sentence; check `discovery.services` first.
const answer = await client.ai.chat({
  messages: [{ role: 'user', content: 'How many open orders this quarter?' }],
  conversationId,                        // omit to have one created and echoed back
});
answer.content;                          // string
answer.usage?.totalTokens;

// Streaming — the Vercel UI Message Stream Protocol, frame by frame.
for await (const frame of await client.ai.chatStream({ messages })) {
  if (frame.type === 'text-delta') process.stdout.write(frame.delta as string);
}

await client.ai.complete({ prompt: 'Summarise this account in one line:' });
await client.ai.models();                // plan-filtered picker list (ADR-0028)

// Conversations — all six routes, scoped to the authenticated user server-side.
const conv = await client.ai.conversations.create({ title: 'Q3 pipeline' });
await client.ai.conversations.list({ limit: 20 });
await client.ai.conversations.get(conv.id);
await client.ai.conversations.addMessage(conv.id, { role: 'user', content: 'hi' });
await client.ai.conversations.update(conv.id, { title: 'Renamed' });
await client.ai.conversations.delete(conv.id);

// Named agents — `ai.chat` talks to the environment default; these talk to one
// you name. The catalog is access-filtered server-side (ADR-0049), so an empty
// list is a legitimate answer for a seat-less user, not an error to retry.
const agents = await client.ai.agents.list();
await client.ai.agents.chat('build', { messages, context: { appId: 'crm' } });
for await (const frame of await client.ai.agents.chatStream('build', { messages })) {
  if (frame.type === 'text-delta') process.stdout.write(frame.delta as string);
}

// Pending actions — the human-in-the-loop queue. A tool call needing a human
// decision parks here instead of executing.
await client.ai.pendingActions.list({ status: 'pending', limit: 20 });
await client.ai.pendingActions.get('pa_1');
const outcome = await client.ai.pendingActions.approve('pa_1');
// CHECK `outcome.status`: approve runs the tool, and a tool that fails comes
// back { status: 'failed', error } on HTTP 200 — the approval succeeded, the
// execution did not. Code that reads only `res.ok` calls that a success.
if (outcome.status === 'failed') console.error(outcome.error);
await client.ai.pendingActions.reject('pa_1', 'wrong account');
// Listing takes `ai:read`, deciding takes `ai:approve` — a caller that can see
// the queue may still be refused on approve. Handle the 403.

// In a React chat UI prefer `useChat()` (`@ai-sdk/react`) over `ai.chatStream`:
// it speaks the same protocol and owns message state. These methods are for
// everything that is not a component — server code, jobs, CLIs, tests.
//
// #3718 history: `client.ai` used to hold `nlq`, `suggest` and `insights`,
// building /api/v1/ai/{nlq,suggest,insights}. No server in any repo ever
// mounted those paths, so every call 404ed for the whole life of the
// namespace. They were typed and shipped, which is exactly why they looked
// usable. v17 removed them; the methods above are the surface that exists.

// i18n — Internationalization
await client.i18n.getLocales();
await client.i18n.getTranslations('zh-CN');
await client.i18n.getFieldLabels('account', 'zh-CN');

// Automation — Trigger workflows and automations
await client.automation.trigger('send_welcome_email', { userId });

// A flow that does not run REJECTS — it does not resolve with an inner
// `{ success: false }`. Branch on the thrown error's `code`, not on the
// resolved value. The narrowed `catch` this needs under `strict` is its own
// block below: "Flow execution errors", under Error Handling.
await client.automation.execute('order_approval', { params: { orderId } });

// Screen flows pause for user input instead of completing. `execute()` returns
// `{ status: 'paused', runId, screen }`; render the screen, then resume the run
// with the collected values. A wizard pauses again for each further step.
const run = await client.automation.execute('convert_lead', { params: { recordId } });
// `execute` returns `AutomationResult`, on which `runId` and `screen` are
// OPTIONAL — a run that COMPLETED carries neither — so narrow before resuming.
if (run.status === 'paused' && run.runId) {
  await client.automation.resume('convert_lead', run.runId, {
    inputs: { account_name: 'Radium Labs' },
  });
}
// Re-fetch the pending screen when the client did not launch the run itself
// (a page reload, another tab, an inbox):
await client.automation.getScreen('convert_lead', runId);

// Actions — Invoke server-registered action handlers
// (engine.registerAction). The result is `{ success, data | error }` — a
// failure comes back as `success: false` + `error` instead of a thrown
// exception, so it can be surfaced as a toast. This surface is the one place
// a non-2xx does NOT throw: failures speak HTTP (400 rejection, 404 / 403 /
// 503 dispatch failures, 500 crash) and the SDK folds them into the result;
// on success, `data` is the handler's return value directly.
const res = await client.actions.invoke('crm_lead', 'convert', {
  recordId,
  params: { create_opportunity: true },
});
if (!res.success) console.warn(res.error);
// Global (object-less) actions dispatch to the server's 'global' handler key:
await client.actions.invokeGlobal('nightly_cleanup', { params: { dryRun: true } });

// API Keys — the raw secret is returned exactly ONCE; store it immediately.
const apiKey = await client.keys.create({ name: 'CI key', expiresAt: '2027-01-01' });
console.log(apiKey.key); // never re-displayable

// Share Links — manage record share links (public token URLs stay browser-only)
const link = await client.shareLinks.create('crm_account', recordId, {
  permission: 'view',
  expiresAt: '2026-12-31',
});
await client.shareLinks.list({ object: 'crm_account' });
await client.shareLinks.revoke(link.token);

// Security (admin) — resolve package audience-binding suggestions (ADR-0090)
const { suggestions } = await client.security.suggestedBindings.list({ status: 'pending' });
// A suggestion ROW is deliberately open (`Record<string, unknown>`) — its column
// set belongs to the backing object, not the contract. Read the fields you know
// (`id`, `status`, `package_id`) and narrow them at the point of use.
await client.security.suggestedBindings.confirm(String(suggestions[0].id));

// Storage — File upload and management
await client.storage.upload(fileData, 'user');
await client.storage.getDownloadUrl('file-123');

import { createQuery, createFilter } from '@objectstack/client';

const query = createQuery('account')
  .select('name', 'industry', 'revenue')
  .where((f) => {
    f.equals('industry', 'Technology');
    f.greaterThan('revenue', 10000);
  })
  .orderBy('revenue', 'desc')
  .limit(50)
  .build();

const results = await client.data.query('account', query);

import { createFilter } from '@objectstack/client';

const filter = createFilter()
  .equals('status', 'active')        // field = value
  .notEquals('type', 'archived')      // field != value
  .greaterThan('revenue', 10000)      // field > value
  .lessThanOrEqual('age', 100)        // field <= value
  .in('category', ['A', 'B', 'C'])   // field IN (...)
  .like('name', '%Corp%')             // pattern match — the wildcards are YOURS
  .ilike('name', '%corp%')            // same, ignoring ASCII case
  .contains('name', 'Corp')           // literal substring — no wildcards involved
  .startsWith('name', 'Acme')         // literal prefix
  .isNull('deleted_at')               // field IS NULL
  .between('created_at', '2024-01', '2024-12')
  .build();

/**
 * What the SDK attaches to the `Error` it throws for a non-2xx response.
 * `httpStatus` is always set; the rest are present only when the server
 * sent them.
 */
interface ObjectStackApiError extends Error {
  httpStatus: number;
  code?: string;
  category?: string;
  retryable?: boolean;
  details?: unknown;
  fields?: { field: string; code: string; message: string }[];
}

function isApiError(error: unknown): error is ObjectStackApiError {
  return error instanceof Error && 'httpStatus' in error;
}

try {
  await client.data.create('todo_task', { subject: '' });
} catch (error) {
  if (!isApiError(error)) throw error;  // not a server response — rethrow
  console.error(error.code);       // 'VALIDATION_FAILED'
  console.error(error.httpStatus); // 400
  console.error(error.category);   // optional — set only when the server sent it
  console.error(error.retryable);  // optional — set only when the server sent it
  console.error(error.details);    // { ... }
}

try {
  await client.data.create('contact', { email: 'not-an-email' });
} catch (error) {
  if (!isApiError(error)) throw error;
  if (error.code === 'VALIDATION_FAILED') {
    for (const f of error.fields ?? []) {
      showFieldError(f.field, f.message);   // 'email', 'email must be a valid email address'
    }
  }
}

/**
 * What the automation door attaches to `details` on a `FLOW_FAILED`: the run's
 * own artefacts. A flow that never dispatched (`FLOW_DISABLED`,
 * `FLOW_NO_START_NODE`, `FLOW_INPUT_SCHEMA_INVALID`, or an unknown flow's 404)
 * has no author text and no node log to point at, which is why both members
 * are optional.
 */
interface FlowFailureDetails {
  errorMessage?: string;   // the flow author's own text (`flow.errorMessage`)
  summary?: unknown;       // per-node accounting (spec's `FlowRunSummary`)
}

function hasFlowFailureDetails(
  error: ObjectStackApiError,
): error is ObjectStackApiError & { details: FlowFailureDetails } {
  return typeof error.details === 'object' && error.details !== null;
}

try {
  await client.automation.execute('order_approval', { params: { orderId } });
} catch (err) {
  if (!isApiError(err)) throw err;     // not a server response — rethrow
  console.error(err.httpStatus);       // 409 | 422 | 400 | 404
  console.error(err.code);             // 'FLOW_DISABLED' | 'FLOW_NO_START_NODE' | 'FLOW_INPUT_SCHEMA_INVALID' | 'FLOW_FAILED'
  if (err.code === 'FLOW_FAILED' && hasFlowFailureDetails(err)) {
    console.error(err.details.errorMessage);   // the flow author's own text
    console.error(err.details.summary);        // which node failed
  }
}

interface ClientConfig {
  /** ObjectStack server URL */
  baseUrl: string;
  /** Bearer token for authentication (if auth plugin installed) */
  token?: string;
  /** Custom fetch implementation (e.g. for SSR or testing) */
  fetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
  /** Logger instance for debugging */
  logger?: Logger;
  /** Enable debug logging */
  debug?: boolean;
  /** Active project/environment id — injects an `X-Environment-Id` header for multi-tenant routing */
  environmentId?: string;
  /** Active UI locale (BCP-47, e.g. `'zh-CN'`) — injects an `Accept-Language` header; sync via `setLocale()` */
  locale?: string;
}

pnpm add @objectstack/client-react

import { ObjectStackProvider, useClient, useQuery } from '@objectstack/client-react';
import { ObjectStackClient } from '@objectstack/client';

// 1. Wrap your app with the provider
const client = new ObjectStackClient({ baseUrl: 'http://localhost:3004' });

function App() {
  return (
    <ObjectStackProvider client={client}>
      <AccountList />
    </ObjectStackProvider>
  );
}

// 2. Use hooks in child components
function AccountList() {
  const { data, isLoading, error, refetch } = useQuery('account', {
    where: { status: 'active' },
    orderBy: ['-created_at'],
    limit: 20,
  });

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;
  return data?.records.map(a => <div key={a.id}>{a.name}</div>);
}

cd packages/client
pnpm test

# Prerequisite: Start an ObjectStack server with test data
# For example, using the reference server repository
# Follow the server repository's documentation for local setup

# From this repository, run the integration test script
cd packages/client
pnpm test:integration