@rebasepro/server-core 0.4.0 → 0.5.0

package/README.md

@@ -1,40 +1,77 @@
-# @rebasepro/backend
+# @rebasepro/server-core
 
-PostgreSQL and Drizzle ORM backend implementation for Rebase.
-
-This package provides a complete backend solution for Rebase applications using PostgreSQL as the database and Drizzle ORM for type-safe database operations.
+Database-agnostic backend core for Rebase.
 
 ## Installation
 
 ```bash
-npm install @rebasepro/backend @rebasepro/core
+pnpm add @rebasepro/server-core
 ```
 
-## Usage
+## What This Package Does
 
-```typescript
-import { createBackend } from "@rebasepro/backend";
+This is the central orchestrator for any Rebase backend. It provides the framework-level plumbing — HTTP routing (Hono), authentication middleware, storage, email, cron jobs, custom functions, and the REST/GraphQL API generator — without being coupled to any specific database. Database implementations are plugged in via driver packages like `@rebasepro/server-postgresql` or `@rebasepro/server-mongodb`.
 
-const backend = createBackend({
-  connectionString: "postgresql://user:password@localhost:5432/database",
-  schema: "public",
-  debug: true
-});
-```
+## Key Exports
+
+| Export | Description |
+|--------|-------------|
+| `initializeRebaseBackend(config)` | Main entry point. Wires up drivers, auth, storage, API routes, cron, and custom functions. Returns a `RebaseBackendInstance`. |
+| `rebase` | Server-side singleton (`RebaseClient`). Available after init. Admin-level access to data, auth, email, and storage. |
+| `loadEnv()` | Validates `process.env` against the Rebase env schema (Zod). Auto-generates dev secrets. Supports `extend` for custom vars. |
+| `serveSPA(app, config)` | Mounts SPA static-file serving + index.html fallback on a Hono app. |
+| `RebaseBackendConfig` | Config type for `initializeRebaseBackend`. |
+| `RebaseAuthConfig` | Auth config type (JWT, OAuth providers, hooks, service key). |
+| `RebaseBackendInstance` | Return type — includes `driver`, `healthCheck()`, `shutdown()`, `cronScheduler`, `storageController`, etc. |
+| `RebaseEnv` | Zod-inferred type of validated environment variables. |
+| `z` | Re-exported Zod instance for extending `loadEnv`. |
+| `_setRebaseMock` / `_resetRebaseMock` | Test helpers to mock the `rebase` singleton (NODE_ENV=test only). |
 
-## Features
+Also re-exports all abstract interfaces (`DatabaseAdapter`, `AuthAdapter`, `DataDriver`, etc.), API types (`HonoEnv`, `ApiConfig`), auth module, email module, storage module, history module, cron module, custom functions, logging utilities, and driver registry.
 
-- PostgreSQL database support
-- Drizzle ORM integration
-- Type-safe database operations
-- Full Rebase compatibility
-- Migration support
-- Connection pooling
+## Quick Start
 
-## Development
+```typescript
+import { serve } from "@hono/node-server";
+import { Hono } from "hono";
+import { initializeRebaseBackend, loadEnv, serveSPA } from "@rebasepro/server-core";
+import { createPostgresAdapter } from "@rebasepro/server-postgresql";
 
-This package is part of the Rebase monorepo. For development instructions, see the main repository README.
+// 1. Load and validate environment
+const env = loadEnv();
+
+// 2. Create Hono app + HTTP server
+const app = new Hono();
+const server = serve({ fetch: app.fetch, port: env.PORT });
+
+// 3. Initialize Rebase
+const backend = await initializeRebaseBackend({
+  app,
+  server,
+  database: createPostgresAdapter({ connection: db, schema }),
+  collections: myCollections,
+  auth: {
+    collection: defaultUsersCollection,
+    jwtSecret: env.JWT_SECRET,
+    allowRegistration: env.ALLOW_REGISTRATION,
+    serviceKey: env.REBASE_SERVICE_KEY,
+    google: { clientId: env.GOOGLE_CLIENT_ID },
+  },
+  storage: { type: "s3", bucket: env.S3_BUCKET },
+  functionsDir: "./functions",
+  cronsDir: "./crons",
+});
+
+// 4. Optionally serve a frontend SPA
+serveSPA(app, { frontendPath: "./frontend/dist" });
+```
 
-## License
+## Related Packages
 
-MIT
+| Package | Role |
+|---------|------|
+| `@rebasepro/server-postgresql` | PostgreSQL database driver (Drizzle ORM) |
+| `@rebasepro/server-mongodb` | MongoDB database driver |
+| `@rebasepro/types` | Shared type definitions (`DataDriver`, `EntityCollection`, etc.) |
+| `@rebasepro/client` | Client SDK used internally by the `rebase` singleton |
+| `@rebasepro/common` | Shared utilities and default collections |

