@rebasepro/types 0.23.0 → 0.24.1-canary.g56af4a4

package/dist/types/backend.d.ts

@@ -246,6 +246,42 @@ export interface RealtimeChannelsConfig {
      * Defaults to `{ type: "memory" }` — i.e. they don't.
      */
     bus?: ChannelBusSetting;
+    /**
+     * How many subscriptions one socket may hold; the next is refused with
+     * `TOO_MANY_SUBSCRIPTIONS`. A positive whole number, checked at boot.
+     * Defaults to 1000. `REALTIME_MAX_SUBSCRIPTIONS_PER_SOCKET` wins over it.
+     */
+    maxSubscriptionsPerSocket?: number;
+    /**
+     * How many sockets one user (one identity: a signed-in user, an API key's
+     * user, an impersonated user) may hold open on one server instance. The
+     * next one's `AUTHENTICATE` is refused with `TOO_MANY_SOCKETS` and the
+     * socket closed with 4002; the SDK keeps retrying with backoff, so it gets
+     * in once another closes. A positive whole number, checked at boot.
+     * Unset (the default) is no ceiling. `REALTIME_MAX_SOCKETS_PER_USER` wins
+     * over it.
+     */
+    maxSocketsPerUser?: number;
+    /**
+     * The longest a change waits for the refetch that delivers it, in ms. A
+     * refetch waits for 300 ms without a change, and at most this long under a
+     * steady stream of writes. Defaults to 1000. A positive whole number,
+     * checked at boot. `REALTIME_REFETCH_MAX_WAIT_MS` wins over it.
+     */
+    refetchMaxWaitMs?: number;
+    /**
+     * How long a big list subscription's total may be reused before it is
+     * counted again, in ms. Unset (the default), every frame counts. Frames
+     * that reuse it carry `meta.totalAsOf`. `REALTIME_RECOUNT_INTERVAL_MS`
+     * wins over it.
+     */
+    recountIntervalMs?: number;
+    /**
+     * The smallest last total at which {@link recountIntervalMs} applies;
+     * smaller lists are counted on every frame. Defaults to 100 000.
+     * `REALTIME_RECOUNT_MIN_ROWS` wins over it.
+     */
+    recountMinRows?: number;
 }
 /**
  * Abstract realtime provider interface.
@@ -293,6 +329,25 @@ export interface RealtimeProvider {
      * Called during graceful shutdown before closing database connections.
      */
     stopListening?(): Promise<void>;
+    /**
+     * The long-lived connections realtime depends on, for `/health`. A change
+     * feed that has gone quiet — a half-open LISTEN connection — loses every
+     * external and cross-instance change while writes through this instance
+     * still look live, so it is reported rather than inferred.
+     */
+    health?(): RealtimeListenerHealth[];
+}
+/**
+ * One long-lived realtime connection, as `/health` reports it.
+ * @group Backend
+ */
+export interface RealtimeListenerHealth {
+    /** What it carries — `"cdc"`, `"cross-instance"`, `"channel-bus"`. */
+    name: string;
+    /** Listening on a connection that answered its last heartbeat. */
+    connected: boolean;
+    /** When (epoch ms) it went down, while it is down. */
+    downSince?: number;
 }
 /**
  * Abstract collection registry interface.
@@ -341,6 +396,124 @@ export interface DataTransformer {
      */
     deserializeFromDatabase<M extends Record<string, unknown>>(data: Record<string, unknown>, collection: CollectionConfig): Promise<M>;
 }
