@venizia/ignis 0.4.3 → 0.4.4

package/dist/esm/components/mail/common/types/options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.js","sourceRoot":"","sources":["../../../../../../src/components/mail/common/types/options.ts"],"names":[],"mappings":"","sourcesContent":["import type { AnyType } from '@venizia/ignis-helpers/common';\nimport type SMTPTransport from 'nodemailer/lib/smtp-transport';\nimport type { IMailTransport } from './message';\n\nexport interface IBaseMailOptions {\n  from?: string;\n  fromName?: string;\n  /**\n   * The only directory an `attachment.path` may be read from; `path` is resolved against it and\n   * refused if it lands outside, symlinks included. Unset, every `path` is refused.\n   */\n  attachmentRoot?: string;\n  /** Bytes of attachment content one message may carry, all attachments together. Default 25 MB. */\n  maxAttachmentBytes?: number;\n}\n\nexport interface INodemailerMailOptions extends IBaseMailOptions {\n  provider: 'nodemailer';\n  config: TNodemailerConfig;\n  module?: TNodemailerModule;\n}\n\nexport interface IMailgunMailOptions extends IBaseMailOptions {\n  provider: 'mailgun';\n  config: TMailgunConfig;\n  module?: TMailgunModule;\n}\n\nexport interface IAmazonSesMailOptions extends IBaseMailOptions {\n  provider: 'amazon-ses';\n  config: TAmazonSesConfig;\n  module?: TAmazonSesModule;\n}\n\nexport interface ICustomMailOptions extends IBaseMailOptions {\n  provider: 'custom';\n  config: IMailTransport;\n}\n\nexport interface IGenericMailOptions extends IBaseMailOptions {\n  provider: string;\n  config: Record<string, AnyType>;\n}\n\nexport type TMailOptions =\n  | INodemailerMailOptions\n  | IAmazonSesMailOptions\n  | IMailgunMailOptions\n  | ICustomMailOptions\n  | IGenericMailOptions;\n\nexport type TNodemailerConfig = SMTPTransport | SMTPTransport.Options | string;\n\n// MailgunClientOptions & {domain: string}\nexport type TMailgunConfig = AnyType & { domain: string };\n\n/**\n * The peer module itself, handed over by an application that already holds it. A `bun build\n * --compile` binary carries no `node_modules`, so the runtime lookup these transports fall back to\n * has nothing to resolve against - passing the module through the options is what a compiled\n * application does instead. Typed as the shape each transport actually uses, so a wrong module is\n * a compile error rather than a boot crash.\n */\nexport type TNodemailerModule = {\n  createTransport: (config: AnyType, defaults?: AnyType) => AnyType;\n};\n\nexport type TMailgunModule = new (formData: AnyType) => AnyType;\n\nexport type TAmazonSesConfig = {\n  region: string;\n  credentials?: { accessKeyId: string; secretAccessKey: string; sessionToken?: string };\n  endpoint?: string;\n};\n\n/** Same story as {@link TNodemailerModule} - a compiled binary hands this over explicitly since there is no `node_modules` to resolve `@aws-sdk/client-sesv2` against. */\nexport type TAmazonSesModule<\n  TConfig extends AnyType = AnyType,\n  TClient extends AnyType = AnyType,\n> = {\n  SESv2Client: new (config: TConfig) => TClient;\n  SendEmailCommand: new (input: AnyType) => AnyType;\n  GetAccountCommand: new (input?: AnyType) => AnyType;\n};\n\nexport type TAmazonSesClient = Pick<TAmazonSesModule, 'SendEmailCommand' | 'GetAccountCommand'> & {\n  client: AnyType;\n};\n"]}

package/dist/esm/components/mail/common/types/queue.d.ts

@@ -0,0 +1,57 @@
+import type { TMailBackoffType } from '../constants.js';
+import type { TConstValue } from '@venizia/ignis-helpers/common';
+import type { IRedisSingleHelperOptions } from '@venizia/ignis-helpers';
+import type { BullMQExecutorModes, MailQueueExecutorTypes } from '../constants.js';
+export interface IMailQueueOptions {
+    priority?: number;
+    delay?: number;
+    attempts?: number;
+    backoff?: {
+        type: TMailBackoffType;
+        delay: number;
+    };
+}
+export interface IMailProcessorResult {
+    success: boolean;
+    message: string;
+    expiresInMinutes: number;
+    nextResendAt?: string;
+}
+export interface IMailQueueResult {
+    jobId?: string;
+    queued: boolean;
+    message: string;
+    result?: IMailProcessorResult;
+}
+export interface IMailQueueExecutor {
+    enqueueVerificationEmail(email: string, options?: IMailQueueOptions): Promise<IMailQueueResult>;
+    setProcessor(processor: (email: string) => Promise<IMailProcessorResult>): void;
+}
+/** Envelope every queue-backed executor stores for one pending verification email. */
+export interface IQueueJobPayload {
+    id: string;
+    email: string;
+    options?: IMailQueueOptions;
+    attempts: number;
+    scheduledAt: number;
+}
+export interface IInternalQueueMailExecutorOpts {
+    identifier: string;
+}
+export interface IBullMQMailExecutorOpts {
+    /** `redis.module` passes `ioredis` itself - see `module` below for why. */
+    redis: IRedisSingleHelperOptions;
+    queue: {
+        identifier: string;
+        name: string;
+    };
+    mode: TConstValue<typeof BullMQExecutorModes>;
+    /** `bullmq` itself, for a `bun build --compile` binary that has no `node_modules` to load it from. */
+    module?: typeof import('bullmq');
+}
+export interface IMailQueueExecutorConfig {
+    type: TConstValue<typeof MailQueueExecutorTypes>;
+    internalQueue?: IInternalQueueMailExecutorOpts;
+    bullmq?: IBullMQMailExecutorOpts;
+}
+//# sourceMappingURL=queue.d.ts.map

