@fluxiapi/react 0.3.0

package/dist/index.d.ts

@@ -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 };