@rebasepro/client-postgresql 0.0.1-canary.dbf160a → 0.0.1-canary.e17585f

package/dist/types/src/types/backend_hooks.d.ts

@@ -0,0 +1,187 @@
+import type { AdminUser, AdminRole } from "../controllers/client";
+/**
+ * Context passed to every backend hook.
+ * Provides information about the request that triggered the hook.
+ * @group Backend Hooks
+ */
+export interface BackendHookContext {
+    /** The currently authenticated user making the request (if any) */
+    requestUser?: {
+        userId: string;
+        roles: string[];
+    };
+    /** The HTTP method of the request */
+    method: "GET" | "POST" | "PUT" | "DELETE";
+}
+/**
+ * Hooks for intercepting Admin User data at the API boundary.
+ *
+ * These hooks run on the server after the database operation completes
+ * but before the response is sent to the client.
+ *
+ * @group Backend Hooks
+ */
+export interface UserHooks {
+    /**
+     * Transform a user record after it's read from the database,
+     * before it's returned to the client.
+     *
+     * Return the modified user, or `null` to filter it out entirely
+     * (the user won't appear in listings or individual fetches).
+     */
+    afterRead?(user: AdminUser, context: BackendHookContext): AdminUser | null | Promise<AdminUser | null>;
+    /**
+     * Transform user data before it's written to the database.
+     * Runs on POST (create) and PUT (update).
+     *
+     * Return the (possibly modified) data to proceed with the save.
+     * Throw an error to abort the operation.
+     */
+    beforeSave?(data: {
+        email?: string;
+        displayName?: string;
+        roles?: string[];
+    }, context: BackendHookContext): {
+        email?: string;
+        displayName?: string;
+        roles?: string[];
+    } | Promise<{
+        email?: string;
+        displayName?: string;
+        roles?: string[];
+    }>;
+    /**
+     * Called after a user is successfully created or updated.
+     * Useful for side-effects like sending notifications.
+     */
+    afterSave?(user: AdminUser, context: BackendHookContext): void | Promise<void>;
+    /**
+     * Called before a user is deleted. Throw to prevent deletion.
+     */
+    beforeDelete?(userId: string, context: BackendHookContext): void | Promise<void>;
+    /**
+     * Called after a user is successfully deleted.
+     */
+    afterDelete?(userId: string, context: BackendHookContext): void | Promise<void>;
+}
+/**
+ * Hooks for intercepting Admin Role data at the API boundary.
+ * @group Backend Hooks
+ */
+export interface RoleHooks {
+    /**
+     * Transform a role record after it's read from the database,
+     * before it's returned to the client.
+     *
+     * Return the modified role, or `null` to filter it out entirely.
+     */
+    afterRead?(role: AdminRole, context: BackendHookContext): AdminRole | null | Promise<AdminRole | null>;
+}
+/**
+ * Hooks for intercepting collection entity data at the REST API boundary.
+ *
+ * These run **after** per-collection `EntityCallbacks` (which execute inside
+ * the DataDriver) and provide a single cross-cutting interception point for
+ * ALL collections flowing through the REST API.
+ *
+ * Every callback receives the collection `slug` so you can target specific
+ * collections or apply logic globally.
+ *
+ * @group Backend Hooks
+ */
+export interface DataHooks {
+    /**
+     * Transform an entity after it's read from the database,
+     * before it's returned to the client.
+     *
+     * Runs for both list (GET /:slug) and single (GET /:slug/:id) fetches.
+     * Return the modified entity, or `null` to filter it out.
+     *
+     * @param slug - The collection slug (e.g. "orders", "products")
+     * @param entity - The flattened entity object (id + values merged)
+     * @param context - Request context (authenticated user, HTTP method)
+     */
+    afterRead?(slug: string, entity: Record<string, unknown>, context: BackendHookContext): Record<string, unknown> | null | Promise<Record<string, unknown> | null>;
+    /**
+     * Transform entity values before they are written to the database.
+     * Runs on POST (create) and PUT (update).
+     *
+     * Return the (possibly modified) values. Throw to abort the save.
+     *
+     * @param slug - The collection slug
+     * @param values - The raw request body values
+     * @param entityId - The entity ID (only present on updates)
+     * @param context - Request context
+     */
+    beforeSave?(slug: string, values: Record<string, unknown>, entityId: string | undefined, context: BackendHookContext): Record<string, unknown> | Promise<Record<string, unknown>>;
+    /**
+     * Called after an entity is successfully saved (created or updated).
+     * Useful for side-effects like syncing to external systems.
+     *
+     * @param slug - The collection slug
+     * @param entity - The saved entity (flattened)
+     * @param context - Request context
+     */
+    afterSave?(slug: string, entity: Record<string, unknown>, context: BackendHookContext): void | Promise<void>;
+    /**
+     * Called before an entity is deleted. Throw to prevent deletion.
+     *
+     * @param slug - The collection slug
+     * @param entityId - The entity ID being deleted
+     * @param context - Request context
+     */
+    beforeDelete?(slug: string, entityId: string, context: BackendHookContext): void | Promise<void>;
+    /**
+     * Called after an entity is successfully deleted.
+     *
+     * @param slug - The collection slug
+     * @param entityId - The deleted entity ID
+     * @param context - Request context
+     */
+    afterDelete?(slug: string, entityId: string, context: BackendHookContext): void | Promise<void>;
+}
+/**
+ * Backend-level hooks for intercepting data at the API boundary.
+ *
+ * These hooks run server-side after database operations complete and before
+ * API responses are sent.
+ *
+ * - `users` / `roles` — intercept admin user and role management endpoints
+ * - `data` — intercept ALL collection entity data flowing through the REST API
+ *
+ * `data` hooks complement per-collection `EntityCallbacks`. Entity callbacks
+ * run inside the DataDriver (close to the DB); data hooks run at the HTTP
+ * boundary (close to the client). Use data hooks for cross-cutting concerns
+ * like audit logging, response enrichment, or field masking.
+ *
+ * @example
+ * ```typescript
+ * const hooks: BackendHooks = {
+ *     data: {
+ *         afterRead(slug, entity, ctx) {
+ *             // Mask PII for non-admin users across all collections
+ *             if (!ctx.requestUser?.roles.includes("admin") && entity.email) {
+ *                 return { ...entity, email: "***" };
+ *             }
+ *             return entity;
+ *         }
+ *     },
+ *     users: {
+ *         afterRead(user, ctx) {
+ *             if (user.email.endsWith("@system.internal")) return null;
+ *             return user;
+ *         }
+ *     }
+ * };
+ * ```
+ *
+ * @group Backend Hooks
+ */
+export interface BackendHooks {
+    /** Hooks for intercepting user management data */
+    users?: UserHooks;
+    /** Hooks for intercepting role management data */
+    roles?: RoleHooks;
+    /** Hooks for intercepting ALL collection entity data via the REST API */
+    data?: DataHooks;
+}

