Gateway Pulse 💓

gateway-pulse is a robust, heavily typed Node.js package designed to monitor the health and uptime of various payment gateways. It intelligently combines status page data with direct API pings, guards against transient failures, and alerts your team through multiple channels when issues arise.

Installation

npm install gateway-pulse

Quick Start

Create a simple monitor that checks Stripe every 30 seconds and logs to the console:

import { GatewayMonitor } from 'gateway-pulse';

const monitor = new GatewayMonitor({
  gateways: ['stripe'],
  interval: 30,
});

monitor.on('down', (event) => {
  console.log(`🚨 ${event.gateway} is DOWN!`);
});

monitor.on('up', (event) => {
  console.log(`✅ ${event.gateway} recovered.`);
});

monitor.start();

Supported Gateways

You can pass the following lowercase strings in the gateways array:

| Gateway | ID | | :-------- | :---------- | | Stripe | stripe | | PayPal | paypal | | Razorpay | razorpay | | Braintree | braintree | | Square | square | | Adyen | adyen |

Configuration

The GatewayMonitor accepts a MonitorConfig object upon initialization:

| Option | Type | Default | Description | | :------------------ | :---------------------------- | :------ | :-------------------------------------------------------------------- | | gateways | (string \| GatewayConfig)[] | [] | List of gateway IDs or custom gateway configurations. | | interval | number | 60 | Polling interval in seconds. | | timeout | number | 10000 | HTTP request timeout in milliseconds. | | failureThreshold | number | 3 | Consecutive failures before dispatching a down or degraded alert. | | recoveryThreshold | number | 2 | Consecutive successes before dispatching an up (recovery) alert. | | debug | boolean | false | Enables verbose internal logging. | | notify | NotifyConfig | {} | Settings for configuring notification integrations. |

Notification Channels

The library includes resilient notifiers to distribute alerts automatically:

| Channel | Config Needed | Description | | :-------- | :---------------------------- | :--------------------------------------------------------------- | | Console | (Always on) | ANSI-colored terminal logs. | | Slack | notify.slack.webhookUrl | Rich Block Kit messages delivered to a Slack channel. | | Webhook | notify.webhook.url | Sends standard JSON AlertEvent payloads. | | Email | notify.email | Beautiful HTML email tables delivered via SMTP (Nodemailer). | | PagerDuty | notify.pagerduty.routingKey | Triggers and resolves incidents in PagerDuty via the Events API. |

Events API

You can hook directly into the GatewayMonitor instance since it extends EventEmitter:

monitor.on('down', (event: AlertEvent) => {
  /* Gateway went down */
});
monitor.on('degraded', (event: AlertEvent) => {
  /* Gateway is experiencing partial outages or high latency */
});
monitor.on('up', (event: AlertEvent) => {
  /* Gateway recovered fully */
});
monitor.on('check', (result: CheckResult) => {
  /* Fired quietly on EVERY check */
});
monitor.on('error', (err: { gateway: string; error: Error }) => {
  /* Fired on execution or HTTP faults */
});

Custom Gateways

If your payment provider isn't supported out-of-the-box, or you want to track internal APIs, provide a GatewayConfig directly to the gateways array:

monitor = new GatewayMonitor({
  gateways: [
    'stripe',
    {
      name: 'my-api',
      pingUrl: 'https://api.myapp.com/ping',
      statusPageUrl: 'https://status.myapp.com/api/v2/status.json', // Required to be Atlassian Statuspage v2 format
      incidentUrl: 'https://status.myapp.com',
    },
  ],
});

TypeScript Support

gateway-pulse is written entirely in strict TypeScript. All types and interfaces (Option, GatewayConfig, CheckResult, AlertEvent) are exposed via:

import { AlertEvent, GatewayConfig, CheckResult } from 'gateway-pulse';

Contributing

1. Fork the repo and create your feature branch.
2. Ensure you have Node.js installed.
3. Run npm install, then execute the test suite npm test.
4. Ensure 80% coverage and no lint errors.

License

MIT