@rebasepro/server-core 0.6.1 → 0.8.0

package/src/email/types.ts

@@ -57,6 +57,14 @@ export type WelcomeEmailTemplateFunction = (
     appName: string
 ) => { subject: string; html: string; text?: string };
 
+/**
+ * Template function for magic link emails
+ */
+export type MagicLinkTemplateFunction = (
+    magicLinkUrl: string,
+    user: { email: string; displayName?: string | null }
+) => { subject: string; html: string; text?: string };
+
 /**
  * Complete email configuration
  */
@@ -89,6 +97,13 @@ export interface EmailConfig {
      */
     verifyEmailUrl?: string;
 
+    /**
+     * Base URL for magic link login (e.g., "https://myapp.com")
+     * The magic link will be: {baseUrl}/auth/magic-link?token={token}
+     * Falls back to `resetPasswordUrl` if not set.
+     */
+    magicLinkUrl?: string;
+
     /**
      * Application name to use in email templates
      */
@@ -102,5 +117,6 @@ export interface EmailConfig {
         emailVerification?: EmailVerificationTemplateFunction;
         userInvitation?: UserInvitationTemplateFunction;
         welcomeEmail?: WelcomeEmailTemplateFunction;
+        magicLink?: MagicLinkTemplateFunction;
     };
 }

package/src/functions/define-function.ts

@@ -0,0 +1,59 @@
+import { Hono } from "hono";
+import type { RebaseClient } from "@rebasepro/types";
+import type { HonoEnv } from "../api/types";
+import { rebase } from "../singleton";
+
+/**
+ * Typed context injected into a function authored with {@link defineFunction}.
+ *
+ * Surfaces the app-scoped Rebase singleton so handlers don't need to reach
+ * for the global `rebase` import. Request-scoped values (the authenticated
+ * `user`, the RLS-scoped `driver`, the `apiKey`, the `requestId`) are typed
+ * on the Hono context via {@link HonoEnv} — read them with `c.get("user")`
+ * / `c.var.driver` inside a handler.
+ */
+export interface RebaseFunctionContext {
+    /**
+     * The server-side Rebase singleton (`data`, `auth`, `storage`, `email`,
+     * `sql`). `rebase.data` runs with **admin privileges** (no RLS) — use the
+     * request `driver` (`c.var.driver`) for user-scoped queries.
+     */
+    rebase: RebaseClient;
+}
+
+/**
+ * Typed authoring contract for a custom backend function.
+ *
+ * A custom function is a file in the `functionsDir` that default-exports a
+ * Hono app; the loader mounts it at `/<filename>`. `defineFunction` is the
+ * typed opt-in for that contract: it hands you a pre-typed `Hono<HonoEnv>`
+ * app (so `c.var.user` / `c.var.driver` are typed) plus a
+ * {@link RebaseFunctionContext}, and returns exactly the Hono app the loader
+ * already accepts — so it is fully interchangeable with a plain
+ * `export default new Hono()`.
+ *
+ * @example
+ * ```ts
+ * import { defineFunction, requireAuth } from "@rebasepro/server-core";
+ *
+ * export default defineFunction((app, { rebase }) => {
+ *     app.use("/*", requireAuth);
+ *     app.get("/home", async (c) => {
+ *         const [stats] = await rebase.sql!(`SELECT count(*) AS n FROM orders`);
+ *         return c.json({ orders: Number(stats.n) });
+ *     });
+ * });
+ * ```
+ *
+ * @param definition Receives the function's Hono app and the typed context.
+ *   Register routes on the provided `app` and return nothing, or return your
+ *   own `Hono<HonoEnv>` app to use instead.
+ * @returns The Hono app to default-export from the function file.
+ */
+export function defineFunction(
+    definition: (app: Hono<HonoEnv>, ctx: RebaseFunctionContext) => void | Hono<HonoEnv>
+): Hono<HonoEnv> {
+    const app = new Hono<HonoEnv>();
+    const returned = definition(app, { rebase });
+    return returned instanceof Hono ? returned : app;
+}

package/src/functions/function-loader.ts

@@ -24,6 +24,10 @@ export async function loadFunctionsFromDirectory(
     directory: string
 ): Promise<LoadedFunction[]> {
     const functions: LoadedFunction[] = [];
+    // Aggregate problem files so a broken function surfaces as one loud
+    // summary line, not just a warning buried per-file. We still don't throw:
+    // a single malformed function must not crash server boot.
+    const problems: string[] = [];
 
     if (!fs.existsSync(directory)) {
         return functions;
@@ -51,6 +55,7 @@ export async function loadFunctionsFromDirectory(
 
                 if (!exported) {
                     logger.warn(`[functions] ${file}: no default export. Skipping.`);
+                    problems.push(`${file} (no default export)`);
                     continue;
                 }
 
@@ -86,16 +91,27 @@ app: result as Hono });
                     `  export type: ${exportType}${exported?.constructor?.name ? ` (${exported.constructor.name})` : ""}\n` +
                     `  prototype methods: ${keys}\n` +
                     "  Hint: ensure the function exports a Hono app created with the same hono version as the server.\n" +
+                    "  Author with `defineFunction(...)` from @rebasepro/server-core for a typed, checked contract.\n" +
                     "  The loader checks for .fetch() and .routes — any Hono-compatible app will work."
                 );
