@reproapp/node-sdk 0.0.1

package/README.md

@@ -0,0 +1,343 @@
+# Repro Nest SDK
+
+Capture NestJS request/response data, function traces, and Mongoose activity for
+Repro sessions. This SDK is designed for Nest apps running on Express, with
+optional tracing and masking controls.
+
+## 1) Install
+
+Requirements:
+- Node.js 18+
+- NestJS app using Express (default) and optionally Mongoose 6+
+
+Install the package:
+
+```bash
+npm install repro-nest
+# or
+yarn add repro-nest
+# or
+pnpm add repro-nest
+```
+
+## 2) Configure
+
+At minimum, provide your Repro credentials and wire the middleware. If you want
+function tracing, call `initReproTracing` before importing your `AppModule` so
+Nest classes are instrumented at load time.
+
+```ts
+import 'reflect-metadata';
+import { NestFactory } from '@nestjs/core';
+import mongoose from 'mongoose';
+import {
+  initReproTracing,
+  reproMiddleware,
+  reproMongoosePlugin,
+} from 'repro-nest';
+
+const reproConfig = {
+  appId: process.env.REPRO_APP_ID as string,
+  appName: process.env.REPRO_APP_NAME as string,
+  tenantId: process.env.REPRO_TENANT_ID as string,
+  appSecret: process.env.REPRO_APP_SECRET as string,
+};
+
+async function bootstrap() {
+  // Enable function tracing before loading your modules.
+  initReproTracing({
+    disableFunctionTypes: ['constructor'],
+    logFunctionCalls: false,
+  });
+
+  // Optional: capture MongoDB queries + document diffs.
+  mongoose.plugin(reproMongoosePlugin(reproConfig));
+
+  const { AppModule } = await import('./app.module');
+  const app = await NestFactory.create(AppModule);
+
+  // Capture request/response payloads for tagged Repro sessions.
+  app.use(reproMiddleware(reproConfig));
+
+  await app.listen(3000);
+}
+
+bootstrap();
+```
+
+Configuration notes:
+- `REPRO_API_BASE` (optional) overrides the backend base URL used to send data.
+- `REPRO_APP_NAME` (optional) sets `appName`, which is sent as `X-App-Name`.
+
+### initReproTracing
+
+Enables function tracing. Call this before importing `AppModule` so Nest classes
+are loaded through the tracer.
+
+Options (type -> purpose):
+- `instrument` (boolean): enable or disable instrumentation of loaded modules.
+- `include` (RegExp[]): file path include patterns for instrumentation.
+- `exclude` (RegExp[]): file path exclude patterns for instrumentation.
+- `mode` (string): tracer mode (defaults to `TRACE_MODE` or `trace`).
+- `samplingMs` (number): sampling interval in milliseconds.
+- `disableFunctionTraces` (DisableFunctionTraceConfig[] | null): drop trace events
+  that match rule objects or predicates.
+- `disableFunctionTypes` (TraceRulePattern | null): drop events for matching
+  function kinds (for example, constructors).
+- `disableTraceFiles` (DisableTraceFileConfig | DisableTraceFileConfig[] | null):
+  drop events emitted from matching files.
+- `traceInterceptors` (boolean): include Nest interceptors in traces (default false).
+- `logFunctionCalls` (boolean): log enter/exit events to console.
+
+Type reference:
+- `TraceRulePattern`: `string | number | RegExp | Array<string | number | RegExp>`
+- `DisableFunctionTraceConfig`: `DisableFunctionTraceRule | DisableFunctionTracePredicate`
+- `DisableFunctionTracePredicate`: `(event: TraceEventForFilter) => boolean`
+- `DisableFunctionTraceRule` fields (all accept `TraceRulePattern`):
+  - `fn` / `functionName`: function name substring/regex
+  - `wrapper` / `wrapperClass` / `className` / `owner`: wrapper/owner name
+  - `file`: source filename
+  - `line`: source line number
+  - `lib` / `library`: npm package name inferred from path
+  - `type` / `functionType`: function kind (`method`, `constructor`, etc.)
+  - `event` / `eventType`: trace phase (`enter` or `exit`)
+- `DisableTraceByFilename`: `{ file: TraceRulePattern }`
+- `DisableTraceFileConfig`: `TraceRulePattern | DisableTraceByFilename | null | undefined`
+
+Full config example (shows every option; aliases are interchangeable, use one per group in real configs):
+
+```ts
+import { initReproTracing } from 'repro-nest';
+
+initReproTracing({
+  instrument: true,
+  include: [/^\/app\/src\//],
+  exclude: [/node_modules\//, /dist\//],
+  mode: process.env.TRACE_MODE || 'trace',
+  samplingMs: 10,
+  disableFunctionTraces: [
+    {
+      fn: 'findAll',
+      wrapper: 'TasksService',
+      file: 'src/tasks/tasks.service.ts',
+      line: 27,
+      lib: 'mongoose',
+      type: 'method',
+      event: 'exit',
+    },
+    {
+      functionName: 'formatSensitiveData',
+      wrapperClass: 'AuthService',
+      className: 'AuthService',
+      owner: 'AuthService',
+      library: 'bcrypt',
+      functionType: 'method',
+      eventType: 'enter',
+    },
+    (event) => event.fn?.startsWith('debug') ?? false,
+  ],
+  disableFunctionTypes: ['constructor', /getter/i],
+  disableTraceFiles: [
+    /node_modules\/some-logger\//,
+    { file: 'dist/health.check.js' },
+    'dist/generated.js',
+  ],
+  traceInterceptors: true,
+  logFunctionCalls: false,
+});
+```
+
+### reproMiddleware
+
+Captures request/response payloads for active Repro sessions. Requests must
+include `x-bug-session-id` and `x-bug-action-id` headers to be captured.
+
+Options (type -> purpose):
+- `appId` (string): Repro app id.
+- `appName` (string, optional): Repro app name (sent as `X-App-Name`).
+- `tenantId` (string): Repro tenant id.
+- `appSecret` (string): Repro app secret.
+- `captureHeaders` (boolean | HeaderCaptureOptions): enable/disable header capture
+  and masking.
+- `masking` (ReproMaskingConfig): mask request/response bodies and trace args/returns.
+
+Header capture options (`HeaderCaptureOptions`):
+- `allowSensitiveHeaders` (boolean): keep default sensitive headers unmasked.
+- `maskHeaders` (HeaderRule | HeaderRule[]): header names to mask.
+- `dropHeaders` (HeaderRule | HeaderRule[]): alias for `maskHeaders`.
+- `unmaskHeaders` (HeaderRule | HeaderRule[]): header names to keep unmasked.
+- `keepHeaders` (HeaderRule | HeaderRule[]): alias for `unmaskHeaders`.
+- `HeaderRule`: `string | RegExp`
+
+Masking options (`ReproMaskingConfig`):
+- `replacement` (any): default replacement value (defaults to `"[REDACTED]"`).
+- `rules` (ReproMaskRule[] | null): list of masking rules.
+
+Masking rule options (`ReproMaskRule`):
+- `when` (ReproMaskWhen): scope rules by request or function trace fields.
+- `target` (ReproMaskTarget | ReproMaskTarget[]): where to apply the mask.
+- `paths` (string | string[]): dot/bracket paths to mask.
+- `keys` (TraceRulePattern): mask keys anywhere in the payload.
+- `replacement` (any): override replacement value for this rule.
+
+`ReproMaskTarget` values:
+- `request.headers`, `request.body`, `request.params`, `request.query`
+- `response.body`, `trace.args`, `trace.returnValue`, `trace.error`
+
+`ReproMaskWhen` fields (all accept `TraceRulePattern` unless noted):
+- Request scope: `method`, `path`, `key`
+- Function scope: `fn` / `functionName`, `wrapper` / `wrapperClass` / `className` / `owner`,
+  `file`, `line`, `lib` / `library`, `type` / `functionType`, `event` / `eventType`
+
+Full config example (shows every option; aliases are interchangeable, use one per group in real configs):
+
+```ts
+import { reproMiddleware } from 'repro-nest';
+
+app.use(reproMiddleware({
+  appId: process.env.REPRO_APP_ID as string,
+  appName: process.env.REPRO_APP_NAME as string,
+  tenantId: process.env.REPRO_TENANT_ID as string,
+  appSecret: process.env.REPRO_APP_SECRET as string,
+  captureHeaders: {
+    allowSensitiveHeaders: false,
+    maskHeaders: [/authorization/i, /cookie/i],
+    dropHeaders: ['x-api-key'],
+    unmaskHeaders: ['x-request-id'],
+    keepHeaders: ['x-trace-id'],
+  },
+  masking: {
+    replacement: '[REDACTED]',
+    rules: [
+      {
+        when: { method: 'POST', path: '/api/auth/login', key: 'POST /api/auth/login' },
+        target: ['request.body', 'response.body'],
+        paths: ['password'],
+        keys: [/token/i],
+        replacement: '[FILTERED]',
+      },
+      {
+        when: {
+          functionName: 'findAll',
+          wrapperClass: 'TasksService',
+          file: 'src/tasks/tasks.service.ts',
+          line: 27,
+          library: 'mongoose',
+          functionType: 'method',
+          eventType: 'exit',
+        },
+        target: ['trace.args', 'trace.returnValue', 'trace.error'],
+        paths: ['0.user.token'],
+        keys: ['password'],
+      },
+      {
+        when: {
+          fn: 'create',
+          wrapper: 'UsersService',
+          className: 'UsersService',
+          owner: 'UsersService',
+          lib: 'mongoose',
+          type: 'method',
+          event: 'enter',
+        },
+        target: 'trace.args',
+        paths: ['0.password'],
+      },
+    ],
+  },
+}));
+```
+
+See `docs/tracing.md` for full masking and trace filtering details.
+
+### Mongoose plugin
+
+`reproMongoosePlugin` attaches schema middleware to capture query activity and
+document diffs. It emits data only when a Repro session is active (i.e., when
+`reproMiddleware` has set the session context for the current request).
+
+Arguments:
+- `appId` (string): Repro app id
+- `appName` (string, optional): Repro app name (sent as `X-App-Name`)
+- `tenantId` (string): Repro tenant id
+- `appSecret` (string): Repro app secret
+
+Example: global plugin (all schemas)
+
+```ts
+import mongoose from 'mongoose';
+import { reproMongoosePlugin } from 'repro-nest';
+
+mongoose.plugin(reproMongoosePlugin({
+  appId: process.env.REPRO_APP_ID as string,
+  appName: process.env.REPRO_APP_NAME as string,
+  tenantId: process.env.REPRO_TENANT_ID as string,
+  appSecret: process.env.REPRO_APP_SECRET as string,
+}));
+```
+
+Example: Nest `MongooseModule` connection factory
+
+```ts
+import { MongooseModule } from '@nestjs/mongoose';
+import { reproMongoosePlugin } from 'repro-nest';
+
+MongooseModule.forRoot(process.env.MONGO_URL as string, {
+  connectionFactory: (connection) => {
+    connection.plugin(reproMongoosePlugin({
+      appId: process.env.REPRO_APP_ID as string,
+      appName: process.env.REPRO_APP_NAME as string,
+      tenantId: process.env.REPRO_TENANT_ID as string,
+      appSecret: process.env.REPRO_APP_SECRET as string,
+    }));
+    return connection;
+  },
+});
+```
+
+Example: schema-level plugin (single model)
+
+```ts
+import { Schema } from 'mongoose';
+import { reproMongoosePlugin } from 'repro-nest';
+
+const userSchema = new Schema({ email: String });
+userSchema.plugin(reproMongoosePlugin({
+  appId: process.env.REPRO_APP_ID as string,
+  appName: process.env.REPRO_APP_NAME as string,
+  tenantId: process.env.REPRO_TENANT_ID as string,
+  appSecret: process.env.REPRO_APP_SECRET as string,
+}));
+```
+
+## 3) Run
+
+Run your Nest app as usual after wiring the SDK:
+
+```bash
+npm run start:dev
+# or
+node dist/main.js
+```
+
+If you use `initReproTracing`, keep it at the top of your bootstrap so modules
+load after instrumentation is enabled.
+
+## 4) Verify It Works
+
+Send a request with Repro headers and confirm the session shows up in Repro.
+
+```bash
+curl \
+  -H "x-bug-session-id: session-123" \
+  -H "x-bug-action-id: action-123" \
+  http://localhost:3000/health
+```
+
+Verification tips:
+- If the Repro UI does not show the session, confirm `REPRO_API_BASE` and
+  credentials are correct.
+- Temporarily set `logFunctionCalls: true` in `initReproTracing` to see trace
+  enter/exit logs in your console.
+- If you use Mongoose, exercise a query/mutation and verify DB entries appear
+  in the session trace.