+/**
+ * The table column a value of a {@link SqlScriptResult} was read from, as the
+ * database itself reported it — not as the query's text suggests.
+ *
+ * @group Admin
+ */
+export interface SqlScriptColumnSource {
+    schema: string;
+    table: string;
+    column: string;
+}
+/**
+ * One column of a {@link SqlScriptResult}, in result order.
+ *
+ * @group Admin
+ */
+export interface SqlScriptColumn {
+    /** The name the result gives it. Two columns of one result may share it. */
+    name: string;
+    /** Its type, as the database names it: `integer`, `text[]`, `timestamp with time zone`. */
+    type?: string;
+    /**
+     * Where the database says the value came from: a plain reference to a
+     * column of a table or view, through any number of subqueries.
+     *
+     * Absent for everything no stored row holds — an expression, a cast that
+     * changes the type, a literal, an aggregate, a function's output, a
+     * `UNION`.
+     */
+    source?: SqlScriptColumnSource;
+}
+/**
+ * A table or view some column of a {@link SqlScriptResult} came from.
+ *
+ * @group Admin
+ */
+export interface SqlScriptTable {
+    schema: string;
+    table: string;
+    /** What the relation is. Only a `table` or a `partitioned table` holds rows that can be updated by key. */
+    kind: "table" | "partitioned table" | "view" | "materialized view" | "foreign table" | "other";
+    /** Its primary key columns, in key order. Empty when it has none. */
+    primaryKey: string[];
+    /**
+     * Other tables inherit this one (by `INHERITS`, not as partitions). A row
+     * read from it may live in one of them, and a primary key is not unique
+     * across them.
+     */
+    hasInheritors: boolean;
+}
+/**
+ * Something the database said while a script ran: `there is no transaction in
+ * progress` for a ROLLBACK with nothing to end, a `RAISE NOTICE`.
+ *
+ * @group Admin
+ */
+export interface SqlScriptNotice {
+    severity: string;
+    message: string;
+}
+/**
+ * What a SQL script a person wrote returned. See {@link SQLAdmin.runSqlScript}.
+ *
+ * @group Admin
+ */
+export interface SqlScriptResult {
+    /**
+     * The last statement's rows, every value as the text the database wrote
+     * for it and `null` for SQL NULL — so a value written back is the value
+     * that was read, whatever its type. Keyed by column name: of two columns
+     * that share a name, the row holds the last.
+     */
+    rows: Record<string, string | null>[];
+    /** The last statement's columns, in order. */
+    columns: SqlScriptColumn[];
+    /** The tables and views {@link SqlScriptColumn.source} names. */
+    tables: SqlScriptTable[];
+    /** The last statement's command: `SELECT`, `UPDATE`, `CREATE TABLE` … */
+    command?: string;
+    /**
+     * How many rows the last statement returned or changed, when its command
+     * reports a count — or, for a {@link truncated} result, how many it
+     * returned, of which {@link rows} holds the first.
+     */
+    rowCount?: number;
+    /**
+     * The last statement returned more than a run keeps, and {@link rows}
+     * holds only its first rows. The Studio console's door keeps at most
+     * 10,000 rows, or 32 Mi characters of values, of one result: a run that
+     * held every row of a million-row table took the server down with it.
+     */
+    truncated?: boolean;
+    /** What the database said while the script ran, in order. */
+    notices: SqlScriptNotice[];
+    /**
+     * The database role the script ran as, when it asked for one — said by
+     * the transport that ran it. The role asked for, unless the server has
+     * role switching turned off (`DISABLE_DB_ROLE_SWITCHING`) and runs every
+     * statement as the connection owner, who is named here instead.
+     */
+    effectiveRole?: string;
+}
+/**
+ * A query's result being read a batch at a time — see `SQLAdmin.openSqlCursor`.
+ *
+ * @group Admin
+ */
+export interface SqlCursor {
+    /** The result's column names, in order. */
+    readonly columns: string[];
+    /**
+     * The next rows, each value the text the database wrote for it and `null`
+     * for NULL — `null` once there are none left.
+     */
+    read(): Promise<(string | null)[][] | null>;
+    /** End the read and give the session back. Safe to call more than once. */
+    close(): Promise<void>;
+}
 /**
  * Administrative operations for SQL-based databases (PostgreSQL, MySQL, etc.).
  * Used by the SQL Editor, RLS Editor, and schema browser.
@@ -356,13 +529,60 @@ export interface SQLAdmin {
      * before it is reused. For SQL a person wrote (the Studio editor), which
      * may `SET ROLE` and must not leave that on a pooled connection the
      * server's own queries use next.
+     *
+     * `maxResultBytes` refuses a result whose rows take more than that many
+     * bytes, with an error whose `code` is `RESULT_TOO_LARGE`, rather than
+     * return it — never a part of it. On a session of its own the read stops
+     * there; elsewhere the rows are measured once read. The WebSocket
+     * `EXECUTE_SQL` door sets it for every caller.
      */
     executeSql(sql: string, options?: {
         database?: string;
         role?: string;
         params?: unknown[];
         isolateSession?: boolean;
+        maxResultBytes?: number;
     }): Promise<Record<string, unknown>[]>;
