@rebasepro/types 0.22.0 → 0.24.0

package/dist/types/collection_patch.d.ts

@@ -0,0 +1,74 @@
+/** One change to a collection. `path` is a list of object keys. */
+export type CollectionPatchOp = {
+    op: "set";
+    path: string[];
+    value: unknown;
+} | {
+    op: "remove";
+    path: string[];
+};
+/** @group Models */
+export type CollectionPatch = CollectionPatchOp[];
+/**
+ * Keys the runtime adds to a collection that must never be written into its
+ * source. `resolvedRelation` is the registry's resolved form of a relation; a
+ * file holding one does not type-check (`target` is missing from it).
+ */
+export declare const RUNTIME_ONLY_COLLECTION_KEYS: readonly string[];
+/** A JSON value as JSON would carry it: functions, `undefined` and symbols dropped. */
+export declare function toCollectionJson(value: unknown): unknown;
+/**
+ * The operations that take `before` to `after`, both JSON values.
+ *
+ * Objects are compared key by key; anything else that differs — a primitive,
+ * an array, a change of kind — is set whole.
+ */
+export declare function diffJsonValues(before: unknown, after: unknown, path?: string[]): CollectionPatch;
+/**
+ * The patch, with every flat presentation key moved into its `admin` block.
+ *
+ * The panel edits a flat view model — `icon` beside `name`, a property's
+ * `readOnly` beside its `type` — while the file keeps them under `admin`. The
+ * difference is taken on the flat model, because that is where a cleared field
+ * shows up as a removed key (the `admin` copy the model was loaded with still
+ * holds the old value), and moved here.
+ *
+ * The flat value wins over the `admin` copy, as in {@link nestAdminKeysOf}:
+ * operations that were already under `admin` are ordered first, so the flat
+ * one — what the form just wrote — is applied last.
+ */
+export declare function nestCollectionPatchPaths(patch: CollectionPatch): CollectionPatch;
+/**
+ * The patch that takes the collection the editor loaded to the one it is
+ * saving, in the authoring shape. Empty when nothing changed.
+ *
+ * Both sides go through JSON first, so whatever JSON cannot carry — a
+ * function, a value it drops — is equally absent from both and never appears
+ * as a change.
+ */
+export declare function diffCollections(loaded: unknown, saving: unknown): CollectionPatch;
+/**
+ * Why a patch may not be applied, or an empty list.
+ *
+ * Checked by every door that accepts one: a path is a list of non-empty object
+ * keys that cannot reach a prototype, and no runtime-only key may be written.
+ */
+export declare function collectionPatchProblems(patch: unknown): string[];
+/**
+ * The first runtime-only key (see {@link RUNTIME_ONLY_COLLECTION_KEYS}) found
+ * anywhere in a value, or `undefined`. For the doors that take a whole
+ * collection rather than a patch.
+ */
+export declare function runtimeOnlyKeyIn(value: unknown): string | undefined;
+/** A patch every door may apply: {@link collectionPatchProblems} found nothing. */
+export declare function isCollectionPatch(patch: unknown): patch is CollectionPatch;
+/**
+ * `target` with the patch applied, copying only what it changes.
+ *
+ * Everything the patch does not reach is shared with `target` by reference —
+ * functions, thunks and all — which is what lets a planner see a relation's
+ * `target()` on the patched collection exactly as it was. Intermediate objects
+ * a `set` needs are created; a `remove` of a key that is not there is nothing
+ * to do.
+ */
+export declare function applyCollectionPatch<T>(target: T, patch: CollectionPatch): T;

package/dist/types/collections.d.ts

@@ -4,6 +4,7 @@ import type { User } from "../users/index.js";
 import type { EmailSendResult } from "../controllers/email.js";
 import type { Relation } from "./relations.js";
 import type { SecurityRule } from "./security_rules.js";
+import type { RoleDefinition, ScopeDefinition } from "./scopes.js";
 import type { SearchConfig } from "./search.js";
 import type { CollectionIndex } from "./indexes.js";
 import type { CollectionTenantConfig } from "./tenancy.js";
