@open-mercato/shared 0.9.1-develop.7574.1.837288eec1 → 0.10.1-develop.7576.1.21d5b50435

package/src/lib/crud/__tests__/ids.test.ts

@@ -1,11 +1,4 @@
-import {
-  MAX_IDS_PER_REQUEST,
-  mergeIdFilter,
-  parseIdsParam,
-  isIdsParamProvided,
-  isUuidListParam,
-  splitIdListParam,
-} from '@open-mercato/shared/lib/crud/ids'
+import { MAX_IDS_PER_REQUEST, mergeIdFilter, parseIdsParam, isIdsParamProvided } from '@open-mercato/shared/lib/crud/ids'
 
 describe('crud ids helpers', () => {
   const idA = '550e8400-e29b-41d4-a716-446655440001'
@@ -175,30 +168,4 @@ describe('crud ids helpers', () => {
       tenantId: 't1',
     })
   })
-
-  it('splitIdListParam trims entries and drops empty ones', () => {
-    expect(splitIdListParam(` ${idA} ,, ${idB} ,`)).toEqual([idA, idB])
-    expect(splitIdListParam(undefined)).toEqual([])
-    expect(splitIdListParam(['not', 'a', 'string'])).toEqual([])
-  })
-
-  it('isUuidListParam accepts absent, empty, and all-UUID lists', () => {
-    expect(isUuidListParam(undefined)).toBe(true)
-    expect(isUuidListParam('')).toBe(true)
-    expect(isUuidListParam(` ${idA}, ${idB.toUpperCase()} `)).toBe(true)
-    expect(isUuidListParam('00000000-0000-0000-0000-000000000000')).toBe(true)
-  })
-
-  it('isUuidListParam rejects malformed and mixed lists', () => {
-    expect(isUuidListParam('not-a-uuid')).toBe(false)
-    expect(isUuidListParam(`${idA},not-a-uuid`)).toBe(false)
-    expect(isUuidListParam(`${idA}0`)).toBe(false)
-    expect(isUuidListParam(`{${idA}}`)).toBe(false)
-  })
-
-  it('isUuidListParam fails closed on non-string values', () => {
-    expect(isUuidListParam(['not-a-uuid'])).toBe(false)
-    expect(isUuidListParam([idA])).toBe(false)
-    expect(isUuidListParam(null)).toBe(false)
-  })
 })

package/src/lib/crud/exporters.ts

