@colixsystems/datastore-client 0.4.0 → 0.6.0

package/dist/index.d.ts

@@ -1,27 +1,60 @@
 // 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.
+//
+// CONTRACT: snake_case in BOTH directions. Wire fields are snake_case
+// verbatim (`table_id`, `created_at`, `can_read`, …) and the client does NO
+// case transform. The only camelCase here is JS method names and the factory
+// option names. This is the DATA PLANE only — tables, records, aggregates,
+// and record-level permissions. Users / groups / files / payments live in
+// sibling packages.
+
+// A column on a virtual table (snake_case wire shape).
+export interface Column {
+  id: string;
+  table_id: string;
+  name: string;
+  data_type: string;
+  required?: boolean;
+  target_table_id?: string | null;
+  relation_type?: string | null;
+  is_identification_column?: boolean;
+  encrypted?: boolean;
+  inherit_acl?: boolean;
+  default_value?: unknown;
+  created_at?: string;
+  updated_at?: string;
+  [key: string]: unknown;
+}
 
-export interface TableMeta {
+// The full table schema returned by `tables.get(idOrName)` / `schema(t)`.
+export interface Table {
   id: string;
+  tenant_id?: string;
   name: string;
-  displayName?: string;
-  columns: Array<{
-    name: string;
-    type: string;
-    required?: boolean;
-  }>;
+  grant_creator_permissions?: boolean;
+  allow_anonymous_create?: boolean;
+  html_template?: string | null;
+  columns?: Column[];
+  created_at?: string;
+  updated_at?: string;
+  deleted_at?: string | null;
+  [key: string]: unknown;
 }
 
+// A free-form record. Keys correspond to the table's column `name`s; the
+// host-managed fields are snake_case (`id`, `created_at`, `updated_at`).
 export interface Record_ {
   id: string;
+  created_at?: string;
+  updated_at?: string;
   [key: string]: unknown;
 }
 export { Record_ as Record };
 
 // The uniform list envelope every collection endpoint returns
-// (`{ data, meta }`). `meta.total` is the ACL-aware row count; use it
-// with `limit`/`offset` to page.
+// (`{ data, meta }`), returned VERBATIM. `meta.total` is the ACL-aware row
+// count; use it with `limit` / `offset` to page.
 export interface Page<T> {
   data: T[];
   meta: {
@@ -34,93 +67,78 @@ export interface Page<T> {
 // Record-list query. A `filter` maps a column name to an `op:value`
 // expression — e.g. `{ status: "eq:Open", priority: "gte:3" }`. Supported
 // operators: eq, neq, lt, gt, gte, lte, contains, empty, nempty (and the
-// `me` sentinel for USER columns). `filterMode` ANDs conditions by
-// default, or ORs them. `q` is a free-text search across the table's
-// string/text columns. Pagination is `limit` + `offset`.
+// `me` sentinel for USER / USER_GROUP columns). `filterMode` ANDs conditions
+// by default, or ORs them (sent as `filter_mode`). `q` is a free-text search
+// across the table's string/text columns. `sort` is a column name optionally
+// prefixed with `-` for descending (e.g. `-created_at`). Pagination is
+// `limit` + `offset`.
 export interface Query {
-  filter?: Record<string, string>;
+  filter?: { [column: string]: string };
   filterMode?: "and" | "or";
   q?: string;
+  sort?: string;
   limit?: number;
   offset?: number;
 }
 
 // Aggregate request: group rows by a single column and (optionally) sum a
-// single numeric field, with the same `filter` map the list accepts.
+// single numeric field, with the same `filter` map the list accepts. Sent as
+// `group_by` / `sum_field` on the wire.
 export interface AggregateSpec {
   groupBy?: string;
   sumField?: string;
-  filter?: Record<string, string>;
+  filter?: { [column: string]: string };
 }
 
 // Aggregate response: one row per group with the row count and the sum of
-// `sumField` (0 when no `sumField` was requested).
+// `sum_field` (0 when no `sum_field` was requested).
 export type AggregateResult = Array<{
   group: string;
   count: number;
   sum: number;
 }>;
 
-// The principal returned by `users.me()` (`GET /auth/app/me`). `email` is
-// present for the logged-in user; the directory projection from
-// `users.get(id)` returns `{ id, name, role }` for non-Studio callers.
-export interface AppUser {
-  id: string;
-  name: string | null;
-  email?: string | null;
-  role?: string;
-  groupIds?: string[];
-}
-
-export interface Group {
+// A single row-level grant on a record (REQ-ACL-06), snake_case verbatim.
+// Exactly one of `user_id` / `group_id` is set; the four `can_*` flags are
+// the capability bits. `source_kind` / `source_id` are non-null only for
+// grants cascaded from a parent record through an inheriting relation —
+// directly-authored grants have both null.
+export interface RecordPermission {
   id: string;
-  name: string;
-  tenantId?: string;
-  createdAt?: string;
-  updatedAt?: string;
+  table_id: string;
+  record_id: string | null;
+  user_id: string | null;
+  group_id: string | null;
+  can_read: boolean;
+  can_write: boolean;
+  can_delete: boolean;
+  can_grant: boolean;
+  source_kind: string | null;
+  source_id: string | null;
+  created_at: string;
+  updated_at: string;
 }
 
-// A single row-level grant on a record (REQ-ACL-06). Exactly one of
-// `userId` / `groupId` is set; the four `can*` flags are the capability
-// bits. `sourceKind` / `sourceId` are non-null only for grants cascaded
-// from a parent record through an inheriting relation — directly-authored
-// grants have both null.
-export interface RecordPermission {
-  id: string;
-  tableId: string;
-  recordId: string | null;
-  userId: string | null;
-  groupId: string | null;
-  canRead: boolean;
-  canWrite: boolean;
-  canDelete: boolean;
-  canGrant: boolean;
-  sourceKind: string | null;
-  sourceId: string | null;
-  createdAt: string;
-  updatedAt: string;
-}
-
-// Grant body for `permissions(recordId).grant(...)`. Provide exactly ONE of
-// `userId` or `groupId`. Flags default server-side to `canRead: true` and
-// the rest `false` when omitted.
+// Grant body for `permissions(recordId).grant(...)`, sent snake_case
+// verbatim. Provide exactly ONE of `user_id` or `group_id`. Flags default
+// server-side to `can_read: true` and the rest `false` when omitted.
 export interface RecordPermissionGrant {
-  userId?: string | null;
-  groupId?: string | null;
-  canRead?: boolean;
-  canWrite?: boolean;
-  canDelete?: boolean;
-  canGrant?: boolean;
+  user_id?: string | null;
+  group_id?: string | null;
+  can_read?: boolean;
+  can_write?: boolean;
+  can_delete?: boolean;
+  can_grant?: boolean;
 }
 
-// Flag patch for `permissions(recordId).update(...)`. Only the four
-// capability bits are mutable; the grantee is fixed at grant time. Omitted
-// flags are left unchanged.
+// Flag patch for `permissions(recordId).update(...)`, sent snake_case
+// verbatim. Only the four capability bits are mutable; the grantee is fixed
+// at grant time. Omitted flags are left unchanged.
 export interface RecordPermissionPatch {
-  canRead?: boolean;
-  canWrite?: boolean;
-  canDelete?: boolean;
-  canGrant?: boolean;
+  can_read?: boolean;
+  can_write?: boolean;
+  can_delete?: boolean;
+  can_grant?: boolean;
 }
 
 export interface RecordPermissionsNamespace {
@@ -133,6 +151,29 @@ export interface RecordPermissionsNamespace {
   revoke(permissionId: string): Promise<void>;
 }
 
+// REQ-RT-07 realtime subscription transport state, reported via
+// `subscribe({ onStatus })`. "live" = socket open + subscribe acked;
+// "fallback" = the caller should poll (no WebSocket impl, subscribe rejected
+// by ACL, or the first connect timed out).
+export type SubscriptionStatus =
+  | "connecting"
+  | "live"
+  | "reconnecting"
+  | "fallback";
+
+export interface SubscriptionHandlers {
+  onCreated?: (record: Record_) => void;
+  onUpdated?: (record: Record_) => void;
+  onDeleted?: (record: Record_) => void;
+  onStatus?: (status: SubscriptionStatus) => void;
+}
+
+export interface SubscriptionOptions {
+  // Emit "fallback" if the first subscribe doesn't land within this many ms
+  // (default 3000) so the caller can start polling without waiting forever.
+  fallbackAfterMs?: number;
+}
+
 export interface RecordsNamespace {
   list(query?: Query): Promise<Page<Record_>>;
   get(id: string): Promise<Record_>;
@@ -141,28 +182,42 @@ export interface RecordsNamespace {
   delete(id: string): Promise<void>;
   aggregate(spec: AggregateSpec): Promise<AggregateResult>;
   permissions(recordId: string): RecordPermissionsNamespace;
+  // REQ-RT-07: subscribe to this table's realtime change stream. Returns a
+  // synchronous unsubscribe function.
+  subscribe(
+    handlers: SubscriptionHandlers,
+    options?: SubscriptionOptions,
+  ): () => void;
 }
 
 export interface DatastoreClient {
   tables: {
-    list(): Promise<TableMeta[]>;
-    get(idOrName: string): Promise<TableMeta>;
+    list(): Promise<Page<Table>>;
+    get(idOrName: string): Promise<Table>;
   };
+  // Alias of tables.get for the table's column structure (the host calls
+  // ctx.datastore.schema(t)).
+  schema(tableId: string): Promise<Table>;
   records(table: string): RecordsNamespace;
-  users: {
-    me(): Promise<AppUser>;
-    get(id: string): Promise<AppUser>;
-  };
-  groups: {
-    listMine(): Promise<Group[]>;
-  };
+}
+
+export interface RequestHeadersContext {
+  namespace: string;
+  operation: string;
 }
 
 export interface CreateDatastoreClientOptions {
   baseUrl: string;
   getToken: () => string | Promise<string>;
   getTenantId: () => string | Promise<string>;
+  getRequestHeaders?: (
+    ctx: RequestHeadersContext,
+  ) => Record<string, string> | Promise<Record<string, string>>;
   fetchImpl?: typeof fetch;
+  // REQ-RT-07: WebSocket constructor for records(t).subscribe(). Defaults to
+  // globalThis.WebSocket (browser + React Native). Omit in environments
+  // without one — subscribe() then reports "fallback".
+  webSocketImpl?: typeof WebSocket;
 }
 
 export function createDatastoreClient(

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@colixsystems/datastore-client",
-  "version": "0.4.0",
-  "description": "Typed, scoped client for the AppStudio datastore API. Used by widgets through the injected WidgetContext.",
+  "version": "0.6.0",
+  "description": "Typed, scoped data-plane client for the AppStudio datastore API (tables, records, aggregates, record-level permissions, realtime subscribe). snake_case wire contract, no transform.",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",