@rebasepro/server-core 0.4.0 → 0.6.0

package/README.md

@@ -1,40 +1,77 @@
-# @rebasepro/backend
+# @rebasepro/server-core
 
-PostgreSQL and Drizzle ORM backend implementation for Rebase.
-
-This package provides a complete backend solution for Rebase applications using PostgreSQL as the database and Drizzle ORM for type-safe database operations.
+Database-agnostic backend core for Rebase.
 
 ## Installation
 
 ```bash
-npm install @rebasepro/backend @rebasepro/core
+pnpm add @rebasepro/server-core
 ```
 
-## Usage
+## What This Package Does
 
-```typescript
-import { createBackend } from "@rebasepro/backend";
+This is the central orchestrator for any Rebase backend. It provides the framework-level plumbing — HTTP routing (Hono), authentication middleware, storage, email, cron jobs, custom functions, and the REST/GraphQL API generator — without being coupled to any specific database. Database implementations are plugged in via driver packages like `@rebasepro/server-postgresql` or `@rebasepro/server-mongodb`.
 
-const backend = createBackend({
-  connectionString: "postgresql://user:password@localhost:5432/database",
-  schema: "public",
-  debug: true
-});
-```
+## Key Exports
+
+| Export | Description |
+|--------|-------------|
+| `initializeRebaseBackend(config)` | Main entry point. Wires up drivers, auth, storage, API routes, cron, and custom functions. Returns a `RebaseBackendInstance`. |
+| `rebase` | Server-side singleton (`RebaseClient`). Available after init. Admin-level access to data, auth, email, and storage. |
+| `loadEnv()` | Validates `process.env` against the Rebase env schema (Zod). Auto-generates dev secrets. Supports `extend` for custom vars. |
+| `serveSPA(app, config)` | Mounts SPA static-file serving + index.html fallback on a Hono app. |
+| `RebaseBackendConfig` | Config type for `initializeRebaseBackend`. |
+| `RebaseAuthConfig` | Auth config type (JWT, OAuth providers, hooks, service key). |
+| `RebaseBackendInstance` | Return type — includes `driver`, `healthCheck()`, `shutdown()`, `cronScheduler`, `storageController`, etc. |
+| `RebaseEnv` | Zod-inferred type of validated environment variables. |
+| `z` | Re-exported Zod instance for extending `loadEnv`. |
+| `_setRebaseMock` / `_resetRebaseMock` | Test helpers to mock the `rebase` singleton (NODE_ENV=test only). |
 
-## Features
+Also re-exports all abstract interfaces (`DatabaseAdapter`, `AuthAdapter`, `DataDriver`, etc.), API types (`HonoEnv`, `ApiConfig`), auth module, email module, storage module, history module, cron module, custom functions, logging utilities, and driver registry.
 
-- PostgreSQL database support
-- Drizzle ORM integration
-- Type-safe database operations
-- Full Rebase compatibility
-- Migration support
-- Connection pooling
+## Quick Start
 
-## Development
+```typescript
+import { serve } from "@hono/node-server";
+import { Hono } from "hono";
+import { initializeRebaseBackend, loadEnv, serveSPA } from "@rebasepro/server-core";
+import { createPostgresAdapter } from "@rebasepro/server-postgresql";
 
-This package is part of the Rebase monorepo. For development instructions, see the main repository README.
+// 1. Load and validate environment
+const env = loadEnv();
+
+// 2. Create Hono app + HTTP server
+const app = new Hono();
+const server = serve({ fetch: app.fetch, port: env.PORT });
+
+// 3. Initialize Rebase
+const backend = await initializeRebaseBackend({
+  app,
+  server,
+  database: createPostgresAdapter({ connection: db, schema }),
+  collections: myCollections,
+  auth: {
+    collection: defaultUsersCollection,
+    jwtSecret: env.JWT_SECRET,
+    allowRegistration: env.ALLOW_REGISTRATION,
+    serviceKey: env.REBASE_SERVICE_KEY,
+    google: { clientId: env.GOOGLE_CLIENT_ID },
+  },
+  storage: { type: "s3", bucket: env.S3_BUCKET },
+  functionsDir: "./functions",
+  cronsDir: "./crons",
+});
+
+// 4. Optionally serve a frontend SPA
+serveSPA(app, { frontendPath: "./frontend/dist" });
+```
 
-## License
+## Related Packages
 
-MIT
+| Package | Role |
+|---------|------|
+| `@rebasepro/server-postgresql` | PostgreSQL database driver (Drizzle ORM) |
+| `@rebasepro/server-mongodb` | MongoDB database driver |
+| `@rebasepro/types` | Shared type definitions (`DataDriver`, `EntityCollection`, etc.) |
+| `@rebasepro/client` | Client SDK used internally by the `rebase` singleton |
+| `@rebasepro/common` | Shared utilities and default collections |

package/dist/{server-core/src/api → api}/errors.d.ts

@@ -1,4 +1,5 @@
-import { ErrorHandler } from "hono";
+import type { ErrorHandler } from "hono";
+import type { HonoEnv } from "./types";
 /**
  * Standardized API error class.
  * Throw this from any route handler — the errorHandler middleware
@@ -26,10 +27,27 @@ export interface ErrorResponse {
         message: string;
         code: string;
         details?: unknown;
+        /** Request correlation ID for tracing (echoes X-Request-ID). */
+        requestId?: string;
     };
 }
+/**
+ * General shape of errors that flow through the API error handler.
+ * Extends Error with optional HTTP status, error code, and details.
+ */
+export interface RebaseApiError extends Error {
+    statusCode?: number;
+    code?: string;
+    details?: unknown;
+}
+/**
+ * Type guard for errors that carry optional API metadata (statusCode, code, details).
+ * Returns true for any Error instance — the optional properties are then
+ * checked via normal property access.
+ */
+export declare function isRebaseApiError(error: unknown): error is RebaseApiError;
 /**
  * Hono error-handling middleware (`app.onError`).
  * Converts any error into the canonical `{ error: { message, code } }` shape.
  */
