midline-agent 0.1.9 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # midline-agent
 
-**The Node.js SDK for Midline** — automatic request and error monitoring with security and threat detection.
+**The Node.js SDK for Midline** — request and error monitoring with security and threat detection.
 
 Midline itself is not tied to Node. Every event lands on the same stream through a plain JSON
 endpoint, so a Django, Rails, Laravel, Spring, Go or .NET service reports exactly what an Express
@@ -9,328 +9,409 @@ to [Any other backend](#any-other-backend).
 
 ---
 
-## Features
+## How it fits together
 
-- Capture all HTTP requests & responses
-- Capture all errors and exceptions
-- Queue and batch events to Midline Cloud
-- Mask sensitive fields (passwords, tokens, etc.)
-- Non-blocking, minimal boilerplate
-- Works with Express, and with anything that accepts Express-style middleware (NestJS, Fastify via `middie`)
+There are two separate things, and the agent never confuses them:
 
----
+| | What it is | Configured with |
+| --- | --- | --- |
+| **Midline server** (control plane) | Where events, API keys, logs, analytics and security data live. `https://api.usemidline.com` | `endpoint` / `MIDLINE_ENDPOINT`, `apiKey` / `MIDLINE_API_KEY`, `ca` / `MIDLINE_CUSTOM_CA` |
+| **Destination API** (data plane) | The API being monitored — local, staging or production | `target` / `TARGET_API_URL`, `targetCa` / `TARGET_API_CA` (proxy mode only) |
 
-## Getting Started
+Your traffic never goes through the Midline server. The agent runs next to your API, observes each
+request, and ships a redacted event to Midline in the background:
 
-### 1. Sign up on Midline Cloud
+```
+                 ┌──────────────── your infrastructure ────────────────┐
+client ────────► │  midline-agent  ──────────────►  destination API    │
+                 │  (middleware in your app, or proxy in front of it)  │
+                 └───────┬─────────────────────────────────────────────┘
+                         │ events, batched, redacted, async (HTTPS, verified)
+                         ▼
+               https://api.usemidline.com
+```
 
-Visit [https://midline.com](https://midline.com) and create an account.  
-After login, navigate to your **Dashboard → API Keys** and generate a key for your application.
+That is deliberate. If Midline is down, slow or misconfigured, your API keeps serving and only
+telemetry is buffered. A hosted gateway that sits in the request path can't do that, and it can't
+reach `http://localhost:4000` on your laptop at all.
+
+Two ways to run the agent:
+
+- **Middleware** — inside an Express/NestJS/Node app. No extra hop.
+- **Proxy** — a small reverse proxy in front of any HTTP API, in any language. `TARGET_API_URL`
+  decides where requests go.
 
 ---
 
-### 2. Install Package
+## Install
 
 ```bash
 npm install midline-agent
 ```
 
-Choose one of the guides below based on your framework.
+Get a project API key from the Midline dashboard (**Project → API Keys**).
 
 ---
 
-## Framework Setup
+## Middleware mode
 
-### Express.js
-
-```bash
-npm install midline-agent express
-```
+### Express
 
 ```ts
 import express from "express";
 import { MidlineAgent, midlineMiddleware, midlineErrorHandler } from "midline-agent";
 
-const app = express();
-
-// Initialize Midline Agent (do this once, early in your app startup)
 MidlineAgent.init({
-  apiKey: process.env.MIDLINE_KEY!,
+  apiKey: process.env.MIDLINE_API_KEY,
   serviceName: "checkout-api",
-  environment: "production",
-  maskFields: ["password", "token", "card_number", "cvv"]
+  environment: process.env.NODE_ENV,
 });
 
-// Parse incoming JSON
+const app = express();
+app.use(midlineMiddleware());   // before your routes
 app.use(express.json());
 
-// Add request capture middleware BEFORE your routes
-app.use(midlineMiddleware());
-
-// Your routes here
-app.get("/health", (req, res) => res.json({ status: "ok" }));
-app.post("/v1/charges", async (req, res) => {
-  // Handle payment processing
-  res.json({ success: true });
-});
-
-// Add error handler middleware AFTER your routes
-// This must be the last middleware registered
-app.use(midlineErrorHandler());
+app.post("/v1/charges", (req, res) => res.json({ ok: true }));
 
-app.listen(3000, () => console.log("Server running on port 3000"));
+app.use(midlineErrorHandler()); // after your routes; passes the error on untouched
+app.listen(3000);
 ```
 
-**Key points:**
-- `MidlineAgent.init()` must be called once during app startup
-- `midlineMiddleware()` captures all requests and responses
-- `midlineErrorHandler()` must be registered **after** all other middleware and routes
-- Express only routes errors to handlers declared after the code that threw, so order matters
+### NestJS
 
----
+```ts
+import { NestFactory } from "@nestjs/core";
+import { MidlineAgent, midlineMiddleware } from "midline-agent";
+import { AppModule } from "./app.module";
 
-### NestJS
+async function bootstrap() {
+  MidlineAgent.init({
+    apiKey: process.env.MIDLINE_API_KEY,
+    serviceName: "nest-api",
+    environment: process.env.NODE_ENV,
+  });
 
-```bash
-npm install midline-agent
+  const app = await NestFactory.create(AppModule);
+  app.use(midlineMiddleware());
+  app.enableShutdownHooks();
+  await app.listen(3000);
+}
+bootstrap();
+
+// On shutdown (e.g. in onApplicationShutdown): await MidlineAgent.shutdown();
 ```
 
-**Using with NestJS requires wrapping the Express middleware. Here's the setup:**
+Nest handles exceptions in its own filters, so they rarely reach Express error middleware. The
+request middleware still records every 4xx/5xx response.
+
+### Plain Node `http`
 
 ```ts
-import { NestFactory } from '@nestjs/core';
-import { AppModule } from './app.module';
-import { MidlineAgent, midlineMiddleware, midlineErrorHandler } from 'midline-agent';
+import http from "http";
+import { MidlineAgent, midlineMiddleware } from "midline-agent";
 
-async function bootstrap() {
-  const app = await NestFactory.create(AppModule);
+MidlineAgent.init({ apiKey: process.env.MIDLINE_API_KEY, serviceName: "raw-node" });
+const midline = midlineMiddleware();
 
-  // Initialize Midline Agent early in bootstrap
-  MidlineAgent.init({
-    apiKey: process.env.MIDLINE_KEY!,
-    serviceName: 'nest-api',
-    environment: process.env.NODE_ENV || 'development',
-    maskFields: ['password', 'token', 'apiKey', 'secret']
+http.createServer((req, res) => {
+  midline(req, res, () => {
+    res.writeHead(200, { "content-type": "application/json" });
+    res.end('{"ok":true}');
   });
+}).listen(3000);
+```
 
-  // Apply request capture middleware
-  app.use(midlineMiddleware());
+---
 
-  // Apply error handler after NestJS is configured
-  app.use(midlineErrorHandler());
+## Proxy mode
 
-  await app.listen(3000);
-}
+Put the agent in front of any API — Node or not — without touching its code:
 
-bootstrap();
+```bash
+MIDLINE_API_KEY=... TARGET_API_URL=http://localhost:4000 npx midline-agent proxy --port 8080
+# clients now call http://localhost:8080 instead of :4000
 ```
 
-**For module-level integration, create a middleware:**
+The same binary, pointed elsewhere:
 
-```ts
-// midline.middleware.ts
-import { Injectable, NestMiddleware } from '@nestjs/common';
-import { midlineMiddleware, midlineErrorHandler } from 'midline-agent';
-import { Request, Response, NextFunction } from 'express';
-
-@Injectable()
-export class MidlineMiddleware implements NestMiddleware {
-  use(req: Request, res: Response, next: NextFunction) {
-    midlineMiddleware()(req, res, next);
-  }
-}
+```bash
+TARGET_API_URL=https://staging.example.com npx midline-agent proxy
+TARGET_API_URL=https://api.example.com     npx midline-agent proxy --host 0.0.0.0
 ```
 
-Then apply it in your module:
+Or from code:
 
 ```ts
-import { Module, MiddlewareConsumer } from '@nestjs/common';
-import { MidlineMiddleware } from './midline.middleware';
-
-@Module({
-  imports: [],
-  controllers: [],
-  providers: [],
-})
-export class AppModule {
-  configure(consumer: MiddlewareConsumer) {
-    consumer
-      .apply(MidlineMiddleware)
-      .forRoutes('*');
-  }
-}
+import { startMidlineProxy } from "midline-agent";
+
+await startMidlineProxy({
+  target: process.env.TARGET_API_URL,          // required; never defaulted
+  port: 8080,
+  midline: { apiKey: process.env.MIDLINE_API_KEY, serviceName: "orders-gateway" },
+});
 ```
 
+`createMidlineProxy(options)` returns a plain `(req, res)` handler if you want your own server.
+
+What the proxy does per request:
+
+- Forwards method, path, query, headers and body to the target, streaming both ways
+- Strips hop-by-hop headers; sets `Host` to the target (unless `preserveHost`), adds `X-Forwarded-*`,
+  `X-Request-Id` and `X-Correlation-Id`
+- Only accepts origin-form request lines (`GET /path`). It can't be used as an open forward proxy.
+- Answers `502` if the destination is unreachable, `504` if it's too slow (`timeoutMs`, default
+  30s), `413` if the body exceeds `maxRequestBodyBytes` (default 10 MiB). Error bodies carry a
+  `requestId` and no internal detail.
+- Retries (`retries`, default 0) only `GET`/`HEAD`/`OPTIONS` without a body, and only when the
+  request never reached the destination. A write is never replayed.
+- Records the exchange — including destination failures as `infrastructure` errors — to Midline
+
+WebSocket upgrades are not proxied.
+
 ---
 
-### Plain Node.js / HTTP Server
+## TLS
 
-If you're not using Express or NestJS, you can integrate midline-agent by manually wrapping your request handlers:
+**Certificate verification is always on**, for both the Midline server and the destination.
+There is no option to turn it off, and the agent never sets `rejectUnauthorized: false`.
+
+### The Midline server
+
+`https://api.usemidline.com` has a publicly trusted certificate, so nothing needs configuring. If
+verification ever fails, you'll see one line like:
+
+```
+midline: https://api.usemidline.com presented a self-signed certificate (DEPTH_ZERO_SELF_SIGNED_CERT),
+so the connection was refused. Certificate verification stays on. ...
+Delivery resumes on its own once a trusted certificate is served. 12 event(s) buffered; your application is unaffected.
+```
+
+That is a server-side problem, not something to work around in your app. Events stay buffered and
+delivery resumes on its own once the server is fixed — no restart needed.
+
+For a **self-hosted** Midline server behind a private CA, trust that CA for the Midline connection
+only:
 
 ```ts
-import http from 'http';
-import { MidlineAgent, midlineMiddleware, midlineErrorHandler } from 'midline-agent';
+MidlineAgent.init({ apiKey, endpoint: "https://midline.internal", ca: fs.readFileSync("/etc/ssl/internal-ca.pem") });
+```
 
-MidlineAgent.init({
-  apiKey: process.env.MIDLINE_KEY!,
-  serviceName: 'raw-node-server',
-  environment: 'production',
-  maskFields: ['password', 'token']
-});
+```bash
+MIDLINE_CUSTOM_CA=/etc/ssl/internal-ca.pem   # PEM text also works
+```
 
-const server = http.createServer((req, res) => {
-  // Create Express-like req/res wrapper for middleware
-  const next = (err?: any) => {
-    if (err) throw err;
-    // Handle your route
-    if (req.url === '/health') {
-      res.writeHead(200, { 'Content-Type': 'application/json' });
-      res.end(JSON.stringify({ status: 'ok' }));
-    } else {
-      res.writeHead(404);
-      res.end('Not Found');
-    }
-  };
-
-  midlineMiddleware()(req, res, next);
-});
+The CA is **added** to Node's default trust store, not substituted for it. Hostname checks still
+apply.
 
-server.listen(3000, () => console.log('Server listening on port 3000'));
+`endpoint` must be `https://`. Plain `http://` is only accepted for `localhost`/`127.0.0.1` (running
+a Midline server on your own machine), so the API key never crosses a network in cleartext.
+
+### The destination (proxy mode)
+
+A local destination is fine over plain HTTP: `TARGET_API_URL=http://localhost:4000`. That doesn't
+relax anything about the Midline connection.
+
+For an HTTPS destination signed by a private/internal CA:
+
+```bash
+TARGET_API_URL=https://orders.internal TARGET_API_CA=/etc/ssl/internal-ca.pem npx midline-agent proxy
 ```
 
+`TARGET_API_CA` and `MIDLINE_CUSTOM_CA` are independent. Trusting a CA for one never trusts it for
+the other.
+
 ---
 
-## Configuration Options
+## Configuration
 
 ```ts
 MidlineAgent.init({
-  // Required
-  apiKey: string;                  // Get from https://midline.com/dashboard/api-keys
-  serviceName: string;              // Name of your service (e.g., "checkout-api", "auth-service")
-
-  // Optional
-  maskFields?: string[];            // Field names to mask before sending (passwords, tokens, etc)
-  environment?: string;             // e.g., "production", "staging", "development"
-  endpoint?: string;                // Override default ingest URL (for self-hosted)
-  host?: string;                    // Machine/pod name for identifying instances
-  region?: string;                  // Deployment region (e.g., "us-east-1", "eu-west-1")
+  apiKey: string,                 // MIDLINE_API_KEY
+  serviceName?: string,           // MIDLINE_SERVICE_NAME
+  endpoint?: string,              // MIDLINE_ENDPOINT — default https://api.usemidline.com (base or full ingest URL)
+  ca?: string | Buffer | Array,   // MIDLINE_CUSTOM_CA — extra CA for the Midline server only
+  environment?: string,           // MIDLINE_ENVIRONMENT
+  release?: string,               // MIDLINE_RELEASE
+  host?: string,
+  region?: string,
+  enabled?: boolean,              // MIDLINE_ENABLED=false keeps the agent inert
+
+  // What to capture beyond method, path, status and timing. All off by default.
+  capture?: {
+    headers?: boolean,
+    query?: boolean,
+    requestBody?: boolean,        // whatever your body parser produced (req.body)
+    responseBody?: boolean,
+    maxBodyBytes?: number,        // default 4096
+  },
+  redactFields?: string[],        // added to the built-in list (maskFields still works)
+  redactHeaders?: string[],
+  captureConsole?: boolean,       // MIDLINE_CAPTURE_CONSOLE — also send what the process prints (off by default)
+
+  // Delivery
+  flushIntervalMs?: number,       // default 1500
+  timeoutMs?: number,             // whole request deadline, default 10000
+  connectTimeoutMs?: number,      // TCP + TLS handshake, default 5000
+  maxBatchSize?: number,          // default 100
+  maxQueueSize?: number,          // default 1000; oldest dropped past this
+  maxEventBytes?: number,         // default 65536; bodies dropped first
+  maxRetryDelayMs?: number,       // backoff cap, default 300000
+
+  onError?: (message: string) => void, // route diagnostics to your logger
+  debug?: boolean,                // MIDLINE_DEBUG — log every diagnostic, not one per fault
 });
 ```
 
----
+### Environment
+
+```env
+MIDLINE_API_KEY=...
+MIDLINE_ENDPOINT=https://api.usemidline.com
+# MIDLINE_CAPTURE_CONSOLE=true
+
+# proxy mode
+TARGET_API_URL=http://localhost:4000
+# TARGET_API_CA=/etc/ssl/internal-ca.pem
+# TARGET_API_TIMEOUT_MS=30000
+# TARGET_API_RETRIES=0
+# MIDLINE_PROXY_PORT=8080
+# MIDLINE_PROXY_HOST=127.0.0.1
+```
 
-## Sensitive Field Masking
+---
 
-By default, `maskFields` removes the following fields before serialization:
-- `password`
-- `token`
-- `apiKey`
-- `secret`
-- `authorization`
+## Console output
 
-Add custom fields as needed:
+Set `captureConsole: true` (or `MIDLINE_CAPTURE_CONSOLE=true`) and whatever the process prints
+shows up on the dashboard's Logs page as `console` events, one per line, next to your requests. That
+covers `console.log`, Nest's logger, pino, winston: anything written to stdout or stderr.
 
 ```ts
-MidlineAgent.init({
-  apiKey: process.env.MIDLINE_KEY!,
-  serviceName: 'checkout-api',
-  maskFields: [
-    'password',
-    'card_number',
-    'cvv',
-    'ssn',
-    'oauth_token',
-    'jwt'
-  ]
-});
+MidlineAgent.init({ apiKey: process.env.MIDLINE_API_KEY, captureConsole: true });
+const app = await NestFactory.create(AppModule); // startup lines are captured from here on
 ```
 
-**Important:** Masking happens in your process before the event is built. Masked values never leave your machine and are never stored on Midline servers.
+- Initialise the agent before creating the app. Anything printed before `init()` isn't captured.
+- Your terminal output doesn't change. The agent reads each write after it has happened.
+- Colour codes are stripped, each line is capped at 4096 characters, and lines are redacted like any
+  other text.
+- Severity comes from the line: `ERROR` or `FATAL` is high, `WARN` is medium, other stderr output is
+  medium, and everything else is low.
+- Up to 100 lines a second are sent, with room for a 1,000-line burst such as Nest mapping its routes
+  at startup. Lines past that still print but aren't sent.
+- Printed lines don't count towards request totals, error rates or latency.
+- It needs a Midline server that knows the `console` event type. An older server refuses the first
+  line; the agent then turns console capture off, says so once, and keeps sending requests and errors.
+- The agent's own diagnostics are never captured.
+
+---
+
+## Sensitive data
+
+Redaction happens **in your process, before an event is queued**. What's masked never reaches a
+socket, a log line or the Midline server. The server redacts again on ingest as a second line of
+defence.
+
+- **Headers, always masked when captured:** `Authorization`, `Proxy-Authorization`, `Cookie`,
+  `Set-Cookie`, `X-API-Key`, `API-Key`, `X-Auth-Token`, `X-Access-Token`, `X-Refresh-Token`,
+  `X-CSRF-Token`, `X-XSRF-Token`, `X-Amz-Security-Token`, plus anything matching the field rules below.
+- **Fields, at any depth, in bodies, queries and payloads.** Matched case- and
+  punctuation-insensitively, so `api_key`, `apiKey` and `X-API-Key` are the same key. Anything
+  containing `password`, `passwd`, `passphrase`, `secret`, `token`, `apikey`, `accesskey`,
+  `privatekey`, `authorization`, `cookie`, `session`, `credential`, `csrf`, `xsrf`, `signature`,
+  `creditcard`, `cardnumber`, `cvv`, `cvc`, `ssn`, `socialsecurity`; and the exact keys `auth`,
+  `pwd`, `pin`, `otp`, `sid`, `jwt`, `bearer`.
+- **Values inside any text** — error messages, stack traces, routes, console lines: bearer/basic credentials,
+  JWTs, Midline keys (`ak_…`), Stripe and AWS key formats, PEM private keys, `user:pass@` in URLs,
+  and `key=value` / `"key": value` pairs whose key is sensitive.
+- Query strings are never part of `route`.
+- Bodies are only captured if you turn them on. They're capped at `maxBodyBytes`, and compressed or
+  binary bodies are skipped.
+
+The lists err on the side of masking (`tokenCount` is masked too). Extend them with `redactFields`
+and `redactHeaders`.
 
 ---
 
-## Error Handling
+## Delivery and failure behaviour
 
-The error handler middleware captures:
-- Unhandled errors thrown by your route handlers
-- HTTP error responses
-- Validation errors
+The agent's contract is that the Midline server can never break your application.
 
-**Example with error throwing:**
+- Recording happens after the response is handed to the socket; nothing waits on the network
+- Events are batched (`POST /api/api-monitor/events/batch`) with the key in the `X-API-Key` header
+- **Unreachable, DNS failure, timeout, TLS failure, 5xx, 408, 429:** events stay buffered.
+  Retries use exponential backoff with jitter, capped by `maxRetryDelayMs`, and honour `Retry-After`.
+- **401/403:** the key is wrong. The agent logs once and turns itself off — retrying can't fix it.
+- **413:** the batch is split and retried; a single event that's still too large is dropped
+- **Other 4xx:** the batch is re-sent one event at a time, so a malformed event only costs itself
+- **Redirects** are never followed, because that would hand the API key to wherever they point
+- One log line per distinct fault, and one when delivery recovers
+- The buffer is bounded (`maxQueueSize`, 16 MB total); past that, the oldest events go first
+- The flush timer and background sockets are `unref`'d, so telemetry never keeps your process alive
+
+Events still in memory are lost if the process crashes. That's fine for operational telemetry, but
+not for billing or audit. On graceful shutdown:
 
 ```ts
-app.post('/v1/charges', (req, res, next) => {
-  try {
-    if (!req.body.amount) {
-      throw new Error('Amount is required');
-    }
-    // Process payment...
-  } catch (error) {
-    next(error); // Pass to Midline error handler
-  }
+process.on("SIGTERM", async () => {
+  await MidlineAgent.shutdown(5000); // flush with a deadline, then close
+  process.exit(0);
 });
-
-// The error handler will capture and report this
-app.use(midlineErrorHandler());
 ```
 
----
+### Request and correlation IDs
 
-## How Delivery Works
+Every request gets a `requestId`: an incoming `X-Request-Id` if it's sane, otherwise a UUID. It also
+gets a `correlationId`: `X-Correlation-Id` if present, otherwise the request ID. A W3C
+`traceparent` header becomes `traceId`/`spanId`. Read them in your own code to stamp logs:
 
-- Events are queued in memory and flushed to Midline Cloud every 1.5 seconds
-- Request capturing is non-blocking — your response is sent before telemetry is reported
-- No network call can slow down your API responses
-
-**Important for production:**
-- In-memory events are lost if your process crashes before the flush interval
-- This is acceptable for monitoring telemetry (good for operations, not billing/audit)
-- For high-traffic services, consider using the batch endpoint directly for reliability
+```ts
+import { getRequestContext } from "midline-agent";
+app.get("/x", (req, res) => { logger.info({ requestId: getRequestContext(req)?.requestId }); });
+```
 
 ---
 
-## Not using Node.js? Any other backend
+## Any other backend
 
-This agent does two things: it turns a request or an error into an event, and it POSTs that event to
-the Midline ingest API. Both are things your own service can do directly, in whatever language it
-is written in.
+The agent does two things: it turns a request or an error into an event, and it POSTs that event to
+the Midline ingest API. Your own service can do both directly, in whatever language it's written in
+— or run `midline-agent proxy` in front of it.
 
 **Endpoints**
 
 | Endpoint | Use |
 | --- | --- |
 | `POST https://api.usemidline.com/api/api-monitor/events` | One event |
-| `POST https://api.usemidline.com/api/api-monitor/events/batch` | Many events — `{ "events": [ … ] }` |
+| `POST https://api.usemidline.com/api/api-monitor/events/batch` | Many events — `{ "events": [ … ] }`, up to 500 |
 
-The API key identifies your organisation and travels in the body; there is no separate auth header.
+Authenticate with the `X-API-Key` header. An `apiKey` field in the body is still accepted.
 
 **Event shape**
 
 | Field | Required | Notes |
 | --- | --- | --- |
-| `apiKey` | yes | From Dashboard → API Keys |
 | `eventType` | yes | `request` · `error` · `security` · `performance` · `custom` |
-| `route` | yes | The route that produced the event, e.g. `/v1/charges` |
+| `route` | yes | Path only, e.g. `/v1/charges` |
 | `method` | no | HTTP method |
 | `statusCode` | no | 100–599 |
 | `responseTime` | no | Milliseconds |
 | `severity` | no | `low` · `medium` · `high` · `critical` |
 | `category` | no | `application` · `infrastructure` · `security` · `performance` · `business` |
-| `service` | no | Which service reported it |
-| `environment` | no | e.g. `production` |
-| `timestamp` | no | ISO 8601; defaults to server time |
-| `payload` | no | Free-form context — error message, stack, anything you need |
+| `service` / `environment` / `release` | no | Where it came from |
+| `timestamp` | no | ISO 8601; clamped to server time if implausibly far off |
+| `requestId` / `correlationId` / `traceId` | no | For joining events across services |
+| `payload` | no | Free-form context — error message, stack, captured request/response |
+| `metadata` | no | Free-form, e.g. SDK name and version |
 
-Mask sensitive fields in your own process, before you build the payload. Nothing you do not send can
+Mask sensitive fields in your own process before you build the payload. Nothing you don't send can
 be stored.
 
-**curl**
-
 ```bash
 curl -X POST https://api.usemidline.com/api/api-monitor/events \
   -H "Content-Type: application/json" \
+  -H "X-API-Key: $MIDLINE_API_KEY" \
   -d '{
-    "apiKey": "YOUR_API_KEY",
     "eventType": "error",
     "service": "checkout-api",
     "route": "/v1/charges",
@@ -343,67 +424,50 @@ curl -X POST https://api.usemidline.com/api/api-monitor/events \
   }'
 ```
 
-**Python (Django / Flask / FastAPI)**
-
 ```python
-import requests, threading
+import os, threading, requests
 
 INGEST = "https://api.usemidline.com/api/api-monitor/events"
 
 def report(event: dict) -> None:
-    event["apiKey"] = MIDLINE_KEY
-    event.setdefault("service", "checkout-api")
-    # off the request path - never make your user wait on telemetry
+    # off the request path - never make a user wait on telemetry
     threading.Thread(
-        target=lambda: requests.post(INGEST, json=event, timeout=3),
+        target=lambda: requests.post(INGEST, json=event, headers={"X-API-Key": os.environ["MIDLINE_API_KEY"]}, timeout=3),
         daemon=True,
     ).start()
-
-report({
-    "eventType": "error",
-    "route": "/v1/charges",
-    "method": "POST",
-    "statusCode": 500,
-    "severity": "critical",
-    "category": "application",
-    "payload": {"error": str(exc)},
-})
 ```
 
-**Go**
-
 ```go
-type Event struct {
-    APIKey     string `json:"apiKey"`
-    EventType  string `json:"eventType"`
-    Route      string `json:"route"`
-    Method     string `json:"method"`
-    StatusCode int    `json:"statusCode"`
-    Severity   string `json:"severity"`
-    Service    string `json:"service"`
-}
-
-func Report(e Event) {
-    e.APIKey = os.Getenv("MIDLINE_KEY")
-    body, _ := json.Marshal(e)
-    go http.Post(
-        "https://api.usemidline.com/api/api-monitor/events",
-        "application/json",
-        bytes.NewReader(body),
-    ) // fire and forget
+func Report(body []byte) {
+    go func() {
+        req, _ := http.NewRequest("POST", "https://api.usemidline.com/api/api-monitor/events", bytes.NewReader(body))
+        req.Header.Set("Content-Type", "application/json")
+        req.Header.Set("X-API-Key", os.Getenv("MIDLINE_API_KEY"))
+        client := &http.Client{Timeout: 3 * time.Second}
+        if resp, err := client.Do(req); err == nil {
+            resp.Body.Close()
+        }
+    }()
 }
 ```
 
-Send events from a goroutine, background thread or queue worker — the same rule the Node agent
-follows. Telemetry should never be able to slow down or fail a response.
+Same rule everywhere: send events from a goroutine, a background thread or a queue worker. Keep TLS
+verification on. Telemetry should never be able to slow down or fail a response.
+
+---
+
+## Upgrading from 0.1.x
 
-**No code at all**
+- `insecureTLS` / `MIDLINE_INSECURE_TLS` are gone (they were never published). Fix the server's
+  certificate, or pass the private CA with `ca` / `MIDLINE_CUSTOM_CA`.
+- `endpoint` can now be just `https://api.usemidline.com`; full ingest URLs still work.
+- `maskFields` used to be accepted and ignored. It's now honoured, as an alias for `redactFields`.
+- `serviceName` is optional; `MIDLINE_API_KEY` / `MIDLINE_ENDPOINT` are read if not passed.
+- `cross-fetch` is no longer a dependency; Node 18+ is required.
+- New: `MidlineAgent.shutdown(timeoutMs)` flushes with a deadline and stops the agent.
+- The agent sends the key both in the `X-API-Key` header and in each event body. That keeps it
+  compatible with Midline servers that predate header auth.
 
-If you would rather not touch the service, put it behind the Midline gateway instead: point traffic
-at your fence URL and every request is authenticated, scanned, logged and forwarded upstream
-unchanged. That path is language-agnostic by construction — the gateway never knows or cares what
-your backend is written in.
+## License
 
-### License
 MIT
-# Midline-agent