package/dist/types/src/types/collections.d.ts

@@ -9,6 +9,7 @@ import type { RebaseContext } from "../rebase_context";
 import type { Relation } from "./relations";
 import type { EntityCustomView } from "./entity_views";
 import type { EntityAction } from "./entity_actions";
+import type { ComponentRef } from "./component_ref";
 /**
  * Base interface containing all driver-agnostic collection properties.
  * Use {@link PostgresCollection} or {@link FirebaseCollection} for
@@ -19,9 +20,8 @@ import type { EntityAction } from "./entity_actions";
  */
 export interface BaseEntityCollection<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User> {
     /**
-     * You can set an alias that will be used internally instead of the `path`.
-     * The `alias` value will be used to determine the URL of the collection,
-     * while `path` will still be used in the driver.
+     * You can set an alias that will be used internally instead of the collection name.
+     * The `slug` value will be used to determine the URL of the collection.
      * Note that you can use this value in reference properties too.
      */
     slug: string;
@@ -87,6 +87,9 @@ export interface BaseEntityCollection<M extends Record<string, unknown> = Record
     icon?: string | React.ReactNode;
     /**
      * Navigation group for this collection.
+     * Collections sharing the same group name will be visually grouped
+     * together in the drawer and home page. If not set, the collection
+     * falls into the default "Views" group.
      */
     group?: string;
     /**
@@ -158,17 +161,35 @@ export interface BaseEntityCollection<M extends Record<string, unknown> = Record
     /**
      * Force a filter in this view. If applied, the rest of the filters will
      * be disabled. Filters applied with this prop cannot be changed.
-     * e.g. `forceFilter: { age: [">", 18] }`
-     * e.g. `forceFilter: { related_user: ["==", new EntityReference("sdc43dsw2", "users")] }`
+     * e.g. `fixedFilter: { age: [">", 18] }`
+     * e.g. `fixedFilter: { related_user: ["==", new EntityReference("sdc43dsw2", "users")] }`
      */
-    readonly forceFilter?: FilterValues<Extract<keyof M, string> | (string & {})>;
+    readonly fixedFilter?: FilterValues<Extract<keyof M, string> | (string & {})>;
     /**
      * Initial filters applied to the collection this collection is related to.
      * Defaults to none. Filters applied with this prop can be changed.
-     * e.g. `filter: { age: [">", 18] }`
-     * e.g. `filter: { related_user: ["==", new EntityReference("sdc43dsw2", "users")] }`
+     * e.g. `defaultFilter: { age: [">", 18] }`
+     * e.g. `defaultFilter: { related_user: ["==", new EntityReference("sdc43dsw2", "users")] }`
      */
-    readonly filter?: FilterValues<Extract<keyof M, string> | (string & {})>;
+    readonly defaultFilter?: FilterValues<Extract<keyof M, string> | (string & {})>;
+    /**
+     * Pre-defined filter presets that appear as quick-access options in the
+     * collection toolbar. Each preset applies a set of filters (and
+     * optionally a sort order) with a single click.
+     *
+     * ```ts
+     * filterPresets: [
+     *   {
+     *     label: "Shipped this month",
+     *     filterValues: {
+     *       status: ["==", "shipped"],
+     *       order_date: [">=", new Date(Date.now() - 30 * 86400000)]
+     *     }
+     *   }
+     * ]
+     * ```
+     */
+    readonly filterPresets?: FilterPreset<Extract<keyof M, string> | (string & {})>[];
     /**
      * Default sort applied to this collection.
      * When setting this prop, entities will have a default order
@@ -302,7 +323,7 @@ export interface BaseEntityCollection<M extends Record<string, unknown> = Record
     /**
      * Builder for the collection actions rendered in the toolbar
      */
-    Actions?: React.ComponentType<any>[];
+    Actions?: ComponentRef<CollectionActionsProps>[];
 }
 /**
  * A collection backed by PostgreSQL (or any SQL database).
@@ -314,6 +335,7 @@ export interface BaseEntityCollection<M extends Record<string, unknown> = Record
  * @group Models
  */
 export interface PostgresCollection<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User> extends BaseEntityCollection<M, USER> {
+    properties: Properties;
     /**
      * The driver for this collection. For Postgres collections this
      * can be omitted (Postgres is the default) or set to `"postgres"`.
@@ -457,7 +479,8 @@ export interface CollectionActionsProps<M extends Record<string, unknown> = Reco
     /**
      * Array of the parent path segments like `['users']`
      */
-    parentCollectionIds: string[];
+    parentCollectionSlugs: string[];
+    parentEntityIds: string[];
     /**
      * The collection configuration
      */
@@ -481,6 +504,21 @@ export interface CollectionActionsProps<M extends Record<string, unknown> = Reco
      * undefined means the count is still loading.
      */
     collectionEntitiesCount?: number;
+    /**
+     * Programmatically open the new-document form for this collection,
+     * optionally pre-populating it with initial field values.
+     * The form opens in the same mode configured for the collection
+     * (side panel, full screen, or split).
+     *
+     * This is the primary hook for workflows that need to create a document
+     * from external data — e.g. fetching content from a URL, importing from
+     * a third-party API, or duplicating from another system.
+     *
+     * @example
+     * // Inside a custom CollectionAction component:
+     * openNewDocument({ title: "Fetched title", body: "..." });
+     */
+    openNewDocument: (defaultValues?: Record<string, unknown>) => void;
 }
 /**
  * Use this controller to retrieve the selected entities or modify them in
@@ -508,6 +546,32 @@ export type WhereFilterOp = "<" | "<=" | "==" | "!=" | ">=" | ">" | "array-conta
  * @group Models
  */
 export type FilterValues<Key extends string> = Partial<Record<Key, [WhereFilterOp, unknown]>>;