-export declare const errorHandler: ErrorHandler;
+export declare const errorHandler: ErrorHandler<HonoEnv>;

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

@@ -1,5 +1,5 @@
 import { Hono } from "hono";
-import { DataDriver, EntityCollection, DataHooks } from "@rebasepro/types";
+import { AuthAdapter, DataDriver, EntityCollection, DataHooks } from "@rebasepro/types";
 import { HonoEnv } from "../types";
 /**
  * Lightweight REST API generator that leverages existing Rebase DataDriver.
@@ -10,7 +10,8 @@ export declare class RestApiGenerator {
     private router;
     private driver;
     private dataHooks?;
-    constructor(collections: EntityCollection[], driver: DataDriver, dataHooks?: DataHooks);
+    private authAdapter?;
+    constructor(collections: EntityCollection[], driver: DataDriver, dataHooks?: DataHooks, authAdapter?: AuthAdapter);
     /** Build a BackendHookContext from a Hono context */
     private buildHookContext;
     /**
@@ -23,6 +24,11 @@ export declare class RestApiGenerator {
      * No-ops if the request is not authenticated via an API key.
      */
     private enforceApiKeyPermission;
+    /**
+     * Get the request-scoped driver. Throws if none is set — never falls
+     * back to the unscoped `this.driver` to avoid bypassing RLS/auth.
+     */
+    private getScopedDriver;
     /**
      * Get the typed RestFetchService from a driver if it exposes one (for include support).
      */

package/dist/{server-core/src/api → api}/types.d.ts

@@ -16,6 +16,8 @@ export type HonoEnv = {
         driver?: DataDriver;
         /** Set when the request is authenticated via a Service API Key. */
         apiKey?: ApiKeyMasked;
+        /** Unique request correlation ID (generated or propagated from X-Request-ID header). */
+        requestId?: string;
     };
 };
 /**

package/dist/auth/admin-user-ops.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Admin User Operations
+ *
+ * Shared utilities and orchestration for admin-initiated user management
+ * (user creation via REST API, password reset via admin panel).
+ *
+ * Hook resolution order:
+ * 1. Collection-level hook (`auth.onCreateUser` on the collection) — closest to the data
+ * 2. Backend-level hook (`AuthHooks.onAdminCreateUser`) — global override
+ * 3. Built-in default — framework fallback
+ */
+import type { AuthRepository } from "./interfaces";
+import type { EmailService, EmailConfig } from "../email";
+import type { ResolvedAuthHooks } from "./auth-hooks";
+import type { AuthCollectionConfig } from "@rebasepro/types";
+/**
+ * Generate a cryptographically secure random password that meets strength requirements.
+ *
+ * 16 characters, guaranteed at least one uppercase, one lowercase, one digit.
+ * Ambiguous characters (0, O, 1, l, I) are excluded.
+ */
+export declare function generateSecurePassword(): string;
+/**
+ * Generate a cryptographically secure random token (80 hex characters).
+ */
+export declare function generateSecureToken(): string;
+/**
+ * Hash a token for database storage using SHA-256.
+ */
+export declare function hashToken(token: string): string;
+/**
+ * Context needed by admin user creation / password reset operations.
+ */
+export interface AdminUserContext {
+    authRepo: AuthRepository;
+    emailService?: EmailService;
+    emailConfig?: EmailConfig;
+    resolvedHooks: ResolvedAuthHooks;
+    /** The parsed auth config from the collection (if `auth` is an object, not just `true`). */
+    collectionAuthConfig?: AuthCollectionConfig;
+}
+/**
+ * Result of preparing user values for admin-initiated creation.
+ */
+export interface AdminUserPrepareResult {
+    /** Values ready for `driver.saveEntity()`. */
+    values: Record<string, unknown>;
+    /** The cleartext password (for returning to admin or sending via email). */
+    clearPassword?: string;
+    /** Whether the hook already handled the invitation email. */
+    hookHandledEmail: boolean;
+    /** Whether an invitation was sent (only relevant when hookHandledEmail is true). */
+    invitationSent: boolean;
+}
+/**
+ * Prepare user values for an admin-initiated user creation.
+ *
+ * Resolution order:
+ * 1. Collection-level `auth.onCreateUser` — closest to the data
+ * 2. Backend-level `AuthHooks.onAdminCreateUser` — global override
+ * 3. Built-in default — generate password → hash → normalize email
+ *
+ * The caller is responsible for persisting (via `driver.saveEntity()`).
+ */
+export declare function prepareAdminUserValues(body: Record<string, unknown>, ctx: AdminUserContext): Promise<AdminUserPrepareResult>;
+/**
+ * Handle post-creation work for admin-created users.
+ *
+ * Sends an invitation email (password-reset link) if email is configured
+ * and no explicit password was provided. Falls back to returning the
+ * temporary password if email fails or is not configured.
+ */
+export declare function finalizeAdminUserCreation(entity: {
+    id: string;
+    values: Record<string, unknown>;
+}, clearPassword: string | undefined, ctx: AdminUserContext): Promise<{
+    temporaryPassword?: string;
+    invitationSent: boolean;
+}>;

package/dist/{server-core/src/auth → auth}/api-keys/index.d.ts

@@ -6,12 +6,12 @@
  *
  * @module
  */
-export type { ApiKey, ApiKeyMasked, ApiKeyPermission, ApiKeyWithSecret, CreateApiKeyRequest, UpdateApiKeyRequest, } from "./api-key-types";
+export type { ApiKey, ApiKeyMasked, ApiKeyPermission, ApiKeyWithSecret, CreateApiKeyRequest, UpdateApiKeyRequest } from "./api-key-types";
 export { createApiKeyStore } from "./api-key-store";
 export type { ApiKeyStore } from "./api-key-store";
 export { isApiKeyToken, validateApiKey } from "./api-key-middleware";
 export type { ApiKeyAuthOptions } from "./api-key-middleware";
