@rebasepro/server-core 0.7.0 → 0.9.0

package/dist/storage/GCSStorageController.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Google Cloud Storage controller (works with GCS and Firebase Storage)
+ *
+ * The `@google-cloud/storage` package is loaded lazily so it remains an
+ * optional peer dependency — users who don't need GCS never pay for the
+ * import cost or need it installed.
+ */
+import { StorageController, GCSStorageConfig } from "./types";
+import { UploadFileProps, UploadFileResult, DownloadConfig, StorageListResult } from "@rebasepro/types";
+/**
+ * Google Cloud Storage implementation of `StorageController`.
+ *
+ * Works with standard GCS buckets **and** Firebase Storage buckets
+ * (e.g. `"my-project.appspot.com"`).
+ */
+export declare class GCSStorageController implements StorageController {
+    private config;
+    private client;
+    constructor(config: GCSStorageConfig);
+    private getClient;
+    getType(): "gcs";
+    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>;
+    /**
+     * Validate file before upload
+     */
+    private validateFile;
+    /**
+     * Get the bucket name — either from parameter or config.
+     */
+    private getBucket;
+    /**
+     * Flatten nested metadata to string values (GCS custom metadata requirement)
+     */
+    private flattenMetadata;
+}

package/dist/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/storage/S3StorageController.d.ts

@@ -0,0 +1,40 @@
+/**
+ * S3-compatible storage controller (works with AWS S3 and MinIO)
+ */
+import { S3StorageConfig, StorageController } from "./types";
+import { DownloadConfig, StorageListResult, UploadFileProps, UploadFileResult } 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);
+    /**
+     * Lazily create and cache the S3 client on first use
+     */
+    private getClient;
+    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/storage/image-transform.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Image Transformation Service
+ *
+ * Provides on-the-fly image resize, crop, format conversion, and quality
+ * adjustment using the `sharp` library. Results are cached in an LRU
+ * in-memory cache to avoid redundant processing.
+ */
+/** Options that can be specified via query parameters. */
+export interface ImageTransformOptions {
+    width?: number;
+    height?: number;
+    quality?: number;
+    format?: "webp" | "avif" | "jpeg" | "png";
+    fit?: "cover" | "contain" | "fill" | "inside" | "outside";
+}
+/**
+ * Parse transform options from URL query parameters.
+ * Returns `null` when no transformation is requested.
+ */
+export declare function parseTransformOptions(query: Record<string, string>): ImageTransformOptions | null;
+/** Check whether a content type is a transformable image. */
+export declare function isTransformableImage(contentType: string): boolean;
+/**
+ * Apply image transformations and return the result buffer + content type.
+ */
+export declare function transformImage(buffer: Buffer | Uint8Array, options: ImageTransformOptions): Promise<{
+    data: Buffer;
+    contentType: string;
+}>;
+/**
+ * Simple LRU cache for transformed images.
+ *
+ * Entries expire after `maxAgeMs` (default: 1 hour) and the cache
+ * evicts the oldest entry when `maxEntries` is exceeded.
+ */
+export declare class TransformCache {
+    private cache;
+    private readonly maxEntries;
+    private readonly maxAgeMs;
+    private readonly maxTotalBytes;
+    private totalBytes;
+    constructor(maxEntries?: number, maxAgeMs?: number, maxTotalBytes?: number);
+    /** Build a deterministic cache key from file key + transform options. */
+    buildKey(fileKey: string, options: ImageTransformOptions): string;
+    get(cacheKey: string): {
+        data: Buffer;
+        contentType: string;
+    } | null;
+    set(cacheKey: string, data: Buffer, contentType: string): void;
+}

package/{src/storage/index.ts → dist/storage/index.d.ts}

@@ -1,46 +1,31 @@
 /**
  * Storage module for Rebase backend
  *
- * Provides pluggable file storage with two built-in providers:
+ * Provides pluggable file storage with three 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).
+ * - **Google Cloud Storage / Firebase Storage** — native GCS support via `@google-cloud/storage`
+ *   (optional peer dependency, lazily loaded).
  *
- * For other providers (native GCS SDK, Azure Blob, etc.), implement the
+ * For other providers (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 { GCSStorageController } from "./GCSStorageController";
 export { createStorageRoutes } from "./routes";
 export type { StorageRoutesConfig } from "./routes";
 export * from "./storage-registry";
 export { parseTransformOptions, transformImage, isTransformableImage, TransformCache } from "./image-transform";
 export type { ImageTransformOptions } from "./image-transform";
 export { TusHandler } from "./tus-handler";
-
 import { BackendStorageConfig, StorageController } from "./types";
-import { LocalStorageController } from "./LocalStorageController";
-import { S3StorageController } from "./S3StorageController";
-
 /**
  * Create a storage controller from a config object.
  *
  * For custom providers, implement `StorageController` directly instead
  * of going through this factory.
  */
