Configuration

Overview

The VaultConfig interface defines all configuration options accepted by new VaultClient(config). Configuration is validated on construction and will throw VaultConfigError if invalid.

VaultConfig

Root configuration object for VaultClient.

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;
}

providers

Record<string, ProviderConfig>

required

Map of provider names to their configurations. At least one enabled provider is required.

Show ProviderConfig properties

adapter

PaymentAdapterConstructor

required

The adapter class to use for this provider (e.g., StripeAdapter, DLocalAdapter)

config

Record<string, unknown>

required

Provider-specific configuration object (e.g., API keys, credentials)

priority

number

Provider priority for fallback routing. Lower numbers have higher priority. Default: 0

enabled

boolean

Whether this provider is enabled. Default: true

Example

import { VaultClient, StripeAdapter, DLocalAdapter } from '@vaultsaas/core';

const client = new VaultClient({
  providers: {
    stripe: {
      adapter: StripeAdapter,
      config: {
        apiKey: process.env.STRIPE_API_KEY,
      },
      priority: 0,
    },
    dlocal: {
      adapter: DLocalAdapter,
      config: {
        apiKey: process.env.DLOCAL_API_KEY,
        apiSecret: process.env.DLOCAL_SECRET,
      },
      priority: 1,
    },
  },
  routing: {
    rules: [{ match: { default: true }, provider: 'stripe' }],
  },
});

routing

object

Local routing configuration. Optional if using platform routing.

Show routing properties

rules

RoutingRule[]

required

Array of routing rules evaluated in order. Must include at least one default rule.

RoutingRule

Each routing rule matches transaction attributes and routes to a specific provider.

interface RoutingRule {
  match: {
    currency?: string | string[];
    country?: string | string[];
    paymentMethod?: string | string[];
    amountMin?: number;
    amountMax?: number;
    metadata?: Record<string, string>;
    default?: boolean;
  };
  provider: string;
  weight?: number;
}

match

object

required

Conditions that must be met for this rule to apply

Show match properties

currency

string | string[]

Match transactions with this currency (e.g., “USD”, [“USD”, “EUR”])

country

string | string[]

Match transactions from this country (e.g., “BR”, [“BR”, “AR”])

paymentMethod

string | string[]

Match transactions with this payment method type (e.g., “card”, [“pix”, “boleto”])

amountMin

number

Minimum transaction amount (inclusive, in smallest currency unit)

amountMax

number

Maximum transaction amount (inclusive, in smallest currency unit)

metadata

Record<string, string>

Match transactions with these metadata key-value pairs

default

boolean

If true, this rule matches all transactions (fallback rule). Required for at least one rule.

provider

string

required

The provider name to route to (must match a key in config.providers)

weight

number

Weight for probabilistic routing among multiple matching rules. Higher weights increase selection probability.

Routing Examples

const config: VaultConfig = {
  providers: {
    stripe: { /* ... */ },
    dlocal: { /* ... */ },
    paystack: { /* ... */ },
  },
  routing: {
    rules: [
      // Route Brazilian PIX to DLocal
      {
        match: { currency: 'BRL', paymentMethod: 'pix' },
        provider: 'dlocal',
      },
      // Route Nigerian transactions to Paystack
      {
        match: { country: 'NG' },
        provider: 'paystack',
      },
      // Route high-value USD transactions to Stripe
      {
        match: { currency: 'USD', amountMin: 100000 }, // $1000+
        provider: 'stripe',
      },
      // Load-balance remaining USD between Stripe (70%) and DLocal (30%)
      {
        match: { currency: 'USD' },
        provider: 'stripe',
        weight: 70,
      },
      {
        match: { currency: 'USD' },
        provider: 'dlocal',
        weight: 30,
      },
      // Default fallback to Stripe
      {
        match: { default: true },
        provider: 'stripe',
      },
    ],
  },
};

idempotency

object

Idempotency configuration for preventing duplicate operations

Show idempotency properties

store

IdempotencyStore

Custom idempotency store implementation. Default: MemoryIdempotencyStore (in-memory, not suitable for production)

ttlMs

number

Time-to-live for idempotency records in milliseconds. Default: 86400000 (24 hours)

IdempotencyStore Interface

Custom idempotency stores must implement:

interface IdempotencyStore {
  get(key: string): Promise<IdempotencyRecord | null>;
  set(record: IdempotencyRecord): Promise<void>;
  delete(key: string): Promise<void>;
  clearExpired(): Promise<void>;
}