-export { httpMethodToOperation, isOperationAllowed, } from "./api-key-permission-guard";
+export { httpMethodToOperation, isOperationAllowed } from "./api-key-permission-guard";
 export type { ApiKeyOperation } from "./api-key-permission-guard";
 export { createApiKeyRoutes } from "./api-key-routes";
 export type { ApiKeyRouteOptions } from "./api-key-routes";

package/dist/{server-core/src/auth → auth}/auth-hooks.d.ts

@@ -38,6 +38,7 @@
  */
 import type { PasswordValidationResult } from "./password";
 import type { AuthRepository, UserData, CreateUserData } from "./interfaces";
+import type { EmailService, EmailConfig } from "../email";
 /**
  * Authentication method identifier for lifecycle hooks.
  */
@@ -176,22 +177,49 @@ export interface AuthHooks {
      * This is fire-and-forget — errors are logged but do not fail the request.
      */
     afterUserDelete?(userId: string): Promise<void>;
+    /**
+     * Optional hook to customize or override the default user creation flow via the admin panel/REST API.
+     * When provided, this replaces the built-in password generation, hashing, and invitation email logic.
+     */
+    onAdminCreateUser?(values: Record<string, unknown>, ctx: {
+        authRepo: AuthRepository;
+        emailService?: EmailService;
+        emailConfig?: EmailConfig;
+        hashPassword: (password: string) => Promise<string>;
+    }): Promise<{
+        values: Record<string, unknown>;
+        temporaryPassword?: string;
+        invitationSent?: boolean;
+    }>;
+    /**
+     * Optional hook to customize or override the default password reset flow via the admin panel.
+     * When provided, this replaces the built-in password reset token generation, hashing, and email logic.
+     */
+    onAdminResetPassword?(userId: string, ctx: {
+        authRepo: AuthRepository;
+        emailService?: EmailService;
+        emailConfig?: EmailConfig;
+    }): Promise<{
+        temporaryPassword?: string;
+        invitationSent?: boolean;
+    }>;
 }
 /**
- * Resolved auth operations — every method is guaranteed to exist.
+ * Resolved auth hooks — password operations are guaranteed to exist,
+ * all other hooks are passed through as-is (optional).
+ *
  * Created by `resolveAuthHooks()` which merges user hooks
  * with built-in defaults.
+ *
+ * Consumers should use the resolved object exclusively —
+ * never access the raw `AuthHooks` directly.
  */
-export interface ResolvedAuthOperations {
-    hashPassword(password: string): Promise<string>;
-    verifyPassword(password: string, storedHash: string): Promise<boolean>;
-    validatePasswordStrength(password: string): PasswordValidationResult;
-}
+export type ResolvedAuthHooks = Required<Pick<AuthHooks, "hashPassword" | "verifyPassword" | "validatePasswordStrength">> & Omit<AuthHooks, "hashPassword" | "verifyPassword" | "validatePasswordStrength">;
 /**
  * Merge user-provided hooks with the built-in defaults to produce
- * a complete set of resolved operations.
+ * a complete set of resolved hooks.
  *
  * This is the single point where defaults are applied — all consumers
- * call this once and use the resolved operations throughout.
+ * call this once and use the resolved hooks throughout.
  */
-export declare function resolveAuthHooks(hooks?: AuthHooks): ResolvedAuthOperations;
+export declare function resolveAuthHooks(hooks?: AuthHooks): ResolvedAuthHooks;

package/dist/{server-core/src/auth → auth}/builtin-auth-adapter.d.ts

@@ -6,10 +6,10 @@
  * when the user passes a plain `RebaseAuthConfig` object.
  *
  * This is NOT a rewrite — it delegates to the existing `createAuthRoutes()`,
- * `createAdminRoutes()`, and `verifyAccessToken()` functions. The goal is to
+ * `createResetPasswordRoute()`, and `verifyAccessToken()` functions. The goal is to
  * present the same functionality through the pluggable `AuthAdapter` contract.
  */
-import type { AuthAdapter, BackendHooks } from "@rebasepro/types";
+import type { AuthAdapter } from "@rebasepro/types";
 import type { AuthRepository, OAuthProvider } from "./interfaces";
 import type { AuthHooks } from "./auth-hooks";
 import type { EmailService, EmailConfig } from "../email";
@@ -34,10 +34,10 @@ export interface BuiltinAuthAdapterConfig {
     oauthProviders?: OAuthProvider<any>[];
     /** Static service key for server-to-server auth. */
     serviceKey?: string;
-    /** Backend hooks for intercepting admin data. */
-    hooks?: BackendHooks;
     /** Auth hooks for customizing password, credentials, lifecycle, etc. */
     authHooks?: AuthHooks;
+    /** The parsed auth config from the collection (if `auth` is an object, not just `true`). */
+    collectionAuthConfig?: import("@rebasepro/types").AuthCollectionConfig;
 }
 /**
  * Create the built-in Rebase auth adapter.

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

@@ -3,8 +3,10 @@ export { configureJwt, generateAccessToken, verifyAccessToken, generateRefreshTo
 export type { JwtConfig, AccessTokenPayload } from "./jwt";
 export { hashPassword, verifyPassword, validatePasswordStrength } from "./password";
 export type { PasswordValidationResult } from "./password";
-export type { AuthHooks, AuthMethod, ResolvedAuthOperations } from "./auth-hooks";
+export type { AuthHooks, AuthMethod, ResolvedAuthHooks } from "./auth-hooks";
 export { resolveAuthHooks } from "./auth-hooks";
+export { generateSecurePassword, generateSecureToken, hashToken, prepareAdminUserValues, finalizeAdminUserCreation } from "./admin-user-ops";
+export type { AdminUserContext, AdminUserPrepareResult } from "./admin-user-ops";
 export { createGoogleProvider } from "./google-oauth";
 export type { GoogleProviderConfig } from "./google-oauth";
 export { createLinkedinProvider } from "./linkedin-oauth";
@@ -22,7 +24,8 @@ export { requireAuth, requireAdmin, optionalAuth, extractUserFromToken, createAu
 export type { AuthMiddlewareOptions, AuthResult } from "./middleware";
 export { createAuthRoutes } from "./routes";
 export type { AuthModuleConfig } from "./routes";
-export { createAdminRoutes } from "./admin-routes";
+export { createResetPasswordRoute } from "./reset-password-admin";
+export type { ResetPasswordRouteConfig } from "./reset-password-admin";
 export { createRateLimiter, defaultAuthLimiter, strictAuthLimiter, createApiKeyRateLimiter, apiKeyKeyGenerator } from "./rate-limiter";
 export { createApiKeyStore, createApiKeyRoutes, isApiKeyToken, validateApiKey, httpMethodToOperation, isOperationAllowed } from "./api-keys";
 export type { ApiKey, ApiKeyMasked, ApiKeyPermission, ApiKeyWithSecret, CreateApiKeyRequest, UpdateApiKeyRequest, ApiKeyStore, ApiKeyOperation } from "./api-keys";

package/dist/{server-core/src/auth → auth}/jwt.d.ts

@@ -9,6 +9,16 @@ export interface AccessTokenPayload {
     uid?: string;
     /** Authentication Assurance Level: aal1 = password/oauth, aal2 = MFA verified */
     aal?: "aal1" | "aal2";
