@rebasepro/types 0.25.0 → 0.26.0

package/dist/types/api_keys.d.ts

@@ -24,6 +24,26 @@ import type { ScopeSummary } from "./scopes.js";
  * @group Models
  */
 export type ApiKeyKind = "service" | "personal";
+/**
+ * The API key a request authenticated with, as server-side code sees it:
+ * `context.credential` in a collection callback, and `credential` on the
+ * identity the request's driver is scoped to.
+ *
+ * It tells a write made with a key from the same person's own session. A
+ * personal key acts as its owner, so `context.user` is the owner either way;
+ * this is what says "the CI token did it" rather than "Ada did it". Never the
+ * secret: only what the key list shows.
+ *
+ * @group Models
+ */
+export interface CallerCredential {
+    /** `"personal"` acts as its owner (`context.user`); `"service"` as the key itself. */
+    kind: ApiKeyKind;
+    /** The key's id, as `GET /api/auth/keys` lists it. */
+    id: string;
+    /** The name the key was given when it was created. */
+    name: string;
+}
 /**
  * An API key with the secret masked — what list / get / update return.
  * @group Models

package/dist/types/auth_adapter.d.ts

@@ -65,6 +65,89 @@ export interface MountableRouter {
  * @group Auth
  */
 export declare const IMPERSONATE_HEADER = "x-rebase-impersonate";
+/**
+ * The request header that asks for a data-plane request to run as a role —
+ * the RLS simulator's "view as". Alone it runs as a signed-in holder of that
+ * role who owns no rows; with {@link SIMULATE_USER_ID_HEADER} it runs as that
+ * uid holding that role, whether or not such an account exists.
+ *
+ * `anon` (or `anonymous`) runs as a caller with no session at all.
+ *
+ * Like {@link IMPERSONATE_HEADER}, only a signed-in administrator's own session
+ * may send it; anyone else is refused with 403, never answered as themselves.
+ *
+ * @group Auth
+ */
+export declare const SIMULATE_ROLE_HEADER = "x-rebase-simulate-role";
+/**
+ * The uid a simulated request runs as. With {@link SIMULATE_ROLE_HEADER} it is
+ * a hypothetical — "u_1 holding customer" — and need not name an account;
+ * without it, the uid must be an active user and runs with their roles now.
+ *
+ * @group Auth
+ */
+export declare const SIMULATE_USER_ID_HEADER = "x-rebase-simulate-user-id";
+/**
+ * The id of a service API key a simulated request runs as: the key's identity,
+ * its RLS roles and its scopes, exactly as a request presenting the key would.
+ * Excludes the other two simulation headers.
+ *
+ * @group Auth
+ */
+export declare const SIMULATE_API_KEY_ID_HEADER = "x-rebase-simulate-api-key-id";
+/**
+ * The response header naming what a simulated request ran as:
+ * `role=<role>;sub=<uid>;masked_columns=<a,b>`, plus `api_key=<id>` and
+ * `collection=<slug>` when they apply. Every value is URI-encoded. Read it
+ * with {@link parseSimulatedContext}.
+ *
+ * @group Auth
+ */
+export declare const SIMULATED_CONTEXT_HEADER = "x-rebase-simulated-context";
+/**
+ * What an administrator asks a request to run as. Exactly one of these
+ * shapes is honoured: a role (optionally with a uid), a uid alone (an existing
+ * user, with their roles), or an API key id alone.
+ *
+ * @group Auth
+ */
+export interface AccessSimulation {
+    role?: string;
+    userId?: string;
+    apiKeyId?: string;
+}
+/**
+ * The request headers for an {@link AccessSimulation}. Empty when it asks for
+ * nothing, so spreading it into a header set is always safe.
+ *
+ * @group Auth
+ */
+export declare function simulationHeaders(simulation: AccessSimulation | null | undefined): Record<string, string>;
+/**
+ * What {@link SIMULATED_CONTEXT_HEADER} says a request ran as.
+ *
+ * @group Auth
+ */
+export interface SimulatedContext {
+    role: string;
+    sub: string;
+    maskedColumns: string[];
+    apiKeyId?: string;
+    collection?: string;
+}
+/**
+ * Write a {@link SimulatedContext} as the header value.
+ *
+ * @group Auth
+ */
+export declare function formatSimulatedContext(context: SimulatedContext): string;
+/**
+ * Read {@link SIMULATED_CONTEXT_HEADER}. `undefined` for an absent header or one
+ * missing `role` or `sub`.
+ *
+ * @group Auth
+ */
+export declare function parseSimulatedContext(value: string | null | undefined): SimulatedContext | undefined;
 /**
  * The normalized user object returned by `AuthAdapter.verifyRequest()`.
  *

package/dist/types/backend.d.ts

@@ -7,6 +7,7 @@ import type { HistoryConfig } from "../controllers/client.js";
 import type { ChannelBusSetting } from "./channel_bus.js";
 import type { SchemaEditingAdmin } from "./schema_editing.js";
 import type { AccessModel } from "./scopes.js";
+import type { ApiKeyKind } from "./api_keys.js";
 /**
  * Abstract database connection interface.
  * Represents a connection to any database system.
@@ -353,6 +354,14 @@ export interface RealtimeProvider {
      * still look live, so it is reported rather than inferred.
      */
     health?(): RealtimeListenerHealth[];
