flow-debugger 1.0.0

package/dist/esm/core/RootCause.js

@@ -0,0 +1,86 @@
+// ─────────────────────────────────────────────────────────────
+// flow-debugger — Root Cause Detection
+// Analyzes trace steps to identify the most likely failure origin
+// ─────────────────────────────────────────────────────────────
+/**
+ * Detect the root cause of a trace failure or slowness.
+ *
+ * Algorithm:
+ *  1. If response is 500 and a step failed → root cause = first failed step
+ *  2. If a step timed out → root cause = timeout step (CRITICAL)
+ *  3. If DB/Redis slow and total latency high → root cause = slow dependency
+ *  4. If no failures but overall slow → root cause = slowest step
+ */
+export function detectRootCause(steps, statusCode, config) {
+    if (steps.length === 0)
+        return null;
+    const slowThreshold = config.slowThreshold ?? 300;
+    // 1. Look for timed-out steps (highest priority)
+    const timedOut = steps.find(s => s.status === 'timeout');
+    if (timedOut) {
+        return {
+            cause: `${timedOut.name} timed out`,
+            step: timedOut.name,
+            service: timedOut.service,
+            confidence: 'high',
+        };
+    }
+    // 2. Look for failed steps when response is 5xx
+    if (statusCode && statusCode >= 500) {
+        const failedSteps = steps.filter(s => s.status === 'error');
+        if (failedSteps.length > 0) {
+            // First failure is most likely root cause
+            const first = failedSteps[0];
+            return {
+                cause: `${first.name} failed: ${first.error || 'unknown error'}`,
+                step: first.name,
+                service: first.service,
+                confidence: 'high',
+            };
+        }
+    }
+    // 3. Look for any failed step (even if response isn't 500)
+    const failedStep = steps.find(s => s.status === 'error');
+    if (failedStep) {
+        return {
+            cause: `${failedStep.name} failed: ${failedStep.error || 'unknown error'}`,
+            step: failedStep.name,
+            service: failedStep.service,
+            confidence: statusCode && statusCode >= 400 ? 'high' : 'medium',
+        };
+    }
+    // 4. Look for slow steps
+    const slowSteps = steps.filter(s => s.duration > slowThreshold);
+    if (slowSteps.length > 0) {
+        // Slowest step is the most likely bottleneck
+        const slowest = slowSteps.reduce((a, b) => (a.duration > b.duration ? a : b));
+        const totalDuration = steps.reduce((sum, s) => sum + s.duration, 0);
+        const ratio = slowest.duration / totalDuration;
+        return {
+            cause: `Slow ${getServiceLabel(slowest.service)} query: ${slowest.name} (${Math.round(slowest.duration)}ms)`,
+            step: slowest.name,
+            service: slowest.service,
+            confidence: ratio > 0.5 ? 'high' : 'medium',
+        };
+    }
+    return null;
+}
+function getServiceLabel(service) {
+    const labels = {
+        mongo: 'MongoDB',
+        mysql: 'MySQL',
+        postgres: 'PostgreSQL',
+        redis: 'Redis',
+        axios: 'HTTP',
+        fetch: 'HTTP',
+        stripe: 'Stripe',
+        razorpay: 'Razorpay',
+        sendgrid: 'SendGrid',
+        twilio: 'Twilio',
+        external: 'External',
+        internal: 'Internal',
+        unknown: 'Unknown',
+    };
+    return labels[service] || service;
+}
+//# sourceMappingURL=RootCause.js.map

package/dist/esm/core/RootCause.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RootCause.js","sourceRoot":"","sources":["../../../src/core/RootCause.ts"],"names":[],"mappings":"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"}

package/dist/esm/core/Sampler.js

@@ -0,0 +1,30 @@
+// ─────────────────────────────────────────────────────────────
+// flow-debugger — Sampler
+// Probabilistic sampling for high-traffic environments
+// ─────────────────────────────────────────────────────────────
+export class Sampler {
+    constructor(rate = 1, alwaysSampleErrors = true) {
+        this.rate = Math.max(0, Math.min(1, rate));
+        this.alwaysSampleErrors = alwaysSampleErrors;
+    }
+    /** Should this request be sampled? */
+    shouldSample() {
+        if (this.rate >= 1)
+            return true;
+        if (this.rate <= 0)
+            return false;
+        return Math.random() < this.rate;
+    }
+    /** Force sample if it's an error (if alwaysSampleErrors is true) */
+    shouldSampleError() {
+        return this.alwaysSampleErrors;
+    }
+    /** Update sampling rate at runtime */
+    setRate(rate) {
+        this.rate = Math.max(0, Math.min(1, rate));
+    }
+    getRate() {
+        return this.rate;
+    }
+}
+//# sourceMappingURL=Sampler.js.map

