@n24q02m/better-email-mcp 1.0.0

package/build/src/tools/helpers/errors.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Error Handling Utilities
+ * AI-friendly error messages and suggestions for email operations
+ */
+export declare class EmailMCPError extends Error {
+    code: string;
+    suggestion?: string | undefined;
+    details?: any | undefined;
+    constructor(message: string, code: string, suggestion?: string | undefined, details?: any | undefined);
+    toJSON(): {
+        error: string;
+        code: string;
+        message: string;
+        suggestion: string | undefined;
+        details: any;
+    };
+}
+/**
+ * Enhance email-related errors with helpful context
+ */
+export declare function enhanceError(error: any): EmailMCPError;
+/**
+ * Create AI-readable error message
+ */
+export declare function aiReadableMessage(error: EmailMCPError): string;
+/**
+ * Suggest fixes based on error
+ */
+export declare function suggestFixes(error: EmailMCPError): string[];
+/**
+ * Wrap async function with error handling
+ */
+export declare function withErrorHandling<T extends (...args: any[]) => Promise<any>>(fn: T): (...args: Parameters<T>) => Promise<ReturnType<T>>;
+//# sourceMappingURL=errors.d.ts.map

package/build/src/tools/helpers/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../../src/tools/helpers/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,qBAAa,aAAc,SAAQ,KAAK;IAG7B,IAAI,EAAE,MAAM;IACZ,UAAU,CAAC,EAAE,MAAM;IACnB,OAAO,CAAC,EAAE,GAAG;gBAHpB,OAAO,EAAE,MAAM,EACR,IAAI,EAAE,MAAM,EACZ,UAAU,CAAC,EAAE,MAAM,YAAA,EACnB,OAAO,CAAC,EAAE,GAAG,YAAA;IAMtB,MAAM;;;;;;;CASP;AAoBD;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,GAAG,GAAG,aAAa,CAgEtD;AAyCD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAY9D;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,EAAE,CAqC3D;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,EAC1E,EAAE,EAAE,CAAC,GACJ,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAQpD"}

package/build/src/tools/helpers/errors.js

