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

package/package.json

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

package/src/middleware/createEhMiddleware.ts

@@ -1,6 +1,10 @@
 import express, { Router } from 'express'
 import * as trpcExpress from '@trpc/server/adapters/express'
-import type { EhMiddlewareOptions, EhMiddlewareResult, MiddlewareContext } from './types'
+import type {
+  EhMiddlewareOptions,
+  EhMiddlewareResult,
+  MiddlewareContext,
+} from './types'
 import { EhDatabaseManager } from './database'
 import { createBackendResolver } from './backendResolver'
 import { registerFeatures } from './featureRegistry'
@@ -8,61 +12,6 @@ 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> {
@@ -70,29 +19,10 @@ export async function createEhMiddleware(
   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()
-  }
+  // Initialize database manager
+  const dbManager = new EhDatabaseManager(options.database)
+  // Initialize the client (which also sets the global singleton)
+  dbManager.getClient()
 
   // Create auth instance
   const auth = createAuth({
@@ -153,9 +83,7 @@ export async function createEhMiddleware(
     trpcRouter,
 
     async connect(): Promise<void> {
-      if (dbManager) {
-        await dbManager.connect()
-      }
+      await dbManager.connect()
       if (options.hooks?.onDatabaseConnected) {
         await options.hooks.onDatabaseConnected()
       }
@@ -165,9 +93,7 @@ export async function createEhMiddleware(
       if (options.hooks?.onDatabaseDisconnecting) {
         await options.hooks.onDatabaseDisconnecting()
       }
-      if (dbManager) {
-        await dbManager.disconnect()
-      }
+      await dbManager.disconnect()
     },
 
     addRoutes(callback: (router: Router) => void): void {

package/src/middleware/featureRegistry.ts

@@ -10,6 +10,14 @@ import { registerAssetRestController } from '../modules/assets/assetRestControll
 import { registerScreenshotRestController } from '../modules/assets/screenshotRestController'
 import { createAdminChatHandler } from '../modules/admin/chat/createAdminChatHandler'
 import { getAssetByName } from '../modules/icons/iconService'
+import {
+  exportAsset,
+  exportCatalog,
+  importAsset,
+  importCatalog,
+  listAssets,
+} from '../modules/appCatalogAdmin/catalogBackupController'
+import multer from 'multer'
 
 interface FeatureRegistration {
   name: keyof EhFeatureToggles
@@ -22,6 +30,7 @@ interface FeatureRegistration {
   ) => void
 }
 
+// Optional features that can be toggled
 const FEATURES: Array<FeatureRegistration> = [
   {
     name: 'auth',
@@ -51,33 +60,6 @@ const FEATURES: Array<FeatureRegistration> = [
       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
@@ -132,6 +114,38 @@ export function registerFeatures(
     EhMiddlewareOptions,
   context: MiddlewareContext,
 ): void {
+  const basePath = options.basePath
+
+  // Always-on features (required for core functionality)
+
+  // Icons
+  registerIconRestController(router, {
+    basePath: `${basePath}/icons`,
+  })
+
+  // Assets
+  registerAssetRestController(router, {
+    basePath: `${basePath}/assets`,
+  })
+
+  // Screenshots
+  registerScreenshotRestController(router, {
+    basePath: `${basePath}/screenshots`,
+  })
+
+  // Catalog backup/restore
+  const upload = multer({ storage: multer.memoryStorage() })
+  router.get(`${basePath}/catalog/backup/export`, exportCatalog)
+  router.post(`${basePath}/catalog/backup/import`, importCatalog)
+  router.get(`${basePath}/catalog/backup/assets`, listAssets)
+  router.get(`${basePath}/catalog/backup/assets/:name`, exportAsset)
+  router.post(
+    `${basePath}/catalog/backup/assets`,
+    upload.single('file'),
+    importAsset,
+  )
+
+  // Optional toggleable features
   const toggles = options.features || {}
 
   for (const feature of FEATURES) {

package/src/middleware/index.ts

@@ -1,3 +1,28 @@
+/**
+ * Middleware module for env-hopper backend integration.
+ *
+ * Provides a batteries-included middleware factory that handles all backend wiring:
+ * - Database connection management
+ * - Authentication setup
+ * - tRPC router configuration
+ * - Feature registration (icons, assets, screenshots, admin chat)
+ *
+ * @example
+ * ```typescript
+ * const eh = await createEhMiddleware({
+ *   basePath: '/api',
+ *   database: { host, port, database, username, password, schema },
+ *   auth: { baseURL, secret, providers },
+ *   backend: myBackendImplementation,
+ * })
+ *
+ * app.use(eh.router)
+ * await eh.connect()
+ * ```
+ *
+ * @module middleware
+ */
+
 // Main middleware factory
 export { createEhMiddleware } from './createEhMiddleware'
 

package/src/middleware/types.ts

@@ -57,19 +57,15 @@ export interface EhAdminChatConfig {
 
 /**
  * Feature toggles for enabling/disabling specific functionality.
- * All features are enabled by default.
+ *
+ * Note: Icons, assets, screenshots, and catalog backup are always enabled.
+ * Only these optional features can be toggled:
  */
 export interface EhFeatureToggles {
   /** Enable tRPC endpoints (default: true) */
   trpc?: boolean
   /** Enable auth endpoints (default: true) */
   auth?: boolean
-  /** Enable icon REST endpoints (default: true) */
-  icons?: boolean
-  /** Enable asset REST endpoints (default: true) */
-  assets?: boolean
-  /** Enable screenshot REST endpoints (default: true) */
-  screenshots?: boolean
   /** Enable admin chat endpoint (default: true if adminChat config provided) */
   adminChat?: boolean
   /** Enable legacy icon endpoint at /static/icon/:icon (default: false) */
@@ -117,11 +113,10 @@ export interface EhMiddlewareOptions {
   basePath?: string
 
   /**
-   * Database connection configuration.
-   * Required when icons, assets, or screenshots features are enabled.
-   * Can be omitted when these features are disabled and you manage your own database.
+   * Database connection configuration (required).
+   * Backend-core manages the database for all features.
    */
-  database?: EhDatabaseConfig
+  database: EhDatabaseConfig
 
   /** Auth configuration (required) */
   auth: EhAuthConfig
@@ -141,6 +136,22 @@ export interface EhMiddlewareOptions {
 
 /**
  * Result of middleware initialization.
+ *
+ * @example
+ * ```typescript
+ * const eh = await createEhMiddleware({ ... })
+ *
+ * // Mount routes
+ * app.use(eh.router)
+ *
+ * // Connect to database
+ * await eh.connect()
+ *
+ * // Cleanup on shutdown
+ * process.on('SIGTERM', async () => {
+ *   await eh.disconnect()
+ * })
+ * ```
  */
 export interface EhMiddlewareResult {
   /** Express router with all env-hopper routes */
@@ -163,5 +174,7 @@ export interface EhMiddlewareResult {
 export interface MiddlewareContext {
   auth: BetterAuth
   trpcRouter: TRPCRouter
-  createContext: () => Promise<{ companySpecificBackend: EhBackendCompanySpecificBackend }>
+  createContext: () => Promise<{
+    companySpecificBackend: EhBackendCompanySpecificBackend
+  }>
 }

package/src/modules/appCatalogAdmin/catalogBackupController.ts

@@ -0,0 +1,182 @@
+import type { Request, Response } from 'express'
+import { getDbClient } from '../../db'
+
+/**
+ * Export the complete app catalog as JSON
+ * Includes all fields from DbAppForCatalog
+ */
+export async function exportCatalog(
+  _req: Request,
+  res: Response,
+): Promise<void> {
+  try {
+    const prisma = getDbClient()
+
+    // Fetch all catalog entries
+    const apps = await prisma.dbAppForCatalog.findMany({
+      orderBy: { slug: 'asc' },
+    })
+
+    res.json({
+      version: '1.0',
+      exportDate: new Date().toISOString(),
+      apps,
+    })
+  } catch (error) {
+    console.error('Error exporting catalog:', error)
+    res.status(500).json({ error: 'Failed to export catalog' })
+  }
+}
+
+/**
+ * Import/restore the complete app catalog from JSON
+ * Overwrites existing data
+ */
+export async function importCatalog(
+  req: Request,
+  res: Response,
+): Promise<void> {
+  try {
+    const prisma = getDbClient()
+    const { apps } = req.body
+
+    if (!Array.isArray(apps)) {
+      res
+        .status(400)
+        .json({ error: 'Invalid data format: apps must be an array' })
+      return
+    }
+
+    // Use transaction to ensure atomicity
+    await prisma.$transaction(async (tx) => {
+      // Delete all existing catalog entries
+      await tx.dbAppForCatalog.deleteMany({})
+
+      // Insert new entries
+      for (const app of apps) {
+        // Remove id, createdAt, updatedAt to let Prisma generate new ones
+        const { id, createdAt, updatedAt, ...appData } = app
+
+        await tx.dbAppForCatalog.create({
+          data: appData,
+        })
+      }
+    })
+
+    res.json({ success: true, imported: apps.length })
+  } catch (error) {
+    console.error('Error importing catalog:', error)
+    res.status(500).json({ error: 'Failed to import catalog' })
+  }
+}
+
+/**
+ * Export an asset (icon or screenshot) by name
+ */
+export async function exportAsset(req: Request, res: Response): Promise<void> {
+  try {
+    const { name } = req.params
+    const prisma = getDbClient()
+
+    const asset = await prisma.dbAsset.findUnique({
+      where: { name },
+    })
+
+    if (!asset) {
+      res.status(404).json({ error: 'Asset not found' })
+      return
+    }
+
+    // Set appropriate content type and send binary data
+    res.set('Content-Type', asset.mimeType)
+    res.set('Content-Disposition', `attachment; filename="${name}"`)
+    res.send(Buffer.from(asset.content))
+  } catch (error) {
+    console.error('Error exporting asset:', error)
+    res.status(500).json({ error: 'Failed to export asset' })
+  }
+}
+
+/**
+ * List all assets with metadata
+ */
+export async function listAssets(_req: Request, res: Response): Promise<void> {
+  try {
+    const prisma = getDbClient()
+
+    const assets = await prisma.dbAsset.findMany({
+      select: {
+        id: true,
+        name: true,
+        assetType: true,
+        mimeType: true,
+        fileSize: true,
+        width: true,
+        height: true,
+        checksum: true,
+      },
+      orderBy: { name: 'asc' },
+    })
+
+    res.json({ assets })
+  } catch (error) {
+    console.error('Error listing assets:', error)
+    res.status(500).json({ error: 'Failed to list assets' })
+  }
+}
+
+/**
+ * Import an asset (icon or screenshot)
+ */
+export async function importAsset(req: Request, res: Response): Promise<void> {
+  try {
+    const file = req.file
+    const { name, assetType, mimeType, width, height } = req.body
+
+    if (!file) {
+      res.status(400).json({ error: 'No file uploaded' })
+      return
+    }
+
+    const prisma = getDbClient()
+    const crypto = await import('node:crypto')
+
+    // Calculate checksum
+    const checksum = crypto
+      .createHash('sha256')
+      .update(file.buffer)
+      .digest('hex')
+
+    // Convert Buffer to Uint8Array for Prisma Bytes type
+    const content = new Uint8Array(file.buffer)
+
+    // Upsert asset (update if exists, create if not)
+    await prisma.dbAsset.upsert({
+      where: { name },
+      update: {
+        content,
+        checksum,
+        mimeType: mimeType || file.mimetype,
+        fileSize: file.size,
+        width: width ? parseInt(width) : null,
+        height: height ? parseInt(height) : null,
+        assetType: assetType || 'icon',
+      },
+      create: {
+        name,
+        content,
+        checksum,
+        mimeType: mimeType || file.mimetype,
+        fileSize: file.size,
+        width: width ? parseInt(width) : null,
+        height: height ? parseInt(height) : null,
+        assetType: assetType || 'icon',
+      },
+    })
+
+    res.json({ success: true, name, size: file.size })
+  } catch (error) {
+    console.error('Error importing asset:', error)
+    res.status(500).json({ error: 'Failed to import asset' })
+  }
+}

package/src/modules/icons/iconService.ts

@@ -47,7 +47,7 @@ export async function upsertIcon(input: UpsertIconInput) {
  * This is more efficient than calling upsertIcon multiple times.
  */
 export async function upsertIcons(icons: Array<UpsertIconInput>) {
-  const results = []
+  const results: Array<Awaited<ReturnType<typeof upsertIcon>>> = []
   for (const icon of icons) {
     const result = await upsertIcon(icon)
     results.push(result)