+/**
+ * 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"];
+}
+/**
+ * @deprecated Use {@link FilterPreset} instead.
+ */
+export type QuickFilter<Key extends string = string> = FilterPreset<Key>;
 /**
  * Used to indicate valid filter combinations (e.g. created in Firestore)
  * If the user selects a specific filter/sort combination, the CMS checks if it's

package/dist/types/src/types/component_ref.d.ts

@@ -0,0 +1,47 @@
+import type React from "react";
+/**
+ * Internal marker for a lazily-loaded component reference.
+ * Created by the Vite transform plugin when converting string paths
+ * to deferred `import()` calls. Users should NOT create these manually.
+ *
+ * @internal
+ */
+export interface LazyComponentRef<P = unknown> {
+    readonly __rebaseLazy: true;
+    readonly load: () => Promise<{
+        default: React.ComponentType<P>;
+    }>;
+}
+/**
+ * A reference to a React component that can be provided in three forms:
+ *
+ * 1. **String path** (recommended for collection configs):
+ *    ```ts
+ *    Field: "../../frontend/src/components/MyField"
+ *    ```
+ *    The Vite plugin transforms this into a `LazyComponentRef` at build time.
+ *    On the backend, the string stays inert and is never evaluated.
+ *
+ * 2. **Lazy import function**:
+ *    ```ts
+ *    Field: () => import("../../frontend/src/components/MyField")
+ *    ```
+ *    Standard ES dynamic import. Backend never calls the function.
+ *
+ * 3. **Direct component reference** (use only in frontend-only code):
+ *    ```ts
+ *    Field: MyFieldComponent
+ *    ```
+ *    Importing a component at the top level will pull React into the
+ *    backend runtime — only safe in code that the backend never imports.
+ *
+ * @group Types
+ */
+export type ComponentRef<P = unknown> = React.ComponentType<P> | LazyComponentRef<P> | (() => Promise<{
+    default: React.ComponentType<P>;
+}>) | string;
+/**
+ * Type guard: checks if a value is a `LazyComponentRef` produced by the
+ * Vite transform plugin.
+ */
+export declare function isLazyComponentRef<P = unknown>(ref: unknown): ref is LazyComponentRef<P>;

