@open-mercato/shared 0.8.1-develop.7297.1.67605e74f9 → 0.9.0

package/src/lib/i18n/__tests__/detect-locale-narrowed.test.ts

@@ -4,21 +4,25 @@ import type { Locale } from '../config'
 // mock has to be in place before the module under test is loaded.
 const cookieStore = { value: undefined as string | undefined }
 const headerStore = { acceptLanguage: '' }
+const nextHeadersCalls = { cookies: 0, headers: 0 }
+let caseReadsTheRequest = true
 
-jest.mock(
-  'next/headers',
-  () => ({
-    cookies: async () => ({
+jest.mock('next/headers', () => ({
+  cookies: async () => {
+    nextHeadersCalls.cookies += 1
+    return {
       get: (name: string) =>
         name === 'locale' && cookieStore.value ? { value: cookieStore.value } : undefined,
-    }),
-    headers: async () => ({
+    }
+  },
+  headers: async () => {
+    nextHeadersCalls.headers += 1
+    return {
       get: (name: string) =>
         name.toLowerCase() === 'accept-language' ? headerStore.acceptLanguage : null,
-    }),
-  }),
-  { virtual: true },
-)
+    }
+  },
+}))
 
 import { detectLocale } from '../server'
 import { clearRegisteredLocales, registerLocales } from '../locale-registry'
@@ -30,9 +34,14 @@ describe('detectLocale with a narrowed supported set', () => {
     cookieStore.value = undefined
     headerStore.acceptLanguage = ''
     delete process.env.OM_FORCE_LOCALE
+    nextHeadersCalls.cookies = 0
+    nextHeadersCalls.headers = 0
+    caseReadsTheRequest = true
+    clearRegisteredLocales()
   })
 
   afterEach(() => {
+    if (caseReadsTheRequest) expect(nextHeadersCalls.cookies + nextHeadersCalls.headers).toBeGreaterThan(0)
     clearRegisteredLocales()
   })
 