+    /**
+     * Run a script a person wrote — the Studio SQL console — and describe what
+     * it returned.
+     *
+     * On a session of its own, reset afterwards, as `role` for every statement
+     * of it. Values come back as the database's text, and each column says
+     * which table column it was read from, when the database says so: what
+     * the console needs to write a cell back to the row it came from and to
+     * no other. A script that leaves a transaction open is refused, and the
+     * transaction rolled back: nothing outlives the run to be committed or
+     * rolled back by a later one.
+     *
+     * Aborting `signal` cancels the run: the statement in progress is stopped
+     * (`pg_cancel_backend` on a Postgres server; the in-process development
+     * database cannot be interrupted, and the run ends on its own), and the
+     * promise rejects.
+     */
+    runSqlScript?(sql: string, options?: {
+        database?: string;
+        role?: string;
+        signal?: AbortSignal;
+    }): Promise<SqlScriptResult>;
+    /**
+     * Read the whole result of ONE query a person wrote, a batch at a time —
+     * the Studio SQL console's "Download full result as CSV", which the
+     * console's 10,000-row cap would otherwise leave no way to get.
+     *
+     * Through a server-side cursor, in a read-only transaction, on a session
+     * of its own, as `role`: a write is refused by the database, and a second
+     * statement by the protocol. Each batch is read when the previous one has
+     * been consumed, so memory holds one batch whatever the result's size;
+     * every read runs under the session's `statement_timeout`. The session is
+     * reset and returned when the cursor is closed — which the caller must do,
+     * on success, failure or a reader that went away.
+     */
+    openSqlCursor?(sql: string, options?: {
+        database?: string;
+        role?: string;
+        batchSize?: number;
+    }): Promise<SqlCursor>;
     /**
      * Fetch the available databases on the server.
      */
@@ -388,6 +608,21 @@ export interface SQLAdmin {
      * Fetch the current database name.
      */
     fetchCurrentDatabase?(): Promise<string | undefined>;
+    /**
+     * Hold a `LISTEN` on `channel`, on a connection of its own that stays open
+     * and comes back after a drop, and call `onNotify` with each payload — what
+     * wakes the job worker when another process enqueues, instead of a poll
+     * every two seconds.
+     *
+     * Resolves once listening, with the stop. Rejects when no such connection
+     * can be had — an in-process database, a first connect that fails — so the
+     * caller can fall back to polling. `onReconnect` is called each time a
+     * dropped connection is listening again: whatever was sent meanwhile is
+     * lost. `channel` must be a plain identifier.
+     */
+    listen?(channel: string, onNotify: (payload: string) => void, options?: {
+        onReconnect?: () => void;
+    }): Promise<() => Promise<void>>;
 }
 /**
  * Administrative operations for document-based databases (MongoDB, Firestore, etc.).
@@ -433,6 +668,12 @@ export interface SchemaAdmin {
 export interface BranchInfo {
     /** Branch name (without prefix). */
     name: string;
+    /**
+     * The PostgreSQL database the branch is — what to connect to, and what to
+     * name as the source when copying it. As the branch's record says, never
+     * derived from `name` again.
+     */
+    database: string;
     /** The database this branch was created from. */
     parentDatabase: string;
     /** When the branch was created. */
