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

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

@@ -0,0 +1,46 @@
+/**
+ * Local filesystem storage controller
+ */
+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}
+ */
+export declare class LocalStorageController implements StorageController {
+    private config;
+    private basePath;
+    constructor(config: LocalStorageConfig);
+    getType(): "local";
+    /**
+     * Ensure directory exists, creating it if necessary
+     */
+    private ensureDir;
+    /**
+     * Get the full filesystem path for a storage path.
+     * Includes a path traversal guard to prevent escaping the base directory.
+     */
+    private getFullPath;
+    /**
+     * Validate file before upload
+     */
+    private validateFile;
+    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;
+    }): Promise<StorageListResult>;
+    /**
+     * Get the absolute filesystem path for serving files
+     * Used by the storage routes to serve files directly
+     */
+    getAbsolutePath(key: string, bucket?: string): string;
+    /**
+     * Get the base path for the storage
+     */
+    getBasePath(): string;
+}

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

@@ -0,0 +1,36 @@
+/**
+ * S3-compatible storage controller (works with AWS S3 and MinIO)
+ */
+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)
+ */
+export declare class S3StorageController implements StorageController {
+    private config;
+    private client;
+    constructor(config: S3StorageConfig);
+    getType(): "s3";
+    /**
+     * Validate file before upload
+     */
+    private validateFile;
+    /**
+     * Get the bucket name - either from parameter or config
+     */
+    private getBucket;
+    putObject({ file, key, metadata, bucket }: UploadFileProps): Promise<UploadFileResult>;
+    /**
+     * Flatten nested metadata to string values (S3 requirement)
+     */
+    private flattenMetadata;
+    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;
+    }): Promise<StorageListResult>;
+}

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

@@ -0,0 +1,25 @@
+/**
+ * Storage module for Rebase backend
+ *
+ * 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";
+/**
+ * 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

@@ -0,0 +1,38 @@
+/**
+ * Storage REST API routes using Hono
+ */
+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') */
+    basePath?: string;
+    /** Require authentication for write operations (default: true) */
+    requireAuth?: boolean;
+    /** Allow unauthenticated read access to stored files (default: false).
+     *  When false and requireAuth is true, reads also require authentication. */
+    publicRead?: boolean;
+}
+/**
+ * Extract the wildcard portion of a route path from the full request path.
+ *
+ * Hono's `c.req.param('*')` does not work reliably in sub-routers mounted
+ * via `app.route(prefix, subRouter)`. Instead we derive the wildcard value
+ * from the fully-resolved `c.req.path` and `c.req.routePath`.
+ *
+ * For a route `/metadata/*` mounted at `/api/storage`, a request to
+ * `/api/storage/metadata/default/file.jpg` yields routePath
+ * `/api/storage/metadata/*`.  We strip the prefix (everything before `/*`)
+ * plus one character for the trailing `/` to obtain `default/file.jpg`.
+ */
+export declare function extractWildcardPath(c: {
+    req: {
+        path: string;
+        routePath: string;
+    };
+}): string;
+/**
+ * Create storage REST API routes
+ */
+export declare function createStorageRoutes(config: StorageRoutesConfig): Hono<HonoEnv>;

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