package/dist/common/src/util/permissions.d.ts

@@ -1,6 +1,14 @@
-import { AuthController, Entity, EntityCollection, User } from "@rebasepro/types";
-export declare function checkOperation<M extends Record<string, unknown>, USER extends User>(collection: EntityCollection<M>, authController: AuthController<USER>, entity: Entity<M> | null, targetOperation: "select" | "insert" | "update" | "delete"): boolean;
-export declare function canReadCollection<M extends Record<string, unknown>, USER extends User>(collection: EntityCollection<M>, authController: AuthController<USER>): boolean;
-export declare function canEditEntity<M extends Record<string, unknown>, USER extends User>(collection: EntityCollection<M>, authController: AuthController<USER>, path: string, entity: Entity<M> | null): boolean;
-export declare function canCreateEntity<M extends Record<string, unknown>, USER extends User>(collection: EntityCollection<M>, authController: AuthController<USER>, path: string, entity: Entity<M> | null): boolean;
-export declare function canDeleteEntity<M extends Record<string, unknown>, USER extends User>(collection: EntityCollection<M>, authController: AuthController<USER>, path: string, entity: Entity<M> | null): boolean;
+import { Entity, EntityCollection, User } from "@rebasepro/types";
+/**
+ * Minimal auth context for permission checking.
+ * Only requires the user object — avoids forcing callers to construct
+ * a full AuthController just to check permissions.
+ */
+export interface AuthContext<USER extends User = User> {
+    user: USER | null;
+}
+export declare function checkOperation<M extends Record<string, unknown>, USER extends User>(collection: EntityCollection<M>, authContext: AuthContext<USER>, entity: Entity<M> | null, targetOperation: "select" | "insert" | "update" | "delete"): boolean;
+export declare function canReadCollection<M extends Record<string, unknown>, USER extends User>(collection: EntityCollection<M>, authContext: AuthContext<USER>): boolean;
+export declare function canEditEntity<M extends Record<string, unknown>, USER extends User>(collection: EntityCollection<M>, authContext: AuthContext<USER>, path: string, entity: Entity<M> | null): boolean;
+export declare function canCreateEntity<M extends Record<string, unknown>, USER extends User>(collection: EntityCollection<M>, authContext: AuthContext<USER>, path: string, entity: Entity<M> | null): boolean;
+export declare function canDeleteEntity<M extends Record<string, unknown>, USER extends User>(collection: EntityCollection<M>, authContext: AuthContext<USER>, path: string, entity: Entity<M> | null): boolean;

package/dist/index.es.js

@@ -2790,6 +2790,9 @@ class ApiError extends Error {
     return new ApiError(503, code2, message);
   }
 }