package/dist/esm/core/Sampler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Sampler.js","sourceRoot":"","sources":["../../../src/core/Sampler.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,0BAA0B;AAC1B,uDAAuD;AACvD,gEAAgE;AAEhE,MAAM,OAAO,OAAO;IAIhB,YAAY,IAAI,GAAG,CAAC,EAAE,kBAAkB,GAAG,IAAI;QAC3C,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC;QAC3C,IAAI,CAAC,kBAAkB,GAAG,kBAAkB,CAAC;IACjD,CAAC;IAED,sCAAsC;IACtC,YAAY;QACR,IAAI,IAAI,CAAC,IAAI,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC;QAChC,IAAI,IAAI,CAAC,IAAI,IAAI,CAAC;YAAE,OAAO,KAAK,CAAC;QACjC,OAAO,IAAI,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC;IACrC,CAAC;IAED,oEAAoE;IACpE,iBAAiB;QACb,OAAO,IAAI,CAAC,kBAAkB,CAAC;IACnC,CAAC;IAED,sCAAsC;IACtC,OAAO,CAAC,IAAY;QAChB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC;IAC/C,CAAC;IAED,OAAO;QACH,OAAO,IAAI,CAAC,IAAI,CAAC;IACrB,CAAC;CACJ"}

package/dist/esm/core/Timeline.js

@@ -0,0 +1,86 @@
+// ─────────────────────────────────────────────────────────────
+// flow-debugger — Timeline Renderer
+// Prints a visual timeline of a trace to the console
+// ─────────────────────────────────────────────────────────────
+const ICONS = {
+    success: '✔',
+    error: '❌',
+    timeout: '⏱ TIMEOUT',
+};
+const LEVEL_COLORS = {
+    INFO: '\x1b[32m', // green
+    WARN: '\x1b[33m', // yellow
+    ERROR: '\x1b[31m', // red
+    CRITICAL: '\x1b[35m', // magenta
+};
+const RESET = '\x1b[0m';
+const DIM = '\x1b[2m';
+const BOLD = '\x1b[1m';
+const CYAN = '\x1b[36m';
+/**
+ * Render a trace timeline to the console.
+ *
+ * Output example:
+ * ┌─── flow-debugger ── req_abc123 ── POST /login ───
+ * │ [0ms]   Request start
+ * │ [2ms]   DB find user ✔ (14ms) [mongo]
+ * │ [16ms]  Redis cache ❌ (3ms) [redis]
+ * │ [20ms]  Response 200
+ * │
+ * │ ⚠ Root cause: Redis cache failed: connection refused
+ * │ Classification: ERROR
+ * │ Total: 20ms
+ * └────────────────────────────────────────────────────
+ */
+export function renderTimeline(trace, logger = console.log) {
+    const lines = [];
+    const divider = '─'.repeat(50);
+    lines.push('');
+    lines.push(`${CYAN}┌─── flow-debugger ── ${trace.traceId} ── ${trace.method} ${trace.endpoint} ───${RESET}`);
+    lines.push(`${DIM}│ [0ms]    Request start${RESET}`);
+    for (const step of trace.steps) {
+        const offset = Math.round(step.startTime);
+        const dur = Math.round(step.duration);
+        const icon = ICONS[step.status] || '?';
+        const levelColor = LEVEL_COLORS[step.classification] || '';
+        const serviceTag = step.service !== 'internal' ? ` ${DIM}[${step.service}]${RESET}` : '';
+        const line = `│ [${offset}ms]${' '.repeat(Math.max(1, 5 - String(offset).length))}` +
+            `${levelColor}${step.name} ${icon} (${dur}ms)${RESET}${serviceTag}`;
+        lines.push(line);
+        if (step.error) {
+            lines.push(`│         ${DIM}└─ ${step.error}${RESET}`);
+        }
+        // Slow query warning
+        if (step.classification === 'WARN' && step.duration > 300) {
+            lines.push(`│         ${LEVEL_COLORS.WARN}⚠ Slow ${step.service} query detected (${dur}ms)${RESET}`);
+        }
+    }
+    // Response line
+    lines.push(`${DIM}│ [${Math.round(trace.totalDuration)}ms]${' '.repeat(Math.max(1, 5 - String(Math.round(trace.totalDuration)).length))}Response ${trace.statusCode || '—'}${RESET}`);
+    lines.push('│');
+    // Root cause
+    if (trace.rootCause) {
+        const rcColor = LEVEL_COLORS.ERROR;
+        lines.push(`${rcColor}│ 🔍 Root cause: ${trace.rootCause.cause}${RESET}`);
+        lines.push(`${DIM}│    Service: ${trace.rootCause.service} | Confidence: ${trace.rootCause.confidence}${RESET}`);
+    }
+    // Classification
+    const clsColor = LEVEL_COLORS[trace.classification];
+    lines.push(`${clsColor}│ Classification: ${trace.classification}${RESET}`);
+    lines.push(`${DIM}│ Total: ${Math.round(trace.totalDuration)}ms${RESET}`);
+    lines.push(`${CYAN}└${divider}${RESET}`);
+    lines.push('');
+    logger(lines.join('\n'));
+}
+/**
+ * Render a compact one-line summary for high-traffic mode.
+ */
+export function renderCompact(trace, logger = console.log) {
+    const icon = trace.classification === 'INFO' ? '✔' :
+        trace.classification === 'WARN' ? '⚠' :
+            trace.classification === 'ERROR' ? '❌' :
+                '🔴';
+    const rc = trace.rootCause ? ` → ${trace.rootCause.cause}` : '';
+    logger(`${icon} ${trace.method} ${trace.endpoint} ${Math.round(trace.totalDuration)}ms [${trace.classification}]${rc}`);
+}
+//# sourceMappingURL=Timeline.js.map

