@nest-rn-lens/nest 0.1.1 → 0.2.0

package/README.md

@@ -4,14 +4,15 @@
 
 A NestJS interceptor that records every request your API handles: the app and
 the exact file and line that sent it, the endpoint and the handler that answered,
-the status, and the time it took.
+the status, the time it took, and the request and response bodies (with secrets
+redacted).
 
 ```
 [NestRnLens] mobile (ios) apps/mobile/src/screens/order-details.tsx:23 → GET /orders/:id → OrdersController.findOne 200 4ms
 ```
 
 It is the server half of **NestRN Lens**, a toolkit for Turborepo monorepos with
-a NestJS API and a React Native (Expo) app. On its own it gives you readable
+a NestJS API and a React Native (Expo) or Next.js app. On its own it gives you readable
 request logs and a typed event for every call. With the [NestRN Lens VS Code
 extension](https://marketplace.visualstudio.com/items?itemName=IsaiasDiaz.nest-rn-lens), those events become a live traffic panel where you can click any
 request to open the screen that made it or the handler that answered it.
@@ -64,6 +65,22 @@ That's it. Every request handled by a controller is now logged:
 Requests show `unknown` until the client says who it is. The next section
 explains how.
 
+## Step by step with React Native or Next.js
+
+1. **API:** install the package and add `NestRnLensModule.forRoot({ app: 'api' })`
+   to your root module (above).
+2. **API:** enable CORS in development (`app.enableCors()` in `main.ts`), since
+   web builds call the API from another origin. See [Browsers and CORS](#browsers-and-cors).
+3. **App:** route your API calls through one helper that adds the
+   `x-nest-rn-lens-app` header (and, on the web, `x-nest-rn-lens-caller` with
+   `window.location.pathname`), only in development.
+4. **Watch:** read the log lines, use `onEvent`, or open the
+   [NestRN Lens VS Code extension](https://marketplace.visualstudio.com/items?itemName=IsaiasDiaz.nest-rn-lens),
+   which starts everything and shows the traffic live.
+
+Copy-paste helpers for React Native (Expo) and Next.js are in the extension's
+guide: [Integrate your app, step by step](https://github.com/isa95Ar/nest-rn-lens-vscode#integrate-your-app-step-by-step).
+
 ## Telling the API who's calling
 
 A request on its own doesn't say which app or which screen sent it. The client
@@ -72,7 +89,7 @@ adds that with three headers:
 | Header                    | Example                                         | Used for                                          |
 | ------------------------- | ----------------------------------------------- | ------------------------------------------------- |
 | `x-nest-rn-lens-app`      | `mobile`                                        | Which app made the request                        |
-| `x-nest-rn-lens-caller`   | `/repo/apps/mobile/src/screens/orders.tsx:23`   | The file and line that made it                    |
+| `x-nest-rn-lens-caller`   | `/repo/apps/mobile/src/screens/orders.tsx:23`   | The file and line that made it, or the page path for web apps (`/orders/42`) |
 | `x-nest-rn-lens-trace-id` | `5f0c…`                                         | Linking every hop of one request chain            |
 
 You don't have to write these by hand. The upcoming React Native client,
@@ -105,6 +122,9 @@ NestRnLensModule.forRoot({
   enabled: true,
   log: true,
   onEvent: (event) => {},
+  captureBodies: true,
+  maxBodyBytes: 16 * 1024,
+  redactKeys: ['pin'],
 });
 ```
 
@@ -114,6 +134,9 @@ NestRnLensModule.forRoot({
 | `enabled` | `boolean`                         | `true` unless `NODE_ENV=production`  | Turns the interceptor on or off. When off, requests pass through untouched.                   |
 | `log`     | `boolean`                         | `true`                               | Logs a readable line per request, plus the full event as JSON at debug level.                 |
 | `onEvent` | `(event: NestRnLensEvent) => void` | none                                 | Called with every event. Forward traffic to your own tooling, tests or metrics.               |
+| `captureBodies` | `boolean`                   | `true`                               | Adds the request (headers, query, route params, body) and the response body to each event.    |
+| `maxBodyBytes`  | `number`                    | `16384` (16 KB)                      | Bodies larger than this are cut to a preview of that many characters.                          |
+| `redactKeys`    | `string[]`                  | `[]`                                 | Extra field or header names to hide, added to the built-in list (see below).                   |
 
 ### The event
 
@@ -138,13 +161,61 @@ interface NestRnLensEvent {
   };
   status: number; // 200, 201, 404, 500…
   error?: string; // exception message, when the handler threw
+  request?: {
+    headers: Record<string, string>; // sensitive ones redacted
+    query?: unknown; // { type: "water" }
+    params?: unknown; // { id: "42" } for /orders/:id
+    body?: CapturedBody;
+  };
+  response?: {
+    body?: CapturedBody; // the handler's return value, or the error body Nest sends
+  };
+}
+
+interface CapturedBody {
+  size: number; // bytes, once serialized
+  value?: unknown; // the body, redacted (absent when truncated or summarized)
+  truncated?: boolean; // larger than maxBodyBytes...
+  preview?: string; // ...so this holds its start
+  summary?: string; // "[binary 12.0 KB]", "[stream]" for non-JSON bodies
 }
 ```
 
+`request` and `response` are present when `captureBodies` is on (the default).
+
 `route` is the route pattern, not the URL, so all calls to one endpoint group
 together. `status` follows Nest's rules: `@HttpCode()` when set, `201` for
 `POST`, the exception's status when a handler throws, and `500` for other errors.
 
+## Request and response bodies
+
+Each event carries what the client sent and what the API answered, so you can
+see the data behind every request, not just its status:
+
+- **Request:** headers, query parameters, route parameters and the parsed body.
+- **Response:** the value the handler returned. When a handler throws, it's the
+  error body Nest sends, for example
+  `{ "statusCode": 404, "message": "Order #42 not found", "error": "Not Found" }`.
+
+**Secrets are redacted.** Any field or header whose name contains one of these
+words is replaced with `"[redacted]"`, at any depth, in bodies, query, params
+and headers:
+
+`password`, `passwd`, `secret`, `token`, `authorization`, `cookie`, `apiKey`,
+`privateKey`, `creditCard`, `cardNumber`, `cvv`, `ssn`
+
+Matching ignores case and separators, so `api_key`, `API-Key` and `apiKey` are
+all covered, and `token` also hides `accessToken` and `refreshToken`. Add your
+own with `redactKeys`.
+
+**Large and binary bodies are summarized.** A body bigger than `maxBodyBytes`
+(16 KB by default) keeps only a text preview of its start. Files and streams
+(`StreamableFile`, buffers) show as `[binary 12.0 KB]` or `[stream]`, and are
+never read.
+
+Turn it all off with `captureBodies: false`, for example if your API handles
+data that shouldn't appear in development logs at all.
+
 ## Safe by design
 
 NestRN Lens is a development tool. It is built so that it can't hurt the API it
@@ -155,6 +226,8 @@ watches:
 - **Never breaks a request.** If your `onEvent` callback or the logger throws,
   the error is swallowed and the response goes out as usual.
 - **Doesn't change responses.** The only thing it adds is the trace id header.
+- **Redacts secrets.** Passwords, tokens, cookies and similar fields never
+  appear in captured bodies or headers (see above).
 - **HTTP only.** Microservice, WebSocket and GraphQL contexts pass straight
   through.
 

package/dist/cjs/capture.d.ts

@@ -0,0 +1,25 @@
+import type { CapturedBody } from './types.js';
+export declare const DEFAULT_MAX_BODY_BYTES: number;
+/**
+ * Field and header names whose values are never captured, matched ignoring case
+ * and separators ("api_key", "apiKey" and "API-Key" are the same).
+ */
+export declare const DEFAULT_REDACT_KEYS: string[];
+export declare const REDACTED = "[redacted]";
+export interface CaptureOptions {
+    maxBodyBytes: number;
+    redactKeys: string[];
+}
+export declare function isSensitive(key: string, redactKeys: string[]): boolean;
+/**
+ * Turns a request or response body into something safe to log: sensitive
+ * fields redacted, binary data and streams summarized, and anything larger
+ * than `maxBodyBytes` cut to a text preview.
+ */
+export declare function captureBody(value: unknown, { maxBodyBytes, redactKeys }: CaptureOptions): CapturedBody | undefined;
+/** Request headers with sensitive values replaced. */
+export declare function captureHeaders(headers: Record<string, string | string[] | undefined>, redactKeys: string[]): Record<string, string>;
+/** The body Nest sends for an exception: HttpException's response, or its generic 500. */
+export declare function errorResponseBody(error: unknown): unknown;
+/** Leaves out empty query and params objects: there's nothing to show. */
+export declare function nonEmpty(value: unknown): unknown;

package/dist/cjs/capture.js

@@ -0,0 +1,105 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REDACTED = exports.DEFAULT_REDACT_KEYS = exports.DEFAULT_MAX_BODY_BYTES = void 0;
+exports.isSensitive = isSensitive;
+exports.captureBody = captureBody;
+exports.captureHeaders = captureHeaders;
+exports.errorResponseBody = errorResponseBody;
+exports.nonEmpty = nonEmpty;
+const common_1 = require("@nestjs/common");
+exports.DEFAULT_MAX_BODY_BYTES = 16 * 1024;
+/**
+ * Field and header names whose values are never captured, matched ignoring case
+ * and separators ("api_key", "apiKey" and "API-Key" are the same).
+ */
+exports.DEFAULT_REDACT_KEYS = [
+    'password',
+    'passwd',
+    'secret',
+    'token',
+    'authorization',
+    'cookie',
+    'apikey',
+    'privatekey',
+    'creditcard',
+    'cardnumber',
+    'cvv',
+    'ssn',
+];
+exports.REDACTED = '[redacted]';
+const normalize = (key) => key.toLowerCase().replace(/[^a-z0-9]/g, '');
+function isSensitive(key, redactKeys) {
+    const name = normalize(key);
+    return name.length > 0 && redactKeys.some((pattern) => name.includes(normalize(pattern)));
+}
+/**
+ * Turns a request or response body into something safe to log: sensitive
+ * fields redacted, binary data and streams summarized, and anything larger
+ * than `maxBodyBytes` cut to a text preview.
+ */
+function captureBody(value, { maxBodyBytes, redactKeys }) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (isBinary(value)) {
+        return { size: value.byteLength, summary: `[binary ${formatBytes(value.byteLength)}]` };
+    }
+    if (isStream(value)) {
+        return { size: 0, summary: '[stream]' };
+    }
+    let json;
+    try {
+        json = JSON.stringify(value, (key, field) => (key && isSensitive(key, redactKeys) ? exports.REDACTED : field));
+    }
+    catch {
+        return { size: 0, summary: '[could not be serialized]' };
+    }
+    if (json === undefined) {
+        return undefined;
+    }
+    const size = Buffer.byteLength(json);
+    if (size > maxBodyBytes) {
+        return { size, truncated: true, preview: json.slice(0, maxBodyBytes) };
+    }
+    return { size, value: JSON.parse(json) };
+}
+/** Request headers with sensitive values replaced. */
+function captureHeaders(headers, redactKeys) {
+    const captured = {};
+    for (const [name, value] of Object.entries(headers)) {
+        if (value === undefined) {
+            continue;
+        }
+        captured[name] = isSensitive(name, redactKeys) ? exports.REDACTED : Array.isArray(value) ? value.join(', ') : value;
+    }
+    return captured;
+}
+/** The body Nest sends for an exception: HttpException's response, or its generic 500. */
+function errorResponseBody(error) {
+    if (error instanceof common_1.HttpException) {
+        const response = error.getResponse();
+        return typeof response === 'string' ? { statusCode: error.getStatus(), message: response } : response;
+    }
+    return { statusCode: 500, message: 'Internal server error' };
+}
+/** Leaves out empty query and params objects: there's nothing to show. */
+function nonEmpty(value) {
+    if (value && typeof value === 'object' && Object.keys(value).length === 0) {
+        return undefined;
+    }
+    return value;
+}
+function isBinary(value) {
+    return value instanceof Uint8Array || value instanceof ArrayBuffer;
+}
+// Readable streams and Nest's StreamableFile.
+function isStream(value) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const candidate = value;
+    return typeof candidate.pipe === 'function' || typeof candidate.getStream === 'function';
+}
+function formatBytes(bytes) {
+    return bytes < 1024 ? `${bytes} B` : `${(bytes / 1024).toFixed(1)} KB`;
+}

package/dist/cjs/http.d.ts

@@ -15,6 +15,10 @@ export interface HttpRequest {
     };
     /** Fastify 3. */
     routerPath?: string;
+    /** Parsed by Nest's body parser (Express) or by Fastify. */
+    body?: unknown;
+    query?: unknown;
+    params?: unknown;
 }
 export interface HttpResponse {
     statusCode: number;

package/dist/cjs/index.d.ts

@@ -1,4 +1,4 @@
 export { NestRnLensModule } from './module.js';
 export { NestRnLensInterceptor } from './interceptor.js';
 export { NEST_RN_LENS_HEADERS } from './types.js';
-export type { NestRnLensEvent, NestRnLensOptions, Platform } from './types.js';
+export type { CapturedBody, NestRnLensEvent, NestRnLensOptions, Platform } from './types.js';

package/dist/cjs/interceptor.d.ts

@@ -11,6 +11,7 @@ export declare class NestRnLensInterceptor implements NestInterceptor {
     private readonly reporter;
     constructor(options: NestRnLensOptions, reporter: NestRnLensReporter);
     intercept(context: ExecutionContext, next: CallHandler): Observable<unknown>;
+    private captureOptions;
     /**
      * The status Nest is about to send. Depending on the platform it may not be
      * written to the response yet, so follow Nest's own rules: @HttpCode(),

package/dist/cjs/interceptor.js

@@ -16,6 +16,7 @@ exports.NestRnLensInterceptor = void 0;
 const common_1 = require("@nestjs/common");
 const node_crypto_1 = require("node:crypto");
 const rxjs_1 = require("rxjs");
+const capture_js_1 = require("./capture.js");
 const constants_js_1 = require("./constants.js");
 const http_js_1 = require("./http.js");
 const reporter_js_1 = require("./reporter.js");
@@ -46,7 +47,15 @@ let NestRnLensInterceptor = class NestRnLensInterceptor {
         const traceId = (0, http_js_1.readHeader)(req, types_js_1.NEST_RN_LENS_HEADERS.traceId) ?? (0, node_crypto_1.randomUUID)();
         // Lets the client, and the next service in the chain, reuse the trace id.
         (0, http_js_1.writeHeader)(res, types_js_1.NEST_RN_LENS_HEADERS.traceId, traceId);
-        const finish = (status, error) => {
+        // Captured before the handler runs, in case it mutates the request.
+        const capture = this.captureOptions();
+        const request = capture && {
+            headers: (0, capture_js_1.captureHeaders)(req.headers, capture.redactKeys),
+            query: captureValue((0, capture_js_1.nonEmpty)(req.query), capture),
+            params: captureValue((0, capture_js_1.nonEmpty)(req.params), capture),
+            body: (0, capture_js_1.captureBody)(req.body, capture),
+        };
+        const finish = (status, error, responseBody) => {
             const event = {
                 id: (0, node_crypto_1.randomUUID)(),
                 traceId,
@@ -67,14 +76,22 @@ let NestRnLensInterceptor = class NestRnLensInterceptor {
                 },
                 status,
                 error,
+                ...(capture && { request, response: { body: (0, capture_js_1.captureBody)(responseBody, capture) } }),
             };
             this.reporter.report(event);
         };
         return next.handle().pipe((0, rxjs_1.tap)({
-            next: () => finish(this.successStatus(context, req, res)),
-            error: (err) => finish(err instanceof common_1.HttpException ? err.getStatus() : 500, err instanceof Error ? err.message : String(err)),
+            next: (body) => finish(this.successStatus(context, req, res), undefined, body),
+            error: (err) => finish(err instanceof common_1.HttpException ? err.getStatus() : 500, err instanceof Error ? err.message : String(err), (0, capture_js_1.errorResponseBody)(err)),
         }));
     }
+    captureOptions() {
+        const { captureBodies, maxBodyBytes, redactKeys } = this.options;
+        if (captureBodies === false) {
+            return undefined;
+        }
+        return { maxBodyBytes: maxBodyBytes ?? capture_js_1.DEFAULT_MAX_BODY_BYTES, redactKeys: redactKeys ?? capture_js_1.DEFAULT_REDACT_KEYS };
+    }
     /**
      * The status Nest is about to send. Depending on the platform it may not be
      * written to the response yet, so follow Nest's own rules: @HttpCode(),
@@ -98,3 +115,7 @@ exports.NestRnLensInterceptor = NestRnLensInterceptor = __decorate([
     __param(0, (0, common_1.Inject)(constants_js_1.NEST_RN_LENS_OPTIONS)),
     __metadata("design:paramtypes", [Object, reporter_js_1.NestRnLensReporter])
 ], NestRnLensInterceptor);
+/** Small values (query, params) keep their structure; their redacted value is all we need. */
+function captureValue(value, capture) {
+    return (0, capture_js_1.captureBody)(value, capture)?.value;
+}

package/dist/cjs/module.js

@@ -10,6 +10,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.NestRnLensModule = void 0;
 const common_1 = require("@nestjs/common");
 const core_1 = require("@nestjs/core");
+const capture_js_1 = require("./capture.js");
 const constants_js_1 = require("./constants.js");
 const interceptor_js_1 = require("./interceptor.js");
 const reporter_js_1 = require("./reporter.js");
@@ -27,6 +28,9 @@ let NestRnLensModule = NestRnLensModule_1 = class NestRnLensModule {
             ...options,
             enabled: options.enabled ?? process.env.NODE_ENV !== 'production',
             log: options.log ?? true,
+            captureBodies: options.captureBodies ?? true,
+            maxBodyBytes: options.maxBodyBytes ?? capture_js_1.DEFAULT_MAX_BODY_BYTES,
+            redactKeys: [...capture_js_1.DEFAULT_REDACT_KEYS, ...(options.redactKeys ?? [])],
         };
         return {
             module: NestRnLensModule_1,

package/dist/cjs/reporter.d.ts

@@ -10,3 +10,9 @@ export declare class NestRnLensReporter {
     private describe;
     private shortPath;
 }
+/**
+ * Callers that are source locations are shown relative to the monorepo root
+ * (clients send absolute paths so editors can open them). Anything else, such as
+ * a web page path like "/orders/42", is shown as sent.
+ */
+export declare function formatCaller(caller: string, repoRoot: string): string;

package/dist/cjs/reporter.js

@@ -13,6 +13,7 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NestRnLensReporter = void 0;
+exports.formatCaller = formatCaller;
 const common_1 = require("@nestjs/common");
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
@@ -48,14 +49,12 @@ let NestRnLensReporter = class NestRnLensReporter {
         const from = [`${source.app} (${source.platform})`, this.shortPath(source.caller)].filter(Boolean).join(' ');
         return `${from} → ${target.method} ${target.route} → ${target.controller}.${target.handler} ${status} ${durationMs}ms`;
     }
-    // Clients send absolute paths (editors need them to open the file); logs are
-    // easier to read relative to the monorepo root.
-    shortPath(file) {
-        if (!file?.startsWith('/')) {
-            return file;
+    shortPath(caller) {
+        if (!caller || !SOURCE_LOCATION.test(caller)) {
+            return caller;
         }
         this.repoRoot ??= findRepoRoot(process.cwd());
-        return (0, node_path_1.relative)(this.repoRoot, file);
+        return formatCaller(caller, this.repoRoot);
     }
 };
 exports.NestRnLensReporter = NestRnLensReporter;
@@ -64,6 +63,16 @@ exports.NestRnLensReporter = NestRnLensReporter = __decorate([
     __param(0, (0, common_1.Inject)(constants_js_1.NEST_RN_LENS_OPTIONS)),
     __metadata("design:paramtypes", [Object])
 ], NestRnLensReporter);
+// "/repo/apps/mobile/src/screens/Orders.tsx:23": an absolute file path plus a line.
+const SOURCE_LOCATION = /^\/.+:\d+$/;
+/**
+ * Callers that are source locations are shown relative to the monorepo root
+ * (clients send absolute paths so editors can open them). Anything else, such as
+ * a web page path like "/orders/42", is shown as sent.
+ */
+function formatCaller(caller, repoRoot) {
+    return SOURCE_LOCATION.test(caller) ? (0, node_path_1.relative)(repoRoot, caller) : caller;
+}
 const ROOT_MARKERS = ['turbo.json', 'pnpm-workspace.yaml', '.git'];
 function findRepoRoot(from) {
     let dir = from;

package/dist/cjs/types.d.ts

@@ -11,6 +11,18 @@ export declare const NEST_RN_LENS_HEADERS: {
     readonly traceId: "x-nest-rn-lens-trace-id";
 };
 export type Platform = 'ios' | 'android' | 'web' | 'unknown';
+/** A request or response body, made safe to log. */
+export interface CapturedBody {
+    /** Size of the serialized body, in bytes. */
+    size: number;
+    /** The body, with sensitive fields redacted. Absent when truncated or summarized. */
+    value?: unknown;
+    /** Set when the body was larger than `maxBodyBytes`; `preview` holds its start. */
+    truncated?: boolean;
+    preview?: string;
+    /** For bodies that aren't JSON: "[binary 12.0 KB]", "[stream]". */
+    summary?: string;
+}
 /** One request, as seen by the API. */
 export interface NestRnLensEvent {
     id: string;
@@ -40,6 +52,20 @@ export interface NestRnLensEvent {
     status: number;
     /** Message of the exception, when the handler threw. */
     error?: string;
+    /** What the client sent. Only present when `captureBodies` is on (the default). */
+    request?: {
+        /** Request headers; sensitive ones redacted. */
+        headers: Record<string, string>;
+        query?: unknown;
+        /** Route parameters, e.g. { id: "42" } for /orders/:id. */
+        params?: unknown;
+        body?: CapturedBody;
+    };
+    /** What the API answered. Only present when `captureBodies` is on (the default). */
+    response?: {
+        /** The handler's return value, or the error body Nest sends for an exception. */
+        body?: CapturedBody;
+    };
 }
 export interface NestRnLensOptions {
     /** Name of this API in the traffic graph, e.g. "api". */
@@ -59,4 +85,19 @@ export interface NestRnLensOptions {
      * debug level that the NestRN Lens VS Code extension reads). Defaults to `true`.
      */
     log?: boolean;
+    /**
+     * Include request and response bodies, query, route params and request
+     * headers in each event. Defaults to `true`. Sensitive fields are redacted
+     * (see `redactKeys`).
+     */
+    captureBodies?: boolean;
+    /** Bodies larger than this are cut to a preview. Defaults to 16 KB. */
+    maxBodyBytes?: number;
+    /**
+     * Extra field or header names to redact, added to the defaults (password,
+     * secret, token, authorization, cookie, apiKey, privateKey, creditCard,
+     * cardNumber, cvv, ssn). Matched ignoring case and separators, anywhere in
+     * the name: "token" also covers "accessToken".
+     */
+    redactKeys?: string[];
 }

package/dist/esm/capture.d.ts

@@ -0,0 +1,25 @@
+import type { CapturedBody } from './types.js';
+export declare const DEFAULT_MAX_BODY_BYTES: number;
+/**
+ * Field and header names whose values are never captured, matched ignoring case
+ * and separators ("api_key", "apiKey" and "API-Key" are the same).
+ */
+export declare const DEFAULT_REDACT_KEYS: string[];
+export declare const REDACTED = "[redacted]";
+export interface CaptureOptions {
+    maxBodyBytes: number;
+    redactKeys: string[];
+}
+export declare function isSensitive(key: string, redactKeys: string[]): boolean;
+/**
+ * Turns a request or response body into something safe to log: sensitive
+ * fields redacted, binary data and streams summarized, and anything larger
+ * than `maxBodyBytes` cut to a text preview.
+ */
+export declare function captureBody(value: unknown, { maxBodyBytes, redactKeys }: CaptureOptions): CapturedBody | undefined;
+/** Request headers with sensitive values replaced. */
+export declare function captureHeaders(headers: Record<string, string | string[] | undefined>, redactKeys: string[]): Record<string, string>;
+/** The body Nest sends for an exception: HttpException's response, or its generic 500. */
+export declare function errorResponseBody(error: unknown): unknown;
+/** Leaves out empty query and params objects: there's nothing to show. */
+export declare function nonEmpty(value: unknown): unknown;

package/dist/esm/capture.js

@@ -0,0 +1,97 @@
+import { HttpException } from '@nestjs/common';
+export const DEFAULT_MAX_BODY_BYTES = 16 * 1024;
+/**
+ * Field and header names whose values are never captured, matched ignoring case
+ * and separators ("api_key", "apiKey" and "API-Key" are the same).
+ */
+export const DEFAULT_REDACT_KEYS = [
+    'password',
+    'passwd',
+    'secret',
+    'token',
+    'authorization',
+    'cookie',
+    'apikey',
+    'privatekey',
+    'creditcard',
+    'cardnumber',
+    'cvv',
+    'ssn',
+];
+export const REDACTED = '[redacted]';
+const normalize = (key) => key.toLowerCase().replace(/[^a-z0-9]/g, '');
+export function isSensitive(key, redactKeys) {
+    const name = normalize(key);
+    return name.length > 0 && redactKeys.some((pattern) => name.includes(normalize(pattern)));
+}
+/**
+ * Turns a request or response body into something safe to log: sensitive
+ * fields redacted, binary data and streams summarized, and anything larger
+ * than `maxBodyBytes` cut to a text preview.
+ */
+export function captureBody(value, { maxBodyBytes, redactKeys }) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (isBinary(value)) {
+        return { size: value.byteLength, summary: `[binary ${formatBytes(value.byteLength)}]` };
+    }
+    if (isStream(value)) {
+        return { size: 0, summary: '[stream]' };
+    }
+    let json;
+    try {
+        json = JSON.stringify(value, (key, field) => (key && isSensitive(key, redactKeys) ? REDACTED : field));
+    }
+    catch {
+        return { size: 0, summary: '[could not be serialized]' };
+    }
+    if (json === undefined) {
+        return undefined;
+    }
+    const size = Buffer.byteLength(json);
+    if (size > maxBodyBytes) {
+        return { size, truncated: true, preview: json.slice(0, maxBodyBytes) };
+    }
+    return { size, value: JSON.parse(json) };
+}
+/** Request headers with sensitive values replaced. */
+export function captureHeaders(headers, redactKeys) {
+    const captured = {};
+    for (const [name, value] of Object.entries(headers)) {
+        if (value === undefined) {
+            continue;
+        }
+        captured[name] = isSensitive(name, redactKeys) ? REDACTED : Array.isArray(value) ? value.join(', ') : value;
+    }
+    return captured;
+}
+/** The body Nest sends for an exception: HttpException's response, or its generic 500. */
+export function errorResponseBody(error) {
+    if (error instanceof HttpException) {
+        const response = error.getResponse();
+        return typeof response === 'string' ? { statusCode: error.getStatus(), message: response } : response;
+    }
+    return { statusCode: 500, message: 'Internal server error' };
+}
+/** Leaves out empty query and params objects: there's nothing to show. */
+export function nonEmpty(value) {
+    if (value && typeof value === 'object' && Object.keys(value).length === 0) {
+        return undefined;
+    }
+    return value;
+}
+function isBinary(value) {
+    return value instanceof Uint8Array || value instanceof ArrayBuffer;
+}
+// Readable streams and Nest's StreamableFile.
+function isStream(value) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const candidate = value;
+    return typeof candidate.pipe === 'function' || typeof candidate.getStream === 'function';
+}
+function formatBytes(bytes) {
+    return bytes < 1024 ? `${bytes} B` : `${(bytes / 1024).toFixed(1)} KB`;
+}

package/dist/esm/http.d.ts

@@ -15,6 +15,10 @@ export interface HttpRequest {
     };
     /** Fastify 3. */
     routerPath?: string;
+    /** Parsed by Nest's body parser (Express) or by Fastify. */
+    body?: unknown;
+    query?: unknown;
+    params?: unknown;
 }
 export interface HttpResponse {
     statusCode: number;

package/dist/esm/index.d.ts

@@ -1,4 +1,4 @@
 export { NestRnLensModule } from './module.js';
 export { NestRnLensInterceptor } from './interceptor.js';
 export { NEST_RN_LENS_HEADERS } from './types.js';
-export type { NestRnLensEvent, NestRnLensOptions, Platform } from './types.js';
+export type { CapturedBody, NestRnLensEvent, NestRnLensOptions, Platform } from './types.js';

package/dist/esm/interceptor.d.ts

@@ -11,6 +11,7 @@ export declare class NestRnLensInterceptor implements NestInterceptor {
     private readonly reporter;
     constructor(options: NestRnLensOptions, reporter: NestRnLensReporter);
     intercept(context: ExecutionContext, next: CallHandler): Observable<unknown>;
+    private captureOptions;
     /**
      * The status Nest is about to send. Depending on the platform it may not be
      * written to the response yet, so follow Nest's own rules: @HttpCode(),

package/dist/esm/interceptor.js

@@ -13,6 +13,7 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 import { HttpException, Inject, Injectable, } from '@nestjs/common';
 import { randomUUID } from 'node:crypto';
 import { tap } from 'rxjs';
+import { captureBody, captureHeaders, DEFAULT_MAX_BODY_BYTES, DEFAULT_REDACT_KEYS, errorResponseBody, nonEmpty, } from './capture.js';
 import { NEST_RN_LENS_OPTIONS } from './constants.js';
 import { detectPlatform, readHeader, requestPath, routePattern, writeHeader, } from './http.js';
 import { NestRnLensReporter } from './reporter.js';
@@ -43,7 +44,15 @@ let NestRnLensInterceptor = class NestRnLensInterceptor {
         const traceId = readHeader(req, NEST_RN_LENS_HEADERS.traceId) ?? randomUUID();
         // Lets the client, and the next service in the chain, reuse the trace id.
         writeHeader(res, NEST_RN_LENS_HEADERS.traceId, traceId);
-        const finish = (status, error) => {
+        // Captured before the handler runs, in case it mutates the request.
+        const capture = this.captureOptions();
+        const request = capture && {
+            headers: captureHeaders(req.headers, capture.redactKeys),
+            query: captureValue(nonEmpty(req.query), capture),
+            params: captureValue(nonEmpty(req.params), capture),
+            body: captureBody(req.body, capture),
+        };
+        const finish = (status, error, responseBody) => {
             const event = {
                 id: randomUUID(),
                 traceId,
@@ -64,14 +73,22 @@ let NestRnLensInterceptor = class NestRnLensInterceptor {
                 },
                 status,
                 error,
+                ...(capture && { request, response: { body: captureBody(responseBody, capture) } }),
             };
             this.reporter.report(event);
         };
         return next.handle().pipe(tap({
-            next: () => finish(this.successStatus(context, req, res)),
-            error: (err) => finish(err instanceof HttpException ? err.getStatus() : 500, err instanceof Error ? err.message : String(err)),
+            next: (body) => finish(this.successStatus(context, req, res), undefined, body),
+            error: (err) => finish(err instanceof HttpException ? err.getStatus() : 500, err instanceof Error ? err.message : String(err), errorResponseBody(err)),
         }));
     }
+    captureOptions() {
+        const { captureBodies, maxBodyBytes, redactKeys } = this.options;
+        if (captureBodies === false) {
+            return undefined;
+        }
+        return { maxBodyBytes: maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES, redactKeys: redactKeys ?? DEFAULT_REDACT_KEYS };
+    }
     /**
      * The status Nest is about to send. Depending on the platform it may not be
      * written to the response yet, so follow Nest's own rules: @HttpCode(),
@@ -95,3 +112,7 @@ NestRnLensInterceptor = __decorate([
     __metadata("design:paramtypes", [Object, NestRnLensReporter])
 ], NestRnLensInterceptor);
 export { NestRnLensInterceptor };
+/** Small values (query, params) keep their structure; their redacted value is all we need. */
+function captureValue(value, capture) {
+    return captureBody(value, capture)?.value;
+}

package/dist/esm/module.js

@@ -7,6 +7,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var NestRnLensModule_1;
 import { Module } from '@nestjs/common';
 import { APP_INTERCEPTOR } from '@nestjs/core';
+import { DEFAULT_MAX_BODY_BYTES, DEFAULT_REDACT_KEYS } from './capture.js';
 import { NEST_RN_LENS_OPTIONS } from './constants.js';
 import { NestRnLensInterceptor } from './interceptor.js';
 import { NestRnLensReporter } from './reporter.js';
@@ -24,6 +25,9 @@ let NestRnLensModule = NestRnLensModule_1 = class NestRnLensModule {
             ...options,
             enabled: options.enabled ?? process.env.NODE_ENV !== 'production',
             log: options.log ?? true,
+            captureBodies: options.captureBodies ?? true,
+            maxBodyBytes: options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES,
+            redactKeys: [...DEFAULT_REDACT_KEYS, ...(options.redactKeys ?? [])],
         };
         return {
             module: NestRnLensModule_1,

package/dist/esm/reporter.d.ts

@@ -10,3 +10,9 @@ export declare class NestRnLensReporter {
     private describe;
     private shortPath;
 }
+/**
+ * Callers that are source locations are shown relative to the monorepo root
+ * (clients send absolute paths so editors can open them). Anything else, such as
+ * a web page path like "/orders/42", is shown as sent.
+ */
+export declare function formatCaller(caller: string, repoRoot: string): string;

package/dist/esm/reporter.js

@@ -45,14 +45,12 @@ let NestRnLensReporter = class NestRnLensReporter {
         const from = [`${source.app} (${source.platform})`, this.shortPath(source.caller)].filter(Boolean).join(' ');
         return `${from} → ${target.method} ${target.route} → ${target.controller}.${target.handler} ${status} ${durationMs}ms`;
     }
-    // Clients send absolute paths (editors need them to open the file); logs are
-    // easier to read relative to the monorepo root.
-    shortPath(file) {
-        if (!file?.startsWith('/')) {
-            return file;
+    shortPath(caller) {
+        if (!caller || !SOURCE_LOCATION.test(caller)) {
+            return caller;
         }
         this.repoRoot ??= findRepoRoot(process.cwd());
-        return relative(this.repoRoot, file);
+        return formatCaller(caller, this.repoRoot);
     }
 };
 NestRnLensReporter = __decorate([
@@ -61,6 +59,16 @@ NestRnLensReporter = __decorate([
     __metadata("design:paramtypes", [Object])
 ], NestRnLensReporter);
 export { NestRnLensReporter };
+// "/repo/apps/mobile/src/screens/Orders.tsx:23": an absolute file path plus a line.
+const SOURCE_LOCATION = /^\/.+:\d+$/;
+/**
+ * Callers that are source locations are shown relative to the monorepo root
+ * (clients send absolute paths so editors can open them). Anything else, such as
+ * a web page path like "/orders/42", is shown as sent.
+ */
+export function formatCaller(caller, repoRoot) {
+    return SOURCE_LOCATION.test(caller) ? relative(repoRoot, caller) : caller;
+}
 const ROOT_MARKERS = ['turbo.json', 'pnpm-workspace.yaml', '.git'];
 function findRepoRoot(from) {
     let dir = from;

package/dist/esm/types.d.ts

@@ -11,6 +11,18 @@ export declare const NEST_RN_LENS_HEADERS: {
     readonly traceId: "x-nest-rn-lens-trace-id";
 };
 export type Platform = 'ios' | 'android' | 'web' | 'unknown';
+/** A request or response body, made safe to log. */
+export interface CapturedBody {
+    /** Size of the serialized body, in bytes. */
+    size: number;
+    /** The body, with sensitive fields redacted. Absent when truncated or summarized. */
+    value?: unknown;
+    /** Set when the body was larger than `maxBodyBytes`; `preview` holds its start. */
+    truncated?: boolean;
+    preview?: string;
+    /** For bodies that aren't JSON: "[binary 12.0 KB]", "[stream]". */
+    summary?: string;
+}
 /** One request, as seen by the API. */
 export interface NestRnLensEvent {
     id: string;
@@ -40,6 +52,20 @@ export interface NestRnLensEvent {
     status: number;
     /** Message of the exception, when the handler threw. */
     error?: string;
+    /** What the client sent. Only present when `captureBodies` is on (the default). */
+    request?: {
+        /** Request headers; sensitive ones redacted. */
+        headers: Record<string, string>;
+        query?: unknown;
+        /** Route parameters, e.g. { id: "42" } for /orders/:id. */
+        params?: unknown;
+        body?: CapturedBody;
+    };
+    /** What the API answered. Only present when `captureBodies` is on (the default). */
+    response?: {
+        /** The handler's return value, or the error body Nest sends for an exception. */
+        body?: CapturedBody;
+    };
 }
 export interface NestRnLensOptions {
     /** Name of this API in the traffic graph, e.g. "api". */
@@ -59,4 +85,19 @@ export interface NestRnLensOptions {
      * debug level that the NestRN Lens VS Code extension reads). Defaults to `true`.
      */
     log?: boolean;
+    /**
+     * Include request and response bodies, query, route params and request
+     * headers in each event. Defaults to `true`. Sensitive fields are redacted
+     * (see `redactKeys`).
+     */
+    captureBodies?: boolean;
+    /** Bodies larger than this are cut to a preview. Defaults to 16 KB. */
+    maxBodyBytes?: number;
+    /**
+     * Extra field or header names to redact, added to the defaults (password,
+     * secret, token, authorization, cookie, apiKey, privateKey, creditCard,
+     * cardNumber, cvv, ssn). Matched ignoring case and separators, anywhere in
+     * the name: "token" also covers "accessToken".
+     */
+    redactKeys?: string[];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nest-rn-lens/nest",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "NestJS interceptor that reports every request together with the React Native screen that made it. Part of NestRN Lens.",
   "keywords": [
     "nestjs",
@@ -12,7 +12,8 @@
     "monorepo",
     "observability",
     "tracing",
-    "devtools"
+    "devtools",
+    "nextjs"
   ],
   "license": "MIT",
   "author": "isa",