@vaultsaas/core 0.1.0

package/dist/index.cjs

@@ -0,0 +1,4314 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AdapterComplianceError: () => AdapterComplianceError,
+  BatchBuffer: () => BatchBuffer,
+  DEFAULT_IDEMPOTENCY_TTL_MS: () => DEFAULT_IDEMPOTENCY_TTL_MS,
+  DEFAULT_VAULT_EVENT_TYPES: () => DEFAULT_VAULT_EVENT_TYPES,
+  DLocalAdapter: () => DLocalAdapter,
+  MemoryIdempotencyStore: () => MemoryIdempotencyStore,
+  MockAdapter: () => MockAdapter,
+  PaystackAdapter: () => PaystackAdapter,
+  PlatformConnector: () => PlatformConnector,
+  Router: () => Router,
+  StripeAdapter: () => StripeAdapter,
+  VAULT_ERROR_CODE_DEFINITIONS: () => VAULT_ERROR_CODE_DEFINITIONS,
+  VaultClient: () => VaultClient,
+  VaultConfigError: () => VaultConfigError,
+  VaultError: () => VaultError,
+  VaultIdempotencyConflictError: () => VaultIdempotencyConflictError,
+  VaultNetworkError: () => VaultNetworkError,
+  VaultProviderError: () => VaultProviderError,
+  VaultRoutingError: () => VaultRoutingError,
+  WebhookVerificationError: () => WebhookVerificationError,
+  buildVaultErrorDocsUrl: () => buildVaultErrorDocsUrl,
+  createAdapterComplianceHarness: () => createAdapterComplianceHarness,
+  createDLocalSignedWebhookPayload: () => createDLocalSignedWebhookPayload,
+  createPaystackSignedWebhookPayload: () => createPaystackSignedWebhookPayload,
+  createSignedWebhookPayload: () => createSignedWebhookPayload,
+  createStripeSignedWebhookPayload: () => createStripeSignedWebhookPayload,
+  getVaultErrorCodeDefinition: () => getVaultErrorCodeDefinition,
+  hashIdempotencyPayload: () => hashIdempotencyPayload,
+  isProviderErrorHint: () => isProviderErrorHint,
+  mapProviderError: () => mapProviderError,
+  normalizeWebhookEvent: () => normalizeWebhookEvent,
+  ruleMatchesContext: () => ruleMatchesContext,
+  validatePaymentMethods: () => validatePaymentMethods,
+  validatePaymentResult: () => validatePaymentResult,
+  validateRefundResult: () => validateRefundResult,
+  validateTransactionStatus: () => validateTransactionStatus,
+  validateVoidResult: () => validateVoidResult,
+  validateWebhookEvent: () => validateWebhookEvent
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors/error-codes.ts
+var ERROR_DOCS_BASE_URL = "https://docs.vaultsaas.com/errors";
+var FALLBACK_CODE_DEFINITION = {
+  category: "unknown",
+  suggestion: "Review provider response details and retry only when the failure is transient.",
+  retriable: false
+};
+var VAULT_ERROR_CODE_DEFINITIONS = {
+  INVALID_CONFIGURATION: {
+    category: "configuration_error",
+    suggestion: "Check VaultClient configuration values and required provider settings.",
+    retriable: false
+  },
+  PROVIDER_NOT_CONFIGURED: {
+    category: "configuration_error",
+    suggestion: "Add the provider adapter and credentials to VaultClient.providers.",
+    retriable: false
+  },
+  ADAPTER_NOT_FOUND: {
+    category: "configuration_error",
+    suggestion: "Install the provider adapter package and wire it in config.",
+    retriable: false
+  },
+  PROVIDER_AUTH_FAILED: {
+    category: "configuration_error",
+    suggestion: "Verify provider credentials and ensure they match the current environment.",
+    retriable: false
+  },
+  NO_ROUTING_MATCH: {
+    category: "routing_error",
+    suggestion: "Add a matching routing rule or configure a default fallback provider.",
+    retriable: false
+  },
+  ROUTING_PROVIDER_EXCLUDED: {
+    category: "routing_error",
+    suggestion: "Remove the forced provider from exclusions or choose a different provider override.",
+    retriable: false
+  },
+  ROUTING_PROVIDER_UNAVAILABLE: {
+    category: "routing_error",
+    suggestion: "Enable the provider in config or update routing rules to a valid provider.",
+    retriable: false
+  },
+  INVALID_REQUEST: {
+    category: "invalid_request",
+    suggestion: "Fix invalid or missing request fields before retrying the operation.",
+    retriable: false
+  },
+  IDEMPOTENCY_CONFLICT: {
+    category: "invalid_request",
+    suggestion: "Reuse the same payload for an idempotency key or generate a new key.",
+    retriable: false
+  },
+  WEBHOOK_SIGNATURE_INVALID: {
+    category: "invalid_request",
+    suggestion: "Verify webhook secret, signature algorithm, and that the raw body is unmodified.",
+    retriable: false
+  },
+  CARD_DECLINED: {
+    category: "card_declined",
+    suggestion: "Ask the customer for another payment method or a retry with updated details.",
+    retriable: false
+  },
+  AUTHENTICATION_REQUIRED: {
+    category: "authentication_required",
+    suggestion: "Trigger customer authentication (for example, a 3DS challenge).",
+    retriable: false
+  },
+  FRAUD_SUSPECTED: {
+    category: "fraud_suspected",
+    suggestion: "Block automatic retries and route the payment through manual fraud review.",
+    retriable: false
+  },
+  RATE_LIMITED: {
+    category: "rate_limited",
+    suggestion: "Apply exponential backoff before retrying provider requests.",
+    retriable: true
+  },
+  NETWORK_ERROR: {
+    category: "network_error",
+    suggestion: "Retry with backoff and confirm outbound connectivity/timeouts to the provider.",
+    retriable: true
+  },
+  PROVIDER_TIMEOUT: {
+    category: "network_error",
+    suggestion: "Retry with backoff and increase timeout if the provider latency is expected.",
+    retriable: true
+  },
+  PLATFORM_UNREACHABLE: {
+    category: "network_error",
+    suggestion: "Use local routing fallback and verify platform API key and network reachability.",
+    retriable: true
+  },
+  PROVIDER_ERROR: {
+    category: "provider_error",
+    suggestion: "Retry if transient, or fail over to another provider when configured.",
+    retriable: true
+  },
+  PROVIDER_UNKNOWN: {
+    category: "unknown",
+    suggestion: "Capture provider response metadata and map this error case for deterministic handling.",
+    retriable: false
+  }
+};
+function getVaultErrorCodeDefinition(code) {
+  return VAULT_ERROR_CODE_DEFINITIONS[code] ?? FALLBACK_CODE_DEFINITION;
+}
+function buildVaultErrorDocsUrl(code, docsPath) {
+  const path = docsPath ?? code.toLowerCase();
+  return `${ERROR_DOCS_BASE_URL}/${path}`;
+}
+
+// src/errors/vault-error.ts
+var VaultError = class extends Error {
+  code;
+  category;
+  suggestion;
+  docsUrl;
+  retriable;
+  context;
+  constructor(message, options) {
+    super(message);
+    const definition = getVaultErrorCodeDefinition(options.code);
+    this.name = "VaultError";
+    this.code = options.code;
+    this.category = options.category ?? definition.category;
+    this.suggestion = options.suggestion ?? definition.suggestion;
+    this.docsUrl = options.docsUrl ?? buildVaultErrorDocsUrl(options.code, definition.docsPath);
+    this.retriable = options.retriable ?? definition.retriable;
+    this.context = options.context ?? {};
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var SUBCLASS_OPTION_KEYS = [
+  "code",
+  "category",
+  "suggestion",
+  "docsUrl",
+  "retriable",
+  "context"
+];
+function isSubclassOptions(value) {
+  if (!value || typeof value !== "object") {
+    return false;
+  }
+  const record = value;
+  return SUBCLASS_OPTION_KEYS.some((key) => key in record);
+}
+function normalizeSubclassOptions(value) {
+  if (isSubclassOptions(value)) {
+    return value;
+  }
+  return value ? { context: value } : {};
+}
+var VaultConfigError = class extends VaultError {
+  constructor(message, options) {
+    const normalized = normalizeSubclassOptions(options);
+    super(message, {
+      code: normalized.code ?? "INVALID_CONFIGURATION",
+      category: normalized.category,
+      suggestion: normalized.suggestion,
+      docsUrl: normalized.docsUrl,
+      retriable: normalized.retriable,
+      context: normalized.context
+    });
+    this.name = "VaultConfigError";
+  }
+};
+var VaultRoutingError = class extends VaultError {
+  constructor(message, options) {
+    const normalized = normalizeSubclassOptions(options);
+    super(message, {
+      code: normalized.code ?? "NO_ROUTING_MATCH",
+      category: normalized.category,
+      suggestion: normalized.suggestion,
+      docsUrl: normalized.docsUrl,
+      retriable: normalized.retriable,
+      context: normalized.context
+    });
+    this.name = "VaultRoutingError";
+  }
+};
+var VaultProviderError = class extends VaultError {
+  constructor(message, options) {
+    const normalized = normalizeSubclassOptions(options);
+    super(message, {
+      code: normalized.code ?? "PROVIDER_ERROR",
+      category: normalized.category,
+      suggestion: normalized.suggestion,
+      docsUrl: normalized.docsUrl,
+      retriable: normalized.retriable,
+      context: normalized.context
+    });
+    this.name = "VaultProviderError";
+  }
+};
+var VaultNetworkError = class extends VaultError {
+  constructor(message, options) {
+    const normalized = normalizeSubclassOptions(options);
+    super(message, {
+      code: normalized.code ?? "NETWORK_ERROR",
+      category: normalized.category,
+      suggestion: normalized.suggestion,
+      docsUrl: normalized.docsUrl,
+      retriable: normalized.retriable ?? true,
+      context: normalized.context
+    });
+    this.name = "VaultNetworkError";
+  }
+};
+var WebhookVerificationError = class extends VaultError {
+  constructor(message, options) {
+    const normalized = normalizeSubclassOptions(options);
+    super(message, {
+      code: normalized.code ?? "WEBHOOK_SIGNATURE_INVALID",
+      category: normalized.category,
+      suggestion: normalized.suggestion,
+      docsUrl: normalized.docsUrl,
+      retriable: normalized.retriable,
+      context: normalized.context
+    });
+    this.name = "WebhookVerificationError";
+  }
+};
+var VaultIdempotencyConflictError = class extends VaultError {
+  constructor(message, options) {
+    const normalized = normalizeSubclassOptions(options);
+    super(message, {
+      code: normalized.code ?? "IDEMPOTENCY_CONFLICT",
+      category: normalized.category,
+      suggestion: normalized.suggestion,
+      docsUrl: normalized.docsUrl,
+      retriable: normalized.retriable,
+      context: normalized.context
+    });
+    this.name = "VaultIdempotencyConflictError";
+  }
+};
+
+// src/errors/provider-error-mapper.ts
+var NETWORK_ERROR_CODES = /* @__PURE__ */ new Set([
+  "ECONNABORTED",
+  "ECONNREFUSED",
+  "ECONNRESET",
+  "ENETUNREACH",
+  "ENOTFOUND",
+  "ETIMEDOUT",
+  "EAI_AGAIN",
+  "UND_ERR_CONNECT_TIMEOUT"
+]);
+var CARD_DECLINED_PATTERNS = [
+  /card[\s_-]?declined/i,
+  /insufficient[\s_-]?funds/i,
+  /do[\s_-]?not[\s_-]?honou?r/i,
+  /generic[\s_-]?decline/i
+];
+var AUTHENTICATION_REQUIRED_PATTERNS = [
+  /\b3ds\b/i,
+  /authentication[\s_-]?required/i,
+  /requires[\s_-]?action/i,
+  /challenge[\s_-]?required/i
+];
+var FRAUD_PATTERNS = [
+  /fraud/i,
+  /risk[\s_-]?check/i,
+  /suspected/i,
+  /blocked[\s_-]?for[\s_-]?risk/i
+];
+var INVALID_REQUEST_PATTERNS = [
+  /invalid[\s_-]?request/i,
+  /missing required/i,
+  /malformed/i,
+  /validation/i
+];
+var RATE_LIMIT_PATTERNS = [/rate[\s_-]?limit/i, /too many requests/i];
+var AUTH_FAILED_PATTERNS = [
+  /invalid[\s_-]?api[\s_-]?key/i,
+  /unauthorized/i,
+  /authentication failed/i,
+  /forbidden/i
+];
+function asRecord(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+  return value;
+}
+function readString(source, key) {
+  if (!source) {
+    return void 0;
+  }
+  const value = source[key];
+  return typeof value === "string" && value.trim() ? value : void 0;
+}
+function readNumber(source, key) {
+  if (!source) {
+    return void 0;
+  }
+  const value = source[key];
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function matchAny(text, patterns) {
+  return patterns.some((pattern) => pattern.test(text));
+}
+function isProviderErrorHint(value) {
+  const record = asRecord(value);
+  if (!record) {
+    return false;
+  }
+  return typeof record.providerCode === "string" || typeof record.providerMessage === "string" || typeof record.requestId === "string" || typeof record.httpStatus === "number" || typeof record.declineCode === "string" || typeof record.type === "string" || typeof record.isNetworkError === "boolean" || typeof record.isTimeout === "boolean" || "raw" in record;
+}
+function extractHint(source) {
+  if (isProviderErrorHint(source)) {
+    return source;
+  }
+  const record = asRecord(source);
+  if (!record) {
+    return void 0;
+  }
+  const hint = record.hint;
+  if (isProviderErrorHint(hint)) {
+    return hint;
+  }
+  const providerError = record.providerError;
+  if (isProviderErrorHint(providerError)) {
+    return providerError;
+  }
+  return void 0;
+}
+function extractProviderError(error) {
+  const record = asRecord(error);
+  const hint = extractHint(error);
+  const response = asRecord(record?.response);
+  const responseData = asRecord(response?.data);
+  const responseError = asRecord(responseData?.error);
+  const providerCode = hint?.providerCode ?? readString(record, "providerCode") ?? readString(responseError, "code") ?? readString(responseData, "code");
+  const providerMessage = hint?.providerMessage ?? readString(record, "providerMessage") ?? readString(responseError, "message") ?? readString(responseData, "message");
+  const requestId = hint?.requestId ?? readString(record, "requestId") ?? readString(response, "requestId");
+  const httpStatus = hint?.httpStatus ?? readNumber(record, "status") ?? readNumber(record, "statusCode") ?? readNumber(response, "status");
+  const declineCode = hint?.declineCode ?? readString(record, "declineCode") ?? readString(responseError, "declineCode") ?? readString(responseData, "declineCode");
+  const type = hint?.type ?? readString(record, "type") ?? readString(responseError, "type") ?? readString(responseData, "type");
+  const message = providerMessage ?? (error instanceof Error ? error.message : void 0) ?? readString(record, "message") ?? "Provider operation failed.";
+  const errorCode = readString(record, "code") ?? readString(responseError, "code") ?? readString(responseData, "code");
+  const errorCodeUpper = errorCode?.toUpperCase();
+  const textBlob = [message, providerMessage, providerCode, declineCode, type].filter((value) => Boolean(value)).join(" ");
+  const isTimeout = hint?.isTimeout ?? (errorCodeUpper === "ETIMEDOUT" || /timeout|timed out/i.test(textBlob));
+  const isNetworkError = hint?.isNetworkError ?? (isTimeout || (errorCodeUpper ? NETWORK_ERROR_CODES.has(errorCodeUpper) : false) || /network|socket|dns|connection reset|connection refused/i.test(textBlob));
+  return {
+    message,
+    providerCode,
+    providerMessage,
+    requestId,
+    httpStatus,
+    declineCode,
+    type,
+    errorCode,
+    isNetworkError,
+    isTimeout,
+    raw: hint?.raw ?? responseData ?? error
+  };
+}
+function classifyProviderError(details) {
+  const textBlob = [
+    details.message,
+    details.providerMessage,
+    details.providerCode,
+    details.declineCode,
+    details.type
+  ].filter((value) => Boolean(value)).join(" ");
+  if (details.httpStatus === 429 || matchAny(textBlob, RATE_LIMIT_PATTERNS)) {
+    return { code: "RATE_LIMITED" };
+  }
+  if (details.httpStatus === 401 || details.httpStatus === 403 || matchAny(textBlob, AUTH_FAILED_PATTERNS)) {
+    return { code: "PROVIDER_AUTH_FAILED" };
+  }
+  if (matchAny(textBlob, AUTHENTICATION_REQUIRED_PATTERNS)) {
+    return { code: "AUTHENTICATION_REQUIRED" };
+  }
+  if (matchAny(textBlob, FRAUD_PATTERNS)) {
+    return { code: "FRAUD_SUSPECTED" };
+  }
+  if (matchAny(textBlob, CARD_DECLINED_PATTERNS)) {
+    return { code: "CARD_DECLINED" };
+  }
+  if (details.httpStatus === 400 || details.httpStatus === 404 || details.httpStatus === 409 || details.httpStatus === 422 || matchAny(textBlob, INVALID_REQUEST_PATTERNS)) {
+    return { code: "INVALID_REQUEST" };
+  }
+  if (details.httpStatus !== void 0 && details.httpStatus >= 500) {
+    return { code: "PROVIDER_ERROR" };
+  }
+  return { code: "PROVIDER_UNKNOWN" };
+}
+function mapProviderError(error, mappingContext) {
+  if (error instanceof VaultError) {
+    return error;
+  }
+  const details = extractProviderError(error);
+  const context = {
+    provider: mappingContext.provider,
+    operation: mappingContext.operation,
+    providerCode: details.providerCode,
+    providerMessage: details.providerMessage ?? details.message,
+    requestId: details.requestId,
+    httpStatus: details.httpStatus,
+    declineCode: details.declineCode,
+    errorCode: details.errorCode,
+    raw: details.raw
+  };
+  if (details.isNetworkError) {
+    return new VaultNetworkError(details.message, {
+      code: details.isTimeout ? "PROVIDER_TIMEOUT" : "NETWORK_ERROR",
+      context
+    });
+  }
+  const classification = classifyProviderError(details);
+  return new VaultProviderError(details.message, {
+    code: classification.code,
+    context
+  });
+}
+
+// src/webhooks/event-types.ts
+var DEFAULT_VAULT_EVENT_TYPES = [
+  "payment.completed",
+  "payment.failed",
+  "payment.pending",
+  "payment.requires_action",
+  "payment.refunded",
+  "payment.partially_refunded",
+  "payment.disputed",
+  "payment.dispute_resolved",
+  "payout.completed",
+  "payout.failed"
+];
+
+// src/webhooks/handler.ts
+var KNOWN_EVENT_TYPES = {
+  "payment.completed": true,
+  "payment.failed": true,
+  "payment.pending": true,
+  "payment.requires_action": true,
+  "payment.refunded": true,
+  "payment.partially_refunded": true,
+  "payment.disputed": true,
+  "payment.dispute_resolved": true,
+  "payout.completed": true,
+  "payout.failed": true
+};
+function normalizeEventType(value) {
+  if (value && value in KNOWN_EVENT_TYPES) {
+    return value;
+  }
+  return "payment.failed";
+}
+function normalizeWebhookEvent(provider, payload, rawPayload = payload) {
+  const timestamp = payload.timestamp ?? (/* @__PURE__ */ new Date()).toISOString();
+  const providerEventId = payload.providerEventId ?? payload.id ?? `pevt_${Date.now()}`;
+  return {
+    id: payload.id ?? `vevt_${provider}_${Date.now()}`,
+    type: normalizeEventType(payload.type),
+    provider,
+    transactionId: payload.transactionId,
+    providerEventId,
+    data: payload.data ?? {},
+    rawPayload,
+    timestamp
+  };
+}
+
+// src/adapters/shared/http.ts
+function asRecord2(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+  return value;
+}
+function readString2(source, key) {
+  if (!source) {
+    return void 0;
+  }
+  const value = source[key];
+  return typeof value === "string" && value.trim() ? value : void 0;
+}
+function readNumber2(source, key) {
+  if (!source) {
+    return void 0;
+  }
+  const value = source[key];
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function stringifyBody(body) {
+  if (body === void 0 || body === null) {
+    return void 0;
+  }
+  if (typeof body === "string") {
+    return body;
+  }
+  return JSON.stringify(body);
+}
+function parseJsonSafe(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+function encodeFormBody(body) {
+  const params = new URLSearchParams();
+  function appendValue(prefix, value) {
+    if (value === void 0) {
+      return;
+    }
+    if (value === null) {
+      params.append(prefix, "");
+      return;
+    }
+    if (Array.isArray(value)) {
+      value.forEach((item, index) => {
+        appendValue(`${prefix}[${index}]`, item);
+      });
+      return;
+    }
+    if (typeof value === "object") {
+      for (const [key, nestedValue] of Object.entries(
+        value
+      )) {
+        appendValue(`${prefix}[${key}]`, nestedValue);
+      }
+      return;
+    }
+    const primitive = value;
+    params.append(prefix, String(primitive));
+  }
+  for (const [key, value] of Object.entries(body)) {
+    appendValue(key, value);
+  }
+  return params;
+}
+function readHeader(headers, name) {
+  const needle = name.toLowerCase();
+  for (const [key, value] of Object.entries(headers)) {
+    if (key.toLowerCase() === needle) {
+      return value;
+    }
+  }
+  return void 0;
+}
+async function requestJson(options) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), options.timeoutMs);
+  const url = `${options.baseUrl}${options.path}`;
+  const serializedBody = stringifyBody(options.body);
+  const headers = {
+    ...options.body !== void 0 ? { "content-type": "application/json" } : {},
+    ...options.headers
+  };
+  try {
+    const response = await options.fetchFn(url, {
+      method: options.method ?? "GET",
+      headers,
+      body: serializedBody,
+      signal: controller.signal
+    });
+    const text = await response.text();
+    const payload = text ? parseJsonSafe(text) : null;
+    if (!response.ok) {
+      const payloadRecord = asRecord2(payload);
+      const errorRecord = asRecord2(payloadRecord?.error) ?? payloadRecord;
+      const hint = {
+        httpStatus: response.status,
+        providerCode: readString2(errorRecord, "code") ?? readString2(payloadRecord, "code"),
+        providerMessage: readString2(errorRecord, "message") ?? readString2(payloadRecord, "message") ?? response.statusText,
+        declineCode: readString2(errorRecord, "decline_code") ?? readString2(errorRecord, "declineCode"),
+        type: readString2(errorRecord, "type"),
+        requestId: response.headers.get("request-id") ?? response.headers.get("x-request-id") ?? void 0,
+        raw: payload
+      };
+      throw {
+        message: hint.providerMessage ?? `Provider request failed with status ${response.status}.`,
+        status: response.status,
+        hint
+      };
+    }
+    if (!text) {
+      return {};
+    }
+    return payload;
+  } catch (error) {
+    const record = asRecord2(error);
+    const isAbortError = error instanceof Error && error.name === "AbortError";
+    const message = (error instanceof Error ? error.message : void 0) ?? readString2(record, "message") ?? "Provider request failed.";
+    if (isAbortError) {
+      throw {
+        message: "Request timed out.",
+        code: "ETIMEDOUT",
+        hint: {
+          httpStatus: readNumber2(record, "status"),
+          providerMessage: message,
+          isNetworkError: true,
+          isTimeout: true,
+          raw: error
+        }
+      };
+    }
+    if (record && "hint" in record) {
+      throw error;
+    }
+    throw {
+      message,
+      hint: {
+        providerMessage: message,
+        isNetworkError: true,
+        raw: error
+      }
+    };
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+// src/adapters/shared/signature.ts
+var import_node_crypto = require("crypto");
+function toRawString(payload) {
+  return typeof payload === "string" ? payload : payload.toString("utf-8");
+}
+function createHmacDigest(algorithm, secret, content) {
+  return (0, import_node_crypto.createHmac)(algorithm, secret).update(content).digest("hex");
+}
+function secureCompareHex(leftHex, rightHex) {
+  const left = Buffer.from(leftHex, "hex");
+  const right = Buffer.from(rightHex, "hex");
+  if (left.length !== right.length || left.length === 0) {
+    return false;
+  }
+  return (0, import_node_crypto.timingSafeEqual)(left, right);
+}
+
+// src/adapters/dlocal-adapter.ts
+var DEFAULT_DLOCAL_BASE_URL = "https://api.dlocal.com";
+var DEFAULT_TIMEOUT_MS = 15e3;
+var DLOCAL_API_VERSION = "2.1";
+function asRecord3(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+  return value;
+}
+function readString3(source, key) {
+  if (!source) {
+    return void 0;
+  }
+  const value = source[key];
+  return typeof value === "string" && value.trim() ? value : void 0;
+}
+function readNumber3(source, key) {
+  if (!source) {
+    return void 0;
+  }
+  const value = source[key];
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function mapDLocalStatus(status) {
+  switch (status?.toUpperCase()) {
+    case "AUTHORIZED":
+      return "authorized";
+    case "PAID":
+    case "APPROVED":
+    case "CAPTURED":
+      return "completed";
+    case "PENDING":
+    case "IN_PROCESS":
+      return "pending";
+    case "REJECTED":
+    case "DECLINED":
+      return "declined";
+    case "CANCELED":
+    case "CANCELLED":
+      return "cancelled";
+    case "REQUIRES_ACTION":
+      return "requires_action";
+    default:
+      return "failed";
+  }
+}
+function mapRefundStatus(status) {
+  switch (status?.toUpperCase()) {
+    case "COMPLETED":
+    case "APPROVED":
+      return "completed";
+    case "PENDING":
+      return "pending";
+    default:
+      return "failed";
+  }
+}
+function mapDLocalEventType(type) {
+  switch (type?.toLowerCase()) {
+    case "payment.approved":
+    case "payment.captured":
+      return "payment.completed";
+    case "payment.pending":
+      return "payment.pending";
+    case "payment.failed":
+    case "payment.rejected":
+      return "payment.failed";
+    case "payment.refunded":
+      return "payment.refunded";
+    case "payment.partially_refunded":
+      return "payment.partially_refunded";
+    case "chargeback.created":
+      return "payment.disputed";
+    case "chargeback.closed":
+      return "payment.dispute_resolved";
+    default:
+      return "payment.failed";
+  }
+}
+function mapPaymentMethod(paymentMethod) {
+  if (paymentMethod.type === "card" && "token" in paymentMethod) {
+    return {
+      payment_method_id: "CARD",
+      card: {
+        token: paymentMethod.token
+      }
+    };
+  }
+  if (paymentMethod.type === "card") {
+    return {
+      payment_method_id: "CARD",
+      card: {
+        number: paymentMethod.number,
+        expiration_month: paymentMethod.expMonth,
+        expiration_year: paymentMethod.expYear,
+        cvv: paymentMethod.cvc
+      }
+    };
+  }
+  if (paymentMethod.type === "pix") {
+    return {
+      payment_method_id: "PIX"
+    };
+  }
+  if (paymentMethod.type === "boleto") {
+    return {
+      payment_method_id: "BOLETO",
+      payer: {
+        document: paymentMethod.customerDocument
+      }
+    };
+  }
+  if (paymentMethod.type === "bank_transfer") {
+    return {
+      payment_method_id: "BANK_TRANSFER",
+      bank_transfer: {
+        bank_code: paymentMethod.bankCode,
+        account_number: paymentMethod.accountNumber
+      }
+    };
+  }
+  return {
+    payment_method_id: paymentMethod.type.toUpperCase()
+  };
+}
+function timestampOrNow(input) {
+  if (!input) {
+    return (/* @__PURE__ */ new Date()).toISOString();
+  }
+  const date = new Date(input);
+  return Number.isNaN(date.getTime()) ? (/* @__PURE__ */ new Date()).toISOString() : date.toISOString();
+}
+var DLocalAdapter = class _DLocalAdapter {
+  name = "dlocal";
+  static supportedMethods = [
+    "card",
+    "pix",
+    "boleto",
+    "bank_transfer"
+  ];
+  static supportedCurrencies = [
+    "BRL",
+    "MXN",
+    "ARS",
+    "CLP",
+    "COP",
+    "PEN",
+    "UYU",
+    "BOB",
+    "PYG",
+    "CRC",
+    "GTQ",
+    "PAB",
+    "DOP",
+    "USD"
+  ];
+  static supportedCountries = [
+    "BR",
+    "MX",
+    "AR",
+    "CL",
+    "CO",
+    "PE",
+    "UY",
+    "BO",
+    "PY",
+    "CR",
+    "GT",
+    "PA",
+    "DO",
+    "EC",
+    "SV",
+    "NI",
+    "HN"
+  ];
+  metadata = {
+    supportedMethods: _DLocalAdapter.supportedMethods,
+    supportedCurrencies: _DLocalAdapter.supportedCurrencies,
+    supportedCountries: _DLocalAdapter.supportedCountries
+  };
+  config;
+  constructor(rawConfig) {
+    const xLogin = typeof rawConfig.xLogin === "string" ? rawConfig.xLogin.trim() : "";
+    const xTransKey = typeof rawConfig.xTransKey === "string" ? rawConfig.xTransKey.trim() : "";
+    const secretKey = typeof rawConfig.secretKey === "string" ? rawConfig.secretKey.trim() : "";
+    if (!xLogin || !xTransKey || !secretKey) {
+      throw new VaultConfigError(
+        "dLocal adapter requires config.xLogin, config.xTransKey, and config.secretKey.",
+        {
+          code: "INVALID_CONFIGURATION",
+          context: {
+            provider: "dlocal"
+          }
+        }
+      );
+    }
+    const baseUrl = typeof rawConfig.baseUrl === "string" && rawConfig.baseUrl.trim() ? rawConfig.baseUrl.trim() : DEFAULT_DLOCAL_BASE_URL;
+    const timeoutMs = typeof rawConfig.timeoutMs === "number" && Number.isFinite(rawConfig.timeoutMs) && rawConfig.timeoutMs > 0 ? Math.floor(rawConfig.timeoutMs) : DEFAULT_TIMEOUT_MS;
+    const customFetch = rawConfig.fetchFn;
+    const fetchFn = typeof customFetch === "function" ? customFetch : fetch;
+    this.config = {
+      xLogin,
+      xTransKey,
+      secretKey,
+      baseUrl,
+      timeoutMs,
+      fetchFn,
+      webhookSecret: typeof rawConfig.webhookSecret === "string" ? rawConfig.webhookSecret : void 0
+    };
+  }
+  async charge(request) {
+    return this.createPayment(request, false);
+  }
+  async authorize(request) {
+    return this.createPayment(request, true);
+  }
+  async capture(request) {
+    const payment = await this.request({
+      operation: "capture",
+      path: `/v1/payments/${request.transactionId}/capture`,
+      method: "POST",
+      body: request.amount !== void 0 ? {
+        amount: request.amount
+      } : void 0
+    });
+    return this.normalizePaymentResult(
+      payment,
+      void 0,
+      request.transactionId
+    );
+  }
+  async refund(request) {
+    const refund = await this.request({
+      operation: "refund",
+      path: `/v1/payments/${request.transactionId}/refund`,
+      method: "POST",
+      body: {
+        amount: request.amount,
+        reason: request.reason
+      }
+    });
+    return {
+      id: refund.refund_id ?? refund.id ?? `refund_${Date.now()}`,
+      transactionId: refund.payment_id ?? request.transactionId,
+      status: mapRefundStatus(refund.status),
+      amount: refund.amount ?? request.amount ?? 0,
+      currency: (refund.currency ?? "USD").toUpperCase(),
+      provider: this.name,
+      providerId: refund.id ?? refund.refund_id ?? request.transactionId,
+      reason: refund.reason ?? request.reason,
+      createdAt: timestampOrNow(refund.created_date)
+    };
+  }
+  async void(request) {
+    const payment = await this.request({
+      operation: "void",
+      path: `/v1/payments/${request.transactionId}/cancel`,
+      method: "POST",
+      body: {}
+    });
+    return {
+      id: `void_${payment.payment_id ?? payment.id ?? request.transactionId}`,
+      transactionId: request.transactionId,
+      status: mapDLocalStatus(payment.status) === "cancelled" ? "completed" : "failed",
+      provider: this.name,
+      createdAt: timestampOrNow(payment.created_date)
+    };
+  }
+  async getStatus(transactionId) {
+    const payment = await this.request({
+      operation: "getStatus",
+      path: `/v1/payments/${transactionId}`,
+      method: "GET"
+    });
+    const status = mapDLocalStatus(payment.status);
+    const timestamp = timestampOrNow(payment.created_date);
+    return {
+      id: payment.payment_id ?? payment.id ?? transactionId,
+      status,
+      provider: this.name,
+      providerId: payment.id ?? payment.payment_id ?? transactionId,
+      amount: payment.amount ?? 0,
+      currency: (payment.currency ?? "USD").toUpperCase(),
+      history: [
+        {
+          status,
+          timestamp,
+          reason: `dlocal status: ${payment.status ?? "unknown"}`
+        }
+      ],
+      updatedAt: timestamp
+    };
+  }
+  async listPaymentMethods(country, currency) {
+    const normalizedCurrency = currency.toUpperCase();
+    return [
+      {
+        type: "card",
+        provider: this.name,
+        name: "dLocal Card",
+        countries: [country],
+        currencies: [normalizedCurrency]
+      },
+      {
+        type: "pix",
+        provider: this.name,
+        name: "dLocal PIX",
+        countries: ["BR"],
+        currencies: ["BRL"]
+      },
+      {
+        type: "boleto",
+        provider: this.name,
+        name: "dLocal Boleto",
+        countries: ["BR"],
+        currencies: ["BRL"]
+      }
+    ];
+  }
+  async handleWebhook(payload, headers) {
+    const rawPayload = toRawString(payload);
+    this.verifyWebhook(rawPayload, headers);
+    let parsed;
+    try {
+      parsed = JSON.parse(rawPayload);
+    } catch {
+      throw new WebhookVerificationError(
+        "dLocal webhook payload is not valid JSON.",
+        {
+          context: {
+            provider: this.name
+          }
+        }
+      );
+    }
+    const providerEventId = parsed.id ?? `evt_${Date.now()}`;
+    return normalizeWebhookEvent(
+      this.name,
+      {
+        id: providerEventId,
+        providerEventId,
+        type: mapDLocalEventType(parsed.type ?? parsed.event),
+        transactionId: parsed.payment_id ?? parsed.transaction_id ?? readString3(asRecord3(parsed.data), "payment_id"),
+        data: parsed.data ?? {},
+        timestamp: timestampOrNow(parsed.timestamp ?? parsed.created_date)
+      },
+      parsed
+    );
+  }
+  verifyWebhook(rawPayload, headers) {
+    const secret = this.config.webhookSecret ?? this.config.secretKey;
+    const receivedSignature = readHeader(headers, "x-dlocal-signature") ?? readHeader(headers, "x-signature");
+    if (!receivedSignature) {
+      throw new WebhookVerificationError("Missing dLocal signature header.", {
+        context: {
+          provider: this.name
+        }
+      });
+    }
+    const computedSignature = createHmacDigest("sha256", secret, rawPayload);
+    if (!secureCompareHex(receivedSignature, computedSignature)) {
+      throw new WebhookVerificationError(
+        "dLocal webhook signature verification failed.",
+        {
+          context: {
+            provider: this.name
+          }
+        }
+      );
+    }
+  }
+  async createPayment(request, authorizeOnly) {
+    const body = {
+      amount: request.amount,
+      currency: request.currency.toUpperCase(),
+      capture: !authorizeOnly,
+      description: request.description,
+      metadata: request.metadata,
+      country: request.customer?.address?.country,
+      payer: {
+        name: request.customer?.name,
+        email: request.customer?.email,
+        document: request.customer?.document
+      },
+      ...mapPaymentMethod(request.paymentMethod)
+    };
+    const payment = await this.request({
+      operation: authorizeOnly ? "authorize" : "charge",
+      path: "/v1/payments",
+      method: "POST",
+      body
+    });
+    return this.normalizePaymentResult(payment, request);
+  }
+  normalizePaymentResult(payment, request, fallbackId) {
+    const transactionId = payment.payment_id ?? payment.id ?? fallbackId;
+    const status = mapDLocalStatus(payment.status);
+    return {
+      id: transactionId ?? `payment_${Date.now()}`,
+      status,
+      provider: this.name,
+      providerId: payment.id ?? transactionId ?? `provider_${Date.now()}`,
+      amount: payment.amount ?? request?.amount ?? 0,
+      currency: (payment.currency ?? request?.currency ?? "USD").toUpperCase(),
+      paymentMethod: {
+        type: payment.payment_method_id?.toLowerCase() ?? request?.paymentMethod.type ?? "card",
+        last4: payment.card?.last4
+      },
+      customer: request?.customer?.email ? {
+        email: request.customer.email
+      } : void 0,
+      metadata: request?.metadata ?? {},
+      routing: {
+        source: "local",
+        reason: "dlocal adapter request"
+      },
+      createdAt: timestampOrNow(payment.created_date),
+      providerMetadata: {
+        dlocalStatus: payment.status,
+        orderId: payment.order_id
+      }
+    };
+  }
+  buildHeaders(serializedBody, timestamp) {
+    const authPayload = `${this.config.xLogin}${timestamp}${serializedBody}`;
+    const signature = createHmacDigest(
+      "sha256",
+      this.config.secretKey,
+      authPayload
+    );
+    return {
+      "x-login": this.config.xLogin,
+      "x-trans-key": this.config.xTransKey,
+      "x-version": DLOCAL_API_VERSION,
+      "x-date": timestamp,
+      authorization: `V2-HMAC-SHA256, Signature: ${signature}`,
+      "content-type": "application/json"
+    };
+  }
+  async request(params) {
+    const serializedBody = params.body ? JSON.stringify(params.body) : "";
+    return requestJson({
+      provider: this.name,
+      fetchFn: this.config.fetchFn,
+      baseUrl: this.config.baseUrl,
+      path: params.path,
+      method: params.method,
+      timeoutMs: this.config.timeoutMs,
+      headers: this.buildHeaders(serializedBody, (/* @__PURE__ */ new Date()).toISOString()),
+      body: params.body
+    }).catch((error) => {
+      const record = asRecord3(error);
+      const hint = asRecord3(record?.hint);
+      const raw = asRecord3(hint?.raw);
+      throw {
+        ...record,
+        hint: {
+          ...hint,
+          providerCode: readString3(hint, "providerCode") ?? readString3(raw, "code") ?? readString3(raw, "error_code"),
+          providerMessage: readString3(hint, "providerMessage") ?? readString3(raw, "message") ?? readString3(record, "message") ?? "dLocal request failed.",
+          httpStatus: readNumber3(hint, "httpStatus") ?? readNumber3(record, "status"),
+          raw: error
+        },
+        operation: params.operation
+      };
+    });
+  }
+};
+
+// src/adapters/paystack-adapter.ts
+var DEFAULT_PAYSTACK_BASE_URL = "https://api.paystack.co";
+var DEFAULT_TIMEOUT_MS2 = 15e3;
+function asRecord4(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+  return value;
+}
+function readString4(source, key) {
+  if (!source) {
+    return void 0;
+  }
+  const value = source[key];
+  return typeof value === "string" && value.trim() ? value : void 0;
+}
+function readNumber4(source, key) {
+  if (!source) {
+    return void 0;
+  }
+  const value = source[key];
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function mapPaystackPaymentStatus(status) {
+  switch (status?.toLowerCase()) {
+    case "success":
+      return "completed";
+    case "pending":
+    case "ongoing":
+    case "queued":
+      return "pending";
+    case "abandoned":
+      return "cancelled";
+    case "failed":
+    case "reversed":
+      return "failed";
+    default:
+      return "failed";
+  }
+}
+function mapPaystackRefundStatus(status) {
+  switch (status?.toLowerCase()) {
+    case "processed":
+    case "success":
+      return "completed";
+    case "pending":
+      return "pending";
+    default:
+      return "failed";
+  }
+}
+function mapPaystackEventType(event) {
+  switch (event) {
+    case "charge.success":
+      return "payment.completed";
+    case "charge.failed":
+      return "payment.failed";
+    case "charge.pending":
+      return "payment.pending";
+    case "refund.processed":
+    case "refund.success":
+      return "payment.refunded";
+    case "refund.pending":
+      return "payment.partially_refunded";
+    case "dispute.create":
+    case "charge.dispute.create":
+      return "payment.disputed";
+    case "dispute.resolve":
+    case "charge.dispute.resolve":
+      return "payment.dispute_resolved";
+    case "transfer.success":
+      return "payout.completed";
+    case "transfer.failed":
+      return "payout.failed";
+    default:
+      return "payment.failed";
+  }
+}
+function mapPaymentMethod2(paymentMethod) {
+  if (paymentMethod.type === "card" && "token" in paymentMethod) {
+    return {
+      authorization_code: paymentMethod.token
+    };
+  }
+  if (paymentMethod.type === "card") {
+    return {
+      card: {
+        number: paymentMethod.number,
+        cvv: paymentMethod.cvc,
+        expiry_month: String(paymentMethod.expMonth).padStart(2, "0"),
+        expiry_year: String(paymentMethod.expYear)
+      }
+    };
+  }
+  if (paymentMethod.type === "bank_transfer") {
+    return {
+      bank: {
+        code: paymentMethod.bankCode,
+        account_number: paymentMethod.accountNumber
+      }
+    };
+  }
+  if (paymentMethod.type === "wallet") {
+    return {
+      mobile_money: {
+        provider: paymentMethod.walletType,
+        token: paymentMethod.token
+      }
+    };
+  }
+  return {
+    channel: paymentMethod.type
+  };
+}
+function timestampOrNow2(input) {
+  if (!input) {
+    return (/* @__PURE__ */ new Date()).toISOString();
+  }
+  const date = new Date(input);
+  return Number.isNaN(date.getTime()) ? (/* @__PURE__ */ new Date()).toISOString() : date.toISOString();
+}
+var PaystackAdapter = class _PaystackAdapter {
+  name = "paystack";
+  static supportedMethods = [
+    "card",
+    "bank_transfer",
+    "wallet"
+  ];
+  static supportedCurrencies = [
+    "NGN",
+    "GHS",
+    "ZAR",
+    "KES",
+    "USD"
+  ];
+  static supportedCountries = ["NG", "GH", "ZA", "KE"];
+  metadata = {
+    supportedMethods: _PaystackAdapter.supportedMethods,
+    supportedCurrencies: _PaystackAdapter.supportedCurrencies,
+    supportedCountries: _PaystackAdapter.supportedCountries
+  };
+  config;
+  constructor(rawConfig) {
+    const secretKey = typeof rawConfig.secretKey === "string" ? rawConfig.secretKey.trim() : "";
+    if (!secretKey) {
+      throw new VaultConfigError(
+        "Paystack adapter requires config.secretKey.",
+        {
+          code: "INVALID_CONFIGURATION",
+          context: {
+            provider: "paystack"
+          }
+        }
+      );
+    }
+    const baseUrl = typeof rawConfig.baseUrl === "string" && rawConfig.baseUrl.trim() ? rawConfig.baseUrl.trim() : DEFAULT_PAYSTACK_BASE_URL;
+    const timeoutMs = typeof rawConfig.timeoutMs === "number" && Number.isFinite(rawConfig.timeoutMs) && rawConfig.timeoutMs > 0 ? Math.floor(rawConfig.timeoutMs) : DEFAULT_TIMEOUT_MS2;
+    const customFetch = rawConfig.fetchFn;
+    const fetchFn = typeof customFetch === "function" ? customFetch : fetch;
+    this.config = {
+      secretKey,
+      baseUrl,
+      timeoutMs,
+      fetchFn,
+      webhookSecret: typeof rawConfig.webhookSecret === "string" ? rawConfig.webhookSecret : void 0
+    };
+  }
+  async charge(request) {
+    const payload = this.buildChargePayload(request, false);
+    const transaction = await this.request({
+      operation: "charge",
+      path: "/charge",
+      method: "POST",
+      body: payload
+    });
+    return this.normalizePaymentResult(transaction, request);
+  }
+  async authorize(request) {
+    const payload = this.buildChargePayload(request, true);
+    const transaction = await this.request({
+      operation: "authorize",
+      path: "/charge",
+      method: "POST",
+      body: payload
+    });
+    return this.normalizePaymentResult(transaction, request);
+  }
+  async capture(request) {
+    const current = await this.request({
+      operation: "capture.verify",
+      path: `/transaction/verify/${request.transactionId}`,
+      method: "GET"
+    });
+    const authorizationCode = current.authorization?.authorization_code;
+    const email = current.customer?.email;
+    if (!authorizationCode || !email) {
+      throw new VaultProviderError(
+        "Paystack capture requires an authorization code and customer email.",
+        {
+          code: "INVALID_REQUEST",
+          context: {
+            provider: this.name,
+            operation: "capture"
+          }
+        }
+      );
+    }
+    const charged = await this.request({
+      operation: "capture",
+      path: "/transaction/charge_authorization",
+      method: "POST",
+      body: {
+        authorization_code: authorizationCode,
+        email,
+        amount: request.amount ?? current.amount,
+        currency: current.currency
+      }
+    });
+    return this.normalizePaymentResult(charged);
+  }
+  async refund(request) {
+    const refund = await this.request({
+      operation: "refund",
+      path: "/refund",
+      method: "POST",
+      body: {
+        transaction: request.transactionId,
+        amount: request.amount
+      }
+    });
+    return {
+      id: String(refund.id ?? `refund_${Date.now()}`),
+      transactionId: String(refund.transaction ?? request.transactionId),
+      status: mapPaystackRefundStatus(refund.status),
+      amount: refund.amount ?? request.amount ?? 0,
+      currency: (refund.currency ?? "NGN").toUpperCase(),
+      provider: this.name,
+      providerId: String(refund.id ?? request.transactionId),
+      reason: refund.reason ?? request.reason,
+      createdAt: timestampOrNow2(refund.created_at)
+    };
+  }
+  async void(request) {
+    const refund = await this.refund({
+      transactionId: request.transactionId,
+      reason: "void"
+    });
+    return {
+      id: `void_${refund.id}`,
+      transactionId: request.transactionId,
+      status: refund.status === "completed" ? "completed" : "failed",
+      provider: this.name,
+      createdAt: refund.createdAt
+    };
+  }
+  async getStatus(transactionId) {
+    const transaction = await this.request({
+      operation: "getStatus",
+      path: `/transaction/verify/${transactionId}`,
+      method: "GET"
+    });
+    const status = mapPaystackPaymentStatus(transaction.status);
+    const timestamp = timestampOrNow2(
+      transaction.paid_at ?? transaction.created_at
+    );
+    return {
+      id: transaction.reference ?? transactionId,
+      status,
+      provider: this.name,
+      providerId: String(
+        transaction.id ?? transaction.reference ?? transactionId
+      ),
+      amount: transaction.amount ?? 0,
+      currency: (transaction.currency ?? "NGN").toUpperCase(),
+      history: [
+        {
+          status,
+          timestamp,
+          reason: transaction.gateway_response
+        }
+      ],
+      updatedAt: timestamp
+    };
+  }
+  async listPaymentMethods(country, currency) {
+    return [
+      {
+        type: "card",
+        provider: this.name,
+        name: "Paystack Card",
+        countries: [country],
+        currencies: [currency.toUpperCase()]
+      },
+      {
+        type: "bank_transfer",
+        provider: this.name,
+        name: "Paystack Bank Transfer",
+        countries: ["NG", "GH", "ZA", "KE"],
+        currencies: ["NGN", "GHS", "ZAR", "KES"]
+      }
+    ];
+  }
+  async handleWebhook(payload, headers) {
+    const rawPayload = toRawString(payload);
+    this.verifyWebhook(rawPayload, headers);
+    let parsed;
+    try {
+      parsed = JSON.parse(rawPayload);
+    } catch {
+      throw new WebhookVerificationError(
+        "Paystack webhook payload is not valid JSON.",
+        {
+          context: {
+            provider: this.name
+          }
+        }
+      );
+    }
+    const data = asRecord4(parsed.data);
+    const providerEventId = readString4(data, "id") ?? readString4(data, "reference") ?? `evt_${Date.now()}`;
+    return normalizeWebhookEvent(
+      this.name,
+      {
+        id: providerEventId,
+        providerEventId,
+        type: mapPaystackEventType(parsed.event),
+        transactionId: readString4(data, "reference") ?? (typeof readNumber4(data, "id") === "number" ? String(readNumber4(data, "id")) : void 0),
+        data: data ?? {},
+        timestamp: timestampOrNow2(readString4(data, "created_at"))
+      },
+      parsed
+    );
+  }
+  verifyWebhook(rawPayload, headers) {
+    const signature = readHeader(headers, "x-paystack-signature");
+    if (!signature) {
+      throw new WebhookVerificationError("Missing Paystack signature header.", {
+        context: {
+          provider: this.name
+        }
+      });
+    }
+    const secret = this.config.webhookSecret ?? this.config.secretKey;
+    const computed = createHmacDigest("sha512", secret, rawPayload);
+    if (!secureCompareHex(signature, computed)) {
+      throw new WebhookVerificationError(
+        "Paystack webhook signature verification failed.",
+        {
+          context: {
+            provider: this.name
+          }
+        }
+      );
+    }
+  }
+  buildChargePayload(request, authorizeOnly) {
+    const email = request.customer?.email;
+    if (!email) {
+      throw new VaultProviderError(
+        "Paystack charge requires customer.email in the request.",
+        {
+          code: "INVALID_REQUEST",
+          context: {
+            provider: this.name,
+            operation: authorizeOnly ? "authorize" : "charge"
+          }
+        }
+      );
+    }
+    return {
+      email,
+      amount: request.amount,
+      currency: request.currency.toUpperCase(),
+      metadata: {
+        ...request.metadata ?? {},
+        vaultsaas_intent: authorizeOnly ? "authorize" : "charge"
+      },
+      ...mapPaymentMethod2(request.paymentMethod)
+    };
+  }
+  normalizePaymentResult(transaction, request) {
+    const id = transaction.reference ?? String(transaction.id ?? `txn_${Date.now()}`);
+    return {
+      id,
+      status: mapPaystackPaymentStatus(transaction.status),
+      provider: this.name,
+      providerId: String(transaction.id ?? id),
+      amount: transaction.amount ?? request?.amount ?? 0,
+      currency: (transaction.currency ?? request?.currency ?? "NGN").toUpperCase(),
+      paymentMethod: {
+        type: request?.paymentMethod.type ?? "card",
+        last4: transaction.authorization?.last4,
+        brand: transaction.authorization?.brand,
+        expiryMonth: transaction.authorization?.exp_month ? Number(transaction.authorization.exp_month) : void 0,
+        expiryYear: transaction.authorization?.exp_year ? Number(transaction.authorization.exp_year) : void 0
+      },
+      customer: transaction.customer?.email || request?.customer?.email ? {
+        email: transaction.customer?.email ?? request?.customer?.email
+      } : void 0,
+      metadata: transaction.metadata ?? request?.metadata ?? {},
+      routing: {
+        source: "local",
+        reason: "paystack adapter request"
+      },
+      createdAt: timestampOrNow2(transaction.paid_at ?? transaction.created_at),
+      providerMetadata: {
+        paystackStatus: transaction.status,
+        gatewayResponse: transaction.gateway_response
+      }
+    };
+  }
+  async request(params) {
+    const envelope = await requestJson({
+      provider: this.name,
+      fetchFn: this.config.fetchFn,
+      baseUrl: this.config.baseUrl,
+      path: params.path,
+      method: params.method,
+      timeoutMs: this.config.timeoutMs,
+      headers: {
+        Authorization: `Bearer ${this.config.secretKey}`
+      },
+      body: params.body
+    }).catch((error) => {
+      const record = asRecord4(error);
+      const hint = asRecord4(record?.hint);
+      const raw = asRecord4(hint?.raw);
+      throw {
+        ...record,
+        hint: {
+          ...hint,
+          providerCode: readString4(hint, "providerCode") ?? readString4(raw, "code"),
+          providerMessage: readString4(hint, "providerMessage") ?? readString4(raw, "message") ?? readString4(record, "message") ?? "Paystack request failed.",
+          httpStatus: readNumber4(hint, "httpStatus") ?? readNumber4(record, "status"),
+          raw: error
+        },
+        operation: params.operation
+      };
+    });
+    if (!envelope.status) {
+      throw {
+        message: envelope.message || "Paystack rejected the request.",
+        hint: {
+          providerMessage: envelope.message,
+          providerCode: "paystack_error",
+          raw: envelope
+        },
+        operation: params.operation
+      };
+    }
+    return envelope.data;
+  }
+};
+
+// src/adapters/stripe-adapter.ts
+var DEFAULT_STRIPE_BASE_URL = "https://api.stripe.com";
+var DEFAULT_TIMEOUT_MS3 = 15e3;
+function asRecord5(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+  return value;
+}
+function readString5(source, key) {
+  if (!source) {
+    return void 0;
+  }
+  const value = source[key];
+  return typeof value === "string" && value.trim() ? value : void 0;
+}
+function toIsoTimestamp(unixSeconds) {
+  if (!unixSeconds || !Number.isFinite(unixSeconds)) {
+    return (/* @__PURE__ */ new Date()).toISOString();
+  }
+  return new Date(unixSeconds * 1e3).toISOString();
+}
+function mapStripeStatus(status) {
+  switch (status) {
+    case "succeeded":
+      return "completed";
+    case "requires_capture":
+      return "authorized";
+    case "requires_action":
+      return "requires_action";
+    case "processing":
+      return "pending";
+    case "canceled":
+      return "cancelled";
+    case "requires_payment_method":
+      return "declined";
+    case "requires_confirmation":
+      return "pending";
+    default:
+      return "failed";
+  }
+}
+function mapRefundStatus2(status) {
+  switch (status) {
+    case "succeeded":
+      return "completed";
+    case "pending":
+      return "pending";
+    default:
+      return "failed";
+  }
+}
+function buildStripePaymentMethodData(paymentMethod) {
+  if (paymentMethod.type === "card" && "token" in paymentMethod) {
+    return {
+      payment_method: paymentMethod.token,
+      payment_method_types: ["card"]
+    };
+  }
+  if (paymentMethod.type === "card") {
+    return {
+      payment_method_data: {
+        type: "card",
+        card: {
+          number: paymentMethod.number,
+          exp_month: paymentMethod.expMonth,
+          exp_year: paymentMethod.expYear,
+          cvc: paymentMethod.cvc
+        }
+      },
+      payment_method_types: ["card"]
+    };
+  }
+  if (paymentMethod.type === "wallet") {
+    return {
+      payment_method_types: [paymentMethod.walletType],
+      payment_method_data: {
+        type: paymentMethod.walletType,
+        wallet: {
+          token: paymentMethod.token
+        }
+      }
+    };
+  }
+  if (paymentMethod.type === "bank_transfer") {
+    return {
+      payment_method_types: ["customer_balance"],
+      payment_method_data: {
+        type: "customer_balance",
+        customer_balance: {
+          funding_type: "bank_transfer"
+        }
+      }
+    };
+  }
+  return {
+    payment_method_types: [paymentMethod.type]
+  };
+}
+function extractPaymentMethodSnapshot(request, intent) {
+  if (request?.paymentMethod.type === "card" && "number" in request.paymentMethod) {
+    return {
+      type: "card",
+      last4: request.paymentMethod.number.slice(-4),
+      expiryMonth: request.paymentMethod.expMonth,
+      expiryYear: request.paymentMethod.expYear
+    };
+  }
+  if (request?.paymentMethod.type === "card" && "token" in request.paymentMethod) {
+    return {
+      type: "card"
+    };
+  }
+  if (request) {
+    return {
+      type: request.paymentMethod.type
+    };
+  }
+  return {
+    type: intent.payment_method_types?.[0] ?? "card"
+  };
+}
+function mapStripeEventType(type) {
+  switch (type) {
+    case "payment_intent.succeeded":
+      return "payment.completed";
+    case "payment_intent.payment_failed":
+      return "payment.failed";
+    case "payment_intent.processing":
+      return "payment.pending";
+    case "payment_intent.requires_action":
+      return "payment.requires_action";
+    case "charge.refunded":
+      return "payment.refunded";
+    case "charge.dispute.created":
+      return "payment.disputed";
+    case "charge.dispute.closed":
+      return "payment.dispute_resolved";
+    case "payout.paid":
+      return "payout.completed";
+    case "payout.failed":
+      return "payout.failed";
+    default:
+      return "payment.failed";
+  }
+}
+function extractStripeTransactionId(webhook) {
+  const object = asRecord5(webhook.data?.object);
+  return readString5(object, "payment_intent") ?? readString5(object, "id") ?? readString5(object, "charge");
+}
+var StripeAdapter = class _StripeAdapter {
+  name = "stripe";
+  static supportedMethods = [
+    "card",
+    "bank_transfer",
+    "wallet"
+  ];
+  static supportedCurrencies = [
+    "USD",
+    "EUR",
+    "GBP",
+    "CAD",
+    "AUD",
+    "JPY",
+    "CHF",
+    "SEK",
+    "NOK",
+    "DKK",
+    "NZD",
+    "SGD",
+    "HKD",
+    "MXN",
+    "BRL",
+    "PLN",
+    "CZK",
+    "HUF",
+    "RON",
+    "BGN",
+    "INR",
+    "MYR",
+    "THB"
+  ];
+  static supportedCountries = [
+    "US",
+    "GB",
+    "DE",
+    "FR",
+    "CA",
+    "AU",
+    "JP",
+    "IT",
+    "ES",
+    "NL",
+    "BE",
+    "AT",
+    "CH",
+    "SE",
+    "NO",
+    "DK",
+    "FI",
+    "IE",
+    "PT",
+    "LU",
+    "NZ",
+    "SG",
+    "HK",
+    "MY",
+    "MX",
+    "BR",
+    "PL",
+    "CZ",
+    "HU",
+    "RO",
+    "BG",
+    "HR",
+    "CY",
+    "EE",
+    "GR",
+    "LV",
+    "LT",
+    "MT",
+    "SK",
+    "SI",
+    "IN",
+    "TH"
+  ];
+  metadata = {
+    supportedMethods: _StripeAdapter.supportedMethods,
+    supportedCurrencies: _StripeAdapter.supportedCurrencies,
+    supportedCountries: _StripeAdapter.supportedCountries
+  };
+  config;
+  constructor(rawConfig) {
+    const apiKey = typeof rawConfig.apiKey === "string" ? rawConfig.apiKey.trim() : "";
+    if (!apiKey) {
+      throw new VaultConfigError("Stripe adapter requires config.apiKey.", {
+        code: "INVALID_CONFIGURATION",
+        context: {
+          provider: "stripe"
+        }
+      });
+    }
+    const baseUrl = typeof rawConfig.baseUrl === "string" && rawConfig.baseUrl.trim() ? rawConfig.baseUrl.trim() : DEFAULT_STRIPE_BASE_URL;
+    const timeoutMs = typeof rawConfig.timeoutMs === "number" && Number.isFinite(rawConfig.timeoutMs) && rawConfig.timeoutMs > 0 ? Math.floor(rawConfig.timeoutMs) : DEFAULT_TIMEOUT_MS3;
+    const customFetch = rawConfig.fetchFn;
+    const fetchFn = typeof customFetch === "function" ? customFetch : fetch;
+    this.config = {
+      apiKey,
+      baseUrl,
+      timeoutMs,
+      fetchFn,
+      webhookSecret: typeof rawConfig.webhookSecret === "string" ? rawConfig.webhookSecret : void 0
+    };
+  }
+  async charge(request) {
+    return this.createPaymentIntent(request, "automatic");
+  }
+  async authorize(request) {
+    return this.createPaymentIntent(request, "manual");
+  }
+  async capture(request) {
+    const body = {};
+    if (request.amount !== void 0) {
+      body.amount_to_capture = request.amount;
+    }
+    const intent = await this.postForm(
+      `/v1/payment_intents/${request.transactionId}/capture`,
+      body,
+      "capture"
+    );
+    return this.normalizePaymentResult(intent);
+  }
+  async refund(request) {
+    const body = {
+      payment_intent: request.transactionId
+    };
+    if (request.amount !== void 0) {
+      body.amount = request.amount;
+    }
+    if (request.reason) {
+      body.reason = request.reason;
+    }
+    const refund = await this.postForm(
+      "/v1/refunds",
+      body,
+      "refund"
+    );
+    return {
+      id: refund.id,
+      transactionId: refund.payment_intent ?? request.transactionId,
+      status: mapRefundStatus2(refund.status),
+      amount: refund.amount,
+      currency: refund.currency.toUpperCase(),
+      provider: this.name,
+      providerId: refund.charge ?? refund.id,
+      reason: refund.reason,
+      createdAt: toIsoTimestamp(refund.created)
+    };
+  }
+  async void(request) {
+    const intent = await this.postForm(
+      `/v1/payment_intents/${request.transactionId}/cancel`,
+      {},
+      "void"
+    );
+    return {
+      id: `void_${intent.id}`,
+      transactionId: request.transactionId,
+      status: intent.status === "canceled" ? "completed" : "failed",
+      provider: this.name,
+      createdAt: toIsoTimestamp(intent.created)
+    };
+  }
+  async getStatus(transactionId) {
+    const intent = await this.get(
+      `/v1/payment_intents/${transactionId}`,
+      "getStatus"
+    );
+    const status = mapStripeStatus(intent.status);
+    const timestamp = toIsoTimestamp(intent.created);
+    return {
+      id: intent.id,
+      status,
+      provider: this.name,
+      providerId: intent.latest_charge ?? intent.id,
+      amount: intent.amount,
+      currency: intent.currency.toUpperCase(),
+      history: [
+        {
+          status,
+          timestamp,
+          reason: `stripe status: ${intent.status}`
+        }
+      ],
+      updatedAt: timestamp
+    };
+  }
+  async listPaymentMethods(country, currency) {
+    return [
+      {
+        type: "card",
+        provider: this.name,
+        name: "Stripe Card",
+        countries: [country],
+        currencies: [currency.toUpperCase()]
+      },
+      {
+        type: "wallet",
+        provider: this.name,
+        name: "Stripe Wallets",
+        countries: [country],
+        currencies: [currency.toUpperCase()]
+      }
+    ];
+  }
+  async handleWebhook(payload, headers) {
+    const rawPayload = toRawString(payload);
+    this.verifyWebhook(rawPayload, headers);
+    let parsed;
+    try {
+      parsed = JSON.parse(rawPayload);
+    } catch {
+      throw new WebhookVerificationError(
+        "Stripe webhook payload is not valid JSON.",
+        {
+          context: {
+            provider: this.name
+          }
+        }
+      );
+    }
+    const transactionId = extractStripeTransactionId(parsed);
+    const providerEventId = parsed.id ?? `evt_${Date.now()}`;
+    return normalizeWebhookEvent(
+      this.name,
+      {
+        id: providerEventId,
+        providerEventId,
+        type: mapStripeEventType(parsed.type),
+        transactionId,
+        data: asRecord5(parsed.data?.object) ?? {},
+        timestamp: toIsoTimestamp(parsed.created)
+      },
+      parsed
+    );
+  }
+  verifyWebhook(rawPayload, headers) {
+    if (!this.config.webhookSecret) {
+      throw new WebhookVerificationError(
+        "Stripe webhook secret is not configured.",
+        {
+          context: {
+            provider: this.name
+          }
+        }
+      );
+    }
+    const signature = readHeader(headers, "stripe-signature");
+    if (!signature) {
+      throw new WebhookVerificationError("Missing Stripe signature header.", {
+        context: {
+          provider: this.name
+        }
+      });
+    }
+    const components = signature.split(",").map((part) => part.trim());
+    let timestamp;
+    const signatures = [];
+    for (const component of components) {
+      const [key, value] = component.split("=");
+      if (!key || !value) {
+        continue;
+      }
+      if (key === "t") {
+        timestamp = value;
+      } else if (key === "v1") {
+        signatures.push(value);
+      }
+    }
+    if (!timestamp || signatures.length === 0) {
+      throw new WebhookVerificationError(
+        "Stripe signature header is malformed.",
+        {
+          context: {
+            provider: this.name
+          }
+        }
+      );
+    }
+    const timestampNum = Number(timestamp);
+    if (!Number.isFinite(timestampNum)) {
+      throw new WebhookVerificationError(
+        "Stripe webhook timestamp is not a valid number.",
+        {
+          context: {
+            provider: this.name
+          }
+        }
+      );
+    }
+    const ageMs = Date.now() - timestampNum * 1e3;
+    const toleranceMs = 5 * 60 * 1e3;
+    if (ageMs > toleranceMs) {
+      throw new WebhookVerificationError(
+        "Stripe webhook timestamp is too old (exceeds 5-minute tolerance). Possible replay attack.",
+        {
+          context: {
+            provider: this.name,
+            timestampAge: `${Math.round(ageMs / 1e3)}s`
+          }
+        }
+      );
+    }
+    const computed = createHmacDigest(
+      "sha256",
+      this.config.webhookSecret,
+      `${timestamp}.${rawPayload}`
+    );
+    const verified = signatures.some(
+      (item) => secureCompareHex(item, computed)
+    );
+    if (!verified) {
+      throw new WebhookVerificationError(
+        "Stripe webhook signature verification failed.",
+        {
+          context: {
+            provider: this.name
+          }
+        }
+      );
+    }
+  }
+  async createPaymentIntent(request, captureMethod) {
+    const body = {
+      amount: request.amount,
+      currency: request.currency.toLowerCase(),
+      confirm: true,
+      capture_method: captureMethod,
+      metadata: request.metadata ?? {},
+      ...buildStripePaymentMethodData(request.paymentMethod)
+    };
+    if (request.description) {
+      body.description = request.description;
+    }
+    if (request.customer?.email) {
+      body.receipt_email = request.customer.email;
+    }
+    if (request.customer?.name) {
+      body["shipping[name]"] = request.customer.name;
+    }
+    const intent = await this.postForm(
+      "/v1/payment_intents",
+      body,
+      captureMethod === "manual" ? "authorize" : "charge"
+    );
+    return this.normalizePaymentResult(intent, request);
+  }
+  normalizePaymentResult(intent, request) {
+    return {
+      id: intent.id,
+      status: mapStripeStatus(intent.status),
+      provider: this.name,
+      providerId: intent.latest_charge ?? intent.id,
+      amount: intent.amount,
+      currency: intent.currency.toUpperCase(),
+      paymentMethod: extractPaymentMethodSnapshot(request, intent),
+      customer: request?.customer?.email ? {
+        email: request.customer.email
+      } : void 0,
+      metadata: {
+        ...request?.metadata ?? {},
+        ...intent.metadata ?? {}
+      },
+      routing: {
+        source: "local",
+        reason: "stripe adapter request"
+      },
+      createdAt: toIsoTimestamp(intent.created),
+      providerMetadata: {
+        stripeStatus: intent.status,
+        paymentMethod: intent.payment_method
+      }
+    };
+  }
+  async get(path, operation) {
+    return requestJson({
+      provider: this.name,
+      fetchFn: this.config.fetchFn,
+      baseUrl: this.config.baseUrl,
+      path,
+      method: "GET",
+      timeoutMs: this.config.timeoutMs,
+      headers: {
+        Authorization: `Bearer ${this.config.apiKey}`
+      }
+    }).catch((error) => {
+      throw {
+        ...asRecord5(error),
+        hint: {
+          ...asRecord5(asRecord5(error)?.hint) ?? {},
+          providerMessage: readString5(asRecord5(error), "message") ?? "Stripe request failed.",
+          raw: error
+        },
+        operation
+      };
+    });
+  }
+  async postForm(path, body, operation) {
+    const formBody = encodeFormBody(body);
+    const payload = formBody.toString();
+    return requestJson({
+      provider: this.name,
+      fetchFn: this.config.fetchFn,
+      baseUrl: this.config.baseUrl,
+      path,
+      method: "POST",
+      timeoutMs: this.config.timeoutMs,
+      headers: {
+        Authorization: `Bearer ${this.config.apiKey}`,
+        "content-type": "application/x-www-form-urlencoded"
+      },
+      body: payload
+    }).catch((error) => {
+      const record = asRecord5(error);
+      const hint = asRecord5(record?.hint);
+      throw {
+        ...record,
+        hint: {
+          ...hint,
+          providerCode: readString5(hint, "providerCode") ?? readString5(record, "providerCode"),
+          providerMessage: readString5(hint, "providerMessage") ?? readString5(record, "message") ?? "Stripe request failed.",
+          declineCode: readString5(hint, "declineCode") ?? readString5(asRecord5(hint?.raw), "decline_code"),
+          raw: error
+        },
+        operation
+      };
+    });
+  }
+};
+
+// src/idempotency/memory-store.ts
+var MemoryIdempotencyStore = class {
+  records = /* @__PURE__ */ new Map();
+  get(key) {
+    const record = this.records.get(key);
+    if (!record) {
+      return null;
+    }
+    if (record.expiresAt <= Date.now()) {
+      this.records.delete(key);
+      return null;
+    }
+    return record;
+  }
+  set(record) {
+    this.records.set(record.key, record);
+  }
+  delete(key) {
+    this.records.delete(key);
+  }
+  clearExpired(now = Date.now()) {
+    for (const [key, record] of this.records.entries()) {
+      if (record.expiresAt <= now) {
+        this.records.delete(key);
+      }
+    }
+  }
+};
+
+// src/idempotency/hash.ts
+var import_node_crypto2 = require("crypto");
+function stableSerialize(value) {
+  if (value === null || value === void 0) {
+    return "null";
+  }
+  if (typeof value !== "object") {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => stableSerialize(item)).join(",")}]`;
+  }
+  const entries = Object.entries(value).sort(([left], [right]) => left.localeCompare(right)).map(([key, item]) => `${JSON.stringify(key)}:${stableSerialize(item)}`);
+  return `{${entries.join(",")}}`;
+}
+function hashIdempotencyPayload(payload) {
+  const serialized = stableSerialize(payload);
+  return (0, import_node_crypto2.createHash)("sha256").update(serialized).digest("hex");
+}
+
+// src/idempotency/store.ts
+var DEFAULT_IDEMPOTENCY_TTL_MS = 864e5;
+
+// src/platform/buffer.ts
+var BatchBuffer = class {
+  constructor(maxSize) {
+    this.maxSize = maxSize;
+  }
+  items = [];
+  push(item) {
+    this.items.push(item);
+    if (this.items.length >= this.maxSize) {
+      return this.flush();
+    }
+    return null;
+  }
+  flush() {
+    const snapshot = [...this.items];
+    this.items.length = 0;
+    return snapshot;
+  }
+  size() {
+    return this.items.length;
+  }
+};
+
+// src/platform/connector.ts
+var PlatformConnector = class _PlatformConnector {
+  static DEFAULT_BASE_URL = "https://api.vaultsaas.com";
+  static DEFAULT_TIMEOUT_MS = 75;
+  static DEFAULT_BATCH_SIZE = 50;
+  static DEFAULT_FLUSH_INTERVAL_MS = 2e3;
+  static DEFAULT_MAX_RETRIES = 2;
+  static DEFAULT_INITIAL_BACKOFF_MS = 100;
+  config;
+  transactionBuffer;
+  webhookBuffer;
+  fetchFn;
+  logger;
+  flushTimer;
+  transactionSendQueue = Promise.resolve();
+  webhookSendQueue = Promise.resolve();
+  constructor(config) {
+    this.config = {
+      ...config,
+      baseUrl: config.baseUrl ?? _PlatformConnector.DEFAULT_BASE_URL,
+      timeoutMs: config.timeoutMs ?? _PlatformConnector.DEFAULT_TIMEOUT_MS,
+      batchSize: config.batchSize ?? _PlatformConnector.DEFAULT_BATCH_SIZE,
+      flushIntervalMs: config.flushIntervalMs ?? _PlatformConnector.DEFAULT_FLUSH_INTERVAL_MS,
+      maxRetries: config.maxRetries ?? _PlatformConnector.DEFAULT_MAX_RETRIES,
+      initialBackoffMs: config.initialBackoffMs ?? _PlatformConnector.DEFAULT_INITIAL_BACKOFF_MS
+    };
+    this.fetchFn = config.fetchFn ?? fetch;
+    this.logger = config.logger;
+    this.transactionBuffer = new BatchBuffer(this.config.batchSize);
+    this.webhookBuffer = new BatchBuffer(this.config.batchSize);
+    this.flushTimer = setInterval(() => {
+      void this.flush().catch((error) => {
+        this.warn("Platform connector periodic flush failed.", {
+          error: error instanceof Error ? error.message : String(error)
+        });
+      });
+    }, this.config.flushIntervalMs);
+    if (typeof this.flushTimer.unref === "function") {
+      this.flushTimer.unref();
+    }
+  }
+  close() {
+    clearInterval(this.flushTimer);
+  }
+  async decideRouting(request) {
+    try {
+      const response = await this.postJson({
+        path: "/v1/routing/decide",
+        body: request,
+        timeoutMs: this.config.timeoutMs,
+        maxRetries: 0
+      });
+      const decision = this.normalizeRoutingDecision(response);
+      if (!decision) {
+        return null;
+      }
+      return decision.provider ? decision : null;
+    } catch (error) {
+      throw new VaultNetworkError("Platform routing decision failed.", {
+        code: "PLATFORM_UNREACHABLE",
+        context: {
+          endpoint: "/v1/routing/decide",
+          operation: "decideRouting",
+          cause: error instanceof Error ? error.message : String(error)
+        }
+      });
+    }
+  }
+  queueTransactionReport(transaction) {
+    const batch = this.transactionBuffer.push(transaction);
+    if (!batch) {
+      return;
+    }
+    this.enqueueTransactionBatch(batch);
+  }
+  queueWebhookEvent(event) {
+    const batch = this.webhookBuffer.push(event);
+    if (!batch) {
+      return;
+    }
+    this.enqueueWebhookBatch(batch);
+  }
+  async flush() {
+    const pendingTransactions = this.transactionBuffer.flush();
+    if (pendingTransactions.length > 0) {
+      this.enqueueTransactionBatch(pendingTransactions);
+    }
+    const pendingWebhookEvents = this.webhookBuffer.flush();
+    if (pendingWebhookEvents.length > 0) {
+      this.enqueueWebhookBatch(pendingWebhookEvents);
+    }
+    await Promise.all([this.transactionSendQueue, this.webhookSendQueue]);
+  }
+  enqueueTransactionBatch(batch) {
+    this.transactionSendQueue = this.transactionSendQueue.then(async () => {
+      try {
+        await this.postJson({
+          path: "/v1/transactions/report",
+          body: { transactions: batch }
+        });
+      } catch (error) {
+        this.warn("Failed to report transactions batch to platform.", {
+          endpoint: "/v1/transactions/report",
+          batchSize: batch.length,
+          error: error instanceof Error ? error.message : String(error)
+        });
+      }
+    });
+  }
+  enqueueWebhookBatch(batch) {
+    this.webhookSendQueue = this.webhookSendQueue.then(async () => {
+      try {
+        await this.postJson({
+          path: "/v1/events/webhook",
+          body: { events: batch }
+        });
+      } catch (error) {
+        this.warn("Failed to forward webhook batch to platform.", {
+          endpoint: "/v1/events/webhook",
+          batchSize: batch.length,
+          error: error instanceof Error ? error.message : String(error)
+        });
+      }
+    });
+  }
+  async postJson(options) {
+    const maxRetries = options.maxRetries ?? this.config.maxRetries;
+    const timeoutMs = options.timeoutMs ?? this.config.timeoutMs;
+    let attempt = 0;
+    while (attempt <= maxRetries) {
+      attempt += 1;
+      try {
+        const response = await this.fetchWithTimeout(options.path, {
+          method: "POST",
+          body: JSON.stringify(options.body),
+          timeoutMs
+        });
+        if (!response.ok) {
+          if (attempt <= maxRetries && (response.status >= 500 || response.status === 429)) {
+            await this.delay(this.backoffForAttempt(attempt));
+            continue;
+          }
+          throw new Error(`platform status ${response.status}`);
+        }
+        const contentType = response.headers.get("content-type");
+        if (contentType?.includes("application/json")) {
+          return await response.json();
+        }
+        return {};
+      } catch (error) {
+        if (attempt > maxRetries) {
+          throw error;
+        }
+        this.debug("Retrying platform request after failure.", {
+          endpoint: options.path,
+          attempt,
+          maxRetries,
+          error: error instanceof Error ? error.message : String(error)
+        });
+        await this.delay(this.backoffForAttempt(attempt));
+      }
+    }
+    throw new Error("Platform request exhausted retries.");
+  }
+  async fetchWithTimeout(path, options) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => {
+      controller.abort();
+    }, options.timeoutMs);
+    try {
+      const response = await this.fetchFn(this.urlFor(path), {
+        method: options.method,
+        headers: {
+          authorization: `Bearer ${this.config.apiKey}`,
+          "content-type": "application/json"
+        },
+        body: options.body,
+        signal: controller.signal
+      });
+      return response;
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+  normalizeRoutingDecision(input) {
+    if (!input || typeof input !== "object" || Array.isArray(input)) {
+      return null;
+    }
+    const data = input;
+    return {
+      provider: typeof data.provider === "string" ? data.provider : null,
+      source: typeof data.source === "string" ? data.source : void 0,
+      reason: typeof data.reason === "string" ? data.reason : void 0,
+      decisionId: typeof data.decisionId === "string" ? data.decisionId : void 0,
+      ttlMs: typeof data.ttlMs === "number" ? data.ttlMs : void 0,
+      cascade: Array.isArray(data.cascade) ? data.cascade.filter(
+        (value) => typeof value === "string"
+      ) : void 0
+    };
+  }
+  backoffForAttempt(attempt) {
+    return this.config.initialBackoffMs * 2 ** (attempt - 1);
+  }
+  urlFor(path) {
+    const base = this.config.baseUrl.replace(/\/+$/, "");
+    return `${base}${path}`;
+  }
+  async delay(ms) {
+    await new Promise((resolve) => {
+      setTimeout(resolve, ms);
+    });
+  }
+  debug(message, context) {
+    this.logger?.debug(message, context);
+  }
+  warn(message, context) {
+    this.logger?.warn(message, context);
+  }
+};
+
+// src/router/rule-evaluator.ts
+function matchesValue(ruleValue, input) {
+  if (input === void 0) {
+    return false;
+  }
+  return Array.isArray(ruleValue) ? ruleValue.includes(input) : ruleValue === input;
+}
+function ruleMatchesContext(rule, context) {
+  const { match } = rule;
+  if (match.default) {
+    return true;
+  }
+  if (match.country && !matchesValue(match.country, context.country)) {
+    return false;
+  }
+  if (match.currency && !matchesValue(match.currency, context.currency)) {
+    return false;
+  }
+  if (match.paymentMethod && !matchesValue(match.paymentMethod, context.paymentMethod)) {
+    return false;
+  }
+  if (match.amountMin !== void 0 && (context.amount ?? Number.NEGATIVE_INFINITY) < match.amountMin) {
+    return false;
+  }
+  if (match.amountMax !== void 0 && (context.amount ?? Number.POSITIVE_INFINITY) > match.amountMax) {
+    return false;
+  }
+  if (match.metadata) {
+    for (const [key, expected] of Object.entries(match.metadata)) {
+      if (context.metadata?.[key] !== expected) {
+        return false;
+      }
+    }
+  }
+  return true;
+}
+
+// src/router/router.ts
+var Router = class {
+  rules;
+  random;
+  adapterMetadata;
+  logger;
+  constructor(rules, options = {}) {
+    this.rules = [...rules];
+    this.random = options.random ?? Math.random;
+    this.adapterMetadata = options.adapterMetadata ?? {};
+    this.logger = options.logger;
+    if (!this.rules.some((rule) => rule.match.default)) {
+      throw new VaultRoutingError(
+        "Routing rules must include a default fallback rule."
+      );
+    }
+  }
+  decide(context) {
+    if (context.providerOverride) {
+      if (context.exclude?.includes(context.providerOverride)) {
+        return null;
+      }
+      if (!this.providerSupportsContext(context.providerOverride, context)) {
+        return null;
+      }
+      return {
+        provider: context.providerOverride,
+        reason: `provider override selected ${context.providerOverride}`,
+        rule: {
+          provider: context.providerOverride,
+          match: {
+            default: true
+          }
+        }
+      };
+    }
+    for (let index = 0; index < this.rules.length; index += 1) {
+      const rule = this.rules[index];
+      if (!rule) {
+        continue;
+      }
+      if (context.exclude?.includes(rule.provider)) {
+        continue;
+      }
+      if (!ruleMatchesContext(rule, context)) {
+        continue;
+      }
+      if (!this.providerSupportsContext(rule.provider, context)) {
+        continue;
+      }
+      if (rule.weight !== void 0) {
+        const weightedCandidates = this.getWeightedCandidates(index, context);
+        if (weightedCandidates.length > 0) {
+          const selected = this.selectWeightedRule(weightedCandidates);
+          return {
+            provider: selected.rule.provider,
+            reason: this.buildWeightedReason(
+              selected,
+              weightedCandidates.length
+            ),
+            rule: selected.rule
+          };
+        }
+      }
+      return {
+        provider: rule.provider,
+        reason: this.buildRuleReason(rule, index),
+        rule
+      };
+    }
+    return null;
+  }
+  providerSupportsContext(provider, context) {
+    const meta = this.adapterMetadata[provider];
+    if (!meta) {
+      return true;
+    }
+    if (context.paymentMethod && meta.supportedMethods.length > 0 && !meta.supportedMethods.includes(context.paymentMethod)) {
+      this.logger?.warn(
+        `Provider "${provider}" does not support payment method "${context.paymentMethod}". Skipping.`,
+        {
+          provider,
+          paymentMethod: context.paymentMethod,
+          supportedMethods: [...meta.supportedMethods]
+        }
+      );
+      return false;
+    }
+    if (context.currency && meta.supportedCurrencies.length > 0 && !meta.supportedCurrencies.includes(context.currency)) {
+      this.logger?.warn(
+        `Provider "${provider}" does not support currency "${context.currency}". Skipping.`,
+        {
+          provider,
+          currency: context.currency,
+          supportedCurrencies: [...meta.supportedCurrencies]
+        }
+      );
+      return false;
+    }
+    if (context.country && meta.supportedCountries.length > 0 && !meta.supportedCountries.includes(context.country)) {
+      this.logger?.warn(
+        `Provider "${provider}" does not support country "${context.country}". Skipping.`,
+        {
+          provider,
+          country: context.country,
+          supportedCountries: [...meta.supportedCountries]
+        }
+      );
+      return false;
+    }
+    return true;
+  }
+  getWeightedCandidates(startIndex, context) {
+    const candidates = [];
+    for (let index = startIndex; index < this.rules.length; index += 1) {
+      const rule = this.rules[index];
+      if (!rule) {
+        continue;
+      }
+      if (!ruleMatchesContext(rule, context)) {
+        break;
+      }
+      if (rule.weight === void 0) {
+        break;
+      }
+      if (context.exclude?.includes(rule.provider)) {
+        continue;
+      }
+      if (!this.providerSupportsContext(rule.provider, context)) {
+        continue;
+      }
+      if (rule.weight > 0) {
+        candidates.push({
+          index,
+          rule
+        });
+      }
+    }
+    return candidates;
+  }
+  selectWeightedRule(candidates) {
+    const totalWeight = candidates.reduce(
+      (acc, candidate) => acc + (candidate.rule.weight ?? 0),
+      0
+    );
+    const randomValue = this.random() * totalWeight;
+    let cumulativeWeight = 0;
+    for (const candidate of candidates) {
+      cumulativeWeight += candidate.rule.weight ?? 0;
+      if (randomValue < cumulativeWeight) {
+        return candidate;
+      }
+    }
+    const fallback = candidates[candidates.length - 1];
+    if (!fallback) {
+      throw new VaultRoutingError(
+        "No weighted routing candidates were available."
+      );
+    }
+    return fallback;
+  }
+  buildRuleReason(rule, index) {
+    if (rule.match.default) {
+      return `default fallback rule matched at index ${index}`;
+    }
+    const criteria = this.getMatchCriteria(rule);
+    if (criteria.length > 0) {
+      return `rule matched at index ${index} using ${criteria.join(", ")}`;
+    }
+    return `rule matched at index ${index}`;
+  }
+  buildWeightedReason(selected, candidateCount) {
+    return `weighted selection chose provider ${selected.rule.provider} from ${candidateCount} candidates starting at index ${selected.index}`;
+  }
+  getMatchCriteria(rule) {
+    const criteria = [];
+    if (rule.match.currency !== void 0) {
+      criteria.push("currency");
+    }
+    if (rule.match.country !== void 0) {
+      criteria.push("country");
+    }
+    if (rule.match.paymentMethod !== void 0) {
+      criteria.push("paymentMethod");
+    }
+    if (rule.match.amountMin !== void 0 || rule.match.amountMax !== void 0) {
+      criteria.push("amount");
+    }
+    if (rule.match.metadata !== void 0) {
+      criteria.push("metadata");
+    }
+    return criteria;
+  }
+};
+
+// src/client/config-validation.ts
+var LOG_LEVELS = /* @__PURE__ */ new Set(["silent", "error", "warn", "info", "debug"]);
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function assertPositiveFiniteInteger(value, field, context) {
+  if (!Number.isFinite(value) || !Number.isInteger(value) || value <= 0) {
+    throw new VaultConfigError(`${field} must be a positive integer.`, context);
+  }
+}
+function validateProviderConfig(name, provider) {
+  if (!provider || typeof provider !== "object") {
+    throw new VaultConfigError("Provider configuration must be an object.", {
+      provider: name
+    });
+  }
+  if (typeof provider.adapter !== "function") {
+    throw new VaultConfigError("Provider adapter constructor is missing.", {
+      provider: name
+    });
+  }
+  const adapter = provider.adapter;
+  if (!Array.isArray(adapter.supportedMethods)) {
+    throw new VaultConfigError(
+      "Provider adapter must declare static supportedMethods.",
+      {
+        provider: name
+      }
+    );
+  }
+  if (!Array.isArray(adapter.supportedCurrencies)) {
+    throw new VaultConfigError(
+      "Provider adapter must declare static supportedCurrencies.",
+      {
+        provider: name
+      }
+    );
+  }
+  if (!Array.isArray(adapter.supportedCountries)) {
+    throw new VaultConfigError(
+      "Provider adapter must declare static supportedCountries.",
+      {
+        provider: name
+      }
+    );
+  }
+  if (!isPlainObject(provider.config)) {
+    throw new VaultConfigError("Provider config must be a plain object.", {
+      provider: name
+    });
+  }
+  if (provider.priority !== void 0 && (!Number.isFinite(provider.priority) || !Number.isInteger(provider.priority))) {
+    throw new VaultConfigError("Provider priority must be an integer.", {
+      provider: name
+    });
+  }
+}
+function validateLogger(logger) {
+  const methods = [
+    "error",
+    "warn",
+    "info",
+    "debug"
+  ];
+  for (const method of methods) {
+    if (typeof logger[method] !== "function") {
+      throw new VaultConfigError("Logger implementation is missing a method.", {
+        method
+      });
+    }
+  }
+}
+function validateRoutingRules(rules, providers) {
+  if (!Array.isArray(rules) || rules.length === 0) {
+    throw new VaultConfigError(
+      "Routing rules must include at least one rule when routing is configured."
+    );
+  }
+  let hasDefaultRule = false;
+  for (const [index, rule] of rules.entries()) {
+    if (!rule || typeof rule !== "object") {
+      throw new VaultConfigError("Routing rule must be an object.", {
+        index
+      });
+    }
+    if (!rule.provider || typeof rule.provider !== "string") {
+      throw new VaultConfigError(
+        "Routing rule provider must be a non-empty string.",
+        {
+          index
+        }
+      );
+    }
+    const provider = providers[rule.provider];
+    if (!provider || provider.enabled === false) {
+      throw new VaultConfigError(
+        "Routing rule provider must reference an enabled configured provider.",
+        {
+          index,
+          provider: rule.provider
+        }
+      );
+    }
+    if (!rule.match || typeof rule.match !== "object") {
+      throw new VaultConfigError(
+        "Routing rule match configuration is required.",
+        {
+          index,
+          provider: rule.provider
+        }
+      );
+    }
+    if (rule.match.default) {
+      hasDefaultRule = true;
+    }
+    if (rule.match.amountMin !== void 0 && (!Number.isFinite(rule.match.amountMin) || rule.match.amountMin < 0)) {
+      throw new VaultConfigError(
+        "Routing rule amountMin must be a non-negative number.",
+        {
+          index,
+          provider: rule.provider
+        }
+      );
+    }
+    if (rule.match.amountMax !== void 0 && (!Number.isFinite(rule.match.amountMax) || rule.match.amountMax < 0)) {
+      throw new VaultConfigError(
+        "Routing rule amountMax must be a non-negative number.",
+        {
+          index,
+          provider: rule.provider
+        }
+      );
+    }
+    if (rule.match.amountMin !== void 0 && rule.match.amountMax !== void 0 && rule.match.amountMin > rule.match.amountMax) {
+      throw new VaultConfigError(
+        "Routing rule amountMin cannot exceed amountMax.",
+        {
+          index,
+          provider: rule.provider
+        }
+      );
+    }
+    if (rule.weight !== void 0 && (!Number.isFinite(rule.weight) || rule.weight <= 0)) {
+      throw new VaultConfigError(
+        "Routing rule weight must be a positive number.",
+        {
+          index,
+          provider: rule.provider
+        }
+      );
+    }
+  }
+  if (!hasDefaultRule) {
+    throw new VaultConfigError(
+      "Routing configuration must include a default fallback rule."
+    );
+  }
+}
+function validateVaultConfig(config) {
+  if (!config || typeof config !== "object") {
+    throw new VaultConfigError("VaultClient configuration must be an object.");
+  }
+  if (!isPlainObject(config.providers)) {
+    throw new VaultConfigError("At least one provider must be configured.");
+  }
+  const providerEntries = Object.entries(config.providers);
+  if (providerEntries.length === 0) {
+    throw new VaultConfigError("At least one provider must be configured.");
+  }
+  for (const [name, provider] of providerEntries) {
+    validateProviderConfig(name, provider);
+  }
+  const enabledProviders = providerEntries.filter(
+    ([, provider]) => provider.enabled !== false
+  );
+  if (enabledProviders.length === 0) {
+    throw new VaultConfigError("No enabled providers are available.");
+  }
+  if (config.routing) {
+    validateRoutingRules(config.routing.rules, config.providers);
+  }
+  if (config.timeout !== void 0) {
+    assertPositiveFiniteInteger(config.timeout, "timeout");
+  }
+  if (config.idempotency?.ttlMs !== void 0) {
+    assertPositiveFiniteInteger(config.idempotency.ttlMs, "idempotency.ttlMs");
+  }
+  if (config.idempotency?.store) {
+    const store = config.idempotency.store;
+    const requiredMethods = ["get", "set", "delete", "clearExpired"];
+    for (const method of requiredMethods) {
+      if (typeof store[method] !== "function") {
+        throw new VaultConfigError(
+          "Idempotency store is missing required methods.",
+          {
+            method
+          }
+        );
+      }
+    }
+  }
+  if (config.platformApiKey !== void 0 && config.platformApiKey.trim() === "") {
+    throw new VaultConfigError("platformApiKey cannot be empty when provided.");
+  }
+  if (config.platform) {
+    if (config.platform.baseUrl !== void 0 && config.platform.baseUrl.trim() === "") {
+      throw new VaultConfigError(
+        "platform.baseUrl cannot be empty when provided."
+      );
+    }
+    if (config.platform.timeoutMs !== void 0) {
+      assertPositiveFiniteInteger(
+        config.platform.timeoutMs,
+        "platform.timeoutMs"
+      );
+    }
+    if (config.platform.batchSize !== void 0) {
+      assertPositiveFiniteInteger(
+        config.platform.batchSize,
+        "platform.batchSize"
+      );
+    }
+    if (config.platform.flushIntervalMs !== void 0) {
+      assertPositiveFiniteInteger(
+        config.platform.flushIntervalMs,
+        "platform.flushIntervalMs"
+      );
+    }
+    if (config.platform.maxRetries !== void 0) {
+      assertPositiveFiniteInteger(
+        config.platform.maxRetries,
+        "platform.maxRetries"
+      );
+    }
+    if (config.platform.initialBackoffMs !== void 0) {
+      assertPositiveFiniteInteger(
+        config.platform.initialBackoffMs,
+        "platform.initialBackoffMs"
+      );
+    }
+  }
+  if (config.logging?.level && !LOG_LEVELS.has(config.logging.level)) {
+    throw new VaultConfigError("Invalid logging level configured.", {
+      level: config.logging.level
+    });
+  }
+  if (config.logging?.logger) {
+    validateLogger(config.logging.logger);
+  }
+}
+
+// src/client/vault-client.ts
+function normalizeAdapterMetadata(metadata) {
+  return {
+    supportedMethods: metadata.supportedMethods.map(
+      (method) => method.toLowerCase()
+    ),
+    supportedCurrencies: metadata.supportedCurrencies.map(
+      (currency) => currency.toUpperCase()
+    ),
+    supportedCountries: metadata.supportedCountries.map(
+      (country) => country.toUpperCase()
+    )
+  };
+}
+var VaultClient = class {
+  config;
+  adapters = /* @__PURE__ */ new Map();
+  providerOrder;
+  router;
+  platformConnector;
+  idempotencyStore;
+  idempotencyTtlMs;
+  transactionProviderIndex = /* @__PURE__ */ new Map();
+  constructor(config) {
+    validateVaultConfig(config);
+    this.config = config;
+    const entries = Object.entries(config.providers);
+    const adapterMetadata = {};
+    this.providerOrder = entries.filter(([, provider]) => provider.enabled !== false).sort(([, a], [, b]) => (a.priority ?? 0) - (b.priority ?? 0)).map(([name, provider]) => {
+      if (!provider.adapter) {
+        throw new VaultConfigError(
+          "Provider adapter constructor is missing.",
+          {
+            code: "PROVIDER_NOT_CONFIGURED",
+            context: {
+              provider: name
+            }
+          }
+        );
+      }
+      const adapter = new provider.adapter(provider.config);
+      this.adapters.set(name, adapter);
+      adapterMetadata[name] = normalizeAdapterMetadata({
+        supportedMethods: provider.adapter.supportedMethods ?? adapter.metadata.supportedMethods,
+        supportedCurrencies: provider.adapter.supportedCurrencies ?? adapter.metadata.supportedCurrencies,
+        supportedCountries: provider.adapter.supportedCountries ?? adapter.metadata.supportedCountries
+      });
+      return name;
+    });
+    if (this.providerOrder.length === 0) {
+      throw new VaultConfigError("No enabled providers are available.");
+    }
+    this.router = config.routing?.rules?.length ? new Router(config.routing.rules, {
+      adapterMetadata,
+      logger: config.logging?.logger
+    }) : null;
+    this.platformConnector = config.platformApiKey ? new PlatformConnector({
+      apiKey: config.platformApiKey,
+      baseUrl: config.platform?.baseUrl,
+      timeoutMs: config.platform?.timeoutMs,
+      batchSize: config.platform?.batchSize,
+      flushIntervalMs: config.platform?.flushIntervalMs,
+      maxRetries: config.platform?.maxRetries,
+      initialBackoffMs: config.platform?.initialBackoffMs,
+      logger: config.logging?.logger
+    }) : null;
+    this.idempotencyStore = config.idempotency?.store ?? new MemoryIdempotencyStore();
+    this.idempotencyTtlMs = config.idempotency?.ttlMs ?? DEFAULT_IDEMPOTENCY_TTL_MS;
+  }
+  async charge(request) {
+    return this.executeIdempotentOperation("charge", request, async () => {
+      const route = await this.resolveProviderForCharge(request);
+      const adapter = this.getAdapter(route.provider);
+      const startedAt = Date.now();
+      const result = await this.wrapProviderCall(
+        route.provider,
+        "charge",
+        () => adapter.charge(request)
+      );
+      const latencyMs = Date.now() - startedAt;
+      const normalized = this.withRouting(result, route, request);
+      this.transactionProviderIndex.set(normalized.id, route.provider);
+      this.queueTransactionReport({
+        id: normalized.id,
+        provider: normalized.provider,
+        providerId: normalized.providerId,
+        status: normalized.status,
+        amount: normalized.amount,
+        currency: normalized.currency,
+        country: request.customer?.address?.country,
+        paymentMethod: normalized.paymentMethod.type,
+        cardBin: this.extractCardBin(request),
+        cardBrand: normalized.paymentMethod.brand,
+        latencyMs,
+        routingSource: normalized.routing.source,
+        routingDecisionId: route.decisionId,
+        idempotencyKey: request.idempotencyKey,
+        timestamp: normalized.createdAt
+      });
+      return normalized;
+    });
+  }
+  async authorize(request) {
+    return this.executeIdempotentOperation("authorize", request, async () => {
+      const route = await this.resolveProviderForCharge(request);
+      const adapter = this.getAdapter(route.provider);
+      const startedAt = Date.now();
+      const result = await this.wrapProviderCall(
+        route.provider,
+        "authorize",
+        () => adapter.authorize(request)
+      );
+      const latencyMs = Date.now() - startedAt;
+      const normalized = this.withRouting(result, route, request);
+      this.transactionProviderIndex.set(normalized.id, route.provider);
+      this.queueTransactionReport({
+        id: normalized.id,
+        provider: normalized.provider,
+        providerId: normalized.providerId,
+        status: normalized.status,
+        amount: normalized.amount,
+        currency: normalized.currency,
+        country: request.customer?.address?.country,
+        paymentMethod: normalized.paymentMethod.type,
+        cardBin: this.extractCardBin(request),
+        cardBrand: normalized.paymentMethod.brand,
+        latencyMs,
+        routingSource: normalized.routing.source,
+        routingDecisionId: route.decisionId,
+        idempotencyKey: request.idempotencyKey,
+        timestamp: normalized.createdAt
+      });
+      return normalized;
+    });
+  }
+  async capture(request) {
+    return this.executeIdempotentOperation("capture", request, async () => {
+      const provider = this.resolveProviderForTransaction(
+        request.transactionId
+      );
+      const adapter = this.getAdapter(provider);
+      const startedAt = Date.now();
+      const result = await this.wrapProviderCall(
+        provider,
+        "capture",
+        () => adapter.capture(request)
+      );
+      const latencyMs = Date.now() - startedAt;
+      const normalized = this.withRouting(result, {
+        provider,
+        source: "local",
+        reason: "transaction provider lookup"
+      });
+      this.transactionProviderIndex.set(normalized.id, provider);
+      this.queueTransactionReport({
+        id: normalized.id,
+        provider: normalized.provider,
+        providerId: normalized.providerId,
+        status: normalized.status,
+        amount: normalized.amount,
+        currency: normalized.currency,
+        paymentMethod: normalized.paymentMethod.type,
+        cardBrand: normalized.paymentMethod.brand,
+        latencyMs,
+        routingSource: normalized.routing.source,
+        idempotencyKey: request.idempotencyKey,
+        timestamp: normalized.createdAt
+      });
+      return normalized;
+    });
+  }
+  async refund(request) {
+    return this.executeIdempotentOperation("refund", request, async () => {
+      const provider = this.resolveProviderForTransaction(
+        request.transactionId
+      );
+      const adapter = this.getAdapter(provider);
+      const startedAt = Date.now();
+      const result = await this.wrapProviderCall(
+        provider,
+        "refund",
+        () => adapter.refund(request)
+      );
+      const latencyMs = Date.now() - startedAt;
+      this.queueTransactionReport({
+        id: result.id,
+        provider: result.provider,
+        providerId: result.providerId,
+        status: result.status,
+        amount: result.amount,
+        currency: result.currency,
+        latencyMs,
+        idempotencyKey: request.idempotencyKey,
+        timestamp: result.createdAt
+      });
+      return result;
+    });
+  }
+  async void(request) {
+    return this.executeIdempotentOperation("void", request, async () => {
+      const provider = this.resolveProviderForTransaction(
+        request.transactionId
+      );
+      const adapter = this.getAdapter(provider);
+      const result = await this.wrapProviderCall(
+        provider,
+        "void",
+        () => adapter.void(request)
+      );
+      this.queueTransactionReport({
+        id: result.id,
+        provider: result.provider,
+        status: result.status,
+        amount: 0,
+        currency: "N/A",
+        idempotencyKey: request.idempotencyKey,
+        timestamp: result.createdAt
+      });
+      return result;
+    });
+  }
+  async getStatus(transactionId) {
+    const provider = this.resolveProviderForTransaction(transactionId);
+    const adapter = this.getAdapter(provider);
+    const startedAt = Date.now();
+    const status = await this.wrapProviderCall(
+      provider,
+      "getStatus",
+      () => adapter.getStatus(transactionId)
+    );
+    const latencyMs = Date.now() - startedAt;
+    this.transactionProviderIndex.set(status.id, provider);
+    this.queueTransactionReport({
+      id: status.id,
+      provider: status.provider,
+      providerId: status.providerId,
+      status: status.status,
+      amount: status.amount,
+      currency: status.currency,
+      latencyMs,
+      timestamp: status.updatedAt
+    });
+    return status;
+  }
+  async listPaymentMethods(country, currency) {
+    const methods = await Promise.all(
+      this.providerOrder.map(async (provider) => {
+        const adapter = this.getAdapter(provider);
+        const providerMethods = await this.wrapProviderCall(
+          provider,
+          "listPaymentMethods",
+          () => adapter.listPaymentMethods(country, currency)
+        );
+        return providerMethods.map((method) => ({
+          ...method,
+          provider: method.provider || provider
+        }));
+      })
+    );
+    return methods.flat();
+  }
+  async handleWebhook(provider, payload, headers) {
+    const adapter = this.getAdapter(provider);
+    if (adapter.handleWebhook) {
+      const handler = adapter.handleWebhook;
+      const event2 = await this.wrapProviderCall(
+        provider,
+        "handleWebhook",
+        () => Promise.resolve(handler.call(adapter, payload, headers))
+      );
+      if (event2.transactionId) {
+        this.transactionProviderIndex.set(event2.transactionId, provider);
+      }
+      this.queueWebhookEvent(event2);
+      return event2;
+    }
+    const parsedPayload = this.parseWebhookPayload(payload);
+    const event = normalizeWebhookEvent(provider, parsedPayload, payload);
+    if (event.transactionId) {
+      this.transactionProviderIndex.set(event.transactionId, provider);
+    }
+    this.queueWebhookEvent(event);
+    return event;
+  }
+  async resolveProviderForCharge(request) {
+    if (request.routing?.provider) {
+      if (request.routing.exclude?.includes(request.routing.provider)) {
+        throw new VaultRoutingError(
+          "Forced provider is listed in routing exclusions.",
+          {
+            code: "ROUTING_PROVIDER_EXCLUDED",
+            context: {
+              provider: request.routing.provider
+            }
+          }
+        );
+      }
+      this.getAdapter(request.routing.provider);
+      return {
+        provider: request.routing.provider,
+        source: "local",
+        reason: "forced provider"
+      };
+    }
+    const platformDecision = await this.resolveProviderFromPlatform(request);
+    if (platformDecision) {
+      return platformDecision;
+    }
+    const context = {
+      currency: request.currency.toUpperCase(),
+      country: request.customer?.address?.country?.toUpperCase(),
+      paymentMethod: request.paymentMethod.type,
+      amount: request.amount,
+      metadata: request.metadata,
+      exclude: request.routing?.exclude
+    };
+    const decision = this.router?.decide(context);
+    if (decision) {
+      this.getAdapter(decision.provider);
+      return {
+        provider: decision.provider,
+        source: "local",
+        reason: decision.reason
+      };
+    }
+    const fallback = this.providerOrder.find(
+      (provider) => !request.routing?.exclude?.includes(provider)
+    );
+    if (!fallback) {
+      throw new VaultRoutingError(
+        "No eligible provider found after exclusions."
+      );
+    }
+    return {
+      provider: fallback,
+      source: "local",
+      reason: "fallback provider"
+    };
+  }
+  async resolveProviderFromPlatform(request) {
+    if (!this.platformConnector) {
+      return null;
+    }
+    try {
+      const decision = await this.platformConnector.decideRouting({
+        currency: request.currency,
+        country: request.customer?.address?.country,
+        amount: request.amount,
+        paymentMethod: request.paymentMethod.type,
+        cardBin: this.extractCardBin(request),
+        metadata: request.metadata
+      });
+      if (!decision?.provider) {
+        return null;
+      }
+      if (request.routing?.exclude?.includes(decision.provider)) {
+        return null;
+      }
+      this.getAdapter(decision.provider);
+      return {
+        provider: decision.provider,
+        source: "platform",
+        reason: decision.reason ?? "platform routing decision",
+        decisionId: decision.decisionId
+      };
+    } catch (error) {
+      this.config.logging?.logger?.warn(
+        "Platform routing unavailable. Falling back to local routing.",
+        {
+          operation: "resolveProviderForCharge",
+          cause: error instanceof Error ? error.message : String(error)
+        }
+      );
+      return null;
+    }
+  }
+  resolveProviderForTransaction(transactionId) {
+    const mappedProvider = this.transactionProviderIndex.get(transactionId);
+    if (mappedProvider) {
+      return mappedProvider;
+    }
+    const fallbackProvider = this.providerOrder[0];
+    if (!fallbackProvider) {
+      throw new VaultRoutingError(
+        "No configured providers are available for transaction lookup."
+      );
+    }
+    return fallbackProvider;
+  }
+  getAdapter(provider) {
+    const adapter = this.adapters.get(provider);
+    if (!adapter) {
+      throw new VaultRoutingError("Provider is not configured or enabled.", {
+        code: "ROUTING_PROVIDER_UNAVAILABLE",
+        context: {
+          provider
+        }
+      });
+    }
+    return adapter;
+  }
+  withRouting(result, route, request) {
+    return {
+      ...result,
+      provider: result.provider || route.provider,
+      metadata: {
+        ...request?.metadata ?? {},
+        ...result.metadata
+      },
+      routing: {
+        source: route.source,
+        reason: route.reason
+      },
+      providerMetadata: result.providerMetadata ?? {}
+    };
+  }
+  parseWebhookPayload(payload) {
+    const raw = typeof payload === "string" ? payload : payload.toString("utf-8");
+    try {
+      const parsed = JSON.parse(raw);
+      return parsed;
+    } catch {
+      return {
+        data: {
+          payload: raw
+        }
+      };
+    }
+  }
+  extractCardBin(request) {
+    if (request.paymentMethod.type === "card" && "number" in request.paymentMethod) {
+      const digits = request.paymentMethod.number.replace(/\D/g, "");
+      if (digits.length >= 6) {
+        return digits.slice(0, 6);
+      }
+    }
+    return void 0;
+  }
+  queueTransactionReport(report) {
+    if (!this.platformConnector) {
+      return;
+    }
+    this.platformConnector.queueTransactionReport(report);
+  }
+  queueWebhookEvent(event) {
+    if (!this.platformConnector) {
+      return;
+    }
+    this.platformConnector.queueWebhookEvent({
+      id: event.id,
+      type: event.type,
+      provider: event.provider,
+      transactionId: event.transactionId,
+      providerEventId: event.providerEventId,
+      data: event.data,
+      timestamp: event.timestamp
+    });
+  }
+  async executeIdempotentOperation(operation, request, execute) {
+    const key = request.idempotencyKey;
+    if (!key) {
+      return execute();
+    }
+    await this.idempotencyStore.clearExpired();
+    const payloadHash = hashIdempotencyPayload({
+      operation,
+      request
+    });
+    const existingRecord = await this.idempotencyStore.get(key);
+    if (existingRecord) {
+      if (existingRecord.payloadHash !== payloadHash) {
+        throw new VaultIdempotencyConflictError(
+          "Idempotency key was reused with a different payload.",
+          {
+            operation,
+            key
+          }
+        );
+      }
+      return existingRecord.result;
+    }
+    const result = await execute();
+    await this.idempotencyStore.set({
+      key,
+      payloadHash,
+      result,
+      expiresAt: Date.now() + this.idempotencyTtlMs
+    });
+    return result;
+  }
+  async wrapProviderCall(provider, operation, execute) {
+    try {
+      return await execute();
+    } catch (error) {
+      if (error instanceof VaultError) {
+        throw error;
+      }
+      throw mapProviderError(error, {
+        provider,
+        operation
+      });
+    }
+  }
+};
+
+// src/testing/adapter-compliance.ts
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+function isNumber(value) {
+  return typeof value === "number" && Number.isFinite(value);
+}
+var PAYMENT_STATUSES = /* @__PURE__ */ new Set([
+  "completed",
+  "pending",
+  "requires_action",
+  "declined",
+  "failed",
+  "cancelled",
+  "authorized"
+]);
+var REFUND_STATUSES = /* @__PURE__ */ new Set(["completed", "pending", "failed"]);
+var VOID_STATUSES = /* @__PURE__ */ new Set(["completed", "failed"]);
+var ROUTING_SOURCES = /* @__PURE__ */ new Set(["local", "platform"]);
+var AdapterComplianceError = class extends Error {
+  operation;
+  field;
+  constructor(operation, message, field) {
+    super(`[${operation}] ${message}`);
+    this.name = "AdapterComplianceError";
+    this.operation = operation;
+    this.field = field;
+  }
+};
+function assertCondition(condition, operation, message, field) {
+  if (!condition) {
+    throw new AdapterComplianceError(operation, message, field);
+  }
+}
+function validateStringArray(operation, field, value) {
+  assertCondition(
+    Array.isArray(value),
+    operation,
+    `${field} must be an array.`,
+    field
+  );
+  assertCondition(
+    value.every(isNonEmptyString),
+    operation,
+    `${field} must contain non-empty strings.`,
+    field
+  );
+}
+function validatePaymentResult(value, operation, expectedProvider) {
+  assertCondition(isRecord(value), operation, "Result must be an object.");
+  assertCondition(
+    isNonEmptyString(value.id),
+    operation,
+    "id must be a non-empty string.",
+    "id"
+  );
+  assertCondition(
+    isNonEmptyString(value.provider),
+    operation,
+    "provider must be a non-empty string.",
+    "provider"
+  );
+  if (expectedProvider) {
+    assertCondition(
+      value.provider === expectedProvider,
+      operation,
+      `provider must equal "${expectedProvider}".`,
+      "provider"
+    );
+  }
+  assertCondition(
+    isNonEmptyString(value.providerId),
+    operation,
+    "providerId must be a non-empty string.",
+    "providerId"
+  );
+  assertCondition(
+    isNumber(value.amount),
+    operation,
+    "amount must be a number.",
+    "amount"
+  );
+  assertCondition(
+    isNonEmptyString(value.currency),
+    operation,
+    "currency must be a non-empty string.",
+    "currency"
+  );
+  assertCondition(
+    PAYMENT_STATUSES.has(value.status),
+    operation,
+    "status must be a canonical payment status.",
+    "status"
+  );
+  assertCondition(
+    isRecord(value.paymentMethod),
+    operation,
+    "paymentMethod must be an object.",
+    "paymentMethod"
+  );
+  assertCondition(
+    isNonEmptyString(value.paymentMethod.type),
+    operation,
+    "paymentMethod.type must be a non-empty string.",
+    "paymentMethod.type"
+  );
+  assertCondition(
+    isRecord(value.routing),
+    operation,
+    "routing must be an object.",
+    "routing"
+  );
+  assertCondition(
+    ROUTING_SOURCES.has(value.routing.source),
+    operation,
+    'routing.source must be "local" or "platform".',
+    "routing.source"
+  );
+  assertCondition(
+    isNonEmptyString(value.routing.reason),
+    operation,
+    "routing.reason must be a non-empty string.",
+    "routing.reason"
+  );
+  assertCondition(
+    isNonEmptyString(value.createdAt),
+    operation,
+    "createdAt must be a non-empty string.",
+    "createdAt"
+  );
+  assertCondition(
+    isRecord(value.metadata),
+    operation,
+    "metadata must be an object.",
+    "metadata"
+  );
+  assertCondition(
+    isRecord(value.providerMetadata),
+    operation,
+    "providerMetadata must be an object.",
+    "providerMetadata"
+  );
+}
+function validateRefundResult(value, operation = "refund", expectedProvider) {
+  assertCondition(isRecord(value), operation, "Result must be an object.");
+  assertCondition(
+    isNonEmptyString(value.id),
+    operation,
+    "id must be a non-empty string.",
+    "id"
+  );
+  assertCondition(
+    isNonEmptyString(value.transactionId),
+    operation,
+    "transactionId must be a non-empty string.",
+    "transactionId"
+  );
+  assertCondition(
+    REFUND_STATUSES.has(value.status),
+    operation,
+    'status must be "completed", "pending", or "failed".',
+    "status"
+  );
+  assertCondition(
+    isNumber(value.amount),
+    operation,
+    "amount must be a number.",
+    "amount"
+  );
+  assertCondition(
+    isNonEmptyString(value.currency),
+    operation,
+    "currency must be a non-empty string.",
+    "currency"
+  );
+  assertCondition(
+    isNonEmptyString(value.provider),
+    operation,
+    "provider must be a non-empty string.",
+    "provider"
+  );
+  if (expectedProvider) {
+    assertCondition(
+      value.provider === expectedProvider,
+      operation,
+      `provider must equal "${expectedProvider}".`,
+      "provider"
+    );
+  }
+  assertCondition(
+    isNonEmptyString(value.providerId),
+    operation,
+    "providerId must be a non-empty string.",
+    "providerId"
+  );
+  assertCondition(
+    isNonEmptyString(value.createdAt),
+    operation,
+    "createdAt must be a non-empty string.",
+    "createdAt"
+  );
+}
+function validateVoidResult(value, operation = "void", expectedProvider) {
+  assertCondition(isRecord(value), operation, "Result must be an object.");
+  assertCondition(
+    isNonEmptyString(value.id),
+    operation,
+    "id must be a non-empty string.",
+    "id"
+  );
+  assertCondition(
+    isNonEmptyString(value.transactionId),
+    operation,
+    "transactionId must be a non-empty string.",
+    "transactionId"
+  );
+  assertCondition(
+    VOID_STATUSES.has(value.status),
+    operation,
+    'status must be "completed" or "failed".',
+    "status"
+  );
+  assertCondition(
+    isNonEmptyString(value.provider),
+    operation,
+    "provider must be a non-empty string.",
+    "provider"
+  );
+  if (expectedProvider) {
+    assertCondition(
+      value.provider === expectedProvider,
+      operation,
+      `provider must equal "${expectedProvider}".`,
+      "provider"
+    );
+  }
+  assertCondition(
+    isNonEmptyString(value.createdAt),
+    operation,
+    "createdAt must be a non-empty string.",
+    "createdAt"
+  );
+}
+function validateTransactionStatus(value, operation = "getStatus", expectedProvider) {
+  assertCondition(isRecord(value), operation, "Result must be an object.");
+  assertCondition(
+    isNonEmptyString(value.id),
+    operation,
+    "id must be a non-empty string.",
+    "id"
+  );
+  assertCondition(
+    isNonEmptyString(value.provider),
+    operation,
+    "provider must be a non-empty string.",
+    "provider"
+  );
+  if (expectedProvider) {
+    assertCondition(
+      value.provider === expectedProvider,
+      operation,
+      `provider must equal "${expectedProvider}".`,
+      "provider"
+    );
+  }
+  assertCondition(
+    isNonEmptyString(value.providerId),
+    operation,
+    "providerId must be a non-empty string.",
+    "providerId"
+  );
+  assertCondition(
+    isNumber(value.amount),
+    operation,
+    "amount must be a number.",
+    "amount"
+  );
+  assertCondition(
+    isNonEmptyString(value.currency),
+    operation,
+    "currency must be a non-empty string.",
+    "currency"
+  );
+  assertCondition(
+    PAYMENT_STATUSES.has(value.status),
+    operation,
+    "status must be a canonical payment status.",
+    "status"
+  );
+  assertCondition(
+    Array.isArray(value.history),
+    operation,
+    "history must be an array.",
+    "history"
+  );
+  for (const [index, item] of value.history.entries()) {
+    const fieldPrefix = `history[${index}]`;
+    assertCondition(
+      isRecord(item),
+      operation,
+      `${fieldPrefix} must be an object.`,
+      fieldPrefix
+    );
+    assertCondition(
+      PAYMENT_STATUSES.has(item.status),
+      operation,
+      `${fieldPrefix}.status must be a canonical payment status.`,
+      `${fieldPrefix}.status`
+    );
+    assertCondition(
+      isNonEmptyString(item.timestamp),
+      operation,
+      `${fieldPrefix}.timestamp must be a non-empty string.`,
+      `${fieldPrefix}.timestamp`
+    );
+  }
+  assertCondition(
+    isNonEmptyString(value.updatedAt),
+    operation,
+    "updatedAt must be a non-empty string.",
+    "updatedAt"
+  );
+}
+function validatePaymentMethods(methods, operation = "listPaymentMethods", expectedProvider) {
+  assertCondition(
+    Array.isArray(methods),
+    operation,
+    "Result must be an array.",
+    "paymentMethods"
+  );
+  for (const [index, method] of methods.entries()) {
+    const fieldPrefix = `paymentMethods[${index}]`;
+    assertCondition(
+      isRecord(method),
+      operation,
+      `${fieldPrefix} must be an object.`,
+      fieldPrefix
+    );
+    assertCondition(
+      isNonEmptyString(method.type),
+      operation,
+      `${fieldPrefix}.type must be a non-empty string.`,
+      `${fieldPrefix}.type`
+    );
+    assertCondition(
+      isNonEmptyString(method.provider),
+      operation,
+      `${fieldPrefix}.provider must be a non-empty string.`,
+      `${fieldPrefix}.provider`
+    );
+    if (expectedProvider) {
+      assertCondition(
+        method.provider === expectedProvider,
+        operation,
+        `${fieldPrefix}.provider must equal "${expectedProvider}".`,
+        `${fieldPrefix}.provider`
+      );
+    }
+    assertCondition(
+      isNonEmptyString(method.name),
+      operation,
+      `${fieldPrefix}.name must be a non-empty string.`,
+      `${fieldPrefix}.name`
+    );
+    validateStringArray(
+      operation,
+      `${fieldPrefix}.currencies`,
+      method.currencies
+    );
+    validateStringArray(
+      operation,
+      `${fieldPrefix}.countries`,
+      method.countries
+    );
+    if (typeof method.minAmount !== "undefined") {
+      assertCondition(
+        isNumber(method.minAmount),
+        operation,
+        `${fieldPrefix}.minAmount must be a number when provided.`,
+        `${fieldPrefix}.minAmount`
+      );
+    }
+    if (typeof method.maxAmount !== "undefined") {
+      assertCondition(
+        isNumber(method.maxAmount),
+        operation,
+        `${fieldPrefix}.maxAmount must be a number when provided.`,
+        `${fieldPrefix}.maxAmount`
+      );
+    }
+  }
+}
+function validateWebhookEvent(event, operation = "handleWebhook", expectedProvider) {
+  assertCondition(isRecord(event), operation, "Result must be an object.");
+  assertCondition(
+    isNonEmptyString(event.id),
+    operation,
+    "id must be a non-empty string.",
+    "id"
+  );
+  assertCondition(
+    isNonEmptyString(event.provider),
+    operation,
+    "provider must be a non-empty string.",
+    "provider"
+  );
+  if (expectedProvider) {
+    assertCondition(
+      event.provider === expectedProvider,
+      operation,
+      `provider must equal "${expectedProvider}".`,
+      "provider"
+    );
+  }
+  assertCondition(
+    isNonEmptyString(event.type),
+    operation,
+    "type must be a non-empty string.",
+    "type"
+  );
+  assertCondition(
+    isNonEmptyString(event.providerEventId),
+    operation,
+    "providerEventId must be a non-empty string.",
+    "providerEventId"
+  );
+  assertCondition(
+    isNonEmptyString(event.timestamp),
+    operation,
+    "timestamp must be a non-empty string.",
+    "timestamp"
+  );
+}
+function createAdapterComplianceHarness(adapter, options = {}) {
+  const expectedProvider = options.expectedProvider ?? adapter.name;
+  return {
+    async charge(request) {
+      const result = await adapter.charge(request);
+      validatePaymentResult(result, "charge", expectedProvider);
+      return result;
+    },
+    async authorize(request) {
+      const result = await adapter.authorize(request);
+      validatePaymentResult(result, "authorize", expectedProvider);
+      return result;
+    },
+    async capture(request) {
+      const result = await adapter.capture(request);
+      validatePaymentResult(result, "capture", expectedProvider);
+      return result;
+    },
+    async refund(request) {
+      const result = await adapter.refund(request);
+      validateRefundResult(result, "refund", expectedProvider);
+      return result;
+    },
+    async void(request) {
+      const result = await adapter.void(request);
+      validateVoidResult(result, "void", expectedProvider);
+      return result;
+    },
+    async getStatus(transactionId) {
+      const result = await adapter.getStatus(transactionId);
+      validateTransactionStatus(result, "getStatus", expectedProvider);
+      return result;
+    },
+    async listPaymentMethods(country, currency) {
+      const result = await adapter.listPaymentMethods(country, currency);
+      validatePaymentMethods(result, "listPaymentMethods", expectedProvider);
+      return result;
+    },
+    async handleWebhook(payload, headers) {
+      if (!adapter.handleWebhook) {
+        throw new AdapterComplianceError(
+          "handleWebhook",
+          "Adapter does not implement handleWebhook."
+        );
+      }
+      const result = await adapter.handleWebhook(payload, headers);
+      validateWebhookEvent(result, "handleWebhook", expectedProvider);
+      return result;
+    }
+  };
+}
+
+// src/testing/mock-adapter.ts
+function unsupported(method) {
+  throw new Error(`MockAdapter handler not configured: ${method}`);
+}
+var DEFAULT_MOCK_METADATA = {
+  supportedMethods: ["card", "bank_transfer", "wallet"],
+  supportedCurrencies: ["USD", "EUR", "GBP"],
+  supportedCountries: ["US", "GB", "DE"]
+};
+function hasMockAdapterOptions(value) {
+  return "handlers" in value || "scenarios" in value || "name" in value || "metadata" in value;
+}
+function toScenarioQueue(scenarios) {
+  if (!scenarios || scenarios.length === 0) {
+    return [];
+  }
+  return scenarios.map((scenario) => {
+    if (scenario instanceof Error) {
+      return async () => Promise.reject(scenario);
+    }
+    if (typeof scenario === "function") {
+      return async (input) => scenario(input);
+    }
+    return async () => scenario;
+  });
+}
+var MockAdapter = class {
+  static supportedMethods = DEFAULT_MOCK_METADATA.supportedMethods;
+  static supportedCurrencies = DEFAULT_MOCK_METADATA.supportedCurrencies;
+  static supportedCountries = DEFAULT_MOCK_METADATA.supportedCountries;
+  name;
+  metadata;
+  handlers;
+  chargeScenarios;
+  authorizeScenarios;
+  captureScenarios;
+  refundScenarios;
+  voidScenarios;
+  statusScenarios;
+  paymentMethodsScenarios;
+  webhookScenarios;
+  constructor(options = {}) {
+    const normalized = hasMockAdapterOptions(options) ? options : { handlers: options };
+    this.name = normalized.name ?? "mock";
+    this.metadata = normalized.metadata ?? DEFAULT_MOCK_METADATA;
+    this.handlers = normalized.handlers ?? {};
+    this.chargeScenarios = toScenarioQueue(normalized.scenarios?.charge);
+    this.authorizeScenarios = toScenarioQueue(normalized.scenarios?.authorize);
+    this.captureScenarios = toScenarioQueue(normalized.scenarios?.capture);
+    this.refundScenarios = toScenarioQueue(normalized.scenarios?.refund);
+    this.voidScenarios = toScenarioQueue(normalized.scenarios?.void);
+    this.statusScenarios = toScenarioQueue(normalized.scenarios?.getStatus);
+    this.paymentMethodsScenarios = toScenarioQueue(
+      normalized.scenarios?.listPaymentMethods
+    );
+    this.webhookScenarios = toScenarioQueue(
+      normalized.scenarios?.handleWebhook
+    );
+  }
+  enqueue(method, scenario) {
+    switch (method) {
+      case "charge":
+        this.chargeScenarios.push(
+          ...toScenarioQueue([
+            scenario
+          ])
+        );
+        break;
+      case "authorize":
+        this.authorizeScenarios.push(
+          ...toScenarioQueue([
+            scenario
+          ])
+        );
+        break;
+      case "capture":
+        this.captureScenarios.push(
+          ...toScenarioQueue([
+            scenario
+          ])
+        );
+        break;
+      case "refund":
+        this.refundScenarios.push(
+          ...toScenarioQueue([
+            scenario
+          ])
+        );
+        break;
+      case "void":
+        this.voidScenarios.push(
+          ...toScenarioQueue([
+            scenario
+          ])
+        );
+        break;
+      case "getStatus":
+        this.statusScenarios.push(
+          ...toScenarioQueue([
+            scenario
+          ])
+        );
+        break;
+      case "listPaymentMethods":
+        this.paymentMethodsScenarios.push(
+          ...toScenarioQueue([
+            scenario
+          ])
+        );
+        break;
+      case "handleWebhook":
+        this.webhookScenarios.push(
+          ...toScenarioQueue([
+            scenario
+          ])
+        );
+        break;
+      default:
+        unsupported(method);
+    }
+    return this;
+  }
+  async charge(request) {
+    const scenario = this.chargeScenarios.shift();
+    if (scenario) {
+      return scenario(request);
+    }
+    const handler = this.handlers.charge;
+    if (!handler) {
+      unsupported("charge");
+    }
+    return handler(request);
+  }
+  async authorize(request) {
+    const scenario = this.authorizeScenarios.shift();
+    if (scenario) {
+      return scenario(request);
+    }
+    const handler = this.handlers.authorize;
+    if (!handler) {
+      unsupported("authorize");
+    }
+    return handler(request);
+  }
+  async capture(request) {
+    const scenario = this.captureScenarios.shift();
+    if (scenario) {
+      return scenario(request);
+    }
+    const handler = this.handlers.capture;
+    if (!handler) {
+      unsupported("capture");
+    }
+    return handler(request);
+  }
+  async refund(request) {
+    const scenario = this.refundScenarios.shift();
+    if (scenario) {
+      return scenario(request);
+    }
+    const handler = this.handlers.refund;
+    if (!handler) {
+      unsupported("refund");
+    }
+    return handler(request);
+  }
+  async void(request) {
+    const scenario = this.voidScenarios.shift();
+    if (scenario) {
+      return scenario(request);
+    }
+    const handler = this.handlers.void;
+    if (!handler) {
+      unsupported("void");
+    }
+    return handler(request);
+  }
+  async getStatus(transactionId) {
+    const scenario = this.statusScenarios.shift();
+    if (scenario) {
+      return scenario(transactionId);
+    }
+    const handler = this.handlers.getStatus;
+    if (!handler) {
+      unsupported("getStatus");
+    }
+    return handler(transactionId);
+  }
+  async listPaymentMethods(country, currency) {
+    const scenario = this.paymentMethodsScenarios.shift();
+    if (scenario) {
+      return scenario({ country, currency });
+    }
+    const handler = this.handlers.listPaymentMethods;
+    if (!handler) {
+      unsupported("listPaymentMethods");
+    }
+    return handler(country, currency);
+  }
+  async handleWebhook(payload, headers) {
+    const scenario = this.webhookScenarios.shift();
+    if (scenario) {
+      return scenario({ payload, headers });
+    }
+    const handler = this.handlers.handleWebhook;
+    if (!handler) {
+      unsupported("handleWebhook");
+    }
+    return handler(payload, headers);
+  }
+};
+
+// src/testing/webhook-helper.ts
+var import_node_crypto3 = require("crypto");
+function toPayloadString(payload) {
+  return typeof payload === "string" ? payload : JSON.stringify(payload);
+}
+function createHmacDigest2(algorithm, secret, content) {
+  return (0, import_node_crypto3.createHmac)(algorithm, secret).update(content).digest("hex");
+}
+function createSignedWebhookPayload(payload, secret, options = {}) {
+  const serialized = toPayloadString(payload);
+  const provider = options.provider ?? "generic";
+  switch (provider) {
+    case "stripe": {
+      const timestamp = String(
+        options.timestamp ?? Math.floor(Date.now() / 1e3)
+      );
+      const signature = createHmacDigest2(
+        "sha256",
+        secret,
+        `${timestamp}.${serialized}`
+      );
+      const headerName = options.headerName ?? "stripe-signature";
+      return {
+        payload: serialized,
+        headers: {
+          [headerName]: `t=${timestamp},v1=${signature}`
+        }
+      };
+    }
+    case "dlocal": {
+      const signature = createHmacDigest2("sha256", secret, serialized);
+      const headerName = options.headerName ?? "x-dlocal-signature";
+      return {
+        payload: serialized,
+        headers: {
+          [headerName]: signature
+        }
+      };
+    }
+    case "paystack": {
+      const signature = createHmacDigest2("sha512", secret, serialized);
+      const headerName = options.headerName ?? "x-paystack-signature";
+      return {
+        payload: serialized,
+        headers: {
+          [headerName]: signature
+        }
+      };
+    }
+    case "generic": {
+      const signature = createHmacDigest2("sha256", secret, serialized);
+      const headerName = options.headerName ?? "x-vault-test-signature";
+      return {
+        payload: serialized,
+        headers: {
+          [headerName]: signature
+        }
+      };
+    }
+    default: {
+      const unsupportedProvider = provider;
+      throw new Error(
+        `Unsupported webhook signing provider: ${unsupportedProvider}`
+      );
+    }
+  }
+}
+function createStripeSignedWebhookPayload(payload, secret, options = {}) {
+  return createSignedWebhookPayload(payload, secret, {
+    ...options,
+    provider: "stripe"
+  });
+}
+function createDLocalSignedWebhookPayload(payload, secret, options = {}) {
+  return createSignedWebhookPayload(payload, secret, {
+    ...options,
+    provider: "dlocal"
+  });
+}
+function createPaystackSignedWebhookPayload(payload, secret, options = {}) {
+  return createSignedWebhookPayload(payload, secret, {
+    ...options,
+    provider: "paystack"
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AdapterComplianceError,
+  BatchBuffer,
+  DEFAULT_IDEMPOTENCY_TTL_MS,
+  DEFAULT_VAULT_EVENT_TYPES,
+  DLocalAdapter,
+  MemoryIdempotencyStore,
+  MockAdapter,
+  PaystackAdapter,
+  PlatformConnector,
+  Router,
+  StripeAdapter,
+  VAULT_ERROR_CODE_DEFINITIONS,
+  VaultClient,
+  VaultConfigError,
+  VaultError,
+  VaultIdempotencyConflictError,
+  VaultNetworkError,
+  VaultProviderError,
+  VaultRoutingError,
+  WebhookVerificationError,
+  buildVaultErrorDocsUrl,
+  createAdapterComplianceHarness,
+  createDLocalSignedWebhookPayload,
+  createPaystackSignedWebhookPayload,
+  createSignedWebhookPayload,
+  createStripeSignedWebhookPayload,
+  getVaultErrorCodeDefinition,
+  hashIdempotencyPayload,
+  isProviderErrorHint,
+  mapProviderError,
+  normalizeWebhookEvent,
+  ruleMatchesContext,
+  validatePaymentMethods,
+  validatePaymentResult,
+  validateRefundResult,
+  validateTransactionStatus,
+  validateVoidResult,
+  validateWebhookEvent
+});
+//# sourceMappingURL=index.cjs.map