@rebasepro/types 0.11.1-canary.gfd39654 → 0.12.0

package/dist/types/admin_block.d.ts

@@ -32,3 +32,23 @@
 export declare const ADMIN_COLLECTION_KEYS: readonly ["Actions", "additionalFields", "alwaysApplyDefaultValues", "components", "defaultEntityAction", "defaultFilter", "defaultSelectedView", "defaultSize", "defaultViewMode", "disableDefaultActions", "enabledViews", "entityActions", "entityViews", "exportable", "filterPresets", "fixedFilter", "formAutoSave", "formView", "group", "hideFromNavigation", "hideIdFromCollection", "hideIdFromForm", "icon", "includeJsonView", "inlineEditing", "kanban", "listProperties", "localChangesBackup", "openEntityMode", "orderProperty", "pagination", "previewProperties", "propertiesOrder", "selectionController", "selectionEnabled", "sideDialogWidth", "sort", "titleProperty"];
 /** A key of a collection's `admin` block. @group Models */
 export type AdminCollectionKey = typeof ADMIN_COLLECTION_KEYS[number];
+/**
+ * Every key that belongs inside a *property's* `admin` block, as data.
+ *
+ * The union of `AdminPropertyOptions` and its per-type extensions
+ * (`AdminStringOptions`, `AdminArrayOptions`, …) in `@rebasepro/admin-types`.
+ * It lives here for the same reason {@link ADMIN_COLLECTION_KEYS} does: the
+ * runtime consumers are core packages that the BaaS guard forbids from
+ * importing `@rebasepro/admin-types`. Here it is the boot-time collection
+ * validator in `@rebasepro/server`, which has to tell "you left `readOnly` at
+ * the top of the property, where nothing reads it" apart from "you invented a
+ * key we have never heard of".
+ *
+ * `@rebasepro/admin-types` re-exports this and asserts it names only real
+ * option keys.
+ *
+ * @group Models
+ */
+export declare const ADMIN_PROPERTY_KEYS: readonly ["canAddElements", "clearable", "columnWidth", "customProps", "disabled", "expanded", "Field", "Filter", "filterOperators", "fixedFilter", "hideFromCollection", "includeEntityLink", "includeId", "markdown", "minimalistView", "multiline", "Preview", "previewAsTag", "previewProperties", "readOnly", "sortable", "spreadChildren", "urlPreview", "widget", "widthPercentage"];
+/** 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,15 +1,54 @@
-/** A single permission entry scoping an API key to a collection and its allowed operations. */
+/**
+ * Service API keys — machine-to-machine authentication for scripts, cron jobs
+ * 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 database row itself (`ApiKey`, which carries `key_hash`) stays in the
+ * server package: nothing off the server may see it.
+ */
+/**
+ * A single permission entry scoping an API key to a collection and set of
+ * operations.
+ *
+ * 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.
+ *
+ * @group Models
+ */
 export interface ApiKeyPermission {
+    /** Collection slug, `"functions"`/`"functions/<name>"`, or `"*"` for everything. */
     collection: string;
+    /** Allowed operations on the collection. */
     operations: ("read" | "write" | "delete")[];
 }
