flow-debugger 1.0.0 → 1.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "flow-debugger",
-    "version": "1.0.0",
+    "version": "1.0.1",
     "description": "Production-safe flow-level debugging SDK. Traces requests, measures timing, classifies errors, detects root causes, and provides endpoint analytics with a live dashboard.",
     "main": "dist/cjs/index.js",
     "module": "dist/esm/index.js",

package/PORTFOLIO_README_SECTION.md

@@ -1,177 +0,0 @@
-# Flow Debugger - Portfolio README Section
-
-Copy this section and add it to your portfolio README at:
-https://github.com/sannuk79/PROJECTS-AND-NPM-PACKAGES-
-
----
-
-### 🔍 3. Flow Debugger
-**Production-safe request tracing with root cause detection and live analytics dashboard.**
-
-[![NPM Version](https://img.shields.io/npm/v/flow-debugger?color=purple)](https://www.npmjs.com/package/flow-debugger)
-[![GitHub](https://img.shields.io/badge/GitHub-debugerpackages-purple)](https://github.com/sannuk79/debugerpackages)
-[![Downloads](https://img.shields.io/npm/dm/flow-debugger)](https://www.npmjs.com/package/flow-debugger)
-
-![Flow Debugger Dashboard](https://via.placeholder.com/800x400/1a1a2e/7c3aed?text=Flow+Debugger+Dashboard)
-
-### 🔄 Architecture Overview
-```mermaid
-graph LR
-    A[Request] --> B[Generate TraceID]
-    B --> C[Step-by-Step Tracking]
-    C --> D[Auto-Classify: INFO/WARN/ERROR/CRITICAL]
-    D --> E[Root Cause Detection]
-    E --> F[Analytics Dashboard]
-    F --> G[Search & Filter]
-```
-
-### ✨ Key Features
-
-**Auto-Instrumentation (Zero Code Changes):**
-- ✅ MongoDB, MySQL, PostgreSQL, Redis
-- ✅ Fetch API, Axios
-- ✅ Express middleware
-
-**External API Tracing:**
-- 🔵 Stripe API auto-tagged
-- 🟢 Razorpay API auto-tagged
-- 🟡 SendGrid API auto-tagged
-- 🟣 Twilio API auto-tagged
-
-**Advanced Debugging:**
-- 🎯 **Root Cause Detection**: Timeout → Failure → Slow bottleneck algorithm
-- 📄 **Error Stack Preview**: Shows `errorFile:line` in dashboard (e.g., `auth.service.ts:42`)
-- 📦 **Payload Size Detection**: Warns on large payloads (>1MB) slowing requests
-- 🌍 **Environment Tagging**: Filter traces by dev/staging/production
-- 🔍 **Trace Search**: Search by traceId, endpoint, error message
-- 📊 **Live Dashboard**: Real-time analytics at `/__debugger/dashboard`
-
-**Production-Safe:**
-- ⚡ Never blocks requests
-- 🛡️ All code wrapped in try/catch
-- 🚀 <1ms overhead per request
-
-### 📈 Performance Metrics
-
-**Load Testing Results:**
-```
-✅ 56,000 requests in 10 seconds
-✅ 100 concurrent connections
-✅ 5,600 req/sec throughput
-✅ <1ms average overhead
-```
-
-**Test Coverage:**
-```
-✅ 30/30 tests passing
-✅ CJS, ESM, TypeScript builds
-✅ Production-tested
-```
-
-### 🚀 Quick Start
-
-```bash
-npm install flow-debugger
-```
-
-```javascript
-const express = require('express');
-const { flowDebugger, fetchTracer, axiosTracer } = require('flow-debugger');
-const axios = require('axios');
-
-const app = express();
-app.use(express.json());
-
-// Initialize with environment
-const debugger_ = flowDebugger({
-  environment: 'production',
-  slowThreshold: 300,
-  largePayloadThreshold: 1024 * 1024, // 1MB
-});
-
-app.use(debugger_.middleware);
-
-// Auto-trace external APIs
-fetchTracer({ getTracer: debugger_.getTracer });
-axiosTracer(axios, { getTracer: debugger_.getTracer });
-
-// Your routes...
-app.get('/api/users', async (req, res) => {
-  // All database calls, API calls automatically traced
-  const users = await User.find();
-  res.json(users);
-});
-
-app.listen(3000);
-// Dashboard: http://localhost:3000/__debugger/dashboard
-```
-
-### 🎯 Real Production Use Cases
-
-**1. Payment Gateway Failures**
-```
-🔍 Root Cause: Stripe API timed out after 2000ms
-   Service: stripe | Confidence: high
-   📄 payment.service.ts:89
-```
-
-**2. Large Payload Slowdown**
-```
-POST /api/upload  📦 5.2MB  WARN  1200ms
-Root Cause: Large payload (5.2MB) slowed JSON parsing
-```
-
-**3. Environment-Specific Bugs**
-```
-Search: "redis" | Environment: production
-Found 12 results — all showing ECONNREFUSED in production only
-```
-
-**4. Service Failure Breakdown**
-```
-Top Failures:
-  Stripe API    42%
-  Redis         33%
-  PostgreSQL    12%
-```
-
-### 📊 Dashboard Features
-
-- **Real-time Monitoring**: Live request traces with auto-refresh
-- **Service Health**: Track MongoDB, MySQL, PostgreSQL, Redis, external APIs
-- **Endpoint Analytics**: Avg/P95/Max latency, error rates, slow query detection
-- **Search & Filter**: Find traces by ID, endpoint, error message, environment
-- **Root Cause Detection**: Automatic identification of failure origins
-- **Error Stack Preview**: Direct file:line references for debugging
-
-### 🔗 Links
-
-**[View on NPM](https://www.npmjs.com/package/flow-debugger)** | **[Source Code](https://github.com/sannuk79/debugerpackages)** | **[Documentation](https://github.com/sannuk79/debugerpackages#readme)**
-
----
-
-## Combined Usage Example
-
-Build a hardened, monitored, and debuggable API with all three packages:
-
-```javascript
-const { apiMonitor } = require('@sannuk792/api-response-monitor');
-const { guard } = require('payload-guard-filter');
-const { flowDebugger } = require('flow-debugger');
-
-const debugger_ = flowDebugger({ environment: 'production' });
-
-app.use(apiMonitor({ mode: 'minimal' }));  // Global Monitoring
-app.use(debugger_.middleware);              // Request Tracing
-
-app.post('/api/secure-data', (req, res) => {
-  const safeBody = userShape(req.body);     // Precise Filtering
-  res.json(safeBody);
-});
-
-// Dashboards:
-// - API Monitor: http://localhost:3000/__monitor
-// - Flow Debugger: http://localhost:3000/__debugger/dashboard
-```
-
----

package/example/server.ts

@@ -1,234 +0,0 @@
-// ─────────────────────────────────────────────────────────────
-// flow-debugger — Example Server
-// Simulates real-world APIs with DB, Redis, and external calls
-// Demonstrates all features: tracing, root cause, timeline, dashboard
-// ─────────────────────────────────────────────────────────────
-
-import express from 'express';
-import { flowDebugger } from '../src/middleware/express';
-
-const app = express();
-app.use(express.json());
-
-// ─── Initialize Flow Debugger ─────────────────────────────
-const debugger_ = flowDebugger({
-    slowThreshold: 300,
-    slowQueryThreshold: 300,
-    enableTimeline: true,
-    enableDashboard: true,
-    samplingRate: 1, // 100% for testing
-});
-
-app.use(debugger_.middleware);
-
-// ─── Simulated DB / Redis helpers ─────────────────────────
-function simulateDelay(ms: number): Promise<void> {
-    return new Promise(resolve => setTimeout(resolve, ms));
-}
-
-function randomBetween(min: number, max: number): number {
-    return Math.floor(Math.random() * (max - min + 1)) + min;
-}
-
-// ─── API Routes ───────────────────────────────────────────
-
-// 1. Login — simulates DB + Redis + JWT
-app.post('/api/login', async (req, res) => {
-    const tracer = req.tracer!;
-
-    try {
-        // Step 1: Find user in DB
-        const user = await tracer.step('DB find user', async () => {
-            await simulateDelay(randomBetween(5, 25));
-            return { id: 'u_123', name: 'Saurabh', email: 'saurabh@test.com' };
-        }, { service: 'mongo' });
-
-        // Step 2: Verify password
-        await tracer.step('Verify password', async () => {
-            await simulateDelay(randomBetween(2, 10));
-            return true;
-        }, { service: 'internal' });
-
-        // Step 3: Cache session in Redis
-        await tracer.step('Redis set session', async () => {
-            await simulateDelay(randomBetween(1, 8));
-            return 'OK';
-        }, { service: 'redis' });
-
-        // Step 4: Generate JWT
-        const token = await tracer.step('JWT generate', async () => {
-            await simulateDelay(randomBetween(1, 5));
-            return 'eyJhbGciOiJIUzI1NiJ9.mock_token';
-        }, { service: 'internal' });
-
-        res.json({ success: true, token, user });
-    } catch (err: any) {
-        res.status(500).json({ error: err.message });
-    }
-});
-
-// 2. Orders — simulates slow DB query
-app.get('/api/orders', async (req, res) => {
-    const tracer = req.tracer!;
-
-    try {
-        // Slow query simulation
-        const orders = await tracer.step('DB query orders', async () => {
-            const delay = randomBetween(100, 600); // Sometimes slow!
-            await simulateDelay(delay);
-            return [
-                { id: 'ord_1', amount: 2500, status: 'completed' },
-                { id: 'ord_2', amount: 1800, status: 'pending' },
-            ];
-        }, { service: 'postgres', metadata: { sql: 'SELECT * FROM orders WHERE user_id = ?' } });
-
-        // Cache result
-        await tracer.step('Redis cache orders', async () => {
-            await simulateDelay(randomBetween(1, 5));
-            return 'OK';
-        }, { service: 'redis' });
-
-        res.json({ orders });
-    } catch (err: any) {
-        res.status(500).json({ error: err.message });
-    }
-});
-
-// 3. Dashboard — simulates multiple DB queries
-app.get('/api/dashboard', async (req, res) => {
-    const tracer = req.tracer!;
-
-    try {
-        const [stats, recentOrders, notifications] = await Promise.all([
-            tracer.step('MySQL stats query', async () => {
-                await simulateDelay(randomBetween(10, 40));
-                return { totalUsers: 1200, totalOrders: 890, revenue: 125000 };
-            }, { service: 'mysql', metadata: { sql: 'SELECT COUNT(*) FROM users' } }),
-
-            tracer.step('Postgres recent orders', async () => {
-                await simulateDelay(randomBetween(15, 50));
-                return [{ id: 'ord_1', amount: 500 }];
-            }, { service: 'postgres', metadata: { sql: 'SELECT * FROM orders ORDER BY created_at DESC LIMIT 10' } }),
-
-            tracer.step('Redis get notifications', async () => {
-                await simulateDelay(randomBetween(2, 8));
-                return [{ msg: 'New order received' }];
-            }, { service: 'redis' }),
-        ]);
-
-        res.json({ stats, recentOrders, notifications });
-    } catch (err: any) {
-        res.status(500).json({ error: err.message });
-    }
-});
-
-// 4. User Profile — simulates Redis failure
-app.get('/api/profile/:id', async (req, res) => {
-    const tracer = req.tracer!;
-
-    try {
-        // Try Redis cache first
-        let cached: any = null;
-        try {
-            cached = await tracer.step('Redis get cache', async () => {
-                // Randomly fail to simulate Redis issues
-                if (Math.random() > 0.5) {
-                    throw new Error('ECONNREFUSED: Redis connection refused');
-                }
-                await simulateDelay(randomBetween(1, 5));
-                return null; // cache miss
-            }, { service: 'redis' });
-        } catch {
-            // Redis failed, fall through to DB
-        }
-
-        // Fetch from DB
-        const user = await tracer.step('Mongo find user', async () => {
-            await simulateDelay(randomBetween(8, 30));
-            return { id: req.params.id, name: 'Saurabh', role: 'admin' };
-        }, { service: 'mongo' });
-
-        res.json({ user, fromCache: false });
-    } catch (err: any) {
-        res.status(500).json({ error: err.message });
-    }
-});
-
-// 5. Payment — simulates external API call with timeout potential
-app.post('/api/payment', async (req, res) => {
-    const tracer = req.tracer!;
-
-    try {
-        // Validate in DB
-        await tracer.step('MySQL validate order', async () => {
-            await simulateDelay(randomBetween(5, 20));
-            return true;
-        }, { service: 'mysql', metadata: { sql: 'SELECT * FROM orders WHERE id = ? AND status = ?' } });
-
-        // Call external payment gateway
-        await tracer.step('Payment Gateway API', async () => {
-            const delay = randomBetween(50, 400);
-            await simulateDelay(delay);
-            if (delay > 350) throw new Error('Gateway timeout');
-            return { transactionId: 'txn_abc123', status: 'success' };
-        }, { service: 'external', timeout: 5000 });
-
-        // Update DB
-        await tracer.step('MySQL update payment', async () => {
-            await simulateDelay(randomBetween(5, 15));
-            return true;
-        }, { service: 'mysql', metadata: { sql: 'UPDATE orders SET payment_status = ? WHERE id = ?' } });
-
-        // Clear cache
-        await tracer.step('Redis clear cache', async () => {
-            await simulateDelay(randomBetween(1, 5));
-            return 'OK';
-        }, { service: 'redis' });
-
-        res.json({ success: true, transactionId: 'txn_abc123' });
-    } catch (err: any) {
-        res.status(500).json({ error: err.message });
-    }
-});
-
-// 6. Search — simulates heavy query
-app.get('/api/search', async (req, res) => {
-    const tracer = req.tracer!;
-    const q = req.query.q || 'test';
-
-    try {
-        const results = await tracer.step('Postgres full-text search', async () => {
-            // Simulate a potentially slow full-text search
-            const delay = randomBetween(50, 800);
-            await simulateDelay(delay);
-            return [{ id: 1, title: `Result for: ${q}` }];
-        }, { service: 'postgres', metadata: { sql: `SELECT * FROM products WHERE to_tsvector(name) @@ to_tsquery('${q}')` } });
-
-        res.json({ results, count: results.length });
-    } catch (err: any) {
-        res.status(500).json({ error: err.message });
-    }
-});
-
-// ─── Start Server ─────────────────────────────────────────
-const PORT = process.env.PORT || 3500;
-app.listen(PORT, () => {
-    console.log('');
-    console.log('  ┌──────────────────────────────────────────────────┐');
-    console.log('  │                                                  │');
-    console.log('  │   🔍 Flow Debugger — Example Server              │');
-    console.log(`  │   Server:    http://localhost:${PORT}               │`);
-    console.log(`  │   Dashboard: http://localhost:${PORT}/__debugger/dashboard │`);
-    console.log(`  │   API:       http://localhost:${PORT}/__debugger    │`);
-    console.log('  │                                                  │');
-    console.log('  │   Test endpoints:                                │');
-    console.log('  │   POST /api/login        (DB + Redis + JWT)      │');
-    console.log('  │   GET  /api/orders       (Slow DB query)         │');
-    console.log('  │   GET  /api/dashboard    (Multi-service)         │');
-    console.log('  │   GET  /api/profile/:id  (Redis failures)        │');
-    console.log('  │   POST /api/payment      (External API)          │');
-    console.log('  │   GET  /api/search?q=x   (Heavy Postgres)        │');
-    console.log('  │                                                  │');
-    console.log('  └──────────────────────────────────────────────────┘');
-    console.log('');
-});

package/jest.config.js

@@ -1,8 +0,0 @@
-module.exports = {
-    preset: 'ts-jest',
-    testEnvironment: 'node',
-    roots: ['<rootDir>/tests'],
-    testMatch: ['**/*.test.ts'],
-    moduleFileExtensions: ['ts', 'js', 'json'],
-    collectCoverageFrom: ['src/**/*.ts'],
-};

package/portfolio-repo/README.md

@@ -1,182 +0,0 @@
-# 🚀 Sannu Kumar - Full-Stack & Systems Engineer
-
-> **Portfolio:** [sannu-portfolio.vercel.app](https://sannu-portfolio.vercel.app/portfolio) | **Catalog:** [Projects Catalog](https://sannu-portfolio.vercel.app/portfolio/projects)
-
-Welcome to my professional laboratory. Here, I build production-grade NPM packages, enterprise-scale web applications, and high-performance mobile solutions.
-
----
-
-
-## 💎 Featured NPM Packages
-
-### 📊 1. API Response Monitor
-**Debug production API issues in seconds with request tracing and slow endpoint detection.**
-
-[![NPM Version](https://img.shields.io/npm/v/@sannuk792/api-response-monitor?color=brightgreen)](https://www.npmjs.com/package/@sannuk792/api-response-monitor)
-[![NPM Downloads](https://img.shields.io/npm/dm/@sannuk792/api-response-monitor)](https://www.npmjs.com/package/@sannuk792/api-response-monitor)
-
-![API Monitor Dashboard](./APIRESPONSE%20DASH.png)
-
-### � Workflow Overview
-```mermaid
-graph LR
-    A[Request] --> B[Generate RequestID]
-    B --> C[Intercept Response]
-    C --> D[Calculate Metrics]
-    D --> E[Async Logging/Storage]
-    E --> F[Dashboard/Analytics]
-```
-
-- **Production Tracing**: Auto-generated `requestId` in every response.
-- **Protocol Metadata**: Built-in SDK version, platform, and service tagging for microservices.
-- **Hardened Stability**: Verified with a **14-point stress test** (100 req/sec, circular ref protection, middleware isolation).
-- **Advanced Monitoring**: Built-in slow endpoint detection & health metrics.
-- **Fail-Safe Design**: Monitoring logic never blocks or crashes your API.
-- **Non-Blocking**: Non-allocation fast paths with ~0.2ms overhead.
-
-
-### ⛑️ Maintained actively.
-**Bug fixes usually within 24–48 hours.**
-
-
-**[View on NPM](https://www.npmjs.com/package/@sannuk792/api-response-monitor)** | **[Source Code](https://github.com/sannuk79/ApiMonitor)**
-
----
-
-### 🛡️ 2. Payload Guard
-**Lightweight, zero-dependency shape-based filtering & sanitization.**
-
-[![NPM Version](https://img.shields.io/npm/v/payload-guard-filter?color=blue)](https://www.npmjs.com/package/payload-guard-filter)
-
-![Payload Guard Workflow](./PAYLOAD.png)
-
-### �️ Workflow Overview
-```mermaid
-graph LR
-    A[Request] --> B(Gatekeeper)
-    B --> C{Shape Check}
-    C -- Valid --> D[Redact & Clean]
-    C -- Invalid --> E[Strict Error / Fail Safe]
-    D --> F[Secure Response]
-    E --> F
-    F --> G((Metrics))
-```
-
-- **Shape-based Filtering**: Define what you want, auto-remove everything else.
-- **Sensitive Protection**: `password`, `token`, `secret` auto-redacted.
-- **High Performance**: Optimized schema compilation for sub-millisecond execution.
-
-**[View on NPM](https://www.npmjs.com/package/payload-guard-filter)**
-
----
-
-### 🔍 3. Flow Debugger
-**Production-safe request tracing with root cause detection and live analytics dashboard.**
-
-[![NPM Version](https://img.shields.io/npm/v/flow-debugger?color=purple)](https://www.npmjs.com/package/flow-debugger)
-[![GitHub](https://img.shields.io/badge/GitHub-debugerpackages-purple)](https://github.com/sannuk79/debugerpackages)
-
-![Flow Debugger Architecture](https://via.placeholder.com/800x400/1a1a2e/7c3aed?text=Flow+Debugger+Dashboard)
-
-### 🔄 Workflow Overview
-```mermaid
-graph LR
-    A[Request] --> B[Generate TraceID]
-    B --> C[Step-by-Step Tracking]
-    C --> D[Auto-Classify: INFO/WARN/ERROR/CRITICAL]
-    D --> E[Root Cause Detection]
-    E --> F[Analytics Dashboard]
-    F --> G[Search & Filter]
-```
-
-**Key Features:**
-- **Auto-Instrumentation**: MongoDB, MySQL, PostgreSQL, Redis, Fetch, Axios — zero code changes
-- **External API Tracing**: Stripe, Razorpay, SendGrid, Twilio auto-tagged
-- **Root Cause Detection**: Timeout → Failure → Slow bottleneck algorithm
-- **Error Stack Preview**: Shows `errorFile:line` in dashboard (e.g., `auth.service.ts:42`)
-- **Payload Size Detection**: Warns on large payloads (>1MB) slowing requests
-- **Environment Tagging**: Filter traces by dev/staging/production
-- **Trace Search**: Search by traceId, endpoint, error message
-- **Live Dashboard**: Real-time analytics at `/__debugger/dashboard`
-- **Production-Safe**: Never blocks requests, all try/catch wrapped
-
-**Performance:**
-- **Load Tested**: 56,000 requests in 10s (100 concurrent connections)
-- **Throughput**: 5,600 req/sec
-- **Overhead**: <1ms per request
-
-**[View on NPM](https://www.npmjs.com/package/flow-debugger)** | **[Source Code](https://github.com/sannuk79/debugerpackages)**
-
----
-
-## 📂 Project Catalog
-
-A selection of production-grade applications and experimental prototypes.
-
-| Project | Category | Description | Tech Stack |
-|:---|:---|:---|:---|
-| **DRIVERRUNNER** | Mobile | Complete Ride Sharing Platform with real-time tracking & payments. | Node, Mongo, RN, Socket.IO |
-| **SHOPMIND AI** | Web | AI-powered price comparison with Rust-accelerated scraping. | Next.js 15, FastAPI, Rust |
-| **URBANCRUISE LMS** | Web | Enterprise Lead Management System with real-time visualization. | Next.js, Express, MySQL |
-| **TASKVISTA** | Web | Team Management Dashboard for developer communities. | React, Kendo UI, Tailwind |
-| **BIOMETRIC AUTH** | Tools | WebAuthn system for passwordless fingerprint login. | WebAuthn, React 19, Security |
-| **API MONITOR** | Tools | The official NPM package for API latency and health tracking. | NPM, Node.js, Metrics |
-
-### ✨ Project Deep Dives
-
-#### 🚕 [DriverRunner](#)
-A comprehensive ride-hailing solution featuring 3 separate apps. Includes OTP-based authentication, real-time driver tracking (React Native Maps), and live booking systems via Socket.IO.
-
-#### 🤖 [ShopMind AI](https://shopmind-ai.vercel.app/)
-Intelligent price comparison platform. Uses Rust-accelerated scraping engines for speed and WebAuthn for biometric fingerprint login.
-
-#### 📊 [UrbanCruise LMS](https://lms-leadmangsystem.vercel.app/)
-Enterprise-grade lead tracking system. Handles multi-source collection (Meta, Google Ads) with real-time dashboards using Recharts and role-based access control.
-
----
-
-## ⚡ Performance Benchmarks
-
-### 🛡️ Payload Guard (Production Scale)
-| Benchmark | ops/sec | avg (ms) |
-|-----------|---------|----------|
-| **Small payload** | 449,365 | **0.0022ms** |
-| **Medium payload** | 7,791 | **0.1284ms** |
-| **Large payload** | 246 | **4.0724ms** |
-
-### 📊 API Monitor (Middleware Overhead)
-| Metric | Full Mode | Minimal Mode |
-|-----------|---------|----------|
-| **Latency** | ~0.18ms | **<0.05ms** |
-| **Throughput** | 50k+ RPM | 100k+ RPM |
-
----
-
-## 🛠️ Combined Usage
-
-Build a hardened, monitored, and debuggable API:
-```javascript
-const { apiMonitor } = require('@sannuk792/api-response-monitor');
-const { guard } = require('payload-guard-filter');
-const { flowDebugger } = require('flow-debugger');
-
-const debugger_ = flowDebugger({ environment: 'production' });
-
-app.use(apiMonitor({ mode: 'minimal' }));  // Global Monitoring
-app.use(debugger_.middleware);              // Request Tracing
-
-app.post('/api/secure-data', (req, res) => {
-  const safeBody = userShape(req.body);     // Precise Filtering
-  res.json(safeBody);
-});
-
-// Dashboard: http://localhost:3000/__debugger/dashboard
-```
-
----
-
-<p align="center">
-  Connect with me on <strong>[Portfolio](https://sannu-portfolio.vercel.app/portfolio)</strong>
-  <br>
-  Made with ❤️ for High-Performance Systems
-</p>