@rebasepro/plugin-data-enhancement 0.1.2 → 0.2.3

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

@@ -0,0 +1,356 @@
+/**
+ * @module AuthAdapter
+ *
+ * Pluggable authentication abstraction for Rebase.
+ *
+ * An `AuthAdapter` decouples authentication from the database layer,
+ * allowing users to bring their own auth system (Clerk, Auth0, Firebase Auth,
+ * custom JWT, etc.) while keeping the Rebase admin frontend fully functional.
+ *
+ * @example Built-in auth (default — zero config change)
+ * ```ts
+ * initializeRebaseBackend({
+ *   auth: { jwtSecret: "...", google: { clientId: "..." } },
+ *   database: createPostgresAdapter({ ... }),
+ * });
+ * ```
+ *
+ * @example Custom auth
+ * ```ts
+ * import { createCustomAuthAdapter } from "@rebasepro/server-core";
+ *
+ * initializeRebaseBackend({
+ *   auth: createCustomAuthAdapter({
+ *     verifyRequest: async (req) => { ... },
+ *   }),
+ *   database: createPostgresAdapter({ ... }),
+ * });
+ * ```
+ *
+ * @group Auth
+ */
+import type { Hono } from "hono";
+/**
+ * The normalized user object returned by `AuthAdapter.verifyRequest()`.
+ *
+ * Regardless of the auth provider, every request is resolved to this shape
+ * so that downstream middleware (RLS scoping, route guards) can work uniformly.
+ *
+ * @group Auth
+ */
+export interface AuthenticatedUser {
+    /** Unique user identifier (provider-specific). */
+    uid: string;
+    /** Primary email address. */
+    email: string;
+    /** Human-readable display name. */
+    displayName?: string | null;
+    /** Avatar URL. */
+    photoUrl?: string | null;
+    /** Role identifiers the user holds. */
+    roles: string[];
+    /** Whether the user has admin privileges. */
+    isAdmin: boolean;
+    /** Raw bearer token from the request (for forwarding). */
+    rawToken?: string;
+    /** Extra claims/metadata from the auth provider. */
+    claims?: Record<string, unknown>;
+}
+/**
+ * Feature flags advertised by an auth adapter.
+ *
+ * The frontend reads these from `GET /api/auth/config` to dynamically
+ * show/hide UI elements (login form, registration, password reset, etc.).
+ *
+ * @group Auth
+ */
+export interface AuthAdapterCapabilities {
+    /**
+     * Whether this adapter mounts its own `/auth/*` routes.
+     *
+     * - `true` for the built-in Rebase auth (login, register, refresh, etc.)
+     * - `false` for external providers like Clerk or Auth0 that handle
+     *   auth flows outside of the Rebase backend.
+     */
+    hasBuiltInAuthRoutes: boolean;
+    /** Supports email/password login. */
+    emailPasswordLogin: boolean;
+    /** Supports new user registration. */
+    registration: boolean;
+    /** Supports password reset flow. */
+    passwordReset: boolean;
+    /** Supports session listing/revocation. */
+    sessionManagement: boolean;
+    /** Supports profile updates (display name, photo). */
+    profileUpdate: boolean;
+    /** Supports email verification. */
+    emailVerification: boolean;
+    /** List of enabled OAuth provider IDs (e.g. `["google", "github"]`). */
+    enabledProviders: string[];
+    /**
+     * For external auth (Clerk, Auth0, etc.): the URL where the user should
+     * be redirected for login. The Rebase frontend will navigate here instead
+     * of showing its own login form.
+     */
+    externalLoginUrl?: string;
+    /**
+     * True when no users exist yet — first-user bootstrap mode.
+     * Only applicable for built-in auth.
+     */
+    needsSetup?: boolean;
+    /** Whether new user registration is enabled (may differ from `registration` capability at runtime). */
+    registrationEnabled?: boolean;
+}
+/**
+ * Options for paginated user listing.
+ * @group Auth
+ */
+export interface AuthUserListOptions {
+    limit?: number;
+    offset?: number;
+    search?: string;
+    orderBy?: string;
+    orderDir?: "asc" | "desc";
+    roleId?: string;
+}
+/**
+ * Paginated user listing result.
+ * @group Auth
+ */
+export interface AuthUserListResult {
+    users: AuthUserData[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+/**
+ * User data exposed by the auth adapter.
+ * @group Auth
+ */
+export interface AuthUserData {
+    id: string;
+    email: string;
+    displayName?: string | null;
+    photoUrl?: string | null;
+    emailVerified?: boolean;
+    metadata?: Record<string, any>;
+    createdAt?: Date;
+    updatedAt?: Date;
+}
+/**
+ * Data for creating a user.
+ * @group Auth
+ */
+export interface AuthCreateUserData {
+    email: string;
+    password?: string;
+    displayName?: string;
+    photoUrl?: string;
+    metadata?: Record<string, any>;
+}
+/**
+ * Role data exposed by the auth adapter.
+ * @group Auth
+ */
+export interface AuthRoleData {
+    id: string;
+    name: string;
+    isAdmin: boolean;
+    defaultPermissions?: {
+        read?: boolean;
+        create?: boolean;
+        edit?: boolean;
+        delete?: boolean;
+    } | null;
+    collectionPermissions?: Record<string, {
+        read?: boolean;
+        create?: boolean;
+        edit?: boolean;
+        delete?: boolean;
+    }> | null;
+    config?: Record<string, unknown> | null;
+}
+/**
+ * Data for creating a role.
+ * @group Auth
+ */
+export interface AuthCreateRoleData {
+    id: string;
+    name: string;
+    isAdmin?: boolean;
+    defaultPermissions?: AuthRoleData["defaultPermissions"];
+    collectionPermissions?: AuthRoleData["collectionPermissions"];
+    config?: AuthRoleData["config"];
+}
+/**
+ * User management operations for the admin panel.
+ *
+ * Optional — if not provided by the adapter, the user management UI is hidden.
+ *
+ * @group Auth
+ */
+export interface UserManagementAdapter {
+    listUsers(options?: AuthUserListOptions): Promise<AuthUserListResult>;
+    getUserById(id: string): Promise<AuthUserData | null>;
+    createUser(data: AuthCreateUserData): Promise<AuthUserData>;
+    updateUser(id: string, data: Partial<AuthCreateUserData>): Promise<AuthUserData | null>;
+    deleteUser(id: string): Promise<void>;
+    getUserRoles(userId: string): Promise<AuthRoleData[]>;
+    setUserRoles(userId: string, roleIds: string[]): Promise<void>;
+}
+/**
+ * Role management operations for the admin panel.
+ *
+ * Optional — if not provided by the adapter, role management is disabled.
+ *
+ * @group Auth
+ */
+export interface RoleManagementAdapter {
+    listRoles(): Promise<AuthRoleData[]>;
+    getRoleById(id: string): Promise<AuthRoleData | null>;
+    createRole(data: AuthCreateRoleData): Promise<AuthRoleData>;
+    updateRole(id: string, data: Partial<AuthRoleData>): Promise<AuthRoleData | null>;
+    deleteRole(id: string): Promise<void>;
+}
+/**
+ * Pluggable authentication adapter for Rebase.
+ *
+ * This is the **key interface** that decouples authentication from the
+ * database layer. Each auth adapter knows how to:
+ *
+ * 1. Verify incoming HTTP requests (`verifyRequest`)
+ * 2. Optionally manage users and roles (for the admin panel)
+ * 3. Optionally mount auth-specific routes (login, register, etc.)
+ * 4. Advertise its capabilities so the frontend can adapt
+ *
+ * The built-in Rebase auth implements this interface internally.
+ * External providers (Clerk, Auth0, Firebase Auth) provide their own adapters.
+ * Users with custom auth can use `createCustomAuthAdapter()` for a minimal setup.
+ *
+ * @group Auth
+ */
+export interface AuthAdapter {
+    /**
+     * Unique identifier for this auth adapter.
+     *
+     * @example "rebase-builtin", "clerk", "auth0", "firebase", "custom"
+     */
+    readonly id: string;
+    /**
+     * Verify an incoming request and extract the authenticated user.
+     *
+     * This replaces the hardcoded JWT verification in server-core's middleware.
+     * Each adapter implements its own token verification strategy:
+     * - Built-in: verify Rebase JWT
+     * - Clerk: call Clerk's `verifyToken()`
+     * - Auth0: validate Auth0 JWT with JWKS
+     * - Custom: whatever logic the user provides
+     *
+     * @param request - The raw `Request` object (portable across Hono, Express, Fastify)
+     * @returns The authenticated user, or `null` for unauthenticated requests.
+     *          Throw an error to reject the request with 401.
+     */
+    verifyRequest(request: Request): Promise<AuthenticatedUser | null>;
+    /**
+     * Verify a raw bearer token and extract the authenticated user.
+     *
+     * Used for **WebSocket authentication**, where there is no HTTP `Request`
+     * object — only a token string sent over the socket.
+     *
+     * If not implemented, the default behavior synthesizes a minimal `Request`
+     * with an `Authorization: Bearer <token>` header and delegates to
+     * `verifyRequest()`. Adapters should override this if their token
+     * verification logic doesn't depend on request headers/cookies.
+     *
+     * @param token - The raw bearer token string.
+     * @returns The authenticated user, or `null` if the token is invalid.
+     */
+    verifyToken?(token: string): Promise<AuthenticatedUser | null>;
+    /**
+     * User CRUD for the admin panel's user management UI.
+     * Optional — if not provided, user management UI is hidden.
+     */
+    userManagement?: UserManagementAdapter;
+    /**
+     * Role CRUD for the admin panel.
+     * Optional — if not provided, role management is disabled.
+     */
+    roleManagement?: RoleManagementAdapter;
+    /**
+     * Mount adapter-specific auth routes (login, register, refresh, etc.).
+     *
+     * - Built-in adapter: mounts `/auth/login`, `/auth/register`, etc.
+     * - External adapter: typically returns `undefined` (auth is handled externally).
+     * - Custom adapter: user mounts their own routes.
+     *
+     * The return type uses `Hono<any, any, any>` because this sub-app will be
+     * mounted into a parent app via `.route()`, which accepts any Hono env type.
+     * Adapter implementations are free to use their own env (e.g. `Hono<HonoEnv>`).
+     *
+     * @returns A Hono sub-app with auth routes, or `undefined` to skip route mounting.
+     */
+    createAuthRoutes?(): Hono<any, any, any> | undefined;
+    /**
+     * Mount admin routes for user/role management.
+     *
+     * Same typing rationale as `createAuthRoutes` — the sub-app env is
+     * unconstrained to support arbitrary adapter implementations.
+     *
+     * @returns A Hono sub-app with admin routes, or `undefined` to skip.
+     */
+    createAdminRoutes?(): Hono<any, any, any> | undefined;
+    /**
+     * Advertise what this auth adapter supports.
+     *
+     * The frontend reads this from `GET /api/auth/config` to dynamically
+     * show/hide UI elements. This is the bridge between backend capabilities
+     * and the frontend's `AuthCapabilities` type.
+     */
+    getCapabilities(): AuthAdapterCapabilities | Promise<AuthAdapterCapabilities>;
+    /**
+     * Called during backend initialization.
+     * Use for running migrations, creating tables, seeding initial data, etc.
+     */
+    initialize?(): Promise<void>;
+    /**
+     * Called during graceful shutdown.
+     * Use for closing connections, flushing caches, etc.
+     */
+    destroy?(): Promise<void>;
+    /**
+     * A static secret key for server-to-server / script authentication.
+     *
+     * When set, requests with `Authorization: Bearer <serviceKey>` bypass
+     * normal token verification and are granted admin-level access.
+     */
+    serviceKey?: string;
+}
+/**
+ * Options for creating a minimal custom auth adapter via `createCustomAuthAdapter()`.
+ *
+ * This is the simplest way to plug an existing auth system into Rebase.
+ * Only `verifyRequest` is required — everything else is optional.
+ *
+ * @group Auth
+ */
+export interface CustomAuthAdapterOptions {
+    /**
+     * Verify an incoming request and return the authenticated user.
+     * This is the only required method.
+     */
+    verifyRequest: (request: Request) => Promise<AuthenticatedUser | null>;
+    /**
+     * Verify a raw bearer token for WebSocket authentication.
+     * Optional — if omitted, a synthetic `Request` is constructed and passed
+     * to `verifyRequest`.
+     */
+    verifyToken?: (token: string) => Promise<AuthenticatedUser | null>;
+    /** Optional user management for the admin panel. */
+    userManagement?: UserManagementAdapter;
+    /** Optional role management for the admin panel. */
+    roleManagement?: RoleManagementAdapter;
+    /** Static service key for server-to-server auth. */
+    serviceKey?: string;
+    /** Override default capabilities. */
+    capabilities?: Partial<AuthAdapterCapabilities>;
+}

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

@@ -7,7 +7,7 @@ import type { EntityOverrides } from "./entity_overrides";
 import type { User } from "../users";
 import type { RebaseContext } from "../rebase_context";
 import type { Relation } from "./relations";
-import type { EntityCustomView } from "./entity_views";
+import type { EntityCustomView, EntityDetailViewConfig } from "./entity_views";
 import type { EntityAction } from "./entity_actions";
 import type { ComponentRef } from "./component_ref";
 /**
@@ -116,7 +116,22 @@ export interface BaseEntityCollection<M extends Record<string, unknown> = Record
      * When editing an entity, you can choose to open the entity in a side dialog
      * or in a full screen dialog. Defaults to `full_screen`.
      */
-    openEntityMode?: "side_panel" | "full_screen" | "split";
+    openEntityMode?: "side_panel" | "full_screen" | "split" | "dialog";
+    /**
+     * Controls what happens when a user clicks on an entity in the collection view.
+     * - `"edit"` (default): Opens the entity in the edit form.
+     * - `"view"`: Opens a read-only detail view with an "Edit" button.
+     */
+    defaultEntityAction?: "view" | "edit";
+    /**
+     * Customization options for the read-only detail view.
+     * Only used when `defaultEntityAction` is `"view"`.
+     */
+    detailView?: EntityDetailViewConfig;
+    /**
+     * Prevent default actions from being displayed or executed on this collection.
+     */
+    disableDefaultActions?: ("edit" | "copy" | "delete")[];
     /**
      * Order in which the properties are displayed.
      * If you are specifying your collection as code, the order is the same as the
@@ -172,6 +187,24 @@ export interface BaseEntityCollection<M extends Record<string, unknown> = Record
      * e.g. `defaultFilter: { related_user: ["==", new EntityReference("sdc43dsw2", "users")] }`
      */
     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
@@ -327,6 +360,12 @@ export interface PostgresCollection<M extends Record<string, unknown> = Record<s
      * The PostgreSQL table name for this collection.
      */
     table: string;
+    /**
+     * The PostgreSQL schema name for this table.
+     * E.g. "public", "rebase", "auth".
+     * If not specified, "public" is used (or the default search path).
+     */
+    schema?: string;
     /**
      * For SQL databases, you can define the relations between collections here.
      * Relations describe JOINs, foreign keys, and junction tables.
@@ -528,6 +567,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/database_adapter.d.ts

@@ -0,0 +1,94 @@
+/**
+ * @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, BootstrappedAuth } 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 auth tables / services if this driver supports them.
+     */
+    initializeAuth?(config: unknown, driverResult: InitializedDriver): Promise<BootstrappedAuth | 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_actions.d.ts

@@ -40,6 +40,12 @@ export interface EntityAction<M extends Record<string, unknown> = Record<string,
      * @param props
      */
     isEnabled?(props: EntityActionClickProps<M, USER>): boolean;
+    /**
+     * When true, this action is rendered inline on each row in the list view.
+     * By default, entity actions only appear in the table view and entity form.
+     * Use this for actions that should be easily accessible regardless of view mode.
+     */
+    showActionsInListView?: boolean;
     /**
      * Show this action collapsed in the menu of the collection view.
      * Defaults to true
@@ -72,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";
+    openEntityMode: "side_panel" | "full_screen" | "split" | "dialog";
     /**
      * Optional selection controller, present if the action is being called from a collection view
      */

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

@@ -39,7 +39,7 @@ export type EntityCallbacks<M extends Record<string, unknown> = Record<string, u
      *
      * @param props
      */
-    beforeDelete?(props: EntityBeforeDeleteProps<M, USER>): void;
+    beforeDelete?(props: EntityBeforeDeleteProps<M, USER>): Promise<boolean | void> | boolean | void;
     /**
      * Callback used after the entity is deleted.
      *

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

@@ -35,12 +35,17 @@ 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";
+    openEntityMode: "side_panel" | "full_screen" | "split" | "dialog";
     /**
      * The underlying formex controller that powers the form.
      */
     formex: FormexController<M>;
     disabled: boolean;
+    /**
+     * Whether the form context is in read-only detail view mode.
+     * Custom entity views can use this to adjust their rendering.
+     */
+    readOnly?: boolean;
 }
 export type EntityCustomView<M extends Record<string, unknown> = Record<string, unknown>> = {
     key: string;
@@ -58,3 +63,33 @@ export interface EntityCustomViewParams<M extends Record<string, unknown> = Reco
     parentCollectionSlugs?: string[];
     parentEntityIds?: string[];
 }
+/**
+ * Configuration for customizing the read-only detail view of an entity.
+ * Only used when `defaultEntityAction` is set to `"view"` on the collection.
+ * @group Models
+ */
+export type EntityDetailViewConfig<M extends Record<string, unknown> = Record<string, unknown>> = {
+    /**
+     * Custom component rendered above the property display in the detail view.
+     */
+    Header?: ComponentRef<EntityDetailViewParams<M>>;
+    /**
+     * Custom component rendered below the property display in the detail view.
+     */
+    Footer?: ComponentRef<EntityDetailViewParams<M>>;
+    /**
+     * Completely replace the default detail view with a custom component.
+     * When set, Header and Footer are ignored.
+     */
+    Builder?: ComponentRef<EntityDetailViewParams<M>>;
+};
+/**
+ * Props passed to detail view customization components (Header, Footer, Builder).
+ * @group Models
+ */
+export interface EntityDetailViewParams<M extends Record<string, unknown> = Record<string, unknown>> {
+    collection: EntityCollection<M>;
+    entity: Entity<M>;
+    path: string;
+    onEditClick: () => void;
+}

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

@@ -24,3 +24,5 @@ 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

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