@hakam-aldeen-kh/blix 0.3.2

package/dist/chunk-OQHKPRNI.js

@@ -0,0 +1,287 @@
+import {
+  MONITOR_ENABLED,
+  PERSIST_MAX_ENTRY_BYTES,
+  configureDbName,
+  estimateBytes,
+  getOwner,
+  networkMonitor,
+  now,
+  serializeBody,
+  serializeHeaders,
+  truncateForPersist
+} from "./chunk-MRTSIXR7.js";
+
+// src/capture/monitorStamp.ts
+var MONITOR_ID = /* @__PURE__ */ Symbol.for("blix.monitorId");
+var stampFallback = /* @__PURE__ */ new WeakMap();
+function stampMonitorId(config, id) {
+  try {
+    Object.defineProperty(config, MONITOR_ID, {
+      value: id,
+      enumerable: false,
+      writable: true,
+      configurable: true
+    });
+  } catch (e) {
+    stampFallback.set(config, id);
+  }
+}
+function readMonitorId(config) {
+  if (config === null || typeof config !== "object") return void 0;
+  const stamped = config;
+  const direct = stamped[MONITOR_ID];
+  if (typeof direct === "string") return direct;
+  if (typeof stamped.__monitorId === "string") return stamped.__monitorId;
+  return stampFallback.get(config);
+}
+
+// src/capture/attachHttp.ts
+function attachHttpMonitor(instance, options) {
+  if (!MONITOR_ENABLED) return;
+  if (options == null ? void 0 : options.dbName) configureDbName(options.dbName);
+  instance.interceptors.request.use((config) => {
+    var _a, _b;
+    if (networkMonitor.isPaused) return config;
+    try {
+      const id = networkMonitor.nextId();
+      const monitored = config;
+      monitored.__monitorId = id;
+      stampMonitorId(config, id);
+      const hadFormData = typeof FormData !== "undefined" && config.data instanceof FormData;
+      const requestPayload = serializeBody(config.data);
+      const owner = getOwner();
+      networkMonitor.start({
+        id,
+        method: ((_a = config.method) != null ? _a : "post").toUpperCase(),
+        url: (_b = config.url) != null ? _b : "",
+        baseURL: config.baseURL,
+        at: Date.now(),
+        startTime: now(),
+        requestPayload,
+        requestHeaders: serializeHeaders(config.headers),
+        sizeBytes: estimateBytes(requestPayload),
+        skipEncryption: monitored.skipEncryption === true,
+        hadFormData,
+        replayOf: monitored.__monitorReplayOf,
+        initiator: monitored.__monitorInitiator,
+        ownerId: owner == null ? void 0 : owner.id,
+        initiatorKind: owner == null ? void 0 : owner.kind
+      });
+      if (owner) networkMonitor.linkChild(owner.id, id);
+    } catch (e) {
+    }
+    return config;
+  });
+  instance.interceptors.response.use(
+    (response) => {
+      const id = response.config.__monitorId;
+      if (!id) return response;
+      try {
+        const payload = response.data;
+        networkMonitor.update(id, {
+          state: "success",
+          status: response.status,
+          endTime: now(),
+          responsePayload: payload,
+          responseHeaders: serializeHeaders(response.headers),
+          sizeBytes: estimateBytes(payload)
+        });
+      } catch (e) {
+      }
+      return response;
+    },
+    (error) => {
+      var _a, _b, _c, _d, _e;
+      const id = (_a = error.config) == null ? void 0 : _a.__monitorId;
+      if (id) {
+        try {
+          const payload = (_c = (_b = error.response) == null ? void 0 : _b.data) != null ? _c : error.message;
+          networkMonitor.update(id, {
+            state: "error",
+            status: (_d = error.response) == null ? void 0 : _d.status,
+            endTime: now(),
+            error: payload,
+            responseHeaders: serializeHeaders((_e = error.response) == null ? void 0 : _e.headers),
+            sizeBytes: estimateBytes(payload)
+          });
+        } catch (e) {
+        }
+      }
+      return Promise.reject(error);
+    }
+  );
+}
+
+// src/capture/captureEncrypted.ts
+var MAX_ENCRYPTED_BYTES = PERSIST_MAX_ENTRY_BYTES;
+var BINARY_PREVIEW_BYTES = 512;
+var HEX = "0123456789abcdef";
+function toBytes(value) {
+  if (typeof ArrayBuffer === "undefined") return null;
+  if (value instanceof ArrayBuffer) return new Uint8Array(value);
+  if (ArrayBuffer.isView(value)) {
+    return new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+  }
+  return null;
+}
+function labelOf(value) {
+  var _a;
+  const name = (_a = value.constructor) == null ? void 0 : _a.name;
+  return typeof name === "string" && name.length > 0 ? name : "BufferSource";
+}
+function binaryPreview(bytes, label) {
+  const limit = Math.min(bytes.length, BINARY_PREVIEW_BYTES);
+  let head = "";
+  for (let i = 0; i < limit; i += 1) {
+    const byte = bytes[i];
+    head += HEX[byte >> 4] + HEX[byte & 15];
+  }
+  return {
+    __blixBinary: label,
+    byteLength: bytes.length,
+    head,
+    truncated: bytes.length > limit
+  };
+}
+function normalize(value) {
+  const bytes = toBytes(value);
+  if (bytes) return binaryPreview(bytes, labelOf(value));
+  return truncateForPersist(serializeBody(value), MAX_ENCRYPTED_BYTES).value;
+}
+function captureEncrypted(config, payload) {
+  if (!MONITOR_ENABLED) return;
+  try {
+    const id = readMonitorId(config);
+    if (!id) return;
+    if (!payload) return;
+    const patch = {};
+    if (payload.request != null) patch.encryptedRequest = normalize(payload.request);
+    if (payload.response != null) patch.encryptedResponse = normalize(payload.response);
+    if (patch.encryptedRequest === void 0 && patch.encryptedResponse === void 0) {
+      return;
+    }
+    networkMonitor.update(id, patch);
+  } catch (e) {
+  }
+}
+
+// src/capture/realtimeCapture.ts
+var frameCounter = 0;
+function makeFrame(direction, event, data) {
+  frameCounter += 1;
+  return {
+    id: `f${frameCounter}`,
+    at: Date.now(),
+    direction,
+    event,
+    data,
+    sizeBytes: estimateBytes(data)
+  };
+}
+function tapRealtimeAdapter(adapter, transport) {
+  if (!MONITOR_ENABLED) return adapter;
+  let connectionId = null;
+  const frame = (direction, event, data) => {
+    if (!connectionId) return;
+    try {
+      networkMonitor.appendFrame(connectionId, makeFrame(direction, event, data));
+    } catch (e) {
+    }
+  };
+  const openConnection = (url) => {
+    try {
+      const id = networkMonitor.nextId();
+      connectionId = id;
+      const startTime = now();
+      networkMonitor.start({
+        id,
+        kind: "ws",
+        transport,
+        method: "WS",
+        // Strip the token from the query string — it is a credential, and the
+        // panel already masks the equivalent HTTP header.
+        url: redactUrl(url),
+        at: Date.now(),
+        startTime,
+        // A connection has no response body; size accrues from its frames.
+        sizeBytes: 0,
+        frames: []
+      });
+      return id;
+    } catch (e) {
+      connectionId = null;
+      return null;
+    }
+  };
+  const closeConnection = (state, reason) => {
+    if (!connectionId) return;
+    try {
+      networkMonitor.update(connectionId, {
+        state,
+        endTime: now(),
+        responsePayload: { closed: reason != null ? reason : "disconnected" }
+      });
+    } catch (e) {
+    }
+    connectionId = null;
+  };
+  return new Proxy(adapter, {
+    get(target, prop, receiver) {
+      const value = Reflect.get(target, prop, receiver);
+      if (typeof value !== "function") return value;
+      if (prop === "connect") {
+        return (token, url) => {
+          openConnection(url);
+          frame("system", "connect", { url: redactUrl(url), transport });
+          return value.call(target, token, url);
+        };
+      }
+      if (prop === "disconnect") {
+        return () => {
+          frame("system", "disconnect", null);
+          const result = value.call(target);
+          closeConnection("success", "client disconnect");
+          return result;
+        };
+      }
+      if (prop === "subscribe") {
+        return (channelName) => {
+          frame("out", `subscribe:${channelName}`, { channel: channelName });
+          return value.call(target, channelName);
+        };
+      }
+      if (prop === "onMessage") {
+        return (cb) => value.call(target, (payload) => {
+          var _a;
+          frame("in", (_a = payload == null ? void 0 : payload.event) != null ? _a : "message", payload == null ? void 0 : payload.data);
+          cb(payload);
+        });
+      }
+      if (prop === "onPresenceUpdate") {
+        return (cb) => value.call(target, (status) => {
+          frame("system", `presence:${status}`, { status });
+          if (status === "offline") closeConnection("error", "transport offline");
+          cb(status);
+        });
+      }
+      return value.bind(target);
+    }
+  });
+}
+function redactUrl(url) {
+  try {
+    const parsed = new URL(url, "http://local");
+    for (const key of ["token", "access_token", "accessToken", "auth"]) {
+      if (parsed.searchParams.has(key)) parsed.searchParams.set(key, "\u2022\u2022\u2022");
+    }
+    return url.startsWith("/") ? parsed.pathname + parsed.search : parsed.toString();
+  } catch (e) {
+    return url.replace(/([?&](?:token|access_token|accessToken|auth)=)[^&]*/gi, "$1\u2022\u2022\u2022");
+  }
+}
+
+export {
+  attachHttpMonitor,
+  captureEncrypted,
+  tapRealtimeAdapter
+};

