@colixsystems/datastore-client

Typed, scoped client for the AppStudio datastore API. Widgets receive an instance through the injected WidgetContext.datastore — they never instantiate this client themselves.

See the design reference: docs/architecture/widget-marketplace.md, specifically section 3.2.

Status

v0.2.0 — pre-publish. Not yet published to npm.

Differences from frontend/src/api/client.js

| Concern | frontend/src/api/client.js | @colixsystems/datastore-client | | --- | --- | --- | | Auth header | Reads useAuthStore directly | Token injected by host | | Tenant header | Pulled from store | Injected by host; widget cannot override | | Retries | None | Idempotent GETs retried 3x with exponential backoff | | Timeouts | Browser default | 10s default, configurable per call | | Error model | Raw axios error | Typed DatastoreError hierarchy | | Platform | Browser only | Browser and React Native (uses fetch) |

Public API

import {
  createDatastoreClient,
  DatastoreError,
  NotFoundError,
  ForbiddenError,
  ValidationError,
  RateLimitedError,
  ServerError,
} from "@colixsystems/datastore-client";

const client = createDatastoreClient({
  baseUrl: "https://api.appstudio.io",
  getToken: () => "Bearer ...",
  getTenantId: () => "tenant_abc",
  // fetchImpl defaults to globalThis.fetch
});

const tables = await client.tables.list();
const orders = await client.records("orders").list({ filter: { status: "PAID" } });

Dependencies

None. The client uses only platform fetch and AbortController, both available in modern browsers, Node 18+, and React Native.