@@ -81,7 +81,7 @@ function escapeXmlValue(value: string): string {
 }
 
 function serializeCsv(prepared: PreparedExport): SerializedExport {
-  const headers = prepared.columns.map((col) => escapeCsv(neutralizeSpreadsheetFormula(col.header)))
+  const headers = prepared.columns.map((col) => col.header)
   const lines = [headers.join(',')]
   for (const row of prepared.rows) {
     const values = prepared.columns.map((col) => {

package/src/lib/crud/ids.ts

@@ -51,30 +51,6 @@ export function parseIdsParam(raw: unknown, maxIds: number = MAX_IDS_PER_REQUEST
   return parsed.slice(0, safeMax)
 }
 
-const UUID_SHAPE_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
-
-/**
- * Splits a comma-separated id list query param into its trimmed, non-empty entries.
- */
-export function splitIdListParam(raw: unknown): string[] {
-  if (typeof raw !== 'string') return []
-  return raw
-    .split(',')
-    .map((value) => value.trim())
-    .filter((value) => value.length > 0)
-}
-
-/**
- * Whether every entry of a comma-separated id list query param is UUID-shaped, so it can be
- * bound to a uuid column without a database error. Use it to reject a malformed or mixed list
- * with a 400 instead of dropping the bad entries and widening the result set (#7265).
- */
-export function isUuidListParam(raw: unknown): boolean {
-  if (raw === undefined) return true
-  if (typeof raw !== 'string') return false
-  return splitIdListParam(raw).every((value) => UUID_SHAPE_REGEX.test(value))
-}
-
 /**
  * Whether an `?ids=` param was supplied at all (a non-empty string, or repeated
  * `?ids=` occurrences), regardless of whether any value survived UUID

package/src/lib/db/__tests__/pg-errors.test.ts

@@ -1,11 +1,4 @@
-import {
-  getForeignKeyViolationConstraint,
-  isForeignKeyViolation,
-  isTransientDbError,
-  isTransientLockDbError,
-  isUniqueViolation,
-  readPgSqlState,
-} from '../pg-errors'
+import { getForeignKeyViolationConstraint, isForeignKeyViolation, isTransientDbError, isUniqueViolation, readPgSqlState } from '../pg-errors'
 
 describe('isTransientDbError', () => {
   it('is true for the max_connections SQLSTATE', () => {
@@ -54,66 +47,6 @@ describe('isTransientDbError', () => {
   })
 })
 
-describe('isTransientLockDbError', () => {
-  it('matches lock, statement and idle-in-transaction timeouts', () => {
-    for (const code of ['55P03', '57014', '25P03']) {
-      expect(isTransientLockDbError({ code })).toBe(true)
-    }
-  })
-
-  it('matches the pg-pool acquire timeout and the node-postgres not-queryable error', () => {
-    expect(isTransientLockDbError(new Error('timeout exceeded when trying to connect'))).toBe(true)
-    expect(isTransientLockDbError(new Error('Client has encountered a connection error and is not queryable'))).toBe(true)
-  })
-
-  it('matches everything isTransientDbError matches', () => {
-    for (const code of ['53300', '53400', '57P01', '57P02', '57P03', '08000', '08001', '08003', '08006']) {
-      expect(isTransientLockDbError({ code })).toBe(true)
-    }
-    expect(isTransientLockDbError(new Error('sorry, too many clients already'))).toBe(true)
-    expect(isTransientLockDbError(new Error('Connection terminated unexpectedly'))).toBe(true)
-  })
-
-  it('looks through cause and previous on every layer of the wrapper chain', () => {
-    expect(isTransientLockDbError({ message: 'wrapped', cause: { code: '55P03' } })).toBe(true)
-    expect(isTransientLockDbError({ message: 'wrapped', previous: { code: '57014' } })).toBe(true)
-    expect(isTransientLockDbError({ message: 'outer', cause: { message: 'inner', previous: { code: '25P03' } } })).toBe(true)
-    expect(isTransientLockDbError(new Error('commit failed', { cause: new Error('timeout exceeded when trying to connect') }))).toBe(true)
-    expect(
-      isTransientLockDbError({ message: 'wrapped', cause: new Error('Client has encountered a connection error and is not queryable') }),
-    ).toBe(true)
-    expect(isTransientLockDbError({ message: 'wrapped', previous: { code: '53300' } })).toBe(true)
-  })
-
-  it('is false for query-level conflicts, socket codes and non-DB errors', () => {
-    expect(isTransientLockDbError({ code: '23505' })).toBe(false)
-    expect(isTransientLockDbError({ code: '40P01' })).toBe(false)
-    expect(isTransientLockDbError({ code: '40001' })).toBe(false)
-    expect(isTransientLockDbError({ code: 'ECONNREFUSED' })).toBe(false)
-    expect(isTransientLockDbError(new Error('something unrelated broke'))).toBe(false)
-    expect(isTransientLockDbError(null)).toBe(false)
-    expect(isTransientLockDbError(undefined)).toBe(false)
-    expect(isTransientLockDbError('timeout exceeded when trying to connect')).toBe(false)
-  })
-
-  it('stops on cyclic or very deep wrapper chains', () => {
-    const cyclic: Record<string, unknown> = { message: 'loop' }
-    cyclic.cause = cyclic
-    expect(isTransientLockDbError(cyclic)).toBe(false)
-    const deep = { cause: { cause: { cause: { cause: { cause: { code: '55P03' } } } } } }
-    expect(isTransientLockDbError(deep)).toBe(false)
-  })
-
-  it('leaves isTransientDbError unchanged for the lock-only signals', () => {
-    for (const code of ['55P03', '57014', '25P03']) {
-      expect(isTransientDbError({ code })).toBe(false)
-    }
-    expect(isTransientDbError(new Error('timeout exceeded when trying to connect'))).toBe(false)
-    expect(isTransientDbError(new Error('Client has encountered a connection error and is not queryable'))).toBe(false)
-    expect(isTransientDbError({ message: 'wrapped', cause: { code: '53300' } })).toBe(false)
-  })
-})
-
 describe('isForeignKeyViolation', () => {
   it('is true for the foreign_key_violation SQLSTATE', () => {
     expect(isForeignKeyViolation({ code: '23503' })).toBe(true)

package/src/lib/db/pg-errors.ts

@@ -148,38 +148,3 @@ export function isTransientDbError(err: unknown): boolean {
   }
   return false
 }
-
-/**
- * SQLSTATEs that end a lock transaction early but say nothing about the data it
- * would have written, so the work can be retried: lock_not_available (55P03,
- * raised by `DB_LOCK_TIMEOUT_MS`), query_canceled (57014, raised by the opt-in
- * `DB_STATEMENT_TIMEOUT_MS`) and idle_in_transaction_session_timeout (25P03).
- */
-const TRANSIENT_LOCK_SQLSTATES = new Set(['55P03', '57014', '25P03'])
-
-/**
- * Driver messages for a connection that never arrived or was lost mid-transaction:
- * the pg-pool acquire timeout (`connectionTimeoutMillis`) and node-postgres's
- * error for a client whose connection already failed.
- */
-const TRANSIENT_LOCK_MESSAGE_PATTERNS = [
-  /timeout exceeded when trying to connect/i,
-  /client has encountered a connection error and is not queryable/i,
-]
-
-/**
- * @internal Detect a transient failure of a short lock transaction: everything
- * `isTransientDbError` matches, plus lock, statement and idle-in-transaction
- * timeouts, the pg-pool acquire timeout and node-postgres's "not queryable"
- * error. Checks every layer of the driver-error wrapper chain (`cause` /
- * `previous`, see `pgErrorCandidates`). `isTransientDbError` keeps its narrower
- * scope because its callers answer 503 "service unavailable".
- */
-export function isTransientLockDbError(err: unknown): boolean {
-  return pgErrorCandidates(err).some((candidate) => {
-    if (isTransientDbError(candidate)) return true
-    if (typeof candidate.code === 'string' && TRANSIENT_LOCK_SQLSTATES.has(candidate.code)) return true
-    const message = candidate.message
-    return typeof message === 'string' && TRANSIENT_LOCK_MESSAGE_PATTERNS.some((pattern) => pattern.test(message))
-  })
-}

package/src/lib/encryption/__tests__/tenantDataEncryptionService.test.ts

@@ -883,26 +883,3 @@ describe('TenantDataEncryptionService map read failures (issue #6334)', () => {
     expect(execute).toHaveBeenCalledTimes(2)
   })
 })
-
-describe('TenantDataEncryptionService transaction-aware map reads', () => {
-  it('prefers the EntityManager executor over the bare connection', async () => {
-    const entityId = 'test:transaction_aware_map_read'
-    const execute = jest.fn(async () => [{
-      entity_id: entityId,
-      fields_json: [{ field: 'display_name' }],
-    }])
-    const bareExecute = jest.fn(async () => {
-      throw new Error('bare connection must not be used')
-    })
-    const service = new TenantDataEncryptionService({
-      execute,
-      getConnection: () => ({ execute: bareExecute }),
-    } as never)
-    jest.spyOn(service, 'isEnabled').mockReturnValue(true)
-
-    await expect(service.getEncryptedFieldNames(entityId, 'tenant-transaction', 'org-transaction'))
-      .resolves.toEqual(['display_name'])
-    expect(execute).toHaveBeenCalled()
-    expect(bareExecute).not.toHaveBeenCalled()
-  })
-})

package/src/lib/localization/__tests__/translatable-fields.test.ts

@@ -2,8 +2,6 @@ import {
   registerTranslatableFields,
   getTranslatableFields,
   getTranslatableFieldsRegistry,
-  registerTranslatableFieldExpander,
-  getTranslatableFieldExpander,
 } from '../translatable-fields'
 
 // The registry is global mutable state — we snapshot before all tests
@@ -69,18 +67,3 @@ describe('translatable fields registry', () => {
     expect(getTranslatableFields('b:second')).toEqual(['f2'])
   })
 })