package/dist/esm/core/Timeline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Timeline.js","sourceRoot":"","sources":["../../../src/core/Timeline.ts"],"names":[],"mappings":"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"}

package/dist/esm/core/TraceEngine.js

@@ -0,0 +1,217 @@
+// ─────────────────────────────────────────────────────────────
+// flow-debugger — Trace Engine
+// Manages trace lifecycle: create → add steps → end
+// ─────────────────────────────────────────────────────────────
+import { EventEmitter } from 'events';
+import { DEFAULT_CONFIG, } from './types';
+import { classify, classifyTrace } from './Classifier';
+import { detectRootCause } from './RootCause';
+import { renderTimeline } from './Timeline';
+let idCounter = 0;
+/** Generate a unique trace ID */
+function generateTraceId() {
+    const ts = Date.now().toString(36);
+    const rand = Math.random().toString(36).substring(2, 8);
+    idCounter++;
+    return `req_${ts}_${rand}_${idCounter}`;
+}
+/**
+ * Extract file and line number from stack trace for dashboard preview.
+ * Example: "at Object.<anonymous> (d:\\project\\auth.service.ts:42:15)"
+ * Returns: { file: "auth.service.ts", line: 42 }
+ */
+function extractErrorLocation(stackTrace) {
+    if (!stackTrace)
+        return {};
+    try {
+        // Match patterns like:
+        // at functionName (file.ts:42:15)
+        // at file.ts:42:15
+        const match = stackTrace.match(/\(([^)]+):(\d+):\d+\)/) || stackTrace.match(/at\s+([^:]+):(\d+):\d+/);
+        if (match) {
+            const fullPath = match[1];
+            const lineNum = parseInt(match[2], 10);
+            // Extract just the filename from full path
+            const fileName = fullPath.split(/[/\\]/).pop() || fullPath;
+            return { file: fileName, line: lineNum };
+        }
+    }
+    catch (_) {
+        // ignore parse errors
+    }
+    return {};
+}
+/**
+ * TraceEngine — manages the lifecycle of a single request trace.
+ *
+ * Usage:
+ *   const engine = new TraceEngine(config);
+ *   const tracer = engine.startTrace('/login', 'POST');
+ *   await tracer.step('DB find user', async () => User.findOne(), { service: 'mongo' });
+ *   tracer.end(200);
+ */
+export class TraceEngine extends EventEmitter {
+    constructor(config) {
+        super();
+        this.config = { ...DEFAULT_CONFIG, ...config };
+    }
+    /** Update config at runtime */
+    updateConfig(patch) {
+        Object.assign(this.config, patch);
+    }
+    getConfig() {
+        return { ...this.config };
+    }
+    /** Start a new request trace */
+    startTrace(endpoint, method) {
+        const tracer = new RequestTracer(endpoint, method, this.config, this);
+        this.safeEmit('trace:start', { traceId: tracer.getTraceId(), endpoint, method });
+        return tracer;
+    }
+    /** Safe emit — never throws */
+    safeEmit(event, data) {
+        try {
+            this.emit(event, data);
+        }
+        catch (_) {
+            // debugger never crashes the app
+        }
+    }
+}
+/**
+ * RequestTracer — the object attached to a single request.
+ * Provides `step()` for manual instrumentation and `addStep()` for auto-instrumentation.
+ */
+export class RequestTracer {
+    constructor(endpoint, method, config, engine) {
+        this.steps = [];
+        this.ended = false;
+        this.traceId = generateTraceId();
+        this.endpoint = endpoint;
+        this.method = method;
+        this.startTime = performance.now();
+        this.config = config;
+        this.engine = engine;
+    }
+    getTraceId() {
+        return this.traceId;
+    }
+    getSteps() {
+        return [...this.steps];
+    }
+    /** Manually run & trace an async step */
+    async step(name, fn, options) {
+        const service = options?.service ?? 'internal';
+        const timeout = options?.timeout ?? this.config.defaultTimeout;
+        const stepStart = performance.now();
+        let status = 'success';
+        let error;
+        let stackTrace;
+        let result;
+        try {
+            // Race the function against a timeout
+            result = await Promise.race([
+                Promise.resolve(fn()),
+                new Promise((_, reject) => setTimeout(() => reject(new Error(`Step "${name}" timed out after ${timeout}ms`)), timeout)),
+            ]);
+        }
+        catch (err) {
+            const e = err instanceof Error ? err : new Error(String(err));
+            if (e.message.includes('timed out')) {
+                status = 'timeout';
+            }
+            else {
+                status = 'error';
+            }
+            error = e.message;
+            stackTrace = e.stack;
+            const { file: errorFile, line: errorLine } = extractErrorLocation(stackTrace);
+            // Re-throw so the caller can handle the error
+            const stepEnd = performance.now();
+            const duration = stepEnd - stepStart;
+            const classification = classify(duration, status, this.config);
+            this.steps.push({
+                name,
+                service,
+                status,
+                classification,
+                startTime: stepStart - this.startTime,
+                endTime: stepEnd - this.startTime,
+                duration,
+                error,
+                stackTrace,
+                errorFile,
+                errorLine,
+                metadata: options?.metadata,
+            });
+            throw err;
+        }
+        const stepEnd = performance.now();
+        const duration = stepEnd - stepStart;
+        const classification = classify(duration, status, this.config);
+        const { file: errorFile, line: errorLine } = error ? extractErrorLocation(stackTrace) : {};
+        this.steps.push({
+            name,
+            service,
+            status,
+            classification,
+            startTime: stepStart - this.startTime,
+            endTime: stepEnd - this.startTime,
+            duration,
+            error,
+            stackTrace,
+            errorFile,
+            errorLine,
+            metadata: options?.metadata,
+        });
+        return result;
+    }
+    /** Add a pre-recorded step (used by auto-integrations) */
+    addStep(step) {
+        try {
+            this.steps.push(step);
+        }
+        catch (_) {
+            // never crash
+        }
+    }
+    /** End the trace and produce the final result */
+    end(statusCode) {
+        if (this.ended) {
+            return this.buildTrace(statusCode);
+        }
+        this.ended = true;
+        const trace = this.buildTrace(statusCode);
+        // Render timeline to console
+        if (this.config.enableTimeline) {
+            try {
+                renderTimeline(trace, this.config.logger);
+            }
+            catch (_) {
+                // never crash
+            }
+        }
+        this.engine.safeEmit('trace:end', trace);
+        return trace;
+    }
+    buildTrace(statusCode) {
+        const endTime = performance.now();
+        const totalDuration = endTime - this.startTime;
+        const traceClassification = classifyTrace(this.steps, totalDuration, this.config);
+        const rootCause = detectRootCause(this.steps, statusCode, this.config);
+        return {
+            traceId: this.traceId,
+            endpoint: this.endpoint,
+            method: this.method,
+            statusCode,
+            steps: [...this.steps],
+            totalDuration,
+            classification: traceClassification,
+            rootCause,
+            startTime: 0,
+            endTime: totalDuration,
+            timestamp: new Date(),
+        };
+    }
+}
+//# sourceMappingURL=TraceEngine.js.map