+                problems.push(`${file} (not a Hono app or factory)`);
             } catch (err: unknown) {
                 const message =
                     err instanceof Error ? err.message : String(err);
                 logger.error(`[functions] Failed to load ${file}: ${message}`);
+                problems.push(`${file} (threw: ${message})`);
             }
         }
     }
 
+    if (problems.length > 0) {
+        logger.warn(
+            `[functions] ${problems.length} function file(s) were skipped and will NOT be served:\n` +
+            problems.map((p) => `  - ${p}`).join("\n") + "\n" +
+            "  Fix these or author them with `defineFunction(...)` for a typed, compile-checked contract."
+        );
+    }
+
     return functions;
 }
 

package/src/functions/index.ts

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

package/src/index.ts

@@ -8,63 +8,96 @@
  */
 
 // =============================================================================
-// Abstract Interfaces (for database abstraction)
+// Core Initialization
 // =============================================================================
-export * from "./db/interfaces";
-export * from "./auth/interfaces";
-
-// Core functionality
-export * from "./init";
+export {
+    initializeRebaseBackend,
+    isAuthAdapter,
+    isDatabaseAdapter
+} from "./init";
+export type {
+    RebaseBackendConfig,
+    RebaseBackendInstance,
+    RebaseAuthConfig
+} from "./init";
 
+// =============================================================================
 // Server-side singleton (import { rebase } from "@rebasepro/server-core")
+// =============================================================================
 export { rebase, _setRebaseMock, _resetRebaseMock } from "./singleton";
 
-// Services
-export * from "./services/driver-registry";
+// =============================================================================
+// DB Abstractions (for database driver implementations)
+// =============================================================================
+export * from "./db/interfaces";
 
-// API types (HonoEnv, ApiConfig, etc.)
-export * from "./api/types";
+// =============================================================================
+// Auth
+// =============================================================================
+export * from "./auth";
 
-// API Generation
+// =============================================================================
+// API Layer
+// =============================================================================
 export * from "./api";
 
-// Types
-export * from "./types";
-export * from "./types/index";
-
-// Auth module
-export * from "./auth";
-
-// Email module
+// =============================================================================
+// Email
+// =============================================================================
 export * from "./email";
 
-// Storage module
+// =============================================================================
+// Storage
+// =============================================================================
 export * from "./storage";
 
-export * from "./utils/logging";
-export * from "./utils/logger";
-export * from "./utils/request-logger";
-export * from "./utils/request-id";
-export * from "./utils/sql";
-
-// Entity history
-export * from "./history";
+// =============================================================================
+// Entity History
+// =============================================================================
+export { createHistoryRoutes } from "./history";
 
+// =============================================================================
 // Custom Functions (auto-discovered Hono routes)
-export * from "./functions";
+// =============================================================================
+export { loadFunctionsFromDirectory, createFunctionRoutes, defineFunction } from "./functions";
+export type { LoadedFunction, RebaseFunctionContext } from "./functions";
 
+// =============================================================================
 // Cron Jobs (auto-discovered scheduled tasks)
-export * from "./cron";
-
+// =============================================================================
+export { loadCronJobsFromDirectory, CronScheduler, validateCronExpression, createCronRoutes, createCronStore } from "./cron";
+export type { LoadedCronJob, CronStore } from "./cron";
 
-// SPA serving helper
-export * from "./serve-spa";
+// =============================================================================
+// SQL Helpers (for RLS policies)
+// =============================================================================
+export { authUid, authRoles, authJwt } from "./utils/sql";
 
-// Dev-mode port resolution (retry on EADDRINUSE)
-export * from "./utils/dev-port";
+// =============================================================================
+// Logger
+// =============================================================================
+export { logger } from "./utils/logger";
+export type { Logger } from "./utils/logger";
 
-// Environment validation
+// =============================================================================
+// Environment Validation
+// =============================================================================
 export { loadEnv } from "./env";
 export type { RebaseEnv } from "./env";
-export { z } from "zod";
 
+// =============================================================================
+// Server-core specific types (subscription types)
+// =============================================================================
+export * from "./types";
+
+// =============================================================================
+// Driver Registry
+// =============================================================================
+export * from "./services/driver-registry";
+
+// =============================================================================
+// Internal plumbing exported for the official app/backend
+// =============================================================================
+export { cleanupDevPortFile, listenWithPortRetry } from "./utils/dev-port";
+export { serveSPA } from "./serve-spa";
+export { z } from "zod";