@@ -598,6 +839,15 @@ export interface DataRateLimitCaller {
      * the caller by address at the anonymous allowance.
      */
     uid?: string;
+    /**
+     * The API key the connection authenticated with. Its frames count in the
+     * key's own bucket at the key's own `rate_limit`, the bucket its HTTP
+     * requests count in, rather than as `uid`.
+     */
+    apiKey?: {
+        id: string;
+        rate_limit: number | null;
+    };
     /**
      * A header of the request that opened the connection, by lower-case name:
      * the proxy headers an address is read from when proxies are declared.
@@ -607,11 +857,30 @@ export interface DataRateLimitCaller {
     socketAddress?: string;
 }
 /**
- * The data API's request limits, handed to the realtime socket so its frames
- * carry the ones an HTTP request to the same rows does.
+ * What the realtime socket shares with the HTTP data API: its request limits,
+ * so a frame carries the ones an HTTP request to the same rows does, and its
+ * API-key verification, so a key means the same thing on both.
  * @group Backend
  */
-export interface RealtimeSocketLimits {
+export interface RealtimeSocketOptions {
+    /**
+     * Verify an `rk_` API key presented to `AUTHENTICATE`: the identity it acts
+     * as and the scopes it holds, or why it does not authenticate. Absent when
+     * the deployment has no API-key store, and then keys cannot authenticate
+     * the socket.
+     */
+    resolveApiKey?: (token: string) => Promise<{
+        uid: string;
+        roles: string[];
+        scopes: string[];
+        /** The key itself: its id and `rate_limit` decide which rate-limit bucket its frames count in. */
+        apiKey?: {
+            id: string;
+            rate_limit: number | null;
+        };
+    } | {
+        message: string;
+    }>;
     /**
      * The largest frame accepted, in bytes — the data API's body limit. `0` or
      * less for none. Defaults to the server's default body limit.
@@ -626,6 +895,24 @@ export interface RealtimeSocketLimits {
         allowed: boolean;
         retryAfterMs: number;
     } | null>;
+    /**
+     * How often a socket that only listens has its identity re-read, in ms
+     * (default 30 000). A socket that sends frames is re-checked before each
+     * one; this bounds how long a subscription keeps receiving rows as an
+     * identity that has since signed out, been revoked, demoted or deleted.
+     */
+    identityRecheckIntervalMs?: number;
+    /**
+     * How often a socket that asked for heartbeats (`?rebase_caps=heartbeat`)
+     * is sent one, in ms (default 30 000). The SDK redials after two missed.
+     */
+    heartbeatIntervalMs?: number;
+    /**
+     * How many sockets one identity may hold open on this server; the next
+     * one's `AUTHENTICATE` is refused with `TOO_MANY_SOCKETS` and the socket
+     * closed (4002). Unset for no ceiling. See `realtime.maxSocketsPerUser`.
+     */
+    maxSocketsPerUser?: number;
 }
 /**
  * A `BackendBootstrapper` encapsulates all driver-specific initialization logic.
@@ -832,7 +1119,7 @@ export interface BackendBootstrapper {
     /**
      * Initialize WebSocket server for realtime operations.
      */
-    initializeWebsockets?(server: unknown, realtimeService: RealtimeProvider, driver: import("../controllers/data_driver.js").DataDriver, config?: unknown, authAdapter?: AuthAdapter, limits?: RealtimeSocketLimits): Promise<void> | void;
+    initializeWebsockets?(server: unknown, realtimeService: RealtimeProvider, driver: import("../controllers/data_driver.js").DataDriver, config?: unknown, authAdapter?: AuthAdapter, limits?: RealtimeSocketOptions): Promise<void> | void;
 }
 /**
  * Result of `BackendBootstrapper.initializeDriver()`.
@@ -868,8 +1155,6 @@ export interface InitializedDriver {
 export interface BootstrappedAuth {
     /** User management service. */
     userService: unknown;
-    /** Role management service (optional, roles are now simple strings). */
-    roleService?: unknown;
     /** Email service (optional). */
     emailService?: unknown;
     /** Combined Auth Repository for unified token and user management. */

package/dist/types/backup.d.ts

@@ -25,3 +25,105 @@ export interface BackupInfo {
      */
     globalsKey?: string;
 }
+/**
+ * How one run of the scheduled backup went, read from the cron's run history.
+ */
+export interface BackupRunOutcome {
+    /** ISO timestamp the run started. */
+    startedAt: string;
+    /** ISO timestamp the run ended. */
+    finishedAt: string;
+    /** Whether the run produced a backup. */
+    success: boolean;
+    /** Why it did not, when it failed — e.g. `Could not find the 'pg_dump' binary.` */
+    error?: string;
+    /** True when someone triggered the run by hand rather than the schedule. */
+    manual: boolean;
+}
+/**
+ * The deployment's scheduled backup job — the cron that default-exports
+ * `createBackupCron` — and the outcome of its last run.
+ *
+ * Shown by the Backups panel so a backup that fails every night is visible
+ * where the backups are listed, rather than only in the cron history.
+ */
+export interface BackupScheduleStatus {
+    /** The cron job's id, which is its file's name. */
+    jobId: string;
+    /** The job's display name. */
+    name: string;
+    /** Its cron expression. */
+    schedule: string;
+    /** False when the job is paused (or declared `enabled: false`), or refused. */
+    enabled: boolean;
+    /**
+     * True when the job is off because its own definition says
+     * `enabled: false` — the documented backup cron file exports it that way
+     * while `BACKUP_SCHEDULE` is unset — and not because someone paused it.
+     * Resuming it in Cron Jobs would run that definition as written.
+     */
+    disabledInCode?: boolean;
+    /**
+     * Why the scheduler refused the job — an invalid schedule, timezone or
+     * timeout. A refused job is not registered and never runs; the cron file
+     * has to change.
+     */
+    refused?: string;
+    /** ISO timestamp of the next scheduled run, when one is armed. */
+    nextRunAt?: string;
+    /**
+     * The most recent scheduled run, absent when the schedule has never run
+     * it — or when its run history could not be read, which
+     * {@link historyError} says. A run someone started by hand is not one:
+     * see {@link lastManualRun}.
+     */
+    lastRun?: BackupRunOutcome;
+    /** A run started by hand ("Run Now") since {@link lastRun}, when there is one. */
+    lastManualRun?: BackupRunOutcome;
+    /**
+     * Why the job's run history could not be read. Whether it ran, and how it
+     * went, is then unknown: `lastRun` is absent for that reason, not because
+     * the job never ran.
+     */
+    historyError?: string;
+}
+/**
+ * A short-lived link to one backup's bytes, from `POST /admin/backups/download-url`.
+ *
+ * The URL needs no `Authorization` header — the token in it stands in for one,
+ * for this backup only — so a browser can be sent to it and stream the dump to
+ * disk instead of holding it in the page.
+ */
+export interface BackupDownloadLink {
+    /**
+     * `…/admin/backups/download?key=…&token=…`. The server answers it as a
+     * path on itself; the SDK's `downloadUrl()` answers it absolute, on the
+     * client's own base URL.
+     */
+    url: string;
+    /** The token in {@link url}, on its own. */
+    token: string;
+    /** Seconds until the link stops working (60). */
+    expiresIn: number;
+}
+/** What the backup listing (`GET /admin/backups`) answers. */
+export interface BackupListing {
+    /** Backups at the destination, newest first. */
+    backups: BackupInfo[];
+    /** The kind of destination they were read from. */
+    destinationKind: BackupDestinationKind;
+    /** False when `BACKUP_DESTINATION` is unset. */
+    configured: boolean;
+    /**
+     * The scheduled backup job, or `null` when the deployment registers none.
+     * Absent from a server that predates the field.
+     */
+    schedule?: BackupScheduleStatus | null;
+    /**
+     * True when the destination is a local path and the scheduled backup runs
+     * in another process (the worker of a split deployment). The backups
+     * listed are the ones on this process's disk; the scheduled runs write to
+     * theirs, which is the same directory only when both mount it.
+     */
+    localDiskOfThisProcess?: boolean;
+}

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`.