@venizia/ignis 0.4.2 → 0.4.4

package/dist/esm/components/mail/helpers/executors/bull-mq-executor.helper.js

@@ -0,0 +1,245 @@
+import { BaseHelper, getError } from '@venizia/ignis-helpers/core';
+import { RedisSingleHelper } from '@venizia/ignis-helpers';
+import { BullMQHelper } from '@venizia/ignis-helpers/bullmq';
+import { BullMQExecutorModes, MailBackoffTypes, MailErrorCodes, MailExecutorErrors, } from '../../common/index.js';
+export class BullMQMailExecutorHelper extends BaseHelper {
+    constructor(opts) {
+        super({ scope: BullMQMailExecutorHelper.name });
+        this.workerHelpers = [];
+        this.jobIdCounter = 0;
+        this.mode = opts.mode;
+        this.redisConnection = new RedisSingleHelper({
+            ...opts.redis,
+            maxRetry: undefined,
+        });
+        this.bullmqModule = opts.module;
+        this.queueIdentifier = opts.queue.identifier;
+        this.queueName = opts.queue.name;
+        this.initQueue(opts.queue);
+    }
+    initQueue(queue) {
+        switch (this.mode) {
+            case BullMQExecutorModes.QUEUE_ONLY:
+            case BullMQExecutorModes.BOTH: {
+                this.queueHelper = new BullMQHelper({
+                    identifier: queue.identifier,
+                    queueName: queue.name,
+                    redisConnection: this.redisConnection,
+                    role: 'queue',
+                    module: this.bullmqModule,
+                });
+                this.logger
+                    .for(this.constructor.name)
+                    .info('BullMQ queue executor initialized (queue enabled) | Identifier: %s | Mode: %s', this.queueIdentifier, this.mode);
+                break;
+            }
+            default: {
+                this.logger
+                    .for(this.constructor.name)
+                    .info('BullMQ queue executor initialized (worker-only mode) | Identifier: %s | Mode: %s', this.queueIdentifier, this.mode);
+                break;
+            }
+        }
+    }
+    async setProcessor(processor, opts) {
+        this.processor = processor;
+        if (this.mode === BullMQExecutorModes.QUEUE_ONLY) {
+            this.logger
+                .for(this.setProcessor.name)
+                .warn('Skipping worker creation in queue-only mode. Workers will not be started.');
+            return;
+        }
+        const numberOfWorkers = opts?.numberOfWorkers ?? 1;
+        const concurrencyPerWorker = opts?.concurrencyPerWorker ?? 5;
+        const lockDuration = opts?.lockDuration ?? 30000;
+        await this.clearWorkers();
+        for (let i = 0; i < numberOfWorkers; i++) {
+            this.addWorker({
+                workerIdentifier: `${this.queueIdentifier}-worker-${i}`,
+                concurrency: concurrencyPerWorker,
+                lockDuration,
+            });
+        }
+        this.logger
+            .for(this.setProcessor.name)
+            .info('Processor registered | Mode: %s | Workers: %d | Concurrency per worker: %d', this.mode, numberOfWorkers, concurrencyPerWorker);
+    }
+    addWorker(opts) {
+        if (!this.processor) {
+            throw getError({ message: MailExecutorErrors.PROCESSOR_NOT_SET });
+        }
+        const workerIdentifier = opts.workerIdentifier;
+        const concurrency = opts?.concurrency ?? 5;
+        const lockDuration = opts?.lockDuration ?? 30000;
+        const workerHelper = new BullMQHelper({
+            identifier: workerIdentifier,
+            queueName: this.queueName,
+            redisConnection: this.redisConnection,
+            role: 'worker',
+            module: this.bullmqModule,
+            numberOfWorker: concurrency,
+            lockDuration,
+            onWorkerData: async (job) => {
+                const maxAttempts = job.data.options?.attempts ?? 3;
+                this.logger
+                    .for('onWorkerData')
+                    .info('Processing job | Worker: %s | jobId: %s | email: %s | attempt: %d/%d', workerIdentifier, job.data.id, job.data.email, job.attemptsMade + 1, maxAttempts);
+                if (!this.processor) {
+                    // Returning undefined would let BullMQ mark the job COMPLETED and (with removeOnComplete) delete it - mail silently dropped.
+                    throw getError({
+                        messageCode: MailErrorCodes.SEND_FAILED,
+                        message: `[onWorkerData] ${MailExecutorErrors.PROCESSOR_NOT_SET} | jobId: ${job.data.id}`,
+                    });
+                }
+                const result = await this.processor(job.data.email);
+                // A processor reports SMTP rejection by RETURNING `{ success: false }`; BullMQ only treats a REJECTION as failure, so resolving completes the job - no retry, no DLQ.
+                if (result?.success === false) {
+                    throw getError({
+                        messageCode: MailErrorCodes.SEND_FAILED,
+                        message: `[onWorkerData] Processor reported failure | jobId: ${job.data.id} | reason: ${result.message}`,
+                    });
+                }
+                return result;
+            },
+            onWorkerDataCompleted: async (job) => {
+                this.logger
+                    .for('onWorkerDataCompleted')
+                    .info('Job completed | Worker: %s | jobId: %s | email: %s', workerIdentifier, job.data.id, job.data.email);
+            },
+            onWorkerDataFail: async (job, error) => {
+                if (job) {
+                    const maxAttempts = job.data.options?.attempts ?? 3;
+                    this.logger
+                        .for('onWorkerDataFail')
+                        .error('Job failed | Worker: %s | jobId: %s | email: %s | attempt: %d/%d | error: %s', workerIdentifier, job.data.id, job.data.email, job.attemptsMade, maxAttempts, error.message);
+                }
+                else {
+                    this.logger
+                        .for('onWorkerDataFail')
+                        .error('Worker error (no job) | Worker: %s | error: %s', workerIdentifier, error.message);
+                }
+            },
+        });
+        this.workerHelpers.push(workerHelper);
+        this.logger
+            .for(this.addWorker.name)
+            .info('Worker added | Identifier: %s | Concurrency: %d | Total workers: %d', workerIdentifier, concurrency, this.workerHelpers.length);
+    }
+    async removeWorker(index) {
+        if (index < 0 || index >= this.workerHelpers.length) {
+            this.logger.for(this.removeWorker.name).warn('Invalid worker index: %d', index);
+            return false;
+        }
+        // Dropped from the list BEFORE the close is awaited: a rejecting close must not leave a half-closed worker still counted and still handed jobs.
+        const [workerHelper] = this.workerHelpers.splice(index, 1);
+        await workerHelper.worker.close();
+        this.logger
+            .for(this.removeWorker.name)
+            .info('Worker removed | Index: %d | Remaining workers: %d', index, this.workerHelpers.length);
+        return true;
+    }
+    /** Closes every worker without stopping at the first failure, always empties the list, and returns failures instead of throwing so teardown can continue. */
+    async closeWorkers() {
+        const workerHelpers = this.workerHelpers;
+        this.workerHelpers = [];
+        const results = await Promise.allSettled(workerHelpers.map((workerHelper) => workerHelper.worker.close()));
+        const failures = [];
+        for (const result of results) {
+            if (result.status !== 'rejected') {
+                continue;
+            }
+            const error = result.reason instanceof Error
+                ? result.reason
+                : getError({ message: `Worker close failed | reason: ${String(result.reason)}` });
+            failures.push(error);
+            this.logger.for('closeWorkers').error('Failed to close worker | error: %s', error.message);
+        }
+        return failures;
+    }
+    async clearWorkers() {
+        const count = this.workerHelpers.length;
+        await this.closeWorkers();
+        this.logger.for(this.clearWorkers.name).info('All workers cleared | Count: %d', count);
+    }
+    /** Full teardown: workers -> queue -> Redis. Every step runs even if an earlier one failed (skipping leaks a queue client + Redis socket); failures are reported once, at the end. */
+    async close() {
+        const failures = [...(await this.closeWorkers())];
+        if (this.queueHelper) {
+            try {
+                await this.queueHelper.queue.close();
+            }
+            catch (error) {
+                const closeError = error instanceof Error ? error : getError({ message: String(error) });
+                failures.push(closeError);
+                this.logger.for(this.close.name).error('Failed to close queue | error: %s', closeError);
+            }
+        }
+        try {
+            await this.redisConnection.disconnect();
+        }
+        catch (error) {
+            const disconnectError = error instanceof Error ? error : getError({ message: String(error) });
+            failures.push(disconnectError);
+            this.logger
+                .for(this.close.name)
+                .error('Failed to disconnect redis | error: %s', disconnectError);
+        }
+        if (failures.length > 0) {
+            throw getError({
+                message: `[close] Incomplete BullMQ mail executor teardown | failures: ${failures
+                    .map((failure) => failure.message)
+                    .join(' | ')}`,
+            });
+        }
+        this.logger.for(this.close.name).info('BullMQ mail executor closed | Mode: %s', this.mode);
+    }
+    getWorkerCount() {
+        return this.workerHelpers.length;
+    }
+    getMode() {
+        return this.mode;
+    }
+    async enqueueVerificationEmail(email, options) {
+        if (this.mode === BullMQExecutorModes.WORKER_ONLY) {
+            throw getError({
+                message: 'Cannot enqueue jobs in worker-only mode. Set mode to "queue-only" or "both".',
+            });
+        }
+        if (!this.queueHelper) {
+            throw getError({
+                message: 'Queue helper not initialized. This should not happen in queue-enabled mode.',
+            });
+        }
+        if (!this.processor && this.mode !== BullMQExecutorModes.QUEUE_ONLY) {
+            throw getError({ message: MailExecutorErrors.PROCESSOR_NOT_SET });
+        }
+        const jobId = `job_${++this.jobIdCounter}_${Date.now()}`;
+        const job = {
+            id: jobId,
+            email,
+            options,
+            attempts: 0,
+            scheduledAt: Date.now() + (options?.delay ?? 0),
+        };
+        this.logger
+            .for(this.enqueueVerificationEmail.name)
+            .info('Queuing email to BullMQ/Redis | jobId: %s | email: %s | mode: %s', jobId, email, this.mode);
+        const bullJob = await this.queueHelper.queue.add('send-verification-email', job, {
+            priority: options?.priority,
+            delay: options?.delay,
+            attempts: options?.attempts ?? 3,
+            backoff: {
+                type: options?.backoff?.type ?? MailBackoffTypes.EXPONENTIAL,
+                delay: options?.backoff?.delay ?? 1000,
+            },
+            removeOnComplete: true,
+            removeOnFail: false,
+        });
+        return {
+            jobId: bullJob.id ?? jobId,
+            queued: true,
+            message: 'Email queued successfully (BullMQ/Redis)',
+        };
+    }
+}
+//# sourceMappingURL=bull-mq-executor.helper.js.map

