@rebasepro/types 0.5.0 → 0.6.0

package/src/controllers/client.ts

@@ -1,6 +1,8 @@
 import type { User } from "../users";
 import type { RebaseData } from "./data";
 import type { EmailService } from "./email";
+import type { StorageSource } from "./storage";
+import type { CronJobStatus, CronJobLogEntry } from "../types/cron";
 
 /**
  * Event type for authentication state changes
@@ -17,8 +19,6 @@ export interface RebaseSession {
     user: User;
 }
 
-import type { StorageSource } from "./storage";
-
 /**
  * Unified Authentication Client Interface
  * Pure functional SDK interface, decoupled from UI and React hooks
@@ -50,6 +50,8 @@ export interface AuthClient {
     refreshSession(): Promise<RebaseSession>;
 }
 
+// ─── Admin API ───────────────────────────────────────────────────────────────
+
 /**
  * User record as returned by the Admin API.
  * @group Admin
@@ -87,9 +89,62 @@ export interface AdminAPI {
     bootstrap(): Promise<{ success: boolean; message: string; user: { uid: string; roles: string[] } }>;
 }
 
+// ─── Cron API ────────────────────────────────────────────────────────────────
+
+/**
+ * Client-side Cron job management interface.
+ * @group Cron
+ */
+export interface CronAPI {
+    listJobs(): Promise<{ jobs: CronJobStatus[] }>;
+    getJob(jobId: string): Promise<{ job: CronJobStatus }>;
+    triggerJob(jobId: string): Promise<{ log: CronJobLogEntry; job: CronJobStatus }>;
+    getJobLogs(jobId: string, options?: { limit?: number }): Promise<{ logs: CronJobLogEntry[] }>;
+    toggleJob(jobId: string, enabled: boolean): Promise<{ job: CronJobStatus }>;
+}
+
+// ─── Functions API ───────────────────────────────────────────────────────────
+
+/**
+ * Options for invoking a custom backend function.
+ * @group Functions
+ */
+export interface FunctionInvokeOptions {
+    /** HTTP method — defaults to `"POST"`. */
+    method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    /** Sub-path appended after the function name. */
+    path?: string;
+    /** Extra headers merged into the request. */
+    headers?: Record<string, string>;
+}
+
+/**
+ * Client interface for invoking custom backend functions.
+ * @group Functions
+ */
+export interface FunctionsAPI {
+    /**
+     * Invoke a custom backend function by name.
+     *
+     * @typeParam T - Expected shape of the response payload.
+     * @param name    - Function name (filename without extension, e.g. `"extract-job"`).
+     * @param payload - Optional JSON-serialisable body sent as POST.
+     * @param options - Optional overrides (method, sub-path, headers).
+     */
+    invoke<T = unknown>(name: string, payload?: unknown, options?: FunctionInvokeOptions): Promise<T>;
+}
+
+// ─── RebaseClient ────────────────────────────────────────────────────────────
+
 /**
- * Overarching abstraction that unites Data, Auth, Storage, and Email.
- * Adapters for Supabase or Firebase simply need to implement this interface.
+ * The single, canonical Rebase client interface.
+ *
+ * Used everywhere: the server-side `rebase` singleton, the SDK's
+ * `createRebaseClient()`, React context, cron job context, etc.
+ *
+ * Core fields (`data`, `auth`) are always present. Everything else
+ * is optional — which capabilities are populated depends on the
+ * runtime environment and adapter.
  */
 export interface RebaseClient<DB = unknown> {
     /** Unified Data access layer */
@@ -103,47 +158,44 @@ export interface RebaseClient<DB = unknown> {
 
     /**
      * Server-side email service.
-     *
-     * Available when SMTP (or a custom `sendEmail` function) is configured
-     * in the backend auth config. `undefined` when email is not configured.
-     *
-     * > **Note:** This is only available on the server-side `rebase` singleton.
-     * > The client-side SDK does not include an email service.
+     * Available when SMTP or a custom `sendEmail` function is configured.
      */
     email?: EmailService;
 
     /** Admin API for user management */
     admin?: AdminAPI;
 
-    /**
-     * The base HTTP URL of the backend server.
-     * Exposed by the SDK client (`@rebasepro/client`) and used to auto-derive
-     * the `ApiConfigProvider` URL.
-     */
+    /** Cron job management API */
+    cron?: CronAPI;
+
+    /** Custom backend functions API */
+    functions?: FunctionsAPI;
+
+    /** Base HTTP URL of the backend server */
     baseUrl?: string;
 
-    /**
-     * WebSocket client for realtime subscriptions and admin capabilities.
-     * Exposed by the SDK client (`@rebasepro/client`). The shape is intentionally
-     * left as `unknown` in the base interface — callers should narrow via feature
-     * detection (e.g. `typeof ws.executeSql === "function"`).
-     */
+    /** WebSocket client for realtime subscriptions */
     ws?: unknown;
 
+    /** Set the auth token for subsequent requests */
+    setToken?(token: string | null): void;
+
+    /** Set a function that lazily resolves the auth token */
+    setAuthTokenGetter?(getter: () => Promise<string | null>): void;
+
+    /** Set handler called when a request returns 401 */
+    setOnUnauthorized?(handler: () => Promise<boolean>): void;
+
+    /** Resolve the current auth token */
+    resolveToken?(): Promise<string | null>;
+
+    /** Make a raw HTTP call to the backend */
+    call?<T = unknown>(endpoint: string, payload?: unknown): Promise<T>;
+
     /**
      * Execute raw SQL against the database.
-     *
-     * Only available server-side when the backend uses a SQL database
-     * (PostgreSQL, MySQL, etc.). `undefined` for document databases
-     * (MongoDB, Firestore) and on the client-side SDK.
-     *
-     * @example
-     * ```typescript
-     * // In a cron job or custom function:
-     * if (ctx.client.sql) {
-     *     const rows = await ctx.client.sql("SELECT count(*) FROM orders");
-     * }
-     * ```
+     * Only available server-side with a SQL database.
      */
     sql?(query: string, options?: { database?: string; role?: string }): Promise<Record<string, unknown>[]>;
 }
+

package/src/controllers/customization_controller.tsx

@@ -1,4 +1,4 @@
-import React from "react";
+
 import type { EntityLinkBuilder } from "../types/entity_link_builder";
 import type { Locale } from "../types/locales";
 import type { EntityAction } from "../types/entity_actions";
@@ -6,6 +6,7 @@ import type { EntityCustomView } from "../types/entity_views";
 import type { RebasePlugin } from "../types/plugins";
 import type { PropertyConfig } from "../types/property_config";
 import type { SlotContribution } from "../types/slots";
+import type { ComponentOverrideMap } from "../types/component_overrides";
 
 export type CustomizationController = {
 
@@ -59,14 +60,13 @@ export type CustomizationController = {
      */
     propertyConfigs: Record<string, PropertyConfig>;
 
-    components?: {
-
-        /**
-         * Component to render when a reference is missing
-         */
-        missingReference?: React.ComponentType<{
-            path: string,
-        }>;
-
-    };
+    /**
+     * Global component overrides. Keys are component names from
+     * {@link OverridableComponentName}. Values replace the default
+     * implementation everywhere in the app.
+     *
+     * Collection-scoped overrides (set on individual collections)
+     * take precedence over global overrides.
+     */
+    components?: ComponentOverrideMap;
 }

package/src/rebase_context.tsx

@@ -7,7 +7,6 @@ import type { RebaseClient } from "./controllers/client";
 
 import type { RebaseData } from "./controllers/data";
 import type { User } from "./users";
-import type { UserManagementDelegate } from "./types/user_management_delegate";
 
 
 /**
@@ -112,21 +111,6 @@ export type RebaseContext<USER extends User = User, AuthControllerType extends A
      */
     analyticsController?: AnalyticsController;
 
-    /**
-     * This section is used to manage users in the CMS.
-     * It is used to show user information in various places of the CMS,
-     * for example, to show who created or modified an entity,
-     * or to assign ownership of an entity.
-     *
-     * In the base CMS, this information is not used for access control.
-     * You can pass your own implementation of this section, to populate
-     * the dropdown of users when assigning ownership of an entity,
-     * or to show more information about the user.
-     *
-     * If you are using the Rebase user management plugin, this
-     * section will be implemented automatically.
-     */
-    userManagement?: UserManagementDelegate<USER>;
 
     /**
      * Administrative database operations (SQL, schema discovery).

package/src/types/auth_adapter.ts

@@ -183,6 +183,41 @@ export interface UserManagementAdapter {
     setUserRoles(userId: string, roleIds: string[]): Promise<void>;
 }
 
+// ─── User Creation Lifecycle ─────────────────────────────────────────────────
+
+/**
+ * Result of `AuthAdapter.prepareUserCreation()`.
+ *
+ * Contains the processed values ready for persistence and metadata
+ * needed by the finalization step.
+ *
+ * @group Auth
+ */
+export interface UserCreationPrepareResult {
+    /** Processed values to persist (passwordHash instead of raw password, etc.). */
+    values: Record<string, unknown>;
+    /** Cleartext password for post-save processing (email or admin display). */
+    clearPassword?: string;
+    /** Whether the hook already handled the invitation (email, etc.). */
+    hookHandledEmail: boolean;
+    /** Whether an invitation was sent (only relevant when hookHandledEmail is true). */
+    invitationSent: boolean;
+}
+
+/**
+ * Result of `AuthAdapter.finalizeUserCreation()`.
+ *
+ * Returned to the REST API for inclusion in the response.
+ *
+ * @group Auth
+ */
+export interface UserCreationFinalizeResult {
+    /** If set, returned to the admin in the API response. */
+    temporaryPassword?: string;
+    /** Whether an invitation email was sent. */
+    invitationSent: boolean;
+}
+
 // ─── Auth Adapter ────────────────────────────────────────────────────────────
 
 /**
@@ -270,10 +305,7 @@ export interface AuthAdapter {
     createAuthRoutes?(): Hono<any, any, any> | undefined;
 
     /**
-     * Mount admin routes for user management.
-     *
-     * Same typing rationale as `createAuthRoutes` — the sub-app env is
-     * unconstrained to support arbitrary adapter implementations.
+     * Mount admin routes (e.g. password reset for users).
      *
      * @returns A Hono sub-app with admin routes, or `undefined` to skip.
      */
@@ -304,6 +336,40 @@ export interface AuthAdapter {
      */
     destroy?(): Promise<void>;
 
+    // ── Collection User Creation (for auth collections) ───────────────
+
+    /**
+     * Prepare values for creating a user via the auth collection's REST API.
+     *
+     * Called on POST to a collection with `auth: true`. Handles password
+     * hashing, email normalization, and any collection/backend-level hooks.
+     *
+     * If not implemented, the collection saves values as-is (no password hashing).
+     *
+     * @param values - Raw request body from the client.
+     * @param collectionAuth - The parsed `AuthCollectionConfig` from the collection (if `auth` is an object).
+     * @returns Processed values ready for `driver.saveEntity()`, plus metadata for the post-save step.
+     */
+    prepareUserCreation?(
+        values: Record<string, unknown>,
+        collectionAuth?: unknown
+    ): Promise<UserCreationPrepareResult>;
+
+    /**
+     * Finalize a user creation after the entity has been persisted.
+     *
+     * Handles post-save work: sending invitation emails, generating
+     * password-reset tokens, or falling back to returning a temporary password.
+     *
+     * @param entity - The persisted entity (id + values).
+     * @param clearPassword - The cleartext password from the prepare step (if any).
+     * @returns Metadata for the API response (temporary password, invitation status).
+     */
+    finalizeUserCreation?(
+        entity: { id: string; values: Record<string, unknown> },
+        clearPassword?: string
+    ): Promise<UserCreationFinalizeResult>;
+
     // ── Service Key (optional) ──────────────────────────────────────────
 
     /**

package/src/types/backend_hooks.ts

@@ -1,4 +1,3 @@
-import type { AdminUser } from "../controllers/client";
 
 /**
  * Context passed to every backend hook.
@@ -12,49 +11,6 @@ export interface BackendHookContext {
     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 collection entity data at the REST API boundary.
@@ -130,9 +86,6 @@ export interface DataHooks {
  * These hooks run server-side after database operations complete and before
  * API responses are sent.
  *
- * - `users` — intercept admin user 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
@@ -149,12 +102,6 @@ export interface DataHooks {
  *             }
  *             return entity;
  *         }
- *     },
- *     users: {
- *         afterRead(user, ctx) {
- *             if (user.email.endsWith("@system.internal")) return null;
- *             return user;
- *         }
  *     }
  * };
  * ```
@@ -162,8 +109,6 @@ export interface DataHooks {
  * @group Backend Hooks
  */
 export interface BackendHooks {
-    /** Hooks for intercepting user management data */
-    users?: UserHooks;
     /** Hooks for intercepting ALL collection entity data via the REST API */
     data?: DataHooks;
 }

package/src/types/breadcrumbs.ts

@@ -0,0 +1,27 @@
+export interface BreadcrumbEntry {
+    title: string;
+    url: string;
+    /**
+     * Optional entity count for collection breadcrumbs.
+     * - undefined: not applicable (e.g., entity breadcrumb, custom view)
+     * - null: loading
+     * - number: loaded count
+     */
+    count?: number | null;
+    /**
+     * Unique identifier for this breadcrumb (e.g., collection path).
+     * Used to update count without replacing entire breadcrumb array.
+     */
+    id?: string;
+}
+
+export interface BreadcrumbsController {
+    breadcrumbs: BreadcrumbEntry[];
+    set: (props: {
+        breadcrumbs: BreadcrumbEntry[];
+    }) => void;
+    /**
+     * Update the count for a specific breadcrumb by ID.
+     */
+    updateCount: (id: string, count: number | null | undefined) => void;
+}

package/src/types/collections.ts

@@ -11,6 +11,7 @@ import type { Relation } from "./relations";
 import type { EntityCustomView, FormViewConfig } from "./entity_views";
 import type { EntityAction } from "./entity_actions";
 import type { ComponentRef } from "./component_ref";
+import type { CollectionComponentOverrideMap } from "./component_overrides";
 
 /**
  * Base interface containing all driver-agnostic collection properties.
@@ -158,6 +159,11 @@ export interface BaseEntityCollection<M extends Record<string, unknown> = Record
      */
     disableDefaultActions?: ("edit" | "copy" | "delete")[];
 
+    /**
+     * Mark this collection as an authentication collection.
+     * When true, this collection is used for user management, login, password hashing, and invitation flows.
+     */
+    auth?: boolean | AuthCollectionConfig;
 
 
     /**
@@ -418,6 +424,31 @@ export interface BaseEntityCollection<M extends Record<string, unknown> = Record
      * When defined, the backend enforces access control policies.
      */
     securityRules?: SecurityRule[];
+
+    /**
+     * Collection-scoped component overrides. These take precedence over
+     * global overrides set on `<Rebase>`, but only within this collection's
+     * views (entity form, detail view, table, empty state, etc.).
+     *
+     * Only collection-scoped components (like `Entity.Form`, `Collection.EmptyState`,
+     * `Collection.Card`, etc.) can be overridden here. App-level components
+     * (like `Shell.AppBar`, `HomePage`) can only be overridden at the `<Rebase>` level.
+     *
+     * @example
+     * ```tsx
+     * const productsCollection: PostgresCollection = {
+     *     name: "Products",
+     *     slug: "products",
+     *     table: "products",
+     *     components: {
+     *         "Entity.Form": { Component: ProductCustomForm },
+     *         "Collection.Card": { Component: ProductCard },
+     *     },
+     *     properties: { ... }
+     * };
+     * ```
+     */
+    components?: CollectionComponentOverrideMap;
 }
 
 // ── Driver-specific collection types ──────────────────────────────────
@@ -742,7 +773,6 @@ export interface FilterPreset<Key extends string = string> {
 }
 
 
-
 /**
  * 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
@@ -1120,3 +1150,122 @@ export interface RolesOnlySecurityRule extends SecurityRuleBase {
     using?: never;
     withCheck?: never;
 }
+
+/**
+ * Configuration for authentication collections.
+ *
+ * Controls what happens when admins create users, reset passwords,
+ * and which entity actions are auto-injected.
+ *
+ * Use `auth: true` as sugar for `{ enabled: true }` with all defaults.
+ *
+ * @example Override user creation
+ * ```ts
+ * auth: {
+ *     enabled: true,
+ *     onCreateUser: async (values, ctx) => {
+ *         const hash = await ctx.hashPassword("welcome123");
+ *         return {
+ *             values: { ...values, passwordHash: hash, emailVerified: true },
+ *             temporaryPassword: "welcome123",
+ *         };
+ *     },
+ * }
+ * ```
+ *
+ * @example Disable the reset-password entity action
+ * ```ts
+ * auth: {
+ *     enabled: true,
+ *     actions: { resetPassword: false },
+ * }
+ * ```
+ *
+ * @group Models
+ */
+export interface AuthCollectionConfig {
+    /** Set to true to mark this collection as the authentication collection. */
+    enabled: boolean;
+
+    /**
+     * Called when an admin creates a user via the collection REST API.
+     *
+     * Default: generate password → hash → normalize email → save →
+     *          send invitation email (or return temp password if no email configured).
+     *
+     * Override to implement custom invitation flows, LDAP sync, etc.
+     */
+    onCreateUser?: (
+        values: Record<string, unknown>,
+        ctx: AuthCollectionContext
+    ) => Promise<AuthCollectionCreateResult>;
+
+    /**
+     * Called when an admin resets a user's password via the admin panel.
+     *
+     * Default: generate reset token → send email (or generate + return temp password).
+     * Override for custom reset flows.
+     */
+    onResetPassword?: (
+        userId: string,
+        ctx: AuthCollectionContext
+    ) => Promise<AuthCollectionResetResult>;
+
+    /**
+     * Control which auth-specific entity actions are auto-injected.
+     *
+     * Default: `{ resetPassword: true }` — the framework auto-injects
+     * the built-in `resetPasswordAction` into the collection's entity actions.
+     *
+     * Set to `false` to disable, or pass a custom `EntityAction` to replace the UI.
+     */
+    actions?: {
+        resetPassword?: boolean | EntityAction;
+    };
+}
+
+/**
+ * Context provided to collection-level auth hooks.
+ *
+ * This is a simplified facade over the server internals —
+ * it exposes only what's needed for custom auth flows without
+ * coupling collection config to internal interfaces.
+ *
+ * @group Models
+ */
+export interface AuthCollectionContext {
+    /** Hash a password using the configured algorithm (scrypt by default). */
+    hashPassword: (password: string) => Promise<string>;
+    /** Send an email. Only available when email service is configured. */
+    sendEmail?: (options: { to: string; subject: string; html: string; text?: string }) => Promise<void>;
+    /** Whether the email service is configured and available. */
+    emailConfigured: boolean;
+    /** The app name from email config (for templates). */
+    appName: string;
+    /** The base URL for password reset links. */
+    resetPasswordUrl: string;
+}
+
+/**
+ * Result of a collection-level `onCreateUser` hook.
+ * @group Models
+ */
+export interface AuthCollectionCreateResult {
+    /** Processed values to persist (must include passwordHash, NOT raw password). */
+    values: Record<string, unknown>;
+    /** If set, shown to the admin in the creation result dialog. */
+    temporaryPassword?: string;
+    /** Whether an invitation email was sent. */
+    invitationSent?: boolean;
+}
+
+/**
+ * Result of a collection-level `onResetPassword` hook.
+ * @group Models
+ */
+export interface AuthCollectionResetResult {
+    /** If set, shown to the admin. */
+    temporaryPassword?: string;
+    /** Whether a reset email was sent. */
+    invitationSent?: boolean;
+}