@igstack/app-catalog-backend-core 0.0.1

package/src/db/tableSyncPrismaAdapter.ts

@@ -0,0 +1,203 @@
+import { tableSync } from '@igstack/app-catalog-table-sync'
+import type { Prisma, PrismaClient } from '@prisma/client'
+import type * as runtime from '@prisma/client/runtime/library'
+import { mapValues, omit, pick } from 'radashi'
+
+export type ScalarKeys<TPrismaModelName extends Prisma.ModelName> =
+  keyof Prisma.TypeMap['model'][TPrismaModelName]['payload']['scalars']
+export type ObjectKeys<TPrismaModelName extends Prisma.ModelName> =
+  keyof Prisma.TypeMap['model'][TPrismaModelName]['payload']['objects']
+
+export type ScalarFilter<TPrismaModelName extends Prisma.ModelName> = Partial<
+  Prisma.TypeMap['model'][TPrismaModelName]['payload']['scalars']
+>
+
+export type GetOperationFns<TModel extends Prisma.ModelName> = {
+  [TOperation in keyof Prisma.TypeMap['model']['DbAppForCatalog']['operations']]: (
+    args: Prisma.TypeMap['model'][TModel]['operations'][TOperation]['args'],
+  ) => Promise<
+    Prisma.TypeMap['model'][TModel]['operations'][TOperation]['result']
+  >
+}
+
+export interface TableSyncParamsPrisma<
+  TPrismaClient extends PrismaClient,
+  TPrismaModelName extends Prisma.ModelName,
+  TUniqColumns extends ReadonlyArray<ScalarKeys<TPrismaModelName>>,
+  TRelationColumns extends ReadonlyArray<ObjectKeys<TPrismaModelName>>,
+> {
+  id?: ScalarKeys<TPrismaModelName>
+  prisma: TPrismaClient
+  prismaModelName: TPrismaModelName
+  uniqColumns: TUniqColumns
+  relationColumns?: TRelationColumns
+  where?: ScalarFilter<TPrismaModelName>
+  upsertOnly?: boolean
+}
+
+function getPrismaModelOperations<
+  TPrismaClient extends Omit<PrismaClient, runtime.ITXClientDenyList>,
+  TPrismaModelName extends Prisma.ModelName,
+>(prisma: TPrismaClient, prismaModelName: TPrismaModelName) {
+  const key = (prismaModelName.slice(0, 1).toLowerCase() +
+    prismaModelName.slice(1)) as keyof TPrismaClient
+  return prisma[key] as GetOperationFns<TPrismaModelName>
+}
+
+export type MakeTFromPrismaModel<TPrismaModelName extends Prisma.ModelName> =
+  NonNullable<
+    Prisma.TypeMap['model'][TPrismaModelName]['operations']['findUnique']['result']
+  >
+
+export function tableSyncPrisma<
+  TPrismaClient extends PrismaClient,
+  TPrismaModelName extends Prisma.ModelName,
+  TUniqColumns extends ReadonlyArray<ScalarKeys<TPrismaModelName>>,
+  TRelationColumns extends ReadonlyArray<ObjectKeys<TPrismaModelName>>,
+  TId extends ScalarKeys<TPrismaModelName> = ScalarKeys<TPrismaModelName>,
+>(
+  params: TableSyncParamsPrisma<
+    TPrismaClient,
+    TPrismaModelName,
+    TUniqColumns,
+    TRelationColumns
+  >,
+) {
+  const {
+    prisma,
+    prismaModelName,
+    uniqColumns,
+    where: whereGlobal,
+    upsertOnly,
+  } = params
+  const prismOperations = getPrismaModelOperations(prisma, prismaModelName)
+
+  const idColumn = (params.id ?? 'id') as TId
+  // @ts-ignore maybe someday later (never)
+  return tableSync<MakeTFromPrismaModel<TPrismaModelName>, TUniqColumns, TId>({
+    id: idColumn,
+    uniqColumns,
+    readAll: async () => {
+      const findManyArgs = whereGlobal
+        ? {
+            where: whereGlobal,
+          }
+        : {}
+      return (await prismOperations.findMany(findManyArgs)) as Array<
+        MakeTFromPrismaModel<TPrismaModelName>
+      >
+    },
+    writeAll: async (createData, update, deleteIds) => {
+      const prismaUniqKey = params.uniqColumns.join('_')
+      const relationColumnList =
+        params.relationColumns ?? ([] as Array<ObjectKeys<TPrismaModelName>>)
+
+      return prisma.$transaction(async (tx) => {
+        const txOps = getPrismaModelOperations(tx, prismaModelName)
+        for (const { data, where } of update) {
+          const uniqKeyWhere =
+            Object.keys(where).length > 1
+              ? {
+                  [prismaUniqKey]: where,
+                }
+              : where
+
+          const dataScalar = omit(data, relationColumnList)
+          const dataRelations = mapValues(
+            pick(data, relationColumnList),
+            (value) => {
+              return {
+                set: value,
+              }
+            },
+          )
+
+          // @ts-expect-error This is too difficult for me to come up with right types
+          await txOps.update({
+            data: { ...dataScalar, ...dataRelations },
+            where: { ...uniqKeyWhere },
+          })
+        }
+
+        if (upsertOnly !== true) {
+          await txOps.deleteMany({
+            where: {
+              [idColumn]: {
+                in: deleteIds,
+              },
+            },
+          })
+        }
+
+        // Validate uniqueness of uniqColumns before creating records
+        const createDataMapped = createData.map((data) => {
+          // @ts-expect-error This is too difficult for me to come up with right types
+          const dataScalar = omit(data, relationColumnList)
+
+          // @ts-expect-error This is too difficult for me to come up with right types
+          const onlyRelationColumns = pick(data, relationColumnList)
+          const dataRelations = mapValues(onlyRelationColumns, (value) => {
+            return {
+              connect: value,
+            }
+          })
+
+          return { ...dataScalar, ...dataRelations }
+        })
+
+        // Check for duplicates in the data to be created
+        if (createDataMapped.length > 0) {
+          const uniqKeysInCreate = new Set<string>()
+          const duplicateKeys: Array<string> = []
+
+          for (const data of createDataMapped) {
+            const keyParts = params.uniqColumns.map((col) => {
+              const value = data[col as keyof typeof data]
+              // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- defensive: unique columns may be nullable in schemas
+              return value === null || value === undefined
+                ? 'null'
+                : String(value)
+            })
+            const key = keyParts.join(':')
+
+            if (uniqKeysInCreate.has(key)) {
+              duplicateKeys.push(key)
+            } else {
+              uniqKeysInCreate.add(key)
+            }
+          }
+
+          if (duplicateKeys.length > 0) {
+            const uniqColumnsStr = params.uniqColumns.join(', ')
+            throw new Error(
+              `Duplicate unique key values found in data to be created. ` +
+                `Model: ${prismaModelName}, Unique columns: [${uniqColumnsStr}], ` +
+                `Duplicate keys: [${duplicateKeys.join(', ')}]`,
+            )
+          }
+        }
+
+        const results: Array<MakeTFromPrismaModel<TPrismaModelName>> = []
+
+        if (relationColumnList.length === 0) {
+          // @ts-expect-error This is too difficult for me to come up with right types
+          const batchResult = await txOps.createManyAndReturn({
+            data: createDataMapped,
+          })
+
+          results.push(...batchResult)
+        } else {
+          for (const dataMappedElement of createDataMapped) {
+            // @ts-expect-error too difficult for me
+            const newVar = await txOps.create({
+              data: dataMappedElement,
+            })
+            results.push(newVar as MakeTFromPrismaModel<TPrismaModelName>)
+          }
+        }
+
+        return results
+      })
+    },
+  })
+}

