@rebasepro/types 0.23.0 → 0.24.0

package/dist/types/admin_block.d.ts

@@ -49,7 +49,7 @@ export type AdminCollectionKey = typeof ADMIN_COLLECTION_KEYS[number];
  *
  * @group Models
  */
-export declare const ADMIN_PROPERTY_KEYS: readonly ["canAddElements", "clearable", "columnWidth", "customProps", "disabled", "expanded", "Field", "Filter", "filterOperators", "fixedFilter", "format", "hideFromCollection", "includeEntityLink", "includeId", "markdown", "minimalistView", "multiline", "Preview", "previewAsTag", "previewProperties", "readOnly", "renderInForm", "sortable", "span", "spreadChildren", "urlPreview", "widget"];
+export declare const ADMIN_PROPERTY_KEYS: readonly ["canAddElements", "clearable", "columnWidth", "customProps", "disabled", "expanded", "Field", "filledByServer", "Filter", "filterOperators", "fixedFilter", "format", "hideFromCollection", "includeEntityLink", "includeId", "markdown", "minimalistView", "multiline", "Preview", "previewAsTag", "previewProperties", "readOnly", "renderInForm", "sortable", "span", "spreadChildren", "urlPreview", "widget"];
 /** A key of a property's `admin` block. @group Models */
 export type AdminPropertyKey = typeof ADMIN_PROPERTY_KEYS[number];
 /**

package/dist/types/api_keys.d.ts

@@ -1,49 +1,52 @@
 /**
- * Service API keys — machine-to-machine authentication for scripts, cron jobs
- * and third-party integrations.
+ * API keys — long-lived bearer credentials for scripts, CI, agents and
+ * third-party integrations.
  *
- * The wire contract lives here because all three sides need it and used to
- * declare it separately: `@rebasepro/server` implements the routes,
- * `@rebasepro/client` calls them, and {@link ApiKeysAPI} types the SDK surface.
- * The client's copy had already drifted — it never gained `admin`.
+ * The wire contract lives here because all three sides need it:
+ * `@rebasepro/server` implements the routes, `@rebasepro/client` calls them,
+ * and {@link ApiKeysAPI} types the SDK surface. The database row itself
+ * (which carries `key_hash`) stays in the server package: nothing off the
+ * server may see it.
  *
- * The database row itself (`ApiKey`, which carries `key_hash`) stays in the
- * server package: nothing off the server may see it.
+ * What a key may do is a list of scopes — see `scopes.ts`.
  */
+import type { ScopeSummary } from "./scopes.js";
 /**
- * A single permission entry scoping an API key to a collection and set of
- * operations.
+ * Who a key acts as.
  *
- * Use `"*"` as the collection value to grant access to all collections (and all
- * custom functions). Custom functions are addressed with the `functions`
- * namespace: `"functions"` grants every function, `"functions/<name>"` grants a
- * single one.
+ * - `"service"` — the project's own machine identity, `api-key:<id>`. It is no
+ *   person: it runs as the RLS roles it was given (`service` always, plus any
+ *   in {@link ApiKeyMasked.roles}). Managed by holders of `keys:write`.
+ * - `"personal"` — its owner. It runs as the owner's account, with the owner's
+ *   roles as they are *now*, and can never hold a scope the owner does not.
+ *   Managed by the owner, when the app enables `auth.personalKeys`.
  *
  * @group Models
  */
