@open-mercato/shared 0.4.5-develop-03023b2707 → 0.4.5-develop-0c30cb4b11

package/src/lib/crud/enricher-runner.ts

@@ -0,0 +1,329 @@
+/**
+ * Response Enricher Runner
+ *
+ * Executes response enrichers against API response payloads.
+ * Handles timeout, fallback, ACL feature gating, and error isolation.
+ */
+
+import type {
+  EnricherContext,
+  EnricherRegistryEntry,
+  EnrichmentResult,
+  ResponseEnricher,
+  SingleEnrichmentResult,
+} from './response-enricher'
+import { getEnrichersForEntity } from './enricher-registry'
+
+const DEFAULT_TIMEOUT = 2000
+const SLOW_WARN_MS = 100
+const SLOW_ERROR_MS = 500
+const DEFAULT_CACHE_TTL_MS = 60_000
+
+function timeoutPromise(ms: number): Promise<never> {
+  return new Promise((_, reject) =>
+    setTimeout(() => reject(new Error(`Enricher timed out after ${ms}ms`)), ms),
+  )
+}
+
+function hasRequiredFeatures(
+  enricher: ResponseEnricher,
+  userFeatures: string[] | undefined,
+): boolean {
+  if (!enricher.features || enricher.features.length === 0) return true
+  if (!userFeatures) return false
+  const hasFeature = (required: string): boolean => {
+    for (const granted of userFeatures) {
+      if (granted === '*' || granted === required) return true
+      if (granted.endsWith('.*')) {
+        const prefix = granted.slice(0, -1)
+        if (required.startsWith(prefix)) return true
+      }
+    }
+    return false
+  }
+  return enricher.features.every((feature) => hasFeature(feature))
+}
+
+function getActiveEnrichers(
+  targetEntity: string,
+  context: EnricherContext,
+): EnricherRegistryEntry[] {
+  const entries = getEnrichersForEntity(targetEntity)
+  return entries.filter((entry) => {
+    const enricher = entry.enricher
+    if (!hasRequiredFeatures(enricher, context.userFeatures)) return false
+    if (enricher.disabledTenantIds?.includes(context.tenantId)) return false
+    return true
+  })
+}
+
+type CacheLike = {
+  get: (key: string) => Promise<unknown>
+  set: (key: string, value: unknown, options?: { ttl?: number; tags?: string[] }) => Promise<unknown>
+}
+
+function resolveCache(context: EnricherContext): CacheLike | null {
+  const container = context.container as { resolve?: (name: string) => unknown } | undefined
+  if (!container?.resolve) return null
+  try {
+    const cache = container.resolve('cache') as CacheLike
+    if (cache && typeof cache.get === 'function' && typeof cache.set === 'function') {
+      return cache
+    }
+  } catch {
+    // ignore cache resolution failures
+  }
+  try {
+    const cacheService = container.resolve('cacheService') as CacheLike
+    if (cacheService && typeof cacheService.get === 'function' && typeof cacheService.set === 'function') {
+      return cacheService
+    }
+  } catch {
+    // ignore cache service resolution failures
+  }
+  return null
+}
+
+function buildCacheKey(
+  enricher: ResponseEnricher,
+  context: EnricherContext,
+  mode: 'one' | 'many',
+  recordIds: string[],
+): string {
+  const sortedIds = [...recordIds].sort()
+  return `umes:enricher:${enricher.id}:tenant:${context.tenantId}:org:${context.organizationId}:mode:${mode}:ids:${JSON.stringify(sortedIds)}`
+}
+
+function extractRecordId(record: Record<string, unknown>): string {
+  const idValue = record.id
+  if (typeof idValue === 'string' && idValue.trim().length > 0) return idValue.trim()
+  if (typeof idValue === 'number') return String(idValue)
+  return 'unknown'
+}
+
+function getEnricherCacheTtl(enricher: ResponseEnricher): number {
+  const ttl = enricher.cache?.ttl
+  if (typeof ttl === 'number' && Number.isFinite(ttl) && ttl > 0) {
+    return ttl
+  }
+  return DEFAULT_CACHE_TTL_MS
+}
+
+function getEnricherCacheTags(enricher: ResponseEnricher, context: EnricherContext): string[] {
+  const tags = new Set<string>([
+    `tenant:${context.tenantId}`,
+    `organization:${context.organizationId}`,
+    `enricher:${enricher.id}`,
+  ])
+  for (const tag of enricher.cache?.tags ?? []) {
+    if (!tag || tag.trim().length === 0) continue
+    tags.add(tag)
+  }
+  return Array.from(tags)
+}
+
+async function readEnricherCache<T>(
+  cache: CacheLike | null,
+  key: string,
+): Promise<T | null> {
+  if (!cache) return null
+  try {
+    const value = await cache.get(key)
+    return value == null ? null : (value as T)
+  } catch {
+    return null
+  }
+}
+
+async function writeEnricherCache(
+  cache: CacheLike | null,
+  key: string,
+  value: unknown,
+  ttl: number,
+  tags: string[],
+): Promise<void> {
+  if (!cache) return
+  try {
+    await cache.set(key, value, { ttl, tags })
+  } catch {
+    // ignore cache write failures
+  }
+}
+
+/**
+ * Apply response enrichers to a list of records.
+ *
+ * Runs AFTER CrudHooks.afterList, BEFORE HTTP response serialization.
+ * Each enricher runs independently — a failed non-critical enricher is skipped.
+ */
+export async function applyResponseEnrichers<T extends Record<string, unknown>>(
+  items: T[],
+  targetEntity: string,
+  context: EnricherContext,
+): Promise<EnrichmentResult<T>> {
+  const activeEntries = getActiveEnrichers(targetEntity, context)
+
+  if (activeEntries.length === 0) {
+    return { items, _meta: { enrichedBy: [] } }
+  }
+
+  const enrichedBy: string[] = []
+  const enricherErrors: string[] = []
+  let currentItems = items
+  const cache = resolveCache(context)
+
+  for (const entry of activeEntries) {
+    const enricher = entry.enricher
+    const timeout = enricher.timeout ?? DEFAULT_TIMEOUT
+    const startTime = Date.now()
+
+    try {
+      let result: T[]
+      const recordIds = currentItems.map((item) => extractRecordId(item))
+      const shouldUseCache = enricher.cache?.strategy === 'read-through'
+      const cacheKey = shouldUseCache ? buildCacheKey(enricher, context, 'many', recordIds) : null
+      if (shouldUseCache && cacheKey) {
+        const cached = await readEnricherCache<T[]>(cache, cacheKey)
+        if (cached) {
+          currentItems = cached
+          enrichedBy.push(enricher.id)
+          continue
+        }
+      }
+
+      if (enricher.enrichMany) {
+        result = await Promise.race([
+          enricher.enrichMany(currentItems, context) as Promise<T[]>,
+          timeoutPromise(timeout),
+        ])
+      } else {
+        throw new Error(
+          `Enricher ${enricher.id} must implement enrichMany() for list endpoints`,
+        )
+      }
+
+      const elapsedMs = Date.now() - startTime
+      if (elapsedMs > SLOW_ERROR_MS) {
+        console.error(
+          `[UMES] Enricher ${enricher.id} took ${elapsedMs}ms (threshold: ${SLOW_ERROR_MS}ms)`,
+        )
+      } else if (elapsedMs > SLOW_WARN_MS) {
+        console.warn(
+          `[UMES] Enricher ${enricher.id} took ${elapsedMs}ms (threshold: ${SLOW_WARN_MS}ms)`,
+        )
+      }
+
+      currentItems = result
+      if (shouldUseCache && cacheKey) {
+        await writeEnricherCache(
+          cache,
+          cacheKey,
+          result,
+          getEnricherCacheTtl(enricher),
+          getEnricherCacheTags(enricher, context),
+        )
+      }
+      enrichedBy.push(enricher.id)
+    } catch (err) {
+      if (enricher.critical) {
+        throw err
+      }
+
+      const message = err instanceof Error ? err.message : String(err)
+      console.warn(`[UMES] Enricher ${enricher.id} failed: ${message}`)
+      enricherErrors.push(enricher.id)
+
+      if (enricher.fallback) {
+        currentItems = currentItems.map((item) => ({
+          ...item,
+          ...enricher.fallback,
+        })) as T[]
+      }
+    }
+  }
+
+  return {
+    items: currentItems,
+    _meta: {
+      enrichedBy,
+      ...(enricherErrors.length > 0 ? { enricherErrors } : {}),
+    },
+  }
+}
+
+/**
+ * Apply response enrichers to a single record.
+ *
+ * Used for detail endpoints (GET /:id), POST, and PUT responses.
+ */
+export async function applyResponseEnricherToRecord<T extends Record<string, unknown>>(
+  record: T,
+  targetEntity: string,
+  context: EnricherContext,
+): Promise<SingleEnrichmentResult<T>> {
+  const activeEntries = getActiveEnrichers(targetEntity, context)
+
+  if (activeEntries.length === 0) {
+    return { record, _meta: { enrichedBy: [] } }
+  }
+
+  const enrichedBy: string[] = []
+  const enricherErrors: string[] = []
+  let currentRecord = record
+  const cache = resolveCache(context)
+
+  for (const entry of activeEntries) {
+    const enricher = entry.enricher
+    const timeout = enricher.timeout ?? DEFAULT_TIMEOUT
+
+    try {
+      const recordId = extractRecordId(currentRecord)
+      const shouldUseCache = enricher.cache?.strategy === 'read-through'
+      const cacheKey = shouldUseCache ? buildCacheKey(enricher, context, 'one', [recordId]) : null
+      if (shouldUseCache && cacheKey) {
+        const cached = await readEnricherCache<T>(cache, cacheKey)
+        if (cached) {
+          currentRecord = cached
+          enrichedBy.push(enricher.id)
+          continue
+        }
+      }
+      const result = await Promise.race([
+        enricher.enrichOne(currentRecord, context) as Promise<T>,
+        timeoutPromise(timeout),
+      ])
+
+      currentRecord = result
+      if (shouldUseCache && cacheKey) {
+        await writeEnricherCache(
+          cache,
+          cacheKey,
+          result,
+          getEnricherCacheTtl(enricher),
+          getEnricherCacheTags(enricher, context),
+        )
+      }
+      enrichedBy.push(enricher.id)
+    } catch (err) {
+      if (enricher.critical) {
+        throw err
+      }
+
+      const message = err instanceof Error ? err.message : String(err)
+      console.warn(`[UMES] Enricher ${enricher.id} failed: ${message}`)
+      enricherErrors.push(enricher.id)
+
+      if (enricher.fallback) {
+        currentRecord = { ...currentRecord, ...enricher.fallback } as T
+      }
+    }
+  }
+
+  return {
+    record: currentRecord,
+    _meta: {
+      enrichedBy,
+      ...(enricherErrors.length > 0 ? { enricherErrors } : {}),
+    },
+  }
+}