package/dist/esm/core/TraceEngine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TraceEngine.js","sourceRoot":"","sources":["../../../src/core/TraceEngine.ts"],"names":[],"mappings":"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"}

package/dist/esm/core/types.js

@@ -0,0 +1,18 @@
+// ─────────────────────────────────────────────────────────────
+// flow-debugger — Core Type Definitions
+// ─────────────────────────────────────────────────────────────
+export const DEFAULT_CONFIG = {
+    enabled: true,
+    environment: process.env.NODE_ENV || 'development',
+    slowThreshold: 300,
+    slowQueryThreshold: 300,
+    defaultTimeout: 30000,
+    samplingRate: 1,
+    alwaysSampleErrors: true,
+    maxTraces: 1000,
+    enableTimeline: true,
+    enableDashboard: true,
+    largePayloadThreshold: 1024 * 1024, // 1MB
+    logger: console.log,
+};
+//# sourceMappingURL=types.js.map

package/dist/esm/core/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/core/types.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,wCAAwC;AACxC,gEAAgE;AA0JhE,MAAM,CAAC,MAAM,cAAc,GAA6B;IACpD,OAAO,EAAE,IAAI;IACb,WAAW,EAAE,OAAO,CAAC,GAAG,CAAC,QAAQ,IAAI,aAAa;IAClD,aAAa,EAAE,GAAG;IAClB,kBAAkB,EAAE,GAAG;IACvB,cAAc,EAAE,KAAK;IACrB,YAAY,EAAE,CAAC;IACf,kBAAkB,EAAE,IAAI;IACxB,SAAS,EAAE,IAAI;IACf,cAAc,EAAE,IAAI;IACpB,eAAe,EAAE,IAAI;IACrB,qBAAqB,EAAE,IAAI,GAAG,IAAI,EAAE,MAAM;IAC1C,MAAM,EAAE,OAAO,CAAC,GAAG;CACtB,CAAC"}

