@open-mercato/shared 0.10.1-develop.7576.1.21d5b50435 → 0.10.1-develop.7577.1.477f2486e5

package/src/lib/query/engine.ts

@@ -38,6 +38,13 @@ import { resolveListCountCap } from './count-cap'
 import { mapWithConcurrency } from './bounded-decrypt'
 import { parseNumberWithDefault } from '../number'
 import { createLogger } from '../logger'
+import {
+  buildArrayColumnNoOverlapPredicate,
+  buildArrayColumnOverlapPredicate,
+  buildJsonbNoOverlapPredicate,
+  buildJsonbOverlapPredicate,
+  buildScalarOverlapPredicate,
+} from './overlap'
 
 const logger = createLogger('shared').child({ component: 'query' })
 
@@ -1216,7 +1223,11 @@ export class BasicQueryEngine implements QueryEngine {
           })
           continue
         }
-        q = this.applyColumnOp(q, expr, f.op, f.value)
+        q = f.op === 'overlap'
+          ? q.where(buildScalarOverlapPredicate(expr, f.value))
+          : f.op === 'noverlap'
+            ? q.where(sql<boolean>`false`)
+            : this.applyColumnOp(q, expr, f.op, f.value)
       }
 
       // OR groups are applied here, after the cf:* value expressions exist, so a
@@ -1263,7 +1274,10 @@ export class BasicQueryEngine implements QueryEngine {
                     value: rf.value,
                   })
                 }
