@rebasepro/types 0.11.1-canary.gfd39654 → 0.12.0

package/src/types/database_adapter.ts

@@ -119,17 +119,22 @@ export interface DatabaseAdapterInitConfig {
     /** The shared collection registry to register into. */
     collectionRegistry: CollectionRegistryInterface;
     /**
-     * How the server is being run — see `RebaseBackendConfig.mode`.
+     * Whether this driver should describe its own schema.
      *
-     * In `"baas"` mode `collections` is empty by design: a driver that can
-     * describe its own schema should introspect the database and report the
-     * collections it found back on `InitializedDriver.collections`. Drivers
-     * that cannot introspect may ignore this.
+     * True when the project declared no collections, so there is nothing to
+     * serve unless the driver reads the live database and reports what it found
+     * on `InitializedDriver.collections`. Drivers that cannot introspect may
+     * ignore it — `initializeRebaseBackend` fails the boot with their name
+     * rather than serving nothing.
+     *
+     * This was a `mode: "cms" | "baas"` flag, which was never independent of
+     * `collections`: every consumer already required the list to be empty
+     * before acting on it, so the flag could only ever agree or contradict.
      */
-    mode?: "cms" | "baas";
+    introspectCollections?: boolean;
     /**
-     * `baas`-mode options — see `RebaseBackendConfig.baas`. Drivers that
-     * introspect should honour `unprotectedTables`.
+     * Options for an introspecting driver — see `RebaseBackendConfig.baas`.
+     * Drivers that introspect should honour `unprotectedTables`.
      */
     baas?: { unprotectedTables?: "exclude" | "serve" };
 }

package/src/types/entity_callbacks.ts

@@ -85,7 +85,7 @@ export interface AfterReadProps<M extends Record<string, unknown> = Record<strin
     collection: CollectionConfig<M>;
 
     /**
-     * Full path of the CMS where this collection is being fetched.
+     * Full path of the admin where this collection is being fetched.
      * Might contain unresolved aliases.
      */
     path: string;
@@ -132,7 +132,7 @@ export interface AfterSaveProps<M extends Record<string, unknown> = Record<strin
     collection: CollectionConfig<M>;
 
     /**
-     * Full path of the CMS where this entity is being saved.
+     * Full path of the admin where this entity is being saved.
      * Might contain unresolved aliases.
      */
     path: string;

package/src/types/history.ts

@@ -0,0 +1,66 @@
+/**
+ * Entity change history — the shape a history entry has on the wire.
+ *
+ * This was declared three times: once in `@rebasepro/server-postgres`, once in
+ * `@rebasepro/server-mongo`, and once again in the admin's `useHistory` hook.
+ * The two driver copies disagreed on the one field that matters for a consumer,
+ * `updated_at`, which was a `string` in Postgres and a `Date` in MongoDB — so
+ * nothing could read history without first choosing a driver.
+ *
+ * The contract is the wire shape, and on the wire it is an ISO-8601 string.
+ * A driver whose stored document differs (MongoDB keeps a `Date` and an
+ * `ObjectId`) declares that storage row for itself and maps to this on the way
+ * out; it is not the shared type.
+ *
+ * @group Backend
+ */
+
+/**
+ * One recorded change to a row.
+ * @group Backend
+ */
+export interface EntityHistoryEntry {
+    id: string;
+    /** The table (Postgres) or collection (MongoDB) the row belongs to. */
+    table_name: string;
+    /** The row's id, as a string regardless of its native type. */
+    entity_id: string;
+    action: "create" | "update" | "delete";
+    /** Which fields changed. `null` for creates and deletes. */
+    changed_fields: string[] | null;
+    values: Record<string, unknown> | null;
+    previous_values: Record<string, unknown> | null;
+    updated_by: string | null;
+    /** ISO-8601. A driver storing a native date converts on read. */
+    updated_at: string;
+}
+
+/**
+ * Arguments to record one change.
+ * @group Backend
+ */
+export interface RecordHistoryParams {
+    tableName: string;
+    id: string;
+    action: "create" | "update" | "delete";
+    values?: Record<string, unknown> | null;
+    previousValues?: Record<string, unknown> | null;
+    updatedBy?: string | null;
+}
+
+/**
+ * How much history to keep. Pruning runs per row after each write.
+ * @group Backend
+ */
+export interface HistoryRetentionConfig {
+    /** Max entries per row. Oldest pruned first. Default 200. */
+    maxEntries: number;
+    /** Entries older than this many days are pruned. Default 90. */
+    ttlDays: number;
+}
+
+/** @group Backend */
+export interface FetchHistoryOptions {
+    limit?: number;
+    offset?: number;
+}