-export function createStorageController(config: BackendStorageConfig): StorageController {
-    switch (config.type) {
-        case "local":
-            return new LocalStorageController(config);
-        case "s3":
-            return new S3StorageController(config);
-        default:
-            throw new Error(
-                `Unknown storage type: ${(config as Record<string, unknown>).type}. ` +
-                "Built-in types: local, s3. " +
-                "For other providers, implement the StorageController interface directly."
-            );
-    }
-}
+export declare function createStorageController(config: BackendStorageConfig): Promise<StorageController>;

package/dist/storage/routes.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Storage REST API routes using Hono
+ *
+ * Supports multi-backend routing via `StorageRegistry`. Each endpoint
+ * accepts an optional `storageId` parameter (query string or form field)
+ * to target a named storage backend. When omitted, the default backend
+ * is used.
+ */
+import { Hono } from "hono";
+import { StorageController } from "./types";
+import type { StorageRegistry } from "./storage-registry";
+import { type StorageSourceDefinition, type AuthAdapter } from "@rebasepro/types";
+import { HonoEnv } from "../api/types";
+export interface StorageRoutesConfig {
+    /**
+     * Single storage controller (backward-compatible).
+     * Used as fallback when no `registry` is provided.
+     */
+    controller?: StorageController;
+    /**
+     * Full storage registry for multi-backend routing.
+     * When provided, endpoints resolve the controller from `storageId`
+     * parameter. Takes precedence over `controller`.
+     */
+    registry?: StorageRegistry;
+    /**
+     * Declared storage sources, surfaced by `GET /sources` so the client can
+     * bootstrap its registry. Carries the frontend `transport` (server vs
+     * direct) and human-readable labels. Server-transport sources are also
+     * derived from the registry; `direct` sources (e.g. Firebase Storage) only
+     * exist here since the backend does not proxy them.
+     */
+    sources?: StorageSourceDefinition[];
+    /** 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;
+    /**
+     * When provided, storage routes delegate auth to this adapter instead
+     * of the built-in JWT module. This mirrors how data routes use
+     * `createAdapterAuthMiddleware()` and avoids the "JWT secret not
+     * configured" crash when `configureJwt()` was never called.
+     */
+    authAdapter?: AuthAdapter;
+}
+/**
+ * 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/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/storage/tus-handler.d.ts

@@ -0,0 +1,53 @@
+/**
+ * TUS Protocol Handler
+ *
+ * Implements the TUS v1.0.0 resumable upload protocol with the
+ * Creation and Termination extensions. Uploads are stored in a
+ * temporary directory and moved to final storage on completion.
+ *
+ * @see https://tus.io/protocols/resumable-upload
+ */
+import type { Context } from "hono";
+import type { StorageController } from "./types";
+import type { StorageRegistry } from "./storage-registry";
+/**
+ * TUS resumable upload handler.
+ *
+ * Each instance manages uploads for a single storage root. The
+ * `storageController` is used to finalize completed uploads by
+ * calling `putObject`.
+ */
+export declare class TusHandler {
+    private storageController?;
+    private storageRegistry?;
+    private uploads;
+    private tusDir;
+    private cleanupTimer?;
+    constructor(storageBaseDir: string, storageController?: StorageController | undefined, storageRegistry?: StorageRegistry | undefined);
+    /** Ensure the temp directory exists. */
+    private ensureDir;
+    /** Start periodic cleanup of stale uploads. */
+    startCleanup(): void;
+    /** Remove uploads that have been idle for longer than UPLOAD_EXPIRY_MS. */
+    private cleanupStale;
+    /**
+     * Parse the `Upload-Metadata` header.
+     *
+     * Format: `key base64value,key2 base64value2`
+     */
+    private parseMetadata;
+    /** `OPTIONS /tus` — TUS capability discovery. */
+    options(): Response;
+    /** `POST /tus` — Create a new upload. */
+    create(c: Context): Promise<Response>;
+    /** `HEAD /tus/:id` — Query upload progress. */
+    head(c: Context, id: string): Response;
+    /** `PATCH /tus/:id` — Append data to an upload. */
+    patch(c: Context, id: string): Promise<Response>;
+    /** `DELETE /tus/:id` — Cancel and remove an upload. */
+    delete(c: Context, id: string): Promise<Response>;
+    /**
+     * Move a completed upload into the storage controller.
+     */
+    private finalize;
+}

package/{src/storage/types.ts → dist/storage/types.d.ts}

@@ -1,9 +1,7 @@
 /**
  * Storage configuration and types for Rebase backend
  */
-
-import { StorageSource, UploadFileProps, UploadFileResult, DownloadConfig, StorageListResult, StorageReference } from "@rebasepro/types";
-
+import { UploadFileProps, UploadFileResult, DownloadConfig, StorageListResult } from "@rebasepro/types";
 /**
  * Local filesystem storage configuration
  */
@@ -18,7 +16,6 @@ export interface LocalStorageConfig {
     /** Base URL for generating download URLs (default: auto-detected from request) */
     baseUrl?: string;
 }
-
 /**
  * S3-compatible storage configuration (works with AWS S3 and MinIO)
  */
@@ -43,21 +40,44 @@ export interface S3StorageConfig {
     /** URL expiration time in seconds for signed URLs (default: 3600) */
     signedUrlExpiration?: number;
 }
