@juspay/neurolink 9.94.1 → 9.94.3

package/dist/lib/utils/csvUtils.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Shared, RFC-4180-aware delimiter-separated-value helpers.
+ *
+ * Consolidates quote-aware field counting/splitting that was previously
+ * duplicated across csvProcessor.ts and fileDetector.ts (#359), and adds
+ * delimiter detection so TSV / semicolon / pipe files parse correctly (#361).
+ * Keeping these in one module prevents the same quoting edge case from having
+ * to be fixed in three places and drifting out of sync.
+ */
+/** Delimiter candidates, in tie-break preference order (comma first). */
+export declare const CANDIDATE_DELIMITERS: readonly [",", "\t", ";", "|"];
+/**
+ * Split a single line into fields, respecting RFC-4180 quoting: a delimiter
+ * inside a `"…"` quoted field does not split, and `""` is an escaped quote.
+ */
+export declare function splitCSVFields(line: string, delimiter?: string): string[];
+/** Count fields in a single line, respecting RFC-4180 quoting. */
+export declare function countCSVColumns(line: string, delimiter?: string): number;
+/**
+ * Detect the delimiter of DSV content by testing comma/tab/semicolon/pipe
+ * against up to 5 sampled non-empty lines and keeping the candidate with the
+ * most consistent (>1) column count. Comma wins ties and the "nothing splits"
+ * case, so plain CSVs are never reclassified. An optional extension hint
+ * (`tsv` → tab, `psv` → pipe) breaks ambiguity in the file's favor.
+ */
+export declare function detectDelimiter(lines: string[], extensionHint?: string): string;

package/dist/lib/utils/csvUtils.js

@@ -0,0 +1,85 @@
+/**
+ * Shared, RFC-4180-aware delimiter-separated-value helpers.
+ *
+ * Consolidates quote-aware field counting/splitting that was previously
+ * duplicated across csvProcessor.ts and fileDetector.ts (#359), and adds
+ * delimiter detection so TSV / semicolon / pipe files parse correctly (#361).
+ * Keeping these in one module prevents the same quoting edge case from having
+ * to be fixed in three places and drifting out of sync.
+ */
+/** Delimiter candidates, in tie-break preference order (comma first). */
+export const CANDIDATE_DELIMITERS = [",", "\t", ";", "|"];
+/**
+ * Split a single line into fields, respecting RFC-4180 quoting: a delimiter
+ * inside a `"…"` quoted field does not split, and `""` is an escaped quote.
+ */
+export function splitCSVFields(line, delimiter = ",") {
+    const fields = [];
+    let field = "";
+    let inQuotes = false;
+    for (let i = 0; i < line.length; i++) {
+        const ch = line[i];
+        if (ch === '"') {
+            if (inQuotes && line[i + 1] === '"') {
+                field += '"';
+                i++; // consume the escaped quote
+                continue;
+            }
+            inQuotes = !inQuotes;
+        }
+        else if (ch === delimiter && !inQuotes) {
+            fields.push(field);
+            field = "";
+        }
+        else {
+            field += ch;
+        }
+    }
+    fields.push(field);
+    return fields;
+}
+/** Count fields in a single line, respecting RFC-4180 quoting. */
+export function countCSVColumns(line, delimiter = ",") {
+    return splitCSVFields(line, delimiter).length;
+}
+/**
+ * Detect the delimiter of DSV content by testing comma/tab/semicolon/pipe
+ * against up to 5 sampled non-empty lines and keeping the candidate with the
+ * most consistent (>1) column count. Comma wins ties and the "nothing splits"
+ * case, so plain CSVs are never reclassified. An optional extension hint
+ * (`tsv` → tab, `psv` → pipe) breaks ambiguity in the file's favor.
+ */
+export function detectDelimiter(lines, extensionHint) {
+    const sample = lines.filter((l) => l.trim() !== "").slice(0, 5);
+    if (sample.length === 0) {
+        return ",";
+    }
+    const hint = extensionHint?.toLowerCase().replace(/^\./, "");
+    const hinted = hint === "tsv" ? "\t" : hint === "psv" ? "|" : undefined;
+    let best = ",";
+    let bestScore = -1;
+    for (const delim of CANDIDATE_DELIMITERS) {
+        const counts = sample.map((l) => countCSVColumns(l, delim));
+        const headerCols = counts[0];
+        if (headerCols <= 1) {
+            continue; // this delimiter doesn't split the header — not the delimiter
+        }
+        const consistent = counts.every((c) => c === headerCols);
+        // Prefer: a matching extension hint, then consistency, then more columns,
+        // with a small comma bias so comma stays the default on ties.
+        const score = (delim === hinted ? 1000 : 0) +
+            (consistent ? 100 : 0) +
+            headerCols +
+            (delim === "," ? 0.5 : 0);
+        if (score > bestScore) {
+            bestScore = score;
+            best = delim;
+        }
+    }
+    // Nothing split multi-column, but the extension says otherwise — honor it.
+    if (bestScore < 0 && hinted) {
+        return hinted;
+    }
+    return best;
+}
+//# sourceMappingURL=csvUtils.js.map

package/dist/lib/utils/errorHandling.d.ts

@@ -51,6 +51,10 @@ export declare const ERROR_CODES: {
     readonly INVALID_PPT_LOGO_PATH: "INVALID_PPT_LOGO_PATH";
     readonly INVALID_PPT_MODE: "INVALID_PPT_MODE";
     readonly INVALID_PPT_PROMPT: "INVALID_PPT_PROMPT";
+    readonly CSV_INVALID_INPUT: "CSV_INVALID_INPUT";
+    readonly CSV_ROW_INVALID: "CSV_ROW_INVALID";
+    readonly CSV_FILE_ACCESS_FAILED: "CSV_FILE_ACCESS_FAILED";
+    readonly CSV_PARSE_FAILED: "CSV_PARSE_FAILED";
 };
 /**
  * Enhanced error class with structured information
@@ -128,6 +132,25 @@ export declare class ErrorFactory {
      * Create an invalid configuration error (e.g., NaN for numeric values)
      */
     static invalidConfiguration(configName: string, reason: string, context?: Record<string, unknown>): NeuroLinkError;
+    /**
+     * Create an invalid CSV input error (e.g. an empty filePath/csvString argument).
+     */
+    static csvInvalidInput(message: string): NeuroLinkError;
+    /**
+     * Create a CSV row-shape violation error (#384) — a parsed row that isn't a
+     * string-keyed object with string values.
+     */
+    static csvRowInvalid(message: string, rowNumber: number): NeuroLinkError;
+    /**
+     * Create a CSV file access error (bad path, permissions, ENOENT/EACCES) (#375).
+     */
+    static csvFileAccessFailed(message: string, filePath: string, originalError?: Error): NeuroLinkError;
+    /**
+     * Create a CSV read/parse failure error (#375) — source stream errors and
+     * csv-parser errors both route through this, carrying the enriched
+     * `buildCsvParseErrorMessage` context in `message`.
+     */
+    static csvParseFailed(message: string, context: Record<string, unknown>, originalError?: Error): NeuroLinkError;
     /**
      * Create an invalid video resolution error
      */

package/dist/lib/utils/errorHandling.js

@@ -66,6 +66,11 @@ export const ERROR_CODES = {
     INVALID_PPT_LOGO_PATH: "INVALID_PPT_LOGO_PATH",
     INVALID_PPT_MODE: "INVALID_PPT_MODE",
     INVALID_PPT_PROMPT: "INVALID_PPT_PROMPT",
+    // CSV validation/parsing errors (#1199)
+    CSV_INVALID_INPUT: "CSV_INVALID_INPUT",
+    CSV_ROW_INVALID: "CSV_ROW_INVALID",
+    CSV_FILE_ACCESS_FAILED: "CSV_FILE_ACCESS_FAILED",
+    CSV_PARSE_FAILED: "CSV_PARSE_FAILED",
 };
 /**
  * Enhanced error class with structured information
@@ -259,6 +264,66 @@ export class ErrorFactory {
         });
     }
     // ============================================================================
+    // CSV VALIDATION/PARSING ERRORS (#1199)
+    // ============================================================================
+    /**
+     * Create an invalid CSV input error (e.g. an empty filePath/csvString argument).
+     */
+    static csvInvalidInput(message) {
+        return new NeuroLinkError({
+            code: ERROR_CODES.CSV_INVALID_INPUT,
+            message,
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: false,
+            context: {},
+        });
+    }
+    /**
+     * Create a CSV row-shape violation error (#384) — a parsed row that isn't a
+     * string-keyed object with string values.
+     */
+    static csvRowInvalid(message, rowNumber) {
+        return new NeuroLinkError({
+            code: ERROR_CODES.CSV_ROW_INVALID,
+            message,
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: false,
+            context: { rowNumber },
+        });
+    }
+    /**
+     * Create a CSV file access error (bad path, permissions, ENOENT/EACCES) (#375).
+     */
+    static csvFileAccessFailed(message, filePath, originalError) {
+        return new NeuroLinkError({
+            code: ERROR_CODES.CSV_FILE_ACCESS_FAILED,
+            message,
+            category: ErrorCategory.RESOURCE,
+            severity: ErrorSeverity.HIGH,
+            retriable: false,
+            context: { filePath },
+            originalError,
+        });
+    }
+    /**
+     * Create a CSV read/parse failure error (#375) — source stream errors and
+     * csv-parser errors both route through this, carrying the enriched
+     * `buildCsvParseErrorMessage` context in `message`.
+     */
+    static csvParseFailed(message, context, originalError) {
+        return new NeuroLinkError({
+            code: ERROR_CODES.CSV_PARSE_FAILED,
+            message,
+            category: ErrorCategory.EXECUTION,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: false,
+            context,
+            originalError,
+        });
+    }
+    // ============================================================================
     // VIDEO VALIDATION ERRORS
     // ============================================================================
     /**

package/dist/lib/utils/multimodalOptionsBuilder.d.ts

@@ -50,11 +50,7 @@ export declare function buildMultimodalOptions(options: StreamOptions, providerN
         csvFiles: (string | Buffer<ArrayBufferLike>)[] | undefined;
         pdfFiles: (string | Buffer<ArrayBufferLike>)[] | undefined;
     };
-    csvOptions: {
-        maxRows?: number;
-        formatStyle?: "raw" | "markdown" | "json";
-        includeHeaders?: boolean;
-    } | undefined;
+    csvOptions: import("../types/file.js").CSVProcessorOptions | undefined;
     systemPrompt: string | undefined;
     conversationHistory: import("../types/conversation.js").ChatMessage[] | undefined;
     provider: string;

package/dist/lib/utils/textEncoding.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Buffer → string decoding with encoding detection (#362).
+ *
+ * Order of resolution:
+ *   1. Explicit override (any iconv-lite label).
+ *   2. Deterministic BOM sniff (UTF-8 / UTF-16 LE / UTF-16 BE).
+ *   3. `chardet` statistical detection, mapped to an iconv-lite label.
+ *   4. Fallback to UTF-8 (preserves the historical hard-coded default).
+ *
+ * Decoding always goes through `iconv-lite`, and any residual BOM is stripped
+ * from the decoded string so it can't glue onto the first token.
+ */
+import type { DecodedBuffer } from "../types/index.js";
+/** Strip a leading BOM (U+FEFF) from an already-decoded string. */
+export declare function stripBomString(text: string): string;
+/**
+ * Decode a buffer to text, detecting the encoding unless overridden.
+ *
+ * @param isCompleteBuffer - Whether `buffer` is the entire source (default
+ *   `true`). Pass `false` when `buffer` is only a peeked prefix (e.g. a
+ *   streaming head-sniff) — the ASCII fast path still commits to "utf-8" for
+ *   the peeked bytes (unchanged behavior), but reports a lower confidence
+ *   since later bytes not yet seen could still be non-ASCII (#1199).
+ */
+export declare function decodeBuffer(buffer: Buffer, override?: string, isCompleteBuffer?: boolean): DecodedBuffer;

package/dist/lib/utils/textEncoding.js

@@ -0,0 +1,141 @@
+/**
+ * Buffer → string decoding with encoding detection (#362).
+ *
+ * Order of resolution:
+ *   1. Explicit override (any iconv-lite label).
+ *   2. Deterministic BOM sniff (UTF-8 / UTF-16 LE / UTF-16 BE).
+ *   3. `chardet` statistical detection, mapped to an iconv-lite label.
+ *   4. Fallback to UTF-8 (preserves the historical hard-coded default).
+ *
+ * Decoding always goes through `iconv-lite`, and any residual BOM is stripped
+ * from the decoded string so it can't glue onto the first token.
+ */
+import chardet from "chardet";
+import iconv from "iconv-lite";
+import { logger } from "./logger.js";
+/** Strip a leading BOM (U+FEFF) from an already-decoded string. */
+export function stripBomString(text) {
+    return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}
+/** Deterministic BOM detection from the raw bytes. Returns null when absent. */
+function sniffBom(buffer) {
+    if (buffer.length >= 3 &&
+        buffer[0] === 0xef &&
+        buffer[1] === 0xbb &&
+        buffer[2] === 0xbf) {
+        return "utf-8";
+    }
+    if (buffer.length >= 2 && buffer[0] === 0xff && buffer[1] === 0xfe) {
+        return "utf-16le";
+    }
+    if (buffer.length >= 2 && buffer[0] === 0xfe && buffer[1] === 0xff) {
+        return "utf-16be";
+    }
+    return null;
+}
+/**
+ * Map a chardet label to an iconv-lite-supported label. Returns null when the
+ * label is unknown/unsupported so the caller falls back to UTF-8.
+ */
+function toIconvLabel(detected) {
+    if (!detected) {
+        return null;
+    }
+    const normalized = detected.toLowerCase().replace(/[^a-z0-9]/g, "");
+    const map = {
+        utf8: "utf-8",
+        utf16le: "utf-16le",
+        utf16be: "utf-16be",
+        ascii: "utf-8", // ASCII is a strict UTF-8 subset
+        windows1252: "windows-1252",
+        iso88591: "latin1",
+        latin1: "latin1",
+        iso88592: "iso-8859-2",
+        windows1251: "windows-1251",
+        koi8r: "koi8-r",
+        gb18030: "gb18030",
+        big5: "big5",
+        shiftjis: "shift_jis",
+        euckr: "euc-kr",
+        eucjp: "euc-jp",
+    };
+    const label = map[normalized] ?? detected;
+    return iconv.encodingExists(label) ? label : null;
+}
+/**
+ * Decode a buffer to text, detecting the encoding unless overridden.
+ *
+ * @param isCompleteBuffer - Whether `buffer` is the entire source (default
+ *   `true`). Pass `false` when `buffer` is only a peeked prefix (e.g. a
+ *   streaming head-sniff) — the ASCII fast path still commits to "utf-8" for
+ *   the peeked bytes (unchanged behavior), but reports a lower confidence
+ *   since later bytes not yet seen could still be non-ASCII (#1199).
+ */
+export function decodeBuffer(buffer, override, isCompleteBuffer = true) {
+    // 1. Explicit override wins outright.
+    if (override && iconv.encodingExists(override)) {
+        return {
+            text: stripBomString(iconv.decode(buffer, override)),
+            encoding: override,
+            confidence: 100,
+        };
+    }
+    if (override && !iconv.encodingExists(override)) {
+        logger.warn(`[textEncoding] Unsupported encoding override "${override}"; falling back to detection.`);
+    }
+    // 2. BOM is authoritative when present.
+    const bom = sniffBom(buffer);
+    if (bom) {
+        return {
+            text: stripBomString(iconv.decode(buffer, bom)),
+            encoding: bom,
+            confidence: 100,
+        };
+    }
+    // 2b. Pure-ASCII fast path — chardet often reports ASCII as ISO-8859-1, but
+    // ASCII is a strict UTF-8 subset and decodes identically, so report "utf-8"
+    // to preserve the historical default for plain-ASCII files.
+    let ascii = true;
+    for (let i = 0; i < buffer.length; i++) {
+        if (buffer[i] >= 0x80) {
+            ascii = false;
+            break;
+        }
+    }
+    if (ascii) {
+        return {
+            text: stripBomString(iconv.decode(buffer, "utf-8")),
+            encoding: "utf-8",
+            // A partial peek being pure-ASCII only proves the peeked prefix is
+            // ASCII, not the whole file — a later chunk could still switch to a
+            // legacy encoding. Only report full certainty when `buffer` is known
+            // to be the complete source.
+            confidence: isCompleteBuffer ? 100 : 60,
+        };
+    }
+    // 3. Statistical detection.
+    let detected = null;
+    try {
+        detected = chardet.detect(buffer);
+    }
+    catch (error) {
+        logger.debug(`[textEncoding] chardet failed: ${String(error)}`);
+    }
+    const label = toIconvLabel(detected);
+    if (label) {
+        return {
+            text: stripBomString(iconv.decode(buffer, label)),
+            encoding: label,
+            // chardet gives a winner but not a numeric score via detect(); treat a
+            // confident non-UTF-8 hit as reasonably (not fully) certain.
+            confidence: label === "utf-8" ? 100 : 80,
+        };
+    }
+    // 4. Fallback: historical UTF-8 default.
+    return {
+        text: stripBomString(iconv.decode(buffer, "utf-8")),
+        encoding: "utf-8",
+        confidence: 0,
+    };
+}
+//# sourceMappingURL=textEncoding.js.map

package/dist/neurolink.js

@@ -3820,6 +3820,11 @@ Current user's request: ${currentInput}`;
             evaluationDomain: options.evaluationDomain,
             toolUsageContext: options.toolUsageContext,
             input: options.input,
+            // CSV processing options must survive the reconstruction into
+            // TextGenerationOptions — the message builder reads them (encoding,
+            // formatting, sanitization, parse timeout). Omitting them silently
+            // dropped every csvOptions field (incl. the CLI --csv-* flags).
+            csvOptions: options.csvOptions,
             region: options.region,
             tts: options.tts,
             stt: options.stt,

package/dist/rag/document/loaders.d.ts

@@ -61,9 +61,20 @@ export declare class JSONLoader extends TextLoader {
 export declare class CSVLoader extends TextLoader {
     load(source: string, options?: CSVLoaderOptions): Promise<MDocument>;
     canHandle(source: string): boolean;
-    private parseCSVLine;
     private toMarkdownTable;
     private toTextTable;
+    /**
+     * Collapse embedded newlines to a single space so one logical CSV row
+     * renders as exactly one line in the text/markdown table output.
+     *
+     * The shared quote-aware parser (`splitCsvLines` + `splitCSVFields`)
+     * preserves newlines embedded inside a quoted field verbatim — correct
+     * for the `json` output format (where `JSON.stringify` escapes them), but
+     * left as-is here it would split a single record across multiple
+     * physical table rows. Mirrors the same normalization `CSVProcessor`
+     * already applies in its own markdown formatter.
+     */
+    private collapseEmbeddedNewlines;
 }
 /**
  * PDF file loader

package/dist/rag/document/loaders.js

@@ -27,6 +27,8 @@ import { existsSync } from "fs";
 import { readFile } from "fs/promises";
 import { basename, extname } from "path";
 import { logger } from "../../utils/logger.js";
+import { CSVProcessor, stripBom, stripMetadataLine, splitCsvLines, dedupeColumnNames, sanitizeColumnName, } from "../../utils/csvProcessor.js";
+import { splitCSVFields } from "../../utils/csvUtils.js";
 import { MDocument } from "./MDocument.js";
 /**
  * Text file loader
@@ -115,17 +117,48 @@ export class JSONLoader extends TextLoader {
 export class CSVLoader extends TextLoader {
     async load(source, options) {
         const content = await this.loadContent(source, options?.encoding);
-        const { delimiter = ",", hasHeader = true, columns, outputFormat = "text", } = options || {};
-        const lines = content.split("\n").filter((line) => line.trim());
-        const headers = hasHeader
-            ? this.parseCSVLine(lines[0], delimiter)
-            : columns || lines[0]?.split(delimiter).map((_, i) => `col${i + 1}`);
+        const { delimiter, hasHeader = true, columns, outputFormat = "text", sanitizeColumnNames = false, columnNameCase = "snake_case", } = options || {};
+        // #361: an explicit delimiter always wins; otherwise detect it from the
+        // content + extension so a .tsv fed through RAG isn't collapsed into one
+        // comma-column (CSVLoader.canHandle already accepts .tsv).
+        const effectiveDelimiter = delimiter ?? CSVProcessor.detectDelimiter(content, extname(source));
+        // Route header/row parsing through the same shared, quote-aware path
+        // detectDelimiter() above already uses internally: a quote-aware logical
+        // row split (splitCsvLines — a newline inside a quoted field stays part
+        // of that field instead of breaking the row) with a leading Excel `sep=`
+        // preamble line stripped (stripMetadataLine), so it can't be parsed as
+        // the header. Field-level splitting also goes through the shared
+        // RFC-4180-aware splitCSVFields() instead of the loader's own naive
+        // backslash-escape parser, which didn't handle doubled-quote (`""`)
+        // escaping or quoted delimiters in the headerless-columns branch.
+        const { dataLines: strippedLines } = stripMetadataLine(splitCsvLines(stripBom(content)));
+        const lines = strippedLines.filter((line) => line.trim());
+        const rawHeaders = hasHeader
+            ? splitCSVFields(lines[0] ?? "", effectiveDelimiter).map((h) => h.trim())
+            : columns ||
+                splitCSVFields(lines[0] ?? "", effectiveDelimiter).map((_, i) => `col${i + 1}`);
+        // #378: apply the same opt-in header sanitization CSVProcessor offers, so
+        // the RAG ingestion path doesn't corrupt "Price ($)"-style headers as keys.
+        const headers = sanitizeColumnNames
+            ? dedupeColumnNames(rawHeaders.map((h, i) => sanitizeColumnName(h, columnNameCase, i)))
+            : rawHeaders;
         const dataLines = hasHeader ? lines.slice(1) : lines;
-        const rows = dataLines.map((line) => this.parseCSVLine(line, delimiter));
+        const rows = dataLines.map((line) => splitCSVFields(line, effectiveDelimiter).map((field) => field.trim()));
         let formattedContent;
         switch (outputFormat) {
             case "json":
-                formattedContent = JSON.stringify(rows.map((row) => Object.fromEntries(headers.map((h, i) => [h, row[i]]))), null, 2);
+                formattedContent = JSON.stringify(rows.map((row) => {
+                    // Defense-in-depth against a caller-controlled header literally
+                    // named "__proto__"/"constructor"/"prototype" (#1199);
+                    // Object.fromEntries can't actually pollute Object.prototype here
+                    // (spec semantics), but a null-prototype target avoids relying on
+                    // that for future readers.
+                    const record = Object.create(null);
+                    headers.forEach((h, i) => {
+                        record[h] = row[i];
+                    });
+                    return record;
+                }), null, 2);
                 break;
             case "markdown":
                 formattedContent = this.toMarkdownTable(headers, rows);
@@ -145,42 +178,39 @@ export class CSVLoader extends TextLoader {
         const ext = extname(source).toLowerCase();
         return ext === ".csv" || ext === ".tsv";
     }
-    parseCSVLine(line, delimiter) {
-        const result = [];
-        let current = "";
-        let inQuotes = false;
-        for (let i = 0; i < line.length; i++) {
-            const char = line[i];
-            if (char === '"' && (i === 0 || line[i - 1] !== "\\")) {
-                inQuotes = !inQuotes;
-            }
-            else if (char === delimiter && !inQuotes) {
-                result.push(current.trim());
-                current = "";
-            }
-            else {
-                current += char;
-            }
-        }
-        result.push(current.trim());
-        return result;
-    }
     toMarkdownTable(headers, rows) {
-        const headerRow = `| ${headers.join(" | ")} |`;
-        const separator = `| ${headers.map(() => "---").join(" | ")} |`;
-        const dataRows = rows.map((row) => `| ${row.join(" | ")} |`);
+        const safeHeaders = headers.map((h) => this.collapseEmbeddedNewlines(h));
+        const headerRow = `| ${safeHeaders.join(" | ")} |`;
+        const separator = `| ${safeHeaders.map(() => "---").join(" | ")} |`;
+        const dataRows = rows.map((row) => `| ${row.map((cell) => this.collapseEmbeddedNewlines(cell)).join(" | ")} |`);
         return [headerRow, separator, ...dataRows].join("\n");
     }
     toTextTable(headers, rows) {
-        const allRows = [headers, ...rows];
-        const colWidths = headers.map((_, i) => Math.max(...allRows.map((row) => (row[i] || "").length)));
+        const safeHeaders = headers.map((h) => this.collapseEmbeddedNewlines(h));
+        const safeRows = rows.map((row) => row.map((cell) => this.collapseEmbeddedNewlines(cell)));
+        const allRows = [safeHeaders, ...safeRows];
+        const colWidths = safeHeaders.map((_, i) => Math.max(...allRows.map((row) => (row[i] || "").length)));
         const formatRow = (row) => row.map((cell, i) => (cell || "").padEnd(colWidths[i])).join(" | ");
         return [
-            formatRow(headers),
+            formatRow(safeHeaders),
             colWidths.map((w) => "-".repeat(w)).join("-+-"),
-            ...rows.map(formatRow),
+            ...safeRows.map(formatRow),
         ].join("\n");
     }
+    /**
+     * Collapse embedded newlines to a single space so one logical CSV row
+     * renders as exactly one line in the text/markdown table output.
+     *
+     * The shared quote-aware parser (`splitCsvLines` + `splitCSVFields`)
+     * preserves newlines embedded inside a quoted field verbatim — correct
+     * for the `json` output format (where `JSON.stringify` escapes them), but
+     * left as-is here it would split a single record across multiple
+     * physical table rows. Mirrors the same normalization `CSVProcessor`
+     * already applies in its own markdown formatter.
+     */
+    collapseEmbeddedNewlines(cell) {
+        return cell.replace(/\r\n|\n|\r/g, " ");
+    }
 }
 /**
  * PDF file loader

package/dist/types/file.d.ts

@@ -80,6 +80,17 @@ export type FileProcessingResult = {
         hasHeaders?: boolean;
         /** Detected delimiter */
         detectedDelimiter?: string;
+        /** Detected (or overridden) character encoding used to decode the CSV (#362) */
+        detectedEncoding?: string;
+        /** Confidence (0-100) of the detected encoding (#362) */
+        encodingConfidence?: number;
+        /** Original→sanitized column-name mapping when sanitizeColumnNames is on (#378) */
+        columnNameMapping?: Array<{
+            original: string;
+            sanitized: string;
+        }>;
+        /** True when the parse hit its time budget and returned partial rows (#379) */
+        parseTimedOut?: boolean;
         version?: string;
         estimatedPages?: number | null;
         provider?: string;
@@ -125,6 +136,8 @@ export type CSVDataQualityWarning = {
  */
 export type CSVColumnMetadata = {
     name: string;
+    /** Original header text before sanitization, when sanitizeColumnNames rewrote it (#378) */
+    originalName?: string;
     index: number;
     detectedType: CSVColumnDataType;
     /** Confidence of type detection (0-100) */
@@ -146,6 +159,17 @@ export type CSVColumnMetadata = {
     /** Column name validation issues */
     nameIssues?: string[];
 };
+/** A parsed CSV row: string-keyed with string (or missing) cell values (#384). */
+export type CSVRow = Record<string, string | undefined>;
+/** Result of decoding a buffer with encoding detection (#362). */
+export type DecodedBuffer = {
+    /** Decoded text with any BOM removed. */
+    text: string;
+    /** iconv-lite label actually used to decode. */
+    encoding: string;
+    /** Detection confidence 0-100 (100 for BOM/override, 0 for the UTF-8 fallback). */
+    confidence: number;
+};
 /**
  * CSV processor options
  */
@@ -155,6 +179,25 @@ export type CSVProcessorOptions = {
     includeHeaders?: boolean;
     sampleDataFormat?: SampleDataFormat;
     extension?: string | null;
+    /**
+     * Character encoding override (#362). When omitted, the encoding is detected
+     * from a BOM then `chardet`, falling back to UTF-8. Accepts any label
+     * `iconv-lite` supports (e.g. "utf-8", "utf-16le", "windows-1252", "latin1").
+     */
+    encoding?: string;
+    /**
+     * Rewrite column headers into valid identifiers (#378). Opt-in; default false
+     * preserves the raw header strings as object keys.
+     */
+    sanitizeColumnNames?: boolean;
+    /** Case style used when `sanitizeColumnNames` is on (#378). Default "snake_case". */
+    columnNameCase?: "camelCase" | "snake_case";
+    /**
+     * Wall-clock cap for the streaming parse in milliseconds (#379). On timeout the
+     * parse returns the rows collected so far and flags `metadata.parseTimedOut`,
+     * rather than hanging forever. Defaults: 30s for strings, 5min for files.
+     */
+    parseTimeoutMs?: number;
 };
 /**
  * PDF API types for different providers