@push.rocks/smartmta 5.1.2 → 5.2.0

package/dist_ts/mail/core/classes.email.d.ts

@@ -0,0 +1,291 @@
+import * as plugins from '../../plugins.js';
+export interface IAttachment {
+    filename: string;
+    content: Buffer;
+    contentType: string;
+    contentId?: string;
+    encoding?: string;
+}
+export interface IEmailOptions {
+    from: string;
+    to?: string | string[];
+    cc?: string | string[];
+    bcc?: string | string[];
+    subject: string;
+    text: string;
+    html?: string;
+    attachments?: IAttachment[];
+    headers?: Record<string, string>;
+    mightBeSpam?: boolean;
+    priority?: 'high' | 'normal' | 'low';
+    skipAdvancedValidation?: boolean;
+    variables?: Record<string, any>;
+}
+/**
+ * Email class represents a complete email message.
+ *
+ * This class takes IEmailOptions in the constructor and normalizes the data:
+ * - 'to', 'cc', 'bcc' are always converted to arrays
+ * - Optional properties get default values
+ * - Additional properties like messageId and envelopeFrom are generated
+ */
+export declare class Email {
+    from: string;
+    to: string[];
+    cc: string[];
+    bcc: string[];
+    subject: string;
+    text: string;
+    html?: string;
+    attachments: IAttachment[];
+    headers: Record<string, string>;
+    mightBeSpam: boolean;
+    priority: 'high' | 'normal' | 'low';
+    variables: Record<string, any>;
+    private envelopeFrom;
+    private messageId;
+    private static emailValidator;
+    constructor(options: IEmailOptions);
+    /**
+     * Validates an email address using smartmail's EmailAddressValidator
+     * For constructor validation, we only check syntax to avoid delays
+     * Supports RFC-compliant addresses including display names and bounce addresses.
+     *
+     * @param email The email address to validate
+     * @returns boolean indicating if the email is valid
+     */
+    private isValidEmail;
+    /**
+     * Extracts the email address from a string that may contain a display name.
+     * Handles formats like:
+     * - simple@example.com
+     * - "John Doe" <john@example.com>
+     * - John Doe <john@example.com>
+     *
+     * @param emailString The email string to parse
+     * @returns The extracted email address or null
+     */
+    private extractEmailAddress;
+    /**
+     * Parses and validates recipient email addresses
+     * @param recipients A string or array of recipient emails
+     * @returns Array of validated email addresses
+     */
+    private parseRecipients;
+    /**
+     * Basic sanitization for strings to prevent header injection
+     * @param input The string to sanitize
+     * @returns Sanitized string
+     */
+    private sanitizeString;
+    /**
+     * Gets the domain part of the from email address
+     * @returns The domain part of the from email or null if invalid
+     */
+    getFromDomain(): string | null;
+    /**
+     * Gets the clean from email address without display name
+     * @returns The email address without display name
+     */
+    getFromAddress(): string;
+    /**
+     * Converts IDN (International Domain Names) to ASCII
+     * @param email The email address to convert
+     * @returns The email with ASCII-converted domain
+     */
+    private convertIDNToASCII;
+    /**
+     * Gets clean to email addresses without display names
+     * @returns Array of email addresses without display names
+     */
+    getToAddresses(): string[];
+    /**
+     * Gets clean cc email addresses without display names
+     * @returns Array of email addresses without display names
+     */
+    getCcAddresses(): string[];
+    /**
+     * Gets clean bcc email addresses without display names
+     * @returns Array of email addresses without display names
+     */
+    getBccAddresses(): string[];
+    /**
+     * Gets all recipients (to, cc, bcc) as a unique array
+     * @returns Array of all unique recipient email addresses
+     */
+    getAllRecipients(): string[];
+    /**
+     * Gets primary recipient (first in the to field)
+     * @returns The primary recipient email or null if none exists
+     */
+    getPrimaryRecipient(): string | null;
+    /**
+     * Checks if the email has attachments
+     * @returns Boolean indicating if the email has attachments
+     */
+    hasAttachments(): boolean;
+    /**
+     * Add a recipient to the email
+     * @param email The recipient email address
+     * @param type The recipient type (to, cc, bcc)
+     * @returns This instance for method chaining
+     */
+    addRecipient(email: string, type?: 'to' | 'cc' | 'bcc'): this;
+    /**
+     * Add an attachment to the email
+     * @param attachment The attachment to add
+     * @returns This instance for method chaining
+     */
+    addAttachment(attachment: IAttachment): this;
+    /**
+     * Add a custom header to the email
+     * @param name The header name
+     * @param value The header value
+     * @returns This instance for method chaining
+     */
+    addHeader(name: string, value: string): this;
+    /**
+     * Set the email priority
+     * @param priority The priority level
+     * @returns This instance for method chaining
+     */
+    setPriority(priority: 'high' | 'normal' | 'low'): this;
+    /**
+     * Set a template variable
+     * @param key The variable key
+     * @param value The variable value
+     * @returns This instance for method chaining
+     */
+    setVariable(key: string, value: any): this;
+    /**
+     * Set multiple template variables at once
+     * @param variables The variables object
+     * @returns This instance for method chaining
+     */
+    setVariables(variables: Record<string, any>): this;
+    /**
+     * Get the subject with variables applied
+     * @param variables Optional additional variables to apply
+     * @returns The processed subject
+     */
+    getSubjectWithVariables(variables?: Record<string, any>): string;
+    /**
+     * Get the text content with variables applied
+     * @param variables Optional additional variables to apply
+     * @returns The processed text content
+     */
+    getTextWithVariables(variables?: Record<string, any>): string;
+    /**
+     * Get the HTML content with variables applied
+     * @param variables Optional additional variables to apply
+     * @returns The processed HTML content or undefined if none
+     */
+    getHtmlWithVariables(variables?: Record<string, any>): string | undefined;
+    /**
+     * Apply template variables to a string
+     * @param template The template string
+     * @param additionalVariables Optional additional variables to apply
+     * @returns The processed string
+     */
+    private applyVariables;
+    /**
+     * Gets the total size of all attachments in bytes
+     * @returns Total size of all attachments in bytes
+     */
+    getAttachmentsSize(): number;
+    /**
+     * Perform advanced validation on sender and recipient email addresses
+     * This should be called separately after instantiation when ready to check MX records
+     * @param options Validation options
+     * @returns Promise resolving to validation results for all addresses
+     */
+    validateAddresses(options?: {
+        checkMx?: boolean;
+        checkDisposable?: boolean;
+        checkSenderOnly?: boolean;
+        checkFirstRecipientOnly?: boolean;
+    }): Promise<{
+        sender: {
+            email: string;
+            result: any;
+        };
+        recipients: Array<{
+            email: string;
+            result: any;
+        }>;
+        isValid: boolean;
+    }>;
+    /**
+     * Convert this email to a smartmail instance
+     * @returns A new Smartmail instance
+     */
+    toSmartmail(): Promise<plugins.smartmail.Smartmail<any>>;
+    /**
+     * Get the from email address
+     * @returns The from email address
+     */
+    getFromEmail(): string;
+    /**
+     * Get the subject (Smartmail compatibility method)
+     * @returns The email subject
+     */
+    getSubject(): string;
+    /**
+     * Get the body content (Smartmail compatibility method)
+     * @param isHtml Whether to return HTML content if available
+     * @returns The email body (HTML if requested and available, otherwise plain text)
+     */
+    getBody(isHtml?: boolean): string;
+    /**
+     * Get the from address (Smartmail compatibility method)
+     * @returns The sender email address
+     */
+    getFrom(): string;
+    /**
+     * Get the message ID
+     * @returns The message ID
+     */
+    getMessageId(): string;
+    /**
+     * Convert the Email instance back to IEmailOptions format.
+     * Useful for serialization or passing to APIs that expect IEmailOptions.
+     * Note: This loses some Email-specific properties like messageId and envelopeFrom.
+     *
+     * @returns IEmailOptions representation of this email
+     */
+    toEmailOptions(): IEmailOptions;
+    /**
+     * Set a custom message ID
+     * @param id The message ID to set
+     * @returns This instance for method chaining
+     */
+    setMessageId(id: string): this;
+    /**
+     * Get the envelope from address (return-path)
+     * @returns The envelope from address
+     */
+    getEnvelopeFrom(): string;
+    /**
+     * Set the envelope from address (return-path)
+     * @param address The envelope from address to set
+     * @returns This instance for method chaining
+     */
+    setEnvelopeFrom(address: string): this;
+    /**
+     * Creates an RFC822 compliant email string
+     * @param variables Optional template variables to apply
+     * @returns The email formatted as an RFC822 compliant string
+     */
+    toRFC822String(variables?: Record<string, any>): string;
+    /**
+     * Convert to simple Smartmail-compatible object (for backward compatibility)
+     * @returns A Promise with a simple Smartmail-compatible object
+     */
+    toSmartmailBasic(): Promise<any>;
+    /**
+     * Create an Email instance from a Smartmail object
+     * @param smartmail The Smartmail instance to convert
+     * @returns A new Email instance
+     */
+    static fromSmartmail(smartmail: plugins.smartmail.Smartmail<any>): Email;
+}