@@ -614,6 +615,28 @@ export type InferCollectionConfigType<S extends CollectionConfig> = S extends Co
 export interface AuthCollectionConfig {
     /** Set to true to mark this collection as the authentication collection. */
     enabled: boolean;
+    /**
+     * The app's roles and the admin-plane scopes each holds.
+     *
+     * `admin` is built in — it holds every scope — and cannot be declared. A
+     * role used only by RLS policies needs no entry here. See
+     * {@link RoleDefinition}.
+     */
+    roles?: Record<string, RoleDefinition>;
+    /**
+     * Scopes the app defines for its own operations, named `resource:action`
+     * like the built-in ones and checked with `requireScope` in a function.
+     * Every signed-in person holds them; they exist so a key can be narrowed
+     * to one action. See {@link ScopeDefinition}.
+     */
+    scopes?: Record<string, ScopeDefinition>;
+    /**
+     * Let every signed-in account mint personal API keys at
+     * `/api/auth/keys`. A personal key acts as its owner and can never hold
+     * a scope its owner does not. Off by default: each one is a long-lived
+     * credential for the account, and an app opts into handing those out.
+     */
+    personalKeys?: boolean;
     /**
      * Called when an admin creates a user, through the collection REST API or
      * `POST /admin/users`.

package/dist/types/cron.d.ts

@@ -43,7 +43,9 @@ export interface CronJobDefinition {
     enabled?: boolean;
     /**
      * Maximum number of seconds the handler may run before being
-     * considered timed-out. Default: 300 (5 min).
+     * considered timed-out. Default: 300 (5 min). `Infinity` means no
+     * timeout. Zero, a negative number or `NaN` is refused when the job
+     * loads, and the job is listed as rejected.
      */
     timeoutSeconds?: number;
     /**
@@ -92,10 +94,15 @@ export interface CronJobContext {
     jobId: string;
     /** The current scheduled tick timestamp. */
     scheduledAt: Date;
-    /** A simple logger scoped to this job run. */
+    /**
+     * A simple logger scoped to this job run. Each line is kept with the
+     * run's log entry and also written to the server log at `info`, with a
+     * `cron` field holding the job ID.
+     */
     log: (...args: unknown[]) => void;
     /**
-     * Aborted when the run exceeds `timeoutSeconds`.
+     * Aborted when the run exceeds `timeoutSeconds`, or when the server
+     * shuts down and the run has not finished within the shutdown's wait.
      *
      * The timeout has always stopped the scheduler *waiting* — it loses the
      * race and the run is recorded as failed. It has never stopped the handler:
@@ -176,11 +183,43 @@ export interface CronJobStatus {
     lastDurationMs?: number;
     /** Error message from the last failed run. */
     lastError?: string;
-    /** Total number of executions since server start. */
+    /**
+     * Executions in the run history: every process's, read from `cron_logs`
+     * where runs are persisted, and this process's own otherwise.
+     */
     totalRuns: number;
-    /** Total number of failed executions since server start. */
+    /** How many of {@link totalRuns} failed. */
     totalFailures: number;
 }
+/**
+ * A job the scheduler refused, and why.
+ *
+ * It is not a `CronJobStatus`: it has no state, no next run and no counters,
+ * because it was never registered. Reporting it as a job with `state: "error"`
+ * would be a lie in the other direction — nothing is going to run it.
+ */
+export interface RejectedCronJob {
+    id: string;
+    name: string;
+    schedule: string;
+    /** Why it was refused — most often `Expected 5 fields, got 6`. */
+    reason: string;
+}
+/** What the cron listing (`GET /admin/cron`) answers. */
+export interface CronJobListing {
+    /** The registered jobs. */
+    jobs: CronJobStatus[];
+    /**
+     * Cron files that did not become jobs: the files that failed to load,
+     * plus the jobs in {@link rejected}. Absent when there are none. None of
+     * them is scheduled.
+     */
+    skipped?: number;
+    /** The jobs the scheduler refused, by name, with the reason. */
+    rejected?: RejectedCronJob[];
+    /** {@link skipped} and {@link rejected}, in a sentence. */
+    note?: string;
+}
 export type CronLogLevel = "info" | "error" | "warn";
 /**
  * A single execution log entry stored in the in-memory ring buffer.

package/dist/types/database_adapter.d.ts

@@ -21,7 +21,7 @@
  */
 import type { DataDriver } from "../controllers/data_driver.js";
 import type { CollectionConfig } from "./collections.js";
