@marktiderman/genesis-core 1.2.0 → 1.4.0

package/dist/hooks/use-resource-form.d.ts

@@ -1,5 +1,6 @@
 import { UseFormReturn } from 'react-hook-form';
 import { ResourceFormFieldDef } from '../form-types.js';
+import { p as InvalidationKey } from '../types-zILrlHuV.js';
 
 interface UseResourceFormOptions {
     resource: string;
@@ -11,14 +12,31 @@ interface UseResourceFormOptions {
     listData?: Record<string, unknown>[];
     onSuccess?: (data: Record<string, unknown>) => void;
     onError?: (error: Error) => void;
-    /** Pre-fill create form defaults from URL query params. Default true. */
+    /**
+     * Pre-fill create form defaults from URL query params: a param named like a
+     * field (`?status=draft`) becomes that field's starting value. Default true.
+     * Pass false for a form that should not read the page's URL, e.g. one
+     * opened from a list whose own filters live in the query string.
+     */
     prefillFromUrl?: boolean;
+    /**
+     * Generate a placeholder ("Enter name", "name@example.com") for a field
+     * whose `placeholder` is unset. Default true. A placeholder that only
+     * repeats the label adds noise without information, so `ResourceForm`
+     * turns this off unless asked.
+     */
+    autoPlaceholder?: boolean;
     /** Validation trigger mode. Default "onBlur". */
     validationMode?: "onBlur" | "onChange" | "onSubmit";
     /** Enable autosave drafts to localStorage for create mode. */
     autosave?: boolean | {
         debounceMs?: number;
     };
+    /**
+     * Other query keys to invalidate after a save, on top of `[resource]` and
+     * the provider's own `invalidates`.
+     */
+    invalidates?: InvalidationKey[];
 }
 interface UseResourceFormReturn {
     form: UseFormReturn<Record<string, unknown>>;

package/dist/hooks/use-resource-form.js

@@ -1,7 +1,8 @@
-export { buildArrayItemDefaults, useResourceForm } from '../chunk-5FTUB2M6.js';
+export { buildArrayItemDefaults, useResourceForm } from '../chunk-IHWWJUEN.js';
 import '../chunk-RYEXWQFD.js';
-import '../chunk-3P4PHPMJ.js';
-import '../chunk-6V2TIN3G.js';
+import '../chunk-ZK5C3OOT.js';
+import '../chunk-7NUL32W7.js';
+import '../chunk-GGSXSI6Z.js';
 import '../chunk-ZYJUEJ4Z.js';
 //# sourceMappingURL=use-resource-form.js.map
 //# sourceMappingURL=use-resource-form.js.map

package/dist/hooks/use-resource.d.ts

@@ -1,5 +1,5 @@
 import { UseQueryResult, UseMutationResult } from '@tanstack/react-query';
-import { s as SortParam, i as FilterParam, m as ListResult, L as ListParams, I as Identifier, B as BaseRecord } from '../types-C7UVaF87.js';
+import { E as SortParam, k as FilterParam, p as InvalidationKey, q as ListResult, L as ListParams, I as Identifier, B as BaseRecord } from '../types-zILrlHuV.js';
 import '../form-types.js';
 
 interface UseResourceOptions<T> {
@@ -21,6 +21,19 @@ interface UseResourceOptions<T> {
     searchFields?: string[];
     /** Disable auto-fetching. */
     enabled?: boolean;
+    /**
+     * Other query keys to invalidate after a create, update or delete, on top
+     * of `[resource]` and the provider's own `invalidates` (e.g. `[["me"]]`
+     * when a write changes the signed-in user's roles).
+     */
+    invalidates?: InvalidationKey[];
+    /**
+     * While the next page / sort / search is loading, keep returning the
+     * previous result (`list.isPlaceholderData` is true meanwhile) instead of
+     * dropping to `undefined`. A paged list then stays on screen between pages
+     * rather than flashing a skeleton. Default false.
+     */
+    keepPreviousData?: boolean;
     onCreateSuccess?: (data: T) => void;
     onUpdateSuccess?: (data: T) => void;
     onDeleteSuccess?: () => void;

package/dist/hooks/use-resource.js

@@ -1,5 +1,6 @@
-export { useResource } from '../chunk-QFTMHOEH.js';
-import '../chunk-6V2TIN3G.js';
+export { useResource } from '../chunk-P4OIIRQS.js';
+import '../chunk-7NUL32W7.js';
+import '../chunk-GGSXSI6Z.js';
 import '../chunk-ZYJUEJ4Z.js';
 //# sourceMappingURL=use-resource.js.map
 //# sourceMappingURL=use-resource.js.map

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-export { A as ArrayFilter, a as AuditEntry, B as BaseRecord, C as CreateParams, b as CreateResult, D as DataProvider, c as DataRow, d as DeleteParams, e as DeleteResult, F as FieldPermissions, f as FieldReference, g as FieldSchema, h as FilterOperator, i as FilterParam, G as GetManyParams, j as GetManyResult, k as GetOneParams, l as GetOneResult, I as Identifier, L as ListParams, m as ListResult, N as NullFilter, P as PaginationParam, n as ProviderCapabilities, R as RangeFilter, o as ResourceAccess, p as ResourceContract, q as ResourceSchema, r as ResourceSummary, S as ScalarFilter, s as SortParam, t as StorageType, U as UpdateParams, u as UpdateResult, V as VersionField } from './types-C7UVaF87.js';
-export { D as DataWriteError, a as DataWriteErrorOptions, W as WriteOutcome, i as isDataWriteError } from './write-outcome-D8kjoQ1A.js';
-export { DataProviderRoot, DataProviderRootProps, GenesisProvider, GenesisProviderProps, MockProviderOptions, SupabaseClient, SupabaseClientInput, createMockProvider, createSupabaseProvider, useDataProvider, useStorage } from './provider/index.js';
+export { A as ArrayFilter, a as AuditEntry, B as BaseRecord, b as BulkChange, c as BulkResult, C as CreateParams, d as CreateResult, D as DataProvider, e as DataRow, f as DeleteParams, g as DeleteResult, F as FieldPermissions, h as FieldReference, i as FieldSchema, j as FilterOperator, k as FilterParam, G as GetManyParams, l as GetManyResult, m as GetOneParams, n as GetOneResult, H as HistoryParams, I as Identifier, o as ImportParams, p as InvalidationKey, L as ListParams, q as ListResult, N as NullFilter, P as PaginationParam, r as ProviderCapabilities, R as RangeFilter, s as RecordComment, t as ResourceAccess, u as ResourceContract, v as ResourceRelation, w as ResourceSchema, x as ResourceSummary, y as RowAction, z as RowFailure, S as ScalarFilter, E as SortParam, J as StorageType, U as UpdateParams, K as UpdateResult, V as VersionField, W as WriteEvent } from './types-zILrlHuV.js';
+export { D as DataWriteError, a as DataWriteErrorOptions, W as WriteOutcome, i as isDataWriteError } from './write-outcome-BE3Tk6bA.js';
+export { DataProviderRoot, DataProviderRootProps, GenesisProvider, GenesisProviderProps, MockProviderOptions, SupabaseClient, SupabaseClientInput, SupabaseProviderOptions, SupabaseResourceConfig, SupabaseWriteContext, createMockProvider, createSupabaseProvider, toDataWriteError, useDataProvider, useStorage, writeOutcomeFromCode } from './provider/index.js';
 export { S as StorageAdapter } from './types-DKcxHXxq.js';
 export { createLocalStorageAdapter, createMemoryStorageAdapter, createNoopStorageAdapter } from './storage/index.js';
 export { UseResourceOptions, UseResourceReturn, useResource } from './hooks/use-resource.js';

package/dist/index.js

@@ -1,15 +1,16 @@
-export { createSupabaseProvider } from './chunk-6AA4ISUA.js';
+export { createSupabaseProvider, toDataWriteError, writeOutcomeFromCode } from './chunk-NW26Z3LZ.js';
 export { decodeRecordKey, encodeRecordKey, keyFields } from './chunk-KV2HW4G4.js';
-export { DataWriteError, isDataWriteError } from './chunk-4W4W7F4I.js';
+export { DataWriteError, isDataWriteError } from './chunk-6MBACQYA.js';
 import './chunk-XCX2TRBL.js';
 import './chunk-65SXNHWE.js';
 import './chunk-EL7YGOTY.js';
-export { buildArrayItemDefaults, useResourceForm } from './chunk-5FTUB2M6.js';
+export { useWizard } from './chunk-7KOLYF27.js';
+export { buildArrayItemDefaults, useResourceForm } from './chunk-IHWWJUEN.js';
 export { titleCase } from './chunk-RYEXWQFD.js';
-export { useOne } from './chunk-3P4PHPMJ.js';
-export { useResource } from './chunk-QFTMHOEH.js';
-export { DataProviderRoot, GenesisProvider, createMockProvider, useDataProvider, useStorage } from './chunk-6V2TIN3G.js';
+export { useOne } from './chunk-ZK5C3OOT.js';
+export { useResource } from './chunk-P4OIIRQS.js';
+import './chunk-7NUL32W7.js';
+export { DataProviderRoot, GenesisProvider, createMockProvider, useDataProvider, useStorage } from './chunk-GGSXSI6Z.js';
 export { createLocalStorageAdapter, createMemoryStorageAdapter, createNoopStorageAdapter } from './chunk-ZYJUEJ4Z.js';
-export { useWizard } from './chunk-7KOLYF27.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/provider/index.d.ts

@@ -1,8 +1,10 @@
-import { D as DataProvider } from '../types-C7UVaF87.js';
-export { A as ArrayFilter, B as BaseRecord, C as CreateParams, b as CreateResult, d as DeleteParams, e as DeleteResult, i as FilterParam, G as GetManyParams, j as GetManyResult, k as GetOneParams, l as GetOneResult, I as Identifier, L as ListParams, m as ListResult, N as NullFilter, P as PaginationParam, R as RangeFilter, S as ScalarFilter, s as SortParam, U as UpdateParams, u as UpdateResult } from '../types-C7UVaF87.js';
-export { D as DataWriteError, a as DataWriteErrorOptions, W as WriteOutcome, i as isDataWriteError } from '../write-outcome-D8kjoQ1A.js';
+import { D as DataProvider, I as Identifier, B as BaseRecord, p as InvalidationKey, W as WriteEvent } from '../types-zILrlHuV.js';
+export { A as ArrayFilter, b as BulkChange, c as BulkResult, C as CreateParams, d as CreateResult, f as DeleteParams, g as DeleteResult, k as FilterParam, G as GetManyParams, l as GetManyResult, m as GetOneParams, n as GetOneResult, H as HistoryParams, o as ImportParams, L as ListParams, q as ListResult, N as NullFilter, P as PaginationParam, R as RangeFilter, z as RowFailure, S as ScalarFilter, E as SortParam, U as UpdateParams, K as UpdateResult } from '../types-zILrlHuV.js';
+import { D as DataWriteError, W as WriteOutcome } from '../write-outcome-BE3Tk6bA.js';
+export { a as DataWriteErrorOptions, i as isDataWriteError } from '../write-outcome-BE3Tk6bA.js';
 import * as react from 'react';
 import { ReactNode } from 'react';
+import { QueryClient } from '@tanstack/react-query';
 import { S as StorageAdapter } from '../types-DKcxHXxq.js';
 import '../form-types.js';
 
@@ -70,8 +72,124 @@ interface SupabaseClient {
 interface SupabaseClientInput {
     from(table: string): unknown;
 }
-declare function createSupabaseProvider(client: SupabaseClientInput): DataProvider;
+/** What a write hook is told about the write it is part of. */
+interface SupabaseWriteContext {
+    resource: string;
+    action: "create" | "update";
+    /** The row's id, for an update. */
+    id?: Identifier;
+}
+/** Per-resource rules for `createSupabaseProvider`. Every field is optional. */
+interface SupabaseResourceConfig {
+    /** Singular noun for failure messages, e.g. "project". Defaults to "record". */
+    noun?: string;
+    /**
+     * `"bin"` for a table whose delete trigger moves the row to a recycle bin
+     * instead of removing it (see `SupabaseProviderOptions.binTables`).
+     * `"hard"` forces a plain delete even when `binTables` lists the table.
+     */
+    deleteMode?: "hard" | "bin";
+    /**
+     * Turns submitted values into the row to write: trim, drop read-only keys,
+     * validate. Runs before every create and update, including the `create`
+     * and `update` overrides. Throw (ideally `DataWriteError("invalid", ...)`)
+     * to refuse the write; nothing is sent.
+     */
+    prepare?: (values: Record<string, unknown>, context: SupabaseWriteContext) => Record<string, unknown> | Promise<Record<string, unknown>>;
+    /**
+     * Creates the row some other way than an insert, e.g. a security-definer
+     * RPC. Return the new row, or its id and the provider reads the row back
+     * (if the read-back fails, the create is still reported as saved, with
+     * just the id, so the user does not retry and make a second one). Throw to
+     * fail; a Supabase `{ message, code }` error is mapped like any other.
+     */
+    create?: (row: Record<string, unknown>) => Promise<BaseRecord | Identifier>;
+    /**
+     * Updates the row some other way than an update, e.g. an RPC. Return the
+     * updated row, or its id (or `true`) and the provider reads it back.
+     * Returning nothing (`undefined`/`null`/`false`) means no row changed: the provider then reads the
+     * row to say why (`forbidden` or `gone`), exactly as for a plain update,
+     * so a function that silently skips a row never reports a save.
+     */
+    update?: (id: Identifier, row: Record<string, unknown>) => Promise<BaseRecord | Identifier | boolean | null | undefined | void>;
+    /** Maps a stored row to edit-form values; see `DataProvider.toFormValues`. */
+    toFormValues?: (record: Record<string, unknown>) => Record<string, unknown>;
+    /**
+     * Other cache keys a committed write to this resource makes stale, e.g.
+     * `[["staff"], ["me"]]`. Served through `DataProvider.invalidates`, which
+     * `useResource` and `useResourceForm` invalidate after their writes.
+     */
+    invalidates?: InvalidationKey[] | ((event: WriteEvent) => InvalidationKey[]);
+}
+/** Options for `createSupabaseProvider`. All optional; none changes reads. */
+interface SupabaseProviderOptions {
+    /**
+     * Recycle-bin tables: their delete trigger turns a delete into a "binned"
+     * mark and the binned row drops out of the caller's view (RLS or a view
+     * filter). The database reports such a delete as zero rows, so for these
+     * the provider checks the row is visible, deletes it, and reads it back:
+     * gone from view is success, still visible is `forbidden`. A row that was
+     * not visible beforehand is `gone`.
+     */
+    binTables?: readonly string[] | ((resource: string) => boolean);
+    /** Per-resource rules, keyed by resource (table) name. */
+    resources?: Record<string, SupabaseResourceConfig>;
+    /**
+     * Called after every committed create, update and delete, e.g. to
+     * invalidate caches the Genesis hooks don't know about. Awaited, but a
+     * failure is logged and never turns a committed write into a failed one.
+     */
+    onWrite?: (event: WriteEvent) => void | Promise<void>;
+}
+/**
+ * The Supabase data provider. Reads and writes go through the client you
+ * pass, under that client's session and RLS.
+ *
+ * Writes never report a save that did not happen:
+ * - `update` and `deleteOne` ask for the affected rows. Zero rows is a
+ *   `DataWriteError`: the row is read back, and still visible means
+ *   `forbidden` (RLS or a trigger refused the change), no longer visible
+ *   means `gone`.
+ * - Database errors on writes are thrown as `DataWriteError` with the
+ *   outcome their code means (`writeOutcomeFromCode`) and the code kept on
+ *   `error.code`.
+ * - Recycle-bin tables (`binTables`) succeed when the row leaves the
+ *   caller's view.
+ *
+ * Reads are unchanged: errors are thrown as an `Error` carrying `code`.
+ */
+declare function createSupabaseProvider(client: SupabaseClientInput, options?: SupabaseProviderOptions): DataProvider;
+
+/**
+ * Maps a Postgres SQLSTATE or PostgREST error code to the write outcome it
+ * means. Anything not listed is `error`: a code is only read as a refusal or
+ * a bad value when it says so.
+ *
+ * - `42501` (insufficient privilege, including "new row violates row-level
+ *   security policy") → `forbidden`
+ * - `22***` (data exception: bad type, out of range) and `23***` (integrity
+ *   constraint: `23505` unique, `23503` foreign key, `23502` not null,
+ *   `23514` check) → `invalid`
+ * - `PGRST301`–`PGRST303` (JWT missing, expired or rejected), `28000`,
+ *   `28P01` → `unauthenticated`
+ * - `PGRST116` (one row was asked for and none came back) → `gone`
+ */
+declare function writeOutcomeFromCode(code: string | null | undefined): WriteOutcome;
+/**
+ * Turns anything a write threw, or the `{ message, code }` error a Supabase
+ * client returned, into a `DataWriteError`. A `DataWriteError` passes through
+ * unchanged; anything else keeps its message and `code`, and is kept as the
+ * `cause`.
+ */
+declare function toDataWriteError(error: unknown): DataWriteError;
 
+/**
+ * Puts a `DataProvider` in context, and nothing else. Mount it inside your
+ * app's own `QueryClientProvider` and the Genesis hooks share that cache:
+ * the same query keys (`[resource, "list", params]`,
+ * `[resource, "detail", id, select]`), so invalidating `[resource]` from app
+ * code refreshes Genesis lists too, and vice versa.
+ */
 interface DataProviderRootProps {
     provider: DataProvider;
     children: ReactNode;
@@ -87,6 +205,14 @@ type GenesisProviderProps = {
     mock?: never;
     /** Platform-specific storage adapter. Defaults to localStorage (SSR-safe). */
     storage?: StorageAdapter;
+    /**
+     * The TanStack Query client to use. Without it, GenesisProvider creates
+     * its OWN client — a second cache beside any the app already has, so app
+     * queries and Genesis queries would not see each other's invalidations.
+     * An app with a `QueryClientProvider` should pass its client here, or
+     * use `DataProviderRoot` inside that provider instead.
+     */
+    queryClient?: QueryClient;
 } | {
     children: ReactNode;
     provider?: never;
@@ -97,7 +223,15 @@ type GenesisProviderProps = {
     };
     /** Platform-specific storage adapter. Defaults to localStorage (SSR-safe). */
     storage?: StorageAdapter;
+    /** See the `provider` variant. */
+    queryClient?: QueryClient;
 };
-declare function GenesisProvider({ children, provider, mock, storage, }: GenesisProviderProps): react.JSX.Element;
+/**
+ * Convenience root: a `QueryClientProvider`, storage, and a data provider
+ * (yours, or a mock built from datasets). It creates its own `QueryClient`
+ * unless you pass `queryClient`; an app that already has one should pass it,
+ * or mount `DataProviderRoot` inside its existing `QueryClientProvider`.
+ */
+declare function GenesisProvider({ children, provider, mock, storage, queryClient: queryClientProp, }: GenesisProviderProps): react.JSX.Element;
 
-export { DataProvider, DataProviderRoot, type DataProviderRootProps, GenesisProvider, type GenesisProviderProps, type MockProviderOptions, type SupabaseClient, type SupabaseClientInput, createMockProvider, createSupabaseProvider, useDataProvider, useStorage };
+export { BaseRecord, DataProvider, DataProviderRoot, type DataProviderRootProps, DataWriteError, GenesisProvider, type GenesisProviderProps, Identifier, InvalidationKey, type MockProviderOptions, type SupabaseClient, type SupabaseClientInput, type SupabaseProviderOptions, type SupabaseResourceConfig, type SupabaseWriteContext, WriteEvent, WriteOutcome, createMockProvider, createSupabaseProvider, toDataWriteError, useDataProvider, useStorage, writeOutcomeFromCode };

package/dist/provider/index.js

@@ -1,6 +1,6 @@
-export { createSupabaseProvider } from '../chunk-6AA4ISUA.js';
-export { DataWriteError, isDataWriteError } from '../chunk-4W4W7F4I.js';
-export { DataProviderRoot, GenesisProvider, createMockProvider, useDataProvider, useStorage } from '../chunk-6V2TIN3G.js';
+export { createSupabaseProvider, toDataWriteError, writeOutcomeFromCode } from '../chunk-NW26Z3LZ.js';
+export { DataWriteError, isDataWriteError } from '../chunk-6MBACQYA.js';
+export { DataProviderRoot, GenesisProvider, createMockProvider, useDataProvider, useStorage } from '../chunk-GGSXSI6Z.js';
 import '../chunk-ZYJUEJ4Z.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/schema/index.d.ts

@@ -1,6 +1,6 @@
-import { p as ResourceContract, I as Identifier, c as DataRow } from '../types-C7UVaF87.js';
-export { a as AuditEntry, F as FieldPermissions, f as FieldReference, g as FieldSchema, h as FilterOperator, n as ProviderCapabilities, o as ResourceAccess, q as ResourceSchema, r as ResourceSummary, t as StorageType, V as VersionField } from '../types-C7UVaF87.js';
-export { D as DataWriteError, a as DataWriteErrorOptions, W as WriteOutcome, i as isDataWriteError } from '../write-outcome-D8kjoQ1A.js';
+import { u as ResourceContract, I as Identifier, e as DataRow } from '../types-zILrlHuV.js';
+export { a as AuditEntry, F as FieldPermissions, h as FieldReference, i as FieldSchema, j as FilterOperator, r as ProviderCapabilities, s as RecordComment, t as ResourceAccess, v as ResourceRelation, w as ResourceSchema, x as ResourceSummary, y as RowAction, J as StorageType, V as VersionField } from '../types-zILrlHuV.js';
+export { D as DataWriteError, a as DataWriteErrorOptions, W as WriteOutcome, i as isDataWriteError } from '../write-outcome-BE3Tk6bA.js';
 export { FieldType as WidgetHint } from '../form-types.js';
 
 /** The key of a contract as a list, whichever form `key` was declared in. */

package/dist/schema/index.js

@@ -1,4 +1,4 @@
 export { decodeRecordKey, encodeRecordKey, keyFields } from '../chunk-KV2HW4G4.js';
-export { DataWriteError, isDataWriteError } from '../chunk-4W4W7F4I.js';
+export { DataWriteError, isDataWriteError } from '../chunk-6MBACQYA.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/{types-C7UVaF87.d.ts → types-zILrlHuV.d.ts}

@@ -47,6 +47,8 @@ interface FieldSchema {
     readonly array?: boolean;
     /** Human note (surfaces in describe()/drift reports). */
     readonly description?: string;
+    /** Human label, e.g. "Date of birth". Absent means a UI derives one from `name`. */
+    readonly label?: string;
     /** The store's exact type, e.g. `timestamp with time zone` or `public.status`. */
     readonly dbType?: string;
     /** Which control fits this field. A hint: a UI may still choose another. */
@@ -68,7 +70,7 @@ interface FieldSchema {
  * One declaration of a resource: its fields and its identity.
  *
  * `key` names the identity field, or several for a composite key (a junction
- * table keyed on `(coach_id, client_id)`). Use {@link keyFields} to read it as
+ * table keyed on `(team_id, user_id)`). Use {@link keyFields} to read it as
  * a list without caring which form it took.
  */
 interface ResourceContract<Row extends DataRow = DataRow> {
@@ -97,6 +99,46 @@ interface ResourceAccess {
     readonly update: boolean;
     /** Why `update` (or `read`) is false, in one human sentence. */
     readonly reason?: string;
+    /** True when this user may add rows. Absent means the provider doesn't say. */
+    readonly create?: boolean;
+    /** True when this user may delete rows they can see. */
+    readonly delete?: boolean;
+    /** True when this user may read a row's audit history. */
+    readonly history?: boolean;
+    /** True when this user may read and add comments on rows they can see. */
+    readonly comment?: boolean;
+    /** Why `create`, `delete`, `history` or `comment` is false, in one human sentence each. */
+    readonly reasons?: {
+        readonly create?: string;
+        readonly delete?: string;
+        readonly history?: string;
+        readonly comment?: string;
+    };
+}
+/**
+ * How another resource relates to this one, from the store's foreign keys.
+ *
+ * - `one`: a field on THIS resource points at one row of `resource`.
+ * - `many`: rows of `resource` point at this row through their `field`.
+ * - `through`: many rows of `resource`, linked by the junction resource in
+ *   `through` (a table whose key is two foreign keys).
+ */
+interface ResourceRelation {
+    readonly kind: "one" | "many" | "through";
+    /** The related resource. */
+    readonly resource: string;
+    /**
+     * `one`: the field on this resource. `many`: the field on `resource` that
+     * holds this row's key. `through`: the junction's field holding this row's key.
+     */
+    readonly field: string;
+    /** For `through`: the junction resource, and its field pointing at `resource`. */
+    readonly through?: {
+        readonly resource: string;
+        readonly otherField: string;
+    };
+    /** True when at most one related row can exist (a unique foreign key). */
+    readonly unique?: boolean;
 }
 /**
  * The column a provider checks on every update so an edit never silently
@@ -111,7 +153,12 @@ interface VersionField {
      * `expectedVersion` echoes `String(row[field])` back unchanged.
      */
     readonly field: string;
-    readonly kind: "integer" | "timestamp";
+    /**
+     * `row`: no column tracks versions, so the token is a fingerprint of the
+     * row's values, and `field` is a name the provider adds to each record
+     * (it is not one of the resource's fields).
+     */
+    readonly kind: "integer" | "timestamp" | "row";
 }
 /**
  * A resource as `describe()` reports it for the CURRENT user: the contract,
@@ -124,6 +171,32 @@ interface ResourceSchema<Row extends DataRow = DataRow> extends ResourceContract
     readonly access: ResourceAccess;
     /** Present only when writes can be version-checked. */
     readonly version?: VersionField;
+    /** The field that best names a row to a person (a name or title), for links and pickers. */
+    readonly labelField?: string;
+    /** Resources this one links to or is linked from. Only ones this user may see. */
+    readonly relations?: readonly ResourceRelation[];
+    /** Fields the user may set when creating a row. Absent when creating isn't allowed. */
+    readonly createFields?: readonly string[];
+    /** Row actions this user may run: each calls the app's own function on one row. */
+    readonly actions?: readonly RowAction[];
+}
+/** A named operation on one row, carried out by the app's own database function. */
+interface RowAction {
+    readonly name: string;
+    readonly label: string;
+    /** Ask before running, with this question. */
+    readonly confirm?: string;
+    /** One sentence on what it does. */
+    readonly description?: string;
+}
+/** A comment on a record. */
+interface RecordComment {
+    readonly id: string;
+    /** The signed-in user who wrote it (the token's `sub`). */
+    readonly author: string;
+    readonly body: string;
+    /** ISO 8601, as the store recorded it. */
+    readonly createdAt: string;
 }
 /** One entry of `listResources()`: enough to draw a sidebar. */
 interface ResourceSummary {
@@ -151,6 +224,21 @@ interface ProviderCapabilities {
     readonly versionedWrites: boolean;
     /** Records may be keyed by more than one field. */
     readonly compositeKeys: boolean;
+    /** Server-side sort by several fields at once (`ListParams.sorts`). */
+    readonly multiSort?: boolean;
+    /** `create` and `deleteOne` are served, subject to each resource's access. */
+    readonly create?: boolean;
+    readonly delete?: boolean;
+    /** `history` is served, subject to each resource's access. */
+    readonly history?: boolean;
+    /** `importRows` is served, with a dry run. */
+    readonly import?: boolean;
+    /** `undo` is served. */
+    readonly undo?: boolean;
+    /** `runAction` is served. */
+    readonly actions?: boolean;
+    /** `comments` and `addComment` are served. */
+    readonly comments?: boolean;
 }
 /** One audit record, as committed alongside the edit it describes. */
 interface AuditEntry {
@@ -162,7 +250,10 @@ interface AuditEntry {
     readonly resource: string;
     /** The record's key, field name → value. */
     readonly key: DataRow;
-    readonly action: "create" | "update" | "delete";
+    /** `run` is a row action; `rowAction` names it. */
+    readonly action: "create" | "update" | "delete" | "run";
+    /** For `run`: which row action. */
+    readonly rowAction?: string;
     /** Values of the changed fields before the edit. */
     readonly before: DataRow | null;
     /** Values of the changed fields after the edit. */
@@ -219,6 +310,11 @@ type FilterParam = ScalarFilter | ArrayFilter | RangeFilter | NullFilter;
 interface ListParams {
     pagination?: PaginationParam;
     sort?: SortParam;
+    /**
+     * Sort by several fields, first one first. Wins over `sort` on a provider
+     * whose capabilities report `multiSort`; others use only `sort`.
+     */
+    sorts?: SortParam[];
     filters?: FilterParam[];
     /** Supabase select syntax, e.g. "*, author:profiles(name)". Mock provider ignores this. */
     select?: string;
@@ -258,6 +354,8 @@ interface CreateParams<T> {
 /** Result of `create`. */
 interface CreateResult<T> {
     data: T;
+    /** The audit entry committed with the new row, from a provider that audits. */
+    audit?: AuditEntry;
 }
 /** Parameters for `update`. */
 interface UpdateParams<T> {
@@ -287,13 +385,67 @@ interface UpdateResult<T> {
 /** Parameters for `deleteOne`. */
 interface DeleteParams {
     id: Identifier;
+    /** The version token the row was read at; see `UpdateParams.expectedVersion`. */
+    expectedVersion?: string | null;
 }
 /** Result of `deleteOne`. */
 interface DeleteResult {
     data: {
         id: Identifier;
     };
+    /** The audit entry committed with the deletion, from a provider that audits. */
+    audit?: AuditEntry;
+}
+/** One row's change in a bulk update. */
+interface BulkChange {
+    id: Identifier;
+    data: Record<string, unknown>;
+    /** The version token the row was read at. */
+    expectedVersion?: string | null;
 }
+/** Why one row of a bulk write or import didn't go through. */
+interface RowFailure {
+    /** The row's position in the request, from 0. */
+    index: number;
+    id?: Identifier;
+    outcome: string;
+    message: string;
+}
+/** Result of a bulk write: every row changed, or none did. */
+interface BulkResult {
+    /** Rows changed; always the number requested when `ok`. */
+    count: number;
+    ok: boolean;
+    /** Present when `ok` is false: every row that failed, so the caller can fix them all at once. */
+    failures?: RowFailure[];
+    /** One audit entry per row changed. */
+    audit?: AuditEntry[];
+}
+/** Parameters for `importRows`. */
+interface ImportParams {
+    rows: Record<string, unknown>[];
+    /** Check every row against the database and change nothing. */
+    dryRun: boolean;
+}
+/** Parameters for `history`. */
+interface HistoryParams {
+    id: Identifier;
+    /** Most recent first; default and maximum are the provider's. */
+    limit?: number;
+}
+/** A write that committed, as passed to a provider's `onWrite` and `invalidates`. */
+interface WriteEvent {
+    resource: string;
+    kind: "create" | "update" | "delete";
+    id: Identifier;
+    /** The row as written, when the provider has it (not for a delete). */
+    record?: BaseRecord;
+}
+/**
+ * A cache key to invalidate after a write. Shaped like a TanStack Query
+ * `QueryKey` (`readonly unknown[]`), matched by prefix.
+ */
+type InvalidationKey = readonly unknown[];
 interface DataProvider {
     getList<T extends BaseRecord = BaseRecord>(resource: string, params: ListParams): Promise<ListResult<T>>;
     getOne<T extends BaseRecord = BaseRecord>(resource: string, params: GetOneParams): Promise<GetOneResult<T>>;
@@ -314,6 +466,76 @@ interface DataProvider {
      * controls a provider cannot serve instead of letting them error.
      */
     capabilities?(resource?: string): Promise<ProviderCapabilities>;
+    /**
+     * A record's audit history, most recent first, limited to the fields this
+     * user may read.
+     */
+    history?(resource: string, params: HistoryParams): Promise<AuditEntry[]>;
+    /**
+     * Update many rows in ONE transaction. All of them change or none do: a
+     * single conflict, refusal or invalid value rolls back the rest, and the
+     * result lists every row that failed.
+     */
+    updateMany?(resource: string, params: {
+        changes: BulkChange[];
+    }): Promise<BulkResult>;
+    /** Delete many rows in one transaction, all or none, each at its version. */
+    deleteMany?(resource: string, params: {
+        items: {
+            id: Identifier;
+            expectedVersion?: string | null;
+        }[];
+    }): Promise<BulkResult>;
+    /**
+     * Add rows from an import. With `dryRun`, every row is tried against the
+     * database and nothing is kept, so the result lists every row that would
+     * fail; without it, all rows are added in one transaction or none are.
+     */
+    importRows?(resource: string, params: ImportParams): Promise<BulkResult>;
+    /**
+     * Undo one audited change with a compensating write: put the changed
+     * fields back, remove an added row, or restore a deleted one. Refused when
+     * the row has changed since.
+     */
+    undo?(resource: string, params: {
+        auditId: string;
+    }): Promise<{
+        audit?: AuditEntry;
+    }>;
+    /**
+     * Run one of the resource's row actions (`ResourceSchema.actions`) on a
+     * row, at the version it was read. The app's function does the work; the
+     * row's change is audited.
+     */
+    runAction?(resource: string, params: {
+        id: Identifier;
+        action: string;
+        expectedVersion?: string | null;
+    }): Promise<{
+        data: Record<string, unknown> | null;
+        audit?: AuditEntry;
+    }>;
+    /** A record's comments, oldest first. */
+    comments?(resource: string, params: {
+        id: Identifier;
+    }): Promise<RecordComment[]>;
+    /** Add a comment to a record, as the signed-in user. */
+    addComment?(resource: string, params: {
+        id: Identifier;
+        body: string;
+    }): Promise<RecordComment>;
+    /**
+     * Maps a stored row to the values an edit form starts from, for a resource
+     * whose form shape differs from its table (the reverse of a write's
+     * `prepare`). `useResourceForm` applies it in edit mode.
+     */
+    toFormValues?(resource: string, record: Record<string, unknown>): Record<string, unknown>;
+    /**
+     * Other cache keys a committed write makes stale, beyond the resource's
+     * own `[resource]` keys. `useResource` and `useResourceForm` invalidate
+     * them after their writes.
+     */
+    invalidates?(event: WriteEvent): InvalidationKey[];
 }
 
-export type { ArrayFilter as A, BaseRecord as B, CreateParams as C, DataProvider as D, FieldPermissions as F, GetManyParams as G, Identifier as I, ListParams as L, NullFilter as N, PaginationParam as P, RangeFilter as R, ScalarFilter as S, UpdateParams as U, VersionField as V, AuditEntry as a, CreateResult as b, DataRow as c, DeleteParams as d, DeleteResult as e, FieldReference as f, FieldSchema as g, FilterOperator as h, FilterParam as i, GetManyResult as j, GetOneParams as k, GetOneResult as l, ListResult as m, ProviderCapabilities as n, ResourceAccess as o, ResourceContract as p, ResourceSchema as q, ResourceSummary as r, SortParam as s, StorageType as t, UpdateResult as u };
+export type { ArrayFilter as A, BaseRecord as B, CreateParams as C, DataProvider as D, SortParam as E, FieldPermissions as F, GetManyParams as G, HistoryParams as H, Identifier as I, StorageType as J, UpdateResult as K, ListParams as L, NullFilter as N, PaginationParam as P, RangeFilter as R, ScalarFilter as S, UpdateParams as U, VersionField as V, WriteEvent as W, AuditEntry as a, BulkChange as b, BulkResult as c, CreateResult as d, DataRow as e, DeleteParams as f, DeleteResult as g, FieldReference as h, FieldSchema as i, FilterOperator as j, FilterParam as k, GetManyResult as l, GetOneParams as m, GetOneResult as n, ImportParams as o, InvalidationKey as p, ListResult as q, ProviderCapabilities as r, RecordComment as s, ResourceAccess as t, ResourceContract as u, ResourceRelation as v, ResourceSchema as w, ResourceSummary as x, RowAction as y, RowFailure as z };