api-tracer-kit 1.0.1 → 1.1.0

package/docs/tracer.md

@@ -0,0 +1,330 @@
+# The tracer
+
+The framework-free half of the package. No React, no axios, no DOM required.
+
+## `apiTracer`
+
+A single shared instance. It is held in a global registry keyed by
+`Symbol.for('api-tracer-kit.registry')`, so `api-tracer-kit` and
+`api-tracer-kit/axios` — separate bundles with separate module graphs — resolve
+to the same object. Without that, `useAxios()` would attach to an instance
+`getTraces()` never reads from.
+
+| Method | Description |
+| --- | --- |
+| `init(options?)` | Installs the interceptors. Idempotent: a second call keeps the first one's configuration and warns about the options it ignored. Returns `this`. |
+| `useAxios(axios)` | Traces an axios object and everything it creates. Calls `init()` first if needed. Returns `this`. |
+| `getTraces()` | Every trace held, oldest first. |
+| `getTrace(id)` | One trace, or `undefined`. |
+| `subscribe(fn)` | Calls `fn(trace)` for each **finished** trace. Returns the unsubscribe function. |
+| `clear()` | Drops every trace. |
+| `remove(id)` | Drops one. |
+| `destroy()` | Restores every patched global and every axios adapter. After this the runtime behaves exactly as it did before `init()`. |
+| `isActive` | Whether tracing is currently installed. |
+
+Standalone function forms, for callers who would rather not reach through an
+object: `initApiTracer`, `getApiTraces`, `clearApiTraces`,
+`subscribeToApiTraces`, `destroyApiTracer`. They act on the same shared
+instance.
+
+`ApiTracer` is exported as a class too, if you want an isolated instance — most
+useful in tests, where a shared singleton between test cases is a nuisance.
+
+```ts
+import { ApiTracer } from 'api-tracer-kit';
+
+const tracer = new ApiTracer().init({ transports: ['fetch'] });
+// ...
+tracer.destroy();
+```
+
+## Options
+
+Every one is optional.
+
+### `transports`
+
+```ts
+transports?: ('fetch' | 'xhr' | 'axios')[]
+```
+
+Which globals to patch. Default: all of them that exist in the runtime. Pass
+`[]` to patch nothing globally — useful when you only want axios, which is
+attached separately.
+
+`'axios'` in this list does nothing on its own; axios has no global to patch and
+is reached only through `useAxios()`.
+
+### `include` / `exclude`
+
+```ts
+include?: (string | RegExp)[]
+exclude?: (string | RegExp)[]
+```
+
+Strings match by substring, so `'/api/'` is usually enough. `exclude` is applied
+first and wins. With no `include`, everything not excluded is traced.
+
+```ts
+apiTracer.init({ include: ['/api/'], exclude: [/\/health$/, 'analytics'] });
+```
+
+`reportTo`'s own endpoint is excluded automatically — the tracer never traces
+its own reporting.
+
+### `redactHeaders` / `redactFields`
+
+```ts
+redactHeaders?: string[]     // default: DEFAULT_REDACT_HEADERS
+redactFields?: RegExp        // default: DEFAULT_REDACT_FIELDS
+```
+
+Header names are matched case-insensitively; field names are matched with the
+regex. Both replace the **value** with `<redacted>` and keep the surrounding
+shape. Redaction happens before a trace is stored, so a real credential is never
+held in memory.
+
+Defaults are exported so you can extend rather than replace them:
+
+```ts
+import { DEFAULT_REDACT_HEADERS } from 'api-tracer-kit';
+
+apiTracer.init({ redactHeaders: [...DEFAULT_REDACT_HEADERS, 'x-internal-key'] });
+```
+
+`DEFAULT_REDACT_HEADERS` covers `authorization`, `cookie`, `set-cookie`,
+`proxy-authorization`, `x-api-key`, `api-key`, `auth_token`, `access_token`,
+`secret_token`, `x-auth-token`, `x-csrf-token`.
+
+`DEFAULT_REDACT_FIELDS` is
+`/(token|password|passwd|secret|api[-_]?key|authorization|credential|otp|ssn)/i`.
+
+### `maxBodyBytes`
+
+```ts
+maxBodyBytes?: number        // default 200_000
+```
+
+Bodies larger than this are recorded as omitted rather than truncated — a
+partial JSON body is more misleading than none. A response declaring a larger
+`content-length` is never read at all.
+
+### `maxTraces`
+
+```ts
+maxTraces?: number           // default 500
+```
+
+The in-memory store is a capped ring; older traces fall off the end. An
+unbounded store in a long-lived tab is a memory leak.
+
+### `envelope`
+
+```ts
+envelope?: {
+  codeFields?: string[];     // default ['status', 'code']
+  okField?: string;          // default 'success'
+  failFrom?: number;         // default 400
+} | false
+```
+
+For APIs that answer HTTP `200` and put the real verdict in the body:
+
+```json
+{ "status": 801, "success": false, "message": "Authentication token header missing" }
+```
+
+With an envelope configured, that trace gets `envelopeOk: false` and
+`envelopeCode: 801` even though `response.status` is `200`. Pass an empty object
+`{}` to accept the defaults; omit it entirely and no envelope is read.
+
+### `reportTo`
+
+```ts
+reportTo?: string | boolean
+```
+
+POST each finished trace to a console. `true` means `http://localhost:4400`.
+Failures are swallowed — a console that is not running must never affect the
+app — and after six consecutive failures the reporter stops trying.
+
+### `storage`
+
+```ts
+storage?: TraceStorage
+```
+
+Replaces the in-memory store. See [Storage](#storage).
+
+### `onTrace`
+
+```ts
+onTrace?: (trace: ApiTrace) => void
+```
+
+Identical to `subscribe()`, set up front. This is the one option a second
+`init()` still honours, because adding a subscriber from another module is
+legitimate.
+
+### `debug`
+
+```ts
+debug?: boolean              // default false
+```
+
+Logs a line on init and reports subscribers that throw.
+
+## The `ApiTrace` model
+
+```ts
+interface ApiTrace {
+  id: string;
+  transport: 'fetch' | 'xhr' | 'axios';
+  status: 'pending' | 'success' | 'error' | 'network-error' | 'cancelled';
+
+  request: {
+    url: string;                      // absolute
+    path: string;                     // origin + pathname, for grouping
+    method: string;
+    headers: Record<string, string>;  // redacted
+    params: Record<string, unknown>;  // parsed query string, redacted
+    body?: unknown;                   // parsed and redacted
+    bodyType: 'json' | 'formdata' | 'urlencoded' | 'text' | 'binary' | 'none';
+    bodyOmitted?: 'too-large' | 'stream' | 'binary' | 'unreadable';
+  };
+
+  response?: {
+    status: number;
+    statusText?: string;
+    headers: Record<string, string>;  // redacted
+    body?: string;                    // raw text
+    bodyOmitted?: 'too-large' | 'stream' | 'binary' | 'unreadable';
+    size?: number;
+  };
+
+  timing: {
+    startedAt: number;                // performance.now() where available
+    completedAt?: number;
+    duration?: number;                // milliseconds, rounded
+  };
+
+  error?: { message: string; name?: string; stack?: string };
+
+  envelopeOk?: boolean;
+  envelopeCode?: number;
+}
+```
+
+### What each `status` means
+
+| | |
+| --- | --- |
+| `pending` | in flight; `response` and `timing.duration` are not set yet |
+| `success` | HTTP 2xx |
+| `error` | the server answered, but not with a 2xx |
+| `network-error` | no answer: DNS failure, connection refused, timeout |
+| `cancelled` | aborted by the caller — not a broken endpoint |
+
+Subscribers are called only when a trace finishes, so a subscriber never sees
+`pending`. `getTraces()` can return one.
+
+### Bodies
+
+`bodyType` records what actually went on the wire, so a captured call can be
+replayed the same way. A `FormData` is unpacked field by field — `JSON.stringify`
+flattens one to `{}` — and files inside it become
+`<file: scan.pdf, 20418 bytes>`, because a file cannot be replayed.
+
+`bodyOmitted` says why a body is missing:
+
+| | |
+| --- | --- |
+| `too-large` | over `maxBodyBytes` |
+| `stream` | a `ReadableStream` request body, or a `text/event-stream` response — reading either would break it |
+| `binary` | a Blob, ArrayBuffer, or a non-textual content type |
+| `unreadable` | the body could not be cloned or parsed |
+
+## Storage
+
+```ts
+interface TraceStorage {
+  add(trace: ApiTrace): void;
+  update(id: string, patch: Partial<ApiTrace>): ApiTrace | undefined;
+  get(id: string): ApiTrace | undefined;
+  getAll(): ApiTrace[];
+  remove(id: string): void;
+  clear(): void;
+}
+```
+
+The default is `MemoryTraceStorage`, exported so you can size it yourself:
+
+```ts
+import { MemoryTraceStorage } from 'api-tracer-kit';
+
+apiTracer.init({ storage: new MemoryTraceStorage(50) });
+```
+
+`update()` returning `undefined` for an unknown id is normal, not an error: a
+long-running request can be evicted by the cap while still in flight.
+
+Nothing is persisted by default. To keep traces across reloads, supply storage
+backed by `sessionStorage` or IndexedDB — but see
+[Security](./security.md) first, because traces contain request and response
+bodies.
+
+## axios
+
+axios calls are traced two ways.
+
+In a browser axios rides on `XMLHttpRequest`, so `apiTracer.init()` alone sees
+them. `useAxios()` adds what the XHR adapter cannot:
+
+- the `params` object as axios received it, rather than a re-parsed query string
+- Node's `http` adapter, which no global patch can reach
+- correct handling of axios's habit of rejecting on non-2xx while still having a
+  response
+
+A call seen by both adapters is recorded **once**. axios builds and opens its
+XHR synchronously inside its adapter, so the tracer raises a flag around the
+adapter call that is still up when `open` runs and down before anything else can
+start a request. The suppression is exact, not time-based.
+
+`useAxios()` wraps the instance's adapter rather than only its interceptors,
+because the adapter is the one place both the request and the raw response are
+available. If your application later assigns `axios.defaults.adapter` — a mock,
+a retry library, a custom transport — tracing survives it: the property is an
+accessor that routes the assignment underneath the wrapper.
+
+`destroy()` gives every instance back the adapter it last had, including
+instances created through the patched `create()`.
+
+## What the tracer will not do to your app
+
+Removing it changes nothing. Specifically:
+
+- responses are read through `Response.clone()`, **after** the original has been
+  handed back, so your `.json()` still works
+- `text/event-stream` responses are never buffered
+- binary and non-textual responses are described, not read
+- request bodies that are streams are never consumed
+- errors are rethrown exactly as they arrived; aborts stay `AbortError`
+- `AbortSignal`, redirects, credentials and headers pass through untouched
+- nothing is retried, and no request is made twice
+- XHR is observed with `addEventListener`, never by taking `onload` or
+  `onreadystatechange` — those belong to the caller
+- a subscriber that throws is caught
+- `destroy()` restores every patched global
+
+## Cleanup
+
+```ts
+apiTracer.destroy();
+```
+
+Restores `fetch`, the `XMLHttpRequest` prototype and every axios adapter, clears
+the subscribers, and stops reporting. `fetch` is only restored if nothing else
+has patched it since — clobbering another tool's interceptor on the way out
+would be worse than leaving ours in place.
+
+Calling `destroy()` on a tracer that was never started is safe.

package/docs/troubleshooting.md

@@ -0,0 +1,194 @@
+# Troubleshooting
+
+## Nothing is being recorded
+
+Work down this list in order. Each step tells you which link in the chain is
+broken, so you never have to guess.
+
+### 1. Is the tracer running at all?
+
+Open your app and look at the **browser** console. With `debug: true` or a log
+of your own you should see the tracer start. If you see nothing, `init()` never
+ran — the package is installed but nothing imported it.
+
+**Installing a package does not run it.** Something must import the module that
+calls `init()`, and that module must be reachable from your entry point:
+
+```js
+// src/index.js
+import './services/apiRecorder';
+```
+
+Check the module is actually in the bundle:
+
+```bash
+curl -s http://localhost:3000/static/js/bundle.js | grep -c 'api-tracer-kit'
+```
+
+Zero means it is not being compiled in.
+
+### 2. Is it configured the way you think?
+
+Inspect the live tracer from the browser console:
+
+```js
+const t = globalThis[Symbol.for('api-tracer-kit.registry')].tracer;
+({ active: t.isActive, patches: t.uninstallers.length, excludes: t.options.exclude.map(String) });
+```
+
+| What you see | What it means |
+| --- | --- |
+| `active: false` | `init()` never ran |
+| `excludes: []` when you passed `reportTo` | **your options were ignored — see below** |
+| `patches: 3` when you passed `transports: []` | same cause |
+
+**The most common cause of a tracer that runs but reports nothing is a second
+`init()`.** It is idempotent — a second call keeps the first one's configuration
+so it cannot install a second set of interceptors and double-count every
+request. Since 1.0.1 it warns:
+
+```
+[api-tracer] init() was called again on a tracer that is already running, so these
+options were ignored: reportTo, transports, envelope.
+```
+
+Find every call and keep exactly one:
+
+```bash
+grep -rn 'apiTracer.init\|initApiTracer' src/
+```
+
+### 3. Is your app actually making API calls?
+
+An app sitting on a login screen may make none. Check the Network tab, or:
+
+```js
+globalThis[Symbol.for('api-tracer-kit.registry')].tracer.getTraces().length;
+```
+
+Traces above zero means the tracer works and the problem is downstream — go to
+step 5. Zero traces with calls visible in the Network tab means the transport
+carrying them is not patched — step 4.
+
+### 4. Is the right transport patched?
+
+`transports: []` patches **nothing globally**. That is correct when you only
+want axios, but it means plain `fetch` and `XMLHttpRequest` calls are invisible.
+
+axios instances need `useAxios()`; there is no global to patch. And it must
+cover the instance your code actually uses — `useAxios(axios)` covers the
+default export and everything `axios.create()` makes **after** that call, so
+`init()` has to run before your API layer creates its instances.
+
+### 5. Are traces reaching the console?
+
+```bash
+curl -s http://127.0.0.1:4400/api/live | python3 -c 'import json,sys; print(json.load(sys.stdin)["count"])'
+```
+
+Still zero with traces in memory? The reporter is failing. It fails **silently
+by design** — a console that is not running must never affect your app — so look
+at the Network tab for the POST to `/api/record`.
+
+| | |
+| --- | --- |
+| No request at all | `reportTo` is not set. Back to step 2. |
+| `404` | Path mismatch. If `reportTo` is `/api-console`, the console must run with `BASE_PATH=/api-console`. |
+| CORS error | Add your app's origin to `ALLOWED_ORIGINS`. Localhost always works. |
+| `ERR_CONNECTION_REFUSED` | The console is not running, or is on a different port. |
+| Blocked, mixed content | An HTTPS app cannot post to an `http://` console. Serve the console over TLS or under a path on the app's own origin. |
+
+### 6. Are you looking at the right app?
+
+If port 3000 was taken, CRA silently starts on 3001 — and you may be browsing a
+different project entirely:
+
+```bash
+lsof -nP -iTCP:3000 -sTCP:LISTEN
+```
+
+## The scan finds no endpoints
+
+```bash
+npx api-tracer init
+```
+
+It prints what each preset found:
+
+```
+  service-object   325
+  fetch-direct       1
+  axios-direct       0
+```
+
+All zero means no preset reads your codebase. Check `sources` covers where your
+API layer lives, then either force one with `--preset`, or write a `parse`
+function — see [Configuration](./configuration.md#your-own-scanner).
+
+Live recording works without a catalog: every call is adopted as an endpoint of
+its own.
+
+## Endpoints list, but nothing is captured
+
+Those are independent. The list comes from the console reading your source; the
+captures come from your app posting traffic. A working list tells you nothing
+about the tracer. Go to step 1 above.
+
+## `Module not found: ... falls outside of the project src/ directory`
+
+CRA's `ModuleScopePlugin`. You imported by relative path. Import by package
+name; see [Frameworks → CRA](./frameworks.md#create-react-app).
+
+## `Package "api-tracer-kit" refers to a non-existing file`
+
+Yarn 1 resolving a relative `file:` path wrongly. Use a packed tarball, or a
+published version. See [Frameworks → CRA](./frameworks.md#create-react-app).
+
+## A second React, or "invalid hook call"
+
+`yarn add file:<directory>` copies the whole directory, **including its own
+`node_modules`** — React among them. Two Reacts in one build breaks hooks. A
+registry install or a packed tarball ships only what `files` allows.
+
+## Every call is recorded twice
+
+Two `init()` calls on separate instances, or a second copy of the package in the
+build. The shared tracer is held in a global registry so entry points agree; a
+duplicate usually means two different versions are installed.
+
+```bash
+npm ls api-tracer-kit
+```
+
+axios calls are **not** a cause: a call seen by both the axios and XHR adapters
+is recorded once.
+
+## Response bodies are missing
+
+Check `response.bodyOmitted`:
+
+| | |
+| --- | --- |
+| `too-large` | over `maxBodyBytes` (default 200 kB). Raise it if you need them. |
+| `stream` | `text/event-stream`. Never buffered, deliberately. |
+| `binary` | a non-textual content type. Described, not read. |
+| `unreadable` | the body could not be cloned or parsed. |
+
+## A response body is `<redacted>`
+
+A field whose **name** matched `redactFields`, or a header matching
+`redactHeaders`. That is working as intended. Narrow the pattern if it is too
+eager — but see [Security](./security.md) first.
+
+## The app broke after adding the tracer
+
+It should not have; that is the package's first design constraint. Confirm by
+removing it:
+
+```js
+apiTracer.destroy();
+```
+
+That restores every patched global and axios adapter. If the problem survives
+`destroy()`, it is not the tracer. If it does not, please open an issue with the
+transport and the call shape.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "api-tracer-kit",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Trace every API call an app makes, and map, exercise and monitor the endpoints it has.",
   "keywords": [
     "api",
@@ -50,6 +50,7 @@
   "files": [
     "dist",
     "cli",
+    "docs",
     "README.md",
     "LICENSE",
     "CHANGELOG.md"