@zyther/tzmail 0.1.3 → 0.5.0

package/dist/providers/provider.interface.d.ts

@@ -0,0 +1,30 @@
+import { IAttachment } from '../core/interfaces/email.interface';
+export interface ITransportMessage {
+    from?: string;
+    to: string | string[];
+    cc?: string | string[];
+    bcc?: string | string[];
+    subject: string;
+    text?: string;
+    html?: string;
+    attachments?: IAttachment[];
+}
+export interface ITransportSendInfo {
+    messageId?: string;
+    response?: string;
+    accepted?: Array<string | {
+        address: string;
+        name: string;
+    }>;
+    rejected?: Array<string | {
+        address: string;
+        name: string;
+    }>;
+}
+/** Small common contract; provider transports may omit verify when their API has no safe health check. */
+export interface IEmailTransport {
+    sendMail(message: ITransportMessage): Promise<ITransportSendInfo>;
+    verify?(): Promise<true>;
+    close?(): void;
+}
+//# sourceMappingURL=provider.interface.d.ts.map

package/dist/providers/provider.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.interface.d.ts","sourceRoot":"","sources":["../../src/providers/provider.interface.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,oCAAoC,CAAC;AAEjE,MAAM,WAAW,iBAAiB;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACtB,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACvB,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,WAAW,EAAE,CAAC;CAC7B;AAED,MAAM,WAAW,kBAAkB;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC7D,QAAQ,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC9D;AAED,0GAA0G;AAC1G,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAClE,MAAM,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,KAAK,CAAC,IAAI,IAAI,CAAC;CAChB"}

package/dist/providers/provider.interface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/providers/sendgrid.transport.d.ts

@@ -0,0 +1,10 @@
+import { ISendGridConfig } from '../core/interfaces/email.interface';
+import { ITransportMessage, ITransportSendInfo, IEmailTransport } from './provider.interface';
+export declare class SendGridTransport implements IEmailTransport {
+    private readonly config;
+    private readonly apiUrl;
+    private readonly fetchImpl;
+    constructor(config: ISendGridConfig, fetchImpl?: typeof fetch);
+    sendMail(message: ITransportMessage): Promise<ITransportSendInfo>;
+}
+//# sourceMappingURL=sendgrid.transport.d.ts.map

package/dist/providers/sendgrid.transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sendgrid.transport.d.ts","sourceRoot":"","sources":["../../src/providers/sendgrid.transport.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AACrE,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAG9F,qBAAa,iBAAkB,YAAW,eAAe;IAI3C,OAAO,CAAC,QAAQ,CAAC,MAAM;IAHnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;gBAEZ,MAAM,EAAE,eAAe,EAAE,SAAS,GAAE,OAAO,KAAa;IAU/E,QAAQ,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;CA6DxE"}