package/dist/esm/index.js

@@ -0,0 +1,22 @@
+// ─────────────────────────────────────────────────────────────
+// flow-debugger — Main Entry Point
+// ─────────────────────────────────────────────────────────────
+// Core
+export { TraceEngine, RequestTracer } from './core/TraceEngine';
+export { classify, classifyTrace, classifyQuery } from './core/Classifier';
+export { detectRootCause } from './core/RootCause';
+export { Analytics } from './core/Analytics';
+export { HealthMonitor } from './core/HealthMonitor';
+export { Sampler } from './core/Sampler';
+export { renderTimeline, renderCompact } from './core/Timeline';
+export { DEFAULT_CONFIG } from './core/types';
+// Integrations
+export { mongoTracer, removeMongoTracer } from './integrations/mongo';
+export { mysqlTracer } from './integrations/mysql';
+export { pgTracer } from './integrations/postgres';
+export { redisTracer } from './integrations/redis';
+export { fetchTracer, removeFetchTracer } from './integrations/fetch';
+export { axiosTracer } from './integrations/axios';
+// Middleware
+export { flowDebugger } from './middleware/express';
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,mCAAmC;AACnC,gEAAgE;AAEhE,OAAO;AACP,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAC3E,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAkBhE,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C,eAAe;AACf,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACtE,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACtE,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAEnD,aAAa;AACb,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/esm/integrations/axios.js

