@open-mercato/shared 0.7.0 → 0.7.1-develop.7102.1.b41f7e3e51

package/src/lib/crud/__tests__/crud-factory.test.ts

@@ -12,6 +12,16 @@ import {
 import { loadCustomFieldDefinitionIndex } from '@open-mercato/shared/lib/crud/custom-fields'
 import { registerMutationGuards } from '@open-mercato/shared/lib/crud/mutation-guard-store'
 import { CommandInterceptorError } from '@open-mercato/shared/lib/commands/errors'
+import {
+  registerLoggerExtension,
+  resetLoggerExtension,
+  type LoggerExtensionRecord,
+} from '@open-mercato/shared/lib/logger'
+import {
+  registerTelemetryRuntime,
+  resetTelemetryRuntime,
+  type TelemetryRuntime,
+} from '@open-mercato/shared/lib/telemetry/runtime'
 import { z } from 'zod'
 
 // Keep the real custom-field helpers but spy on the definition loader so we can
@@ -268,6 +278,28 @@ describe('CRUD Factory', () => {
     }))
   })
 
+  it('GET spreads totalIsCapped only when the engine reports a capped count', async () => {
+    queryEngine.query.mockResolvedValueOnce({
+      items: [{ id: 'id-1', title: 'A', is_done: false }],
+      total: 10_000,
+      page: 1,
+      pageSize: 10,
+      meta: { listCountCapWarning: { entity: 'example.todo', cap: 10_000 } },
+    })
+    const res = await route.GET(new Request('http://x/api/example/todos?page=1&pageSize=10&sortField=id&sortDir=asc'))
+    expect(res.status).toBe(200)
+    const body = await res.json()
+    expect(body.total).toBe(10_000)
+    expect(body.totalIsCapped).toBe(true)
+    expect(body.meta.listCountCapWarning).toEqual({ entity: 'example.todo', cap: 10_000 })
+  })
+
+  it('GET omits totalIsCapped entirely for exact totals', async () => {
+    const res = await route.GET(new Request('http://x/api/example/todos?page=1&pageSize=10&sortField=id&sortDir=asc'))
+    const body = await res.json()
+    expect('totalIsCapped' in body).toBe(false)
+  })
+
   const makeDecoratedRoute = () => makeCrudRoute({
     metadata: { GET: { requireAuth: true } },
     orm: { entity: Todo, idField: 'id', orgField: 'organizationId', tenantField: 'tenantId', softDeleteField: 'deletedAt' },
@@ -1054,6 +1086,7 @@ describe('CRUD Factory', () => {
     await expect(res.json()).resolves.toEqual({
       error: 'Internal server error',
       message: 'Something went wrong. Please try again later.',
+      requestId: expect.any(String),
     })
   })
 
@@ -1092,6 +1125,138 @@ describe('CRUD Factory', () => {
     await expect(res.json()).resolves.toEqual({
       error: 'Internal server error',
       message: 'Something went wrong. Please try again later.',
+      requestId: expect.any(String),
+    })
+  })
+
+  // Issue #5608 — a generic 500 must carry a requestId the client/support can cite, and
+  // that same id must appear on the server log line so the two can be correlated.
+  describe('generic 500 requestId correlation', () => {
+    const logRecords: LoggerExtensionRecord[] = []
+    const reportError = jest.fn()
+
+    const postWithRequestId = (requestId: string) => interceptorErrorRoute().POST(
+      new Request('http://x/api/example/todos/command', {
+        method: 'POST',
+        body: JSON.stringify({ title: 'A' }),
+        headers: { 'content-type': 'application/json', 'x-request-id': requestId },
+      }),
+    )
+
+    beforeEach(() => {
+      logRecords.length = 0
+      reportError.mockClear()
+      registerLoggerExtension({ emit: (record) => logRecords.push(record) })
+      registerTelemetryRuntime({
+        canUseGlobalTracePropagation: () => false,
+        captureTraceContext: () => ({}),
+        continueTrace: (_carrier, _name, fn) => fn(),
+        recordHttpDuration: () => {},
+        reportError,
+        shutdown: async () => {},
+      } satisfies TelemetryRuntime)
+    })
+
+    afterEach(() => {
+      resetLoggerExtension()
+      resetTelemetryRuntime()
+    })
+
+    it('includes a requestId in the body that matches the server log line', async () => {
+      commandBus.execute.mockRejectedValue(new Error('boom'))
+
+      const res = await postInterceptorErrorRequest(interceptorErrorRoute())
+      const body = await res.json()
+
+      expect(res.status).toBe(500)
+      expect(typeof body.requestId).toBe('string')
+      expect(body.requestId.length).toBeGreaterThan(0)
+
+      const logRecord = logRecords.find((record) => record.message === 'Unexpected CRUD error')
+      expect(logRecord?.fields.requestId).toBe(body.requestId)
+    })
+
+    it('echoes the requestId on an x-request-id response header', async () => {
+      commandBus.execute.mockRejectedValue(new Error('boom'))
+
+      const res = await postInterceptorErrorRequest(interceptorErrorRoute())
+      const body = await res.json()
+
+      expect(res.headers.get('x-request-id')).toBe(body.requestId)
+    })
+
+    it('reuses an inbound x-request-id header instead of generating a new one', async () => {
+      commandBus.execute.mockRejectedValue(new Error('boom'))
+
+      const res = await postWithRequestId('req-fixed-123')
+      const body = await res.json()
+
+      expect(res.status).toBe(500)
+      expect(body.requestId).toBe('req-fixed-123')
+      const logRecord = logRecords.find((record) => record.message === 'Unexpected CRUD error')
+      expect(logRecord?.fields.requestId).toBe('req-fixed-123')
+    })
+
+    // `Headers.get()` returns '' for an empty or whitespace-only header, which a plain
+    // `?? randomUUID()` would hand straight through as a blank correlation id.
+    it.each([
+      ['an empty inbound header', ''],
+      ['a whitespace-only inbound header', '   '],
+    ])('generates a fresh id for %s', async (_label, inbound) => {
+      commandBus.execute.mockRejectedValue(new Error('boom'))
+
+      const res = await postWithRequestId(inbound)
+      const body = await res.json()
+
+      expect(res.status).toBe(500)
+      expect(typeof body.requestId).toBe('string')
+      expect(body.requestId.length).toBeGreaterThan(0)
+      const logRecord = logRecords.find((record) => record.message === 'Unexpected CRUD error')
+      expect(logRecord?.fields.requestId).toBe(body.requestId)
+    })
+
+    // A caller-controlled id lands verbatim in the unquoted `key=value` log line, so an
+    // over-long one or one carrying spaces/`=` is discarded rather than echoed.
+    it.each([
+      ['a value carrying log-field separators', 'a=1 tenantId=victim'],
+      ['an over-long value', 'x'.repeat(129)],
+    ])('discards %s in favor of a generated id', async (_label, inbound) => {
+      commandBus.execute.mockRejectedValue(new Error('boom'))
+
+      const res = await postWithRequestId(inbound)
+      const body = await res.json()
+
+      expect(res.status).toBe(500)
+      expect(body.requestId).not.toBe(inbound)
+      expect(body.requestId).toMatch(/^[A-Za-z0-9-]{36}$/)
+    })
+
+    it('reports the error to telemetry with the same requestId', async () => {
+      commandBus.execute.mockRejectedValue(new Error('boom'))
+
+      const res = await postWithRequestId('req-fixed-123')
+      const body = await res.json()
+
+      expect(body.requestId).toBe('req-fixed-123')
+      expect(reportError).toHaveBeenCalledTimes(1)
+      expect(reportError).toHaveBeenCalledWith(
+        expect.any(Error),
+        { module: 'crud', attributes: { requestId: 'req-fixed-123', errorName: 'Error' } },
+      )
+    })
+
+    // The 503/422 branches deliberately stay outside this change (issue #5608) — lock that
+    // in so a later refactor cannot quietly widen the correlation id across every branch.
+    it('leaves the interceptor-rejection branch without a requestId', async () => {
+      commandBus.execute.mockRejectedValue(
+        new CommandInterceptorError('Missing required fields: VAT id', { status: 422 }),
+      )
+
+      const res = await postWithRequestId('req-fixed-123')
+
+      expect(res.status).toBe(422)
+      await expect(res.json()).resolves.toEqual({ error: 'Missing required fields: VAT id' })
+      expect(res.headers.get('x-request-id')).toBeNull()
     })
   })
 

package/src/lib/crud/factory.ts

@@ -75,6 +75,8 @@ import { createGenericOptimisticLockReader } from './optimistic-lock'
 import { registerOptimisticLockReaderIfAbsent } from './optimistic-lock-store'
 import { createLogger } from '../logger'
 import { isTransientDbError } from '../db/pg-errors'
+import { getTelemetryRuntime } from '../telemetry/runtime'
+import { randomUUID } from 'node:crypto'
 
 type RbacServiceLike = {
   getGrantedFeatures: (userId: string, opts: { tenantId: string | null; organizationId: string | null }) => Promise<string[]>
@@ -594,7 +596,19 @@ function attachOperationHeader(res: Response, logEntry: any) {
   return res
 }
 
-function handleError(err: unknown): Response {
+// An inbound `x-request-id` is caller-controlled, so it is only reused when it still
+// looks like an id. `Headers.get()` yields '' for an empty or whitespace-only header —
+// which `??` would not replace — and an unbounded value carrying spaces or `=` would
+// forge fields in the unquoted `key=value` log line this id exists to be read from.
+const INBOUND_REQUEST_ID_PATTERN = /^[A-Za-z0-9._-]{1,128}$/
+
+function resolveRequestId(request?: Request): string {
+  const inbound = request?.headers.get('x-request-id')?.trim()
+  if (inbound && INBOUND_REQUEST_ID_PATTERN.test(inbound)) return inbound
+  return randomUUID()
+}
+
+function handleError(err: unknown, request?: Request): Response {
   if (err instanceof Response) return err
   if (isCrudHttpError(err)) return json(err.body, { status: err.status })
   // A command interceptor that blocked with an explicit status is a deliberate business
@@ -618,14 +632,25 @@ function handleError(err: unknown): Response {
     )
   }
 
+  // Unexpected exceptions still collapse into a generic 500 for the client (no internal
+  // detail leaked), but a requestId ties that response to this log line and to whatever
+  // reaches APM, so a client/support ticket citing it can be correlated with server-side
+  // detail (issue #5608).
   const message = err instanceof Error ? err.message : undefined
   const stack = err instanceof Error ? err.stack : undefined
-  logger.error('Unexpected CRUD error', { message, stack, err })
+  const errorName = err instanceof Error ? err.name : undefined
+  const requestId = resolveRequestId(request)
+  logger.error('Unexpected CRUD error', { message, stack, err, requestId })
+  getTelemetryRuntime()?.reportError(err, {
+    module: 'crud',
+    attributes: { requestId, errorName },
+  })
   const body: Record<string, unknown> = {
     error: 'Internal server error',
     message: 'Something went wrong. Please try again later.',
+    requestId,
   }
-  return json(body, { status: 500 })
+  return json(body, { status: 500, headers: { 'x-request-id': requestId } })
 }
 
 const LIFECYCLE_ACTION_MAP: Record<string, { before: string; after: string }> = {
@@ -1941,6 +1966,7 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
           page: page.page || requestedPage,
           pageSize: page.pageSize || requestedPageSize,
           totalPages: Math.ceil(res.total / (Number(page.pageSize) || 1)),
+          ...(res.meta?.listCountCapWarning ? { totalIsCapped: true } : {}),
           ...(res.meta ? { meta: res.meta } : {}),
         }
         await opts.hooks?.afterList?.(payload, { ...ctx, query: validated as any })
@@ -2162,7 +2188,7 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
       return response
     } catch (e) {
       finishProfile({ result: 'error' })
-      return handleError(e)
+      return handleError(e, request)
     }
   }
 
@@ -2476,7 +2502,7 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
       payload = await enrichSingleRecord(payload, ctx)
       return json(payload, { status: 201 })
     } catch (e) {
-      return handleError(e)
+      return handleError(e, request)
     }
   }
 