package/dist/providers/sendgrid.transport.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SendGridTransport = void 0;
+const provider_utils_1 = require("./provider-utils");
+class SendGridTransport {
+    config;
+    apiUrl;
+    fetchImpl;
+    constructor(config, fetchImpl = fetch) {
+        this.config = config;
+        (0, provider_utils_1.validateApiConfig)(config);
+        this.apiUrl = (config.apiUrl ?? 'https://api.sendgrid.com').replace(/\/+$/, '');
+        const parsedUrl = new URL(this.apiUrl);
+        if (parsedUrl.protocol !== 'https:' && parsedUrl.hostname !== 'localhost' && parsedUrl.hostname !== '127.0.0.1') {
+            throw new Error('SendGrid apiUrl must use HTTPS');
+        }
+        this.fetchImpl = fetchImpl;
+    }
+    async sendMail(message) {
+        const recipients = (0, provider_utils_1.parseMailboxes)(message.to);
+        if (recipients.length === 0)
+            throw new Error('SendGrid requires at least one recipient');
+        const from = (0, provider_utils_1.parseMailboxes)(message.from ?? this.config.defaultFrom)[0];
+        if (!from)
+            throw new Error('SendGrid requires a sender');
+        const content = [
+            ...(message.text !== undefined ? [{ type: 'text/plain', value: message.text }] : []),
+            ...(message.html !== undefined ? [{ type: 'text/html', value: message.html }] : [])
+        ];
+        if (content.length === 0)
+            throw new Error('SendGrid requires a text or HTML body');
+        const attachments = await Promise.all((message.attachments ?? []).map(async (attachment) => ({
+            content: (await (0, provider_utils_1.attachmentToBuffer)(attachment, this.config.maxAttachmentBytes)).toString('base64'),
+            filename: attachment.filename,
+            type: attachment.contentType ?? 'application/octet-stream',
+            disposition: attachment.cid ? 'inline' : 'attachment',
+            ...(attachment.cid ? { content_id: attachment.cid } : {})
+        })));
+        const payload = {
+            personalizations: [{
+                    to: recipients,
+                    ...(message.cc ? { cc: (0, provider_utils_1.parseMailboxes)(message.cc) } : {}),
+                    ...(message.bcc ? { bcc: (0, provider_utils_1.parseMailboxes)(message.bcc) } : {})
+                }],
+            from,
+            subject: message.subject,
+            content,
+            ...(attachments.length > 0 ? { attachments } : {})
+        };
+        const response = await this.fetchImpl(`${this.apiUrl}/v3/mail/send`, {
+            method: 'POST',
+            headers: {
+                authorization: `Bearer ${this.config.apiKey}`,
+                'content-type': 'application/json'
+            },
+            body: JSON.stringify(payload),
+            redirect: 'error',
+            signal: AbortSignal.timeout(this.config.requestTimeoutMs ?? 30_000)
+        });
+        if (response.status !== 202) {
+            const responseBody = await response.text();
+            const error = new Error(`SendGrid API returned HTTP ${response.status}${responseBody ? `: ${responseBody}` : ''}`);
+            Object.assign(error, { statusCode: response.status, responseBody });
+            throw error;
+        }
+        const accepted = [...recipients, ...(0, provider_utils_1.parseMailboxes)(message.cc), ...(0, provider_utils_1.parseMailboxes)(message.bcc)].map(({ email, name }) => name ? { address: email, name } : email);
+        const messageId = response.headers.get('x-message-id') ?? undefined;
+        return {
+            ...(messageId ? { messageId } : {}),
+            response: '202 Accepted',
+            accepted,
+            rejected: []
+        };
+    }
+}
+exports.SendGridTransport = SendGridTransport;

package/dist/queues/bullmq-email-queue.d.ts