package/src/lib/crud/factory.ts

@@ -49,6 +49,8 @@ import {
 import { deriveCrudSegmentTag } from './cache-stats'
 import { createProfiler, shouldEnableProfiler, type Profiler } from '@open-mercato/shared/lib/profiler'
 import { getTranslationOverlayPlugin } from '@open-mercato/shared/lib/localization/overlay-plugin'
+import { applyResponseEnrichers, applyResponseEnricherToRecord } from './enricher-runner'
+import type { EnricherContext } from './response-enricher'
 
 export type CrudHooks<TCreate, TUpdate, TList> = {
   beforeList?: (q: TList, ctx: CrudCtx) => Promise<void> | void
@@ -279,6 +281,9 @@ function normalizeFullRecordForExport(input: any): any {
 
   for (const [key, value] of Object.entries(input)) {
     if (key.startsWith('cf_') || key.startsWith('cf:')) continue
+    // Strip enricher namespaced fields and metadata from exports
+    if (key === '_meta') continue
+    if (key.startsWith('_') && key.length > 1) continue
     record[key] = value
   }
   const custom = extractAllCustomFieldEntries(input)
@@ -345,6 +350,11 @@ export type CrudFactoryOptions<TCreate, TUpdate, TList> = {
     update?: CrudCommandActionConfig
     delete?: CrudCommandActionConfig
   }
+  /** Response enricher configuration. When set, enrichers targeting this entity run after afterList hook. */
+  enrichers?: {
+    /** Entity ID for enricher matching (e.g., 'customers.person') */
+    entityId: string
+  }
 }
 
 function deriveResourceFromActions(actions: CrudFactoryOptions<any, any, any>['actions']): string | null {
@@ -763,6 +773,70 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
     }
   }
 
+  /**
+   * Build enricher context from CRUD context and resolve user features for ACL gating.
+   * Returns null if enrichers are not configured or auth is missing.
+   */
+  async function buildEnricherContext(ctx: CrudCtx): Promise<EnricherContext | null> {
+    if (!opts.enrichers?.entityId) return null
+    if (!ctx.auth) return null
+
+    let userFeatures: string[] | undefined
+    try {
+      const rbac = (ctx.container.resolve('rbacService') as any)
+      if (rbac?.getGrantedFeatures) {
+        userFeatures = await rbac.getGrantedFeatures(ctx.auth.sub, {
+          tenantId: ctx.auth.tenantId,
+          organizationId: ctx.selectedOrganizationId ?? ctx.auth.orgId,
+        })
+      }
+    } catch {
+      // rbacService not available — enrichers without feature requirements still run
+    }
+
+    return {
+      organizationId: ctx.selectedOrganizationId ?? ctx.auth.orgId ?? '',
+      tenantId: ctx.auth.tenantId ?? '',
+      userId: ctx.auth.sub,
+      em: ctx.container.resolve('em'),
+      container: ctx.container,
+      userFeatures,
+    }
+  }
+
+  /**
+   * Apply response enrichers to list payload items.
+   * Mutates payload.items and adds payload._meta.
+   * No-op if enrichers are not configured.
+   */
+  async function enrichListPayload(payload: any, ctx: CrudCtx, profiler?: Profiler): Promise<void> {
+    if (!opts.enrichers?.entityId) return
+    const enricherCtx = await buildEnricherContext(ctx)
+    if (!enricherCtx) return
+    profiler?.mark('enrichers_start')
+    const result = await applyResponseEnrichers(payload.items, opts.enrichers.entityId, enricherCtx)
+    payload.items = result.items
+    if (result._meta.enrichedBy.length > 0 || result._meta.enricherErrors?.length) {
+      payload._meta = { ...(payload._meta || {}), ...result._meta }
+    }
+    profiler?.mark('enrichers_complete', { enricherCount: result._meta.enrichedBy.length })
+  }
+
+  /**
+   * Apply response enrichers to a single record.
+   * Returns the enriched record with _meta merged.
+   */
+  async function enrichSingleRecord(record: any, ctx: CrudCtx): Promise<any> {
+    if (!opts.enrichers?.entityId) return record
+    const enricherCtx = await buildEnricherContext(ctx)
+    if (!enricherCtx) return record
+    const result = await applyResponseEnricherToRecord(record, opts.enrichers.entityId, enricherCtx)
+    if (result._meta.enrichedBy.length > 0 || result._meta.enricherErrors?.length) {
+      return { ...result.record, _meta: result._meta }
+    }
+    return result.record
+  }
+
   async function ensureAuth(request?: Request | null) {
     const auth = request ? await getAuthFromRequest(request) : await getAuthFromCookies()
     if (!auth) return null
@@ -981,6 +1055,7 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
           query: validated,
         })
         await opts.hooks?.afterList?.(payload, { ...ctx, query: validated as any })
