hrpc-inspector 0.1.0 → 0.1.1

package/dist/detect.d.ts

@@ -0,0 +1,10 @@
+export type Runtime = 'pear' | 'bare' | 'react-native' | 'electron' | 'node' | 'browser' | 'unknown';
+export interface RuntimeInfo {
+    runtime: Runtime;
+    /** Bare is available (Pear, plain Bare, or an RN bare-kit worklet) → hyperswarm can run in-process. */
+    isBareRuntime: boolean;
+    /** A browser/RN JS context where we must export over a bridge, not a socket. */
+    isBridgeOnly: boolean;
+}
+/** Pure and injectable (pass a fake global in tests). Order matters: most specific first. */
+export declare function detectRuntime(env?: any): RuntimeInfo;

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+export { observe, DEFAULT_TOPIC } from './observe.js';
+export type { ObserveOptions, ObserveHandle } from './observe.js';
+export { detectRuntime } from './detect.js';
+export type { Runtime, RuntimeInfo } from './detect.js';
+export { wrapClient } from './wrap-client.js';
+export type { Report, WrapClientOptions } from './wrap-client.js';
+export { createWebSocketReporter } from './reporters.js';
+export type { Reporter, WebSocketReporterOptions } from './reporters.js';
+export { instrumentDataChannel, instrumentPeerConnection, } from 'hrpc-inspector-probe/adapters/webrtc';
+export { instrumentWebSocket } from 'hrpc-inspector-probe/adapters/websocket';
+export { instrumentHyperswarmStream } from 'hrpc-inspector-probe/adapters/hyperswarm';
+export { CollectorSink } from 'hrpc-inspector-probe/core/sink';
+export { BatchFlusher } from 'hrpc-inspector-probe/flush';
+export { createHyperswarmExporter } from 'hrpc-inspector-probe/exporters/hyperswarm';
+export { StreamFramer, encodeFrame } from 'hrpc-inspector-probe/transport/framing';
+export type { EventSink, L2Event, L2EventType } from 'hrpc-inspector-probe/sink';

package/dist/index.js

@@ -247,7 +247,8 @@ async function autoSwarm(topic, onConnection) {
   const Hyperswarm = (await import("hyperswarm")).default;
   const crypto = (await import("hypercore-crypto")).default;
   const swarm = new Hyperswarm();
-  const topicKey = crypto.hash(Buffer.from(topic));
+  const enc = new TextEncoder();
+  const topicKey = crypto.hash(enc.encode(topic));
   swarm.on("connection", (conn) => onConnection(conn));
   await swarm.join(topicKey, { client: true, server: false }).flushed();
 }

package/dist/observe.d.ts