package/dist/esm/components/mail/common/types/queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.d.ts","sourceRoot":"","sources":["../../../../../../src/components/mail/common/types/queue.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,wBAAwB,CAAC;AACxE,OAAO,KAAK,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAEhF,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE;QACR,IAAI,EAAE,gBAAgB,CAAC;QACvB,KAAK,EAAE,MAAM,CAAC;KACf,CAAC;CACH;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,gBAAgB,EAAE,MAAM,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,oBAAoB,CAAC;CAC/B;AAED,MAAM,WAAW,kBAAkB;IACjC,wBAAwB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAChG,YAAY,CAAC,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,oBAAoB,CAAC,GAAG,IAAI,CAAC;CACjF;AAED,sFAAsF;AACtF,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,iBAAiB,CAAC;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,8BAA8B;IAC7C,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,uBAAuB;IACtC,2EAA2E;IAC3E,KAAK,EAAE,yBAAyB,CAAC;IACjC,KAAK,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,IAAI,EAAE,WAAW,CAAC,OAAO,mBAAmB,CAAC,CAAC;IAC9C,sGAAsG;IACtG,MAAM,CAAC,EAAE,cAAc,QAAQ,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,WAAW,CAAC,OAAO,sBAAsB,CAAC,CAAC;IACjD,aAAa,CAAC,EAAE,8BAA8B,CAAC;IAC/C,MAAM,CAAC,EAAE,uBAAuB,CAAC;CAClC"}

package/dist/esm/components/mail/common/types/queue.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=queue.js.map

package/dist/esm/components/mail/common/types/queue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.js","sourceRoot":"","sources":["../../../../../../src/components/mail/common/types/queue.ts"],"names":[],"mappings":"","sourcesContent":["import type { TMailBackoffType } from '../constants';\nimport type { TConstValue } from '@venizia/ignis-helpers/common';\nimport type { IRedisSingleHelperOptions } from '@venizia/ignis-helpers';\nimport type { BullMQExecutorModes, MailQueueExecutorTypes } from '../constants';\n\nexport interface IMailQueueOptions {\n  priority?: number;\n  delay?: number;\n  attempts?: number;\n  backoff?: {\n    type: TMailBackoffType;\n    delay: number;\n  };\n}\n\nexport interface IMailProcessorResult {\n  success: boolean;\n  message: string;\n  expiresInMinutes: number;\n  nextResendAt?: string;\n}\n\nexport interface IMailQueueResult {\n  jobId?: string;\n  queued: boolean;\n  message: string;\n  result?: IMailProcessorResult;\n}\n\nexport interface IMailQueueExecutor {\n  enqueueVerificationEmail(email: string, options?: IMailQueueOptions): Promise<IMailQueueResult>;\n  setProcessor(processor: (email: string) => Promise<IMailProcessorResult>): void;\n}\n\n/** Envelope every queue-backed executor stores for one pending verification email. */\nexport interface IQueueJobPayload {\n  id: string;\n  email: string;\n  options?: IMailQueueOptions;\n  attempts: number;\n  scheduledAt: number;\n}\n\nexport interface IInternalQueueMailExecutorOpts {\n  identifier: string;\n}\n\nexport interface IBullMQMailExecutorOpts {\n  /** `redis.module` passes `ioredis` itself - see `module` below for why. */\n  redis: IRedisSingleHelperOptions;\n  queue: { identifier: string; name: string };\n  mode: TConstValue<typeof BullMQExecutorModes>;\n  /** `bullmq` itself, for a `bun build --compile` binary that has no `node_modules` to load it from. */\n  module?: typeof import('bullmq');\n}\n\nexport interface IMailQueueExecutorConfig {\n  type: TConstValue<typeof MailQueueExecutorTypes>;\n  internalQueue?: IInternalQueueMailExecutorOpts;\n  bullmq?: IBullMQMailExecutorOpts;\n}\n"]}

package/dist/esm/components/mail/common/types/template.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template.d.ts","sourceRoot":"","sources":["../../../../../../src/components/mail/common/types/template.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,+BAA+B,CAAC;AAE7D,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,CAAC;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,CAAC,IAAI,EAAE;QACX,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAC1B,eAAe,CAAC,EAAE,OAAO,CAAC;KAC3B,GAAG,MAAM,CAAC;IACX,gBAAgB,CAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAChE,oBAAoB,CAAC,IAAI,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;KAAE,GAAG;QAC3E,OAAO,EAAE,OAAO,CAAC;QACjB,WAAW,EAAE,MAAM,EAAE,CAAC;QACtB,OAAO,EAAE,MAAM,EAAE,CAAC;KACnB,CAAC;IACF,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAAC;IACjD,aAAa,IAAI,SAAS,EAAE,CAAC;IAC7B,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IACnC,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;CACvC"}

package/dist/esm/components/mail/common/types/template.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=template.js.map