@@ -2814,7 +2840,7 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
       }
       return json(payload)
     } catch (e) {
-      return handleError(e)
+      return handleError(e, request)
     }
   }
 
@@ -3103,7 +3129,7 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
       }
       return json(payload)
     } catch (e) {
-      return handleError(e)
+      return handleError(e, request)
     }
   }
 

package/src/lib/data/__tests__/engine.event-validation.test.ts

@@ -68,7 +68,15 @@ describe('DataEngine event contract validation (issue #1421)', () => {
       })
 
       expect(emitted).toEqual([
-        expect.objectContaining({ name: 'issue1421_test.widget.created' }),
+        expect.objectContaining({
+          name: 'issue1421_test.widget.created',
+          options: {
+            persistent: false,
+            tenantId: 'tenant-1',
+            organizationId: 'org-1',
+            emitterModuleId: 'issue1421_test',
+          },
+        }),
       ])
       expect(loggerWarn).not.toHaveBeenCalled()
     } finally {

package/src/lib/data/engine.ts

@@ -226,7 +226,12 @@ export class DefaultDataEngine implements DataEngine {
           const eventName = `${mod}.${ent}.updated`
           warnIfUndeclaredEvent(eventName, 'setCustomFields')
           try {
-            await bus.emitEvent(eventName, { id: recordId, organizationId, tenantId }, { persistent: true })
+            await bus.emitEvent(eventName, { id: recordId, organizationId, tenantId }, {
+              persistent: true,
+              tenantId,
+              organizationId,
+              emitterModuleId: mod,
+            })
           } catch {
             // non-blocking
           }
@@ -627,6 +632,7 @@ export class DefaultDataEngine implements DataEngine {
           persistent: !!events.persistent,
           tenantId: ctx.identifiers.tenantId ?? null,
           organizationId: ctx.identifiers.organizationId ?? null,
+          emitterModuleId: events.module,
         })
       } catch {
         // non-blocking

package/src/lib/html/__tests__/htmlToPlainText.test.ts

@@ -0,0 +1,59 @@
+import { htmlToPlainText } from '../htmlToPlainText'
+
+describe('htmlToPlainText', () => {
+  it('returns an empty string for empty input without invoking the parser', () => {
+    expect(htmlToPlainText('')).toBe('')
+  })
+
+  it('renders block-level markup as readable prose', () => {
+    const html = '<html><body><p>Hello,</p><p>second paragraph.</p></body></html>'
+
+    const text = htmlToPlainText(html)
+
+    expect(text).toContain('Hello,')
+    expect(text).toContain('second paragraph.')
+    expect(text).not.toContain('<p>')
+    expect(text).not.toContain('</body>')
+  })
+
+  it('drops script and style content instead of inlining it as text', () => {
+    // Email HTML routinely carries a <style> block and a tracking <script>.
+    // Rendering either as text is what made ingested bodies unreadable.
+    const html = [
+      '<!DOCTYPE html><html><head>',
+      '<style>body { margin: 0; font-family: Helvetica; }</style>',
+      '<script>trackOpen("beacon")</script>',
+      '</head><body><p>Visible copy</p></body></html>',
+    ].join('')
+
+    const text = htmlToPlainText(html)
+
+    expect(text).toBe('Visible copy')
+    expect(text).not.toContain('font-family')
+    expect(text).not.toContain('trackOpen')
+    expect(text).not.toContain('<!DOCTYPE')
+  })
+
+  it('normalizes CRLF and lone CR line endings to LF', () => {
+    const text = htmlToPlainText('<pre>first\r\nsecond\rthird</pre>')
+
+    expect(text).not.toContain('\r')
+    expect(text).toBe('first\nsecond\nthird')
+  })
+
+  it('collapses runs of three or more blank lines down to one', () => {
+    const text = htmlToPlainText('<pre>top\n\n\n\n\nbottom</pre>')
+
+    expect(text).toBe('top\n\nbottom')
+  })
+
+  it('preserves a single blank line between paragraphs', () => {
+    const text = htmlToPlainText('<pre>top\n\nbottom</pre>')
+
+    expect(text).toBe('top\n\nbottom')
+  })
+
+  it('trims surrounding whitespace', () => {
+    expect(htmlToPlainText('<pre>\n\n  padded  \n\n</pre>')).toBe('padded')
+  })
+})

package/src/lib/html/htmlToPlainText.ts

@@ -0,0 +1,17 @@
+import { convert } from 'html-to-text'
+
+export function htmlToPlainText(html: string): string {
+  if (!html) return ''
+  return convert(html, {
+    wordwrap: false,
+    preserveNewlines: true,
+    selectors: [
+      { selector: 'script', format: 'skip' },
+      { selector: 'style', format: 'skip' },
+    ],
+  })
+    .replace(/\r\n/g, '\n')
+    .replace(/\r/g, '\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim()
+}

package/src/lib/location/__tests__/countries.test.ts

@@ -2,6 +2,7 @@ import {
   COUNTRY_PRIORITY,
   ISO_COUNTRIES,
   buildCountryOptions,
+  matchCountryCodes,
   resolveCountryName,
 } from '../countries'
 
@@ -80,3 +81,17 @@ describe('buildCountryOptions', () => {
     expect(options).toEqual(expect.arrayContaining([{ code: 'XK', label: 'Kosovo (XK)' }]))
   })
 })
