@laphilosophia/api-tape 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Erdem Arslan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,94 @@
+# 📼 API Tape
+
+**Record and Replay HTTP API responses for offline development.**
+
+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.
+
+## ✨ Features
+
+- 🎬 **Record Mode** — Proxies requests to your target API and saves responses
+- 🔄 **Replay Mode** — Serves cached responses instantly from disk
+- 📦 **Zero Config** — Works out of the box with sensible defaults
+- 🔒 **Binary Safe** — Handles images, compressed responses, and any content type
+- 🏷️ **Replay Header** — Responses include `X-Api-Tape: Replayed` for easy debugging
+
+## 📦 Installation
+
+```bash
+npm install -g api-tape
+```
+
+Or use it directly with npx:
+
+```bash
+npx api-tape --target "https://api.example.com" --mode record
+```
+
+## 🚀 Quick Start
+
+### Step 1: Record API Responses
+
+```bash
+tape --target "https://jsonplaceholder.typicode.com" --mode record
+```
+
+In another terminal:
+
+```bash
+curl http://localhost:8080/todos/1
+```
+
+You'll see `● RECORD GET /todos/1` in the terminal and a new tape file in `./tapes/`.
+
+### Step 2: Replay Offline
+
+Stop the server and restart in replay mode:
+
+```bash
+tape --target "https://jsonplaceholder.typicode.com" --mode replay
+```
+
+```bash
+curl http://localhost:8080/todos/1
+```
+
+You'll see `↺ REPLAY GET /todos/1` — the response comes from disk, no network needed!
+
+## ⚙️ CLI Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-t, --target <url>` | Target API URL **(required)** | — |
+| `-m, --mode <mode>` | Operation mode: `record` or `replay` | `replay` |
+| `-p, --port <number>` | Local server port | `8080` |
+| `-d, --dir <path>` | Directory to save tapes | `./tapes` |
+
+## 📁 Tape Format
+
+Each tape is a JSON file named with an MD5 hash of `METHOD|URL`:
+
+```json
+{
+  "meta": {
+    "url": "/todos/1",
+    "method": "GET",
+    "timestamp": "2026-01-14T19:12:39.000Z"
+  },
+  "statusCode": 200,
+  "headers": { ... },
+  "body": "eyJ1c2VySWQiOjEsImlkIjoxLC..."
+}
+```
+
+The body is base64-encoded for binary safety.
+
+## 🎯 Use Cases
+
+- **Offline Development** — Work without internet or VPN
+- **Flaky API Testing** — Eliminate network inconsistencies in tests
+- **Demo Environments** — Reproducible API responses for presentations
+- **Rate Limit Bypass** — Develop against recorded responses
+
+## 📄 License
+
+MIT © [Erdem Arslan](https://github.com/laphilosophia)

package/dist/index.js

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// src/index.ts
+var import_chalk = __toESM(require("chalk"));
+var import_commander = require("commander");
+var import_crypto = __toESM(require("crypto"));
+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"));
+import_commander.program.name("api-tape").description("Record and Replay HTTP API responses for offline development.").requiredOption("-t, --target <url>", "Target API URL (e.g., https://api.github.com)").option("-p, --port <number>", "Local server port", "8080").option("-m, --mode <mode>", 'Operation mode: "record" or "replay"', "replay").option("-d, --dir <path>", "Directory to save tapes", "./tapes").version("1.0.0").parse();
+var opts = import_commander.program.opts();
+var TARGET_URL = opts.target;
+var PORT = parseInt(opts.port);
+var MODE = opts.mode;
+var TAPES_DIR = import_path.default.resolve(opts.dir);
+var proxy = import_http_proxy.default.createProxyServer({
+  target: TARGET_URL,
+  changeOrigin: true,
+  selfHandleResponse: true
+});
+import_fs_extra.default.ensureDirSync(TAPES_DIR);
+var getTapeKey = (req) => {
+  const key = `${req.method}|${req.url}`;
+  return import_crypto.default.createHash("md5").update(key).digest("hex");
+};
+var timestamp = () => import_chalk.default.gray(`[${(/* @__PURE__ */ new Date()).toLocaleTimeString()}]`);
+var server = import_http.default.createServer((req, res) => {
+  const tapeKey = getTapeKey(req);
+  const tapePath = import_path.default.join(TAPES_DIR, `${tapeKey}.json`);
+  if (MODE === "replay") {
+    if (import_fs_extra.default.existsSync(tapePath)) {
+      try {
+        const tape = import_fs_extra.default.readJsonSync(tapePath);
+        Object.keys(tape.headers).forEach((key) => {
+          res.setHeader(key, tape.headers[key]);
+        });
+        res.setHeader("X-Api-Tape", "Replayed");
+        res.writeHead(tape.statusCode);
+        res.end(Buffer.from(tape.body, "base64"));
+        console.log(`${timestamp()} ${import_chalk.default.green("\u21BA REPLAY")} ${req.method} ${req.url}`);
+      } catch (e) {
+        console.error(import_chalk.default.red("Corrupted Tape:"), tapePath);
+        res.statusCode = 500;
+        res.end("Corrupted Tape");
+      }
+    } else {
+      console.log(`${timestamp()} ${import_chalk.default.red("\u2718 MISSING")} ${req.method} ${req.url}`);
+      res.statusCode = 404;
+      res.end(`Tape not found for: ${req.method} ${req.url}`);
+    }
+    return;
+  }
+  if (MODE === "record") {
+    console.log(`${timestamp()} ${import_chalk.default.blue("\u25CF RECORD")} ${req.method} ${req.url}`);
+    proxy.web(req, res, {}, (e) => {
+      console.error(import_chalk.default.red("Proxy Error:"), e.message);
+      res.statusCode = 502;
+      res.end("Proxy Error");
+    });
+  }
+});
+proxy.on("proxyRes", (proxyRes, req, res) => {
+  const bodyChunks = [];
+  proxyRes.on("data", (chunk) => bodyChunks.push(chunk));
+  proxyRes.on("end", () => {
+    const bodyBuffer = Buffer.concat(bodyChunks);
+    const tapeData = {
+      meta: {
+        url: req.url,
+        method: req.method,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      },
+      statusCode: proxyRes.statusCode,
+      headers: proxyRes.headers,
+      body: bodyBuffer.toString("base64")
+    };
+    const tapeKey = getTapeKey(req);
+    const tapePath = import_path.default.join(TAPES_DIR, `${tapeKey}.json`);
+    import_fs_extra.default.writeJsonSync(tapePath, tapeData, { spaces: 2 });
+    Object.keys(proxyRes.headers).forEach((key) => {
+      res.setHeader(key, proxyRes.headers[key]);
+    });
+    res.writeHead(proxyRes.statusCode || 200);
+    res.end(bodyBuffer);
+  });
+});
+console.log(import_chalk.default.bold(`
+\u{1F4FC} API Tape Running`));
+console.log(`   ${import_chalk.default.dim("Mode:")}   ${MODE === "record" ? import_chalk.default.red("\u25CF RECORD") : import_chalk.default.green("\u21BA REPLAY")}`);
+console.log(`   ${import_chalk.default.dim("Target:")} ${TARGET_URL}`);
+console.log(`   ${import_chalk.default.dim("Port:")}   http://localhost:${PORT}`);
+console.log(`   ${import_chalk.default.dim("Dir:")}    ${TAPES_DIR}
+`);
+server.listen(PORT);

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@laphilosophia/api-tape",
+  "version": "1.0.0",
+  "description": "Record and Replay HTTP API responses for offline development",
+  "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"
+  },
+  "keywords": [
+    "api",
+    "mock",
+    "record",
+    "replay",
+    "proxy",
+    "offline",
+    "testing",
+    "http",
+    "vcr"
+  ],
+  "author": "Erdem Arslan",
+  "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"
+  }
+}