@igstack/app-catalog-backend-core 0.0.1

package/src/middleware/featureRegistry.ts

@@ -0,0 +1,173 @@
+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'
+import {
+  exportAsset,
+  exportCatalog,
+  importAsset,
+  importCatalog,
+  listAssets,
+} from '../modules/appCatalogAdmin/catalogBackupController'
+import multer from 'multer'
+import { createMockSessionResponse } from '../modules/auth/devMockUserUtils'
+
+interface FeatureRegistration {
+  name: keyof EhFeatureToggles
+  defaultEnabled: boolean
+  register: (
+    router: Router,
+    options: Required<Pick<EhMiddlewareOptions, 'basePath'>> &
+      EhMiddlewareOptions,
+    context: MiddlewareContext,
+  ) => void
+}
+
+// Optional features that can be toggled
+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): Promise<void> => {
+          try {
+            // Check if dev mock user is configured
+            if (ctx.authConfig.devMockUser) {
+              res.json(createMockSessionResponse(ctx.authConfig.devMockUser))
+              return
+            }
+
+            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: '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 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) {
+    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,43 @@
+/**
+ * Middleware module for app-catalog 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'
+
+// Types
+export type {
+  EhDatabaseConfig,
+  EhAuthConfig,
+  EhAdminChatConfig,
+  EhFeatureToggles,
+  EhBackendProvider,
+  EhLifecycleHooks,
+  EhMiddlewareOptions,
+  EhMiddlewareResult,
+  MiddlewareContext,
+} from './types'
+
+// Database manager (for advanced use cases)
+export { EhDatabaseManager } from './database'

package/src/middleware/types.ts

@@ -0,0 +1,202 @@
+import type { Router } from 'express'
+import type { LanguageModel, Tool } from 'ai'
+import type { BetterAuthOptions, BetterAuthPlugin } from 'better-auth'
+import type { AppCatalogCompanySpecificBackend } from '../types/backend/companySpecificBackend'
+import type { BetterAuth } from '../modules/auth/auth'
+import type { TRPCRouter } from '../server/controller'
+
+/**
+ * Database connection configuration.
+ * Supports both connection URL and structured config.
+ */
+export type EhDatabaseConfig =
+  | { url: string }
+  | {
+      host: string
+      port: number
+      database: string
+      username: string
+      password: string
+      schema?: string
+    }
+
+/**
+ * Mock user configuration for development/testing.
+ * When provided, bypasses authentication and injects this user into all requests.
+ */
+export interface EhDevMockUser {
+  /** User ID */
+  id: string
+  /** User email */
+  email: string
+  /** User display name */
+  name: string
+  /** User groups (for authorization) */
+  groups: Array<string>
+}
+
+/**
+ * Auth configuration for Better Auth integration.
+ */
+export interface EhAuthConfig {
+  /** Base URL for auth callbacks (e.g., 'http://localhost:4000') */
+  baseURL: string
+  /** Secret for signing sessions (min 32 chars in production) */
+  secret: string
+  /** OAuth providers configuration */
+  providers?: BetterAuthOptions['socialProviders']
+  /** Additional Better Auth plugins (e.g., Okta) */
+  plugins?: Array<BetterAuthPlugin>
+  /** Session expiration in seconds (default: 30 days) */
+  sessionExpiresIn?: number
+  /** Session refresh threshold in seconds (default: 1 day) */
+  sessionUpdateAge?: number
+  /** Application name shown in auth UI */
+  appName?: string
+  /** Development mock user - bypasses auth when provided */
+  devMockUser?: EhDevMockUser
+  /** Admin group names for authorization (default: ['env_hopper_ui_super_admins']) */
+  adminGroups?: Array<string>
+  /** Okta groups claim name (e.g., 'env_hopper_ui_groups') - used to extract groups from access token JWT */
+  oktaGroupsClaim?: string
+}
+
+/**
+ * Admin chat (AI) configuration.
+ * When provided, enables the admin/chat endpoint.
+ */
+export interface EhAdminChatConfig {
+  /** AI model instance from @ai-sdk/* packages */
+  model: LanguageModel
+  /** System prompt for the AI assistant */
+  systemPrompt?: string
+  /** Custom tools available to the AI */
+  tools?: Record<string, Tool>
+  /** Validation function called before each request */
+  validateConfig?: () => void
+}
+
+/**
+ * Feature toggles for enabling/disabling specific functionality.
+ *
+ * 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 admin chat endpoint (default: true if adminChat config provided) */
+  adminChat?: boolean
+  /** Enable legacy icon endpoint at /static/icon/:icon (default: false) */
+  legacyIconEndpoint?: boolean
+}
+
+/**
+ * Company-specific backend can be provided as:
+ * 1. Direct object implementing the interface
+ * 2. Factory function called per-request (for DI integration)
+ * 3. Async factory function
+ */
+export type EhBackendProvider =
+  | AppCatalogCompanySpecificBackend
+  | (() => AppCatalogCompanySpecificBackend)
+  | (() => Promise<AppCatalogCompanySpecificBackend>)
+
+/**
+ * Lifecycle hooks for database and middleware events.
+ */
+export interface EhLifecycleHooks {
+  /** Called after database connection is established */
+  onDatabaseConnected?: () => void | Promise<void>
+  /** Called before database disconnection (for cleanup) */
+  onDatabaseDisconnecting?: () => void | Promise<void>
+  /** Called after all routes are registered - use to add custom routes */
+  onRoutesRegistered?: (router: Router) => void | Promise<void>
+  /** Custom error handler for middleware errors */
+  onError?: (error: Error, context: { path: string }) => void
+}
+
+/**
+ * Main configuration options for the app-catalog middleware.
+ */
+export interface EhMiddlewareOptions {
+  /**
+   * Base path prefix for all routes (default: '/api')
+   * - tRPC: {basePath}/trpc
+   * - Auth: {basePath}/auth (note: auth basePath is hardcoded, this affects where router mounts)
+   * - Icons: {basePath}/icons
+   * - Assets: {basePath}/assets
+   * - Screenshots: {basePath}/screenshots
+   * - Admin Chat: {basePath}/admin/chat
+   */
+  basePath?: string
+
+  /**
+   * Database connection configuration (required).
+   * Backend-core manages the database for all features.
+   */
+  database: EhDatabaseConfig
+
+  /** Auth configuration (required) */
+  auth: EhAuthConfig
+
+  /** Company-specific backend implementation (required) */
+  backend: EhBackendProvider
+
+  /** AI admin chat configuration (optional) */
+  adminChat?: EhAdminChatConfig
+
+  /** Feature toggles (all enabled by default) */
+  features?: EhFeatureToggles
+
+  /** Lifecycle hooks */
+  hooks?: EhLifecycleHooks
+}
+
+/**
+ * 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 app-catalog routes */
+  router: Router
+  /** Better Auth instance (for extending auth functionality) */
+  auth: BetterAuth
+  /** tRPC router (for extending with custom procedures) */
+  trpcRouter: TRPCRouter
+  /** Connect to database (call during app startup) */
+  connect: () => Promise<void>
+  /** Disconnect from database (call during app shutdown) */
+  disconnect: () => Promise<void>
+  /** Add custom routes to the middleware router */
+  addRoutes: (callback: (router: Router) => void) => void
+}
+
+/**
+ * Internal context passed to feature registration functions.
+ */
+export interface MiddlewareContext {
+  auth: BetterAuth
+  trpcRouter: TRPCRouter
+  createContext: () => Promise<{
+    companySpecificBackend: AppCatalogCompanySpecificBackend
+  }>
+  authConfig: EhAuthConfig
+}

