apitrap 1.1.0

package/README.md

@@ -0,0 +1,200 @@
+# apitrap
+
+**Turn your Express routes into living API documentation — automatically.**
+
+Most teams write their API docs manually, or forget to update them after changes.  
+`apitrap` captures real API traffic as it happens and sends it to your monitor dashboard, so your collection always reflects what your API _actually does_.
+
+```bash
+npm install apitrap
+```
+
+---
+
+## How it works
+
+Add one middleware per route group. Every time a request hits that route, the library captures the method, path, body, query, response, status code, and duration — then sends it to your monitor server in the background.
+
+No manual effort. No extra tools. Just traffic → collection.
+
+---
+
+## Quick start
+
+### 1. Initialize (once, in your entry file)
+
+```javascript
+const { initApiCapture } = require("apitrap");
+
+initApiCapture({
+  appName: "my-app",
+  monitorUrl: "https://your-monitor-server.com/api/capture",
+  monitorApiKey: process.env.MONITOR_API_KEY,
+});
+```
+
+### 2. Add to your routes
+
+```javascript
+const { getClient } = require("apitrap");
+
+const router = express.Router();
+const auth = getClient().createMiddlewareFactory("Authentication");
+
+router.post(
+  "/login",
+  auth.capture("User login", "Login page"),
+  async (req, res) => {
+    // your logic here
+    res.json({ success: true });
+  },
+);
+
+router.post(
+  "/register",
+  auth.capture("New user registration", ["Login page", "Onboarding"]),
+  async (req, res) => {
+    res.json({ userId: "..." });
+  },
+);
+```
+
+That's it. Both routes are now tracked in your dashboard under the **Authentication** group.
+
+---
+
+## TypeScript
+
+```typescript
+import { initApiCapture, getClient } from "apitrap";
+
+initApiCapture({
+  appName: "my-ts-app",
+  monitorUrl: process.env.MONITOR_URL,
+  monitorApiKey: process.env.MONITOR_API_KEY,
+});
+
+const api = getClient().createMiddlewareFactory("Products");
+
+router.get("/products", api.capture("List all products"), handler);
+```
+
+---
+
+## Try it without a monitor server
+
+Skip `monitorUrl` entirely. The library switches to **debug mode** and prints captured data to your console — perfect for development.
+
+```javascript
+initApiCapture({
+  appName: "local-test",
+  // no monitorUrl needed
+});
+```
+
+Output:
+
+```
+--- [ApiCapture] [200] 12ms ---
+[POST] /api/login
+Desc: User login
+Body: { "email": "user@example.com", "password": "[REDACTED]" }
+Response: { "success": true }
+---------------------------
+```
+
+---
+
+## Save to a local file
+
+Useful for offline inspection or building your initial API collection before setting up a monitor server:
+
+```javascript
+initApiCapture({
+  appName: "my-app",
+  saveLocal: true,
+  localPath: "./data/api-capture.json",
+});
+```
+
+---
+
+## Sensitive data is always masked
+
+Passwords, tokens, and secrets are automatically redacted before leaving your server. You can add custom keys too:
+
+```javascript
+initApiCapture({
+  sensitiveKeys: ["ssn", "tax-id", "card-number"],
+});
+```
+
+The following keys are masked by default (case-insensitive): `password`, `token`, `secret`, `creditcard`, `pin`, `auth`, `authorization`, `cookie`.
+
+---
+
+## Graceful shutdown
+
+If you need to make sure all captured events are flushed before your server stops:
+
+```javascript
+process.on("SIGTERM", async () => {
+  await getClient().shutdown();
+  process.exit(0);
+});
+```
+
+---
+
+## Configuration
+
+| Option          | Type       | Default                   | Description                                             |
+| :-------------- | :--------- | :------------------------ | :------------------------------------------------------ |
+| `appName`       | `string`   | `"Unknown App"`           | App name shown in the monitor dashboard                 |
+| `monitorUrl`    | `string`   | —                         | Endpoint of your monitor server                         |
+| `monitorApiKey` | `string`   | —                         | API key for authenticating with the monitor server      |
+| `enabled`       | `boolean`  | `true`                    | Master switch — set to `false` to disable all capturing |
+| `debug`         | `boolean`  | `true` if no `monitorUrl` | Print captured data to console instead of sending       |
+| `saveLocal`     | `boolean`  | `false`                   | Append captured events to a local JSON file             |
+| `localPath`     | `string`   | `./captured-apis.json`    | Path for the local JSON file                            |
+| `sensitiveKeys` | `string[]` | See above                 | Additional keys to redact from bodies and queries       |
+| `batchSize`     | `number`   | `10`                      | Max events per HTTP batch to the monitor server         |
+| `batchInterval` | `number`   | `3000`                    | How often (ms) to flush the event queue                 |
+
+---
+
+## What gets captured per request
+
+| Field        | Description                                    |
+| :----------- | :--------------------------------------------- |
+| `route`      | Full URL path including query string           |
+| `method`     | HTTP method (GET, POST, etc.)                  |
+| `body`       | Request body (sensitive keys redacted)         |
+| `query`      | Query parameters                               |
+| `response`   | Response body (sensitive keys redacted)        |
+| `statusCode` | HTTP status code                               |
+| `durationMs` | Request processing time in milliseconds        |
+| `desc`       | Your description for this endpoint             |
+| `menus`      | Menu/page labels for grouping in the UI        |
+| `routeName`  | Group name (set via `createMiddlewareFactory`) |
+| `capturedAt` | ISO timestamp                                  |
+
+---
+
+## Changelog
+
+### v1.1.0
+
+- **Response capture** — `res.json()` is now intercepted to capture response body
+- **Status code + duration** — every captured event includes HTTP status and response time
+- **Async local save** — file I/O is now non-blocking
+- **Batch sender** — events are queued and sent in batches to reduce HTTP overhead
+- **Deep masking fix** — nested sensitive keys are now correctly redacted
+- **`enabled` config** — replaces `openGen` (still supported for backward compatibility)
+- **`shutdown()` method** — flush pending events before process exit
+
+---
+
+## License
+
+ISC

