@afir/sdk - Node.js SDK for API Failure Recorder

A lightweight Node.js SDK for monitoring and tracking API failures in your web applications.

Installation

npm install @afir/sdk

Quick Start

Express Integration

import express from 'express';
import { createExpressMiddleware } from '@afir/sdk';

const app = express();

// Add the AFIR middleware
app.use(createExpressMiddleware({
  apiKey: 'your-api-key',
  endpoint: 'http://localhost:8000/api/v1',
  serviceName: 'my-api',
  environment: 'prod'
}));

// Your routes
app.get('/users/:id', (req, res) => {
  // If this returns 4xx/5xx, it will be tracked automatically
  res.json({ id: req.params.id });
});

app.listen(3000);

Manual Event Tracking

import { AFIRClient } from '@afir/sdk';

const client = new AFIRClient({
  apiKey: 'your-api-key',
  serviceName: 'my-service',
  environment: 'prod'
});

// Track an event manually
client.trackEvent({
  http_method: 'POST',
  path: '/api/payment',
  status_code: 500,
  latency_ms: 1500,
  error_payload: { error: 'Payment gateway timeout' }
});

// Shutdown gracefully
await client.shutdown();

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiKey | string | required | Your AFIR API key | | endpoint | string | http://localhost:8000/api/v1 | AFIR server URL | | serviceName | string | unknown-service | Service name | | environment | string | dev | Environment | | enabled | boolean | true | Enable/disable tracking | | batchSize | number | 10 | Events per batch | | flushIntervalMs | number | 5000 | Ms between flushes | | ignoredPaths | string[] | ["/health", ...] | Paths to skip | | minStatusCode | number | 400 | Minimum status to track |

Features

• ✅ Automatic failure detection (4xx/5xx responses)
• ✅ Request batching for efficiency
• ✅ Periodic flush for timely delivery
• ✅ Correlation ID support
• ✅ Automatic header redaction
• ✅ Graceful shutdown

License

MIT