@@ -0,0 +1,153 @@
+import { IAttachment, IEmailOptions, IEmailSendResult } from '../core/interfaces/email.interface';
+export interface IBullMQBackoffOptions {
+    type: 'fixed' | 'exponential';
+    delay: number;
+    jitter?: number;
+}
+export interface IEmailQueueJobOptions {
+    /** Stable business key. It is hashed before being used as a Redis job ID. */
+    idempotencyKey?: string;
+    delay?: number;
+    priority?: number;
+    attempts?: number;
+    backoff?: IBullMQBackoffOptions;
+}
+export interface IBullMQRateLimiterOptions {
+    max: number;
+    duration: number;
+}
+export interface IBullMQWorkerMetricsOptions {
+    /** Number of one-minute data points retained in Redis for completed/failed jobs. */
+    maxDataPoints: number;
+}
+export interface IBullMQEmailQueueConfig {
+    /** Redis/ioredis connection options. Keep credentials in a secret manager. */
+    connection: Record<string, unknown>;
+    queueName?: string;
+    prefix?: string;
+    concurrency?: number;
+    limiter?: IBullMQRateLimiterOptions;
+    workerMetrics?: IBullMQWorkerMetricsOptions;
+    maxPayloadBytes?: number;
+    maxBulkSize?: number;
+    defaultJobOptions?: {
+        attempts?: number;
+        backoff?: IBullMQBackoffOptions;
+        removeOnComplete?: boolean | number | {
+            age?: number;
+            count?: number;
+        };
+        removeOnFail?: boolean | number | {
+            age?: number;
+            count?: number;
+        };
+    };
+}
+export interface IEmailQueueSender {
+    sendEmail(options: IEmailOptions): Promise<IEmailSendResult>;
+}
+export interface IQueuedEmailJob {
+    id?: string;
+}
+export type ISerializedEmailAttachment = Omit<IAttachment, 'content'> & {
+    contentBase64?: string;
+};
+export interface IEmailQueueJobData {
+    version: 1;
+    email: Omit<IEmailOptions, 'template' | 'templateData' | 'attachments'> & {
+        attachments?: ISerializedEmailAttachment[];
+    };
+}
+export interface IBullMQJobLike {
+    id?: string | number;
+    name: string;
+    data: IEmailQueueJobData;
+}
+export interface IBullMQQueueMetrics {
+    data: number[];
+    count: number;
+    meta: {
+        count: number;
+        prevTS: number;
+        prevCount: number;
+    };
+}
+export interface IBullMQQueueEventPayload {
+    jobId?: string;
+    prev?: string;
+    failedReason?: string;
+    returnvalue?: unknown;
+    data?: unknown;
+    [key: string]: unknown;
+}
+export interface IBullMQQueueEventsLike {
+    on(event: string, listener: (payload: IBullMQQueueEventPayload) => void): this;
+    close(): Promise<void>;
+}
+interface IBullMQQueueLike {
+    add(name: string, data: IEmailQueueJobData, options?: Record<string, unknown>): Promise<IQueuedEmailJob>;
+    addBulk(jobs: Array<{
+        name: string;
+        data: IEmailQueueJobData;
+        opts?: Record<string, unknown>;
+    }>): Promise<IQueuedEmailJob[]>;
+    close(): Promise<void>;
+    pause(): Promise<void>;
+    resume(): Promise<void>;
+    getJobCounts(...types: string[]): Promise<Record<string, number>>;
+    exportPrometheusMetrics?(globalVariables?: Record<string, string>): Promise<string>;
+    getMetrics?(type: 'completed' | 'failed', start?: number, end?: number): Promise<IBullMQQueueMetrics>;
+}
+interface IBullMQWorkerLike {
+    close(): Promise<void>;
+}
+export interface IBullMQRuntime {
+    Queue: new (name: string, options: Record<string, unknown>) => IBullMQQueueLike;
+    Worker: new (name: string, processor: (job: IBullMQJobLike) => Promise<IEmailSendResult>, options: Record<string, unknown>) => IBullMQWorkerLike;
+    UnrecoverableError: new (message: string) => Error;
+    QueueEvents?: new (name: string, options: Record<string, unknown>) => IBullMQQueueEventsLike;
+}
+/**
+ * Redis-backed asynchronous email delivery using BullMQ. This class may be
+ * instantiated in producer and worker processes with the same queue settings.
+ */
+export declare class BullMQEmailQueue {
+    private readonly config;
+    readonly queueName: string;
+    private readonly runtime;
+    private readonly queue;
+    private readonly workers;
+    private readonly queueEvents;
+    private readonly maxPayloadBytes;
+    private readonly maxBulkSize;
+    private closed;
+    constructor(config: IBullMQEmailQueueConfig, runtime?: IBullMQRuntime);
+    /** Add one email job. Template rendering happens before enqueue so jobs stay serializable. */
+    enqueueEmail(options: IEmailOptions, job?: IEmailQueueJobOptions): Promise<IQueuedEmailJob>;
+    /** Add a bounded batch with one Redis bulk operation. BullMQ/Redis bulk calls can partially add jobs on failure. */
+    enqueueBulk(items: Array<{
+        email: IEmailOptions;
+        job?: IEmailQueueJobOptions;
+    }>): Promise<IQueuedEmailJob[]>;
+    /** Start a BullMQ Worker. Run this in dedicated worker processes for horizontal scaling. */
+    startWorker(sender: IEmailQueueSender, options?: {
+        concurrency?: number;
+        limiter?: IBullMQRateLimiterOptions;
+        metrics?: IBullMQWorkerMetricsOptions;
+    }): IBullMQWorkerLike;
+    pause(): Promise<void>;
+    resume(): Promise<void>;
+    getJobCounts(): Promise<Record<string, number>>;
+    /** Export queue counts in Prometheus text exposition format. */
+    exportPrometheusMetrics(globalVariables?: Record<string, string>): Promise<string>;
+    /** Read BullMQ's per-minute completed/failed worker metrics from Redis. */
+    getMetrics(type: 'completed' | 'failed', start?: number, end?: number): Promise<IBullMQQueueMetrics>;
+    /** Listen to lifecycle events across all workers using BullMQ QueueEvents. */
+    createQueueEvents(): IBullMQQueueEventsLike;
+    /** Gracefully wait for active workers and release the BullMQ queue connection. */
+    close(): Promise<void>;
+    private serializeEmail;
+    private assertOpen;
+}
+export {};
+//# sourceMappingURL=bullmq-email-queue.d.ts.map