package/index.d.ts

@@ -0,0 +1,117 @@
+import { Request, Response, NextFunction } from "express";
+
+export interface ApiCaptureConfig {
+  /** ชื่อแอปพลิเคชัน */
+  appName?: string;
+
+  /** URL ของ Monitor Server */
+  monitorUrl?: string;
+
+  /** API Key สำหรับ authenticate กับ Monitor Server */
+  monitorApiKey?: string;
+
+  /**
+   * เปิด/ปิดการ capture (ค่าเริ่มต้น: true)
+   * @alias openGen (deprecated — ใช้ enabled แทน)
+   */
+  enabled?: boolean;
+
+  /** @deprecated ใช้ enabled แทน */
+  openGen?: boolean;
+
+  /** เปิด debug mode — print ข้อมูลลง console แทนการยิง API */
+  debug?: boolean;
+
+  /** บันทึกข้อมูลลงไฟล์ JSON (ค่าเริ่มต้น: false) */
+  saveLocal?: boolean;
+
+  /** path ของไฟล์ที่จะบันทึก (ค่าเริ่มต้น: ./captured-apis.json) */
+  localPath?: string;
+
+  /** Keys เพิ่มเติมที่ต้องการ redact (case-insensitive) */
+  sensitiveKeys?: string[];
+
+  /**
+   * จำนวน events ต่อ batch (ค่าเริ่มต้น: 10)
+   * เมื่อ queue เต็มจะ flush ทันที
+   */
+  batchSize?: number;
+
+  /**
+   * ช่วงเวลา flush อัตโนมัติ เป็น ms (ค่าเริ่มต้น: 3000)
+   */
+  batchInterval?: number;
+}
+
+export interface ApiCaptureParams {
+  routeName?: string;
+  menus?: string[];
+  route?: string;
+  method?: string;
+  desc?: string;
+  body?: any;
+  query?: any;
+  /** v1.x: response body ที่ถูก intercept */
+  responseBody?: any;
+  /** v1.x: HTTP status code ของ response */
+  statusCode?: number;
+  /** v1.x: เวลาที่ใช้ในการ process request (ms) */
+  durationMs?: number;
+}
+
+export type MiddlewareFunction = (
+  req: Request,
+  res: Response,
+  next: NextFunction,
+) => void;
+
+export interface MiddlewareFactory {
+  /**
+   * สร้าง Express middleware สำหรับ route นั้นๆ
+   * @param desc - คำอธิบาย API
+   * @param menus - ชื่อเมนูที่ใช้ API นี้ (optional)
+   */
+  capture: (desc?: string, menus?: string | string[]) => MiddlewareFunction;
+}
+
+export class ApiCaptureClient {
+  serverUrl: string;
+  apiKey: string;
+  enabled: boolean;
+  appName: string;
+  debug: boolean;
+  saveLocal: boolean;
+  localPath: string;
+  sensitiveKeys: string[];
+
+  constructor(config?: ApiCaptureConfig);
+
+  maskSensitiveData(data: any): any;
+  capture(params: ApiCaptureParams): void;
+
+  /**
+   * สร้าง Middleware factory สำหรับกลุ่ม routes
+   * @param routeName - ชื่อกลุ่ม route (แสดงใน dashboard)
+   * @param routeEnabled - เปิด/ปิด capture สำหรับกลุ่มนี้ (ค่าเริ่มต้น: true)
+   */
+  createMiddlewareFactory(
+    routeName: string,
+    routeEnabled?: boolean,
+  ): MiddlewareFactory;
+
+  /**
+   * Flush ข้อมูลที่ค้างอยู่ใน queue และหยุด timer
+   * ควรเรียกก่อน process.exit()
+   */
+  shutdown(): Promise<void>;
+}
+
+/**
+ * Initialize ApiCapture client แบบ Singleton
+ */
+export function initApiCapture(config?: ApiCaptureConfig): ApiCaptureClient;
+
+/**
+ * ดึง client instance ที่ init ไว้แล้ว
+ */
+export function getClient(): ApiCaptureClient;

