email-origin-chain 1.0.0

package/dist/index.js

@@ -0,0 +1,132 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractDeepestHybrid = extractDeepestHybrid;
+const mime_layer_1 = require("./mime-layer");
+const inline_layer_1 = require("./inline-layer");
+const utils_1 = require("./utils");
+/**
+ * Main entry point: Extract the deepest forwarded email using hybrid strategy
+ */
+async function extractDeepestHybrid(raw, options) {
+    // Validation
+    if (typeof raw !== 'string') {
+        throw new Error('Input must be a string');
+    }
+    const opts = {
+        maxDepth: options?.maxDepth ?? 15,
+        timeoutMs: options?.timeoutMs ?? 10000,
+        skipMimeLayer: options?.skipMimeLayer ?? false,
+        customDetectors: options?.customDetectors ?? []
+    };
+    const warnings = [];
+    // If skipMimeLayer is true, parse only inline forwards (text-only mode)
+    if (opts.skipMimeLayer) {
+        return await (0, inline_layer_1.processInline)(raw, 0, [], opts.customDetectors);
+    }
+    try {
+        // Step 1: MIME Layer
+        let timer;
+        const mimeResult = await Promise.race([
+            (0, mime_layer_1.processMime)(raw, opts),
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error('MIME parsing timeout')), opts.timeoutMs);
+            })
+        ]).finally(() => {
+            if (timer)
+                clearTimeout(timer);
+        });
+        // Step 2: Inline Layer
+        const inlineResult = await (0, inline_layer_1.processInline)(mimeResult.rawBody, mimeResult.depth, mimeResult.history, opts.customDetectors);
+        // Step 3: Align results
+        let from = (0, utils_1.normalizeFrom)(inlineResult.from);
+        let subject = inlineResult.subject;
+        let date_raw = inlineResult.date_raw;
+        let date_iso = inlineResult.date_iso;
+        let text = inlineResult.text;
+        if (inlineResult.diagnostics.method === 'fallback' && mimeResult.metadata) {
+            const m = mimeResult.metadata;
+            if (!from && m.from?.value?.[0]) {
+                from = (0, utils_1.normalizeFrom)({ name: m.from.value[0].name, address: m.from.value[0].address });
+            }
+            if (!subject && m.subject)
+                subject = m.subject;
+            if (!date_iso && m.date)
+                date_iso = m.date.toISOString();
+            if (!date_raw && m.date)
+                date_raw = m.date.toString();
+            if (!text)
+                text = mimeResult.rawBody;
+        }
+        // Align the root entry of history
+        if (inlineResult.history.length > 0) {
+            const rootInHistory = inlineResult.history[inlineResult.history.length - 1];
+            if (!rootInHistory.from && mimeResult.metadata) {
+                const m = mimeResult.metadata;
+                if (m.from?.value?.[0]) {
+                    rootInHistory.from = (0, utils_1.normalizeFrom)({ name: m.from.value[0].name, address: m.from.value[0].address });
+                }
+                if (m.subject)
+                    rootInHistory.subject = m.subject;
+            }
+        }
+        // Step 4: Final enrichment
+        const attachments = mimeResult.lastAttachments.map(att => ({
+            filename: att.filename,
+            contentType: att.contentType || 'application/octet-stream',
+            size: att.size || 0
+        }));
+        date_iso = date_iso || (0, utils_1.normalizeDateToISO)(date_raw);
+        // Destructure to exclude 'from' since we have our own normalized version
+        const { from: _unusedFrom, ...restInlineResult } = inlineResult;
+        const result = {
+            ...restInlineResult,
+            // Use our normalized/enriched values
+            from,
+            subject,
+            date_raw,
+            date_iso,
+            text: (0, utils_1.cleanText)(text),
+            attachments: [...attachments, ...inlineResult.attachments],
+            diagnostics: {
+                ...inlineResult.diagnostics,
+                depth: mimeResult.depth + inlineResult.diagnostics.depth,
+                method: (inlineResult.diagnostics.method === 'fallback' && mimeResult.isRfc822) ? 'rfc822' : inlineResult.diagnostics.method,
+                parsedOk: !!(from && subject) || !!(from && inlineResult.diagnostics.method !== 'fallback'),
+                warnings: [...warnings, ...inlineResult.diagnostics.warnings]
+            }
+        };
+        return result;
+    }
+    catch (error) {
+        return {
+            from: null,
+            subject: null,
+            date_raw: null,
+            date_iso: null,
+            text: (0, utils_1.cleanText)(raw),
+            attachments: [],
+            history: [],
+            diagnostics: {
+                method: 'fallback',
+                depth: 0,
+                parsedOk: false,
+                warnings: [`Fatal error: ${error.message}`]
+            }
+        };
+    }
+}
+__exportStar(require("./types"), exports);