+
+describe('matchCountryCodes', () => {
+  it('maps English country names to ISO codes so list search can find stored PL rows', () => {
+    expect(matchCountryCodes('Poland')).toContain('PL')
+  })
+
+  it('maps localized names when extra locales are provided', () => {
+    expect(matchCountryCodes('Polska', { locales: ['pl'] })).toContain('PL')
+  })
+
+  it('returns nothing for blank search terms', () => {
+    expect(matchCountryCodes('   ')).toEqual([])
+  })
+})

package/src/lib/location/countries.ts

@@ -106,3 +106,20 @@ export function buildCountryOptions(options: {
 
   return [...prioritized, ...remaining]
 }
+
+export function matchCountryCodes(
+  term: string,
+  options: { locales?: string[] } = {},
+): string[] {
+  const needle = term.trim().toLowerCase()
+  if (!needle) return []
+  const searchLocales = options.locales?.length ? options.locales : ['en']
+  return ISO_COUNTRIES
+    .filter((entry) => {
+      if (entry.name.toLowerCase().includes(needle)) return true
+      return searchLocales.some((locale) =>
+        resolveCountryName(entry.code, { locale }).toLowerCase().includes(needle),
+      )
+    })
+    .map((entry) => entry.code)
+}

package/src/lib/openapi/crud.ts

@@ -17,6 +17,9 @@ export function createPagedListResponseSchema(itemSchema: ZodTypeAny, options: P
     page: paginationMetaOptional ? z.number().optional() : z.number(),
     pageSize: paginationMetaOptional ? z.number().optional() : z.number(),
     totalPages: z.number(),
+    // Present (true) only when the list count was bounded at OM_LIST_COUNT_CAP:
+    // `total` is then a floor, not an exact value.
+    totalIsCapped: z.boolean().optional(),
   })
 }