@rebasepro/server-core 0.0.1-canary.eae7889 → 0.1.0

package/dist/server-core/src/api/rest/api-generator.d.ts

@@ -1,5 +1,5 @@
 import { Hono } from "hono";
-import { DataDriver, EntityCollection } from "@rebasepro/types";
+import { DataDriver, EntityCollection, DataHooks } from "@rebasepro/types";
 import { HonoEnv } from "../types";
 /**
  * Lightweight REST API generator that leverages existing Rebase DataDriver.
@@ -9,13 +9,16 @@ export declare class RestApiGenerator {
     private collections;
     private router;
     private driver;
-    constructor(collections: EntityCollection[], driver: DataDriver);
+    private dataHooks?;
+    constructor(collections: EntityCollection[], driver: DataDriver, dataHooks?: DataHooks);
+    /** Build a BackendHookContext from a Hono context */
+    private buildHookContext;
     /**
      * Generate REST routes using existing DataDriver
      */
     generateRoutes(): Hono<HonoEnv>;
     /**
-     * Get the EntityFetchService from a driver if it exposes one (for include support)
+     * Get the typed RestFetchService from a driver if it exposes one (for include support).
      */
     private getFetchService;
     /**
@@ -61,4 +64,13 @@ export declare class RestApiGenerator {
      * Fetch single entity raw data without Entity wrapper (fallback)
      */
     private fetchRawEntity;
+    /**
+     * Apply data.afterRead hook to a single entity.
+     * Returns the transformed entity, or null to filter it out.
+     */
+    private applyAfterRead;
+    /**
+     * Apply data.afterRead hook to an array of entities, filtering out nulls.
+     */
+    private applyAfterReadBatch;
 }

package/dist/server-core/src/auth/admin-routes.d.ts

@@ -1,5 +1,6 @@
 import { Hono } from "hono";
 import { AuthModuleConfig } from "./routes";
+import type { BackendHooks } from "@rebasepro/types";
 interface AdminRouteOptions extends AuthModuleConfig {
     serviceKey?: string;
     /**
@@ -7,6 +8,10 @@ interface AdminRouteOptions extends AuthModuleConfig {
      * Invoked after the first admin user is promoted via POST /admin/bootstrap.
      */
     setBootstrapCompleted?: () => Promise<void>;
+    /**
+     * Backend-level hooks for intercepting admin data.
+     */
+    hooks?: BackendHooks;
 }
 import { HonoEnv } from "../api/types";
 /**

package/dist/server-core/src/auth/google-oauth.d.ts

@@ -6,9 +6,42 @@ export interface GoogleUserInfo {
     photoUrl: string | null;
     emailVerified: boolean;
 }
+export interface GoogleProviderConfig {
+    clientId: string;
+    /**
+     * The OAuth 2.0 client secret from Google Cloud Console.
+     *
+     * Required for the **authorization code flow** (Path 3), where the
+     * frontend sends an authorization `code` and the backend exchanges it
+     * server-side for tokens. This is the most secure flow because tokens
+     * never touch the browser.
+     *
+     * When omitted, only ID-token and access-token verification are available
+     * (Paths 1 & 2), which rely on the frontend obtaining tokens directly.
+     */
+    clientSecret?: string;
+}
 /**
- * Creates a Google OAuth Provider integration
+ * Creates a Google OAuth Provider integration.
+ *
+ * Supports three verification paths:
+ *
+ * **Path 1 – ID Token** (One Tap / Sign In With Google button):
+ *   Frontend sends `idToken`. Backend verifies cryptographically using
+ *   Google's public keys. No secret required.
+ *
+ * **Path 2 – Access Token** (popup via `initTokenClient`):
+ *   Frontend sends `accessToken`. Backend validates by calling Google's
+ *   userinfo endpoint. No secret required.
+ *
+ * **Path 3 – Authorization Code** (most secure, requires `clientSecret`):
+ *   Frontend sends `code` + `redirectUri`. Backend exchanges the code
+ *   server-side for an ID token using `clientId` + `clientSecret`, then
+ *   verifies the ID token. Tokens never touch the browser.
  */