package/dist/types/src/types/cron.d.ts

@@ -1,3 +1,4 @@
+import type { RebaseClient } from "../controllers/client";
 /**
  * Cron Job type definitions for Rebase.
  *
@@ -32,7 +33,6 @@ export interface CronJobDefinition {
      */
     handler: (ctx: CronJobContext) => Promise<unknown> | unknown;
 }
-import type { RebaseClient } from "../controllers/client";
 /**
  * Context passed to each cron handler invocation.
  */

package/dist/types/src/types/database_adapter.d.ts

@@ -0,0 +1,90 @@
+/**
+ * @module DatabaseAdapter
+ *
+ * Pluggable database abstraction for Rebase.
+ *
+ *
+ * A `DatabaseAdapter` focuses purely on data persistence and related concerns (realtime, history).
+ * It does NOT handle authentication — auth is managed separately by an `AuthAdapter`.
+ *
+ * @example
+ * ```ts
+ * import { createPostgresAdapter } from "@rebasepro/server-postgresql";
+ *
+ * initializeRebaseBackend({
+ *   database: createPostgresAdapter({ connection: db, schema }),
+ *   auth: { jwtSecret: "..." },
+ * });
+ * ```
+ *
+ * @group Backend
+ */
+import type { DataDriver } from "../controllers/data_driver";
+import type { EntityCollection } from "./collections";
+import type { CollectionRegistryInterface, DatabaseAdmin, InitializedDriver, RealtimeProvider } from "./backend";
+/**
+ * A `DatabaseAdapter` provides data persistence for Rebase.
+ *
+ * @group Backend
+ */
+export interface DatabaseAdapter {
+    /**
+     * Which database engine this adapter handles.
+     *
+     * @example "postgres", "mysql", "mongodb", "sqlite"
+     */
+    readonly type: string;
+    /**
+     * Create the DataDriver for CRUD operations.
+     *
+     * This is the only **required** method.
+     *
+     * @param config - Coordinator-provided config containing registered
+     *                 collections and the collection registry.
+     */
+    initializeDriver(config: DatabaseAdapterInitConfig): Promise<InitializedDriver>;
+    /**
+     * Create a realtime provider for this database.
+     *
+     * Return `undefined` if the database does not support realtime
+     * change notifications.
+     */
+    initializeRealtime?(driverResult: InitializedDriver): Promise<RealtimeProvider | undefined>;
+    /**
+     * Initialize entity history tracking.
+     *
+     * Return `undefined` if the database does not support history.
+     */
+    initializeHistory?(config: unknown, driverResult: InitializedDriver): Promise<{
+        historyService: unknown;
+    } | undefined>;
+    /**
+     * Initialize WebSocket server for realtime operations.
+     */
+    initializeWebsockets?(server: unknown, realtimeService: RealtimeProvider, driver: DataDriver, config?: unknown): Promise<void> | void;
+    /**
+     * Return admin capabilities for this database (SQL editor, schema browser, branching).
+     */
+    getAdmin?(driverResult: InitializedDriver): DatabaseAdmin | undefined;
+    /**
+     * Mount any database-specific HTTP routes (e.g., custom admin endpoints).
+     *
+     * Called after all adapters are initialized.
+     */
+    mountRoutes?(app: unknown, basePath: string, driverResult: InitializedDriver): void;
+    /**
+     * Graceful shutdown: close connections, release resources.
+     */
+    destroy?(): Promise<void>;
+}
+/**
+ * Configuration passed by the coordinator to `DatabaseAdapter.initializeDriver()`.
+ *
+ * @group Backend
+ */
+export interface DatabaseAdapterInitConfig {
+    /** Registered collection definitions. */
+    collections: EntityCollection[];
+    /** The shared collection registry to register into. */
+    collectionRegistry: CollectionRegistryInterface;
+}