package/dist/chunk-PQIOIMAQ.js

@@ -0,0 +1,7 @@
+// src/ui/BlixContext.tsx
+import { createContext } from "react";
+var BlixContext = createContext({});
+
+export {
+  BlixContext
+};

package/dist/index.d.ts

@@ -0,0 +1,75 @@
+export { CacheLike, Corner, DiffOp, DockMode, EncryptedPayload, FrameDirection, InitiatorFrame, MiddlewareApiLike, MiddlewareLike, MonitorEntry, MonitorKind, MonitorPrefs, MonitorState, PersistedEntry, Pos, QueryClientLike, QueryMeta, RealtimeAdapterLike, ReduxActionMeta, ReduxCaptureOptions, Size, StateDiff, StateDiffEntry, TimingMarks, WsFrame, attachHttpMonitor, captureEncrypted, createReduxMonitorMiddleware, tapQueryClient, tapRealtimeAdapter, withInitiatorCapture } from './capture/index.js';
+import * as react from 'react';
+import 'axios';
+
+/** Structural redux-store shape — only the subset the panel actually uses.
+ * Mirrors `MiddlewareApiLike` in `reduxCapture.ts` but adds `subscribe` and
+ * `dispatch` so the State tab and Re-dispatch action can work. */
+interface StoreLike<S> {
+    getState(): S;
+    subscribe(listener: () => void): () => void;
+    dispatch(action: unknown): unknown;
+}
+/**
+ * The config Blix hands to `request()` when replaying an entry — exactly the
+ * eight fields `replayEntry` sets (`services/replayRequest.ts`), nothing more.
+ *
+ * Two deliberate choices here, both forced by making a genuine `AxiosInstance`
+ * assignable to `HttpClientLike` without a cast:
+ *
+ * 1. **`headers` is `unknown`, not `Record<string, unknown>`.** Axios types
+ *    headers as `AxiosHeaders | (Partial<RawAxiosHeaders & …> & …)`, which a
+ *    `Record<string, unknown>` is not assignable to. Since Blix only ever
+ *    *writes* this field (a flat `Record<string, string>` built from the
+ *    captured request), nothing here needs to read it back, so the widest type
+ *    that still accepts what Blix passes is the correct one.
+ *
+ * 2. **No `[key: string]: unknown` index signature.** Method parameters are
+ *    compared bivariantly, so it is enough for `AxiosRequestConfig` to be
+ *    assignable to *this* type — but an interface never satisfies a target
+ *    index signature (TypeScript only infers implicit index signatures for
+ *    object-literal types), so the index signature was what actually blocked
+ *    that direction. The three non-axios fields Blix passes are therefore
+ *    named explicitly instead of being swept up by the index signature.
+ *
+ * Declared as a `type` alias rather than an `interface` on purpose: an
+ * object-literal type gets an implicit index signature, so this stays
+ * assignable to a client whose own parameter is declared as
+ * `Record<string, unknown>` — a shape that was valid in 0.2.1 and must remain
+ * valid.
+ */
+type HttpClientRequestConfig = {
+    url?: string;
+    method?: string;
+    baseURL?: string;
+    /** Written by Blix, never read — see note 1 above. */
+    headers?: unknown;
+    data?: unknown;
+    /** Host convention: opt this request out of the encryption pipeline. */
+    skipEncryption?: boolean;
+    /** Host convention: mark as already-retried, so auth interceptors don't loop. */
+    _retry?: boolean;
+    /** Blix internal: id of the entry this replay came from. */
+    __monitorReplayOf?: string;
+};
+/**
+ * Structural axios-instance shape — `request` is the only member the panel
+ * touches (`services/replayRequest.ts:90`), so it is the only one declared.
+ *
+ * Structural on purpose: Blix does not import from axios here and does not
+ * depend on it, so any client exposing a compatible `request` works.
+ */
+interface HttpClientLike {
+    request(config: HttpClientRequestConfig): Promise<unknown>;
+}
+
+interface BlixProps {
+    store?: StoreLike<unknown>;
+    apiClient?: HttpClientLike;
+    /** IndexedDB database name. Defaults to "nm-devtools". Useful when running
+     * multiple apps on the same origin that would otherwise share a log. */
+    dbName?: string;
+}
+declare function Blix({ store, apiClient, dbName }: BlixProps): react.JSX.Element | null;
+
+export { Blix, type BlixProps };