+    /** Email claim from the JWT, if present */
+    email?: string;
+    /** Display name claim from the JWT, if present */
+    displayName?: string;
+    /** Photo URL claim from the JWT, if present */
+    photoURL?: string;
+    /** Whether MFA has been verified for this session */
+    mfa_verified?: boolean;
+    /** Authentication Methods Reference — list of methods used (e.g. 'pwd', 'otp') */
+    amr?: string[];
 }
 /**
  * Configure JWT settings - call this during initialization.

package/dist/auth/mfa-routes.d.ts

@@ -0,0 +1,6 @@
+import { Hono } from "hono";
+import { z } from "zod";
+import { HonoEnv } from "../api/types";
+import type { AuthModuleConfig } from "./routes";
+import { resolveAuthHooks } from "./auth-hooks";
+export declare function mountMfaRoutes(router: Hono<HonoEnv>, config: AuthModuleConfig, ops: ReturnType<typeof resolveAuthHooks>, parseBody: <T>(schema: z.ZodSchema<T>, body: unknown) => T): void;

package/dist/auth/reset-password-admin.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Standalone admin endpoint for resetting a user's password.
+ *
+ * Hook resolution order:
+ * 1. Collection-level hook (`auth.onResetPassword` on the collection)
+ * 2. Backend-level hook (`AuthHooks.onAdminResetPassword`)
+ * 3. Built-in default (send reset email, or generate temp password)
+ */
+import { Hono } from "hono";
+import type { AuthRepository } from "./interfaces";
+import type { AuthHooks } from "./auth-hooks";
+import type { EmailService, EmailConfig } from "../email";
+import type { HonoEnv } from "../api/types";
+import type { AuthCollectionConfig } from "@rebasepro/types";
+export interface ResetPasswordRouteConfig {
+    authRepo: AuthRepository;
+    emailService?: EmailService;
+    emailConfig?: EmailConfig;
+    serviceKey?: string;
+    authHooks?: AuthHooks;
+    /** The parsed auth config from the collection, if available. */
+    collectionAuthConfig?: AuthCollectionConfig;
+}
+/**
+ * Create a standalone admin route for resetting user passwords.
+ *
+ * Mounts: POST /users/:userId/reset-password
+ */
+export declare function createResetPasswordRoute(config: ResetPasswordRouteConfig): Hono<HonoEnv>;

package/dist/auth/session-routes.d.ts

@@ -0,0 +1,25 @@
+import { Hono } from "hono";
+import { z } from "zod";
+import { HonoEnv } from "../api/types";
+import type { AuthModuleConfig } from "./routes";
+import { resolveAuthHooks } from "./auth-hooks";
+interface SessionRoutesConfig {
+    router: Hono<HonoEnv>;
+    config: AuthModuleConfig;
+    ops: ReturnType<typeof resolveAuthHooks>;
+    parseBody: <T>(schema: z.ZodSchema<T>, body: unknown) => T;
+    buildAuthResponse: (user: {
+        id: string;
+        email: string;
+        displayName?: string | null;
+        photoUrl?: string | null;
+        metadata?: Record<string, unknown> | null;
+    }, roleIds: string[], accessToken: string, refreshToken: string) => unknown;
+    createSessionAndTokens: (userId: string, userAgent: string, ipAddress: string) => Promise<{
+        roleIds: string[];
+        accessToken: string;
+        refreshToken: string;
+    }>;
+}
+export declare function mountSessionRoutes(opts: SessionRoutesConfig): void;
+export {};

package/dist/backend-CIxN4FVm.js

@@ -0,0 +1,15 @@
+import { createRequire as __createRequire } from "module";
+import "process";
+__createRequire(import.meta.url);
+//#region ../types/src/types/backend.ts
+/**
+* Type guard: does this admin support SQL operations?
+* @group Admin
+*/
+function isSQLAdmin(admin) {
+	return !!admin && typeof admin.executeSql === "function";
+}
+//#endregion
+export { isSQLAdmin as t };
+
+//# sourceMappingURL=backend-CIxN4FVm.js.map

