@juspay/neurolink 9.30.0 → 9.31.0

package/dist/client/processors/errors/errorSerializer.js

@@ -0,0 +1,507 @@
+/**
+ * Error Serializer Utility
+ *
+ * Safe error serialization with full context preservation.
+ * Features:
+ * - Handles circular references
+ * - Filters sensitive data (PII, credentials)
+ * - Generates error fingerprints for deduplication
+ * - Preserves custom error properties
+ * - Filters stack traces in production
+ *
+ * @module processors/errors
+ */
+import { createHash } from "crypto";
+/**
+ * Fields that should be redacted for security/privacy.
+ */
+const SENSITIVE_FIELDS = [
+    "password",
+    "token",
+    "secret",
+    "apiKey",
+    "api_key",
+    "authorization",
+    "cookie",
+    "session",
+    "credentials",
+    "privateKey",
+    "private_key",
+    "accessToken",
+    "access_token",
+    "refreshToken",
+    "refresh_token",
+    "apiSecret",
+    "api_secret",
+    "clientSecret",
+    "client_secret",
+    "bearer",
+    "auth",
+    "ssn",
+    "socialSecurity",
+    "creditCard",
+    "credit_card",
+    "cvv",
+    "pin",
+    "jwt",
+    "x-api-key",
+    "passphrase",
+    "connectionString",
+    "connection_string",
+];
+/**
+ * Maximum size limits for serialization.
+ */
+const MAX_METADATA_SIZE = 2000;
+const MAX_STACK_FRAMES = 20;
+const MAX_DEPTH = 5;
+/**
+ * Safely serialize an error with full context preservation.
+ * Handles circular references, redacts sensitive data, and preserves error metadata.
+ *
+ * @param error - Error instance or unknown value to serialize
+ * @param options - Serialization options
+ * @returns Serialized error with full context
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await riskyOperation();
+ * } catch (error) {
+ *   const serialized = serializeError(error);
+ *   logger.error("Operation failed", serialized);
+ * }
+ * ```
+ */
+export function serializeError(error, options) {
+    const { includeStack = true, maxDepth = MAX_DEPTH, filterStacks = process.env.NODE_ENV === "production", } = options || {};
+    const timestamp = new Date().toISOString();
+    // Handle non-Error objects
+    if (!(error instanceof Error)) {
+        return {
+            errorId: generateErrorId(),
+            errorFingerprint: generateFingerprintFromString(String(error)),
+            errorType: "UnknownError",
+            message: String(error),
+            metadata: { originalValue: safeStringify(error, maxDepth) },
+            timestamp,
+        };
+    }
+    // Extract basic error info
+    const serialized = {
+        errorId: generateErrorId(),
+        errorType: error.name,
+        message: error.message,
+        errorFingerprint: generateErrorFingerprint(error),
+        timestamp,
+    };
+    // Add stack trace
+    if (includeStack && error.stack) {
+        const frames = error.stack.split("\n");
+        if (filterStacks) {
+            serialized.stackFrames = filterStackFrames(frames, MAX_STACK_FRAMES);
+            serialized.stack = serialized.stackFrames.join("\n");
+        }
+        else {
+            serialized.stack = error.stack;
+            serialized.stackFrames = frames.slice(0, MAX_STACK_FRAMES);
+        }
+    }
+    // Add custom properties from error objects
+    if ("statusCode" in error) {
+        serialized.statusCode = error.statusCode;
+    }
+    if ("isOperational" in error) {
+        serialized.isOperational = error.isOperational;
+    }
+    if ("isRetryable" in error) {
+        serialized.isRetryable = error.isRetryable;
+    }
+    if ("retryable" in error) {
+        serialized.isRetryable = error.retryable;
+    }
+    if ("retriable" in error) {
+        serialized.isRetryable = error.retriable;
+    }
+    if ("code" in error) {
+        serialized.code = String(error.code);
+    }
+    // Extract additional metadata
+    const metadata = {};
+    const errorKeys = Object.keys(error);
+    const excludedKeys = [
+        "name",
+        "message",
+        "stack",
+        "statusCode",
+        "isOperational",
+        "isRetryable",
+        "retryable",
+        "retriable",
+        "code",
+        "cause",
+    ];
+    for (const key of errorKeys) {
+        if (!excludedKeys.includes(key)) {
+            const value = error[key];
+            metadata[key] = sanitizeAndTruncate(key, value, MAX_METADATA_SIZE, maxDepth);
+        }
+    }
+    // Add context if provided
+    if (options?.context) {
+        for (const [key, value] of Object.entries(options.context)) {
+            metadata[`context.${key}`] = sanitizeAndTruncate(key, value, MAX_METADATA_SIZE, maxDepth);
+        }
+    }
+    if (Object.keys(metadata).length > 0) {
+        serialized.metadata = metadata;
+    }
+    // Handle error chaining (cause) - use type assertion for ES2022 cause property
+    const errorWithCause = error;
+    if (errorWithCause.cause instanceof Error) {
+        serialized.cause = serializeError(errorWithCause.cause, {
+            ...options,
+            maxDepth: Math.max(1, maxDepth - 1),
+        });
+    }
+    return serialized;
+}
+/**
+ * Generate a unique error instance ID.
+ *
+ * @returns Unique error ID in format "err_<timestamp>_<random>"
+ */
+function generateErrorId() {
+    const timestamp = Date.now().toString(36);
+    const random = Math.random().toString(36).substring(2, 11);
+    return `err_${timestamp}_${random}`;
+}
+/**
+ * Generate a deterministic fingerprint for error aggregation.
+ * Normalizes dynamic values (IDs, timestamps, paths) to group similar errors together.
+ *
+ * @param error - Error to fingerprint
+ * @param context - Optional context with operation name
+ * @returns 16-character hex fingerprint hash
+ *
+ * @example
+ * ```typescript
+ * const fp1 = generateErrorFingerprint(new Error("User 123 not found"));
+ * const fp2 = generateErrorFingerprint(new Error("User 456 not found"));
+ * // fp1 === fp2 (same error pattern, different IDs)
+ * ```
+ */
+export function generateErrorFingerprint(error, context) {
+    // Normalize message by replacing dynamic values
+    const normalizedMessage = normalizeErrorMessage(error.message);
+    // Get first relevant stack frame (most relevant location)
+    const firstFrame = extractFirstRelevantFrame(error.stack);
+    const components = [
+        error.name,
+        normalizedMessage,
+        firstFrame,
+        context?.operation || "",
+    ];
+    return createHash("sha256")
+        .update(components.join("|"))
+        .digest("hex")
+        .substring(0, 16);
+}
+/**
+ * Generate a fingerprint from a plain string (for non-Error values).
+ *
+ * @param value - String value to fingerprint
+ * @returns 16-character hex fingerprint hash
+ */
+function generateFingerprintFromString(value) {
+    const normalized = normalizeErrorMessage(value);
+    return createHash("sha256").update(normalized).digest("hex").substring(0, 16);
+}
+/**
+ * Normalize an error message by replacing dynamic values with placeholders.
+ * This allows grouping similar errors together regardless of specific IDs, paths, etc.
+ *
+ * @param message - Original error message
+ * @returns Normalized message with placeholders
+ */
+function normalizeErrorMessage(message) {
+    return (message
+        // Numbers (IDs, counts, etc.)
+        .replace(/\d+/g, "N")
+        // UUIDs (v4)
+        .replace(/[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}/gi, "UUID")
+        // MongoDB ObjectIDs (24 hex chars)
+        .replace(/[a-f0-9]{24}/gi, "OBJID")
+        // File paths
+        .replace(/\/[\w/.~-]+/g, "PATH")
+        // Windows paths
+        .replace(/[A-Z]:\\[\w\\.~-]+/gi, "PATH")
+        // URLs
+        .replace(/https?:\/\/[^\s]+/g, "URL")
+        // Single-quoted strings
+        .replace(/'[^']*'/g, "STR")
+        // Double-quoted strings
+        .replace(/"[^"]*"/g, "STR")
+        // Timestamps (ISO format)
+        .replace(/\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/g, "TIMESTAMP")
+        // Email addresses
+        .replace(/[\w.-]+@[\w.-]+\.\w+/g, "EMAIL")
+        // IP addresses
+        .replace(/\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}/g, "IP"));
+}
+/**
+ * Extract the first relevant stack frame (application code, not node_modules).
+ *
+ * @param stack - Full stack trace
+ * @returns First relevant frame or empty string
+ */
+function extractFirstRelevantFrame(stack) {
+    if (!stack) {
+        return "";
+    }
+    const frames = stack.split("\n");
+    for (const frame of frames) {
+        const trimmed = frame.trim();
+        if (trimmed.startsWith("at ") &&
+            !trimmed.includes("node_modules") &&
+            !trimmed.includes("node:internal")) {
+            return trimmed;
+        }
+    }
+    // Fall back to first "at" frame
+    const firstAtFrame = frames.find((f) => f.trim().startsWith("at "));
+    return firstAtFrame?.trim() || "";
+}
+/**
+ * Filter stack frames to application code only.
+ * Removes node_modules and internal Node.js frames.
+ *
+ * @param frames - Array of stack frame strings
+ * @param maxFrames - Maximum number of frames to include
+ * @returns Filtered stack frames
+ */
+function filterStackFrames(frames, maxFrames) {
+    const filtered = frames.filter((frame) => {
+        // Keep error message line (first line)
+        if (!frame.trim().startsWith("at ")) {
+            return true;
+        }
+        // Filter out node internals and dependencies
+        return (!frame.includes("node_modules") &&
+            !frame.includes("node:internal") &&
+            !frame.includes("node:async_hooks") &&
+            !frame.includes("node:events"));
+    });
+    return filtered.slice(0, maxFrames);
+}
+/**
+ * Safely stringify an object with circular reference handling.
+ *
+ * @param obj - Object to stringify
+ * @param maxDepth - Maximum depth for nested objects
+ * @returns JSON string representation
+ */
+export function safeStringify(obj, maxDepth = MAX_DEPTH) {
+    const seen = new WeakSet();
+    const replacer = (key, value, depth = 0) => {
+        // Depth limit
+        if (depth > maxDepth) {
+            return "[max depth reached]";
+        }
+        // Check for sensitive fields
+        if (key && isSensitiveField(key)) {
+            return "[REDACTED]";
+        }
+        // Handle null/undefined
+        if (value === null) {
+            return null;
+        }
+        if (value === undefined) {
+            return "[undefined]";
+        }
+        // Handle circular references
+        if (typeof value === "object" && value !== null) {
+            if (seen.has(value)) {
+                return "[Circular]";
+            }
+            seen.add(value);
+        }
+        // Handle special types
+        if (typeof value === "bigint") {
+            return value.toString() + "n";
+        }
+        if (value instanceof Error) {
+            return {
+                name: value.name,
+                message: value.message,
+                stack: value.stack?.split("\n").slice(0, 5).join("\n"),
+            };
+        }
+        if (value instanceof Date) {
+            return value.toISOString();
+        }
+        if (value instanceof RegExp) {
+            return value.toString();
+        }
+        if (typeof value === "function") {
+            return `[Function: ${value.name || "anonymous"}]`;
+        }
+        if (typeof value === "symbol") {
+            return value.toString();
+        }
+        if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer) {
+            const length = value.byteLength;
+            return `[Buffer: ${length} bytes]`;
+        }
+        if (typeof Buffer !== "undefined" && Buffer.isBuffer(value)) {
+            return `[Buffer: ${value.length} bytes]`;
+        }
+        if (value instanceof Map) {
+            return {
+                __type: "Map",
+                entries: Array.from(value.entries()).slice(0, 100),
+            };
+        }
+        if (value instanceof Set) {
+            return { __type: "Set", values: Array.from(value).slice(0, 100) };
+        }
+        return value;
+    };
+    try {
+        // Custom JSON.stringify with depth tracking
+        const stringifyWithDepth = (val, currentDepth) => {
+            if (currentDepth > maxDepth) {
+                return '"[max depth reached]"';
+            }
+            if (val === null) {
+                return "null";
+            }
+            if (val === undefined) {
+                return '"[undefined]"';
+            }
+            const processed = replacer("", val, currentDepth);
+            if (processed === null) {
+                return "null";
+            }
+            if (typeof processed === "string") {
+                return JSON.stringify(processed);
+            }
+            if (typeof processed === "number" || typeof processed === "boolean") {
+                return String(processed);
+            }
+            if (Array.isArray(processed)) {
+                const items = processed.map((item) => stringifyWithDepth(item, currentDepth + 1));
+                return `[${items.join(",")}]`;
+            }
+            if (typeof processed === "object") {
+                const entries = Object.entries(processed).map(([k, v]) => {
+                    const stringifiedValue = stringifyWithDepth(v, currentDepth + 1);
+                    return `${JSON.stringify(k)}:${stringifiedValue}`;
+                });
+                return `{${entries.join(",")}}`;
+            }
+            return JSON.stringify(processed);
+        };
+        return stringifyWithDepth(obj, 0);
+    }
+    catch {
+        return String(obj);
+    }
+}
+/**
+ * Check if a field name is sensitive and should be redacted.
+ *
+ * @param fieldName - Field name to check
+ * @returns true if the field is sensitive
+ */
+function isSensitiveField(fieldName) {
+    const lowerName = fieldName.toLowerCase();
+    return SENSITIVE_FIELDS.some((field) => lowerName.includes(field.toLowerCase()));
+}
+/**
+ * Sanitize and truncate metadata values.
+ * Redacts sensitive fields and limits size.
+ *
+ * @param key - Field key
+ * @param value - Field value
+ * @param maxSize - Maximum size in characters
+ * @param maxDepth - Maximum depth for nested objects
+ * @returns Sanitized and truncated value
+ */
+function sanitizeAndTruncate(key, value, maxSize, maxDepth) {
+    // Check for sensitive fields
+    if (isSensitiveField(key)) {
+        return "[REDACTED]";
+    }
+    // Serialize value
+    const serialized = typeof value === "string" ? value : safeStringify(value, maxDepth);
+    // Truncate if too large
+    if (serialized.length > maxSize) {
+        return `${serialized.substring(0, maxSize)}... [truncated, total: ${serialized.length} chars]`;
+    }
+    // Return original value if it's a primitive, for cleaner logs
+    if (typeof value === "string" ||
+        typeof value === "number" ||
+        typeof value === "boolean") {
+        return value;
+    }
+    // For objects, try to return parsed version for cleaner logs
+    try {
+        return JSON.parse(serialized);
+    }
+    catch {
+        return serialized;
+    }
+}
+/**
+ * Extract safe metadata from an object.
+ * Sanitizes sensitive fields and handles truncation.
+ *
+ * @param obj - Object to extract metadata from
+ * @param options - Extraction options
+ * @returns Sanitized metadata record
+ *
+ * @example
+ * ```typescript
+ * const metadata = extractSafeMetadata({
+ *   userId: "123",
+ *   password: "secret",
+ *   data: largeObject,
+ * });
+ * // Result: { userId: "123", password: "[REDACTED]", data: truncated }
+ * ```
+ */
+export function extractSafeMetadata(obj, options) {
+    const { maxSize = MAX_METADATA_SIZE, maxDepth = MAX_DEPTH } = options || {};
+    const metadata = {};
+    if (!obj || typeof obj !== "object") {
+        return { value: String(obj) };
+    }
+    for (const [key, value] of Object.entries(obj)) {
+        metadata[key] = sanitizeAndTruncate(key, value, maxSize, maxDepth);
+    }
+    return metadata;
+}
+/**
+ * Create a minimal error representation for logging.
+ * Useful when you need just the essentials without full serialization.
+ *
+ * @param error - Error to summarize
+ * @returns Minimal error representation
+ */
+export function summarizeError(error) {
+    if (error instanceof Error) {
+        return {
+            type: error.name,
+            message: error.message.substring(0, 200),
+            code: "code" in error ? String(error.code) : undefined,
+            fingerprint: generateErrorFingerprint(error),
+        };
+    }
+    const message = String(error).substring(0, 200);
+    return {
+        type: "UnknownError",
+        message,
+        fingerprint: generateFingerprintFromString(message),
+    };
+}