@@ -0,0 +1,119 @@
+import { BatchFlusher } from 'hrpc-inspector-probe/flush';
+import type { WritableStreamLike, HyperswarmExporter } from 'hrpc-inspector-probe/exporters/hyperswarm';
+import { Redactor } from 'hrpc-inspector-probe/redactor';
+import type { EventSink, L2Event } from 'hrpc-inspector-probe/sink';
+import type { Runtime } from './detect.js';
+import type { Report, WrapClientOptions } from './wrap-client.js';
+export declare const DEFAULT_TOPIC = "p2p-observability-hub:v0";
+export interface SourceInfo {
+    /** Stable id used to group/select this source in the GUI. */
+    id: string;
+    /** Human label shown in the selector. */
+    label: string;
+    /** Detected runtime (react-native | pear | bare | electron | node | browser). */
+    runtime: string;
+    /** Physical device id (client-supplied; e.g. an app's own options.deviceId). Lets the GUI select by device. */
+    deviceId?: string;
+    /** App / install instance id — distinguishes MULTIPLE apps sharing one package. */
+    appId?: string;
+    [extra: string]: unknown;
+}
+export interface ObserveOptions {
+    /** Flush cadence; must be in the collector's verified 100-250ms window. Default 200. */
+    intervalMs?: number;
+    /** Explicit hub connection (a NoiseSecretStream / socket). Skips auto-swarm. */
+    stream?: WritableStreamLike;
+    /** Fully custom exporter (e.g. Rozenite bridge, OTLP). Skips everything else. */
+    exporter?: HyperswarmExporter;
+    /** Hub topic string; must match the hub's. Default DEFAULT_TOPIC. */
+    topic?: string;
+    /** Set false to disable Bare/Pear auto-dial (then attach() a stream yourself). */
+    autoSwarm?: boolean;
+    /**
+     * Send events to a local GUI over WebSocket instead of the Hyperswarm hub — the reliable
+     * dev-viewer path for EVERY runtime (RN / Pear / desktop / browser),
+     * e.g. 'ws://127.0.0.1:9420/ws'. When set, redaction defaults OFF (local viewing);
+     * pass redact:true to force it. Takes precedence over stream/auto-swarm.
+     */
+    websocket?: string;
+    /**
+     * Redact every event on the way OUT (peer ids hashed, URLs host-only, bodies off)
+     * — ON by default, because the export path (hub / .p2plog) leaves the device.
+     * Set false ONLY for a purely-local view that never leaves the machine (F3/F4/F9).
+     */
+    redact?: boolean;
+    /** Supply a shared Redactor (e.g. to reuse its local peer reverse-map). Default: a fresh one. */
+    redactor?: Redactor;
+    /** Per-`method` opt-in allowlist for full payload bodies (default: none — bodies summarised). */
+    bodyAllowlist?: Iterable<string>;
+    /**
+     * Identity of THIS device/app, for the GUI's device & app selectors. A string label, or an
+     * object `{ id?, label?, deviceId?, appId?, app?, device?, variant? }`.
+     *   • deviceId — physical device (client-supplied; e.g. the app's own options.deviceId) → select by device
+     *   • appId    — app/install instance → distinguishes MULTIPLE apps sharing one package
+     * Omit → auto: browser reuses localStorage for a stable id (clears on delete-data); other
+     * runtimes get a session id (pass deviceId/appId for stability). Only the client knows its
+     * app name / device / variant, so it supplies those.
+     */
+    source?: string | Record<string, unknown>;
+    /**
+     * Allow the GUI to REPLAY a logged call back into this client (re-run a call the app already
+     * made). Boundary: the GUI references a call by corrId and the METHOD is resolved from this
+     * client's own call log — it never crosses the wire, so a replay cannot be redirected to a
+     * method the app never called. The ARGS may be supplied by the GUI (edit-and-replay) and are
+     * NOT validated here beyond "must be a JSON array"; use `canReplay` to check them.
+     *
+     * Fails CLOSED: must be set to `true` EXPLICITLY. There is no dev-detection default — omit it
+     * and replay is off, so a shipped build never installs the inbound handler. Only meaningful
+     * together with `websocket`.
+     */
+    allowInvoke?: boolean;
+    /**
+     * Optional gate consulted before a replay runs — return false to block (e.g. to refuse
+     * re-running a mutating method like a send). Default: allow. Receives the logged method and the
+     * args that will actually be used — which may be UNVALIDATED, GUI-supplied args. This is the
+     * only argument check in the system, so an app whose methods mutate state should implement it.
+     */
+    canReplay?: (method: string, args: unknown[]) => boolean;
+    /** Max logged calls retained for replay (corrId→method+args). Default 500. */
+    replayLogMax?: number;
+}
+export interface ObserveHandle {
+    /** Wire your L1 adapters into this: `instrumentDataChannel(dc, peerId, obs.sink)`. */
+    sink: EventSink;
+    flusher: BatchFlusher<L2Event>;
+    runtime: Runtime;
+    mode: 'websocket' | 'stream' | 'custom' | 'buffering';
+    /** The redactor applied on export (null if redact:false). Use `.resolvePeer()` for a local names view. */
+    redactor: Redactor | null;
+    /** This device/app's resolved identity — stamped on every event as `src` and announced to the GUI. */
+    source: SourceInfo;
+    /** Report one event directly to the sink (this is what wrapClient uses). */
+    report: Report;
+    /** Wrap an RPC/service client so its calls + subscription streams are observed. */
+    wrapClient<T extends Record<string, any>>(client: T, opts?: WrapClientOptions): T;
+    /**
+     * Snapshot of request/response calls currently in flight — started (request.start) but not yet
+     * settled (request.end). Each `{ method, corrId, t }`. Subscription streams are not included (see
+     * observe.ts). Wire this to a thread-occupancy probe's `getInflight` so a stall names the call
+     * that was running (e.g. hrpc-inspector-threads).
+     */
+    inflight(): Array<{
+        method: string;
+        corrId: string;
+        t: number;
+    }>;
+    /**
+     * Bridge a hypertrace tracer into the SAME event stream: pass hypertrace's `setTraceFunction`
+     * and every `trace()` from instrumented classes (e.g. a WebRTC/call layer) becomes a
+     * `type:'trace'` event on a distinct "trace" plane in the GUI. Install this BEFORE the traced
+     * objects are constructed (hypertrace only traces objects created after the function is set).
+     * Dependency-free: the app supplies `setTraceFunction`, so the package never imports hypertrace.
+     * Returns a disposer that stops forwarding.
+     */
+    bridgeTraces(setTraceFunction: (fn: (trace: any) => void) => void): () => void;
+    /** Attach a hub connection later (auto-swarm calls this on 'connection'). */
+    attach(stream: WritableStreamLike): void;
+    stop(): void;
+}
+export declare function observe(opts?: ObserveOptions): ObserveHandle;

