@rebasepro/server-core 0.0.1-canary.09e5ec5

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

@@ -0,0 +1,61 @@
+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";
+export declare class CronScheduler {
+    private jobs;
+    private started;
+    private store?;
+    private client?;
+    /**
+     * Set the RebaseClient instance to make it available to cron job handlers.
+     */
+    setClient(client: RebaseClient): void;
+    /**
+     * Attach a persistence store for cron logs.
+     * When set, execution logs are written to the database after each run,
+     * and counters are seeded from the database on start.
+     */
+    setStore(store: CronStore): void;
+    /**
+     * Register a batch of loaded cron jobs.
+     */
+    registerJobs(loadedJobs: LoadedCronJob[]): void;
+    /**
+     * Start the scheduler — begins ticking all enabled jobs.
+     */
+    start(): void;
+    /**
+     * Stop the scheduler and clear all timers.
+     */
+    stop(): void;
+    /**
+     * List all registered jobs with their current status.
+     */
+    listJobs(): CronJobStatus[];
+    /**
+     * Get a single job status by ID.
+     */
+    getJob(id: string): CronJobStatus | undefined;
+    /**
+     * Get log entries for a job.
+     */
+    getJobLogs(id: string, limit?: number): CronJobLogEntry[];
+    /**
+     * Get log entries for a job from the database (if store is available).
+     * Falls back to in-memory logs if no store is configured.
+     */
+    getJobLogsFromDb(id: string, limit?: number): Promise<CronJobLogEntry[]>;
+    /**
+     * Enable or disable a job at runtime.
+     */
+    setJobEnabled(id: string, enabled: boolean): CronJobStatus | undefined;
+    /**
+     * Manually trigger a job execution immediately.
+     */
+    triggerJob(id: string): Promise<CronJobLogEntry | undefined>;
+    private scheduleNext;
+    private stopJob;
+    private executeJob;
+    private toStatus;
+}

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

@@ -0,0 +1,32 @@
+import type { CronJobLogEntry } from "@rebasepro/types";
+import type { DataDriver } from "@rebasepro/types";
+/**
+ * Persistence layer for cron job execution logs.
+ *
+ * Uses the DataDriver's `admin.executeSql` capability to store logs in a
+ * `rebase.cron_logs` table. Falls back gracefully if the driver doesn't
+ * support SQL (e.g. MongoDB) — in that case, no persistence occurs.
+ */
+export interface CronStore {
+    /** Ensure the backing table exists. Called once on startup. */
+    ensureTable(): Promise<void>;
+    /** Persist a single log entry after execution. */
+    insertLog(entry: CronJobLogEntry): Promise<void>;
+    /**
+     * Fetch the most recent logs for a job.
+     * @param jobId  The job identifier
+     * @param limit  Max entries to return (default 50)
+     * @returns Logs sorted newest-first
+     */
+    fetchLogs(jobId: string, limit?: number): Promise<CronJobLogEntry[]>;
+    /**
+     * Fetch aggregate stats for all jobs (totalRuns, totalFailures, lastRunAt).
+     * Used to seed in-memory counters on startup.
+     */
+    fetchJobStats(): Promise<Map<string, {
+        totalRuns: number;
+        totalFailures: number;
+        lastRunAt?: string;
+    }>>;
+}
+export declare function createCronStore(driver: DataDriver): CronStore | undefined;

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

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