package/dist/esm/components/mail/common/types/template.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"template.js","sourceRoot":"","sources":["../../../../../../src/components/mail/common/types/template.ts"],"names":[],"mappings":"","sourcesContent":["import type { AnyType } from '@venizia/ignis-helpers/common';\n\nexport interface ITemplate {\n  name: string;\n  content?: string;\n  render?: (data: Record<string, AnyType>) => string;\n  subject?: string;\n  description?: string;\n}\n\nexport interface IMailTemplateEngine {\n  render(opts: {\n    templateData?: string;\n    templateName?: string;\n    data: Record<string, any>;\n    requireValidate?: boolean;\n  }): string;\n  registerTemplate(opts: { name: string; content: string }): void;\n  validateTemplateData(opts: { template: string; data: Record<string, any> }): {\n    isValid: boolean;\n    missingKeys: string[];\n    allKeys: string[];\n  };\n  getTemplate(name: string): ITemplate | undefined;\n  listTemplates(): ITemplate[];\n  hasTemplate(name: string): boolean;\n  removeTemplate(name: string): boolean;\n}\n"]}

package/dist/esm/components/mail/common/types/verification.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verification.d.ts","sourceRoot":"","sources":["../../../../../../src/components/mail/common/types/verification.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,8BAA8B;IAC7C,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,iBAAiB;IAChC,gBAAgB,EAAE,MAAM,CAAC;IACzB,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IAErB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,gBAAgB,EAAE,MAAM,CAAC;IACzB,cAAc,EAAE,MAAM,CAAC;IAEvB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,0BAA0B;IACzC,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;CACtC;AAED,MAAM,WAAW,2BAA2B;IAC1C,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;CACtC;AAED,MAAM,WAAW,0BAA0B;IACzC,wBAAwB,CAAC,OAAO,EAAE,8BAA8B,GAAG,iBAAiB,CAAC;CACtF"}

package/dist/esm/components/mail/common/types/verification.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=verification.js.map

package/dist/esm/components/mail/common/types/verification.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verification.js","sourceRoot":"","sources":["../../../../../../src/components/mail/common/types/verification.ts"],"names":[],"mappings":"","sourcesContent":["export interface IVerificationGenerationOptions {\n  codeLength: number;\n  tokenBytes: number;\n  codeExpiryMinutes: number;\n  tokenExpiryHours: number;\n}\n\nexport interface IVerificationData {\n  verificationCode: string;\n  codeGeneratedAt: string;\n  codeExpiresAt: string;\n  codeAttempts: number;\n\n  verificationToken: string;\n  tokenGeneratedAt: string;\n  tokenExpiresAt: string;\n\n  lastCodeSentAt: string;\n}\n\nexport interface IVerificationCodeGenerator {\n  generateCode(length: number): string;\n}\n\nexport interface IVerificationTokenGenerator {\n  generateToken(bytes: number): string;\n}\n\nexport interface IVerificationDataGenerator {\n  generateVerificationData(options: IVerificationGenerationOptions): IVerificationData;\n}\n"]}

package/dist/esm/components/mail/component.d.ts

@@ -0,0 +1,17 @@
+import { type BaseApplication } from '../../base/applications/index.js';
+import { BaseComponent } from '@venizia/ignis-kernel';
+import type { TMailOptions } from './common/index.js';
+export declare class MailComponent extends BaseComponent<TMailOptions> {
+    private application;
+    constructor(application: BaseApplication);
+    /** `application.component(MailComponent, { options })` lands here; the call site outranks a key bound earlier. */
+    configure(opts?: TMailOptions): Promise<void>;
+    binding(): void | Promise<void>;
+    initGenerators(): void;
+    initProviders(): void;
+    initServices(): void;
+    /** A bad limit or root would otherwise surface on every send, as a 400 that blames the caller. */
+    private validateAttachmentOptions;
+    createAndBindInstances(): void;
+}
+//# sourceMappingURL=component.d.ts.map

package/dist/esm/components/mail/component.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"component.d.ts","sourceRoot":"","sources":["../../../../src/components/mail/component.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAOtD,OAAO,KAAK,EAA4B,YAAY,EAAE,MAAM,UAAU,CAAC;AAYvE,qBAAa,aAAc,SAAQ,aAAa,CAAC,YAAY,CAAC;IAEN,OAAO,CAAC,WAAW;gBAAX,WAAW,EAAE,eAAe;IAS1F,kHAAkH;IACnG,SAAS,CAAC,IAAI,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAcnD,OAAO,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAsBxC,cAAc;IAYd,aAAa;IAWb,YAAY;IAWZ,kGAAkG;IAClG,OAAO,CAAC,yBAAyB;IA2CjC,sBAAsB,IAAI,IAAI;CAqC/B"}

package/dist/esm/components/mail/component.js