package/dist/observe.js

@@ -247,7 +247,8 @@ async function autoSwarm(topic, onConnection) {
   const Hyperswarm = (await import("hyperswarm")).default;
   const crypto = (await import("hypercore-crypto")).default;
   const swarm = new Hyperswarm();
-  const topicKey = crypto.hash(Buffer.from(topic));
+  const enc = new TextEncoder();
+  const topicKey = crypto.hash(enc.encode(topic));
   swarm.on("connection", (conn) => onConnection(conn));
   await swarm.join(topicKey, { client: true, server: false }).flushed();
 }

package/dist/reporters.d.ts

@@ -0,0 +1,25 @@
+export interface Reporter {
+    export(batch: unknown[]): void;
+    close(): void;
+}
+export interface WebSocketReporterOptions {
+    /** WebSocket implementation. Default globalThis.WebSocket (RN/browser/Bare/Node ≥22 have it). */
+    WebSocketImpl?: any;
+    /** Max events buffered while disconnected (oldest dropped past this). Default 1000. */
+    maxQueue?: number;
+    /** Reconnect delay ms. Default 3000. */
+    reconnectMs?: number;
+    /** Source identity sent once per connection as `{ __source }` so the GUI can build a device selector. */
+    announce?: unknown;
+    /**
+     * Inbound frame handler. When set, the reporter becomes BIDIRECTIONAL — it installs
+     * `ws.onmessage` and forwards parsed frames here. observe() passes this ONLY in dev (for the
+     * replay/invoke path); leaving it undefined keeps the reporter strictly send-only, as before.
+     */
+    onMessage?: (msg: any) => void;
+}
+/**
+ * Send each event as one JSON WebSocket message to `url` (e.g. ws://127.0.0.1:9420/ws).
+ * Auto-connects, queues while down, flushes on open, reconnects on close. Never throws.
+ */
+export declare function createWebSocketReporter(url: string, opts?: WebSocketReporterOptions): Reporter;

package/dist/wrap-client.d.ts

@@ -0,0 +1,27 @@
+export type Report = (event: Record<string, unknown>) => void;
+export interface WrapClientOptions {
+    /** Summarise args/response/stream items before reporting. Default: bounded JSON. */
+    preview?: (v: unknown) => unknown;
+    /** Monitor subscription streams' data/end/error. Default true. */
+    monitorStreams?: boolean;
+    /**
+     * Called with the RAW (un-previewed) args at each call site, keyed by the minted corrId.
+     * observe() uses this to keep a bounded call-log so a GUI can REPLAY a logged call by corrId.
+     * The METHOD comes from this log, never from the wire, so a replay cannot be redirected to a
+     * method the app never called. ARGS, however, may be supplied by the GUI (edit-and-replay) and
+     * are not validated by this library — the app's `canReplay(method, args)` hook is the only
+     * argument check. Wired only when `allowInvoke: true` is passed explicitly.
+     */
+    onCall?: (corrId: string, method: string, args: unknown[]) => void;
+}
+export declare function setInvokeContext(ctx: {
+    invokeId: string;
+    replayOf: string;
+    method: string;
+} | null): void;
+/**
+ * Wrap a client object of namespaced methods (`client.namespace.method(...)`) so every call
+ * reports endpoint + request + response/stream. Mutates and returns the same client; method
+ * return values and `this` binding are preserved (a wrapped call behaves identically).
+ */
+export declare function wrapClient<T extends Record<string, any>>(client: T, report: Report, opts?: WrapClientOptions): T;

package/package.json

