api-tracer-kit 1.0.1 → 1.1.0

package/docs/frameworks.md

@@ -0,0 +1,192 @@
+# Frameworks
+
+The tracer only needs one thing: `init()` called once, at the entry point,
+before anything makes a request. No bundler, Babel, TypeScript or ESLint
+configuration is required anywhere.
+
+## Plain JavaScript
+
+```html
+<script type="module">
+  import { apiTracer } from 'https://esm.sh/api-tracer-kit';
+  apiTracer.init();
+</script>
+```
+
+or in a bundled project:
+
+```js
+import { apiTracer } from 'api-tracer-kit';
+apiTracer.init();
+```
+
+## React
+
+```tsx
+// src/main.tsx — before ReactDOM.render / createRoot
+import { apiTracer } from 'api-tracer-kit';
+
+apiTracer.init({ reportTo: import.meta.env.DEV });
+```
+
+Or from inside the tree, which is StrictMode-safe:
+
+```tsx
+import { useApiTracer } from 'api-tracer-kit/react';
+
+function App() {
+  useApiTracer({ reportTo: true });
+  return <Routes />;
+}
+```
+
+`useApiTracer` deliberately does **not** destroy on unmount: in StrictMode that
+would tear the interceptors down immediately after installing them.
+
+To render the traces:
+
+```tsx
+import { useApiTraces } from 'api-tracer-kit/react';
+
+function CallCount() {
+  const { traces, clear } = useApiTraces();
+  return <button onClick={clear}>{traces.length} calls</button>;
+}
+```
+
+Updates are batched on an animation frame, so a burst of calls on page load
+re-renders once rather than once per request.
+
+## Create React App
+
+CRA's `ModuleScopePlugin` allows imports only from `src/` and `node_modules/`.
+Always import by **package name** — never by a relative path to a checkout
+outside the project:
+
+```js
+import { apiTracer } from 'api-tracer-kit';                     // ✅
+import { apiTracer } from '../../../packages/api-tracer-kit';   // ❌ rejected
+```
+
+A `yarn add file:` dependency creates a **symlink**, and webpack resolves
+symlinks to their real path — which lands outside the project and is rejected
+the same way. Depend on a published version, or on a packed tarball:
+
+```bash
+npm pack --pack-destination ./vendor   # in the package
+```
+
+```json
+"api-tracer-kit": "file:vendor/api-tracer-kit-1.0.1.tgz"
+```
+
+Gate it on `REACT_APP_ENV`, not `NODE_ENV` — a dev or stage deploy is a
+production build, so `NODE_ENV` would compile the tracer out of exactly the
+environments it is meant for:
+
+```js
+// src/services/apiRecorder.js
+import axios from 'axios';
+import { apiTracer } from 'api-tracer-kit';
+
+const isEnabled =
+  process.env.REACT_APP_ENV === 'dev' || process.env.REACT_APP_ENV === 'stage';
+
+if (isEnabled) {
+  apiTracer.init({ reportTo: process.env.REACT_APP_API_CONSOLE_URL || 'http://localhost:4400' });
+  apiTracer.useAxios(axios);
+}
+```
+
+```js
+// src/index.js — one import, at the top
+import './services/apiRecorder';
+```
+
+Compare `process.env.REACT_APP_ENV` **directly**, not through a variable, so
+DefinePlugin substitutes the literal and the whole condition folds away in a
+production build.
+
+## Vite
+
+```ts
+// src/main.ts
+import { apiTracer } from 'api-tracer-kit';
+
+if (import.meta.env.DEV) {
+  apiTracer.init({ reportTo: true });
+}
+```
+
+`import.meta.env.DEV` is statically replaced, so the branch is removed from a
+production build.
+
+## Next.js
+
+Importing the package on the server is safe — it evaluates no browser global —
+but there is no point tracing a render, so guard the call:
+
+```tsx
+// app/providers.tsx
+'use client';
+
+import { useApiTracer } from 'api-tracer-kit/react';
+
+export function Providers({ children }) {
+  useApiTracer({ reportTo: process.env.NODE_ENV === 'development' });
+  return children;
+}
+```
+
+For the Pages Router, `pages/_app.tsx` works the same way.
+
+To trace server-side calls too, `init()` in `instrumentation.ts` — Node has
+`fetch`, so it works there as well:
+
+```ts
+export async function register() {
+  if (process.env.NEXT_RUNTIME === 'nodejs') {
+    const { apiTracer } = await import('api-tracer-kit');
+    apiTracer.init({ include: ['/api/'] });
+  }
+}
+```
+
+Server traces stay in that process's memory; they do not reach the browser
+panel.
+
+## Node.js
+
+```js
+import { apiTracer } from 'api-tracer-kit';
+
+apiTracer.init();
+await fetch('https://api.example.com/users');
+console.log(apiTracer.getTraces());
+```
+
+Node 18+ has global `fetch`, so it is traced. There is no `XMLHttpRequest`, and
+that transport is skipped rather than erroring. For axios on Node's `http`
+adapter, `useAxios()` is required — no global patch can reach it.
+
+## Testing
+
+Use an isolated instance rather than the shared one, so cases cannot leak into
+each other:
+
+```ts
+import { ApiTracer } from 'api-tracer-kit';
+
+let tracer;
+beforeEach(() => { tracer = new ApiTracer().init({ transports: ['fetch'] }); });
+afterEach(() => { tracer.destroy(); });
+```
+
+`destroy()` restores the original `fetch`, so a suite that traces is
+indistinguishable from one that does not.
+
+## Webpack, Rollup, esbuild, Parcel
+
+Nothing to configure. The package ships ESM and CJS with `sideEffects: false`,
+so an unused import is dropped entirely and the four entry points are bundled
+separately — importing the tracer never pulls in React.