-export interface ApiKeyPermission {
-    /** Collection slug, `"functions"`/`"functions/<name>"`, or `"*"` for everything. */
-    collection: string;
-    /** Allowed operations on the collection. */
-    operations: ("read" | "write" | "delete")[];
-}
+export type ApiKeyKind = "service" | "personal";
 /**
- * An API key with the secret portion masked — what list / get / update return.
+ * An API key with the secret masked — what list / get / update return.
  * @group Models
  */
 export interface ApiKeyMasked {
     id: string;
     name: string;
+    kind: ApiKeyKind;
     /** First 12 characters of the plaintext key, for display only. */
     key_prefix: string;
-    permissions: ApiKeyPermission[];
     /**
-     * When true, the key is granted the `admin` role: it passes the admin-gated
-     * routes (users, roles, cron, backups, logs, API keys) and the RLS
-     * `default_admin` policies. Non-admin keys carry only the `service` role —
-     * RLS grants them nothing unless a collection policy names that role.
+     * What the key may do, as `resource:action[:target]` scope strings —
+     * `data:read:posts`, `functions:invoke`, `logs:read`.
+     */
+    scopes: string[];
+    /**
+     * The RLS roles a service key runs as, beside `service`. `["admin"]` reads
+     * every row through the default admin policies. Always empty on a personal
+     * key, which runs as its owner's live roles.
      */
-    admin: boolean;
+    roles: string[];
+    /** The account a personal key acts as. Null on a service key. */
+    owner_uid: string | null;
     /**
      * Requests per 15-minute window. `null` means "no per-key override" — the
      * data rate limiter then applies its default API-key limit (1000/window
@@ -67,32 +70,44 @@ export interface ApiKeyWithSecret extends ApiKeyMasked {
     key: string;
 }
 /**
- * Payload for creating a new API key.
+ * Payload for creating a service key.
  * @group Models
  */
 export interface CreateApiKeyRequest {
     name: string;
-    permissions: ApiKeyPermission[];
-    /** When true, grants the `admin` role. See {@link ApiKeyMasked.admin}. */
-    admin?: boolean;
+    /** At least one. `keys:*` is refused, and so is any scope the creator does not hold. */
+    scopes: string[];
+    /** RLS roles beside `service`. A creator may only give roles they hold, unless they are an admin. */
+    roles?: string[];
     /** Requests per 15-minute window. Omit or `null` for the server default. */
     rate_limit?: number | null;
     /** ISO-8601 expiration timestamp. Omit for no expiration. */
     expires_at?: string | null;
 }
 /**
- * Payload for updating an existing API key. Only the fields provided change.
+ * Payload for updating a service key. Only the fields provided change.
  * @group Models
  */
 export interface UpdateApiKeyRequest {
     name?: string;
-    permissions?: ApiKeyPermission[];
-    /** When true, grants the `admin` role. See {@link ApiKeyMasked.admin}. */
-    admin?: boolean;
+    scopes?: string[];
+    roles?: string[];
     rate_limit?: number | null;
     expires_at?: string | null;
 }
-/** @group Models */
+/**
+ * Payload for creating a personal key. It acts as the caller, so it carries no
+ * roles and no rate-limit override.
+ * @group Models
+ */
+export interface CreatePersonalKeyRequest {
+    name: string;
+    /** At least one, and none the caller does not hold. `keys:*` is refused. */
+    scopes: string[];
+    /** ISO-8601 expiration timestamp. Omit for no expiration. */
+    expires_at?: string | null;
+}
+/** The project's service keys. Requires `keys:read` / `keys:write`. @group Models */
 export interface ApiKeysAPI {
     listKeys(): Promise<{
         keys: ApiKeyMasked[];
@@ -110,3 +125,20 @@ export interface ApiKeysAPI {
         success: boolean;
     }>;
 }
+/** The signed-in person's own keys, when the app enables them. @group Models */
+export interface PersonalKeysAPI {
+    listKeys(): Promise<{
+        keys: ApiKeyMasked[];
+    }>;
+    createKey(data: CreatePersonalKeyRequest): Promise<{
+        key: ApiKeyWithSecret;
+    }>;
+    revokeKey(id: string): Promise<{
+        success: boolean;
+    }>;
+    /** Every scope the backend knows, described, and the ones the caller holds. */
+    listScopes(): Promise<{
+        scopes: ScopeSummary[];
+        held: string[];
+    }>;
+}

package/dist/types/auth_adapter.d.ts

@@ -53,6 +53,18 @@ export interface MountableRouter {
     /** The routes the sub-app declares. Only its presence is contractual. */
     routes: readonly unknown[];
 }
+/**
+ * The request header that asks for a data-plane request to run as another
+ * user, named by uid.
+ *
+ * The server honours it only on a signed-in administrator's own session —
+ * never on an API key or the service key — and only through an adapter that
+ * implements {@link AuthAdapter.resolveUser}. Everywhere else a request that
+ * carries it is refused, never run as its caller.
+ *
+ * @group Auth
+ */
+export declare const IMPERSONATE_HEADER = "x-rebase-impersonate";
 /**
  * The normalized user object returned by `AuthAdapter.verifyRequest()`.
  *
@@ -72,7 +84,11 @@ export interface AuthenticatedUser {
     photoUrl?: string | null;
     /** Role identifiers the user holds. */
     roles: string[];
-    /** Whether the user has admin privileges. */
+    /**
+     * Whether `roles` includes `admin`. Informational — every authorization
+     * decision reads `roles` and the scopes they hold, so an adapter that
+     * wants a user treated as an administrator gives them the `admin` role.
+     */
     isAdmin: boolean;
     /**
      * Whether this session is a GUEST — anonymous sign-in rather than an
@@ -90,6 +106,12 @@ export interface AuthenticatedUser {
     rawToken?: string;
     /** Extra claims/metadata from the auth provider. */
     claims?: Record<string, unknown>;
+    /**
+     * What this credential may do, when it is narrower than its person — set
+     * for an API key. Absent means everything the user's roles hold
+     * (`scopesForRoles`).
+     */
+    scopes?: string[];
 }
 /**
  * Feature flags advertised by an auth adapter.
@@ -171,6 +193,26 @@ export interface AuthAdapterCapabilities {
      */
     needsSetup?: boolean;
 }