+        await enrichListPayload(payload, ctx, profiler)
         logCacheOutcome('hit', items.length)
         const response = respondWithPayload(payload)
         finishProfile({ result: 'cache_hit', cacheStatus })
@@ -1162,6 +1237,7 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
         }
         await opts.hooks?.afterList?.(payload, { ...ctx, query: validated as any })
         profiler.mark('after_list_hook')
+        await enrichListPayload(payload, ctx, profiler)
         await maybeStoreCrudCache(payload)
         profiler.mark('cache_store_attempt', { cacheEnabled })
         logCacheOutcome(cacheStatus, payload.items.length)
@@ -1281,6 +1357,7 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
       const payload = { items: list, total: list.length }
       await opts.hooks?.afterList?.(payload, { ...ctx, query: validated as any })
       profiler.mark('after_list_hook')
+      await enrichListPayload(payload, ctx, profiler)
       await maybeStoreCrudCache(payload)
       profiler.mark('cache_store_attempt', { cacheEnabled })
       logCacheOutcome(cacheStatus, payload.items.length)
@@ -1394,7 +1471,8 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
       await de.flushOrmEntityChanges()
       await invalidateCrudCache(ctx.container, resourceKind, identifiers, ctx.auth.tenantId ?? null, 'created', resourceTargets)
 