-/** An API key with the secret portion masked (returned by list / get / update). */
+/**
+ * An API key with the secret portion masked — what list / get / update return.
+ * @group Models
+ */
 export interface ApiKeyMasked {
     id: string;
     name: string;
+    /** 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.
+     */
     admin: boolean;
+    /**
+     * Requests per 15-minute window. `null` means "no per-key override" — the
+     * data rate limiter then applies its default API-key limit (1000/window
+     * unless configured otherwise), not unlimited.
+     */
     rate_limit: number | null;
     created_by: string;
     created_at: string;
@@ -18,26 +57,42 @@ export interface ApiKeyMasked {
     expires_at: string | null;
     revoked_at: string | null;
 }
-/** An API key including the full secret (returned only on creation). */
+/**
+ * Returned exactly once, when a key is created. The `key` field holds the full
+ * plaintext key — it is never stored or returned again.
+ * @group Models
+ */
 export interface ApiKeyWithSecret extends ApiKeyMasked {
+    /** Full plaintext API key (e.g. `rk_live_abc123...`). */
     key: string;
 }
-/** Payload for creating a new API key. */
+/**
+ * Payload for creating a new API key.
+ * @group Models
+ */
 export interface CreateApiKeyRequest {
     name: string;
     permissions: ApiKeyPermission[];
+    /** When true, grants the `admin` role. See {@link ApiKeyMasked.admin}. */
     admin?: boolean;
+    /** 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. */
+/**
+ * Payload for updating an existing API 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;
     rate_limit?: number | null;
     expires_at?: string | null;
 }
+/** @group Models */
 export interface ApiKeysAPI {
     listKeys(): Promise<{
         keys: ApiKeyMasked[];

package/dist/types/collections.d.ts

@@ -90,23 +90,26 @@ export interface BaseCollectionConfig<M extends Record<string, unknown> = Record
      */
     auth?: boolean | AuthCollectionConfig;
     /**
-     * Opt out of the framework's default Row Level Security policies.
-     *
-     * The schema generator automatically injects, for every collection, a
-     * baseline SELECT policy granting the trusted server context and the
-     * `admin` role read access (reads run under a restricted role, so RLS
-     * default-denies without it). For auth collections it additionally injects
-     * a self-read policy (`id = auth.uid()`) and an admin-only write gate
-     * (INSERT/UPDATE/DELETE require the `admin` role or the trusted server
-     * context), making privileged columns such as `roles` safe by default.
+     * Row-level authorization rules for this collection.
      *
-     * Author-defined `securityRules` are permissive and broaden access on top
-     * of these defaults. Set this flag to `true` to remove the defaults
-     * entirely and take full responsibility for the collection's RLS.
+     * Driver-agnostic on purpose, unlike `disableDefaultPolicies`, `table` and
+     * `relations`, which are declared on {@link PostgresCollectionConfig} only.
+     * The rules are a *contract* — who may read or write which rows — and each
+     * engine enforces it its own way:
      *
-     * @default false
+     * - **Postgres** compiles them to real `CREATE POLICY` statements and lets
+     *   the database enforce them (see {@link PostgresCollectionConfig.securityRules},
+     *   which narrows this with the raw-SQL details).
+     * - **MongoDB** translates them into a query filter it AND-s into every
+     *   read and write, honouring `access`, `ownerField`, `roles`, `mode` and
+     *   the `operation`/`operations` selectors, and making a best effort at raw
+     *   `using`/`withCheck` SQL.
+     * - **Firestore** does not implement them at all; its own rules language is
+     *   evaluated by Google, not from here. `supportsRLS` on
+     *   {@link DataSourceCapabilities} reports which engines generate policies,
+     *   which is not the same question as whether an engine honours a rule.
      */
-    disableDefaultPolicies?: boolean;
+    securityRules?: readonly SecurityRule[];
     /**
      * This interface defines all the callbacks that can be used when a entity
      * is being created, updated or deleted.
@@ -140,23 +143,6 @@ export interface BaseCollectionConfig<M extends Record<string, unknown> = Record
      * quietly worked. The second case is the reason for the escape hatch.
      */
     strictWrites?: boolean;
-    /**
-     * The database table name for this collection.
-     * Automatically set for PostgreSQL collections.
-     * For non-SQL backends, this may be undefined.
-     */
-    table?: string;
-    /**
-     * Relations defined for this collection.
-     * Populated at normalization time from inline relation properties
-     * or explicit relation definitions.
-     */
-    relations?: Relation[];
-    /**
-     * Security rules for this collection (Row Level Security).
-     * When defined, the backend enforces access control policies.
-     */
-    securityRules?: readonly SecurityRule[];
 }
 /**
  * A collection backed by PostgreSQL (or any SQL database).
@@ -205,6 +191,24 @@ export interface PostgresCollectionConfig<M extends Record<string, unknown> = Re
      * - `auth.jwt()`   — full JWT claims as JSONB
      */
     securityRules?: readonly SecurityRule[];
+    /**
+     * Opt out of the framework's default Row Level Security policies.
+     *
+     * The schema generator automatically injects, for every collection, a
+     * baseline SELECT policy granting the trusted server context and the
+     * `admin` role read access (reads run under a restricted role, so RLS
+     * default-denies without it). For auth collections it additionally injects
+     * a self-read policy (`id = auth.uid()`) and an admin-only write gate
+     * (INSERT/UPDATE/DELETE require the `admin` role or the trusted server
+     * context), making privileged columns such as `roles` safe by default.
+     *
+     * Author-defined `securityRules` are permissive and broaden access on top
+     * of these defaults. Set this flag to `true` to remove the defaults
+     * entirely and take full responsibility for the collection's RLS.
+     *
+     * @default false
+     */
+    disableDefaultPolicies?: boolean;
 }
 /**
  * A collection backed by Firebase / Firestore.
@@ -329,6 +333,27 @@ export type AnyCollectionConfig = CollectionConfig<any, any>;
  * @group Models
  */
 export declare function isPostgresCollectionConfig<C extends CollectionConfig<any, any>>(collection: C): collection is C & PostgresCollectionConfig<any, any>;
+/**
+ * Narrows to the SQL collection fields — `table`, `relations`,
+ * `disableDefaultPolicies` — by asking the engine's declared capabilities
+ * rather than by naming Postgres.
+ *
+ * The two halves of this already existed and were never joined. The engine
+ * split (`PostgresCollectionConfig` / `FirebaseCollectionConfig` /
+ * `MongoDBCollectionConfig`) said which fields belong to which engine at the
+ * type level; {@link DataSourceCapabilities} said the same thing at runtime,
+ * down to a `supportsRelations` flag. So call sites guarded on the capability
+ * and then read a field the base type had to declare for them — which is why
+ * those fields were on the base, and why a MongoDB collection could be written
+ * with a `table`.
+ *
+ * Prefer this over {@link isPostgresCollectionConfig} wherever the question is
+ * "does this collection live in a SQL table", so a custom SQL engine
+ * registered through `registerDataSourceCapabilities` is included.
+ *
+ * @group Models
+ */
+export declare function isRelationalCollectionConfig<C extends CollectionConfig<any, any>>(collection: C): collection is C & PostgresCollectionConfig<any, any>;
 /**
  * Type guard for Firebase / Firestore collections.
  * @group Models

package/dist/types/data_source.d.ts

@@ -3,7 +3,7 @@ import { WhereFilterOp } from "./filter-operators";
  * Describes the capabilities and features supported by a data source (driver).
  *
  * Each driver (Postgres, Firebase, MongoDB, etc.) declares which features it
- * supports. The CMS uses this descriptor to:
+ * supports. The admin uses this descriptor to:
  * - Show/hide editor tabs (e.g. Relations for SQL, Subcollections for Firebase)
  * - Filter the property type picker (e.g. `relation` for SQL, `reference` for Firebase)
  * - Toggle driver-specific form controls (e.g. `columnType` for SQL)
@@ -27,6 +27,16 @@ export interface DataSourceCapabilities {
     supportsColumnTypes: boolean;
     /** Does this source support real-time listeners? */
     supportsRealtime: boolean;
+    /**
+     * Does this source store vectors natively?
+     *
+     * `VectorProperty` carries a `dimensions` and is pgvector-shaped. It was
+     * the one driver-specific property kind with no flag to gate it, so unlike
+     * every other field in this descriptor there was not even a runtime answer
+     * to appeal to — a Firestore collection could declare an embedding column
+     * and no driver would do anything with it.
+     */
+    supportsVectors: boolean;
     /**
      * Canonical filter operators this engine can execute.
      *
@@ -37,6 +47,27 @@ export interface DataSourceCapabilities {
      * would throw at query time.
      */
     filterOperators: readonly WhereFilterOp[];
+    /**
+     * Relation kinds this engine's driver can compile into a filter.
+     *
+     * Only `belongsTo` puts a column on the row being filtered; the others are
+     * answered with a correlated subquery over the junction or the target
+     * table, which not every driver can build. An engine with no relations at
+     * all declares none.
+     *
+     * The admin uses this to decide whether a relation column offers a filter
+     * control. Offering one an engine cannot answer is not cosmetic: a driver
+     * that drops the key it cannot resolve *widens* the read to every row, and
+     * one that fails closed answers a control the admin itself put on screen
+     * with a 400.
+     *
+     * Optional, so a third-party driver registered before this existed still
+     * compiles. Omitted means {@link DEFAULT_FILTERABLE_RELATION_KINDS} — the
+     * one kind that is a plain column comparison, which every relational
+     * driver can do. The subquery kinds are a real capability and have to be
+     * claimed rather than assumed: assuming them wrongly is the widening.
+     */
+    filterableRelationKinds?: readonly string[];
     /** Does this source support SQL admin operations (SQL editor, EXPLAIN, etc.)? */
     supportsSQLAdmin: boolean;
     /** Does this source support document admin operations (aggregation, stats)? */
@@ -128,6 +159,16 @@ export interface ResolvedDataSource {
     /** Capabilities derived from {@link engine}. */
     capabilities: DataSourceCapabilities;
 }
+/**
+ * Relation kinds assumed filterable when a driver does not say.
+ *
+ * `belongsTo` alone: its filter is a comparison on a column of the row being
+ * filtered, the one shape that needs no query construction a driver might not
+ * have. Everything else is a correlated subquery over another table.
+ *
+ * @group Models
+ */
+export declare const DEFAULT_FILTERABLE_RELATION_KINDS: readonly string[];
 /** @group Models */
 export declare const POSTGRES_CAPABILITIES: DataSourceCapabilities;
 /** @group Models */

package/dist/types/database_adapter.d.ts

@@ -93,17 +93,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/dist/types/entity_callbacks.d.ts

@@ -69,7 +69,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;
@@ -106,7 +106,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/dist/types/history.d.ts

@@ -0,0 +1,62 @@
+/**
+ * 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/dist/types/index.d.ts

@@ -19,6 +19,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/dist/types/postgres_introspection.d.ts

@@ -0,0 +1,95 @@
+/**
+ * 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";
+}