package/src/modules/admin/chat/createAdminChatHandler.ts

@@ -0,0 +1,152 @@
+import { stepCountIs, streamText, tool } from 'ai'
+import type { LanguageModel, Tool } from 'ai'
+
+import type { Request, Response } from 'express'
+
+export interface AdminChatHandlerOptions {
+  /** The AI model to use (from @ai-sdk/openai, @ai-sdk/anthropic, etc.) */
+  model: LanguageModel
+  /** System prompt for the AI assistant */
+  systemPrompt?: string
+  /** Tools available to the AI assistant */
+  tools?: Record<string, Tool>
+  /**
+   * Optional function to validate configuration before processing requests.
+   * Should throw an error if configuration is invalid (e.g., missing API key).
+   * @example
+   * validateConfig: () => {
+   *   if (!process.env.OPENAI_API_KEY) {
+   *     throw new Error('OPENAI_API_KEY is not configured')
+   *   }
+   * }
+   */
+  validateConfig?: () => void
+}
+
+interface TextPart {
+  type: 'text'
+  text: string
+}
+
+interface UIMessageInput {
+  role: 'user' | 'assistant' | 'system'
+  content?: string
+  parts?: Array<TextPart | { type: string }>
+}
+
+interface CoreMessage {
+  role: 'user' | 'assistant' | 'system'
+  content: string
+}
+
+function convertToCoreMessages(
+  messages: Array<UIMessageInput>,
+): Array<CoreMessage> {
+  return messages.map((msg) => {
+    if (msg.content) {
+      return { role: msg.role, content: msg.content }
+    }
+    // Extract text from parts array (AI SDK v3 format)
+    const textContent =
+      msg.parts
+        ?.filter((part): part is TextPart => part.type === 'text')
+        .map((part) => part.text)
+        .join('') ?? ''
+    return { role: msg.role, content: textContent }
+  })
+}
+
+/**
+ * Creates an Express handler for the admin chat endpoint.
+ *
+ * Usage in thin wrappers:
+ *
+ * ```typescript
+ * // With OpenAI
+ * import { openai } from '@ai-sdk/openai'
+ * app.post('/api/admin/chat', createAdminChatHandler({
+ *   model: openai('gpt-4o-mini'),
+ * }))
+ *
+ * // With Claude
+ * import { anthropic } from '@ai-sdk/anthropic'
+ * app.post('/api/admin/chat', createAdminChatHandler({
+ *   model: anthropic('claude-sonnet-4-20250514'),
+ * }))
+ * ```
+ */
+export function createAdminChatHandler(options: AdminChatHandlerOptions) {
+  const {
+    model,
+    systemPrompt = 'You are a helpful admin assistant for the App Catalog application. Help users manage apps, data sources, and MCP server configurations.',
+    tools = {},
+    validateConfig,
+  } = options
+
+  return async (req: Request, res: Response) => {
+    try {
+      // Validate configuration if validator provided
+      if (validateConfig) {
+        validateConfig()
+      }
+
+      const { messages } = req.body as { messages: Array<UIMessageInput> }
+      const coreMessages = convertToCoreMessages(messages)
+
+      console.log(
+        '[Admin Chat] Received messages:',
+        JSON.stringify(coreMessages, null, 2),
+      )
+      console.log('[Admin Chat] Available tools:', Object.keys(tools))
+
+      const result = streamText({
+        model,
+        system: systemPrompt,
+        messages: coreMessages,
+        tools,
+        // Allow up to 5 steps so the model can call tools and then generate a response
+        stopWhen: stepCountIs(5),
+        onFinish: (event) => {
+          console.log('[Admin Chat] Finished:', {
+            finishReason: event.finishReason,
+            usage: event.usage,
+            hasText: !!event.text,
+            textLength: event.text.length,
+          })
+        },
+      })
+
+      // Use UI message stream response which is compatible with AI SDK React hooks
+      const response = result.toUIMessageStreamResponse()
+
+      // Copy headers from the response
+      response.headers.forEach((value, key) => {
+        res.setHeader(key, value)
+      })
+
+      // Pipe the stream to the response
+      if (response.body) {
+        const reader = response.body.getReader()
+        const pump = async (): Promise<void> => {
+          const { done, value } = await reader.read()
+          if (done) {
+            res.end()
+            return
+          }
+          res.write(value)
+          return pump()
+        }
+        await pump()
+      } else {
+        console.error('[Admin Chat] No response body')
+        res.status(500).json({ error: 'No response from AI model' })
+      }
+    } catch (error) {
+      console.error('[Admin Chat] Error:', error)
+      res.status(500).json({ error: 'Failed to process chat request' })
+    }
+  }
+}
+
+// Re-export tool helper for convenience
+export { tool }