@rebasepro/server-core 0.7.0 → 0.8.0

package/dist/init/docs.d.ts

@@ -0,0 +1,4 @@
+import { Hono } from "hono";
+import { EntityCollection } from "@rebasepro/types";
+import { HonoEnv } from "../api/types";
+export declare function mountOpenApiDocs(app: Hono<HonoEnv>, basePath: string, enableSwagger: boolean | undefined, activeCollections: EntityCollection[], requireAuth: boolean): Promise<void>;

package/dist/init/health.d.ts

@@ -0,0 +1,2 @@
+import { DataDriver, HealthCheckResult } from "@rebasepro/types";
+export declare function createHealthCheck(defaultDriver: DataDriver): () => Promise<HealthCheckResult>;

package/dist/init/middlewares.d.ts

@@ -0,0 +1,10 @@
+import { Hono } from "hono";
+import { HonoEnv } from "../api/types";
+interface MiddlewareConfig {
+    maxBodySize?: number;
+    csrf?: {
+        origin: string | string[] | ((origin: string) => boolean);
+    };
+}
+export declare function configureMiddlewares(app: Hono<HonoEnv>, basePath: string, isProduction: boolean, config: MiddlewareConfig): void;
+export {};

package/dist/init/shutdown.d.ts

@@ -0,0 +1,11 @@
+import { Server } from "http";
+import { RealtimeProvider } from "@rebasepro/types";
+interface ShutdownConfig {
+    server: Server;
+    cronScheduler?: {
+        stop(): void;
+    };
+    realtimeServices: Record<string, RealtimeProvider>;
+}
+export declare function createShutdown(config: ShutdownConfig): (timeoutMs?: number) => Promise<void>;
+export {};

package/dist/init/storage.d.ts

@@ -0,0 +1,5 @@
+import { BackendStorageConfig, StorageController, StorageRegistry } from "../storage";
+export declare function initializeStorage(storageConfig: BackendStorageConfig | StorageController | Record<string, BackendStorageConfig | StorageController> | undefined, isProduction: boolean): {
+    storageRegistry?: StorageRegistry;
+    storageController?: StorageController;
+};

package/dist/init.d.ts