@@ -0,0 +1,152 @@
+/**
+ * Error Handling Utilities
+ * AI-friendly error messages and suggestions for email operations
+ */
+export class EmailMCPError extends Error {
+    constructor(message, code, suggestion, details) {
+        super(message);
+        this.code = code;
+        this.suggestion = suggestion;
+        this.details = details;
+        this.name = 'EmailMCPError';
+    }
+    toJSON() {
+        return {
+            error: this.name,
+            code: this.code,
+            message: this.message,
+            suggestion: this.suggestion,
+            details: this.details
+        };
+    }
+}
+/**
+ * Sanitize error object to remove sensitive information (passwords, tokens)
+ */
+function sanitizeErrorDetails(error) {
+    if (!error || typeof error !== 'object')
+        return error;
+    const safe = {
+        message: error.message,
+        name: error.name,
+        code: error.code
+    };
+    if (error.status)
+        safe.status = error.status;
+    if (error.responseCode)
+        safe.responseCode = error.responseCode;
+    return safe;
+}
+/**
+ * Enhance email-related errors with helpful context
+ */
+export function enhanceError(error) {
+    const message = error.message || 'Unknown error occurred';
+    // IMAP authentication errors
+    if (message.includes('Invalid credentials') ||
+        message.includes('AUTHENTICATIONFAILED') ||
+        error.authenticationFailed) {
+        return new EmailMCPError('Email authentication failed', 'AUTH_FAILED', 'Check that your email and App Password are correct. For Gmail: enable 2FA then create an App Password at https://myaccount.google.com/apppasswords. For Outlook: enable 2FA then create an App Password in security settings.');
+    }
+    // Connection errors
+    if (message.includes('ECONNREFUSED') || message.includes('ENOTFOUND') || message.includes('ETIMEDOUT')) {
+        return new EmailMCPError('Cannot connect to email server', 'CONNECTION_ERROR', 'Check your internet connection and verify the email server address is correct.');
+    }
+    // TLS/SSL errors
+    if (message.includes('CERT') || message.includes('SSL') || message.includes('TLS')) {
+        return new EmailMCPError('TLS/SSL connection error', 'TLS_ERROR', 'The email server certificate could not be verified. Check the server address and port.');
+    }
+    // IMAP mailbox errors
+    if (message.includes('Mailbox not found') || message.includes('NO [NONEXISTENT]')) {
+        return new EmailMCPError('Mailbox/folder not found', 'FOLDER_NOT_FOUND', 'Check the folder name. Use the folders tool to list available folders.');
+    }
+    // SMTP errors
+    if (error.responseCode) {
+        return handleSmtpError(error);
+    }
+    // Configuration errors
+    if (message.includes('EMAIL_CREDENTIALS')) {
+        return new EmailMCPError('EMAIL_CREDENTIALS environment variable is required', 'CONFIG_ERROR', 'Set EMAIL_CREDENTIALS in format: email1:password1,email2:password2');
+    }
+    // Generic error
+    return new EmailMCPError(message, 'UNKNOWN_ERROR', 'Please check your request and try again', sanitizeErrorDetails(error));
+}
+/**
+ * Handle SMTP-specific errors
+ */
+function handleSmtpError(error) {
+    const code = error.responseCode;
+    switch (code) {
+        case 535:
+            return new EmailMCPError('SMTP authentication failed', 'SMTP_AUTH_FAILED', 'Check your email and App Password for the sending account.');
+        case 550:
+            return new EmailMCPError('Recipient address rejected', 'RECIPIENT_REJECTED', 'Check the recipient email address is correct and exists.');
+        case 552:
+        case 554:
+            return new EmailMCPError('Message rejected by server', 'MESSAGE_REJECTED', 'The email was rejected. It may be too large or flagged as spam.');
+        default:
+            return new EmailMCPError(error.message || `SMTP error ${code}`, `SMTP_${code}`, 'Check the SMTP error code and try again.', sanitizeErrorDetails(error));
+    }
+}
+/**
+ * Create AI-readable error message
+ */
+export function aiReadableMessage(error) {
+    let message = `Error: ${error.message}`;
+    if (error.suggestion) {
+        message += `\n\nSuggestion: ${error.suggestion}`;
+    }
+    if (error.details) {
+        message += `\n\nDetails: ${JSON.stringify(error.details, null, 2)}`;
+    }
+    return message;
+}
+/**
+ * Suggest fixes based on error
+ */
+export function suggestFixes(error) {
+    const suggestions = [];
+    switch (error.code) {
+        case 'AUTH_FAILED':
+        case 'SMTP_AUTH_FAILED':
+            suggestions.push('Verify your App Password is correct (not your regular password)');
+            suggestions.push('For Gmail: https://myaccount.google.com/apppasswords');
+            suggestions.push('For Outlook: Security settings → App passwords');
+            suggestions.push('Ensure 2-Factor Authentication is enabled on your account');
+            break;
+        case 'CONNECTION_ERROR':
+            suggestions.push('Check your internet connection');
+            suggestions.push('Verify the email server address');
+            suggestions.push('Check if a firewall is blocking the connection');
+            break;
+        case 'FOLDER_NOT_FOUND':
+            suggestions.push('Use the folders tool to list available folders');
+            suggestions.push('Folder names are case-sensitive');
+            suggestions.push('Gmail uses labels (e.g. [Gmail]/All Mail) instead of traditional folders');
+            break;
+        case 'CONFIG_ERROR':
+            suggestions.push('Set EMAIL_CREDENTIALS environment variable');
+            suggestions.push('Format: email1:password1,email2:password2');
+            suggestions.push('Passwords with colons can use format: email:password:imap_host');
+            break;
+        default:
+            suggestions.push('Check the error message for details');
+            suggestions.push('Try again in a few moments');
+            suggestions.push('Verify your email account settings');
+    }
+    return suggestions;
+}
+/**
+ * Wrap async function with error handling
+ */
+export function withErrorHandling(fn) {
+    return async (...args) => {
+        try {
+            return await fn(...args);
+        }
+        catch (error) {
+            throw enhanceError(error);
+        }
+    };
+}
+//# sourceMappingURL=errors.js.map

package/build/src/tools/helpers/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../../src/tools/helpers/errors.ts"],"names":[],"mappings":"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"}

package/build/src/tools/helpers/errors.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=errors.test.d.ts.map

package/build/src/tools/helpers/errors.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.test.d.ts","sourceRoot":"","sources":["../../../../src/tools/helpers/errors.test.ts"],"names":[],"mappings":""}