package/index.js

@@ -0,0 +1,395 @@
+const http = require("http");
+const https = require("https");
+const fs = require("fs");
+const fsPromises = require("fs").promises;
+const path = require("path");
+
+class ApiCaptureClient {
+  constructor(config = {}) {
+    this.serverUrl = config.monitorUrl || process.env.MONITOR_URL;
+    this.apiKey = config.monitorApiKey || process.env.MONITOR_API_KEY || "";
+    this.appName = config.appName || "Unknown App";
+    this.debug = config.debug === true || !this.serverUrl;
+
+    // v1.x: รองรับทั้ง enabled และ openGen (backward compat)
+    if (config.enabled !== undefined) {
+      this.enabled = config.enabled !== false;
+    } else if (config.openGen !== undefined) {
+      this.enabled = config.openGen !== false;
+    } else {
+      this.enabled = true;
+    }
+
+    // Local storage config
+    this.saveLocal = config.saveLocal === true;
+    this.localPath = config.localPath || "./captured-apis.json";
+
+    // Sensitive keys
+    this.sensitiveKeys = [
+      "password",
+      "token",
+      "secret",
+      "creditcard",
+      "pin",
+      "auth",
+      "authorization",
+      "cookie",
+      ...(config.sensitiveKeys || []),
+    ];
+
+    // v1.x: Batch sender — กันยิง HTTP ทุก request
+    this._queue = [];
+    this._batchSize = config.batchSize || 10;
+    this._batchInterval = config.batchInterval || 3000; // ms
+    this._flushTimer = null;
+
+    if (this.serverUrl) {
+      this._startBatchFlush();
+    }
+
+    if (!this.serverUrl && !this.debug && !this.saveLocal) {
+      this.enabled = false;
+    }
+  }
+
+  // ---------------------------------------------------------
+  // v1.x FIX: Deep clone ด้วย structuredClone (ไม่ mutate ข้อมูลหลัก)
+  // ---------------------------------------------------------
+  maskSensitiveData(data) {
+    if (!data || typeof data !== "object") return data;
+
+    // structuredClone รองรับ Node 17+ / ถ้า env เก่าใช้ JSON fallback
+    let cloned;
+    try {
+      cloned = structuredClone(data);
+    } catch {
+      cloned = JSON.parse(JSON.stringify(data));
+    }
+
+    return this._maskDeep(cloned);
+  }
+
+  _maskDeep(obj) {
+    if (!obj || typeof obj !== "object") return obj;
+
+    for (const key of Object.keys(obj)) {
+      const lowerKey = key.toLowerCase();
+      const isSensitive = this.sensitiveKeys.some((s) =>
+        lowerKey.includes(s.toLowerCase()),
+      );
+
+      if (isSensitive) {
+        obj[key] = "[REDACTED]";
+      } else if (typeof obj[key] === "object" && obj[key] !== null) {
+        obj[key] = this._maskDeep(obj[key]);
+      }
+    }
+
+    return obj;
+  }
+
+  // ---------------------------------------------------------
+  // v1.x NEW: Intercept res.json() เพื่อ capture response body
+  // ---------------------------------------------------------
+  _patchResponse(res) {
+    const originalJson = res.json.bind(res);
+    let capturedResponseBody = null;
+
+    res.json = function (body) {
+      capturedResponseBody = body;
+      return originalJson(body);
+    };
+
+    return {
+      getBody: () => capturedResponseBody,
+    };
+  }
+
+  // ---------------------------------------------------------
+  // v1.x NEW: Async local save (ไม่ block event loop)
+  // ---------------------------------------------------------
+  async _saveLocalAsync(payloadObj) {
+    try {
+      const fullPath = path.resolve(this.localPath);
+      const dir = path.dirname(fullPath);
+
+      await fsPromises.mkdir(dir, { recursive: true });
+
+      let existingData = [];
+      try {
+        const fileContent = await fsPromises.readFile(fullPath, "utf-8");
+        const parsed = JSON.parse(fileContent);
+        existingData = Array.isArray(parsed) ? parsed : [];
+      } catch {
+        existingData = [];
+      }
+
+      existingData.push(payloadObj);
+      await fsPromises.writeFile(
+        fullPath,
+        JSON.stringify(existingData, null, 2),
+        "utf-8",
+      );
+
+      if (this.debug) {
+        console.log(`[ApiCapture] Saved to: ${fullPath}`);
+      }
+    } catch (err) {
+      console.error("[ApiCapture] Failed to save local JSON:", err.message);
+    }
+  }
+
+  // ---------------------------------------------------------
+  // v1.x NEW: Batch flush — ส่ง HTTP เป็น batch ลด overhead
+  // ---------------------------------------------------------
+  _startBatchFlush() {
+    this._flushTimer = setInterval(() => {
+      this._flush();
+    }, this._batchInterval);
+
+    // ป้องกัน timer ค้างตอน process ปิด
+    if (this._flushTimer.unref) this._flushTimer.unref();
+  }
+
+  _flush() {
+    if (this._queue.length === 0) return;
+
+    const batch = this._queue.splice(0, this._batchSize);
+    this._sendBatch(batch);
+  }
+
+  _sendBatch(batch) {
+    const payload = JSON.stringify({ events: batch });
+
+    try {
+      const url = new URL(this.serverUrl);
+      const client = url.protocol === "https:" ? https : http;
+
+      const options = {
+        hostname: url.hostname,
+        port: url.port || (url.protocol === "https:" ? 443 : 80),
+        path: url.pathname,
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Content-Length": Buffer.byteLength(payload),
+          "x-api-key": this.apiKey,
+        },
+      };
+
+      const req = client.request(options, (res) => {
+        if (this.debug) {
+          let responseData = "";
+          res.on("data", (c) => (responseData += c));
+          res.on("end", () => {
+            if (res.statusCode >= 400) {
+              console.error(
+                `[ApiCapture] Server error (${res.statusCode}):`,
+                responseData,
+              );
+            } else {
+              console.log(
+                `[ApiCapture] Sent ${batch.length} event(s) (${res.statusCode})`,
+              );
+            }
+          });
+        } else {
+          res.on("data", () => {});
+        }
+      });
+
+      req.on("error", (err) => {
+        if (this.debug) {
+          console.error(
+            "[ApiCapture] Cannot reach monitor server:",
+            err.message,
+          );
+        }
+        // v1.x: put failed events back in queue (simple retry)
+        this._queue.unshift(...batch);
+      });
+
+      req.write(payload);
+      req.end();
+    } catch (err) {
+      if (this.debug) {
+        console.error("[ApiCapture] Invalid monitor URL:", err.message);
+      }
+    }
+  }
+
+  // ---------------------------------------------------------
+  // capture() — core method
+  // ---------------------------------------------------------
+  capture(params) {
+    if (!this.enabled) return;
+
+    const {
+      routeName,
+      menus,
+      route,
+      method,
+      desc,
+      body,
+      query,
+      responseBody, // v1.x NEW
+      statusCode, // v1.x NEW
+      durationMs, // v1.x NEW
+    } = params;
+
+    const safeBody = this.maskSensitiveData(body);
+    const safeQuery = this.maskSensitiveData(query);
+    const safeResponse = this.maskSensitiveData(responseBody);
+
+    const payloadObj = {
+      appName: this.appName,
+      routeName: routeName || "unknown",
+      menus: Array.isArray(menus) ? menus : [],
+      route: route || "/",
+      method: (method || "GET").toUpperCase(),
+      desc: desc || "",
+      body: safeBody || null,
+      query: safeQuery || null,
+      response: safeResponse || null, // v1.x NEW
+      statusCode: statusCode || null, // v1.x NEW
+      durationMs: durationMs || null, // v1.x NEW
+      capturedAt: new Date().toISOString(),
+    };
+
+    // Debug mode
+    if (this.debug) {
+      const status = statusCode ? ` [${statusCode}]` : "";
+      const dur = durationMs ? ` ${durationMs}ms` : "";
+      console.log(`\n--- [ApiCapture]${status}${dur} ---`);
+      console.log(`[${payloadObj.method}] ${payloadObj.route}`);
+      if (payloadObj.desc) console.log(`Desc: ${payloadObj.desc}`);
+      if (payloadObj.body)
+        console.log("Body:", JSON.stringify(payloadObj.body, null, 2));
+      if (payloadObj.query)
+        console.log("Query:", JSON.stringify(payloadObj.query, null, 2));
+      if (payloadObj.response)
+        console.log("Response:", JSON.stringify(payloadObj.response, null, 2));
+      console.log("---------------------------\n");
+    }
+
+    // Async local save
+    if (this.saveLocal) {
+      this._saveLocalAsync(payloadObj);
+    }
+
+    // Push to batch queue
+    if (this.serverUrl) {
+      this._queue.push(payloadObj);
+
+      // Flush immediately if batch is full
+      if (this._queue.length >= this._batchSize) {
+        this._flush();
+      }
+    }
+  }
+
+  // ---------------------------------------------------------
+  // createMiddlewareFactory() — v1.x: now captures response + timing
+  // ---------------------------------------------------------
+  createMiddlewareFactory(routeName, routeEnabled = true) {
+    return {
+      capture: (desc = "", menus = []) => {
+        if (!routeEnabled || !this.enabled) {
+          return (req, res, next) => next();
+        }
+
+        const menuArray = Array.isArray(menus) ? menus : menus ? [menus] : [];
+
+        return (req, res, next) => {
+          const startTime = Date.now();
+
+          // v1.x: Patch res.json to intercept response body
+          const { getBody } = this._patchResponse(res);
+
+          res.on("finish", () => {
+            this.capture({
+              routeName,
+              menus: menuArray,
+              route: req.originalUrl || req.path,
+              method: req.method,
+              desc,
+              body: req.body,
+              query: req.query,
+              responseBody: getBody(), // v1.x NEW
+              statusCode: res.statusCode, // v1.x NEW
+              durationMs: Date.now() - startTime, // v1.x NEW
+            });
+          });
+
+          next();
+        };
+      },
+    };
+  }
+
+  // ---------------------------------------------------------
+  // flush() — manual flush ก่อน process ปิด
+  // ---------------------------------------------------------
+  async shutdown() {
+    if (this._flushTimer) clearInterval(this._flushTimer);
+    if (this._queue.length > 0) {
+      this._flush();
+      // รอนิดนึงให้ HTTP request ไปก่อน
+      await new Promise((resolve) => setTimeout(resolve, 500));
+    }
+  }
+}
+
+// ---------------------------------------------------------
+// Singleton
+// ---------------------------------------------------------
+let clientInstance = null;
+
+const initApiCapture = (config = {}) => {
+  if (!clientInstance) {
+    clientInstance = new ApiCaptureClient(config);
+  } else {
+    if (config.monitorUrl) clientInstance.serverUrl = config.monitorUrl;
+    if (config.monitorApiKey) clientInstance.apiKey = config.monitorApiKey;
+    if (config.appName) clientInstance.appName = config.appName;
+    if (config.enabled !== undefined)
+      clientInstance.enabled = config.enabled !== false;
+    else if (config.openGen !== undefined)
+      clientInstance.enabled = config.openGen !== false;
+    if (config.debug !== undefined)
+      clientInstance.debug = config.debug === true;
+    if (config.saveLocal !== undefined)
+      clientInstance.saveLocal = config.saveLocal === true;
+    if (config.localPath) clientInstance.localPath = config.localPath;
+    if (config.sensitiveKeys) {
+      clientInstance.sensitiveKeys = [
+        "password",
+        "token",
+        "secret",
+        "creditcard",
+        "pin",
+        "auth",
+        "authorization",
+        "cookie",
+        ...config.sensitiveKeys,
+      ];
+    }
+  }
+  return clientInstance;
+};
+
+const getClient = () => {
+  if (!clientInstance) {
+    console.warn(
+      "[ApiCapture] Warning: getClient() called before initApiCapture(). Using defaults.",
+    );
+    return initApiCapture();
+  }
+  return clientInstance;
+};
+
+module.exports = {
+  ApiCaptureClient,
+  initApiCapture,
+  getClient,
+};

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "apitrap",
+  "version": "1.1.0",
+  "description": "Express middleware that captures API traffic and sends it to your monitor dashboard — turn real requests into living API documentation.",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "README.md"
+  ],
+  "keywords": [
+    "express",
+    "api",
+    "capture",
+    "monitor",
+    "middleware",
+    "documentation",
+    "traffic",
+    "collection"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/POND9912/apitrap"
+  },
+  "license": "ISC",
+  "engines": {
+    "node": ">=16.0.0"
+  }
+}