@realtimex/email-automator 2.4.5 → 2.6.4

package/dist/api/src/services/processor.js

@@ -1,14 +1,17 @@
+import { simpleParser } from 'mailparser';
 import { createLogger } from '../utils/logger.js';
 import { config } from '../config/index.js';
 import { getGmailService } from './gmail.js';
 import { getMicrosoftService } from './microsoft.js';
 import { getIntelligenceService } from './intelligence.js';
+import { getStorageService } from './storage.js';
 import { EventLogger } from './eventLogger.js';
 const logger = createLogger('Processor');
 export class EmailProcessorService {
     supabase;
     gmailService = getGmailService();
     microsoftService = getMicrosoftService();
+    storageService = getStorageService();
     constructor(supabase) {
         this.supabase = supabase;
     }
@@ -35,6 +38,11 @@ export class EmailProcessorService {
             if (accError || !account) {
                 throw new Error('Account not found or access denied');
             }
+            logger.info('Retrieved account settings', {
+                accountId: account.id,
+                sync_start_date: account.sync_start_date,
+                last_sync_checkpoint: account.last_sync_checkpoint
+            });
             // Refresh token if needed
             let refreshedAccount = account;
             if (account.provider === 'gmail') {
@@ -72,6 +80,8 @@ export class EmailProcessorService {
             }
             // After processing new emails, run retention rules for this account
             await this.runRetentionRules(refreshedAccount, rules || [], settings, result, eventLogger);
+            // Trigger background worker (async) to process the queue
+            this.processQueue(userId, settings).catch(err => logger.error('Background worker failed', err));
             // Update log and account on success
             if (log) {
                 await this.supabase
@@ -89,10 +99,11 @@ export class EmailProcessorService {
                 .from('email_accounts')
                 .update({
                 last_sync_status: 'success',
-                last_sync_error: null
+                last_sync_error: null,
+                sync_start_date: null // Clear manual override once used successfully
             })
                 .eq('id', accountId);
-            logger.info('Sync completed', { accountId, ...result });
+            logger.info('Sync completed and override cleared', { accountId, ...result });
         }
         catch (error) {
             logger.error('Sync failed', error, { accountId });
@@ -125,51 +136,69 @@ export class EmailProcessorService {
     }
     async processGmailAccount(account, rules, settings, result, eventLogger) {
         const batchSize = account.sync_max_emails_per_run || config.processing.batchSize;
-        // Construct query: Use checkpoint if it's newer than the user-defined start date
+        // Debug: Log account sync settings
+        logger.info('Gmail sync settings', {
+            accountId: account.id,
+            sync_start_date: account.sync_start_date,
+            last_sync_checkpoint: account.last_sync_checkpoint,
+            sync_max_emails_per_run: account.sync_max_emails_per_run,
+        });
+        // Construct query: Use a sliding window for efficiency and determinism
         let effectiveStartMs = 0;
         if (account.sync_start_date) {
             effectiveStartMs = new Date(account.sync_start_date).getTime();
+            logger.info('Using sync_start_date override', { effectiveStartMs, date: new Date(effectiveStartMs).toISOString() });
         }
-        if (account.last_sync_checkpoint) {
-            const checkpointMs = parseInt(account.last_sync_checkpoint);
-            if (checkpointMs > effectiveStartMs) {
-                effectiveStartMs = checkpointMs;
+        else if (account.last_sync_checkpoint) {
+            effectiveStartMs = parseInt(account.last_sync_checkpoint);
+            logger.info('Using last_sync_checkpoint', { effectiveStartMs, date: new Date(effectiveStartMs).toISOString() });
+        }
+        // Use a 7-day sliding window. If empty, skip forward (up to 10 weeks per run)
+        const windowSizeMs = 7 * 24 * 60 * 60 * 1000;
+        const nowMs = Date.now();
+        const tomorrowMs = nowMs + (24 * 60 * 60 * 1000);
+        let currentStartMs = effectiveStartMs;
+        let messages = [];
+        let hasMore = false;
+        let attempts = 0;
+        const maxAttempts = 10;
+        while (attempts < maxAttempts && currentStartMs < nowMs) {
+            let effectiveEndMs = currentStartMs + windowSizeMs;
+            if (effectiveEndMs > tomorrowMs)
+                effectiveEndMs = tomorrowMs;
+            const startSec = Math.floor(currentStartMs / 1000) - 1;
+            const endSec = Math.floor(effectiveEndMs / 1000);
+            const query = `after:${startSec} before:${endSec}`;
+            logger.info('Gmail window attempt', { attempt: attempts + 1, query });
+            const result = await this.gmailService.fetchMessagesOldestFirst(account, {
+                limit: batchSize,
+                query,
+            });
+            if (result.messages.length > 0) {
+                messages = result.messages;
+                hasMore = result.hasMore;
+                break; // Found emails, stop skipping
+            }
+            // No emails found in this week, move to next week
+            logger.info('No emails in 7-day window, skipping forward', { start: new Date(currentStartMs).toISOString() });
+            currentStartMs = effectiveEndMs;
+            attempts++;
+            if (eventLogger && attempts % 3 === 0) {
+                await eventLogger.info('Sync', `Scanning history... reached ${new Date(currentStartMs).toLocaleDateString()}`);
             }
         }
-        let query = '';
-        if (effectiveStartMs > 0) {
-            // Subtract 1 second to make query inclusive (Gmail's after: is exclusive)
-            // This ensures we don't miss emails at the exact checkpoint timestamp
-            const startSeconds = Math.floor(effectiveStartMs / 1000) - 1;
-            query = `after:${startSeconds}`;
+        if (eventLogger && messages.length > 0) {
+            await eventLogger.info('Fetching', `Fetched ${messages.length} emails in window${hasMore ? ', more available' : ''}`);
         }
-        if (eventLogger)
-            await eventLogger.info('Fetching', 'Fetching emails from Gmail (oldest first)', { query, batchSize });
-        // Use "Fetch IDs → Sort → Hydrate" strategy to get OLDEST emails first
-        // Gmail API always returns newest first, so we must fetch all IDs, sort, then hydrate
-        // This prevents skipping emails when using max_emails pagination
-        const { messages, hasMore } = await this.gmailService.fetchMessagesOldestFirst(account, {
-            limit: batchSize,
-            query: query || undefined,
-            maxIdsToFetch: 1000, // Safety limit for ID fetching
-        });
-        if (eventLogger) {
-            await eventLogger.info('Fetching', `Fetched ${messages.length} emails (oldest first)${hasMore ? ', more available' : ''}`);
-        }
-        // Messages are already sorted oldest-first by fetchMessagesOldestFirst
-        let maxInternalDate = account.last_sync_checkpoint ? parseInt(account.last_sync_checkpoint) : 0;
+        // Initialize max tracking with the point we reached
+        let maxInternalDate = currentStartMs;
         for (const message of messages) {
             try {
                 await this.processMessage(account, message, rules, settings, result, eventLogger);
-                // Checkpoint tracking: Use Gmail's internalDate for accurate checkpoint
-                // internalDate is when Gmail received the email, which matches what after: query uses
-                const msgInternalDate = message.internalDate ? parseInt(message.internalDate) : new Date(message.date).getTime();
+                // Track highest internalDate in memory
+                const msgInternalDate = parseInt(message.internalDate);
                 if (msgInternalDate > maxInternalDate) {
                     maxInternalDate = msgInternalDate;
-                    await this.supabase
-                        .from('email_accounts')
-                        .update({ last_sync_checkpoint: maxInternalDate.toString() })
-                        .eq('id', account.id);
                 }
             }
             catch (error) {
@@ -179,24 +208,47 @@ export class EmailProcessorService {
                 result.errors++;
             }
         }
+        // Update checkpoint once at the end of the batch if we made progress
+        if (maxInternalDate > effectiveStartMs) {
+            logger.info('Updating Gmail checkpoint', {
+                accountId: account.id,
+                oldCheckpoint: account.last_sync_checkpoint,
+                newCheckpoint: maxInternalDate.toString()
+            });
+            const { error: updateError } = await this.supabase
+                .from('email_accounts')
+                .update({ last_sync_checkpoint: maxInternalDate.toString() })
+                .eq('id', account.id);
+            if (updateError) {
+                logger.error('Failed to update Gmail checkpoint', updateError);
+            }
+        }
     }
     async processOutlookAccount(account, rules, settings, result, eventLogger) {
         const batchSize = account.sync_max_emails_per_run || config.processing.batchSize;
-        // Construct filter: Use checkpoint if it's newer than the user-defined start date
+        // Debug: Log account sync settings
+        logger.info('Outlook sync settings', {
+            accountId: account.id,
+            sync_start_date: account.sync_start_date,
+            last_sync_checkpoint: account.last_sync_checkpoint,
+            sync_max_emails_per_run: account.sync_max_emails_per_run,
+        });
+        // Construct filter: Use sync_start_date if present (Override), otherwise checkpoint
         let effectiveStartIso = '';
         if (account.sync_start_date) {
             effectiveStartIso = new Date(account.sync_start_date).toISOString();
+            logger.info('Using sync_start_date override', { effectiveStartIso });
         }
-        if (account.last_sync_checkpoint) {
-            if (!effectiveStartIso || account.last_sync_checkpoint > effectiveStartIso) {
-                effectiveStartIso = account.last_sync_checkpoint;
-            }
+        else if (account.last_sync_checkpoint) {
+            effectiveStartIso = account.last_sync_checkpoint;
+            logger.info('Using last_sync_checkpoint', { effectiveStartIso });
         }
         let filter = '';
         if (effectiveStartIso) {
             // Use 'ge' (>=) instead of 'gt' (>) to ensure we don't miss emails at exact checkpoint
             // The duplicate check in processMessage() will skip already-processed emails
             filter = `receivedDateTime ge ${effectiveStartIso}`;
+            logger.info('Final Outlook filter', { filter });
         }
         if (eventLogger)
             await eventLogger.info('Fetching', 'Fetching emails from Outlook (oldest first)', { filter, batchSize });
@@ -210,16 +262,12 @@ export class EmailProcessorService {
             await eventLogger.info('Fetching', `Fetched ${messages.length} emails (oldest first)${hasMore ? ', more available' : ''}`);
         }
         // Messages are already sorted oldest-first by the API
-        let latestCheckpoint = account.last_sync_checkpoint || '';
+        let latestCheckpoint = effectiveStartIso;
         for (const message of messages) {
             try {
-                await this.processMessage(account, message, rules, settings, result, eventLogger);
-                if (!latestCheckpoint || message.date > latestCheckpoint) {
-                    latestCheckpoint = message.date;
-                    await this.supabase
-                        .from('email_accounts')
-                        .update({ last_sync_checkpoint: latestCheckpoint })
-                        .eq('id', account.id);
+                const processResult = await this.processMessage(account, message, rules, settings, result, eventLogger);
+                if (processResult && (!latestCheckpoint || processResult.date > latestCheckpoint)) {
+                    latestCheckpoint = processResult.date;
                 }
             }
             catch (error) {
@@ -229,6 +277,27 @@ export class EmailProcessorService {
                 result.errors++;
             }
         }
+        // Update checkpoint once at the end of the batch if we made progress
+        if (latestCheckpoint && latestCheckpoint !== effectiveStartIso) {
+            logger.info('Updating Outlook checkpoint', {
+                accountId: account.id,
+                oldCheckpoint: account.last_sync_checkpoint,
+                newCheckpoint: latestCheckpoint
+            });
+            const { error: updateError } = await this.supabase
+                .from('email_accounts')
+                .update({ last_sync_checkpoint: latestCheckpoint })
+                .eq('id', account.id);
+            if (updateError) {
+                logger.error('Failed to update Outlook checkpoint', updateError);
+            }
+        }
+        else {
+            logger.info('Outlook checkpoint not updated (no newer emails found in this batch)', {
+                latestCheckpoint,
+                effectiveStartIso
+            });
+        }
     }
     async processMessage(account, message, rules, settings, result, eventLogger) {
         // Check if already processed
@@ -241,20 +310,60 @@ export class EmailProcessorService {
         if (existing) {
             logger.debug('Message already processed', { messageId: message.id });
             if (eventLogger)
-                await eventLogger.info('Skipped', `Already processed: ${message.subject}`);
+                await eventLogger.info('Skipped', `Already processed ID: ${message.id}`);
+            // Still need to return the date for checkpointing even if skipped
+            const rawMime = 'raw' in message
+                ? (account.provider === 'gmail'
+                    ? Buffer.from(message.raw, 'base64').toString('utf-8')
+                    : message.raw)
+                : '';
+            if (rawMime) {
+                const parsed = await simpleParser(rawMime);
+                return { date: parsed.date ? parsed.date.toISOString() : new Date().toISOString() };
+            }
             return;
         }
+        // Extract raw content string (Gmail is base64url, Outlook is raw text from $value)
+        const rawMime = 'raw' in message
+            ? (account.provider === 'gmail'
+                ? Buffer.from(message.raw, 'base64').toString('utf-8')
+                : message.raw)
+            : '';
+        if (!rawMime) {
+            throw new Error(`No raw MIME content found for message ${message.id}`);
+        }
+        // 1. Extract metadata from raw MIME using mailparser for the DB record
+        const parsed = await simpleParser(rawMime);
+        const subject = parsed.subject || 'No Subject';
+        const sender = parsed.from?.text || 'Unknown';
+        const recipient = parsed.to ? (Array.isArray(parsed.to) ? parsed.to[0].text : parsed.to.text) : '';
+        const date = parsed.date ? parsed.date.toISOString() : new Date().toISOString();
+        const bodySnippet = (parsed.text || parsed.textAsHtml || '').substring(0, 500);
         if (eventLogger)
-            await eventLogger.info('Processing', `Processing email: ${message.subject}`);
-        // 1. Create a "Skeleton" record to get an ID for tracing
+            await eventLogger.info('Ingesting', `Ingesting email: ${subject}`);
+        // 2. Save raw content to local storage (.eml format)
+        let filePath = '';
+        try {
+            const filename = `${account.id}_${message.id}.eml`.replace(/[^a-z0-9._-]/gi, '_');
+            filePath = await this.storageService.saveEmail(rawMime, filename, settings?.storage_path);
+        }
+        catch (storageError) {
+            logger.error('Failed to save raw email content', storageError);
+            if (eventLogger)
+                await eventLogger.error('Storage Error', storageError);
+            throw storageError;
+        }
+        // 3. Create a "Skeleton" record with 'pending' status
         const emailData = {
             account_id: account.id,
             external_id: message.id,
-            subject: message.subject,
-            sender: message.sender,
-            recipient: message.recipient,
-            date: message.date ? new Date(message.date).toISOString() : null,
-            body_snippet: message.snippet || message.body.substring(0, 500),
+            subject,
+            sender,
+            recipient,
+            date,
+            body_snippet: bodySnippet,
+            file_path: filePath,
+            processing_status: 'pending',
         };
         const { data: savedEmail, error: saveError } = await this.supabase
             .from('emails')
@@ -265,50 +374,173 @@ export class EmailProcessorService {
             logger.error('Failed to create initial email record', saveError);
             if (eventLogger)
                 await eventLogger.error('Database Error', saveError);
+            return { date };
+        }
+        // Log successful ingestion linked to email ID
+        if (eventLogger)
+            await eventLogger.info('Ingested', `Successfully ingested email: ${subject}`, { filePath }, savedEmail.id);
+        result.processed++;
+        return { date };
+    }
+    /**
+     * Background Worker: Processes pending emails for a user recursively until empty.
+     */
+    async processQueue(userId, settings) {
+        logger.info('Worker: Checking queue', { userId });
+        // Fetch up to 5 pending emails for this user
+        const { data: pendingEmails, error } = await this.supabase
+            .from('emails')
+            .select('*, email_accounts!inner(id, user_id, provider)')
+            .eq('email_accounts.user_id', userId)
+            .eq('processing_status', 'pending')
+            .limit(5);
+        if (error) {
+            logger.error('Worker: Failed to fetch queue', error);
             return;
         }
-        // 2. Analyze with AI (passing the ID so events are linked)
-        const intelligenceService = getIntelligenceService(settings?.llm_model || settings?.llm_base_url || settings?.llm_api_key
-            ? {
-                model: settings.llm_model,
-                baseUrl: settings.llm_base_url,
-                apiKey: settings.llm_api_key,
-            }
-            : undefined);
-        const analysis = await intelligenceService.analyzeEmail(message.body, {
-            subject: message.subject,
-            sender: message.sender,
-            date: message.date,
-            metadata: message.headers,
-            userPreferences: {
-                autoTrashSpam: settings?.auto_trash_spam,
-                smartDrafts: settings?.smart_drafts,
-            },
-        }, eventLogger || undefined, savedEmail.id);
-        if (!analysis) {
-            result.errors++;
+        if (!pendingEmails || pendingEmails.length === 0) {
+            logger.info('Worker: Queue empty', { userId });
             return;
         }
-        // 3. Update the email record with results
-        await this.supabase
-            .from('emails')
-            .update({
-            category: analysis.category,
-            is_useless: analysis.is_useless,
-            ai_analysis: analysis,
-            suggested_actions: analysis.suggested_actions || [],
-            suggested_action: analysis.suggested_actions?.[0] || 'none',
+        logger.info('Worker: Processing batch', { userId, count: pendingEmails.length });
+        for (const email of pendingEmails) {
+            await this.processPendingEmail(email, userId, settings);
+        }
+        // Slight delay to prevent hitting rate limits too fast, then check again
+        await new Promise(resolve => setTimeout(resolve, 1000));
+        return this.processQueue(userId, settings);
+    }
+    async processPendingEmail(email, userId, settings) {
+        // Create a real processing log entry for this background task to ensure RLS compliance
+        const { data: log } = await this.supabase
+            .from('processing_logs')
+            .insert({
+            user_id: userId,
+            account_id: email.account_id,
+            status: 'running',
         })
-            .eq('id', savedEmail.id);
-        const processedEmail = {
-            ...savedEmail,
-            category: analysis.category,
-            is_useless: analysis.is_useless,
-            suggested_actions: analysis.suggested_actions
-        };
-        result.processed++;
-        // 4. Execute automation rules
-        await this.executeRules(account, processedEmail, analysis, rules, settings, result, eventLogger);
+            .select()
+            .single();
+        const eventLogger = log ? new EventLogger(this.supabase, log.id) : null;
+        try {
+            // 1. Double-check status and mark as processing (Atomic-ish)
+            const { data: current } = await this.supabase
+                .from('emails')
+                .select('processing_status')
+                .eq('id', email.id)
+                .single();
+            if (current?.processing_status !== 'pending') {
+                if (log)
+                    await this.supabase.from('processing_logs').delete().eq('id', log.id);
+                return;
+            }
+            await this.supabase
+                .from('emails')
+                .update({ processing_status: 'processing' })
+                .eq('id', email.id);
+            if (eventLogger)
+                await eventLogger.info('Processing', `Background processing: ${email.subject}`, undefined, email.id);
+            // 2. Read content from disk and parse with mailparser
+            if (!email.file_path)
+                throw new Error('No file path found for email');
+            const rawMime = await this.storageService.readEmail(email.file_path);
+            const parsed = await simpleParser(rawMime);
+            // Extract clean content (prioritize text)
+            const cleanContent = parsed.text || parsed.textAsHtml || '';
+            // Extract metadata signals from headers
+            const metadata = {
+                importance: parsed.headers.get('importance')?.toString() || parsed.headers.get('x-priority')?.toString(),
+                listUnsubscribe: parsed.headers.get('list-unsubscribe')?.toString(),
+                autoSubmitted: parsed.headers.get('auto-submitted')?.toString(),
+                mailer: parsed.headers.get('x-mailer')?.toString()
+            };
+            // 3. Analyze with AI
+            const intelligenceService = getIntelligenceService(settings?.llm_model || settings?.llm_base_url || settings?.llm_api_key
+                ? {
+                    model: settings.llm_model,
+                    baseUrl: settings.llm_base_url,
+                    apiKey: settings.llm_api_key,
+                }
+                : undefined);
+            const analysis = await intelligenceService.analyzeEmail(cleanContent, {
+                subject: email.subject || '',
+                sender: email.sender || '',
+                date: email.date || '',
+                metadata,
+                userPreferences: {
+                    autoTrashSpam: settings?.auto_trash_spam,
+                    smartDrafts: settings?.smart_drafts,
+                },
+            }, eventLogger || undefined, email.id);
+            if (!analysis) {
+                throw new Error('AI analysis returned no result');
+            }
+            // 4. Update the email record with results
+            await this.supabase
+                .from('emails')
+                .update({
+                category: analysis.category,
+                is_useless: analysis.is_useless,
+                ai_analysis: analysis,
+                suggested_actions: analysis.suggested_actions || [],
+                suggested_action: analysis.suggested_actions?.[0] || 'none',
+                processing_status: 'completed'
+            })
+                .eq('id', email.id);
+            // 5. Execute automation rules
+            // Fetch account and rules needed for execution
+            const { data: account } = await this.supabase
+                .from('email_accounts')
+                .select('*')
+                .eq('id', email.account_id)
+                .single();
+            const { data: rules } = await this.supabase
+                .from('rules')
+                .select('*')
+                .eq('user_id', userId)
+                .eq('is_enabled', true);
+            if (account && rules) {
+                const tempResult = { processed: 0, deleted: 0, drafted: 0, errors: 0 };
+                // Ensure email object for rules has the analysis fields merged in
+                const emailForRules = { ...email, ...analysis };
+                await this.executeRules(account, emailForRules, analysis, rules, settings, tempResult, eventLogger);
+            }
+            // Mark log as success
+            if (log) {
+                await this.supabase
+                    .from('processing_logs')
+                    .update({
+                    status: 'success',
+                    completed_at: new Date().toISOString(),
+                    emails_processed: 1
+                })
+                    .eq('id', log.id);
+            }
+        }
+        catch (error) {
+            logger.error('Failed to process pending email', error, { emailId: email.id });
+            if (eventLogger)
+                await eventLogger.error('Processing Failed', error, email.id);
+            // Mark log as failed
+            if (log) {
+                await this.supabase
+                    .from('processing_logs')
+                    .update({
+                    status: 'failed',
+                    completed_at: new Date().toISOString(),
+                    error_message: error instanceof Error ? error.message : String(error)
+                })
+                    .eq('id', log.id);
+            }
+            await this.supabase
+                .from('emails')
+                .update({
+                processing_status: 'failed',
+                processing_error: error instanceof Error ? error.message : String(error),
+                retry_count: (email.retry_count || 0) + 1
+            })
+                .eq('id', email.id);
+        }
     }
     async executeRules(account, email, analysis, rules, settings, result, eventLogger) {
         // User-defined and System rules (Unified)
@@ -408,7 +640,8 @@ export class EmailProcessorService {
                 case 'suggested_actions':
                     // Handle array membership check (e.g. if condition expects "reply" to be in actions)
                     const requiredActions = Array.isArray(value) ? value : [value];
-                    const hasAllActions = requiredActions.every(req => analysis.suggested_actions?.includes(req));
+                    const actualActions = analysis.suggested_actions || [];
+                    const hasAllActions = requiredActions.every(req => actualActions.includes(req));
                     if (!hasAllActions)
                         return false;
                     break;
@@ -470,6 +703,9 @@ export class EmailProcessorService {
             if (account.provider === 'gmail') {
                 if (action === 'delete') {
                     await this.gmailService.trashMessage(account, email.external_id);
+                    if (email.file_path) {
+                        await this.storageService.deleteEmail(email.file_path);
+                    }
                 }
                 else if (action === 'archive') {
                     await this.gmailService.archiveMessage(account, email.external_id);
@@ -490,6 +726,9 @@ export class EmailProcessorService {
             else if (account.provider === 'outlook') {
                 if (action === 'delete') {
                     await this.microsoftService.trashMessage(account, email.external_id);
+                    if (email.file_path) {
+                        await this.storageService.deleteEmail(email.file_path);
+                    }
                 }
                 else if (action === 'archive') {
                     await this.microsoftService.archiveMessage(account, email.external_id);

package/dist/api/src/services/storage.js

@@ -0,0 +1,81 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { createLogger } from '../utils/logger.js';
+const logger = createLogger('StorageService');
+export class StorageService {
+    defaultPath;
+    constructor() {
+        // Default to a folder in the user's home directory or current project
+        // Using project-relative path for now as discussed
+        this.defaultPath = path.resolve(process.cwd(), 'data', 'emails');
+    }
+    /**
+     * Ensures the storage directory exists and is writable.
+     */
+    async ensureDirectory(customPath) {
+        const targetPath = customPath || this.defaultPath;
+        try {
+            await fs.mkdir(targetPath, { recursive: true });
+            // Test writability
+            const testFile = path.join(targetPath, '.write_test');
+            await fs.writeFile(testFile, 'ok');
+            await fs.unlink(testFile);
+            return targetPath;
+        }
+        catch (error) {
+            logger.error('Storage directory validation failed', error, { targetPath });
+            throw new Error(`Storage path "${targetPath}" is not accessible or writable.`);
+        }
+    }
+    /**
+     * Saves raw email content to disk.
+     * Returns the absolute path to the saved file.
+     */
+    async saveEmail(content, filename, customPath) {
+        const baseDir = await this.ensureDirectory(customPath);
+        const filePath = path.join(baseDir, filename);
+        try {
+            await fs.writeFile(filePath, content, 'utf8');
+            logger.debug('Email saved to disk', { filePath });
+            return filePath;
+        }
+        catch (error) {
+            logger.error('Failed to save email to disk', error, { filePath });
+            throw error;
+        }
+    }
+    /**
+     * Reads email content from disk.
+     */
+    async readEmail(filePath) {
+        try {
+            return await fs.readFile(filePath, 'utf8');
+        }
+        catch (error) {
+            logger.error('Failed to read email from disk', error, { filePath });
+            throw error;
+        }
+    }
+    /**
+     * Deletes email from disk.
+     */
+    async deleteEmail(filePath) {
+        try {
+            await fs.unlink(filePath);
+            logger.debug('Email deleted from disk', { filePath });
+        }
+        catch (error) {
+            // If file doesn't exist, we don't care much
+            if (error.code !== 'ENOENT') {
+                logger.warn('Failed to delete email from disk', { error, filePath });
+            }
+        }
+    }
+}
+let storageService = null;
+export function getStorageService() {
+    if (!storageService) {
+        storageService = new StorageService();
+    }
+    return storageService;
+}