package/dist/queues/bullmq-email-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bullmq-email-queue.d.ts","sourceRoot":"","sources":["../../src/queues/bullmq-email-queue.ts"],"names":[],"mappings":"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"}

package/dist/queues/bullmq-email-queue.js

@@ -0,0 +1,292 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BullMQEmailQueue = void 0;
+const crypto_1 = require("crypto");
+const module_1 = require("module");
+const loadOptionalModule = (0, module_1.createRequire)(__filename);
+function loadBullMQRuntime() {
+    try {
+        return loadOptionalModule('bullmq');
+    }
+    catch (error) {
+        throw new Error('BullMQ support requires the optional package bullmq. Install it with: npm install bullmq', { cause: error });
+    }
+}
+function assertPositiveInteger(name, value) {
+    if (value !== undefined && (!Number.isSafeInteger(value) || value <= 0)) {
+        throw new Error(`${name} must be a positive safe integer`);
+    }
+}
+function assertJobOptions(options) {
+    assertPositiveInteger('attempts', options.attempts);
+    if (options.delay !== undefined && (!Number.isSafeInteger(options.delay) || options.delay < 0)) {
+        throw new Error('delay must be a non-negative safe integer');
+    }
+    if (options.priority !== undefined && (!Number.isSafeInteger(options.priority) || options.priority < 0)) {
+        throw new Error('priority must be a non-negative safe integer');
+    }
+    if (options.backoff) {
+        assertPositiveInteger('backoff.delay', options.backoff.delay);
+        if (options.backoff.jitter !== undefined && (options.backoff.jitter < 0 || options.backoff.jitter > 1)) {
+            throw new Error('backoff.jitter must be between 0 and 1');
+        }
+    }
+    if (options.idempotencyKey !== undefined && !options.idempotencyKey.trim()) {
+        throw new Error('idempotencyKey must not be empty');
+    }
+}
+function jobOptions(options) {
+    const { idempotencyKey, ...bullOptions } = options;
+    return {
+        ...bullOptions,
+        ...(idempotencyKey ? { jobId: `email-${(0, crypto_1.createHash)('sha256').update(idempotencyKey).digest('hex')}` } : {})
+    };
+}
+function serializeAttachment(attachment) {
+    const { content, ...metadata } = attachment;
+    if (content === undefined)
+        return metadata;
+    const buffer = Buffer.isBuffer(content) ? content : Buffer.from(content);
+    return { ...metadata, contentBase64: buffer.toString('base64') };
+}
+function deserializeEmail(data) {
+    if (data?.version !== 1 || !data.email || typeof data.email !== 'object') {
+        throw new Error('Unsupported or malformed tzmail queue job payload');
+    }
+    const { attachments, ...message } = data.email;
+    return {
+        ...message,
+        ...(attachments ? {
+            attachments: attachments.map(({ contentBase64, ...attachment }) => ({
+                ...attachment,
+                ...(contentBase64 !== undefined ? { content: Buffer.from(contentBase64, 'base64') } : {})
+            }))
+        } : {})
+    };
+}
+/**
+ * Redis-backed asynchronous email delivery using BullMQ. This class may be
+ * instantiated in producer and worker processes with the same queue settings.
+ */
+class BullMQEmailQueue {
+    config;
+    queueName;
+    runtime;
+    queue;
+    workers = new Set();
+    queueEvents = new Set();
+    maxPayloadBytes;
+    maxBulkSize;
+    closed = false;
+    constructor(config, runtime) {
+        this.config = config;
+        if (!config.connection || typeof config.connection !== 'object') {
+            throw new Error('BullMQ Redis connection options are required');
+        }
+        this.queueName = config.queueName ?? 'tzmail-email';
+        if (!/^[A-Za-z0-9_-]{1,128}$/.test(this.queueName)) {
+            throw new Error('queueName must contain only letters, numbers, underscores or hyphens, with a maximum length of 128');
+        }
+        assertPositiveInteger('concurrency', config.concurrency);
+        assertPositiveInteger('maxPayloadBytes', config.maxPayloadBytes);
+        assertPositiveInteger('maxBulkSize', config.maxBulkSize);
+        assertPositiveInteger('defaultJobOptions.attempts', config.defaultJobOptions?.attempts);
+        assertPositiveInteger('workerMetrics.maxDataPoints', config.workerMetrics?.maxDataPoints);
+        if (config.defaultJobOptions?.backoff)
+            assertJobOptions({ backoff: config.defaultJobOptions.backoff });
+        if (config.limiter) {
+            assertPositiveInteger('limiter.max', config.limiter.max);
+            assertPositiveInteger('limiter.duration', config.limiter.duration);
+        }
+        this.maxPayloadBytes = config.maxPayloadBytes ?? 10 * 1024 * 1024;
+        this.maxBulkSize = config.maxBulkSize ?? 1_000;
+        this.runtime = runtime ?? loadBullMQRuntime();
+        this.queue = new this.runtime.Queue(this.queueName, {
+            connection: config.connection,
+            ...(config.prefix ? { prefix: config.prefix } : {}),
+            defaultJobOptions: {
+                attempts: 5,
+                backoff: { type: 'exponential', delay: 1_000, jitter: 0.2 },
+                removeOnComplete: { age: 86_400, count: 10_000 },
+                removeOnFail: { age: 604_800, count: 50_000 },
+                ...config.defaultJobOptions
+            }
+        });
+    }
+    /** Add one email job. Template rendering happens before enqueue so jobs stay serializable. */
+    async enqueueEmail(options, job = {}) {
+        this.assertOpen();
+        assertJobOptions(job);
+        const data = await this.serializeEmail(options);
+        return this.queue.add('send-email', data, jobOptions(job));
+    }
+    /** Add a bounded batch with one Redis bulk operation. BullMQ/Redis bulk calls can partially add jobs on failure. */
+    async enqueueBulk(items) {
+        this.assertOpen();
+        if (!Array.isArray(items))
+            throw new Error('items must be an array');
+        if (items.length === 0)
+            return [];
+        if (items.length > this.maxBulkSize) {
+            throw new Error(`Bulk exceeds configured maxBulkSize (${this.maxBulkSize})`);
+        }
+        if (items.some((item) => !item || !item.email)) {
+            throw new Error('Each bulk item requires an email message');
+        }
+        const keys = items.map((item) => item.job?.idempotencyKey).filter((key) => key !== undefined);
+        if (new Set(keys).size !== keys.length) {
+            throw new Error('idempotencyKey values must be unique within one bulk request');
+        }
+        const jobs = await Promise.all(items.map(async (item) => {
+            const options = item.job ?? {};
+            assertJobOptions(options);
+            return {
+                name: 'send-email',
+                data: await this.serializeEmail(item.email),
+                opts: jobOptions(options)
+            };
+        }));
+        return this.queue.addBulk(jobs);
+    }
+    /** Start a BullMQ Worker. Run this in dedicated worker processes for horizontal scaling. */
+    startWorker(sender, options = {}) {
+        this.assertOpen();
+        const concurrency = options.concurrency ?? this.config.concurrency ?? 5;
+        assertPositiveInteger('concurrency', concurrency);
+        const limiter = options.limiter ?? this.config.limiter;
+        const metrics = options.metrics ?? this.config.workerMetrics;
+        if (limiter) {
+            assertPositiveInteger('limiter.max', limiter.max);
+            assertPositiveInteger('limiter.duration', limiter.duration);
+        }
+        assertPositiveInteger('metrics.maxDataPoints', metrics?.maxDataPoints);
+        const worker = new this.runtime.Worker(this.queueName, async (job) => {
+            let email;
+            try {
+                email = deserializeEmail(job.data);
+            }
+            catch (error) {
+                throw new this.runtime.UnrecoverableError(error instanceof Error ? error.message : 'Malformed email job payload');
+            }
+            const result = await sender.sendEmail(email);
+            if (result.status === 'success')
+                return result;
+            if (result.status === 'partial') {
+                throw new this.runtime.UnrecoverableError('Email was accepted for only some recipients; automatic retry is disabled to avoid duplicate delivery.');
+            }
+            if (result.errorStage === 'validation' || result.errorStage === 'render') {
+                throw new this.runtime.UnrecoverableError(`Email job failed at ${result.errorStage} stage.`);
+            }
+            if (result.error instanceof Error)
+                throw result.error;
+            throw new Error(`Email job failed at ${result.errorStage ?? 'unknown'} stage.`);
+        }, {
+            connection: this.config.connection,
+            ...(this.config.prefix ? { prefix: this.config.prefix } : {}),
+            concurrency,
+            ...(limiter ? { limiter } : {}),
+            ...(metrics ? { metrics } : {})
+        });
+        this.workers.add(worker);
+        return worker;
+    }
+    pause() {
+        this.assertOpen();
+        return this.queue.pause();
+    }
+    resume() {
+        this.assertOpen();
+        return this.queue.resume();
+    }
+    getJobCounts() {
+        this.assertOpen();
+        return this.queue.getJobCounts('wait', 'active', 'completed', 'failed', 'delayed', 'paused');
+    }
+    /** Export queue counts in Prometheus text exposition format. */
+    async exportPrometheusMetrics(globalVariables) {
+        this.assertOpen();
+        if (!this.queue.exportPrometheusMetrics) {
+            throw new Error('The installed BullMQ version does not support exportPrometheusMetrics().');
+        }
+        return this.queue.exportPrometheusMetrics(globalVariables);
+    }
+    /** Read BullMQ's per-minute completed/failed worker metrics from Redis. */
+    async getMetrics(type, start = 0, end = -1) {
+        this.assertOpen();
+        if (!this.queue.getMetrics) {
+            throw new Error('The installed BullMQ version does not support getMetrics().');
+        }
+        return this.queue.getMetrics(type, start, end);
+    }
+    /** Listen to lifecycle events across all workers using BullMQ QueueEvents. */
+    createQueueEvents() {
+        this.assertOpen();
+        if (!this.runtime.QueueEvents) {
+            throw new Error('The installed BullMQ runtime does not expose QueueEvents.');
+        }
+        const events = new this.runtime.QueueEvents(this.queueName, {
+            connection: this.config.connection,
+            ...(this.config.prefix ? { prefix: this.config.prefix } : {})
+        });
+        this.queueEvents.add(events);
+        return events;
+    }
+    /** Gracefully wait for active workers and release the BullMQ queue connection. */
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        const workerResults = await Promise.allSettled([
+            ...[...this.workers].map((worker) => worker.close()),
+            ...[...this.queueEvents].map((events) => events.close())
+        ]);
+        this.workers.clear();
+        this.queueEvents.clear();
+        const errors = workerResults.flatMap((result) => result.status === 'rejected' ? [result.reason] : []);
+        try {
+            await this.queue.close();
+        }
+        catch (error) {
+            errors.push(error);
+        }
+        if (errors.length > 0) {
+            throw new AggregateError(errors, 'One or more BullMQ resources failed to close cleanly.');
+        }
+    }
+    async serializeEmail(options) {
+        if (!options || typeof options !== 'object')
+            throw new Error('Email options are required');
+        const template = options.template;
+        const attachments = options.attachments;
+        const message = { ...options };
+        delete message.template;
+        delete message.templateData;
+        delete message.attachments;
+        let html = message.html;
+        if (html === undefined && template) {
+            html = await template.render(options);
+        }
+        const serializedAttachments = attachments?.map(serializeAttachment);
+        const email = {
+            ...message,
+            ...(html !== undefined ? { html } : {}),
+            ...(serializedAttachments ? { attachments: serializedAttachments } : {})
+        };
+        let payload;
+        try {
+            payload = JSON.stringify({ version: 1, email });
+        }
+        catch (error) {
+            throw new Error('Email job payload must be JSON serializable; template functions are rendered before enqueue.', { cause: error });
+        }
+        if (Buffer.byteLength(payload, 'utf8') > this.maxPayloadBytes) {
+            throw new Error(`Email job payload exceeds configured maxPayloadBytes (${this.maxPayloadBytes})`);
+        }
+        return JSON.parse(payload);
+    }
+    assertOpen() {
+        if (this.closed)
+            throw new Error('BullMQEmailQueue is closed. Create a new instance to resume queue operations.');
+    }
+}
+exports.BullMQEmailQueue = BullMQEmailQueue;

