@rebasepro/types 0.6.1 → 0.7.0

package/dist/types/collections.d.ts

@@ -49,33 +49,42 @@ export interface BaseEntityCollection<M extends Record<string, unknown> = Record
      */
     childCollections?: () => EntityCollection<Record<string, unknown>>[];
     /**
-     * Which driver handles this collection.
-     * Use this to route collections to different backends:
-     * - `"postgres"` - Route to PostgreSQL backend
-     * - `"firestore"` - Route to Firestore (client-side)
-     * - `"mongodb"` - Route to MongoDB backend
-     * - Custom IDs for your own driver implementations
+     * The data source this collection belongs to — the routing key shared by
+     * the frontend router and the backend driver registry. It points at a
+     * {@link DataSourceDefinition} registered on `<Rebase dataSources>` (front)
+     * and `initRebase({ dataSources })` (back).
      *
-     * If not specified, the default driver `"(default)"` is used.
+     * If not specified, the default data source `"(default)"` is used, which
+     * for a standard Rebase app is the server-mediated Postgres backend.
      *
      * @example
-     * // Simple - no driver needed for default
+     * // Default data source (server-mediated Postgres)
      * { slug: "products" }
      *
-     * // Firestore collection (client-side real-time)
-     * { slug: "analytics", driver: "firestore" }
+     * // A direct-transport Firestore data source registered as "analytics"
+     * { slug: "events", dataSource: "analytics" }
+     */
+    dataSource?: string;
+    /**
+     * The engine backing this collection (`"postgres"`, `"firestore"`,
+     * `"mongodb"`, or a custom id). Drives editor capabilities (relations vs
+     * subcollections, RLS, column types).
+     *
+     * @deprecated Prefer {@link dataSource} for routing. `driver` is retained
+     * as an engine hint and for backward compatibility: when `dataSource` is
+     * omitted it also acts as the data-source key.
      *
-     * // Multiple databases within a driver
-     * { slug: "orders", driver: "postgres", databaseId: "orders_db" }
+     * If not specified, `"postgres"` is assumed.
      */
     driver?: string;
     /**
-     * Which database within the driver.
+     * Which database within the engine.
      * - For Firestore: The Firestore database ID (e.g., for multi-database projects)
      * - For PostgreSQL: Schema or database name
      * - For MongoDB: Database name
      *
-     * If not specified, the default database of the driver is used.
+     * If not specified, the default database of the engine is used. Resolved
+     * from the collection's {@link DataSourceDefinition} when omitted here.
      */
     databaseId?: string;
     /**
@@ -142,6 +151,25 @@ export interface BaseEntityCollection<M extends Record<string, unknown> = Record
      * When true, this collection is used for user management, login, password hashing, and invitation flows.
      */
     auth?: boolean | AuthCollectionConfig;
+    /**
+     * Opt out of the framework's default Row Level Security policies for
+     * authentication collections.
+     *
+     * When a collection has `auth` enabled, the schema generator automatically
+     * injects an admin-only write policy (INSERT/UPDATE/DELETE require the
+     * `admin` role, or the trusted server context) for any write operation that
+     * the collection does not already cover with an explicit `securityRules`
+     * entry. This makes privileged columns such as `roles` safe by default — a
+     * non-admin cannot modify the user row through the data API regardless of
+     * which code path issues the write.
+     *
+     * Defining your own write rule for an operation overrides the default for
+     * that operation. Set this flag to `true` to remove the default policies
+     * entirely and take full responsibility for the collection's RLS.
+     *
+     * @default false
+     */
+    disableDefaultAuthPolicies?: boolean;
     /**
      * Order in which the properties are displayed.
      * If you are specifying your collection as code, the order is the same as the
@@ -277,6 +305,12 @@ export interface BaseEntityCollection<M extends Record<string, unknown> = Record
      * are writing custom code
      */
     ownerId?: string;
+    /**
+     * Arbitrary key-value metadata for external consumers.
+     * Not interpreted by Rebase — passed through serialization unchanged.
+     * Used by domain apps to store custom per-collection config.
+     */
+    metadata?: Record<string, unknown>;
     /**
      * Overrides for the entity view, like the data source or the storage source.
      */
@@ -324,7 +358,7 @@ export interface BaseEntityCollection<M extends Record<string, unknown> = Record
      * Possible values: "table", "cards", "kanban".
      * Defaults to all three: ["table", "cards", "kanban"].
      * Note: "kanban" will only be available if the collection has at least
