@scanfix/node

Node.js SDK for ScanFix error tracking. Works with Express, NestJS, and any Node.js application. Zero runtime dependencies — uses the built-in https/http modules only.

Installation

npm install @scanfix/node
# or
yarn add @scanfix/node
# or
pnpm add @scanfix/node

Quick Start

import { init } from '@scanfix/node';

const scanfix = init({
  apiKey: 'sf_your_api_key',       // Required — from your ScanFix project settings
  environment: 'production',        // Optional
  apiUrl: 'https://api.scanfix.ai', // Optional — override API endpoint
});

Call init() once at application startup (before any routes or middleware).

Express Integration

import express from 'express';
import { init, expressErrorHandler } from '@scanfix/node';

const scanfix = init({ apiKey: 'sf_your_key' });
const app = express();

// ... your routes ...

// Must be the LAST middleware (after all routes and other error handlers):
app.use(expressErrorHandler(scanfix));

The middleware automatically captures every Express error, enriches it with request metadata (URL, method, IP), strips sensitive headers (authorization, cookie, x-api-key), then calls next(error) to continue normal error handling.

NestJS Integration

// main.ts
import { NestFactory } from '@nestjs/core';
import { init, ScanFixExceptionFilter } from '@scanfix/node';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  const scanfix = init({ apiKey: process.env.SCANFIX_API_KEY! });

  // Apply globally — extend and decorate with @Catch() in your own app:
  // See example below for the recommended pattern.

  await app.listen(3000);
}

Custom exception filter (recommended):

// scanfix-filter.ts
import { Catch, ArgumentsHost } from '@nestjs/common';
import { ScanFixExceptionFilter } from '@scanfix/node';
import { scanfix } from './scanfix'; // your initialized client

@Catch()
export class AllExceptionsFilter extends ScanFixExceptionFilter {
  constructor() {
    super(scanfix);
  }
  catch(exception: unknown, host: ArgumentsHost) {
    super.catch(exception, host);
    // Add custom handling here if needed
  }
}

Manual API

import { captureError, log, flush } from '@scanfix/node';

// Capture Error objects or strings
captureError(new Error('DB connection lost'));
captureError('Queue processing failed', { jobId: 'job_456' });

// Log at any level with optional metadata
log('WARN', 'High memory usage', { heapUsed: process.memoryUsage().heapUsed });
log('INFO', 'Worker started', { pid: process.pid });

// Flush all queued logs immediately
await flush();

Class API (advanced)

import { ScanFixClient } from '@scanfix/node';

const client = new ScanFixClient({
  apiKey: 'sf_your_key',
  environment: 'staging',
  captureUnhandledErrors: false, // disable uncaughtException / unhandledRejection
});

client.captureError(new Error('Oops'));
await client.flush();
client.destroy(); // clear flush timer

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiKey | string | — | Required. Your ScanFix project API key (sf_...) | | environment | string | undefined | Tag logs with environment | | apiUrl | string | https://api.scanfix.ai | Override the ingestion endpoint | | captureUnhandledErrors | boolean | true | Auto-capture uncaughtException and unhandledRejection | | maxBatchSize | number | 10 | Flush when this many logs are queued | | flushIntervalMs | number | 5000 | Auto-flush interval in milliseconds |

Metadata Enrichment

All logs are automatically enriched with:

• hostname — os.hostname()
• pid — process.pid
• environment — from config

Process Exit Safety

The flush timer is unreffed (timer.unref()) so it never blocks process shutdown. A final flush() is called automatically on uncaughtException and unhandledRejection before the process exits.

Integration Example — Full Express App

import express from 'express';
import { init, expressErrorHandler, log } from '@scanfix/node';

const scanfix = init({
  apiKey: process.env.SCANFIX_API_KEY!,
  environment: process.env.NODE_ENV,
});

const app = express();
app.use(express.json());

app.get('/users/:id', async (req, res) => {
  log('INFO', 'Fetching user', { userId: req.params.id });
  // ... handler logic
});

// Error middleware MUST be last
app.use(expressErrorHandler(scanfix));

app.listen(3000, () => log('INFO', 'Server started', { port: 3000 }));