package/dist/types/src/types/entity_views.d.ts

@@ -1,10 +1,10 @@
 import React from "react";
 import type { Entity, EntityValues } from "./entities";
 import type { EntityCollection } from "./collections";
+import type { FormexController } from "./formex";
+import type { ComponentRef } from "./component_ref";
 /**
  * Context passed to custom fields and entity views.
- * This is the base definition — `@rebasepro/admin` re-exports a
- * fully-typed version that narrows the `formex` field.
  * @group Form custom fields
  */
 export interface FormContext<M extends Record<string, unknown> = Record<string, unknown>> {
@@ -38,10 +38,8 @@ export interface FormContext<M extends Record<string, unknown> = Record<string,
     openEntityMode: "side_panel" | "full_screen" | "split";
     /**
      * The underlying formex controller that powers the form.
-     * Prefer importing `FormContext` from `@rebasepro/admin` for the
-     * fully-typed `FormexController<M>` version.
      */
-    formex: Record<string, unknown>;
+    formex: FormexController<M>;
     disabled: boolean;
 }
 export type EntityCustomView<M extends Record<string, unknown> = Record<string, unknown>> = {
@@ -49,7 +47,7 @@ export type EntityCustomView<M extends Record<string, unknown> = Record<string,
     name: string;
     tabComponent?: React.ReactNode;
     includeActions?: boolean | "bottom";
-    Builder?: React.ComponentType<EntityCustomViewParams<M>>;
+    Builder?: ComponentRef<EntityCustomViewParams<M>>;
     position?: "start" | "end";
 };
 export interface EntityCustomViewParams<M extends Record<string, unknown> = Record<string, unknown>> {
@@ -57,5 +55,6 @@ export interface EntityCustomViewParams<M extends Record<string, unknown> = Reco
     entity?: Entity<M>;
     modifiedValues?: EntityValues<M>;
     formContext: FormContext<M>;
-    parentCollectionIds?: string[];
+    parentCollectionSlugs?: string[];
+    parentEntityIds?: string[];
 }