package/dist/server-core/src/db/interfaces.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Database Abstraction Interfaces
+ *
+ * These interfaces define the contracts that any database backend must implement
+ * to be used with Rebase. This allows for pluggable database backends like
+ * PostgreSQL, MongoDB, MySQL, etc.
+ */
+import { DatabaseConnection, QueryFilter, FetchCollectionOptions, SearchOptions, CountOptions, ConditionBuilder, ConditionBuilderStatic, EntityRepository, CollectionSubscriptionConfig, EntitySubscriptionConfig, RealtimeProvider, CollectionRegistryInterface, DataTransformer, BackendConfig, BackendInstance, BackendFactory } from "@rebasepro/types";
+import { NodePgDatabase } from "drizzle-orm/node-postgres";
+import { PgTransaction } from "drizzle-orm/pg-core";
+/**
+ * Type representing either a direct database connection or a transaction.
+ * Used to allow services to operate within a transaction context.
+ * Note: `any` is intentional here — it represents a Drizzle client with
+ * a dynamic schema, enabling `db.query[tableName]` access without casts.
+ */
+export type DrizzleClient = NodePgDatabase<Record<string, unknown>> | PgTransaction<any, any, any>;
+export type { DatabaseConnection, QueryFilter, FetchCollectionOptions, SearchOptions, CountOptions, ConditionBuilder, ConditionBuilderStatic, EntityRepository, CollectionSubscriptionConfig, EntitySubscriptionConfig, RealtimeProvider, CollectionRegistryInterface, DataTransformer, BackendConfig, BackendInstance, BackendFactory };

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

@@ -0,0 +1,6 @@
+/**
+ * Email module exports
+ */
+export type { EmailService, EmailSendOptions, SMTPConfig, EmailConfig, PasswordResetTemplateFunction, EmailVerificationTemplateFunction, UserInvitationTemplateFunction, WelcomeEmailTemplateFunction } from "./types";
+export { SMTPEmailService, createEmailService } from "./smtp-email-service";
+export { getPasswordResetTemplate, getEmailVerificationTemplate, getUserInvitationTemplate, getWelcomeEmailTemplate } from "./templates";

package/dist/server-core/src/email/smtp-email-service.d.ts

@@ -0,0 +1,25 @@
+import { EmailService, EmailSendOptions, EmailConfig } from "./types";
+/**
+ * SMTP Email Service implementation using Nodemailer
+ */
+export declare class SMTPEmailService implements EmailService {
+    private transporter;
+    private config;
+    constructor(config: EmailConfig);
+    /**
+     * Check if the email service is properly configured
+     */
+    isConfigured(): boolean;
+    /**
+     * Send an email using SMTP or custom send function
+     */
+    send(options: EmailSendOptions): Promise<void>;
+    /**
+     * Verify SMTP connection (useful for startup checks)
+     */
+    verifyConnection(): Promise<boolean>;
+}
+/**
+ * Create an email service from configuration
+ */
+export declare function createEmailService(config: EmailConfig): EmailService;

package/dist/server-core/src/email/templates.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Default email templates for authentication emails
+ */
+interface TemplateUser {
+    email: string;
+    displayName?: string | null;
+}
+/**
+ * Default password reset email template
+ */
+export declare function getPasswordResetTemplate(resetUrl: string, user: TemplateUser, appName?: string): {
+    subject: string;
+    html: string;
+    text: string;
+};
+/**
+ * Default email verification template
+ */
+export declare function getEmailVerificationTemplate(verifyUrl: string, user: TemplateUser, appName?: string): {
+    subject: string;
+    html: string;
+    text: string;
+};
+/**
+ * Default user invitation email template
+ * Sent when an admin creates a new user account
+ */
+export declare function getUserInvitationTemplate(setPasswordUrl: string, user: TemplateUser, appName?: string): {
+    subject: string;
+    html: string;
+    text: string;
+};
+/**
+ * Default welcome email template
+ * Sent automatically when a new user registers
+ */
+export declare function getWelcomeEmailTemplate(user: TemplateUser, appName?: string, loginUrl?: string): {
+    subject: string;
+    html: string;
+    text: string;
+};
+export {};