+/**
+ * What `GET /api/auth/config` answers: the auth adapter's capabilities, plus
+ * the optional features of the backend around it.
+ *
+ * The admin panel reads this document before anything else, so it is where
+ * the panel learns that a feature is off, without first asking for that
+ * feature and getting a refusal.
+ *
+ * @group Auth
+ */
+export interface AuthConfigDocument extends AuthAdapterCapabilities {
+    /**
+     * Whether this backend serves file storage. When it is `false`, no storage
+     * backend is configured: `GET /storage/sources` lists nothing and every
+     * other `/storage` route answers 501 `STORAGE_NOT_CONFIGURED`. Absent from
+     * a backend that predates the field, so a client must ask
+     * `GET /storage/sources` there.
+     */
+    storage?: boolean;
+}
 /**
  * Options for paginated user listing.
  * @group Auth
@@ -217,6 +259,11 @@ export interface AuthCreateUserData {
     displayName?: string;
     photoUrl?: string;
     metadata?: Record<string, unknown>;
+    /**
+     * Store the address as verified: whoever creates the account named it
+     * (an operator, an administrator), so nobody needs to prove it.
+     */
+    emailVerified?: boolean;
 }
 /**
  * User management operations for the admin panel.
@@ -390,6 +437,23 @@ export interface AuthAdapter {
      * @returns The authenticated user, or `null` if the token is invalid.
      */
     verifyToken?(token: string): Promise<AuthenticatedUser | null>;
+    /**
+     * The identity a verified request from this account would carry right
+     * now, with no credential involved: its uid, its roles as they are now,
+     * its guest flag, and the custom claims a token minted for it now would
+     * hold. `null` when no active account has this uid — none at all, or one
+     * that is disabled.
+     *
+     * This is what lets an administrator run a request as another user (the
+     * {@link IMPERSONATE_HEADER} header). The server calls it only after it
+     * has decided the caller may do that, and it calls it for the caller too,
+     * so the decision rests on the caller's roles as they are now rather than
+     * on the ones their token claims.
+     *
+     * Optional. An adapter without it cannot be impersonated through, and a
+     * request carrying the header is refused rather than run as its caller.
+     */
+    resolveUser?(uid: string): Promise<AuthenticatedUser | null>;
     /**
      * User CRUD for the admin panel's user management UI.
      * Optional — if not provided, user management UI is hidden.

package/dist/types/backend.d.ts

@@ -246,6 +246,12 @@ 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;
 }
 /**
  * Abstract realtime provider interface.
@@ -293,6 +299,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 +366,97 @@ 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. */
+    rowCount?: number;
+    /** 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;
+}
 /**
  * Administrative operations for SQL-based databases (PostgreSQL, MySQL, etc.).
  * Used by the SQL Editor, RLS Editor, and schema browser.
@@ -363,6 +479,22 @@ export interface SQLAdmin {
         params?: unknown[];
         isolateSession?: boolean;
     }): 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.
+     */
+    runSqlScript?(sql: string, options?: {
+        database?: string;
+        role?: string;
+    }): Promise<SqlScriptResult>;
     /**
      * Fetch the available databases on the server.
      */
@@ -433,6 +565,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 +736,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 +754,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 +792,13 @@ 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;
 }
 /**
  * A `BackendBootstrapper` encapsulates all driver-specific initialization logic.
@@ -832,7 +1005,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 +1041,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,86 @@ 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;
+}
+/** 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;
+}