@reproapp/node-sdk 0.0.3 → 0.0.4

package/README.md

@@ -39,6 +39,7 @@ import {
 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,
 };
@@ -66,8 +67,9 @@ bootstrap();
 ```
 
 Configuration notes:
-- `REPRO_API_BASE` (optional) overrides the backend base URL used to send data.
+- `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
 
@@ -155,6 +157,7 @@ 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
@@ -197,6 +200,7 @@ 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: {
@@ -259,6 +263,7 @@ document diffs. It emits data only when a Repro session is active (i.e., when
 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
 
@@ -271,6 +276,7 @@ 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,
 }));
@@ -287,6 +293,7 @@ MongooseModule.forRoot(process.env.MONGO_URL as string, {
     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,
     }));
@@ -305,11 +312,38 @@ 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,
 }));
 ```
 
+### KafkaJS integration
+
+`patchKafkaJs` instruments `kafkajs` producers and consumers.
+
+- Producer calls (`send`, `sendBatch`) propagate Repro trace/session headers.
+- Consumer handlers (`eachMessage`, `eachBatch`) restore context and emit backend
+  request + trace batches for Kafka processing.
+
+Call it once during bootstrap, before creating producers/consumers:
+
+```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,
+});
+```
+
+Notes:
+- `kafkajs` must be installed in the host service.
+- The integration is a no-op when `kafkajs` is not present.
+
 ## 3) Run
 
 Run your Nest app as usual after wiring the SDK:
@@ -335,7 +369,7 @@ curl \
 ```
 
 Verification tips:
-- If the Repro UI does not show the session, confirm `REPRO_API_BASE` and
+- 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.

package/dist/index.d.ts

@@ -25,6 +25,8 @@
 /// <reference types="mongoose/types/inferrawdoctype" />
 import type { Request, Response, NextFunction } from 'express';
 import type { Schema } from 'mongoose';