interface IdempotencyRecord {
  key: string;
  payloadHash: string;
  result: unknown;
  expiresAt: number;
}

Example with Custom Redis Store

import { VaultClient, type IdempotencyStore, type IdempotencyRecord } from '@vaultsaas/core';
import Redis from 'ioredis';

// Custom Redis implementation of IdempotencyStore
class RedisIdempotencyStore implements IdempotencyStore {
  constructor(private redis: Redis) {}

  async get(key: string): Promise<IdempotencyRecord | null> {
    const data = await this.redis.get(`idempotency:${key}`);
    return data ? JSON.parse(data) : null;
  }

  async set(record: IdempotencyRecord): Promise<void> {
    const ttl = Math.max(0, record.expiresAt - Date.now());
    await this.redis.setex(
      `idempotency:${record.key}`,
      Math.ceil(ttl / 1000),
      JSON.stringify(record)
    );
  }

  async delete(key: string): Promise<void> {
    await this.redis.del(`idempotency:${key}`);
  }

  async clearExpired(): Promise<void> {
    // Redis TTL handles expiration automatically
  }
}

const redis = new Redis({
  host: 'localhost',
  port: 6379,
});

const client = new VaultClient({
  providers: { /* ... */ },
  idempotency: {
    store: new RedisIdempotencyStore(redis),
    ttlMs: 86400000, // 24 hours
  },
});

platformApiKey

string

API key for VaultSaaS platform integration. Enables platform routing, analytics, and monitoring.

Example

const client = new VaultClient({
  providers: { /* ... */ },
  platformApiKey: process.env.VAULTSAAS_API_KEY,
});

platform

object

Advanced platform connector configuration. Only relevant when platformApiKey is set.

Show platform properties

baseUrl

string

Platform API base URL. Default: https://api.vaultsaas.com

timeoutMs

number

Request timeout in milliseconds. Default: 5000 (5 seconds)

batchSize

number

Maximum number of events to batch before flushing. Default: 100

flushIntervalMs

number

Interval in milliseconds to flush batched events. Default: 10000 (10 seconds)

maxRetries

number

Maximum number of retry attempts for failed requests. Default: 3

initialBackoffMs

number

Initial backoff delay in milliseconds for retries. Default: 1000 (1 second)

Example

const client = new VaultClient({
  providers: { /* ... */ },
  platformApiKey: process.env.VAULTSAAS_API_KEY,
  platform: {
    timeoutMs: 3000,
    batchSize: 50,
    flushIntervalMs: 5000,
    maxRetries: 5,
  },
});

logging

object

Logging configuration for SDK operations

Show logging properties

level

'silent' | 'error' | 'warn' | 'info' | 'debug'

Logging level. Default: 'info'

logger

LoggerInterface

Custom logger implementation. If not provided, logs are output to console.

LoggerInterface

Custom loggers must implement:

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;
}

Example with Winston

import { VaultClient } from '@vaultsaas/core';
import winston from 'winston';

const logger = winston.createLogger({
  level: 'info',
  format: winston.format.json(),
  transports: [
    new winston.transports.File({ filename: 'vault.log' }),
  ],
});

const client = new VaultClient({
  providers: { /* ... */ },
  logging: {
    level: 'debug',
    logger: {
      error: (msg, ctx) => logger.error(msg, ctx),
      warn: (msg, ctx) => logger.warn(msg, ctx),
      info: (msg, ctx) => logger.info(msg, ctx),
      debug: (msg, ctx) => logger.debug(msg, ctx),
    },
  },
});

timeout

number

Global timeout in milliseconds for all payment operations. Individual adapters may have their own timeouts.

Example

const client = new VaultClient({
  providers: { /* ... */ },
  timeout: 30000, // 30 seconds
});

Validation

The SDK validates all configuration options on construction:

Required Fields

At least one provider must be configured
At least one provider must be enabled
Each provider must have a valid adapter constructor
Each provider must have a config object

Provider Validation

adapter must be a constructor function with static supportedMethods, supportedCurrencies, and supportedCountries arrays
config must be a plain object
priority must be an integer (if provided)
enabled must be a boolean (if provided)

Routing Validation

If routing is provided, rules must be a non-empty array
Each rule must have a provider that references an enabled provider
Each rule must have a match object
At least one rule must have match.default: true
amountMin and amountMax must be non-negative numbers
amountMin must not exceed amountMax
weight must be a positive number (if provided)

Idempotency Validation