@@ -0,0 +1,133 @@
+// ─────────────────────────────────────────────────────────────
+// flow-debugger — Axios Auto-Instrument
+// Uses interceptors to trace all Axios requests
+// ─────────────────────────────────────────────────────────────
+import { DEFAULT_CONFIG } from '../core/types';
+import { classifyQuery } from '../core/Classifier';
+const DEFAULT_SERVICE_MAP = {
+    'stripe.com': 'stripe',
+    'api.stripe.com': 'stripe',
+    'razorpay.com': 'razorpay',
+    'api.razorpay.com': 'razorpay',
+    'sendgrid.com': 'sendgrid',
+    'api.sendgrid.com': 'sendgrid',
+    'twilio.com': 'twilio',
+    'api.twilio.com': 'twilio',
+};
+/**
+ * Auto-instrument Axios instance to trace all HTTP requests.
+ *
+ * Usage:
+ *   axiosTracer(axios, { getTracer: () => currentTracer })
+ *
+ * Output:
+ *   Axios POST https://api.stripe.com/v1/charges → 234ms ✔ [stripe]
+ *   Axios GET https://api.razorpay.com/orders → 502 error ❌ [razorpay]
+ */
+export function axiosTracer(axiosInstance, options) {
+    try {
+        if (axiosInstance.__flowDebuggerPatched)
+            return;
+        axiosInstance.__flowDebuggerPatched = true;
+        const config = { ...DEFAULT_CONFIG, ...options?.config };
+        const serviceMap = { ...DEFAULT_SERVICE_MAP, ...options?.serviceMap };
+        // Request interceptor — attach start time
+        axiosInstance.interceptors.request.use((reqConfig) => {
+            reqConfig.__flowDebuggerStartTime = performance.now();
+            return reqConfig;
+        }, (error) => Promise.reject(error));
+        // Response interceptor — record success
+        axiosInstance.interceptors.response.use((response) => {
+            const tracer = options?.getTracer?.();
+            if (!tracer)
+                return response;
+            const reqConfig = response.config;
+            const startTime = reqConfig.__flowDebuggerStartTime || performance.now();
+            const endTime = performance.now();
+            const duration = endTime - startTime;
+            const url = reqConfig.url || 'unknown';
+            const method = (reqConfig.method || 'GET').toUpperCase();
+            const service = getServiceFromUrl(url, serviceMap);
+            const stepName = `Axios ${method} ${getDomain(url)}`;
+            const classification = classifyQuery(duration, 'success', config);
+            tracer.addStep({
+                name: stepName,
+                service,
+                status: 'success',
+                classification,
+                startTime,
+                endTime,
+                duration,
+                metadata: { url, method, statusCode: response.status },
+            });
+            return response;
+        }, (error) => {
+            const tracer = options?.getTracer?.();
+            if (!tracer)
+                return Promise.reject(error);
+            const reqConfig = error.config || {};
+            const startTime = reqConfig.__flowDebuggerStartTime || performance.now();
+            const endTime = performance.now();
+            const duration = endTime - startTime;
+            const url = reqConfig.url || 'unknown';
+            const method = (reqConfig.method || 'GET').toUpperCase();
+            const service = getServiceFromUrl(url, serviceMap);
+            const stepName = `Axios ${method} ${getDomain(url)}`;
+            let status = 'error';
+            let errorMsg = error.message || 'Request failed';
+            // Detect timeouts
+            if (error.code === 'ECONNABORTED' || error.code === 'ETIMEDOUT' || errorMsg.includes('timeout')) {
+                status = 'timeout';
+            }
+            // HTTP error status
+            if (error.response) {
+                errorMsg = `HTTP ${error.response.status} ${error.response.statusText || ''}`;
+            }
+            const classification = classifyQuery(duration, status, config);
+            tracer.addStep({
+                name: stepName,
+                service,
+                status,
+                classification,
+                startTime,
+                endTime,
+                duration,
+                error: errorMsg,
+                stackTrace: error.stack,
+                metadata: { url, method, statusCode: error.response?.status },
+            });
+            return Promise.reject(error);
+        });
+    }
+    catch (_) {
+        // Production-safe: never crash
+    }
+}
+/** Extract service tag from URL */
+function getServiceFromUrl(url, serviceMap) {
+    try {
+        const urlObj = new URL(url);
+        const hostname = urlObj.hostname;
+        if (serviceMap[hostname])
+            return serviceMap[hostname];
+        for (const [pattern, service] of Object.entries(serviceMap)) {
+            if (hostname.includes(pattern))
+                return service;
+        }
+        return 'axios';
+    }
+    catch {
+        return 'axios';
+    }
+}
+/** Extract domain from URL for display */
+function getDomain(url) {
+    try {
+        const urlObj = new URL(url);
+        return urlObj.hostname + urlObj.pathname.substring(0, 30);
+    }
+    catch {
+        return url.substring(0, 50);
+    }
+}
+//# sourceMappingURL=axios.js.map

package/dist/esm/integrations/axios.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"axios.js","sourceRoot":"","sources":["../../../src/integrations/axios.ts"],"names":[],"mappings":"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"}