@usageflow/express

@usageflow/express

Express.js middleware for UsageFlow API tracking. Easily monitor and analyze your Express.js API usage with real-time tracking and allocation management.

Installation

npm install @usageflow/express

Quick Start

const express = require('express');
const { ExpressUsageFlowAPI } = require('@usageflow/express');

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

// Initialize UsageFlow with API key
const usageFlow = new ExpressUsageFlowAPI('YOUR_API_KEY');

// Apply middleware
app.use(usageFlow.createMiddleware());

// Your routes
app.get('/api/users', (req, res) => {
  res.json({ users: ['John', 'Jane'] });
});

app.listen(3000, () => {
  console.log('Server running on port 3000');
});

TypeScript Support

import express from 'express';
import { ExpressUsageFlowAPI } from '@usageflow/express';

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

// Initialize UsageFlow with API key
const usageFlow = new ExpressUsageFlowAPI('YOUR_API_KEY');

// Apply middleware
app.use(usageFlow.createMiddleware());

// Your routes
app.get('/api/users', (req, res) => {
  res.json({ users: ['John', 'Jane'] });
});

app.listen(3000, () => {
  console.log('Server running on port 3000');
});

Configuration

ExpressUsageFlowAPI

Constructor

constructor(apiKey: string)

• apiKey: Your UsageFlow API key (required)

createMiddleware

Creates Express middleware for tracking API usage. The middleware automatically tracks all routes and handles route configuration through the UsageFlow dashboard.

createMiddleware(): (req: Request, res: Response, next: NextFunction) => Promise<void>

Usage

// Simple usage - tracks all routes automatically
const usageFlow = new ExpressUsageFlowAPI('YOUR_API_KEY');
app.use(usageFlow.createMiddleware());

Route configuration (which routes to track, whitelist, etc.) is managed through the UsageFlow dashboard, not through code parameters.

Features

• Automatic Route Detection: Automatically detects route patterns from Express router
• Request Metadata Collection: Collects comprehensive request metadata including headers, query params, path params, and body
• Response Tracking: Tracks response status codes and duration
• WebSocket Communication: Uses WebSocket for real-time communication with UsageFlow API
• Connection Pooling: Maintains a pool of WebSocket connections for better performance
• Header Sanitization: Automatically sanitizes sensitive headers (authorization, API keys)
• Error Handling: Gracefully handles errors and provides meaningful error messages

Request Metadata

The middleware automatically collects the following metadata for each request:

• HTTP method
• Route pattern
• Raw URL
• Client IP (with X-Forwarded-For support)
• User agent
• Timestamp
• Headers (sanitized)
• Query parameters
• Path parameters
• Request body
• Response status code
• Request duration

Error Handling

If an allocation request fails, the middleware will:

• Return a 400 status code
• Include an error message in the response
• Set blocked: true in the response body

// Error response format
{
  message: "Error message",
  blocked: true
}

Advanced Usage

Custom Route Pattern Extraction

The middleware automatically extracts route patterns from Express. It supports:

• Direct route paths (req.route.path)
• Router stack traversal
• Nested routers
• Parameterized routes (/users/:id)

Ledger ID Generation

The middleware automatically generates ledger IDs based on:

• HTTP method and route pattern
• Configured identity fields from UsageFlow policies
• Identity field locations (path params, query params, body, bearer token, headers)

Requirements

• Node.js >= 18.0.0
• Express >= 4.17.0
• TypeScript >= 5.0.0 (for TypeScript projects)

Dependencies

• @usageflow/core: Core UsageFlow functionality
• express: Express.js framework

Development

# Install dependencies
npm install

# Build the package
npm run build

# Run tests
npm test

License

MIT

Support

For issues, questions, or contributions, please visit our GitHub repository.