package/src/types/index.ts

@@ -21,6 +21,8 @@ export * from "./component_ref";
 export * from "./auth_adapter";
 export * from "./database_adapter";
 export * from "./api_keys";
+export * from "./history";
+export * from "./postgres_introspection";
 export * from "./project_manifest";
 export * from "./collection_contract";
 export * from "./schema_version";

package/src/types/postgres_introspection.ts

@@ -0,0 +1,101 @@
+/**
+ * Shapes returned by Postgres introspection queries.
+ *
+ * These are **not** driver-agnostic and they are not a model of anything — each
+ * one is the projection of a specific `SELECT` against `information_schema` or
+ * `pg_policies`, which is why the fields are snake_cased and why `is_nullable`
+ * is a string rather than a boolean. They describe rows, not concepts.
+ *
+ * They were spread across three places that had nothing to do with each other:
+ * the `Table*` shapes sat in `websockets.ts`, next to the WebSocket frame types
+ * they share no relationship with, and `PostgresPolicy` was declared twice — in
+ * `@rebasepro/admin`'s RLS tab and again in `@rebasepro/studio`'s RLS editor,
+ * the second with a comment explaining it was inline "to avoid depending on
+ * @rebasepro/studio". Neither had to: this package is already a dependency of
+ * both.
+ *
+ * Producer: `@rebasepro/server-postgres`. Consumers: the collection editor, the
+ * studio schema browser, the RLS editors.
+ */
+
+/**
+ * A column, as `information_schema.columns` reports it.
+ * @group Models
+ */
+export interface TableColumnInfo {
+    column_name: string;
+    data_type: string;
+    udt_name: string;
+    /** `"YES"` or `"NO"` — `information_schema` reports this as text. */
+    is_nullable: string;
+    column_default: string | null;
+    character_maximum_length: number | null;
+    /** Enum values, populated for USER-DEFINED (enum) columns */
+    enum_values?: string[];
+}
+
+/** @group Models */
+export interface TableForeignKeyInfo {
+    column_name: string;
+    foreign_table_name: string;
+    foreign_column_name: string;
+}
+
+/** @group Models */
+export interface TableJunctionInfo {
+    junction_table_name: string;
+    source_column_name: string;
+    target_table_name: string;
+    target_column_name: string;
+}
+
+/**
+ * A policy as the *table metadata* query projects it.
+ *
+ * Distinct from {@link PostgresPolicy}, which is the RLS editor's fuller
+ * projection of `pg_policies` — this one carries only what the collection
+ * editor needs to show that a table is protected.
+ *
+ * @group Models
+ */
+export interface TablePolicyInfo {
+    policy_name: string;
+    roles: string[];
+    cmd: string;
+    qual?: string;
+    with_check?: string;
+}
+
+/** @group Models */
+export interface TableMetadata {
+    columns: TableColumnInfo[];
+    foreignKeys: TableForeignKeyInfo[];
+    junctions: TableJunctionInfo[];
+    policies: TablePolicyInfo[];
+}
+
+/**
+ * A row of `pg_policies`, as the RLS editors read it.
+ *
+ * Note the unseparated column names (`policyname`, `tablename`) — those are
+ * Postgres's, not ours. See {@link TablePolicyInfo} for the narrower projection
+ * the collection editor uses.
+ *
+ * @group Models
+ */
+export interface PostgresPolicy {
+    policyname: string;
+    tablename: string;
+    permissive: "PERMISSIVE" | "RESTRICTIVE";
+    roles: string[];
+    cmd: "SELECT" | "INSERT" | "UPDATE" | "DELETE" | "ALL";
+    /** The `USING` clause. */
+    qual: string | null;
+    /** The `WITH CHECK` clause. */
+    with_check: string | null;
+    /**
+     * Whether this policy exists in the live database, in the collection's
+     * `securityRules`, or both. Computed by the editor, not by Postgres.
+     */
+    status?: "live" | "code_only" | "both";
+}

package/src/types/project_manifest.ts

@@ -25,30 +25,50 @@
  * project.
  */
 
