@juspay/neurolink 9.54.6 → 9.54.7

package/dist/lib/observability/utils/spanSerializer.js

@@ -4,18 +4,34 @@
  */
 import { randomBytes } from "node:crypto";
 import { SpanStatus, SpanType, } from "../../types/index.js";
+import { getActiveTraceContext } from "../../telemetry/traceContext.js";
 /**
  * Utility class for span creation and serialization
  */
 export class SpanSerializer {
     /**
-     * Create a new span with generated IDs
+     * Create a new span with generated IDs.
+     *
+     * When `traceId` / `parentSpanId` are omitted, the method automatically
+     * attempts to inherit them from the active OTel context so that Pipeline B
+     * spans land inside the same Langfuse trace as Pipeline A spans (fix A5).
      */
     static createSpan(type, name, attributes = {}, parentSpanId, traceId) {
+        // A5 fix: When no explicit traceId is provided, try to inherit from the
+        // active OTel context so Pipeline B spans are linked to Pipeline A traces.
+        let resolvedTraceId = traceId;
+        let resolvedParentSpanId = parentSpanId;
+        if (!resolvedTraceId) {
+            const otelCtx = getActiveTraceContext();
+            resolvedTraceId = otelCtx.traceId ?? randomBytes(16).toString("hex");
+            if (!resolvedParentSpanId && otelCtx.parentSpanId) {
+                resolvedParentSpanId = otelCtx.parentSpanId;
+            }
+        }
         return {
             spanId: randomBytes(8).toString("hex"),
-            traceId: traceId ?? randomBytes(16).toString("hex"),
-            parentSpanId,
+            traceId: resolvedTraceId,
+            parentSpanId: resolvedParentSpanId,
             type,
             name,
             startTime: new Date().toISOString(),
@@ -109,7 +125,11 @@ export class SpanSerializer {
             // Langfuse tracing; use LangfuseExporterConfig.redactIO=true to suppress them
             // in compliance-sensitive deployments.
             metadata: filterSafeMetadata(span.attributes),
-            level: span.status === SpanStatus.ERROR ? "ERROR" : "DEFAULT",
+            level: span.status === SpanStatus.ERROR
+                ? "ERROR"
+                : span.status === SpanStatus.WARNING
+                    ? "WARNING"
+                    : "DEFAULT",
             statusMessage: span.statusMessage,
             input: span.attributes["input"],
             output: span.attributes["output"],

package/dist/lib/processors/base/BaseFileProcessor.js

@@ -47,6 +47,8 @@ import { promisify } from "util";
 import { gunzip } from "zlib";
 import { SIZE_LIMITS } from "../config/index.js";
 import { isAbortError } from "../../utils/errorHandling.js";
+import { withSpan } from "../../telemetry/withSpan.js";
+import { tracers } from "../../telemetry/tracers.js";
 import { createFileError, extractHttpStatus, FileErrorCode, isRetryableError, } from "../errors/index.js";
 import { DEFAULT_RETRY_CONFIG } from "../../types/index.js";
 const gunzipAsync = promisify(gunzip);
@@ -104,78 +106,89 @@ export class BaseFileProcessor {
      * ```
      */
     async processFile(fileInfo, options) {
-        try {
-            // Step 1: Validate file type and size
-            const validationResult = this.validateFileWithResult(fileInfo);
-            if (!validationResult.success) {
-                return {
-                    success: false,
-                    error: validationResult.error,
-                };
-            }
-            // Step 2: Get file buffer (from direct buffer or download from URL)
-            let buffer;
-            if (fileInfo.buffer) {
-                // Direct buffer provided - skip download
-                buffer = fileInfo.buffer;
-            }
-            else if (fileInfo.url) {
-                // Download from URL
-                const downloadResult = await this.downloadFileWithRetry(fileInfo, options);
-                if (!downloadResult.success) {
+        return withSpan({
+            name: "neurolink.file.process",
+            tracer: tracers.file,
+            attributes: {
+                "file.processor": this.constructor.name,
+                "file.type": this.config.fileTypeName,
+                "file.mimetype": fileInfo.mimetype ?? "unknown",
+                "file.name": fileInfo.name ?? "unknown",
+            },
+        }, async (_span) => {
+            try {
+                // Step 1: Validate file type and size
+                const validationResult = this.validateFileWithResult(fileInfo);
+                if (!validationResult.success) {
                     return {
                         success: false,
-                        error: downloadResult.error,
+                        error: validationResult.error,
                     };
                 }
-                if (!downloadResult.data) {
+                // Step 2: Get file buffer (from direct buffer or download from URL)
+                let buffer;
+                if (fileInfo.buffer) {
+                    // Direct buffer provided - skip download
+                    buffer = fileInfo.buffer;
+                }
+                else if (fileInfo.url) {
+                    // Download from URL
+                    const downloadResult = await this.downloadFileWithRetry(fileInfo, options);
+                    if (!downloadResult.success) {
+                        return {
+                            success: false,
+                            error: downloadResult.error,
+                        };
+                    }
+                    if (!downloadResult.data) {
+                        return {
+                            success: false,
+                            error: this.createError(FileErrorCode.DOWNLOAD_FAILED, {
+                                reason: "Download succeeded but returned no data",
+                            }),
+                        };
+                    }
+                    buffer = downloadResult.data;
+                    // Validate actual downloaded size against limit
+                    if (!this.validateFileSize(buffer.length)) {
+                        return {
+                            success: false,
+                            error: this.createError(FileErrorCode.FILE_TOO_LARGE, {
+                                sizeMB: (buffer.length / (1024 * 1024)).toFixed(2),
+                                maxMB: this.config.maxSizeMB,
+                                type: this.config.fileTypeName,
+                            }),
+                        };
+                    }
+                }
+                else {
+                    // No buffer or URL provided
                     return {
                         success: false,
                         error: this.createError(FileErrorCode.DOWNLOAD_FAILED, {
-                            reason: "Download succeeded but returned no data",
+                            reason: "No buffer or URL provided for file",
                         }),
                     };
                 }
-                buffer = downloadResult.data;
-                // Validate actual downloaded size against limit
-                if (!this.validateFileSize(buffer.length)) {
+                // Step 3: Post-download validation (subclasses can override)
+                const postValidationResult = await this.validateDownloadedFileWithResult(buffer, fileInfo);
+                if (!postValidationResult.success) {
                     return {
                         success: false,
-                        error: this.createError(FileErrorCode.FILE_TOO_LARGE, {
-                            sizeMB: (buffer.length / (1024 * 1024)).toFixed(2),
-                            maxMB: this.config.maxSizeMB,
-                            type: this.config.fileTypeName,
-                        }),
+                        error: postValidationResult.error,
                     };
                 }
+                // Step 4: Build processed result using template method
+                return await this.buildProcessedResultWithResult(buffer, fileInfo);
             }
-            else {
-                // No buffer or URL provided
-                return {
-                    success: false,
-                    error: this.createError(FileErrorCode.DOWNLOAD_FAILED, {
-                        reason: "No buffer or URL provided for file",
-                    }),
-                };
-            }
-            // Step 3: Post-download validation (subclasses can override)
-            const postValidationResult = await this.validateDownloadedFileWithResult(buffer, fileInfo);
-            if (!postValidationResult.success) {
+            catch (error) {
+                // Catch any unexpected errors
                 return {
                     success: false,
-                    error: postValidationResult.error,
+                    error: this.createError(FileErrorCode.UNKNOWN_ERROR, { error: error instanceof Error ? error.message : String(error) }, error instanceof Error ? error : undefined),
                 };
             }
-            // Step 4: Build processed result using template method
-            return await this.buildProcessedResultWithResult(buffer, fileInfo);
-        }
-        catch (error) {
-            // Catch any unexpected errors
-            return {
-                success: false,
-                error: this.createError(FileErrorCode.UNKNOWN_ERROR, { error: error instanceof Error ? error.message : String(error) }, error instanceof Error ? error : undefined),
-            };
-        }
+        }); // end withSpan
     }
     /**
      * Process multiple files with detailed summary.

package/dist/lib/processors/document/ExcelProcessor.d.ts

@@ -36,7 +36,7 @@
  * ```
  */
 import { BaseFileProcessor } from "../base/BaseFileProcessor.js";
-import type { FileInfo, ProcessorFileProcessingResult, ProcessOptions, ProcessedExcel } from "../../types/index.js";
+import type { FileInfo, ProcessOptions, ProcessedExcel, ProcessorFileProcessingResult } from "../../types/index.js";
 /**
  * Excel Processor - handles .xlsx and .xls files.
  * Uses exceljs library for parsing with support for large files.

package/dist/lib/processors/errors/errorHelpers.d.ts

@@ -7,37 +7,8 @@
  *
  * @module processors/errors
  */
-import type { FileProcessingError } from "../../types/index.js";
+import type { FileProcessingError, FileProcessingSummary } from "../../types/index.js";
 import { FileErrorCode } from "./FileErrorCode.js";
-/**
- * Summary of file processing operations.
- */
-type FileProcessingSummary = {
-    /** Total number of files attempted */
-    totalFiles: number;
-    /** Successfully processed files */
-    processedFiles: Array<{
-        filename: string;
-        size?: number;
-        type?: string;
-    }>;
-    /** Files that failed to process */
-    failedFiles: Array<{
-        filename: string;
-        error: FileProcessingError;
-    }>;
-    /** Files that were skipped */
-    skippedFiles: Array<{
-        filename: string;
-        reason: string;
-        suggestedAlternative?: string;
-    }>;
-    /** Non-fatal warnings */
-    warnings: Array<{
-        filename: string;
-        message: string;
-    }>;
-};
 /**
  * Create a structured file processing error with user-friendly messaging.
  *
@@ -148,4 +119,3 @@ export declare function combineSummaries(summaries: FileProcessingSummary[]): Fi
  * @returns Delay in milliseconds before next retry
  */
 export declare function getRetryDelay(error: unknown, attempt: number, baseDelayMs?: number): number;
-export {};

package/dist/lib/processors/errors/errorSerializer.d.ts

@@ -11,50 +11,7 @@
  *
  * @module processors/errors
  */
-/**
- * Serialized error representation with full context.
- */
-type SerializedError = {
-    /** Unique error instance ID */
-    errorId: string;
-    /** Deterministic fingerprint for error aggregation */
-    errorFingerprint: string;
-    /** Error type/class name */
-    errorType: string;
-    /** Error message */
-    message: string;
-    /** Full stack trace */
-    stack?: string;
-    /** Parsed stack frames */
-    stackFrames?: string[];
-    /** HTTP status code if applicable */
-    statusCode?: number;
-    /** Whether the error is operational (expected) vs programmer error */
-    isOperational?: boolean;
-    /** Whether the error is retryable */
-    isRetryable?: boolean;
-    /** Error code */
-    code?: string;
-    /** Additional metadata */
-    metadata?: Record<string, unknown>;
-    /** Serialized cause error (for error chaining) */
-    cause?: SerializedError;
-    /** ISO timestamp of when the error was serialized */
-    timestamp: string;
-};
-/**
- * Options for error serialization.
- */
-type SerializeOptions = {
-    /** Include stack trace in output (default: true) */
-    includeStack?: boolean;
-    /** Max depth for nested object serialization (default: 5) */
-    maxDepth?: number;
-    /** Filter stack traces to application frames only (default: true in production) */
-    filterStacks?: boolean;
-    /** Additional context to include */
-    context?: Record<string, unknown>;
-};
+import type { SerializeOptions, SerializedError } from "../../types/index.js";
 /**
  * Safely serialize an error with full context preservation.
  * Handles circular references, redacts sensitive data, and preserves error metadata.
@@ -137,4 +94,3 @@ export declare function summarizeError(error: unknown): {
     code?: string;
     fingerprint: string;
 };
-export {};

package/dist/lib/processors/registry/ProcessorRegistry.js

@@ -43,6 +43,8 @@
  * const result = await registry.processFile(fileInfo);
  * ```
  */
+import { withSpan } from "../../telemetry/withSpan.js";
+import { tracers } from "../../telemetry/tracers.js";
 // =============================================================================
 // UTILITY FUNCTIONS
 // =============================================================================
@@ -399,12 +401,21 @@ export class ProcessorRegistry {
      * ```
      */
     async processFile(fileInfo, options) {
-        const match = this.findProcessor(fileInfo.mimetype, fileInfo.name);
-        if (!match) {
-            return null;
-        }
-        const processor = match.processor;
-        return processor.processFile(fileInfo, options);
+        return withSpan({
+            name: "neurolink.processor.processFile",
+            tracer: tracers.processor,
+            attributes: {
+                "processor.filename": fileInfo.name ?? "unknown",
+                "processor.mimetype": fileInfo.mimetype ?? "unknown",
+            },
+        }, async () => {
+            const match = this.findProcessor(fileInfo.mimetype, fileInfo.name);
+            if (!match) {
+                return null;
+            }
+            const processor = match.processor;
+            return processor.processFile(fileInfo, options);
+        });
     }
     /**
      * Process a file with detailed result including error information.