@@ -0,0 +1,78 @@
+/**
+ * Storage Registry
+ *
+ * Manages multiple storage controllers for Rebase backend.
+ * Allows different storage backends for different use cases.
+ *
+ * Usage:
+ * - Single storage: Pass a single StorageController → maps to "(default)"
+ * - Multiple storages: Pass a map of { storageId: StorageController }
+ * - String properties use `storageId` in their config to specify which storage to use
+ * - Properties without `storageId` fallback to "(default)"
+ */
+import { StorageController } from "./types";
+/**
+ * The default storage identifier used when:
+ * - A single storage controller is provided (not a map)
+ * - A property doesn't specify a storageId
+ */
+export declare const DEFAULT_STORAGE_ID = "(default)";
+/**
+ * Registry for managing multiple storage controllers
+ */
+export interface StorageRegistry {
+    /**
+     * Register a storage controller with an ID
+     * @param id - Unique identifier for this storage (e.g., "media", "backups")
+     * @param controller - The StorageController instance
+     */
+    register(id: string, controller: StorageController): void;
+    /**
+     * Get the default storage controller (id = "(default)")
+     * @throws Error if no default storage is registered
+     */
+    getDefault(): StorageController;
+    /**
+     * Get a storage controller by ID
+     * @param id - Storage identifier, or undefined/null for default
+     * @returns The StorageController, or undefined if not found
+     */
+    get(id: string | undefined | null): StorageController | undefined;
+    /**
+     * Get a storage controller by ID, with fallback to default
+     * @param id - Storage identifier, or undefined/null for default
+     * @returns The StorageController (falls back to default if id not found)
+     * @throws Error if neither the specified nor default storage exists
+     */
+    getOrDefault(id: string | undefined | null): StorageController;
+    /**
+     * Check if a storage with the given ID exists
+     */
+    has(id: string): boolean;
+    /**
+     * List all registered storage IDs
+     */
+    list(): string[];
+    /**
+     * Get the number of registered storage controllers
+     */
+    size(): number;
+}
+/**
+ * Default implementation of StorageRegistry
+ */
+export declare class DefaultStorageRegistry implements StorageRegistry {
+    private controllers;
+    /**
+     * Create a StorageRegistry from either a single controller or a map
+     * @param input - Single StorageController (maps to "(default)") or Record<string, StorageController>
+     */
+    static create(input: StorageController | Record<string, StorageController>): DefaultStorageRegistry;
+    register(id: string, controller: StorageController): void;
+    getDefault(): StorageController;
+    get(id: string | undefined | null): StorageController | undefined;
+    getOrDefault(id: string | undefined | null): StorageController;
+    has(id: string): boolean;
+    list(): string[];
+    size(): number;
+}

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

@@ -0,0 +1,103 @@
+/**
+ * Storage configuration and types for Rebase backend
+ */
+import { UploadFileProps, UploadFileResult, DownloadConfig, StorageListResult } from "@rebasepro/types";
+/**
+ * Local filesystem storage configuration
+ */
+export interface LocalStorageConfig {
+    type: "local";
+    /** Base directory for file storage (e.g., './uploads') */
+    basePath: string;
+    /** Maximum file size in bytes (default: 50MB) */
+    maxFileSize?: number;
+    /** Allowed MIME types (if not set, all types allowed) */
+    allowedMimeTypes?: string[];
+    /** Base URL for generating download URLs (default: auto-detected from request) */
+    baseUrl?: string;
+}
+/**
+ * S3-compatible storage configuration (works with AWS S3 and MinIO)
+ */
+export interface S3StorageConfig {
+    type: "s3";
+    /** S3 bucket name */
+    bucket: string;
+    /** AWS region (e.g., 'us-east-1') */
+    region?: string;
+    /** Custom endpoint URL (required for MinIO, Cloudflare R2, Hetzner Object Storage) */
+    endpoint?: string;
+    /** AWS access key ID */
+    accessKeyId: string;
+    /** AWS secret access key */
+    secretAccessKey: string;
+    /** Use path-style URLs (required for MinIO) */
+    forcePathStyle?: boolean;
+    /** Maximum file size in bytes (default: 50MB) */
+    maxFileSize?: number;
+    /** Allowed MIME types (if not set, all types allowed) */
+    allowedMimeTypes?: string[];
+    /** URL expiration time in seconds for signed URLs (default: 3600) */
+    signedUrlExpiration?: number;
+}
+/**
+ * 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;
+/**
+ * Storage controller interface for backend implementations
+ */
+export interface StorageController {
+    /**
+     * Upload an object
+     */
+    putObject(props: UploadFileProps): Promise<UploadFileResult>;
+    /**
+     * Get a download URL (signed URL equivalent) for an object
+     */
+    getSignedUrl(key: string, bucket?: string): Promise<DownloadConfig>;
+    /**
+     * Get object as a File
+     */
+    getObject(key: string, bucket?: string): Promise<File | null>;
+    /**
+     * Delete an object
+     */
+    deleteObject(key: string, bucket?: string): Promise<void>;
+    /**
+     * List objects in a prefix
+     */
+    listObjects(prefix: string, options?: {
+        bucket?: string;
+        maxResults?: number;
+        pageToken?: string;
+    }): Promise<StorageListResult>;
+    /**
+     * Get the storage provider identifier.
+     *
+     * Built-in values are `'local'` and `'s3'`. Custom implementations
+     * should return their own identifier (e.g. `'gcs'`, `'azure'`).
+     */
+    getType(): string;
+}
+/**
+ * Default maximum file size (50MB)
+ */
+export declare const DEFAULT_MAX_FILE_SIZE: number;
+/**
+ * Common image MIME types
+ */
+export declare const IMAGE_MIME_TYPES: string[];
+/**
+ * Common document MIME types
+ */
+export declare const DOCUMENT_MIME_TYPES: string[];

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

