@breadstone/archipel-platform-mailing 0.0.34 → 0.0.35

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@breadstone/archipel-platform-mailing",
-  "version": "0.0.34",
+  "version": "0.0.35",
   "description": "Email delivery with strategy-based transport and template engines for NestJS applications.",
   "type": "commonjs",
   "main": "./src/index.js",
@@ -134,10 +134,10 @@
     "README.md"
   ],
   "dependencies": {
-    "@breadstone/archipel-platform-blob-storage": "0.0.34",
-    "@breadstone/archipel-platform-configuration": "0.0.34",
-    "@breadstone/archipel-platform-core": "0.0.34",
-    "@breadstone/archipel-platform-resources": "0.0.34",
+    "@breadstone/archipel-platform-blob-storage": "0.0.35",
+    "@breadstone/archipel-platform-configuration": "0.0.35",
+    "@breadstone/archipel-platform-core": "0.0.35",
+    "@breadstone/archipel-platform-resources": "0.0.35",
     "tslib": "2.8.1"
   },
   "peerDependencies": {

package/src/MailModule.d.ts

@@ -1,29 +1,50 @@
 import type { IConfigRegistryEntry } from '@breadstone/archipel-platform-configuration';
-import { type DynamicModule, type Provider } from '@nestjs/common';
+import { type DynamicModule, type Provider, type Type } from '@nestjs/common';
+import type { DeliveryStrategyBase } from './delivering/strategies/abstracts/DeliveryStrategyBase';
 import type { IMailTemplateRepository } from './ports/IMailTemplateRepository';
+import type { TemplateFetchStrategyBase } from './templating/strategies/abstracts/TemplateFetchStrategyBase';
 /**
  * Options for configuring the {@link MailModule}.
  *
  * @public
  */
 export interface IMailModuleOptions {
+    /**
+     * Concrete implementation of the {@link DeliveryStrategyBase} port.
+     * For example, `SmtpDeliveryStrategy`, `PostmarkDeliveryStrategy`, or `LogDeliveryStrategy`.
+     */
+    readonly deliveryStrategy: Type<DeliveryStrategyBase>;
+    /**
+     * Concrete implementation of the {@link TemplateFetchStrategyBase} port.
+     * For example, `FileTemplateFetchStrategy`, `BlobTemplateFetchStrategy`, or `DatabaseTemplateFetchStrategy`.
+     */
+    readonly templateFetchStrategy: Type<TemplateFetchStrategyBase>;
     /**
      * Whether to register the module globally.
      * Defaults to `true`.
      */
     readonly isGlobal?: boolean;
     /**
-     * Additional or overriding configuration entries.
-     * Merged with the platform default entries.
+     * Provider-specific configuration entries to register with the config module.
      */
     readonly configEntries?: ReadonlyArray<Omit<IConfigRegistryEntry, 'module'>>;
+    /**
+     * Template names to load when using the `FileTemplateFetchStrategy`.
+     * Each name corresponds to a resource file (e.g. `'AuthRegister'` loads
+     * `AuthRegister.html` and `AuthRegister.txt`).
+     *
+     * Defaults to an empty array (no templates loaded).
+     */
+    readonly templateNames?: ReadonlyArray<string>;
     /**
      * Provider for the `IMailTemplateRepository` port.
-     * Required when `MAIL_TEMPLATE_STRATEGY` is set to `'database'`.
+     * Required when using `DatabaseTemplateFetchStrategy`.
      *
      * Example:
      * ```typescript
      * MailModule.register({
+     *   deliveryStrategy: SmtpDeliveryStrategy,
+     *   templateFetchStrategy: DatabaseTemplateFetchStrategy,
      *   templateRepositoryProvider: {
      *     provide: MAIL_TEMPLATE_REPOSITORY_TOKEN,
      *     useClass: PrismaMailTemplateRepository,
@@ -36,19 +57,19 @@ export interface IMailModuleOptions {
 /**
  * Represents the mail module.
  *
- * Delivery and template strategies are resolved at runtime based on
- * configuration keys `MAIL_DELIVERY_STRATEGY` and `MAIL_TEMPLATE_STRATEGY`.
+ * Delivery and template strategies are selected at compile time via
+ * `IMailModuleOptions`. NestJS DI resolves the concrete classes.
  *
  * @public
  */
 export declare class MailModule {
     /**
-     * Registers the mail module with optional configuration.
+     * Registers the mail module with the specified configuration.
      *
      * @param options - Module registration options.
      * @returns A configured `DynamicModule`.
      *
      * @public
      */
-    static register(options?: IMailModuleOptions): DynamicModule;
+    static register(options: IMailModuleOptions): DynamicModule;
 }

package/src/MailModule.js

@@ -7,7 +7,6 @@ const tslib_1 = require("tslib");
 const archipel_platform_blob_storage_1 = require("@breadstone/archipel-platform-blob-storage");
 const archipel_platform_configuration_1 = require("@breadstone/archipel-platform-configuration");
 const archipel_platform_core_1 = require("@breadstone/archipel-platform-core");
-const archipel_platform_resources_1 = require("@breadstone/archipel-platform-resources");
 const common_1 = require("@nestjs/common");
 const env_1 = require("./env");
 const MailEventSubscriber_1 = require("./events/listeners/MailEventSubscriber");
@@ -19,14 +18,15 @@ const MailTokens_1 = require("./tokens/MailTokens");
 /**
  * Represents the mail module.
  *
- * Delivery and template strategies are resolved at runtime based on
- * configuration keys `MAIL_DELIVERY_STRATEGY` and `MAIL_TEMPLATE_STRATEGY`.
+ * Delivery and template strategies are selected at compile time via
+ * `IMailModuleOptions`. NestJS DI resolves the concrete classes.
  *
  * @public
  */
 let MailModule = MailModule_1 = class MailModule {
+    // #region Methods
     /**
-     * Registers the mail module with optional configuration.
+     * Registers the mail module with the specified configuration.
      *
      * @param options - Module registration options.
      * @returns A configured `DynamicModule`.
@@ -34,87 +34,42 @@ let MailModule = MailModule_1 = class MailModule {
      * @public
      */
     static register(options) {
-        const isGlobal = options?.isGlobal ?? true;
-        const configEntries = options?.configEntries ?? env_1.PLATFORM_MAILING_CONFIG_ENTRIES;
-        const additionalProviders = [];
-        if (options?.templateRepositoryProvider) {
-            additionalProviders.push(options.templateRepositoryProvider);
+        const isGlobal = options.isGlobal ?? true;
+        const configEntries = options.configEntries ?? env_1.PLATFORM_MAILING_CONFIG_ENTRIES;
+        const providers = [
+            {
+                provide: MailTokens_1.MAIL_TEMPLATE_FETCH_STRATEGY_TOKEN,
+                useClass: options.templateFetchStrategy,
+            },
+            {
+                provide: MailTokens_1.MAIL_DELIVERY_STRATEGY_TOKEN,
+                useClass: options.deliveryStrategy,
+            },
+            {
+                provide: MailTokens_1.MAIL_TEMPLATE_NAMES_TOKEN,
+                useValue: options.templateNames ?? [],
+            },
+            archipel_platform_core_1.ContentTemplateEngine,
+            MailService_1.MailService,
+            MailTemplateEngine_1.MailTemplateEngine,
+            MailVerificationService_1.MailVerificationService,
+            SmtpConnectionVerifier_1.SmtpConnectionVerifier,
+            MailEventSubscriber_1.MailEventSubscriber,
+        ];
+        const exports = [
+            MailService_1.MailService,
+            MailVerificationService_1.MailVerificationService,
+            SmtpConnectionVerifier_1.SmtpConnectionVerifier,
+        ];
+        if (options.templateRepositoryProvider) {
+            providers.push(options.templateRepositoryProvider);
         }
         return {
             module: MailModule_1,
             global: isGlobal,
             imports: [archipel_platform_configuration_1.ConfigModule.register('platform-mailing', configEntries), archipel_platform_blob_storage_1.BlobModule, archipel_platform_core_1.EventModule],
-            providers: [
-                ...additionalProviders,
-                {
-                    provide: MailTokens_1.MAIL_TEMPLATE_FETCH_STRATEGY_TOKEN,
-                    useFactory: async (configService, blobService, resourceManager, ...extra) => {
-                        const templateStrategy = configService.get(env_1.MAIL_TEMPLATE_STRATEGY.key);
-                        if (templateStrategy === 'file') {
-                            const { FileTemplateFetchStrategy } = await Promise.resolve().then(() => tslib_1.__importStar(require('./templating/strategies/file/FileTemplateFetchStrategy')));
-                            return new FileTemplateFetchStrategy(resourceManager);
-                        }
-                        if (templateStrategy === 'blob') {
-                            const { BlobTemplateFetchStrategy } = await Promise.resolve().then(() => tslib_1.__importStar(require('./templating/strategies/blob/BlobTemplateFetchStrategy')));
-                            return new BlobTemplateFetchStrategy(blobService);
-                        }
-                        if (templateStrategy === 'database') {
-                            const repository = extra[0];
-                            if (!repository) {
-                                throw new Error("Template strategy 'database' requires a templateRepositoryProvider in MailModule.register() options.");
-                            }
-                            const { DatabaseTemplateFetchStrategy } = await Promise.resolve().then(() => tslib_1.__importStar(require('./templating/strategies/database/DatabaseTemplateFetchStrategy')));
-                            return new DatabaseTemplateFetchStrategy(repository);
-                        }
-                        throw new Error(`Unknown template strategy: ${templateStrategy}`);
-                    },
-                    inject: [
-                        archipel_platform_configuration_1.ConfigService,
-                        archipel_platform_blob_storage_1.BlobService,
-                        archipel_platform_resources_1.ResourceManager,
-                        ...(options?.templateRepositoryProvider ? [MailTokens_1.MAIL_TEMPLATE_REPOSITORY_TOKEN] : []),
-                    ],
-                },
-                {
-                    provide: MailTokens_1.MAIL_DELIVERY_STRATEGY_TOKEN,
-                    useFactory: async (configService) => {
-                        const deliveryStrategy = configService.get(env_1.MAIL_DELIVERY_STRATEGY.key);
-                        if (deliveryStrategy === 'log') {
-                            const { LogDeliveryStrategy } = await Promise.resolve().then(() => tslib_1.__importStar(require('./delivering/strategies/logger/LogDeliveryStrategy')));
-                            return new LogDeliveryStrategy();
-                        }
-                        if (deliveryStrategy === 'smtp') {
-                            const { SmtpDeliveryStrategy } = await Promise.resolve().then(() => tslib_1.__importStar(require('./delivering/strategies/smtp/SmtpDeliveryStrategy')));
-                            return new SmtpDeliveryStrategy(configService);
-                        }
-                        if (deliveryStrategy === 'postmark') {
-                            const { PostmarkDeliveryStrategy } = await Promise.resolve().then(() => tslib_1.__importStar(require('./delivering/strategies/postmark/PostmarkDeliveryStrategy')));
-                            return new PostmarkDeliveryStrategy(configService);
-                        }
-                        if (deliveryStrategy === 'resend') {
-                            const { ResendDeliveryStrategy } = await Promise.resolve().then(() => tslib_1.__importStar(require('./delivering/strategies/resend/ResendDeliveryStrategy')));
-                            return new ResendDeliveryStrategy(configService);
-                        }
-                        if (deliveryStrategy === 'sendgrid') {
-                            const { SendGridDeliveryStrategy } = await Promise.resolve().then(() => tslib_1.__importStar(require('./delivering/strategies/sendgrid/SendGridDeliveryStrategy')));
-                            return new SendGridDeliveryStrategy(configService);
-                        }
-                        if (deliveryStrategy === 'mailgun') {
-                            const { MailgunDeliveryStrategy } = await Promise.resolve().then(() => tslib_1.__importStar(require('./delivering/strategies/mailgun/MailgunDeliveryStrategy')));
-                            return new MailgunDeliveryStrategy(configService);
-                        }
-                        throw new Error(`Unknown delivery strategy: ${deliveryStrategy}`);
-                    },
-                    inject: [archipel_platform_configuration_1.ConfigService],
-                },
-                archipel_platform_core_1.ContentTemplateEngine,
-                MailService_1.MailService,
-                MailTemplateEngine_1.MailTemplateEngine,
-                MailVerificationService_1.MailVerificationService,
-                SmtpConnectionVerifier_1.SmtpConnectionVerifier,
-                MailEventSubscriber_1.MailEventSubscriber,
-            ],
-            exports: [MailService_1.MailService, MailVerificationService_1.MailVerificationService, SmtpConnectionVerifier_1.SmtpConnectionVerifier],
+            providers,
+            exports,
         };
     }
 };

package/src/env.d.ts

@@ -1,8 +1,4 @@
 import { IConfigRegistryEntry } from '@breadstone/archipel-platform-configuration';
-/** Which template-fetch strategy to use (e.g. `file`, `blob`). */
-export declare const MAIL_TEMPLATE_STRATEGY: import("@breadstone/archipel-platform-configuration").IConfigKey<string>;
-/** Which delivery strategy to use (e.g. `smtp`, `postmark`, `resend`, `sendgrid`, `mailgun`, `log`). */
-export declare const MAIL_DELIVERY_STRATEGY: import("@breadstone/archipel-platform-configuration").IConfigKey<string>;
 /** Sender e-mail address shown in the `From` header. */
 export declare const MAIL_SENDER_EMAIL: import("@breadstone/archipel-platform-configuration").IConfigKey<string>;
 /** Template engine format identifier (e.g. `handlebars`). */

package/src/env.js

@@ -1,16 +1,12 @@
 "use strict";
 // #region Imports
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PLATFORM_MAILING_CONFIG_ENTRIES = exports.MAIL_PORT = exports.MAIL_USER = exports.MAIL_HOST = exports.MAIL_SMTP_PASSWORD = exports.MAIL_SMTP_USER = exports.MAIL_SMTP_SECURE = exports.MAIL_SMTP_PORT = exports.MAIL_SMTP_HOST = exports.MAIL_MAILGUN_DOMAIN = exports.MAIL_MAILGUN_API_KEY = exports.MAIL_SENDGRID_API_KEY = exports.MAIL_RESEND_API_KEY = exports.MAIL_POSTMARK_API_KEY = exports.MAIL_TEMPLATE_ENGINE_FORMAT = exports.MAIL_SENDER_EMAIL = exports.MAIL_DELIVERY_STRATEGY = exports.MAIL_TEMPLATE_STRATEGY = void 0;
+exports.PLATFORM_MAILING_CONFIG_ENTRIES = exports.MAIL_PORT = exports.MAIL_USER = exports.MAIL_HOST = exports.MAIL_SMTP_PASSWORD = exports.MAIL_SMTP_USER = exports.MAIL_SMTP_SECURE = exports.MAIL_SMTP_PORT = exports.MAIL_SMTP_HOST = exports.MAIL_MAILGUN_DOMAIN = exports.MAIL_MAILGUN_API_KEY = exports.MAIL_SENDGRID_API_KEY = exports.MAIL_RESEND_API_KEY = exports.MAIL_POSTMARK_API_KEY = exports.MAIL_TEMPLATE_ENGINE_FORMAT = exports.MAIL_SENDER_EMAIL = void 0;
 const archipel_platform_configuration_1 = require("@breadstone/archipel-platform-configuration");
 // #endregion
 // ──────────────────────────────────────────────────────────────
-// Delivery & Template Strategy
+// Core
 // ──────────────────────────────────────────────────────────────
-/** Which template-fetch strategy to use (e.g. `file`, `blob`). */
-exports.MAIL_TEMPLATE_STRATEGY = (0, archipel_platform_configuration_1.createConfigKey)('MAIL_TEMPLATE_STRATEGY');
-/** Which delivery strategy to use (e.g. `smtp`, `postmark`, `resend`, `sendgrid`, `mailgun`, `log`). */
-exports.MAIL_DELIVERY_STRATEGY = (0, archipel_platform_configuration_1.createConfigKey)('MAIL_DELIVERY_STRATEGY');
 /** Sender e-mail address shown in the `From` header. */
 exports.MAIL_SENDER_EMAIL = (0, archipel_platform_configuration_1.createConfigKey)('MAIL_SENDER_EMAIL');
 /** Template engine format identifier (e.g. `handlebars`). */
@@ -64,13 +60,7 @@ exports.MAIL_PORT = (0, archipel_platform_configuration_1.createConfigKey)('MAIL
 // ──────────────────────────────────────────────────────────────
 /** All configuration entries required by `platform-mailing`. */
 exports.PLATFORM_MAILING_CONFIG_ENTRIES = [
-    // Strategy
-    { key: exports.MAIL_TEMPLATE_STRATEGY, required: true, description: 'Template-fetch strategy (file, blob, database).' },
-    {
-        key: exports.MAIL_DELIVERY_STRATEGY,
-        required: true,
-        description: 'Delivery strategy (smtp, postmark, resend, sendgrid, mailgun, log).',
-    },
+    // Core
     { key: exports.MAIL_SENDER_EMAIL, required: true, description: 'Sender e-mail address for the From header.' },
     { key: exports.MAIL_TEMPLATE_ENGINE_FORMAT, required: true, description: 'Template engine format identifier.' },
     // Postmark

package/src/events/IMailEvents.d.ts

@@ -2,14 +2,25 @@ import { IEventMap } from '@breadstone/archipel-platform-core';
 /**
  * Represents the contract of events emitted by the mail domain.
  *
+ * Publishers only need to specify `recipientEmail`, `templateName`, and `templateParams`.
+ * The subject is resolved from the stored template (industry-standard behavior).
+ * An explicit `subject` can be provided as an override.
+ *
  * @public
  */
 export interface IMailEvents extends IEventMap {
     sendMail: {
+        /** Recipient email address. */
         recipientEmail: string;
-        subject: string;
+        /** Template key to resolve (e.g. `'AuthRegister'`). */
         templateName: string;
+        /** Placeholder values to interpolate into subject and body. */
         templateParams: Record<string, string | number | boolean | Date | undefined | null>;
+        /** Optional locale for template resolution (e.g. `'de'`, `'en'`). */
+        locale?: string;
+        /** Optional subject override. When omitted, resolved from the template. */
+        subject?: string;
+        /** Optional sender email override. When omitted, uses the configured default. */
         senderEmail?: string;
     };
 }

package/src/events/listeners/MailEventSubscriber.js

@@ -29,7 +29,8 @@ let MailEventSubscriber = MailEventSubscriber_1 = class MailEventSubscriber {
         this._mailService = mailService;
         this._subscription = eventHub.observe(MailEventKeys_1.SEND_MAIL_EVENT_KEY).subscribe({
             next: (payload) => {
-                this._logger.debug(`Received mail event for recipient ${(0, archipel_platform_core_1.maskSensitive)(payload.recipientEmail)} with subject "${(0, archipel_platform_core_1.maskSensitive)(payload.subject)}"`);
+                this._logger.debug(`Received mail event for recipient ${(0, archipel_platform_core_1.maskSensitive)(payload.recipientEmail)} ` +
+                    `with template "${payload.templateName}"${payload.subject ? ` (subject override: "${(0, archipel_platform_core_1.maskSensitive)(payload.subject)}")` : ''}`);
                 void this.handle(payload);
             },
             error: (err) => {

package/src/index.d.ts

@@ -5,6 +5,8 @@ export * from './events';
 export * from './MailModule';
 export * from './models/IMailAttachment';
 export * from './models/IMailTemplate';
+export * from './models/IMailTemplateVariants';
+export * from './models/MailTemplateFormat';
 export * from './ports/IMailTemplateRepository';
 export * from './services/MailService';
 export * from './services/MailVerificationService';

package/src/index.js

@@ -8,6 +8,8 @@ tslib_1.__exportStar(require("./events"), exports);
 tslib_1.__exportStar(require("./MailModule"), exports);
 tslib_1.__exportStar(require("./models/IMailAttachment"), exports);
 tslib_1.__exportStar(require("./models/IMailTemplate"), exports);
+tslib_1.__exportStar(require("./models/IMailTemplateVariants"), exports);
+tslib_1.__exportStar(require("./models/MailTemplateFormat"), exports);
 tslib_1.__exportStar(require("./ports/IMailTemplateRepository"), exports);
 tslib_1.__exportStar(require("./services/MailService"), exports);
 tslib_1.__exportStar(require("./services/MailVerificationService"), exports);

package/src/models/IMailTemplateVariants.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Represents the in-memory structure for a single template (multiple formats).
+ *
+ * @public
+ */
+export interface IMailTemplateVariants {
+    subject?: string;
+    html?: string;
+    txt?: string;
+}

package/src/models/IMailTemplateVariants.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=IMailTemplateVariants.js.map

package/src/models/MailTemplateFormat.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Union type of all supported template formats.
+ *
+ * @public
+ */
+export type MailTemplateFormat = 'html' | 'txt';

package/src/models/MailTemplateFormat.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=MailTemplateFormat.js.map

package/src/services/MailService.d.ts

@@ -37,17 +37,21 @@ export declare class MailService {
      * Sends an email using a predefined template (HTML or text).
      * Automatically uses the template format (either 'html' or 'txt') based on the environment variable.
      *
+     * When no `subject` is provided in `mailOptions`, the subject is resolved from the
+     * stored template and interpolated with the given `templateParams` (industry-standard
+     * behavior matching Mailchimp/SendGrid/Postmark).
+     *
      * @public
      * @param mailOptions.from - Sender's email address (optional, defaults to config)
      * @param mailOptions.to - Recipient's email address
-     * @param mailOptions.subject - Subject of the email
+     * @param mailOptions.subject - Subject of the email (optional — resolved from template if omitted)
      * @param templateOptions.templateName - Name of the template to be used
-     * @param templateOptions.params - Parameters to inject into the template
+     * @param templateOptions.templateParams - Parameters to inject into the template
      */
     sendTemplate(mailOptions: {
         from?: string;
         to: string;
-        subject: string;
+        subject?: string;
     }, templateOptions: {
         templateName: string;
         templateParams: Record<string, string | number | boolean | Date | undefined | null>;

package/src/services/MailService.js

@@ -62,17 +62,26 @@ let MailService = class MailService {
      * Sends an email using a predefined template (HTML or text).
      * Automatically uses the template format (either 'html' or 'txt') based on the environment variable.
      *
+     * When no `subject` is provided in `mailOptions`, the subject is resolved from the
+     * stored template and interpolated with the given `templateParams` (industry-standard
+     * behavior matching Mailchimp/SendGrid/Postmark).
+     *
      * @public
      * @param mailOptions.from - Sender's email address (optional, defaults to config)
      * @param mailOptions.to - Recipient's email address
-     * @param mailOptions.subject - Subject of the email
+     * @param mailOptions.subject - Subject of the email (optional — resolved from template if omitted)
      * @param templateOptions.templateName - Name of the template to be used
-     * @param templateOptions.params - Parameters to inject into the template
+     * @param templateOptions.templateParams - Parameters to inject into the template
      */
     async sendTemplate(mailOptions, templateOptions) {
         const content = this._mailTemplateEngine.compileTemplate(templateOptions.templateName, templateOptions.templateParams, this._mailTemplateFormat);
         const isHtml = this._mailTemplateFormat === 'html';
-        await this.send(mailOptions, content, isHtml);
+        const subject = mailOptions.subject ?? this._mailTemplateEngine.resolveSubject(templateOptions.templateName, templateOptions.templateParams);
+        if (!subject) {
+            throw new Error(`No subject provided and template '${templateOptions.templateName}' has no stored subject. ` +
+                'Either pass a subject in mailOptions or ensure the template includes a subject.');
+        }
+        await this.send({ from: mailOptions.from, to: mailOptions.to, subject }, content, isHtml);
     }
     /**
      * Performs a minimal email address validation. Not exhaustive but filters obvious mistakes.
@@ -97,9 +106,7 @@ let MailService = class MailService {
             if (!IMailAttachment_1.ALLOWED_ATTACHMENT_MIME_TYPES.includes(attachment.contentType)) {
                 throw new Error(`Unsupported attachment MIME type: '${attachment.contentType}'`);
             }
-            const size = typeof attachment.content === 'string'
-                ? Buffer.byteLength(attachment.content, 'utf-8')
-                : attachment.content.length;
+            const size = typeof attachment.content === 'string' ? Buffer.byteLength(attachment.content, 'utf-8') : attachment.content.length;
             if (size > IMailAttachment_1.MAX_ATTACHMENT_SIZE_BYTES) {
                 throw new Error(`Attachment '${attachment.filename}' exceeds maximum size of ${IMailAttachment_1.MAX_ATTACHMENT_SIZE_BYTES} bytes`);
             }

package/src/templating/MailTemplateEngine.d.ts

@@ -1,6 +1,6 @@
 import { ContentTemplateEngine } from '@breadstone/archipel-platform-core';
 import { OnModuleInit } from '@nestjs/common';
-import { MailTemplateFormat } from '../tokens/MailTokens';
+import type { MailTemplateFormat } from '../models/MailTemplateFormat';
 import { TemplateFetchStrategyBase } from './strategies/abstracts/TemplateFetchStrategyBase';
 /**
  * The `MailTemplateEngine` class.
@@ -35,6 +35,15 @@ export declare class MailTemplateEngine implements OnModuleInit {
      * @returns The compiled template as a string.
      */
     compileTemplate(templateKey: string, params: Record<string, unknown>, format: MailTemplateFormat): string;
+    /**
+     * Resolves and interpolates the subject line from a stored template.
+     *
+     * @public
+     * @param templateKey The key of the template.
+     * @param params The parameters to insert into the subject.
+     * @returns The compiled subject string, or `undefined` if no subject is stored.
+     */
+    resolveSubject(templateKey: string, params: Record<string, unknown>): string | undefined;
     private escapeHtmlParams;
     private escapeHtml;
 }

package/src/templating/MailTemplateEngine.js

@@ -66,6 +66,21 @@ let MailTemplateEngine = class MailTemplateEngine {
             throw error;
         }
     }
+    /**
+     * Resolves and interpolates the subject line from a stored template.
+     *
+     * @public
+     * @param templateKey The key of the template.
+     * @param params The parameters to insert into the subject.
+     * @returns The compiled subject string, or `undefined` if no subject is stored.
+     */
+    resolveSubject(templateKey, params) {
+        const templateVariants = this._templates[templateKey];
+        if (!templateVariants?.subject) {
+            return undefined;
+        }
+        return this._contentTemplateEngine.compileTemplate(templateVariants.subject, params);
+    }
     escapeHtmlParams(params) {
         const escaped = {};
         for (const [key, value] of Object.entries(params)) {
@@ -74,12 +89,7 @@ let MailTemplateEngine = class MailTemplateEngine {
         return escaped;
     }
     escapeHtml(text) {
-        return text
-            .replace(/&/g, '&')
-            .replace(/</g, '&lt;')
-            .replace(/>/g, '&gt;')
-            .replace(/"/g, '&quot;')
-            .replace(/'/g, '&#39;');
+        return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&#39;');
     }
 };
 exports.MailTemplateEngine = MailTemplateEngine;

package/src/templating/strategies/abstracts/TemplateFetchStrategyBase.d.ts

@@ -1,3 +1,4 @@
+import type { IMailTemplateVariants } from '../../../models/IMailTemplateVariants';
 /**
  * Represents the base class for template fetch strategies.
  *
@@ -17,8 +18,5 @@ export declare abstract class TemplateFetchStrategyBase {
      * @public
      * @abstract
      */
-    abstract load(): Promise<Record<string, {
-        html?: string;
-        txt?: string;
-    }>>;
+    abstract load(): Promise<Record<string, IMailTemplateVariants>>;
 }

package/src/templating/strategies/blob/BlobTemplateFetchStrategy.d.ts

@@ -1,5 +1,5 @@
 import { BlobService } from '@breadstone/archipel-platform-blob-storage';
-import { IMailTemplateVariants } from '../../../tokens/MailTokens';
+import type { IMailTemplateVariants } from '../../../models/IMailTemplateVariants';
 import { TemplateFetchStrategyBase } from '../abstracts/TemplateFetchStrategyBase';
 /**
  * The `BlobTemplateFetchStrategy` class.

package/src/templating/strategies/database/DatabaseTemplateFetchStrategy.d.ts

@@ -1,5 +1,5 @@
+import type { IMailTemplateVariants } from '../../../models/IMailTemplateVariants';
 import type { IMailTemplateRepository } from '../../../ports/IMailTemplateRepository';
-import type { IMailTemplateVariants } from '../../../tokens/MailTokens';
 import { TemplateFetchStrategyBase } from '../abstracts/TemplateFetchStrategyBase';
 /**
  * Template fetch strategy that loads templates from a database via the

package/src/templating/strategies/database/DatabaseTemplateFetchStrategy.js

@@ -44,6 +44,9 @@ let DatabaseTemplateFetchStrategy = DatabaseTemplateFetchStrategy_1 = class Data
                 templates[key] = {};
             }
             // Only set if not already filled (first match wins — default locale preferred)
+            if (template.subject && !templates[key].subject) {
+                templates[key].subject = template.subject;
+            }
             if (template.htmlBody && !templates[key].html) {
                 templates[key].html = template.htmlBody;
             }

package/src/templating/strategies/file/FileTemplateFetchStrategy.d.ts

@@ -1,25 +1,23 @@
 import { ResourceManager } from '@breadstone/archipel-platform-resources';
-import { IMailTemplateVariants } from '../../../tokens/MailTokens';
+import type { IMailTemplateVariants } from '../../../models/IMailTemplateVariants';
 import { TemplateFetchStrategyBase } from '../abstracts/TemplateFetchStrategyBase';
 /**
  * The `FileTemplateFetchStrategy` class.
  *
+ * Loads mail templates from the file system via `ResourceManager`.
+ * Template names are injected via `MAIL_TEMPLATE_NAMES_TOKEN` — defaults to an empty array.
+ *
  * @public
  */
 export declare class FileTemplateFetchStrategy extends TemplateFetchStrategyBase {
     private readonly _resourceManager;
+    private readonly _templateNames;
     private readonly _logger;
-    constructor(resourceManager: ResourceManager);
+    constructor(resourceManager: ResourceManager, templateNames: ReadonlyArray<string>);
     /**
      * Loads mail templates from the file system.
      *
      * @public
      */
     load(): Promise<Record<string, IMailTemplateVariants>>;
-    /**
-     * Returns the list of known template names.
-     *
-     * @private
-     */
-    private getTemplateNames;
 }

package/src/templating/strategies/file/FileTemplateFetchStrategy.js

@@ -6,20 +6,25 @@ exports.FileTemplateFetchStrategy = void 0;
 const tslib_1 = require("tslib");
 const archipel_platform_resources_1 = require("@breadstone/archipel-platform-resources");
 const common_1 = require("@nestjs/common");
+const MailTokens_1 = require("../../../tokens/MailTokens");
 const TemplateFetchStrategyBase_1 = require("../abstracts/TemplateFetchStrategyBase");
 // #endregion
 /**
  * The `FileTemplateFetchStrategy` class.
  *
+ * Loads mail templates from the file system via `ResourceManager`.
+ * Template names are injected via `MAIL_TEMPLATE_NAMES_TOKEN` — defaults to an empty array.
+ *
  * @public
  */
 let FileTemplateFetchStrategy = FileTemplateFetchStrategy_1 = class FileTemplateFetchStrategy extends TemplateFetchStrategyBase_1.TemplateFetchStrategyBase {
     // #endregion
     // #region Ctor
-    constructor(resourceManager) {
+    constructor(resourceManager, templateNames) {
         super();
         this._logger = new common_1.Logger(FileTemplateFetchStrategy_1.name);
         this._resourceManager = resourceManager;
+        this._templateNames = templateNames;
     }
     // #endregion
     // #region Methods
@@ -30,9 +35,8 @@ let FileTemplateFetchStrategy = FileTemplateFetchStrategy_1 = class FileTemplate
      */
     async load() {
         const templates = {};
-        const templateNames = this.getTemplateNames();
         let templateCount = 0;
-        for (const templateName of templateNames) {
+        for (const templateName of this._templateNames) {
             if (!templates[templateName]) {
                 templates[templateName] = {};
             }
@@ -52,20 +56,11 @@ let FileTemplateFetchStrategy = FileTemplateFetchStrategy_1 = class FileTemplate
         this._logger.log(`${templateCount} Templates loaded from file system`);
         return templates;
     }
-    // #endregion
-    // #region Private Methods
-    /**
-     * Returns the list of known template names.
-     *
-     * @private
-     */
-    getTemplateNames() {
-        return ['AppointmentInvitation', 'AppointmentUpdate', 'AuthForgotPassword', 'AuthRegister', 'AuthVerify'];
-    }
 };
 exports.FileTemplateFetchStrategy = FileTemplateFetchStrategy;
 exports.FileTemplateFetchStrategy = FileTemplateFetchStrategy = FileTemplateFetchStrategy_1 = tslib_1.__decorate([
     (0, common_1.Injectable)(),
-    tslib_1.__metadata("design:paramtypes", [archipel_platform_resources_1.ResourceManager])
+    tslib_1.__param(1, (0, common_1.Inject)(MailTokens_1.MAIL_TEMPLATE_NAMES_TOKEN)),
+    tslib_1.__metadata("design:paramtypes", [archipel_platform_resources_1.ResourceManager, Array])
 ], FileTemplateFetchStrategy);
 //# sourceMappingURL=FileTemplateFetchStrategy.js.map

package/src/tokens/MailTokens.d.ts

@@ -6,14 +6,4 @@
 export declare const MAIL_TEMPLATE_FETCH_STRATEGY_TOKEN: unique symbol;
 export declare const MAIL_DELIVERY_STRATEGY_TOKEN: unique symbol;
 export declare const MAIL_TEMPLATE_REPOSITORY_TOKEN: unique symbol;
-/**
- * Union type of all supported template formats.
- */
-export type MailTemplateFormat = 'html' | 'txt';
-/**
- * Represents the in-memory structure for a single template (multiple formats).
- */
-export interface IMailTemplateVariants {
-    html?: string;
-    txt?: string;
-}
+export declare const MAIL_TEMPLATE_NAMES_TOKEN: unique symbol;

package/src/tokens/MailTokens.js

@@ -7,8 +7,9 @@
  */
 // #endregion
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MAIL_TEMPLATE_REPOSITORY_TOKEN = exports.MAIL_DELIVERY_STRATEGY_TOKEN = exports.MAIL_TEMPLATE_FETCH_STRATEGY_TOKEN = void 0;
+exports.MAIL_TEMPLATE_NAMES_TOKEN = exports.MAIL_TEMPLATE_REPOSITORY_TOKEN = exports.MAIL_DELIVERY_STRATEGY_TOKEN = exports.MAIL_TEMPLATE_FETCH_STRATEGY_TOKEN = void 0;
 exports.MAIL_TEMPLATE_FETCH_STRATEGY_TOKEN = Symbol('MailTemplateFetchStrategy');
 exports.MAIL_DELIVERY_STRATEGY_TOKEN = Symbol('MailDeliveryStrategy');
 exports.MAIL_TEMPLATE_REPOSITORY_TOKEN = Symbol('MailTemplateRepository');
+exports.MAIL_TEMPLATE_NAMES_TOKEN = Symbol('MailTemplateNames');
 //# sourceMappingURL=MailTokens.js.map