2.1.0

changelog.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 2025-05-07 - 2.1.0 - feat(smartmail)
+Add new email validation helper methods (getMxRecords, isDisposableEmail, isRoleAccount) and an applyVariables method to Smartmail for dynamic templating.
+
+- Introduced getMxRecords in EmailAddressValidator to extract MX records from DNS responses.
+- Added isDisposableEmail to determine if an email is from a disposable domain.
+- Added isRoleAccount to identify role-based email addresses.
+- Implemented applyVariables in Smartmail to update subject, body, and htmlBody templates with provided data.
+
+## 2025-05-07 - 2.0.1 - fix(readme)
+Update documentation to include usage of creation object reference and update API details.
+
+- Added a new section explaining how to use the creationObjectRef in Smartmail.
+- Included detailed examples on retrieving and using the creation object reference.
+- Updated the API reference to document the getCreationObject method.
+
 ## 2025-05-07 - 2.0.0 - 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.
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smartmail",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "private": false,
   "description": "A unified format for representing and dealing with emails, with support for attachments and email validation.",
   "main": "dist_ts/index.js",

readme.md

@@ -95,6 +95,51 @@ const email = new Smartmail({
 });
 ```
 
+### Using Creation Object Reference
+
+The Smartmail constructor accepts a generic type parameter that lets you associate any additional data with your email, accessible later via the `getCreationObject()` method. This is useful for tracking, referencing original data sources, or maintaining context:
+
+```typescript
+// Define your custom reference type
+interface OrderNotification {
+  orderId: string;
+  customerName: string;
+  items: string[];
+  total: number;
+}
+
+// Create email with typed creation object reference
+const orderEmail = new Smartmail<OrderNotification>({
+  from: 'orders@example.com',
+  to: ['customer@example.com'],
+  subject: 'Your Order #{{orderId}} Confirmation',
+  body: 'Thank you for your order, {{customerName}}!',
+  // Store the full order data as reference
+  creationObjectRef: {
+    orderId: '12345',
+    customerName: 'John Smith',
+    items: ['Product A', 'Product B'],
+    total: 99.95
+  }
+});
+
+// Later, retrieve the original reference data
+const orderData = orderEmail.getCreationObject();
+console.log(`Processing email for order ${orderData.orderId}`);
+console.log(`Order total: $${orderData.total}`);
+
+// Use the reference data for templating
+const subject = orderEmail.getSubject(orderData);  // "Your Order #12345 Confirmation"
+const body = orderEmail.getBody(orderData);        // "Thank you for your order, John Smith!"
+```
+
+This powerful feature allows you to:
+- Maintain a link to original data sources
+- Pass the email object between systems while preserving context
+- Avoid duplicating data between email content and your application
+- Use the reference data to fill template variables
+- Access metadata about the email that doesn't get included in the actual message
+
 ### Adding Recipients
 
 ```typescript
@@ -222,6 +267,7 @@ console.log(mimeObj);
 - `headers`: Optional key-value pairs of custom headers
 - `priority`: 'high' | 'normal' | 'low' (default: 'normal')
 - `validateEmails`: Boolean (default: false) - Validate all emails
+- `creationObjectRef`: Optional reference data of any type (generic T) - Store arbitrary data with the email
 
 #### Methods
 - `addRecipient(email, type?)`: Add a single recipient (to/cc/bcc)
@@ -234,6 +280,7 @@ console.log(mimeObj);
 - `getHtmlBody(data?)`: Get processed HTML body
 - `validateAllEmails()`: Validate all email addresses
 - `toMimeFormat(data?)`: Convert to MIME format object
+- `getCreationObject()`: Get the stored reference data of type T
 
 ## License and Legal Information
 

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartmail',
-  version: '2.0.0',
+  version: '2.1.0',
   description: 'A unified format for representing and dealing with emails, with support for attachments and email validation.'
 }

ts/smartmail.classes.emailaddressvalidator.ts

@@ -109,6 +109,65 @@ export class EmailAddressValidator {
     
     return result;
   }
+  
+  /**
+   * Gets the MX records for a domain
+   * @param domain The domain to get MX records for
+   * @returns Array of MX records as strings
+   */
+  public async getMxRecords(domain: string): Promise<string[]> {
+    const mxRecords = await this.checkMxRecords(domain);
+    
+    if (!mxRecords || !Array.isArray(mxRecords)) {
+      return [];
+    }
+    
+    // Extract exchange values from MX records
+    return mxRecords.map((record: any) => {
+      if (record && record.exchange) {
+        return record.exchange;
+      }
+      return '';
+    }).filter(Boolean);
+  }
+
+  /**
+   * Checks if an email is from a disposable domain
+   * @param email The email address to check
+   * @returns True if the email is from a disposable domain
+   */
+  public async isDisposableEmail(email: string): Promise<boolean> {
+    await this.fetchDomains();
+    
+    if (!this.isValidEmailFormat(email)) {
+      return false;
+    }
+    
+    const domainPart = email.split('@')[1];
+    return this.domainMap[domainPart] === 'disposable';
+  }
+  
+  /**
+   * Checks if an email is a role account (e.g. info@, support@, etc.)
+   * @param email The email address to check
+   * @returns True if the email is a role account
+   */
+  public isRoleAccount(email: string): boolean {
+    if (!this.isValidEmailFormat(email)) {
+      return false;
+    }
+    
+    const localPart = email.split('@')[0].toLowerCase();
+    const roleAccounts = [
+      'admin', 'administrator', 'webmaster', 'hostmaster', 'postmaster',
+      'info', 'support', 'sales', 'marketing', 'contact', 'help',
+      'abuse', 'noc', 'security', 'billing', 'donations', 'donate',
+      'staff', 'office', 'hr', 'jobs', 'careers', 'team',
+      'enquiry', 'enquiries', 'feedback', 'no-reply', 'noreply'
+    ];
+    
+    return roleAccounts.includes(localPart);
+  }
 
   /**
    * Validates an email address

ts/smartmail.classes.smartmail.ts

@@ -73,6 +73,32 @@ export class Smartmail<T> {
     const smartmustache = new plugins.smartmustache.SmartMustache(this.options.subject);
     return smartmustache.applyData(dataArg);
   }
+  
+  /**
+   * Applies variables to all template strings in the email
+   * @param variables Variables to apply to templates
+   */
+  public applyVariables(variables: Record<string, any>): void {
+    if (!variables || typeof variables !== 'object') {
+      return;
+    }
+    
+    // Process the subject, body, and HTML body with the provided variables
+    if (this.options.subject) {
+      const subjectMustache = new plugins.smartmustache.SmartMustache(this.options.subject);
+      this.options.subject = subjectMustache.applyData(variables);
+    }
+    
+    if (this.options.body) {
+      const bodyMustache = new plugins.smartmustache.SmartMustache(this.options.body);
+      this.options.body = bodyMustache.applyData(variables);
+    }
+    
+    if (this.options.htmlBody) {
+      const htmlBodyMustache = new plugins.smartmustache.SmartMustache(this.options.htmlBody);
+      this.options.htmlBody = htmlBodyMustache.applyData(variables);
+    }
+  }
 
   /**
    * Gets the processed plain text body with template variables applied