@@ -0,0 +1,11 @@
+import { Entity, FetchCollectionProps, FetchEntityProps } from "@rebasepro/types";
+export interface ListenCollectionRequest<M extends Record<string, unknown> = Record<string, unknown>> extends FetchCollectionProps<M> {
+    subscriptionId: string;
+    onUpdate: (entities: Entity<M>[]) => void;
+    onError?: (error: Error) => void;
+}
+export interface ListenEntityRequest<M extends Record<string, unknown> = Record<string, unknown>> extends FetchEntityProps<M> {
+    subscriptionId: string;
+    onUpdate: (entity: Entity<M> | null) => void;
+    onError?: (error: Error) => void;
+}

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/logging.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Configure console log levels based on environment variable
+ * Call this early in your application to set up proper logging levels
+ */
+export declare function configureLogLevel(logLevel?: string): void;
+/**
+ * Reset console methods to their original state
+ */
+export declare function resetConsole(): void;

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/server-core/src/utils/sql.d.ts

@@ -0,0 +1,27 @@
+import { SQL } from "drizzle-orm";
+/**
+ * Returns a SQL chunk calling `auth.uid()` — the current user's ID.
+ * This is a Supabase-style helper function created in the `auth` schema
+ * that reads `app.user_id` set per-transaction by `withAuth()`.
+ *
+ * @example
+ * sql`${table.user_id} = ${authUid()}`
+ */
+export declare const authUid: () => SQL;
+/**
+ * Returns a SQL chunk calling `auth.roles()` — the current user's roles
+ * as a comma-separated string.
+ * Reads `app.user_roles` set per-transaction by `withAuth()`.
+ *
+ * @example
+ * sql`auth.roles() ~ 'admin'`
+ */
+export declare const authRoles: () => SQL;
+/**
+ * Returns a SQL chunk calling `auth.jwt()` — the full JWT claims as JSONB.
+ * Reads `app.jwt` set per-transaction by `withAuth()`.
+ *
+ * @example
+ * sql`auth.jwt()->>'sub'`
+ */
+export declare const authJwt: () => SQL;

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

@@ -0,0 +1,7 @@
+export type AnalyticsController = {
+    /**
+     * Callback used to get analytics events from the CMS
+     */
+    onAnalyticsEvent?: (event: AnalyticsEvent, data?: object) => void;
+};
+export type AnalyticsEvent = "entity_click" | "entity_click_from_reference" | "reference_selection_clear" | "reference_selection_toggle" | "reference_selected_single" | "reference_selection_new_entity" | "edit_entity_clicked" | "entity_edited" | "new_entity_click" | "new_entity_saved" | "copy_entity_click" | "entity_copied" | "single_delete_dialog_open" | "multiple_delete_dialog_open" | "single_entity_deleted" | "multiple_entities_deleted" | "drawer_navigate_to_home" | "drawer_navigate_to_collection" | "drawer_navigate_to_view" | "home_navigate_to_collection" | "home_favorite_navigate_to_collection" | "home_navigate_to_view" | "home_navigate_to_admin_view" | "home_favorite_navigate_to_view" | "home_move_card" | "home_move_group" | "home_drop_new_group" | "collection_inline_editing" | "view_mode_changed" | "kanban_card_moved" | "kanban_column_reorder" | "kanban_property_changed" | "kanban_new_entity_in_column" | "kanban_backfill_order" | "card_view_entity_click" | "unmapped_event";

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