-     * one string property with enumValues defined, regardless of this setting.
+     * one string property with `enum` defined, regardless of this setting.
      */
     enabledViews?: ViewMode[];
     /**
@@ -519,9 +553,9 @@ export declare function isMongoDBCollection<M extends Record<string, unknown> =
 export interface KanbanConfig<M extends Record<string, unknown> = Record<string, unknown>> {
     /**
      * Property key to use for Kanban board columns.
-     * Must reference a string property with enumValues defined.
+     * Must reference a string property with `enum` values defined.
      * Entities will be grouped into columns based on this property's value.
-     * The column order is determined by the order of enumValues in the property.
+     * The column order is determined by the order of `enum` values in the property.
      */
     columnProperty: Extract<keyof M, string> | (string & {});
 }

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 */

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_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/index.d.ts

@@ -28,3 +28,4 @@ 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/properties.d.ts

@@ -167,6 +167,13 @@ export interface BaseProperty<CustomProps = unknown> {
      * Callbacks/Hooks for this property field to transform and sanitize data during its lifecycle.
      */
     callbacks?: PropertyCallbacks;
+    /**
+     * Arbitrary key-value metadata for external consumers.
+     * Not interpreted by Rebase — passed through serialization unchanged.
+     * Used by domain apps to store custom per-property config
+     * (e.g. CRM visibility flags, display hints).
+     */
+    metadata?: Record<string, unknown>;
 }
 /**
  * @group Entity properties

package/dist/types/translations.d.ts

@@ -39,6 +39,12 @@ export interface RebaseTranslations {
     unsaved_changes_body: string;
     discard_changes: string;
     keep_editing: string;
+    /** Dialog title when clearing a new/copy form */
+    clear_form?: string;
+    /** Confirmation body when discarding changes on an existing entity */
+    discard_changes_confirmation?: string;
+    /** Confirmation body when clearing a new/copy form */
+    clear_form_confirmation?: string;
     search: string;
     find_by_id: string;
     find_entity_by_id: string;