@@ -0,0 +1,164 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var MailComponent_1;
+import { BaseComponent } from '@venizia/ignis-kernel';
+import { inject } from '../../base/metadata/index.js';
+import { CoreBindings } from '../../common/index.js';
+import { getError } from '@venizia/ignis-helpers/core';
+import { HTTP } from '@venizia/ignis-helpers/common';
+import { statSync } from 'node:fs';
+import { isAbsolute } from 'node:path';
+import { MailErrorCodes, MailKeys, MailQueueExecutorTypes } from './common/index.js';
+import { MailQueueExecutorProvider, MailTransportProvider } from './providers/index.js';
+import { DefaultVerificationDataGenerator, MailService, NumericCodeGenerator, RandomTokenGenerator, TemplateEngineService, } from './services/index.js';
+let MailComponent = MailComponent_1 = class MailComponent extends BaseComponent {
+    constructor(application) {
+        super({
+            scope: MailComponent_1.name,
+            initDefault: { enable: true, container: application },
+            bindings: {},
+        });
+        this.application = application;
+    }
+    /** `application.component(MailComponent, { options })` lands here; the call site outranks a key bound earlier. */
+    async configure(opts) {
+        // The base short-circuits a second call; binding before that check would swap the options
+        // under a transport that was already built from the first ones.
+        if (this.isConfigured) {
+            return;
+        }
+        if (opts !== undefined) {
+            this.application.bind({ key: MailKeys.MAIL_OPTIONS }).toValue(opts);
+        }
+        await super.configure(opts);
+    }
+    binding() {
+        if (!this.application.isBound({ key: MailKeys.MAIL_OPTIONS })) {
+            this.logger
+                .for(this.binding.name)
+                .error('Mail options not configured. Please bind MailKeys.MAIL_OPTIONS before adding MailComponent.');
+            throw getError({
+                message: 'Mail options not configured',
+            });
+        }
+        this.initGenerators();
+        this.initProviders();
+        this.initServices();
+        this.createAndBindInstances();
+        this.logger.for(this.binding.name).info('Mail component initialized successfully');
+    }
+    initGenerators() {
+        this.application
+            .bind({ key: MailKeys.MAIL_VERIFICATION_CODE_GENERATOR })
+            .toClass(NumericCodeGenerator);
+        this.application
+            .bind({ key: MailKeys.MAIL_VERIFICATION_TOKEN_GENERATOR })
+            .toClass(RandomTokenGenerator);
+        this.application
+            .bind({ key: MailKeys.MAIL_VERIFICATION_DATA_GENERATOR })
+            .toClass(DefaultVerificationDataGenerator);
+    }
+    initProviders() {
+        this.application
+            .bind({ key: MailKeys.MAIL_TRANSPORT_PROVIDER })
+            .toProvider(MailTransportProvider)
+            .setScope('singleton');
+        this.application
+            .bind({ key: MailKeys.MAIL_QUEUE_EXECUTOR_PROVIDER })
+            .toProvider(MailQueueExecutorProvider)
+            .setScope('singleton');
+    }
+    initServices() {
+        this.application
+            .bind({ key: MailKeys.MAIL_SERVICE })
+            .toClass(MailService)
+            .setScope('singleton');
+        this.application
+            .bind({ key: MailKeys.MAIL_TEMPLATE_ENGINE })
+            .toClass(TemplateEngineService)
+            .setScope('singleton');
+    }
+    /** A bad limit or root would otherwise surface on every send, as a 400 that blames the caller. */
+    validateAttachmentOptions(opts) {
+        const { attachmentRoot, maxAttachmentBytes } = opts.options;
+        const buildOptionError = (details) => {
+            return getError({
+                statusCode: HTTP.ResultCodes.RS_5.InternalServerError,
+                messageCode: MailErrorCodes.INVALID_CONFIGURATION,
+                message: `Invalid mail options | ${details.message}`,
+                cause: details.cause,
+            });
+        };
+        const isValidLimit = maxAttachmentBytes === undefined ||
+            (Number.isSafeInteger(maxAttachmentBytes) && maxAttachmentBytes > 0);
+        if (!isValidLimit) {
+            throw buildOptionError({ message: 'maxAttachmentBytes must be a positive integer' });
+        }
+        if (attachmentRoot === undefined) {
+            return;
+        }
+        if (typeof attachmentRoot !== 'string' || !isAbsolute(attachmentRoot)) {
+            throw buildOptionError({ message: 'attachmentRoot must be an absolute path' });
+        }
+        let isDirectory;
+        try {
+            isDirectory = statSync(attachmentRoot).isDirectory();
+        }
+        catch (error) {
+            throw buildOptionError({
+                message: 'attachmentRoot must be an existing directory',
+                cause: error,
+            });
+        }
+        if (!isDirectory) {
+            throw buildOptionError({ message: 'attachmentRoot must be an existing directory' });
+        }
+    }
+    createAndBindInstances() {
+        // Transport
+        const transportGetter = this.application.get({
+            key: MailKeys.MAIL_TRANSPORT_PROVIDER,
+        });
+        const mailOptions = this.application.get({ key: MailKeys.MAIL_OPTIONS });
+        this.validateAttachmentOptions({ options: mailOptions });
+        // Only the provider is logged: the options carry SMTP / API credentials, which must never reach a log sink.
+        this.logger
+            .for(this.createAndBindInstances.name)
+            .info('Mail provider: %s', mailOptions.provider);
+        const mailTransportInstance = transportGetter(mailOptions);
+        this.application.bind({ key: MailKeys.MAIL_TRANSPORT_INSTANCE }).toValue(mailTransportInstance);
+        // Queue
+        const queueGetter = this.application.get({
+            key: MailKeys.MAIL_QUEUE_EXECUTOR_PROVIDER,
+        });
+        // Queueing is opt-in: with no executor config bound, fall back to the direct (inline) executor instead of a "binding is not bounded" crash at boot.
+        const queueConfig = this.application.get({
+            key: MailKeys.MAIL_QUEUE_EXECUTOR_CONFIG,
+            isOptional: true,
+        }) ?? { type: MailQueueExecutorTypes.DIRECT };
+        // Same reason as above: a bullmq config carries the Redis password.
+        this.logger
+            .for(this.createAndBindInstances.name)
+            .info('Mail queue executor type: %s', queueConfig.type);
+        const queueExecutorInstance = queueGetter(queueConfig);
+        this.application
+            .bind({ key: MailKeys.MAIL_QUEUE_EXECUTOR_INSTANCE })
+            .toValue(queueExecutorInstance);
+    }
+};
+MailComponent = MailComponent_1 = __decorate([
+    __param(0, inject({ key: CoreBindings.APPLICATION_INSTANCE })),
+    __metadata("design:paramtypes", [Function])
+], MailComponent);
+export { MailComponent };
+//# sourceMappingURL=component.js.map