-
-describe('translatable field expander registry', () => {
-  it('returns undefined for an entity type without an expander', () => {
-    expect(getTranslatableFieldExpander('expander_test:none')).toBeUndefined()
-  })
-
-  it('returns the registered expander and keeps earlier registrations', () => {
-    const first = jest.fn(() => [{ key: 'a.b' }])
-    const second = jest.fn(() => [])
-    registerTranslatableFieldExpander('expander_test:first', first)
-    registerTranslatableFieldExpander('expander_test:second', second)
-    expect(getTranslatableFieldExpander('expander_test:first')).toBe(first)
-    expect(getTranslatableFieldExpander('expander_test:second')).toBe(second)
-  })
-})

package/src/lib/localization/index.ts

@@ -1,12 +1,5 @@
 export type { TranslationRecord, LocaleCode } from './types'
 export { applyLocalizedContent } from './resolver'
-export {
-  registerTranslatableFields,
-  getTranslatableFields,
-  getTranslatableFieldsRegistry,
-  registerTranslatableFieldExpander,
-  getTranslatableFieldExpander,
-} from './translatable-fields'
-export type { TranslatableFieldExpansion, TranslatableFieldExpander } from './translatable-fields'
+export { registerTranslatableFields, getTranslatableFields, getTranslatableFieldsRegistry } from './translatable-fields'
 export { registerTranslationOverlayPlugin, getTranslationOverlayPlugin } from './overlay-plugin'
 export type { TranslationOverlayFn, ResolveLocaleFromRequestFn } from './overlay-plugin'

