@fluxiapi/react 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Aswin
+
+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,231 @@
+# @fluxiapi/react
+
+Drop-in React DevTools for [FluxAPI](https://github.com/aswinsasi/fluxapi). Live API health monitoring with TanStack Query & SWR integration.
+
+## Installation
+
+```bash
+npm install @fluxiapi/react
+```
+
+### Requirements
+
+- **React >= 17** (hooks required)
+- **@fluxiapi/scan** — installed automatically as a dependency
+
+### Optional Peer Dependencies
+
+```bash
+# For TanStack Query integration
+npm install @tanstack/react-query
+
+# For SWR integration
+npm install swr
+```
+
+---
+
+## Quick Start
+
+### 1. Add `<FluxDevTools />`
+
+```jsx
+import { FluxDevTools } from '@fluxiapi/react';
+
+function App() {
+  return (
+    <>
+      <YourApp />
+      <FluxDevTools />
+    </>
+  );
+}
+```
+
+That's it. A floating badge appears in the corner showing your live API health score. Click to expand the full panel.
+
+- Only renders in `development` mode
+- Auto-starts scanning on mount
+- Toggle with `Ctrl+Shift+F`
+
+### 2. With TanStack Query (optional)
+
+```jsx
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { FluxDevTools, wrapQueryClient } from '@fluxiapi/react';
+
+const queryClient = wrapQueryClient(new QueryClient({
+  defaultOptions: { queries: { staleTime: 30_000 } },
+}));
+
+function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <YourApp />
+      <FluxDevTools />
+    </QueryClientProvider>
+  );
+}
+```
+
+`wrapQueryClient` instruments the QueryClient to capture query keys, staleTime, gcTime, refetch patterns for richer analysis.
+
+### 3. With SWR (optional)
+
+```jsx
+import { SWRConfig } from 'swr';
+import { FluxDevTools, fluxSWRMiddleware } from '@fluxiapi/react';
+
+function App() {
+  return (
+    <SWRConfig value={{ use: [fluxSWRMiddleware] }}>
+      <YourApp />
+      <FluxDevTools />
+    </SWRConfig>
+  );
+}
+```
+
+---
+
+## `<FluxDevTools />` Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `position` | `'bottom-right'` \| `'bottom-left'` \| `'top-right'` \| `'top-left'` | `'bottom-right'` | Badge position |
+| `network` | `string` | `'wifi'` | Network profile for scoring |
+| `analysisInterval` | `number` | `3000` | Re-analysis interval (ms) |
+| `autoStart` | `boolean` | `true` | Auto-start scanning on mount |
+| `defaultOpen` | `boolean` | `false` | Start with panel expanded |
+| `verbose` | `boolean` | `false` | Console debug logging |
+| `forceShow` | `boolean` | `false` | Show in production mode |
+| `shortcut` | `string \| null` | `'ctrl+shift+f'` | Keyboard toggle shortcut |
+
+---
+
+## Hooks
+
+Use hooks to access scan data in your own components:
+
+```jsx
+import {
+  useFluxScore,
+  useFluxViolations,
+  useFluxRequests,
+  useFluxReport,
+  useFluxScanning,
+} from '@fluxiapi/react';
+
+function MyStatusBar() {
+  const { overall, grade, color } = useFluxScore();
+  const violations = useFluxViolations({ severity: 'critical' });
+  const { scanning, elapsed, start, stop } = useFluxScanning();
+
+  return (
+    <div style={{ color }}>
+      Score: {overall} ({grade}) · {violations.length} critical issues
+      {scanning ? <span>Scanning... {elapsed}s</span> : null}
+    </div>
+  );
+}
+```
+
+### Available Hooks
+
+| Hook | Returns | Description |
+|------|---------|-------------|
+| `useFluxScore()` | `{ overall, grade, efficiency, caching, patterns, color }` | Current API health score |
+| `useFluxViolations(filter?)` | `RuleViolation[]` | Active violations, filterable by severity/category/ruleId |
+| `useFluxRequests(filter?)` | `FluxRequestRecord[]` | Captured requests, filterable by type/method/duration |
+| `useFluxReport()` | `FluxReport \| null` | Full analysis report |
+| `useFluxScanning()` | `{ scanning, elapsed, requestCount, start, stop, reset }` | Scan lifecycle control |
+
+---
+
+## Advanced: Custom Provider
+
+For shared state across components without `<FluxDevTools />`:
+
+```jsx
+import { FluxProvider, useFluxScore } from '@fluxiapi/react';
+
+function App() {
+  return (
+    <FluxProvider network="jio-4g" analysisInterval={5000}>
+      <Dashboard />
+    </FluxProvider>
+  );
+}
+
+function Dashboard() {
+  const { overall } = useFluxScore();
+  return <h1>API Score: {overall}</h1>;
+}
+```
+
+---
+
+## Advanced: Scanner Bridge
+
+For full control over the scan engine:
+
+```jsx
+import { ScannerBridge } from '@fluxiapi/react';
+
+const bridge = new ScannerBridge({
+  network: 'jio-4g',
+  analysisInterval: 5000,
+  verbose: true,
+});
+
+// Subscribe to state changes
+bridge.subscribe((state) => {
+  console.log('Score:', state.score, 'Violations:', state.violations.length);
+});
+
+// Start/stop
+await bridge.start();
+const report = bridge.stop();
+
+// Pass to FluxDevTools
+<FluxDevTools bridge={bridge} />
+```
+
+---
+
+## What the DevTools Panel Shows
+
+### Overview Tab
+- API health score gauge (0-100)
+- Category breakdown (Efficiency / Caching / Patterns)
+- Stats cards (critical, warnings, API calls)
+- Impact banner (time saved, requests eliminated)
+- Top 3 issues
+
+### Violations Tab
+- All violations with severity dots
+- Rule ID badges (E1, C1, P2, etc.)
+- Impact pills (time, requests, bandwidth)
+- Expandable details with endpoints and fix code
+
+### Requests Tab
+- Live request feed (newest first)
+- Method badges (GET/POST/PUT/DELETE)
+- Status codes with color coding
+- Duration with performance coloring
+
+---
+
+## 13 Rules Detected
+
+| Category | Rules |
+|----------|-------|
+| ⚡ Efficiency | E1 Waterfalls, E2 Duplicates, E3 N+1, E4 Over-fetching, E5 Batchable |
+| 💾 Caching | C1 No Cache, C2 Under-Caching, C3 Over-Caching, C4 Missing Revalidation |
+| 🔄 Patterns | P1 Missing Prefetch, P2 Unnecessary Polling, P3 No Error Recovery, P4 Uncompressed |
+
+---
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,266 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { FluxRequestRecord, FluxReport, RuleViolation } from '@fluxiapi/scan';
+import { ReactNode } from 'react';
+
+interface FluxState {
+    /** Whether the scanner is actively capturing */
+    scanning: boolean;
+    /** Captured requests so far */
+    requests: FluxRequestRecord[];
+    /** Latest analysis report (null before first analysis) */
+    report: FluxReport | null;
+    /** Current API health score 0-100 */
+    score: number;
+    /** Active violations */
+    violations: RuleViolation[];
+    /** Scan start time */
+    startTime: number;
+    /** Elapsed seconds */
+    elapsed: number;
+    /** Selected network profile */
+    network: string;
+    /** Framework info if detected */
+    framework: string | null;
+}
+type FluxStateListener = (state: FluxState) => void;
+interface ScannerBridgeConfig {
+    /** Network profile for scoring */
+    network?: string;
+    /** How often to re-analyze (ms, default: 3000) */
+    analysisInterval?: number;
+    /** Auto-start scanning on mount */
+    autoStart?: boolean;
+    /** Verbose console logging */
+    verbose?: boolean;
+}
+declare class ScannerBridge {
+    private _state;
+    private _listeners;
+    private _analyzeTimer;
+    private _tickTimer;
+    private _config;
+    private _scanner;
+    private _analyzer;
+    constructor(config?: ScannerBridgeConfig);
+    get state(): FluxState;
+    subscribe(listener: FluxStateListener): () => void;
+    private _emit;
+    private _update;
+    start(): Promise<void>;
+    stop(): FluxReport | null;
+    reset(): void;
+    setNetwork(network: string): void;
+    private _runAnalysis;
+    /**
+     * Capture a TanStack Query event. Called by FluxQueryClient wrapper.
+     */
+    captureQueryEvent(event: {
+        type: 'query-added' | 'query-updated' | 'query-removed';
+        queryKey: unknown[];
+        state?: {
+            status: string;
+            fetchStatus: string;
+            dataUpdatedAt: number;
+        };
+        options?: {
+            staleTime?: number;
+            gcTime?: number;
+            refetchInterval?: number | false;
+            enabled?: boolean;
+            retry?: number | boolean;
+        };
+    }): void;
+    /**
+     * Capture a SWR event.
+     */
+    captureSWREvent(event: {
+        type: 'swr-request' | 'swr-success' | 'swr-error';
+        key: string;
+        config?: {
+            refreshInterval?: number;
+            dedupingInterval?: number;
+            revalidateOnFocus?: boolean;
+            errorRetryCount?: number;
+        };
+    }): void;
+    destroy(): void;
+}
+declare function getGlobalBridge(config?: ScannerBridgeConfig): ScannerBridge;
+declare function resetGlobalBridge(): void;
+
+interface FluxDevToolsProps {
+    /**
+     * Position of the floating badge.
+     * @default 'bottom-right'
+     */
+    position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+    /**
+     * Network profile for scoring.
+     * @default 'wifi'
+     */
+    network?: string;
+    /**
+     * Re-analysis interval in ms.
+     * @default 3000
+     */
+    analysisInterval?: number;
+    /**
+     * Auto-start scanning when component mounts.
+     * @default true
+     */
+    autoStart?: boolean;
+    /**
+     * Start with panel expanded.
+     * @default false
+     */
+    defaultOpen?: boolean;
+    /**
+     * Console logging for debug.
+     * @default false
+     */
+    verbose?: boolean;
+    /**
+     * Custom scanner bridge (for shared state with other components).
+     */
+    bridge?: ScannerBridge;
+    /**
+     * Force show even in production. By default, only renders in development.
+     * @default false
+     */
+    forceShow?: boolean;
+    /**
+     * Keyboard shortcut to toggle panel. Set to null to disable.
+     * @default 'ctrl+shift+f'
+     */
+    shortcut?: string | null;
+}
+declare function FluxDevTools({ position, network, analysisInterval, autoStart, defaultOpen, verbose, bridge, forceShow, shortcut, }: FluxDevToolsProps): react_jsx_runtime.JSX.Element | null;
+
+interface FluxContextValue {
+    bridge: ScannerBridge;
+    state: FluxState;
+}
+interface FluxProviderProps {
+    children: ReactNode;
+    /** Network profile for scoring */
+    network?: string;
+    /** Re-analysis interval in ms (default: 3000) */
+    analysisInterval?: number;
+    /** Auto-start scanning on mount (default: true) */
+    autoStart?: boolean;
+    /** Console logging */
+    verbose?: boolean;
+    /** Custom scanner bridge instance */
+    bridge?: ScannerBridge;
+}
+declare function FluxProvider({ children, network, analysisInterval, autoStart, verbose, bridge: customBridge, }: FluxProviderProps): react_jsx_runtime.JSX.Element;
+declare function useFlux(): FluxContextValue;
+declare function useFluxBridge(): ScannerBridge;
+declare function useFluxState(): FluxState;
+
+interface ScoreInfo {
+    overall: number;
+    grade: string;
+    efficiency: number;
+    caching: number;
+    patterns: number;
+    color: string;
+}
+declare function useFluxScore(): ScoreInfo;
+interface ViolationFilter {
+    severity?: 'critical' | 'warning' | 'info';
+    category?: 'efficiency' | 'caching' | 'patterns';
+    ruleId?: string;
+}
+declare function useFluxViolations(filter?: ViolationFilter): RuleViolation[];
+interface RequestFilter {
+    type?: 'api-rest' | 'api-graphql' | 'static' | 'document';
+    method?: string;
+    minDuration?: number;
+}
+declare function useFluxRequests(filter?: RequestFilter): FluxRequestRecord[];
+declare function useFluxReport(): FluxReport | null;
+declare function useFluxScanning(): {
+    scanning: boolean;
+    elapsed: number;
+    requestCount: number;
+    start: () => void;
+    stop: () => void;
+    reset: () => void;
+};
+
+/**
+ * Wraps a TanStack QueryClient to instrument all queries for FluxAPI monitoring.
+ *
+ * Usage:
+ * ```tsx
+ * import { QueryClient } from '@tanstack/react-query';
+ * import { wrapQueryClient } from '@fluxiapi/react';
+ *
+ * const queryClient = wrapQueryClient(new QueryClient({
+ *   defaultOptions: { queries: { staleTime: 30_000 } },
+ * }));
+ * ```
+ */
+declare function wrapQueryClient<T extends object>(queryClient: T, bridge?: ScannerBridge): T;
+interface QueryMetrics {
+    /** Total unique query keys seen */
+    uniqueQueries: number;
+    /** Queries without staleTime configured */
+    queriesWithoutStaleTime: number;
+    /** Queries with refetchInterval (polling) */
+    pollingQueries: number;
+    /** Queries with retry disabled */
+    noRetryQueries: number;
+    /** Average staleTime across queries */
+    avgStaleTime: number;
+}
+/**
+ * Extracts TanStack Query-specific metrics from the current scan report.
+ * Call this after getting a report to see query-level insights.
+ */
+declare function extractQueryMetrics(queryClient: any): QueryMetrics;
+
+type SWRKey = string | unknown[] | null | undefined | (() => string | unknown[] | null);
+interface SWRConfig {
+    refreshInterval?: number;
+    dedupingInterval?: number;
+    revalidateOnFocus?: boolean;
+    revalidateOnReconnect?: boolean;
+    errorRetryCount?: number;
+    [key: string]: unknown;
+}
+type SWRHook = (useSWRNext: any) => (key: SWRKey, fetcher: any, config: SWRConfig) => any;
+/**
+ * SWR middleware that instruments all SWR hooks for FluxAPI monitoring.
+ *
+ * Usage:
+ * ```tsx
+ * import { SWRConfig } from 'swr';
+ * import { fluxSWRMiddleware } from '@fluxiapi/react';
+ *
+ * function App() {
+ *   return (
+ *     <SWRConfig value={{ use: [fluxSWRMiddleware] }}>
+ *       <MyApp />
+ *     </SWRConfig>
+ *   );
+ * }
+ * ```
+ */
+declare function createFluxSWRMiddleware(bridge?: ScannerBridge): SWRHook;
+declare const fluxSWRMiddleware: SWRHook;
+interface SWRMetrics {
+    /** Number of unique SWR keys */
+    totalKeys: number;
+    /** Keys with refreshInterval (polling) */
+    pollingKeys: number;
+    /** Keys with revalidateOnFocus enabled */
+    revalidateOnFocusKeys: number;
+    /** Keys with errorRetryCount = 0 */
+    noRetryKeys: number;
+    /** Average deduping interval */
+    avgDedupingInterval: number;
+}
+
+export { FluxDevTools, type FluxDevToolsProps, FluxProvider, type FluxProviderProps, type FluxState, type FluxStateListener, type QueryMetrics, type RequestFilter, type SWRMetrics, ScannerBridge, type ScannerBridgeConfig, type ScoreInfo, type ViolationFilter, createFluxSWRMiddleware, extractQueryMetrics, fluxSWRMiddleware, getGlobalBridge, resetGlobalBridge, useFlux, useFluxBridge, useFluxReport, useFluxRequests, useFluxScanning, useFluxScore, useFluxState, useFluxViolations, wrapQueryClient };