package/src/index.ts

@@ -0,0 +1,126 @@
+// common
+
+export { createTrpcRouter } from './server/controller'
+export type { TRPCRouter } from './server/controller'
+export { createEhTrpcContext } from './server/ehTrpcContext'
+export type {
+  EhTrpcContext,
+  EhTrpcContextOptions,
+} from './server/ehTrpcContext'
+
+export { staticControllerContract } from './server/ehStaticControllerContract'
+export type { EhStaticControllerContract } from './server/ehStaticControllerContract'
+
+// ui-only
+
+// backend-only
+
+export type { AppForCatalog } from './types/common/appCatalogTypes'
+export * from './types/index'
+
+// Auth
+export {
+  createAuth,
+  type AuthConfig,
+  type BetterAuth,
+} from './modules/auth/auth'
+
+export { registerAuthRoutes } from './modules/auth/registerAuthRoutes'
+
+export { createAuthRouter, type AuthRouter } from './modules/auth/authRouter'
+
+export {
+  getUserGroups,
+  isMemberOfAnyGroup,
+  isMemberOfAllGroups,
+  isAdmin,
+  requireAdmin,
+  requireGroups,
+  type UserWithGroups,
+} from './modules/auth/authorizationUtils'
+
+// Admin
+export {
+  createAdminChatHandler,
+  tool,
+  type AdminChatHandlerOptions,
+} from './modules/admin/chat/createAdminChatHandler'
+
+export {
+  createDatabaseTools,
+  createPrismaDatabaseClient,
+  DEFAULT_ADMIN_SYSTEM_PROMPT,
+  type DatabaseClient,
+} from './modules/admin/chat/createDatabaseTools'
+
+// Icon management
+export {
+  registerIconRestController,
+  type IconRestControllerConfig,
+} from './modules/icons/iconRestController'
+
+export {
+  getAssetByName,
+  upsertIcon,
+  upsertIcons,
+  type UpsertIconInput,
+} from './modules/icons/iconService'
+
+// Asset management (universal for icons, screenshots, etc.)
+export {
+  registerAssetRestController,
+  type AssetRestControllerConfig,
+} from './modules/assets/assetRestController'
+
+export {
+  registerScreenshotRestController,
+  type ScreenshotRestControllerConfig,
+} from './modules/assets/screenshotRestController'
+
+export { createScreenshotRouter } from './modules/assets/screenshotRouter'
+
+export { syncAssets, type SyncAssetsConfig } from './modules/assets/syncAssets'
+
+// App Catalog Admin
+export { createAppCatalogAdminRouter } from './modules/appCatalogAdmin/appCatalogAdminRouter'
+
+// Approval Methods
+export { createApprovalMethodRouter } from './modules/approvalMethod/approvalMethodRouter'
+export {
+  syncApprovalMethods,
+  type ApprovalMethodSyncInput,
+} from './modules/approvalMethod/syncApprovalMethods'
+
+// Database utilities
+export {
+  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,42 @@
+import type { AppCatalogCompanySpecificBackend } from '../types/backend/companySpecificBackend'
+import type { EhBackendProvider } from './types'
+
+/**
+ * Type guard to check if an object implements AppCatalogCompanySpecificBackend.
+ */
+function isBackendInstance(obj: unknown): obj is AppCatalogCompanySpecificBackend {
+  return (
+    typeof obj === 'object' &&
+    obj !== null &&
+    (typeof (obj as AppCatalogCompanySpecificBackend).getApps === 'function' ||
+      typeof (obj as AppCatalogCompanySpecificBackend).getApps === 'undefined')
+  )
+}
+
+/**
+ * Normalizes different backend provider types into a consistent async factory function.
+ * Supports:
+ * - Direct object implementing AppCatalogCompanySpecificBackend
+ * - Sync factory function that returns the backend
+ * - Async factory function that returns the backend
+ */
+export function createBackendResolver(
+  provider: EhBackendProvider,
+): () => Promise<AppCatalogCompanySpecificBackend> {
+  // 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 AppCatalogCompanySpecificBackend or a factory function',
+  )
+}