+    /**
+     * Run the provider's own background reads — the refetches a change
+     * schedules, whatever announced it (a write here, change capture, another
+     * instance) — through `run`. The server passes one that enters the backend
+     * owning this provider, so a hook such a read reaches sees that backend as
+     * `rebase`. Without it they run in the context of whatever scheduled them.
+     */
+    setScopeRunner?(run: <T>(fn: () => T) => T): void;
 }
 /**
  * One long-lived realtime connection, as `/health` reports it.
@@ -697,6 +706,13 @@ export interface BranchInfo {
     createdAt: Date;
     /** Size in bytes, if available from the server. */
     sizeBytes?: number;
+    /**
+     * The transaction that created the branch database, recorded when it was
+     * made: the fork point a branch diff tells the two sides' writes apart by.
+     * Absent for a branch made before it was recorded, or by a server that
+     * does not record it.
+     */
+    forkXid?: string;
 }
 /**
  * Administrative operations for database branching.
@@ -715,6 +731,250 @@ export interface BranchAdmin {
     listBranches(): Promise<BranchInfo[]>;
     /** Get info about a specific branch. */
     getBranchInfo(name: string): Promise<BranchInfo | undefined>;
+    /**
+     * What the branch changed, against the database it was made from: its
+     * tables, columns, constraints, indexes, triggers, row-level-security
+     * policies, enum types, views and functions, and per table the rows it
+     * inserted, updated and deleted. Reads only.
+     */
+    diffBranch?(name: string, options?: BranchDiffOptions): Promise<BranchDiff>;
+    /**
+     * Apply the rows the branch changed to the database it was made from. See
+     * {@link BranchMergeOptions} for what wins, and when nothing is written.
+     */
+    mergeBranch?(name: string, options: BranchMergeOptions): Promise<BranchMergeResult>;
+}
+/**
+ * What {@link BranchAdmin.diffBranch} compares.
+ * @group Admin
+ */
+export interface BranchDiffOptions {
+    /** Rows shown per table, across every kind of change. Default 100, at most 1,000. */
+    sampleLimit?: number;
+    /** Schemas to compare. Default: every schema but the system's, without Rebase's own tables. */
+    schemas?: string[];
+    /**
+     * Rows a table may hold, on either side, for its rows to be matched one by
+     * one. A larger table that differs is reported with its row counts only,
+     * and cannot be merged. Default 100,000.
+     */
+    maxRowsPerTable?: number;
+}
+/**
+ * One change to the schema: a table, a column, a policy, a table's row-level
+ * security, a constraint (unique, foreign key, check, exclusion), an index, a
+ * trigger — or, outside any table, an enum type, a view or a function.
+ * @group Admin
+ */
+export interface BranchSchemaChange {
+    object: "table" | "column" | "policy" | "rls" | "constraint" | "index" | "trigger" | "enum" | "view" | "function";
+    change: "added" | "dropped" | "altered";
+    schema: string;
+    /**
+     * The table the change is on — or, for an enum, a view or a function, the
+     * object's own name (a function's with its argument types).
+     */
+    table: string;
+    /** The column's, policy's, constraint's, index's or trigger's name. */
+    name?: string;
+    /** The definition on the target, as SQL. Absent for an addition. */
+    before?: string;
+    /** The definition on the branch, as SQL. Absent for a drop. */
+    after?: string;
+}
+/**
+ * Why the changed rows of a table cannot be merged.
+ * @group Admin
+ */
+export interface BranchMergeBlock {
+    /**
+     * `TABLE_REWRITTEN`: one side wrote every row anew since the branch was
+     * made (a column type change, a volatile default, `VACUUM FULL`), so which
+     * side changed which row can no longer be told.
+     */
+    code: "TABLE_ADDED" | "TABLE_DROPPED" | "COLUMNS_DIFFER" | "PRIMARY_KEY_DIFFERS" | "NO_PRIMARY_KEY" | "TOO_LARGE" | "TABLE_REWRITTEN";
+    message: string;
+}
+/**
+ * One row the branch changed, or one both sides changed.
+ *
+ * Values are the text the database writes for them, `null` for SQL NULL, so a
+ * `bigint` or a `numeric` reads exactly as it is stored — except a column named
+ * like a credential (`password_hash`, `*_token`, `*secret*`, `*_hash`), whose
+ * value reads `"[redacted]"`. It is still listed in {@link changedColumns}.
+ *
+ * A `"conflict"` with no {@link after} is a row the branch deleted that rows
+ * the target wrote since the branch was made still reference — see
+ * {@link BranchTableDataDiff.referencedBy}.
+ * @group Admin
+ */
+export interface BranchRowChange {
+    change: "inserted" | "updated" | "deleted" | "conflict";
+    /** The primary key, as a JSON array of its columns' values. */
+    key: string;
+    /** The row on the target. Absent for an insert. */
+    before?: Record<string, string | null>;
+    /** The row on the branch. Absent for a delete. */
+    after?: Record<string, string | null>;
+    /** The columns whose values differ, for an update or a conflict. */
+    changedColumns?: string[];
+}
+/**
+ * The rows of one table that differ between the branch and its target.
+ * @group Admin
+ */
+export interface BranchTableDataDiff {
+    schema: string;
+    table: string;
+    /** The collection whose table this is, when the server knows one. */
+    collection?: string;
+    primaryKey: string[];
+    /** Rows the branch inserted. */
+    inserted: number;
+    /** Rows the branch updated. */
+    updated: number;
+    /** Rows the branch deleted. */
+    deleted: number;
+    /**
+     * Rows both sides changed since the branch was made, differently — and
+     * rows the branch deleted that rows the target wrote since still
+     * reference through a foreign key ({@link referencedBy}). Deleting one of
+     * those on the target would cascade into, or rewrite, the target's own
+     * rows, so it is a conflict {@link BranchMergeOptions.onConflict} decides.
+     */
+    conflicts: number;
+    /**
+     * Rows the target changed since the branch was made, and the branch did
+     * not. A merge leaves them as they are.
+     */
+    targetChanges: number;
+    /** Up to {@link BranchDiffOptions.sampleLimit} of the rows counted above, but not of {@link targetChanges}. */
+    samples: BranchRowChange[];
+    /** Present when this table's rows cannot be merged. A merge refuses it unless told to skip it. */
+    blocked?: BranchMergeBlock;
+    /**
+     * Rows on each side, for a table whose rows were not matched one by one.
+     * Its inserted, updated, deleted and conflict counts are then 0 because
+     * they are unknown, not because nothing changed.
+     */
+    rowCounts?: {
+        target: number;
+        branch: number;
+    };
+    /**
+     * The foreign keys through which rows the target wrote since the branch
+     * was made reference rows of this table the branch deleted. Each such
+     * delete is counted in {@link conflicts}.
+     */
+    referencedBy?: BranchReferencingRows[];
+}
+/**
+ * Rows of one table, written on the target since the branch was made, that
+ * reference rows the branch deleted.
+ * @group Admin
+ */
+export interface BranchReferencingRows {
+    schema: string;
+    table: string;
+    /** The foreign key's name. */
+    constraint: string;
+    /** What deleting the referenced row does to them on the target. */
+    onDelete: "cascade" | "set null" | "set default" | "restrict" | "no action";
+    /** How many of them there are. */
+    rows: number;
+}
+/**
+ * What {@link BranchAdmin.diffBranch} returns.
+ * @group Admin
+ */
+export interface BranchDiff {
+    branch: string;
+    /** The branch's database. */
+    branchDatabase: string;
+    /** The database the branch was made from, which a merge writes to. */
+    targetDatabase: string;
+    /** The schemas compared. */
+    schemas: string[];
+    /**
+     * Whether rows could be told apart by which side changed them since the
+     * branch was made. When `false`, every row that differs is counted as the
+     * branch's change, and a merge would undo what the target changed.
+     */
+    forkPointKnown: boolean;
+    /** Pass to {@link BranchAdmin.mergeBranch}: what this diff saw, on both sides. */
+    fingerprint: string;
+    schema: BranchSchemaChange[];
+    /** Only the tables with rows that differ. */
+    data: BranchTableDataDiff[];
+    sampleLimit: number;
+    computedAt: string;
+}
+/**
+ * How {@link BranchAdmin.mergeBranch} applies a branch.
+ *
+ * A merge writes the rows the branch inserted, updated and deleted to the
+ * target, in one statement: all of them, or none. Rows the target changed
+ * since the branch was made are kept. Schema and policy changes are never
+ * merged — they belong to the collections and their migrations.
+ *
+ * Nothing is written when either side changed since the diff that produced
+ * {@link expectedFingerprint}, when a table with changed rows cannot be merged
+ * (unless {@link skipBlocked}), or when a row was changed on both sides and
+ * {@link onConflict} is `"abort"`.
+ * @group Admin
+ */
+export interface BranchMergeOptions {
+    /** {@link BranchDiff.fingerprint} of the diff that was reviewed. */
+    expectedFingerprint: string;
+    /**
+     * A row both sides changed: `"abort"` (the default) writes nothing,
+     * `"branch"` writes the branch's row over the target's, `"target"` keeps
+     * the target's.
+     *
+     * A row the branch deleted that the target's newer rows reference
+     * ({@link BranchTableDataDiff.referencedBy}) is a conflict too: `"target"`
+     * keeps it, and with it the rows that reference it; `"branch"` deletes it,
+     * and the foreign key's `ON DELETE` reaches those rows — the result's
+     * `warnings` say which.
+     */
+    onConflict?: "abort" | "branch" | "target";
+    /** Merge the other tables when some cannot be merged, instead of writing nothing. */
+    skipBlocked?: boolean;
+    /** The schemas the reviewed diff compared, when it was not the default. */
+    schemas?: string[];
+    /** The row limit the reviewed diff used, when it was not the default. */
+    maxRowsPerTable?: number;
+}
+/**
+ * What {@link BranchAdmin.mergeBranch} wrote.
+ * @group Admin
+ */
+export interface BranchMergeResult {
+    branch: string;
+    targetDatabase: string;
+    tables: {
+        schema: string;
+        table: string;
+        inserted: number;
+        updated: number;
+        deleted: number;
+    }[];
+    /** Tables left unmerged because they could not be, with `skipBlocked`. */
+    skipped: {
+        schema: string;
+        table: string;
+        reason: BranchMergeBlock;
+    }[];
+    /** Rows both sides changed that kept the target's version, with `onConflict: "target"`. */
+    conflictsKept: number;
+    /** Schema and policy changes on the branch, none of which a merge applies. */
+    schemaChangesNotMerged: number;
+    /**
+     * What the merge did beyond the rows it counts, or what went wrong after
+     * they were written: a delete whose foreign keys reached the target's own
+     * rows (with `onConflict: "branch"`), a sequence left behind them.
+     */
+    warnings: string[];
 }
 /**
  * Union type for all admin capabilities.
@@ -890,10 +1150,16 @@ export interface RealtimeSocketOptions {
         uid: string;
         roles: string[];
         scopes: string[];
-        /** The key itself: its id and `rate_limit` decide which rate-limit bucket its frames count in. */
+        /**
+         * The key itself: its id and `rate_limit` decide which rate-limit
+         * bucket its frames count in. With `name` and `kind`, collection
+         * callbacks on its write frames read it as `context.credential`.
+         */
         apiKey?: {
             id: string;
             rate_limit: number | null;
+            name?: string;
+            kind?: ApiKeyKind;
         };
     } | {
         message: string;
@@ -960,6 +1226,14 @@ export interface RealtimeSocketOptions {
      * answered `404` and closed, so the client is not left hanging.
      */
     path?: string;
+    /**
+     * Run `fn` on behalf of the backend that owns this socket: each connection
+     * and each frame is handled inside it, so a hook a frame reaches sees that
+     * backend as `rebase`, as it does over REST. The server passes its own.
+     * Absent, frames run in the context the HTTP connection was accepted in —
+     * the process default's.
+     */
+    runInScope?: <T>(fn: () => T) => T;
 }
 /**
  * A `BackendBootstrapper` encapsulates all driver-specific initialization logic.

package/dist/types/properties.d.ts

@@ -392,9 +392,9 @@ export interface BaseProperty<CustomProps = unknown> {
      * Give the expression, in the template form `isId` takes
      * (``databaseDefault: "sql`gen_random_uuid()`"``), and the schema planner
      * writes it as the column's `DEFAULT`, so `rebase db push` keeps it. `true`
-     * declares a DEFAULT someone else wrote and the planner does not write
-     * one, so a push plans dropping it. "Import from table" and
-     * `rebase schema introspect` set the expression they read.
+     * declares a DEFAULT someone else wrote: the planner writes none, and
+     * `rebase db push` leaves the one the database holds as it is. "Import
+     * from table" and `rebase schema introspect` set the expression they read.
      */
     databaseDefault?: boolean | SqlExpression;
     /**

package/dist/types/relations.d.ts

@@ -314,9 +314,11 @@ export interface ViaRelation extends RelationBase {
      * The joins, in order, from this collection's table to the target's.
      *
      * Each step names a table and the columns to join it on; the last step's
-     * table is the target. Read-only, because Rebase will not work out how to
-     * write through an arbitrary chain, and guessing is what this kind exists to
-     * stop.
+     * table is the target. A single-hop chain is writable through a create or
+     * update — to-one in one step (the target holds the key), to-many through
+     * one junction table — and a longer one is read-only, because Rebase will
+     * not work out how to write through an arbitrary chain, and guessing is
+     * what this kind exists to stop.
      */
     joinPath: JoinStep[];
 }