package/dist/types/src/types/formex.d.ts

@@ -0,0 +1,40 @@
+import React, { FormEvent } from "react";
+export type FormexController<T = any> = {
+    values: T;
+    initialValues: T;
+    setValues: (values: T) => void;
+    setFieldValue: (key: string, value: unknown, shouldValidate?: boolean) => void;
+    touched: Record<string, boolean>;
+    setFieldTouched: (key: string, touched: boolean, shouldValidate?: boolean) => void;
+    setTouched: (touched: Record<string, boolean>) => void;
+    dirty: boolean;
+    setDirty: (dirty: boolean) => void;
+    setSubmitCount: (submitCount: number) => void;
+    errors: Record<string, string>;
+    setFieldError: (key: string, error?: string) => void;
+    handleChange: (event: React.SyntheticEvent) => void;
+    handleBlur: (event: React.FocusEvent) => void;
+    handleSubmit: (event?: FormEvent<HTMLFormElement>) => void;
+    validate: () => void;
+    resetForm: (props?: FormexResetProps<T>) => void;
+    submitCount: number;
+    isSubmitting: boolean;
+    setSubmitting: (isSubmitting: boolean) => void;
+    isValidating: boolean;
+    /**
+     * The version of the form. This is incremented every time the form is reset
+     * or the form is submitted.
+     */
+    version: number;
+    debugId?: string;
+    undo: () => void;
+    redo: () => void;
+    canUndo: boolean;
+    canRedo: boolean;
+};
+export type FormexResetProps<T = any> = {
+    values?: T;
+    submitCount?: number;
+    errors?: Record<string, string>;
+    touched?: Record<string, boolean>;
+};

package/dist/types/src/types/index.d.ts

@@ -10,6 +10,7 @@ export * from "./entity_callbacks";
 export * from "./entity_overrides";
 export * from "./export_import";
 export * from "./modify_collections";
+export * from "./formex";
 export * from "./websockets";
 export * from "./backend";
 export * from "./translations";
@@ -21,3 +22,7 @@ export * from "./property_config";
 export * from "./entity_views";
 export * from "./data_source";
 export * from "./cron";
+export * from "./backend_hooks";
+export * from "./component_ref";
+export * from "./auth_adapter";
+export * from "./database_adapter";

package/dist/types/src/types/plugins.d.ts

@@ -157,7 +157,8 @@ export interface PluginHooks {
      */
     onColumnsReorder?: (props: {
         fullPath: string;
-        parentCollectionIds: string[];
+        parentCollectionSlugs: string[];
+        parentEntityIds: string[];
         collection: EntityCollection;
         newPropertiesOrder: string[];
     }) => void;
@@ -166,7 +167,8 @@ export interface PluginHooks {
      */
     onKanbanColumnsReorder?: (props: {
         fullPath: string;
-        parentCollectionIds: string[];
+        parentCollectionSlugs: string[];
+        parentEntityIds: string[];
         collection: EntityCollection;
         kanbanColumnProperty: string;
         newColumnsOrder: string[];
@@ -241,7 +243,8 @@ export interface PluginHomePageActionsProps<EP extends object = object, M extend
 export interface PluginFormActionProps<USER extends User = User, EC extends EntityCollection = EntityCollection> {
     entityId?: string | number;
     path: string;
-    parentCollectionIds: string[];
+    parentCollectionSlugs: string[];
+    parentEntityIds: string[];
     status: EntityStatus;
     collection: EC;
     disabled: boolean;