@rebasepro/server 0.24.0 → 0.24.1-canary.gcb918fc

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

@@ -265,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;
     /**
@@ -330,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
      */

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 {};

package/dist/api/rest/field-ops.d.ts

@@ -1,4 +1,4 @@
-import { CollectionConfig, FieldOperation, FIELD_OPERATORS, isFieldOperation } from "@rebasepro/types";
+import { CollectionConfig, FieldOperation, FIELD_OPERATORS, isFieldOperation, Properties, Property } from "@rebasepro/types";
 /**
  * Writes expressed as a change to the column's current value.
  *
@@ -38,23 +38,32 @@ export interface ParsedFieldOp {
  * this package.
  */
 export declare const looksLikeFieldOp: typeof isFieldOperation;
-/** True when any value in the payload is (or is attempting to be) an operation. */
-export declare function hasFieldOps(values: Record<string, unknown> | undefined): boolean;
+/**
+ * True when any value in the payload is (or is attempting to be) an operation.
+ * With `properties`, a `map` value is one only when it is `{ <operator>: … }`;
+ * see `isFieldOperation`.
+ */
+export declare function hasFieldOps(values: Record<string, unknown> | undefined, properties?: Properties): boolean;
 /**
  * Parse one value as an operation, or report why it is not a legal one.
  *
  * Returns `undefined` for an ordinary value. Throws for a value that reads as
- * an operation and is malformed, so a typo cannot be written as data.
+ * an operation and is malformed, so a typo cannot be written as data. Given
+ * the field's `property`, a `map` value with `$` keys is data unless it is a
+ * single real operator.
  */
-export declare function parseFieldOp(key: string, value: unknown): ParsedFieldOp | undefined;
+export declare function parseFieldOp(key: string, value: unknown, property?: Property): ParsedFieldOp | undefined;
 /**
  * Split a write payload into ordinary values and field operations.
  *
  * The two travel together in one body — `{ title: "x", views: { $inc: 1 } }` is
  * a single `PATCH` — and are applied in one statement, so a caller never has to
  * choose between setting a column and incrementing another.
+ *
+ * Pass the collection's `properties`: without them a `map` value carrying `$`
+ * keys reads as a (malformed) operation rather than as the document it is.
  */
