@vaultsaas/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,814 @@
+type VaultEventType = 'payment.completed' | 'payment.failed' | 'payment.pending' | 'payment.requires_action' | 'payment.refunded' | 'payment.partially_refunded' | 'payment.disputed' | 'payment.dispute_resolved' | 'payout.completed' | 'payout.failed';
+interface VaultEvent {
+    id: string;
+    type: VaultEventType;
+    provider: string;
+    transactionId?: string;
+    providerEventId: string;
+    data: Record<string, unknown>;
+    rawPayload: unknown;
+    timestamp: string;
+}
+
+/**
+ * @description Normalized payment status across all providers.
+ * Each adapter maps provider-specific statuses to one of these canonical values.
+ */
+type PaymentStatus = 'completed' | 'pending' | 'requires_action' | 'declined' | 'failed' | 'cancelled' | 'authorized';
+/**
+ * @description Payment method input discriminated by `type`. Supports card (token or raw),
+ * bank transfer, wallet, PIX, and boleto payment methods.
+ */
+type PaymentMethodInput = {
+    type: 'card';
+    token: string;
+} | {
+    type: 'card';
+    number: string;
+    expMonth: number;
+    expYear: number;
+    cvc: string;
+} | {
+    type: 'bank_transfer';
+    bankCode: string;
+    accountNumber: string;
+} | {
+    type: 'wallet';
+    walletType: string;
+    token: string;
+} | {
+    type: 'pix';
+} | {
+    type: 'boleto';
+    customerDocument: string;
+};
+/** @description Customer billing or shipping address. */
+interface AddressInput {
+    line1: string;
+    line2?: string;
+    city: string;
+    state?: string;
+    postalCode: string;
+    /** ISO 3166-1 alpha-2 country code (e.g. "US", "BR"). */
+    country: string;
+}
+/** @description Customer details passed with a charge or authorize request. */
+interface CustomerInput {
+    email?: string;
+    name?: string;
+    phone?: string;
+    /** Tax ID or national document number (e.g. CPF in Brazil). */
+    document?: string;
+    address?: AddressInput;
+}
+/**
+ * @description Per-request routing overrides. Force a specific provider or exclude
+ * providers from selection.
+ */
+interface RoutingPreference {
+    /** Force routing to this provider, bypassing rules. */
+    provider?: string;
+    /** Provider names to exclude from routing consideration. */
+    exclude?: string[];
+}
+/**
+ * @description Request payload for a one-step charge (immediate capture).
+ *
+ * @example
+ * ```ts
+ * const request: ChargeRequest = {
+ *   amount: 5000,
+ *   currency: 'USD',
+ *   paymentMethod: { type: 'card', token: 'tok_visa' },
+ *   idempotencyKey: 'order-123',
+ * };
+ * ```
+ */
+interface ChargeRequest {
+    /** Amount in the smallest currency unit (e.g. cents for USD). */
+    amount: number;
+    /** ISO 4217 currency code (e.g. "USD", "BRL"). */
+    currency: string;
+    paymentMethod: PaymentMethodInput;
+    customer?: CustomerInput;
+    description?: string;
+    /** Arbitrary key-value pairs forwarded to the provider. */
+    metadata?: Record<string, string>;
+    /** Prevents duplicate charges when retrying the same request. */
+    idempotencyKey?: string;
+    routing?: RoutingPreference;
+}
+/**
+ * @description Request payload for a two-step authorization (hold funds without capture).
+ * Identical shape to {@link ChargeRequest}; the client calls `authorize` instead of `charge`.
+ */
+type AuthorizeRequest = ChargeRequest;
+/**
+ * @description Request payload to capture a previously authorized transaction.
+ */
+interface CaptureRequest {
+    /** The transaction ID returned from a prior `authorize` call. */
+    transactionId: string;
+    /** Partial capture amount. Omit to capture the full authorized amount. */
+    amount?: number;
+    idempotencyKey?: string;
+}
+/**
+ * @description Request payload to refund a completed transaction (full or partial).
+ */
+interface RefundRequest {
+    /** The transaction ID of the original charge or capture. */
+    transactionId: string;
+    /** Partial refund amount. Omit to refund the full amount. */
+    amount?: number;
+    /** Human-readable reason forwarded to the provider. */
+    reason?: string;
+    idempotencyKey?: string;
+}
+/**
+ * @description Request payload to void (cancel) an authorized transaction before capture.
+ */
+interface VoidRequest {
+    /** The transaction ID of the authorization to void. */
+    transactionId: string;
+    idempotencyKey?: string;
+}
+/**
+ * @description Normalized result returned by `charge`, `authorize`, and `capture` operations.
+ * Provider-specific data is available via `providerMetadata`.
+ */
+interface PaymentResult {
+    /** VaultSaaS-normalized transaction identifier. */
+    id: string;
+    status: PaymentStatus;
+    /** Name of the provider that processed the transaction (e.g. "stripe"). */
+    provider: string;
+    /** Provider's own identifier for this transaction. */
+    providerId: string;
+    /** Amount in smallest currency unit. */
+    amount: number;
+    /** ISO 4217 currency code. */
+    currency: string;
+    /** Snapshot of the payment method used. */
+    paymentMethod: {
+        type: string;
+        last4?: string;
+        brand?: string;
+        expiryMonth?: number;
+        expiryYear?: number;
+    };
+    customer?: {
+        id?: string;
+        email?: string;
+    };
+    /** Merged metadata from the request and provider response. */
+    metadata: Record<string, string>;
+    /** How the provider was selected for this transaction. */
+    routing: {
+        source: 'local' | 'platform';
+        reason: string;
+    };
+    /** ISO 8601 timestamp. */
+    createdAt: string;
+    /** Raw provider-specific fields not mapped to the normalized schema. */
+    providerMetadata: Record<string, unknown>;
+}
+/** @description Normalized result returned by a `refund` operation. */
+interface RefundResult {
+    /** Unique refund identifier. */
+    id: string;
+    /** The original transaction that was refunded. */
+    transactionId: string;
+    status: 'completed' | 'pending' | 'failed';
+    /** Refunded amount in smallest currency unit. */
+    amount: number;
+    currency: string;
+    provider: string;
+    providerId: string;
+    reason?: string;
+    /** ISO 8601 timestamp. */
+    createdAt: string;
+}
+/** @description Normalized result returned by a `void` (cancellation) operation. */
+interface VoidResult {
+    id: string;
+    /** The original authorized transaction that was voided. */
+    transactionId: string;
+    status: 'completed' | 'failed';
+    provider: string;
+    /** ISO 8601 timestamp. */
+    createdAt: string;
+}
+/** @description A single entry in a transaction's status history timeline. */
+interface StatusChange {
+    status: PaymentStatus;
+    /** ISO 8601 timestamp when this status was recorded. */
+    timestamp: string;
+    reason?: string;
+}
+/** @description Full transaction status including status history, returned by `getStatus`. */
+interface TransactionStatus {
+    id: string;
+    status: PaymentStatus;
+    provider: string;
+    providerId: string;
+    amount: number;
+    currency: string;
+    /** Chronological status changes for this transaction. */
+    history: StatusChange[];
+    /** ISO 8601 timestamp of the most recent status update. */
+    updatedAt: string;
+}
+/**
+ * @description Describes a payment method supported by a provider for a given
+ * country/currency combination. Returned by `listPaymentMethods`.
+ */
+interface PaymentMethodInfo {
+    /** Payment method type identifier (e.g. "card", "pix", "bank_transfer"). */
+    type: string;
+    provider: string;
+    /** Human-readable display name. */
+    name: string;
+    /** ISO 4217 currency codes this method supports. */
+    currencies: string[];
+    /** ISO 3166-1 alpha-2 country codes this method supports. */
+    countries: string[];
+    /** Minimum amount in smallest currency unit, if applicable. */
+    minAmount?: number;
+    /** Maximum amount in smallest currency unit, if applicable. */
+    maxAmount?: number;
+}
+
+/** Static provider capability declaration used by routing validation. */
+interface AdapterMetadata {
+    readonly supportedMethods: readonly string[];
+    readonly supportedCurrencies: readonly string[];
+    readonly supportedCountries: readonly string[];
+}
+/** Runtime adapter contract used by `VaultClient`. */
+interface PaymentAdapter {
+    readonly name: string;
+    readonly metadata: AdapterMetadata;
+    charge(request: ChargeRequest): Promise<PaymentResult>;
+    authorize(request: AuthorizeRequest): Promise<PaymentResult>;
+    capture(request: CaptureRequest): Promise<PaymentResult>;
+    refund(request: RefundRequest): Promise<RefundResult>;
+    void(request: VoidRequest): Promise<VoidResult>;
+    getStatus(transactionId: string): Promise<TransactionStatus>;
+    listPaymentMethods(country: string, currency: string): Promise<PaymentMethodInfo[]>;
+    handleWebhook?(payload: Buffer | string, headers: Record<string, string>): Promise<VaultEvent> | VaultEvent;
+}
+/** Adapter class contract used in provider configuration. */
+interface PaymentAdapterConstructor {
+    new (config: Record<string, unknown>): PaymentAdapter;
+    readonly supportedMethods: readonly string[];
+    readonly supportedCurrencies: readonly string[];
+    readonly supportedCountries: readonly string[];
+}
+
+declare const DEFAULT_IDEMPOTENCY_TTL_MS = 86400000;
+interface IdempotencyRecord<T = unknown> {
+    key: string;
+    payloadHash: string;
+    result: T;
+    expiresAt: number;
+}
+interface IdempotencyStore<T = unknown> {
+    get(key: string): Promise<IdempotencyRecord<T> | null> | IdempotencyRecord<T> | null;
+    set(record: IdempotencyRecord<T>): Promise<void> | void;
+    delete(key: string): Promise<void> | void;
+    clearExpired(now?: number): Promise<void> | void;
+}
+
+declare class MemoryIdempotencyStore<T = unknown> implements IdempotencyStore<T> {
+    private readonly records;
+    get(key: string): IdempotencyRecord<T> | null;
+    set(record: IdempotencyRecord<T>): void;
+    delete(key: string): void;
+    clearExpired(now?: number): void;
+}
+
+declare function hashIdempotencyPayload(payload: unknown): string;
+
+type RoutingMatchValue = string | string[];
+interface RoutingMatch {
+    currency?: RoutingMatchValue;
+    country?: RoutingMatchValue;
+    paymentMethod?: RoutingMatchValue;
+    amountMin?: number;
+    amountMax?: number;
+    metadata?: Record<string, string>;
+    default?: boolean;
+}
+interface RoutingRule {
+    match: RoutingMatch;
+    provider: string;
+    weight?: number;
+}
+interface RoutingContext {
+    currency?: string;
+    country?: string;
+    paymentMethod?: string;
+    amount?: number;
+    metadata?: Record<string, string>;
+    providerOverride?: string;
+    exclude?: string[];
+}
+interface RoutingDecision {
+    provider: string;
+    reason: string;
+    rule: RoutingRule;
+}
+
+/** Logger contract used by `VaultClient` and `PlatformConnector`. */
+interface LoggerInterface {
+    error(message: string, context?: Record<string, unknown>): void;
+    warn(message: string, context?: Record<string, unknown>): void;
+    info(message: string, context?: Record<string, unknown>): void;
+    debug(message: string, context?: Record<string, unknown>): void;
+}
+/** Config for a single provider adapter instance. */
+interface ProviderConfig {
+    adapter: PaymentAdapterConstructor;
+    config: Record<string, unknown>;
+    priority?: number;
+    enabled?: boolean;
+}
+/** Root configuration object accepted by `new VaultClient(config)`. */
+interface VaultConfig {
+    providers: Record<string, ProviderConfig>;
+    routing?: {
+        rules: RoutingRule[];
+    };
+    idempotency?: {
+        store?: IdempotencyStore;
+        ttlMs?: number;
+    };
+    platformApiKey?: string;
+    platform?: {
+        baseUrl?: string;
+        timeoutMs?: number;
+        batchSize?: number;
+        flushIntervalMs?: number;
+        maxRetries?: number;
+        initialBackoffMs?: number;
+    };
+    logging?: {
+        level?: 'silent' | 'error' | 'warn' | 'info' | 'debug';
+        logger?: LoggerInterface;
+    };
+    timeout?: number;
+}
+
+declare class DLocalAdapter implements PaymentAdapter {
+    readonly name = "dlocal";
+    static readonly supportedMethods: readonly ["card", "pix", "boleto", "bank_transfer"];
+    static readonly supportedCurrencies: readonly ["BRL", "MXN", "ARS", "CLP", "COP", "PEN", "UYU", "BOB", "PYG", "CRC", "GTQ", "PAB", "DOP", "USD"];
+    static readonly supportedCountries: readonly ["BR", "MX", "AR", "CL", "CO", "PE", "UY", "BO", "PY", "CR", "GT", "PA", "DO", "EC", "SV", "NI", "HN"];
+    readonly metadata: {
+        supportedMethods: readonly ["card", "pix", "boleto", "bank_transfer"];
+        supportedCurrencies: readonly ["BRL", "MXN", "ARS", "CLP", "COP", "PEN", "UYU", "BOB", "PYG", "CRC", "GTQ", "PAB", "DOP", "USD"];
+        supportedCountries: readonly ["BR", "MX", "AR", "CL", "CO", "PE", "UY", "BO", "PY", "CR", "GT", "PA", "DO", "EC", "SV", "NI", "HN"];
+    };
+    private readonly config;
+    constructor(rawConfig: Record<string, unknown>);
+    charge(request: ChargeRequest): Promise<PaymentResult>;
+    authorize(request: AuthorizeRequest): Promise<PaymentResult>;
+    capture(request: CaptureRequest): Promise<PaymentResult>;
+    refund(request: RefundRequest): Promise<RefundResult>;
+    void(request: VoidRequest): Promise<VoidResult>;
+    getStatus(transactionId: string): Promise<TransactionStatus>;
+    listPaymentMethods(country: string, currency: string): Promise<PaymentMethodInfo[]>;
+    handleWebhook(payload: Buffer | string, headers: Record<string, string>): Promise<VaultEvent>;
+    private verifyWebhook;
+    private createPayment;
+    private normalizePaymentResult;
+    private buildHeaders;
+    private request;
+}
+
+declare class PaystackAdapter implements PaymentAdapter {
+    readonly name = "paystack";
+    static readonly supportedMethods: readonly ["card", "bank_transfer", "wallet"];
+    static readonly supportedCurrencies: readonly ["NGN", "GHS", "ZAR", "KES", "USD"];
+    static readonly supportedCountries: readonly ["NG", "GH", "ZA", "KE"];
+    readonly metadata: {
+        supportedMethods: readonly ["card", "bank_transfer", "wallet"];
+        supportedCurrencies: readonly ["NGN", "GHS", "ZAR", "KES", "USD"];
+        supportedCountries: readonly ["NG", "GH", "ZA", "KE"];
+    };
+    private readonly config;
+    constructor(rawConfig: Record<string, unknown>);
+    charge(request: ChargeRequest): Promise<PaymentResult>;
+    authorize(request: AuthorizeRequest): Promise<PaymentResult>;
+    capture(request: CaptureRequest): Promise<PaymentResult>;
+    refund(request: RefundRequest): Promise<RefundResult>;
+    void(request: VoidRequest): Promise<VoidResult>;
+    getStatus(transactionId: string): Promise<TransactionStatus>;
+    listPaymentMethods(country: string, currency: string): Promise<PaymentMethodInfo[]>;
+    handleWebhook(payload: Buffer | string, headers: Record<string, string>): Promise<VaultEvent>;
+    private verifyWebhook;
+    private buildChargePayload;
+    private normalizePaymentResult;
+    private request;
+}
+
+declare class StripeAdapter implements PaymentAdapter {
+    readonly name = "stripe";
+    static readonly supportedMethods: readonly ["card", "bank_transfer", "wallet"];
+    static readonly supportedCurrencies: readonly ["USD", "EUR", "GBP", "CAD", "AUD", "JPY", "CHF", "SEK", "NOK", "DKK", "NZD", "SGD", "HKD", "MXN", "BRL", "PLN", "CZK", "HUF", "RON", "BGN", "INR", "MYR", "THB"];
+    static readonly supportedCountries: readonly ["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"];
+    readonly metadata: {
+        supportedMethods: readonly ["card", "bank_transfer", "wallet"];
+        supportedCurrencies: readonly ["USD", "EUR", "GBP", "CAD", "AUD", "JPY", "CHF", "SEK", "NOK", "DKK", "NZD", "SGD", "HKD", "MXN", "BRL", "PLN", "CZK", "HUF", "RON", "BGN", "INR", "MYR", "THB"];
+        supportedCountries: readonly ["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"];
+    };
+    private readonly config;
+    constructor(rawConfig: Record<string, unknown>);
+    charge(request: ChargeRequest): Promise<PaymentResult>;
+    authorize(request: AuthorizeRequest): Promise<PaymentResult>;
+    capture(request: CaptureRequest): Promise<PaymentResult>;
+    refund(request: RefundRequest): Promise<RefundResult>;
+    void(request: VoidRequest): Promise<VoidResult>;
+    getStatus(transactionId: string): Promise<TransactionStatus>;
+    listPaymentMethods(country: string, currency: string): Promise<PaymentMethodInfo[]>;
+    handleWebhook(payload: Buffer | string, headers: Record<string, string>): Promise<VaultEvent>;
+    private verifyWebhook;
+    private createPaymentIntent;
+    private normalizePaymentResult;
+    private get;
+    private postForm;
+}
+
+/** Main orchestration client for charge, auth/capture, refund, void, and webhooks. */
+declare class VaultClient {
+    readonly config: VaultConfig;
+    private readonly adapters;
+    private readonly providerOrder;
+    private readonly router;
+    private readonly platformConnector;
+    private readonly idempotencyStore;
+    private readonly idempotencyTtlMs;
+    private readonly transactionProviderIndex;
+    constructor(config: VaultConfig);
+    charge(request: ChargeRequest): Promise<PaymentResult>;
+    authorize(request: AuthorizeRequest): Promise<PaymentResult>;
+    capture(request: CaptureRequest): Promise<PaymentResult>;
+    refund(request: RefundRequest): Promise<RefundResult>;
+    void(request: VoidRequest): Promise<VoidResult>;
+    getStatus(transactionId: string): Promise<TransactionStatus>;
+    listPaymentMethods(country: string, currency: string): Promise<PaymentMethodInfo[]>;
+    handleWebhook(provider: string, payload: Buffer | string, headers: Record<string, string>): Promise<VaultEvent>;
+    private resolveProviderForCharge;
+    private resolveProviderFromPlatform;
+    private resolveProviderForTransaction;
+    private getAdapter;
+    private withRouting;
+    private parseWebhookPayload;
+    private extractCardBin;
+    private queueTransactionReport;
+    private queueWebhookEvent;
+    private executeIdempotentOperation;
+    private wrapProviderCall;
+}
+
+type VaultErrorCategory = 'card_declined' | 'authentication_required' | 'invalid_request' | 'provider_error' | 'fraud_suspected' | 'rate_limited' | 'network_error' | 'configuration_error' | 'routing_error' | 'unknown';
+
+interface VaultErrorCodeDefinition {
+    category: VaultErrorCategory;
+    suggestion: string;
+    retriable: boolean;
+    docsPath?: string;
+}
+declare const VAULT_ERROR_CODE_DEFINITIONS: Record<string, VaultErrorCodeDefinition>;
+declare function getVaultErrorCodeDefinition(code: string): VaultErrorCodeDefinition;
+declare function buildVaultErrorDocsUrl(code: string, docsPath?: string): string;
+
+interface VaultErrorContext {
+    provider?: string;
+    operation?: string;
+    requestId?: string;
+    providerCode?: string;
+    providerMessage?: string;
+    [key: string]: unknown;
+}
+interface VaultErrorOptions {
+    code: string;
+    category?: VaultErrorCategory;
+    suggestion?: string;
+    docsUrl?: string;
+    retriable?: boolean;
+    context?: VaultErrorContext;
+}
+declare class VaultError extends Error {
+    readonly code: string;
+    readonly category: VaultErrorCategory;
+    readonly suggestion: string;
+    readonly docsUrl: string;
+    readonly retriable: boolean;
+    readonly context: VaultErrorContext;
+    constructor(message: string, options: VaultErrorOptions);
+}
+interface VaultSubclassOptions extends Omit<VaultErrorOptions, 'code'> {
+    code?: string;
+}
+declare class VaultConfigError extends VaultError {
+    constructor(message: string, options?: VaultErrorContext | VaultSubclassOptions);
+}
+declare class VaultRoutingError extends VaultError {
+    constructor(message: string, options?: VaultErrorContext | VaultSubclassOptions);
+}
+declare class VaultProviderError extends VaultError {
+    constructor(message: string, options?: VaultErrorContext | VaultSubclassOptions);
+}
+declare class VaultNetworkError extends VaultError {
+    constructor(message: string, options?: VaultErrorContext | VaultSubclassOptions);
+}
+declare class WebhookVerificationError extends VaultError {
+    constructor(message: string, options?: VaultErrorContext | VaultSubclassOptions);
+}
+declare class VaultIdempotencyConflictError extends VaultError {
+    constructor(message: string, options?: VaultErrorContext | VaultSubclassOptions);
+}
+
+/** Optional provider-side fields used to improve error classification. */
+interface ProviderErrorHint {
+    providerCode?: string;
+    providerMessage?: string;
+    requestId?: string;
+    httpStatus?: number;
+    declineCode?: string;
+    type?: string;
+    isNetworkError?: boolean;
+    isTimeout?: boolean;
+    raw?: unknown;
+}
+/** Context attached to mapped provider errors. */
+interface ProviderErrorMappingContext {
+    provider: string;
+    operation: string;
+}
+declare function isProviderErrorHint(value: unknown): value is ProviderErrorHint;
+/** Normalizes unknown provider errors into Vault error classes with stable codes. */
+declare function mapProviderError(error: unknown, mappingContext: ProviderErrorMappingContext): VaultError;
+
+declare class BatchBuffer<T> {
+    private readonly maxSize;
+    private readonly items;
+    constructor(maxSize: number);
+    push(item: T): T[] | null;
+    flush(): T[];
+    size(): number;
+}
+
+/** Platform telemetry and routing client configuration. */
+interface PlatformConnectorConfig {
+    apiKey: string;
+    baseUrl?: string;
+    timeoutMs?: number;
+    batchSize?: number;
+    flushIntervalMs?: number;
+    maxRetries?: number;
+    initialBackoffMs?: number;
+    logger?: LoggerInterface;
+    fetchFn?: typeof fetch;
+}
+interface ResolvedPlatformConnectorConfig extends PlatformConnectorConfig {
+    baseUrl: string;
+    timeoutMs: number;
+    batchSize: number;
+    flushIntervalMs: number;
+    maxRetries: number;
+    initialBackoffMs: number;
+}
+interface PlatformRoutingRequest {
+    currency: string;
+    amount: number;
+    paymentMethod: string;
+    country?: string;
+    cardBin?: string;
+    metadata?: Record<string, string>;
+}
+/** Response shape for remote routing decisions. */
+interface PlatformRoutingDecision {
+    provider: string | null;
+    source?: string;
+    reason?: string;
+    decisionId?: string;
+    ttlMs?: number;
+    cascade?: string[];
+}
+/** Transaction telemetry event sent to the VaultSaaS platform. */
+interface PlatformTransactionReport {
+    id: string;
+    provider: string;
+    providerId?: string;
+    status: string;
+    amount: number;
+    currency: string;
+    country?: string;
+    paymentMethod?: string;
+    cardBin?: string;
+    cardBrand?: string;
+    latencyMs?: number;
+    errorCategory?: string | null;
+    routingSource?: 'local' | 'platform';
+    routingDecisionId?: string;
+    idempotencyKey?: string;
+    timestamp: string;
+}
+/** Webhook forwarding payload sent to the VaultSaaS platform. */
+interface PlatformWebhookForwardEvent {
+    id: string;
+    type: string;
+    provider: string;
+    transactionId?: string;
+    providerEventId: string;
+    data: Record<string, unknown>;
+    timestamp: string;
+}
+/** Batches platform routing/telemetry requests with retry and timeout controls. */
+declare class PlatformConnector {
+    private static readonly DEFAULT_BASE_URL;
+    private static readonly DEFAULT_TIMEOUT_MS;
+    private static readonly DEFAULT_BATCH_SIZE;
+    private static readonly DEFAULT_FLUSH_INTERVAL_MS;
+    private static readonly DEFAULT_MAX_RETRIES;
+    private static readonly DEFAULT_INITIAL_BACKOFF_MS;
+    readonly config: ResolvedPlatformConnectorConfig;
+    readonly transactionBuffer: BatchBuffer<PlatformTransactionReport>;
+    readonly webhookBuffer: BatchBuffer<PlatformWebhookForwardEvent>;
+    private readonly fetchFn;
+    private readonly logger?;
+    private readonly flushTimer;
+    private transactionSendQueue;
+    private webhookSendQueue;
+    constructor(config: PlatformConnectorConfig);
+    close(): void;
+    decideRouting(request: PlatformRoutingRequest): Promise<PlatformRoutingDecision | null>;
+    queueTransactionReport(transaction: PlatformTransactionReport): void;
+    queueWebhookEvent(event: PlatformWebhookForwardEvent): void;
+    flush(): Promise<void>;
+    private enqueueTransactionBatch;
+    private enqueueWebhookBatch;
+    private postJson;
+    private fetchWithTimeout;
+    private normalizeRoutingDecision;
+    private backoffForAttempt;
+    private urlFor;
+    private delay;
+    private debug;
+    private warn;
+}
+
+/** Optional controls for routing behavior and capability validation. */
+interface RouterOptions {
+    random?: () => number;
+    adapterMetadata?: Record<string, AdapterMetadata>;
+    logger?: {
+        warn(message: string, context?: Record<string, unknown>): void;
+    };
+}
+/** Deterministic routing engine for selecting a provider from ordered rules. */
+declare class Router {
+    readonly rules: RoutingRule[];
+    private readonly random;
+    private readonly adapterMetadata;
+    private readonly logger?;
+    constructor(rules: RoutingRule[], options?: RouterOptions);
+    decide(context: RoutingContext): RoutingDecision | null;
+    private providerSupportsContext;
+    private getWeightedCandidates;
+    private selectWeightedRule;
+    private buildRuleReason;
+    private buildWeightedReason;
+    private getMatchCriteria;
+}
+
+declare function ruleMatchesContext(rule: RoutingRule, context: RoutingContext): boolean;
+
+declare class AdapterComplianceError extends Error {
+    readonly operation: string;
+    readonly field?: string;
+    constructor(operation: string, message: string, field?: string);
+}
+declare function validatePaymentResult(value: PaymentResult, operation: string, expectedProvider?: string): void;
+declare function validateRefundResult(value: RefundResult, operation?: string, expectedProvider?: string): void;
+declare function validateVoidResult(value: VoidResult, operation?: string, expectedProvider?: string): void;
+declare function validateTransactionStatus(value: TransactionStatus, operation?: string, expectedProvider?: string): void;
+declare function validatePaymentMethods(methods: PaymentMethodInfo[], operation?: string, expectedProvider?: string): void;
+declare function validateWebhookEvent(event: VaultEvent, operation?: string, expectedProvider?: string): void;
+interface AdapterComplianceHarness {
+    charge(request: ChargeRequest): Promise<PaymentResult>;
+    authorize(request: AuthorizeRequest): Promise<PaymentResult>;
+    capture(request: CaptureRequest): Promise<PaymentResult>;
+    refund(request: RefundRequest): Promise<RefundResult>;
+    void(request: VoidRequest): Promise<VoidResult>;
+    getStatus(transactionId: string): Promise<TransactionStatus>;
+    listPaymentMethods(country: string, currency: string): Promise<PaymentMethodInfo[]>;
+    handleWebhook(payload: Buffer | string, headers: Record<string, string>): Promise<VaultEvent>;
+}
+interface AdapterComplianceHarnessOptions {
+    expectedProvider?: string;
+}
+declare function createAdapterComplianceHarness(adapter: PaymentAdapter, options?: AdapterComplianceHarnessOptions): AdapterComplianceHarness;
+
+type SyncOrAsync<T> = T | Promise<T>;
+type ListPaymentMethodsInput = {
+    country: string;
+    currency: string;
+};
+type HandleWebhookInput = {
+    payload: Buffer | string;
+    headers: Record<string, string>;
+};
+type HandlerMap = {
+    charge: (request: ChargeRequest) => Promise<PaymentResult>;
+    authorize: (request: AuthorizeRequest) => Promise<PaymentResult>;
+    capture: (request: CaptureRequest) => Promise<PaymentResult>;
+    refund: (request: RefundRequest) => Promise<RefundResult>;
+    void: (request: VoidRequest) => Promise<VoidResult>;
+    getStatus: (transactionId: string) => Promise<TransactionStatus>;
+    listPaymentMethods: (country: string, currency: string) => Promise<PaymentMethodInfo[]>;
+    handleWebhook: (payload: Buffer | string, headers: Record<string, string>) => SyncOrAsync<VaultEvent>;
+};
+type MockAdapterHandlers = Partial<HandlerMap>;
+type MockAdapterScenario<Input, Output> = Output | Error | ((input: Input) => SyncOrAsync<Output>);
+interface MockAdapterScenarios {
+    charge: MockAdapterScenario<ChargeRequest, PaymentResult>[];
+    authorize: MockAdapterScenario<AuthorizeRequest, PaymentResult>[];
+    capture: MockAdapterScenario<CaptureRequest, PaymentResult>[];
+    refund: MockAdapterScenario<RefundRequest, RefundResult>[];
+    void: MockAdapterScenario<VoidRequest, VoidResult>[];
+    getStatus: MockAdapterScenario<string, TransactionStatus>[];
+    listPaymentMethods: MockAdapterScenario<ListPaymentMethodsInput, PaymentMethodInfo[]>[];
+    handleWebhook: MockAdapterScenario<HandleWebhookInput, VaultEvent>[];
+}
+interface MockAdapterOptions {
+    name?: string;
+    metadata?: AdapterMetadata;
+    handlers?: MockAdapterHandlers;
+    scenarios?: Partial<MockAdapterScenarios>;
+}
+declare class MockAdapter implements PaymentAdapter {
+    static readonly supportedMethods: readonly string[];
+    static readonly supportedCurrencies: readonly string[];
+    static readonly supportedCountries: readonly string[];
+    readonly name: string;
+    readonly metadata: AdapterMetadata;
+    private readonly handlers;
+    private readonly chargeScenarios;
+    private readonly authorizeScenarios;
+    private readonly captureScenarios;
+    private readonly refundScenarios;
+    private readonly voidScenarios;
+    private readonly statusScenarios;
+    private readonly paymentMethodsScenarios;
+    private readonly webhookScenarios;
+    constructor(options?: MockAdapterOptions | MockAdapterHandlers);
+    enqueue(method: 'charge', scenario: MockAdapterScenario<ChargeRequest, PaymentResult>): this;
+    enqueue(method: 'authorize', scenario: MockAdapterScenario<AuthorizeRequest, PaymentResult>): this;
+    enqueue(method: 'capture', scenario: MockAdapterScenario<CaptureRequest, PaymentResult>): this;
+    enqueue(method: 'refund', scenario: MockAdapterScenario<RefundRequest, RefundResult>): this;
+    enqueue(method: 'void', scenario: MockAdapterScenario<VoidRequest, VoidResult>): this;
+    enqueue(method: 'getStatus', scenario: MockAdapterScenario<string, TransactionStatus>): this;
+    enqueue(method: 'listPaymentMethods', scenario: MockAdapterScenario<ListPaymentMethodsInput, PaymentMethodInfo[]>): this;
+    enqueue(method: 'handleWebhook', scenario: MockAdapterScenario<HandleWebhookInput, VaultEvent>): this;
+    charge(request: ChargeRequest): Promise<PaymentResult>;
+    authorize(request: AuthorizeRequest): Promise<PaymentResult>;
+    capture(request: CaptureRequest): Promise<PaymentResult>;
+    refund(request: RefundRequest): Promise<RefundResult>;
+    void(request: VoidRequest): Promise<VoidResult>;
+    getStatus(transactionId: string): Promise<TransactionStatus>;
+    listPaymentMethods(country: string, currency: string): Promise<PaymentMethodInfo[]>;
+    handleWebhook(payload: Buffer | string, headers: Record<string, string>): Promise<VaultEvent>;
+}
+
+interface SignedWebhookPayload {
+    payload: string;
+    headers: Record<string, string>;
+}
+type WebhookSigningProvider = 'stripe' | 'dlocal' | 'paystack' | 'generic';
+interface SignedWebhookPayloadOptions {
+    provider?: WebhookSigningProvider;
+    timestamp?: number | string;
+    headerName?: string;
+}
+declare function createSignedWebhookPayload(payload: unknown, secret: string, options?: SignedWebhookPayloadOptions): SignedWebhookPayload;
+declare function createStripeSignedWebhookPayload(payload: unknown, secret: string, options?: Omit<SignedWebhookPayloadOptions, 'provider'>): SignedWebhookPayload;
+declare function createDLocalSignedWebhookPayload(payload: unknown, secret: string, options?: Omit<SignedWebhookPayloadOptions, 'provider'>): SignedWebhookPayload;
+declare function createPaystackSignedWebhookPayload(payload: unknown, secret: string, options?: Omit<SignedWebhookPayloadOptions, 'provider'>): SignedWebhookPayload;
+
+declare const DEFAULT_VAULT_EVENT_TYPES: readonly VaultEventType[];
+
+interface ProviderWebhookPayload {
+    id?: string;
+    type?: string;
+    transactionId?: string;
+    providerEventId?: string;
+    data?: Record<string, unknown>;
+    timestamp?: string;
+}
+declare function normalizeWebhookEvent(provider: string, payload: ProviderWebhookPayload, rawPayload?: unknown): VaultEvent;
+
+export { AdapterComplianceError, type AdapterMetadata, type AddressInput, type AuthorizeRequest, BatchBuffer, type CaptureRequest, type ChargeRequest, type CustomerInput, DEFAULT_IDEMPOTENCY_TTL_MS, DEFAULT_VAULT_EVENT_TYPES, DLocalAdapter, type IdempotencyRecord, type IdempotencyStore, type LoggerInterface, MemoryIdempotencyStore, MockAdapter, type MockAdapterHandlers, type MockAdapterOptions, type MockAdapterScenario, type MockAdapterScenarios, type PaymentAdapter, type PaymentAdapterConstructor, type PaymentMethodInfo, type PaymentMethodInput, type PaymentResult, type PaymentStatus, PaystackAdapter, PlatformConnector, type PlatformConnectorConfig, type PlatformRoutingDecision, type PlatformRoutingRequest, type PlatformTransactionReport, type PlatformWebhookForwardEvent, type ProviderConfig, type ProviderErrorHint, type ProviderErrorMappingContext, type ProviderWebhookPayload, type RefundRequest, type RefundResult, Router, type RouterOptions, type RoutingContext, type RoutingDecision, type RoutingMatch, type RoutingMatchValue, type RoutingPreference, type RoutingRule, type SignedWebhookPayload, type SignedWebhookPayloadOptions, type StatusChange, StripeAdapter, type TransactionStatus, VAULT_ERROR_CODE_DEFINITIONS, VaultClient, type VaultConfig, VaultConfigError, VaultError, type VaultErrorCategory, type VaultErrorContext, type VaultEvent, type VaultEventType, VaultIdempotencyConflictError, VaultNetworkError, VaultProviderError, VaultRoutingError, type VoidRequest, type VoidResult, type WebhookSigningProvider, WebhookVerificationError, buildVaultErrorDocsUrl, createAdapterComplianceHarness, createDLocalSignedWebhookPayload, createPaystackSignedWebhookPayload, createSignedWebhookPayload, createStripeSignedWebhookPayload, getVaultErrorCodeDefinition, hashIdempotencyPayload, isProviderErrorHint, mapProviderError, normalizeWebhookEvent, ruleMatchesContext, validatePaymentMethods, validatePaymentResult, validateRefundResult, validateTransactionStatus, validateVoidResult, validateWebhookEvent };