@colixsystems/datastore-client 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AppStudio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,48 @@
+# @colixsystems/datastore-client
+
+Typed, scoped client for the [AppStudio](https://github.com/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`](../../docs/architecture/widget-marketplace.md), specifically section 3.2.
+
+## Status
+
+`v0.1.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
+
+```js
+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.

package/dist/client.js

@@ -0,0 +1,133 @@
+// Datastore client factory.
+// The host injects baseUrl, a token provider, a tenant-id provider, and an
+// optional fetch implementation. Widgets never touch this directly — they
+// receive a built client through WidgetContext.datastore.
+
+import { errorFromResponse, DatastoreError } from "./errors.js";
+import { withRetry } from "./retry.js";
+
+function joinUrl(base, path) {
+  const b = base.endsWith("/") ? base.slice(0, -1) : base;
+  const p = path.startsWith("/") ? path : `/${path}`;
+  return `${b}${p}`;
+}
+
+function buildQueryString(query) {
+  if (!query || typeof query !== "object") return "";
+  const parts = [];
+  if (query.limit != null) parts.push(`limit=${encodeURIComponent(query.limit)}`);
+  if (query.cursor) parts.push(`cursor=${encodeURIComponent(query.cursor)}`);
+  if (query.sort && Array.isArray(query.sort)) {
+    const sortStr = query.sort
+      .map((s) => `${s.dir === "desc" ? "-" : ""}${s.field}`)
+      .join(",");
+    if (sortStr) parts.push(`sort=${encodeURIComponent(sortStr)}`);
+  }
+  if (query.filter && typeof query.filter === "object") {
+    parts.push(`filter=${encodeURIComponent(JSON.stringify(query.filter))}`);
+  }
+  return parts.length ? `?${parts.join("&")}` : "";
+}
+
+/**
+ * @param {object} opts
+ * @param {string} opts.baseUrl
+ * @param {() => string | Promise<string>} opts.getToken  Returns the Authorization header value (e.g. "Bearer <jwt>").
+ * @param {() => string | Promise<string>} opts.getTenantId Returns the x-tenant-id header value.
+ * @param {typeof fetch} [opts.fetchImpl] Defaults to globalThis.fetch.
+ */
+export function createDatastoreClient(opts) {
+  if (!opts || typeof opts !== "object") {
+    throw new TypeError("createDatastoreClient: opts is required");
+  }
+  const { baseUrl, getToken, getTenantId } = opts;
+  if (typeof baseUrl !== "string" || baseUrl.length === 0) {
+    throw new TypeError("createDatastoreClient: baseUrl is required");
+  }
+  if (typeof getToken !== "function") {
+    throw new TypeError("createDatastoreClient: getToken must be a function");
+  }
+  if (typeof getTenantId !== "function") {
+    throw new TypeError("createDatastoreClient: getTenantId must be a function");
+  }
+  const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+  if (typeof fetchImpl !== "function") {
+    throw new TypeError(
+      "createDatastoreClient: no fetch available. Pass fetchImpl or run in an environment with global fetch."
+    );
+  }
+
+  async function request(method, path, { body, timeoutMs } = {}) {
+    const url = joinUrl(baseUrl, path);
+    const token = await getToken();
+    const tenantId = await getTenantId();
+
+    const headers = { accept: "application/json" };
+    if (token) headers.authorization = token.startsWith("Bearer ") ? token : `Bearer ${token}`;
+    if (tenantId) headers["x-tenant-id"] = tenantId;
+    if (body !== undefined) headers["content-type"] = "application/json";
+
+    return withRetry({ method, timeoutMs }, async (signal) => {
+      let res;
+      try {
+        res = await fetchImpl(url, {
+          method,
+          headers,
+          body: body !== undefined ? JSON.stringify(body) : undefined,
+          signal,
+        });
+      } catch (err) {
+        // Network or abort failure — let withRetry decide if retryable.
+        throw new DatastoreError(`Network failure: ${err.message}`, {
+          code: "NETWORK",
+          status: 0,
+        });
+      }
+
+      const text = await res.text();
+      let parsed = null;
+      if (text.length > 0) {
+        try {
+          parsed = JSON.parse(text);
+        } catch {
+          parsed = { raw: text };
+        }
+      }
+      if (!res.ok) {
+        throw errorFromResponse(res.status, parsed);
+      }
+      return parsed;
+    });
+  }
+
+  function recordsNs(table) {
+    if (typeof table !== "string" || table.length === 0) {
+      throw new TypeError("records(table): table must be a non-empty string");
+    }
+    const enc = encodeURIComponent(table);
+    return {
+      list: (query) => request("GET", `/tables/${enc}/records${buildQueryString(query)}`),
+      get: (id) => request("GET", `/tables/${enc}/records/${encodeURIComponent(id)}`),
+      create: (values) => request("POST", `/tables/${enc}/records`, { body: values }),
+      update: (id, values) =>
+        request("PATCH", `/tables/${enc}/records/${encodeURIComponent(id)}`, { body: values }),
+      delete: (id) => request("DELETE", `/tables/${enc}/records/${encodeURIComponent(id)}`),
+      aggregate: (spec) => request("POST", `/tables/${enc}/aggregate`, { body: spec }),
+    };
+  }
+
+  return {
+    tables: {
+      list: () => request("GET", `/tables`),
+      get: (idOrName) => request("GET", `/tables/${encodeURIComponent(idOrName)}`),
+    },
+    records: recordsNs,
+    users: {
+      me: () => request("GET", `/app/users/me`),
+      get: (id) => request("GET", `/app/users/${encodeURIComponent(id)}`),
+    },
+    groups: {
+      listMine: () => request("GET", `/app/groups/mine`),
+    },
+  };
+}

package/dist/errors.js

@@ -0,0 +1,69 @@
+// Typed error hierarchy for the datastore client.
+// Each subclass carries .code, .status, and .details so callers can branch
+// without parsing strings.
+
+export class DatastoreError extends Error {
+  constructor(message, { code = "DATASTORE_ERROR", status = 0, details = null } = {}) {
+    super(message);
+    this.name = "DatastoreError";
+    this.code = code;
+    this.status = status;
+    this.details = details;
+  }
+}
+
+export class NotFoundError extends DatastoreError {
+  constructor(message = "Resource not found", details = null) {
+    super(message, { code: "NOT_FOUND", status: 404, details });
+    this.name = "NotFoundError";
+  }
+}
+
+export class ForbiddenError extends DatastoreError {
+  constructor(message = "Forbidden", details = null) {
+    super(message, { code: "FORBIDDEN", status: 403, details });
+    this.name = "ForbiddenError";
+  }
+}
+
+export class ValidationError extends DatastoreError {
+  constructor(message = "Validation failed", details = null) {
+    super(message, { code: "VALIDATION", status: 400, details });
+    this.name = "ValidationError";
+  }
+}
+
+export class RateLimitedError extends DatastoreError {
+  constructor(message = "Rate limited", details = null) {
+    super(message, { code: "RATE_LIMITED", status: 429, details });
+    this.name = "RateLimitedError";
+  }
+}
+
+export class ServerError extends DatastoreError {
+  constructor(message = "Server error", status = 500, details = null) {
+    super(message, { code: "SERVER_ERROR", status, details });
+    this.name = "ServerError";
+  }
+}
+
+/**
+ * Map an HTTP response status + body to the appropriate DatastoreError subclass.
+ */
+export function errorFromResponse(status, body) {
+  const details = body && typeof body === "object" ? body : null;
+  const message = details?.error?.message || details?.message || `HTTP ${status}`;
+  switch (status) {
+    case 400:
+      return new ValidationError(message, details);
+    case 403:
+      return new ForbiddenError(message, details);
+    case 404:
+      return new NotFoundError(message, details);
+    case 429:
+      return new RateLimitedError(message, details);
+    default:
+      if (status >= 500) return new ServerError(message, status, details);
+      return new DatastoreError(message, { code: "UNKNOWN", status, details });
+  }
+}

package/dist/index.d.ts

@@ -0,0 +1,116 @@
+// Hand-written ambient types for @colixsystems/datastore-client.
+// The package is plain ESM JavaScript; this file is shipped for IDE
+// IntelliSense. Keep in sync with src/index.js when adding exports.
+
+export interface TableMeta {
+  id: string;
+  name: string;
+  displayName?: string;
+  columns: Array<{
+    name: string;
+    type: string;
+    required?: boolean;
+  }>;
+}
+
+export interface Record_ {
+  id: string;
+  [key: string]: unknown;
+}
+export { Record_ as Record };
+
+export interface Page<T> {
+  data: T[];
+  nextCursor?: string | null;
+}
+
+export interface Query {
+  filter?: Record<string, unknown>;
+  sort?: Array<{ field: string; dir: "asc" | "desc" }>;
+  limit?: number;
+  cursor?: string;
+}
+
+export interface AggregateSpec {
+  groupBy?: string[];
+  metrics: Array<{
+    field?: string;
+    op: "count" | "sum" | "avg" | "min" | "max";
+    alias?: string;
+  }>;
+  filter?: Record<string, unknown>;
+}
+
+export interface AggregateResult {
+  rows: Array<Record<string, unknown>>;
+}
+
+export interface AppUser {
+  id: string;
+  email: string | null;
+  displayName: string | null;
+  roles: string[];
+  groupIds: string[];
+}
+
+export interface Group {
+  id: string;
+  name: string;
+}
+
+export interface RecordsNamespace {
+  list(query?: Query): Promise<Page<Record_>>;
+  get(id: string): Promise<Record_>;
+  create(values: Partial<Record_>): Promise<Record_>;
+  update(id: string, values: Partial<Record_>): Promise<Record_>;
+  delete(id: string): Promise<void>;
+  aggregate(spec: AggregateSpec): Promise<AggregateResult>;
+}
+
+export interface DatastoreClient {
+  tables: {
+    list(): Promise<TableMeta[]>;
+    get(idOrName: string): Promise<TableMeta>;
+  };
+  records(table: string): RecordsNamespace;
+  users: {
+    me(): Promise<AppUser>;
+    get(id: string): Promise<AppUser>;
+  };
+  groups: {
+    listMine(): Promise<Group[]>;
+  };
+}
+
+export interface CreateDatastoreClientOptions {
+  baseUrl: string;
+  getToken: () => string | Promise<string>;
+  getTenantId: () => string | Promise<string>;
+  fetchImpl?: typeof fetch;
+}
+
+export function createDatastoreClient(
+  opts: CreateDatastoreClientOptions
+): DatastoreClient;
+
+export class DatastoreError extends Error {
+  code: string;
+  status: number;
+  details: unknown;
+  constructor(
+    message: string,
+    init?: { code?: string; status?: number; details?: unknown }
+  );
+}
+export class NotFoundError extends DatastoreError {}
+export class ForbiddenError extends DatastoreError {}
+export class ValidationError extends DatastoreError {}
+export class RateLimitedError extends DatastoreError {}
+export class ServerError extends DatastoreError {}
+
+export function errorFromResponse(status: number, body: unknown): DatastoreError;
+
+export function withRetry<T>(
+  opts: { method: string; timeoutMs?: number },
+  attempt: (signal: AbortSignal) => Promise<T>
+): Promise<T>;

package/dist/index.js

@@ -0,0 +1,13 @@
+// Public entry for @colixsystems/datastore-client.
+
+export { createDatastoreClient } from "./client.js";
+export {
+  DatastoreError,
+  NotFoundError,
+  ForbiddenError,
+  ValidationError,
+  RateLimitedError,
+  ServerError,
+  errorFromResponse,
+} from "./errors.js";
+export { withRetry } from "./retry.js";

package/dist/retry.js

@@ -0,0 +1,55 @@
+// Small retry helper.
+// - Idempotent verbs (GET) retried up to 3x with exponential backoff: 200ms, 400ms, 800ms.
+// - Non-idempotent verbs (POST, PUT, PATCH, DELETE) are not retried.
+// - 10s default per-call timeout via AbortController.
+// - 429 with Retry-After honoured; 5xx retried; 4xx (other than 429) not retried.
+
+import { RateLimitedError, ServerError } from "./errors.js";
+
+const IDEMPOTENT = new Set(["GET", "HEAD"]);
+const DEFAULT_TIMEOUT_MS = 10_000;
+const BACKOFF_MS = [200, 400, 800];
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function isRetryable(err) {
+  if (err instanceof RateLimitedError) return true;
+  if (err instanceof ServerError) return true;
+  // AbortError or network failure
+  if (err && (err.name === "AbortError" || err.name === "TypeError")) return true;
+  return false;
+}
+
+/**
+ * Run `attempt` with retry semantics. `attempt` is invoked with an AbortSignal
+ * and is expected to return a Promise. It must reject with a DatastoreError
+ * subclass on transport / HTTP failures.
+ *
+ * @param {{ method: string, timeoutMs?: number }} opts
+ * @param {(signal: AbortSignal) => Promise<any>} attempt
+ */
+export async function withRetry(opts, attempt) {
+  const method = (opts.method || "GET").toUpperCase();
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const maxAttempts = IDEMPOTENT.has(method) ? BACKOFF_MS.length + 1 : 1;
+
+  let lastErr;
+  for (let i = 0; i < maxAttempts; i++) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      const result = await attempt(controller.signal);
+      clearTimeout(timer);
+      return result;
+    } catch (err) {
+      clearTimeout(timer);
+      lastErr = err;
+      if (i === maxAttempts - 1) break;
+      if (!isRetryable(err)) break;
+      await sleep(BACKOFF_MS[i] ?? BACKOFF_MS[BACKOFF_MS.length - 1]);
+    }
+  }
+  throw lastErr;
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@colixsystems/datastore-client",
+  "version": "0.1.0",
+  "description": "Typed, scoped client for the AppStudio datastore API. Used by widgets through the injected WidgetContext.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "node scripts/build.js",
+    "test": "node --test src"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/colixwestin/appstudio.git",
+    "directory": "packages/datastore-client"
+  },
+  "keywords": [
+    "appstudio",
+    "datastore",
+    "client"
+  ],
+  "license": "MIT"
+}