@rebasepro/server-core 0.0.1-canary.4d4fb3e → 0.0.1-canary.ca2cb6e

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

@@ -1,28 +1,13 @@
 /**
- * Email service types and interfaces
+ * 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.).
  */
-/**
- * Options for sending an email
- */
-export interface EmailSendOptions {
-    to: string;
-    subject: string;
-    html: string;
-    text?: string;
-}
-/**
- * Email service interface - abstraction for sending emails
- */
-export interface EmailService {
-    /**
-     * Send an email
-     */
-    send(options: EmailSendOptions): Promise<void>;
-    /**
-     * Check if the email service is properly configured
-     */
-    isConfigured(): boolean;
-}
+import type { EmailService, EmailSendOptions } from "@rebasepro/types";
+export type { EmailService, EmailSendOptions };
 /**
  * SMTP server configuration
  */
@@ -68,6 +53,17 @@ export type UserInvitationTemplateFunction = (setPasswordUrl: string, user: {
     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
  */
@@ -106,5 +102,6 @@ export interface EmailConfig {
         passwordReset?: PasswordResetTemplateFunction;
         emailVerification?: EmailVerificationTemplateFunction;
         userInvitation?: UserInvitationTemplateFunction;
+        welcomeEmail?: WelcomeEmailTemplateFunction;
     };
 }

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

@@ -11,10 +11,10 @@ export interface HistoryService {
         limit: number;
         offset: number;
     }): Promise<{
-        data: any[];
+        data: Record<string, unknown>[];
         total: number;
     }>;
