@env-hopper/backend-core 2.0.1-alpha.1 → 2.0.1-alpha.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@env-hopper/backend-core",
-  "version": "2.0.1-alpha.1",
+  "version": "2.0.1-alpha.3",
   "description": "Backend core library for Env Hopper",
   "homepage": "https://github.com/lislon/env-hopper",
   "repository": {
@@ -48,8 +48,8 @@
     "tsyringe": "^4.10.0",
     "yaml": "^2.8.0",
     "zod": "^4.3.5",
-    "@env-hopper/shared-core": "2.0.1-alpha.1",
-    "@env-hopper/table-sync": "2.0.1-alpha"
+    "@env-hopper/table-sync": "2.0.1-alpha.3",
+    "@env-hopper/shared-core": "2.0.1-alpha.1"
   },
   "devDependencies": {
     "@tanstack/vite-config": "^0.4.3",

package/src/db/client.ts

@@ -13,6 +13,14 @@ export function getDbClient(): PrismaClient {
   return prismaClient
 }
 
+/**
+ * Sets the internal Prisma client instance.
+ * Used by middleware to bridge with existing getDbClient() usage.
+ */
+export function setDbClient(client: PrismaClient): void {
+  prismaClient = client
+}
+
 /**
  * Connects to the database.
  * Call this before performing database operations.

package/src/db/index.ts

@@ -1,16 +1,20 @@
 // Database connection
-export { connectDb, disconnectDb, getDbClient } from './client'
+export { connectDb, disconnectDb, getDbClient, setDbClient } from './client'
 
 // Table sync utilities
 export {
-  tableSyncPrisma, type MakeTFromPrismaModel, type ObjectKeys,
-  type ScalarFilter, type ScalarKeys, type TableSyncParamsPrisma
+  tableSyncPrisma,
+  type MakeTFromPrismaModel,
+  type ObjectKeys,
+  type ScalarFilter,
+  type ScalarKeys,
+  type TableSyncParamsPrisma,
 } from './tableSyncPrismaAdapter'
 
 export {
   TABLE_SYNC_MAGAZINE,
   type TableSyncMagazine,
-  type TableSyncMagazineModelNameKey
+  type TableSyncMagazineModelNameKey,
 } from './tableSyncMagazine'
 
 // App catalog sync

package/src/index.ts

@@ -4,8 +4,8 @@ export { createTrpcRouter } from './server/controller'
 export type { TRPCRouter } from './server/controller'
 export { createEhTrpcContext } from './server/ehTrpcContext'
 export type {
-    EhTrpcContext,
-    EhTrpcContextOptions
+  EhTrpcContext,
+  EhTrpcContextOptions,
 } from './server/ehTrpcContext'
 
 export { staticControllerContract } from './server/ehStaticControllerContract'
@@ -20,92 +20,107 @@ export * from './types/index'
 
 // Auth
 export {
-    createAuth,
-    type AuthConfig,
-    type BetterAuth
+  createAuth,
+  type AuthConfig,
+  type BetterAuth,
 } from './modules/auth/auth'
 
-export {
-    registerAuthRoutes
-} from './modules/auth/registerAuthRoutes'
+export { registerAuthRoutes } from './modules/auth/registerAuthRoutes'
 
-export {
-    createAuthRouter,
-    type AuthRouter
-} from './modules/auth/authRouter'
+export { createAuthRouter, type AuthRouter } from './modules/auth/authRouter'
 
 export {
-    getAuthProvidersFromEnv,
-    getAuthPluginsFromEnv,
-    validateAuthConfig
+  getAuthProvidersFromEnv,
+  getAuthPluginsFromEnv,
+  validateAuthConfig,
 } from './modules/auth/authProviders'
 
 export {
-    getUserGroups,
-    isMemberOfAnyGroup,
-    isMemberOfAllGroups,
-    getAdminGroupsFromEnv,
-    isAdmin,
-    requireAdmin,
-    requireGroups,
-    type UserWithGroups
+  getUserGroups,
+  isMemberOfAnyGroup,
+  isMemberOfAllGroups,
+  getAdminGroupsFromEnv,
+  isAdmin,
+  requireAdmin,
+  requireGroups,
+  type UserWithGroups,
 } from './modules/auth/authorizationUtils'
 
 // Admin
 export {
-    createAdminChatHandler,
-    tool,
-    type AdminChatHandlerOptions
+  createAdminChatHandler,
+  tool,
+  type AdminChatHandlerOptions,
 } from './modules/admin/chat/createAdminChatHandler'
 
 export {
-    createDatabaseTools,
-    createPrismaDatabaseClient, DEFAULT_ADMIN_SYSTEM_PROMPT, type DatabaseClient
+  createDatabaseTools,
+  createPrismaDatabaseClient,
+  DEFAULT_ADMIN_SYSTEM_PROMPT,
+  type DatabaseClient,
 } from './modules/admin/chat/createDatabaseTools'
 
 // Icon management
 export {
-    registerIconRestController,
-    type IconRestControllerConfig
+  registerIconRestController,
+  type IconRestControllerConfig,
 } from './modules/icons/iconRestController'
 
 export {
-    getAssetByName,
-    upsertIcon,
-    upsertIcons,
-    type UpsertIconInput
+  getAssetByName,
+  upsertIcon,
+  upsertIcons,
+  type UpsertIconInput,
 } from './modules/icons/iconService'
 
 // Asset management (universal for icons, screenshots, etc.)
 export {
-    registerAssetRestController,
-    type AssetRestControllerConfig
+  registerAssetRestController,
+  type AssetRestControllerConfig,
 } from './modules/assets/assetRestController'
 
 export {
-    registerScreenshotRestController,
-    type ScreenshotRestControllerConfig
+  registerScreenshotRestController,
+  type ScreenshotRestControllerConfig,
 } from './modules/assets/screenshotRestController'
 
-export {
-    createScreenshotRouter
-} from './modules/assets/screenshotRouter'
+export { createScreenshotRouter } from './modules/assets/screenshotRouter'
 
-export {
-    syncAssets,
-    type SyncAssetsConfig
-} from './modules/assets/syncAssets'
+export { syncAssets, type SyncAssetsConfig } from './modules/assets/syncAssets'
 
 // App Catalog Admin
-export {
-    createAppCatalogAdminRouter
-} from './modules/appCatalogAdmin/appCatalogAdminRouter'
+export { createAppCatalogAdminRouter } from './modules/appCatalogAdmin/appCatalogAdminRouter'
 
 // Database utilities
 export {
-    connectDb,
-    disconnectDb, getDbClient, syncAppCatalog, TABLE_SYNC_MAGAZINE, tableSyncPrisma, type MakeTFromPrismaModel, type ObjectKeys,
-    type ScalarFilter, type ScalarKeys, type SyncAppCatalogResult, type TableSyncMagazine,
-    type TableSyncMagazineModelNameKey, type TableSyncParamsPrisma
+  connectDb,
+  disconnectDb,
+  getDbClient,
+  setDbClient,
+  syncAppCatalog,
+  TABLE_SYNC_MAGAZINE,
+  tableSyncPrisma,
+  type MakeTFromPrismaModel,
+  type ObjectKeys,
+  type ScalarFilter,
+  type ScalarKeys,
+  type SyncAppCatalogResult,
+  type TableSyncMagazine,
+  type TableSyncMagazineModelNameKey,
+  type TableSyncParamsPrisma,
 } from './db'
 
+// Middleware (batteries-included backend setup)
+export {
+  createEhMiddleware,
+  EhDatabaseManager,
+  type EhDatabaseConfig,
+  type EhAuthConfig,
+  type EhAdminChatConfig,
+  type EhFeatureToggles,
+  type EhBackendProvider,
+  type EhLifecycleHooks,
+  type EhMiddlewareOptions,
+  type EhMiddlewareResult,
+  type MiddlewareContext,
+} from './middleware'

package/src/middleware/backendResolver.ts

@@ -0,0 +1,49 @@
+import type { EhBackendCompanySpecificBackend } from '../types/backend/companySpecificBackend'
+import type { EhBackendProvider } from './types'
+
+/**
+ * Type guard to check if an object implements EhBackendCompanySpecificBackend.
+ */
+function isBackendInstance(obj: unknown): obj is EhBackendCompanySpecificBackend {
+  return (
+    typeof obj === 'object' &&
+    obj !== null &&
+    typeof (obj as EhBackendCompanySpecificBackend).getBootstrapData === 'function' &&
+    typeof (obj as EhBackendCompanySpecificBackend).getAvailabilityMatrix ===
+      'function' &&
+    typeof (obj as EhBackendCompanySpecificBackend).getNameMigrations ===
+      'function' &&
+    typeof (obj as EhBackendCompanySpecificBackend).getResourceJumps ===
+      'function' &&
+    typeof (obj as EhBackendCompanySpecificBackend).getResourceJumpsExtended ===
+      'function'
+  )
+}
+
+/**
+ * Normalizes different backend provider types into a consistent async factory function.
+ * Supports:
+ * - Direct object implementing EhBackendCompanySpecificBackend
+ * - Sync factory function that returns the backend
+ * - Async factory function that returns the backend
+ */
+export function createBackendResolver(
+  provider: EhBackendProvider,
+): () => Promise<EhBackendCompanySpecificBackend> {
+  // If it's already an object with the required methods, wrap it
+  if (isBackendInstance(provider)) {
+    return async () => provider
+  }
+
+  // If it's a function, call it and handle both sync and async results
+  if (typeof provider === 'function') {
+    return async () => {
+      const result = provider()
+      return result instanceof Promise ? result : result
+    }
+  }
+
+  throw new Error(
+    'Invalid backend provider: must be an object implementing EhBackendCompanySpecificBackend or a factory function',
+  )
+}

package/src/middleware/createEhMiddleware.ts

@@ -0,0 +1,177 @@
+import express, { Router } from 'express'
+import * as trpcExpress from '@trpc/server/adapters/express'
+import type { EhMiddlewareOptions, EhMiddlewareResult, MiddlewareContext } from './types'
+import { EhDatabaseManager } from './database'
+import { createBackendResolver } from './backendResolver'
+import { registerFeatures } from './featureRegistry'
+import { createTrpcRouter } from '../server/controller'
+import { createEhTrpcContext } from '../server/ehTrpcContext'
+import { createAuth } from '../modules/auth/auth'
+
+/**
+ * Creates a fully-configured env-hopper middleware.
+ *
+ * @example
+ * ```typescript
+ * // Simple usage with inline backend
+ * const eh = await createEhMiddleware({
+ *   basePath: '/api',
+ *   database: { url: process.env.DATABASE_URL! },
+ *   auth: {
+ *     baseURL: 'http://localhost:4000',
+ *     secret: process.env.AUTH_SECRET!,
+ *   },
+ *   backend: {
+ *     getBootstrapData: async () => loadStaticData(),
+ *     getAvailabilityMatrix: async () => ({}),
+ *     getNameMigrations: async () => false,
+ *     getResourceJumps: async () => ({ resourceJumps: [], envs: [], lateResolvableParams: [] }),
+ *     getResourceJumpsExtended: async () => ({ envs: [] }),
+ *   },
+ * })
+ *
+ * app.use(eh.router)
+ * await eh.connect()
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With DI-resolved backend (e.g., tsyringe)
+ * const eh = await createEhMiddleware({
+ *   basePath: '/api',
+ *   database: {
+ *     host: cfg.db.host,
+ *     port: cfg.db.port,
+ *     database: cfg.db.name,
+ *     username: cfg.db.username,
+ *     password: cfg.db.password,
+ *     schema: cfg.db.schema,
+ *   },
+ *   auth: {
+ *     baseURL: process.env.BETTER_AUTH_URL || 'http://localhost:4000',
+ *     secret: process.env.BETTER_AUTH_SECRET!,
+ *     providers: getAuthProvidersFromEnv(),
+ *     plugins: getAuthPluginsFromEnv(),
+ *   },
+ *   // Factory function - resolved fresh per request from DI container
+ *   backend: () => container.resolve(NateraEhBackend),
+ *   hooks: {
+ *     onRoutesRegistered: (router) => {
+ *       router.get('/health', (_, res) => res.send('ok'))
+ *     },
+ *   },
+ * })
+ * ```
+ */
+export async function createEhMiddleware(
+  options: EhMiddlewareOptions,
+): Promise<EhMiddlewareResult> {
+  // Normalize options with defaults
+  const basePath = options.basePath ?? '/api'
+  const normalizedOptions = { ...options, basePath }
+
+  // Check if database-dependent features are enabled
+  const features = options.features ?? {}
+  const iconsEnabled = features.icons !== false
+  const assetsEnabled = features.assets !== false
+  const screenshotsEnabled = features.screenshots !== false
+  const legacyIconEnabled = features.legacyIconEndpoint === true
+  const needsDatabase = iconsEnabled || assetsEnabled || screenshotsEnabled || legacyIconEnabled
+
+  // Validate database is provided when needed
+  if (needsDatabase && !options.database) {
+    throw new Error(
+      'Database configuration is required when icons, assets, screenshots, or legacyIconEndpoint features are enabled. ' +
+        'Either provide database config or disable these features.',
+    )
+  }
+
+  // Initialize database manager only if database config is provided
+  let dbManager: EhDatabaseManager | null = null
+  if (options.database) {
+    dbManager = new EhDatabaseManager(options.database)
+    // Initialize the client (which also sets the global singleton)
+    dbManager.getClient()
+  }
+
+  // Create auth instance
+  const auth = createAuth({
+    appName: options.auth.appName,
+    baseURL: options.auth.baseURL,
+    secret: options.auth.secret,
+    providers: options.auth.providers,
+    plugins: options.auth.plugins,
+    sessionExpiresIn: options.auth.sessionExpiresIn,
+    sessionUpdateAge: options.auth.sessionUpdateAge,
+  })
+
+  // Create tRPC router
+  const trpcRouter = createTrpcRouter(auth)
+
+  // Normalize backend provider to async factory function
+  const resolveBackend = createBackendResolver(options.backend)
+
+  // Create tRPC context factory
+  const createContext = async () => {
+    const companySpecificBackend = await resolveBackend()
+    return createEhTrpcContext({ companySpecificBackend })
+  }
+
+  // Create Express router
+  const router = Router()
+  router.use(express.json())
+
+  // Build middleware context for feature registration
+  const middlewareContext: MiddlewareContext = {
+    auth,
+    trpcRouter,
+    createContext,
+  }
+
+  // Register tRPC middleware (if enabled)
+  if (normalizedOptions.features?.trpc !== false) {
+    router.use(
+      `${basePath}/trpc`,
+      trpcExpress.createExpressMiddleware({
+        router: trpcRouter,
+        createContext,
+      }),
+    )
+  }
+
+  // Register all enabled features
+  registerFeatures(router, normalizedOptions, middlewareContext)
+
+  // Call onRoutesRegistered hook if provided
+  if (options.hooks?.onRoutesRegistered) {
+    await options.hooks.onRoutesRegistered(router)
+  }
+
+  return {
+    router,
+    auth,
+    trpcRouter,
+
+    async connect(): Promise<void> {
+      if (dbManager) {
+        await dbManager.connect()
+      }
+      if (options.hooks?.onDatabaseConnected) {
+        await options.hooks.onDatabaseConnected()
+      }
+    },
+
+    async disconnect(): Promise<void> {
+      if (options.hooks?.onDatabaseDisconnecting) {
+        await options.hooks.onDatabaseDisconnecting()
+      }
+      if (dbManager) {
+        await dbManager.disconnect()
+      }
+    },
+
+    addRoutes(callback: (router: Router) => void): void {
+      callback(router)
+    },
+  }
+}

package/src/middleware/database.ts

@@ -0,0 +1,62 @@
+import { PrismaClient } from '@prisma/client'
+import type { EhDatabaseConfig } from './types'
+import { setDbClient } from '../db/client'
+
+/**
+ * Formats a database connection URL from structured config.
+ */
+function formatConnectionUrl(config: EhDatabaseConfig): string {
+  if ('url' in config) {
+    return config.url
+  }
+
+  const { host, port, database, username, password, schema = 'public' } = config
+  return `postgresql://${username}:${encodeURIComponent(password)}@${host}:${port}/${database}?schema=${schema}`
+}
+
+/**
+ * Internal database manager used by the middleware.
+ * Handles connection URL formatting and lifecycle.
+ */
+export class EhDatabaseManager {
+  private client: PrismaClient | null = null
+  private config: EhDatabaseConfig
+
+  constructor(config: EhDatabaseConfig) {
+    this.config = config
+  }
+
+  /**
+   * Get or create the Prisma client instance.
+   * Uses lazy initialization for flexibility.
+   */
+  getClient(): PrismaClient {
+    if (!this.client) {
+      const datasourceUrl = formatConnectionUrl(this.config)
+
+      this.client = new PrismaClient({
+        datasourceUrl,
+        log:
+          process.env.NODE_ENV === 'development'
+            ? ['warn', 'error']
+            : ['warn', 'error'],
+      })
+
+      // Bridge with existing backend-core getDbClient() usage
+      setDbClient(this.client)
+    }
+    return this.client
+  }
+
+  async connect(): Promise<void> {
+    const client = this.getClient()
+    await client.$connect()
+  }
+
+  async disconnect(): Promise<void> {
+    if (this.client) {
+      await this.client.$disconnect()
+      this.client = null
+    }
+  }
+}

package/src/middleware/featureRegistry.ts

@@ -0,0 +1,149 @@
+import type { Router } from 'express'
+import { toNodeHandler } from 'better-auth/node'
+import type {
+  EhFeatureToggles,
+  EhMiddlewareOptions,
+  MiddlewareContext,
+} from './types'
+import { registerIconRestController } from '../modules/icons/iconRestController'
+import { registerAssetRestController } from '../modules/assets/assetRestController'
+import { registerScreenshotRestController } from '../modules/assets/screenshotRestController'
+import { createAdminChatHandler } from '../modules/admin/chat/createAdminChatHandler'
+import { getAssetByName } from '../modules/icons/iconService'
+
+interface FeatureRegistration {
+  name: keyof EhFeatureToggles
+  defaultEnabled: boolean
+  register: (
+    router: Router,
+    options: Required<Pick<EhMiddlewareOptions, 'basePath'>> &
+      EhMiddlewareOptions,
+    context: MiddlewareContext,
+  ) => void
+}
+
+const FEATURES: Array<FeatureRegistration> = [
+  {
+    name: 'auth',
+    defaultEnabled: true,
+    register: (router, options, ctx) => {
+      const basePath = options.basePath
+
+      // Explicit session endpoint handler
+      router.get(`${basePath}/auth/session`, async (req, res) => {
+        try {
+          const session = await ctx.auth.api.getSession({
+            headers: req.headers as HeadersInit,
+          })
+          if (session) {
+            res.json(session)
+          } else {
+            res.status(401).json({ error: 'Not authenticated' })
+          }
+        } catch (error) {
+          console.error('[Auth Session Error]', error)
+          res.status(500).json({ error: 'Internal server error' })
+        }
+      })
+
+      // Use toNodeHandler to adapt better-auth for Express/Node.js
+      const authHandler = toNodeHandler(ctx.auth)
+      router.all(`${basePath}/auth/{*any}`, authHandler)
+    },
+  },
+  {
+    name: 'icons',
+    defaultEnabled: true,
+    register: (router, options) => {
+      registerIconRestController(router, {
+        basePath: `${options.basePath}/icons`,
+      })
+    },
+  },
+  {
+    name: 'assets',
+    defaultEnabled: true,
+    register: (router, options) => {
+      registerAssetRestController(router, {
+        basePath: `${options.basePath}/assets`,
+      })
+    },
+  },
+  {
+    name: 'screenshots',
+    defaultEnabled: true,
+    register: (router, options) => {
+      registerScreenshotRestController(router, {
+        basePath: `${options.basePath}/screenshots`,
+      })
+    },
+  },
+  {
+    name: 'adminChat',
+    defaultEnabled: false, // Only enabled if adminChat config is provided
+    register: (router, options) => {
+      if (options.adminChat) {
+        router.post(
+          `${options.basePath}/admin/chat`,
+          createAdminChatHandler(options.adminChat),
+        )
+      }
+    },
+  },
+  {
+    name: 'legacyIconEndpoint',
+    defaultEnabled: false,
+    register: (router) => {
+      // Legacy endpoint at /static/icon/:icon for backwards compatibility
+      router.get('/static/icon/:icon', async (req, res) => {
+        const { icon } = req.params
+
+        if (!icon || !/^[a-z0-9-]+$/i.test(icon)) {
+          res.status(400).send('Invalid icon name')
+          return
+        }
+
+        try {
+          const dbIcon = await getAssetByName(icon)
+
+          if (!dbIcon) {
+            res.status(404).send('Icon not found')
+            return
+          }
+
+          res.setHeader('Content-Type', dbIcon.mimeType)
+          res.setHeader('Cache-Control', 'public, max-age=86400')
+          res.send(dbIcon.content)
+        } catch (error) {
+          console.error('Error fetching icon:', error)
+          res.status(404).send('Icon not found')
+        }
+      })
+    },
+  },
+]
+
+/**
+ * Registers all enabled features on the router.
+ */
+export function registerFeatures(
+  router: Router,
+  options: Required<Pick<EhMiddlewareOptions, 'basePath'>> &
+    EhMiddlewareOptions,
+  context: MiddlewareContext,
+): void {
+  const toggles = options.features || {}
+
+  for (const feature of FEATURES) {
+    const isEnabled = toggles[feature.name] ?? feature.defaultEnabled
+
+    // Special case: adminChat is only enabled if config is provided
+    if (feature.name === 'adminChat' && !options.adminChat) {
+      continue
+    }
+
+    if (isEnabled) {
+      feature.register(router, options, context)
+    }
+  }
+}

package/src/middleware/index.ts

@@ -0,0 +1,18 @@
+// Main middleware factory
+export { createEhMiddleware } from './createEhMiddleware'
+
+// Types
+export type {
+  EhDatabaseConfig,
+  EhAuthConfig,
+  EhAdminChatConfig,
+  EhFeatureToggles,
+  EhBackendProvider,
+  EhLifecycleHooks,
+  EhMiddlewareOptions,
+  EhMiddlewareResult,
+  MiddlewareContext,
+} from './types'
+
+// Database manager (for advanced use cases)
+export { EhDatabaseManager } from './database'