@rebasepro/types 0.13.0 → 0.13.1-canary.g18cfeb7

package/dist/call_context.d.ts

@@ -1,3 +1,4 @@
+import type { DataDriver } from "./controllers/data_driver";
 import type { StorageSource } from "./controllers/storage";
 import type { RebaseClient } from "./controllers/client";
 import type { RebaseSdkData } from "./controllers/data";
@@ -19,7 +20,14 @@ export type RebaseCallContext<USER extends User = User> = {
      * The Rebase client instance.
      * Available in all entity callbacks (beforeSave, afterSave, afterRead,
      * beforeDelete, afterDelete) and in CollectionActionsProps via context.
-     * Use it to call backend functions, access data, storage, etc.
+     * Use it to call backend functions, access storage, send email, etc.
+     *
+     * ⚠️ **Not the same trust level as {@link data}.** Server-side this is the
+     * app singleton, so `client.dataAsAdmin` is **always** the RLS-bypassing
+     * plane — while {@link data}, one property over, follows whoever triggered
+     * the callback. On a user request, reaching for `context.client.dataAsAdmin`
+     * silently escalates a user-scoped operation to admin. For queries in a
+     * callback use {@link data}; come here for functions, storage and email.
      *
      * @example
      * // In a beforeSave callback:
@@ -35,11 +43,60 @@ export type RebaseCallContext<USER extends User = User> = {
      * Unified data access — `context.data.products.create(...)`.
      * Access any collection as a dynamic property.
      *
-     * Returns flat rows (`{ id, ...columns }`), identical to the frontend SDK
-     * client — so `context.data` in a backend callback and `client.data` in the
-     * frontend behave the same way (`row.title`, never `row.values.title`).
+     * **Inherits the privilege of whatever triggered the callback.** This is not
+     * a fixed trust level, and it is the one thing to know about this accessor:
+     *
+     * - Triggered by a **user request** (REST, realtime, an admin-panel edit):
+     *   user-scoped. The callback runs on the RLS-bound transaction opened for
+     *   that request, so policies apply to reads *and* writes — a callback
+     *   cannot see a row its caller could not.
+     * - Triggered by **server-context work** (`rebase.dataAsAdmin`, a cron):
+     *   unscoped, on the owner connection, bypassing RLS.
+     *
+     * So a callback that reads a sibling row will find it when an admin task
+     * saves and may find nothing when an end user saves — without an error,
+     * because RLS filters rather than raises. Write callbacks that tolerate
+     * that, or reach for {@link client}`.dataAsAdmin` deliberately when the
+     * callback genuinely has to see past its caller.
+     *
+     * Verified end-to-end against Postgres rather than asserted — see
+     * `"scopes context.data to the caller when a callback runs on a user
+     * request"` in `server-postgres`' `rls-enforcement` e2e suite. The
+     * documentation previously claimed the opposite (that callbacks always have
+     * full access), which is the unsafe direction to be wrong in.
+     *
+     * Returns flat rows (`{ id, ...columns }`), identical in *shape* to the
+     * frontend SDK client — so `context.data` in a backend callback and
+     * `client.data` in the frontend are accessed the same way (`row.title`,
+     * never `row.values.title`). Shape only: privilege differs as above.
      */
     data: RebaseSdkData;
+    /**
+     * The driver executing the operation this callback is attached to.
+     *
+     * Present server-side only. Declared here because it is already public in
+     * practice — the backend has always passed it, and the callbacks guide
+     * documented `context.driver.withAuth(user)` in all six locales. The
+     * contract simply did not name it, so `buildCallContext` was cast through
+     * `as unknown as RebaseCallContext` and nothing about the object was
+     * type-checked at all.
+     *
+     * The guide no longer recommends `withAuth` — {@link data} is already
+     * user-scoped on a user request, so the manual re-scoping it described was
+     * answering a problem that did not exist. The field stays declared rather
+     * than removed: it is on the runtime object, dropping it would break anyone
+     * who found it, and a named optional is better than a silent extra.
+     *
+     * `withAuth` is not on {@link DataDriver} because not every engine supports
+     * RLS scoping; it is narrowed here, and left optional so a driver without it
+     * is a compile-time absence rather than a runtime surprise.
+     */
+    driver?: DataDriver & {
+        withAuth?(user: {
+            uid: string;
+            roles?: string[];
+        }): Promise<DataDriver>;
+    };
     /**
      * Used storage implementation
      */

package/dist/controllers/client.d.ts

@@ -371,7 +371,22 @@ export interface RebaseClient<DB = unknown> {
     setOnUnauthorized?(handler: () => Promise<boolean>): void;
     /** Resolve the current auth token */
     resolveToken?(): Promise<string | null>;
-    /** Make a raw HTTP call to the backend */
+    /**
+     * POST to an arbitrary path on the backend — the escape hatch, not the way
+     * to call a function.
+     *
+     * For a custom function use {@link functions}`.invoke(name, payload)`: it
+     * targets `/functions/<name>`, takes a method and sub-path, and returns the
+     * response body as sent. This posts wherever you point it and **unwraps**:
+     * it returns `res.data` when the response has a `data` property and the
+     * whole envelope otherwise — so an endpoint that legitimately answers
+     * `{ data: null }` hands back the envelope rather than `null`. Two ways to
+     * reach a function with two different response contracts is a trap; this is
+     * the one that exists for paths `invoke` cannot express.
+     *
+     * @internal Prefer `functions.invoke()`. Kept public because a backend can
+     * mount routes outside `/functions`, and nothing else reaches those.
+     */
     call?<T = unknown>(endpoint: string, payload?: unknown): Promise<T>;
     /**
      * Execute raw SQL against the database.
@@ -419,64 +434,6 @@ export interface RebaseServerClient<DB = unknown> extends Omit<RebaseClient<DB>,
         params?: unknown[];
     }): Promise<Record<string, unknown>[]>;
 }
-/**
- * The browser-side Rebase surface — the shape produced by
- * `createRebaseClient()` in `@rebasepro/client`.
- *
- * Its {@link data} accessor is **user-scoped**: every call carries the signed-in
- * user's token, so backend RLS policies apply. It deliberately omits the
- * server-only members — there is no `sql`, no `email`, and no
- * `dataAsAdmin`, so the RLS-bypassing accessor can never be reached from
- * browser code.
- */
-export interface RebaseBrowserClient<DB = unknown> {
-    /** User-scoped data access layer (carries the signed-in user's token). */
-    data: RebaseSdkData<DB>;
-    /** Unified Authentication layer */
-    auth: AuthClient;
-    /** Unified Storage layer (default storage source, backward-compatible) */
-    storage?: StorageSource;
-    /** Registry of all named storage sources for multi-backend support */
-    storageRegistry?: StorageSourceRegistry;
-    /** Build a server-backed {@link StorageSource} for a named storage source. */
-    createStorageSource?(storageId: string): StorageSource;
-    /** Discover the storage sources declared on the backend. */
-    fetchStorageSources?(): Promise<StorageSourceDefinition[]>;
-    /** Admin API for user management */
-    admin?: AdminAPI;
-    /** Cron job management API */
-    cron?: CronAPI;
-    /** Database backup management API */
-    backups?: BackupsAPI;
-    /** Custom backend functions API */
-    functions?: FunctionsAPI;
-    /** Service API keys management API */
-    apiKeys?: ApiKeysAPI;
-    /** Base HTTP URL of the backend server */
-    baseUrl?: string;
-    /**
-     * The path every API route is mounted under, appended to {@link baseUrl}.
-     *
-     * `"/api"` unless the backend was configured with a different `basePath`
-     * and the client told to match. Exposed because code that builds a URL by
-     * hand — rather than going through the client's own methods — otherwise has
-     * to guess, and guessing `/api` is wrong for exactly the projects that set
-     * the option.
-     */
-    apiPath?: string;
-    /** WebSocket client for realtime subscriptions */
-    ws?: RebaseWebSocket;
-    /** Set the auth token for subsequent requests */
-    setToken?(token: string | null): void;
-    /** Set a function that lazily resolves the auth token */
-    setAuthTokenGetter?(getter: () => Promise<string | null>): void;
-    /** Set handler called when a request returns 401 */
-    setOnUnauthorized?(handler: () => Promise<boolean>): void;
-    /** Resolve the current auth token */
-    resolveToken?(): Promise<string | null>;
-    /** Make a raw HTTP call to the backend */
-    call?<T = unknown>(endpoint: string, payload?: unknown): Promise<T>;
-}
 /**
  * Client-side registry for managing multiple storage sources.
  *

package/dist/controllers/data.d.ts

@@ -34,13 +34,19 @@ export interface FilterCondition {
  *
  * `limit`/`offset` and `page` describe the same window two ways. If **both
  * `offset` and `page` are provided, `page` wins** — the backend computes
- * `offset = (page - 1) * (limit ?? 20)` and ignores the explicit `offset`.
- * Pick one style per query.
+ * `offset = (page - 1) * (limit ?? DEFAULT_LIST_LIMIT)` and ignores the
+ * explicit `offset`. Pick one style per query.
  *
  * @group Data
  */
 export interface FindParams<M extends Record<string, unknown> = Record<string, unknown>> {
-    /** Maximum number of items to return (default: 20). */
+    /**
+     * Maximum number of items to return.
+     *
+     * Defaults to {@link DEFAULT_LIST_LIMIT}, and is clamped to
+     * {@link MAX_LIST_LIMIT}. Both bounds are applied by the backend, so a
+     * read is never unbounded whether or not a limit was asked for.
+     */
     limit?: number;
     /**
      * Number of items to skip. Ignored when {@link FindParams.page} is also
@@ -49,7 +55,7 @@ export interface FindParams<M extends Record<string, unknown> = Record<string, u
     offset?: number;
     /**
      * Page number (1-indexed), alternative to {@link FindParams.offset}.
-     * When set, overrides `offset` as `(page - 1) * (limit ?? 20)`.
+     * When set, overrides `offset` as `(page - 1) * (limit ?? DEFAULT_LIST_LIMIT)`.
      */
     page?: number;
     /**
@@ -108,12 +114,12 @@ export interface FindResponse<M extends Record<string, unknown> = Record<string,
     };
 }
 /**
- * Fluent query builder for the **admin admin** — resolves to `FindResponse<M>`
+ * Fluent query builder for the **admin panel** — resolves to `FindResponse<M>`
  * (Snapshot-wrapped rows).
  *
  * @internal App developers should use {@link SDKQueryBuilderInterface}
  * (flat rows, returned by `client.data.*` / `context.data.*`). This
- * Snapshot-flavored variant backs the admin admin internals only.
+ * Snapshot-flavored variant backs the admin panel internals only.
  *
  * @group Data
  */
@@ -129,13 +135,13 @@ export interface QueryBuilderInterface<M extends Record<string, unknown> = Recor
     listen(onUpdate: (data: FindResponse<M>) => void, onError?: (error: Error) => void): () => void;
 }
 /**
- * A single collection's CRUD accessor for the **admin admin** — every method
+ * A single collection's CRUD accessor for the **admin panel** — every method
  * resolves to `Snapshot`-wrapped rows (`FindResponse<M>` / `Snapshot<M>`).
  *
  * @internal App developers do **not** use this. The public, symmetric surface
  * is {@link SDKCollectionClient} (flat rows), exposed as `client.data.products`
  * in the SDK and `context.data.products` in framework callbacks. This
- * Snapshot-flavored accessor backs the admin admin view-model only.
+ * Snapshot-flavored accessor backs the admin panel view-model only.
  *
  * @group Data
  */
@@ -169,6 +175,21 @@ export interface CollectionAccessor<M extends Record<string, unknown> = Record<s
      * @returns The updated entity
      */
     update(id: string | number, data: Partial<EntityValues<M>>): Promise<Entity<M>>;
+    /**
+     * Update many records in a single transaction.
+     *
+     * See {@link SDKCollectionClient.updateMany}. Optional, as `createMany` is.
+     */
+    updateMany?(updates: {
+        id: string | number;
+        data: Partial<EntityValues<M>>;
+    }[]): Promise<Entity<M>[]>;
+    /**
+     * Delete many records in a single transaction.
+     *
+     * See {@link SDKCollectionClient.deleteMany}. Optional, as `createMany` is.
+     */
+    deleteMany?(ids: (string | number)[]): Promise<void>;
     /**
      * Delete a record by ID.
      */
@@ -185,6 +206,12 @@ export interface CollectionAccessor<M extends Record<string, unknown> = Record<s
     listenById?(id: string | number, onUpdate: (entity: Entity<M> | undefined) => void, onError?: (error: Error) => void): () => void;
     /**
      * Count the number of records matching the given filter.
+     *
+     * Optional on this contract because a data source need not support it, and
+     * required on `CollectionClient` — the HTTP implementation always has it.
+     * So `client.data.posts.count()` compiles in the browser while the same
+     * call through a `context.data` accessor needs `count?.()`, which is the
+     * one place the two halves of this API are not interchangeable.
      */
     count?(params?: FindParams<M>): Promise<number>;
     where<K extends keyof M & string>(column: K, operator: WhereFilterOp, value: WhereValue<M[K]>): QueryBuilderInterface<M>;
@@ -461,6 +488,12 @@ export interface SDKCollectionClient<M extends Record<string, unknown> = Record<
      * Batches are capped server-side (1000 rows by default) because one batch
      * holds its locks for the whole transaction — chunk larger jobs.
      *
+     * Pass {@link WriteOptions.idempotencyKey} on anything that may be retried.
+     * A client that never sees the response cannot know whether the batch
+     * committed, and without a key the server cannot tell the retry from a
+     * second genuine import — so it performs it again, duplicating every row in
+     * the batch rather than just one.
+     *
      * @returns The written rows, in the order given.
      *
      * @example
@@ -472,7 +505,7 @@ export interface SDKCollectionClient<M extends Record<string, unknown> = Record<
      */
     createMany(data: I[], options?: {
         upsert?: boolean;
-    }): Promise<M[]>;
+    } & WriteOptions): Promise<M[]>;
     /**
      * Update an existing record by ID.
      * @param data The fields to update (the collection's `Update` shape).
@@ -480,18 +513,94 @@ export interface SDKCollectionClient<M extends Record<string, unknown> = Record<
      * @throws {RebaseApiError} with status 404 when the record does not exist.
      */
     update(id: string | number, data: U): Promise<M>;
+    /**
+     * Update many records in a single request and a single transaction.
+     *
+     * The counterpart to {@link createMany}, and the reason it exists is the
+     * same: one call per row means one HTTP round trip and one transaction per
+     * row. Every record still runs the normal pipeline — callbacks, relations,
+     * row-level security — and the batch is all-or-nothing, so a rejected
+     * record leaves none of them written and the error names the offending
+     * index.
+     *
+     * Each entry is `{ id, data }` rather than a flat row carrying its own key.
+     * That is deliberate: on a table keyed on something other than `id` — a
+     * `sku`, a composite key — a flat row cannot say whether a column is the
+     * address or a value to write. Naming the address separately mirrors
+     * single-row `update(id, data)` exactly and leaves nothing to infer.
+     *
+     * An id that matches no row fails the batch with a 404 rather than being
+     * skipped, for the same reason `update()` does: silently updating four of
+     * five rows is worse than updating none.
+     *
+     * Batches share `createMany`'s server-side cap (1000 rows by default),
+     * because one batch holds its locks for the whole transaction.
+     *
+     * Pass {@link WriteOptions.idempotencyKey} on anything that may be retried.
+     * An update replayed in full is naturally idempotent, but one interleaved
+     * with another writer's is not — the key is what stops a lost ACK from
+     * re-applying a stale batch over newer data.
+     *
+     * @returns The updated rows, in the order given.
+     *
+     * @example
+     * ```ts
+     * await client.data.orders.updateMany([
+     *     { id: "o-1", data: { status: "shipped" } },
+     *     { id: "o-2", data: { status: "shipped" } }
+     * ]);
+     * ```
+     */
+    updateMany(updates: {
+        id: string | number;
+        data: U;
+    }[], options?: WriteOptions): Promise<M[]>;
     /**
      * Delete a record by ID.
      * @throws {RebaseApiError} with status 404 when the record does not exist.
      */
     delete(id: string | number): Promise<void>;
     /**
-     * Subscribe to a collection for real-time updates.
+     * Delete many records in a single request and a single transaction.
+     *
+     * Takes ids, not a filter. A filter-shaped bulk delete is a different and
+     * far more dangerous operation — the failure mode is an omitted or
+     * mistyped condition emptying a table, and it cannot be reviewed at the
+     * call site the way an explicit list can. Read first, then pass the ids you
+     * meant.
+     *
+     * `beforeDelete` and `afterDelete` fire per row, exactly as they do for
+     * single deletes, and returning `false` from `beforeDelete` fails the batch
+     * rather than quietly dropping one row from it. All-or-nothing, so an id
+     * that matches no row 404s the whole call.
+     *
+     * Shares `createMany`'s row cap.
+     *
+     * @example
+     * ```ts
+     * const stale = await client.data.sessions.findAll({
+     *     where: { expires_at: ["<", cutoff] }
+     * });
+     * await client.data.sessions.deleteMany(stale.map(s => s.id as string));
+     * ```
      */
-    listen?(params: FindParams<M> | undefined, onUpdate: (response: FindResult<M>) => void, onError?: (error: Error) => void): () => void;
+    deleteMany(ids: (string | number)[], options?: WriteOptions): Promise<void>;
     /**
-     * Subscribe to a single record for real-time updates.
+     * The low-level realtime subscription: raw server pushes, nothing else.
+     *
+     * **Prefer `observe()`** on a client from `@rebasepro/client`, which wraps
+     * this one and is what a UI actually wants — it emits from the local
+     * database first when offline is enabled, re-emits on local writes and
+     * rollbacks, and de-duplicates emissions so a refresh that changes nothing
+     * does not call back. `listen` does none of that; it forwards what the
+     * socket sends.
+     *
+     * Optional because it is only present when realtime is enabled. `observe()`
+     * is not — it degrades to a single fetch — which is the other reason to
+     * reach for it instead.
      */
+    listen?(params: FindParams<M> | undefined, onUpdate: (response: FindResult<M>) => void, onError?: (error: Error) => void): () => void;
+    /** {@link listen} for a single row. Prefer `observeById()`. */
     listenById?(id: string | number, onUpdate: (row: M | undefined) => void, onError?: (error: Error) => void): () => void;
     /**
      * Count the number of records matching the given filter.
@@ -506,7 +615,7 @@ export interface SDKCollectionClient<M extends Record<string, unknown> = Record<
     include(...relations: string[]): SDKQueryBuilderInterface<M>;
 }
 /**
- * The unified data access object for the **admin admin** (Entity-shaped).
+ * The unified data access object for the **admin panel** (Entity-shaped).
  *
  * Access collections as dynamic properties: `data.products.find(...)`. Each
  * accessor returns `Entity`-wrapped records (`{ id, path, values }`) — the
@@ -515,7 +624,7 @@ export interface SDKCollectionClient<M extends Record<string, unknown> = Record<
  *
  * @internal App developers do **not** use this — they use
  * {@link RebaseSdkData} (flat rows), which is what the SDK client and backend
- * `context.data` expose. This Entity-shaped map backs the admin admin only.
+ * `context.data` expose. This Entity-shaped map backs the admin panel only.
  *
  * @group Data
  */
@@ -539,10 +648,15 @@ export type RebaseData<DB = unknown> = {
      * Dynamic collection accessor.
      * Access any collection by its slug as a property.
      *
+     * The index signature is `CollectionAccessor` alone, for the reason
+     * spelled out on {@link RebaseSdkData}: unioning in the `collection`
+     * method's own signature is unnecessary across an intersection, and it
+     * costs `data.products.find()` — the access this `@example` documents.
+     *
      * @example
      * data.products.find({ where: { status: ["==", "published"] } })
      */
-    [collectionSlug: string]: CollectionAccessor | ((slug: string) => CollectionAccessor);
+    [collectionSlug: string]: CollectionAccessor;
 });
 /**
  * The unified data access object for the **SDK** — flat rows, no Entity wrapper.
@@ -595,6 +709,26 @@ export type InsertOf<T> = T extends {
 export type UpdateOf<T> = T extends {
     Update: infer U extends Record<string, unknown>;
 } ? U : Partial<RowOf<T>>;
+/**
+ * Note on the untyped branch below: its index signature is
+ * `SDKCollectionClient`, NOT `SDKCollectionClient | ((slug: string) => …)`.
+ *
+ * The union looks like it is needed so `collection` — a method on this same
+ * object — satisfies the index signature. It is not, because `collection` is
+ * declared in a *separate* member of the intersection, and TypeScript only
+ * requires named properties to be assignable to an index signature declared
+ * alongside them. Including the function arm cost the documented accessor:
+ *
+ *     rebase.dataAsAdmin.projects.find()
+ *     //                          ^ Property 'find' does not exist on type
+ *     //                            'SDKCollectionClient | ((slug: string) => …)'
+ *
+ * Every project without a generated `Database` type lands on this branch, so
+ * property-style access — the form used by the `@example` below, by the
+ * scaffolded function template, and by the 0.13 migration note — did not
+ * compile for any of them. Do not restore the arm; use `collection(slug)` if a
+ * caller genuinely needs the by-slug function.
+ */
 export type RebaseSdkData<DB = unknown> = {
     /**
      * Get a flat collection accessor by slug.
@@ -614,5 +748,5 @@ export type RebaseSdkData<DB = unknown> = {
      * @example
      * data.products.find({ where: { status: ["==", "published"] } })
      */
-    [collectionSlug: string]: SDKCollectionClient | ((slug: string) => SDKCollectionClient);
+    [collectionSlug: string]: SDKCollectionClient;
 });