-      const payload = createConfig.response ? createConfig.response(entity) : { id: String((entity as any)[ormCfg.idField!]) }
+      let payload = createConfig.response ? createConfig.response(entity) : { id: String((entity as any)[ormCfg.idField!]) }
+      payload = await enrichSingleRecord(payload, ctx)
       return json(payload, { status: 201 })
     } catch (e) {
       return handleError(e)

package/src/lib/crud/response-enricher.ts

@@ -0,0 +1,110 @@
+/**
+ * Response Enricher Contract
+ *
+ * Allows modules to enrich other modules' API responses without touching core code.
+ * Similar to GraphQL Federation's @extends — modules can add computed fields to
+ * any entity's API response by declaring enrichers.
+ *
+ * Enrichers run AFTER CrudHooks.afterList and BEFORE HTTP response serialization.
+ * They are additive-only: enriched data lives under a `_<module>` namespace prefix.
+ */
+
+/**
+ * Context available to enrichers during execution.
+ * The EntityManager is read-only — enrichers MUST NOT perform writes.
+ */
+export interface EnricherContext {
+  organizationId: string
+  tenantId: string
+  userId: string
+  em: unknown
+  container: unknown
+  requestedFields?: string[]
+  userFeatures?: string[]
+}
+
+/**
+ * Response enricher definition.
+ *
+ * @template TRecord - The shape of the record being enriched
+ * @template TEnriched - Additional fields added by this enricher
+ *
+ * Rules:
+ * - `enrichMany` MUST be implemented for list endpoints (N+1 prevention)
+ * - Enrichers MUST NOT modify or remove existing fields (additive only)
+ * - Enriched data MUST be namespaced under `_<module>` prefix
+ * - Enrichers MUST NOT perform writes via EntityManager
+ */
+export interface ResponseEnricher<TRecord = any, TEnriched = any> {
+  /** Unique identifier: `<module>.<enricher-name>` */
+  id: string
+
+  /** Target entity to enrich: `<module>.<entity>` (e.g., 'customers.person') */
+  targetEntity: string
+
+  /** ACL features required for this enricher to run */
+  features?: string[]
+
+  /** Execution priority (higher = runs first). Default: 0 */
+  priority?: number
+
+  /** Maximum execution time in ms before the enricher is skipped. Default: 2000 */
+  timeout?: number
+
+  /** Fallback value to merge into the record when the enricher times out or throws */
+  fallback?: Record<string, unknown>
+
+  /** If true, enricher errors propagate as HTTP errors. Default: false */
+  critical?: boolean
+
+  /** Tenant IDs where this enricher should be disabled. */
+  disabledTenantIds?: string[]
+
+  /** Optional cache configuration for read-through enrichment results. */
+  cache?: {
+    strategy: 'read-through'
+    ttl: number
+    tags?: string[]
+    invalidateOn?: string[]
+  }
+
+  /** Enrich a single record. Used for detail endpoints. */
+  enrichOne(record: TRecord, context: EnricherContext): Promise<TRecord & TEnriched>
+
+  /**
+   * Enrich multiple records in a single batch call.
+   * MUST be implemented for list endpoints to prevent N+1 queries.
+   * Use batch queries (e.g., `$in` with all record IDs) instead of per-record queries.
+   */
+  enrichMany?(records: TRecord[], context: EnricherContext): Promise<(TRecord & TEnriched)[]>
+}
+
+/**
+ * Registered enricher entry with module context.
+ */
+export interface EnricherRegistryEntry {
+  moduleId: string
+  enricher: ResponseEnricher
+}
+
+/**
+ * Result of applying enrichers to a set of records.
+ */
+export interface EnrichmentResult<T = any> {
+  items: T[]
+  _meta: {
+    enrichedBy: string[]
+    enricherErrors?: string[]
+  }
+}
+
+/**
+ * Result of applying enrichers to a single record.
+ */
+export interface SingleEnrichmentResult<T = any> {
+  record: T
+  _meta: {
+    enrichedBy: string[]
+    enricherErrors?: string[]
+  }
+}

package/src/modules/events/factory.ts

@@ -92,6 +92,15 @@ export function getDeclaredEvents(): EventDefinition[] {
   return [...allDeclaredEvents]
 }
 
+/**
+ * Check if an event has clientBroadcast enabled.
+ * Used by the SSE endpoint to filter events for the DOM Event Bridge.
+ */
+export function isBroadcastEvent(eventId: string): boolean {
+  const event = allDeclaredEvents.find(e => e.id === eventId)
+  return event?.clientBroadcast === true
+}
+
 // =============================================================================
 // Bootstrap Registration (similar to searchModuleConfigs pattern)
 // =============================================================================

package/src/modules/events/types.ts

@@ -32,6 +32,8 @@ export interface EventDefinition {
   entity?: string
   /** Whether excluded from workflow triggers */
   excludeFromTriggers?: boolean
+  /** When true, this event is bridged to the browser via SSE (DOM Event Bridge). Default: false */
+  clientBroadcast?: boolean
 }
 
 // =============================================================================

package/src/modules/registry.ts

@@ -1,7 +1,7 @@
 import type { ReactNode } from 'react'
 import type { OpenApiRouteDoc, OpenApiMethodDoc } from '@open-mercato/shared/lib/openapi/types'
 import type { DashboardWidgetModule } from './dashboard/widgets'
-import type { InjectionWidgetModule, ModuleInjectionTable } from './widgets/injection'
+import type { InjectionAnyWidgetModule, ModuleInjectionTable } from './widgets/injection'
 
 // Context passed to dynamic metadata guards
 export type RouteVisibilityContext = { path?: string; auth?: any }
@@ -130,7 +130,7 @@ export type ModuleInjectionWidgetEntry = {
   moduleId: string
   key: string
   source: 'app' | 'package'
-  loader: () => Promise<InjectionWidgetModule<any, any>>
+  loader: () => Promise<InjectionAnyWidgetModule<any, any>>
 }
 
 export type Module = {

package/src/modules/widgets/__tests__/injection-position.test.ts

@@ -0,0 +1,33 @@
+/**
+ * @jest-environment jsdom
+ */
+import { describe, expect, it } from '@jest/globals'
+import {
+  InjectionPosition,
+  insertByInjectionPlacement,
+} from '@open-mercato/shared/modules/widgets/injection-position'
+
+type Item = { id: string }
+
+describe('injection-position', () => {
+  it('should resolve insertion order for before/after/first/last', () => {
+    let items: Item[] = [{ id: 'a' }, { id: 'b' }, { id: 'c' }]
+    items = insertByInjectionPlacement(items, { id: 'x' }, { position: InjectionPosition.Before, relativeTo: 'b' }, (entry) => entry.id)
+    items = insertByInjectionPlacement(items, { id: 'y' }, { position: InjectionPosition.After, relativeTo: 'a' }, (entry) => entry.id)
+    items = insertByInjectionPlacement(items, { id: 'z' }, { position: InjectionPosition.First }, (entry) => entry.id)
+    items = insertByInjectionPlacement(items, { id: 'w' }, { position: InjectionPosition.Last }, (entry) => entry.id)
+
+    expect(items.map((entry) => entry.id)).toEqual(['z', 'a', 'y', 'x', 'b', 'c', 'w'])
+  })
+
+  it('should append item when relative target is missing', () => {
+    const items = insertByInjectionPlacement(
+      [{ id: 'a' }],
+      { id: 'x' },
+      { position: InjectionPosition.Before, relativeTo: 'missing' },
+      (entry) => entry.id,
+    )
+
+    expect(items.map((entry) => entry.id)).toEqual(['a', 'x'])
+  })
+})