{"version":3,"sources":["../src/result.ts","../src/validators.ts","../src/finality.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * Result type utilities for adapter operations\n *\n * Enforces \"never throws\" invariant - all adapter functions return Result.\n */\n\nimport type { AdapterError, AdapterErrorCode } from './types.js';\n\n/**\n * Result type for adapter operations\n *\n * All adapter parsing/validation functions should return this type\n * instead of throwing exceptions. This makes error handling explicit\n * and predictable.\n *\n * @example\n * function parseEvent(input: unknown): Result {\n * if (!input) {\n * return adapterErr('input is required', 'missing_required_field');\n * }\n * return ok({ ... });\n * }\n */\nexport type Result = { ok: true; value: T } | { ok: false; error: E };\n\n/**\n * Create a success result\n */\nexport function ok(value: T): Result {\n return { ok: true, value };\n}\n\n/**\n * Create a generic error result\n */\nexport function err(error: E): Result {\n return { ok: false, error };\n}\n\n/**\n * Create an adapter error result (convenience helper)\n *\n * @param message - Human-readable error message\n * @param code - Machine-readable error code\n * @param field - Optional field name that caused the error\n */\nexport function adapterErr(\n message: string,\n code: AdapterErrorCode,\n field?: string\n): Result {\n return err({ code, message, field });\n}\n\n/**\n * Check if result is ok (type guard)\n */\nexport function isOk(result: Result): result is { ok: true; value: T } {\n return result.ok;\n}\n\n/**\n * Check if result is error (type guard)\n */\nexport function isErr(result: Result): result is { ok: false; error: E } {\n return !result.ok;\n}\n\n/**\n * Map over a successful result\n *\n * @example\n * const result = ok(5);\n * const doubled = map(result, x => x * 2); // ok(10)\n */\nexport function map(result: Result, fn: (value: T) => U): Result {\n return result.ok ? ok(fn(result.value)) : result;\n}\n\n/**\n * Map over an error result\n *\n * @example\n * const result = err({ message: 'oops' });\n * const mapped = mapErr(result, e => ({ ...e, prefix: 'Error: ' }));\n */\nexport function mapErr(result: Result, fn: (error: E) => F): Result {\n return result.ok ? result : err(fn(result.error));\n}\n\n/**\n * Chain results (flatMap/bind)\n *\n * @example\n * const parseNumber = (s: string): Result => {\n * const n = parseInt(s);\n * return isNaN(n) ? err('not a number') : ok(n);\n * };\n *\n * const result = chain(ok('42'), parseNumber); // ok(42)\n */\nexport function chain(result: Result, fn: (value: T) => Result): Result {\n return result.ok ? fn(result.value) : result;\n}\n\n/**\n * Unwrap a result, throwing if it's an error\n *\n * Use sparingly - prefer explicit error handling.\n *\n * @throws The error value if result is an error\n */\nexport function unwrap(result: Result): T {\n if (result.ok) {\n return result.value;\n }\n throw result.error;\n}\n\n/**\n * Unwrap a result with a default value for errors\n */\nexport function unwrapOr(result: Result, defaultValue: T): T {\n return result.ok ? result.value : defaultValue;\n}\n","/**\n * Shared validators for PEAC payment rail adapters\n *\n * These validators enforce consistent validation logic across all adapters.\n * They follow the \"never throws\" pattern using Result types.\n */\n\nimport { adapterErr, ok, type Result } from './result.js';\nimport type { AdapterError } from './types.js';\n\n/**\n * Validate required string field\n *\n * @param value - Value to validate\n * @param fieldName - Field name for error messages\n * @returns Result with string value or error\n */\nexport function requireString(value: unknown, fieldName: string): Result {\n if (typeof value !== 'string' || value.trim() === '') {\n return adapterErr(\n `${fieldName} is required and must be a non-empty string`,\n 'missing_required_field',\n fieldName\n );\n }\n return ok(value);\n}\n\n/**\n * Validate optional string field\n *\n * @param value - Value to validate\n * @param fieldName - Field name for error messages\n * @returns Result with string value, undefined, or error\n */\nexport function optionalString(\n value: unknown,\n fieldName: string\n): Result {\n if (value === undefined || value === null) {\n return ok(undefined);\n }\n if (typeof value !== 'string') {\n return adapterErr(`${fieldName} must be a string if provided`, 'validation_error', fieldName);\n }\n return ok(value);\n}\n\n/**\n * Validate required number field\n *\n * @param value - Value to validate\n * @param fieldName - Field name for error messages\n * @returns Result with number value or error\n */\nexport function requireNumber(value: unknown, fieldName: string): Result {\n if (typeof value !== 'number' || !Number.isFinite(value)) {\n return adapterErr(`${fieldName} must be a finite number`, 'validation_error', fieldName);\n }\n return ok(value);\n}\n\n/**\n * Validate amount (must be safe non-negative integer in minor units)\n *\n * @param value - Value to validate\n * @returns Result with amount or error\n */\nexport function requireAmount(value: unknown): Result {\n if (typeof value !== 'number') {\n return adapterErr('amount must be a number', 'invalid_amount', 'amount');\n }\n if (!Number.isSafeInteger(value)) {\n return adapterErr('amount must be a safe integer', 'invalid_amount', 'amount');\n }\n if (value < 0) {\n return adapterErr('amount must be non-negative', 'invalid_amount', 'amount');\n }\n return ok(value);\n}\n\n/**\n * Validate currency code (ISO 4217, uppercase)\n *\n * @param value - Value to validate\n * @returns Result with normalized currency code or error\n */\nexport function requireCurrency(value: unknown): Result {\n if (typeof value !== 'string') {\n return adapterErr('currency must be a string', 'invalid_currency', 'currency');\n }\n const normalized = value.toUpperCase();\n if (!/^[A-Z]{3}$/.test(normalized)) {\n return adapterErr(\n 'currency must be a valid ISO 4217 code (3 uppercase letters)',\n 'invalid_currency',\n 'currency'\n );\n }\n return ok(normalized);\n}\n\n/**\n * Validate optional network identifier (CAIP-2 format preferred)\n *\n * @param value - Value to validate\n * @returns Result with network string, undefined, or error\n */\nexport function optionalNetwork(value: unknown): Result {\n if (value === undefined || value === null) {\n return ok(undefined);\n }\n if (typeof value !== 'string' || value.trim() === '') {\n return adapterErr(\n 'network must be a non-empty string if provided',\n 'invalid_network',\n 'network'\n );\n }\n return ok(value);\n}\n\n/**\n * Parse object safely (for webhook payloads)\n *\n * @param value - Value to validate\n * @param fieldName - Field name for error messages\n * @returns Result with object or error\n */\nexport function requireObject(\n value: unknown,\n fieldName: string = 'input'\n): Result, AdapterError> {\n if (!value || typeof value !== 'object' || Array.isArray(value)) {\n return adapterErr(`${fieldName} must be a non-null object`, 'parse_error', fieldName);\n }\n return ok(value as Record);\n}\n\n/**\n * Validate optional timestamp (ISO 8601 string or Unix seconds)\n *\n * @param value - Value to validate\n * @returns Result with ISO 8601 string, undefined, or error\n */\nexport function optionalTimestamp(value: unknown): Result {\n if (value === undefined || value === null) {\n return ok(undefined);\n }\n if (typeof value === 'string') {\n // Accept ISO 8601 strings as-is\n return ok(value);\n }\n if (typeof value === 'number' && Number.isSafeInteger(value) && value > 0) {\n // Convert Unix seconds to ISO string\n return ok(new Date(value * 1000).toISOString());\n }\n return adapterErr(\n 'timestamp must be an ISO 8601 string or Unix seconds',\n 'validation_error',\n 'timestamp'\n );\n}\n\n/**\n * Validate optional boolean field\n *\n * @param value - Value to validate\n * @param fieldName - Field name for error messages\n * @returns Result with boolean value, undefined, or error\n */\nexport function optionalBoolean(\n value: unknown,\n fieldName: string\n): Result {\n if (value === undefined || value === null) {\n return ok(undefined);\n }\n if (typeof value !== 'boolean') {\n return adapterErr(`${fieldName} must be a boolean if provided`, 'validation_error', fieldName);\n }\n return ok(value);\n}\n\n/**\n * Validate enum value\n *\n * @param value - Value to validate\n * @param allowed - Array of allowed values\n * @param fieldName - Field name for error messages\n * @returns Result with validated value or error\n */\nexport function requireEnum(\n value: unknown,\n allowed: readonly T[],\n fieldName: string\n): Result {\n if (typeof value !== 'string') {\n return adapterErr(`${fieldName} must be a string`, 'validation_error', fieldName);\n }\n if (!allowed.includes(value as T)) {\n return adapterErr(\n `${fieldName} must be one of: ${allowed.join(', ')}`,\n 'validation_error',\n fieldName\n );\n }\n return ok(value as T);\n}\n\n/**\n * Validate optional enum value\n *\n * @param value - Value to validate\n * @param allowed - Array of allowed values\n * @param fieldName - Field name for error messages\n * @returns Result with validated value, undefined, or error\n */\nexport function optionalEnum(\n value: unknown,\n allowed: readonly T[],\n fieldName: string\n): Result {\n if (value === undefined || value === null) {\n return ok(undefined);\n }\n return requireEnum(value, allowed, fieldName);\n}\n","/**\n * Mapper-boundary finality-synthesis guard.\n *\n * Commerce mappings preserve raw upstream artifacts and MUST NOT synthesize\n * payment finality (authorization, capture, settlement, refund, void,\n * chargeback) from non-payment artifacts or lifecycle states alone.\n *\n * This module provides the runtime guard that callers in commerce mappings\n * use to enforce that rule at the mapper boundary. It is deliberately\n * dependency-light and emits a stable string code via MapperBoundaryError\n * rather than registering a new wire-level error code.\n */\n\n/**\n * Strictness mode for commerce mappers.\n *\n * - `strict` - reject any synthesis attempt; reject silent fallbacks\n * (currency='UNKNOWN', defaulted env).\n * - `interop` - emit a deprecation warning instead of rejecting; preserves\n * current consumer behavior. Default.\n * - `legacy` - preserve historical behavior with no warning. Reserved for\n * callers that have migration plans recorded elsewhere.\n */\nexport type StrictnessMode = 'strict' | 'interop' | 'legacy';\n\n/**\n * Stable string identifier for the mapper-boundary finality-synthesis\n * violation. NOT a wire-level error code; consumers may switch on this\n * value to map to caller-specific error reporting.\n */\nexport const COMMERCE_FINALITY_SYNTHESIS_CODE = 'commerce.finality_synthesis_blocked' as const;\n\nexport type MapperBoundaryErrorCode = typeof COMMERCE_FINALITY_SYNTHESIS_CODE;\n\nexport interface MapperBoundaryErrorInit {\n code: MapperBoundaryErrorCode;\n pointer?: string;\n upstreamArtifactHash?: string;\n reason?: string;\n}\n\n/**\n * Error thrown by mapper-boundary guards. Plain class, no schema dependency.\n * Carries a stable `code` and optional pointer + upstream-artifact-hash\n * fields to help callers correlate the failure.\n */\nexport class MapperBoundaryError extends Error {\n readonly code: MapperBoundaryErrorCode;\n readonly pointer?: string;\n readonly upstreamArtifactHash?: string;\n\n constructor(init: MapperBoundaryErrorInit) {\n const message = init.reason\n ? `${init.code}: ${init.reason}`\n : `${init.code}: mapper-boundary guard rejected synthesis`;\n super(message);\n this.name = 'MapperBoundaryError';\n this.code = init.code;\n this.pointer = init.pointer;\n this.upstreamArtifactHash = init.upstreamArtifactHash;\n }\n}\n\n/**\n * Closed enum of commerce events that imply finality and therefore require\n * an explicit upstream payment artifact when present in mapper input.\n */\nconst FINALITY_EVENTS = new Set([\n 'authorization',\n 'capture',\n 'settlement',\n 'refund',\n 'void',\n 'chargeback',\n]);\n\nexport type CommerceFinalityEvent =\n | 'authorization'\n | 'capture'\n | 'settlement'\n | 'refund'\n | 'void'\n | 'chargeback';\n\nexport interface FinalityGuardInput {\n /**\n * The candidate commerce `event` value (or `undefined` if unset). When\n * unset, the guard is a no-op.\n */\n event?: string | undefined;\n\n /**\n * Whether the upstream artifact explicitly proves the claimed finality.\n * Mappers MUST set this from a definite read of upstream-supplied data,\n * NOT from inferred lifecycle state.\n */\n hasExplicitUpstreamArtifact: boolean;\n\n /**\n * The currency code as read from upstream. Mappers MUST set this; callers\n * MUST NOT silently fall back to `'UNKNOWN'`. In strict mode, an empty,\n * `'UNKNOWN'`, or non-string value rejects.\n */\n currency?: string;\n\n /**\n * The environment discriminant as read from upstream. Mappers MUST set\n * this when known; callers MUST NOT silently default. In strict mode, an\n * unset or non-`live`/`test` value rejects.\n */\n env?: 'live' | 'test' | string | undefined;\n\n /**\n * Whether the env was explicitly asserted by upstream (vs defaulted).\n */\n envExplicit?: boolean;\n}\n\nexport interface FinalityGuardOptions {\n mode?: StrictnessMode;\n pointer?: string;\n upstreamArtifactHash?: string;\n /**\n * Optional warning sink for `interop` mode. Defaults to a no-op.\n */\n warn?: (message: string) => void;\n}\n\nconst DEFAULT_MODE: StrictnessMode = 'interop';\n\nfunction noopWarn(_message: string): void {\n /* no-op */\n}\n\n/**\n * Mapper-boundary finality-synthesis guard.\n *\n * Throws `MapperBoundaryError` when:\n * - `event` is one of the finality-bearing values AND\n * `hasExplicitUpstreamArtifact` is false (any mode).\n * - `currency` is missing, empty, or `'UNKNOWN'` and mode is `strict`.\n * - `env` is missing or `envExplicit` is false and mode is `strict`.\n *\n * In `interop` mode, the second and third conditions emit a warning via\n * the supplied `warn` sink instead of throwing. In `legacy` mode, only\n * the first condition throws; the second and third are silent.\n *\n * No-ops when `event` is unset (the common discovery / capability path).\n */\nexport function assertExplicitFinality(\n input: FinalityGuardInput,\n options: FinalityGuardOptions = {}\n): void {\n const mode: StrictnessMode = options.mode ?? DEFAULT_MODE;\n const warn = options.warn ?? noopWarn;\n const pointer = options.pointer;\n const upstreamArtifactHash = options.upstreamArtifactHash;\n\n // Rule 1: finality event without explicit upstream artifact - reject in all modes.\n if (input.event !== undefined && FINALITY_EVENTS.has(input.event)) {\n if (!input.hasExplicitUpstreamArtifact) {\n throw new MapperBoundaryError({\n code: COMMERCE_FINALITY_SYNTHESIS_CODE,\n pointer,\n upstreamArtifactHash,\n reason: `event=${JSON.stringify(input.event)} requires an explicit upstream payment artifact`,\n });\n }\n }\n\n // Rule 2: silent currency fallback - reject in strict, warn in interop, silent in legacy.\n const isMissingCurrency =\n typeof input.currency !== 'string' ||\n input.currency.length === 0 ||\n input.currency === 'UNKNOWN';\n if (isMissingCurrency) {\n if (mode === 'strict') {\n throw new MapperBoundaryError({\n code: COMMERCE_FINALITY_SYNTHESIS_CODE,\n pointer,\n upstreamArtifactHash,\n reason:\n 'currency missing or fallback (UNKNOWN); strict mode requires upstream-asserted currency',\n });\n }\n if (mode === 'interop') {\n warn(\n 'commerce mapper: currency missing or fallback (UNKNOWN). Strict mode will reject this in v0.13.0+. Provide an upstream-asserted currency.'\n );\n }\n }\n\n // Rule 3: defaulted env - reject in strict, warn in interop, silent in legacy.\n const envIsExplicit = input.envExplicit === true;\n const envIsKnown = input.env === 'live' || input.env === 'test';\n if (!envIsKnown || !envIsExplicit) {\n if (mode === 'strict') {\n throw new MapperBoundaryError({\n code: COMMERCE_FINALITY_SYNTHESIS_CODE,\n pointer,\n upstreamArtifactHash,\n reason: 'env missing or defaulted; strict mode requires upstream-asserted env (live|test)',\n });\n }\n if (mode === 'interop') {\n warn(\n 'commerce mapper: env missing or defaulted. Strict mode will reject this in v0.13.0+. Provide an upstream-asserted env.'\n );\n }\n }\n}\n\n/**\n * Returns whether the given event is one of the finality-bearing commerce\n * events. Useful for callers that want to short-circuit before assembling\n * full guard input.\n */\nexport function isFinalityEvent(event: string | undefined): event is CommerceFinalityEvent {\n return event !== undefined && FINALITY_EVENTS.has(event);\n}\n"]}