@xecurecode/node-sdk

AI-driven reliability SDK for Node.js applications.

The official Node.js SDK for the XecureTrace Reliability Platform — a human-first failure analysis and recovery recommendation system.

Why This SDK Exists

Modern backend systems fail in unpredictable ways.

This SDK:

• Captures structured runtime errors
• Generates deterministic fingerprints
• Classifies error types (DATABASE, NETWORK, VALIDATION, etc.)
• Determines severity
• Sends non-blocking telemetry to your backend
• Never crashes your application

AI assists. Humans decide. Nothing executes automatically.

Installation

npm install @xecurecode/node-sdk

Requirements

• Node.js 18+
• TypeScript (recommended)
• Express (optional, for middleware)

Quick Start

1️⃣ Initialize the SDK

import { ReliabilityClient } from "@xecurecode/node-sdk";

const reliability = new ReliabilityClient({
  apiKey: "your-api-key",
  service_id: "your-service",
  mode: "development"
});

Configuration Options: | Option | Required | Description | |--------|----------|-------------| | apiKey | Yes | Your API key | | service_id | Yes | Service identifier | | mode | Yes | development or production | | timeout | No | Request timeout (default: 5000ms) |

2️⃣ Automatic Global Error Capture

The SDK automatically tracks:

• uncaughtException
• unhandledRejection

// This will be automatically captured
throw new Error("Database timeout");

3️⃣ Express Integration

Add the middleware after all routes and include an error handler:

import express from "express";
import { ReliabilityClient } from "@xecurecode/node-sdk";

const reliability = new ReliabilityClient({
  apiKey: "your-api-key",
  service_id: "my-service",
  mode: "development"
});

const app = express();

// Your routes
app.get("/api/users", (req, res) => {
  throw new Error("Database connection failed");
});

// Add SDK middleware AFTER all routes
app.use(reliability.middleware());

// Error handler (required for Express to work properly)
app.use((err, req, res, next) => {
  res.status(500).json({ error: err.message });
});

app.listen(3000);

4️⃣ Manual Capture

try {
  riskyOperation();
} catch (err) {
  reliability.capture(err);
}

// With request context
reliability.capture(err, req);

What Gets Sent

Example structured payload:

{
  "message": "Database connection failed",
  "name": "Error",
  "fingerprint": "a8c39c21...",
  "timestamp": 1700000000000,
  "service_id": "my-service",
  "environment": "development",
  "severity": "critical",
  "errorType": "DATABASE",
  "serviceContext": {
    "pid": 12345,
    "nodeVersion": "v20.0.0",
    "platform": "linux",
    "hostname": "server-01"
  },
  "requestContext": {
    "method": "GET",
    "url": "/api/users",
    "ip": "10.0.0.5"
  },
  "occurrenceCount": 1
}

Error Classification

The SDK automatically categorizes errors:

| Type | Example | |------|---------| | DATABASE | Timeout, SQL errors, connection issues | | NETWORK | Fetch failures, socket errors | | VALIDATION | Invalid input, type errors | | RUNTIME | Standard JS errors | | UNKNOWN | Fallback |

Severity Detection

• Critical → Database, timeout, connection errors
• Warning → Validation, recoverable issues

Design Guarantees

• Non-blocking HTTP calls
• Timeout protected (5s default)
• Retry logic (3 attempts)
• Deduplication (1-minute window)
• Rate limiting
• Never throws inside SDK
• Never crashes host application
• No sensitive data leakage

API Reference

ReliabilityClient

const client = new ReliabilityClient(config);

// Capture an error
client.capture(error);
client.capture(error, requestContext);

// Express middleware
const middleware = client.middleware();

// Graceful shutdown
await client.flush();
client.shutdown();

Development

cd node_sdk
npm install
npm run build

Build outputs:

dist/
├── index.js      (CommonJS)
├── index.mjs     (ESM)
├── index.d.ts

Testing

Run the test server:

cd test_sdk
npm install
node index.ts

License

MIT