package/dist/inline-layer.d.ts

@@ -0,0 +1,7 @@
+import { ResultObject, HistoryEntry } from './types';
+import { ForwardDetector } from './detectors/types';
+/**
+ * Process inline forwarded content recursively.
+ * Uses a manual loop with DetectorRegistry to allow multiple strategies (lib, custom regexes, etc.)
+ */
+export declare function processInline(text: string, depth: number, baseHistory?: HistoryEntry[], customDetectors?: ForwardDetector[]): Promise<ResultObject>;

package/dist/inline-layer.js

@@ -0,0 +1,116 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.processInline = processInline;
+const detectors_1 = require("./detectors");
+const utils_1 = require("./utils");
+/**
+ * Process inline forwarded content recursively.
+ * Uses a manual loop with DetectorRegistry to allow multiple strategies (lib, custom regexes, etc.)
+ */
+async function processInline(text, depth, baseHistory = [], customDetectors = []) {
+    const warnings = [];
+    const registry = new detectors_1.DetectorRegistry(customDetectors);
+    const history = [...baseHistory];
+    let currentText = text.trim();
+    const startingDepth = depth;
+    let currentDepth = depth;
+    const maxRecursiveDepth = 15; // Increased for deep chains
+    // Ensure we have at least one entry representing the "current" starting point
+    if (history.length === 0) {
+        history.push({
+            from: null,
+            subject: null,
+            date_raw: null,
+            date_iso: null,
+            text: '',
+            depth: currentDepth,
+            flags: ['level:root', 'trust:medium_inline']
+        });
+    }
+    // Detection loop: This allows combining the library (CrispDetector) 
+    // with custom local detectors (OutlookFRDetector, etc.)
+    while (currentDepth < maxRecursiveDepth) {
+        const result = registry.detect(currentText);
+        if (!result.found || !result.email) {
+            // No more forwards detected
+            const lastIdx = history.length - 1;
+            history[lastIdx].text = (0, utils_1.cleanText)(currentText);
+            break;
+        }
+        const email = result.email;
+        // Update previous level's exclusive text
+        const previousIdx = history.length - 1;
+        history[previousIdx].text = (0, utils_1.cleanText)(result.message || '');
+        if (!history[previousIdx].text && !history[previousIdx].flags.includes('content:silent_forward')) {
+            history[previousIdx].flags.push('content:silent_forward');
+        }
+        // Build flags 
+        const flags = [`method:${result.detector || 'unknown'}`, 'trust:medium_inline'];
+        if (!email.body || email.body.trim() === '') {
+            flags.push('content:silent_forward');
+        }
+        // Normalize date
+        const dateIso = (0, utils_1.normalizeDateToISO)(email.date);
+        if (email.date && !dateIso) {
+            warnings.push(`Could not normalize date: "${email.date}"`);
+            flags.push('date:unparseable');
+        }
+        // Normalize from address (fix patterns like "email [email]")
+        let fromNormalized = typeof email.from === 'object'
+            ? { name: email.from.name, address: email.from.address }
+            : (email.from ? { address: email.from } : null);
+        fromNormalized = (0, utils_1.normalizeFrom)(fromNormalized);
+        // Add this forward level to history
+        history.push({
+            from: fromNormalized,
+            subject: email.subject || null,
+            date_raw: email.date || null,
+            date_iso: dateIso,
+            text: (0, utils_1.cleanText)(email.body || ''),
+            depth: currentDepth + 1,
+            flags: flags
+        });
+        // Continue with the body for next iteration
+        currentText = (email.body || '').trim();
+        currentDepth++;
+    }
+    // Mark the deepest entry
+    if (currentDepth > startingDepth) {
+        const deepestEntry = history[history.length - 1];
+        if (!deepestEntry.flags.includes('level:deepest')) {
+            deepestEntry.flags.push('level:deepest');
+        }
+        return {
+            from: deepestEntry.from,
+            subject: deepestEntry.subject,
+            date_raw: deepestEntry.date_raw,
+            date_iso: deepestEntry.date_iso,
+            text: deepestEntry.text,
+            attachments: [],
+            history: history.slice().reverse(),
+            diagnostics: {
+                method: (deepestEntry.flags.find(f => f.startsWith('method:')) || 'inline'),
+                depth: currentDepth - startingDepth,
+                parsedOk: true,
+                warnings: warnings
+            }
+        };
+    }
+    // No forwards found
+    const currentEntry = history[history.length - 1];
+    return {
+        from: currentEntry.from,
+        subject: currentEntry.subject,
+        date_raw: currentEntry.date_raw,
+        date_iso: currentEntry.date_iso,
+        text: currentEntry.text || (0, utils_1.cleanText)(currentText),
+        attachments: [],
+        history: history.slice().reverse(),
+        diagnostics: {
+            method: 'fallback',
+            depth: 0,
+            parsedOk: false,
+            warnings: warnings.length > 0 ? warnings : ['No forwarded content detected']
+        }
+    };
+}