package/dist/services/attachment.service.d.ts

@@ -1,46 +1,24 @@
 import { IAttachment } from '../core/interfaces/email.interface';
+export interface IAttachmentServiceOptions {
+    /** Restrict path attachments to this directory, resolved through realpath. */
+    allowedRoot?: string;
+    /** Optional maximum byte size for path- and buffer-backed attachments. */
+    maxSizeBytes?: number;
+}
 /**
- * AttachmentService - Gerencia anexos para emails
- *
- * Métodos:
- * - addFromPath(filePath: string, options?: Partial<IAttachment>): Promise<IAttachment>
- *   Adiciona um anexo a partir de um caminho de arquivo.
- *
- * - addFromBuffer(buffer: Buffer, filename: string, options?: Partial<IAttachment>): Promise<IAttachment>
- *   Adiciona um anexo a partir de um buffer em memória.
- *
- * - addFromUrl(url: string, filename: string): Promise<IAttachment>
- *   Adiciona um anexo a partir de uma URL (ainda não implementado).
- *
- * Exemplo de uso:
- *
- * const attachmentService = new AttachmentService();
- * const attachment = await attachmentService.addFromPath('path/to/file.pdf');
- *
- * emailFactory.sendEmail({
- *   to: 'user@example.com',
- *   subject: 'Assunto do Email',
- *   template: myTemplate,
- *   attachments: [{...attachment}]
- * });
+ * Creates Nodemailer attachment descriptors. Path attachments remain paths so
+ * Nodemailer can stream large files instead of loading them into memory.
+ * If allowedRoot is omitted, callers are responsible for supplying trusted paths.
  */
 export declare class AttachmentService {
-    /**
-     * addFromPath - Adiciona um anexo a partir de um caminho de arquivo
-     * @param filePath - Caminho do arquivo a ser anexado
-     * @param options - Opções adicionais para o anexo (filename, contentType, cid)
-     * @returns Promise<IAttachment> - Objeto de anexo formatado para Nodemailer
-     * @throws Error se o caminho não for um arquivo válido
-     */
+    private readonly options;
+    private readonly maxSizeBytes?;
+    constructor(options?: IAttachmentServiceOptions);
+    /** Add an attachment as a file path, preserving streaming behavior. */
     addFromPath(filePath: string, options?: Partial<IAttachment>): Promise<IAttachment>;
     addFromBuffer(buffer: Buffer, filename: string, options?: Partial<IAttachment>): Promise<IAttachment>;
-    /**
-     * addFromUrl - Adiciona um anexo a partir de uma URL (a ser implementado)
-     * @param url - URL do recurso a ser anexado
-     * @param filename - Nome do arquivo para o anexo
-     * @returns Promise<IAttachment> - Objeto de anexo formatado para Nodemailer
-     * @throws Error se o método não for implementado
-     */
+    /** URL attachments are deliberately not fetched by this service. */
     addFromUrl(url: string, filename: string): Promise<IAttachment>;
+    private assertSize;
 }
 //# sourceMappingURL=attachment.service.d.ts.map

package/dist/services/attachment.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"attachment.service.d.ts","sourceRoot":"","sources":["../../src/services/attachment.service.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,WAAW,EAAE,MAAM,oCAAoC,CAAC;AAEjE;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,iBAAiB;IAC5B;;;;;;OAMG;IACG,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC;IAcnF,aAAa,CACjB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC7B,OAAO,CAAC,WAAW,CAAC;IASvB;;;;;;OAMG;IACH,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;CAGhE"}
+{"version":3,"file":"attachment.service.d.ts","sourceRoot":"","sources":["../../src/services/attachment.service.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,MAAM,oCAAoC,CAAC;AAEjE,MAAM,WAAW,yBAAyB;IACxC,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;GAIG;AACH,qBAAa,iBAAiB;IAGhB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAFpC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAS;gBAEV,OAAO,GAAE,yBAA8B;IAQpE,uEAAuE;IACjE,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC;IAoCnF,aAAa,CACjB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC7B,OAAO,CAAC,WAAW,CAAC;IAiBvB,oEAAoE;IACpE,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAM/D,OAAO,CAAC,UAAU;CAKnB"}