package/build/src/tools/helpers/errors.test.js

@@ -0,0 +1,203 @@
+import { describe, expect, it } from 'vitest';
+import { aiReadableMessage, EmailMCPError, enhanceError, suggestFixes, withErrorHandling } from './errors.js';
+describe('EmailMCPError', () => {
+    it('creates error with message and code', () => {
+        const error = new EmailMCPError('test error', 'TEST_CODE');
+        expect(error.message).toBe('test error');
+        expect(error.code).toBe('TEST_CODE');
+        expect(error.name).toBe('EmailMCPError');
+        expect(error.suggestion).toBeUndefined();
+        expect(error.details).toBeUndefined();
+    });
+    it('creates error with suggestion and details', () => {
+        const error = new EmailMCPError('test', 'CODE', 'try this', { key: 'value' });
+        expect(error.suggestion).toBe('try this');
+        expect(error.details).toEqual({ key: 'value' });
+    });
+    it('serializes to JSON correctly', () => {
+        const error = new EmailMCPError('msg', 'CODE', 'hint', { x: 1 });
+        const json = error.toJSON();
+        expect(json).toEqual({
+            error: 'EmailMCPError',
+            code: 'CODE',
+            message: 'msg',
+            suggestion: 'hint',
+            details: { x: 1 }
+        });
+    });
+    it('is an instance of Error', () => {
+        const error = new EmailMCPError('test', 'CODE');
+        expect(error).toBeInstanceOf(Error);
+        expect(error).toBeInstanceOf(EmailMCPError);
+    });
+});
+describe('enhanceError', () => {
+    it('handles IMAP auth errors', () => {
+        const result = enhanceError({ message: 'AUTHENTICATIONFAILED' });
+        expect(result.code).toBe('AUTH_FAILED');
+        expect(result.suggestion).toContain('App Password');
+    });
+    it('handles Invalid credentials', () => {
+        const result = enhanceError({ message: 'Invalid credentials' });
+        expect(result.code).toBe('AUTH_FAILED');
+    });
+    it('handles authenticationFailed flag', () => {
+        const result = enhanceError({ message: 'some error', authenticationFailed: true });
+        expect(result.code).toBe('AUTH_FAILED');
+    });
+    it('handles connection refused', () => {
+        const result = enhanceError({ message: 'ECONNREFUSED' });
+        expect(result.code).toBe('CONNECTION_ERROR');
+    });
+    it('handles DNS not found', () => {
+        const result = enhanceError({ message: 'ENOTFOUND' });
+        expect(result.code).toBe('CONNECTION_ERROR');
+    });
+    it('handles timeout', () => {
+        const result = enhanceError({ message: 'ETIMEDOUT' });
+        expect(result.code).toBe('CONNECTION_ERROR');
+    });
+    it('handles TLS errors', () => {
+        const result = enhanceError({ message: 'SSL handshake failed' });
+        expect(result.code).toBe('TLS_ERROR');
+    });
+    it('handles CERT errors', () => {
+        const result = enhanceError({ message: 'CERT_HAS_EXPIRED' });
+        expect(result.code).toBe('TLS_ERROR');
+    });
+    it('handles mailbox not found', () => {
+        const result = enhanceError({ message: 'Mailbox not found' });
+        expect(result.code).toBe('FOLDER_NOT_FOUND');
+    });
+    it('handles IMAP NONEXISTENT', () => {
+        const result = enhanceError({ message: 'NO [NONEXISTENT] folder' });
+        expect(result.code).toBe('FOLDER_NOT_FOUND');
+    });
+    it('handles SMTP 535 auth error', () => {
+        const result = enhanceError({ message: 'auth failed', responseCode: 535 });
+        expect(result.code).toBe('SMTP_AUTH_FAILED');
+    });
+    it('handles SMTP 550 recipient rejected', () => {
+        const result = enhanceError({ message: 'rejected', responseCode: 550 });
+        expect(result.code).toBe('RECIPIENT_REJECTED');
+    });
+    it('handles SMTP 552 message rejected', () => {
+        const result = enhanceError({ message: 'too large', responseCode: 552 });
+        expect(result.code).toBe('MESSAGE_REJECTED');
+    });
+    it('handles SMTP 554 message rejected', () => {
+        const result = enhanceError({ message: 'spam', responseCode: 554 });
+        expect(result.code).toBe('MESSAGE_REJECTED');
+    });
+    it('handles unknown SMTP error codes', () => {
+        const result = enhanceError({ message: 'unknown', responseCode: 421 });
+        expect(result.code).toBe('SMTP_421');
+    });
+    it('handles EMAIL_CREDENTIALS config error', () => {
+        const result = enhanceError({ message: 'EMAIL_CREDENTIALS is missing' });
+        expect(result.code).toBe('CONFIG_ERROR');
+    });
+    it('handles generic unknown errors', () => {
+        const result = enhanceError({ message: 'something weird happened' });
+        expect(result.code).toBe('UNKNOWN_ERROR');
+    });
+    it('handles errors with no message', () => {
+        const result = enhanceError({});
+        expect(result.code).toBe('UNKNOWN_ERROR');
+        expect(result.message).toBe('Unknown error occurred');
+    });
+    it('sanitizes error details (no password leakage)', () => {
+        const result = enhanceError({ message: 'generic', password: 'secret123', status: 500 });
+        // details should not contain password
+        if (result.details) {
+            expect(result.details.password).toBeUndefined();
+            expect(result.details.status).toBe(500);
+        }
+    });
+});
+describe('aiReadableMessage', () => {
+    it('formats error without suggestion or details', () => {
+        const error = new EmailMCPError('test error', 'CODE');
+        const msg = aiReadableMessage(error);
+        expect(msg).toBe('Error: test error');
+    });
+    it('includes suggestion when present', () => {
+        const error = new EmailMCPError('test', 'CODE', 'try this');
+        const msg = aiReadableMessage(error);
+        expect(msg).toContain('Suggestion: try this');
+    });
+    it('includes details when present', () => {
+        const error = new EmailMCPError('test', 'CODE', undefined, { key: 'val' });
+        const msg = aiReadableMessage(error);
+        expect(msg).toContain('Details:');
+        expect(msg).toContain('"key": "val"');
+    });
+    it('includes both suggestion and details', () => {
+        const error = new EmailMCPError('test', 'CODE', 'hint', { x: 1 });
+        const msg = aiReadableMessage(error);
+        expect(msg).toContain('Error: test');
+        expect(msg).toContain('Suggestion: hint');
+        expect(msg).toContain('Details:');
+    });
+});
+describe('suggestFixes', () => {
+    it('returns auth suggestions for AUTH_FAILED', () => {
+        const error = new EmailMCPError('auth', 'AUTH_FAILED');
+        const fixes = suggestFixes(error);
+        expect(fixes.length).toBeGreaterThan(0);
+        expect(fixes.some((f) => f.includes('App Password'))).toBe(true);
+    });
+    it('returns auth suggestions for SMTP_AUTH_FAILED', () => {
+        const error = new EmailMCPError('smtp auth', 'SMTP_AUTH_FAILED');
+        const fixes = suggestFixes(error);
+        expect(fixes.some((f) => f.includes('App Password'))).toBe(true);
+    });
+    it('returns connection suggestions for CONNECTION_ERROR', () => {
+        const error = new EmailMCPError('conn', 'CONNECTION_ERROR');
+        const fixes = suggestFixes(error);
+        expect(fixes.some((f) => f.includes('internet'))).toBe(true);
+    });
+    it('returns folder suggestions for FOLDER_NOT_FOUND', () => {
+        const error = new EmailMCPError('folder', 'FOLDER_NOT_FOUND');
+        const fixes = suggestFixes(error);
+        expect(fixes.some((f) => f.includes('folders tool'))).toBe(true);
+    });
+    it('returns config suggestions for CONFIG_ERROR', () => {
+        const error = new EmailMCPError('config', 'CONFIG_ERROR');
+        const fixes = suggestFixes(error);
+        expect(fixes.some((f) => f.includes('EMAIL_CREDENTIALS'))).toBe(true);
+    });
+    it('returns generic suggestions for unknown codes', () => {
+        const error = new EmailMCPError('unknown', 'RANDOM_CODE');
+        const fixes = suggestFixes(error);
+        expect(fixes.length).toBeGreaterThan(0);
+    });
+});
+describe('withErrorHandling', () => {
+    it('passes through successful results', async () => {
+        const fn = async () => 'success';
+        const wrapped = withErrorHandling(fn);
+        const result = await wrapped();
+        expect(result).toBe('success');
+    });
+    it('enhances thrown errors', async () => {
+        const fn = async () => {
+            throw new Error('AUTHENTICATIONFAILED');
+        };
+        const wrapped = withErrorHandling(fn);
+        await expect(wrapped()).rejects.toThrow(EmailMCPError);
+        try {
+            await wrapped();
+        }
+        catch (e) {
+            expect(e.code).toBe('AUTH_FAILED');
+        }
+    });
+    it('passes arguments through', async () => {
+        const fn = async (a, b) => a + b;
+        const wrapped = withErrorHandling(fn);
+        const result = await wrapped(2, 3);
+        expect(result).toBe(5);
+    });
+});
+//# sourceMappingURL=errors.test.js.map

