@zyther/tzmail 0.1.3 → 0.5.0

package/dist/core/interfaces/email.interface.d.ts

@@ -1,4 +1,4 @@
-import { ITemplate } from "./template.interface";
+import { ITemplate } from './template.interface';
 export interface IEmailOptions {
     to: string | string[];
     subject: string;
@@ -7,6 +7,8 @@ export interface IEmailOptions {
     bcc?: string | string[];
     attachments?: IAttachment[];
     template?: ITemplate;
+    /** Primitive named values interpolated into `{{variable}}` placeholders. */
+    templateData?: Record<string, unknown>;
     text?: string;
     html?: string;
 }
@@ -17,14 +19,102 @@ export interface IAttachment {
     contentType?: string;
     cid?: string;
 }
+/**
+ * Typed outcome of an email attempt. `success` is true only when the transport
+ * did not report rejected recipients. `partial` means that at least one
+ * recipient was accepted and at least one rejected; a failure result must not
+ * be interpreted as successful delivery. `error` retains the original thrown
+ * validation, rendering or transport error, when present.
+ */
+export interface IEmailSendResult {
+    success: boolean;
+    status: 'success' | 'partial' | 'failure';
+    messageId?: string;
+    response?: string;
+    accepted?: Array<string | {
+        address: string;
+        name: string;
+    }>;
+    rejected?: Array<string | {
+        address: string;
+        name: string;
+    }>;
+    error?: unknown;
+    errorStage?: 'validation' | 'render' | 'smtp' | 'provider';
+}
+export type IEmailAuth = {
+    user: string;
+    pass: string;
+    type?: 'login' | 'Login' | 'LOGIN';
+} | {
+    user: string;
+    type: 'oauth2' | 'OAuth2' | 'OAUTH2';
+    clientId?: string;
+    clientSecret?: string;
+    refreshToken?: string;
+    accessToken?: string;
+    accessUrl?: string;
+    expires?: number;
+    timeout?: number;
+    privateKey?: string | {
+        key: string;
+        passphrase: string;
+    };
+    serviceClient?: string;
+    provisionCallback?: (user: string, renew: boolean, callback: (error: Error | null, accessToken: string, expires: number) => void) => void;
+} | {
+    user: string;
+    pass: string;
+    type: 'custom' | 'Custom' | 'CUSTOM';
+    method: string;
+};
 export interface IEmailConfig {
     host: string;
     port: number;
     secure: boolean;
-    auth: {
-        user: string;
-        pass: string;
-    };
+    /** Reuse SMTP connections; set true with pool sizing for sustained throughput. */
+    pool?: boolean;
+    maxConnections?: number;
+    maxMessages?: number;
+    /** Shared rate limiter window and message limit (requires pool: true). */
+    rateDelta?: number;
+    rateLimit?: number;
+    connectionTimeout?: number;
+    greetingTimeout?: number;
+    socketTimeout?: number;
+    auth: IEmailAuth;
+    defaultFrom?: string;
+}
+/** SendGrid Web API v3 settings. API keys should come from a secret manager. */
+export interface ISendGridConfig {
+    apiKey: string;
+    defaultFrom: string;
+    /** Optional API base URL, for example the regional EU API endpoint. */
+    apiUrl?: string;
+    requestTimeoutMs?: number;
+    /** Optional per-attachment memory guard; API attachments are encoded in memory. */
+    maxAttachmentBytes?: number;
+}
+/** Mailgun Messages API settings. */
+export interface IMailgunConfig {
+    apiKey: string;
+    domain: string;
+    defaultFrom: string;
+    region?: 'us' | 'eu';
+    /** Optional custom API base URL, useful for regional or controlled endpoints. */
+    apiUrl?: string;
+    requestTimeoutMs?: number;
+    /** Optional per-attachment memory guard; API attachments are uploaded in memory. */
+    maxAttachmentBytes?: number;
+}
+/** Amazon SES v2 settings; when credentials are omitted, the AWS SDK default credential chain is used. */
+export interface IAmazonSesConfig {
+    region: string;
     defaultFrom?: string;
+    credentials?: {
+        accessKeyId: string;
+        secretAccessKey: string;
+        sessionToken?: string;
+    };
 }
 //# sourceMappingURL=email.interface.d.ts.map

package/dist/core/interfaces/email.interface.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"email.interface.d.ts","sourceRoot":"","sources":["../../../src/core/interfaces/email.interface.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEjD,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACvB,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACxB,WAAW,CAAC,EAAE,WAAW,EAAE,CAAC;IAC5B,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE;QACJ,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;IACF,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB"}
+{"version":3,"file":"email.interface.d.ts","sourceRoot":"","sources":["../../../src/core/interfaces/email.interface.ts"],"names":[],"mappings":"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"}

package/dist/core/interfaces/template.interface.d.ts

@@ -7,6 +7,14 @@ export interface ITemplate {
     render(data: any): Promise<string>;
 }
 export interface ITemplateConfig {
+    /** BCP 47 language tag written to the generated document; defaults to en. */
+    language?: string;
+    /** Text direction for right-to-left or automatic-script content; defaults to ltr. */
+    direction?: 'ltr' | 'rtl' | 'auto';
+    /** Hidden inbox preview text shown beside the subject; limited to 500 characters. */
+    preheader?: string;
+    /** Decoration for generated footer links; defaults to none. Set to underline when desired. */
+    linkDecoration?: 'none' | 'underline';
     header?: IHeaderConfig;
     body?: IBodyConfig;
     footer?: IFooterConfig;
@@ -17,6 +25,7 @@ export interface ITemplateConfig {
 export interface IBodyConfig {
     title?: string;
     message?: string;
+    /** HTML intencionalmente confiável; os demais campos textuais são escapados pelo renderer. */
     content?: string;
     buttonText?: string;
     buttonUrl?: string;
@@ -45,11 +54,13 @@ export interface IFooterConfig {
         url: string;
     }>;
     socialLinks?: Array<{
-        platform: 'facebook' | 'twitter' | 'linkedin' | 'github' | 'instagram' | 'youtube' | 'tiktok' | 'pinterest' | 'reddit' | 'pinterest' | 'tiktok' | 'gitlab' | 'stackoverflow' | 'medium' | 'dribbble' | 'behance' | 'telegram';
+        platform: 'facebook' | 'twitter' | 'linkedin' | 'github' | 'instagram' | 'youtube' | 'tiktok' | 'pinterest' | 'reddit' | 'gitlab' | 'stackoverflow' | 'medium' | 'dribbble' | 'behance' | 'telegram';
         url: string;
     }>;
     copyrightText?: string;
     unsubscribeText?: string;
+    /** URL opcional do link de cancelamento; sem ela, o texto é exibido sem href fictício. */
+    unsubscribeUrl?: string;
     backgroundColor?: string;
     textColor?: string;
 }

package/dist/core/interfaces/template.interface.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"template.interface.d.ts","sourceRoot":"","sources":["../../../src/core/interfaces/template.interface.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAEhD,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,SAAS,CAAC;IACjB,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC;IAC1B,MAAM,EAAE,eAAe,CAAC;IACxB,MAAM,CAAC,IAAI,EAAE,GAAG,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,OAAO,CAAC,EAAE,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;IAC3C,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC;CACtD;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,SAAS,GAAG,WAAW,GAAG,SAAS,GAAG,QAAQ,CAAC;IAC/D,SAAS,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;IACxC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,CAAC,EAAE;QACL,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,IAAI,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC;KACrC,CAAC;IACF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,CAAC,EAAE,KAAK,CAAC;QACZ,IAAI,EAAE,MAAM,CAAC;QACb,GAAG,EAAE,MAAM,CAAC;KACb,CAAC,CAAC;IACH,WAAW,CAAC,EAAE,KAAK,CAAC;QAClB,QAAQ,EAAE,UAAU,GAAG,SAAS,GAAG,UAAU,GAAG,QAAQ,GAAG,WAAW,GAAG,SAAS,GAAG,QAAQ,GAAG,WAAW,GAAG,QAAQ,GAAG,WAAW,GAAG,QAAQ,GAAG,QAAQ,GAAG,eAAe,GAAG,QAAQ,GAAG,UAAU,GAAG,SAAS,GAAG,UAAU,CAAC;QAC9N,GAAG,EAAE,MAAM,CAAC;KACb,CAAC,CAAC;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB"}
+{"version":3,"file":"template.interface.d.ts","sourceRoot":"","sources":["../../../src/core/interfaces/template.interface.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAEhD,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,SAAS,CAAC;IACjB,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC;IAC1B,MAAM,EAAE,eAAe,CAAC;IACxB,MAAM,CAAC,IAAI,EAAE,GAAG,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,eAAe;IAC9B,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qFAAqF;IACrF,SAAS,CAAC,EAAE,KAAK,GAAG,KAAK,GAAG,MAAM,CAAC;IACnC,qFAAqF;IACrF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8FAA8F;IAC9F,cAAc,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC;IACtC,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,OAAO,CAAC,EAAE,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;IAC3C,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC;CACtD;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8FAA8F;IAC9F,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,SAAS,GAAG,WAAW,GAAG,SAAS,GAAG,QAAQ,CAAC;IAC/D,SAAS,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;IACxC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,CAAC,EAAE;QACL,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,IAAI,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC;KACrC,CAAC;IACF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,CAAC,EAAE,KAAK,CAAC;QACZ,IAAI,EAAE,MAAM,CAAC;QACb,GAAG,EAAE,MAAM,CAAC;KACb,CAAC,CAAC;IACH,WAAW,CAAC,EAAE,KAAK,CAAC;QAClB,QAAQ,EAAE,UAAU,GAAG,SAAS,GAAG,UAAU,GAAG,QAAQ,GAAG,WAAW,GAAG,SAAS,GAAG,QAAQ,GAAG,WAAW,GAAG,QAAQ,GAAG,QAAQ,GAAG,eAAe,GAAG,QAAQ,GAAG,UAAU,GAAG,SAAS,GAAG,UAAU,CAAC;QACrM,GAAG,EAAE,MAAM,CAAC;KACb,CAAC,CAAC;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,0FAA0F;IAC1F,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB"}

package/dist/factories/email-factory.d.ts

@@ -1,19 +1,42 @@
-import { IEmailConfig, IEmailOptions } from '../core/interfaces/email.interface';
-import { TemplateService } from '../services/template.service';
-import { AttachmentService } from '../services/attachment.service';
+import { IAmazonSesConfig, IEmailConfig, IEmailOptions, IEmailSendResult, IMailgunConfig, ISendGridConfig } from '../core/interfaces/email.interface';
+import { ITemplateServiceOptions, TemplateService } from '../services/template.service';
+import { AttachmentService, IAttachmentServiceOptions } from '../services/attachment.service';
 import { ThemeType } from '../core/enums/theme.enum';
 import { ITemplateConfig } from '../core/interfaces/template.interface';
+import { IEmailTransport } from '../providers/provider.interface';
+import { BullMQEmailQueue, IBullMQEmailQueueConfig } from '../queues/bullmq-email-queue';
 export declare class EmailFactory {
-    private static instance;
+    private static instance?;
+    private static singletonFingerprint?;
     private emailService;
     private templateService;
     private attachmentService;
     private constructor();
-    static initialize(config: IEmailConfig, templateOptions?: any): EmailFactory;
+    /**
+     * Returns the process singleton. A later call with different settings fails
+     * explicitly rather than silently continuing with the first configuration.
+     */
+    static initialize(config: IEmailConfig, templateOptions?: ITemplateServiceOptions, attachmentOptions?: IAttachmentServiceOptions): EmailFactory;
+    /** Creates an independent factory instance without changing the singleton. */
+    static create(config: IEmailConfig, templateOptions?: ITemplateServiceOptions, attachmentOptions?: IAttachmentServiceOptions): EmailFactory;
+    /** Creates an independent SendGrid Web API v3 client; no provider state is shared between instances. */
+    static createSendGrid(config: ISendGridConfig, templateOptions?: ITemplateServiceOptions, attachmentOptions?: IAttachmentServiceOptions): EmailFactory;
+    /** Creates an independent Mailgun Messages API client. */
+    static createMailgun(config: IMailgunConfig, templateOptions?: ITemplateServiceOptions, attachmentOptions?: IAttachmentServiceOptions): EmailFactory;
+    /** Creates an Amazon SES v2 transport using the AWS SDK credential provider chain unless credentials are supplied. */
+    static createSES(config: IAmazonSesConfig, templateOptions?: ITemplateServiceOptions, attachmentOptions?: IAttachmentServiceOptions): EmailFactory;
+    /** Creates an instance around a user-supplied transport adapter. */
+    static createWithTransport(transport: IEmailTransport, defaultFrom?: string, templateOptions?: ITemplateServiceOptions, attachmentOptions?: IAttachmentServiceOptions): EmailFactory;
+    /** Creates an optional Redis-backed BullMQ producer/worker integration. */
+    static createBullMQQueue(config: IBullMQEmailQueueConfig): BullMQEmailQueue;
     static getInstance(): EmailFactory;
-    sendEmail(options: IEmailOptions): Promise<any>;
+    sendEmail(options: IEmailOptions): Promise<IEmailSendResult>;
     getTemplateService(): TemplateService;
     getAttachmentService(): AttachmentService;
+    /** Verify connectivity when supported by the selected transport; API transports may not provide a safe check. */
+    verifyTransport(): Promise<true>;
+    /** Release pooled SMTP connections and the template cache cleanup timer. */
+    close(): void;
     previewTemplate(themeType: ThemeType, variant: 'light' | 'dark', config: ITemplateConfig, data: any): Promise<string>;
     getThemeInfo(themeType: ThemeType): {
         name: string;
@@ -27,8 +50,11 @@ export declare class EmailFactory {
         totalTemplates: number;
         cachedTemplates: number;
         totalHits: number;
+        cacheRequests: number;
         templatesByTheme: Record<ThemeType, number>;
         cacheHitRate: number;
     };
+    /** Hashes canonicalized settings so credentials are never exposed in errors/logs. */
+    private static fingerprint;
 }
 //# sourceMappingURL=email-factory.d.ts.map

package/dist/factories/email-factory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"email-factory.d.ts","sourceRoot":"","sources":["../../src/factories/email-factory.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,oCAAoC,CAAC;AAEjF,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAC/D,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AACnE,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,uCAAuC,CAAC;AAExE,qBAAa,YAAY;IACvB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAe;IACtC,OAAO,CAAC,YAAY,CAAe;IACnC,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,iBAAiB,CAAoB;IAE7C,OAAO;IAOP,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,YAAY,EAAE,eAAe,CAAC,EAAE,GAAG,GAAG,YAAY;IAO5E,MAAM,CAAC,WAAW,IAAI,YAAY;IAO5B,SAAS,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,GAAG,CAAC;IAIrD,kBAAkB,IAAI,eAAe;IAIrC,oBAAoB,IAAI,iBAAiB;IAInC,eAAe,CACnB,SAAS,EAAE,SAAS,EACpB,OAAO,EAAE,OAAO,GAAG,MAAM,EACzB,MAAM,EAAE,eAAe,EACvB,IAAI,EAAE,GAAG,GACR,OAAO,CAAC,MAAM,CAAC;IAIlB,YAAY,CAAC,SAAS,EAAE,SAAS;;;;;;;IAIjC,UAAU;IAIV,gBAAgB;;;;;;;CAGjB"}
+{"version":3,"file":"email-factory.d.ts","sourceRoot":"","sources":["../../src/factories/email-factory.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,gBAAgB,EAChB,cAAc,EACd,eAAe,EAChB,MAAM,oCAAoC,CAAC;AAE5C,OAAO,EAAE,uBAAuB,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AACxF,OAAO,EAAE,iBAAiB,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAC9F,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,uCAAuC,CAAC;AACxE,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAIlE,OAAO,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAIzF,qBAAa,YAAY;IACvB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAe;IACvC,OAAO,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAAS;IAC7C,OAAO,CAAC,YAAY,CAAe;IACnC,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,iBAAiB,CAAoB;IAE7C,OAAO;IAYP;;;OAGG;IACH,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,YAAY,EAAE,eAAe,CAAC,EAAE,uBAAuB,EAAE,iBAAiB,CAAC,EAAE,yBAAyB,GAAG,YAAY;IAgB/I,8EAA8E;IAC9E,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,EAAE,eAAe,CAAC,EAAE,uBAAuB,EAAE,iBAAiB,CAAC,EAAE,yBAAyB,GAAG,YAAY;IAS3I,wGAAwG;IACxG,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,eAAe,EAAE,eAAe,CAAC,EAAE,uBAAuB,EAAE,iBAAiB,CAAC,EAAE,yBAAyB,GAAG,YAAY;IAItJ,0DAA0D;IAC1D,MAAM,CAAC,aAAa,CAAC,MAAM,EAAE,cAAc,EAAE,eAAe,CAAC,EAAE,uBAAuB,EAAE,iBAAiB,CAAC,EAAE,yBAAyB,GAAG,YAAY;IAIpJ,sHAAsH;IACtH,MAAM,CAAC,SAAS,CAAC,MAAM,EAAE,gBAAgB,EAAE,eAAe,CAAC,EAAE,uBAAuB,EAAE,iBAAiB,CAAC,EAAE,yBAAyB,GAAG,YAAY;IA2BlJ,oEAAoE;IACpE,MAAM,CAAC,mBAAmB,CACxB,SAAS,EAAE,eAAe,EAC1B,WAAW,CAAC,EAAE,MAAM,EACpB,eAAe,CAAC,EAAE,uBAAuB,EACzC,iBAAiB,CAAC,EAAE,yBAAyB,GAC5C,YAAY;IAIf,2EAA2E;IAC3E,MAAM,CAAC,iBAAiB,CAAC,MAAM,EAAE,uBAAuB,GAAG,gBAAgB;IAI3E,MAAM,CAAC,WAAW,IAAI,YAAY;IAO5B,SAAS,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAIlE,kBAAkB,IAAI,eAAe;IAIrC,oBAAoB,IAAI,iBAAiB;IAIzC,iHAAiH;IAC3G,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC;IAItC,4EAA4E;IAC5E,KAAK,IAAI,IAAI;IASP,eAAe,CACnB,SAAS,EAAE,SAAS,EACpB,OAAO,EAAE,OAAO,GAAG,MAAM,EACzB,MAAM,EAAE,eAAe,EACvB,IAAI,EAAE,GAAG,GACR,OAAO,CAAC,MAAM,CAAC;IAIlB,YAAY,CAAC,SAAS,EAAE,SAAS;;;;;;;IAIjC,UAAU;IAIV,gBAAgB;;;;;;;;IAIhB,qFAAqF;IACrF,OAAO,CAAC,MAAM,CAAC,WAAW;CAyB3B"}

package/dist/factories/email-factory.js

@@ -4,23 +4,83 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EmailFactory = void 0;
+const crypto_1 = require("crypto");
+const module_1 = require("module");
 const nodemailer_1 = __importDefault(require("nodemailer"));
 const email_service_1 = require("../services/email.service");
 const template_service_1 = require("../services/template.service");
 const attachment_service_1 = require("../services/attachment.service");
+const nodemailer_transport_1 = require("../providers/nodemailer.transport");
+const sendgrid_transport_1 = require("../providers/sendgrid.transport");
+const mailgun_transport_1 = require("../providers/mailgun.transport");
+const bullmq_email_queue_1 = require("../queues/bullmq-email-queue");
+const loadOptionalModule = (0, module_1.createRequire)(__filename);
 class EmailFactory {
-    constructor(config, templateOptions) {
-        const transporter = nodemailer_1.default.createTransport(config);
-        this.emailService = new email_service_1.EmailService(transporter, config.defaultFrom);
+    static instance;
+    static singletonFingerprint;
+    emailService;
+    templateService;
+    attachmentService;
+    constructor(transport, defaultFrom, templateOptions, attachmentOptions, errorStage = 'smtp') {
+        this.emailService = new email_service_1.EmailService(transport, defaultFrom, errorStage);
         this.templateService = new template_service_1.TemplateService(templateOptions);
-        this.attachmentService = new attachment_service_1.AttachmentService();
+        this.attachmentService = new attachment_service_1.AttachmentService(attachmentOptions);
     }
-    static initialize(config, templateOptions) {
+    /**
+     * Returns the process singleton. A later call with different settings fails
+     * explicitly rather than silently continuing with the first configuration.
+     */
+    static initialize(config, templateOptions, attachmentOptions) {
+        const fingerprint = this.fingerprint(config, templateOptions, attachmentOptions);
         if (!this.instance) {
-            this.instance = new EmailFactory(config, templateOptions);
+            this.instance = new EmailFactory(new nodemailer_transport_1.NodemailerTransport(nodemailer_1.default.createTransport(config)), config.defaultFrom, templateOptions, attachmentOptions);
+            this.singletonFingerprint = fingerprint;
+        }
+        else if (this.singletonFingerprint !== fingerprint) {
+            throw new Error('EmailFactory is already initialized with a different configuration; use EmailFactory.create() for an independent instance.');
         }
         return this.instance;
     }
+    /** Creates an independent factory instance without changing the singleton. */
+    static create(config, templateOptions, attachmentOptions) {
+        return new EmailFactory(new nodemailer_transport_1.NodemailerTransport(nodemailer_1.default.createTransport(config)), config.defaultFrom, templateOptions, attachmentOptions);
+    }
+    /** Creates an independent SendGrid Web API v3 client; no provider state is shared between instances. */
+    static createSendGrid(config, templateOptions, attachmentOptions) {
+        return new EmailFactory(new sendgrid_transport_1.SendGridTransport(config), config.defaultFrom, templateOptions, attachmentOptions, 'provider');
+    }
+    /** Creates an independent Mailgun Messages API client. */
+    static createMailgun(config, templateOptions, attachmentOptions) {
+        return new EmailFactory(new mailgun_transport_1.MailgunTransport(config), config.defaultFrom, templateOptions, attachmentOptions, 'provider');
+    }
+    /** Creates an Amazon SES v2 transport using the AWS SDK credential provider chain unless credentials are supplied. */
+    static createSES(config, templateOptions, attachmentOptions) {
+        if (!config.region.trim())
+            throw new Error('Amazon SES region is required');
+        let awsSes;
+        try {
+            awsSes = loadOptionalModule('@aws-sdk/client-sesv2');
+        }
+        catch (error) {
+            throw new Error('Amazon SES support requires optional package @aws-sdk/client-sesv2. Install it with: npm install @aws-sdk/client-sesv2', { cause: error });
+        }
+        const sesClient = new awsSes.SESv2Client({
+            region: config.region,
+            ...(config.credentials ? { credentials: config.credentials } : {})
+        });
+        const transporter = nodemailer_1.default.createTransport({
+            SES: { sesClient, SendEmailCommand: awsSes.SendEmailCommand }
+        });
+        return new EmailFactory(new nodemailer_transport_1.NodemailerTransport(transporter, () => sesClient.destroy?.()), config.defaultFrom, templateOptions, attachmentOptions, 'provider');
+    }
+    /** Creates an instance around a user-supplied transport adapter. */
+    static createWithTransport(transport, defaultFrom, templateOptions, attachmentOptions) {
+        return new EmailFactory(transport, defaultFrom, templateOptions, attachmentOptions, 'provider');
+    }
+    /** Creates an optional Redis-backed BullMQ producer/worker integration. */
+    static createBullMQQueue(config) {
+        return new bullmq_email_queue_1.BullMQEmailQueue(config);
+    }
     static getInstance() {
         if (!this.instance) {
             throw new Error('EmailFactory not initialized. Call initialize() first.');
@@ -36,6 +96,19 @@ class EmailFactory {
     getAttachmentService() {
         return this.attachmentService;
     }
+    /** Verify connectivity when supported by the selected transport; API transports may not provide a safe check. */
+    async verifyTransport() {
+        return this.emailService.verify();
+    }
+    /** Release pooled SMTP connections and the template cache cleanup timer. */
+    close() {
+        this.emailService.close();
+        this.templateService.dispose();
+        if (EmailFactory.instance === this) {
+            EmailFactory.instance = undefined;
+            EmailFactory.singletonFingerprint = undefined;
+        }
+    }
     async previewTemplate(themeType, variant, config, data) {
         return this.templateService.previewTemplate(themeType, variant, config, data);
     }
@@ -48,5 +121,36 @@ class EmailFactory {
     getTemplateStats() {
         return this.templateService.getTemplateStats();
     }
+    /** Hashes canonicalized settings so credentials are never exposed in errors/logs. */
+    static fingerprint(config, templateOptions, attachmentOptions) {
+        const canonicalize = (value, ancestors = new Set()) => {
+            if (value === undefined)
+                return 'undefined';
+            if (value === null || typeof value !== 'object') {
+                if (typeof value === 'function')
+                    return `function:${value.toString()}`;
+                if (typeof value === 'bigint')
+                    return `bigint:${value.toString()}`;
+                return JSON.stringify(value) ?? String(value);
+            }
+            if (ancestors.has(value))
+                return '[Circular]';
+            ancestors.add(value);
+            let result;
+            if (Array.isArray(value)) {
+                result = `[${value.map((item) => canonicalize(item, ancestors)).join(',')}]`;
+            }
+            else if (value instanceof Date) {
+                result = `date:${value.toISOString()}`;
+            }
+            else {
+                result = `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonicalize(value[key], ancestors)}`).join(',')}}`;
+            }
+            ancestors.delete(value);
+            return result;
+        };
+        const serialized = `${canonicalize(config)}|${canonicalize(templateOptions)}|${canonicalize(attachmentOptions)}`;
+        return (0, crypto_1.createHash)('sha256').update(serialized).digest('hex');
+    }
 }
 exports.EmailFactory = EmailFactory;

package/dist/factories/template-factory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"template-factory.d.ts","sourceRoot":"","sources":["../../src/factories/template-factory.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AACrD,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,uCAAuC,CAAC;AACnF,OAAO,EAAE,MAAM,EAAE,MAAM,qCAAqC,CAAC;AAQ7D,qBAAa,eAAe;IAC1B,OAAO,CAAC,MAAM,CAAC,MAAM,CAMlB;IAEH,MAAM,CAAC,cAAc,CACnB,SAAS,EAAE,SAAS,EACpB,OAAO,EAAE,OAAO,GAAG,MAAM,EACzB,MAAM,EAAE,eAAe,GACtB,SAAS;IA+CZ,MAAM,CAAC,QAAQ,CAAC,SAAS,EAAE,SAAS,GAAG,MAAM,GAAG,SAAS;IAIzD,MAAM,CAAC,UAAU,IAAI,SAAS,EAAE;IAIhC,MAAM,CAAC,YAAY,CAAC,SAAS,EAAE,SAAS,GAAG;QACzC,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,MAAM,CAAC;QACpB,QAAQ,EAAE,MAAM,EAAE,CAAC;KACpB;CA+BF"}
+{"version":3,"file":"template-factory.d.ts","sourceRoot":"","sources":["../../src/factories/template-factory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AACrD,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,uCAAuC,CAAC;AACnF,OAAO,EAAE,MAAM,EAAE,MAAM,qCAAqC,CAAC;AA0F7D,qBAAa,eAAe;IAC1B,OAAO,CAAC,MAAM,CAAC,MAAM,CAgBlB;IAEH,MAAM,CAAC,cAAc,CAAC,SAAS,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,EAAE,MAAM,EAAE,eAAe,GAAG,SAAS;IAgE1G,MAAM,CAAC,QAAQ,CAAC,SAAS,EAAE,SAAS,GAAG,MAAM,GAAG,SAAS;IACzD,MAAM,CAAC,UAAU,IAAI,SAAS,EAAE;IAEhC,MAAM,CAAC,YAAY,CAAC,SAAS,EAAE,SAAS,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;KAAE;CAsBrG"}