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

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

@@ -0,0 +1,354 @@
+/**
+ * @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;
+    createdAt?: Date;
+    updatedAt?: Date;
+}
+/**
+ * Data for creating a user.
+ * @group Auth
+ */
+export interface AuthCreateUserData {
+    email: string;
+    password?: string;
+    displayName?: string;
+    photoUrl?: string;
+}
+/**
+ * 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/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