package/build/src/tools/helpers/errors.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.test.js","sourceRoot":"","sources":["../../../../src/tools/helpers/errors.test.ts"],"names":[],"mappings":"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"}

package/build/src/tools/helpers/html-utils.d.ts

@@ -0,0 +1,10 @@
+/**
+ * HTML to Clean Text Utilities
+ * Strips HTML tags, CSS, scripts and returns clean text for LLM consumption
+ */
+/**
+ * Convert HTML email body to clean plain text
+ * Removes CSS, scripts, images, and formatting noise to save LLM tokens
+ */
+export declare function htmlToCleanText(html: string): string;
+//# sourceMappingURL=html-utils.d.ts.map

package/build/src/tools/helpers/html-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"html-utils.d.ts","sourceRoot":"","sources":["../../../../src/tools/helpers/html-utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAkBpD"}

package/build/src/tools/helpers/html-utils.js

@@ -0,0 +1,29 @@
+/**
+ * HTML to Clean Text Utilities
+ * Strips HTML tags, CSS, scripts and returns clean text for LLM consumption
+ */
+import { convert } from 'html-to-text';
+/**
+ * Convert HTML email body to clean plain text
+ * Removes CSS, scripts, images, and formatting noise to save LLM tokens
+ */
+export function htmlToCleanText(html) {
+    if (!html)
+        return '';
+    return convert(html, {
+        wordwrap: false,
+        preserveNewlines: true,
+        selectors: [
+            // Remove style and script tags entirely
+            { selector: 'style', format: 'skip' },
+            { selector: 'script', format: 'skip' },
+            // Remove images (just show alt text if any)
+            { selector: 'img', format: 'skip' },
+            // Keep links as text
+            { selector: 'a', options: { hideLinkHrefIfSameAsText: true, ignoreHref: false } },
+            // Tables as readable text
+            { selector: 'table', format: 'dataTable' }
+        ]
+    }).trim();
+}
+//# sourceMappingURL=html-utils.js.map