package/dist/server-core/src/email/types.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Email service types and interfaces.
+ *
+ * The canonical `EmailService` and `EmailSendOptions` live in `@rebasepro/types`
+ * so they can be used on the `RebaseClient` interface without pulling in nodemailer.
+ * This file re-exports them for backward compatibility and adds server-specific
+ * config types (SMTP, template functions, etc.).
+ */
+import type { EmailService, EmailSendOptions } from "@rebasepro/types";
+export type { EmailService, EmailSendOptions };
+/**
+ * SMTP server configuration
+ */
+export interface SMTPConfig {
+    host: string;
+    port: number;
+    secure?: boolean;
+    auth?: {
+        user: string;
+        pass: string;
+    };
+}
+/**
+ * Template function for password reset emails
+ */
+export type PasswordResetTemplateFunction = (resetUrl: string, user: {
+    email: string;
+    displayName?: string | null;
+}) => {
+    subject: string;
+    html: string;
+    text?: string;
+};
+/**
+ * Template function for email verification emails
+ */
+export type EmailVerificationTemplateFunction = (verifyUrl: string, user: {
+    email: string;
+    displayName?: string | null;
+}) => {
+    subject: string;
+    html: string;
+    text?: string;
+};
+/**
+ * Template function for user invitation emails
+ */
+export type UserInvitationTemplateFunction = (setPasswordUrl: string, user: {
+    email: string;
+    displayName?: string | null;
+}) => {
+    subject: string;
+    html: string;
+    text?: string;
+};
+/**
+ * Template function for welcome emails sent after registration
+ */
+export type WelcomeEmailTemplateFunction = (user: {
+    email: string;
+    displayName?: string | null;
+}, appName: string) => {
+    subject: string;
+    html: string;
+    text?: string;
+};
+/**
+ * Complete email configuration
+ */
+export interface EmailConfig {
+    /**
+     * From address for all emails (e.g., "noreply@example.com" or "MyApp <noreply@example.com>")
+     */
+    from: string;
+    /**
+     * SMTP configuration for sending emails via SMTP server
+     */
+    smtp?: SMTPConfig;
+    /**
+     * Alternative: custom function to send emails
+     * Use this for custom email providers (AWS SES SDK, Resend, etc.)
+     */
+    sendEmail?: (options: EmailSendOptions) => Promise<void>;
+    /**
+     * Base URL for password reset links (e.g., "https://myapp.com")
+     * The reset link will be: {baseUrl}/reset-password?token={token}
+     */
+    resetPasswordUrl?: string;
+    /**
+     * Base URL for email verification links (e.g., "https://myapp.com")
+     * The verification link will be: {baseUrl}/verify-email?token={token}
+     */
+    verifyEmailUrl?: string;
+    /**
+     * Application name to use in email templates
+     */
+    appName?: string;
+    /**
+     * Custom email templates (optional - defaults are provided)
+     */
+    templates?: {
+        passwordReset?: PasswordResetTemplateFunction;
+        emailVerification?: EmailVerificationTemplateFunction;
+        userInvitation?: UserInvitationTemplateFunction;
+        welcomeEmail?: WelcomeEmailTemplateFunction;
+    };
+}

package/dist/server-core/src/functions/function-loader.d.ts

@@ -0,0 +1,17 @@
+import { Hono } from "hono";
+export interface LoadedFunction {
+    /** Endpoint name derived from filename (e.g., "send-invoice") */
+    name: string;
+    /** The Hono sub-app to mount */
+    app: Hono<import("hono").Env>;
+}
+/**
+ * Auto-discover Hono route files from a directory.
+ *
+ * Each file should default-export a Hono app (or router).
+ * The filename (without extension) becomes the mount path:
+ *   `functions/send-invoice.ts` → mounted at `/send-invoice`
+ *
+ * This mirrors how `loadCollectionsFromDirectory` works for collections.
+ */
+export declare function loadFunctionsFromDirectory(directory: string): Promise<LoadedFunction[]>;

package/dist/server-core/src/functions/function-routes.d.ts