package/src/lib/localization/translatable-fields.ts

@@ -23,49 +23,3 @@ export function getTranslatableFields(entityType: string): string[] | undefined
 export function getTranslatableFieldsRegistry(): TranslatableFieldsRegistry {
   return { ...getGlobal() }
 }
-
-export type TranslatableFieldExpansion = {
-  key: string
-  label?: string
-  baseValue?: string
-}
-
-export type TranslatableFieldExpander = (record: Record<string, unknown>) => TranslatableFieldExpansion[]
-
-type TranslatableFieldExpanderRegistry = Record<string, TranslatableFieldExpander>
-
-const EXPANDER_GLOBAL_KEY = '__openMercatoTranslatableFieldExpanders__'
-
-type ExpanderGlobalHost = { [EXPANDER_GLOBAL_KEY]?: TranslatableFieldExpanderRegistry }
-
-function getExpanderGlobal(): TranslatableFieldExpanderRegistry {
-  return (globalThis as ExpanderGlobalHost)[EXPANDER_GLOBAL_KEY] ?? {}
-}
-
-export function registerTranslatableFieldExpander(entityType: string, expander: TranslatableFieldExpander): void {
-  const host = globalThis as ExpanderGlobalHost
-  host[EXPANDER_GLOBAL_KEY] = { ...getExpanderGlobal(), [entityType]: expander }
-}
-
-export function getTranslatableFieldExpander(entityType: string): TranslatableFieldExpander | undefined {
-  return getExpanderGlobal()[entityType]
-}
-
-type TranslatableEntityListPathRegistry = Record<string, string>
-
-const LIST_PATH_GLOBAL_KEY = '__openMercatoTranslatableEntityListPaths__'
-
-type ListPathGlobalHost = { [LIST_PATH_GLOBAL_KEY]?: TranslatableEntityListPathRegistry }
-
-function getListPathGlobal(): TranslatableEntityListPathRegistry {
-  return (globalThis as ListPathGlobalHost)[LIST_PATH_GLOBAL_KEY] ?? {}
-}
-
-export function registerTranslatableEntityListPath(entityType: string, listPath: string): void {
-  const host = globalThis as ListPathGlobalHost
-  host[LIST_PATH_GLOBAL_KEY] = { ...getListPathGlobal(), [entityType]: listPath }
-}
-
-export function getTranslatableEntityListPath(entityType: string): string | undefined {
-  return getListPathGlobal()[entityType]
-}

package/src/lib/number.ts

@@ -101,19 +101,6 @@ export function parseLocaleNumber(input: string | null | undefined, locale?: str
   return Number.isFinite(parsed) ? parsed : null
 }
 
