@laphilosophia/api-tape 1.5.0 → 1.6.0

package/README.md

@@ -17,20 +17,20 @@ API Tape is a zero-config CLI tool that acts as a transparent HTTP proxy. It rec
 - **Binary Safe** — Handles images, compressed responses, and any content type
 - **Replay Header** — Responses include `X-Api-Tape: Replayed` for easy debugging
 - **Versioned Tape Schema** — Each tape includes `schemaVersion` for compatibility checks
-- **Match Strategies** — `exact` and `normalized` matching for better replay hit rates
+- **Match Strategies** — `exact`, `normalized`, and `body-aware` matching for better replay hit rates
 
 ---
 
 ## Installation
 
 ```bash
-npm install -g api-tape
+npm install -g @laphilosophia/api-tape
 ```
 
 Or use it directly with npx:
 
 ```bash
-npx api-tape --target "https://api.example.com" --mode record
+npx @laphilosophia/api-tape --target "https://api.example.com" --mode record
 ```
 
 ---
@@ -96,7 +96,7 @@ Both legacy mode (`tape --target ...`) and explicit serve command (`tape serve -
 | `--redact-json-path <paths>`  | Comma-separated JSON paths to redact in JSON response bodies   | —         |
 | `--stats-interval <seconds>`  | Emit runtime metrics every N seconds (`0` disables)            | `0`       |
 | `--stats-json`                | Emit metrics as JSON lines                                     | `false`   |
-| `--match-strategy <strategy>` | Tape matching strategy: `exact` or `normalized`                | `exact`   |
+| `--match-strategy <strategy>` | Tape matching strategy: `exact`, `normalized`, or `body-aware` | `exact`   |
 
 ### Runtime stats
 
@@ -126,6 +126,7 @@ tape serve --target "https://api.example.com" --mode record \
 
 - `exact` (default): hashes `METHOD|URL` as-is.
 - `normalized`: sorts query params before hashing, so `/search?a=1&b=2` and `/search?b=2&a=1` map to the same tape.
+- `body-aware`: uses normalized URL plus request body signature (JSON canonicalized when possible), useful for POST/PUT APIs sharing paths.
 
 ### Tape management commands
 

package/dist/index.js

@@ -31,6 +31,7 @@ var import_fs_extra = __toESM(require("fs-extra"));
 var import_http = __toESM(require("http"));
 var import_http_proxy = __toESM(require("http-proxy"));
 var import_path = __toESM(require("path"));
+var import_stream = require("stream");
 
 // src/constants.ts
 var CURRENT_SCHEMA_VERSION = 1;
@@ -63,8 +64,56 @@ var parseNonNegativeInt = (value, label) => {
   return parsed;
 };
 var parseCsv = (value) => value.split(",").map((item) => item.trim()).filter(Boolean);
+var stableStringify = (value) => {
+  if (value === null || typeof value !== "object") {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => stableStringify(item)).join(",")}]`;
+  }
+  const obj = value;
+  const keys = Object.keys(obj).sort();
+  return `{${keys.map((key) => `${JSON.stringify(key)}:${stableStringify(obj[key])}`).join(",")}}`;
+};
 
 // src/index.ts
