api-tracer-kit 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+## 1.0.0
+
+First release. Extracted from an in-repo API console and made standalone.
+
+### The tracer
+
+- Automatic `fetch`, `XMLHttpRequest` and axios interception
+- `ApiTrace` model: request, response, timing, status, error, envelope verdict
+- `FormData`, `URLSearchParams`, JSON, text and binary bodies, each recorded as sent
+- HTTP errors, network failures, timeouts and aborts told apart
+- Credential redaction in headers and bodies, on by default
+- Subscribers, a `TraceStorage` interface and a capped in-memory default
+- `reportTo`, streaming finished traces to the console
+- `destroy()`, restoring every patched global and axios adapter
+- ESM and CJS builds, TypeScript declarations, four tree-shakeable entry points
+- `api-tracer-kit/react` hooks and an `api-tracer-kit/ui` panel
+
+### The console
+
+- Preset-driven scanner (`service-object`, `axios-direct`, `fetch-direct`) that
+  picks itself by running each preset and keeping whichever reads the codebase
+- Base URLs and the auth header read from the source rather than configured
+- Live recording, endpoint matching, and adoption of calls the scan cannot explain
+- Send, bulk run, and full replay with a plan shown first
+- Response-shape contracts and drift reporting
+- Coverage, and an insight report with Markdown and JSON export
+- HAR / cURL / Postman export, HAR / cURL import
+- `{{variables}}` captured from responses and chained between calls
+- A config-driven multi-step sign-in flow, replacing a hardcoded one
+- Data kept in `<project>/.api-tracer` rather than inside the package

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 api-tracer-kit contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,466 @@
+# api-tracer-kit
+
+Trace every API call an application makes — and map, exercise and watch the
+endpoints it has.
+
+Two halves that work on their own or together:
+
+- **the tracer** — a framework-free library that records every `fetch`, `XMLHttpRequest`
+  and axios call, with no change to your API layer and no bundler configuration.
+- **the console** — a CLI and web UI that reads your source into an endpoint
+  catalog, receives the tracer's traffic, and lets you re-send any call, watch
+  for response-shape drift, and export what it captured.
+
+```bash
+npm install api-tracer-kit
+```
+
+## Quick start
+
+```ts
+import { apiTracer } from 'api-tracer-kit';
+
+apiTracer.init();
+```
+
+That is the whole setup. Every call made afterwards is traced:
+
+```ts
+await fetch('/api/users');
+
+apiTracer.getTraces();
+// [{ id, request: { url, method, headers, params, body }, response: { status, headers, body },
+//    timing: { startedAt, completedAt, duration }, status: 'success' }]
+```
+
+Nothing happens at import time, so the package is safe to import during SSR, in
+a build step, or in a test. `init()` is the only thing that patches anything.
+
+Then, optionally, the console:
+
+```bash
+npx api-tracer start
+```
+
+It reads your source, finds your endpoints, and opens at
+`http://localhost:4400`. Point the tracer at it with `reportTo: true` and your
+app's own traffic fills it in as you click around.
+
+## Features
+
+**Tracing**
+
+- `fetch`, `XMLHttpRequest` and axios, automatically
+- method, absolute URL, path, parsed query params, headers, request body
+- response status, status text, headers and body
+- start time, completion time and duration
+- HTTP errors, network failures, timeouts and aborts, told apart
+- `FormData`, `URLSearchParams`, JSON, text and binary bodies, each recorded as
+  what it was, so a captured call can be replayed the way it was sent
+- files in a `FormData` recorded as `<file: scan.pdf, 20418 bytes>`
+- a unique id per call, and no mixing between concurrent requests
+- credential redaction in headers and bodies, on by default
+- envelope reading, for APIs that answer `200` and put the real verdict in the body
+- subscribers, a replaceable storage layer, and a capped in-memory store by default
+
+**Console**
+
+- an endpoint catalog read straight out of your source — no hand-maintained list
+- live recording: your app's traffic lands on the endpoint it belongs to, with
+  the real params, payload and path ids already filled in
+- send any endpoint, with a Postman-style tabbed editor (params, headers, body,
+  capture rules) and a syntax-highlighted JSON editor
+- bulk runs, and a full replay of every captured call, with a plan shown before
+  anything is sent
+- response-shape contracts, so a backend that quietly drops a field is caught
+  even though it answered `200`
+- coverage: which endpoints your app has never exercised
+- an insight report — coverage, failures, drift, risks, hygiene, auth surface,
+  latency, inventory and a trend line — exportable as Markdown or JSON
+- HAR / cURL / Postman export, and HAR / cURL import
+- `{{variables}}`, captured from responses and chained between calls
+
+## Supported environments
+
+| | |
+| --- | --- |
+| Browsers | ✅ `fetch`, `XMLHttpRequest`, axios |
+| Node 18+ | ✅ `fetch` and axios; `XMLHttpRequest` is skipped when absent |
+| React / Next.js / Vite / CRA / webpack | ✅ no plugin, loader, alias or config change |
+| SSR and build-time execution | ✅ importing does nothing; `init()` no-ops without a runtime |
+| TypeScript | ✅ types shipped, `strict`-clean |
+| Deno / Bun | ⚠️ untested, but the tracer only uses standard globals |
+
+Nothing in the core imports React or axios. Both are optional peer dependencies
+used only by the entry points that need them.
+
+## Entry points
+
+```ts
+import { apiTracer } from 'api-tracer-kit';           // the tracer
+import { useAxios } from 'api-tracer-kit/axios';      // axios integration
+import { useApiTraces } from 'api-tracer-kit/react';  // hooks
+import { ApiTracerPanel } from 'api-tracer-kit/ui';   // in-app panel
+```
+
+Each is bundled separately, so importing the tracer never pulls in React.
+
+## Configuration
+
+All of it is optional.
+
+```ts
+apiTracer.init({
+  // which transports to patch. Default: all of them that exist.
+  transports: ['fetch', 'xhr'],
+
+  // only trace URLs matching one of these. Strings match by substring.
+  include: ['/api/'],
+  exclude: [/\/health$/],
+
+  // header names replaced with "<redacted>"
+  redactHeaders: ['authorization', 'cookie', 'set-cookie', 'x-api-key'],
+
+  // body and query field names replaced with "<redacted>"
+  redactFields: /(token|password|secret|api[-_]?key)/i,
+
+  // bodies bigger than this are recorded as omitted rather than kept
+  maxBodyBytes: 200_000,
+
+  // how many traces to keep; the oldest fall off the end
+  maxTraces: 500,
+
+  // for APIs that answer 200 and put the verdict in the body
+  envelope: { codeFields: ['status', 'code'], okField: 'success', failFrom: 400 },
+
+  // stream finished traces to the console; `true` means http://localhost:4400
+  reportTo: true,
+
+  // replace the in-memory store
+  storage: myStorage,
+
+  onTrace: (trace) => console.log(trace),
+});
+```
+
+There is no config file, and the consuming project needs no changes to its
+webpack, Vite, Babel, TypeScript, Next.js, CRA or ESLint setup.
+
+## API reference
+
+### `apiTracer`
+
+| | |
+| --- | --- |
+| `init(options?)` | installs the interceptors. Idempotent — calling it twice does not double-install. |
+| `useAxios(axios)` | traces an axios object and everything `axios.create()` makes from it |
+| `getTraces()` | every trace held, oldest first |
+| `getTrace(id)` | one trace |
+| `subscribe(fn)` | called with each finished trace; returns the unsubscribe function |
+| `clear()` | drops every trace |
+| `remove(id)` | drops one |
+| `destroy()` | restores every patched global; the app behaves exactly as it did before `init()` |
+| `isActive` | whether tracing is installed |
+
+Standalone equivalents are exported too, for callers who prefer functions:
+`initApiTracer`, `getApiTraces`, `clearApiTraces`, `subscribeToApiTraces`,
+`destroyApiTracer`.
+
+### `ApiTrace`
+
+```ts
+interface ApiTrace {
+  id: string;
+  transport: 'fetch' | 'xhr' | 'axios';
+  status: 'pending' | 'success' | 'error' | 'network-error' | 'cancelled';
+
+  request: {
+    url: string;
+    path: string;                       // origin + pathname, for grouping
+    method: string;
+    headers: Record<string, string>;
+    params: Record<string, unknown>;    // parsed query string
+    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>;
+    body?: string;
+    bodyOmitted?: 'too-large' | 'stream' | 'binary' | 'unreadable';
+    size?: number;
+  };
+
+  timing: { startedAt: number; completedAt?: number; duration?: number };
+  error?: { message: string; name?: string; stack?: string };
+
+  envelopeOk?: boolean;                 // false when a 2xx carried an error code
+  envelopeCode?: number;
+}
+```
+
+### 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`, a capped ring — an unbounded store in a
+long-lived tab is a memory leak. Nothing is persisted; supply your own storage
+if you want it to be.
+
+## React
+
+```tsx
+import { useApiTracer, useApiTraces } from 'api-tracer-kit/react';
+
+function App() {
+  useApiTracer();                         // init once, StrictMode-safe
+  const { traces, clear } = useApiTraces();
+  return <span>{traces.length} calls</span>;
+}
+```
+
+Updates are batched on an animation frame, so a burst of calls on page load
+re-renders once rather than once per request.
+
+## The in-app panel
+
+```tsx
+import { ApiTracerPanel } from 'api-tracer-kit/ui';
+
+<ApiTracerPanel enabled={process.env.NODE_ENV !== 'production'} />;
+```
+
+A floating panel with the call list, per-call detail (request and response
+headers, params, bodies, status, duration, errors), search, method and status
+filters, sorting, expand/collapse and clear. Styles are inline, so there is no
+stylesheet to import and nothing to collide with your app's CSS.
+
+## Axios
+
+axios calls are traced two ways.
+
+In a browser axios rides on `XMLHttpRequest`, so `apiTracer.init()` alone
+already sees them. For richer data — the params object as axios received it, the
+config, and Node's `http` adapter, which no global patch can reach — attach it
+explicitly:
+
+```ts
+import axios from 'axios';
+import { apiTracer } from 'api-tracer-kit';
+
+apiTracer.init();
+apiTracer.useAxios(axios);
+```
+
+One call covers the default export **and every instance `axios.create()` makes
+afterwards**. That matters in codebases that send some requests through per-page
+instances and the rest through the default object — patching only the default
+misses half the traffic.
+
+A call seen by both adapters is recorded once, not twice.
+
+Why an explicit call at all: an axios instance is a plain object with no global
+to patch, so there is no way for the tracer to reach one it was never handed.
+This is the smallest integration that works, and it is the only one in the
+package.
+
+## SSR
+
+Importing the package evaluates no browser global and installs nothing. `init()`
+checks for each runtime capability before patching it, so on a server it simply
+finds nothing to patch and returns.
+
+```ts
+// safe anywhere
+import { apiTracer } from 'api-tracer-kit';
+
+if (typeof window !== 'undefined') apiTracer.init();
+```
+
+The guard is not required — `init()` is already a no-op without a runtime — but
+it makes the intent obvious in a Next.js file that runs on both sides.
+
+## Not breaking your API calls
+
+The tracer is built so that removing it changes nothing. Specifically:
+
+- responses are read through `Response.clone()`, after the original has been
+  handed back, so your `.json()` still works
+- streaming responses (`text/event-stream`) are never buffered
+- binary and non-textual responses are described, not read
+- request bodies that are `ReadableStream`s are never consumed
+- bodies over `maxBodyBytes` are recorded as omitted rather than copied
+- errors are rethrown exactly as they arrived; aborts stay `AbortError`
+- `AbortSignal`, redirects, credentials and headers are passed through untouched
+- nothing is retried, and no request is ever made twice
+- XHR is observed with `addEventListener`, never by taking `onload` or
+  `onreadystatechange`
+- a subscriber that throws is caught, so a bad listener cannot break a request
+- `destroy()` restores every patched global and every axios adapter
+
+## The console
+
+```bash
+npx api-tracer scan      # read the source, write the endpoint catalog
+npx api-tracer serve     # the UI, at http://127.0.0.1:4400
+npx api-tracer start     # both
+npx api-tracer report    # the insight report, Markdown or JSON
+npx api-tracer init      # write a config file, if the guesses need help
+```
+
+### How it finds your endpoints
+
+It runs every scanner preset over your codebase and keeps whichever actually
+reads it:
+
+| preset | what it reads |
+| --- | --- |
+| `service-object` | `const request = { subUrl: '/users' }; return get(request)` |
+| `axios-direct` | `axios.get('/users')`, `api.post(\`/users/${id}\`, body)` |
+| `fetch-direct` | `fetch('/api/users', { method: 'POST' })` |
+
+Base URLs and the auth header name are read from your source too, so your
+environments stay in sync with the app rather than being copied into a config.
+
+If none of the presets fit, supply your own in `api-tracer.config.mjs`:
+
+```js
+export default {
+  parse: (src, config) => [
+    { name, method, subUrl, usesParams, usesData, chunk, index },
+  ],
+};
+```
+
+### Config file
+
+Optional. `api-tracer init` writes one filled in with what the scan worked out.
+Every field has a default:
+
+```js
+export default {
+  name: 'My API',
+  preset: 'service-object',
+  sources: ['src'],
+  baseUrls: { dev: 'https://dev.example.com/api' },
+  auth: { header: 'Authorization' },
+  envelope: { codeFields: ['status', 'code'], okField: 'success', failFrom: 400 },
+  login: { steps: [/* an optional multi-step sign-in chain */] },
+};
+```
+
+### Environment variables
+
+| | |
+| --- | --- |
+| `API_TRACER_DATA` | where captures are kept (default `<project>/.api-tracer`) |
+| `PORT` / `HOST` | default `4400` / `127.0.0.1` |
+| `BASE_PATH` | serve under a path, e.g. `/api-console`, behind a proxy |
+| `ALLOWED_ORIGINS` | comma-separated origins allowed to post recordings |
+| `CONSOLE_USER` / `CONSOLE_PASS` | basic auth on everything except `/api/record` |
+| `LOCK_RECORDING` / `LOCK_ENV` | stop one person's click changing a shared console |
+
+## Security
+
+The tracer sees whatever your API sees, which on some products means
+credentials and personal data. So:
+
+- `Authorization`, `Cookie`, `Set-Cookie`, `X-API-Key` and the usual token
+  header names are redacted by default, and the list is configurable
+- any field whose **name** looks like a credential (`token`, `password`,
+  `secret`, `api_key`, `otp`, …) is replaced with `<redacted>`, keeping the
+  surrounding shape so the sample stays useful
+- redaction happens before a trace is stored, so a redacted value is never held
+  in memory either
+- the console redacts again before writing anything to disk
+- HAR, cURL and Postman exports carry `<paste your token>` in place of a real
+  token, so an export is safe to attach to a ticket
+
+The console's data directory holds captured request and response bodies from a
+real environment. Treat it as sensitive: keep it out of version control (it is
+`.api-tracer/`, add it to `.gitignore`) and keep a deployed console behind VPN
+or SSO.
+
+## Limitations
+
+Worth knowing before you rely on it.
+
+- **An axios instance must be handed over.** There is no global to patch. In a
+  browser the XHR adapter catches axios anyway; in Node it cannot.
+- **A request body that is a stream is never read**, because reading it would
+  empty it. It is recorded as `omitted: 'stream'`.
+- **Files in a `FormData` are described, not captured**, so a captured upload
+  cannot be replayed with its file.
+- **Response bodies over `maxBodyBytes` are omitted**, not truncated — a partial
+  JSON body is more misleading than none.
+- **`Response.clone()` buffers.** For a large non-streaming response the clone
+  holds a second copy until it is read. The size cap keeps this bounded.
+- **The scanner is regex-based.** It reads the three shapes above well and says
+  what it could not read; it does not understand a URL assembled from three
+  variables. Live recording covers what the scan misses — an unexplained call
+  becomes an endpoint of its own.
+- **The "unused endpoint" count is a substring count**, so `import * as services`
+  or a re-export would hide a real usage. Confirm with a grep before deleting.
+- **The console is single-user by design**: one token, one selected environment,
+  one set of results.
+
+## Architecture
+
+```
+api-tracer-kit
+├── src/
+│   ├── core/         tracer, data model, redaction, bodies, URLs, envelopes, runtime detection
+│   ├── adapters/     fetch, xhr, axios, and the suppression that stops double-counting
+│   ├── storage/      the TraceStorage interface and the capped in-memory default
+│   ├── transport/    posting finished traces to a console
+│   ├── ui/           the React panel (optional entry point)
+│   ├── index.ts      the public API
+│   ├── axios.ts      api-tracer-kit/axios
+│   └── react.ts      api-tracer-kit/react
+└── cli/
+    ├── bin/          the api-tracer command
+    ├── presets.mjs   how to find endpoints in a codebase
+    ├── config.mjs    defaults, and guessing what was not configured
+    ├── scan.mjs      source -> endpoint catalog
+    ├── server.mjs    the console: forwards calls, replays, exports, records
+    ├── import.mjs    HAR and cURL, matched back to the catalog
+    ├── shape.mjs     response shapes and drift diffing
+    ├── report.mjs    the insight report model and its Markdown export
+    └── web/          the dashboard (no framework, no build step)
+```
+
+The core is framework-free and knows nothing about any particular application.
+The console knows nothing about it either: the catalog supplies the endpoints,
+base URLs, auth header and envelope convention, and the config file supplies the
+sign-in flow if there is one worth automating.
+
+## Development
+
+```bash
+npm install
+npm run build      # tsup -> dist/, ESM + CJS + .d.ts
+npm test           # the tracer suite, then the console suite
+npm run typecheck
+```
+
+The example project doubles as an end-to-end check:
+
+```bash
+cd examples/basic && npm install && npm start
+```
+
+## Licence
+
+MIT