@@ -0,0 +1,10 @@
+import { Hono } from "hono";
+import { HonoEnv } from "../api/types";
+import { LoadedFunction } from "./function-loader";
+/**
+ * Mount all loaded function routes under a single Hono router.
+ *
+ * Each function is mounted at `/<function-name>`, preserving
+ * whatever HTTP methods and middleware the Hono sub-app defines.
+ */
+export declare function createFunctionRoutes(functions: LoadedFunction[]): Hono<HonoEnv>;

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

@@ -0,0 +1,3 @@
+export { loadFunctionsFromDirectory } from "./function-loader";
+export type { LoadedFunction } from "./function-loader";
+export { createFunctionRoutes } from "./function-routes";

package/dist/server-core/src/history/history-routes.d.ts

@@ -0,0 +1,23 @@
+import { Hono } from "hono";
+import { HonoEnv } from "../api/types";
+import { BackendCollectionRegistry } from "../collections/BackendCollectionRegistry";
+import { DataDriver } from "@rebasepro/types";
+/**
+ * Create Hono routes for entity history.
+ * Mounted at `{basePath}/data/:slug/:entityId/history`.
+ */
+export interface HistoryService {
+    fetchHistory(tableName: string, entityId: string, options: {
+        limit: number;
+        offset: number;
+    }): Promise<{
+        data: Record<string, unknown>[];
+        total: number;
+    }>;
+    fetchHistoryEntry(historyId: string): Promise<Record<string, unknown> | null>;
+}
+export declare function createHistoryRoutes(params: {
+    historyService: HistoryService;
+    registry: BackendCollectionRegistry;
+    driver: DataDriver;
+}): Hono<HonoEnv>;

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

@@ -0,0 +1 @@
+export { createHistoryRoutes } from "./history-routes";

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

@@ -0,0 +1,29 @@
+/**
+ * @rebasepro/server-core
+ *
+ * Database-Agnostic Backend Core for Rebase.
+ * This package provides the core backend services, generic driver routing,
+ * and API layers. Database implementations (e.g., PostgreSQL) are provided
+ * by specialized driver packages like `@rebasepro/server-postgresql`.
+ */
+export * from "./db/interfaces";
+export * from "./auth/interfaces";
+export * from "./init";
+export { rebase, _setRebaseMock, _resetRebaseMock } from "./singleton";
+export * from "./services/driver-registry";
+export * from "./api/types";
+export * from "./api";
+export * from "./types";
+export * from "./types/index";
+export * from "./auth";
+export * from "./email";
+export * from "./storage";
+export * from "./utils/logging";
+export * from "./utils/logger";
+export * from "./utils/request-logger";
+export * from "./utils/sql";
+export * from "./history";
+export * from "./functions";
+export * from "./cron";
+export * from "./serve-spa";
+export * from "./utils/dev-port";

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

