@hakam-aldeen-kh/blix 0.3.2

package/dist/capture/index.d.ts

@@ -0,0 +1,548 @@
+import { AxiosInstance } from 'axios';
+
+/**
+ * Blix — HTTP capture entry point.
+ *
+ * Registers axios interceptors that feed the monitor store with plaintext
+ * request/response data. Call once at module-init time, before your app's
+ * encryption or auth interceptors, so this interceptor runs last in axios's
+ * LIFO request stack and therefore sees the plaintext request body.
+ *
+ * No-op when `process.env.NODE_ENV !== "development"`.
+ */
+
+/**
+ * Attaches HTTP-capture interceptors to an axios instance.
+ *
+ * Call this at module init time (e.g. at the bottom of your `axios.ts`),
+ * after registering any encryption interceptors so that the monitor sees the
+ * plaintext body first.
+ */
+declare function attachHttpMonitor(instance: AxiosInstance, options?: {
+    dbName?: string;
+}): void;
+
+/**
+ * Blix — encrypted-payload capture (opt-in).
+ *
+ * Blix cannot capture ciphertext by itself. It has no knowledge of any app's
+ * encryption scheme, and — by design — its own interceptors sit on the
+ * *plaintext* side of the pipeline, so the encrypted form simply does not exist
+ * at the moment Blix captures. This is the hand-off: the host calls
+ * `captureEncrypted` from inside its own encrypt/decrypt interceptors, where
+ * the ciphertext does exist, and passes back the same axios config object Blix
+ * already stamped.
+ *
+ * Entirely optional. An app that never calls it behaves exactly as before, and
+ * the panel hides the Encrypted tab for every entry that has nothing in it.
+ *
+ * Like the rest of the capture layer, this must never throw, never warn, and
+ * never be reachable in a production build.
+ */
+/**
+ * What the host hands over. Both sides are optional and independent: the
+ * request-side ciphertext is produced early (on the way out) and the
+ * response-side late (on the way back), so they normally arrive in two separate
+ * calls.
+ */
+interface EncryptedPayload {
+    /** What actually went on the wire, in place of `requestPayload`. */
+    request?: unknown;
+    /** What actually came back, before the host decrypted it. */
+    response?: unknown;
+}
+/**
+ * Attaches the encrypted form of a request and/or response to the entry Blix
+ * already captured for `config`.
+ *
+ * ```ts
+ * apiClient.interceptors.request.use((config) => {
+ *   const encrypted = encrypt(config.data);
+ *   captureEncrypted(config, { request: encrypted });
+ *   return { ...config, data: encrypted };
+ * });
+ * ```
+ *
+ * Correlation is by identity of the config object, never by URL or timing —
+ * two concurrent requests to the same endpoint stay correctly apart. Pass the
+ * object axios gave you; a `{ ...config }` copy made by your own interceptor
+ * also resolves (see `monitorStamp.ts`). Call it as many times as you like, in
+ * either order, before or after the response arrives; each call merges into the
+ * existing entry and refreshes the panel. It never creates an entry of its own.
+ *
+ * A silent no-op — no throw, no console output — in every failure mode:
+ * outside development, when `attachHttpMonitor` was never called, when the
+ * config carries no stamp (a retry that built a fresh config, say), and when
+ * the entry has already been evicted from the ring buffer.
+ */
+declare function captureEncrypted(config: unknown, payload: EncryptedPayload): void;
+
+/**
+ * Network monitor — Redux action capture.
+ *
+ * A structurally-typed middleware, following the same contract-restatement
+ * pattern `realtimeCapture.ts` uses for the realtime adapter: this module
+ * never imports `@reduxjs/toolkit`, so the capture layer — which the host's
+ * HTTP-client module also depends on — stays free of a dependency on the
+ * host's state-management choice. That is what lets `@reduxjs/toolkit` be an
+ * optional peer rather than a hard one.
+ *
+ * Cost per dispatch, dev-only: a handful of reference compares, plus (only
+ * when the action actually changed something) a bounded structural diff — see
+ * `stateDiff.ts`. RTK's own `immutableCheck`/`serializableCheck` dev
+ * middleware already deep-walk the *entire* state on every dispatch; this tap
+ * does strictly less work than that, and is entirely absent in production —
+ * see the pass-through returned below when `MONITOR_ENABLED` is false.
+ */
+/** The subset of a Redux store/middleware API this tap needs, restated
+ * structurally so this file never imports `redux` or `@reduxjs/toolkit`. */
+interface MiddlewareApiLike<S> {
+    getState(): S;
+}
+type NextLike = (action: unknown) => unknown;
+type MiddlewareLike<S> = (api: MiddlewareApiLike<S>) => (next: NextLike) => (action: unknown) => unknown;
+interface ReduxCaptureOptions {
+    /** Action types (exact) or `"prefix/*"` globs never captured. Merged with
+     * the built-in defaults (redux-toolkit's own init/replace actions). */
+    ignore?: readonly string[];
+    /** Consecutive dispatches of the same action type within this window fold
+     * into the existing row (`redux.batchCount`) instead of flooding the log. */
+    coalesceMs?: number;
+    /** Above this dispatch rate, capture drops to type + timing only — no
+     * diff — until the rate falls back under it. */
+    maxActionsPerSecond?: number;
+}
+/**
+ * Builds the Redux-capture middleware. Returns a pure pass-through when the
+ * monitor is disabled (production, or SSR), so the `.concat()` call at the
+ * host's store setup costs nothing at runtime outside development.
+ */
+declare function createReduxMonitorMiddleware<S>(options?: ReduxCaptureOptions): MiddlewareLike<S>;
+
+/**
+ * Network monitor — TanStack Query cache capture.
+ *
+ * Structurally typed against the cache-event shape, exactly like
+ * `realtimeCapture.ts` restates the realtime adapter contract: this module
+ * never imports `@tanstack/react-query`, so the capture layer — which the
+ * host's HTTP-client module also depends on — stays free of a dependency on
+ * the host's data-fetching library. That is what lets `@tanstack/react-query`
+ * be an optional peer rather than a hard one.
+ *
+ * One entry per `queryHash` (or `mutationId`), accumulating lifecycle frames —
+ * the same "one long-lived row" model `realtimeCapture.ts` uses for a socket
+ * connection. Under an aggressive `gcTime` a query is added to and removed
+ * from the cache repeatedly; hashing by key means the *same row* accumulates
+ * that whole session's history instead of flickering in and out of the log —
+ * and turns that churn into the panel's most useful signal: a row can show
+ * "fetched 7 times this session, 5 of them cache misses".
+ *
+ * The Query section is backed entirely by this module's own capture, never by
+ * a live read of `queryCache.getAll()` — under `gcTime: 0` that read is empty
+ * almost all the time, which is the whole reason this capture exists.
+ */
+/** Structural subset of a TanStack Query `Query` this tap needs. */
+interface QueryStateLike {
+    status: string;
+    fetchStatus?: string;
+    data?: unknown;
+    error?: unknown;
+    dataUpdatedAt?: number;
+    errorUpdatedAt?: number;
+    fetchFailureCount?: number;
+    isInvalidated?: boolean;
+}
+interface QueryLike {
+    queryHash: string;
+    queryKey: readonly unknown[];
+    state: QueryStateLike;
+    getObserversCount?(): number;
+}
+interface MutationStateLike {
+    status: string;
+    variables?: unknown;
+    data?: unknown;
+    error?: unknown;
+}
+interface MutationLike {
+    mutationId: number;
+    state: MutationStateLike;
+}
+interface CacheEventLike {
+    type: string;
+    query?: QueryLike;
+    mutation?: MutationLike;
+    action?: {
+        type: string;
+    };
+}
+interface CacheLike {
+    subscribe(listener: (event: CacheEventLike) => void): () => void;
+    getAll(): unknown[];
+}
+/** A TanStack `QueryFilters`-shaped filter — structurally typed, same as
+ * everything else in this module, so this file still never imports
+ * `@tanstack/react-query`. */
+interface QueryFilterLike {
+    queryKey?: readonly unknown[];
+    exact?: boolean;
+}
+interface QueryClientLike {
+    getQueryCache(): CacheLike;
+    getMutationCache(): CacheLike;
+    invalidateQueries(filters?: QueryFilterLike): Promise<void>;
+    refetchQueries(filters?: QueryFilterLike): Promise<void>;
+    removeQueries(filters?: QueryFilterLike): void;
+    resetQueries(filters?: QueryFilterLike): Promise<void>;
+}
+/**
+ * Installs the tap on a `QueryClient`. Idempotent, and safe to call from a
+ * React effect in your query provider rather than the `useState` initializer
+ * that creates the client — React Strict Mode double-invokes initializers, and
+ * tapping there would tap a client that gets discarded.
+ *
+ * Because parent effects run *after* child effects, a child's `useQuery` has
+ * already fired by the time this installs — so it backfills from
+ * `getQueryCache().getAll()` first, rather than starting blind.
+ */
+declare function tapQueryClient(client: QueryClientLike): () => void;
+
+/**
+ * Network monitor — shared types.
+ *
+ * `MonitorEntry` is both the in-memory shape and (minus a few live-only fields)
+ * the persisted shape. Anything added here that should survive a reload must
+ * also be JSON-serializable.
+ */
+type MonitorState = "pending" | "success" | "error" | "aborted";
+/**
+ * HTTP requests, realtime connections, Redux actions and TanStack Query
+ * activity all share one table.
+ *
+ * A WebSocket connection is modelled as a single long-lived entry that
+ * accumulates frames — the same shape Chrome uses, where the connection is a
+ * row and its traffic lives in a Messages tab. Modelling each frame as its own
+ * row would drown the HTTP requests. A Query cache entry reuses that exact
+ * model: one row per `queryHash`/`mutationId`, accumulating lifecycle frames
+ * (fetch → success/error → invalidate → removed) — because under an aggressive
+ * `gcTime` the same key is added to and removed from the cache repeatedly, and
+ * hashing by key lets one row carry that whole session's history instead of
+ * flickering in and out of the log.
+ *
+ * A Redux action, by contrast, gets its own row per dispatch: the detail pane,
+ * selection, pinning and search are all entry-keyed, and a per-action diff
+ * needs a first-class row rather than a frame buried inside one.
+ */
+type MonitorKind = "http" | "ws" | "redux" | "query";
+type FrameDirection = "in" | "out" | "system";
+interface WsFrame {
+    id: string;
+    at: number;
+    direction: FrameDirection;
+    /** Event/channel name where the transport provides one. */
+    event: string;
+    data: unknown;
+    /** Approximate size, estimated once at capture. */
+    sizeBytes: number;
+}
+/**
+ * Where a request's wall-clock time actually went.
+ *
+ * Worth breaking out when the host transforms bodies in its interceptors —
+ * encryption, compression, heavy serialization — because "slow request" then
+ * means a slow backend *or* a slow client-side pipeline, and the two need
+ * telling apart.
+ */
+interface TimingMarks {
+    encryptMs?: number;
+    networkMs?: number;
+    decryptMs?: number;
+}
+/** One frame of a captured call stack, already trimmed and made repo-relative. */
+interface InitiatorFrame {
+    /** Function or component name, when V8 gave us one. */
+    fn?: string;
+    /** Repo-relative path, e.g. `src/hooks/useCheckoutForm.ts`. */
+    file: string;
+    line?: number;
+    col?: number;
+}
+type DiffOp = "add" | "change" | "remove";
+/** One changed path from a bounded structural diff — see `stateDiff.ts`. */
+interface StateDiffEntry {
+    /** Dotted/bracketed path, e.g. `conversations.allConversations[3].unreadCount`. */
+    path: string;
+    op: DiffOp;
+    /** Bounded, truncated *copies* — never a reference into live state. */
+    before?: unknown;
+    after?: unknown;
+}
+interface StateDiff {
+    changes: StateDiffEntry[];
+    /** Hit a depth/node/change ceiling — the diff is a partial picture. */
+    truncated: boolean;
+    /** Top-level slices touched by this action. */
+    slices: string[];
+}
+/** Redux only: the dispatched action and what it changed. */
+interface ReduxActionMeta {
+    /** `action.type`, mirrored into `entry.url` so free-text search works free. */
+    type: string;
+    /** Bounded copy of `action.payload` + `action.meta`. */
+    payload?: unknown;
+    /** RTK rejected-thunk marker (`action.error === true`). */
+    isError?: boolean;
+    diff?: StateDiff;
+    /** Wall time spent inside `next(action)`. */
+    reducerMs: number;
+    /** >1 when identical consecutive actions were coalesced into this row. */
+    batchCount?: number;
+    /** False when the captured payload was truncated — re-dispatching it would
+     * not faithfully reproduce the original action, so the panel's Re-dispatch
+     * action is disabled. */
+    replayable?: boolean;
+}
+/** Query/mutation only: the cache row's current lifecycle state. Deliberately
+ * not folded into `MonitorState` — `MonitorState` drives the shared state
+ * filter and waterfall colour, and pending/success/error covers this fine;
+ * the richer status (fresh/stale/fetching/removed) lives here instead. */
+interface QueryMeta {
+    sub: "query" | "mutation";
+    /** `query.queryHash` / `String(mutation.mutationId)` — the entry's stable
+     * identity, and the correlation handle from an HTTP entry's `ownerId`. */
+    hash: string;
+    key: unknown[];
+    status: "pending" | "success" | "error";
+    fetchStatus?: "fetching" | "paused" | "idle";
+    observers: number;
+    isInvalidated?: boolean;
+    dataUpdatedAt?: number;
+    errorUpdatedAt?: number;
+    failureCount?: number;
+    /** The query left the cache — routine under an aggressive `gcTime`, and
+     * exactly the fact this panel exists to make visible. */
+    gcRemoved?: boolean;
+    /** How many times this key has been fetched this session. */
+    fetchCount?: number;
+    /** Ids of the HTTP entries this query/mutation caused — best-effort, see
+     * `monitorContext.ts`. */
+    causedIds?: string[];
+}
+interface MonitorEntry {
+    id: string;
+    /** HTTP request or realtime connection. Defaults to `"http"` when absent, so
+     * entries persisted before realtime capture existed still load. */
+    kind?: MonitorKind;
+    /** Monotonic capture order. `id` embeds `Date.now()` and is unique but not
+     * order-comparable; `seq` is what sorting and oldest-first eviction use. */
+    seq: number;
+    /** Bumped on every `update()`. Lets the deep-search index cache tell whether
+     * an entry actually changed without stringifying it. */
+    rev: number;
+    method: string;
+    url: string;
+    baseURL?: string;
+    /** Wall-clock epoch ms when the request started (for display). */
+    at: number;
+    /** `performance.now()` at start, used to compute duration. */
+    startTime: number;
+    endTime?: number;
+    durationMs?: number;
+    /** `performance.timeOrigin` of the page load that captured this entry. */
+    timeOrigin: number;
+    /**
+     * Start/end as absolute epoch ms (`timeOrigin + startTime`).
+     *
+     * The waterfall must use these, never `startTime`/`endTime`: those are
+     * relative to a per-page-load origin, so a persisted entry's `startTime` is
+     * meaningless against the current load's.
+     */
+    startAbs: number;
+    endAbs?: number;
+    /** Which page load captured this. Drives the divider rows and the per-load
+     * waterfall timeline. */
+    loadId: string;
+    status?: number;
+    state: MonitorState;
+    /** Plaintext request body, before encryption. */
+    requestPayload?: unknown;
+    /** What is actually sent over the wire (encData / aesKey). */
+    encryptedRequest?: unknown;
+    /** Decrypted response body. */
+    responsePayload?: unknown;
+    /** Raw encrypted response body from the server. */
+    encryptedResponse?: unknown;
+    /** Decrypted/raw error payload, when the request failed. */
+    error?: unknown;
+    /** Outgoing request headers (sanitized to a flat string map). */
+    requestHeaders?: Record<string, string>;
+    /** Response headers returned by the server. */
+    responseHeaders?: Record<string, string>;
+    /** Approximate payload size in bytes, estimated once at capture. Computing
+     * this lazily in the detail pane meant a full `JSON.stringify` per render. */
+    sizeBytes?: number;
+    /** Whether the request opted out of the encryption pipeline. Needed to replay
+     * a request faithfully — it's a config flag, not a header, so it isn't
+     * recoverable from `requestHeaders`. */
+    skipEncryption?: boolean;
+    /** Whether the body was `FormData`. Such requests can't be replayed: file
+     * contents are summarized, not captured. */
+    hadFormData?: boolean;
+    /** Set when this entry is a replay of another; holds the parent's id. */
+    replayOf?: string;
+    /** How many replays this entry has spawned. */
+    replayCount?: number;
+    /** Trimmed call stack captured at the call site. */
+    initiator?: InitiatorFrame[];
+    /** Where the time went — encryption vs. network vs. decryption. */
+    marks?: TimingMarks;
+    /**
+     * Pinned entries survive Clear and buffer eviction, so a reference response
+     * can be held on screen while reproducing an issue.
+     */
+    pinned?: boolean;
+    /** Realtime/Query only: frames/lifecycle events on this connection or key. */
+    frames?: WsFrame[];
+    /** Realtime only: transport name, shown in the Method column. */
+    transport?: string;
+    /** Redux only: the dispatched action and its bounded diff. */
+    redux?: ReduxActionMeta;
+    /** Query only: the cache row's key, status and observer count. */
+    query?: QueryMeta;
+    /** HTTP only: id of the query/mutation entry that caused this request,
+     * when it could be determined — see `monitorContext.ts`. Absence means
+     * "unknown", never "not caused by a query". */
+    ownerId?: string;
+    /** HTTP only: whether the raw call stack (before NOISE-filtering) passed
+     * through `@tanstack/query`, independent of whether `ownerId` resolved. */
+    initiatorKind?: "query" | "mutation" | "direct";
+}
+/** Shape written to IndexedDB. Payloads may be truncated relative to the live
+ * entry; `bytes` is what the storage budget accounts against. */
+interface PersistedEntry extends MonitorEntry {
+    schema: number;
+    bytes: number;
+}
+type DockMode = "bottom" | "right" | "float";
+type Corner = "bottom-left" | "bottom-right" | "top-left" | "top-right";
+interface Size {
+    w: number;
+    h: number;
+}
+interface Pos {
+    x: number;
+    y: number;
+}
+/**
+ * Everything the panel remembers between sessions.
+ *
+ * Stored in IndexedDB (`meta.prefs`) as the source of truth, mirrored into
+ * `localStorage["nm:prefs"]` purely as a synchronous read cache so the panel
+ * can restore its geometry without a frame of flash. The mirror is expendable —
+ * any host that clears web storage wipes it, and the IndexedDB copy silently
+ * restores it on next boot.
+ */
+interface MonitorPrefs {
+    /** Bumped on every write; used to reconcile the two copies. */
+    rev: number;
+    mode: DockMode;
+    /** Dock sizes, per axis. Sharing one value across docks yields absurd
+     * geometry when switching. */
+    bottomH: number;
+    rightW: number;
+    float: {
+        pos: Pos | null;
+        size: Size;
+        maximized: boolean;
+    };
+    /** List/detail splitter, one per split axis. */
+    splitW: number;
+    splitH: number;
+    corner: Corner;
+    preserveLog: boolean;
+    deepSearch: boolean;
+    followLatest: boolean;
+    /** Opt out of call-stack capture when profiling a large burst of requests. */
+    captureInitiator: boolean;
+    /** Last pinned request; restored only if the id still resolves. */
+    selectedId: string | null;
+    /** Active top-level section — `"network"` (HTTP) or `"realtime"` (sockets). */
+    section: string;
+    /** Row height preset: compact | normal | comfy. */
+    density: string;
+    /** User-resized column widths, in px, keyed by column id. */
+    columnWidths: Record<string, number>;
+}
+
+/**
+ * Network monitor — realtime (WebSocket / ActionCable) capture.
+ *
+ * Realtime traffic routed through an adapter is typically invisible: the
+ * browser's own Network tab shows the socket but not the decoded envelope, and
+ * an app's own logging goes to the console where it is drowned by everything
+ * else.
+ *
+ * ## Shape of the capture
+ *
+ * A connection is one long-lived `MonitorEntry` (`kind: "ws"`) that accumulates
+ * frames, rather than one entry per frame. That is how Chrome models it — the
+ * connection is a row, its traffic lives in a Messages tab — and it stops a
+ * chatty channel from burying every HTTP request in the table.
+ *
+ * ## Why a structural adapter type
+ *
+ * The host's adapter interface lives in the host, and this package must not
+ * import from it. The adapter shape is therefore restated structurally here,
+ * so the tap stays a one-line change at the call site with no dependency
+ * pointing the wrong way — any object with the right methods satisfies it.
+ */
+
+/** The subset of the realtime adapter contract this tap needs. */
+interface RealtimeAdapterLike {
+    connect(token: string, url: string): void;
+    disconnect(): void;
+    subscribe(channelName: string): void;
+    onMessage(callback: (payload: {
+        event: string;
+        data: unknown;
+    }) => void): void;
+    onPresenceUpdate(callback: (status: string) => void): void;
+}
+/**
+ * Wraps a realtime adapter so its lifecycle and traffic appear in the monitor.
+ *
+ * Returns the adapter untouched in production, where `MONITOR_ENABLED` is a
+ * constant `false` and the whole wrapper folds away.
+ */
+declare function tapRealtimeAdapter<T extends RealtimeAdapterLike>(adapter: T, transport: string): T;
+
+/**
+ * Network monitor — "who fired this request?"
+ *
+ * ## Why the stack is taken at the call site, not in the interceptor
+ *
+ * By the time the axios request interceptor runs, we are already inside axios's
+ * promise chain: the interceptor callback executes in a microtask, so
+ * `new Error().stack` taken there is `at Object.onFulfilled (axios)` plus a
+ * microtask boundary. V8's async stack traces sometimes recover the real
+ * caller, but not reliably, and never through React Query's internals.
+ *
+ * So `withInitiatorCapture` wraps the axios instance, takes the stack
+ * synchronously in the caller's own frame, and stashes it on the config for
+ * `beginMonitor` to read.
+ *
+ * The whole module is behind a statically-foldable `NODE_ENV` check at its call
+ * site, so it is dead-code-eliminated from production builds.
+ */
+
+/**
+ * Wraps the axios instance so every call site records its own stack.
+ *
+ * Wraps the callable form (`apiClient(config)`), plus `request`, `get`, `post`,
+ * `put`, `patch`, `delete` and `head`. Other entry points (`options`, the
+ * `*Form` helpers) pass through unwrapped — requests made through them are
+ * still captured, they just carry no initiator stack.
+ */
+declare function withInitiatorCapture(instance: AxiosInstance): AxiosInstance;
+
+export { type CacheLike, type Corner, type DiffOp, type DockMode, type EncryptedPayload, type FrameDirection, type InitiatorFrame, type MiddlewareApiLike, type MiddlewareLike, type MonitorEntry, type MonitorKind, type MonitorPrefs, type MonitorState, type PersistedEntry, type Pos, type QueryClientLike, type QueryMeta, type RealtimeAdapterLike, type ReduxActionMeta, type ReduxCaptureOptions, type Size, type StateDiff, type StateDiffEntry, type TimingMarks, type WsFrame, attachHttpMonitor, captureEncrypted, createReduxMonitorMiddleware, tapQueryClient, tapRealtimeAdapter, withInitiatorCapture };

package/dist/capture/index.js

@@ -0,0 +1,18 @@
+import {
+  attachHttpMonitor,
+  captureEncrypted,
+  tapRealtimeAdapter
+} from "../chunk-OQHKPRNI.js";
+import {
+  createReduxMonitorMiddleware,
+  tapQueryClient,
+  withInitiatorCapture
+} from "../chunk-MRTSIXR7.js";
+export {
+  attachHttpMonitor,
+  captureEncrypted,
+  createReduxMonitorMiddleware,
+  tapQueryClient,
+  tapRealtimeAdapter,
+  withInitiatorCapture
+};