-    fetchHistoryEntry(historyId: string): Promise<any>;
+    fetchHistoryEntry(historyId: string): Promise<Record<string, unknown> | null>;
 }
 export declare function createHistoryRoutes(params: {
     historyService: HistoryService;

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

@@ -9,6 +9,7 @@
 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";
@@ -18,7 +19,11 @@ 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

@@ -1,4 +1,4 @@
-import { DataDriver, EntityCollection, BackendBootstrapper, BootstrappedAuth, RealtimeProvider } from "@rebasepro/types";
+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";
@@ -6,17 +6,80 @@ 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 {
@@ -30,10 +93,42 @@ export interface RebaseBackendConfig {
         level?: "error" | "warn" | "info" | "debug";
     };
     auth?: RebaseAuthConfig;
-    storage?: BackendStorageConfig | Record<string, BackendStorageConfig>;
+    /**
+     * 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;
@@ -45,5 +140,20 @@ export interface RebaseBackendInstance {
     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/singleton.d.ts

@@ -0,0 +1,35 @@
+import type { RebaseClient } from "@rebasepro/types";
+/**
+ * @internal Called once during server initialization to set the backing instance.
+ * This is invoked by `initializeRebaseBackend()` — never call it manually.
+ */
+export declare function _initRebase(client: RebaseClient): void;
+/**
+ * @internal Allows overriding the underlying instance for unit testing.
+ * Throws an error if used in a non-test environment to prevent production abuse.
+ */
+export declare function _setRebaseMock(mockInstance: Partial<RebaseClient>): void;
+/**
+ * @internal Resets the singleton instance, useful for afterEach() in test suites.
+ */
+export declare function _resetRebaseMock(): void;
+/**
+ * The server-side Rebase singleton.
+ *
+ * Initialized automatically during server startup. Provides access to all
+ * app-scoped services: **data**, **auth**, **storage**, and **email**.
+ *
+ * `rebase.data` runs with **admin privileges** (no RLS). For user-scoped
+ * queries inside request handlers, continue using the handler's context
+ * or the RLS-scoped driver.
+ *
+ * @example
+ * ```typescript
+ * import { rebase } from "@rebasepro/server-core";
+ *
+ * // In a Hono handler, cron job, hook, or service file:
+ * await rebase.email?.send({ to: "admin@co.com", subject: "Alert", html: "<p>Hi</p>" });
+ * const jobs = await rebase.data.jobs.find({ limit: 10 });
+ * ```
+ */
+export declare const rebase: RebaseClient;

package/dist/server-core/src/storage/LocalStorageController.d.ts

@@ -1,8 +1,8 @@
 /**
  * Local filesystem storage controller
  */
-import { StorageController, LocalStorageConfig } from './types';
-import { UploadFileProps, UploadFileResult, DownloadConfig, StorageListResult } from '@rebasepro/types';
+import { StorageController, LocalStorageConfig } from "./types";
+import { UploadFileProps, UploadFileResult, DownloadConfig, StorageListResult } from "@rebasepro/types";
 /**
  * Local filesystem storage implementation
  * Stores files in a directory structure: {basePath}/{bucket}/{path}
@@ -11,7 +11,7 @@ export declare class LocalStorageController implements StorageController {
     private config;
     private basePath;
     constructor(config: LocalStorageConfig);
-    getType(): 'local';
+    getType(): "local";
     /**
      * Ensure directory exists, creating it if necessary
      */
@@ -25,11 +25,11 @@ export declare class LocalStorageController implements StorageController {
      * Validate file before upload
      */
     private validateFile;
-    uploadFile({ file, fileName, path: storagePath, metadata, bucket }: UploadFileProps): Promise<UploadFileResult>;
-    getDownloadURL(storagePath: string, bucket?: string): Promise<DownloadConfig>;
-    getFile(storagePath: string, bucket?: string): Promise<File | null>;
-    deleteFile(storagePath: string, bucket?: string): Promise<void>;
-    list(storagePath: string, options?: {
+    putObject({ file, key, metadata, bucket }: UploadFileProps): Promise<UploadFileResult>;
+    getSignedUrl(key: string, bucket?: string): Promise<DownloadConfig>;
+    getObject(key: string, bucket?: string): Promise<File | null>;
+    deleteObject(key: string, bucket?: string): Promise<void>;
+    listObjects(prefix: string, options?: {
         bucket?: string;
         maxResults?: number;
         pageToken?: string;
@@ -38,7 +38,7 @@ export declare class LocalStorageController implements StorageController {
      * Get the absolute filesystem path for serving files
      * Used by the storage routes to serve files directly
      */
-    getAbsolutePath(storagePath: string, bucket?: string): string;
+    getAbsolutePath(key: string, bucket?: string): string;
     /**
      * Get the base path for the storage
      */

package/dist/server-core/src/storage/S3StorageController.d.ts

@@ -1,8 +1,8 @@
 /**
  * S3-compatible storage controller (works with AWS S3 and MinIO)
  */
-import { StorageController, S3StorageConfig } from './types';
-import { UploadFileProps, UploadFileResult, DownloadConfig, StorageListResult } from '@rebasepro/types';
+import { StorageController, S3StorageConfig } from "./types";
+import { UploadFileProps, UploadFileResult, DownloadConfig, StorageListResult } from "@rebasepro/types";
 /**
  * S3-compatible storage implementation
  * Works with AWS S3 and MinIO (with forcePathStyle option)
@@ -11,7 +11,7 @@ export declare class S3StorageController implements StorageController {
     private config;
     private client;
     constructor(config: S3StorageConfig);
-    getType(): 's3';
+    getType(): "s3";
     /**
      * Validate file before upload
      */
@@ -20,15 +20,15 @@ export declare class S3StorageController implements StorageController {
      * Get the bucket name - either from parameter or config
      */
     private getBucket;
-    uploadFile({ file, fileName, path: storagePath, metadata, bucket }: UploadFileProps): Promise<UploadFileResult>;
+    putObject({ file, key, metadata, bucket }: UploadFileProps): Promise<UploadFileResult>;
     /**
      * Flatten nested metadata to string values (S3 requirement)
      */
     private flattenMetadata;
-    getDownloadURL(storagePath: string, bucket?: string): Promise<DownloadConfig>;
-    getFile(storagePath: string, bucket?: string): Promise<File | null>;
-    deleteFile(storagePath: string, bucket?: string): Promise<void>;
-    list(storagePath: string, options?: {
+    getSignedUrl(key: string, bucket?: string): Promise<DownloadConfig>;
+    getObject(key: string, bucket?: string): Promise<File | null>;
+    deleteObject(key: string, bucket?: string): Promise<void>;
+    listObjects(prefix: string, options?: {
         bucket?: string;
         maxResults?: number;
         pageToken?: string;

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

@@ -1,18 +1,25 @@
 /**
  * Storage module for Rebase backend
  *
- * Provides file storage functionality with support for:
- * - Local filesystem storage (default, zero config)
- * - S3-compatible storage (AWS S3, MinIO)
+ * Provides pluggable file storage with two built-in providers:
+ * - **Local filesystem** — zero config, great for dev and single-server deployments.
+ * - **S3-compatible** — works with AWS S3, Cloudflare R2, MinIO, Hetzner Object Storage,
+ *   Backblaze B2, DigitalOcean Spaces, and GCS (via S3 interop).
+ *
+ * For other providers (native GCS SDK, Azure Blob, etc.), implement the
+ * `StorageController` interface and pass the instance directly to the `storage` config.
  */
-export * from './types';
-export { LocalStorageController } from './LocalStorageController';
-export { S3StorageController } from './S3StorageController';
-export { createStorageRoutes } from './routes';
-export type { StorageRoutesConfig } from './routes';
-export * from './storage-registry';
-import { BackendStorageConfig, StorageController } from './types';
+export * from "./types";
+export { LocalStorageController } from "./LocalStorageController";
+export { S3StorageController } from "./S3StorageController";
+export { createStorageRoutes } from "./routes";
+export type { StorageRoutesConfig } from "./routes";
+export * from "./storage-registry";
+import { BackendStorageConfig, StorageController } from "./types";
 /**
- * Factory function to create a storage controller based on configuration
+ * Create a storage controller from a config object.
+ *
+ * For custom providers, implement `StorageController` directly instead
+ * of going through this factory.
  */
 export declare function createStorageController(config: BackendStorageConfig): StorageController;

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

@@ -1,9 +1,9 @@
 /**
  * Storage REST API routes using Hono
  */
-import { Hono } from 'hono';
-import { StorageController } from './types';
-import { HonoEnv } from '../api/types';
+import { Hono } from "hono";
+import { StorageController } from "./types";
+import { HonoEnv } from "../api/types";
 export interface StorageRoutesConfig {
     controller: StorageController;
     /** Base path for storage routes (default: '/api/storage') */

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

@@ -6,7 +6,7 @@ import { UploadFileProps, UploadFileResult, DownloadConfig, StorageListResult }
  * Local filesystem storage configuration
  */
 export interface LocalStorageConfig {
-    type: 'local';
+    type: "local";
     /** Base directory for file storage (e.g., './uploads') */
     basePath: string;
     /** Maximum file size in bytes (default: 50MB) */
@@ -20,12 +20,12 @@ export interface LocalStorageConfig {
  * S3-compatible storage configuration (works with AWS S3 and MinIO)
  */
 export interface S3StorageConfig {
-    type: 's3';
+    type: "s3";
     /** S3 bucket name */
     bucket: string;
     /** AWS region (e.g., 'us-east-1') */
     region?: string;
-    /** Custom endpoint URL (required for MinIO) */
+    /** Custom endpoint URL (required for MinIO, Cloudflare R2, Hetzner Object Storage) */
     endpoint?: string;
     /** AWS access key ID */
     accessKeyId: string;
@@ -41,7 +41,16 @@ export interface S3StorageConfig {
     signedUrlExpiration?: number;
 }
 /**
- * Storage configuration - either local filesystem or S3-compatible
+ * Storage configuration — local filesystem or S3-compatible.
+ *
+ * **Built-in providers:**
+ * - `local` — Zero-config filesystem storage. Great for dev and single-server deployments (Hetzner, bare metal).
+ * - `s3` — Any S3-compatible provider. AWS S3, Cloudflare R2, MinIO, Hetzner Object Storage,
+ *           Backblaze B2, DigitalOcean Spaces, and even GCS (via its S3-compatible interoperability API).
+ *
+ * **Custom providers:**
+ * For cloud-native storage (GCS, Azure Blob, etc.), implement the `StorageController`
+ * interface and pass the instance directly to the `storage` config.
  */
 export type BackendStorageConfig = LocalStorageConfig | S3StorageConfig;
 /**
@@ -49,33 +58,36 @@ export type BackendStorageConfig = LocalStorageConfig | S3StorageConfig;
  */
 export interface StorageController {
     /**
-     * Upload a file
+     * Upload an object
      */
-    uploadFile(props: UploadFileProps): Promise<UploadFileResult>;
+    putObject(props: UploadFileProps): Promise<UploadFileResult>;
     /**
-     * Get a download URL for a file
+     * Get a download URL (signed URL equivalent) for an object
      */
-    getDownloadURL(path: string, bucket?: string): Promise<DownloadConfig>;
+    getSignedUrl(key: string, bucket?: string): Promise<DownloadConfig>;
     /**
-     * Get file as a File object
+     * Get object as a File
      */
-    getFile(path: string, bucket?: string): Promise<File | null>;
+    getObject(key: string, bucket?: string): Promise<File | null>;
     /**
-     * Delete a file
+     * Delete an object
      */
-    deleteFile(path: string, bucket?: string): Promise<void>;
+    deleteObject(key: string, bucket?: string): Promise<void>;
     /**
-     * List files in a path
+     * List objects in a prefix
      */
-    list(path: string, options?: {
+    listObjects(prefix: string, options?: {
         bucket?: string;
         maxResults?: number;
         pageToken?: string;
     }): Promise<StorageListResult>;
     /**
-     * Get the storage configuration type
+     * Get the storage provider identifier.
+     *
+     * Built-in values are `'local'` and `'s3'`. Custom implementations
+     * should return their own identifier (e.g. `'gcs'`, `'azure'`).
      */
-    getType(): 'local' | 's3';
+    getType(): string;
 }
 /**
  * Default maximum file size (50MB)

package/dist/server-core/src/utils/dev-port.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Dev-mode port resolution utilities.
+ *
+ * Provides a `listen` wrapper that automatically retries the next port when
+ * the requested one is already in use, and writes the resolved port to a
+ * well-known temp file so the CLI / frontend can discover it.
+ *
+ * Port affinity: when a port file already exists (e.g. after a tsx watch
+ * restart), the saved port is tried FIRST so the backend stays on the same
+ * port the frontend was configured with.
+ *
+ * This module is dev-only and should never run in production.
+ */
+import type { Server } from "http";
+/** Filename written next to the project `.env` so the CLI can read it. */
+export declare const DEV_PORT_FILENAME = ".rebase-dev-port";
+/**
+ * Try to `listen` on `startPort`. If the port is busy (`EADDRINUSE`), increment
+ * and retry up to `maxAttempts` times.
+ *
+ * When a port file already exists (written by a previous run), the saved port
+ * is tried first to maintain port affinity across tsx watch restarts.
+ *
+ * Resolves with the port that was actually bound.
+ */
+export declare function listenWithPortRetry(server: Server, startPort: number, options?: {
+    host?: string;
+    maxAttempts?: number;
+    /** Absolute path to write the resolved port file into.  Defaults to `process.cwd()`. */
+    portFileDir?: string;
+}): Promise<number>;
+/**
+ * Clean up the dev port file and state file (call on graceful shutdown).
+ */
+export declare function cleanupDevPortFile(dir: string): void;

package/dist/server-core/src/utils/logger.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Structured Logger for Rebase Backend
+ *
+ * Outputs JSON lines when `NODE_ENV=production`, human-readable prefixed
+ * lines otherwise.  Designed to work with Google Cloud Logging severity levels.
+ *
+ * Usage:
+ *   import { logger } from "./utils/logger";
+ *   logger.info("Server started", { port: 3001 });
+ *   logger.error("Request failed", { path: "/api/test", error: err });
+ */
+export type LogLevel = "debug" | "info" | "warn" | "error";
+export interface LogEntry {
+    severity: string;
+    message: string;
+    timestamp: string;
+    [key: string]: unknown;
+}
+export interface Logger {
+    debug(message: string, data?: Record<string, unknown>): void;
+    info(message: string, data?: Record<string, unknown>): void;
+    warn(message: string, data?: Record<string, unknown>): void;
+    error(message: string, data?: Record<string, unknown>): void;
+    child(defaultFields: Record<string, unknown>): Logger;
+}
+/**
+ * Singleton logger instance.
+ * In production: emits JSON lines with `severity`, `message`, `timestamp`.
+ * In development: emits human-readable prefixed lines.
+ */
+export declare const logger: Logger;

package/dist/server-core/src/utils/request-logger.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Structured HTTP request logging middleware for Hono.
+ *
+ * Logs every request with method, path, status code, latency, and
+ * content-length. In production, outputs JSON for Cloud Logging; in
+ * development, emits a coloured one-liner.
+ *
+ * @example
+ * ```ts
+ * import { requestLogger } from "@rebasepro/server-core";
+ * app.use("/*", requestLogger());
+ * ```
+ */
+import type { MiddlewareHandler } from "hono";
+export interface RequestLoggerOptions {
+    /** Paths to skip logging (e.g. "/health"). Supports exact match. */
+    skip?: string[];
+}
+export declare function requestLogger(options?: RequestLoggerOptions): MiddlewareHandler;

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

@@ -15,6 +15,8 @@ export interface AuthCapabilities {
     sessionManagement?: boolean;
     profileUpdate?: boolean;
     emailVerification?: boolean;
+    /** List of enabled OAuth provider IDs (e.g. ["google", "github", "discord"]) */
+    enabledProviders?: string[];
 }
 /**
  * Controller for retrieving the logged user or performing auth related operations.