+import type { StorageSourceDefinition } from "./storage_source";
+
 /**
  * Which kind of thing an app is.
  *
  * - `backend` — the collections/hooks/functions that define the project's API.
  *   Exactly one per *project* (not per repository); the registry enforces it.
- * - `static`  — a pre-built client bundle (SPA, static site) served over CDN.
- * - `admin`   — the Rebase admin panel, either hosted by the platform or built
- *   into this repository.
- * - `mobile`  — a native app. Registration only: it gets client credentials and
- *   configuration, and is never built or hosted here.
- * - `custom`  — an arbitrary container image built from a Dockerfile. The eject
- *   hatch: full control, no managed-runtime guarantees.
+ * - `static`  — a pre-built client bundle (SPA, static site), served from the
+ *   backend process at its declared `path` or from a CDN. The admin panel is
+ *   one of these: it is an app in the user's repository like any other.
+ *
+ * That is the whole list. Ownership of the server process is a property of the
+ * backend app ({@link RebaseBackendAppConfig.runtime}), not an app type.
  */
-export type RebaseAppType = "backend" | "static" | "admin" | "mobile" | "custom";
+export type RebaseAppType = "backend" | "static";
 
 /**
  * The backend app: the project's API surface.
  *
  * Paths are relative to the directory holding `rebase.json`. The defaults match
  * the layout `rebase init` scaffolds, so a stock project may declare simply
- * `{ "type": "backend" }`.
+ * `{ "type": "backend", "runtime": "managed" }`.
  */
 export interface RebaseBackendAppConfig {
     type: "backend";
+    /**
+     * Who owns the process this backend runs in.
+     *
+     * - `managed` — the platform's runtime image boots this project's bundle.
+     *   You supply collections, functions, crons and schema; Rebase supplies the
+     *   server.
+     * - `custom` — this repository builds its own image and entrypoint. The
+     *   escape hatch: full control, no managed-runtime guarantees.
+     *
+     * Independent of *where* it runs. Both run on Rebase Cloud and both
+     * self-host — the destination lives in `.rebase/cloud.json`, not here. See
+     * `docker/docker-compose.selfhost.yml`, which boots a managed bundle on a
+     * developer's own Docker host.
+     *
+     * This is authored rather than inferred on purpose. It is the single most
+     * consequential fact about a deployment, and inferring it is what used to
+     * land projects on the custom runtime without anyone choosing it.
+     */
+    runtime: "managed" | "custom";
     /** Directory of the config package (collections + index). Default `config`. */
     config?: string;
     /** Directory of server functions. Default `backend/functions`. */
@@ -60,23 +80,25 @@ export interface RebaseBackendAppConfig {
      * Default `backend/src/schema.generated.ts`.
      */
     schema?: string;
-    /**
-     * Which collections source the runtime uses.
-     *
-     * - `cms` (default) — collections come from the config package.
-     * - `baas` — collections are introspected from the live database at boot and
-     *   the config package is not required.
-     */
-    mode?: "cms" | "baas";
     /**
      * Module path (relative to `config`) exporting the auth users collection as
      * its default export. Default `collections/users`.
      */
     usersCollection?: string;
+
+    /**
+     * `runtime: "custom"` only. Dockerfile path relative to the repository root.
+     * Default `Dockerfile`.
+     */
+    dockerfile?: string;
+    /** `runtime: "custom"` only. Build context relative to the root. Default `.`. */
+    context?: string;
+    /** `runtime: "custom"` only. Port the container listens on. Default 8080. */
+    port?: number;
 }
 
 /**
- * A static client bundle — SPA or static site — built here and served from CDN.
+ * A static client bundle — SPA or static site — built here and served at `path`.
  */
 export interface RebaseStaticAppConfig {
     type: "static";
@@ -87,64 +109,50 @@ export interface RebaseStaticAppConfig {
     /** Directory of built assets, relative to the repository root. */
     output: string;
     /**
-     * Serve `index.html` for unmatched paths (client-side routing).
+     * Public base path this app is served under. Default `/`.
+     *
+     * Several static apps run in one process, each at its own path — the API at
+     * `/api`, a site at `/`, the admin at `/admin` — which is what keeps a
+     * self-hosted deployment a single container.
+     *
+     * **This is a build-time input, not only a serving concern.** An app mounted
+     * at `/admin` must be *built* for `/admin` (Vite's `base`), or `index.html`
+     * 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.
+     */
+    path?: string;
+    /**
+     * Serve `index.html` for unmatched paths under `path` (client-side routing).
      * Default `true` — the overwhelmingly common case for a client app, and a
      * static *site* generator emits real files for its routes anyway.
      */
     spa?: boolean;
 }
 
-/**
- * The admin panel.
- *
- * `hosted` is the default and means the platform serves it — nothing is built
- * into this repository and nothing ships in the bundle. `bundled` builds it here,
- * which is what a self-hosted or air-gapped deployment wants.
- */
-export interface RebaseAdminAppConfig {
-    type: "admin";
-    mode?: "hosted" | "bundled";
-    /** Only for `bundled`: package directory containing the admin sources. */
-    root?: string;
-    /** Only for `bundled`: build command. */
-    build?: string;
-    /** Only for `bundled`: directory of built assets. */
-    output?: string;
-}
+export type RebaseAppConfig = RebaseBackendAppConfig | RebaseStaticAppConfig;
 
 /**
- * A native app. Registered for credentials and configuration; never built here.
- */
-export interface RebaseMobileAppConfig {
-    type: "mobile";
-    platform: "ios" | "android" | "other";
-}
-
-/**
- * An app built from a Dockerfile into an arbitrary image.
+ * One declared storage source, as authored in `rebase.json`.
  *
- * This is the deliberate escape hatch. A project containing one is not eligible
- * for the managed runtime — the platform cannot make guarantees about an image
- * it did not build — but it still deploys, and nothing else about the project
- * changes.
+ * The key comes from the enclosing record, so this is
+ * {@link StorageSourceDefinition} minus its `key` — the same document the
+ * runtime registry and the frontend router consume, expressed the way a JSON
+ * object naturally expresses "a set of named things".
  */
-export interface RebaseCustomAppConfig {
-    type: "custom";
-    /** Dockerfile path relative to the repository root. */
-    dockerfile?: string;
-    /** Build context relative to the repository root. Default `.`. */
-    context?: string;
-    /** Port the container listens on. Default 8080. */
-    port?: number;
+export interface RebaseStorageSourceConfig {
+    /** Engine backing this source: `local`, `s3`, `gcs`, or a custom id. */
+    engine: string;
+    /**
+     * How the frontend reaches it. Default `server` (proxied through
+     * `/api/storage`). `direct` means a provider SDK talks to the bucket and the
+     * backend is not in the upload path.
+     */
+    transport?: "server" | "direct";
+    /** Human-readable label for the console and the admin UI. */
+    label?: string;
 }
 
-export type RebaseAppConfig =
-    | RebaseBackendAppConfig
-    | RebaseStaticAppConfig
-    | RebaseAdminAppConfig
-    | RebaseMobileAppConfig
-    | RebaseCustomAppConfig;
-
 /**
  * `rebase.json` — the authored project manifest.
  */
@@ -152,13 +160,17 @@ export interface RebaseProjectManifest {
     /** JSON Schema URL, for editor completion. Ignored by the tooling. */
     $schema?: string;
     /**
-     * The runtime **major** this project targets, as a semver range
+     * The runtime contract **major** this project targets, as a semver range
      * (e.g. `^1`, `~1.4`, or an exact `1.4.2` to pin).
      *
      * The platform upgrades patches and minors underneath a project without
      * asking; it never crosses a major. See {@link RUNTIME_CONTRACT_VERSION}.
+     *
+     * Named `rebase` rather than `runtime` so that `runtime` means exactly one
+     * thing — {@link RebaseBackendAppConfig.runtime}, who owns the process. It
+     * reads like `engines` in a `package.json`, which is what it is.
      */
-    runtime: string;
+    rebase: string;
     /**
      * Apps this repository contributes, keyed by app name. The key is the app's
      * identity within the project: it is what `rebase deploy <app>` names, what
@@ -166,6 +178,28 @@ export interface RebaseProjectManifest {
      * not collide with.
      */
     apps: Record<string, RebaseAppConfig>;
+    /**
+     * Storage sources this project uses, keyed by source key.
+     *
+     * **Topology only — never credentials.** Which buckets exist is a property of
+     * the project and belongs in the repository; how to reach each one is a
+     * property of the deployment and lives in the environment, read per source
+     * from `<BASE>__<KEY>` (`S3_BUCKET__MEDIA` for a source keyed `media`). The
+     * default source takes no suffix, so a single-bucket project configured with
+     * plain `S3_BUCKET` keeps working having declared nothing at all.
+     *
+     * Declared here rather than only in the config package because this file is
+     * the one artifact a host can read *before* running a build. That is what
+     * lets a console show "this project wants a `media` bucket, and it has none"
+     * on a project's first deploy, and it is why the managed and custom runtimes
+     * can present the same list — a custom build emits no bundle manifest, so a
+     * declaration that lived only in compiled config would leave every custom
+     * project invisible.
+     *
+     * Omitted entirely means one default source, which is the overwhelmingly
+     * common project and must not be required to say so.
+     */
+    storage?: Record<string, RebaseStorageSourceConfig>;
 }
 
 /**
@@ -212,8 +246,16 @@ export interface ManagedCompatibility {
  * not read. A runtime accepts any bundle whose `bundleFormat` is less than or
  * equal to its own — old bundles keep booting on new runtimes, which is the
  * whole point of separating the artifact from the engine.
+ *
+ * - **1** — `mode: "cms" | "baas" | "static"`, `entry.static` a single directory
+ *   string, `entry.admin` for a bundled admin panel.
+ * - **2** — `kind: "backend" | "static"`, `entry.static` a list of
+ *   {@link RebaseBundleStatic}, `entry.admin` removed. A format-1 runtime reading
+ *   one of these would find no `mode` and an array where it expects a string, so
+ *   the bump is what turns that into a refusal to boot instead of a bundle that
+ *   starts and serves nothing.
  */
-export const BUNDLE_FORMAT_VERSION = 1;
+export const BUNDLE_FORMAT_VERSION = 2;
 
 /**
  * The runtime contract major.
@@ -239,10 +281,25 @@ export interface RebaseBundleEntrypoints {
     schema?: string;
     /** Module exporting the auth users collection (default export). */
     usersCollection?: string;
-    /** Built admin assets, when the admin panel is bundled rather than hosted. */
-    admin?: string;
-    /** Built static assets to serve from the runtime, when not on a CDN. */
-    static?: string;
+    /**
+     * Built static apps to serve from this process, in declaration order.
+     *
+     * A list rather than a single directory because one process serves several
+     * apps at different paths — a site at `/` and the admin at `/admin`. The
+     * runtime mounts them longest-path-first so the `/`-rooted app's catch-all
+     * does not claim its siblings' URLs.
+     */
+    static?: RebaseBundleStatic[];
+}
+
+/** One built static app inside a bundle. */
+export interface RebaseBundleStatic {
+    /** Public base path, e.g. `/` or `/admin`. */
+    path: string;
+    /** Bundle-relative directory holding the built assets. */
+    dir: string;
+    /** Serve `index.html` for unmatched paths under `path`. */
+    spa: boolean;
 }
 
 /**
@@ -287,15 +344,17 @@ export interface RebaseBundleManifest {
     /**
      * What the runtime does with this bundle.
      *
-     * - `cms` — a backend with declared collections; the runtime provisions their
-     *   tables and serves the data API.
-     * - `baas` — a backend that introspects an existing database rather than
-     *   declaring collections.
-     * - `static` — no backend at all: the bundle is a built SPA (`entry.static`),
-     *   and the runtime only serves those assets. No database, no data sources —
-     *   this is how a `static`/`admin` app runs on the same image as the backend.
+     * - `backend` — boot the full server: database, auth and the data API, plus
+     *   any static apps in `entry.static`.
+     * - `static` — no backend at all: serve `entry.static` and nothing else. No
+     *   database, no auth, no data sources. This is how a static app runs on the
+     *   same image as the backend.
+     *
+     * Replaces an earlier `mode: "cms" | "baas" | "static"`. The cms/baas
+     * distinction was never a third kind of thing — it is simply whether
+     * `entry.config` is present, so it is derived rather than declared.
      */
-    mode: "cms" | "baas" | "static";
+    kind: "backend" | "static";
     entry: RebaseBundleEntrypoints;
     /** Collection slugs contained in the bundle, for quick inspection. */
     collections?: string[];
@@ -326,6 +385,17 @@ export interface RebaseBundleManifest {
     storage?: {
         /** Whether the config package exports a `storageAuthorize` hook. */
         authorize: boolean;
+        /**
+         * Every storage source this bundle expects, resolved at build time from
+         * `rebase.json`'s `storage` block merged with any `storageSources` the
+         * config package exports.
+         *
+         * Recorded so the runtime does not have to import user code to learn its
+         * own topology, and so a host can tell — from the artifact alone, before
+         * starting anything — which buckets need configuring. Absent on bundles
+         * built before this field existed, which means one default source.
+         */
+        sources?: StorageSourceDefinition[];
     };
     deps: {
         /** Runtime dependencies of user code, as declared. */
@@ -350,7 +420,6 @@ export interface RebaseProjectContract {
         version: string;
         contract: number;
     };
-    mode: "cms" | "baas";
     /** Full collection definitions, serialized — the input to SDK generation. */
     collections: unknown[];
     /** Collection slugs, for cheap inspection without parsing the definitions. */