@@ -91,6 +100,7 @@ describe('detectLocale with a narrowed supported set', () => {
   })
 
   it('still lets OM_FORCE_LOCALE win over the narrowed set', async () => {
+    caseReadsTheRequest = false
     process.env.OM_FORCE_LOCALE = 'ko'
 
     try {

package/src/lib/modules/api-route-identity.ts

@@ -0,0 +1,116 @@
+import type { RouteMatchParams } from '../../modules/registry'
+
+const matchedApiRoutePaths = new WeakMap<Request, string>()
+const ROUTE_IDENTITY_HEADER = 'x-open-mercato-route-identity'
+const MAX_ROUTE_IDENTITY_TOKENS = 4096
+const matchedApiRouteTokens = new Map<string, string>()
+
+function normalizePath(path: string): string {
+  return (path.startsWith('/') ? path : `/${path}`).replace(/\/+$/, '') || '/'
+}
+
+function hasValidPathEncoding(request: Request): boolean {
+  try {
+    const pathname = new URL(request.url).pathname
+    for (const segment of pathname.split('/')) decodeURIComponent(segment)
+    return true
+  } catch {
+    return false
+  }
+}
+
+function buildCanonicalMatchedPath(pattern: string, params: RouteMatchParams): string | null {
+  const segments = normalizePath(pattern).split('/').slice(1)
+  const canonicalSegments: string[] = []
+
+  for (const segment of segments) {
+    const catchAll = segment.match(/^\[\.\.\.(.+)\]$/)
+    const optionalCatchAll = segment.match(/^\[\[\.\.\.(.+)\]\]$/)
+    const dynamic = segment.match(/^\[(.+)\]$/)
+    const paramName = catchAll?.[1] ?? optionalCatchAll?.[1] ?? dynamic?.[1]
+
+    if (!paramName) {
+      canonicalSegments.push(segment)
+      continue
+    }
+
+    const value = params[paramName]
+    if (Array.isArray(value)) {
+      canonicalSegments.push(...value)
+      continue
+    }
+    if (typeof value === 'string') {
+      canonicalSegments.push(value)
+      continue
+    }
+    if (optionalCatchAll) continue
+    return null
+  }
+
+  return `/${canonicalSegments.join('/')}`
+}
+
+function createRouteIdentityToken(): string | null {
+  const cryptoApi = globalThis.crypto
+  if (!cryptoApi) return null
+  if (typeof cryptoApi.randomUUID === 'function') return cryptoApi.randomUUID()
+  const bytes = cryptoApi.getRandomValues(new Uint8Array(24))
+  return Array.from(bytes, (value) => value.toString(16).padStart(2, '0')).join('')
+}
+
+function rememberRouteIdentity(token: string, canonicalPath: string): void {
+  matchedApiRouteTokens.set(token, canonicalPath)
+  while (matchedApiRouteTokens.size > MAX_ROUTE_IDENTITY_TOKENS) {
+    const oldestToken = matchedApiRouteTokens.keys().next().value
+    if (typeof oldestToken !== 'string') return
+    matchedApiRouteTokens.delete(oldestToken)
+  }
+}
+
+export function bindMatchedApiRoutePath(
+  request: Request,
+  pattern: string,
+  params: RouteMatchParams,
+): boolean {
+  if (!hasValidPathEncoding(request)) return false
+  const canonicalPath = buildCanonicalMatchedPath(pattern, params)
+  if (canonicalPath === null) return false
+  const token = createRouteIdentityToken()
+  if (token === null) return false
+  try {
+    request.headers.set(ROUTE_IDENTITY_HEADER, token)
+  } catch {
+    return false
+  }
+  rememberRouteIdentity(token, canonicalPath)
+  matchedApiRoutePaths.set(request, canonicalPath)
+  return true
+}
+
+export function getMatchedApiRoutePath(request: Request): string | undefined {
+  const directPath = matchedApiRoutePaths.get(request)
+  if (directPath !== undefined) return directPath
+  const token = request.headers.get(ROUTE_IDENTITY_HEADER)
+  if (!token) return undefined
+  return matchedApiRouteTokens.get(token)
+}
+
+function toInterceptorRoutePath(pathname: string): string {
+  if (pathname.startsWith('/api/')) return pathname.slice(5)
+  if (pathname === '/api') return ''
+  return pathname.replace(/^\/+/, '')
+}
+
+export function resolveApiInterceptorRoutePath(request: Request): string | null {
+  const matchedPath = getMatchedApiRoutePath(request)
+  if (matchedPath !== undefined) return toInterceptorRoutePath(matchedPath)
+  if (request.headers.has(ROUTE_IDENTITY_HEADER)) return null
+
+  try {
+    const pathname = new URL(request.url).pathname
+    for (const segment of pathname.split('/')) decodeURIComponent(segment)
+    return toInterceptorRoutePath(pathname)
+  } catch {
+    return null
+  }
+}

package/src/lib/telemetry/runtime.ts

@@ -2,6 +2,8 @@ export type TelemetryTraceCarrier = Record<string, string>
 
 export type TelemetrySpanAttributes = Record<string, string | number | boolean | undefined>
 
+export type TelemetryMetricLabels = Record<string, string | number | boolean | undefined>
+
 export type TelemetrySpanKind = 'internal' | 'server' | 'client' | 'producer' | 'consumer'
 
 /** The subset of the telemetry package's `Span` that bridge consumers need. */
@@ -43,6 +45,12 @@ export type TelemetryRuntime = {
    * running `fn` untraced.
    */
   withSpan?<T>(name: string, fn: (span: TelemetrySpan) => T, options?: TelemetrySpanOptions): T
+  recordHistogram?(
+    name: string,
+    value: number,
+    labels?: TelemetryMetricLabels,
+    unit?: string,
+  ): void
   recordHttpDuration(method: string, route: string, status: number, startedAt: number): void
   reportError(
     error: unknown,

package/src/modules/__tests__/registry.test.ts

@@ -17,6 +17,10 @@ import {
   getFrontendRouteManifests,
   resolvePageRouteMetadata,
 } from '../registry'
+import {
+  getMatchedApiRoutePath,
+  resolveApiInterceptorRoutePath,
+} from '../../lib/modules/api-route-identity'
 
 describe('CLI Modules Registry', () => {
   // Clear the registry before each test
@@ -628,6 +632,94 @@ describe('findApiRouteManifestMatch — specificity (issue #1870)', () => {
     const match = findApiRouteManifestMatch(unsorted, 'GET', '/api/things/new')
     expect(match?.route.path).toBe('/api/things/new')
   })
+
+  it.each([
+    ['normal spelling', 'http://localhost/api/auth/users/AbC-123?view=full', '/auth/users/AbC-123'],
+    ['mixed-case alias', 'http://localhost/api/AUTH/users/AbC-123?view=full', '/AUTH/users/AbC-123'],
+    ['percent-encoded alias', 'http://localhost/api/%61uth/users/AbC-123?view=full', '/auth/users/AbC-123'],
+  ])('binds the authored static route as canonical identity for %s', (_label, url, dispatcherPath) => {
+    const request = new Request(url)
+    const routes = [apiEntry('/auth/users/[id]')]
+    const match = findApiRouteManifestMatch(routes, 'GET', dispatcherPath, request)
+
+    expect(match?.params).toEqual({ id: 'AbC-123' })
+    expect(getMatchedApiRoutePath(request)).toBe('/auth/users/AbC-123')
+    expect(resolveApiInterceptorRoutePath(request.clone())).toBe('auth/users/AbC-123')
+    expect(resolveApiInterceptorRoutePath(new Request(request.url, request))).toBe('auth/users/AbC-123')
+    expect(new URL(request.url).searchParams.get('view')).toBe('full')
+  })
+
+  it('preserves catch-all parameter values in the canonical identity', () => {
+    const request = new Request('http://localhost/api/DOCS/guides/Getting-Started')
+    const routes = [apiEntry('/docs/[...slug]')]
+    const match = findApiRouteManifestMatch(
+      routes,
+      'GET',
+      '/DOCS/guides/Getting-Started',
+      request,
+    )
+
+    expect(match?.params).toEqual({ slug: ['guides', 'Getting-Started'] })
+    expect(getMatchedApiRoutePath(request)).toBe('/docs/guides/Getting-Started')
+    expect(resolveApiInterceptorRoutePath(request.clone())).toBe('docs/guides/Getting-Started')
+    expect(resolveApiInterceptorRoutePath(new Request(request.url, request))).toBe('docs/guides/Getting-Started')
+  })
+
+  it('fails closed for an attacker-supplied route identity token', () => {
+    const request = new Request('http://localhost/api/AUTH/users/AbC-123', {
+      headers: { 'x-open-mercato-route-identity': 'attacker-controlled' },
+    })
+
+    expect(resolveApiInterceptorRoutePath(request)).toBeNull()
+    expect(resolveApiInterceptorRoutePath(request.clone())).toBeNull()
+  })
+
+  it('bounds clone-capability state and fails closed after eviction', () => {
+    const routes = [apiEntry('/auth/users/[id]')]
+    let firstClone: Request | null = null
+    let lastClone: Request | null = null
+
+    for (let index = 0; index < 4200; index += 1) {
+      const request = new Request(`http://localhost/api/auth/users/user-${index}`)
+      expect(findApiRouteManifestMatch(
+        routes,
+        'GET',
+        `/auth/users/user-${index}`,
+        request,
+      )).toBeDefined()
+      if (index === 0) firstClone = request.clone()
+      if (index === 4199) lastClone = request.clone()
+    }
+
+    expect(firstClone).not.toBeNull()
+    expect(lastClone).not.toBeNull()
+    expect(resolveApiInterceptorRoutePath(firstClone!)).toBeNull()
+    expect(resolveApiInterceptorRoutePath(lastClone!)).toBe('auth/users/user-4199')
+  })
+
+  it('fails closed before binding a route when the request path has malformed encoding', () => {
+    const request = new Request('http://localhost/api/auth/%ZZ')
+    const match = findApiRouteManifestMatch(
+      [apiEntry('/auth/[id]')],
+      'GET',
+      '/auth/%ZZ',
+      request,
+    )
+
+    expect(match).toBeUndefined()
+    expect(getMatchedApiRoutePath(request)).toBeUndefined()
+  })
+
+  it('keeps the three-argument matcher contract for non-request consumers', () => {
+    const match = findApiRouteManifestMatch(
+      [apiEntry('/auth/users/[id]')],
+      'GET',
+      '/AUTH/users/AbC-123',
+    )
+
+    expect(match?.route.path).toBe('/auth/users/[id]')
+    expect(match?.params).toEqual({ id: 'AbC-123' })
+  })
 })
 
 describe('registerFrontendRouteManifests — sorts on registration (issue #1870)', () => {

package/src/modules/events/__tests__/broadcast-coalescing-declaration.test.ts

@@ -0,0 +1,53 @@
+import { createModuleEvents, isCoalescedBroadcastEvent } from '../factory'
+
+const GLOBAL_EVENT_REGISTRY_KEY = '__openMercatoEventDefinitionRegistry__'
+
+describe('broadcastCoalescing declarations', () => {
+  const globalScope = globalThis as Record<string, unknown>
+  const originalRegistry = globalScope[GLOBAL_EVENT_REGISTRY_KEY]
+
+  beforeEach(() => {
+    delete globalScope[GLOBAL_EVENT_REGISTRY_KEY]
+  })
+
+  afterAll(() => {
+    if (originalRegistry === undefined) delete globalScope[GLOBAL_EVENT_REGISTRY_KEY]
+    else globalScope[GLOBAL_EVENT_REGISTRY_KEY] = originalRegistry
+  })
+
+  it('recognizes an opted-in browser event and nothing else', () => {
+    createModuleEvents({
+      moduleId: 'coalesce_decl_test',
+      events: [
+        { id: 'coalesce_decl_test.bulk', label: 'Bulk', clientBroadcast: true, broadcastCoalescing: true },
+        { id: 'coalesce_decl_test.portal', label: 'Portal', portalBroadcast: true, broadcastCoalescing: true },
+        { id: 'coalesce_decl_test.plain_browser', label: 'Plain Browser', clientBroadcast: true },
+        { id: 'coalesce_decl_test.local', label: 'Local' },
+      ] as const,
+    })
+
+    expect(isCoalescedBroadcastEvent('coalesce_decl_test.bulk')).toBe(true)
+    expect(isCoalescedBroadcastEvent('coalesce_decl_test.portal')).toBe(true)
+    expect(isCoalescedBroadcastEvent('coalesce_decl_test.plain_browser')).toBe(false)
+    expect(isCoalescedBroadcastEvent('coalesce_decl_test.local')).toBe(false)
+    expect(isCoalescedBroadcastEvent('coalesce_decl_test.never_declared')).toBe(false)
+  })
+
+  it('rejects coalescing private cross-process coordination', () => {
+    expect(() => createModuleEvents({
+      moduleId: 'coalesce_decl_test',
+      events: [
+        { id: 'coalesce_decl_test.private', label: 'Private', crossProcessBroadcast: true, broadcastCoalescing: true },
+      ] as const,
+    })).toThrow(/crossProcessBroadcast/)
+  })
+
+  it('rejects coalescing an event with no browser delivery to coalesce', () => {
+    expect(() => createModuleEvents({
+      moduleId: 'coalesce_decl_test',
+      events: [
+        { id: 'coalesce_decl_test.orphan', label: 'Orphan', broadcastCoalescing: true },
+      ] as const,
+    })).toThrow(/clientBroadcast or portalBroadcast/)
+  })
+})

package/src/modules/events/factory.ts

@@ -212,6 +212,20 @@ export function isPrivateCrossProcessEventEmitter(
     && event.module === emitterModuleId
 }
 
+/**
+ * Check whether an event opted into coalesced browser delivery.
+ * Read by the event bus before it hands a browser dispatch to the coalescer.
+ */
+export function isCoalescedBroadcastEvent(eventId: string): boolean {
+  const event = getEventRegistryState().declaredEvents.find(e => e.id === eventId)
+  if (event?.broadcastCoalescing !== true) return false
+  // Private cross-process coordination must never be delayed, and an event with
+  // no browser sink has nothing to coalesce. Both are rejected at declaration
+  // time, so this is defence in depth for events registered by other paths.
+  if (event.crossProcessBroadcast === true) return false
+  return event.clientBroadcast === true || event.portalBroadcast === true
+}
+
 /**
  * Check if an event has portalBroadcast enabled.
  * Used by the portal SSE endpoint to filter events for the Portal Event Bridge.
@@ -308,6 +322,23 @@ export function createModuleEvents<
     }),
   )
 
+  for (const event of fullEvents) {
+    if (event.broadcastCoalescing !== true) continue
+    if (event.crossProcessBroadcast === true) {
+      throw new Error(
+        `[internal] Event "${event.id}" declared by module "${moduleId}" combines crossProcessBroadcast with ` +
+        'broadcastCoalescing. Private cross-process coordination must be delivered immediately — delaying it ' +
+        'would let another process serve stale data. Drop one of the two flags.',
+      )
+    }
+    if (event.clientBroadcast !== true && event.portalBroadcast !== true) {
+      throw new Error(
+        `[internal] Event "${event.id}" declared by module "${moduleId}" sets broadcastCoalescing without ` +
+        'clientBroadcast or portalBroadcast. There is no browser delivery to coalesce.',
+      )
+    }
+  }
+
   // Register all event IDs and definitions in the global registry.
   for (const event of fullEvents) {
     addDeclaredEvent(event)

package/src/modules/events/types.ts

@@ -75,6 +75,19 @@ export interface EventDefinition {
   crossProcessBroadcast?: boolean
   /** When true, this event is bridged to the customer portal via SSE (Portal Event Bridge). Default: false */
   portalBroadcast?: boolean
+  /**
+   * When true, browser deliveries of this event coalesce: within
+   * OM_BROADCAST_COALESCE_INTERVAL_MS only the newest payload per
+   * audience (event, tenant, organizations, recipients) reaches the SSE bridges,
+   * and a trailing flush guarantees the last one is delivered. Subscribers, webhooks and the queue are
+   * unaffected — the domain event still fires once per record.
+   *
+   * Declare it only on events whose browser consumers react to the fact that
+   * something changed (a list refresh), never to each occurrence. Cannot be
+   * combined with crossProcessBroadcast: delaying private coordination would let
+   * another process serve stale data. Default: false
+   */
+  broadcastCoalescing?: boolean
   /**
    * Optional declared payload typing. Platform-emitted CRUD events
    * (`*.created`/`*.updated`/`*.deleted` with category `crud`) receive a

package/src/modules/notifications/types.ts

@@ -165,6 +165,7 @@ export type NotificationDto = {
     labelKey?: string
     variant?: string
     icon?: string
+    href?: string
   }>
   primaryActionId?: string
   sourceModule?: string | null

package/src/modules/registry.ts

@@ -12,6 +12,7 @@ import {
   composeApiRouteOverrides,
   composePageRouteOverrides,
 } from './overrides'
+import { bindMatchedApiRoutePath } from '../lib/modules/api-route-identity'
 
 const logger = createLogger('shared').child({ component: 'cli-registry' })
 
@@ -414,12 +415,14 @@ export function findRouteManifestMatch<T extends { pattern?: string; path?: stri
 export function findApiRouteManifestMatch<T extends { path: string; methods: HttpMethod[] }>(
   routes: T[],
   method: HttpMethod,
-  pathname: string
+  pathname: string,
+  request?: Request,
 ): { route: T; params: RouteMatchParams } | undefined {
   for (const route of ensureSortedRoutes(routes)) {
     if (!route.methods.includes(method)) continue
     const params = matchRoutePattern(route.path, pathname)
     if (params) {
+      if (request && !bindMatchedApiRoutePath(request, route.path, params)) return undefined
       return { route, params }
     }
   }