@@ -153,6 +159,8 @@ export interface RebaseTranslations {
     form_modified: string;
     /** Tooltip when the form is in sync with the database */
     form_in_sync: string;
+    /** Tooltip/alert shown when form has validation errors */
+    fix_errors_before_saving?: string;
     admin: string;
     home: string;
     this_form_has_errors: string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rebasepro/types",
   "type": "module",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "Rebase type definitions — shared interfaces and controller types",
   "funding": {
     "url": "https://github.com/sponsors/rebaseco"

package/src/controllers/client.ts

@@ -3,6 +3,8 @@ import type { RebaseData } from "./data";
 import type { EmailService } from "./email";
 import type { StorageSource } from "./storage";
 import type { CronJobStatus, CronJobLogEntry } from "../types/cron";
+import type { ApiKeysAPI } from "../types/api_keys";
+
 
 /**
  * Event type for authentication state changes
@@ -86,6 +88,8 @@ export interface AdminAPI {
     createUser(data: { email: string; displayName?: string; password?: string; roles?: string[]; metadata?: Record<string, any> }): Promise<{ user: AdminUser }>;
     updateUser(userId: string, data: { email?: string; displayName?: string; password?: string; roles?: string[]; metadata?: Record<string, any> }): Promise<{ user: AdminUser }>;
     deleteUser(userId: string): Promise<{ success: boolean }>;
+    resetPassword(userId: string, options?: { password?: string }): Promise<{ user: AdminUser; temporaryPassword?: string; invitationSent?: boolean }>;
+    listRoles(): Promise<{ roles: Array<{ id: string; name: string }> }>;
     bootstrap(): Promise<{ success: boolean; message: string; user: { uid: string; roles: string[] } }>;
 }
 
@@ -171,6 +175,10 @@ export interface RebaseClient<DB = unknown> {
     /** Custom backend functions API */
     functions?: FunctionsAPI;
 
+    /** Service API keys management API */
+    apiKeys?: ApiKeysAPI;
+
+
     /** Base HTTP URL of the backend server */
     baseUrl?: string;
 

package/src/controllers/navigation.ts

@@ -1,7 +1,7 @@
 import React from "react";
 import type { EntityReference } from "../types/entities";
 import type { EntityCollection } from "../types/collections";
-import type { RebasePlugin } from "../types/plugins";
+
 
 /**
  * Controller that handles URL path building and resolution.
@@ -104,17 +104,12 @@ export type NavigationStateController = {
     /**
      * Was there an error while loading the navigation data
      */
-    navigationLoadingError?: unknown;
+    navigationLoadingError?: Error;
 
     /**
      * Call this method to recalculate the navigation
      */
     refreshNavigation: () => void;
-
-    /**
-     * Plugin system allowing to extend the CMS functionality.
-     */
-    plugins?: RebasePlugin[];
 };
 
 export interface NavigateOptions {
@@ -126,13 +121,7 @@ export interface NavigateOptions {
     viewTransition?: boolean;
 }
 
-// currently not used, in favor of a single blocker in `RebaseRoute`
-export type NavigationBlocker = {
-    updateBlockListener: (path: string, block: boolean, basePath?: string) => () => void;
-    isBlocked: (path: string) => boolean;
-    proceed?: () => void;
-    reset?: () => void;
-};
+
 
 /**
  * Custom additional views created by the developer, added to the main
@@ -181,9 +170,13 @@ export interface AppView {
 
     /**
      * Component to be rendered. This can be any React component, and can use
-     * any of the provided hooks
+     * any of the provided hooks.
+     *
+     * Pass a `ComponentType` to enable lazy rendering — the component will
+     * only be instantiated when the route is visited. This is recommended
+     * for dynamic views generated from database data.
      */
-    view: React.ReactNode;
+    view: React.ReactNode | React.ComponentType;
 
     /**
      * If true, a wildcard route (slug/*) is automatically registered
@@ -191,6 +184,14 @@ export interface AppView {
      */
     nestedRoutes?: boolean;
 
+    /**
+     * Restrict this view to users with at least one of the listed roles.
+     * When omitted or empty, the view is visible to all authenticated users.
+     * Applied during view resolution — the view is filtered out entirely
+     * (not just hidden from nav) if the user lacks a matching role.
+     */
+    roles?: string[];
+
 }
 
 /**

package/src/controllers/registry.ts

@@ -1,6 +1,6 @@
 import { ReactNode } from "react";
 import type { EntityCollection } from "../types/collections";
-import type { EntityCollectionsBuilder } from "../types/builders";
+import type { EntityCollectionsBuilder, AppViewsBuilder } from "../types/builders";
 import type { EntityCustomView } from "../types/entity_views";
 import type { EntityAction } from "../types/entity_actions";
 import type { AppView, NavigationGroupMapping } from "./navigation";
@@ -24,6 +24,14 @@ export interface CollectionEditorOptions {
 
 export interface RebaseCMSConfig<EC extends EntityCollection = EntityCollection> {
     collections?: EC[] | EntityCollectionsBuilder<EC>;
+
+    /**
+     * Custom top-level views added to the main navigation.
+     * Accepts a static array of views or an async builder function
+     * that receives the current user/auth context for role-based views.
+     */
+    views?: AppView[] | AppViewsBuilder;
+
     homePage?: ReactNode;
     entityViews?: EntityCustomView[];
     entityActions?: EntityAction[];
@@ -48,7 +56,7 @@ export interface RebaseCMSConfig<EC extends EntityCollection = EntityCollection>
 }
 
 export interface RebaseStudioConfig {
-    tools?: ("sql" | "js" | "rls" | "schema" | "storage" | "cron" | "schema-visualizer" | "branches" | "api" | "logs")[];
+    tools?: ("sql" | "js" | "rls" | "schema" | "storage" | "cron" | "schema-visualizer" | "branches" | "api" | "logs" | "api-keys")[];
     homePage?: ReactNode;
     devViews?: AppView[];
 }

package/src/types/api_keys.ts

@@ -0,0 +1,52 @@
+/** A single permission entry scoping an API key to a collection and its allowed operations. */
+export interface ApiKeyPermission {
+    collection: string;
+    operations: ("read" | "write" | "delete")[];
+}
+
+/** An API key with the secret portion masked (returned by list / get / update). */
+export interface ApiKeyMasked {
+    id: string;
+    name: string;
+    key_prefix: string;
+    permissions: ApiKeyPermission[];
+    admin: boolean;
+    rate_limit: number | null;
+    created_by: string;
+    created_at: string;
+    updated_at: string;
+    last_used_at: string | null;
+    expires_at: string | null;
+    revoked_at: string | null;
+}
+
+/** An API key including the full secret (returned only on creation). */
+export interface ApiKeyWithSecret extends ApiKeyMasked {
+    key: string;
+}
+
+/** Payload for creating a new API key. */
+export interface CreateApiKeyRequest {
+    name: string;
+    permissions: ApiKeyPermission[];
+    admin?: boolean;
+    rate_limit?: number | null;
+    expires_at?: string | null;
+}
+
+/** Payload for updating an existing API key. */
+export interface UpdateApiKeyRequest {
+    name?: string;
+    permissions?: ApiKeyPermission[];
+    admin?: boolean;
+    rate_limit?: number | null;
+    expires_at?: string | null;
+}
+
+export interface ApiKeysAPI {
+    listKeys(): Promise<{ keys: ApiKeyMasked[] }>;
+    getKey(id: string): Promise<{ key: ApiKeyMasked }>;
+    createKey(data: CreateApiKeyRequest): Promise<{ key: ApiKeyWithSecret }>;
+    updateKey(id: string, data: UpdateApiKeyRequest): Promise<{ key: ApiKeyMasked }>;
+    revokeKey(id: string): Promise<{ success: boolean }>;
+}