-                return this.buildColumnOpExpression(eb, cfValueExprByKey[rf.key], rf.op, rf.value)
+                if (rf.op === 'noverlap') return sql<boolean>`false`
+                return rf.op === 'overlap'
+                  ? buildScalarOverlapPredicate(cfValueExprByKey[rf.key], rf.value)
+                  : this.buildColumnOpExpression(eb, cfValueExprByKey[rf.key], rf.op, rf.value)
               }
               return this.buildIndexDocOpExpression(eb, {
                 entity: String(entity),
@@ -1589,10 +1603,22 @@ export class BasicQueryEngine implements QueryEngine {
         return builder.where(column as any, '<', value as any)
       case 'lte':
         return builder.where(column as any, '<=', value as any)
-      case 'in':
-        return builder.where(column as any, 'in', Array.isArray(value) ? value : [value])
-      case 'nin':
-        return builder.where(column as any, 'not in', Array.isArray(value) ? value : [value])
+      case 'in': {
+        // An empty list ("no id survived validation", #7502) compiles to invalid
+        // SQL (`in ()`) under Kysely/Postgres — short-circuit to a predicate that
+        // never matches instead of letting the driver reject the query.
+        const inValues = Array.isArray(value) ? value : [value]
+        return inValues.length === 0
+          ? builder.where(sql<boolean>`false`)
+          : builder.where(column as any, 'in', inValues)
+      }
+      case 'nin': {
+        // Mirrors 'in' above: empty means "exclude nothing".
+        const ninValues = Array.isArray(value) ? value : [value]
+        return ninValues.length === 0
+          ? builder.where(sql<boolean>`true`)
+          : builder.where(column as any, 'not in', ninValues)
+      }
       case 'like':
         return builder.where(column as any, 'like', value as any)
       case 'ilike':
@@ -1601,6 +1627,10 @@ export class BasicQueryEngine implements QueryEngine {
         return value
           ? builder.where(column as any, 'is not', null)
           : builder.where(column as any, 'is', null)
+      case 'overlap':
+        return builder.where(buildArrayColumnOverlapPredicate(column, value))
+      case 'noverlap':
+        return builder.where(buildArrayColumnNoOverlapPredicate(column, value))
       default:
         return builder
     }
@@ -1734,6 +1764,11 @@ export class BasicQueryEngine implements QueryEngine {
       case 'exists':
         predicate = sql<boolean>`${caseExpr} is not null`
         break
+      case 'overlap':
+        predicate = buildScalarOverlapPredicate(caseExpr, value)
+        break
+      case 'noverlap':
+        return sql<boolean>`false`
       default:
         // Mirrors buildColumnOpExpression's unknown-op fallback: a neutral
         // predicate, so full and count shapes drop the same leaves.
@@ -1751,11 +1786,20 @@ export class BasicQueryEngine implements QueryEngine {
       case 'gte': return eb(column, '>=', value)
       case 'lt': return eb(column, '<', value)
       case 'lte': return eb(column, '<=', value)
-      case 'in': return eb(column, 'in', Array.isArray(value) ? value : [value])
-      case 'nin': return eb(column, 'not in', Array.isArray(value) ? value : [value])
+      case 'in': {
+        // Mirrors the guard in applyColumnOp above (#7502).
+        const inValues = Array.isArray(value) ? value : [value]
+        return inValues.length === 0 ? eb.val(false) : eb(column, 'in', inValues)
+      }
+      case 'nin': {
+        const ninValues = Array.isArray(value) ? value : [value]
+        return ninValues.length === 0 ? eb.val(true) : eb(column, 'not in', ninValues)
+      }
       case 'like': return eb(column, 'like', value)
       case 'ilike': return eb(column, 'ilike', value)
       case 'exists': return value ? eb(column, 'is not', null) : eb(column, 'is', null)
+      case 'overlap': return buildArrayColumnOverlapPredicate(column, value)
+      case 'noverlap': return buildArrayColumnNoOverlapPredicate(column, value)
       default: return eb.val(true)
     }
   }
@@ -1973,6 +2017,12 @@ export class BasicQueryEngine implements QueryEngine {
             ? sub.where(sql<boolean>`${textExpr} is not null`)
             : sub.where(sql<boolean>`${textExpr} is null`)
           break
+        case 'overlap':
+          sub = sub.where(buildJsonbOverlapPredicate(`${alias}.doc`, opts.field, opts.value))
+          break
+        case 'noverlap':
+          sub = sub.where(buildJsonbNoOverlapPredicate(`${alias}.doc`, opts.field, opts.value))
+          break
         default:
           break
       }

package/src/lib/query/join-utils.ts

@@ -7,7 +7,7 @@ type AnyBuilder = any
 
 export type NormalizedFilter = { field: string; op: FilterOp; value?: unknown; orGroup?: string; qualified?: string | null }
 
-const VALID_OPS = ['eq', 'ne', 'gt', 'gte', 'lt', 'lte', 'in', 'nin', 'like', 'ilike', 'exists'] as const
+const VALID_OPS = ['eq', 'ne', 'gt', 'gte', 'lt', 'lte', 'in', 'nin', 'like', 'ilike', 'exists', 'overlap', 'noverlap'] as const
 
 const normalizeField = (key: string) => (key.startsWith('cf_') ? `cf:${key.slice(3)}` : key)
 

package/src/lib/query/overlap.ts

@@ -0,0 +1,106 @@
+import { sql, type RawBuilder } from 'kysely'
+
+const LITERAL_SAFE_DOC_KEY = /^[A-Za-z0-9_:.-]{1,128}$/
+
+/**
+ * Normalizes the right-hand side of an `overlap` filter into a de-duplicated list of strings.
+ *
+ * `null`/`undefined` entries are dropped; a scalar is treated as a one-element list. An empty
+ * result means the filter matches nothing — every `overlap` builder compiles it to `false`
+ * rather than dropping the predicate, so a caller that computes an empty inclusion set can
+ * never widen a query by accident.
+ */
+export function normalizeOverlapValues(value: unknown): string[] {
+  const list: readonly unknown[] = Array.isArray(value)
+    ? value
+    : value === undefined || value === null
+      ? []
+      : [value]
+  const out: string[] = []
+  const seen = new Set<string>()
+  for (const entry of list) {
+    if (entry === undefined || entry === null) continue
+    const normalized = String(entry)
+    if (seen.has(normalized)) continue
+    seen.add(normalized)
+    out.push(normalized)
+  }
+  return out
+}
+
+/**
+ * `(<docColumn> -> '<key>')` — the jsonb sub-document of an index document.
+ *
+ * The key is emitted as an escaped SQL literal when it is a plain identifier so the expression is
+ * textually identical to a GIN expression index such as `((doc -> 'scope_keys'))` and the planner
+ * can match it. Any other key falls back to a bound parameter (still correct, just not indexable).
+ */
+export function jsonbDocKeyExpression(docColumnRef: string, key: string): RawBuilder<unknown> {
+  const keyExpr = LITERAL_SAFE_DOC_KEY.test(key) ? sql.lit(key) : sql`${key}`
+  return sql`(${sql.ref(docColumnRef)} -> ${keyExpr})`
+}
+
+/**
+ * jsonb "has any of" over a string-array key of an index document:
+ * `(<docColumn> -> '<key>') ?| $n::text[]`. The values are bound as one array parameter.
+ * A missing key or a JSON `null` evaluates to SQL NULL, i.e. the row does not match.
+ */
+export function buildJsonbOverlapPredicate(docColumnRef: string, key: string, value: unknown): RawBuilder<boolean> {
+  const values = normalizeOverlapValues(value)
+  if (!values.length) return sql<boolean>`false`
+  return sql<boolean>`${jsonbDocKeyExpression(docColumnRef, key)} ?| ${values}::text[]`
+}
+
+/**
+ * jsonb "has none of" over a string-array key of an index document (`noverlap`):
+ * `(jsonb_typeof(<expr>) = 'array' and not (<expr> ?| $n::text[]))`.
+ *
+ * Only a document whose key holds a JSON array can match: a missing key, a JSON `null` or a
+ * scalar never satisfies it, so an unindexed document can never slip through an exclusion.
+ * An empty value list excludes nothing (only the array check remains).
+ */
+export function buildJsonbNoOverlapPredicate(docColumnRef: string, key: string, value: unknown): RawBuilder<boolean> {
+  const values = normalizeOverlapValues(value)
+  const keyExpr = jsonbDocKeyExpression(docColumnRef, key)
+  const isArray = sql<boolean>`jsonb_typeof(${keyExpr}) = 'array'`
+  if (!values.length) return isArray
+  return sql<boolean>`(${isArray} and not (${keyExpr} ?| ${values}::text[]))`
+}
+
+/**
+ * Postgres array overlap for array-typed columns: `<column> && $n`. The bound array takes its
+ * element type from the column, so `text[]`, `varchar[]` and `uuid[]` columns all work.
+ */
+export function buildArrayColumnOverlapPredicate(
+  column: string | RawBuilder<unknown>,
+  value: unknown,
+): RawBuilder<boolean> {
+  const values = normalizeOverlapValues(value)
+  if (!values.length) return sql<boolean>`false`
+  const columnExpr = typeof column === 'string' ? sql.ref(column) : column
+  return sql<boolean>`${columnExpr} && ${values}`
+}
+
+/**
+ * Postgres array "has none of" for array-typed columns (`noverlap`): `not (<column> && $n)`.
+ * A NULL column never matches; an empty value list excludes nothing (`<column> is not null`).
+ */
+export function buildArrayColumnNoOverlapPredicate(
+  column: string | RawBuilder<unknown>,
+  value: unknown,
+): RawBuilder<boolean> {
+  const values = normalizeOverlapValues(value)
+  const columnExpr = typeof column === 'string' ? sql.ref(column) : column
+  if (!values.length) return sql<boolean>`${columnExpr} is not null`
+  return sql<boolean>`not (${columnExpr} && ${values})`
+}
+
+/**
+ * `overlap` over a scalar expression evaluated once per stored value (custom-field value rows):
+ * the record matches when any of its values is one of the requested ones — `<expr> in (...)`.
+ */
+export function buildScalarOverlapPredicate(expression: RawBuilder<unknown>, value: unknown): RawBuilder<boolean> {
+  const values = normalizeOverlapValues(value)
+  if (!values.length) return sql<boolean>`false`
+  return sql<boolean>`${expression} in (${sql.join(values.map((entry) => sql`${entry}`), sql`, `)})`
+}

package/src/lib/query/types.ts

@@ -2,7 +2,17 @@ import type { EntityId } from '@open-mercato/shared/modules/entities'
 import type { Profiler } from '../profiler'
 import type { ResolvedCustomFieldDefinitions } from '../crud/custom-field-definition-index'
 
-export type FilterOp = 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'nin' | 'like' | 'ilike' | 'exists'
+/**
+ * `overlap` (additive, 2026-10-05): "has any of" over a multi-valued field. An index-document
+ * string array compiles to jsonb `?|`, a `cf:*` key to any-value-in-set, and an array-typed base
+ * column to `&&`. An empty value list matches nothing.
+ *
+ * `noverlap` (additive, 2026-10-05): "has none of" — the negation of `overlap` on an index-document
+ * string array or an array-typed base column. Only a present array can match (a missing/null key or
+ * NULL column never does); an empty value list excludes nothing. Unsupported on `cf:*` keys, where
+ * it compiles to `false`.
+ */
+export type FilterOp = 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'nin' | 'like' | 'ilike' | 'exists' | 'overlap' | 'noverlap'
 
 export enum SortDir {
   Asc = 'asc',
@@ -34,6 +44,8 @@ export type WhereOps<T> = {
   $like?: T extends string ? string : never
   $ilike?: T extends string ? string : never
   $exists?: boolean
+  $overlap?: T extends readonly (infer Element)[] ? Element[] : T[]
+  $noverlap?: T extends readonly (infer Element)[] ? Element[] : T[]
 }
 
 // A field filter can be a direct value (equals) or ops object

package/src/lib/url.ts

@@ -267,6 +267,36 @@ export function toSecurityEmailUrl(input: RequestInput, path: string, env: EnvLi
   return `${base}/${path.replace(/^\/+/, '')}`
 }
 
+export function isCrossSiteBrowserRequest(req: Request, env: EnvLike = process.env): boolean {
+  const rawFetchSite = req.headers.get('sec-fetch-site')
+  const fetchSite = rawFetchSite?.trim().toLowerCase() ?? null
+  if (fetchSite === 'cross-site') return true
+  if (fetchSite === 'same-origin' || fetchSite === 'none') return false
+
+  const rawOrigin = req.headers.get('origin')
+  if (rawOrigin === null) return rawFetchSite !== null
+  const origin = normalizeOrigin(rawOrigin)
+  if (!origin) return true
+
+  const allowedOrigins = readAllowedOrigins(env)
+  if (allowedOrigins.has(origin)) return false
+  if (shouldAllowLoopbackOrigin(origin, allowedOrigins, env)) return false
+
+  const forwardedProto = readFirstHeaderValue(req.headers.get('x-forwarded-proto'))
+  const protocol = forwardedProto
+    ? (forwardedProto.endsWith(':') ? forwardedProto : `${forwardedProto}:`)
+    : new URL(origin).protocol
+  const host = req.headers.get('host')
+  const forwardedHost = req.headers.get('x-forwarded-host')
+  if (originFromHost(protocol, forwardedHost) === origin) return false
+  if (originFromHost(protocol, host) === origin) return false
+
+  if (env.NODE_ENV !== 'test') {
+    logger.warn('Cross-site request rejected', { origin, host, forwardedHost })
+  }
+  return true
+}
+
 export function mapSecurityEmailUrlError(
   error: unknown,
   mapping: SecurityEmailUrlErrorMapping,

package/src/lib/webhooks/__tests__/body.test.ts

@@ -2,6 +2,7 @@
 import {
   DEFAULT_WEBHOOK_BODY_LIMIT_BYTES,
   readBoundedRequestBody,
+  readBoundedRequestBytes,
   resolveWebhookBodyLimitBytes,
   WebhookBodyTooLargeError,
 } from '../body'
@@ -77,6 +78,53 @@ describe('readBoundedRequestBody', () => {
   })
 })
 
+describe('readBoundedRequestBytes', () => {
+  it('preserves exact bytes including invalid UTF-8', async () => {
+    const bytes = new Uint8Array([0xff, 0xfe, 0x41, 0xc3, 0x28])
+    const { request } = makeStreamingRequest([bytes.slice(0, 2), bytes.slice(2)])
+
+    const result = await readBoundedRequestBytes(request, { maxBytes: bytes.byteLength })
+
+    expect(Array.from(result)).toEqual(Array.from(bytes))
+    expect(new TextDecoder().decode(result)).toContain('\uFFFD')
+  })
+
+  it('returns an empty array for a missing body', async () => {
+    const request = new Request('http://localhost/webhook', { method: 'POST' })
+
+    expect((await readBoundedRequestBytes(request)).byteLength).toBe(0)
+    await expect(readBoundedRequestBody(request)).resolves.toBe('')
+  })
+
+  it('enforces the declared and streamed limits and cancels the stream', async () => {
+    const declared = new Request('http://localhost/webhook', {
+      method: 'POST',
+      headers: { 'content-length': '6' },
+      body: 'ok',
+    })
+    await expect(readBoundedRequestBytes(declared, { maxBytes: 5 })).rejects.toBeInstanceOf(
+      WebhookBodyTooLargeError,
+    )
+
+    const { request, cancel } = makeStreamingRequest([
+      new Uint8Array([1, 2, 3]),
+      new Uint8Array([4, 5, 6]),
+      new Uint8Array([7, 8, 9]),
+    ])
+    await expect(readBoundedRequestBytes(request, { maxBytes: 5 })).rejects.toBeInstanceOf(
+      WebhookBodyTooLargeError,
+    )
+    expect(cancel).toHaveBeenCalled()
+  })
+
+  it('keeps the string reader decoding the same bytes', async () => {
+    const bytes = new TextEncoder().encode('zażółć')
+    const { request } = makeStreamingRequest([bytes])
+
+    await expect(readBoundedRequestBody(request)).resolves.toBe('zażółć')
+  })
+})
+
 describe('resolveWebhookBodyLimitBytes', () => {
   it('uses the documented default for missing or invalid configuration', () => {
     expect(resolveWebhookBodyLimitBytes(undefined)).toBe(DEFAULT_WEBHOOK_BODY_LIMIT_BYTES)

package/src/lib/webhooks/body.ts

@@ -23,10 +23,10 @@ export function resolveWebhookBodyLimitBytes(
   return Number.isSafeInteger(parsed) ? parsed : fallback
 }
 
-export async function readBoundedRequestBody(
+export async function readBoundedRequestBytes(
   request: Request,
   options?: { maxBytes?: number },
-): Promise<string> {
+): Promise<Uint8Array> {
   const configuredLimit = options?.maxBytes ?? resolveWebhookBodyLimitBytes()
   const maxBytes = Number.isSafeInteger(configuredLimit) && configuredLimit > 0
     ? configuredLimit
@@ -39,7 +39,7 @@ export async function readBoundedRequestBody(
     }
   }
 
-  if (!request.body) return ''
+  if (!request.body) return new Uint8Array(0)
 
   const reader = request.body.getReader()
   const chunks: Uint8Array[] = []
@@ -66,5 +66,12 @@ export async function readBoundedRequestBody(
     body.set(chunk, offset)
     offset += chunk.byteLength
   }
-  return new TextDecoder().decode(body)
+  return body
+}
+
+export async function readBoundedRequestBody(
+  request: Request,
+  options?: { maxBytes?: number },
+): Promise<string> {
+  return new TextDecoder().decode(await readBoundedRequestBytes(request, options))
 }

package/src/lib/webhooks/index.ts

@@ -4,6 +4,7 @@ export { generateWebhookSecret, parseWebhookSecret, isValidWebhookSecret } from
 export {
   DEFAULT_WEBHOOK_BODY_LIMIT_BYTES,
   readBoundedRequestBody,
+  readBoundedRequestBytes,
   resolveWebhookBodyLimitBytes,
   WebhookBodyTooLargeError,
 } from './body'

package/src/modules/integrations/types.ts

@@ -157,6 +157,12 @@ export interface IntegrationDetailPageConfig {
    * Provider modules can replace these with injected tabs using the same spot.
    */
   hiddenTabs?: IntegrationDetailBuiltInTab[]
+  /**
+   * Detail-page tab that holds the provider's Connect / Reconnect controls (a built-in tab id or
+   * an injected tab id). The OAuth reauth banner links to `?tab=<connectTabId>` while that tab is
+   * visible and the viewer holds `integrations.credentials.manage`.
+   */
+  connectTabId?: string
 }
 
 export type IntegrationDetailBuiltInTab =

package/src/modules/notifications/safeHref.ts

@@ -0,0 +1,19 @@
+const SENTINEL_ORIGIN = 'https://notifications.open-mercato.local'
+const CONTROL_OR_BACKSLASH = /[\u0000-\u001F\u007F\\]/
+
+export function isSafeNotificationHref(href: string): boolean {
+  if (!href.startsWith('/') || href.startsWith('//')) {
+    return false
+  }
+
+  if (CONTROL_OR_BACKSLASH.test(href)) {
+    return false
+  }
+
+  try {
+    const parsed = new URL(href, SENTINEL_ORIGIN)
+    return parsed.origin === SENTINEL_ORIGIN && !parsed.pathname.startsWith('//')
+  } catch {
+    return false
+  }
+}

package/src/modules/notifications/types.ts

@@ -3,6 +3,13 @@ import type { ComponentType } from 'react'
 export type NotificationStatus = 'unread' | 'read' | 'actioned' | 'dismissed'
 export type NotificationSeverity = 'info' | 'warning' | 'success' | 'error'
 
+/**
+ * `code` of the 409 body `POST /api/notifications/:id/action` answers with when the notification's
+ * action has already been executed. Lets a client tell that refusal apart from a 409 raised by
+ * the action's own command.
+ */
+export const NOTIFICATION_ACTION_ALREADY_EXECUTED_ERROR_CODE = 'notification_action_already_executed'
+
 export type NotificationAction = {
   id: string
   label: string

package/src/modules/payment_gateways/__tests__/types.test.ts

@@ -3,6 +3,9 @@ import {
   getWebhookHandler,
   registerWebhookHandler,
   type VerifyWebhookInput,
+  type WebhookLocatorContext,
+  type WebhookResponseOutcome,
+  WebhookVerificationUnavailableError,
   type WebhookEvent,
 } from '../types'
 
@@ -34,4 +37,45 @@ describe('payment gateway webhook registration', () => {
       expect(getWebhookHandler('invalid')).toBeUndefined()
     },
   )
+
+  it('stays compatible with one-argument locator hints', () => {
+    const readSessionIdHint = (payload: Record<string, unknown> | null) => (payload ? 'sess' : null)
+    registerWebhookHandler('legacy', handler, { readSessionIdHint })
+
+    expect(getWebhookHandler('legacy')?.readSessionIdHint?.({})).toBe('sess')
+    expect(getWebhookHandler('legacy')?.rawBody).toBeUndefined()
+    expect(getWebhookHandler('legacy')?.formatResponse).toBeUndefined()
+  })
+
+  it('passes through the optional extension hooks', () => {
+    const readSessionIdHint = (_payload: Record<string, unknown> | null, context?: WebhookLocatorContext) =>
+      context ? String(context.headers['x-id']) : null
+    const readPaymentIdHint = () => 'pay'
+    const formatResponse = (outcome: WebhookResponseOutcome) => ({ status: 200, body: outcome })
+    registerWebhookHandler('extended', handler, {
+      readSessionIdHint,
+      readPaymentIdHint,
+      rawBody: 'bytes',
+      formatResponse,
+    })
+
+    const registration = getWebhookHandler('extended')
+    expect(registration?.rawBody).toBe('bytes')
+    expect(registration?.readPaymentIdHint).toBe(readPaymentIdHint)
+    expect(registration?.formatResponse).toBe(formatResponse)
+    expect(registration?.readSessionIdHint?.(null, { rawBody: '', headers: { 'x-id': 'abc' } })).toBe('abc')
+  })
+
+  it('rejects an unknown rawBody mode', () => {
+    expect(() =>
+      registerWebhookHandler('bad', handler, { rawBody: 'stream' as unknown as 'text' }),
+    ).toThrow('[internal] Payment gateway webhook rawBody must be')
+    expect(getWebhookHandler('bad')).toBeUndefined()
+  })
+
+  it('exposes a typed verification-unavailable error', () => {
+    const error = new WebhookVerificationUnavailableError()
+    expect(error).toBeInstanceOf(Error)
+    expect(error.name).toBe('WebhookVerificationUnavailableError')
+  })
 })

package/src/modules/payment_gateways/types.ts

@@ -237,6 +237,45 @@ export interface VerifyWebhookInput {
   rawBody: string | Buffer
   headers: Record<string, string | string[] | undefined>
   credentials: Record<string, unknown>
+  /** Platform-resolved payment the webhook is expected to concern, when a locator found one. */
+  candidate?: WebhookCandidateSnapshot
+}
+
+/** Raw request material handed to webhook locator hints. */
+export interface WebhookLocatorContext {
+  rawBody: string | Buffer
+  headers: Record<string, string | string[] | undefined>
+}
+
+export interface WebhookCandidateSnapshot {
+  transactionId: string
+  paymentId: string
+  providerSessionId: string | null
+  amount: string
+  currencyCode: string
+}
+
+export type WebhookResponseOutcome =
+  | 'accepted'
+  | 'no_candidate'
+  | 'verification_failed'
+  | 'verification_unavailable'
+  | 'processing_failed'
+  | 'payload_too_large'
+  | 'rate_limited'
+
+export interface WebhookHttpResponse {
+  status: number
+  body: string | Record<string, unknown>
+  contentType?: string
+}
+
+/** Thrown by a webhook handler when verification cannot be performed (for example a provider outage). */
+export class WebhookVerificationUnavailableError extends Error {
+  constructor(message = 'Webhook verification is unavailable') {
+    super(message)
+    this.name = 'WebhookVerificationUnavailableError'
+  }
 }
 
 export interface WebhookEvent {
@@ -252,10 +291,15 @@ export interface WebhookEvent {
 export interface WebhookHandlerRegistration {
   handler: (input: VerifyWebhookInput) => Promise<WebhookEvent>
   queue?: string
-  readSessionIdHint?: (payload: Record<string, unknown> | null) => string | null
+  readSessionIdHint?: (payload: Record<string, unknown> | null, context?: WebhookLocatorContext) => string | null
+  readPaymentIdHint?: (payload: Record<string, unknown> | null, context?: WebhookLocatorContext) => string | null
   maxBodyBytes?: number
+  rawBody?: WebhookRawBodyMode
+  formatResponse?: (outcome: WebhookResponseOutcome) => WebhookHttpResponse
 }
 
+export type WebhookRawBodyMode = 'text' | 'bytes'
+
 // ── Adapter Registry Options ────────────────────────────────────────────────
 
 export interface RegisterAdapterOptions {
@@ -345,12 +389,11 @@ export function clearGatewayAdapters(): void {
 export function registerWebhookHandler(
   providerKey: string,
   handler: (input: VerifyWebhookInput) => Promise<WebhookEvent>,
-  options?: {
-    queue?: string
-    readSessionIdHint?: (payload: Record<string, unknown> | null) => string | null
-    maxBodyBytes?: number
-  },
+  options?: Omit<WebhookHandlerRegistration, 'handler'>,
 ): () => void {
+  if (options?.rawBody !== undefined && options.rawBody !== 'text' && options.rawBody !== 'bytes') {
+    throw new Error("[internal] Payment gateway webhook rawBody must be 'text' or 'bytes'")
+  }
   if (
     options?.maxBodyBytes !== undefined
     && (!Number.isSafeInteger(options.maxBodyBytes)
@@ -366,7 +409,10 @@ export function registerWebhookHandler(
     handler,
     queue: options?.queue,
     readSessionIdHint: options?.readSessionIdHint,
+    readPaymentIdHint: options?.readPaymentIdHint,
     maxBodyBytes: options?.maxBodyBytes,
+    rawBody: options?.rawBody,
+    formatResponse: options?.formatResponse,
   })
   return () => {
     webhookHandlerRegistry.delete(providerKey)

package/src/modules/registry.ts

@@ -178,6 +178,11 @@ export type ApiRouteManifestEntry = {
 export type ModuleCli = {
   command: string
   run: (argv: string[]) => Promise<void> | void
+  // Usage text printed by the `mercato` dispatcher when the command is invoked with --help/-h.
+  help?: string
+  // Set when the command parses --help/-h itself; the dispatcher then forwards the flag
+  // instead of intercepting it, so the command can print its own richer usage text.
+  handlesHelp?: boolean
 }
 
 export type ModuleSubscriber = {