@rebasepro/server 0.23.0 → 0.24.1-canary.g19596ef

package/dist/api/errors.d.ts

@@ -23,6 +23,38 @@ export declare function schemaDriftRemedy(): {
     short: string;
     lines: string[];
 };
+/**
+ * Did the database refuse a value as unreadable for its column's type —
+ * SQLSTATE class 22, anywhere down the cause chain?
+ *
+ * For a lookup by an id the caller supplied, that is an answer rather than a
+ * failure: `abc` against a UUID key names no row, exactly as a well-formed id
+ * nobody has does.
+ */
+export declare function isDataException(error: unknown): boolean;
+/**
+ * Did the request fail because the database could not be reached at all — not
+ * because it refused the statement, and not because some other service is down?
+ *
+ * Read off the error the database driver raised, wherever it sits in the cause
+ * chain:
+ *
+ * - a SQLSTATE that means the connection was refused or dropped (class `08`,
+ *   `57P01`–`57P03`). The database's own word, so it settles the question
+ *   either way: a SQLSTATE of any other class is the database answering;
+ * - node-postgres's own sentence for a socket that closed under a query;
+ * - a socket failure (`ECONNREFUSED`, `ENOTFOUND`, …), but only where it can
+ *   only be the database's: thrown as it is, which is how node-postgres hands
+ *   back a pool connection it could not open, or as the cause of a failed
+ *   Drizzle query (the wrapper that carries the statement). Under any other
+ *   wrapper it belongs to another client: `fetch failed` is a `fetch()` to
+ *   some other host, and an S3 call that cannot connect carries the AWS SDK's
+ *   `$metadata`. Answering those "the database is unreachable" would send an
+ *   operator to a database that is fine.
+ */
+export declare function isDatabaseUnreachable(error: unknown): boolean;
+/** What a caller is told when the database cannot be reached. Retryable, and not about them. */
+export declare const DATABASE_UNAVAILABLE_MESSAGE: string;
 /**
  * Standardized API error class.
  * Throw this from any route handler — the errorHandler middleware
@@ -72,6 +104,15 @@ export declare class ApiError extends Error {
     static conflict(message: string, code?: string, details?: unknown): ApiError;
     static internal(message: string, code?: string): ApiError;
     static serviceUnavailable(message: string, code?: string): ApiError;
+    /**
+     * `503 DATABASE_UNAVAILABLE`: the database could not be reached. What
+     * every door answers then — the data API, sign-in, the admin routes and
+     * the realtime socket — so a client sees one retryable answer, sent with
+     * `Retry-After`, rather than a permission failure or a crash.
+     *
+     * @see isDatabaseUnreachable
+     */
+    static databaseUnavailable(message?: string): ApiError;
 }
 /**
  * Canonical error response shape:

package/dist/api/live-schema-routes.d.ts

@@ -29,7 +29,7 @@
  * — `applySchemaChange` re-checks rather than trusting the plan it is handed.
  */
 import { Hono } from "hono";
-import { type CollectionConfig, type DatabaseAdmin, type SchemaCommitPaths } from "@rebasepro/types";
+import { type AuthAdapter, type CollectionPatch, type CollectionConfig, type DatabaseAdmin, type SchemaCommitPaths } from "@rebasepro/types";
 import { HonoEnv } from "./types.js";
 import { type SchemaEditRepository } from "../schema-edit/apply-schema-change.js";
 import { type SchemaEditPolicy } from "../schema-edit/schema-edit-permissions.js";