-/**
- * Renders a number as the text an input field should show under `locale` — `2,5` under
- * `pl-PL`, `2.5` under `en-US`. Unlike `String()`, which always emits a dot, the result uses
- * the locale's decimal separator, so a value redisplayed after blur or reload matches what the
- * user typed and what the rest of the UI shows. No grouping is applied, and the output always
- * round-trips through `parseLocaleNumber`.
- */
-export function formatLocaleNumberInput(value: number, locale?: string): string {
-  const serialized = String(value)
-  const { decimal } = resolveLocaleNumberSeparators(locale)
-  return decimal === '.' ? serialized : serialized.replace('.', decimal)
-}
-
 export function parseNumberWithDefault(
   raw: string | null | undefined,
   fallback: number,

package/src/lib/openapi/generator.ts

@@ -15,12 +15,6 @@ type PathParamInfo = {
   optional?: boolean
 }
 
-type PathVariant = {
-  path: string
-  params: PathParamInfo[]
-  omittedParam?: string
-}
-
 type ParameterLocation = 'query' | 'path' | 'header'
 
 export type JsonSchema = Record<string, unknown>
@@ -125,20 +119,6 @@ function normalizePath(path: string): { path: string; params: PathParamInfo[] }
   return { path: '/' + normalized, params }
 }
 