package/dist/controllers/data_driver.d.ts

@@ -128,6 +128,25 @@ export interface SaveManyProps<M extends Record<string, unknown> = Record<string
     /** Apply every row as INSERT ... ON CONFLICT DO UPDATE. See {@link SaveProps.upsert}. */
     upsert?: boolean;
 }
+/**
+ * @internal
+ */
+export interface UpdateManyProps<M extends Record<string, unknown> = Record<string, unknown>> {
+    path: string;
+    /**
+     * The rows to update, each named by its address.
+     *
+     * Distinct from {@link SaveManyProps.rows}, which carries keys *inside* the
+     * values and is insert-shaped — `saveMany` passes `status: "new"` and no
+     * `id`, so it cannot express "update exactly this row". This can, and it is
+     * why bulk update is a separate driver method rather than a flag on that one.
+     */
+    updates: {
+        id: string | number;
+        values: Partial<EntityValues<M>>;
+    }[];
+    collection?: CollectionConfig<M>;
+}
 /**
  * @internal
  */
@@ -139,6 +158,14 @@ export interface DeleteProps<M extends Record<string, unknown> = Record<string,
     };
     collection?: CollectionConfig<M>;
 }
+/**
+ * @internal
+ */
+export interface DeleteManyProps<M extends Record<string, unknown> = Record<string, unknown>> {
+    path: string;
+    ids: (string | number)[];
+    collection?: CollectionConfig<M>;
+}
 export type FilterCombinationValidProps = {
     path: string;
     databaseId?: string;
@@ -210,6 +237,16 @@ export interface DataDriver {
      * back to `save` per row.
      */
     saveMany?<M extends Record<string, unknown> = Record<string, unknown>>(props: SaveManyProps<M>): Promise<Record<string, unknown>[]>;
+    /**
+     * Update many rows in one transaction, each addressed by id.
+     *
+     * Optional for the same reason `saveMany` is: a driver that cannot make the
+     * batch atomic should not pretend to. The REST layer reports
+     * `BULK_UNSUPPORTED` rather than silently falling back to a loop of single
+     * writes, which would be neither atomic nor one round trip — the two things
+     * a caller reaches for a batch to get.
+     */
+    updateMany?<M extends Record<string, unknown> = Record<string, unknown>>(props: UpdateManyProps<M>): Promise<Record<string, unknown>[]>;
     /**
      * Delete a entity
      * @param props
@@ -221,6 +258,13 @@ export interface DataDriver {
      * @param path Collection path
      */
     deleteAll?(path: string): Promise<void>;
+    /**
+     * Delete many rows in one transaction, addressed by id.
+     *
+     * Ids rather than a filter, deliberately — see
+     * {@link SDKCollectionClient.deleteMany}. Optional, as `saveMany` is.
+     */
+    deleteMany?<M extends Record<string, unknown> = Record<string, unknown>>(props: DeleteManyProps<M>): Promise<void>;
     /**
      * Check if the given property is unique in the given collection
      * @param path Collection path

package/dist/errors.d.ts

@@ -1,3 +1,29 @@
+/**
+ * The error codes every route can produce, as `RebaseApiError.code`.
+ *
+ * These are the defaults on `ApiError`'s static constructors server-side, so
+ * any endpoint can answer with one. They are **not** the complete set: routes
+ * pass their own more specific codes too (`EMAIL_EXISTS`, `TOKEN_EXPIRED`,
+ * `INVALID_BULK_BODY`, …), and auth alone defines a couple of dozen.
+ *
+ * Hence the union is deliberately open rather than closed. It exists to give
+ * autocomplete and to catch a typo in the common cases — `code` was a bare
+ * `string`, so `e.code === "NOT_FOUND"` and `e.code === "NOTFOUND"` were
+ * equally valid and only one of them worked. Closing it would be a lie that
+ * broke the moment a route added a code.
+ *
+ * @example
+ * if (e instanceof RebaseApiError) {
+ *   switch (e.code) {
+ *     case "NOT_FOUND": return null;          // completed
+ *     case "FORBIDDEN": return redirect();
+ *     default: throw e;                       // routes' own codes land here
+ *   }
+ * }
+ *
+ * @group Errors
+ */
+export type RebaseErrorCode = "BAD_REQUEST" | "UNAUTHORIZED" | "FORBIDDEN" | "NOT_FOUND" | "CONFLICT" | "INTERNAL_ERROR" | "SERVICE_UNAVAILABLE" | "DB_PERMISSION_DENIED" | "SCHEMA_DRIFT" | (string & {});
 /**
  * Structured initializer for {@link RebaseApiError}.
  *
@@ -10,8 +36,8 @@ export interface RebaseErrorInit {
      * logic errors that have no HTTP status.
      */
     status?: number;
-    /** Stable, machine-readable error code (e.g. `"NOT_FOUND"`, `"BAD_REQUEST"`). */
-    code?: string;
+    /** Stable, machine-readable error code. See {@link RebaseErrorCode}. */
+    code?: RebaseErrorCode;
     /** Structured error payload returned by the server, when present. */
     details?: unknown;
     /** The underlying error this one wraps, if any. */
@@ -44,8 +70,8 @@ export interface RebaseErrorInit {
 export declare class RebaseApiError extends Error {
     /** HTTP status code, or `undefined` for non-HTTP errors. */
     readonly status?: number;
-    /** Stable machine-readable error code, when the server supplied one. */
-    readonly code?: string;
+    /** Stable machine-readable error code, when the server supplied one. See {@link RebaseErrorCode}. */
+    readonly code?: RebaseErrorCode;
     /** Structured error payload from the server, when present. */
     readonly details?: unknown;
     constructor(message: string, init?: RebaseErrorInit);