package/dist/mime-layer.d.ts

@@ -0,0 +1,15 @@
+import { Attachment as MailparserAttachment } from 'mailparser';
+import { Options, HistoryEntry } from './types';
+export interface MimeResult {
+    rawBody: string;
+    depth: number;
+    lastAttachments: MailparserAttachment[];
+    isRfc822: boolean;
+    history: HistoryEntry[];
+    metadata?: {
+        from?: any;
+        subject?: string;
+        date?: Date;
+    };
+}
+export declare function processMime(raw: string, options: Options): Promise<MimeResult>;

package/dist/mime-layer.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.processMime = processMime;
+const mailparser_1 = require("mailparser");
+async function processMime(raw, options) {
+    let currentRaw = raw;
+    let depth = 0;
+    const maxDepth = options.maxDepth || 5;
+    let lastAttachments = [];
+    let isRfc822 = false;
+    const history = [];
+    // Safety check
+    if (typeof raw !== 'string') {
+        throw new Error("MIME parser input must be a string");
+    }
+    // Iterative approach to avoid call stack limits, though recursion is also fine for depth < 100
+    while (depth < maxDepth) {
+        try {
+            const parsed = await (0, mailparser_1.simpleParser)(currentRaw);
+            // Record current level in history
+            history.push({
+                from: parsed.from?.value?.[0] ? {
+                    name: parsed.from.value[0].name,
+                    address: parsed.from.value[0].address
+                } : null,
+                subject: parsed.subject || null,
+                date_raw: parsed.date?.toString() || null,
+                date_iso: parsed.date ? parsed.date.toISOString() : null,
+                text: parsed.text || null, // Will be "exclusive" text once we know if there’s a forward inside
+                depth,
+                flags: ['trust:high_mime']
+            });
+            // Check for attached messages
+            const rfcParts = parsed.attachments.filter(a => a.contentType === 'message/rfc822');
+            if (rfcParts.length > 0) {
+                const last = rfcParts[rfcParts.length - 1];
+                if (last.content) {
+                    currentRaw = last.content.toString('utf8');
+                    depth++;
+                    isRfc822 = true;
+                    // Reset attachments for the new level
+                    lastAttachments = [];
+                    continue;
+                }
+            }
+            return {
+                rawBody: parsed.text || currentRaw,
+                depth,
+                lastAttachments: parsed.attachments,
+                isRfc822,
+                history,
+                metadata: {
+                    from: parsed.from,
+                    subject: parsed.subject,
+                    date: parsed.date
+                }
+            };
+        }
+        catch (error) {
+            break;
+        }
+    }
+    return {
+        rawBody: currentRaw,
+        depth,
+        lastAttachments,
+        isRfc822,
+        history
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,63 @@
+import { ForwardDetector, DetectionResult } from './detectors/types';
+export { ForwardDetector, DetectionResult };
+export interface EmailAddress {
+    name?: string;
+    address?: string;
+}
+export interface Attachment {
+    filename?: string;
+    contentType: string;
+    size: number;
+    content?: any;
+}
+export interface Diagnostics {
+    method: 'rfc822' | 'inline' | 'fallback';
+    depth: number;
+    parsedOk: boolean;
+    warnings: string[];
+}
+export interface HistoryEntry {
+    from: EmailAddress | null;
+    subject: string | null;
+    date_raw: string | null;
+    date_iso: string | null;
+    text: string | null;
+    depth: number;
+    flags: string[];
+}
+export interface ResultObject {
+    from: EmailAddress | null;
+    subject: string | null;
+    date_raw: string | null;
+    date_iso: string | null;
+    text: string | null;
+    attachments: Attachment[];
+    history: HistoryEntry[];
+    diagnostics: Diagnostics;
+}
+/**
+ * Options for extraction behavior
+ */
+export interface Options {
+    /**
+     * Maximum depth to descend through MIME attachments.
+     * Default: 5
+     */
+    maxDepth?: number;
+    /**
+     * Maximum time in milliseconds to wait for MIME parsing before timeout.
+     * Default: 5000ms
+     */
+    timeoutMs?: number;
+    /**
+     * Skip MIME layer processing and parse only inline forwards.
+     * Use this when input is plain text body (not a full email with headers).
+     * Default: false
+     */
+    skipMimeLayer?: boolean;
+    /**
+     * Custom forward detectors to register.
+     * These will be added to the registry and used for detection.
+     */
+    customDetectors?: ForwardDetector[];
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/utils/cleaner.d.ts

@@ -0,0 +1,16 @@
+export declare class Cleaner {
+    private static normalizationCache;
+    /**
+     * Normalizes whitespace scories (BOM, nbsp, line breaks)
+     */
+    static normalize(text: string): string;
+    /**
+     * Consistently strips quotes (>) and common Outlook leading indentation (4 spaces)
+     */
+    static stripQuotes(text: string): string;
+    /**
+     * Robustly identifies the body after a header block by finding the
+     * first double-newline (or single if strict) after the last known header line.
+     */
+    static extractBody(lines: string[], lastHeaderIndex: number): string;
+}

package/dist/utils/cleaner.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Cleaner = void 0;
+class Cleaner {
+    /**
+     * Normalizes whitespace scories (BOM, nbsp, line breaks)
+     */
+    static normalize(text) {
+        if (!text)
+            return '';
+        const cached = this.normalizationCache.get(text);
+        if (cached !== undefined)
+            return cached;
+        const normalized = text
+            .replace(/\r\n/gm, '\n')
+            .replace(/\uFEFF/gm, '')
+            .replace(/\u00A0$/gm, '')
+            .replace(/\u00A0/gm, ' ')
+            .trim();
+        if (this.normalizationCache.size > 200) {
+            this.normalizationCache.clear();
+        }
+        this.normalizationCache.set(text, normalized);
+        return normalized;
+    }
+    /**
+     * Consistently strips quotes (>) and common Outlook leading indentation (4 spaces)
+     */
+    static stripQuotes(text) {
+        return text
+            .replace(/^(>+)\s?$/gm, '') // Empty quote lines
+            .replace(/^(>+)\s?/gm, '') // Quote lines with content
+            .replace(/^(\ {4})\s?/gm, ''); // 4 spaces indentation
+    }
+    /**
+     * Robustly identifies the body after a header block by finding the
+     * first double-newline (or single if strict) after the last known header line.
+     */
+    static extractBody(lines, lastHeaderIndex) {
+        // Crisp logic: looks for \n\n (start of next line being empty)
+        // following the last header.
+        let bodyStartIndex = lastHeaderIndex + 1;
+        // Skip any empty lines immediately following headers to find the real body start
+        while (bodyStartIndex < lines.length && lines[bodyStartIndex].trim() === '') {
+            bodyStartIndex++;
+        }
+        return lines.slice(bodyStartIndex).join('\n').trim();
+    }
+}
+exports.Cleaner = Cleaner;
+Cleaner.normalizationCache = new Map();

package/dist/utils.d.ts

@@ -0,0 +1,17 @@
+import { ResultObject, EmailAddress } from './types';
+export declare function normalizeDateToISO(dateRaw: string | Date | null | undefined): string | null;
+export declare function cleanText(text: string | null | undefined): string | null;
+/**
+ * Normalizes EmailAddress to fix edge cases like "email [email]" pattern
+ *
+ * Issue: Some email clients (Gmail, Outlook) produce formats like:
+ *   "john.doe@example.com [john.doe@example.com]"
+ *
+ * email-forward-parser may parse this as:
+ *   { name: "john.doe@example.com [john.doe@example.com]", address: "" }
+ *
+ * This function detects and fixes this pattern to:
+ *   { name: null, address: "john.doe@example.com" }
+ */
+export declare function normalizeFrom(from: EmailAddress | null | undefined): EmailAddress | null;
+export declare function normalizeParserResult(parsed: any, method: 'inline' | 'fallback', depth: number, warnings?: string[]): ResultObject;