package/dist/index.d.ts

@@ -0,0 +1,221 @@
+/// <reference types="mongoose/types/aggregate" />
+/// <reference types="mongoose/types/callback" />
+/// <reference types="mongoose/types/collection" />
+/// <reference types="mongoose/types/connection" />
+/// <reference types="mongoose/types/cursor" />
+/// <reference types="mongoose/types/document" />
+/// <reference types="mongoose/types/error" />
+/// <reference types="mongoose/types/expressions" />
+/// <reference types="mongoose/types/helpers" />
+/// <reference types="mongoose/types/middlewares" />
+/// <reference types="mongoose/types/indexes" />
+/// <reference types="mongoose/types/models" />
+/// <reference types="mongoose/types/mongooseoptions" />
+/// <reference types="mongoose/types/pipelinestage" />
+/// <reference types="mongoose/types/populate" />
+/// <reference types="mongoose/types/query" />
+/// <reference types="mongoose/types/schemaoptions" />
+/// <reference types="mongoose/types/session" />
+/// <reference types="mongoose/types/types" />
+/// <reference types="mongoose/types/utility" />
+/// <reference types="mongoose/types/validation" />
+/// <reference types="mongoose/types/virtuals" />
+/// <reference types="mongoose/types/schematypes" />
+/// <reference types="mongoose/types/inferschematype" />
+/// <reference types="mongoose/types/inferrawdoctype" />
+import type { Request, Response, NextFunction } from 'express';
+import type { Schema } from 'mongoose';
+type SpanContext = {
+    traceId: string | null;
+    spanId: string | number | null;
+    parentSpanId: string | number | null;
+    depth: number | null;
+};
+type TracerApi = {
+    init?: (opts: any) => void;
+    tracer?: {
+        on: (fn: (ev: any) => void) => () => void;
+    };
+    getCurrentTraceId?: () => string | null;
+    getCurrentSpanContext?: () => SpanContext | null;
+    patchHttp?: () => void;
+    setFunctionLogsEnabled?: (enabled: boolean) => void;
+};
+type TraceEventPhase = 'enter' | 'exit';
+export type TraceRulePattern = string | number | RegExp | Array<string | number | RegExp>;
+export type TraceEventForFilter = {
+    type: TraceEventPhase;
+    eventType: TraceEventPhase;
+    functionType?: string | null;
+    fn?: string;
+    wrapperClass?: string | null;
+    file?: string | null;
+    line?: number | null;
+    depth?: number;
+    library?: string | null;
+};
+export type HeaderRule = string | RegExp;
+export type HeaderCaptureOptions = {
+    /** When true, sensitive headers such as Authorization are kept unmasked; default masks them. */
+    allowSensitiveHeaders?: boolean;
+    /**
+     * Header names (string or RegExp) to mask.
+     * `dropHeaders` is kept for backward-compatibility and treated as an alias for `maskHeaders`.
+     */
+    maskHeaders?: HeaderRule | HeaderRule[];
+    /** @deprecated Alias for {@link maskHeaders}. */
+    dropHeaders?: HeaderRule | HeaderRule[];
+    /**
+     * Header names (string or RegExp) to keep unmasked, overriding defaults and `maskHeaders`.
+     * `keepHeaders` is kept for backward-compatibility and treated as an alias for `unmaskHeaders`.
+     */
+    unmaskHeaders?: HeaderRule | HeaderRule[];
+    /** @deprecated Alias for {@link unmaskHeaders}. */
+    keepHeaders?: HeaderRule | HeaderRule[];
+};
+/** Lightweight helper to disable every trace emitted from specific files. */
+export interface DisableTraceByFilename {
+    file: TraceRulePattern;
+}
+type DisableTraceFileConfig = TraceRulePattern | DisableTraceByFilename | null | undefined;
+/**
+ * Declarative rule that disables trace events matching the provided patterns.
+ *
+ * Each property accepts a string (substring match), a RegExp, or an array of
+ * either. When an array is provided, a single match of any entry is enough to
+ * drop the event. Provide no value to leave that dimension unrestricted.
+ */
+export type DisableFunctionTraceRule = {
+    /** Shortcut for {@link functionName}. */
+    fn?: TraceRulePattern;
+    /** Function name (e.g. `"findOne"`, `/^UserService\./`). */
+    functionName?: TraceRulePattern;
+    /** Shortcut for {@link wrapperClass}. */
+    wrapper?: TraceRulePattern;
+    /**
+     * Wrapper/owner name derived from {@link functionName} (e.g. `"UserService"` in `"UserService.create"`).
+     * Useful when multiple functions share the same method name.
+     */
+    wrapperClass?: TraceRulePattern;
+    /** Alias for {@link wrapperClass}. */
+    className?: TraceRulePattern;
+    /** Alias for {@link wrapperClass}. */
+    owner?: TraceRulePattern;
+    /** Source filename reported by the trace event. */
+    file?: TraceRulePattern;
+    /** Line number reported by the trace event. */
+    line?: TraceRulePattern;
+    /** Shortcut for {@link library}. */
+    lib?: TraceRulePattern;
+    /** Library/package name inferred from the file path (e.g. `"mongoose"`). */
+    library?: TraceRulePattern;
+    /** Shortcut for {@link functionType}. */
+    type?: TraceRulePattern;
+    /** Function classification such as `"constructor"`, `"method"`, or `"arrow"`. */
+    functionType?: TraceRulePattern;
+    /** Shortcut for {@link eventType}. */
+    event?: TraceRulePattern;
+    /** Trace phase to filter (`"enter"` or `"exit"`). */
+    eventType?: TraceRulePattern;
+};
+export type DisableFunctionTracePredicate = (event: TraceEventForFilter) => boolean;
+export type DisableFunctionTraceConfig = DisableFunctionTraceRule | DisableFunctionTracePredicate;
+export type ReproMaskTarget = 'request.headers' | 'request.body' | 'request.params' | 'request.query' | 'response.body' | 'trace.args' | 'trace.returnValue' | 'trace.error';
+export type ReproMaskWhen = DisableFunctionTraceRule & {
+    /** Match HTTP method (e.g. `"GET"`, `/^post$/i`). */
+    method?: TraceRulePattern;
+    /** Match request path without query string (e.g. `"/api/auth/login"`). */
+    path?: TraceRulePattern;
+    /** Match normalized endpoint key (e.g. `"POST /api/auth/login"`). */
+    key?: TraceRulePattern;
+};
+export type ReproMaskRule = {
+    when?: ReproMaskWhen;
+    target: ReproMaskTarget | ReproMaskTarget[];
+    /**
+     * Dot/bracket paths to mask (supports `*`, `[0]`, `[*]`).
+     * Examples: `"password"`, `"user.token"`, `"items[*].serial"`, `"0.password"` (for trace args arrays).
+     */
+    paths?: string | string[];
+    /** Key name patterns to mask anywhere in the payload. */
+    keys?: TraceRulePattern;
+    /** Override replacement value for this rule (defaults to config replacement / `"[REDACTED]"`). */
+    replacement?: any;
+};
+export type ReproMaskingConfig = {
+    /** Default replacement value (defaults to `"[REDACTED]"`). */
+    replacement?: any;
+    rules?: ReproMaskRule[] | null;
+};
+export declare function setDisabledFunctionTraces(rules?: DisableFunctionTraceConfig[] | null): void;
+export declare function setDisabledFunctionTypes(patterns?: TraceRulePattern | null): void;
+export declare function setDisabledTraceFiles(config?: DisableTraceFileConfig | DisableTraceFileConfig[] | null): void;
+export declare function setReproTraceLogsEnabled(enabled: boolean): void;
+export declare function enableReproTraceLogs(): void;
+export declare function disableReproTraceLogs(): void;
+type TracerInitOpts = {
+    instrument?: boolean;
+    include?: RegExp[];
+    exclude?: RegExp[];
+    mode?: string;
+    samplingMs?: number;
+};
+export type ReproTracingInitOptions = TracerInitOpts & {
+    /**
+     * Optional list of rules or predicates that suppress unwanted function
+     * trace events. When omitted, every instrumented function will be
+     * recorded. Provide an empty array to reset filters after a previous call.
+     */
+    disableFunctionTraces?: DisableFunctionTraceConfig[] | null;
+    /**
+     * Convenience filter that disables every trace event emitted for the
+     * provided function types (e.g. `"constructor"`). Accepts a string,
+     * regular expression, or array matching the rule syntax above.
+     */
+    disableFunctionTypes?: TraceRulePattern | null;
+    /**
+     * Prevents traces emitted from specific files. Accepts glob-like substrings
+     * or regular expressions, or the {@link DisableTraceByFilename} helper.
+     */
+    disableTraceFiles?: DisableTraceFileConfig | DisableTraceFileConfig[] | null;
+    /**
+     * When `false` (default) Nest interceptors are stripped from traces.
+     * Set to `true` to include them if you need to debug interceptor logic.
+     */
+    traceInterceptors?: boolean;
+    /**
+     * Enables or silences console logs emitted by the tracer when functions
+     * are entered/exited. Equivalent to calling `setReproTraceLogsEnabled`.
+     */
+    logFunctionCalls?: boolean;
+};
+/** Call this from the client app to enable tracing. Safe to call multiple times. */
+export declare function initReproTracing(opts?: ReproTracingInitOptions): TracerApi | null;
+/** Optional helper if users want to check it. */
+export declare function isReproTracingEnabled(): boolean;
+export type ReproMiddlewareConfig = {
+    appId: string;
+    appSecret: string;
+    appName?: string;
+    /** Configure header capture/masking. Defaults to capturing with sensitive headers masked. */
+    captureHeaders?: boolean | HeaderCaptureOptions;
+    /** Optional masking rules for request/response payloads and function traces. */
+    masking?: ReproMaskingConfig;
+};
+export declare function reproMiddleware(cfg: ReproMiddlewareConfig): (req: Request, res: Response, next: NextFunction) => void;
+export declare function reproMongoosePlugin(cfg: {
+    appId: string;
+    appSecret: string;
+    appName?: string;
+}): (schema: Schema) => void;
+export type SendgridPatchConfig = {
+    appId: string;
+    appSecret: string;
+    appName?: string;
+    resolveContext?: () => {
+        sid?: string;
+        aid?: string;
+    } | undefined;
+};
+export declare function patchSendgridMail(cfg: SendgridPatchConfig): void;
+export {};