Node.js SDK

The PulseRoute Node.js SDK provides a lightweight client for integrating intelligent payment routing into Node.js applications. Zero dependencies, TypeScript support, fire-and-forget outcome reporting.

Install

npm install @pulseroute/sdk

Quick Start

const PulseRoute = require('@pulseroute/sdk');

const client = PulseRoute.init({
  apiKey: process.env.PULSEROUTE_API_KEY,
  baseUrl: 'http://localhost:8080',
});

// Get routing decision
const decision = await client.getRoute({
  country: 'US',
  currency: 'USD',
  paymentMethod: 'card',
  amount: 99.99,
});

console.log(`Route to: ${decision.processorId}`);
// => Route to: stripe

// Report outcome (fire-and-forget)
client.reportOutcome({
  ruleId: 'us_usd_card',
  processorId: decision.processorId,
  success: true,
  latencyMs: 120,
});

TypeScript

import { init, RoutingDecision, Outcome } from '@pulseroute/sdk';

const client = init({ apiKey: process.env.PULSEROUTE_API_KEY! });

const decision: RoutingDecision = await client.getRoute({
  country: 'US',
  currency: 'USD',
  amount: 49.99,
});

Configuration

Option	Type	Default	Description
apiKey	string	required	API key for authentication
baseUrl	string	http://localhost:8080	PulseRoute API URL
timeout	number	3000	HTTP timeout (ms)
flushInterval	number	1000	Outcome flush interval (ms)
maxBufferSize	number	500	Max buffered outcomes
enableCache	boolean	true	Cache routing decisions locally

Programmatic Onboarding

Set up routing rules from code instead of the dashboard wizard:

const result = await client.onboard({
  processors: [
    {
      processorId: 'stripe',
      name: 'Stripe',
      countries: ['US', 'GB'],
      currencies: ['USD', 'GBP'],
      paymentMethods: ['card', 'wallet'],
      priority: 1,
    },
    {
      processorId: 'adyen',
      name: 'Adyen',
      countries: ['US', 'GB', 'DE'],
      currencies: ['USD', 'GBP', 'EUR'],
      priority: 2,
    },
  ],
});

console.log(`${result.rulesCreated} rules created`);

Execute with Retry

Automatic failover: route a payment, and if the primary processor fails with a processor-side fault (timeout, 5xx, connection error), automatically retry on the fallback processor. Issuer-side declines (insufficient funds, card declined) are never retried.

const result = await client.executeWithRetry(
  async (processorId) => {
    // Your payment logic — called with the processor to use
    const charge = await yourPaymentGateway.charge(processorId, {
      amount: 9999,
      currency: 'usd',
    });
    return {
      success: charge.status === 'succeeded',
      errorCode: charge.error?.code,
      chargeId: charge.id,
    };
  },
  {
    country: 'US',
    currency: 'USD',
    ruleId: 'us_usd_card',
    maxRetries: 1, // try primary + 1 fallback (default)
  }
);

if (result.success) {
  console.log(`Charged via ${result.processorId}`);
} else {
  console.log(`Failed: ${result.error}, tried ${result.attempts.length} processors`);
}

// result.retried === true if fallback was used
// result.attempts contains details of each attempt

Fault Classification

The SDK classifies errors to decide whether to retry:

Retried (processor fault)	Not retried (issuer fault)
timeout, gateway_timeout	insufficient_funds
connection_error, connection_refused	card_declined, expired_card
service_unavailable, bad_gateway	fraud_detected, do_not_honor
processing_error, system_error	authentication_required

Unknown error codes are treated as processor faults (fail-safe: retry when unsure).

Resilience

The SDK is designed to never block your payment path:

• Outcome buffering: reportOutcome() returns immediately. Outcomes are flushed in the background.
• Local caching: If the API is unreachable, getRoute() returns the last known good decision.
• Graceful shutdown: await client.shutdown() flushes remaining outcomes before exit.
• Timeout protection: All API calls have a configurable timeout (default 3s).
• Automatic retry: executeWithRetry() cascades through fallback processors on infrastructure failures.

API Reference

See the full Node.js SDK README for detailed API documentation.