-function expandOptionalPathParams(normalized: { path: string; params: PathParamInfo[] }): PathVariant[] {
-  const required = normalized.params.filter((param) => !param.optional)
-  const optionalParam = normalized.params.find((param) => param.optional)
-  const fullVariant: PathVariant = {
-    path: normalized.path,
-    params: normalized.params.map((param) => ({ ...param, optional: false })),
-  }
-  if (!optionalParam) return [fullVariant]
-  const placeholder = `/{${optionalParam.name}}`
-  if (!normalized.path.endsWith(placeholder)) return [fullVariant]
-  const basePath = normalized.path.slice(0, -placeholder.length) || '/'
-  return [fullVariant, { path: basePath, params: required, omittedParam: optionalParam.name }]
-}
-
 function unwrap(schema?: ZodTypeAny): {
   schema: ZodTypeAny | undefined
   optional: boolean
@@ -701,14 +681,14 @@ function buildParameters(
 
   if (location === 'path' && pathParamNames && pathParamNames.length) {
     const merged = mergePathParamSchemas(schema, pathParamNames)
-    for (const { name, schema: paramSchema } of merged) {
+    for (const { name, schema: paramSchema, optional } of merged) {
       const jsonSchema = zodToJsonSchema(paramSchema)
       const example = generateExample(paramSchema)
       const description = extractZodDescription(paramSchema)
       params.push({
         name,
         in: 'path',
-        required: true,
+        required: !optional,
         schema: jsonSchema ?? { type: 'string' },
         example,
         ...(description ? { description } : {}),
@@ -758,7 +738,7 @@ function buildParameters(
 }
 
 function mergePathParamSchemas(schema: ZodTypeAny | undefined, params: PathParamInfo[]) {
-  const merged: Array<{ name: string; schema: ZodTypeAny | undefined }> = []
+  const merged: Array<{ name: string; schema: ZodTypeAny | undefined; optional: boolean }> = []
   const map: Record<string, ZodTypeAny> = {}
   if (schema) {
     const { schema: unwrapped } = unwrap(schema)
@@ -773,6 +753,7 @@ function mergePathParamSchemas(schema: ZodTypeAny | undefined, params: PathParam
     merged.push({
       name: param.name,
       schema: map[param.name],
+      optional: !!param.optional,
     })
   }
   return merged
@@ -1070,7 +1051,6 @@ export function buildOpenApiDocument(modules: Module[], options: OpenApiDocument
 
   const includeAccessControlMetadata = options.includeAccessControlMetadata !== false
   const tags = new Map<string, string | undefined>()
-  const derivedOperations = new Set<string>()
 
   for (const moduleEntry of modules) {
     const defaultTag = moduleEntry.info?.title ?? toTitle(moduleEntry.id)
@@ -1080,94 +1060,85 @@ export function buildOpenApiDocument(modules: Module[], options: OpenApiDocument
     for (const api of apis) {
       const routeDoc = collectRouteDoc(api, moduleEntry.id)
       const moduleTag = routeDoc?.tag ?? defaultTag
+      const normalized = normalizePath((api as any).path ?? (api as any).path ?? '')
+      const pathKey = normalized.path
+      if (!doc.paths[pathKey]) doc.paths[pathKey] = {}
       const availableMethods: HttpMethod[] =
         'handlers' in api
           ? HTTP_METHODS.filter((method) => typeof (api as ModuleApiRouteFile).handlers?.[method] === 'function')
           : [api.method as HttpMethod]
 
-      for (const normalized of expandOptionalPathParams(normalizePath((api as any).path ?? ''))) {
-        const pathKey = normalized.path
-        if (!doc.paths[pathKey]) doc.paths[pathKey] = {}
-
-        for (const method of availableMethods) {
-          const methodLower = method.toLowerCase() as Lowercase<HttpMethod>
-          const operationKey = `${methodLower} ${pathKey}`
-          const existing = doc.paths[pathKey][methodLower]
-          if (existing && (normalized.omittedParam || !derivedOperations.has(operationKey))) continue
-          if (normalized.omittedParam) derivedOperations.add(operationKey)
-          else derivedOperations.delete(operationKey)
-
-          const metadata = 'handlers' in api ? (api as ModuleApiRouteFile).metadata?.[method] : undefined
-          const methodDoc = routeDoc?.methods?.[method]
-          const summary = methodDoc?.summary ?? routeDoc?.summary ?? `${method} ${pathKey}`
-          const baseDescription = methodDoc?.description ?? routeDoc?.description
-          const meta = metadata && typeof metadata === 'object' ? (metadata as Record<string, unknown>) : undefined
-          const requireFeatures = Array.isArray(meta?.['requireFeatures'])
-            ? (meta!['requireFeatures'] as string[])
-            : undefined
-          const requireRoles = Array.isArray(meta?.['requireRoles'])
-            ? (meta!['requireRoles'] as string[])
-            : undefined
-          const requireAuth = meta?.['requireAuth'] === true
-          const descriptionParts: string[] = []
-          if (baseDescription) descriptionParts.push(baseDescription)
-          if (includeAccessControlMetadata && Array.isArray(requireFeatures) && requireFeatures.length) {
-            descriptionParts.push(`Requires features: ${requireFeatures.join(', ')}`)
-          }
-          if (includeAccessControlMetadata && Array.isArray(requireRoles) && requireRoles.length) {
-            descriptionParts.push(`Requires roles: ${requireRoles.join(', ')}`)
-          }
+      for (const method of availableMethods) {
+        const methodLower = method.toLowerCase() as Lowercase<HttpMethod>
+        const existing = doc.paths[pathKey][methodLower]
+        if (existing) continue
+
+        const metadata = 'handlers' in api ? (api as ModuleApiRouteFile).metadata?.[method] : undefined
+        const methodDoc = routeDoc?.methods?.[method]
+        const summary = methodDoc?.summary ?? routeDoc?.summary ?? `${method} ${pathKey}`
+        const baseDescription = methodDoc?.description ?? routeDoc?.description
+        const meta = metadata && typeof metadata === 'object' ? (metadata as Record<string, unknown>) : undefined
+        const requireFeatures = Array.isArray(meta?.['requireFeatures'])
+          ? (meta!['requireFeatures'] as string[])
+          : undefined
+        const requireRoles = Array.isArray(meta?.['requireRoles'])
+          ? (meta!['requireRoles'] as string[])
+          : undefined
+        const requireAuth = meta?.['requireAuth'] === true
+        const descriptionParts: string[] = []
+        if (baseDescription) descriptionParts.push(baseDescription)
+        if (includeAccessControlMetadata && Array.isArray(requireFeatures) && requireFeatures.length) {
+          descriptionParts.push(`Requires features: ${requireFeatures.join(', ')}`)
+        }
+        if (includeAccessControlMetadata && Array.isArray(requireRoles) && requireRoles.length) {
+          descriptionParts.push(`Requires roles: ${requireRoles.join(', ')}`)
+        }
 
-          const querySchema = methodDoc?.query
-          const pathSchema = methodDoc?.pathParams ?? routeDoc?.pathParams
-          const headerSchema = methodDoc?.headers
-          const requestBody = methodDoc?.requestBody
-          const examples = collectExamples(querySchema, requestBody?.schema, pathSchema, headerSchema, metadata)
-          const curlSample = buildCurlSample(
-            method,
-            pathKey,
-            normalized.params,
-            examples,
-            options.baseUrlForExamples ?? 'https://api.open-mercato.local',
-            metadata,
-            requestBody
-          )
-
-          doc.paths[pathKey][methodLower] = {
-            operationId: methodDoc?.operationId
-              ? normalized.omittedParam
-                ? `${methodDoc.operationId}_without_${normalizeOperationIdSegment(normalized.omittedParam)}`
-                : methodDoc.operationId
-              : resolveOperationId(moduleEntry.id, pathKey, method),
-            summary,
-            description: descriptionParts.length ? descriptionParts.join('\n\n') : undefined,
-            tags: methodDoc?.tags ?? (moduleTag ? [moduleTag] : undefined),
-            deprecated: methodDoc?.deprecated,
-            externalDocs: methodDoc?.externalDocs,
-            parameters: [
-              ...buildParameters(pathSchema, 'path', normalized.params),
-              ...buildParameters(querySchema, 'query'),
-              ...buildParameters(headerSchema, 'header'),
-            ].filter(Boolean),
-            requestBody: buildRequestBody(requestBody),
-            responses: buildResponses(method, methodDoc?.responses, methodDoc?.errors, metadata),
-            security: buildSecurity(metadata, methodDoc, options.defaultSecurity),
-            'x-codeSamples': methodDoc?.codeSamples ?? [
-              {
-                lang: 'curl',
-                label: 'cURL',
-                source: curlSample,
-              },
-            ],
-            ...(includeAccessControlMetadata && Array.isArray(requireFeatures) && requireFeatures.length
-              ? { 'x-require-features': requireFeatures }
-              : {}),
-            ...(includeAccessControlMetadata && Array.isArray(requireRoles) && requireRoles.length
-              ? { 'x-require-roles': requireRoles }
-              : {}),
-            ...(requireAuth ? { 'x-require-auth': true } : {}),
-            ...(methodDoc?.extensions ?? {}),
-          }
+        const querySchema = methodDoc?.query
+        const pathSchema = methodDoc?.pathParams ?? routeDoc?.pathParams
+        const headerSchema = methodDoc?.headers
+        const requestBody = methodDoc?.requestBody
+        const examples = collectExamples(querySchema, requestBody?.schema, pathSchema, headerSchema, metadata)
+        const curlSample = buildCurlSample(
+          method,
+          pathKey,
+          normalized.params,
+          examples,
+          options.baseUrlForExamples ?? 'https://api.open-mercato.local',
+          metadata,
+          requestBody
+        )
+
+        doc.paths[pathKey][methodLower] = {
+          operationId: methodDoc?.operationId ?? resolveOperationId(moduleEntry.id, pathKey, method),
+          summary,
+          description: descriptionParts.length ? descriptionParts.join('\n\n') : undefined,
+          tags: methodDoc?.tags ?? (moduleTag ? [moduleTag] : undefined),
+          deprecated: methodDoc?.deprecated,
+          externalDocs: methodDoc?.externalDocs,
+          parameters: [
+            ...buildParameters(pathSchema, 'path', normalized.params),
+            ...buildParameters(querySchema, 'query'),
+            ...buildParameters(headerSchema, 'header'),
+          ].filter(Boolean),
+          requestBody: buildRequestBody(requestBody),
+          responses: buildResponses(method, methodDoc?.responses, methodDoc?.errors, metadata),
+          security: buildSecurity(metadata, methodDoc, options.defaultSecurity),
+          'x-codeSamples': methodDoc?.codeSamples ?? [
+            {
+              lang: 'curl',
+              label: 'cURL',
+              source: curlSample,
+            },
+          ],
+          ...(includeAccessControlMetadata && Array.isArray(requireFeatures) && requireFeatures.length
+            ? { 'x-require-features': requireFeatures }
+            : {}),
+          ...(includeAccessControlMetadata && Array.isArray(requireRoles) && requireRoles.length
+            ? { 'x-require-roles': requireRoles }
+            : {}),
+          ...(requireAuth ? { 'x-require-auth': true } : {}),
+          ...(methodDoc?.extensions ?? {}),
         }
       }
     }