@reproapp/node-sdk 0.0.38 → 0.0.41

package/README.md

@@ -1,377 +1,295 @@
-# Repro Nest SDK
+# Repro Node 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.
+Backend recorder for Repro sessions. It captures tagged request/response data,
+function traces, database activity, queue messages, Redis operations, and SendGrid
+email events, then uploads that context to Repro.
 
-## 1) Install
+The current package is `@reproapp/node-sdk`. New apps should start with
+`initRepro`.
 
-Requirements:
-- Node.js 18+
-- NestJS app using Express (default) and optionally Mongoose 6+
-
-Install the package:
+## Install
 
 ```bash
-npm install repro-nest
-# or
-yarn add repro-nest
-# or
-pnpm add repro-nest
+npm install @reproapp/node-sdk
 ```
 
-## 2) Configure
+Requirements:
+- Node.js 18+
+- Express or NestJS on the Express adapter for HTTP capture
+- Optional integrations are patched when their packages are installed: `mongoose`,
+  `mongodb`, `pg`, `postgres`, TypeORM (standalone or NestJS), `kafkajs`,
+  `amqplib`, `redis`, and `@sendgrid/mail`
 
-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.
+## Quickstart
 
-```ts
-import 'reflect-metadata';
-import { NestFactory } from '@nestjs/core';
-import mongoose from 'mongoose';
-import {
-  initReproTracing,
-  reproMiddleware,
-  reproMongoosePlugin,
-} from 'repro-nest';
+Call `initRepro` before importing your application modules. This lets the SDK
+install tracing hooks, auto-attach HTTP middleware to Express/Nest apps, register
+database/message/email integrations, and fetch the runtime privacy policy.
 
-const reproConfig = {
-  appId: process.env.REPRO_APP_ID as string,
-  appName: process.env.REPRO_APP_NAME as string,
-  serviceName: process.env.REPRO_SERVICE_NAME as string,
-  tenantId: process.env.REPRO_TENANT_ID as string,
-  appSecret: process.env.REPRO_APP_SECRET as string,
-};
+```ts
+import { initRepro } from "@reproapp/node-sdk";
 
 async function bootstrap() {
-  // Enable function tracing before loading your modules.
-  initReproTracing({
-    disableFunctionTypes: ['constructor'],
-    logFunctionCalls: false,
+  await initRepro({
+    tenantId: process.env.REPRO_TENANT_ID!,
+    appId: process.env.REPRO_APP_ID!,
+    appSecret: process.env.REPRO_APP_SECRET!,
+    appName: process.env.REPRO_APP_NAME ?? "Acme Web",
+    serviceName: process.env.REPRO_SERVICE_NAME ?? "api",
+    apiBase: process.env.REPRO_API_BASE,
+    tracing: {
+      disableFunctionTypes: ["constructor"],
+      logFunctionCalls: false,
+    },
+    privacy: {
+      environment: process.env.REPRO_PRIVACY_ENV ?? process.env.NODE_ENV ?? "dev",
+      apiBase: process.env.REPRO_PRIVACY_API_BASE ?? process.env.REPRO_API_BASE,
+    },
   });
 
-  // Optional: capture MongoDB queries + document diffs.
-  mongoose.plugin(reproMongoosePlugin(reproConfig));
+  const { AppModule } = await import("./app.module");
+  const { NestFactory } = await import("@nestjs/core");
 
-  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();
+void bootstrap();
 ```
 
-Configuration notes:
-- `REPRO_INGEST_BASE` (optional) overrides the log-collector base URL used to send ingest events.
-- `REPRO_APP_NAME` (optional) sets `appName`, which is sent as `X-App-Name`.
-- `REPRO_SERVICE_NAME` (optional) sets the backend service label stored on request, trace, DB, and email events. Defaults to `appName` when omitted.
-
-### 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):
+Express apps follow the same ordering:
 
 ```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,
-});
-```
+import { initRepro } from "@reproapp/node-sdk";
+
+async function main() {
+  await initRepro({
+    tenantId: process.env.REPRO_TENANT_ID!,
+    appId: process.env.REPRO_APP_ID!,
+    appSecret: process.env.REPRO_APP_SECRET!,
+    appName: "Acme Web",
+    serviceName: "public-api",
+    apiBase: process.env.REPRO_API_BASE,
+  });
 
-### 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`).
-- `serviceName` (string, optional): service label persisted with backend events.
-- `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):
+  const express = (await import("express")).default;
+  const app = express();
+  app.use(express.json());
+  app.get("/health", (_req, res) => res.json({ ok: true }));
+  app.listen(3000);
+}
 
-```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,
-  serviceName: process.env.REPRO_SERVICE_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'],
-      },
-    ],
-  },
-}));
+void main();
 ```
 
-See `docs/tracing.md` for full masking and trace filtering details.
+## Capture modes: tagged sessions and backend live mode
 
-### Mongoose plugin
+The Node SDK has two capture modes:
 
-`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).
+- Tagged session capture is the default. Browser live and staging sessions both
+  add Repro context to app requests. The Node SDK captures backend requests,
+  traces, DB changes, queue work, Redis calls, and email events when that context
+  is present.
+- Backend-owned live mode is opt-in. Use `liveMode` when the backend must create
+  sessions without frontend Repro context, such as backend-only APIs or jobs.
 
