@reproapp/node-sdk 0.0.38 → 0.0.41

package/src/index.ts

@@ -323,6 +323,9 @@ const KAFKA_HEADER_SESSION_ID = 'x-bug-session-id';
 const KAFKA_HEADER_ACTION_ID = 'x-bug-action-id';
 const DEFAULT_INGEST_BASE = 'http://localhost:8080';
 const DEFAULT_INGEST_PATH = '/v1/ingest/events';
+const DEFAULT_LIVE_SESSION_DURATION_MS = 3 * 60_000;
+const DEFAULT_LIVE_SEGMENT_IDLE_MS = 15_000;
+const DEFAULT_LIVE_SEGMENT_DURATION_MS = DEFAULT_LIVE_SESSION_DURATION_MS;
 
 function escapeRx(s: string) { return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); }
 let __TRACER__: TracerApi | null = null;
@@ -1220,6 +1223,35 @@ function buildRequestCaptureManifestPayload(
     };
 }
 
+function emitRequestCaptureStart(
+    cfg: IngestClientConfig,
+    sessionId: string | null | undefined,
+    actionId: string | null | undefined,
+    scope: RequestCaptureScopeState,
+    openedAtMs?: number | null,
+): void {
+    if (!sessionId) {
+        return;
+    }
+    const openedAt =
+        typeof openedAtMs === 'number' && Number.isFinite(openedAtMs)
+            ? openedAtMs
+            : alignedNow();
+    post(cfg, sessionId, {
+        entries: [{
+            actionId: actionId ?? null,
+            requestRid: scope.requestRid,
+            requestCaptureStart: {
+                scopeId: `req:${scope.requestRid}`,
+                requestRid: scope.requestRid,
+                transport: scope.transport,
+                openedAt,
+            },
+            t: openedAt,
+        }],
+    }, { priority: 'high' });
+}
+
 const als = new AsyncLocalStorage<Ctx>();
 const getCtx = () => als.getStore() || {};
 
@@ -2078,6 +2110,397 @@ function toIngestConfig(cfg: IngestClientConfig): IngestClientConfig {
     };
 }
 