+import { type IngestClientConfig } from './ingest/client';
+import { type NormalizedRuntimePrivacyPolicy, type RuntimePrivacyConfig } from './privacy';
 type SpanContext = {
     traceId: string | null;
     spanId: string | number | null;
@@ -54,6 +56,68 @@ export type TraceEventForFilter = {
     depth?: number;
     library?: string | null;
 };
+type TraceEventRecord = {
+    t: number;
+    type: 'enter' | 'exit';
+    functionType?: string | null;
+    fn?: string;
+    file?: string;
+    line?: number | null;
+    depth?: number;
+    spanId?: string | number | null;
+    parentSpanId?: string | number | null;
+    args?: any;
+    returnValue?: any;
+    threw?: boolean;
+    error?: any;
+    unawaited?: boolean;
+    argsValueCapture?: TraceValueCaptureRef;
+    returnValueCapture?: TraceValueCaptureRef;
+    errorValueCapture?: TraceValueCaptureRef;
+};
+type PendingTraceEventRecord = TraceEventRecord & {
+    __reproPending?: {
+        candidate?: TraceEventForFilter;
+        argsRaw?: any;
+        returnValueRaw?: any;
+        errorRaw?: any;
+    };
+    __reproSourceFile?: string | null;
+    __reproTraceValueEntries?: TraceValueBatchEntry[];
+};
+type TraceValueCaptureRef = {
+    status: 'stored' | 'truncated-for-storage' | 'skipped-non-meaningful';
+    valueId?: string;
+    projectedKind?: string;
+};
+type TraceValueBatchEntry = {
+    id: string;
+    target: 'db.pk' | 'db.before' | 'db.after' | 'db.query' | 'db.resultMeta' | 'db.error' | 'request.headers' | 'request.body' | 'request.params' | 'request.query' | 'response.body' | 'trace.args' | 'trace.returnValue' | 'trace.error';
+    value: any;
+    truncatedForStorage?: boolean;
+    projectedKind?: string;
+    fn?: string;
+    file?: string;
+    line?: number | null;
+    spanId?: string | number | null;
+    parentSpanId?: string | number | null;
+    batchIndex?: number;
+    eventIndex?: number;
+};
+type TraceMaterializationConfig = {
+    appId: string;
+    appSecret?: string;
+    appName?: string;
+    privacy?: RuntimePrivacyConfig;
+};
+type TraceMaterializationWorkerPayload = {
+    events: PendingTraceEventRecord[];
+    cfg: TraceMaterializationConfig;
+    maskReq: MaskRequestContext;
+    masking: NormalizedMaskingConfig | null;
+    privacy: NormalizedRuntimePrivacyPolicy | null;
+    fullValueCaptureEnabled: boolean;
+};
 export type HeaderRule = string | RegExp;
 export type HeaderCaptureOptions = {
     /** When true, sensitive headers such as Authorization are kept unmasked; default masks them. */
@@ -120,7 +184,7 @@ export type DisableFunctionTraceRule = {
 };
 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 ReproMaskTarget = 'db.pk' | 'db.before' | 'db.after' | 'db.query' | 'db.resultMeta' | 'db.error' | '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;
@@ -161,6 +225,11 @@ type TracerInitOpts = {
     samplingMs?: number;
 };
 export type ReproTracingInitOptions = TracerInitOpts & {
+    /**
+     * When enabled, trace args/return values/errors that lose meaningful data in
+     * preview form are also persisted via sidecar refs for on-demand loading.
+     */
+    fullValueCapture?: boolean;
     /**
      * Optional list of rules or predicates that suppress unwanted function
      * trace events. When omitted, every instrumented function will be
@@ -193,29 +262,85 @@ export type ReproTracingInitOptions = TracerInitOpts & {
 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;
+export declare function __materializePendingTraceEventsForWorker(payload: TraceMaterializationWorkerPayload): Promise<PendingTraceEventRecord[]>;
+type NormalizedMaskRule = {
+    when?: ReproMaskWhen;
+    targets: ReproMaskTarget[];
+    paths: string[][];
+    keys?: TraceRulePattern;
+    replacement: any;
+};
+type NormalizedMaskingConfig = {
+    replacement: any;
+    rules: NormalizedMaskRule[];
+};
+type MaskRequestContext = {
+    method: string;
+    path: string;
+    key: string;
+};
+declare function shareRuntimePrivacyState(source: ReproMiddlewareConfig, target: ReproMiddlewareConfig): void;
+export type ReproMiddlewareConfig = IngestClientConfig & {
     /** 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;
+    /** Optional privacy policy config for deterministic runtime transformations. */
+    privacy?: RuntimePrivacyConfig;
 };
-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;
+export type ReproInitConfig = ReproMiddlewareConfig & {
+    /**
+     * Tracing configuration for function/http instrumentation.
+     * Pass `false` to skip tracer initialization.
+     */
+    tracing?: ReproTracingInitOptions | false;
+    /**
+     * Optional context resolver used by transport integrations when ALS context
+     * is not present.
+     */
+    resolveContext?: () => {
+        sid?: string;
+        aid?: string;
+    } | undefined;
+};
+export declare function reproMiddleware(cfg: ReproMiddlewareConfig): (req: Request, res: Response, next: NextFunction) => Promise<void>;
+export declare function reproMongoosePlugin(cfg: ReproMiddlewareConfig): (schema: Schema) => void;
+type KafkaContextResolver = () => {
+    sid?: string;
+    aid?: string;
+} | undefined;
+export type KafkaJsPatchConfig = ReproMiddlewareConfig & {
+    resolveContext?: KafkaContextResolver;
+};
+declare function recordKafkaTraceEventAsync(raw: any, sink: TraceEventRecord[], cfg: KafkaJsPatchConfig, maskReq: MaskRequestContext): Promise<void>;
+declare function wrapKafkaEachMessageHandler(eachMessage: any, cfg: KafkaJsPatchConfig, consumer: any): (this: any, payload: any) => Promise<any>;
+export declare function patchKafkaJs(cfg: KafkaJsPatchConfig): void;
+export type RedisPatchConfig = ReproMiddlewareConfig & {
+    resolveContext?: () => {
+        sid?: string;
+        aid?: string;
+    } | undefined;
+};
+export declare function patchRedis(cfg: RedisPatchConfig): void;
+export type SendgridPatchConfig = ReproMiddlewareConfig & {
     resolveContext?: () => {
         sid?: string;
         aid?: string;
     } | undefined;
 };
 export declare function patchSendgridMail(cfg: SendgridPatchConfig): void;
+/**
+ * Datadog-style one-time init.
+ * Enables tracing, auto-patches integrations, auto-registers mongoose plugin,
+ * and auto-attaches middleware to Nest/Express applications.
+ */
+export declare function initRepro(cfg: ReproInitConfig): Promise<void>;
+/** @internal Test hooks for runtime privacy policy wiring. */
+export declare const __reproTestHooks: {
+    shareRuntimePrivacyStateForTest: typeof shareRuntimePrivacyState;
+    getRuntimePrivacyPolicyForTest(cfg: ReproMiddlewareConfig): NormalizedRuntimePrivacyPolicy | null;
+    setRuntimePrivacyPolicyForTest(cfg: ReproMiddlewareConfig, policy: NormalizedRuntimePrivacyPolicy | null): void;
+    recordKafkaTraceEventAsyncForTest: typeof recordKafkaTraceEventAsync;
+    wrapKafkaEachMessageHandlerForTest: typeof wrapKafkaEachMessageHandler;
+};
 export {};