package/dist/backend-CIxN4FVm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend-CIxN4FVm.js","names":[],"sources":["../../types/src/types/backend.ts"],"sourcesContent":["import type { Entity } from \"./entities\";\nimport type { EntityCollection, FilterValues, WhereFilterOp } from \"./collections\";\nimport type { AuthAdapter } from \"./auth_adapter\";\n\n// =============================================================================\n// DATABASE CONNECTION INTERFACES\n// =============================================================================\n\n/**\n * Abstract database connection interface.\n * Represents a connection to any database system.\n */\nexport interface DatabaseConnection {\n    /**\n     * Type identifier for this database (e.g., 'postgres', 'mongodb', 'mysql')\n     */\n    readonly type: string;\n\n    /**\n     * Whether the connection is currently active\n     */\n    readonly isConnected?: boolean;\n\n    /**\n     * Close the database connection and release resources.\n     */\n    close?(): Promise<void>;\n}\n\n// =============================================================================\n// QUERY BUILDING INTERFACES\n// =============================================================================\n\n/**\n * A single filter condition for database queries\n */\nexport interface QueryFilter {\n    field: string;\n    operator: WhereFilterOp;\n    value: unknown;\n}\n\n/**\n * Options for fetching a collection of entities\n */\nexport interface FetchCollectionOptions<M extends Record<string, unknown> = Record<string, unknown>> {\n    filter?: FilterValues<Extract<keyof M, string>>;\n    orderBy?: string;\n    order?: \"desc\" | \"asc\";\n    limit?: number;\n    offset?: number;\n    startAfter?: unknown;\n    searchString?: string;\n    databaseId?: string;\n    collection?: EntityCollection;\n}\n\n/**\n * Options for searching entities\n */\nexport interface SearchOptions<M extends Record<string, unknown> = Record<string, unknown>> {\n    filter?: FilterValues<Extract<keyof M, string>>;\n    orderBy?: string;\n    order?: \"desc\" | \"asc\";\n    limit?: number;\n    databaseId?: string;\n    collection?: EntityCollection;\n}\n\n/**\n * Options for counting entities\n */\nexport interface CountOptions<M extends Record<string, unknown> = Record<string, unknown>> {\n    filter?: FilterValues<Extract<keyof M, string>>;\n    searchString?: string;\n    databaseId?: string;\n}\n\n/**\n * Abstract condition builder interface.\n * Implementations translate Rebase filter conditions to database-specific queries.\n *\n * Note: This interface can be implemented as instance methods or as a class with static methods.\n * For static implementations (like DrizzleConditionBuilder), use the ConditionBuilderStatic type.\n *\n * @template T The type of condition returned by the builder (e.g., SQL for PostgreSQL, Filter<Document> for MongoDB)\n */\nexport interface ConditionBuilder<T = unknown> {\n    /**\n     * Build filter conditions from Rebase FilterValues\n     */\n    buildFilterConditions<M extends Record<string, unknown>>(\n        filter: FilterValues<Extract<keyof M, string>>,\n        collectionPath: string,\n        ...args: unknown[]\n    ): T[];\n\n    /**\n     * Build search conditions for text search\n     */\n    buildSearchConditions(\n        searchString: string,\n        properties: Record<string, unknown>,\n        ...args: unknown[]\n    ): T[];\n\n    /**\n     * Combine multiple conditions with AND operator\n     */\n    combineConditionsWithAnd(conditions: T[]): T | undefined;\n\n    /**\n     * Combine multiple conditions with OR operator\n     */\n    combineConditionsWithOr(conditions: T[]): T | undefined;\n}\n\n/**\n * Static condition builder type for implementations using static methods.\n * Use this type when the class provides static methods rather than instance methods.\n *\n * @example\n * // DrizzleConditionBuilder satisfies this type\n * const builder: ConditionBuilderStatic<SQL> = DrizzleConditionBuilder;\n */\nexport type ConditionBuilderStatic<T = unknown> = {\n    buildFilterConditions<M extends Record<string, unknown>>(\n        filter: FilterValues<Extract<keyof M, string>>,\n        ...args: unknown[]\n    ): T[];\n    buildSearchConditions(\n        searchString: string,\n        properties: Record<string, unknown>,\n        ...args: unknown[]\n    ): T[];\n    combineConditionsWithAnd(conditions: T[]): T | undefined;\n    combineConditionsWithOr(conditions: T[]): T | undefined;\n};\n\n// =============================================================================\n// ENTITY REPOSITORY INTERFACES\n// =============================================================================\n\n/**\n * Abstract entity repository interface.\n * Handles all CRUD operations for entities in the database.\n *\n * Implementations should handle:\n * - Entity serialization/deserialization\n * - Relation resolution\n * - ID generation and conversion\n */\nexport interface EntityRepository {\n    /**\n     * Fetch a single entity by ID\n     */\n    fetchEntity<M extends Record<string, unknown>>(\n        collectionPath: string,\n        entityId: string | number,\n        databaseId?: string\n    ): Promise<Entity<M> | undefined>;\n\n    /**\n     * Fetch a collection of entities with optional filtering, ordering, and pagination\n     */\n    fetchCollection<M extends Record<string, unknown>>(\n        collectionPath: string,\n        options?: FetchCollectionOptions<M>\n    ): Promise<Entity<M>[]>;\n\n    /**\n     * Search entities by text\n     */\n    searchEntities<M extends Record<string, unknown>>(\n        collectionPath: string,\n        searchString: string,\n        options?: SearchOptions<M>\n    ): Promise<Entity<M>[]>;\n\n    /**\n     * Count entities in a collection\n     */\n    countEntities<M extends Record<string, unknown>>(\n        collectionPath: string,\n        options?: CountOptions<M>\n    ): Promise<number>;\n\n    /**\n     * Save an entity (create or update)\n     */\n    saveEntity<M extends Record<string, unknown>>(\n        collectionPath: string,\n        values: Partial<M>,\n        entityId?: string | number,\n        databaseId?: string\n    ): Promise<Entity<M>>;\n\n    /**\n     * Delete an entity by ID\n     */\n    deleteEntity(\n        collectionPath: string,\n        entityId: string | number,\n        databaseId?: string\n    ): Promise<void>;\n\n    /**\n     * Check if a field value is unique in a collection\n     */\n    checkUniqueField(\n        collectionPath: string,\n        fieldName: string,\n        value: unknown,\n        excludeEntityId?: string,\n        databaseId?: string\n    ): Promise<boolean>;\n\n}\n\n// =============================================================================\n// REALTIME INTERFACES\n// =============================================================================\n\n/**\n * Configuration for subscribing to a collection\n */\nexport interface CollectionSubscriptionConfig {\n    clientId: string;\n    path: string;\n    filter?: unknown;\n    orderBy?: string;\n    order?: \"desc\" | \"asc\";\n    limit?: number;\n    startAfter?: unknown;\n    databaseId?: string;\n    searchString?: string;\n}\n\n/**\n * Configuration for subscribing to a single entity\n */\nexport interface EntitySubscriptionConfig {\n    clientId: string;\n    path: string;\n    entityId: string | number;\n}\n\n/**\n * Abstract realtime provider interface.\n * Handles real-time subscriptions and notifications for entity changes.\n */\nexport interface RealtimeProvider {\n    /**\n     * Subscribe to collection changes\n     */\n    subscribeToCollection(\n        subscriptionId: string,\n        config: CollectionSubscriptionConfig,\n        callback?: (entities: Entity[]) => void\n    ): void;\n\n    /**\n     * Subscribe to single entity changes\n     */\n    subscribeToEntity(\n        subscriptionId: string,\n        config: EntitySubscriptionConfig,\n        callback?: (entity: Entity | null) => void\n    ): void;\n\n    /**\n     * Unsubscribe from a subscription\n     */\n    unsubscribe(subscriptionId: string): void;\n\n    /**\n     * Notify all relevant subscribers of an entity update\n     */\n    notifyEntityUpdate(\n        path: string,\n        entityId: string,\n        entity: Entity | null,\n        databaseId?: string\n    ): Promise<void>;\n\n    /**\n     * Called when the HTTP server is ready and listening.\n     * Useful for providers that need the server address for callbacks.\n     */\n    onServerReady?(serverInfo: { port: number; hostname?: string }): void;\n\n    /**\n     * Gracefully shut down the realtime provider.\n     * Called during server shutdown to clean up resources.\n     */\n    destroy?(): Promise<void>;\n\n    /**\n     * Stop the internal LISTEN client (e.g., PostgreSQL LISTEN/NOTIFY).\n     * Called during graceful shutdown before closing database connections.\n     */\n    stopListening?(): Promise<void>;\n}\n\n// =============================================================================\n// COLLECTION REGISTRY INTERFACES\n// =============================================================================\n\n/**\n * Abstract collection registry interface.\n * Manages registration and lookup of entity collections.\n */\nexport interface CollectionRegistryInterface {\n    /**\n     * Register a collection\n     */\n    register(collection: EntityCollection): void;\n\n    /**\n     * Get a collection by its path\n     */\n    getCollectionByPath(path: string): EntityCollection | undefined;\n\n    /**\n     * Get all registered collections\n     */\n    getCollections(): EntityCollection[];\n}\n\n// =============================================================================\n// DATA TRANSFORMER INTERFACES\n// =============================================================================\n\n/**\n * Abstract data transformer interface.\n * Handles serialization/deserialization between frontend and database formats.\n */\nexport interface DataTransformer {\n    /**\n     * Transform entity data for storage in the database\n     */\n    serializeToDatabase<M extends Record<string, unknown>>(\n        entity: M,\n        collection: EntityCollection\n    ): Record<string, unknown>;\n\n    /**\n     * Transform database data back to entity format\n     */\n    deserializeFromDatabase<M extends Record<string, unknown>>(\n        data: Record<string, unknown>,\n        collection: EntityCollection\n    ): Promise<M>;\n}\n\n// =============================================================================\n// DATABASE ADMIN — CAPABILITY-SPECIFIC INTERFACES (1.3)\n// =============================================================================\n\n/**\n * Administrative operations for SQL-based databases (PostgreSQL, MySQL, etc.).\n * Used by the SQL Editor, RLS Editor, and schema browser.\n *\n * @group Admin\n */\nexport interface SQLAdmin {\n    /**\n     * Execute raw SQL against the database.\n     */\n    executeSql(sql: string, options?: { database?: string; role?: string }): Promise<Record<string, unknown>[]>;\n\n    /**\n     * Fetch the available databases on the server.\n     */\n    fetchAvailableDatabases?(): Promise<string[]>;\n\n    /**\n     * Fetch the available database roles.\n     */\n    fetchAvailableRoles?(): Promise<string[]>;\n\n    /**\n     * Fetch the current database name.\n     */\n    fetchCurrentDatabase?(): Promise<string | undefined>;\n}\n\n/**\n * Administrative operations for document-based databases (MongoDB, Firestore, etc.).\n * Used by future document administration tools.\n *\n * @group Admin\n */\nexport interface DocumentAdmin {\n    /**\n     * Execute an aggregation pipeline or equivalent query.\n     */\n    executeAggregate?(pipeline: Record<string, unknown>[]): Promise<Record<string, unknown>[]>;\n\n    /**\n     * Fetch statistics for a collection (document count, size, etc.).\n     */\n    fetchCollectionStats?(collectionName: string): Promise<{ count: number; sizeBytes?: number }>;\n}\n\n/**\n * Administrative operations for schema management.\n * Shared across SQL and document databases.\n *\n * @group Admin\n */\nexport interface SchemaAdmin {\n    /**\n     * Fetch database tables/collections not yet mapped to a Rebase collection.\n     */\n    fetchUnmappedTables?(mappedPaths?: string[]): Promise<string[]>;\n\n    /**\n     * Fetch column/field metadata for a single table/collection.\n     * The return type is generic — SQL backends return TableMetadata,\n     * document backends may return a different shape.\n     */\n    fetchTableMetadata?(tableName: string): Promise<unknown>;\n}\n\n/**\n * Metadata for a database branch.\n * @group Admin\n */\nexport interface BranchInfo {\n    /** Branch name (without prefix). */\n    name: string;\n    /** The database this branch was created from. */\n    parentDatabase: string;\n    /** When the branch was created. */\n    createdAt: Date;\n    /** Size in bytes, if available from the server. */\n    sizeBytes?: number;\n}\n\n/**\n * Administrative operations for database branching.\n * Allows creating isolated database copies for development/preview workflows.\n *\n * @group Admin\n */\nexport interface BranchAdmin {\n    /** Create a new branch (database copy) from the current or specified source database. */\n    createBranch(name: string, options?: { source?: string }): Promise<BranchInfo>;\n\n    /** Delete a branch database. Cannot delete the main/default database. */\n    deleteBranch(name: string): Promise<void>;\n\n    /** List all branches (databases that were created via branching). */\n    listBranches(): Promise<BranchInfo[]>;\n\n    /** Get info about a specific branch. */\n    getBranchInfo(name: string): Promise<BranchInfo | undefined>;\n}\n\n/**\n * Union type for all admin capabilities.\n * A backend may implement any combination of these interfaces.\n *\n * Use type guards (`isSQLAdmin`, `isDocumentAdmin`, `isSchemaAdmin`, `isBranchAdmin`)\n * to safely narrow the type before calling methods.\n *\n * @group Admin\n */\nexport type DatabaseAdmin = Partial<SQLAdmin> & Partial<DocumentAdmin> & Partial<SchemaAdmin> & Partial<BranchAdmin>;\n\n/**\n * Type guard: does this admin support SQL operations?\n * @group Admin\n */\nexport function isSQLAdmin(admin: DatabaseAdmin | undefined): admin is SQLAdmin {\n    return !!admin && typeof (admin as SQLAdmin).executeSql === \"function\";\n}\n\n/**\n * Type guard: does this admin support document operations?\n * @group Admin\n */\nexport function isDocumentAdmin(admin: DatabaseAdmin | undefined): admin is DocumentAdmin {\n    return !!admin && (\n        typeof (admin as DocumentAdmin).executeAggregate === \"function\" ||\n        typeof (admin as DocumentAdmin).fetchCollectionStats === \"function\"\n    );\n}\n\n/**\n * Type guard: does this admin support schema management?\n * @group Admin\n */\nexport function isSchemaAdmin(admin: DatabaseAdmin | undefined): admin is SchemaAdmin {\n    return !!admin && (\n        typeof (admin as SchemaAdmin).fetchUnmappedTables === \"function\" ||\n        typeof (admin as SchemaAdmin).fetchTableMetadata === \"function\"\n    );\n}\n\n/**\n * Type guard: does this admin support database branching?\n * @group Admin\n */\nexport function isBranchAdmin(admin: DatabaseAdmin | undefined): admin is BranchAdmin {\n    return !!admin && typeof (admin as BranchAdmin).createBranch === \"function\";\n}\n\n// =============================================================================\n// LIFECYCLE INTERFACES (1.4)\n// =============================================================================\n\n/**\n * Health check result returned by `healthCheck()`.\n * @group Lifecycle\n */\nexport interface HealthCheckResult {\n    /** Whether the backend is healthy and able to serve requests. */\n    healthy: boolean;\n    /** Round-trip latency to the database in milliseconds. */\n    latencyMs: number;\n    /** Optional details (e.g., pool stats, replication lag). */\n    details?: Record<string, unknown>;\n}\n\n/**\n * Lifecycle contract for backend components that hold resources\n * (database connections, WebSocket pools, timers, etc.).\n *\n * All methods are optional — simple backends (e.g., in-memory) can skip them.\n * @group Lifecycle\n */\nexport interface BackendLifecycle {\n    /**\n     * Initialize the backend: open connections, run migrations, seed data.\n     * Called once during startup. Idempotent.\n     */\n    initialize?(): Promise<void>;\n\n    /**\n     * Check whether the backend is healthy and reachable.\n     * Should be fast (< 1 s) and safe to call frequently.\n     */\n    healthCheck?(): Promise<HealthCheckResult>;\n\n    /**\n     * Gracefully shut down: close connections, flush buffers, cancel timers.\n     * After calling `destroy()`, no other methods should be called.\n     */\n    destroy?(): Promise<void>;\n}\n\n// =============================================================================\n// BACKEND FACTORY INTERFACES\n// =============================================================================\n\n/**\n * Configuration for creating a database backend\n */\nexport interface BackendConfig {\n    /**\n     * Type of database backend\n     */\n    type: string;\n\n    /**\n     * Database connection (implementation-specific)\n     */\n    connection: unknown;\n\n    /**\n     * Schema definition (implementation-specific, e.g., Drizzle schema for PostgreSQL)\n     */\n    schema?: unknown;\n}\n\n/**\n * A complete backend instance with all required services.\n *\n * Now includes optional lifecycle management and admin capabilities.\n */\nexport interface BackendInstance extends BackendLifecycle {\n    /**\n     * Entity repository for CRUD operations\n     */\n    entityRepository: EntityRepository;\n\n    /**\n     * Realtime provider for subscriptions\n     */\n    realtimeProvider: RealtimeProvider;\n\n    /**\n     * Collection registry\n     */\n    collectionRegistry: CollectionRegistryInterface;\n\n    /**\n     * The underlying database connection\n     */\n    connection: DatabaseConnection;\n\n    /**\n     * Administrative operations (SQL, schema, documents).\n     * What's available depends on the backend type — use type guards\n     * (`isSQLAdmin`, `isSchemaAdmin`, etc.) to narrow.\n     */\n    admin?: DatabaseAdmin;\n}\n\n/**\n * Factory function type for creating backend instances\n */\nexport type BackendFactory<TConfig extends BackendConfig = BackendConfig> =\n    (config: TConfig) => BackendInstance;\n\n// =============================================================================\n// BACKEND BOOTSTRAPPER (1.2)\n// =============================================================================\n\n/**\n * A `BackendBootstrapper` encapsulates all driver-specific initialization logic.\n *\n * Instead of hard-coding Postgres setup into `initializeRebaseBackend()`,\n * each database backend provides its own bootstrapper that knows how to:\n * - Create the DataDriver from a config object\n * - Optionally initialize auth tables\n * - Optionally create a realtime service\n * - Mount driver-specific API routes\n *\n * The main `initializeRebaseBackend()` becomes a **coordinator** that iterates\n * registered bootstrappers, calls their hooks, and wires the results together.\n *\n * @group Backend\n *\n * @example\n * ```typescript\n * // Third-party MySQL bootstrapper\n * const mysqlBootstrapper: BackendBootstrapper = {\n *   type: \"mysql\",\n *   initializeDriver: async (config) => new MySQLDataDriver(config.connection),\n *   initializeRealtime: async (config) => new MySQLChangeStreamRealtime(config.connection),\n * };\n *\n * initializeRebaseBackend({\n *   ...config,\n *   bootstrappers: [postgresBootstrapper, mysqlBootstrapper]\n * });\n * ```\n */\nexport interface BackendBootstrapper {\n    /**\n     * Which driver type this bootstrapper handles.\n     * Must match the `type` field on the driver config object\n     * (e.g., `\"postgres\"`, `\"mongodb\"`, `\"mysql\"`).\n     */\n    type: string;\n\n    /**\n     * Unique identifier for this bootstrapper instance.\n     * Used to register the driver in the driver registry.\n     * Defaults to `type` if not set.\n     */\n    id?: string;\n\n    /**\n     * Whether this bootstrapper provides the default driver.\n     * When true, the coordinator uses this driver as the primary one.\n     */\n    isDefault?: boolean;\n\n    /**\n     * Run database migrations for this driver.\n     * Called by the coordinator after all drivers are initialized.\n     */\n    runMigrations?(config: unknown, driverResult: InitializedDriver): Promise<void>;\n\n    /**\n     * Create a DataDriver from the given config.\n     * This is the only **required** method.\n     */\n    initializeDriver(config: unknown): Promise<InitializedDriver>;\n\n    /**\n     * Initialize auth tables / services if this driver supports them.\n     * Return undefined if auth is not supported by this backend.\n     */\n    initializeAuth?(config: unknown, driverResult: InitializedDriver): Promise<BootstrappedAuth | undefined>;\n\n    /**\n     * Initialize history tables / services if this driver supports them.\n     * Return undefined if history is not supported by this backend.\n     */\n    initializeHistory?(config: unknown, driverResult: InitializedDriver): Promise<{ historyService: unknown } | undefined>;\n\n    /**\n     * Create a realtime provider for this driver.\n     * Return undefined if the driver does not support realtime.\n     */\n    initializeRealtime?(config: unknown, driverResult: InitializedDriver): Promise<RealtimeProvider | undefined>;\n\n    /**\n     * Mount any driver-specific HTTP routes (e.g., custom admin endpoints).\n     * Called after all drivers are initialized.\n     */\n    mountRoutes?(app: unknown, basePath: string, driverResult: InitializedDriver): void;\n\n    /**\n     * Return admin capabilities for this driver.\n     */\n    getAdmin?(driverResult: InitializedDriver): DatabaseAdmin | undefined;\n\n    /**\n     * Initialize WebSocket server for realtime operations.\n     */\n    initializeWebsockets?(server: unknown, realtimeService: RealtimeProvider, driver: import(\"../controllers/data_driver\").DataDriver, config?: unknown, authAdapter?: AuthAdapter): Promise<void> | void;\n}\n\n/**\n * Result of `BackendBootstrapper.initializeDriver()`.\n * @group Backend\n */\nexport interface InitializedDriver {\n    /** The DataDriver instance, ready for use. */\n    driver: import(\"../controllers/data_driver\").DataDriver;\n\n    /** The realtime service, if the driver created one during init. */\n    realtimeProvider?: RealtimeProvider;\n\n    /** A collection registry to register schema / tables into. */\n    collectionRegistry?: CollectionRegistryInterface;\n\n    /** The underlying database connection (for lifecycle management). */\n    connection?: DatabaseConnection;\n\n    /**\n     * Opaque handle that the bootstrapper can use in subsequent hooks\n     * (e.g., `initializeAuth`, `mountRoutes`) to access driver internals.\n     * Not used by the coordinator.\n     */\n    internals?: unknown;\n}\n\n/**\n * Result of `BackendBootstrapper.initializeAuth()`.\n * @group Backend\n */\nexport interface BootstrappedAuth {\n    /** User management service. */\n    userService: unknown;\n    /** Role management service (optional, roles are now simple strings). */\n    roleService?: unknown;\n    /** Email service (optional). */\n    emailService?: unknown;\n    /** Combined Auth Repository for unified token and user management. */\n    authRepository?: unknown;\n}\n"],"mappings":";;;;;;;;AA2dA,SAAgB,WAAW,OAAqD;CAC5E,OAAO,CAAC,CAAC,SAAS,OAAQ,MAAmB,eAAe;AAChE"}