package/dist/esm/components/mail/helpers/executors/bull-mq-executor.helper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bull-mq-executor.helper.js","sourceRoot":"","sources":["../../../../../../src/components/mail/helpers/executors/bull-mq-executor.helper.ts"],"names":[],"mappings":"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","sourcesContent":["import { BaseHelper, getError } from '@venizia/ignis-helpers/core';\nimport { RedisSingleHelper } from '@venizia/ignis-helpers';\nimport type { TConstValue } from '@/helpers';\nimport { BullMQHelper } from '@venizia/ignis-helpers/bullmq';\nimport type {\n  IBullMQMailExecutorOpts,\n  IMailProcessorResult,\n  IMailQueueExecutor,\n  IMailQueueOptions,\n  IMailQueueResult,\n  IQueueJobPayload,\n} from '../../common';\nimport {\n  BullMQExecutorModes,\n  MailBackoffTypes,\n  MailErrorCodes,\n  MailExecutorErrors,\n} from '../../common';\nimport type { Job } from 'bullmq';\n\nexport class BullMQMailExecutorHelper extends BaseHelper implements IMailQueueExecutor {\n  private queueIdentifier: string;\n  private queueName: string;\n  private mode: TConstValue<typeof BullMQExecutorModes>;\n\n  private queueHelper?: BullMQHelper<IQueueJobPayload, IMailQueueResult>;\n  private workerHelpers: BullMQHelper<IQueueJobPayload, IMailProcessorResult>[] = [];\n  private redisConnection: RedisSingleHelper;\n  private readonly bullmqModule?: typeof import('bullmq');\n  private jobIdCounter = 0;\n\n  private processor?: (email: string) => Promise<IMailProcessorResult>;\n\n  constructor(opts: IBullMQMailExecutorOpts) {\n    super({ scope: BullMQMailExecutorHelper.name });\n\n    this.mode = opts.mode;\n\n    this.redisConnection = new RedisSingleHelper({\n      ...opts.redis,\n      maxRetry: undefined,\n    });\n\n    this.bullmqModule = opts.module;\n    this.queueIdentifier = opts.queue.identifier;\n    this.queueName = opts.queue.name;\n\n    this.initQueue(opts.queue);\n  }\n\n  initQueue(queue: { identifier: string; name: string }) {\n    switch (this.mode) {\n      case BullMQExecutorModes.QUEUE_ONLY:\n      case BullMQExecutorModes.BOTH: {\n        this.queueHelper = new BullMQHelper<IQueueJobPayload, IMailQueueResult>({\n          identifier: queue.identifier,\n          queueName: queue.name,\n          redisConnection: this.redisConnection,\n          role: 'queue',\n          module: this.bullmqModule,\n        });\n\n        this.logger\n          .for(this.constructor.name)\n          .info(\n            'BullMQ queue executor initialized (queue enabled) | Identifier: %s | Mode: %s',\n            this.queueIdentifier,\n            this.mode,\n          );\n        break;\n      }\n      default: {\n        this.logger\n          .for(this.constructor.name)\n          .info(\n            'BullMQ queue executor initialized (worker-only mode) | Identifier: %s | Mode: %s',\n            this.queueIdentifier,\n            this.mode,\n          );\n\n        break;\n      }\n    }\n  }\n\n  async setProcessor(\n    processor: (email: string) => Promise<IMailProcessorResult>,\n    opts?: {\n      numberOfWorkers?: number;\n      concurrencyPerWorker?: number;\n      lockDuration?: number;\n    },\n  ): Promise<void> {\n    this.processor = processor;\n\n    if (this.mode === BullMQExecutorModes.QUEUE_ONLY) {\n      this.logger\n        .for(this.setProcessor.name)\n        .warn('Skipping worker creation in queue-only mode. Workers will not be started.');\n      return;\n    }\n\n    const numberOfWorkers = opts?.numberOfWorkers ?? 1;\n    const concurrencyPerWorker = opts?.concurrencyPerWorker ?? 5;\n    const lockDuration = opts?.lockDuration ?? 30000;\n\n    await this.clearWorkers();\n\n    for (let i = 0; i < numberOfWorkers; i++) {\n      this.addWorker({\n        workerIdentifier: `${this.queueIdentifier}-worker-${i}`,\n        concurrency: concurrencyPerWorker,\n        lockDuration,\n      });\n    }\n\n    this.logger\n      .for(this.setProcessor.name)\n      .info(\n        'Processor registered | Mode: %s | Workers: %d | Concurrency per worker: %d',\n        this.mode,\n        numberOfWorkers,\n        concurrencyPerWorker,\n      );\n  }\n\n  addWorker(opts: { workerIdentifier: string; concurrency?: number; lockDuration?: number }): void {\n    if (!this.processor) {\n      throw getError({ message: MailExecutorErrors.PROCESSOR_NOT_SET });\n    }\n\n    const workerIdentifier = opts.workerIdentifier;\n    const concurrency = opts?.concurrency ?? 5;\n    const lockDuration = opts?.lockDuration ?? 30000;\n\n    const workerHelper = new BullMQHelper<IQueueJobPayload, IMailProcessorResult>({\n      identifier: workerIdentifier,\n      queueName: this.queueName,\n      redisConnection: this.redisConnection,\n      role: 'worker',\n      module: this.bullmqModule,\n      numberOfWorker: concurrency,\n      lockDuration,\n      onWorkerData: async (job: Job<IQueueJobPayload, IMailProcessorResult>) => {\n        const maxAttempts = job.data.options?.attempts ?? 3;\n\n        this.logger\n          .for('onWorkerData')\n          .info(\n            'Processing job | Worker: %s | jobId: %s | email: %s | attempt: %d/%d',\n            workerIdentifier,\n            job.data.id,\n            job.data.email,\n            job.attemptsMade + 1,\n            maxAttempts,\n          );\n\n        if (!this.processor) {\n          // Returning undefined would let BullMQ mark the job COMPLETED and (with removeOnComplete) delete it - mail silently dropped.\n          throw getError({\n            messageCode: MailErrorCodes.SEND_FAILED,\n            message: `[onWorkerData] ${MailExecutorErrors.PROCESSOR_NOT_SET} | jobId: ${job.data.id}`,\n          });\n        }\n\n        const result = await this.processor(job.data.email);\n\n        // A processor reports SMTP rejection by RETURNING `{ success: false }`; BullMQ only treats a REJECTION as failure, so resolving completes the job - no retry, no DLQ.\n        if (result?.success === false) {\n          throw getError({\n            messageCode: MailErrorCodes.SEND_FAILED,\n            message: `[onWorkerData] Processor reported failure | jobId: ${job.data.id} | reason: ${result.message}`,\n          });\n        }\n\n        return result;\n      },\n      onWorkerDataCompleted: async (job: Job<IQueueJobPayload, IMailProcessorResult>) => {\n        this.logger\n          .for('onWorkerDataCompleted')\n          .info(\n            'Job completed | Worker: %s | jobId: %s | email: %s',\n            workerIdentifier,\n            job.data.id,\n            job.data.email,\n          );\n      },\n      onWorkerDataFail: async (\n        job: Job<IQueueJobPayload, IMailProcessorResult> | undefined,\n        error: Error,\n      ) => {\n        if (job) {\n          const maxAttempts = job.data.options?.attempts ?? 3;\n          this.logger\n            .for('onWorkerDataFail')\n            .error(\n              'Job failed | Worker: %s | jobId: %s | email: %s | attempt: %d/%d | error: %s',\n              workerIdentifier,\n              job.data.id,\n              job.data.email,\n              job.attemptsMade,\n              maxAttempts,\n              error.message,\n            );\n        } else {\n          this.logger\n            .for('onWorkerDataFail')\n            .error(\n              'Worker error (no job) | Worker: %s | error: %s',\n              workerIdentifier,\n              error.message,\n            );\n        }\n      },\n    });\n\n    this.workerHelpers.push(workerHelper);\n\n    this.logger\n      .for(this.addWorker.name)\n      .info(\n        'Worker added | Identifier: %s | Concurrency: %d | Total workers: %d',\n        workerIdentifier,\n        concurrency,\n        this.workerHelpers.length,\n      );\n  }\n\n  async removeWorker(index: number): Promise<boolean> {\n    if (index < 0 || index >= this.workerHelpers.length) {\n      this.logger.for(this.removeWorker.name).warn('Invalid worker index: %d', index);\n      return false;\n    }\n\n    // Dropped from the list BEFORE the close is awaited: a rejecting close must not leave a half-closed worker still counted and still handed jobs.\n    const [workerHelper] = this.workerHelpers.splice(index, 1);\n    await workerHelper.worker.close();\n\n    this.logger\n      .for(this.removeWorker.name)\n      .info('Worker removed | Index: %d | Remaining workers: %d', index, this.workerHelpers.length);\n\n    return true;\n  }\n\n  /** Closes every worker without stopping at the first failure, always empties the list, and returns failures instead of throwing so teardown can continue. */\n  private async closeWorkers(): Promise<Error[]> {\n    const workerHelpers = this.workerHelpers;\n    this.workerHelpers = [];\n\n    const results = await Promise.allSettled(\n      workerHelpers.map((workerHelper) => workerHelper.worker.close()),\n    );\n\n    const failures: Error[] = [];\n\n    for (const result of results) {\n      if (result.status !== 'rejected') {\n        continue;\n      }\n\n      const error =\n        result.reason instanceof Error\n          ? result.reason\n          : getError({ message: `Worker close failed | reason: ${String(result.reason)}` });\n\n      failures.push(error);\n      this.logger.for('closeWorkers').error('Failed to close worker | error: %s', error.message);\n    }\n\n    return failures;\n  }\n\n  async clearWorkers(): Promise<void> {\n    const count = this.workerHelpers.length;\n    await this.closeWorkers();\n\n    this.logger.for(this.clearWorkers.name).info('All workers cleared | Count: %d', count);\n  }\n\n  /** Full teardown: workers -> queue -> Redis. Every step runs even if an earlier one failed (skipping leaks a queue client + Redis socket); failures are reported once, at the end. */\n  async close(): Promise<void> {\n    const failures: Error[] = [...(await this.closeWorkers())];\n\n    if (this.queueHelper) {\n      try {\n        await this.queueHelper.queue.close();\n      } catch (error) {\n        const closeError = error instanceof Error ? error : getError({ message: String(error) });\n        failures.push(closeError);\n        this.logger.for(this.close.name).error('Failed to close queue | error: %s', closeError);\n      }\n    }\n\n    try {\n      await this.redisConnection.disconnect();\n    } catch (error) {\n      const disconnectError = error instanceof Error ? error : getError({ message: String(error) });\n      failures.push(disconnectError);\n      this.logger\n        .for(this.close.name)\n        .error('Failed to disconnect redis | error: %s', disconnectError);\n    }\n\n    if (failures.length > 0) {\n      throw getError({\n        message: `[close] Incomplete BullMQ mail executor teardown | failures: ${failures\n          .map((failure) => failure.message)\n          .join(' | ')}`,\n      });\n    }\n\n    this.logger.for(this.close.name).info('BullMQ mail executor closed | Mode: %s', this.mode);\n  }\n\n  getWorkerCount(): number {\n    return this.workerHelpers.length;\n  }\n\n  getMode(): TConstValue<typeof BullMQExecutorModes> {\n    return this.mode;\n  }\n\n  async enqueueVerificationEmail(\n    email: string,\n    options?: IMailQueueOptions,\n  ): Promise<IMailQueueResult> {\n    if (this.mode === BullMQExecutorModes.WORKER_ONLY) {\n      throw getError({\n        message: 'Cannot enqueue jobs in worker-only mode. Set mode to \"queue-only\" or \"both\".',\n      });\n    }\n\n    if (!this.queueHelper) {\n      throw getError({\n        message: 'Queue helper not initialized. This should not happen in queue-enabled mode.',\n      });\n    }\n\n    if (!this.processor && this.mode !== BullMQExecutorModes.QUEUE_ONLY) {\n      throw getError({ message: MailExecutorErrors.PROCESSOR_NOT_SET });\n    }\n\n    const jobId = `job_${++this.jobIdCounter}_${Date.now()}`;\n    const job: IQueueJobPayload = {\n      id: jobId,\n      email,\n      options,\n      attempts: 0,\n      scheduledAt: Date.now() + (options?.delay ?? 0),\n    };\n\n    this.logger\n      .for(this.enqueueVerificationEmail.name)\n      .info(\n        'Queuing email to BullMQ/Redis | jobId: %s | email: %s | mode: %s',\n        jobId,\n        email,\n        this.mode,\n      );\n\n    const bullJob = await this.queueHelper.queue.add('send-verification-email', job, {\n      priority: options?.priority,\n      delay: options?.delay,\n      attempts: options?.attempts ?? 3,\n      backoff: {\n        type: options?.backoff?.type ?? MailBackoffTypes.EXPONENTIAL,\n        delay: options?.backoff?.delay ?? 1000,\n      },\n      removeOnComplete: true,\n      removeOnFail: false,\n    });\n\n    return {\n      jobId: bullJob.id ?? jobId,\n      queued: true,\n      message: 'Email queued successfully (BullMQ/Redis)',\n    };\n  }\n}\n"]}

package/dist/esm/components/mail/helpers/executors/direct-executor.helper.d.ts

@@ -0,0 +1,9 @@
+import { BaseHelper } from '@venizia/ignis-helpers/core';
+import type { IMailProcessorResult, IMailQueueExecutor, IMailQueueOptions, IMailQueueResult } from '../../common/index.js';
+export declare class DirectMailExecutorHelper extends BaseHelper implements IMailQueueExecutor {
+    private processor?;
+    constructor();
+    setProcessor(processor: (email: string) => Promise<IMailProcessorResult>): void;
+    enqueueVerificationEmail(email: string, _options?: IMailQueueOptions): Promise<IMailQueueResult>;
+}
+//# sourceMappingURL=direct-executor.helper.d.ts.map

package/dist/esm/components/mail/helpers/executors/direct-executor.helper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"direct-executor.helper.d.ts","sourceRoot":"","sources":["../../../../../../src/components/mail/helpers/executors/direct-executor.helper.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAY,MAAM,6BAA6B,CAAC;AACnE,OAAO,KAAK,EACV,oBAAoB,EACpB,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EACjB,MAAM,cAAc,CAAC;AAGtB,qBAAa,wBAAyB,SAAQ,UAAW,YAAW,kBAAkB;IACpF,OAAO,CAAC,SAAS,CAAC,CAAmD;;IAMrE,YAAY,CAAC,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,oBAAoB,CAAC,GAAG,IAAI;IAIzE,wBAAwB,CAC5B,KAAK,EAAE,MAAM,EACb,QAAQ,CAAC,EAAE,iBAAiB,GAC3B,OAAO,CAAC,gBAAgB,CAAC;CAgB7B"}

package/dist/esm/components/mail/helpers/executors/direct-executor.helper.js

@@ -0,0 +1,25 @@
+import { BaseHelper, getError } from '@venizia/ignis-helpers/core';
+import { MailExecutorErrors } from '../../common/index.js';
+export class DirectMailExecutorHelper extends BaseHelper {
+    constructor() {
+        super({ scope: DirectMailExecutorHelper.name });
+    }
+    setProcessor(processor) {
+        this.processor = processor;
+    }
+    async enqueueVerificationEmail(email, _options) {
+        if (!this.processor) {
+            throw getError({ message: MailExecutorErrors.PROCESSOR_NOT_SET });
+        }
+        this.logger
+            .for(this.enqueueVerificationEmail.name)
+            .info('Executing immediately (no queue) for: %s', email);
+        const result = await this.processor(email);
+        return {
+            queued: false,
+            message: 'Email sent immediately (no queue)',
+            result,
+        };
+    }
+}
+//# sourceMappingURL=direct-executor.helper.js.map

package/dist/esm/components/mail/helpers/executors/direct-executor.helper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"direct-executor.helper.js","sourceRoot":"","sources":["../../../../../../src/components/mail/helpers/executors/direct-executor.helper.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AAOnE,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAElD,MAAM,OAAO,wBAAyB,SAAQ,UAAU;IAGtD;QACE,KAAK,CAAC,EAAE,KAAK,EAAE,wBAAwB,CAAC,IAAI,EAAE,CAAC,CAAC;IAClD,CAAC;IAED,YAAY,CAAC,SAA2D;QACtE,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;IAED,KAAK,CAAC,wBAAwB,CAC5B,KAAa,EACb,QAA4B;QAE5B,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;YACpB,MAAM,QAAQ,CAAC,EAAE,OAAO,EAAE,kBAAkB,CAAC,iBAAiB,EAAE,CAAC,CAAC;QACpE,CAAC;QAED,IAAI,CAAC,MAAM;aACR,GAAG,CAAC,IAAI,CAAC,wBAAwB,CAAC,IAAI,CAAC;aACvC,IAAI,CAAC,0CAA0C,EAAE,KAAK,CAAC,CAAC;QAC3D,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QAE3C,OAAO;YACL,MAAM,EAAE,KAAK;YACb,OAAO,EAAE,mCAAmC;YAC5C,MAAM;SACP,CAAC;IACJ,CAAC;CACF","sourcesContent":["import { BaseHelper, getError } from '@venizia/ignis-helpers/core';\nimport type {\n  IMailProcessorResult,\n  IMailQueueExecutor,\n  IMailQueueOptions,\n  IMailQueueResult,\n} from '../../common';\nimport { MailExecutorErrors } from '../../common';\n\nexport class DirectMailExecutorHelper extends BaseHelper implements IMailQueueExecutor {\n  private processor?: (email: string) => Promise<IMailProcessorResult>;\n\n  constructor() {\n    super({ scope: DirectMailExecutorHelper.name });\n  }\n\n  setProcessor(processor: (email: string) => Promise<IMailProcessorResult>): void {\n    this.processor = processor;\n  }\n\n  async enqueueVerificationEmail(\n    email: string,\n    _options?: IMailQueueOptions,\n  ): Promise<IMailQueueResult> {\n    if (!this.processor) {\n      throw getError({ message: MailExecutorErrors.PROCESSOR_NOT_SET });\n    }\n\n    this.logger\n      .for(this.enqueueVerificationEmail.name)\n      .info('Executing immediately (no queue) for: %s', email);\n    const result = await this.processor(email);\n\n    return {\n      queued: false,\n      message: 'Email sent immediately (no queue)',\n      result,\n    };\n  }\n}\n"]}

package/dist/esm/components/mail/helpers/executors/index.d.ts

@@ -0,0 +1,4 @@
+export * from './bull-mq-executor.helper.js';
+export * from './direct-executor.helper.js';
+export * from './internal-queue-executor.helper.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/components/mail/helpers/executors/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../src/components/mail/helpers/executors/index.ts"],"names":[],"mappings":"AAAA,cAAc,2BAA2B,CAAC;AAC1C,cAAc,0BAA0B,CAAC;AACzC,cAAc,kCAAkC,CAAC"}

package/dist/esm/components/mail/helpers/executors/index.js

@@ -0,0 +1,4 @@
+export * from './bull-mq-executor.helper.js';
+export * from './direct-executor.helper.js';
+export * from './internal-queue-executor.helper.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/components/mail/helpers/executors/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../src/components/mail/helpers/executors/index.ts"],"names":[],"mappings":"AAAA,cAAc,2BAA2B,CAAC;AAC1C,cAAc,0BAA0B,CAAC;AACzC,cAAc,kCAAkC,CAAC","sourcesContent":["export * from './bull-mq-executor.helper';\nexport * from './direct-executor.helper';\nexport * from './internal-queue-executor.helper';\n"]}

package/dist/esm/components/mail/helpers/executors/internal-queue-executor.helper.d.ts

@@ -0,0 +1,16 @@
+import { BaseHelper } from '@venizia/ignis-helpers/core';
+import type { IMailQueueOptions, IMailQueueExecutor, IMailProcessorResult, IInternalQueueMailExecutorOpts, IMailQueueResult } from '../../common/index.js';
+export declare class InternalQueueMailExecutorHelper extends BaseHelper implements IMailQueueExecutor {
+    private queue;
+    private jobIdCounter;
+    private delayedJobs;
+    private processor?;
+    constructor(opts: IInternalQueueMailExecutorOpts);
+    setProcessor(processor: (email: string) => Promise<IMailProcessorResult>): void;
+    enqueueVerificationEmail(email: string, options?: IMailQueueOptions): Promise<IMailQueueResult>;
+    /** Releases every pending delayed/backoff timer - a live `setTimeout` holds the event loop open past the executor. */
+    close(): Promise<void>;
+    private processJob;
+    private calculateBackoff;
+}
+//# sourceMappingURL=internal-queue-executor.helper.d.ts.map

package/dist/esm/components/mail/helpers/executors/internal-queue-executor.helper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal-queue-executor.helper.d.ts","sourceRoot":"","sources":["../../../../../../src/components/mail/helpers/executors/internal-queue-executor.helper.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAY,MAAM,6BAA6B,CAAC;AAEnE,OAAO,KAAK,EACV,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,EACpB,8BAA8B,EAC9B,gBAAgB,EAEjB,MAAM,cAAc,CAAC;AAGtB,qBAAa,+BAAgC,SAAQ,UAAW,YAAW,kBAAkB;IAC3F,OAAO,CAAC,KAAK,CAA0C;IACvD,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,WAAW,CAA0C;IAE7D,OAAO,CAAC,SAAS,CAAC,CAAmD;gBAEzD,IAAI,EAAE,8BAA8B;IA0BhD,YAAY,CAAC,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,oBAAoB,CAAC,GAAG,IAAI;IAKzE,wBAAwB,CAC5B,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,gBAAgB,CAAC;IA4C5B,sHAAsH;IAChH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAad,UAAU;IAuExB,OAAO,CAAC,gBAAgB;CAazB"}

package/dist/esm/components/mail/helpers/executors/internal-queue-executor.helper.js

@@ -0,0 +1,134 @@
+import { BaseHelper, getError } from '@venizia/ignis-helpers/core';
+import { SequentialQueueHelper } from '@venizia/ignis-helpers';
+import { MailBackoffTypes, MailErrorCodes, MailExecutorErrors } from '../../common/index.js';
+export class InternalQueueMailExecutorHelper extends BaseHelper {
+    constructor(opts) {
+        super({ scope: InternalQueueMailExecutorHelper.name });
+        this.jobIdCounter = 0;
+        this.delayedJobs = new Map();
+        this.queue = new SequentialQueueHelper({
+            identifier: opts.identifier,
+            autoDispatch: true,
+            onMessage: async ({ queueElement }) => {
+                await this.processJob(queueElement.payload);
+            },
+            onDataEnqueue: ({ queueElement }) => {
+                this.logger
+                    .for('onDataEnqueue')
+                    .info('Job enqueued | jobId: %s | email: %s', queueElement.payload.id, queueElement.payload.email);
+            },
+            onStateChange: ({ from, to }) => {
+                this.logger.for('onStateChange').debug('Queue state changed | from: %s | to: %s', from, to);
+            },
+        });
+        this.logger.for(this.constructor.name).info('Internal queue executor initialized');
+    }
+    setProcessor(processor) {
+        this.processor = processor;
+        this.logger.for(this.setProcessor.name).info('Processor registered');
+    }
+    async enqueueVerificationEmail(email, options) {
+        if (!this.processor) {
+            throw getError({ message: MailExecutorErrors.PROCESSOR_NOT_SET });
+        }
+        const jobId = `job_${++this.jobIdCounter}_${Date.now()}`;
+        const job = {
+            id: jobId,
+            email,
+            options,
+            attempts: 0,
+            scheduledAt: Date.now() + (options?.delay ?? 0),
+        };
+        this.logger
+            .for(this.enqueueVerificationEmail.name)
+            .info('Queuing email | jobId: %s | email: %s', jobId, email);
+        if (options?.delay && options.delay > 0) {
+            const timeout = setTimeout(() => {
+                this.queue.enqueue(job).catch((error) => {
+                    this.logger
+                        .for(this.enqueueVerificationEmail.name)
+                        .error('Failed to enqueue delayed job | jobId: %s | error: %s', jobId, error);
+                });
+                this.delayedJobs.delete(jobId);
+            }, options.delay);
+            this.delayedJobs.set(jobId, timeout);
+            this.logger
+                .for(this.enqueueVerificationEmail.name)
+                .info('Job scheduled with delay | jobId: %s | delay: %dms', jobId, options.delay);
+        }
+        else {
+            await this.queue.enqueue(job);
+        }
+        return {
+            jobId,
+            queued: true,
+            message: 'Email queued successfully (internal queue)',
+        };
+    }
+    /** Releases every pending delayed/backoff timer - a live `setTimeout` holds the event loop open past the executor. */
+    async close() {
+        const pendingCount = this.delayedJobs.size;
+        const delayedJobsValues = this.delayedJobs.values();
+        for (const timeout of delayedJobsValues) {
+            clearTimeout(timeout);
+        }
+        this.delayedJobs.clear();
+        this.logger.for(this.close.name).info('Executor closed | Cleared timers: %d', pendingCount);
+    }
+    async processJob(job) {
+        if (!this.processor) {
+            this.logger.for(this.processJob.name).error('Processor not set | jobId: %s', job.id);
+            return;
+        }
+        const maxAttempts = job.options?.attempts ?? 3;
+        this.logger
+            .for(this.processJob.name)
+            .info('Processing job | jobId: %s | email: %s | attempt: %d/%d', job.id, job.email, job.attempts + 1, maxAttempts);
+        try {
+            const result = await this.processor(job.email);
+            // A processor reports SMTP rejection by RETURNING `{ success: false }`; watching only for throws completes the job and drops the mail.
+            if (result?.success === false) {
+                throw getError({
+                    messageCode: MailErrorCodes.SEND_FAILED,
+                    message: `[processJob] Processor reported failure | jobId: ${job.id} | reason: ${result.message}`,
+                });
+            }
+            this.logger.for(this.processJob.name).info('Job completed successfully | jobId: %s', job.id);
+        }
+        catch (error) {
+            const errorMsg = error instanceof Error ? error.message : error;
+            job.attempts++;
+            if (job.attempts < maxAttempts) {
+                const backoffDelay = this.calculateBackoff(job);
+                this.logger
+                    .for(this.processJob.name)
+                    .warn('Job failed, retrying | jobId: %s | attempt: %d/%d | retryIn: %dms | error: %s', job.id, job.attempts, maxAttempts, backoffDelay, errorMsg);
+                const timeout = setTimeout(() => {
+                    this.queue.enqueue(job).catch((reenqueueError) => {
+                        this.logger
+                            .for(this.processJob.name)
+                            .error('Failed to re-enqueue job | jobId: %s | error: %s', job.id, reenqueueError);
+                    });
+                    this.delayedJobs.delete(job.id);
+                }, backoffDelay);
+                this.delayedJobs.set(job.id, timeout);
+            }
+            else {
+                this.logger
+                    .for(this.processJob.name)
+                    .error('Job failed permanently after %d attempts | jobId: %s | error: %s', maxAttempts, job.id, errorMsg);
+            }
+        }
+    }
+    calculateBackoff(job) {
+        const backoff = job.options?.backoff;
+        if (!backoff) {
+            return 1000;
+        }
+        if (backoff.type === MailBackoffTypes.EXPONENTIAL) {
+            return backoff.delay * Math.pow(2, job.attempts - 1);
+        }
+        return backoff.delay;
+    }
+}
+//# sourceMappingURL=internal-queue-executor.helper.js.map

package/dist/esm/components/mail/helpers/executors/internal-queue-executor.helper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal-queue-executor.helper.js","sourceRoot":"","sources":["../../../../../../src/components/mail/helpers/executors/internal-queue-executor.helper.ts"],"names":[],"mappings":"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","sourcesContent":["import { BaseHelper, getError } from '@venizia/ignis-helpers/core';\nimport { SequentialQueueHelper } from '@venizia/ignis-helpers';\nimport type {\n  IMailQueueOptions,\n  IMailQueueExecutor,\n  IMailProcessorResult,\n  IInternalQueueMailExecutorOpts,\n  IMailQueueResult,\n  IQueueJobPayload,\n} from '../../common';\nimport { MailBackoffTypes, MailErrorCodes, MailExecutorErrors } from '../../common';\n\nexport class InternalQueueMailExecutorHelper extends BaseHelper implements IMailQueueExecutor {\n  private queue: SequentialQueueHelper<IQueueJobPayload>;\n  private jobIdCounter = 0;\n  private delayedJobs: Map<string, NodeJS.Timeout> = new Map();\n\n  private processor?: (email: string) => Promise<IMailProcessorResult>;\n\n  constructor(opts: IInternalQueueMailExecutorOpts) {\n    super({ scope: InternalQueueMailExecutorHelper.name });\n\n    this.queue = new SequentialQueueHelper<IQueueJobPayload>({\n      identifier: opts.identifier,\n      autoDispatch: true,\n      onMessage: async ({ queueElement }) => {\n        await this.processJob(queueElement.payload);\n      },\n      onDataEnqueue: ({ queueElement }) => {\n        this.logger\n          .for('onDataEnqueue')\n          .info(\n            'Job enqueued | jobId: %s | email: %s',\n            queueElement.payload.id,\n            queueElement.payload.email,\n          );\n      },\n      onStateChange: ({ from, to }) => {\n        this.logger.for('onStateChange').debug('Queue state changed | from: %s | to: %s', from, to);\n      },\n    });\n\n    this.logger.for(this.constructor.name).info('Internal queue executor initialized');\n  }\n\n  setProcessor(processor: (email: string) => Promise<IMailProcessorResult>): void {\n    this.processor = processor;\n    this.logger.for(this.setProcessor.name).info('Processor registered');\n  }\n\n  async enqueueVerificationEmail(\n    email: string,\n    options?: IMailQueueOptions,\n  ): Promise<IMailQueueResult> {\n    if (!this.processor) {\n      throw getError({ message: MailExecutorErrors.PROCESSOR_NOT_SET });\n    }\n\n    const jobId = `job_${++this.jobIdCounter}_${Date.now()}`;\n    const job: IQueueJobPayload = {\n      id: jobId,\n      email,\n      options,\n      attempts: 0,\n      scheduledAt: Date.now() + (options?.delay ?? 0),\n    };\n\n    this.logger\n      .for(this.enqueueVerificationEmail.name)\n      .info('Queuing email | jobId: %s | email: %s', jobId, email);\n\n    if (options?.delay && options.delay > 0) {\n      const timeout = setTimeout(() => {\n        this.queue.enqueue(job).catch((error) => {\n          this.logger\n            .for(this.enqueueVerificationEmail.name)\n            .error('Failed to enqueue delayed job | jobId: %s | error: %s', jobId, error);\n        });\n        this.delayedJobs.delete(jobId);\n      }, options.delay);\n\n      this.delayedJobs.set(jobId, timeout);\n\n      this.logger\n        .for(this.enqueueVerificationEmail.name)\n        .info('Job scheduled with delay | jobId: %s | delay: %dms', jobId, options.delay);\n    } else {\n      await this.queue.enqueue(job);\n    }\n\n    return {\n      jobId,\n      queued: true,\n      message: 'Email queued successfully (internal queue)',\n    };\n  }\n\n  /** Releases every pending delayed/backoff timer - a live `setTimeout` holds the event loop open past the executor. */\n  async close(): Promise<void> {\n    const pendingCount = this.delayedJobs.size;\n\n    const delayedJobsValues = this.delayedJobs.values();\n    for (const timeout of delayedJobsValues) {\n      clearTimeout(timeout);\n    }\n\n    this.delayedJobs.clear();\n\n    this.logger.for(this.close.name).info('Executor closed | Cleared timers: %d', pendingCount);\n  }\n\n  private async processJob(job: IQueueJobPayload): Promise<void> {\n    if (!this.processor) {\n      this.logger.for(this.processJob.name).error('Processor not set | jobId: %s', job.id);\n      return;\n    }\n\n    const maxAttempts = job.options?.attempts ?? 3;\n\n    this.logger\n      .for(this.processJob.name)\n      .info(\n        'Processing job | jobId: %s | email: %s | attempt: %d/%d',\n        job.id,\n        job.email,\n        job.attempts + 1,\n        maxAttempts,\n      );\n\n    try {\n      const result = await this.processor(job.email);\n\n      // A processor reports SMTP rejection by RETURNING `{ success: false }`; watching only for throws completes the job and drops the mail.\n      if (result?.success === false) {\n        throw getError({\n          messageCode: MailErrorCodes.SEND_FAILED,\n          message: `[processJob] Processor reported failure | jobId: ${job.id} | reason: ${result.message}`,\n        });\n      }\n\n      this.logger.for(this.processJob.name).info('Job completed successfully | jobId: %s', job.id);\n    } catch (error) {\n      const errorMsg = error instanceof Error ? error.message : error;\n      job.attempts++;\n\n      if (job.attempts < maxAttempts) {\n        const backoffDelay = this.calculateBackoff(job);\n\n        this.logger\n          .for(this.processJob.name)\n          .warn(\n            'Job failed, retrying | jobId: %s | attempt: %d/%d | retryIn: %dms | error: %s',\n            job.id,\n            job.attempts,\n            maxAttempts,\n            backoffDelay,\n            errorMsg,\n          );\n\n        const timeout = setTimeout(() => {\n          this.queue.enqueue(job).catch((reenqueueError) => {\n            this.logger\n              .for(this.processJob.name)\n              .error('Failed to re-enqueue job | jobId: %s | error: %s', job.id, reenqueueError);\n          });\n          this.delayedJobs.delete(job.id);\n        }, backoffDelay);\n\n        this.delayedJobs.set(job.id, timeout);\n      } else {\n        this.logger\n          .for(this.processJob.name)\n          .error(\n            'Job failed permanently after %d attempts | jobId: %s | error: %s',\n            maxAttempts,\n            job.id,\n            errorMsg,\n          );\n      }\n    }\n  }\n\n  private calculateBackoff(job: IQueueJobPayload): number {\n    const backoff = job.options?.backoff;\n\n    if (!backoff) {\n      return 1000;\n    }\n\n    if (backoff.type === MailBackoffTypes.EXPONENTIAL) {\n      return backoff.delay * Math.pow(2, job.attempts - 1);\n    }\n\n    return backoff.delay;\n  }\n}\n"]}

package/dist/esm/components/mail/helpers/index.d.ts

@@ -0,0 +1,3 @@
+export * from './executors/index.js';
+export * from './transporters/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/components/mail/helpers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/components/mail/helpers/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC"}

package/dist/esm/components/mail/helpers/index.js

@@ -0,0 +1,3 @@
+export * from './executors/index.js';
+export * from './transporters/index.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/components/mail/helpers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../src/components/mail/helpers/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC","sourcesContent":["export * from './executors';\nexport * from './transporters';\n"]}

package/dist/esm/components/mail/helpers/transporters/amazon-ses-transporter.helper.d.ts

@@ -0,0 +1,19 @@
+import { BaseHelper } from '@venizia/ignis-helpers/core';
+import { type IMailMessage, type IMailSendResult, type IMailTransport, type TAmazonSesClient, type TAmazonSesConfig, type TAmazonSesModule } from '../../common/index.js';
+export declare class AmazonSesTransportHelper extends BaseHelper implements IMailTransport {
+    private client;
+    private sendEmailCommandConstructor;
+    private getAccountCommandConstructor;
+    private module?;
+    constructor(opts: {
+        config: TAmazonSesConfig;
+        module?: TAmazonSesModule;
+    });
+    send(message: IMailMessage): Promise<IMailSendResult>;
+    verify(): Promise<boolean>;
+    close(): Promise<void>;
+    configure(config: TAmazonSesConfig): void;
+    protected buildClient(config: TAmazonSesConfig): TAmazonSesClient;
+    private validateConfig;
+}
+//# sourceMappingURL=amazon-ses-transporter.helper.d.ts.map

package/dist/esm/components/mail/helpers/transporters/amazon-ses-transporter.helper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"amazon-ses-transporter.helper.d.ts","sourceRoot":"","sources":["../../../../../../src/components/mail/helpers/transporters/amazon-ses-transporter.helper.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAY,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACtB,MAAM,cAAc,CAAC;AAItB,qBAAa,wBAAyB,SAAQ,UAAW,YAAW,cAAc;IAChF,OAAO,CAAC,MAAM,CAAU;IACxB,OAAO,CAAC,2BAA2B,CAAU;IAC7C,OAAO,CAAC,4BAA4B,CAAU;IAC9C,OAAO,CAAC,MAAM,CAAC,CAAqC;gBAExC,IAAI,EAAE;QAAE,MAAM,EAAE,gBAAgB,CAAC;QAAC,MAAM,CAAC,EAAE,gBAAgB,CAAA;KAAE;IAQnE,IAAI,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,eAAe,CAAC;IAkDrD,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC;IAwB1B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAM5B,SAAS,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI;IAWzC,SAAS,CAAC,WAAW,CAAC,MAAM,EAAE,gBAAgB,GAAG,gBAAgB;IAkBjE,OAAO,CAAC,cAAc;CAWvB"}