@laphilosophia/api-tape 1.6.0 → 1.6.2

package/README.md

@@ -1,23 +1,23 @@
-# API Tape
+# 🖭 API Tape
 
-**Record and Replay HTTP API responses for offline development.**
+**High-integrity HTTP proxy for deterministic API record & replay.**
 
 API Tape is a zero-config CLI tool that acts as a transparent HTTP proxy. It records API responses to local JSON files ("tapes") and replays them instantly—perfect for offline development, flaky API testing, and reproducible demos.
 
+> [!NOTE]
+> **v1.6.2 Highlights**: Introduced a structural **Graceful Shutdown** mechanism for all platforms (including Windows), a new **Comprehensive Examples** suite, and improved test reliability in CI environments.
+
 ## Features
 
 - **Record Mode** — Proxies requests to your target API and saves responses
 - **Replay Mode** — Serves cached responses instantly from disk
 - **Hybrid Mode** — Replays cached tapes, falls back to upstream on cache miss
-- **Tape Management Commands** — List, inspect, clear, and prune tapes from CLI
-- **Header Redaction** — Mask sensitive response headers before writing tapes
-- **JSON Body Redaction** — Redact selected JSON paths before persisting response bodies
-- **Runtime Metrics** — Periodic and shutdown stats for replay hit/miss, upstream calls, and latency
-- **Zero Config** — Works out of the box with sensible defaults
-- **Binary Safe** — Handles images, compressed responses, and any content type
+- **Forensic CLI** — List, inspect, clear, and prune tapes with `tape`
+- **Security Redaction** — Mask sensitive response headers and JSON body paths
+- **Non-Deterministic Matching** — Handle shifting query params and unstable JSON bodies
+- **Runtime Metrics** — Real-time and shutdown stats for hit rates and latency
+- **Binary Safe** — Handles images, compressed payloads, 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`, `normalized`, and `body-aware` matching for better replay hit rates
 
 ---
 
@@ -92,8 +92,8 @@ Both legacy mode (`tape --target ...`) and explicit serve command (`tape serve -
 | `-p, --port <number>`         | Local server port                                              | `8080`    |
 | `-d, --dir <path>`            | Directory to save tapes                                        | `./tapes` |
 | `--record-on-miss <boolean>`  | In hybrid mode, save upstream response when tape is missing    | `true`    |
-| `--redact-header <headers>`   | Comma-separated response header names to redact in saved tapes | —         |
-| `--redact-json-path <paths>`  | Comma-separated JSON paths to redact in JSON response bodies   | —         |
+| `--redact-header <headers>`   | Comma-separated **response** header names to redact            | —         |
+| `--redact-json-path <paths>`  | Comma-separated JSON paths to redact in 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`, `normalized`, or `body-aware` | `exact`   |
@@ -110,7 +110,7 @@ For machine-readable output:
 tape serve --target "https://jsonplaceholder.typicode.com" --stats-interval 10 --stats-json
 ```
 
-On shutdown, API Tape always prints a final summary (`FINAL_STATS`).
+On shutdown, API Tape flushes one immediate `STATS` snapshot (if interval is enabled) and always prints a final summary (`FINAL_STATS`).
 
 ### Redaction options
 
@@ -122,19 +122,34 @@ tape serve --target "https://api.example.com" --mode record \
 
 `--redact-json-path` applies only when response `content-type` is JSON.
 
-### Match strategy
+### Match Strategies
+
+Use these strategies to handle non-deterministic API behaviors and improve replay hit rates:
 
-- `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.
+- **`exact`** (default): Hashes the literal `METHOD|URL`. Use for simple, static APIs.
+- **`normalized`**: Canonicalizes query parameters by sorting them alphabetically.
+  - Transforms: `/search?page=1&q=test` → `/search?q=test&page=1`
+  - _Benefit_: Drastically improves hit rates for clients that send query params in varying orders.
+- **`body-aware`**: Combines the normalized URL with a canonicalized request body signature.
+  - Handles: Differences in JSON key order or spacing in POST/PUT requests.
+  - _Benefit_: Essential for GraphQL or complex REST APIs where the same URL is used for different operations based on the body payload.
 
 ### Tape management commands
 
+Manage your forensic substrate with built-in tape utilities:
+
 ```bash