ttlMs must be a positive integer (if provided)
store must implement all required methods: get, set, delete, clearExpired

Platform Validation

platformApiKey must not be empty (if provided)
baseUrl must not be empty (if provided)
timeoutMs, batchSize, flushIntervalMs, maxRetries, initialBackoffMs must all be positive integers (if provided)

Logging Validation

level must be one of: 'silent', 'error', 'warn', 'info', 'debug'
logger must implement all required methods: error, warn, info, debug

Complete Example

import { 
  VaultClient, 
  StripeAdapter, 
  DLocalAdapter, 
  PaystackAdapter,
  MemoryIdempotencyStore
} from '@vaultsaas/core';
import winston from 'winston';

const logger = winston.createLogger({
  level: 'info',
  format: winston.format.json(),
  transports: [
    new winston.transports.Console(),
    new winston.transports.File({ filename: 'vault.log' }),
  ],
});

const client = new VaultClient({
  // Provider configuration
  providers: {
    stripe: {
      adapter: StripeAdapter,
      config: {
        apiKey: process.env.STRIPE_API_KEY!,
      },
      priority: 0,
      enabled: true,
    },
    dlocal: {
      adapter: DLocalAdapter,
      config: {
        apiKey: process.env.DLOCAL_API_KEY!,
        apiSecret: process.env.DLOCAL_SECRET!,
      },
      priority: 1,
      enabled: true,
    },
    paystack: {
      adapter: PaystackAdapter,
      config: {
        secretKey: process.env.PAYSTACK_SECRET_KEY!,
      },
      priority: 2,
      enabled: true,
    },
  },

  // Routing rules
  routing: {
    rules: [
      {
        match: { currency: 'BRL', paymentMethod: 'pix' },
        provider: 'dlocal',
      },
      {
        match: { country: 'NG' },
        provider: 'paystack',
      },
      {
        match: { currency: 'USD' },
        provider: 'stripe',
      },
      {
        match: { default: true },
        provider: 'stripe',
      },
    ],
  },

  // Idempotency (use custom Redis store in production - see above example)
  idempotency: {
    store: new MemoryIdempotencyStore(),
    ttlMs: 86400000, // 24 hours
  },

  // Platform integration
  platformApiKey: process.env.VAULTSAAS_API_KEY,
  platform: {
    timeoutMs: 5000,
    batchSize: 100,
    flushIntervalMs: 10000,
    maxRetries: 3,
    initialBackoffMs: 1000,
  },

  // Logging
  logging: {
    level: 'info',
    logger: {
      error: (msg, ctx) => logger.error(msg, ctx),
      warn: (msg, ctx) => logger.warn(msg, ctx),
      info: (msg, ctx) => logger.info(msg, ctx),
      debug: (msg, ctx) => logger.debug(msg, ctx),
    },
  },

  // Global timeout
  timeout: 30000,
});

// Use the client
const result = await client.charge({
  amount: 5000,
  currency: 'BRL',
  paymentMethod: { type: 'pix' },
  customer: {
    email: '[email protected]',
    document: '12345678900',
  },
});

Client

Payment Operations

Types

Adapters

Overview

VaultConfig

providers

Example

routing

RoutingRule

Routing Examples

idempotency

IdempotencyStore Interface

Example with Custom Redis Store

platformApiKey

Example

platform

Example

logging

LoggerInterface

Example with Winston

timeout

Example

Validation

Required Fields

Provider Validation

Routing Validation

Idempotency Validation

Platform Validation

Logging Validation

Complete Example

Build docs developers (and LLMs) love

Client

Payment Operations

Types

Adapters

​Overview

​VaultConfig

​providers

​Example

​routing

​RoutingRule

​Routing Examples

​idempotency

​IdempotencyStore Interface

​Example with Custom Redis Store

​platformApiKey

​Example

​platform

​Example

​logging

​LoggerInterface

​Example with Winston

​timeout

​Example

​Validation

​Required Fields

​Provider Validation

​Routing Validation

​Idempotency Validation

​Platform Validation

​Logging Validation

​Complete Example

Build docs developers (and LLMs) love

Overview

VaultConfig

providers

Example

routing

RoutingRule

Routing Examples

idempotency

IdempotencyStore Interface

Example with Custom Redis Store

platformApiKey

Example

platform

Example

logging

LoggerInterface

Example with Winston

timeout

Example

Validation

Required Fields

Provider Validation

Routing Validation

Idempotency Validation

Platform Validation

Logging Validation

Complete Example