@@ -379,8 +381,12 @@ export interface ResolvedRelationBase {
      */
     cardinality: "one" | "many";
     /**
-     * Whether Rebase knows how to write through this link. False only for
-     * {@link ResolvedVia}, whose join chain it will not invent a write for.
+     * Whether Rebase writes this link through a create or update. True for
+     * every kind but a multi-hop {@link ResolvedVia}: a `via` is writable when
+     * it has a single link to set — a to-one chain of one step (the target
+     * holds the key) or a to-many chain through one junction table — and
+     * read-only otherwise, since Rebase will not invent a write for a longer
+     * chain.
      */
     writable: boolean;
     /**
@@ -463,7 +469,12 @@ export interface ResolvedManyToMany extends ResolvedRelationBase {
 /** @group Models */
 export interface ResolvedVia extends ResolvedRelationBase {
     kind: "via";
-    writable: false;
+    /**
+     * True for a single-hop chain — to-one through one step, or to-many through
+     * one junction table — and false for anything longer. See
+     * {@link ResolvedRelationBase.writable}.
+     */
+    writable: boolean;
     /** The chain as authored — see {@link ViaRelation.joinPath}. Nothing to default. */
     joinPath: JoinStep[];
 }

package/dist/types/scopes.d.ts

@@ -164,6 +164,20 @@ export declare function isDataPlaneScope(scope: string): scope is DataPlaneScope
 export declare function isAdminScope(scope: string): scope is AdminScope;
 /** Does this list of roles include the built-in `admin` role? @group Auth */
 export declare function hasAdminRole(roles: readonly string[] | null | undefined): boolean;
+/**
+ * Why `name` cannot be written as a role, or `undefined` when it can.
+ *
+ * No naming pattern is imposed — an app may call its roles anything. What is
+ * refused is a name that would be read back as *other* roles: a role travels as
+ * one element of a Postgres `text[]` and as one entry of the comma-joined
+ * `app.user_roles` setting that RLS policies split with
+ * `string_to_array(…, ',')`. Written as `"support,admin"`, a role comes back as
+ * `admin`; braces, quotes and backslashes are array-literal syntax, so they are
+ * refused too, as are empty names and control characters.
+ *
+ * @group Auth
+ */
+export declare function roleNameProblem(name: unknown): string | undefined;
 /**
  * Does a set of held scopes grant `scope`, optionally on one `target`?
  *

package/dist/users/user.d.ts

@@ -1,3 +1,4 @@
+import type { CallerCredential } from "../types/api_keys.js";
 /**
  * The canonical representation of an authenticated user in the Rebase ecosystem.
  *
@@ -86,5 +87,12 @@ export type User = {
      * anonymous request.
      */
     readonly claims?: Record<string, unknown>;
+    /**
+     * The API key this request authenticated with, when it was one. Set
+     * server-side on the identity a request's driver is scoped to, and read by
+     * collection callbacks as `context.credential`. Absent for a session, a
+     * service-key request and in the browser.
+     */
+    readonly credential?: CallerCredential;
     getIdToken?: (forceRefresh?: boolean) => Promise<string>;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rebasepro/types",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "description": "Rebase type definitions — shared interfaces and controller types",
   "keywords": [
     "rebase",
@@ -79,9 +79,6 @@
       "node"
     ],
     "testEnvironment": "node",
-    "testPathIgnorePatterns": [
-      "/bivariance/"
-    ],
     "moduleNameMapper": {
       "\\.(css|less)$": "<rootDir>/test/__mocks__/styleMock.js"
     }