package/dist/client/processors/errors/index.js

@@ -0,0 +1,49 @@
+/**
+ * File Processing Error Infrastructure
+ *
+ * Provides comprehensive error handling for file processing operations:
+ * - Error codes for all file processing scenarios
+ * - Factory functions for creating structured errors
+ * - Error serialization with PII redaction
+ * - Fingerprinting for error deduplication
+ * - Retry determination logic
+ *
+ * @module processors/errors
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   FileErrorCode,
+ *   createFileError,
+ *   isRetryableError,
+ *   serializeError,
+ *   generateErrorFingerprint,
+ * } from "./processors/errors/index.js";
+ *
+ * // Create a structured error
+ * const error = createFileError(FileErrorCode.FILE_TOO_LARGE, {
+ *   sizeMB: "15.5",
+ *   maxMB: "10",
+ *   filename: "large-document.pdf",
+ * });
+ *
+ * // Check if error is retryable
+ * if (isRetryableError(error) && retryCount < maxRetries) {
+ *   await delay(getRetryDelay(error, retryCount));
+ *   return retry();
+ * }
+ *
+ * // Serialize for logging (with PII redaction)
+ * const serialized = serializeError(originalError);
+ * logger.error("File processing failed", serialized);
+ *
+ * // Group similar errors by fingerprint
+ * const fingerprint = generateErrorFingerprint(error);
+ * ```
+ */
+// Error creation helpers
+export { combineSummaries, createCustomFileError, createFileError, createProcessingSummary, extractHttpStatus, formatFileError, getRetryDelay, isFileProcessingError, isRetryableError, mapErrorToCode, } from "./errorHelpers.js";
+// Error serialization
+export { extractSafeMetadata, generateErrorFingerprint, safeStringify, serializeError, summarizeError, } from "./errorSerializer.js";
+// Error codes and message templates
+export { ERROR_MESSAGES, FileErrorCode, getErrorTemplate, isRetryableErrorCode, } from "./FileErrorCode.js";