package/src/middleware/createEhMiddleware.ts

@@ -0,0 +1,171 @@
+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'
+import { createMockUserFromDevConfig } from '../modules/auth/devMockUserUtils'
+
+export async function createEhMiddleware(
+  options: EhMiddlewareOptions,
+): Promise<EhMiddlewareResult> {
+  // Normalize options with defaults
+  const basePath = options.basePath ?? '/api'
+  const normalizedOptions = { ...options, basePath }
+
+  // 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({
+    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)
+
+  // Get admin groups from config with default
+  const adminGroups = options.auth.adminGroups ?? ['env_hopper_ui_super_admins']
+
+  // Create tRPC context factory
+  const createContext = async ({
+    req,
+  }: trpcExpress.CreateExpressContextOptions) => {
+    const companySpecificBackend = await resolveBackend()
+
+    let user = null
+    let userGroups: Array<string> = []
+
+    // Check if dev mock user is configured
+    if (options.auth.devMockUser) {
+      user = createMockUserFromDevConfig(options.auth.devMockUser)
+      userGroups = options.auth.devMockUser.groups
+    } else {
+      // Extract user from session
+      try {
+        const session = await auth.api.getSession({
+          headers: req.headers as HeadersInit,
+        })
+        user = session?.user ?? null
+
+        // If user is authenticated and Okta is configured, decode groups from access token
+        if (user && options.auth.oktaGroupsClaim) {
+          try {
+            // Get the current access token (auto-refreshes if expired)
+            // Note: better-auth requires providerId, but we use 'okta' as default
+            const tokenResult = await auth.api.getAccessToken({
+              body: {
+                providerId: 'okta',
+              },
+              headers: req.headers as HeadersInit,
+            })
+
+            if (tokenResult.accessToken) {
+              // Decode JWT to extract groups claim
+              const parts = tokenResult.accessToken.split('.')
+              if (parts.length === 3 && parts[1]) {
+                const payload = JSON.parse(
+                  Buffer.from(parts[1], 'base64').toString(),
+                )
+                const groups = payload[options.auth.oktaGroupsClaim]
+                userGroups = Array.isArray(groups) ? groups : []
+              }
+            }
+          } catch (error) {
+            console.error('[tRPC Context] Failed to get access token:', error)
+          }
+        }
+      } catch (error) {
+        console.error('[tRPC Context] Failed to get session:', error)
+      }
+    }
+
+    // Attach groups to user object for authorization checks
+    const userWithGroups = user ? { ...user, groups: userGroups } : null
+
+    return createEhTrpcContext({
+      companySpecificBackend,
+      user: userWithGroups,
+      adminGroups,
+    })
+  }
+
+  // Create Express router
+  const router = Router()
+  router.use(express.json())
+
+  // Build middleware context for feature registration
+  const middlewareContext: MiddlewareContext = {
+    auth,
+    trpcRouter,
+    createContext: async () => {
+      const companySpecificBackend = await resolveBackend()
+      return createEhTrpcContext({
+        companySpecificBackend,
+        adminGroups,
+      })
+    },
+    authConfig: options.auth,
+  }
+
+  // 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> {
+      await dbManager.connect()
+      if (options.hooks?.onDatabaseConnected) {
+        await options.hooks.onDatabaseConnected()
+      }
+    },
+
+    async disconnect(): Promise<void> {
+      if (options.hooks?.onDatabaseDisconnecting) {
+        await options.hooks.onDatabaseDisconnecting()
+      }
+      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
+    }
+  }
+}