-import type { CollectionRegistryInterface, DatabaseAdmin, InitializedDriver, RealtimeProvider, BootstrappedAuth } from "./backend.js";
+import type { CollectionRegistryInterface, DatabaseAdmin, InitializedDriver, RealtimeProvider, RealtimeSocketOptions, BootstrappedAuth } from "./backend.js";
 import type { HistoryConfig } from "../controllers/client.js";
 /**
  * A `DatabaseAdapter` provides data persistence for Rebase.
@@ -73,8 +73,12 @@ export interface DatabaseAdapter {
      * already passed it, so it was dropped at every adapter that routed through
      * here — turning an adapter-authenticated server's socket into one that
      * accepted every client as already authenticated.
+     *
+     * `limits` are the data API's body and per-caller rate limits, for the
+     * socket's frames: it serves the same rows, and without them a frame had
+     * neither. Forwarded for the same reason `adapter` is.
      */
-    initializeWebsockets?(server: unknown, realtimeService: RealtimeProvider, driver: DataDriver, config?: unknown, adapter?: import("./auth_adapter.js").AuthAdapter): Promise<void> | void;
+    initializeWebsockets?(server: unknown, realtimeService: RealtimeProvider, driver: DataDriver, config?: unknown, adapter?: import("./auth_adapter.js").AuthAdapter, limits?: RealtimeSocketOptions): Promise<void> | void;
     /**
      * Ask the database whether it is there, before boot's first real query. See
      * `BackendBootstrapper.verifyConnection` for the contract.

package/dist/types/index.d.ts

@@ -15,6 +15,7 @@ export * from "./entity_callbacks.js";
 export * from "./websockets.js";
 export * from "./backend.js";
 export * from "./schema_editing.js";
+export * from "./collection_patch.js";
 export * from "./channel_bus.js";
 export * from "./data_source.js";
 export * from "./resources.js";
@@ -27,6 +28,7 @@ export * from "./component_ref.js";
 export * from "./auth_adapter.js";
 export * from "./database_adapter.js";
 export * from "./api_keys.js";
+export * from "./scopes.js";
 export * from "./history.js";
 export * from "./postgres_introspection.js";
 export * from "./project_manifest.js";

package/dist/types/postgres_introspection.d.ts

@@ -56,8 +56,18 @@ export interface TableJunctionInfo {
  */
 export interface TablePolicyInfo {
     policy_name: string;
+    /**
+     * The policy's `TO` list — *database* roles, `public` for every
+     * connection — as `pg_policies.roles` reports it.
+     */
     roles: string[];
+    /** `SELECT`, `INSERT`, `UPDATE`, `DELETE` or `ALL`, as `pg_policies.cmd` reports it. */
     cmd: string;
+    /**
+     * `pg_policies.permissive`. Absent means `PERMISSIVE`, Postgres's own
+     * default.
+     */
+    permissive?: "PERMISSIVE" | "RESTRICTIVE";
     qual?: string;
     with_check?: string;
 }

package/dist/types/project_manifest.d.ts