-
 /**
- * Storage configuration — local filesystem or S3-compatible.
+ * Google Cloud Storage configuration (works with GCS and Firebase Storage)
+ */
+export interface GCSStorageConfig {
+    type: "gcs";
+    /** GCS bucket name (e.g. "my-project.appspot.com" for Firebase Storage) */
+    bucket: string;
+    /** GCP project ID (optional, auto-detected from credentials) */
+    projectId?: string;
+    /** Path to service account JSON key file */
+    keyFilename?: string;
+    /** Service account credentials object (alternative to keyFilename) */
+    credentials?: {
+        client_email: string;
+        private_key: string;
+        project_id?: string;
+    };
+    /** Maximum file size in bytes (default: 50MB) */
+    maxFileSize?: number;
+    /** Allowed MIME types */
+    allowedMimeTypes?: string[];
+    /** Signed URL expiration in seconds (default: 3600) */
+    signedUrlExpiration?: number;
+}
+/**
+ * Storage configuration — local filesystem, S3-compatible, or Google Cloud Storage.
  *
  * **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).
+ * - `gcs` — Native Google Cloud Storage / Firebase Storage via `@google-cloud/storage`.
  *
  * **Custom providers:**
- * For cloud-native storage (GCS, Azure Blob, etc.), implement the `StorageController`
+ * For other cloud storage (Azure Blob, etc.), implement the `StorageController`
  * interface and pass the instance directly to the `storage` config.
  */
-export type BackendStorageConfig = LocalStorageConfig | S3StorageConfig;
-
+export type BackendStorageConfig = LocalStorageConfig | S3StorageConfig | GCSStorageConfig;
 /**
  * Storage controller interface for backend implementations
  */
@@ -66,22 +86,18 @@ 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
      */
@@ -90,7 +106,6 @@ export interface StorageController {
         maxResults?: number;
         pageToken?: string;
     }): Promise<StorageListResult>;
-
     /**
      * Get the storage provider identifier.
      *
@@ -99,36 +114,15 @@ export interface StorageController {
      */
     getType(): string;
 }
-
 /**
  * Default maximum file size (50MB)
  */
-export const DEFAULT_MAX_FILE_SIZE = 50 * 1024 * 1024;
-
+export declare const DEFAULT_MAX_FILE_SIZE: number;
 /**
  * Common image MIME types
  */
-export const IMAGE_MIME_TYPES = [
-    "image/jpeg",
-    "image/png",
-    "image/gif",
-    "image/webp",
-    "image/svg+xml",
-    "image/bmp",
-    "image/tiff"
-];
-
+export declare const IMAGE_MIME_TYPES: string[];
 /**
  * Common document MIME types
  */
-export const DOCUMENT_MIME_TYPES = [
-    "application/pdf",
-    "application/msword",
-    "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
-    "application/vnd.ms-excel",
-    "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
-    "application/vnd.ms-powerpoint",
-    "application/vnd.openxmlformats-officedocument.presentationml.presentation",
-    "text/plain",
-    "text/csv"
-];
+export declare const DOCUMENT_MIME_TYPES: string[];

package/dist/types/index.d.ts

@@ -0,0 +1,11 @@
+import { Entity, FetchCollectionProps, FetchOneProps } 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 FetchOneProps<M> {
+    subscriptionId: string;
+    onUpdate: (entity: Entity<M> | null) => void;
+    onError?: (error: Error) => void;
+}

package/dist/utils/dev-port.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 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.
+ *
+ * @internal Not part of the stable public API. Exported only because the
+ * official app template (`packages/cli/templates/template/backend/src/index.ts`
+ * and `app/backend/src/index.ts`) calls it directly in dev mode. Its dev-only
+ * port-affinity behavior is an implementation detail and may change without
+ * a major version bump.
+ */
+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;
+    /** Service key to include in the state file for MCP server auto-discovery. */
+    serviceKey?: string;
+}): Promise<number>;
+/**
+ * Clean up the dev port file and state file (call on graceful shutdown).
+ *
+ * @internal Not part of the stable public API. See {@link listenWithPortRetry}.
+ */
+export declare function cleanupDevPortFile(dir: string): void;

package/dist/utils/dynamic-import.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Shape returned by a dynamic module import: an object whose `default`
+ * property holds the module's default export (CJS `module.exports` is exposed
+ * as `default` by Node's ESM interop).
+ */
+export interface ImportedModule {
+    default?: unknown;
+    [key: string]: unknown;
+}
+/**
+ * Imports a module by file URL. Injected into the directory loaders so tests
+ * can supply a deterministic importer.
+ */
+export type ModuleImporter = (url: string) => Promise<ImportedModule>;
+/**
+ * Native ESM dynamic import.
+ *
+ * Wrapped in `new Function` so TypeScript / bundlers don't down-compile the
+ * `import()` to `require()` — the loaders must import user-authored `.ts`/`.js`
+ * files at runtime using the host's real ESM loader. This is the production
+ * default for {@link loadFunctionsFromDirectory} / {@link loadCronJobsFromDirectory}.
+ *
+ * @internal
+ */
+export declare const nativeDynamicImport: ModuleImporter;