api-visualizer/README.md

A tunnel-based API inspector for visualizing requests and responses in real time.

# api-visualizer

[![NPM Version](https://img.shields.io/npm/v/api-visualizer?color=blue&label=npm&style=flat)](https://www.npmjs.com/package/api-visualizer)
[![License](https://img.shields.io/npm/l/api-visualizer?color=green&style=flat)](LICENSE)
[![Node Version](https://img.shields.io/node/v/api-visualizer?style=flat)](https://nodejs.org)
[![JavaScript](https://img.shields.io/badge/JavaScript-supported-blue?style=flat)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/)
[![TypeScript](https://img.shields.io/badge/TypeScript-supported-blue?style=flat)](https://www.typescriptlang.org/)
[![Dashboard](https://img.shields.io/badge/Dashboard-Open%20Live-green?style=flat)](https://api-visualizer-nine.vercel.app)
[![Made With ❤️](https://img.shields.io/badge/Made%20with-%E2%9D%A4-red?style=flat)](https://github.com/krishna-singha)

**api-visualizer** is a lightweight middleware that captures live API traffic from your local JavaScript or TypeScript server and streams it to a real-time WebSocket-based dashboard for inspection, debugging, and monitoring.

🔗 **Live Dashboard**: [API Visualizer App](https://api-visualizer-nine.vercel.app)

---

## 📚 Table of Contents

- [Installation](#installation)
- [Usage (Express Example)](#usage-express-example)
- [Real-Time Dashboard](#real-time-dashboard)
- [Captured Data Format](#captured-data-format)
- [Use Cases](#use-cases)
- [License](#license)
- [Author](#author)

---

## Installation

Install the middleware using npm:

```bash
npm install api-visualizer
```

---

## Usage (Express Example)

1. **Register** at the dashboard:  
   👉 [api-visualizer.vercel.app](https://api-visualizer-nine.vercel.app)

2. **Generate an API Key** after logging in.

3. **Add the middleware to your Express server:**

```ts
import express from "express";

//-------- IMPORT API COMPONENTS --------
import { connectToTunnel, tunnelMiddleware } from "api-visualizer";

// ------- CONNECT TO THE TUNNEL WITH YOUR API KEY ---------
(async () => {
  try {
    connectToTunnel("YOUR_API_KEY"); // 🔑 REPLACE WITH YOU API KEY -------
  } catch (err) {
    console.error("[Tunnel] Failed to connect:", err);
  }
})();

const app = express();

// -------- ATTACH THE MIDDLEWARE -------
app.use(tunnelMiddleware);

app.use(express.json());
app.use(express.urlencoded({ extended: true }));

app.post("/api", (req, res) => {
  res.json({ message: "Received", body: req.body });
});

app.listen(3000, () => {
  console.log("Server running at http://localhost:3000");
});
```

---

## Real-Time Dashboard

Visualize API traffic from your local server in real time:  
👉 [API Visualizer App](https://api-visualizer-nine.vercel.app)

---

## Captured Data Format

Sample structure of the captured API request and response data:

```json
{
  "method": "PATCH",
  "fullUrl": "http://localhost:3000/?key=value%2312",
  "route": "/",
  "queryParams": { "key": "value#12" },
  "duration": 7,
  "timestamp": 1751218377927,
  "size": { "request": 53, "response": 100, "total": 153 },
  "status": 200,
  "request": {
    "headers": {
      "authorization": "Basic a3JpOnNobmE=",
      "content-type": "application/javascript"
    },
    "body": "const a = 4, b = 3;\nconst c = a + b;\nconsole.log(c); ",
    "contentType": "javascript"
  },
  "response": {
    "statusCode": 200,
    "body": {
      "message": "Test PATCH successful",
      "data": "const a = 4, b = 3;\nconst c = a + b;\nconsole.log(c); "
    },
    "contentType": "json"
  },
  "authorization": {
    "hasAuthHeader": true,
    "authType": "basic",
    "parsed": { "username": "kri", "password": "shna" },
  },
  "meta": {
    "ip": "127.0.0.1",
    "protocol": "http",
    "httpVersion": "1.1",
    "deviceType": "desktop"
  }
}
```

---

## Use Cases

- Inspect and debug API requests/responses live
- Monitor local backend traffic during development

---

## License

[MIT](LICENSE) © 2025 Krishna Singha

---

## Author

[Krishna Singha](https://github.com/krishna-singha) [(krishnasingha.dev@gmail.com)](mailto:krishnasingha.dev@gmail.com)