@@ -132,6 +132,20 @@ export interface RebaseStaticAppConfig {
      * loads and every asset 404s: a blank page with no server error. `rebase
      * build` passes it as `REBASE_APP_BASE` and asserts the emitted HTML honours
      * it. Changing this value requires rebuilding the app.
+     *
+     * **Or a full URL, to give the app a hostname of its own:**
+     * `"https://admin.example.com"`, or `"https://admin.example.com/cms"` for a
+     * path under it. The app then answers only on that hostname, and every app
+     * without one keeps answering on all the others. The URL form is split by
+     * {@link parseAppAddress}: the hostname travels as the bundle's
+     * {@link RebaseBundleStatic.host}, and the path part is what the rules above
+     * (and `REBASE_APP_BASE`) apply to. HTTPS only, with no port, query or
+     * fragment — a hostname is served over TLS by the platform, not chosen per
+     * request.
+     *
+     * On Rebase Cloud the deploy registers the hostname on the project. It is
+     * live once its DNS records verify, which the deploy prints when they don't
+     * yet.
      */
     path?: string;
     /**
@@ -191,6 +205,42 @@ export declare const RESERVED_BACKEND_PREFIXES: readonly ["/api", "/health", "/h
  * that is looser admits paths that will not.
  */
 export declare function reservedPrefixFor(path: string): string | undefined;
+/**
+ * Where a static app answers: on one hostname or all of them, at a path.
+ *
+ * `host` absent is every hostname the project is served on.
+ */
+export interface AppAddress {
+    host?: string;
+    path: string;
+}
+export type AppAddressResult = {
+    ok: true;
+    address: AppAddress;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Split a static app's declared `path` into the hostname it claims and the path
+ * under it.
+ *
+ * `"/admin"` is `{ path: "/admin" }`, returned as written: the path rules
+ * (leading slash, no `..`, reserved prefixes) belong to the caller, which
+ * applies them to the path part of either form. `"https://admin.example.com/cms"`
+ * is `{ host: "admin.example.com", path: "/cms" }`.
+ *
+ * Shared because three parties must read the same value the same way: the CLI
+ * while `rebase.json` is edited, the control plane at deploy intake (a bundle can
+ * come from any CLI, or none), and the runtime choosing which app answers.
+ */
+export declare function parseAppAddress(value: string): AppAddressResult;
+/**
+ * Whether `host` is a public DNS name an app can be given: lowercase labels of
+ * letters, digits and hyphens, at least two of them, not an IP address and not
+ * `localhost`. Internationalised names arrive here already in punycode.
+ */
+export declare function isValidAppHost(host: string): boolean;
 /**
  * One declared storage source, as authored in `rebase.json`.
  *
@@ -375,8 +425,22 @@ export interface RebaseBundleEntrypoints {
 }
 /** One built static app inside a bundle. */
 export interface RebaseBundleStatic {
-    /** Public base path, e.g. `/` or `/admin`. */
+    /** Public base path, e.g. `/` or `/admin`. Always a path, never a URL. */
     path: string;
+    /**
+     * The one hostname this app answers on, lowercase, e.g. `admin.example.com`.
+     *
+     * Absent means every hostname the project is served on, which is what every
+     * app was before this field existed. Present, the app answers only for
+     * requests whose `Host` is exactly this — the path part of its address is
+     * still `path`. At an equal `path`, an app naming the request's hostname
+     * wins over one that does not.
+     *
+     * A runtime that predates this field ignores it and would mount two apps at
+     * the same `path`, so a bundle carrying it must only ever reach a runtime
+     * that reads it. The control plane enforces that at intake.
+     */
+    host?: string;
     /** Bundle-relative directory holding the built assets. */
     dir: string;
     /** Serve `index.html` for unmatched paths under `path`. */

package/dist/types/properties.d.ts

@@ -435,6 +435,13 @@ export interface StringProperty extends BaseProperty {
      * Drizzle append: `.primaryKey()`
      * UI behavior: Field value cannot be changed after creation.
      *
+     * Marking several properties declares one composite key: the table gets a
+     * single `PRIMARY KEY (a, b)` constraint (Drizzle: `primaryKey({ columns })`)
+     * and a row is addressed by all of its key values, joined in declaration
+     * order — `1:::en_US`. A foreign key cannot point at a composite key, so a
+     * relation or reference into such a collection is refused by the schema
+     * generators.
+     *
      * You can set this to `"manual"` for a user-defined ID, or specify a generation strategy:
      * 'uuid' -> Drizzle `.defaultRandom()` (Postgres gen_random_uuid())
      * Or any other string to act as a raw SQL default expression, written either
@@ -565,6 +572,10 @@ export interface NumberProperty extends BaseProperty {
      * Drizzle append: `.primaryKey()`
      * UI behavior: Field value cannot be changed after creation.
      *
+     * Marking several properties declares one composite key — see
+     * {@link StringProperty.isId}. A column whose value the database does not
+     * generate, such as a foreign key that is part of the key, takes `true`.
+     *
      * You can set this to `"manual"` for a user-defined ID, or specify a generation strategy:
      * 'increment' -> PostgreSQL `INTEGER GENERATED BY DEFAULT AS IDENTITY`.
      * Or any other string to act as a raw SQL default expression, bare or in

package/dist/types/schema_editing.d.ts

@@ -24,7 +24,19 @@
  *   changing a type, moving a primary key.
  */
 export type SchemaChangeVerdict = "safe" | "diverges" | "needs-migration";
-export type SchemaChangeKind = "add-collection" | "remove-collection" | "add-property" | "remove-property" | "change-property-type" | "rename-column" | "add-enum-value" | "remove-enum-value" | "change-required" | "change-primary-key";
+export type SchemaChangeKind = "add-collection" | "remove-collection" | "add-property" | "remove-property" | "change-property-type" | "rename-column" | "add-enum-value" | "remove-enum-value" | "change-required" | "change-primary-key" | "rename-table"
+/** A property key renamed while keeping its column: no data moves. */
+ | "rename-property"
+/** A relation's kind, foreign key or link column changes. */
+ | "change-relation"
+/** A UNIQUE constraint, an index or an update trigger appears or goes. */
+ | "change-constraint"
+/** A column's DEFAULT is set, changed or dropped. */
+ | "change-default"
+/** The proposed collections cannot be planned at all. */
+ | "invalid-collection"
+/** A collection's row-level security policies change. */
+ | "change-security-rules";
 export interface SchemaChange {
     kind: SchemaChangeKind;
     verdict: SchemaChangeVerdict;
@@ -36,6 +48,15 @@ export interface SchemaChange {
     detail: string;
     /** What to do instead, when the verdict is not `safe`. */
     remedy?: string;
+    /**
+     * What "Edit source only" leaves behind for this change: the collection is
+     * committed and the database is not touched. Absent on a change that may
+     * not be written source-only at all — one that would leave a project that
+     * does not start, or reads its data as the wrong type.
+     */
+    sourceOnly?: string;
+    /** The same, in a few words for a commit subject: `column products.sku kept`. */
+    kept?: string;
 }
 export interface ClassifiedSchemaChanges {
     changes: SchemaChange[];
@@ -56,24 +77,23 @@ export interface ClassifiedSchemaChanges {
 export interface SchemaCommitPaths {
     /** Drizzle schema, imported by the backend. */
     schemaFile: string;
-    /** Declarative DDL, what `db push` applies and Atlas diffs against. */
-    ddlFile: string;
-    policiesFile: string;
-    searchFile: string;
-    /** Vector columns and ANN indexes — like search, applied by Rebase not Atlas. */
-    vectorFile: string;
-    /**
-     * `autoValue: "on_update"` triggers and the function they share. Atlas's
-     * free tier will not parse a desired state containing a function, so this
-     * is applied by Rebase like search and vector.
-     */
-    triggersFile: string;
 }
+/**
+ * The SQL `db push` and `db generate` render — `schema.sql`, `policies.sql` and
+ * the rest — is not here, and must not come back. Both commands regenerate it
+ * from the collections before reading it, so nothing ever read a committed
+ * copy; it lives in the gitignored `.rebase/sql/`. When the commit carried it,
+ * it carried a second copy besides: these paths are from the project root,
+ * while the CLI writes beside the backend, so a live edit left `drizzle/` and
+ * `backend/drizzle/` disagreeing about the schema.
+ */
 export declare const DEFAULT_COMMIT_PATHS: SchemaCommitPaths;
 /** One file the commit writes, as content rather than as a path on a disk. */
 export interface SchemaChangeFile {
     path: string;
     contents: string;
+    /** The commit removes this file — a deleted collection. `contents` is ignored. */
+    deleted?: boolean;
 }
 /**
  * Everything a change needs written and run.
@@ -106,7 +126,7 @@ export interface SchemaChangePlan {
 export interface WithheldSchemaConstraint {
     /** `schema.table.column`. */
     target: string;
-    kind: "not-null";
+    kind: "not-null" | "unique";
     /** What is in the way, naming the obstacle rather than the rule. */
     reason: string;
     /** What would make it applicable. */
@@ -131,5 +151,11 @@ export interface SchemaEditingAdmin {
      */
     planSchemaChange(before: unknown[], after: unknown[], options?: {
         paths?: Partial<SchemaCommitPaths>;
+        /**
+         * Plan a commit of the source alone — "Edit source only": never
+         * rejects an unapplicable change, carries no statements, and its
+         * message names what is left in the database.
+         */
+        sourceOnly?: boolean;
     }): Promise<SchemaChangePlan>;
 }