@rebasepro/types 0.6.1 → 0.8.0

package/dist/types/data_source.d.ts

@@ -39,6 +39,82 @@ export interface DataSourceCapabilities {
  * @group Models
  */
 export type DataSourceFeatures = Omit<DataSourceCapabilities, "key" | "label">;
+/**
+ * The default data-source key, used when a collection does not name a
+ * `dataSource`. Shared by the frontend router and the backend driver
+ * registry so both agree on "the default database".
+ * @group Models
+ */
+export declare const DEFAULT_DATA_SOURCE_KEY = "(default)";
+/**
+ * How the *frontend* reaches a data source.
+ *
+ * - `"server"` — through the Rebase backend (the `RebaseClient`). The backend
+ *   holds the actual database adapter and routes by data-source key. This is
+ *   the default and covers Postgres, MongoDB, and any other server-mediated
+ *   engine.
+ * - `"direct"` — straight from the client to the external backend via its own
+ *   SDK driver (e.g. Firestore). The Rebase backend is not in the data path.
+ * - `"custom"` — a developer-supplied {@link DataDriver}, transport unspecified.
+ *
+ * @group Models
+ */
+export type DataSourceTransport = "server" | "direct" | "custom";
+/**
+ * Declarative definition of a data source — a named place data lives.
+ *
+ * Declared once and shared front and back: the frontend uses it to decide
+ * transport (client vs direct driver), the backend uses the same `key` to
+ * resolve a database adapter, and the editor derives capabilities from
+ * `engine`. Collections reference a definition by its `key` via
+ * `collection.dataSource`.
+ *
+ * @group Models
+ */
+export interface DataSourceDefinition {
+    /**
+     * Unique identifier for this data source. Collections point at it via
+     * `dataSource`. Defaults to {@link DEFAULT_DATA_SOURCE_KEY}.
+     */
+    key: string;
+    /**
+     * The engine backing this data source (e.g. `"postgres"`, `"mongodb"`,
+     * `"firestore"`, or a custom id). Determines the
+     * {@link DataSourceCapabilities} surfaced in the editor.
+     */
+    engine: string;
+    /**
+     * How the frontend reaches this source. Defaults to `"server"`.
+     */
+    transport: DataSourceTransport;
+    /**
+     * The physical database/schema/Firestore-database within the engine.
+     * Threaded to drivers/adapters as the existing `databaseId` runtime
+     * parameter. Defaults to the engine's own default.
+     */
+    databaseId?: string;
+    /** Human-readable label for the UI. */
+    label?: string;
+}
+/**
+ * The resolved data source for a collection: the single source of truth that
+ * the frontend router, backend registry, and editor all derive from.
+ * Produced by `resolveDataSource(collection, registry)`.
+ *
+ * @group Models
+ */
+export interface ResolvedDataSource {
+    /** Data-source key (routing key, shared front + back). */
+    key: string;
+    /** Engine backing the source (drives capabilities). */
+    engine: string;
+    /** Frontend transport. */
+    transport: DataSourceTransport;
+    /** Within-engine instance, if any (the `databaseId` runtime param). */
+    databaseId?: string;
+    /** Capabilities derived from {@link engine}. */
+    capabilities: DataSourceCapabilities;
+}
 /** @group Models */
 export declare const POSTGRES_CAPABILITIES: DataSourceCapabilities;
 /** @group Models */
@@ -52,11 +128,11 @@ export declare const MONGODB_CAPABILITIES: DataSourceCapabilities;
  */
 export declare const DEFAULT_CAPABILITIES: DataSourceCapabilities;
 /**
- * Look up capabilities for a given driver key.
- * If `driver` is undefined or not found, returns `DEFAULT_CAPABILITIES`.
+ * Look up capabilities for a given engine key.
+ * If `engine` is undefined or not found, returns `DEFAULT_CAPABILITIES`.
  * @group Models
  */
-export declare function getDataSourceCapabilities(driver?: string): DataSourceCapabilities;
+export declare function getDataSourceCapabilities(engine?: string): DataSourceCapabilities;
 /**
  * Register custom capabilities for a third-party driver.
  * @group Models

package/dist/types/entity_actions.d.ts

@@ -59,7 +59,7 @@ export interface EntityAction<M extends Record<string, unknown> = Record<string,
 }
 export type EntityActionClickProps<M extends Record<string, unknown>, USER extends User = User> = {
     entity?: Entity<M>;
-    context: RebaseContext<USER>;
+    context?: RebaseContext<USER>;
     path?: string;
     collection?: EntityCollection<M>;
     /**
@@ -78,7 +78,7 @@ export type EntityActionClickProps<M extends Record<string, unknown>, USER exten
     /**
      * If the action is rendered in the form, is it open in a side panel or full screen?
      */
-    openEntityMode: "side_panel" | "full_screen" | "split" | "dialog";
+    openEntityMode?: "side_panel" | "full_screen" | "split" | "dialog";
     /**
      * Optional selection controller, present if the action is being called from a collection view
      */

package/dist/types/entity_callbacks.d.ts

@@ -3,14 +3,24 @@ import type { Entity, EntityStatus, EntityValues } from "./entities";
 import type { User } from "../users";
 import type { RebaseCallContext } from "../rebase_context";
 /**
- * This interface defines all the callbacks that can be used when an entity
- * is being created, updated or deleted.
- * Useful for adding your own logic or blocking the execution of the operation.
+ * Lifecycle callbacks for entity CRUD operations.
+ *
+ * Register per-collection on the collection's `callbacks` field, or globally
+ * via `initBackend({ callbacks })`. Fires on **every** data path — REST API,
+ * WebSocket / realtime subscriptions, and server-side `rebase.data`.
+ *
+ * When both global and per-collection callbacks are registered, execution
+ * order is: **global → collection → property callbacks**.
+ *
  * @group Models
  */
 export type EntityCallbacks<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User> = {
     /**
-     * Callback used after fetching data
+     * Callback used after fetching data.
+     *
+     * Fires on every read path. Use this for security-critical redaction
+     * (PII masking, row filtering) — no read path bypasses it.
+     *
      * @param props
      */
     afterRead?(props: EntityAfterReadProps<M, USER>): Promise<Entity<M>> | Entity<M>;
@@ -19,11 +29,13 @@ export type EntityCallbacks<M extends Record<string, unknown> = Record<string, u
      * saved. If you throw an error in this method the process stops, and an
      * error snackbar gets displayed.
      * This runs after schema validation.
+     *
      * @param props
      */
     beforeSave?(props: EntityBeforeSaveProps<M, USER>): Promise<Partial<EntityValues<M>>> | Partial<EntityValues<M>>;
     /**
-     * Callback used when save is successful
+     * Callback used when save is successful.
+     *
      * @param props
      */
     afterSave?(props: EntityAfterSaveProps<M, USER>): Promise<void> | void;
@@ -45,7 +57,7 @@ export type EntityCallbacks<M extends Record<string, unknown> = Record<string, u
      *
      * @param props
      */
-    afterDelete?(props: EntityAfterDeleteProps<M, USER>): void;
+    afterDelete?(props: EntityAfterDeleteProps<M, USER>): Promise<void> | void;
 };
 /**
  * Parameters passed to hooks when an entity is fetched

package/dist/types/entity_views.d.ts

@@ -43,7 +43,7 @@ export interface FormContext<M extends Record<string, unknown> = Record<string,
     status: "new" | "existing" | "copy";
     entity?: Entity<M>;
     savingError?: Error;
-    openEntityMode: "side_panel" | "full_screen" | "split" | "dialog";
+    openEntityMode?: "side_panel" | "full_screen" | "split" | "dialog";
     /**
      * The underlying formex controller that powers the form.
      */

package/dist/types/filter-operators.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Canonical filter operators and REST wire-format mappings.
+ *
+ * `WhereFilterOp` is THE operator type used at every layer — from React
+ * components through the SDK, server, and down to the database driver.
+ *
+ * PostgREST short-codes (`eq`, `gt`, `cs`, …) exist **only** at the
+ * HTTP wire boundary, handled by `serializeFilter` / `deserializeFilter`
+ * in `@rebasepro/common`.
+ *
+ * ┌──────────────────┬───────────────┬──────────────────────────┐
+ * │ Canonical        │ REST short    │ Meaning                  │
+ * ├──────────────────┼───────────────┼──────────────────────────┤
+ * │ "=="             │ "eq"          │ Equal                    │
+ * │ "!="             │ "neq"         │ Not equal                │
+ * │ ">"              │ "gt"          │ Greater than             │
+ * │ ">="             │ "gte"         │ Greater than or equal    │
+ * │ "<"              │ "lt"          │ Less than                │
+ * │ "<="             │ "lte"         │ Less than or equal       │
+ * │ "in"             │ "in"          │ Value in list            │
+ * │ "not-in"         │ "nin"         │ Value not in list        │
+ * │ "array-contains" │ "cs"          │ Array contains element   │
+ * │ "array-contains-any" │ "csa"     │ Array contains any of    │
+ * └──────────────────┴───────────────┴──────────────────────────┘
+ *
+ * @module
+ */
+/**
+ * Canonical filter operators supported across all database backends.
+ * Each DB driver translates these to its native query format.
+ *
+ * @group Models
+ */
+export type WhereFilterOp = "<" | "<=" | "==" | "!=" | ">=" | ">" | "array-contains" | "in" | "not-in" | "array-contains-any";
+/**
+ * Used to define filters applied in collections.
+ *
+ * A single condition is a tuple `[operator, value]`.
+ * Multiple conditions on the same field use an array of tuples.
+ *
+ * @example
+ * // Single condition per field
+ * { status: ["==", "active"], price: [">=", 9.99] }
+ *
+ * // Multiple conditions on one field
+ * { age: [[">=", 18], ["<", 65]] }
+ *
+ * // Array operators
+ * { role: ["in", ["admin", "editor"]] }
+ * { tags: ["array-contains", "featured"] }
+ *
+ * @group Models
+ */
+export type FilterValues<Key extends string> = Partial<Record<Key, [WhereFilterOp, unknown] | [WhereFilterOp, unknown][]>>;
+/**
+ * Relaxed filter type that also accepts pre-serialized PostgREST strings.
+ * **Internal only** — used at the wire-format boundary
+ * (`serializeFilter` / `deserializeFilter` in `@rebasepro/common`).
+ *
+ * Application code, UI components, and SDK consumers should use
+ * {@link FilterValues} instead.
+ *
+ * @internal
+ */
+export type WireFilterValues<Key extends string> = Partial<Record<Key, [WhereFilterOp, unknown] | [WhereFilterOp, unknown][] | string>>;
+/**
+ * A pre-defined filter preset for quick access in the collection toolbar.
+ * Users can select a preset to instantly apply a set of filters and
+ * optionally a sort order.
+ *
+ * @group Models
+ */
+export interface FilterPreset<Key extends string = string> {
+    /**
+     * Display label shown in the preset menu.
+     * If omitted, a summary is auto-generated from the filter keys.
+     */
+    label?: string;
+    /**
+     * The filter values to apply when this preset is selected.
+     */
+    filterValues: FilterValues<Key>;
+    /**
+     * Optional sort override to apply alongside the filter values.
+     */
+    sort?: [Key, "asc" | "desc"];
+}
+/**
+ * PostgREST short-code operators. Wire format only — these never appear
+ * in application code. Used by `serializeFilter`/`deserializeFilter`
+ * in `@rebasepro/common`.
+ */
+export type RestFilterOp = "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "in" | "nin" | "cs" | "csa";
+/** Maps canonical operators to their REST short-code equivalents. */
+export declare const CANONICAL_TO_REST: Readonly<Record<WhereFilterOp, RestFilterOp>>;
+/** Maps REST short-code operators to their canonical equivalents. */
+export declare const REST_TO_CANONICAL: Readonly<Record<RestFilterOp, WhereFilterOp>>;
+/**
+ * Resolve any operator string (canonical or REST short-code) to its
+ * canonical `WhereFilterOp` form. Returns `undefined` for unknown operators.
+ *
+ * @example
+ * toCanonicalOp("==")   // "=="
+ * toCanonicalOp("eq")   // "=="
+ * toCanonicalOp("cs")   // "array-contains"
+ * toCanonicalOp("xyz")  // undefined
+ */
+export declare function toCanonicalOp(op: string): WhereFilterOp | undefined;

package/dist/types/index.d.ts

@@ -1,13 +1,14 @@
 export * from "./entities";
+export * from "./filter-operators";
 export * from "./chips";
 export * from "./properties";
 export * from "./collections";
 export * from "./relations";
+export * from "./policy";
 export * from "./locales";
 export * from "./entity_link_builder";
 export * from "./user_management_delegate";
 export * from "./entity_callbacks";
-export * from "./entity_overrides";
 export * from "./export_import";
 export * from "./modify_collections";
 export * from "./formex";
@@ -21,10 +22,11 @@ export * from "./entity_actions";
 export * from "./property_config";
 export * from "./entity_views";
 export * from "./data_source";
+export * from "./storage_source";
 export * from "./cron";
-export * from "./backend_hooks";
 export * from "./component_ref";
 export * from "./auth_adapter";
 export * from "./database_adapter";
 export * from "./breadcrumbs";
 export * from "./component_overrides";
+export * from "./api_keys";

package/dist/types/plugins.d.ts

@@ -245,7 +245,7 @@ export interface PluginFormActionProps<USER extends User = User, EC extends Enti
     disabled: boolean;
     formContext?: FormContext;
     context: RebaseContext<USER>;
-    openEntityMode: "side_panel" | "full_screen" | "split" | "dialog";
+    openEntityMode?: "side_panel" | "full_screen" | "split" | "dialog";
 }
 /**
  * Parameters passed to the field builder wrap function.

package/dist/types/policy.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Structured, engine-agnostic policy expressions.
+ *
+ * A {@link PolicyExpression} is the single source of truth for a row-level
+ * security condition. It is compiled to Postgres `USING`/`WITH CHECK` SQL
+ * (authoritative enforcement) and independently evaluated in JavaScript (to
+ * drive the admin UI, and — in future — to enforce on engines without native
+ * RLS such as MongoDB). Because both the SQL and the JS decision derive from
+ * the *same* expression, the UI matches database enforcement by construction —
+ * no drift between two hand-written implementations.
+ *
+ * The only escape hatch that cannot be evaluated client-side is the
+ * {@link RawPolicyExpression} node (`{ kind: "raw" }`): it preserves full
+ * PostgreSQL power but, being arbitrary SQL, is treated as *unknown* by the
+ * JavaScript evaluator (never silently allowed) and reflected exactly in the UI
+ * via server-computed capability flags.
+ *
+ * @group Models
+ */
+export type PolicyExpression = TruePolicyExpression | FalsePolicyExpression | AndPolicyExpression | OrPolicyExpression | NotPolicyExpression | ComparePolicyExpression | RolesOverlapPolicyExpression | RolesContainPolicyExpression | AuthenticatedPolicyExpression | RawPolicyExpression;
+/** Always allows. Compiles to `true`. @group Models */
+export interface TruePolicyExpression {
+    kind: "true";
+}
+/** Always denies. Compiles to `false`. @group Models */
+export interface FalsePolicyExpression {
+    kind: "false";
+}
+/** Logical AND — every operand must pass. @group Models */
+export interface AndPolicyExpression {
+    kind: "and";
+    operands: PolicyExpression[];
+}
+/** Logical OR — at least one operand must pass. @group Models */
+export interface OrPolicyExpression {
+    kind: "or";
+    operands: PolicyExpression[];
+}
+/** Logical negation. @group Models */
+export interface NotPolicyExpression {
+    kind: "not";
+    operand: PolicyExpression;
+}
+/** Comparison operators available to {@link ComparePolicyExpression}. @group Models */
+export type PolicyCompareOperator = "eq" | "neq" | "lt" | "lte" | "gt" | "gte";
+/**
+ * Compares two operands, e.g. `owner_id = auth.uid()`.
+ * @group Models
+ */
+export interface ComparePolicyExpression {
+    kind: "compare";
+    op: PolicyCompareOperator;
+    left: PolicyOperand;
+    right: PolicyOperand;
+}
+/**
+ * True when the user holds *at least one* of the given application roles.
+ * Compiles to `string_to_array(auth.roles(), ',') && ARRAY[...]`.
+ * @group Models
+ */
+export interface RolesOverlapPolicyExpression {
+    kind: "rolesOverlap";
+    roles: string[];
+}
+/**
+ * True when the user holds *all* of the given application roles.
+ * Compiles to `string_to_array(auth.roles(), ',') @> ARRAY[...]`.
+ * @group Models
+ */
+export interface RolesContainPolicyExpression {
+    kind: "rolesContain";
+    roles: string[];
+}
+/**
+ * True when there is an authenticated user (`auth.uid() IS NOT NULL`).
+ * @group Models
+ */
+export interface AuthenticatedPolicyExpression {
+    kind: "authenticated";
+}
+/**
+ * A raw PostgreSQL boolean expression — the full-power escape hatch.
+ *
+ * Columns can be referenced as `{column_name}`. This is Postgres-only and
+ * **server-authoritative**: the JavaScript evaluator cannot evaluate arbitrary
+ * SQL, so it treats this node as *unknown* rather than guessing.
+ * @group Models
+ */
+export interface RawPolicyExpression {
+    kind: "raw";
+    sql: string;
+}
+/**
+ * An operand referenced by a {@link ComparePolicyExpression}.
+ * @group Models
+ */
+export type PolicyOperand = FieldPolicyOperand | LiteralPolicyOperand | AuthUidPolicyOperand | AuthRolesPolicyOperand;
+/** A column value on the row being evaluated. @group Models */
+export interface FieldPolicyOperand {
+    kind: "field";
+    /** The property/column name (resolved to its DB column when compiled). */
+    name: string;
+}
+/** A constant value. @group Models */
+export interface LiteralPolicyOperand {
+    kind: "literal";
+    value: string | number | boolean | null;
+}
+/** The current user's id — compiles to `auth.uid()`. @group Models */
+export interface AuthUidPolicyOperand {
+    kind: "authUid";
+}
+/**
+ * The current user's roles as an array — compiles to
+ * `string_to_array(auth.roles(), ',')`.
+ * @group Models
+ */
+export interface AuthRolesPolicyOperand {
+    kind: "authRoles";
+}
+/** @group Models */
+export declare const policy: {
+    true: () => TruePolicyExpression;
+    false: () => FalsePolicyExpression;
+    and: (...operands: PolicyExpression[]) => AndPolicyExpression;
+    or: (...operands: PolicyExpression[]) => OrPolicyExpression;
+    not: (operand: PolicyExpression) => NotPolicyExpression;
+    compare: (left: PolicyOperand, op: PolicyCompareOperator, right: PolicyOperand) => ComparePolicyExpression;
+    rolesOverlap: (roles: string[]) => RolesOverlapPolicyExpression;
+    rolesContain: (roles: string[]) => RolesContainPolicyExpression;
+    authenticated: () => AuthenticatedPolicyExpression;
+    raw: (sql: string) => RawPolicyExpression;
+    field: (name: string) => FieldPolicyOperand;
+    literal: (value: string | number | boolean | null) => LiteralPolicyOperand;
+    authUid: () => AuthUidPolicyOperand;
+    authRoles: () => AuthRolesPolicyOperand;
+};