@@ -0,0 +1,119 @@
+import { StorageSource } from "./storage";
+import { Role, User } from "../users";
+import { RebaseData } from "./data";
+/**
+ * Capabilities advertised by an auth provider.
+ * UI components use this to show/hide features dynamically
+ * (e.g. password reset, registration, session management).
+ * @group Hooks and utilities
+ */
+export interface AuthCapabilities {
+    emailPasswordLogin?: boolean;
+    googleLogin?: boolean;
+    registration?: boolean;
+    passwordReset?: boolean;
+    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.
+ * Note that if you are implementing your AuthController, you probably will want
+ * to do it as the result of a hook.
+ * @group Hooks and utilities
+ */
+export type AuthController<USER extends User = User, ExtraData = unknown> = {
+    /**
+     * The user currently logged in
+     * The values can be: the user object, null if they skipped login
+     */
+    user: USER | null;
+    /**
+     * Initial loading flag. It is used not to display the login screen
+     * when the app first loads, and it has not been checked whether the user
+     * is logged in or not.
+     */
+    initialLoading?: boolean;
+    /**
+     * Loading flag. It is used to display a loading screen when the user is
+     * logging in or out.
+     */
+    authLoading: boolean;
+    /**
+     * Sign out
+     */
+    signOut: () => Promise<void>;
+    /**
+     * Error initializing the authentication
+     */
+    authError?: unknown;
+    /**
+     * Error dispatched by the auth provider
+     */
+    authProviderError?: unknown;
+    /**
+     * You can use this method to retrieve the auth token for the current user.
+     */
+    getAuthToken: () => Promise<string>;
+    /**
+     * Has the user skipped the login process
+     */
+    loginSkipped: boolean;
+    extra: ExtraData;
+    setExtra: (extra: ExtraData) => void;
+    setUser?(user: USER | null): void;
+    setUserRoles?(roles: Role[]): void;
+    /**
+     * Capabilities advertised by the auth provider.
+     * UI components use this to feature-detect what the backend supports.
+     */
+    capabilities?: AuthCapabilities;
+};
+/**
+ * Extended auth controller with common optional auth methods.
+ * Backend implementations (Rebase backend, Firebase, Supabase, etc.)
+ * extend this with their own backend-specific extras.
+ * @group Hooks and utilities
+ */
+export interface AuthControllerExtended<USER extends User = User, ExtraData = unknown> extends AuthController<USER, ExtraData> {
+    /** Login with email and password */
+    emailPasswordLogin?(email: string, password: string): Promise<void>;
+    /** Login with a Google ID token or trigger Google popup */
+    googleLogin?(idToken: string): Promise<void>;
+    /** Register a new user */
+    register?(email: string, password: string, displayName?: string): Promise<void>;
+    /** Skip login (for anonymous access if enabled) */
+    skipLogin?(): void;
+    /** Request password reset email */
+    forgotPassword?(email: string): Promise<void>;
+    /** Reset password using a token */
+    resetPassword?(token: string, password: string): Promise<void>;
+    /** Change password for the authenticated user */
+    changePassword?(oldPassword: string, newPassword: string): Promise<void>;
+    /** Update user profile */
+    updateProfile?(displayName?: string, photoURL?: string): Promise<USER>;
+}
+/**
+ * Implement this function to allow access to specific users.
+ * @group Hooks and utilities
+ */
+export type Authenticator<USER extends User = User> = (props: {
+    /**
+     * Logged-in user or null
+     */
+    user: USER | null;
+    /**
+     * AuthController
+     */
+    authController: AuthController<USER>;
+    /**
+     * Unified data access API
+     */
+    data: RebaseData;
+    /**
+     * Used storage implementation
+     */
+    storageSource: StorageSource;
+}) => boolean | Promise<boolean>;