package/dist/index.js

@@ -0,0 +1,40 @@
+"use client";
+import {
+  attachHttpMonitor,
+  captureEncrypted,
+  tapRealtimeAdapter
+} from "./chunk-OQHKPRNI.js";
+import {
+  BlixContext
+} from "./chunk-PQIOIMAQ.js";
+import {
+  configureDbName,
+  createReduxMonitorMiddleware,
+  tapQueryClient,
+  withInitiatorCapture
+} from "./chunk-MRTSIXR7.js";
+
+// src/ui/Blix.tsx
+import { lazy, Suspense, useRef } from "react";
+import { jsx } from "react/jsx-runtime";
+function Blix({ store, apiClient, dbName }) {
+  const panelRef = useRef(null);
+  if (typeof window !== "undefined" && process.env.NODE_ENV === "development") {
+    if (!panelRef.current) {
+      panelRef.current = lazy(() => import("./DevToolsPanel-GBMCZRMW.js"));
+    }
+    const Panel = panelRef.current;
+    if (dbName) configureDbName(dbName);
+    return /* @__PURE__ */ jsx(BlixContext.Provider, { value: { store, apiClient }, children: /* @__PURE__ */ jsx(Suspense, { fallback: null, children: /* @__PURE__ */ jsx(Panel, {}) }) });
+  }
+  return null;
+}
+export {
+  Blix,
+  attachHttpMonitor,
+  captureEncrypted,
+  createReduxMonitorMiddleware,
+  tapQueryClient,
+  tapRealtimeAdapter,
+  withInitiatorCapture
+};