package/src/types/auth_adapter.ts

@@ -93,6 +93,8 @@ export interface AuthAdapterCapabilities {
     profileUpdate: boolean;
     /** Supports email verification. */
     emailVerification: boolean;
+    /** Supports passwordless magic link login. */
+    magicLink: boolean;
     /** List of enabled OAuth provider IDs (e.g. `["google", "github"]`). */
     enabledProviders: string[];
 
@@ -218,6 +220,49 @@ export interface UserCreationFinalizeResult {
     invitationSent: boolean;
 }
 
+// ─── Auth Response Transform ─────────────────────────────────────────────────
+
+/**
+ * The auth response payload shape that flows through `transformAuthResponse`.
+ *
+ * For login, register, OAuth, anonymous, and magic-link flows the payload
+ * contains both `user` and `tokens`. For refresh and MFA flows the payload
+ * contains only `tokens` (no `user`).
+ *
+ * @group Auth
+ */
+export interface AuthResponsePayload {
+    user?: {
+        uid: string;
+        email: string;
+        displayName: string | null;
+        photoURL: string | null;
+        roles: string[];
+        metadata: Record<string, unknown>;
+    };
+    tokens: {
+        accessToken: string;
+        refreshToken: string;
+        accessTokenExpiresAt: number;
+        /** Additional tokens injected by `transformAuthResponse`. */
+        [key: string]: unknown;
+    };
+}
+
+/**
+ * Context passed to the `transformAuthResponse` hook.
+ *
+ * @group Auth
+ */
+export interface TransformAuthResponseContext {
+    /** The authenticated user's ID. */
+    userId: string;
+    /** The auth method that triggered this response. */
+    method: "login" | "register" | "oauth" | "refresh" | "anonymous" | "magic-link" | "mfa";
+    /** The raw HTTP request (for reading headers, IP, etc.). */
+    request: Request;
+}
+
 // ─── Auth Adapter ────────────────────────────────────────────────────────────
 
 /**
@@ -379,6 +424,28 @@ export interface AuthAdapter {
      * normal token verification and are granted admin-level access.
      */
     serviceKey?: string;
+
+    // ── Response Transform ───────────────────────────────────────────────
+
+    /**
+     * Transform the auth response before sending it to the client.
+     *
+     * Called after successful login, register, refresh, OAuth, anonymous,
+     * magic-link, and MFA flows. The hook receives the fully-formed
+     * response and returns a (potentially enriched) response.
+     *
+     * Use cases:
+     * - Inject tokens from external auth systems (Firebase Custom Tokens, etc.)
+     * - Add project-specific metadata to the response
+     * - Enrich the user object with data from external sources
+     *
+     * The hook runs in the request path — keep it fast.
+     * Heavy work should be offloaded to `onAuthenticated` (fire-and-forget).
+     */
+    transformAuthResponse?(
+        response: AuthResponsePayload,
+        context: TransformAuthResponseContext
+    ): Promise<AuthResponsePayload>;
 }
 
 // ─── Custom Auth Adapter Options ─────────────────────────────────────────────
@@ -413,4 +480,13 @@ export interface CustomAuthAdapterOptions {
 
     /** Override default capabilities. */
     capabilities?: Partial<AuthAdapterCapabilities>;
+
+    /**
+     * Transform the auth response before sending it to the client.
+     * Same semantics as `AuthAdapter.transformAuthResponse`.
+     */
+    transformAuthResponse?: (
+        response: AuthResponsePayload,
+        context: TransformAuthResponseContext
+    ) => Promise<AuthResponsePayload>;
 }

package/src/types/backend.ts

@@ -367,7 +367,7 @@ export interface SQLAdmin {
     /**
      * Execute raw SQL against the database.
      */
-    executeSql(sql: string, options?: { database?: string; role?: string }): Promise<Record<string, unknown>[]>;
+    executeSql(sql: string, options?: { database?: string; role?: string; params?: unknown[] }): Promise<Record<string, unknown>[]>;
 
     /**
      * Fetch the available databases on the server.