-Arguments:
-- `appId` (string): Repro app id
-- `appName` (string, optional): Repro app name (sent as `X-App-Name`)
-- `serviceName` (string, optional): service label persisted with backend events
-- `tenantId` (string): Repro tenant id
-- `appSecret` (string): Repro app secret
+The backend SDK does not set `ingest.mode`; `live` and `staging` are selected in
+the React SDK. Staging manual QA captures from the small Repro button still tag
+backend requests, so the Node SDK captures them through the default tagged flow.
 
-Example: global plugin (all schemas)
+Default tagged capture:
 
 ```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,
-  serviceName: process.env.REPRO_SERVICE_NAME as string,
-  tenantId: process.env.REPRO_TENANT_ID as string,
-  appSecret: process.env.REPRO_APP_SECRET as string,
-}));
+await initRepro({
+  tenantId: process.env.REPRO_TENANT_ID!,
+  appId: process.env.REPRO_APP_ID!,
+  appSecret: process.env.REPRO_APP_SECRET!,
+  appName: "Acme Web",
+  serviceName: "api",
+  apiBase: process.env.REPRO_API_BASE,
+});
 ```
 
-Example: Nest `MongooseModule` connection factory
+Backend-owned live mode:
 
 ```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,
-      serviceName: process.env.REPRO_SERVICE_NAME as string,
-      tenantId: process.env.REPRO_TENANT_ID as string,
-      appSecret: process.env.REPRO_APP_SECRET as string,
-    }));
-    return connection;
+await initRepro({
+  tenantId: process.env.REPRO_TENANT_ID!,
+  appId: process.env.REPRO_APP_ID!,
+  appSecret: process.env.REPRO_APP_SECRET!,
+  appName: "Acme Web",
+  serviceName: "api",
+  apiBase: process.env.REPRO_API_BASE,
+  liveMode: {
+    enabled: true,
+    backendOnly: true,
+    defineActorId: ({ req, ip }) => req.headers["x-user-id"] ?? (ip ? `ip:${ip}` : null),
+    shouldCapture: ({ path }) => path.startsWith("/api/") && !path.includes("/health"),
+    actorType: "user",
+    actorLabels: ({ path }) => ({ routeGroup: path.split("/").filter(Boolean)[0] ?? "api" }),
   },
 });
 ```
 
-Example: schema-level plugin (single model)
+## Manual Wiring
+
+Use the lower-level exports when auto-attach is not appropriate or when you need
+to wire middleware manually.
 
 ```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,
-  serviceName: process.env.REPRO_SERVICE_NAME as string,
-  tenantId: process.env.REPRO_TENANT_ID as string,
-  appSecret: process.env.REPRO_APP_SECRET as string,
-}));
-```
+import express from "express";
+import mongoose from "mongoose";
+import {
+  initReproTracing,
+  patchKafkaJs,
+  patchMongoDb,
+  patchPostgreSql,
+  patchRedis,
+  patchSendgridMail,
+  reproMiddleware,
+  reproMongoosePlugin,
+} from "@reproapp/node-sdk";
+
+const reproConfig = {
+  tenantId: process.env.REPRO_TENANT_ID!,
+  appId: process.env.REPRO_APP_ID!,
+  appSecret: process.env.REPRO_APP_SECRET!,
+  appName: "Acme Web",
+  serviceName: "api",
+};
 