+function normalizeLiveModeConfig(cfg: ReproMiddlewareConfig): ReproLiveModeConfig | null {
+    const liveMode = cfg.liveMode;
+    if (liveMode === true) {
+        return { enabled: true };
+    }
+    if (!liveMode || typeof liveMode !== 'object') {
+        return null;
+    }
+    if (liveMode.enabled === false) {
+        return null;
+    }
+    return liveMode;
+}
+
+type BackendLiveTimingConfig = {
+    sessionMaxDurationMs: number;
+    segmentMaxDurationMs: number;
+    segmentIdleMs: number;
+};
+
+let backendLiveTimingOverrideForTest: Partial<BackendLiveTimingConfig> | null = null;
+
+function positiveInternalDuration(value: unknown, fallback: number): number {
+    const numeric = Number(value);
+    if (!Number.isFinite(numeric) || numeric <= 0) return fallback;
+    return Math.max(1, Math.trunc(numeric));
+}
+
+function getBackendLiveTiming(): BackendLiveTimingConfig {
+    return {
+        sessionMaxDurationMs: positiveInternalDuration(
+            backendLiveTimingOverrideForTest?.sessionMaxDurationMs,
+            DEFAULT_LIVE_SESSION_DURATION_MS,
+        ),
+        segmentMaxDurationMs: positiveInternalDuration(
+            backendLiveTimingOverrideForTest?.segmentMaxDurationMs,
+            DEFAULT_LIVE_SEGMENT_DURATION_MS,
+        ),
+        segmentIdleMs: positiveInternalDuration(
+            backendLiveTimingOverrideForTest?.segmentIdleMs,
+            DEFAULT_LIVE_SEGMENT_IDLE_MS,
+        ),
+    };
+}
+
+function normalizeLiveActorId(value: unknown): string | null {
+    if (value === undefined || value === null) return null;
+    const normalized = String(value).trim();
+    return normalized.length ? normalized : null;
+}
+
+function normalizeLiveActorLabels(
+    value: Record<string, string | number | boolean | null | undefined> | null | undefined,
+): Record<string, string> | undefined {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined;
+    const labels: Record<string, string> = {};
+    for (const [key, rawValue] of Object.entries(value)) {
+        const normalizedKey = key.trim();
+        if (!normalizedKey || rawValue === undefined || rawValue === null) continue;
+        const normalizedValue = String(rawValue).trim();
+        if (normalizedValue) labels[normalizedKey] = normalizedValue;
+    }
+    return Object.keys(labels).length ? labels : undefined;
+}
+
+function newSessionId(base: number = Date.now()): string {
+    return `S_${Math.max(0, Math.trunc(base))}_${randomUUID().slice(0, 8)}`;
+}
+
+function newActionId(base: number = Date.now()): string {
+    return `A_${Math.max(0, Math.trunc(base))}_${randomUUID().slice(0, 8)}`;
+}
+
+function resolveLiveApiBase(cfg: ReproMiddlewareConfig, liveMode?: ReproLiveModeConfig | null): string | null {
+    const env = typeof process !== 'undefined' ? (process as any)?.env : undefined;
+    const raw =
+        liveMode?.apiBase ||
+        cfg.apiBase ||
+        env?.REPRO_API_BASE_URL ||
+        env?.REPRO_API_BASE ||
+        (cfg.privacy as RuntimePrivacyConfig | undefined)?.apiBase ||
+        null;
+    if (typeof raw !== 'string' || !raw.trim()) return null;
+    return raw.trim().replace(/\/+$/, '');
+}
+
+function liveApiHeaders(cfg: ReproMiddlewareConfig): Record<string, string> {
+    const headers: Record<string, string> = {
+        'Content-Type': 'application/json',
+        'X-App-Id': cfg.appId,
+    };
+    if (cfg.appSecret) {
+        headers['X-App-Secret'] = cfg.appSecret;
+    }
+    if (cfg.appName) {
+        headers['X-App-Name'] = cfg.appName;
+    }
+    return headers;
+}
+
+async function postLiveApi(
+    cfg: ReproMiddlewareConfig,
+    liveMode: ReproLiveModeConfig | null,
+    path: string,
+    body: Record<string, any>,
+): Promise<void> {
+    await postLiveApiJson(cfg, liveMode, path, body);
+}
+
+async function postLiveApiJson<T = Record<string, any>>(
+    cfg: ReproMiddlewareConfig,
+    liveMode: ReproLiveModeConfig | null,
+    path: string,
+    body: Record<string, any>,
+): Promise<T | null> {
+    const apiBase = resolveLiveApiBase(cfg, liveMode);
+    const fetchImpl = (globalThis as any).fetch;
+    if (!apiBase || !cfg.appId || !cfg.appSecret || typeof fetchImpl !== 'function') {
+        return null;
+    }
+    try {
+        const res = await fetchImpl(`${apiBase}${path}`, {
+            method: 'POST',
+            headers: liveApiHeaders(cfg),
+            body: JSON.stringify(body),
+        });
+        if (!res?.ok) {
+            return null;
+        }
+        try {
+            return await res.json();
+        } catch {
+            return null;
+        }
+    } catch {
+        // never break user code
+        return null;
+    }
+}
+
+function enqueueLiveSessionStart(
+    cfg: ReproMiddlewareConfig,
+    liveMode: ReproLiveModeConfig | null,
+    payload: Record<string, any>,
+): void {
+    scheduleSdkBackgroundWork(
+        () => postLiveApi(cfg, liveMode, '/v1/live-sessions', payload),
+        { priority: 'high' },
+    );
+}
+
+function enqueueLiveSessionFinish(
+    cfg: ReproMiddlewareConfig,
+    liveMode: ReproLiveModeConfig | null,
+    sessionId: string,
+): void {
+    scheduleSdkBackgroundWork(
+        () => postLiveApi(
+            cfg,
+            liveMode,
+            `/v1/live-sessions/${encodeURIComponent(sessionId)}/finish`,
+            { notes: '' },
+        ),
+        { priority: 'high' },
+    );
+}
+
+function emitBackendLiveSessionManifest(
+    cfg: ReproMiddlewareConfig,
+    session: BackendLiveParentSession | BackendLiveChildSession,
+    options: {
+        sessionKind: 'parent' | 'child';
+        actorId: string;
+        actorType: string;
+        actorLabels?: Record<string, string>;
+        parentSessionId?: string | null;
+        previousSessionId?: string | null;
+        closedAt: number;
+    },
+): void {
+    post(cfg, session.sessionId, {
+        entries: [{
+            sessionCaptureManifest: {
+                mode: 'backend-only',
+                captureMode: 'backend-only',
+                sessionKind: options.sessionKind,
+                parentSessionId: options.parentSessionId ?? null,
+                previousSessionId: options.previousSessionId ?? null,
+                actorId: options.actorId,
+                actorType: options.actorType,
+                actorLabels: options.actorLabels,
+                expected: {
+                    frontendActionDoc: 0,
+                    rrwebChunk: 0,
+                    frontendSessionEnd: 0,
+                },
+                closedAt: options.closedAt,
+            },
+            t: options.closedAt,
+        }],
+    }, { priority: 'high' });
+}
+
+function closeBackendLiveParent(
+    cfg: ReproMiddlewareConfig,
+    liveMode: ReproLiveModeConfig | null,
+    state: BackendLiveActorState,
+    parent: BackendLiveParentSession,
+    closedAt: number,
+): void {
+    if (parent.closed) {
+        return;
+    }
+    parent.closed = true;
+    if (parent.closeTimer) {
+        try { clearTimeout(parent.closeTimer); } catch {}
+        parent.closeTimer = null;
+    }
+    state.previousParentSessionId = parent.sessionId;
+    if (state.parent === parent) {
+        state.parent = null;
+    }
+    emitBackendLiveSessionManifest(cfg, parent, {
+        sessionKind: 'parent',
+        actorId: parent.actorId,
+        actorType: parent.actorType,
+        actorLabels: parent.actorLabels,
+        previousSessionId: parent.previousSessionId,
+        closedAt,
+    });
+    enqueueLiveSessionFinish(cfg, liveMode, parent.sessionId);
+}
+
+function scheduleBackendLiveParentClose(
+    cfg: ReproMiddlewareConfig,
+    liveMode: ReproLiveModeConfig | null,
+    state: BackendLiveActorState,
+    parent: BackendLiveParentSession,
+): void {
+    if (parent.closed) {
+        return;
+    }
+    if (parent.closeTimer) {
+        try { clearTimeout(parent.closeTimer); } catch {}
+        parent.closeTimer = null;
+    }
+
+    const now = Date.now();
+    const activeChild = state.activeChild;
+    const activeChildBelongsToParent =
+        activeChild?.parentSessionId === parent.sessionId;
+    const closeAt =
+        activeChildBelongsToParent && now >= parent.expiresAt
+            ? Math.max(parent.expiresAt, activeChild.closeDeadline, now + 1)
+            : parent.expiresAt;
+
+    parent.closeTimer = setTimeout(() => {
+        parent.closeTimer = null;
+        if (parent.closed || state.parent !== parent) {
+            return;
+        }
+
+        const currentChild = state.activeChild;
+        if (currentChild?.parentSessionId === parent.sessionId) {
+            if (currentChild.requestsInFlight <= 0) {
+                scheduleBackendLiveChildClose(cfg, liveMode, state, currentChild);
+            }
+            scheduleBackendLiveParentClose(cfg, liveMode, state, parent);
+            return;
+        }
+
+        closeBackendLiveParent(cfg, liveMode, state, parent, Date.now());
+    }, Math.max(0, closeAt - now));
+    try { (parent.closeTimer as any).unref?.(); } catch {}
+}
+
+function scheduleBackendLiveChildClose(
+    cfg: ReproMiddlewareConfig,
+    liveMode: ReproLiveModeConfig | null,
+    state: BackendLiveActorState,
+    child: BackendLiveChildSession,
+): void {
+    if (child.closeTimer) {
+        try { clearTimeout(child.closeTimer); } catch {}
+        child.closeTimer = null;
+    }
+    const delay = Math.max(0, child.closeDeadline - Date.now());
+    child.closeTimer = setTimeout(() => {
+        child.closeTimer = null;
+        if (child.requestsInFlight > 0 || Date.now() < child.closeDeadline) {
+            scheduleBackendLiveChildClose(cfg, liveMode, state, child);
+            return;
+        }
+        if (state.activeChild === child) {
+            state.activeChild = null;
+        }
+        state.previousChildSessionId = child.sessionId;
+        const closedAt = Date.now();
+        emitBackendLiveSessionManifest(cfg, child, {
+            sessionKind: 'child',
+            actorId: child.actorId,
+            actorType: child.actorType,
+            actorLabels: child.actorLabels,
+            parentSessionId: child.parentSessionId,
+            previousSessionId: child.previousSessionId,
+            closedAt,
+        });
+        enqueueLiveSessionFinish(cfg, liveMode, child.sessionId);
+    }, delay);
+    try { (child.closeTimer as any).unref?.(); } catch {}
+}
+
+function releaseBackendLiveRequest(
+    cfg: ReproMiddlewareConfig,
+    liveMode: ReproLiveModeConfig | null,
+    state: BackendLiveActorState,
+    child: BackendLiveChildSession,
+    finishedAt: number,
+): void {
+    child.requestsInFlight = Math.max(0, child.requestsInFlight - 1);
+    const idleMs = getBackendLiveTiming().segmentIdleMs;
+    child.closeDeadline = Math.max(child.closeDeadline, finishedAt + idleMs);
+    if (child.requestsInFlight <= 0) {
+        scheduleBackendLiveChildClose(cfg, liveMode, state, child);
+    }
+}
+
+async function resolveBackendLiveContext(
+    cfg: ReproMiddlewareConfig,
+    req: Request,
+    requestStart: number,
+): Promise<BackendLiveResolvedContext | null> {
+    const liveMode = normalizeLiveModeConfig(cfg);
+    if (!liveMode?.backendOnly) {
+        return null;
+    }
+
+    const method = String(req.method || 'GET').toUpperCase();
+    if (method === 'OPTIONS' && !hasReproRequestCorrelation(req)) {
+        return null;
+    }
+    const identity = await resolveLiveActorIdentity(cfg, req);
+    if (!identity) {
+        return null;
+    }
+    const { actorId, actorType, actorLabels } = identity;
+
+    const claim = await postLiveApiJson<BackendLiveClaimResponse>(
+        cfg,
+        liveMode,
+        '/v1/live-sessions/claim',
+        {
+            clientTime: requestStart,
+            captureMode: 'backend-only',
+            actorId,
+            actorIds: [actorId],
+            actorType,
+            actorLabels,
+        },
+    );
+    const sid =
+        normalizeLiveActorId(claim?.childSessionId) ??
+        normalizeLiveActorId(claim?.sessionId);
+    if (!sid) {
+        return null;
+    }
+
+    const aid = normalizeLiveActorId(claim?.actionId) ?? newActionId(requestStart);
+    const parentSessionId = normalizeLiveActorId(claim?.parentSessionId) ?? '';
+    const liveChild: BackendLiveChildSession = {
+        sessionId: sid,
+        parentSessionId,
+        previousSessionId: null,
+        actorId,
+        actorType,
+        actorLabels,
+        startedAt: requestStart,
+        expiresAt: requestStart,
+        closeDeadline: requestStart,
+        requestsInFlight: 0,
+        closeTimer: null,
+    };
+
+    return {
+        sid: liveChild.sessionId,
+        aid,
+        requestStart,
+        child: liveChild,
+    };
+}
+
 function resolveIngestUrl(cfg: IngestClientConfig): string {
     const envBase = typeof process !== 'undefined' ? (process as any)?.env?.REPRO_INGEST_BASE : undefined;
     const ingestBase = String(envBase || cfg.ingestBase || DEFAULT_INGEST_BASE).replace(/\/+$/, '');
@@ -2125,6 +2548,24 @@ function readRequestQueryNumber(req: Request, name: string): number | null {
     return Number.isFinite(parsed) ? parsed : null;
 }
 
+function hasReproRequestCorrelation(req: Request): boolean {
+    const headers = req.headers || {};
+    if (
+        hasHttpHeader(headers, KAFKA_HEADER_SESSION_ID) ||
+        hasHttpHeader(headers, KAFKA_HEADER_ACTION_ID) ||
+        hasHttpHeader(headers, KAFKA_HEADER_REQUEST_ID) ||
+        hasHttpHeader(headers, KAFKA_HEADER_TRACE_ID) ||
+        hasHttpHeader(headers, KAFKA_HEADER_SPAN_ID) ||
+        hasHttpHeader(headers, KAFKA_HEADER_PARENT_SPAN_ID)
+    ) {
+        return true;
+    }
+    return Boolean(
+        readRequestQueryParam(req, REPRO_QUERY_SESSION_PARAM) ||
+        readRequestQueryParam(req, REPRO_QUERY_ACTION_PARAM),
+    );
+}
+
 function stripReproQueryFromUrl(rawUrl: string): string {
     if (!rawUrl || !rawUrl.includes('?')) {
         return rawUrl;
@@ -5008,14 +5449,193 @@ async function maybeCaptureDbValueFromCandidatesAsync(
 // reproMiddleware — unchanged behavior + passive per-request trace
 // ===================================================================
 export type ReproMiddlewareConfig = IngestClientConfig & {
+    /** API base used for backend-owned live session documents. Defaults to REPRO_API_BASE_URL/REPRO_API_BASE/privacy.apiBase. */
+    apiBase?: 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;
     /** Optional privacy policy config for deterministic runtime transformations. */
     privacy?: RuntimePrivacyConfig;
+    /** Opt-in production/live capture mode. Staging/manual tagged capture is unchanged when disabled. */
+    liveMode?: ReproLiveModeConfig | boolean;
 };
 
+export type ReproLiveActorArgs = {
+    req: Request;
+    headers: Request['headers'];
+    method: string;
+    url: string;
+    path: string;
+    ip?: string | null;
+    appId: string;
+    appName?: string;
+    serviceName?: string;
+};
+
+export type ReproLiveActorDecision = ReproLiveActorArgs & {
+    actorId: string;
+    actorType?: string;
+    actorLabels?: Record<string, string>;
+};
+
+export type ReproLiveModeConfig = {
+    enabled?: boolean;
+    backendOnly?: boolean;
+    /**
+     * Stable actor/correlation key for live capture. Return null/undefined/empty
+     * to skip capture for that request.
+     */
+    defineActorId?: (
+        args: ReproLiveActorArgs,
+    ) => string | number | null | undefined | Promise<string | number | null | undefined>;
+    /**
+     * Optional filter for segmenting which actors/requests are captured.
+     */
+    shouldCapture?: (
+        args: ReproLiveActorDecision,
+    ) => boolean | Promise<boolean>;
+    actorType?: string;
+    actorLabels?:
+        | Record<string, string | number | boolean | null | undefined>
+        | ((args: ReproLiveActorDecision) =>
+            | Record<string, string | number | boolean | null | undefined>
+            | null
+            | undefined
+            | Promise<Record<string, string | number | boolean | null | undefined> | null | undefined>);
+    apiBase?: string;
+};
+
+type BackendLiveParentSession = {
+    sessionId: string;
+    startedAt: number;
+    expiresAt: number;
+    previousSessionId: string | null;
+    actorId: string;
+    actorType: string;
+    actorLabels?: Record<string, string>;
+    closeTimer?: NodeJS.Timeout | null;
+    closed?: boolean;
+};
+
+type BackendLiveChildSession = {
+    sessionId: string;
+    parentSessionId: string;
+    previousSessionId: string | null;
+    actorId: string;
+    actorType: string;
+    actorLabels?: Record<string, string>;
+    startedAt: number;
+    expiresAt: number;
+    closeDeadline: number;
+    requestsInFlight: number;
+    closeTimer?: NodeJS.Timeout | null;
+};
+
+type BackendLiveActorState = {
+    actorId: string;
+    parent: BackendLiveParentSession | null;
+    previousParentSessionId: string | null;
+    activeChild: BackendLiveChildSession | null;
+    previousChildSessionId: string | null;
+};
+
+type BackendLiveActorIdentity = {
+    actorId: string;
+    actorType: string;
+    actorLabels?: Record<string, string>;
+};
+
+type BackendLiveResolvedContext = {
+    sid: string;
+    aid: string;
+    requestStart: number;
+    child: BackendLiveChildSession;
+};
+
+type BackendLiveClaimResponse = {
+    parentSessionId?: string | null;
+    childSessionId?: string | null;
+    sessionId?: string | null;
+    actionId?: string | null;
+    clockOffsetMs?: number | null;
+};
+
+function buildLiveActorArgs(cfg: ReproMiddlewareConfig, req: Request): ReproLiveActorArgs {
+    const rawUrl = String((req as any).originalUrl || req.url || '/');
+    const path = rawUrl.split('?')[0] || '/';
+    return {
+        req,
+        headers: req.headers,
+        method: String(req.method || 'GET').toUpperCase(),
+        url: rawUrl,
+        path,
+        ip: (req as any).ip ?? (req as any).socket?.remoteAddress ?? null,
+        appId: cfg.appId,
+        appName: cfg.appName,
+        serviceName: cfg.serviceName,
+    };
+}
+
+async function resolveLiveActorIdentity(
+    cfg: ReproMiddlewareConfig,
+    req: Request,
+): Promise<BackendLiveActorIdentity | null> {
+    const liveMode = normalizeLiveModeConfig(cfg);
+    if (!liveMode) {
+        return null;
+    }
+
+    const args = buildLiveActorArgs(cfg, req);
+    let rawActorId: string | number | null | undefined;
+    try {
+        rawActorId = liveMode.defineActorId
+            ? await liveMode.defineActorId(args)
+            : cfg.actorId;
+    } catch {
+        rawActorId = null;
+    }
+    const actorId = normalizeLiveActorId(rawActorId);
+    if (!actorId) {
+        return null;
+    }
+
+    const actorType = normalizeLiveActorId(liveMode.actorType) ?? cfg.actorType ?? 'user';
+    const decision: ReproLiveActorDecision = {
+        ...args,
+        actorId,
+        actorType,
+    };
+    if (liveMode.shouldCapture) {
+        let shouldCapture = false;
+        try {
+            shouldCapture = (await liveMode.shouldCapture(decision)) === true;
+        } catch {
+            shouldCapture = false;
+        }
+        if (!shouldCapture) {
+            return null;
+        }
+    }
+
+    let rawLabels:
+        | Record<string, string | number | boolean | null | undefined>
+        | null
+        | undefined;
+    try {
+        rawLabels =
+            typeof liveMode.actorLabels === 'function'
+                ? await liveMode.actorLabels(decision)
+                : liveMode.actorLabels;
+    } catch {
+        rawLabels = undefined;
+    }
+    const actorLabels = normalizeLiveActorLabels(rawLabels) ?? normalizeLiveActorLabels(cfg.actorLabels);
+    return { actorId, actorType, actorLabels };
+}
+
+const backendLiveActors = new Map<string, BackendLiveActorState>();
+
 export type ReproInitConfig = ReproMiddlewareConfig & {
     /**
      * Tracing configuration for function/http instrumentation.
@@ -5060,22 +5680,68 @@ export function reproMiddleware(cfg: ReproMiddlewareConfig) {
             endClientRequest();
         };
 
-        const sid = (req.headers['x-bug-session-id'] as string) || querySid || '';
-        const aid = (req.headers['x-bug-action-id'] as string) || queryAid || '';
+        const requestStartRaw = Date.now();
+        const headerTs = readHeaderNumber(req.headers[REQUEST_START_HEADER]) ?? queryTs;
+        const requestEpochMs = headerTs !== null ? headerTs : requestStartRaw;
+        let backendLiveState: BackendLiveActorState | null = null;
+        let backendLiveChild: BackendLiveChildSession | null = null;
+        const headerSid = (req.headers['x-bug-session-id'] as string) || '';
+        const headerAid = (req.headers['x-bug-action-id'] as string) || '';
+        const hasIncomingReproSession = Boolean(headerSid || querySid || headerAid || queryAid);
+        const backendLiveContext =
+            !hasIncomingReproSession
+                ? await resolveBackendLiveContext(cfg, req, requestEpochMs)
+                : null;
+        const taggedActorIdentity = hasIncomingReproSession
+            ? await resolveLiveActorIdentity(cfg, req)
+            : null;
+        if (backendLiveContext) {
+            backendLiveState = backendLiveActors.get(backendLiveContext.child.actorId) ?? null;
+            backendLiveChild = backendLiveContext.child;
+        }
+        const sid = headerSid || querySid || backendLiveContext?.sid || '';
+        const aid = headerAid || queryAid || backendLiveContext?.aid || '';
         if (!sid || !aid) {
             res.on('finish', endTrackedClientRequest);
             res.on('close', endTrackedClientRequest);
             return next(); // only capture tagged requests
         }
+        const captureCfg: ReproMiddlewareConfig = backendLiveChild
+            ? {
+                ...cfg,
+                actorId: backendLiveChild.actorId,
+                actorType: backendLiveChild.actorType,
+                actorLabels: backendLiveChild.actorLabels,
+            }
+            : taggedActorIdentity
+                ? {
+                    ...cfg,
+                    actorId: taggedActorIdentity.actorId,
+                    actorType: taggedActorIdentity.actorType,
+                    actorLabels: taggedActorIdentity.actorLabels,
+                }
+            : cfg;
+        if (taggedActorIdentity) {
+            post(captureCfg, sid, {
+                entries: [{
+                    actionId: aid,
+                    sessionActor: {
+                        actorId: taggedActorIdentity.actorId,
+                        actorType: taggedActorIdentity.actorType,
+                        actorLabels: taggedActorIdentity.actorLabels,
+                        source: 'node-sdk',
+                    },
+                    t: requestEpochMs,
+                }],
+            }, { priority: 'high' });
+        }
         const resolvePrivacy = (): NormalizedRuntimePrivacyPolicy | null =>
-            getRuntimePrivacyState(cfg).policy ?? null;
+            getRuntimePrivacyState(captureCfg).policy ?? null;
 
-        const requestStartRaw = Date.now();
-        const headerTs = readHeaderNumber(req.headers[REQUEST_START_HEADER]) ?? queryTs;
         const clockSkewMs = headerTs !== null ? headerTs - requestStartRaw : 0;
-        const requestEpochMs = headerTs !== null ? headerTs : requestStartRaw + clockSkewMs;
         const rid = nextRequestId(requestEpochMs);
         const captureScope = createRequestCaptureScope(rid, 'http');
+        emitRequestCaptureStart(captureCfg, sid, aid, captureScope, requestEpochMs);
         const t0 = requestStartRaw;
         const url = (req as any).originalUrl || req.url || '/';
         const urlPathOnly = (url || '/').split('?')[0] || '/';
@@ -5271,7 +5937,7 @@ export function reproMiddleware(cfg: ReproMiddlewareConfig) {
                     ?? await materializeInlinePrivacyValueAsync(
                         'request.body',
                         sanitizeRequestSnapshot(requestBodyRaw),
-                        cfg,
+                        captureCfg,
                         maskReq,
                         endpointTraceCtx,
                         masking,
@@ -5281,7 +5947,7 @@ export function reproMiddleware(cfg: ReproMiddlewareConfig) {
                 const requestParams = await applyPrivacyThenMaskAsync(
                     'request.params',
                     sanitizeRequestSnapshot((req as any).params),
-                    cfg,
+                    captureCfg,
                     maskReq,
                     endpointTraceCtx,
                     masking,
@@ -5290,7 +5956,7 @@ export function reproMiddleware(cfg: ReproMiddlewareConfig) {
                 const requestQuery = await applyPrivacyThenMaskAsync(
                     'request.query',
                     sanitizeRequestSnapshot((req as any).query),
-                    cfg,
+                    captureCfg,
                     maskReq,
                     endpointTraceCtx,
                     masking,
@@ -5299,7 +5965,7 @@ export function reproMiddleware(cfg: ReproMiddlewareConfig) {
                 const maskedHeaders = await applyPrivacyThenMaskAsync(
                     'request.headers',
                     requestHeaders,
-                    cfg,
+                    captureCfg,
                     maskReq,
                     endpointTraceCtx,
                     masking,
@@ -5311,7 +5977,7 @@ export function reproMiddleware(cfg: ReproMiddlewareConfig) {
                         ?? await materializeInlinePrivacyValueAsync(
                             'response.body',
                             sanitizeRequestSnapshot(capturedBody),
-                            cfg,
+                            captureCfg,
                             maskReq,
                             endpointTraceCtx,
                             masking,
@@ -5326,7 +5992,7 @@ export function reproMiddleware(cfg: ReproMiddlewareConfig) {
                         rawValue: (req as any).body,
                         previewValue: requestBody,
                         capture: {
-                            runtimeConfig: cfg,
+                            runtimeConfig: captureCfg,
                             captureHeaders: cfg.captureHeaders,
                             maskReq,
                             trace: endpointTraceCtx,
@@ -5339,7 +6005,7 @@ export function reproMiddleware(cfg: ReproMiddlewareConfig) {
                     rawValue: (req as any).params,
                     previewValue: requestParams,
                     capture: {
-                        runtimeConfig: cfg,
+                        runtimeConfig: captureCfg,
                         captureHeaders: cfg.captureHeaders,
                         maskReq,
                         trace: endpointTraceCtx,
@@ -5352,7 +6018,7 @@ export function reproMiddleware(cfg: ReproMiddlewareConfig) {
                     rawValue: (req as any).query,
                     previewValue: requestQuery,
                     capture: {
-                        runtimeConfig: cfg,
+                        runtimeConfig: captureCfg,
                         captureHeaders: cfg.captureHeaders,
                         maskReq,
                         trace: endpointTraceCtx,
@@ -5365,7 +6031,7 @@ export function reproMiddleware(cfg: ReproMiddlewareConfig) {
                     rawValue: req.headers,
                     previewValue: maskedHeaders,
                     capture: {
-                        runtimeConfig: cfg,
+                        runtimeConfig: captureCfg,
                         captureHeaders: cfg.captureHeaders,
                         maskReq,
                         trace: endpointTraceCtx,
@@ -5380,7 +6046,7 @@ export function reproMiddleware(cfg: ReproMiddlewareConfig) {
                         rawValue: capturedBody,
                         previewValue: responseBody,
                         capture: {
-                            runtimeConfig: cfg,
+                            runtimeConfig: captureCfg,
                             captureHeaders: cfg.captureHeaders,
                             maskReq,
                             trace: endpointTraceCtx,
@@ -5440,7 +6106,7 @@ export function reproMiddleware(cfg: ReproMiddlewareConfig) {
                         chosenEndpoint,
                         hasTraceEvents,
                     );
-                    post(cfg, sid, {
+                    post(captureCfg, sid, {
                         entries: [{
                             actionId: aid,
                             request: requestPayload,
@@ -5457,7 +6123,7 @@ export function reproMiddleware(cfg: ReproMiddlewareConfig) {
             const emitRequestCaptureManifest = (traceBatchTotal: number): void => {
                 if (requestCaptureManifestScheduled) return;
                 requestCaptureManifestScheduled = true;
-                post(cfg, sid, {
+                post(captureCfg, sid, {
                     entries: [{
                         actionId: aid,
                         requestRid: rid,
@@ -5569,7 +6235,7 @@ export function reproMiddleware(cfg: ReproMiddlewareConfig) {
                         try {
                             const pendingEvents = preparePendingTraceEventsForFlush(events.slice());
                             const materializedEvents = await materializePendingTraceEventsAsync(pendingEvents, {
-                                cfg,
+                                cfg: captureCfg,
                                 maskReq,
                                 masking,
                                 resolvePrivacy,
@@ -5602,7 +6268,7 @@ export function reproMiddleware(cfg: ReproMiddlewareConfig) {
                                 const batch = traceBatches[i];
                                 const traceValues = collectBatchTraceValueEntries(batch, i);
 
-                                post(cfg, sid, {
+                                post(captureCfg, sid, {
                                     entries: [{
                                         actionId: aid,
                                         trace: batch,
@@ -5624,6 +6290,15 @@ export function reproMiddleware(cfg: ReproMiddlewareConfig) {
 
                 sessionDrainWait = waitForSessionDrain(sid);
                 endSessionRequest(sid);
+                if (backendLiveState && backendLiveChild) {
+                    releaseBackendLiveRequest(
+                        cfg,
+                        normalizeLiveModeConfig(cfg),
+                        backendLiveState,
+                        backendLiveChild,
+                        finishedAtAligned ?? alignedNow(),
+                    );
+                }
                 endTrackedClientRequest();
 
                 if (__TRACER_READY) {
@@ -7165,6 +7840,7 @@ function patchKafkaProducerInstance(producer: any, cfg: KafkaJsPatchConfig) {
             const span = captureSpanContextFromTracer();
             const publishRid = nextRequestId(alignedNow());
             const captureScope = createRequestCaptureScope(publishRid, 'kafka');
+            emitRequestCaptureStart(cfg, sid, aid, captureScope);
             const payloadObj = payload && typeof payload === 'object' ? payload : {};
             const topic = sanitizeKafkaTopic((payloadObj as any).topic);
             const rawMessages = Array.isArray((payloadObj as any).messages) ? (payloadObj as any).messages : [];
@@ -7279,6 +7955,7 @@ function patchKafkaProducerInstance(producer: any, cfg: KafkaJsPatchConfig) {
             const span = captureSpanContextFromTracer();
             const publishRid = nextRequestId(alignedNow());
             const captureScope = createRequestCaptureScope(publishRid, 'kafka');
+            emitRequestCaptureStart(cfg, sid, aid, captureScope);
 
             const payloadObj = payload && typeof payload === 'object' ? payload : {};
             const topicMessages = Array.isArray((payloadObj as any).topicMessages)
@@ -7429,6 +8106,7 @@ function wrapKafkaEachMessageHandler(eachMessage: any, cfg: KafkaJsPatchConfig,
         const consumeRid = nextRequestId(`${topic}-${message?.offset ?? alignedNow()}`);
         const traceId = consumeRid;
         const captureScope = createRequestCaptureScope(consumeRid, 'kafka');
+        emitRequestCaptureStart(cfg, sid, aid, captureScope);
         const rawTraceEvents: any[] = [];
         const maskReq: MaskRequestContext = {
             method: 'KAFKA_CONSUME',
@@ -7539,6 +8217,7 @@ function wrapKafkaEachBatchHandler(eachBatch: any, cfg: KafkaJsPatchConfig, cons
         const consumeRid = nextRequestId(`${topic}-batch-${alignedNow()}`);
         const traceId = consumeRid;
         const captureScope = createRequestCaptureScope(consumeRid, 'kafka');
+        emitRequestCaptureStart(cfg, sid, aid, captureScope);
         const rawTraceEvents: any[] = [];
         const maskReq: MaskRequestContext = {
             method: 'KAFKA_CONSUME_BATCH',
@@ -8246,6 +8925,7 @@ function patchAmqplibPublishMethod(
         const key = `${method} ${methodName === 'publish' ? `${exchange || 'default'}/${routingKey}` : queue}`;
         const content = methodName === 'publish' ? args[2] : args[1];
         const captureScope = createRequestCaptureScope(publishRid, 'amqp');
+        emitRequestCaptureStart(cfg, sid, aid, captureScope);
         const t0 = Date.now();
         let finished = false;
 
@@ -8335,6 +9015,7 @@ function wrapAmqplibConsumeHandler(onMessage: any, cfg: AmqplibPatchConfig, queu
         const consumeRid = nextRequestId(`${queueName}-${deliveryTag}`);
         const traceId = consumeRid;
         const captureScope = createRequestCaptureScope(consumeRid, 'amqp');
+        emitRequestCaptureStart(cfg, sid, aid, captureScope);
         const rawTraceEvents: any[] = [];
         const maskReq: MaskRequestContext = {
             method: 'AMQP_CONSUME',
@@ -8938,6 +9619,616 @@ export function patchRedis(cfg: RedisPatchConfig) {
     }
 }
 
+// ===================================================================
+// PostgreSQL integrations: pg, postgres.js, and TypeORM
+// ===================================================================
+export type PostgreSqlPatchConfig = ReproMiddlewareConfig & {
+    resolveContext?: () => { sid?: string; aid?: string } | undefined;
+};
+
+type PostgreSqlSource = {
+    library: 'pg' | 'postgres' | 'typeorm';
+    driver: 'pg' | 'postgres';
+};
+
+type PostgreSqlCaptureContext = {
+    cfg: PostgreSqlPatchConfig;
+    sid: string;
+    aid: string | null;
+    spanContext: SpanContext | null;
+    source: PostgreSqlSource;
+};
+
+const postgresSqlPatchConfigs: PostgreSqlPatchConfig[] = [];
+const postgresSqlSourceAls = new AsyncLocalStorage<PostgreSqlSource>();
+const pgPoolQueryAls = new AsyncLocalStorage<boolean>();
+let pgRequireHookInstalled = false;
+let postgresJsRequireHookInstalled = false;
+let typeOrmRequireHookInstalled = false;
+
+const PG_CLIENT_PATCHED = Symbol.for('@reproapp/node-sdk/pg-client-patched');
+const PG_POOL_PATCHED = Symbol.for('@reproapp/node-sdk/pg-pool-patched');
+const POSTGRES_JS_QUERY_PATCHED = Symbol.for('@reproapp/node-sdk/postgres-js-query-patched');
+const TYPEORM_DATASOURCE_PATCHED = Symbol.for('@reproapp/node-sdk/typeorm-datasource-patched');
+const TYPEORM_QUERY_RUNNER_PATCHED = Symbol.for('@reproapp/node-sdk/typeorm-query-runner-patched');
+
+function registerPostgreSqlPatchConfig(cfg: PostgreSqlPatchConfig): void {
+    if (!postgresSqlPatchConfigs.includes(cfg)) {
+        postgresSqlPatchConfigs.push(cfg);
+    }
+}
+
+function resolvePostgreSqlCaptureContext(defaultSource: PostgreSqlSource, source?: any): PostgreSqlCaptureContext | null {
+    const ctx = getCtx();
+    const contextualSource = postgresSqlSourceAls.getStore();
+    for (let i = postgresSqlPatchConfigs.length - 1; i >= 0; i -= 1) {
+        const cfg = postgresSqlPatchConfigs[i];
+        if (!cfg) continue;
+        const fallback = cfg.resolveContext?.() ?? {};
+        const sid = ctx.sid ?? fallback.sid ?? null;
+        if (!sid) continue;
+        return {
+            cfg,
+            sid,
+            aid: ctx.aid ?? fallback.aid ?? null,
+            spanContext: captureSpanContextFromTracer(source),
+            source: contextualSource ?? defaultSource,
+        };
+    }
+    return null;
+}
+
+function stripSqlComments(sql: string): string {
+    let remaining = sql.trimStart();
+    while (remaining.length) {
+        if (remaining.startsWith('--')) {
+            const newline = remaining.indexOf('\n');
+            remaining = newline < 0 ? '' : remaining.slice(newline + 1).trimStart();
+            continue;
+        }
+        if (remaining.startsWith('/*')) {
+            const end = remaining.indexOf('*/', 2);
+            remaining = end < 0 ? '' : remaining.slice(end + 2).trimStart();
+            continue;
+        }
+        break;
+    }
+    return remaining;
+}
+
+function normalizeSqlOperation(sql: string): string {
+    const normalized = stripSqlComments(sql);
+    const first = normalized.match(/^([a-z]+)/i)?.[1]?.toLowerCase() ?? 'query';
+    if (first !== 'with') return first;
+
+    // CTEs can wrap any DML statement. The last top-level DML keyword is the
+    // operation users care about, while nested SELECTs only build the CTE.
+    const matches = Array.from(normalized.matchAll(/\b(select|insert|update|delete|merge)\b/gi));
+    return matches.length ? String(matches[matches.length - 1][1]).toLowerCase() : 'query';
+}
+
+function cleanSqlIdentifier(value: string | undefined): string | undefined {
+    if (!value) return undefined;
+    const cleaned = value
+        .trim()
+        .replace(/[;,]$/, '')
+        .split('.')
+        .map((part) => part.replace(/^['"`]|['"`]$/g, ''))
+        .join('.');
+    return cleaned || undefined;
+}
+
+function resolveSqlTable(sql: string, op: string): string {
+    const normalized = stripSqlComments(sql);
+    let match: RegExpMatchArray | null = null;
+    if (op === 'insert') match = normalized.match(/\binsert\s+into\s+([^\s(]+)/i);
+    else if (op === 'update') match = normalized.match(/\bupdate\s+([^\s(]+)/i);
+    else if (op === 'delete') match = normalized.match(/\bdelete\s+from\s+([^\s(]+)/i);
+    else if (op === 'merge') match = normalized.match(/\bmerge\s+into\s+([^\s(]+)/i);
+    else match = normalized.match(/\bfrom\s+([^\s(]+)/i);
+    return cleanSqlIdentifier(match?.[1]) ?? 'unknown';
+}
+
+function buildPostgresQueryPayload(
+    sql: string,
+    parameters: any[],
+    source: PostgreSqlSource,
+    extra?: Record<string, any>,
+): Record<string, any> {
+    return {
+        sql,
+        parameters,
+        library: source.library,
+        driver: source.driver,
+        ...(extra ?? {}),
+    };
+}
+
+function summarizePostgresError(error: any): Record<string, any> {
+    return {
+        name: error?.name ?? 'Error',
+        message: error?.message ?? String(error),
+        code: error?.code,
+        severity: error?.severity,
+        detail: error?.detail,
+        hint: error?.hint,
+        position: error?.position,
+        internalPosition: error?.internalPosition,
+        internalQuery: error?.internalQuery,
+        where: error?.where,
+        schema: error?.schema,
+        table: error?.table,
+        column: error?.column,
+        dataType: error?.dataType,
+        constraint: error?.constraint,
+        file: error?.file,
+        line: error?.line,
+        routine: error?.routine,
+    };
+}
+
+function normalizePgQueryInput(config: any, values: any): { sql: string; parameters: any[]; extra?: Record<string, any> } {
+    if (typeof config === 'string') {
+        return { sql: config, parameters: Array.isArray(values) ? values : [] };
+    }
+    const sql = typeof config?.text === 'string' ? config.text : '';
+    const parameters = Array.isArray(config?.values)
+        ? config.values
+        : Array.isArray(values)
+            ? values
+            : [];
+    return {
+        sql,
+        parameters,
+        extra: {
+            name: typeof config?.name === 'string' ? config.name : undefined,
+            rowMode: config?.rowMode,
+            binary: config?.binary,
+        },
+    };
+}
+
+function normalizePgResult(result: any): any {
+    if (Array.isArray(result)) return result.map(normalizePgResult);
+    if (!result || typeof result !== 'object') return result;
+    return {
+        command: result.command,
+        rowCount: result.rowCount,
+        oid: result.oid,
+        fields: Array.isArray(result.fields)
+            ? result.fields.map((field: any) => ({
+                name: field?.name,
+                tableID: field?.tableID,
+                columnID: field?.columnID,
+                dataTypeID: field?.dataTypeID,
+                dataTypeSize: field?.dataTypeSize,
+                dataTypeModifier: field?.dataTypeModifier,
+                format: field?.format,
+            }))
+            : undefined,
+        rows: result.rows,
+    };
+}
+
+function emitPostgreSqlResult(
+    capture: PostgreSqlCaptureContext,
+    sql: string,
+    parameters: any[],
+    startedAt: number,
+    result: any,
+    error?: any,
+    extra?: Record<string, any>,
+): void {
+    const op = normalizeSqlOperation(sql);
+    emitDbQuery(capture.cfg, capture.sid, capture.aid ?? undefined, {
+        type: 'postgresql',
+        collection: resolveSqlTable(sql, op),
+        op,
+        queryRaw: buildPostgresQueryPayload(sql, parameters, capture.source, extra),
+        resultMetaRaw: error ? undefined : result,
+        error: error ? summarizePostgresError(error) : undefined,
+        durMs: Date.now() - startedAt,
+        t: alignedNow(),
+        spanContext: capture.spanContext,
+    });
+}
+
+function findPgCallbackIndex(args: any[]): number {
+    for (let i = args.length - 1; i >= 1; i -= 1) {
+        if (typeof args[i] === 'function') return i;
+    }
+    return -1;
+}
+
+function patchPgClientPrototype(proto: any): void {
+    if (!proto || proto[PG_CLIENT_PATCHED]) return;
+    const original = proto.query;
+    if (typeof original !== 'function') return;
+    try {
+        Object.defineProperty(proto, PG_CLIENT_PATCHED, { value: true, configurable: true });
+    } catch {
+        return;
+    }
+
+    proto.query = function reproPatchedPgQuery(this: any, ...args: any[]) {
+        if (pgPoolQueryAls.getStore()) return original.apply(this, args);
+        const capture = resolvePostgreSqlCaptureContext({ library: 'pg', driver: 'pg' }, this);
+        if (!capture) return original.apply(this, args);
+
+        const input = normalizePgQueryInput(args[0], args[1]);
+        const startedAt = Date.now();
+        const callbackIndex = findPgCallbackIndex(args);
+        const actualArgs = callbackIndex >= 0 ? [...args] : args;
+        let emitted = false;
+        const emitSuccess = (result: any) => {
+            if (emitted) return;
+            emitted = true;
+            emitPostgreSqlResult(
+                capture,
+                input.sql,
+                input.parameters,
+                startedAt,
+                normalizePgResult(result),
+                undefined,
+                input.extra,
+            );
+        };
+        const emitFailure = (error: any) => {
+            if (emitted) return;
+            emitted = true;
+            emitPostgreSqlResult(capture, input.sql, input.parameters, startedAt, undefined, error, input.extra);
+        };
+
+        if (callbackIndex >= 0) {
+            const callback = args[callbackIndex];
+            actualArgs[callbackIndex] = function reproPgQueryCallback(this: any, error: any, result: any, ...rest: any[]) {
+                if (error) emitFailure(error);
+                else emitSuccess(result);
+                return callback.call(this, error, result, ...rest);
+            };
+        }
+
+        try {
+            const returned = original.apply(this, actualArgs);
+            if (returned && typeof returned.then === 'function') {
+                return returned.then(
+                    (result: any) => {
+                        emitSuccess(result);
+                        return result;
+                    },
+                    (error: any) => {
+                        emitFailure(error);
+                        throw error;
+                    },
+                );
+            }
+            if (returned && callbackIndex < 0 && typeof returned.once === 'function') {
+                returned.once('end', emitSuccess);
+                returned.once('error', emitFailure);
+            }
+            return returned;
+        } catch (error) {
+            emitFailure(error);
+            throw error;
+        }
+    };
+}
+
+function patchPgPoolPrototype(proto: any): void {
+    if (!proto || proto[PG_POOL_PATCHED]) return;
+    const original = proto.query;
+    if (typeof original !== 'function') return;
+    try {
+        Object.defineProperty(proto, PG_POOL_PATCHED, { value: true, configurable: true });
+    } catch {
+        return;
+    }
+
+    proto.query = function reproPatchedPgPoolQuery(this: any, ...args: any[]) {
+        const capture = resolvePostgreSqlCaptureContext({ library: 'pg', driver: 'pg' }, this);
+        if (!capture) return original.apply(this, args);
+
+        const input = normalizePgQueryInput(args[0], args[1]);
+        const startedAt = Date.now();
+        const callbackIndex = findPgCallbackIndex(args);
+        const actualArgs = callbackIndex >= 0 ? [...args] : args;
+        let emitted = false;
+        const emitSuccess = (result: any) => {
+            if (emitted) return;
+            emitted = true;
+            emitPostgreSqlResult(
+                capture,
+                input.sql,
+                input.parameters,
+                startedAt,
+                normalizePgResult(result),
+                undefined,
+                input.extra,
+            );
+        };
+        const emitFailure = (error: any) => {
+            if (emitted) return;
+            emitted = true;
+            emitPostgreSqlResult(capture, input.sql, input.parameters, startedAt, undefined, error, input.extra);
+        };
+
+        if (callbackIndex >= 0) {
+            const callback = args[callbackIndex];
+            actualArgs[callbackIndex] = function reproPgPoolQueryCallback(this: any, error: any, result: any, ...rest: any[]) {
+                if (error) emitFailure(error);
+                else emitSuccess(result);
+                return callback.call(this, error, result, ...rest);
+            };
+        }
+
+        try {
+            const returned = pgPoolQueryAls.run(true, () => original.apply(this, actualArgs));
+            if (returned && typeof returned.then === 'function') {
+                return returned.then(
+                    (result: any) => {
+                        emitSuccess(result);
+                        return result;
+                    },
+                    (error: any) => {
+                        emitFailure(error);
+                        throw error;
+                    },
+                );
+            }
+            return returned;
+        } catch (error) {
+            emitFailure(error);
+            throw error;
+        }
+    };
+}
+
+function patchPgFromModuleExports(pgModule: any): void {
+    if (!pgModule) return;
+    const candidates = [pgModule, pgModule.default];
+    for (const candidate of candidates) {
+        patchPgClientPrototype(candidate?.Client?.prototype);
+        patchPgClientPrototype(candidate?.native?.Client?.prototype);
+        patchPgPoolPrototype(candidate?.Pool?.prototype);
+        patchPgPoolPrototype(candidate?.native?.Pool?.prototype);
+    }
+}
+
+function installPgRequireHook(): void {
+    if (pgRequireHookInstalled) return;
+    pgRequireHookInstalled = true;
+    try {
+        const rim = requireOptionalHostModule('require-in-the-middle');
+        const Hook = rim?.Hook ?? rim;
+        if (typeof Hook !== 'function') return;
+        // eslint-disable-next-line no-new
+        new Hook(['pg'], (exports: any) => {
+            patchPgFromModuleExports(exports);
+            return exports;
+        });
+    } catch {}
+}
+
+function normalizePostgresJsInput(query: any): { sql: string; parameters: any[]; extra: Record<string, any> } {
+    if (typeof query?.statement?.string === 'string') {
+        return {
+            sql: query.statement.string,
+            parameters: Array.isArray(query?.parameters) ? query.parameters : [],
+            extra: {
+                tagged: query?.tagged === true,
+                parameterTypes: Array.isArray(query?.statement?.types) ? query.statement.types : undefined,
+            },
+        };
+    }
+    const strings = Array.isArray(query?.strings) ? query.strings : [];
+    const parameters = Array.isArray(query?.args) ? query.args : [];
+    if (query?.tagged) {
+        return {
+            sql: strings.map((part: any, index: number) => `${String(part)}${index < parameters.length ? `$${index + 1}` : ''}`).join(''),
+            parameters,
+            extra: { tagged: true },
+        };
+    }
+    return {
+        sql: typeof strings[0] === 'string' ? strings[0] : '',
+        parameters,
+        extra: { tagged: false },
+    };
+}
+
+function normalizePostgresJsResult(result: any): any {
+    if (!Array.isArray(result)) return result;
+    const metadata = result as any;
+    return {
+        command: metadata.command,
+        count: metadata.count,
+        columns: Array.isArray(metadata.columns)
+            ? metadata.columns.map((column: any) => ({
+                name: column?.name,
+                type: column?.type,
+                table: column?.table,
+                number: column?.number,
+            }))
+            : undefined,
+        rows: Array.from(result),
+    };
+}
+
+function patchPostgresJsQueryPrototype(proto: any): void {
+    if (!proto || proto[POSTGRES_JS_QUERY_PATCHED]) return;
+    const originalHandle = proto.handle;
+    if (typeof originalHandle !== 'function') return;
+    try {
+        Object.defineProperty(proto, POSTGRES_JS_QUERY_PATCHED, { value: true, configurable: true });
+    } catch {
+        return;
+    }
+
+    proto.handle = function reproPatchedPostgresJsHandle(this: any, ...args: any[]) {
+        if (!this.__repro_postgres_capture_attached) {
+            const capture = resolvePostgreSqlCaptureContext({ library: 'postgres', driver: 'postgres' }, this);
+            if (capture) {
+                try {
+                    Object.defineProperty(this, '__repro_postgres_capture_attached', { value: true, configurable: true });
+                } catch {
+                    this.__repro_postgres_capture_attached = true;
+                }
+                const input = normalizePostgresJsInput(this);
+                const startedAt = Date.now();
+                Promise.prototype.then.call(
+                    this,
+                    (result: any) => {
+                        const executedInput = normalizePostgresJsInput(this);
+                        emitPostgreSqlResult(
+                            capture,
+                            executedInput.sql || input.sql,
+                            executedInput.parameters,
+                            startedAt,
+                            normalizePostgresJsResult(result),
+                            undefined,
+                            executedInput.extra,
+                        );
+                        return result;
+                    },
+                    (error: any) => {
+                        const executedInput = normalizePostgresJsInput(this);
+                        emitPostgreSqlResult(
+                            capture,
+                            executedInput.sql || input.sql,
+                            executedInput.parameters.length ? executedInput.parameters : input.parameters,
+                            startedAt,
+                            undefined,
+                            error,
+                            executedInput.extra,
+                        );
+                    },
+                );
+            }
+        }
+        return originalHandle.apply(this, args);
+    };
+}
+
+function patchPostgresJsFromModuleExports(postgresModule: any): void {
+    const factories = new Set<any>();
+    const addFactory = (candidate: any) => {
+        if (typeof candidate !== 'function') return;
+        // getLoadedModuleExportsByPackage also returns internal postgres.js
+        // helpers. Only the public factory carries these static exports.
+        if (!candidate.PostgresError && !candidate.BigInt && !candidate.__repro_postgres_factory) return;
+        factories.add(candidate);
+    };
+    addFactory(postgresModule);
+    addFactory(postgresModule?.default);
+
+    for (const factory of factories) {
+        let sql: any;
+        try {
+            sql = factory({ max: 1, idle_timeout: 1, connect_timeout: 1 });
+            const query = sql.unsafe('select 1');
+            patchPostgresJsQueryPrototype(Object.getPrototypeOf(query));
+        } catch {}
+        try {
+            const ended = sql?.end?.({ timeout: 0 });
+            if (ended && typeof ended.catch === 'function') ended.catch(() => undefined);
+        } catch {}
+    }
+}
+
+function installPostgresJsRequireHook(): void {
+    if (postgresJsRequireHookInstalled) return;
+    postgresJsRequireHookInstalled = true;
+    try {
+        const rim = requireOptionalHostModule('require-in-the-middle');
+        const Hook = rim?.Hook ?? rim;
+        if (typeof Hook !== 'function') return;
+        // eslint-disable-next-line no-new
+        new Hook(['postgres'], (exports: any) => {
+            patchPostgresJsFromModuleExports(exports);
+            return exports;
+        });
+    } catch {}
+}
+
+function patchTypeOrmQueryRunner(queryRunner: any): any {
+    if (!queryRunner || queryRunner[TYPEORM_QUERY_RUNNER_PATCHED]) return queryRunner;
+    const original = queryRunner.query;
+    if (typeof original !== 'function') return queryRunner;
+    try {
+        Object.defineProperty(queryRunner, TYPEORM_QUERY_RUNNER_PATCHED, { value: true, configurable: true });
+    } catch {
+        return queryRunner;
+    }
+    queryRunner.query = function reproPatchedTypeOrmQuery(this: any, ...args: any[]) {
+        return postgresSqlSourceAls.run(
+            { library: 'typeorm', driver: 'pg' },
+            () => original.apply(this, args),
+        );
+    };
+    return queryRunner;
+}
+
+function patchTypeOrmDataSourcePrototype(proto: any): void {
+    if (!proto || proto[TYPEORM_DATASOURCE_PATCHED]) return;
+    const original = proto.createQueryRunner;
+    if (typeof original !== 'function') return;
+    try {
+        Object.defineProperty(proto, TYPEORM_DATASOURCE_PATCHED, { value: true, configurable: true });
+    } catch {
+        return;
+    }
+    proto.createQueryRunner = function reproPatchedCreateQueryRunner(this: any, ...args: any[]) {
+        return patchTypeOrmQueryRunner(original.apply(this, args));
+    };
+}
+
+function patchTypeOrmFromModuleExports(typeOrmModule: any): void {
+    if (!typeOrmModule) return;
+    patchTypeOrmDataSourcePrototype(typeOrmModule?.DataSource?.prototype);
+    patchTypeOrmDataSourcePrototype(typeOrmModule?.Connection?.prototype);
+    patchTypeOrmDataSourcePrototype(typeOrmModule?.default?.DataSource?.prototype);
+}
+
+function installTypeOrmRequireHook(): void {
+    if (typeOrmRequireHookInstalled) return;
+    typeOrmRequireHookInstalled = true;
+    try {
+        const rim = requireOptionalHostModule('require-in-the-middle');
+        const Hook = rim?.Hook ?? rim;
+        if (typeof Hook !== 'function') return;
+        // eslint-disable-next-line no-new
+        new Hook(['typeorm'], (exports: any) => {
+            patchTypeOrmFromModuleExports(exports);
+            return exports;
+        });
+    } catch {}
+}
+
+export function patchPostgreSql(cfg: PostgreSqlPatchConfig): void {
+    registerPostgreSqlPatchConfig(cfg);
+    installPgRequireHook();
+    installPostgresJsRequireHook();
+    installTypeOrmRequireHook();
+
+    const pgModules = new Set<any>();
+    const pg = requireOptionalHostModule('pg');
+    if (pg) pgModules.add(pg);
+    for (const loaded of getLoadedModuleExportsByPackage('pg')) pgModules.add(loaded);
+    for (const loaded of pgModules) patchPgFromModuleExports(loaded);
+
+    const postgresModules = new Set<any>();
+    const postgres = requireOptionalHostModule('postgres');
+    if (postgres) postgresModules.add(postgres);
+    for (const loaded of getLoadedModuleExportsByPackage('postgres')) postgresModules.add(loaded);
+    for (const loaded of postgresModules) patchPostgresJsFromModuleExports(loaded);
+
+    const typeOrmModules = new Set<any>();
+    const typeOrm = requireOptionalHostModule('typeorm');
+    if (typeOrm) typeOrmModules.add(typeOrm);
+    for (const loaded of getLoadedModuleExportsByPackage('typeorm')) typeOrmModules.add(loaded);
+    for (const loaded of typeOrmModules) patchTypeOrmFromModuleExports(loaded);
+}
+
 // ===================================================================
 // Native MongoDB driver integration
 // ===================================================================
@@ -10045,9 +11336,11 @@ export async function initRepro(cfg: ReproInitConfig): Promise<void> {
     const ingestCfg = toIngestConfig(cfg);
     reproAutoMiddlewareConfig = {
         ...ingestCfg,
+        apiBase: cfg.apiBase,
         captureHeaders: cfg.captureHeaders,
         masking: cfg.masking,
         privacy: cfg.privacy,
+        liveMode: cfg.liveMode,
     };
     const integrationCfg = {
         ...reproAutoMiddlewareConfig,
@@ -10066,6 +11359,7 @@ export async function initRepro(cfg: ReproInitConfig): Promise<void> {
     patchKafkaJs(integrationCfg);
     patchAmqplib(integrationCfg);
     patchRedis(integrationCfg);
+    patchPostgreSql(integrationCfg);
     patchMongoDb(integrationCfg);
     await installMongoDbImportHook();
     patchSendgridMail(integrationCfg);
@@ -10102,6 +11396,9 @@ export const __reproTestHooks = {
         lastClientActivityAt = 0;
         sdkBackgroundQuietUntil = 0;
     },
+    setBackendLiveTimingForTest(override: Partial<BackendLiveTimingConfig> | null): void {
+        backendLiveTimingOverrideForTest = override;
+    },
     runWithRequestContextForTest<T>(ctx: Partial<Ctx>, fn: () => T): T {
         return als.run({
             ...ctx,
@@ -10129,6 +11426,9 @@ export const __reproTestHooks = {
     patchAmqplibConnectionForTest: patchAmqplibConnection,
     patchAmqplibChannelForTest: patchAmqplibChannel,
     wrapAmqplibConsumeHandlerForTest: wrapAmqplibConsumeHandler,
+    patchPgModuleForTest: patchPgFromModuleExports,
+    patchPostgresJsModuleForTest: patchPostgresJsFromModuleExports,
+    patchTypeOrmModuleForTest: patchTypeOrmFromModuleExports,
     patchMongoDbModuleForTest: patchMongoDbFromModuleExports,
     patchMongoCollectionPrototypeForTest: patchMongoCollectionPrototype,
     chunkTraceEventsForTransportForTest: chunkTraceEventsForTransport,