api-observe 1.0.0 → 1.0.2

package/README.md

@@ -0,0 +1,395 @@
+# api-observe
+
+Framework-agnostic API failure tracker for Node.js. Captures failed HTTP requests with full request/response details and serves a built-in dashboard to browse them.
+
+Works with **Fastify**, **Express**, **NestJS**, **Koa**, or **plain Node.js HTTP**.
+
+## Features
+
+- Captures upstream API failures (via Axios interceptors)
+- Captures controller/route-level errors (via framework hooks)
+- Built-in HTML dashboard at `/observe`
+- REST API for querying failures programmatically
+- In-memory ring buffer with configurable size and TTL
+- Automatic redaction of sensitive headers (authorization, tokens, passwords)
+- Zero external dependencies
+
+## Install
+
+```bash
+npm install api-observe
+```
+
+## Quick Start
+
+### Fastify
+
+```js
+const Fastify = require('fastify');
+const apiObserve = require('api-observe');
+
+const fastify = Fastify();
+
+// Register the plugin
+await fastify.register(apiObserve, {
+  maxEntries: 500,      // max failure records to keep (default: 500)
+  ttlMs: 86400000,      // TTL in ms before eviction (default: 24h)
+  sanitize: (data) => data, // custom sanitizer (optional)
+});
+
+// Attach to your HTTP clients after registration
+fastify.after(() => {
+  // Option A: single client
+  fastify.observer.attach(myHttpClient);
+
+  // Option B: auto-attach to all clients on an object
+  fastify.observer.attachToAll(fastify.services);
+});
+
+await fastify.listen({ port: 3000 });
+// Dashboard: http://localhost:3000/observe
+```
+
+The Fastify plugin automatically captures:
+- **Upstream errors** - failed HTTP calls from attached clients (via Axios interceptors)
+- **Controller errors** - any error thrown during the request lifecycle (via `onError` hook)
+- **404s** - requests to non-existent routes (via `onResponse` hook)
+
+---
+
+### Express
+
+```js
+const express = require('express');
+const { expressMiddleware } = require('api-observe/express');
+
+const app = express();
+
+// Create the middleware
+const observe = expressMiddleware({
+  maxEntries: 500,
+  ttlMs: 86400000,
+});
+
+// Mount the dashboard and API routes
+app.use(observe);
+
+// ... your routes here ...
+
+// Mount the error handler AFTER your routes
+app.use(observe.errorHandler);
+
+// Attach to your HTTP clients
+observe.attach(myHttpClient);
+observe.attachToAll(myServices);
+
+app.listen(3000);
+// Dashboard: http://localhost:3000/observe
+```
+
+**`observe`** (main middleware) serves the dashboard and API routes at `/observe`.
+
+**`observe.errorHandler`** is an Express error middleware `(err, req, res, next)` that captures controller-level errors. Place it after your routes.
+
+---
+
+### Plain Node.js HTTP
+
+Works with any framework that exposes `(req, res)` — including Koa, NestJS, Hapi, etc.
+
+```js
+const http = require('http');
+const { createHttpHandler } = require('api-observe/http');
+
+const observe = createHttpHandler({
+  maxEntries: 500,
+  ttlMs: 86400000,
+});
+
+const server = http.createServer((req, res) => {
+  // Let api-observe handle /observe routes
+  if (observe.handle(req, res)) return;
+
+  // Your app logic...
+  res.end('Hello');
+});
+
+// Attach to your HTTP clients
+observe.attach(myHttpClient);
+
+// Manually capture errors
+try {
+  await doSomething();
+} catch (err) {
+  observe.captureError(err, {
+    method: 'POST',
+    url: '/api/users',
+    headers: req.headers,
+  });
+}
+
+server.listen(3000);
+// Dashboard: http://localhost:3000/observe
+```
+
+---
+
+### NestJS
+
+NestJS runs on Express (or Fastify) under the hood. Use the matching adapter:
+
+**NestJS + Express (default):**
+
+```js
+import { NestFactory } from '@nestjs/core';
+import { AppModule } from './app.module';
+import { expressMiddleware } from 'api-observe/express';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+
+  const observe = expressMiddleware();
+  app.use(observe);
+
+  // Attach to your HTTP clients
+  observe.attach(myHttpClient);
+
+  await app.listen(3000);
+}
+bootstrap();
+```
+
+**NestJS + Fastify:**
+
+```js
+import { NestFactory } from '@nestjs/core';
+import { FastifyAdapter } from '@nestjs/platform-fastify';
+import { AppModule } from './app.module';
+import apiObserve from 'api-observe';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule, new FastifyAdapter());
+
+  const fastify = app.getHttpAdapter().getInstance();
+  await fastify.register(apiObserve);
+
+  await app.listen(3000);
+}
+bootstrap();
+```
+
+## Dashboard
+
+Visit `/observe` in your browser to access the built-in dashboard.
+
+The dashboard provides:
+- Real-time failure table with filtering by type, service, method, status code, and URL
+- Summary cards showing total failures, upstream vs controller errors, and affected services
+- Detail modal with full request/response headers, bodies, and stack traces
+- Auto-refresh every 30 seconds
+- Pagination for large result sets
+
+## REST API
+
+All endpoints are served under `/observe/api/`:
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/observe` | HTML dashboard |
+| `GET` | `/observe/api/failures` | List failures (with filters) |
+| `GET` | `/observe/api/failures/:id` | Single failure detail |
+| `GET` | `/observe/api/summary` | Stats grouped by service/status |
+| `DELETE` | `/observe/api/failures` | Clear all stored failures |
+
+### Query Parameters for `GET /observe/api/failures`
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `type` | string | Filter by `upstream` or `controller` |
+| `service` | string | Filter by service name (partial match) |
+| `method` | string | Filter by HTTP method (`GET`, `POST`, etc.) |
+| `statusCode` | number | Filter by response status code |
+| `url` | string | Filter by URL (partial match) |
+| `from` | string | Start date (ISO 8601) |
+| `to` | string | End date (ISO 8601) |
+| `limit` | number | Results per page (default: 50) |
+| `offset` | number | Pagination offset (default: 0) |
+
+### Example
+
+```bash
+# Get all 5xx failures from the auth service
+curl "http://localhost:3000/observe/api/failures?service=auth&statusCode=500"
+
+# Get summary stats
+curl "http://localhost:3000/observe/api/summary"
+```
+
+## Configuration Options
+
+All adapters accept the same options:
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `maxEntries` | number | `500` | Maximum failure records to keep in memory |
+| `ttlMs` | number | `86400000` (24h) | Time-to-live in ms before entries are evicted |
+| `sanitize` | function | built-in | Custom sanitizer for request/response bodies |
+
+### Default Sanitization
+
+The built-in sanitizer redacts these headers/fields automatically:
+
+- `authorization`
+- `x-access-token`
+- `cookie` / `set-cookie`
+- `secret` / `password` / `token`
+- `refresh`
+- `x-api-key`
+
+To customize, pass your own `sanitize` function:
+
+```js
+apiObserve({
+  sanitize: (data) => {
+    if (!data || typeof data !== 'object') return data;
+    const copy = { ...data };
+    delete copy.ssn;
+    delete copy.creditCard;
+    return copy;
+  },
+});
+```
+
+## Compatible HTTP Client
+
+`api-observe` intercepts failures from any HTTP client object that exposes:
+- `_axios` — an Axios instance
+- `serviceName` — a string identifier for the service
+
+Below is a sample `BaseHttpClient` class that works out of the box:
+
+```js
+const axios = require('axios');
+
+class BaseHttpClient {
+  constructor({ baseUrl, serviceName, timeoutMs = 5000 }) {
+    this.serviceName = serviceName;
+
+    this._axios = axios.create({
+      baseURL: baseUrl,
+      timeout: timeoutMs,
+      headers: {
+        'Content-Type': 'application/json',
+        Accept: 'application/json',
+      },
+    });
+  }
+
+  async get(path, options = {}) {
+    const res = await this._axios.get(path, {
+      params: options.params,
+      correlationId: options.correlationId,
+    });
+    return res.data;
+  }
+
+  async post(path, data, options = {}) {
+    const res = await this._axios.post(path, data, {
+      correlationId: options.correlationId,
+    });
+    return res.data;
+  }
+
+  async put(path, data, options = {}) {
+    const res = await this._axios.put(path, data, {
+      correlationId: options.correlationId,
+    });
+    return res.data;
+  }
+
+  async delete(path, options = {}) {
+    const res = await this._axios.delete(path, {
+      correlationId: options.correlationId,
+    });
+    return res.data;
+  }
+}
+
+module.exports = { BaseHttpClient };
+```
+
+### Creating a service client
+
+Wrap `BaseHttpClient` in a service class for each upstream API:
+
+```js
+const { BaseHttpClient } = require('./base-http.client');
+
+class UserService {
+  constructor(config) {
+    this.client = new BaseHttpClient({
+      baseUrl: config.baseUrl,
+      serviceName: 'user-service',
+      timeoutMs: config.timeoutMs,
+    });
+  }
+
+  async getUserById(id, opts = {}) {
+    return this.client.get(`/v1/users/${id}`, {
+      correlationId: opts.correlationId,
+    });
+  }
+
+  async createUser(data, opts = {}) {
+    return this.client.post('/v1/users', data, {
+      correlationId: opts.correlationId,
+    });
+  }
+}
+
+module.exports = UserService;
+```
+
+### Attaching to api-observe
+
+```js
+// Single client
+observe.attach(userService.client);
+
+// Or auto-attach all clients on an object — api-observe will find
+// any value (or value.client) that has _axios + serviceName
+const services = {
+  userService: new UserService({ baseUrl: 'http://user-svc:4001' }),
+  orderService: new OrderService({ baseUrl: 'http://order-svc:4002' }),
+};
+observe.attachToAll(services);
+```
+
+`attachToAll` walks the object's keys and attaches to:
+- Direct `BaseHttpClient` instances (has `_axios` + `serviceName`)
+- Service wrappers with a `.client` property that is a `BaseHttpClient`
+
+## Exports
+
+```js
+// Default: Fastify plugin
+const apiObserve = require('api-observe');
+
+// Express adapter
+const { expressMiddleware } = require('api-observe/express');
+
+// Plain HTTP adapter
+const { createHttpHandler } = require('api-observe/http');
+
+// Core building blocks (for custom integrations)
+const {
+  FailureStore,        // In-memory failure store
+  attachInterceptor,   // Attach to a single client
+  attachToAll,         // Auto-attach to all clients on an object
+  createRouter,        // Framework-agnostic route handler
+} = require('api-observe');
+```
+
+## License
+
+MIT

package/lib/interceptor.js

@@ -33,8 +33,8 @@ function attachInterceptor(client, store, opts = {}) {
   }
 
   // Mark this client so we don't double-attach
-  if (client.__psObserveAttached) return;
-  client.__psObserveAttached = true;
+  if (client.__observerAttached) return;
+  client.__observerAttached = true;
 
   // ── Eject existing response interceptors ───────────���────────────────────
   // Save them, clear them, add ours first, then re-add the originals.

package/lib/plugin.js

@@ -7,9 +7,9 @@
  *
  * Usage in a consuming service:
  *
- *   const psObserve = require('@pruservices/ps-observe');
+ *   const observer = require('@pruservices/ps-observe');
  *
- *   fastify.register(psObserve, {
+ *   fastify.register(observer, {
  *     // (optional) max failure records to keep in memory (default: 500)
  *     maxEntries: 500,
  *
@@ -26,10 +26,10 @@
  *   // After registering your service clients, attach the interceptors:
  *   fastify.after(() => {
  *     // Option A: Attach to individual clients
- *     fastify.psObserve.attach(myClient);
+ *     fastify.observer.attach(myClient);
  *
  *     // Option B: Auto-attach to all clients on an object
- *     fastify.psObserve.attachToAll(fastify.services);
+ *     fastify.observer.attachToAll(fastify.services);
  *   });
  */
 
@@ -37,7 +37,7 @@ const { FailureStore } = require('./failure-store');
 const { attachInterceptor, attachToAll } = require('./interceptor');
 const { registerRoutes } = require('./routes');
 
-async function psObservePlugin(fastify, opts) {
+async function observerPlugin(fastify, opts) {
   const store = new FailureStore({
     maxEntries: opts.maxEntries,
     ttlMs: opts.ttlMs,
@@ -46,7 +46,7 @@ async function psObservePlugin(fastify, opts) {
   const sanitizeOpts = opts.sanitize ? { sanitize: opts.sanitize } : {};
 
   // Decorate fastify with the observe API so consumers can attach clients
-  fastify.decorate('psObserve', {
+  fastify.decorate('observer', {
     /** Attach interceptor to a single BaseHttpClient instance */
     attach(client) {
       attachInterceptor(client, store, sanitizeOpts);
@@ -151,7 +151,7 @@ async function psObservePlugin(fastify, opts) {
   registerRoutes(fastify, store);
 }
 
-// Skip encapsulation so psObserve decorator is visible to the parent scope
-psObservePlugin[Symbol.for('skip-override')] = true;
+// Skip encapsulation so observer decorator is visible to the parent scope
+observerPlugin[Symbol.for('skip-override')] = true;
 
-module.exports = psObservePlugin;
+module.exports = observerPlugin;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "api-observe",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Framework-agnostic plugin that captures and displays API failure details — works with Fastify, Express, NestJS, Koa, or plain Node.js HTTP",
   "main": "lib/index.js",
   "files": [