@@ -0,0 +1,159 @@
+import { DataDriver, EntityCollection, BackendBootstrapper, BootstrappedAuth, RealtimeProvider, HealthCheckResult } 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";
+export interface RebaseAuthConfig {
+    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 Firebase Service Account key.
+     *
+     * Generate with: `node -e "console.log(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;
+    };
+    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;
+    providers?: OAuthProvider<any>[];
+    [key: string]: unknown;
+}
+export interface RebaseBackendConfig {
+    collections?: EntityCollection[];
+    collectionsDir?: string;
+    server: Server;
+    app: Hono<HonoEnv>;
+    basePath?: string;
+    bootstrappers: BackendBootstrapper[];
+    logging?: {
+        level?: "error" | "warn" | "info" | "debug";
+    };
+    auth?: RebaseAuthConfig;
+    /**
+     * Storage configuration. Accepts:
+     *
+     * - A `BackendStorageConfig` object (`{ type: 'local' | 's3', ... }`)
+     * - A `StorageController` instance (for custom providers like GCS, Azure, etc.)
+     * - A `Record<string, ...>` of either, for multi-backend setups
+     */
+    storage?: BackendStorageConfig | StorageController | Record<string, BackendStorageConfig | StorageController>;
+    history?: unknown;
+    enableSwagger?: boolean;
+    functionsDir?: string;
+    cronsDir?: string;
+    /**
+     * 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);
+    };
+}
+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>;

package/dist/server-core/src/serve-spa.d.ts

@@ -0,0 +1,30 @@
+import { Hono } from "hono";
+/**
+ * Configuration for serving a Single Page Application
+ */
+export interface ServeSPAConfig {
+    /**
+     * Absolute path to the frontend build directory
+     * @example path.join(__dirname, "../../frontend/dist")
+     */
+    frontendPath: string;
+    /**
+     * Base path for API routes (default: "/api")
+     * Requests to this path will be passed through to API handlers
+     */
+    apiBasePath?: string;
+    /**
+     * Additional paths to exclude from SPA handling
+     * These paths will be passed through to other handlers
+     * @example ["/health", "/ws", "/metrics"]
+     */
+    excludePaths?: string[];
+    /**
+     * Index file to serve for SPA routes (default: "index.html")
+     */
+    indexFile?: string;
+}
+/**
+ * Serve a Single Page Application from an Hono app.
+ */
+export declare function serveSPA<E extends import("hono").Env>(app: Hono<E>, config: ServeSPAConfig): void;

package/dist/server-core/src/services/driver-registry.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Driver Registry
+ *
+ * Manages multiple driver delegates for Rebase backend.
+ * Allows different databases for different collections.
+ *
+ * Usage:
+ * - Single DB: Pass a single DataDriver → maps to "(default)"
+ * - Multiple DBs: Pass a map of { dbId: DataDriver }
+ * - Collections use `databaseId` property to specify which driver to use
+ * - Collections without `databaseId` fallback to "(default)"
+ */
+import { DataDriver } from "@rebasepro/types";
+/**
+ * The default driver identifier used when:
+ * - A single driver is provided (not a map)
+ * - A collection doesn't specify a databaseId
+ */
+export declare const DEFAULT_DRIVER_ID = "(default)";
+/**
+ * Registry for managing multiple driver delegates
+ */
+export interface DriverRegistry {
+    /**
+     * Register a driver delegate with an ID
+     * @param id - Unique identifier for this driver (e.g., "analytics", "users")
+     * @param delegate - The DataDriver instance
+     */
+    register(id: string, delegate: DataDriver): void;
+    /**
+     * Get the default driver delegate (id = "(default)")
+     * @throws Error if no default driver is registered
+     */
+    getDefault(): DataDriver;
+    /**
+     * Get a driver delegate by ID
+     * @param id - Driver identifier, or undefined/null for default
+     * @returns The DataDriver, or undefined if not found
+     */
+    get(id: string | undefined | null): DataDriver | undefined;
+    /**
+     * Get a driver delegate by ID, with fallback to default
+     * @param id - Driver identifier, or undefined/null for default
+     * @returns The DataDriver (falls back to default if id not found)
+     * @throws Error if neither the specified nor default driver exists
+     */
+    getOrDefault(id: string | undefined | null): DataDriver;
+    /**
+     * Check if a driver with the given ID exists
+     */
+    has(id: string): boolean;
+    /**
+     * List all registered driver IDs
+     */
+    list(): string[];
+    /**
+     * Get the number of registered drivers
+     */
+    size(): number;
+}
+/**
+ * Default implementation of DriverRegistry
+ */
+export declare class DefaultDriverRegistry implements DriverRegistry {
+    private delegates;
+    /**
+     * Create a DriverRegistry from either a single delegate or a map
+     * @param input - Single DataDriver (maps to "(default)") or Record<string, DataDriver>
+     */
+    static create(input: DataDriver | Record<string, DataDriver>): DefaultDriverRegistry;
+    register(id: string, delegate: DataDriver): void;
+    getDefault(): DataDriver;
+    get(id: string | undefined | null): DataDriver | undefined;
+    getOrDefault(id: string | undefined | null): DataDriver;
+    has(id: string): boolean;
+    list(): string[];
+    size(): number;
+}