-export declare function createGoogleProvider(clientId: string): OAuthProvider<{
-    idToken: string;
+export declare function createGoogleProvider(config: GoogleProviderConfig | string): OAuthProvider<{
+    idToken?: string;
+    accessToken?: string;
+    code?: string;
+    redirectUri?: string;
 }>;

package/dist/server-core/src/auth/index.d.ts

@@ -4,6 +4,7 @@ export type { JwtConfig, AccessTokenPayload } from "./jwt";
 export { hashPassword, verifyPassword, validatePasswordStrength } from "./password";
 export type { PasswordValidationResult } from "./password";
 export { createGoogleProvider } from "./google-oauth";
+export type { GoogleProviderConfig } from "./google-oauth";
 export { createLinkedinProvider } from "./linkedin-oauth";
 export { createGitHubProvider } from "./github-oauth";
 export { createMicrosoftProvider } from "./microsoft-oauth";

package/dist/server-core/src/cron/cron-scheduler.d.ts

@@ -2,6 +2,16 @@ import type { CronJobStatus, CronJobLogEntry } from "@rebasepro/types";
 import type { RebaseClient } from "@rebasepro/client";
 import type { LoadedCronJob } from "./cron-loader";
 import type { CronStore } from "./cron-store";
+/**
+ * Validates a standard 5-field cron expression structurally and semantically.
+ * Returns `{ valid: true }` or `{ valid: false, reason: string }`.
+ */
+export declare function validateCronExpression(schedule: string): {
+    valid: true;
+} | {
+    valid: false;
+    reason: string;
+};
 export declare class CronScheduler {
     private jobs;
     private started;
@@ -19,6 +29,12 @@ export declare class CronScheduler {
     setStore(store: CronStore): void;
     /**
      * Register a batch of loaded cron jobs.
+     *
+     * If the scheduler is already started, newly registered jobs are
+     * automatically scheduled (so late-registered jobs don't sit idle).
+     *
+     * Validates the cron schedule on registration — invalid schedules
+     * are rejected with a warning and the job is NOT registered.
      */
     registerJobs(loadedJobs: LoadedCronJob[]): void;
     /**
@@ -27,6 +43,9 @@ export declare class CronScheduler {
     start(): void;
     /**
      * Stop the scheduler and clear all timers.
+     *
+     * Currently-executing handlers run to completion (they are async),
+     * but no further scheduling occurs after stop.
      */
     stop(): void;
     /**
@@ -52,10 +71,36 @@ export declare class CronScheduler {
     setJobEnabled(id: string, enabled: boolean): CronJobStatus | undefined;
     /**
      * Manually trigger a job execution immediately.
+     *
+     * Returns `undefined` if the job doesn't exist.
+     * If the job is currently executing, returns the log entry with
+     * a `skipped: true` result rather than running concurrently.
      */
     triggerJob(id: string): Promise<CronJobLogEntry | undefined>;
+    /**
+     * Schedule the next execution for a job.
+     *
+     * Safety guarantees:
+     * 1. Clears any existing timer first (prevents leaked/duplicate timers)
+     * 2. Enforces a minimum delay to prevent tight loops from jitter
+     * 3. Unref's the timer so it doesn't prevent process exit
+     * 4. Re-checks enabled & started state before executing
+     * 5. Concurrency guard prevents overlapping handler executions
+     */
     private scheduleNext;
+    /**
+     * Stop a single job's timer and clear its next run state.
+     */
     private stopJob;
+    /**
+     * Execute a job's handler with full isolation and safety.
+     *
+     * - Sets a concurrency flag to prevent overlapping runs
+     * - Wraps handler in a timeout race
+     * - Captures all logs, errors, and results
+     * - Persists to store (non-blocking) if available
+     * - Always restores state even on catastrophic errors
+     */
     private executeJob;
     private toStatus;
 }

package/dist/server-core/src/cron/index.d.ts

@@ -1,6 +1,6 @@
 export { loadCronJobsFromDirectory } from "./cron-loader";
 export type { LoadedCronJob } from "./cron-loader";
-export { CronScheduler } from "./cron-scheduler";
+export { CronScheduler, validateCronExpression } from "./cron-scheduler";
 export { createCronRoutes } from "./cron-routes";
 export { createCronStore } from "./cron-store";
 export type { CronStore } from "./cron-store";

package/dist/server-core/src/init.d.ts

@@ -1,4 +1,4 @@
-import { DataDriver, EntityCollection, BackendBootstrapper, BootstrappedAuth, RealtimeProvider, HealthCheckResult } from "@rebasepro/types";
+import { DataDriver, EntityCollection, BackendBootstrapper, BootstrappedAuth, RealtimeProvider, HealthCheckResult, BackendHooks } from "@rebasepro/types";
 import { BackendCollectionRegistry } from "./collections/BackendCollectionRegistry";
 import { DriverRegistry } from "./services/driver-registry";
 import { Server } from "http";
@@ -29,6 +29,7 @@ export interface RebaseAuthConfig {
     email?: EmailConfig;
     google?: {
         clientId: string;
+        clientSecret?: string;
     };
     linkedin?: {
         clientId: string;
@@ -129,6 +130,15 @@ export interface RebaseBackendConfig {
         /** Allowed origins for CSRF validation. */
         origin: string | string[] | ((origin: string) => boolean);
     };
+    /**
+     * Backend-level hooks for intercepting admin data (users, roles)
+     * at the API boundary. These run server-side after database reads
+     * and before API responses are sent.
+     *
+     * Complement the per-collection `EntityCallbacks` system which
+     * handles collection CRUD operations.
+     */
+    hooks?: BackendHooks;
 }
 export interface RebaseBackendInstance {
     driverRegistry: DriverRegistry;

package/dist/types/src/controllers/auth.d.ts

@@ -80,8 +80,14 @@ export type AuthController<USER extends User = User, ExtraData = unknown> = {
 export interface AuthControllerExtended<USER extends User = User, ExtraData = unknown> extends AuthController<USER, ExtraData> {
     /** Login with email and password */
     emailPasswordLogin?(email: string, password: string): Promise<void>;
-    /** Login with a Google ID token or trigger Google popup */
-    googleLogin?(idToken: string): Promise<void>;
+    /** Login with a Google token or authorization code */
+    googleLogin?: {
+        (token: string, tokenType?: "idToken" | "accessToken"): Promise<void>;
+        (payload: {
+            code: string;
+            redirectUri: string;
+        }): Promise<void>;
+    };
     /** Register a new user */
     register?(email: string, password: string, displayName?: string): Promise<void>;
     /** Skip login (for anonymous access if enabled) */

package/dist/types/src/controllers/client.d.ts

@@ -167,4 +167,17 @@ export interface RebaseClient<DB = unknown> {
     email?: EmailService;
     /** Admin API for user and role 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.
+     */
+    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"`).
+     */
+    ws?: unknown;
 }

package/dist/types/src/controllers/collection_registry.d.ts

@@ -36,7 +36,8 @@ export type CollectionRegistryController<DB = Record<string, unknown>, EC extend
      * Retrieve all the related parent collection ids for a given path
      * @param path
      */
-    getParentCollectionIds: (path: string) => string[];
+    getParentCollectionSlugs: (path: string) => string[];
+    getParentEntityIds: (path: string) => string[];
     /**
      * Resolve paths from a list of ids
      * @param ids

package/dist/types/src/controllers/data_driver.d.ts

@@ -144,12 +144,19 @@ export interface DataDriver {
         path: string;
         databaseId?: string;
         collection: EntityCollection;
-        parentCollectionIds?: string[];
+        parentCollectionSlugs?: string[];
+        parentEntityIds?: string[];
     }) => Promise<boolean>;
     /**
      * Flag to indicate if the driver has requested the initialization of the text search index
      */
     needsInitTextSearch?: boolean;
+    /**
+     * Optional REST-optimised fetch service. When present, the REST API
+     * generator uses these methods instead of the generic `fetchEntity` /
+     * `fetchCollection` pipeline, enabling include-aware eager-loading.
+     */
+    restFetchService?: RestFetchService;
     /**
      * Return the admin capabilities of this driver.
      * @see SQLAdmin
@@ -158,3 +165,31 @@ export interface DataDriver {
      */
     admin?: import("../types/backend").DatabaseAdmin;
 }
+/**
+ * REST-optimised fetch service exposed by drivers that support
+ * eager-loading of relations via `include`.
+ *
+ * The methods return flattened rows (`{ id, ...columns }`) rather
+ * than the `Entity<M>` wrapper used by the generic DataDriver API.
+ *
+ * @group DataDriver
+ */
+export interface RestFetchService {
+    /**
+     * Fetch a collection of flattened entities with optional relation includes.
+     */
+    fetchCollectionForRest(collectionPath: string, options?: {
+        filter?: FilterValues<string>;
+        orderBy?: string;
+        order?: "desc" | "asc";
+        limit?: number;
+        offset?: number;
+        startAfter?: Record<string, unknown>;
+        searchString?: string;
+        databaseId?: string;
+    }, include?: string[]): Promise<Record<string, unknown>[]>;
+    /**
+     * Fetch a single flattened entity with optional relation includes.
+     */
+    fetchEntityForRest(collectionPath: string, entityId: string | number, include?: string[], databaseId?: string): Promise<Record<string, unknown> | null>;
+}

package/dist/types/src/controllers/navigation.d.ts

@@ -144,17 +144,18 @@ export interface AppView {
      * It will still be accessible if you reach the specified path
      */
     hideFromNavigation?: boolean;
+    /**
+     * Navigation group for this view.
+     * Views sharing the same group name will be visually grouped
+     * together in the drawer and home page. If not set, the view
+     * falls into the default "Views" group.
+     */
+    group?: string;
     /**
      * Component to be rendered. This can be any React component, and can use
      * any of the provided hooks
      */
     view: React.ReactNode;
-    /**
-     * Optional field used to group top level navigation entries under a
-     * navigation view.
-     * This prop is ignored for admin views.
-     */
-    group?: string;
     /**
      * If true, a wildcard route (slug/*) is automatically registered
      * alongside the base route, enabling nested navigation within this view.
@@ -193,6 +194,17 @@ export interface NavigationGroupMapping {
      * List of collection ids or view paths that belong to this group.
      */
     entries: string[];
+    /**
+     * Configure which groups start collapsed.
+     * Set to `true` to collapse in both drawer and home page,
+     * or use an object to control each independently.
+     *
+     * @defaultValue false (expanded)
+     */
+    collapsedByDefault?: boolean | {
+        drawer?: boolean;
+        home?: boolean;
+    };
 }
 export interface NavigationEntry {
     id: string;

package/dist/types/src/controllers/registry.d.ts

@@ -3,7 +3,7 @@ import type { EntityCollection } from "../types/collections";
 import type { EntityCollectionsBuilder } from "../types/builders";
 import type { EntityCustomView } from "../types/entity_views";
 import type { EntityAction } from "../types/entity_actions";
-import type { AppView } from "./navigation";
+import type { AppView, NavigationGroupMapping } from "./navigation";
 /**
  * Options to enable the built-in collection editor.
  * When provided to `<RebaseCMS>`, the editor is auto-wired as a native feature.
@@ -25,6 +25,14 @@ export interface RebaseCMSConfig<EC extends EntityCollection = any> {
     entityViews?: EntityCustomView<any>[];
     entityActions?: EntityAction[];
     plugins?: any[];
+    /**
+     * Centralized configuration for how collections and views are grouped
+     * in the navigation sidebar and home page.
+     * Each mapping defines a named group and the collection/view slugs
+     * that belong to it. The array order determines group display order.
+     * Entry order within each group determines card order.
+     */
+    navigationGroupMappings?: NavigationGroupMapping[];
     /**
      * Enable the built-in visual collection/schema editor.
      * Pass `true` for zero-config, or an options object for fine-grained control.

package/dist/types/src/controllers/side_entity_controller.d.ts

@@ -62,6 +62,13 @@ export interface EntitySidePanelProps<M extends Record<string, unknown> = Record
      * Allow the user to open the entity fullscreen
      */
     allowFullScreen?: boolean;
+    /**
+     * Pre-populate the form with these values when creating a new entity.
+     * Only applied when `entityId` is not set (i.e. the form is in "new" mode).
+     * Useful for actions that fetch data from an external source (e.g. a URL)
+     * and want to pre-fill the document before the user saves.
+     */
+    defaultValues?: Partial<M>;
 }
 /**
  * Controller to open the side dialog displaying entity forms

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

@@ -3,6 +3,7 @@ import type { AuthController } from "./controllers/auth";
 import type { StorageSource } from "./controllers/storage";
 import type { UserConfigurationPersistence } from "./controllers/local_config_persistence";
 import type { DatabaseAdmin } from "./types/backend";
+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";
@@ -12,6 +13,22 @@ import type { UserManagementDelegate } from "./types/user_management_delegate";
  * @group Hooks and utilities
  */
 export type RebaseCallContext<USER extends User = User> = {
+    /**
+     * The Rebase client instance.
+     * Available in all entity callbacks (beforeSave, afterSave, afterRead,
+     * beforeDelete, afterDelete) and in CollectionActionsProps via context.
+     * Use it to call backend functions, access data, storage, etc.
+     *
+     * @example
+     * // In a beforeSave callback:
+     * const result = await context.client.functions.invoke('my-function', { ... });
+     *
+     * @example
+     * // In a CollectionAction component:
+     * const { client } = props.context;
+     * const result = await client.functions.invoke('extract-job', { url });
+     */
+    client: RebaseClient<any>;
     /**
      * Unified data access — `context.data.products.create(...)`.
      * Access any collection as a dynamic property.

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;
+}