-tape tape list --dir ./tapes
-tape tape inspect <hash> --dir ./tapes
-tape tape clear --yes --dir ./tapes
-tape tape prune --older-than 30 --dir ./tapes
+# List all recorded tapes with their method, route, and timestamp
+tape list --dir ./tapes
+
+# Inspect a specific tape's metadata, status, and headers
+tape inspect <hash> --dir ./tapes
+
+# Clear all tapes from a directory (requires --yes confirmation)
+tape clear --yes --dir ./tapes
+
+# Prune tapes older than N days to keep your local environment clean
+tape prune --older-than 30 --dir ./tapes
 ```
 
 ---
@@ -177,6 +192,22 @@ A GitHub Actions workflow runs `npm test` on both Linux and Windows for pushes a
 
 ---
 
+---
+
+## Contributing
+
+We welcome contributions! Please see our [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines on how to get started. All participants are expected to follow our [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md).
+
+## Security
+
+To report a security vulnerability, please use the process described in [SECURITY.md](./SECURITY.md).
+
+## Support
+
+If you need help using API Tape, check our [SUPPORT.md](./SUPPORT.md) or join the conversation in [GitHub Discussions](https://github.com/laphilosophia/api-tape/discussions).
+
+---
+
 ## Use Cases
 
 - **Offline Development** — Work without internet or VPN

package/dist/index.js

@@ -33,6 +33,68 @@ var import_http_proxy = __toESM(require("http-proxy"));
 var import_path = __toESM(require("path"));
 var import_stream = require("stream");
 
+// package.json
+var package_default = {
+  name: "@laphilosophia/api-tape",
+  version: "1.6.2",
+  description: "High-integrity HTTP proxy for deterministic API record & replay. Features non-deterministic matching (canonical JSON/Query), sensitive data redaction, and deep forensics via CLI management.",
+  main: "dist/index.js",
+  bin: {
+    tape: "./dist/index.js",
+    "api-tape": "./dist/index.js"
+  },
+  files: [
+    "dist"
+  ],
+  publishConfig: {
+    access: "public"
+  },
+  scripts: {
+    build: "tsup src/index.ts --format cjs --clean",
+    prepublishOnly: "npm run build",
+    test: "npm run build && node --test"
+  },
+  keywords: [
+    "api",
+    "mock",
+    "record",
+    "replay",
+    "proxy",
+    "offline",
+    "testing",
+    "http",
+    "vcr",
+    "deterministic",
+    "redaction",
+    "forensics",
+    "canonical-json"
+  ],
+  author: "Erdem Arslan <me@erdem.work>",
+  license: "MIT",
+  repository: {
+    type: "git",
+    url: "git+https://github.com/laphilosophia/api-tape.git"
+  },
+  homepage: "https://github.com/laphilosophia/api-tape#readme",
+  bugs: {
+    url: "https://github.com/laphilosophia/api-tape/issues"
+  },
+  type: "commonjs",
+  dependencies: {
+    chalk: "^5.6.2",
+    commander: "^14.0.2",
+    "fs-extra": "^11.3.3",
+    "http-proxy": "^1.18.1"
+  },
+  devDependencies: {
+    "@types/fs-extra": "^11.0.4",
+    "@types/http-proxy": "^1.17.17",
+    "@types/node": "^25.0.8",
+    tsup: "^8.5.1",
+    typescript: "^5.9.3"
+  }
+};
+
 // src/constants.ts
 var CURRENT_SCHEMA_VERSION = 1;
 
@@ -423,16 +485,24 @@ var runServe = (opts) => {
     });
   });
   let metricsTimer;
+  let isShuttingDown = false;
   if (statsIntervalSec > 0) {
     metricsTimer = setInterval(() => {
       printMetrics(metrics, statsJson);
     }, statsIntervalSec * 1e3);
   }
-  const shutdown = (signal) => {
+  const shutdown = (_signal) => {
+    if (isShuttingDown) {
+      return;
+    }
+    isShuttingDown = true;
     if (metricsTimer) {
       clearInterval(metricsTimer);
       metricsTimer = void 0;
     }
+    if (statsIntervalSec > 0) {
+      printMetrics(metrics, statsJson, "STATS");
+    }
     printMetrics(metrics, statsJson, "FINAL_STATS");
     server.close(() => {
       process.exit(0);
@@ -444,6 +514,10 @@ var runServe = (opts) => {
   process.once("SIGINT", () => shutdown("SIGINT"));
   process.once("SIGTERM", () => shutdown("SIGTERM"));
   process.once("SIGBREAK", () => shutdown("SIGBREAK"));
+  if (!process.stdin.isTTY) {
+    process.stdin.resume();
+    process.stdin.once("close", () => shutdown("STDIN_EOF"));
+  }
   console.log(import_chalk2.default.bold(`
 \u{1F4FC} API Tape Running`));
   console.log(
@@ -467,7 +541,9 @@ var runServe = (opts) => {
   if (statsJson) {
     console.log(`   ${import_chalk2.default.dim("Stats Format:")} json`);
   }
-  console.log(`   ${import_chalk2.default.dim("Match Strategy:")} ${matchStrategy}`);
+  if (matchStrategy) {
+    console.log(`   ${import_chalk2.default.dim("Match Strategy:")} ${matchStrategy}`);
+  }
   console.log("");
   server.listen(port);
 };
@@ -558,14 +634,14 @@ 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.6.0").action((options) => {
+    const legacy = addServeOptions(new import_commander.Command()).name("api-tape").description("Record and Replay HTTP API responses for offline development.").version(package_default.version).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.6.0");
+  program.name("api-tape").description("Record and Replay HTTP API responses for offline development.").version(package_default.version);
   addServeOptions(program.command("serve").description("Run API Tape proxy server")).action(
     (options) => {
       runServe(options);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@laphilosophia/api-tape",
-  "version": "1.6.0",
-  "description": "Record and Replay HTTP API responses for offline development",
+  "version": "1.6.2",
+  "description": "High-integrity HTTP proxy for deterministic API record & replay. Features non-deterministic matching (canonical JSON/Query), sensitive data redaction, and deep forensics via CLI management.",
   "main": "dist/index.js",
   "bin": {
     "tape": "./dist/index.js",
@@ -27,9 +27,13 @@
     "offline",
     "testing",
     "http",
-    "vcr"
+    "vcr",
+    "deterministic",
+    "redaction",
+    "forensics",
+    "canonical-json"
   ],
-  "author": "Erdem Arslan",
+  "author": "Erdem Arslan <me@erdem.work>",
   "license": "MIT",
   "repository": {
     "type": "git",