package/package.json

@@ -0,0 +1,106 @@
+{
+  "name": "@hakam-aldeen-kh/blix",
+  "version": "0.3.2",
+  "description": "Dev-tools panel for React apps — HTTP, Redux, Query and Realtime monitoring.",
+  "keywords": [
+    "devtools",
+    "dev-tools",
+    "debug",
+    "debugging",
+    "debug-panel",
+    "devtools-panel",
+    "inspector",
+    "monitoring",
+    "observability",
+    "logging",
+    "network-inspector",
+    "http",
+    "http-logger",
+    "request-logger",
+    "api-monitor",
+    "axios",
+    "axios-interceptor",
+    "redux",
+    "redux-devtools",
+    "redux-toolkit",
+    "state-inspector",
+    "react-query",
+    "tanstack-query",
+    "query-devtools",
+    "websocket",
+    "realtime",
+    "socket",
+    "react",
+    "react-devtools",
+    "nextjs",
+    "typescript",
+    "frontend",
+    "dx",
+    "in-app-devtools"
+  ],
+  "license": "MIT",
+  "author": "Hakam aldeen Alkhadraa",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Hakam-aldeen-Kh/blix.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Hakam-aldeen-Kh/blix/issues"
+  },
+  "homepage": "https://github.com/Hakam-aldeen-Kh/blix#readme",
+  "type": "module",
+  "sideEffects": false,
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./capture": {
+      "types": "./dist/capture/index.d.ts",
+      "import": "./dist/capture/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "axios": "^1.0.0",
+    "@reduxjs/toolkit": "^2.0.0",
+    "@tanstack/react-query": "^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "axios": {
+      "optional": true
+    },
+    "@reduxjs/toolkit": {
+      "optional": true
+    },
+    "@tanstack/react-query": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit"
+  }
+}