@@ -0,0 +1,314 @@
+import { AuthAdapter, BackendBootstrapper, BootstrappedAuth, DatabaseAdapter, DataDriver, DataSourceDefinition, EntityCallbacks, EntityCollection, HealthCheckResult, RealtimeProvider, SecurityRule } from "@rebasepro/types";
+import { BackendCollectionRegistry } from "./collections/BackendCollectionRegistry";
+import { DriverRegistry } from "./services/driver-registry";
+import { Server } from "http";
+import { Hono } from "hono";
+import { HonoEnv } from "./api/types";
+import { BackendStorageConfig, StorageController, StorageRegistry } from "./storage";
+import { EmailConfig } from "./email";
+import type { OAuthProvider } from "./auth/interfaces";
+import type { AuthHooks } from "./auth/auth-hooks";
+export interface RebaseAuthConfig {
+    /**
+     * The collection that represents auth users.
+     *
+     * When provided, this collection's underlying database table is used
+     * for all auth operations (login, registration, password reset, etc.).
+     *
+     * Import the built-in default:
+     * ```ts
+     * import { defaultUsersCollection } from "@rebasepro/common";
+     * auth: { collection: defaultUsersCollection, jwtSecret: "..." }
+     * ```
+     *
+     * Or pass your own collection with the required auth fields
+     * (email, passwordHash, displayName, etc.).
+     */
+    collection?: EntityCollection;
+    jwtSecret?: string;
+    accessExpiresIn?: string;
+    refreshExpiresIn?: string;
+    requireAuth?: boolean;
+    allowRegistration?: boolean;
+    /**
+     * A static secret key for server-to-server / script authentication.
+     *
+     * When a request includes `Authorization: Bearer <serviceKey>`, it is
+     * granted admin-level access without JWT verification. This is the
+     * Rebase equivalent of a Service Account key.
+     *
+     * Generate with: `node -e "logger.info(require('crypto').randomBytes(48).toString('base64'))"`
+     *
+     * Set via `REBASE_SERVICE_KEY` in your `.env`.
+     * Must be at least 32 characters.
+     */
+    serviceKey?: string;
+    email?: EmailConfig;
+    google?: {
+        clientId: string;
+        clientSecret?: string;
+    };
+    linkedin?: {
+        clientId: string;
+        clientSecret: string;
+    };
+    github?: {
+        clientId: string;
+        clientSecret: string;
+    };
+    microsoft?: {
+        clientId: string;
+        clientSecret: string;
+        tenantId?: string;
+    };
+    apple?: {
+        clientId: string;
+        teamId: string;
+        keyId: string;
+        privateKey: string;
+    };
+    facebook?: {
+        clientId: string;
+        clientSecret: string;
+    };
+    twitter?: {
+        clientId: string;
+        clientSecret: string;
+    };
+    discord?: {
+        clientId: string;
+        clientSecret: string;
+    };
+    gitlab?: {
+        clientId: string;
+        clientSecret: string;
+        baseUrl?: string;
+    };
+    bitbucket?: {
+        clientId: string;
+        clientSecret: string;
+    };
+    slack?: {
+        clientId: string;
+        clientSecret: string;
+    };
+    spotify?: {
+        clientId: string;
+        clientSecret: string;
+    };
+    defaultRole?: string;
+    /**
+     * Canonical array of OAuth providers.
+     *
+     * This is the primary extension point for **all** OAuth integrations.
+     * Each entry is an `OAuthProvider<unknown>` constructed via one of
+     * the `create*Provider` factories exported from `@rebasepro/server-core`
+     * (e.g. `createGoogleProvider`, `createGitHubProvider`).
+     *
+     * The named convenience fields above (`google`, `github`, etc.) are
+     * automatically resolved into this array at startup. You can mix both
+     * approaches; named fields and explicit entries are merged (named
+     * fields are appended after explicit entries).
+     *
+     * @example
+     * ```ts
+     * import { createGoogleProvider } from "@rebasepro/server-core";
+     *
+     * auth: {
+     *   providers: [
+     *     createGoogleProvider({ clientId: "…", clientSecret: "…" }),
+     *   ],
+     * }
+     * ```
+     */
+    providers?: OAuthProvider<unknown>[];
+    /**
+     * Override specific parts of the built-in auth implementation.
+     *
+     * Each override replaces one piece of the default behavior while
+     * keeping everything else intact. Unset overrides fall through
+     * to the built-in defaults (scrypt passwords, standard validation, etc.).
+     *
+     * @example bcrypt passwords with a custom hash
+     * ```ts
+     * import bcrypt from "bcrypt";
+     *
+     * hooks: {
+     *     hashPassword: (pw) => bcrypt.hash(pw, 12),
+     *     verifyPassword: (pw, hash) => bcrypt.compare(pw, hash),
+     * }
+     * ```
+     */
+    hooks?: AuthHooks;
+    /**
+     * Enable magic link (passwordless email) authentication.
+     * Requires email to be configured.
+     */
+    magicLink?: boolean;
+}
+export interface RebaseBackendConfig {
+    collections?: EntityCollection[];
+    collectionsDir?: string;
+    server: Server;
+    app: Hono<HonoEnv>;
+    basePath?: string;
+    /**
+     * Declared data sources, shared with the frontend `<Rebase dataSources>`.
+     *
+     * Used to resolve each collection's engine (capabilities) and transport.
+     * Collections on a `direct`/`custom` transport are client-only: the backend
+     * still owns their schema/registry but does **not** generate server data
+     * routes for them. Server-mediated sources (the default) need no entry.
+     */
+    dataSources?: DataSourceDefinition[];
+    /**
+     * Database bootstrappers.
+     */
+    bootstrappers?: BackendBootstrapper[];
+    /**
+     * Database adapter.
+     *
+     * When set, this takes precedence over `bootstrappers`.
+     *
+     * @example
+     * ```ts
+     * import { createPostgresAdapter } from "@rebasepro/server-postgresql";
+     * database: createPostgresAdapter({ connection: db, schema }),
+     * ```
+     */
+    database?: DatabaseAdapter;
+    logging?: {
+        level?: "error" | "warn" | "info" | "debug";
+    };
+    /**
+     * Authentication configuration.
+     *
+     * Accepts **either**:
+     * - `RebaseAuthConfig` — built-in configuration
+     * - `AuthAdapter` — pluggable adapter for external auth (Clerk, Auth0, etc.)
+     *
+     * When a plain config object is provided, the built-in adapter is created
+     * automatically from the bootstrapper's `initializeAuth()` result.
+     */
+    auth?: RebaseAuthConfig | AuthAdapter;
+    /**
+     * Storage configuration. Accepts:
+     *
+     * - A `BackendStorageConfig` object (`{ type: 'local' | 's3' | 'gcs', ... }`)
+     * - A `StorageController` instance (for custom providers like Azure, etc.)
+     * - A `Record<string, ...>` of either, for multi-backend setups
+     */
+    storage?: BackendStorageConfig | StorageController | Record<string, BackendStorageConfig | StorageController>;
+    /**
+     * Declared storage sources. Drives the client-side StorageSourceRegistry
+     * and the transport distinction (server vs direct).
+     *
+     * Server-backed sources are auto-derived from the `storage` map — you
+     * only need explicit entries for "direct" transport sources (e.g.
+     * external storage) that the backend does not proxy.
+     */
+    storageSources?: import("@rebasepro/types").StorageSourceDefinition[];
+    history?: unknown;
+    /**
+     * Default security rules applied to any collection that does not define
+     * its own `securityRules`. Opt-in — if not set, collections without
+     * explicit rules remain unrestricted (beyond `requireAuth`).
+     *
+     * @example
+     * ```ts
+     * defaultSecurityRules: [
+     *     { operation: "select", access: "public" },
+     *     { operations: ["insert", "update", "delete"], roles: ["admin"] }
+     * ]
+     * ```
+     */
+    defaultSecurityRules?: SecurityRule[];
+    enableSwagger?: boolean;
+    functionsDir?: string;
+    cronsDir?: string;
+    /**
+     * Enable/disable database persistence for cron job execution logs.
+     * When set to false, cron jobs will run but logs will not be persisted to the database.
+     * Default: true.
+     */
+    cronPersistence?: boolean;
+    /**
+     * Maximum request body size in bytes for API routes (default: 10MB).
+     * Set to 0 to disable the global limit entirely.
+     *
+     * Note: Storage upload routes use their own limit from the storage config's
+     * `maxFileSize` property (default: 50MB), which takes precedence over this.
+     */
+    maxBodySize?: number;
+    /**
+     * CSRF protection configuration. **Opt-in** — disabled by default.
+     *
+     * BaaS APIs are consumed by mobile apps, SPAs on different domains,
+     * and CLI tools, so CSRF is intentionally not enabled unless you
+     * explicitly configure it with allowed origins.
+     *
+     * @example
+     * ```ts
+     * csrf: { origin: ["https://myapp.com", "https://admin.myapp.com"] }
+     * ```
+     */
+    csrf?: {
+        /** Allowed origins for CSRF validation. */
+        origin: string | string[] | ((origin: string) => boolean);
+    };
+    /**
+     * Global lifecycle callbacks applied to every collection.
+     *
+     * Same type as per-collection `callbacks` — fires on **every** data path
+     * (REST API, WebSocket / realtime, server-side `rebase.data`).
+     *
+     * Execution order: global callbacks → collection callbacks → property callbacks.
+     *
+     * @example
+     * ```ts
+     * callbacks: {
+     *     afterRead({ entity, collection }) {
+     *         console.log(`Read ${collection.slug}/${entity.id}`);
+     *         return entity;
+     *     }
+     * }
+     * ```
+     */
+    callbacks?: EntityCallbacks;
+}
+/**
+ * Type guard to detect whether the `auth` config is an `AuthAdapter`
+ * (has a `verifyRequest` method) vs a plain `RebaseAuthConfig` (plain object).
+ */
+export declare function isAuthAdapter(auth: RebaseAuthConfig | AuthAdapter): auth is AuthAdapter;
+/**
+ * Type guard to detect whether `database` is a `DatabaseAdapter`.
+ */
+export declare function isDatabaseAdapter(db: unknown): db is DatabaseAdapter;
+export interface RebaseBackendInstance {
+    driverRegistry: DriverRegistry;
+    driver: DataDriver;
+    realtimeServices: Record<string, RealtimeProvider>;
+    realtimeService: RealtimeProvider;
+    auth?: BootstrappedAuth;
+    history?: unknown;
+    storageRegistry?: StorageRegistry;
+    storageController?: StorageController;
+    collectionRegistry: BackendCollectionRegistry;
+    cronScheduler?: import("./cron").CronScheduler;
+    /**
+     * Deep health check that verifies database connectivity.
+     * Returns latency and component status.
+     */
+    healthCheck(): Promise<HealthCheckResult>;
+    /**
+     * Graceful shutdown helper for the BaaS instance.
+     * Stops the cron scheduler and closes the HTTP server, allowing
+     * in-flight requests to drain within the given timeout.
+     *
+     * @param timeoutMs - Maximum time (ms) to wait for drain before force-exit (default: 15000).
+     *                    Pass 0 to skip the force-exit timer (useful in tests).
+     */
+    shutdown(timeoutMs?: number): Promise<void>;
+}
+export declare function initializeRebaseBackend(config: RebaseBackendConfig): Promise<RebaseBackendInstance>;