@@ -1,24 +1,24 @@
 {
   "name": "hrpc-inspector",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "hrpc based debugging and observability for Bare. Tap an RPC client or a raw transport and read endpoint, request, response, latency and live subscription streams in a local GUI, or merge multi-peer timelines over a Hyperswarm hub.",
   "type": "module",
   "main": "./dist/index.js",
-  "types": "./src/index.ts",
+  "types": "./dist/index.d.ts",
   "bin": {
     "hrpc-inspector": "bin/hrpc-inspector.mjs"
   },
   "exports": {
     ".": {
-      "types": "./src/index.ts",
+      "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
     "./detect": {
-      "types": "./src/detect.ts",
+      "types": "./dist/detect.d.ts",
       "default": "./dist/detect.js"
     },
     "./observe": {
-      "types": "./src/observe.ts",
+      "types": "./dist/observe.d.ts",
       "default": "./dist/observe.js"
     }
   },
@@ -30,18 +30,20 @@
     "LICENSE",
     "NOTICE",
     "README.md",
-    "USAGE.md"
+    "USAGE.md",
+    "scripts"
   ],
   "scripts": {
-    "build": "rm -rf dist && esbuild src/index.ts src/detect.ts src/observe.ts --bundle --format=esm --platform=neutral --external:hrpc-inspector-probe --external:hrpc-inspector-protocol --external:hyperswarm --external:hypercore-crypto --outdir=dist",
+    "build": "rm -rf dist && esbuild src/index.ts src/detect.ts src/observe.ts --bundle --format=esm --platform=neutral --external:hrpc-inspector-probe --external:hrpc-inspector-protocol --external:hyperswarm --external:hypercore-crypto --outdir=dist && npm run build:types",
     "prepare": "npm run build",
-    "test": "bash test/run-all.sh"
+    "test": "bash test/run-all.sh",
+    "build:types": "tsc -p tsconfig.build.json && node scripts/rewrite-dts-specifiers.mjs dist"
   },
   "repository": "git+https://github.com/holepunchto/hrpc-inspector.git",
   "license": "Apache-2.0",
   "sideEffects": false,
   "dependencies": {
-    "hrpc-inspector-probe": "^0.1.0"
+    "hrpc-inspector-probe": "^0.1.1"
   },
   "peerDependencies": {
     "hypercore-crypto": "^3.0.0",
@@ -60,6 +62,7 @@
     }
   },
   "devDependencies": {
-    "esbuild": "^0.28.2"
+    "esbuild": "^0.28.2",
+    "typescript": "^7.0.2"
   }
 }

package/scripts/rewrite-dts-specifiers.mjs

@@ -0,0 +1,32 @@
+// tsc emits declarations that keep the source's explicit `.ts` specifiers, and a consumer
+// type-checking those hits TS5097 unless they enable allowImportingTsExtensions — which no
+// consumer should. rewriteRelativeImportExtensions only rewrites emitted JS, not .d.ts, so
+// rewrite relative `./x.ts` -> `./x.js` here. Resolution then finds ./x.d.ts beside it.
+import { readdirSync, readFileSync, writeFileSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+
+function walk(dir) {
+  return readdirSync(dir).flatMap((entry) => {
+    const full = join(dir, entry)
+    return statSync(full).isDirectory() ? walk(full) : [full]
+  })
+}
+
+const dir = process.argv[2] ?? 'dist'
+const SPECIFIER = /(from\s+|import\s*\(\s*)(['"])(\.\.?\/[^'"]+)\.ts\2/g
+
+const declarations = walk(dir).filter((f) => f.endsWith('.d.ts'))
+
+let changed = 0
+for (const path of declarations) {
+  const before = readFileSync(path, 'utf8')
+  const after = before.replace(SPECIFIER, (_m, kw, q, spec) => `${kw}${q}${spec}.js${q}`)
+  if (after !== before) { writeFileSync(path, after); changed++ }
+}
+
+const leftover = declarations.filter((f) => SPECIFIER.test(readFileSync(f, 'utf8')))
+if (leftover.length) {
+  console.error(`rewrite-dts-specifiers: .ts specifiers survive in ${leftover.join(', ')}`)
+  process.exit(1)
+}
+console.log(`rewrite-dts-specifiers: ${changed} file(s) rewritten in ${dir}`)

package/src/externals.d.ts

@@ -0,0 +1,16 @@
+// hyperswarm / hypercore-crypto are optional peers pulled in by a guarded dynamic import in the
+// Bare/Pear auto-dial path, and marked --external in the build. Neither ships types, so declare
+// the shape this package actually uses rather than depending on the packages being installed.
+declare module 'hyperswarm' {
+  interface SwarmDiscovery { flushed(): Promise<void> }
+  export default class Hyperswarm {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- the stream shape is the consumer's to name
+    on(event: 'connection', listener: (conn: any) => void): this
+    join(topic: Uint8Array, opts?: { client?: boolean; server?: boolean }): SwarmDiscovery
+  }
+}
+
+declare module 'hypercore-crypto' {
+  const crypto: { hash(data: Uint8Array): Uint8Array }
+  export default crypto
+}

package/src/observe.ts

@@ -232,7 +232,9 @@ async function autoSwarm(topic: string, onConnection: (stream: WritableStreamLik
   const Hyperswarm = (await import('hyperswarm')).default;
   const crypto = (await import('hypercore-crypto')).default;
   const swarm = new Hyperswarm();
-  const topicKey = crypto.hash(Buffer.from(topic));
+  // Buffer is a Bare/Node global and absent in browsers; this path only runs under Bare.
+  const enc = new TextEncoder();
+  const topicKey = crypto.hash(enc.encode(topic));
   swarm.on('connection', (conn: WritableStreamLike) => onConnection(conn));
   await swarm.join(topicKey, { client: true, server: false }).flushed();
 }