package/dist/esm/components/mail/component.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"component.js","sourceRoot":"","sources":["../../../../src/components/mail/component.ts"],"names":[],"mappings":";;;;;;;;;;;;;AACA,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AACvD,OAAO,EAAE,IAAI,EAAE,MAAM,+BAA+B,CAAC;AACrD,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAEvC,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAE5E,OAAO,EAAE,yBAAyB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAC/E,OAAO,EACL,gCAAgC,EAChC,WAAW,EACX,oBAAoB,EACpB,oBAAoB,EACpB,qBAAqB,GACtB,MAAM,YAAY,CAAC;AAEpB,IAAa,aAAa,qBAA1B,MAAa,aAAc,SAAQ,aAA2B;IAC5D,YAC8D,WAA4B;QAExF,KAAK,CAAC;YACJ,KAAK,EAAE,eAAa,CAAC,IAAI;YACzB,WAAW,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE;YACrD,QAAQ,EAAE,EAAE;SACb,CAAC,CAAC;QANyD,gBAAW,GAAX,WAAW,CAAiB;IAO1F,CAAC;IAED,kHAAkH;IACzG,KAAK,CAAC,SAAS,CAAC,IAAmB;QAC1C,0FAA0F;QAC1F,gEAAgE;QAChE,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YACtB,OAAO;QACT,CAAC;QAED,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,IAAI,CAAC,WAAW,CAAC,IAAI,CAAe,EAAE,GAAG,EAAE,QAAQ,CAAC,YAAY,EAAE,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACpF,CAAC;QAED,MAAM,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IAC9B,CAAC;IAEQ,OAAO;QACd,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,EAAE,GAAG,EAAE,QAAQ,CAAC,YAAY,EAAE,CAAC,EAAE,CAAC;YAC9D,IAAI,CAAC,MAAM;iBACR,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;iBACtB,KAAK,CACJ,6FAA6F,CAC9F,CAAC;YAEJ,MAAM,QAAQ,CAAC;gBACb,OAAO,EAAE,6BAA6B;aACvC,CAAC,CAAC;QACL,CAAC;QAED,IAAI,CAAC,cAAc,EAAE,CAAC;QACtB,IAAI,CAAC,aAAa,EAAE,CAAC;QACrB,IAAI,CAAC,YAAY,EAAE,CAAC;QAEpB,IAAI,CAAC,sBAAsB,EAAE,CAAC;QAE9B,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,yCAAyC,CAAC,CAAC;IACrF,CAAC;IAED,cAAc;QACZ,IAAI,CAAC,WAAW;aACb,IAAI,CAAC,EAAE,GAAG,EAAE,QAAQ,CAAC,gCAAgC,EAAE,CAAC;aACxD,OAAO,CAAC,oBAAoB,CAAC,CAAC;QACjC,IAAI,CAAC,WAAW;aACb,IAAI,CAAC,EAAE,GAAG,EAAE,QAAQ,CAAC,iCAAiC,EAAE,CAAC;aACzD,OAAO,CAAC,oBAAoB,CAAC,CAAC;QACjC,IAAI,CAAC,WAAW;aACb,IAAI,CAAC,EAAE,GAAG,EAAE,QAAQ,CAAC,gCAAgC,EAAE,CAAC;aACxD,OAAO,CAAC,gCAAgC,CAAC,CAAC;IAC/C,CAAC;IAED,aAAa;QACX,IAAI,CAAC,WAAW;aACb,IAAI,CAAC,EAAE,GAAG,EAAE,QAAQ,CAAC,uBAAuB,EAAE,CAAC;aAC/C,UAAU,CAAC,qBAAqB,CAAC;aACjC,QAAQ,CAAC,WAAW,CAAC,CAAC;QACzB,IAAI,CAAC,WAAW;aACb,IAAI,CAAC,EAAE,GAAG,EAAE,QAAQ,CAAC,4BAA4B,EAAE,CAAC;aACpD,UAAU,CAAC,yBAAyB,CAAC;aACrC,QAAQ,CAAC,WAAW,CAAC,CAAC;IAC3B,CAAC;IAED,YAAY;QACV,IAAI,CAAC,WAAW;aACb,IAAI,CAAC,EAAE,GAAG,EAAE,QAAQ,CAAC,YAAY,EAAE,CAAC;aACpC,OAAO,CAAC,WAAW,CAAC;aACpB,QAAQ,CAAC,WAAW,CAAC,CAAC;QACzB,IAAI,CAAC,WAAW;aACb,IAAI,CAAC,EAAE,GAAG,EAAE,QAAQ,CAAC,oBAAoB,EAAE,CAAC;aAC5C,OAAO,CAAC,qBAAqB,CAAC;aAC9B,QAAQ,CAAC,WAAW,CAAC,CAAC;IAC3B,CAAC;IAED,kGAAkG;IAC1F,yBAAyB,CAAC,IAA+B;QAC/D,MAAM,EAAE,cAAc,EAAE,kBAAkB,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC;QAC5D,MAAM,gBAAgB,GAAG,CAAC,OAA6C,EAAE,EAAE;YACzE,OAAO,QAAQ,CAAC;gBACd,UAAU,EAAE,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,mBAAmB;gBACrD,WAAW,EAAE,cAAc,CAAC,qBAAqB;gBACjD,OAAO,EAAE,0BAA0B,OAAO,CAAC,OAAO,EAAE;gBACpD,KAAK,EAAE,OAAO,CAAC,KAAK;aACrB,CAAC,CAAC;QACL,CAAC,CAAC;QAEF,MAAM,YAAY,GAChB,kBAAkB,KAAK,SAAS;YAChC,CAAC,MAAM,CAAC,aAAa,CAAC,kBAAkB,CAAC,IAAI,kBAAkB,GAAG,CAAC,CAAC,CAAC;QAEvE,IAAI,CAAC,YAAY,EAAE,CAAC;YAClB,MAAM,gBAAgB,CAAC,EAAE,OAAO,EAAE,+CAA+C,EAAE,CAAC,CAAC;QACvF,CAAC;QAED,IAAI,cAAc,KAAK,SAAS,EAAE,CAAC;YACjC,OAAO;QACT,CAAC;QAED,IAAI,OAAO,cAAc,KAAK,QAAQ,IAAI,CAAC,UAAU,CAAC,cAAc,CAAC,EAAE,CAAC;YACtE,MAAM,gBAAgB,CAAC,EAAE,OAAO,EAAE,yCAAyC,EAAE,CAAC,CAAC;QACjF,CAAC;QAED,IAAI,WAAoB,CAAC;QAEzB,IAAI,CAAC;YACH,WAAW,GAAG,QAAQ,CAAC,cAAc,CAAC,CAAC,WAAW,EAAE,CAAC;QACvD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,gBAAgB,CAAC;gBACrB,OAAO,EAAE,8CAA8C;gBACvD,KAAK,EAAE,KAAK;aACb,CAAC,CAAC;QACL,CAAC;QAED,IAAI,CAAC,WAAW,EAAE,CAAC;YACjB,MAAM,gBAAgB,CAAC,EAAE,OAAO,EAAE,8CAA8C,EAAE,CAAC,CAAC;QACtF,CAAC;IACH,CAAC;IAED,sBAAsB;QACpB,YAAY;QACZ,MAAM,eAAe,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAsB;YAChE,GAAG,EAAE,QAAQ,CAAC,uBAAuB;SACtC,CAAC,CAAC;QACH,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAe,EAAE,GAAG,EAAE,QAAQ,CAAC,YAAY,EAAE,CAAC,CAAC;QACvF,IAAI,CAAC,yBAAyB,CAAC,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC,CAAC;QAEzD,4GAA4G;QAC5G,IAAI,CAAC,MAAM;aACR,GAAG,CAAC,IAAI,CAAC,sBAAsB,CAAC,IAAI,CAAC;aACrC,IAAI,CAAC,mBAAmB,EAAE,WAAW,CAAC,QAAQ,CAAC,CAAC;QAEnD,MAAM,qBAAqB,GAAG,eAAe,CAAC,WAAW,CAAC,CAAC;QAC3D,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,QAAQ,CAAC,uBAAuB,EAAE,CAAC,CAAC,OAAO,CAAC,qBAAqB,CAAC,CAAC;QAEhG,QAAQ;QACR,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAA0B;YAChE,GAAG,EAAE,QAAQ,CAAC,4BAA4B;SAC3C,CAAC,CAAC;QAEH,oJAAoJ;QACpJ,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAA2B;YACjE,GAAG,EAAE,QAAQ,CAAC,0BAA0B;YACxC,UAAU,EAAE,IAAI;SACjB,CAAC,IAAI,EAAE,IAAI,EAAE,sBAAsB,CAAC,MAAM,EAAE,CAAC;QAE9C,oEAAoE;QACpE,IAAI,CAAC,MAAM;aACR,GAAG,CAAC,IAAI,CAAC,sBAAsB,CAAC,IAAI,CAAC;aACrC,IAAI,CAAC,8BAA8B,EAAE,WAAW,CAAC,IAAI,CAAC,CAAC;QAE1D,MAAM,qBAAqB,GAAG,WAAW,CAAC,WAAW,CAAC,CAAC;QACvD,IAAI,CAAC,WAAW;aACb,IAAI,CAAC,EAAE,GAAG,EAAE,QAAQ,CAAC,4BAA4B,EAAE,CAAC;aACpD,OAAO,CAAC,qBAAqB,CAAC,CAAC;IACpC,CAAC;CACF,CAAA;AAnKY,aAAa;IAErB,WAAA,MAAM,CAAC,EAAE,GAAG,EAAE,YAAY,CAAC,oBAAoB,EAAE,CAAC,CAAA;;GAF1C,aAAa,CAmKzB","sourcesContent":["import { type BaseApplication } from '@/base/applications';\nimport { BaseComponent } from '@venizia/ignis-kernel';\nimport { inject } from '@/base/metadata';\nimport { CoreBindings } from '@/common';\nimport { getError } from '@venizia/ignis-helpers/core';\nimport { HTTP } from '@venizia/ignis-helpers/common';\nimport { statSync } from 'node:fs';\nimport { isAbsolute } from 'node:path';\nimport type { IMailQueueExecutorConfig, TMailOptions } from './common';\nimport { MailErrorCodes, MailKeys, MailQueueExecutorTypes } from './common';\nimport type { TGetMailQueueExecutorFn, TGetMailTransportFn } from './providers';\nimport { MailQueueExecutorProvider, MailTransportProvider } from './providers';\nimport {\n  DefaultVerificationDataGenerator,\n  MailService,\n  NumericCodeGenerator,\n  RandomTokenGenerator,\n  TemplateEngineService,\n} from './services';\n\nexport class MailComponent extends BaseComponent<TMailOptions> {\n  constructor(\n    @inject({ key: CoreBindings.APPLICATION_INSTANCE }) private application: BaseApplication,\n  ) {\n    super({\n      scope: MailComponent.name,\n      initDefault: { enable: true, container: application },\n      bindings: {},\n    });\n  }\n\n  /** `application.component(MailComponent, { options })` lands here; the call site outranks a key bound earlier. */\n  override async configure(opts?: TMailOptions): Promise<void> {\n    // The base short-circuits a second call; binding before that check would swap the options\n    // under a transport that was already built from the first ones.\n    if (this.isConfigured) {\n      return;\n    }\n\n    if (opts !== undefined) {\n      this.application.bind<TMailOptions>({ key: MailKeys.MAIL_OPTIONS }).toValue(opts);\n    }\n\n    await super.configure(opts);\n  }\n\n  override binding(): void | Promise<void> {\n    if (!this.application.isBound({ key: MailKeys.MAIL_OPTIONS })) {\n      this.logger\n        .for(this.binding.name)\n        .error(\n          'Mail options not configured. Please bind MailKeys.MAIL_OPTIONS before adding MailComponent.',\n        );\n\n      throw getError({\n        message: 'Mail options not configured',\n      });\n    }\n\n    this.initGenerators();\n    this.initProviders();\n    this.initServices();\n\n    this.createAndBindInstances();\n\n    this.logger.for(this.binding.name).info('Mail component initialized successfully');\n  }\n\n  initGenerators() {\n    this.application\n      .bind({ key: MailKeys.MAIL_VERIFICATION_CODE_GENERATOR })\n      .toClass(NumericCodeGenerator);\n    this.application\n      .bind({ key: MailKeys.MAIL_VERIFICATION_TOKEN_GENERATOR })\n      .toClass(RandomTokenGenerator);\n    this.application\n      .bind({ key: MailKeys.MAIL_VERIFICATION_DATA_GENERATOR })\n      .toClass(DefaultVerificationDataGenerator);\n  }\n\n  initProviders() {\n    this.application\n      .bind({ key: MailKeys.MAIL_TRANSPORT_PROVIDER })\n      .toProvider(MailTransportProvider)\n      .setScope('singleton');\n    this.application\n      .bind({ key: MailKeys.MAIL_QUEUE_EXECUTOR_PROVIDER })\n      .toProvider(MailQueueExecutorProvider)\n      .setScope('singleton');\n  }\n\n  initServices() {\n    this.application\n      .bind({ key: MailKeys.MAIL_SERVICE })\n      .toClass(MailService)\n      .setScope('singleton');\n    this.application\n      .bind({ key: MailKeys.MAIL_TEMPLATE_ENGINE })\n      .toClass(TemplateEngineService)\n      .setScope('singleton');\n  }\n\n  /** A bad limit or root would otherwise surface on every send, as a 400 that blames the caller. */\n  private validateAttachmentOptions(opts: { options: TMailOptions }): void {\n    const { attachmentRoot, maxAttachmentBytes } = opts.options;\n    const buildOptionError = (details: { message: string; cause?: unknown }) => {\n      return getError({\n        statusCode: HTTP.ResultCodes.RS_5.InternalServerError,\n        messageCode: MailErrorCodes.INVALID_CONFIGURATION,\n        message: `Invalid mail options | ${details.message}`,\n        cause: details.cause,\n      });\n    };\n\n    const isValidLimit =\n      maxAttachmentBytes === undefined ||\n      (Number.isSafeInteger(maxAttachmentBytes) && maxAttachmentBytes > 0);\n\n    if (!isValidLimit) {\n      throw buildOptionError({ message: 'maxAttachmentBytes must be a positive integer' });\n    }\n\n    if (attachmentRoot === undefined) {\n      return;\n    }\n\n    if (typeof attachmentRoot !== 'string' || !isAbsolute(attachmentRoot)) {\n      throw buildOptionError({ message: 'attachmentRoot must be an absolute path' });\n    }\n\n    let isDirectory: boolean;\n\n    try {\n      isDirectory = statSync(attachmentRoot).isDirectory();\n    } catch (error) {\n      throw buildOptionError({\n        message: 'attachmentRoot must be an existing directory',\n        cause: error,\n      });\n    }\n\n    if (!isDirectory) {\n      throw buildOptionError({ message: 'attachmentRoot must be an existing directory' });\n    }\n  }\n\n  createAndBindInstances(): void {\n    // Transport\n    const transportGetter = this.application.get<TGetMailTransportFn>({\n      key: MailKeys.MAIL_TRANSPORT_PROVIDER,\n    });\n    const mailOptions = this.application.get<TMailOptions>({ key: MailKeys.MAIL_OPTIONS });\n    this.validateAttachmentOptions({ options: mailOptions });\n\n    // Only the provider is logged: the options carry SMTP / API credentials, which must never reach a log sink.\n    this.logger\n      .for(this.createAndBindInstances.name)\n      .info('Mail provider: %s', mailOptions.provider);\n\n    const mailTransportInstance = transportGetter(mailOptions);\n    this.application.bind({ key: MailKeys.MAIL_TRANSPORT_INSTANCE }).toValue(mailTransportInstance);\n\n    // Queue\n    const queueGetter = this.application.get<TGetMailQueueExecutorFn>({\n      key: MailKeys.MAIL_QUEUE_EXECUTOR_PROVIDER,\n    });\n\n    // Queueing is opt-in: with no executor config bound, fall back to the direct (inline) executor instead of a \"binding is not bounded\" crash at boot.\n    const queueConfig = this.application.get<IMailQueueExecutorConfig>({\n      key: MailKeys.MAIL_QUEUE_EXECUTOR_CONFIG,\n      isOptional: true,\n    }) ?? { type: MailQueueExecutorTypes.DIRECT };\n\n    // Same reason as above: a bullmq config carries the Redis password.\n    this.logger\n      .for(this.createAndBindInstances.name)\n      .info('Mail queue executor type: %s', queueConfig.type);\n\n    const queueExecutorInstance = queueGetter(queueConfig);\n    this.application\n      .bind({ key: MailKeys.MAIL_QUEUE_EXECUTOR_INSTANCE })\n      .toValue(queueExecutorInstance);\n  }\n}\n"]}

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

