🔍 ContractLens

Catch API breaking changes before your users do.

Lightweight runtime API contract validation for Node.js. Like Pact, but you add it in one line.

Quick Start · Features · Modes · Pact vs ContractLens

---

The Problem

You have microservices. They talk to each other via APIs. One team changes a response field. The other team's service breaks. Nobody knew until production was on fire.

Pact solves this but needs a broker, consumer tests, provider tests, and weeks of setup. express-openapi-validator validates requests within a single service, not the contract between services.

ContractLens sits in your Express app, watches every response, and tells you the moment your API drifts from its OpenAPI spec.

Quick Start

npm install contractlens

import express from 'express';
import { contractlens } from 'contractlens';

const app = express();

// One line. That's it.
app.use(contractlens({ spec: './openapi.yaml' }));

app.get('/users/:id', (req, res) => {
  res.json({ id: 1, name: 'Özer', role: 'backend' });
});

app.listen(3000);

If /users/:id response doesn't match your OpenAPI spec:

⚠️  ContractLens Drift Detected
├─ GET /users/123 → 200
├─ 🔴 Missing field: "email" (required in spec)
├─ ⚠️  Extra field: "role" (not in spec)
└─ Summary: 1 breaking, 1 warning

Features

• 🔴 Missing field detection — Spec says email is required, response doesn't have it? Breaking.
• ⚠️ Extra field detection — Response has cache_key not in spec? Warning.
• 🔴 Type mismatch — Spec says id: integer, response has "123"? Breaking.
• 🔴 Enum violation — Spec says status: active|inactive, response has "deleted"? Breaking.
• 📡 Webhook alerts — Send drift reports to Slack, PagerDuty, or any URL.
• ⚡ Production sampling — Validate 1% of requests, not all. Zero perf impact.
• 🎯 Express middleware — Drop it in, it works. No config files, no brokers, no setup.

Modes

// Development: log warnings to console
app.use(contractlens({ spec: './openapi.yaml', mode: 'warn' }));

// CI/Staging: throw error on drift (fail fast)
app.use(contractlens({ spec: './openapi.yaml', mode: 'strict' }));

// Production: sample 1% of requests, alert via webhook
app.use(contractlens({
  spec: './openapi.yaml',
  mode: 'log',
  sampleRate: 0.01,
  reporters: ['webhook'],
  webhookUrl: 'https://hooks.slack.com/services/...'
}));

What It Catches

Drift Type	Example	Severity
Missing required field	Spec requires email, response doesn't have it	🔴 Breaking
Extra field	Response has cache_key, spec doesn't define it	⚠️ Warning
Type mismatch	Spec says age: integer, response returns "25"	🔴 Breaking
Enum violation	Spec says status: active|inactive, response has "deleted"	🔴 Breaking

Configuration

contractlens({
  // Required: path to OpenAPI spec or inline object
  spec: './openapi.yaml',

  // 'warn' (default) | 'strict' | 'log'
  mode: 'warn',

  // Fraction of requests to validate (0.0 - 1.0)
  sampleRate: 1.0,

  // Reporter types
  reporters: ['console', 'webhook'],

  // Webhook URL for drift alerts
  webhookUrl: 'https://...',

  // Paths to skip validation
  exclude: ['/health', '/metrics'],
});

Pact vs ContractLens

	Pact	ContractLens
Setup time	Hours (broker, consumer/provider tests)	1 minute (one middleware line)
Approach	Consumer-driven contracts	Spec-driven runtime validation
Where it runs	CI/CD pipeline	Runtime (dev/staging/prod)
Catches drift in	Next CI run	Next request
Learning curve	Steep	Near zero
Dependencies	Pact broker, language-specific libs	Just your OpenAPI spec
Best for	Large teams, complex contract workflows	Teams who already have OpenAPI specs

ContractLens doesn't replace Pact — it complements it. Use Pact for formal contract workflows, use ContractLens for instant runtime drift detection.

How It Works

Request → Your Handler → Response
                            ↓
                      ContractLens
                      ├─ Load OpenAPI spec (cached)
                      ├─ Match route + status code
                      ├─ Validate response against schema
                      ├─ Detect drift (extra/missing/type/enum)
                      └─ Report via console/webhook

ContractLens intercepts res.json() after the response is sent (non-blocking in warn/log mode), so it adds zero latency to your API responses.

Examples

The examples/ directory contains runnable demos for common scenarios:

Example	Description
basic-usage.ts	Warn mode — logs drift to console, doesn't block responses
strict-mode.ts	Strict mode — returns 500 on contract drift (CI/staging)
production-setup.ts	Sampling + webhook alerts + path exclusion
custom-reporter.ts	Implement the Reporter interface for custom logging

git clone https://github.com/ozers/contractlens.git
cd contractlens
npm install && npm run build
npx ts-node examples/basic-usage.ts

Requirements

• Node.js >= 20
• Express >= 4.0
• An OpenAPI 3.0.x or 3.1.x specification

Contributing

Contributions are welcome! Please check out the issues page.

git clone https://github.com/ozers/contractlens.git
cd contractlens
npm install
npm run test
npm run build

License

MIT

---

Built by Ozer — a backend engineer who learned the hard way that a "harmless" field rename can take down three microservices on a Friday afternoon.