-export declare function splitFieldOps(values: Record<string, unknown>): {
+export declare function splitFieldOps(values: Record<string, unknown>, properties?: Properties): {
     values: Record<string, unknown>;
     fieldOps: Record<string, ParsedFieldOp>;
 };
@@ -79,8 +88,11 @@ export declare function assertFieldOpsValid(values: Record<string, unknown>, col
  * are meaningless on an insert — `views + 1` over a row that does not exist yet
  * is just `1`, and accepting it would make `$inc` mean two different things
  * depending on a race the caller cannot observe.
+ *
+ * `collection` decides how a `map` value is read (see {@link splitFieldOps});
+ * every request boundary has it and passes it.
  */
-export declare function assertNoFieldOpsOnCreate(values: Record<string, unknown>, context: string): void;
+export declare function assertNoFieldOpsOnCreate(values: Record<string, unknown>, context: string, collection?: CollectionConfig): void;
 /** Re-exported so callers type against one definition of the wire shape. */
 export type { FieldOperation };
 export { FIELD_OPERATORS };

package/dist/api/rest/query-body.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The body of a `POST /<collection>/query`, as the dictionary the `GET`
+ * listing reads off its URL.
+ *
+ * @param body the parsed JSON body — already known to be an object
+ * @param urlParams the names of any parameters on the request's own URL, which
+ *   are refused: two places to put one parameter is two answers to "which one
+ *   applied", and the listing would silently answer one of them
+ */
+export declare function queryDictFromBody(body: Record<string, unknown>, urlParams?: readonly string[]): Record<string, string[]>;

package/dist/api/rest/write-validation.d.ts

@@ -91,11 +91,13 @@ export interface WriteViolation {
  * from that spec believed the server was checking. Enum membership, `email` and
  * `url` were published the same way and enforced the same amount.
  *
- * `required` is checked only when `options.status` says this write creates a
- * row. A `PATCH` legitimately omits keys — this function sees one request's
- * values, not the row they land on — so demanding them there would refuse every
- * partial update. Callers that do not pass a status get the old behaviour and
- * leave `required` to the database's NOT NULL.
+ * A missing `required` key is checked only when `options.status` says this
+ * write creates a row. A `PATCH` legitimately omits keys — this function sees
+ * one request's values, not the row they land on — so demanding them there
+ * would refuse every partial update. Callers that do not pass a status get the
+ * old behaviour and leave a missing key to the database's NOT NULL. A required
+ * string sent as `""` is refused on every write, whatever the status: NOT NULL
+ * would store it.
  *
  * A value of the wrong *type* is not this function's business — that reaches
  * Postgres, which types every column and gives a 400 through the driver's

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

@@ -1,3 +1,12 @@
 import { Hono } from "hono";
+import { SchemaSourceEditor } from "../schema-edit/source-editor.js";
 import { HonoEnv } from "./types.js";
-export declare function createSchemaEditorRoutes(collectionsDir: string): Hono<HonoEnv>;
+/**
+ * The editor for `collectionsDir`: one per process, shared by these routes
+ * and live schema editing's `/apply`. See {@link SchemaSourceEditor}.
+ *
+ * Here rather than beside the class because building it loads `ts-morph`, an
+ * optional peer dependency this module is imported to probe for.
+ */
+export declare function createSchemaSourceEditor(collectionsDir: string): SchemaSourceEditor;
+export declare function createSchemaEditorRoutes(source: SchemaSourceEditor): Hono<HonoEnv>;

package/dist/api/sql-export-routes.d.ts

@@ -0,0 +1,8 @@
+import { Hono } from "hono";
+import { type DatabaseAdmin } from "@rebasepro/types";
+import type { HonoEnv } from "./types.js";
+export interface SqlExportRoutesOptions {
+    /** The default data source's admin capabilities, read per request. */
+    getAdmin: () => DatabaseAdmin | undefined;
+}
+export declare function createSqlExportRoutes(options: SqlExportRoutesOptions): Hono<HonoEnv>;

package/dist/api/types.d.ts

@@ -2,6 +2,7 @@ import type { VectorSearchParams, IncludeSpec, LogicalCondition, FilterValues, N
 import type { DecodedCursor } from "@rebasepro/common";
 import type { AuthResult } from "../auth/middleware.js";
 import type { ApiKeyMasked } from "../auth/api-keys/api-key-types.js";
+import type { BackendServices } from "../backend/services.js";
 /**
  * Hono Environment Variables
  * Passed to generic Hono<HonoEnv> to type `c.get()`
@@ -51,6 +52,12 @@ export type HonoEnv = {
         };
         /** Unique request correlation ID (generated or propagated from X-Request-ID header). */
         requestId?: string;
+        /**
+         * Aborted when a custom function's request outlasts its timeout and is
+         * answered 504. Read it with `getSignal(c)` from
+         * `@rebasepro/server/functions`. See `functions/request-timeout.ts`.
+         */
+        functionSignal?: AbortSignal;
         /**
          * The collection this request is about, when it is about one.
          *
@@ -97,6 +104,29 @@ export type HonoEnv = {
             client: string;
             server: string;
         };
+        /**
+         * Where the route group answering this request is mounted, e.g.
+         * `/api/data` or `/api/functions` — wherever the application put it.
+         *
+         * Set by the group's first middleware from the request itself, so a
+         * group mounted at a path of the caller's choosing still knows which
+         * collection a path names and which URL a function answers at. See
+         * `api/mount-path.ts`.
+         */
+        mountPath?: string;
+        /**
+         * The backend answering this request: its JWT keys, access model,
+         * API-key store and rate limiters.
+         *
+         * Set by the first middleware of every route group a backend builds,
+         * so a group verifies tokens and checks scopes against its own
+         * backend wherever it is mounted, and two backends mounted on one app
+         * stay two. Absent on a route mounted outside any backend, where the
+         * helpers that read it (`requireScope`, `callerScopes`, `requireAuth`,
+         * …) answer for the process default. Set it yourself to make such a
+         * route answer for a backend: `c.set("services", backend.services)`.
+         */
+        services?: BackendServices;
     };
 };
 /**
@@ -157,4 +187,9 @@ export interface QueryOptions {
      * the point of the feature.
      */
     withDeleted?: boolean | "only";
+    /**
+     * From `?count=exact|none` — whether a listing counts `meta.total`. See
+     * `FindParams.count`. Unset is `"exact"`.
+     */
+    count?: "exact" | "none";
 }

package/dist/{ast-schema-editor-CWqS_sLJ.js → ast-schema-editor-mCeSC03x.js}

@@ -2,7 +2,7 @@ import { createRequire as __rebaseCreateRequire } from "module";
 import __rebaseProcess from "process";
 globalThis.process ??= __rebaseProcess;
 __rebaseCreateRequire(import.meta.url);
-import "./src-CatHFUym.js";
+import "./src-D5Y3N-S4.js";
 import { a as nestCollectionPatchPaths, l as nestAdminCollectionKeys, n as collectionPatchProblems, o as runtimeOnlyKeyIn, u as nestAdminPropertyKeys } from "./collection_patch-BRu-BvDv.js";
 import * as fs$1 from "fs";
 import * as path$1 from "path";
@@ -858,6 +858,6 @@ var AstSchemaEditor = class AstSchemaEditor {
 	}
 };
 //#endregion
-export { AstSchemaEditor };
+export { AstSchemaEditor, nestAdminKeys, nestAdminKeysDeep };
 
-//# sourceMappingURL=ast-schema-editor-CWqS_sLJ.js.map
+//# sourceMappingURL=ast-schema-editor-mCeSC03x.js.map