@@ -87,8 +87,8 @@ export interface LiveSchemaRoutesConfig {
      *
      * Absent for a project that *is* the repository, which is what the defaults
      * describe. Present for one in a subdirectory, where the defaults would
-     * write `backend/` and `drizzle/` beside `.git` and leave the project's real
-     * generated files untouched — committing a source change alongside a stale
+     * write `backend/` beside `.git` and leave the project's real generated
+     * file untouched — committing a source change alongside a stale
      * schema, which is the failure committing the whole change exists to avoid.
      */
     commitPaths?: Partial<SchemaCommitPaths>;
@@ -97,8 +97,8 @@ export interface LiveSchemaRoutesConfig {
      * environment.
      *
      * If it does, applying here is not the whole job: the DDL runs against
-     * *this* database and `drizzle/schema.sql` is committed, but no migration
-     * is written — a server cannot mint one, since that needs Atlas and a
+     * *this* database and the collection is committed, but no migration is
+     * written — a server cannot mint one, since that needs Atlas and a
      * throwaway database. The next environment built by replaying migrations
      * would not have this change, and nothing would have said so.
      */
@@ -110,12 +110,52 @@ export interface LiveSchemaRoutesConfig {
      * commit, a commit needs an author, and a credential is not an author.
      */
     policy?: SchemaEditPolicy;
+    /**
+     * The account behind a uid, for the commit's author line.
+     *
+     * The request's user is what its access token carries, and the built-in
+     * token carries a uid and roles — no name, no address — so without this a
+     * commit is authored by the uid. Absent, or answering nothing, the commit
+     * falls back to what the request carries.
+     */
+    resolveAuthorIdentity?: (uid: string) => Promise<AccountIdentity | null>;
+}
+/** What a commit's author line is made of. */
+export interface AccountIdentity {
+    displayName?: string | null;
+    email?: string | null;
 }
-/** What the panel posts: one collection, in the shape it should end up. */
+/**
+ * The account behind a uid, read through the auth in use: its user-management
+ * lookup when it has one — a plain read — else `resolveUser`. `null` when the
+ * auth has neither, or knows no such account.
+ */
+export declare function readAccountIdentity(adapter: Pick<AuthAdapter, "userManagement" | "resolveUser"> | undefined, uid: string): Promise<AccountIdentity | null>;
+/**
+ * What the panel posts about one collection.
+ *
+ * For a collection that exists, a `patch`: what the person changed, as the
+ * difference between the JSON the editor loaded and the JSON it is saving (see
+ * `collection_patch.ts` in `@rebasepro/types`). The whole collection travelled
+ * here once, and the write rewrote every key it carried and deleted whatever
+ * JSON had dropped — handlers, shared properties, imported enums, comments.
+ *
+ * For a collection that does not exist yet, the whole `collection`. A caller
+ * that sends a whole collection for one that exists has it turned into the
+ * patch of what differs (see {@link asPatch}).
+ */
 export interface ProposedChange {
     collectionId: string;
-    /** The whole collection as it should be after the edit. */
-    collection: Record<string, unknown>;
+    /** The whole collection — only for one that does not exist yet. */
+    collection?: Record<string, unknown>;
+    /** What changed about an existing collection. */
+    patch?: CollectionPatch;
+    /**
+     * Delete the collection's source: its file, and its entry in `index.ts`.
+     * Planned like any change — the table and its rows stay, and say so — and
+     * committed source-only.
+     */
+    remove?: true;
 }
 /**
  * The git identity for the caller.
@@ -123,11 +163,25 @@ export interface ProposedChange {
  * `undefined` when the request carries no user — a service key, say — which
  * lets the repository fall back to its own git config rather than inventing a
  * name for somebody.
+ *
+ * The name and address the request carries win; what it lacks is read from
+ * the account through `resolveAccount`. A lookup that fails costs the commit
+ * its name, never the commit: the author falls back to the uid.
  */
-export declare function commitAuthor(user: unknown): {
+export declare function commitAuthor(user: unknown, resolveAccount?: (uid: string) => Promise<AccountIdentity | null>): Promise<{
     name: string;
     email: string;
-} | undefined;
+} | undefined>;
+/**
+ * The change as a patch against the collection as it is.
+ *
+ * A whole collection posted for one that exists is the difference from the
+ * current one: a caller that sends JSON cannot then delete what JSON could not
+ * carry. A key it left out is removed only when its value is pure data — a
+ * key holding code (`callbacks`, a handler, a component) is not something a
+ * JSON caller could have meant to drop.
+ */
+export declare function asPatch(existing: CollectionConfig, change: ProposedChange): CollectionPatch;
 /**
  * The proposed collection set: everything as it is, with one collection
  * replaced or added.

package/dist/api/logs-routes.d.ts

@@ -44,6 +44,15 @@ declare class LogRingBuffer {
     getLatest(count?: number): LogEntry[];
 }
 export declare const logBuffer: LogRingBuffer;
+/**
+ * Which process this log belongs to.
+ *
+ * The ring is this process's memory, and nothing gathers the rings of a
+ * deployment's other replicas or of its split runtime roles. So a reader is
+ * told whose log it is: `HOSTNAME` is the pod name on Kubernetes and the
+ * container id under Docker; the pid tells two local processes apart.
+ */
+export declare function logInstanceName(): string;
 /** Add a log entry */
 export declare function addLog(level: LogEntry["level"], source: LogEntry["source"], message: string, metadata?: Record<string, unknown>): void;
 export interface LogMiddlewareOptions {
@@ -55,7 +64,25 @@ export interface LogMiddlewareOptions {
      * server it is also the thing evicting real entries out of the ring.
      */
     ignorePaths?: string[];
+    /**
+     * Where the API is mounted (`/api`). The segment after it names the
+     * subsystem a request is filed under — see {@link sourceForRequestPath}.
+     * Unset, the first segment of the path is read.
+     */
+    basePath?: string;
 }
+/**
+ * The `source` of a request entry: the subsystem its path addresses.
+ *
+ * `/api/auth/*` and the MCP authorization server under `/api/oauth/*` are
+ * `auth`, `/api/storage/*` is `storage`, and everything else is `api`. The
+ * Logs Explorer's Source filter matches this field, so a sign-in filed as
+ * `api` was invisible under Auth. The realtime socket is not an HTTP request
+ * and is not recorded here.
+ *
+ * Exported for its test.
+ */
+export declare function sourceForRequestPath(path: string, basePath?: string): LogEntry["source"];
 /** Hono middleware to log API requests */
 export declare function logMiddleware(options?: LogMiddlewareOptions): MiddlewareHandler<HonoEnv>;
 /**
@@ -79,6 +106,17 @@ export interface LogStreamTiming {
     heartbeatMs?: number;
     maxPending?: number;
 }
-export declare function createLogsRoutes(timing?: LogStreamTiming): Hono<HonoEnv>;
+/** What ends the stream from the server's side. */
+export interface LogsRoutesOptions {
+    /**
+     * Aborted when the backend shuts down. Every open stream ends then, rather
+     * than when its client happens to leave: `server.close()` waits on every
+     * open connection, so one Studio → Logs tab held a SIGTERM for the whole
+     * force timeout — longer than Cloud Run's or `docker stop`'s grace period,
+     * which killed the process before the pool was closed.
+     */
+    closeSignal?: AbortSignal;
+}
+export declare function createLogsRoutes(timing?: LogStreamTiming, options?: LogsRoutesOptions): Hono<HonoEnv>;
 declare const _default: Hono<HonoEnv, import("hono/types").BlankSchema, "/">;
 export default _default;

package/dist/api/mount-path.d.ts

@@ -0,0 +1,30 @@
+import type { Context, MiddlewareHandler } from "hono";
+import type { HonoEnv } from "./types.js";
+/**
+ * Where a route group is mounted, read from the request rather than configured.
+ *
+ * A group — the data API, the functions router — is a Hono sub-app a caller can
+ * mount anywhere: `/api/data`, `/v2/data`, `/:tenant/data`. A few of its
+ * decisions need that prefix (which collection a path names, which function a
+ * scoped key is calling, what URL the listing reports), and it used to be passed
+ * in as `${basePath}/data` when the group was built — which pinned the group to
+ * the one path its builder assumed.
+ *
+ * Hono already knows: a middleware registered at the root of a group with
+ * `use("/*")` is stored under the merged path `<mount>/*`, however deeply the
+ * group was nested, and `routePath(c)` returns the path of the handler running
+ * now. Must therefore be called from such a middleware — see
+ * {@link recordMountPath}, which is how a group does it.
+ *
+ * A mount path with parameters (`/:tenant/data`) is resolved against the request
+ * segment by segment, so the answer is the concrete prefix (`/acme/data`).
+ */
+export declare function requestMountPath(c: Context): string;
+/**
+ * A group's first middleware: record where the group is mounted as
+ * `c.var.mountPath`, for everything after it in the same request.
+ *
+ * Registered with `use("/*")` on the group's own router, before anything else —
+ * that registration is what makes {@link requestMountPath} see the mount.
+ */
+export declare function recordMountPath(): MiddlewareHandler<HonoEnv>;

package/dist/api/mount.d.ts

@@ -23,19 +23,12 @@
  */
 import { Hono } from "hono";
 import type { HonoEnv } from "./types.js";
-export interface MountOptions {
-    /** Where the surface lives now. */
-    canonical: string;
-    /** Where it used to live, when it has moved. */
-    legacy?: string;
-    /** For the boot log — "Cron", "Logs". */
-    surface: string;
-}
 /**
- * Mount `router` at its canonical path, and at its legacy path when it has one.
+ * `router`, served again at a path it has moved from.
  *
- * The same router instance serves both, so the two paths cannot drift: there is
- * one set of handlers and one gate, and an alias that forgot to apply the admin
- * gate is not a state this can reach.
+ * Mount the result at the old path, beside `router` at its canonical one. The
+ * same router instance serves both, so the two paths cannot drift: there is one
+ * set of handlers and one gate, and an alias that forgot to apply the admin gate
+ * is not a state this can reach.
  */
-export declare function mountWithLegacyAlias(app: Hono<HonoEnv>, router: Hono<HonoEnv>, options: MountOptions): void;
+export declare function deprecatedAlias(router: Hono<HonoEnv>, canonical: string): Hono<HonoEnv>;

package/dist/api/openapi-generator.d.ts

@@ -28,3 +28,20 @@ export interface OpenApiGeneratorOptions {
     };
 }
 export declare function generateOpenApiSpec(collections: CollectionConfig[], options?: OpenApiGeneratorOptions): Record<string, unknown>;
+/**
+ * Build the component schema for a collection (output / read shape).
+ *
+ * Every declared property except the ones {@link isDocumentedProperty} rules
+ * out, plus the foreign keys and relations {@link emitRelationProperties} adds.
+ */
+export declare function buildCollectionSchema(collection: CollectionConfig, registeredSchemas: ReadonlySet<string>): Record<string, unknown>;
+/**
+ * Build an input schema (for POST/PUT) — excludes auto-generated fields.
+ *
+ * `excludeFromApi` columns are left out too, and the server now agrees: a write
+ * naming one is refused (`write-validation.ts`), which is what the flag's name
+ * and the generated SDK's own documentation always said. This comment used to
+ * record that such a write was "still accepted" — the document was right and
+ * the server was the thing that had not caught up.
+ */
+export declare function buildCollectionInputSchema(collection: CollectionConfig): Record<string, unknown>;

package/dist/api/rest/api-generator.d.ts

@@ -1,7 +1,32 @@
 import { Hono } from "hono";
 import { AuthAdapter, DataDriver, CollectionConfig } from "@rebasepro/types";
-import { HonoEnv } from "../types.js";
+import { QueryOptions, HonoEnv } from "../types.js";
 import { type ListLimitOptions } from "./query-parser.js";
+/**
+ * The row a single-row write addresses, as its route found it.
+ *
+ * `/comments/7` and `/posts/1/comments/7` address the same kind of row — a row
+ * of `comments` — two ways, and a write to it is one operation whichever way
+ * it arrived: the same body checks, the same `If-Match`, the same
+ * `Idempotency-Key`, the same answer. It was two pipelines, and the nested one
+ * re-listed two of the root's checks by hand and skipped the rest.
+ */
+export interface RowAddress {
+    /** The collection the row belongs to: what a body is checked against and an `ETag` computed for. */
+    collection: CollectionConfig;
+    /**
+     * The path the driver reads and writes at: the collection's own, or a
+     * nested one, which the driver resolves and scopes to its parent row.
+     */
+    path: string;
+    /**
+     * Handed to the driver beside `path`. Unset for a nested path, whose
+     * collection the driver resolves from the path itself.
+     */
+    driverCollection?: CollectionConfig;
+    /** What a 404 calls the address. */
+    name: string;
+}
 /**
  * Lightweight REST API generator that leverages existing Rebase DataDriver.
  * Supports `include` query parameter for eager-loading relations via Drizzle.
@@ -113,13 +138,16 @@ export declare class RestApiGenerator {
      */
     private createUnmatchedRoute;
     /**
-     * Check API key permissions for a collection operation.
-     * Throws 403 if the key doesn't have the required permission.
-     * No-ops if the request is not authenticated via an API key.
+     * Check a narrowed credential's data scope for a collection operation:
+     * `data:<operation>` on the collection, or unqualified.
+     *
+     * Throws 403 when it is missing. A person's own session holds the whole
+     * data plane — their rows are RLS's to decide — so this only ever refuses
+     * an API key or a token.
      */
     private enforceApiKeyPermission;
     /**
-     * API key permission check for nested paths.
+     * Data-scope check for nested paths.
      *
      * The operation lands on the collection the path addresses — the target
      * of its last relation — so that is the collection the key must hold the
@@ -237,7 +265,9 @@ export declare class RestApiGenerator {
      *
      * `respond` is applied to the *stored* result rather than the stored result
      * being a response, so a replay honours the `Prefer` header of the request
-     * replaying it rather than the one that first answered.
+     * replaying it rather than the one that first answered. `replayed` says
+     * the result is the stored one, so a route can restore what it put in a
+     * header rather than the body (the `PATCH`'s `ETag`).
      */
     private runIdempotent;
     /**
@@ -260,7 +290,7 @@ export declare class RestApiGenerator {
      *   and a tag compared against a read that hides it compares against
      *   nothing.
      */
-    private rowForETag;
+    static rowForETag(driver: DataDriver, address: RowAddress, id: string, alreadyRead: Record<string, unknown> | undefined, withDeleted?: QueryOptions["withDeleted"]): Promise<Record<string, unknown> | undefined>;
     /**
      * `GET /:id`, at a row's own address or through a parent: the row as the
      * query asked for it, and the `ETag` naming its version.
@@ -272,7 +302,10 @@ export declare class RestApiGenerator {
      * relation was a 412. A narrowed read therefore takes its tag from
      * {@link rowForETag}, the read the write routes make.
      */
-    private readRow;
+    static readRow(driver: DataDriver, address: RowAddress, id: string, queryOptions: QueryOptions): Promise<{
+        row: Record<string, unknown>;
+        etag: string | undefined;
+    } | undefined>;
     /**
      * Answer a bulk write, honouring `Prefer: return=minimal`.
      *
@@ -299,11 +332,61 @@ export declare class RestApiGenerator {
      * through a parent. Errors are not re-classified; see {@link createRow}.
      */
     private updateRow;
+    /**
+     * The 404 and the `If-Match` of an update or a delete, as a precondition
+     * the driver runs inside the write — or, for a driver that cannot, and for
+     * the auth collection, the same judgement made here on a read first.
+     *
+     * Inside the write is the point. The route used to read the row in a
+     * transaction of its own, through the admin's view-model walk, before
+     * writing it: every declared relation of the row was loaded — all 200,000
+     * comments of a post, for a PATCH of its title — and thrown away, and the
+     * write's own read of the row then repeated the lookup. And two writes
+     * carrying the same tag could both pass: each compared before either had
+     * written. Judged on the write's own read, after the row is locked when a
+     * tag is sent, the second one reads what the first wrote and is a 412.
+     *
+     * The auth collection is still read here first, without relations: the
+     * adapter's steps run before the write (`prepareUserUpdates`, and a
+     * deletion's `beforeUserDelete` veto, a hook of the application's), and an
+     * unknown uid must be the 404 before them, as it always was.
+     *
+     * @returns The precondition to hand the driver, or `undefined` for a driver
+     *   that does not run one (the row was judged here).
+     */
+    private storedRowPrecondition;
     /**
      * Delete one row: `DELETE /<collection>/<id>`, and the same row reached
      * through a parent.
      */
     private deleteRow;
+    /**
+     * A listing — `GET /<collection>` and `POST /<collection>/query`, and the
+     * same two through a parent — from the parameters as the `GET` reads them
+     * off its URL.
+     *
+     * One method for both verbs is the whole contract of the POST route: the
+     * same parser, the same field-access refusals, the same page, count,
+     * cursor and include, the same errors. The caller has already checked the
+     * credential's scope for `collection`.
+     *
+     * @param collectionPath a nested listing's `parent/:id/child` path; unset
+     *   for the collection's own.
+     */
+    private listRows;
+    /**
+     * A collection's count, from the query parameters in `queryDict`: the
+     * URL's for `GET …/count`, a body's for `POST …/count`. One method for
+     * both, as {@link listRows} is for the listing — the same parser, the same
+     * field-access refusals, the same count. The caller has already checked
+     * the credential's scope for `collection`.
+     *
+     * @param collectionPath a nested count's `parent/:id/child` path; unset
+     *   for the collection's own.
+     */
+    private countRows;
+    /** A `POST …/query` or `POST …/count` body, as the dictionary {@link listRows} and {@link countRows} read. See `query-body.ts`. */
+    private queryDictFromRequest;
     /**
      * Create REST routes for a collection using existing Rebase patterns
      */
@@ -344,13 +427,16 @@ export declare class RestApiGenerator {
      * @param collectionPath the path to read — a nested listing passes its own
      *   `parent/:id/child` path, which the driver resolves.
      */
-    private readPage;
+    static readPage(driver: DataDriver, collection: CollectionConfig, queryOptions: QueryOptions, searchString?: string, searchExplain?: boolean, collectionPath?: string): Promise<{
+        rows: Record<string, unknown>[];
+        meta: Record<string, unknown>;
+    }>;
     /**
      * Fetch raw collection data without Entity wrapper (fallback for non-Postgres)
      */
-    private fetchRawCollection;
+    static fetchRawCollection(driver: DataDriver, collection: CollectionConfig, queryOptions: QueryOptions, searchString?: string, searchExplain?: boolean, collectionPath?: string, startAfter?: Record<string, unknown>): Promise<Record<string, unknown>[]>;
     /**
      * Count raw entities for a collection
      */
-    private countRawEntities;
+    static countRawEntities(driver: DataDriver, collection: CollectionConfig, queryOptions: QueryOptions, searchString?: string, collectionPath?: string): Promise<number>;
 }

package/dist/api/rest/auth-collection-writes.d.ts

@@ -1,19 +1,3 @@
-/**
- * A write to the auth collection is user administration.
- *
- * The auth collection's rows are the users. `/admin/users` holds a change to
- * one to the auth adapter's rules: a create goes through the adapter's user
- * creation (the password hashed, the email normalized, the collection's
- * `onCreateUser`, the invitation), an update may not leave the project without
- * an administrator and stores an email the way sign-in looks it up, and a
- * deletion runs `beforeUserDelete` (a veto), ends the sessions and runs
- * `afterUserDelete`. The data doors that write the same rows — the REST routes
- * and MCP's write tools — call these, so that no door writes a user by rules
- * of its own. (The Postgres socket calls the adapter's methods directly.)
- *
- * Every function here leaves any other collection, and an adapter without the
- * step, exactly as it was: the rows are then written as any table's.
- */
 import type { AuthAdapter, CollectionConfig, UserCreationFinalizeResult, UserCreationPrepareResult } from "@rebasepro/types";
 import type { FieldViewer } from "@rebasepro/common";
 /** Whether `collection` is the auth collection — its rows are the users. */
@@ -26,6 +10,21 @@ export type UserCreatingAdapter = AuthAdapter & Required<Pick<AuthAdapter, "prep
  * the door writes the row as any other.
  */
 export declare function createsUsers(adapter: AuthAdapter | undefined, collection: CollectionConfig): adapter is UserCreatingAdapter;
+/**
+ * Refuse an upsert on the auth collection.
+ *
+ * An upsert is a create or an update, decided inside the write by whether the
+ * row is already there, and on the auth collection the two follow different
+ * rules: a create sets the password and sends the invitation
+ * ({@link createUserThroughAuthCollection}), an update may not demote the last
+ * administrator and normalizes the email ({@link prepareAuthCollectionUpdates}).
+ * Neither can be applied before the branch is known, so an upsert took
+ * neither — `{ id: <the last admin>, roles: ["viewer"] }` demoted them.
+ *
+ * Only where the adapter administers users; with no such step there is no
+ * rule for an upsert to miss. `where` prefixes the message (`Operation 3`).
+ */
+export declare function assertNoUserUpsert(adapter: AuthAdapter | undefined, collection: CollectionConfig, where?: string): void;
 /**
  * Check a create body for the auth collection against what the adapter says a
  * create consumes (`describeUserCreationContract`).
@@ -43,8 +42,16 @@ export declare function assertUserCreationBodyValid(adapter: AuthAdapter | undef
  * through the adapter's `prepareUserCreation` (the password hashed or
  * generated, the email normalized, the collection's `onCreateUser`), in order.
  * The `values` of each result are what the door writes.
+ *
+ * `caller` is who the door is writing for: an administrator may waive the
+ * password policy for an import (`skipPasswordPolicy: true`), anyone else may
+ * not.
+ *
+ * `nameRows` is set by a bulk door: a refusal of one body (a `WEAK_PASSWORD`,
+ * a hook's 4xx) is then prefixed `Row <index>: `, as the bulk's other row
+ * errors are, so an import can say which line of its file failed.
  */
-export declare function prepareUserCreations(adapter: UserCreatingAdapter, collection: CollectionConfig, bodies: readonly Record<string, unknown>[]): Promise<UserCreationPrepareResult[]>;
+export declare function prepareUserCreations(adapter: UserCreatingAdapter, collection: CollectionConfig, bodies: readonly Record<string, unknown>[], caller: FieldViewer, nameRows?: boolean): Promise<UserCreationPrepareResult[]>;
 /**
  * The second half, once the rows are written — and only then, so a write that
  * fails invites nobody: the credentials' delivery through
@@ -55,14 +62,14 @@ export declare function prepareUserCreations(adapter: UserCreatingAdapter, colle
  */
 export declare function completeUserCreations(adapter: UserCreatingAdapter, prepared: readonly UserCreationPrepareResult[], rows: readonly Record<string, unknown>[]): Promise<UserCreationFinalizeResult[]>;
 /**
- * Create one user through the auth collection: {@link prepareUserCreations},
- * then `save` (the door's own driver write), then
- * {@link completeUserCreations}.
+ * Create one user through the auth collection, for `caller`:
+ * {@link prepareUserCreations}, then `save` (the door's own driver write),
+ * then {@link completeUserCreations}.
  *
  * `undefined` when the create is not a user creation ({@link createsUsers}) —
  * the door then writes the row as any other.
  */
-export declare function createUserThroughAuthCollection(adapter: AuthAdapter | undefined, collection: CollectionConfig, body: Record<string, unknown>, save: (values: Record<string, unknown>) => Promise<Record<string, unknown>>): Promise<{
+export declare function createUserThroughAuthCollection(adapter: AuthAdapter | undefined, collection: CollectionConfig, body: Record<string, unknown>, caller: FieldViewer, save: (values: Record<string, unknown>) => Promise<Record<string, unknown>>): Promise<{
     row: Record<string, unknown>;
     delivery: UserCreationFinalizeResult;
 } | undefined>;

package/dist/api/rest/field-access-query.d.ts

@@ -1,5 +1,5 @@
 import type { CollectionConfig, IncludeSpec } from "@rebasepro/types";
-import type { LogicalCondition } from "@rebasepro/types";
+import { type LogicalCondition } from "@rebasepro/types";
 import { type FieldViewer } from "@rebasepro/common";
 /**
  * A read may not name a field the caller cannot read.
@@ -10,13 +10,22 @@ import { type FieldViewer } from "@rebasepro/common";
  * `?orderBy=salary` returns them in order of it. A column no response can carry
  * has to be a column no query can interrogate, or the read rule is decoration.
  *
- * The refusal names the field. That is deliberate and it is not a leak: the
- * published OpenAPI lists every property of every collection, including the ones
- * a given caller cannot read, because the document is one document and is served
- * off the app rather than off the authenticated data router. Hiding the name
- * here would protect nothing and would answer a caller's genuine typo with
- * "unknown field", sending them to look for a spelling mistake that is not
- * there. Field *names* are public; field *values* are not.
+ * The refusal names a field restricted by role. That is deliberate and it is
+ * not a leak: the published OpenAPI lists every property of every collection,
+ * including the ones a given caller cannot read, because the document is one
+ * document and is served off the app rather than off the authenticated data
+ * router. Hiding the name here would protect nothing and would answer a
+ * caller's genuine typo with "unknown field", sending them to look for a
+ * spelling mistake that is not there. Those field *names* are public; their
+ * *values* are not.
+ *
+ * An `excludeFromApi` field is the exception, because its name is *not*
+ * public: OpenAPI, `list_collections` and the generated SDK all leave it out.
+ * "`email` is not readable on `authors`" would confirm the one thing those hide,
+ * so a filter, sort, projection, include, aggregate or vector search naming one
+ * is answered as one naming a field that does not exist — built by the functions the driver answers a
+ * typo with (`@rebasepro/common`'s `unknown-field`), so the two answers are the
+ * same bytes. See {@link assertNoHiddenNames}.
  *
  * @module
  */
@@ -67,4 +76,15 @@ export declare function assertQueryFieldsReadable(options: {
         property: string;
     };
 }, collection: CollectionConfig, viewer: FieldViewer | undefined): void;
+/**
+ * The aggregate route's `select` and `groupBy`, which it parses itself: an
+ * `excludeFromApi` name there is answered exactly as the driver answers a
+ * column that does not exist. Walked in the driver's order — each aggregate's
+ * field, then each group key — and the first hidden *or* unknown name gets the
+ * answer, so a typo before a hidden name is still the one named.
+ */
+export declare function assertNoHiddenAggregateNames(aggregates: readonly {
+    fn: string;
+    field?: string;
+}[], groupBy: readonly string[], collection: CollectionConfig): void;
 export {};