package/docs/getting-started.md

@@ -0,0 +1,120 @@
+# Getting started
+
+## Install
+
+```bash
+npm install api-tracer-kit
+```
+
+Nothing runs on install, and importing the package evaluates no browser global.
+Tracing begins only when you call `init()`.
+
+## One command
+
+```bash
+npx api-tracer setup
+```
+
+It detects your framework, writes a module that configures the tracer, adds the
+import to your entry file, and gitignores the console's data directory. Re-running
+it is safe, and it warns if anything else already calls `init()`.
+
+| Option | |
+| --- | --- |
+| `--framework cra\|vite\|next\|node` | override the detection |
+| `--entry <file>` | the entry file to import from |
+| `--out <file>` | where to write the module (default `src/apiTracer.js`) |
+| `--axios false` | do not attach axios |
+| `--envelope false` | your API reports failure in the status line, not the body |
+| `--force` | overwrite an existing file |
+
+What it works out for you:
+
+- **the framework**, from your dependencies
+- **the environment gate** that your bundler will actually fold — `REACT_APP_ENV`
+  for CRA, `import.meta.env.DEV` for Vite, `NODE_ENV` for Next and Node
+- **whether to attach axios**, from whether you depend on it
+- **TypeScript or JavaScript**, from whether you have a `tsconfig.json`
+
+## Or do it by hand
+
+Put this at your application's entry point, before anything makes a request:
+
+```ts
+import { apiTracer } from 'api-tracer-kit';
+
+apiTracer.init();
+```
+
+Every `fetch` and `XMLHttpRequest` afterwards is traced. Read them back with:
+
+```ts
+apiTracer.getTraces();
+```
+
+### If you use axios
+
+axios instances are plain objects with no global to patch, so hand yours over:
+
+```ts
+import axios from 'axios';
+
+apiTracer.init();
+apiTracer.useAxios(axios);
+```
+
+One call covers the default export **and every instance `axios.create()` makes
+afterwards**. See [axios](./tracer.md#axios) for why this is the one integration
+the package cannot do for you.
+
+> **Configure it in exactly one place.** `init()` is idempotent — a second call
+> keeps the first one's configuration and warns about the options it ignored.
+> Two modules each calling `init()` is the most common way to end up with a
+> tracer that runs but does nothing you asked for.
+
+## See them
+
+Three options, in increasing order of usefulness.
+
+**1. The console log.** Fine for a quick check:
+
+```ts
+apiTracer.subscribe((trace) => {
+  console.log(trace.request.method, trace.request.url, trace.response?.status, `${trace.timing.duration}ms`);
+});
+```
+
+**2. The in-app panel.** A floating list with search, filters and per-call
+detail. React only:
+
+```tsx
+import { ApiTracerPanel } from 'api-tracer-kit/ui';
+
+<ApiTracerPanel enabled={process.env.NODE_ENV !== 'production'} />;
+```
+
+**3. The console.** A separate process that maps every endpoint in your source,
+receives your app's traffic, and lets you re-send any call. This is the one
+worth setting up. See [the console](./console.md).
+
+```bash
+npx api-tracer start
+```
+
+then point the tracer at it:
+
+```ts
+apiTracer.init({ reportTo: true });   // true means http://localhost:4400
+```
+
+## Where to go next
+
+| | |
+| --- | --- |
+| [Tracer API](./tracer.md) | every option, the `ApiTrace` model, storage, lifecycle |
+| [The console](./console.md) | CLI, dashboard, replay, drift, coverage, import/export |
+| [Configuration](./configuration.md) | the config file, scanner presets, sign-in flows |
+| [Frameworks](./frameworks.md) | React, Next.js, Vite, CRA, Node, plain JavaScript |
+| [Troubleshooting](./troubleshooting.md) | when nothing is being recorded |
+| [Security](./security.md) | redaction, what is stored, what is safe to share |
+| [Architecture](./architecture.md) | how it works inside |

package/docs/security.md

@@ -0,0 +1,143 @@
+# Security
+
+The tracer sees everything your API sees. On some products that means
+credentials, personal data, and — in health, finance or HR software — data whose
+mishandling is a regulatory matter, not just an embarrassment. Read this before
+deploying a console anywhere but your own laptop.
+
+## What is redacted, by default
+
+**Headers**, matched case-insensitively:
+
+```
+authorization, cookie, set-cookie, proxy-authorization, x-api-key, api-key,
+auth_token, access_token, secret_token, x-auth-token, x-csrf-token
+```
+
+**Body and query fields**, matched by name:
+
+```
+/(token|password|passwd|secret|api[-_]?key|authorization|credential|otp|ssn)/i
+```
+
+The **value** is replaced with `<redacted>` and the surrounding shape is kept, so
+the sample still shows what the endpoint expects.
+
+Redaction happens **before** a trace is stored, so a real credential is never
+held in the tracer's memory, never reaches a subscriber, and never leaves the
+browser. The console redacts again before writing anything to disk.
+
+Extend rather than replace:
+
+```ts
+import { DEFAULT_REDACT_HEADERS } from 'api-tracer-kit';
+
+apiTracer.init({
+  redactHeaders: [...DEFAULT_REDACT_HEADERS, 'x-internal-key'],
+  redactFields: /(token|password|secret|nhs_number|date_of_birth)/i,
+});
+```
+
+## What is *not* redacted
+
+This is the part that matters.
+
+Redaction is **name-based**. A field called `notes` containing a patient's
+history, a `body` containing an address, a response listing every user — none of
+those look like credentials, and none are touched. The tracer records response
+bodies in full, up to `maxBodyBytes`.
+
+So: **assume every trace and every capture contains real data from the
+environment you are watching.**
+
+If that is unacceptable for your product, either narrow what is traced:
+
+```ts
+apiTracer.init({ include: ['/api/reference/'] });
+```
+
+or drop response bodies entirely:
+
+```ts
+apiTracer.init({ maxBodyBytes: 0 });
+```
+
+or post-process in a subscriber before anything is stored or reported.
+
+## Where data ends up
+
+### In the browser
+
+Traces live in memory, in a capped ring (500 by default), and disappear on
+reload. Nothing is persisted unless you supply storage that does.
+
+### In the console's data directory
+
+`<project>/.api-tracer/` holds captured request and response bodies, response
+shapes, and a real session token.
+
+**Add it to `.gitignore` before you run anything:**
+
+```
+.api-tracer/
+```
+
+`tokens.json` is written owner-only (`chmod 600`), but it is still a real
+credential on disk. **Sign out** deletes it, and on a shared machine that is
+worth doing.
+
+If it has already been committed, unstage it — the files stay on disk:
+
+```bash
+git rm -r --cached .api-tracer
+```
+
+If it reached a pushed commit, treat the token as compromised and rotate it. The
+bodies are in the history and removing them means rewriting it.
+
+## What is safe to share
+
+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 or hand to a backend
+developer — **as far as credentials go**.
+
+The bodies in them are still real. An export of a busy session is a data
+extract. Treat it accordingly.
+
+## Deploying a console
+
+It is a Node process that writes JSON files and holds a token. It is not a
+static asset.
+
+- **Keep it off the public internet.** VPN, SSO, or an allowlisted origin behind
+  your CDN.
+- **`CONSOLE_USER` / `CONSOLE_PASS`** turn on basic auth — but **`/api/record`
+  stays open**, because the app posts recordings from a browser that cannot send
+  those credentials. The gate protects reading captures, replaying calls and the
+  stored token; it does not stop someone who can reach the host from posting
+  junk recordings. If that matters, put the whole thing behind VPN or SSO.
+- **`ALLOWED_ORIGINS`** is an allowlist for posting recordings. Localhost always
+  works; every other origin must be named, so a stray site cannot feed or read
+  the console.
+- **`HOST`** stays on `127.0.0.1` unless you change it, so a laptop instance is
+  not exposed by accident.
+- **Keep the data volume off shared storage.**
+- **Mixed content**: an HTTPS app cannot post to an `http://` console, and the
+  browser blocks it silently. Terminate TLS in front of it, or serve it under a
+  path on the app's own origin.
+
+## Replaying against production
+
+The console refuses to replay writes against an environment named `prod`.
+
+That is a guard, not a guarantee — it matches on the environment name you
+configured. Consider commenting out the production base URL in your config
+entirely, so it cannot be selected. `LOCK_ENV` pins a shared console to one
+environment so nobody can switch it.
+
+Replay is not a dry run. Every POST creates a real record each time.
+
+## Reporting a vulnerability
+
+Open an issue for anything non-sensitive. For a genuine vulnerability, contact
+the maintainer directly rather than filing publicly.