package/build/src/tools/helpers/html-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"html-utils.js","sourceRoot":"","sources":["../../../../src/tools/helpers/html-utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAEtC;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,IAAI,CAAC,IAAI;QAAE,OAAO,EAAE,CAAA;IAEpB,OAAO,OAAO,CAAC,IAAI,EAAE;QACnB,QAAQ,EAAE,KAAK;QACf,gBAAgB,EAAE,IAAI;QACtB,SAAS,EAAE;YACT,wCAAwC;YACxC,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE;YACrC,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE;YACtC,4CAA4C;YAC5C,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE;YACnC,qBAAqB;YACrB,EAAE,QAAQ,EAAE,GAAG,EAAE,OAAO,EAAE,EAAE,wBAAwB,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,EAAE;YACjF,0BAA0B;YAC1B,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE;SAC3C;KACF,CAAC,CAAC,IAAI,EAAE,CAAA;AACX,CAAC"}

package/build/src/tools/helpers/html-utils.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=html-utils.test.d.ts.map

package/build/src/tools/helpers/html-utils.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"html-utils.test.d.ts","sourceRoot":"","sources":["../../../../src/tools/helpers/html-utils.test.ts"],"names":[],"mappings":""}

package/build/src/tools/helpers/html-utils.test.js

@@ -0,0 +1,103 @@
+import { describe, expect, it } from 'vitest';
+import { htmlToCleanText } from './html-utils.js';
+describe('htmlToCleanText', () => {
+    it('returns empty string for empty input', () => {
+        expect(htmlToCleanText('')).toBe('');
+    });
+    it('returns empty string for null-like input', () => {
+        expect(htmlToCleanText(null)).toBe('');
+        expect(htmlToCleanText(undefined)).toBe('');
+    });
+    it('strips HTML tags', () => {
+        const result = htmlToCleanText('<p>Hello <b>World</b></p>');
+        expect(result).toContain('Hello');
+        expect(result).toContain('World');
+        expect(result).not.toContain('<p>');
+        expect(result).not.toContain('<b>');
+    });
+    it('removes style tags', () => {
+        const result = htmlToCleanText('<style>.red { color: red; }</style><p>Content</p>');
+        expect(result).not.toContain('color');
+        expect(result).toContain('Content');
+    });
+    it('removes script tags', () => {
+        const result = htmlToCleanText('<script>alert("xss")</script><p>Safe</p>');
+        expect(result).not.toContain('alert');
+        expect(result).not.toContain('xss');
+        expect(result).toContain('Safe');
+    });
+    it('removes img tags', () => {
+        const result = htmlToCleanText('<p>Before</p><img src="test.png" alt="test"><p>After</p>');
+        expect(result).not.toContain('test.png');
+        expect(result).toContain('Before');
+        expect(result).toContain('After');
+    });
+    it('preserves link text', () => {
+        const result = htmlToCleanText('<a href="https://example.com">Click here</a>');
+        expect(result).toContain('Click here');
+    });
+    it('handles links with href', () => {
+        const result = htmlToCleanText('<a href="https://example.com">Visit</a>');
+        expect(result).toContain('Visit');
+        expect(result).toContain('https://example.com');
+    });
+    it('hides href when same as text', () => {
+        const result = htmlToCleanText('<a href="https://example.com">https://example.com</a>');
+        // Should not duplicate the URL
+        const count = (result.match(/https:\/\/example\.com/g) || []).length;
+        expect(count).toBe(1);
+    });
+    it('handles nested HTML', () => {
+        const html = '<div><h1>Title</h1><p>Paragraph with <strong>bold</strong> text.</p></div>';
+        const result = htmlToCleanText(html);
+        // html-to-text uppercases headings
+        expect(result.toUpperCase()).toContain('TITLE');
+        expect(result).toContain('bold');
+        expect(result).toContain('text');
+    });
+    it('preserves newlines', () => {
+        const result = htmlToCleanText('<p>Line 1</p><p>Line 2</p>');
+        expect(result).toContain('Line 1');
+        expect(result).toContain('Line 2');
+    });
+    it('handles tables', () => {
+        const html = '<table><tr><th>Name</th><th>Value</th></tr><tr><td>A</td><td>1</td></tr></table>';
+        const result = htmlToCleanText(html);
+        // html-to-text uppercases table headers
+        expect(result.toUpperCase()).toContain('NAME');
+        expect(result.toUpperCase()).toContain('VALUE');
+        expect(result).toContain('A');
+        expect(result).toContain('1');
+    });
+    it('trims output', () => {
+        const result = htmlToCleanText('  <p>  Content  </p>  ');
+        expect(result).not.toMatch(/^\s/);
+        expect(result).not.toMatch(/\s$/);
+    });
+    it('handles complex email HTML', () => {
+        const html = `
+      <html>
+        <head><style>body { font-family: Arial; }</style></head>
+        <body>
+          <div style="max-width: 600px;">
+            <h1>Newsletter</h1>
+            <p>Hello <strong>User</strong>,</p>
+            <p>Check out our <a href="https://example.com/deals">latest deals</a>.</p>
+            <img src="banner.jpg" alt="Banner">
+            <script>tracking()</script>
+          </div>
+        </body>
+      </html>
+    `;
+        const result = htmlToCleanText(html);
+        // html-to-text uppercases headings
+        expect(result.toUpperCase()).toContain('NEWSLETTER');
+        expect(result).toContain('Hello');
+        expect(result).toContain('User');
+        expect(result).toContain('latest deals');
+        expect(result).not.toContain('font-family');
+        expect(result).not.toContain('tracking');
+        expect(result).not.toContain('banner.jpg');
+    });
+});
+//# sourceMappingURL=html-utils.test.js.map

package/build/src/tools/helpers/html-utils.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"html-utils.test.js","sourceRoot":"","sources":["../../../../src/tools/helpers/html-utils.test.ts"],"names":[],"mappings":"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"}