package/dist/chunk-Dze3rakg.js

@@ -0,0 +1,42 @@
+import { createRequire as __createRequire } from "module";
+import "process";
+const require = __createRequire(import.meta.url);
+//#region \0rolldown/runtime.js
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __esmMin = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __commonJSMin = (cb, mod) => () => (mod || (cb((mod = { exports: {} }).exports, mod), cb = null), mod.exports);
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+var __toCommonJS = (mod) => __hasOwnProp.call(mod, "module.exports") ? mod["module.exports"] : __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, { get: (a, b) => (typeof require !== "undefined" ? require : a)[b] }) : x)(function(x) {
+	if (typeof require !== "undefined") return require.apply(this, arguments);
+	throw Error("Calling `require` for \"" + x + "\" in an environment that doesn't expose the `require` function. See https://rolldown.rs/in-depth/bundling-cjs#require-external-modules for more details.");
+});
+//#endregion
+export { __toCommonJS as a, __require as i, __esmMin as n, __toESM as o, __exportAll as r, __commonJSMin as t };

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

@@ -1,5 +1,5 @@
 import type { CronJobStatus, CronJobLogEntry } from "@rebasepro/types";
-import type { RebaseClient } from "@rebasepro/client";
+import type { RebaseClient } from "@rebasepro/types";
 import type { LoadedCronJob } from "./cron-loader";
 import type { CronStore } from "./cron-store";
 /**