+function isRebaseApiError(error2) {
+  return error2 instanceof Error;
+}
 const errorHandler = (err, c) => {
   const error2 = err;
   if (error2 instanceof ApiError || error2.name === "ApiError") {
@@ -3330,9 +3333,10 @@ class RestApiGenerator {
         }
         return c.json(response, 201);
       } catch (error2) {
-        const err = error2;
-        err.code = err.code || "BAD_REQUEST";
-        throw err;
+        if (isRebaseApiError(error2) && !error2.code) {
+          error2.code = "BAD_REQUEST";
+        }
+        throw error2;
       }
     });
     this.router.put(`${basePath}/:id`, async (c) => {
@@ -3368,9 +3372,10 @@ class RestApiGenerator {
         }
         return c.json(response);
       } catch (error2) {
-        const err = error2;
-        err.code = err.code || "BAD_REQUEST";
-        throw err;
+        if (isRebaseApiError(error2) && !error2.code) {
+          error2.code = "BAD_REQUEST";
+        }
+        throw error2;
       }
     });
     this.router.delete(`${basePath}/:id`, async (c) => {
@@ -3447,6 +3452,7 @@ class RestApiGenerator {
       if (!parsed) return next();
       const driver = c.get("driver") || this.driver;
       this.enforceApiKeyPermission(c, c.req.param("parent"));
+      const hookCtx = this.buildHookContext(c, "GET");
       if (parsed.entityId === "count") {
         const queryDict = c.req.queries();
         const queryOptions = parseQueryOptions(queryDict);
@@ -3465,7 +3471,10 @@ class RestApiGenerator {
           entityId: parsed.entityId
         });
         if (!entity) throw ApiError.notFound("Entity not found");
-        return c.json(this.flattenEntity(entity));
+        const flatResult = this.flattenEntity(entity);
+        const hookResult = await this.applyAfterRead(c.req.param("parent"), flatResult, hookCtx);
+        if (!hookResult) throw ApiError.notFound("Entity not found");
+        return c.json(hookResult);
       } else {
         const queryDict = c.req.queries();
         const queryOptions = parseQueryOptions(queryDict);
@@ -3478,13 +3487,20 @@ class RestApiGenerator {
           order: queryOptions.orderBy?.[0]?.direction === "desc" ? "desc" : "asc",
           searchString
         });
+        let flatEntities = entities.map((e) => this.flattenEntity(e));
+        flatEntities = await this.applyAfterReadBatch(c.req.param("parent"), flatEntities, hookCtx);
+        const total = driver.countEntities ? await driver.countEntities({
+          path: parsed.collectionPath,
+          filter: queryOptions.where,
+          searchString
+        }) : flatEntities.length;
         return c.json({
-          data: entities.map((e) => this.flattenEntity(e)),
+          data: flatEntities,
           meta: {
-            total: entities.length,
+            total,
             limit: queryOptions.limit,
             offset: queryOptions.offset,
-            hasMore: false
+            hasMore: (queryOptions.offset || 0) + flatEntities.length < total
           }
         });
       }
@@ -3496,14 +3512,24 @@ class RestApiGenerator {
       const parsed = parseSubPath(rawPath);
       if (!parsed || parsed.entityId) return next();
       const driver = c.get("driver") || this.driver;
+      const hookCtx = this.buildHookContext(c, "POST");
       this.enforceApiKeyPermission(c, c.req.param("parent"));
-      const body = await c.req.json().catch(() => ({}));
+      let body = await c.req.json().catch(() => ({}));
+      if (this.dataHooks?.beforeSave) {
+        body = await this.dataHooks.beforeSave(parsed.collectionPath, body, void 0, hookCtx);
+      }
       const entity = await driver.saveEntity({
         path: parsed.collectionPath,
         values: body,
         status: "new"
       });
-      return c.json(this.formatResponse(entity), 201);
+      const response = this.formatResponse(entity);
+      if (this.dataHooks?.afterSave) {
+        Promise.resolve(this.dataHooks.afterSave(parsed.collectionPath, response, hookCtx)).catch((err) => {
+          console.error("[BackendHooks] data.afterSave error:", err instanceof Error ? err.message : err);
+        });
+      }
+      return c.json(response, 201);
     });
     this.router.put("/:parent/:parentId/:rest{.+}", async (c, next) => {
       const rest = c.req.param("rest");
@@ -3512,15 +3538,25 @@ class RestApiGenerator {
       const parsed = parseSubPath(rawPath);
       if (!parsed || !parsed.entityId) return next();
       const driver = c.get("driver") || this.driver;
+      const hookCtx = this.buildHookContext(c, "PUT");
       this.enforceApiKeyPermission(c, c.req.param("parent"));
-      const body = await c.req.json().catch(() => ({}));
+      let body = await c.req.json().catch(() => ({}));
+      if (this.dataHooks?.beforeSave) {
+        body = await this.dataHooks.beforeSave(parsed.collectionPath, body, parsed.entityId, hookCtx);
+      }
       const entity = await driver.saveEntity({
         path: parsed.collectionPath,
         entityId: parsed.entityId,
         values: body,
         status: "existing"
       });
-      return c.json(this.formatResponse(entity));
+      const response = this.formatResponse(entity);
+      if (this.dataHooks?.afterSave) {
+        Promise.resolve(this.dataHooks.afterSave(parsed.collectionPath, response, hookCtx)).catch((err) => {
+          console.error("[BackendHooks] data.afterSave error:", err instanceof Error ? err.message : err);
+        });
+      }
+      return c.json(response);
     });
     this.router.delete("/:parent/:parentId/:rest{.+}", async (c, next) => {
       const rest = c.req.param("rest");
@@ -3529,15 +3565,24 @@ class RestApiGenerator {
       const parsed = parseSubPath(rawPath);
       if (!parsed || !parsed.entityId) return next();
       const driver = c.get("driver") || this.driver;
+      const hookCtx = this.buildHookContext(c, "DELETE");
       this.enforceApiKeyPermission(c, c.req.param("parent"));
       const existingEntity = await driver.fetchEntity({
         path: parsed.collectionPath,
         entityId: parsed.entityId
       });
       if (!existingEntity) throw ApiError.notFound("Entity not found");
+      if (this.dataHooks?.beforeDelete) {
+        await this.dataHooks.beforeDelete(parsed.collectionPath, parsed.entityId, hookCtx);
+      }
       await driver.deleteEntity({
         entity: existingEntity
       });
+      if (this.dataHooks?.afterDelete) {
+        Promise.resolve(this.dataHooks.afterDelete(parsed.collectionPath, parsed.entityId, hookCtx)).catch((err) => {
+          console.error("[BackendHooks] data.afterDelete error:", err instanceof Error ? err.message : err);
+        });
+      }
       return new Response(null, {
         status: 204
       });
@@ -13020,14 +13065,11 @@ function createAuthRoutes(config) {
     if (!factor || factor.userId !== userCtx.userId) {
       throw ApiError.notFound("MFA factor not found");
     }
-    const isRecoveryCode = code2.length > 6;
-    let isValid2 = false;
-    if (isRecoveryCode) {
+    const secretBuffer = base32Decode(factor.secretEncrypted);
+    let isValid2 = verifyTotp(secretBuffer, code2);
+    if (!isValid2) {
       const codeHash = hashRecoveryCode(code2);
       isValid2 = await authRepo.useRecoveryCode(userCtx.userId, codeHash);
-    } else {
-      const secretBuffer = base32Decode(factor.secretEncrypted);
-      isValid2 = verifyTotp(secretBuffer, code2);
     }
     if (!isValid2) {
       throw ApiError.unauthorized("Invalid verification code", "INVALID_CODE");
@@ -13543,7 +13585,6 @@ function createBuiltinAuthAdapter(config) {
       if (!payload) {
         return null;
       }
-      const extendedPayload = payload;
       let roles = payload.roles || [];
       try {
         roles = await authRepository.getUserRoleIds(payload.userId);
@@ -13552,8 +13593,8 @@ function createBuiltinAuthAdapter(config) {
       const isAdmin = roles.some((r) => r === "admin" || r === "schema-admin");
       return {
         uid: payload.userId,
-        email: extendedPayload.email ?? "",
-        displayName: extendedPayload.displayName ?? null,
+        email: payload.email ?? "",
+        displayName: payload.displayName ?? null,
         roles,
         isAdmin,
         rawToken: token
@@ -13573,7 +13614,6 @@ function createBuiltinAuthAdapter(config) {
       if (!payload) {
         return null;
       }
-      const extendedPayload = payload;
       let roles = payload.roles || [];
       try {
         roles = await authRepository.getUserRoleIds(payload.userId);
@@ -13582,8 +13622,8 @@ function createBuiltinAuthAdapter(config) {
       const isAdmin = roles.some((r) => r === "admin" || r === "schema-admin");
       return {
         uid: payload.userId,
-        email: extendedPayload.email ?? "",
-        displayName: extendedPayload.displayName ?? null,
+        email: payload.email ?? "",
+        displayName: payload.displayName ?? null,
         roles,
         isAdmin,
         rawToken: token
@@ -38575,7 +38615,9 @@ async function _initializeRebaseBackend(config) {
     }
     if (bootstrapper.initializeRealtime) {
       const realtime = await bootstrapper.initializeRealtime({}, driverResult);
-      realtimeServices[b.id || bootstrapper.type] = realtime;
+      if (realtime) {
+        realtimeServices[b.id || bootstrapper.type] = realtime;
+      }
     }
   }
   const driverRegistry = DefaultDriverRegistry.create(delegates);
@@ -39054,7 +39096,7 @@ async function _initializeRebaseBackend(config) {
       });
     }
   }
-  if (defaultBootstrapper.initializeWebsockets) {
+  if (defaultBootstrapper.initializeWebsockets && defaultRealtimeService) {
     await defaultBootstrapper.initializeWebsockets(config.server, defaultRealtimeService, defaultDriver, config.auth, authAdapter);
   }
   logger.info("Rebase Backend Initialized");
@@ -39100,12 +39142,11 @@ async function _initializeRebaseBackend(config) {
         }
         for (const [key, rt] of Object.entries(realtimeServices)) {
           try {
-            const rtWithLifecycle = rt;
-            if (typeof rtWithLifecycle.destroy === "function") {
-              await rtWithLifecycle.destroy();
+            if (typeof rt.destroy === "function") {
+              await rt.destroy();
               logger.info(`Realtime service "${key}" destroyed`);
-            } else if (typeof rtWithLifecycle.stopListening === "function") {
-              await rtWithLifecycle.stopListening();
+            } else if (typeof rt.stopListening === "function") {
+              await rt.stopListening();
               logger.info(`Realtime service "${key}" LISTEN client stopped`);
             }
           } catch (err) {
@@ -51252,6 +51293,7 @@ export {
   isAuthAdapter,
   isDatabaseAdapter,
   isOperationAllowed,
+  isRebaseApiError,
   isTransformableImage,
   listenWithPortRetry,
   loadCronJobsFromDirectory,