+var getRequestBodySignature = (req, bodyBuffer) => {
+  if (bodyBuffer.length === 0) {
+    return "";
+  }
+  const contentType = readHeaderValue(req.headers["content-type"]).toLowerCase();
+  if (contentType.includes("application/json")) {
+    try {
+      const parsed = JSON.parse(bodyBuffer.toString("utf8"));
+      return stableStringify(parsed);
+    } catch {
+      return bodyBuffer.toString("base64");
+    }
+  }
+  return bodyBuffer.toString("base64");
+};
+var collectRequestBody = (req) => new Promise((resolve, reject) => {
+  if (!req.readable || req.method === "GET" || req.method === "HEAD" || req.method === "OPTIONS") {
+    resolve(Buffer.alloc(0));
+    return;
+  }
+  const chunks = [];
+  req.on("data", (chunk) => {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  });
+  req.on("end", () => {
+    resolve(Buffer.concat(chunks));
+  });
+  req.on("error", reject);
+});
+var createProxyBuffer = (requestBody) => {
+  if (requestBody.length === 0) {
+    return void 0;
+  }
+  const stream = new import_stream.PassThrough();
+  stream.end(requestBody);
+  return stream;
+};
 var normalizeUrl = (rawUrl) => {
   if (!rawUrl) {
     return "/";
@@ -87,15 +136,18 @@ var normalizeUrl = (rawUrl) => {
   const normalizedQuery = normalized.toString();
   return normalizedQuery ? `${pathname || "/"}?${normalizedQuery}` : pathname || "/";
 };
-var buildRequestSignature = (req, matchStrategy) => {
+var buildRequestSignature = (req, matchStrategy, requestBody) => {
   const method = req.method || "GET";
   if (matchStrategy === "normalized") {
     return `${method}|${normalizeUrl(req.url)}`;
   }
+  if (matchStrategy === "body-aware") {
+    return `${method}|${normalizeUrl(req.url)}|${getRequestBodySignature(req, requestBody)}`;
+  }
   return `${method}|${req.url}`;
 };
-var getTapeKey = (req, matchStrategy) => {
-  const key = buildRequestSignature(req, matchStrategy);
+var getTapeKey = (req, matchStrategy, requestBody) => {
+  const key = buildRequestSignature(req, matchStrategy, requestBody);
   return import_crypto.default.createHash("md5").update(key).digest("hex");
 };
 var readTape = (tapePath) => import_fs_extra.default.readJsonSync(tapePath);
@@ -229,7 +281,7 @@ var runServe = (opts) => {
   if (!validModes.includes(mode)) {
     throw new Error(`Invalid mode: ${mode}. Expected one of: ${validModes.join(", ")}`);
   }
-  const validMatchStrategies = ["exact", "normalized"];
+  const validMatchStrategies = ["exact", "normalized", "body-aware"];
   if (!validMatchStrategies.includes(matchStrategy)) {
     throw new Error(
       `Invalid match strategy: ${matchStrategy}. Expected one of: ${validMatchStrategies.join(", ")}`
@@ -242,6 +294,7 @@ var runServe = (opts) => {
     selfHandleResponse: true
   });
   const recordByRequest = /* @__PURE__ */ new WeakMap();
+  const requestBodyByRequest = /* @__PURE__ */ new WeakMap();
   const requestStartByResponse = /* @__PURE__ */ new WeakMap();
   const metrics = {
     totalRequests: 0,
@@ -279,18 +332,18 @@ var runServe = (opts) => {
       return true;
     }
   };
-  const proxyRequest = (req, res, shouldRecord, logPrefix) => {
+  const proxyRequest = (req, res, shouldRecord, logPrefix, requestBody) => {
     recordByRequest.set(req, shouldRecord);
     metrics.upstreamRequests += 1;
     console.log(`${timestamp()} ${logPrefix} ${req.method} ${req.url}`);
-    proxy.web(req, res, {}, (error) => {
+    proxy.web(req, res, { buffer: createProxyBuffer(requestBody) }, (error) => {
       metrics.upstreamErrors += 1;
       console.error(import_chalk2.default.red("Proxy Error:"), error.message);
       res.statusCode = 502;
       res.end("Proxy Error");
     });
   };
-  const server = import_http.default.createServer((req, res) => {
+  const server = import_http.default.createServer(async (req, res) => {
     metrics.totalRequests += 1;
     requestStartByResponse.set(res, Date.now());
     res.on("finish", () => {
@@ -300,7 +353,18 @@ var runServe = (opts) => {
         metrics.completedResponses += 1;
       }
     });
-    const tapeKey = getTapeKey(req, matchStrategy);
+    let requestBody = Buffer.alloc(0);
+    if (matchStrategy === "body-aware") {
+      try {
+        requestBody = await collectRequestBody(req);
+      } catch {
+        res.statusCode = 400;
+        res.end("Unable to read request body");
+        return;
+      }
+    }
+    requestBodyByRequest.set(req, requestBody);
+    const tapeKey = getTapeKey(req, matchStrategy, requestBody);
     const tapePath = import_path.default.join(tapesDir, `${tapeKey}.json`);
     if (mode === "replay") {
       const hit2 = replayTape(req, res, tapePath);
@@ -313,7 +377,7 @@ var runServe = (opts) => {
       return;
     }
     if (mode === "record") {
-      proxyRequest(req, res, true, import_chalk2.default.blue("\u25CF RECORD"));
+      proxyRequest(req, res, true, import_chalk2.default.blue("\u25CF RECORD"), requestBody);
       return;
     }
     const hit = replayTape(req, res, tapePath);
@@ -326,7 +390,8 @@ var runServe = (opts) => {
       req,
       res,
       recordOnMiss,
-      recordOnMiss ? import_chalk2.default.magenta("\u21E2 FALLBACK_RECORD") : import_chalk2.default.magenta("\u21E2 FALLBACK_PROXY")
+      recordOnMiss ? import_chalk2.default.magenta("\u21E2 FALLBACK_RECORD") : import_chalk2.default.magenta("\u21E2 FALLBACK_PROXY"),
+      requestBody
     );
   });
   proxy.on("proxyRes", (proxyRes, req, res) => {
@@ -334,7 +399,7 @@ var runServe = (opts) => {
     proxyRes.on("data", (chunk) => bodyChunks.push(chunk));
     proxyRes.on("end", () => {
       const bodyBuffer = Buffer.concat(bodyChunks);
-      const shouldRecord = recordByRequest.get(req) ?? true;
+      const shouldRecord = recordByRequest.get(req) ?? (mode === "record" || mode === "hybrid" && recordOnMiss);
       if (shouldRecord) {
         const tapeData = createTapeRecord(
           req,
@@ -344,7 +409,8 @@ var runServe = (opts) => {
           redactedJsonPaths,
           matchStrategy
         );
-        const tapeKey = getTapeKey(req, matchStrategy);
+        const requestBody = requestBodyByRequest.get(req) || Buffer.alloc(0);
+        const tapeKey = getTapeKey(req, matchStrategy, requestBody);
         const tapePath = import_path.default.join(tapesDir, `${tapeKey}.json`);
         import_fs_extra.default.writeJsonSync(tapePath, tapeData, { spaces: 2 });
         console.log(`${timestamp()} ${import_chalk2.default.cyan("\u{1F4BE} SAVED")} ${req.method} ${req.url}`);
@@ -377,6 +443,7 @@ var runServe = (opts) => {
   };
   process.once("SIGINT", () => shutdown("SIGINT"));
   process.once("SIGTERM", () => shutdown("SIGTERM"));
+  process.once("SIGBREAK", () => shutdown("SIGBREAK"));
   console.log(import_chalk2.default.bold(`
 \u{1F4FC} API Tape Running`));
   console.log(
@@ -482,19 +549,23 @@ var addServeOptions = (command) => command.requiredOption("-t, --target <url>",
   "--redact-json-path <paths>",
   "Comma-separated JSON paths to redact in JSON response bodies",
   ""
-).option("--stats-interval <seconds>", "Emit runtime stats every N seconds (0 disables)", "0").option("--stats-json", "Emit stats in JSON format", false).option("--match-strategy <strategy>", "Tape matching strategy: exact or normalized", "exact");
+).option("--stats-interval <seconds>", "Emit runtime stats every N seconds (0 disables)", "0").option("--stats-json", "Emit stats in JSON format", false).option(
+  "--match-strategy <strategy>",
+  "Tape matching strategy: exact, normalized, or body-aware",
+  "exact"
+);
 var run = () => {
   const argv = process.argv;
   const hasSubCommand = argv.length > 2 && ["serve", "tape"].includes(argv[2]);
   if (!hasSubCommand) {
-    const legacy = addServeOptions(new import_commander.Command()).name("api-tape").description("Record and Replay HTTP API responses for offline development.").version("1.5.0").action((options) => {
+    const legacy = addServeOptions(new import_commander.Command()).name("api-tape").description("Record and Replay HTTP API responses for offline development.").version("1.6.0").action((options) => {
       runServe(options);
     });
     legacy.parse(argv);
     return;
   }
   const program = new import_commander.Command();
-  program.name("api-tape").description("Record and Replay HTTP API responses for offline development.").version("1.5.0");
+  program.name("api-tape").description("Record and Replay HTTP API responses for offline development.").version("1.6.0");
   addServeOptions(program.command("serve").description("Run API Tape proxy server")).action(
     (options) => {
       runServe(options);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@laphilosophia/api-tape",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Record and Replay HTTP API responses for offline development",
   "main": "dist/index.js",
   "bin": {