@@ -0,0 +1,40 @@
+import { BaseHelper } from '@venizia/ignis-helpers/core';
+import type { TConstValue } from '../../../../helpers/index.js';
+import type { IBullMQMailExecutorOpts, IMailProcessorResult, IMailQueueExecutor, IMailQueueOptions, IMailQueueResult } from '../../common/index.js';
+import { BullMQExecutorModes } from '../../common/index.js';
+export declare class BullMQMailExecutorHelper extends BaseHelper implements IMailQueueExecutor {
+    private queueIdentifier;
+    private queueName;
+    private mode;
+    private queueHelper?;
+    private workerHelpers;
+    private redisConnection;
+    private readonly bullmqModule?;
+    private jobIdCounter;
+    private processor?;
+    constructor(opts: IBullMQMailExecutorOpts);
+    initQueue(queue: {
+        identifier: string;
+        name: string;
+    }): void;
+    setProcessor(processor: (email: string) => Promise<IMailProcessorResult>, opts?: {
+        numberOfWorkers?: number;
+        concurrencyPerWorker?: number;
+        lockDuration?: number;
+    }): Promise<void>;
+    addWorker(opts: {
+        workerIdentifier: string;
+        concurrency?: number;
+        lockDuration?: number;
+    }): void;
+    removeWorker(index: number): Promise<boolean>;
+    /** Closes every worker without stopping at the first failure, always empties the list, and returns failures instead of throwing so teardown can continue. */
+    private closeWorkers;
+    clearWorkers(): Promise<void>;
+    /** 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. */
+    close(): Promise<void>;
+    getWorkerCount(): number;
+    getMode(): TConstValue<typeof BullMQExecutorModes>;
+    enqueueVerificationEmail(email: string, options?: IMailQueueOptions): Promise<IMailQueueResult>;
+}
+//# sourceMappingURL=bull-mq-executor.helper.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"bull-mq-executor.helper.d.ts","sourceRoot":"","sources":["../../../../../../src/components/mail/helpers/executors/bull-mq-executor.helper.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAY,MAAM,6BAA6B,CAAC;AAEnE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE7C,OAAO,KAAK,EACV,uBAAuB,EACvB,oBAAoB,EACpB,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAEjB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,mBAAmB,EAIpB,MAAM,cAAc,CAAC;AAGtB,qBAAa,wBAAyB,SAAQ,UAAW,YAAW,kBAAkB;IACpF,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,IAAI,CAA0C;IAEtD,OAAO,CAAC,WAAW,CAAC,CAAmD;IACvE,OAAO,CAAC,aAAa,CAA8D;IACnF,OAAO,CAAC,eAAe,CAAoB;IAC3C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAA0B;IACxD,OAAO,CAAC,YAAY,CAAK;IAEzB,OAAO,CAAC,SAAS,CAAC,CAAmD;gBAEzD,IAAI,EAAE,uBAAuB;IAiBzC,SAAS,CAAC,KAAK,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE;IAmC/C,YAAY,CAChB,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,oBAAoB,CAAC,EAC3D,IAAI,CAAC,EAAE;QACL,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,oBAAoB,CAAC,EAAE,MAAM,CAAC;QAC9B,YAAY,CAAC,EAAE,MAAM,CAAC;KACvB,GACA,OAAO,CAAC,IAAI,CAAC;IAkChB,SAAS,CAAC,IAAI,EAAE;QAAE,gBAAgB,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAsG1F,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAiBnD,6JAA6J;YAC/I,YAAY;IA2BpB,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAOnC,sLAAsL;IAChL,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAkC5B,cAAc,IAAI,MAAM;IAIxB,OAAO,IAAI,WAAW,CAAC,OAAO,mBAAmB,CAAC;IAI5C,wBAAwB,CAC5B,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,gBAAgB,CAAC;CAqD7B"}

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