BREAKING CHANGE(smartmail): Improve email validation and Smartmail features: add detailed validation for email parts, caching for MX lookups, multi-recipient support, custom headers, and update dependency imports and build scripts.

readme.plan.md

@@ -0,0 +1,92 @@
+# Improvement Plan for SmartMail
+
+## Current Code Analysis
+
+### Core Components
+- **EmailAddressValidator**: Validates email addresses checking for validity, whether they are disposable or free
+  - Uses MX record checks to validate domains
+  - Has a domain map from external source that classifies domains as 'disposable' or 'freemail'
+  - Has placeholder 'reason' field in results that's not implemented ("todo")
+  - Fetches domain list from GitHub or falls back to local copy
+  - No validation of email format before DNS checks
+
+- **Smartmail**: Email representation class
+  - Basic email structure with from, subject, body
+  - Supports file attachments via smartfile
+  - Uses mustache templates for subject and body
+  - Lacks recipient handling (to, cc, bcc)
+  - No method to send emails
+  - No HTML body support
+
+### Dependencies
+- Uses several @push.rocks packages:
+  - smartdns: For DNS lookups
+  - smartfile: For file handling/attachments
+  - smartmustache: For template processing
+  - smartpath: For path operations
+  - smartrequest: For HTTP requests
+
+### Testing
+- Basic tests for EmailAddressValidator
+  - Tests validation of regular, free, and disposable emails
+  - No tests for invalid email formats or edge cases
+- Minimal test for Smartmail creation
+  - No tests for attachments, templates, or other features
+
+## Enhanced Improvement Plan
+
+1. [x] Complete the EmailAddressValidator implementation
+   - [x] Implement proper reason messages for validation results
+   - [x] Add email format validation before DNS checks (RFC 5322 compliance)
+   - [x] Add local part validation (check for illegal characters, proper format)
+   - [x] Improve domain validation (check syntax before DNS lookup)
+   - [x] Add email normalization (handle case sensitivity, plus addressing)
+   - [x] Implement caching mechanism for DNS lookups to improve performance
+   - [x] Add option to disable online domain list fetching
+
+2. [x] Enhance the Smartmail class
+   - [x] Add support for multiple recipients (to, cc, bcc arrays)
+   - [x] Add email preparing capabilities via MIME format
+   - [x] Support HTML email bodies with plain text fallback
+   - [x] Add reply-to and headers support
+   - [x] Implement method to convert to standard email formats (MIME)
+   - [x] Add email priority and importance flags
+   - [x] Add validation of email addresses used in from/to/cc/bcc
+
+3. [x] Improve testing
+   - [x] Add tests for email format validation (valid/invalid formats)
+   - [x] Test domain validation edge cases (non-existent domains, etc.)
+   - [x] Add tests for attachment handling
+   - [x] Test template processing with different data structures
+   - [x] Add tests for HTML emails and conversion
+   - [x] Test recipient handling with multiple addresses
+
+4. [x] Performance & security improvements
+   - [x] Optimize domain list handling
+   - [x] Implement intelligent caching strategy for validation results
+   - [x] Add configuration options for external service calls
+   - [x] Ensure secure handling of email data and attachments
+
+5. [x] Documentation improvements
+   - [x] Update README with comprehensive examples
+   - [x] Add detailed API documentation with JSDoc
+   - [x] Document all configuration options
+   - [x] Add usage examples for common scenarios
+   - [x] Document security considerations
+   - [x] Add TypeScript type documentation
+
+6. [ ] Advanced features
+   - [ ] DKIM/SPF validation support
+   - [ ] Implement email address suggestions for typos
+   - [ ] Add disposable email detection improvements
+   - [ ] Support for internationalized email addresses (IDN)
+   - [ ] Email address reputation checking
+   - [ ] Add email deliverability scoring
+   - [ ] Implement bounce address validation
+
+7. [x] Code quality
+   - [x] Add more TypeScript interfaces for clearer API definitions
+   - [x] Improve error handling with specific error types
+   - [x] Add configuration options via constructor
+   - [x] Make domain list updates configurable
+   - [x] Improve code organization with better separation of concerns