-### KafkaJS integration
+initReproTracing({ disableFunctionTypes: ["constructor"] });
+mongoose.plugin(reproMongoosePlugin(reproConfig));
+patchKafkaJs(reproConfig);
+patchMongoDb(reproConfig);
+patchPostgreSql(reproConfig);
+patchRedis(reproConfig);
+patchSendgridMail(reproConfig);
+
+const app = express();
+app.use(express.json());
+app.use(reproMiddleware(reproConfig));
+```
 
-`patchKafkaJs` instruments `kafkajs` producers and consumers.
+## Configuration
 
-- Producer calls (`send`, `sendBatch`) propagate Repro trace/session headers.
-- Consumer handlers (`eachMessage`, `eachBatch`) restore context and emit backend
-  request + trace batches for Kafka processing.
+```ts
+type ReproInitConfig = {
+  tenantId: string;
+  appId: string;
+  appSecret?: string;
+  appName?: string;
+  serviceName?: string;
+  apiBase?: string;
+  actorId?: string;
+  actorType?: string;
+  actorLabels?: Record<string, string>;
+  captureHeaders?: boolean | HeaderCaptureOptions;
+  masking?: ReproMaskingConfig;
+  privacy?: RuntimePrivacyConfig;
+  liveMode?: boolean | ReproLiveModeConfig;
+  tracing?: ReproTracingInitOptions | false;
+  resolveContext?: () => { sid?: string; aid?: string } | undefined;
+};
+```
 
-Call it once during bootstrap, before creating producers/consumers:
+Important options:
+- `tenantId`, `appId`, `appSecret`: Repro service credentials.
+- `appName`: Product or workspace label sent as `X-App-Name`.
+- `serviceName`: Backend service label stored on request, trace, DB, queue, Redis,
+  and email events.
+- `apiBase`: Repro API base URL. Used by backend live sessions and privacy policy fetches.
+- `captureHeaders`: Enables header capture. Sensitive headers are masked unless
+  explicitly unmasked.
+- `masking`: Local masking rules for request bodies, response bodies, and trace values.
+- `privacy`: Runtime privacy policy fetch and enforcement configuration.
+- `liveMode`: Backend-owned live capture for requests without frontend Repro context.
+- `tracing`: Function and HTTP instrumentation options. Pass `false` to disable.
+
+## Header And Body Masking
 
 ```ts
-import { patchKafkaJs } from 'repro-nest';
-
-patchKafkaJs({
-  appId: process.env.REPRO_APP_ID as string,
-  appName: process.env.REPRO_APP_NAME as string,
-  serviceName: process.env.REPRO_SERVICE_NAME as string,
-  tenantId: process.env.REPRO_TENANT_ID as string,
-  appSecret: process.env.REPRO_APP_SECRET as string,
+await initRepro({
+  tenantId: process.env.REPRO_TENANT_ID!,
+  appId: process.env.REPRO_APP_ID!,
+  appSecret: process.env.REPRO_APP_SECRET!,
+  captureHeaders: {
+    maskHeaders: [/authorization/i, /cookie/i],
+    unmaskHeaders: ["x-request-id"],
+  },
+  masking: {
+    replacement: "[REDACTED]",
+    rules: [
+      {
+        when: { method: "POST", path: "/api/auth/login" },
+        target: ["request.body", "response.body"],
+        paths: ["password"],
+        keys: [/token/i],
+      },
+      {
+        when: { wrapperClass: "UsersService", functionName: "create" },
+        target: "trace.args",
+        paths: ["0.password"],
+      },
+    ],
+  },
 });
 ```
 
-Notes:
-- `kafkajs` must be installed in the host service.
-- The integration is a no-op when `kafkajs` is not present.
+Mask targets:
+- `request.headers`
+- `request.body`
+- `request.params`
+- `request.query`
+- `response.body`
+- `trace.args`
+- `trace.returnValue`
+- `trace.error`
 
-## 3) Run
+## Runtime Privacy
 
-Run your Nest app as usual after wiring the SDK:
+The SDK can fetch an approved runtime privacy policy at startup and apply it to
+captured request, trace, DB, queue, Redis, and email values before upload.
 
-```bash
-npm run start:dev
-# or
-node dist/main.js
+```ts
+await initRepro({
+  tenantId: process.env.REPRO_TENANT_ID!,
+  appId: process.env.REPRO_APP_ID!,
+  appSecret: process.env.REPRO_APP_SECRET!,
+  apiBase: process.env.REPRO_API_BASE,
+  privacy: {
+    environment: process.env.REPRO_PRIVACY_ENV ?? "dev",
+    apiBase: process.env.REPRO_PRIVACY_API_BASE ?? process.env.REPRO_API_BASE,
+    fetchTimeoutMs: 2500,
+    startupMaxWaitMs: 10000,
+    startupRetryDelayMs: 500,
+  },
+});
 ```
 
-If you use `initReproTracing`, keep it at the top of your bootstrap so modules
-load after instrumentation is enabled.
+Use `privacy.captureRaw: true` only in controlled local development.
+
+## Verify
 
-## 4) Verify It Works
+With the React SDK, record a browser session in `live` mode or start a manual QA
+capture in `staging` mode from the small Repro button, then call your backend.
+The Node SDK captures requests when Repro context is present as headers or safe
+query params.
 
-Send a request with Repro headers and confirm the session shows up in Repro.
+For a manual smoke test:
 
 ```bash
 curl \
   -H "x-bug-session-id: session-123" \
   -H "x-bug-action-id: action-123" \
+  -H "x-bug-request-start: 1770000000000" \
   http://localhost:3000/health
 ```
 
-Verification tips:
-- If the Repro UI does not show the session, confirm `REPRO_INGEST_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.
+Verification checklist:
+- The session timeline shows the backend request and response.
+- Function traces appear for code loaded after `initRepro`.
+- Mongoose or MongoDB operations appear when those packages are used.
+- Queue, Redis, and SendGrid events appear when their integrations are installed
+  and exercised during a captured request.
+- Sensitive headers and configured payload fields are masked before upload.