@breadstone/archipel-platform-mailing 0.0.31 → 0.0.33

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@breadstone/archipel-platform-mailing",
-  "version": "0.0.31",
+  "version": "0.0.33",
   "description": "Email delivery with strategy-based transport and template engines for NestJS applications.",
   "type": "commonjs",
   "main": "./src/index.js",
@@ -99,10 +99,10 @@
     "README.md"
   ],
   "dependencies": {
-    "@breadstone/archipel-platform-blob-storage": "0.0.31",
-    "@breadstone/archipel-platform-configuration": "0.0.31",
-    "@breadstone/archipel-platform-core": "0.0.31",
-    "@breadstone/archipel-platform-resources": "0.0.31",
+    "@breadstone/archipel-platform-blob-storage": "0.0.33",
+    "@breadstone/archipel-platform-configuration": "0.0.33",
+    "@breadstone/archipel-platform-core": "0.0.33",
+    "@breadstone/archipel-platform-resources": "0.0.33",
     "tslib": "2.8.1"
   },
   "peerDependencies": {
@@ -149,7 +149,7 @@
     "@sendgrid/mail": "8.1.6",
     "form-data": "4.0.5",
     "mailgun.js": "13.0.0",
-    "nodemailer": "8.0.5",
+    "nodemailer": "8.0.6",
     "postmark": "4.0.7",
     "resend": "6.12.2",
     "rxjs": "7.8.2",

package/src/MailTokens.d.ts

@@ -5,6 +5,7 @@
  */
 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.
  */

package/src/MailTokens.js

@@ -7,7 +7,8 @@
  */
 // #endregion
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MAIL_DELIVERY_STRATEGY_TOKEN = exports.MAIL_TEMPLATE_FETCH_STRATEGY_TOKEN = void 0;
+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');
 //# sourceMappingURL=MailTokens.js.map

package/src/env.js

@@ -65,7 +65,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).' },
+    { key: exports.MAIL_TEMPLATE_STRATEGY, required: true, description: 'Template-fetch strategy (file, blob, database).' },
     {
         key: exports.MAIL_DELIVERY_STRATEGY,
         required: true,

package/src/events/listeners/MailEventSubscriber.d.ts

@@ -1,5 +1,5 @@
-import { OnModuleDestroy } from '@nestjs/common';
 import { EventHub } from '@breadstone/archipel-platform-core';
+import { OnModuleDestroy } from '@nestjs/common';
 import { MailService } from '../../services/MailService';
 /**
  * Bridges verification email events to the {@link MailService} delivery workflow.
@@ -9,6 +9,7 @@ import { MailService } from '../../services/MailService';
 export declare class MailEventSubscriber implements OnModuleDestroy {
     private readonly _mailService;
     private readonly _subscription;
+    private readonly _logger;
     /**
      * Initializes a new instance of the {@link MailEventSubscriber} class.
      *

package/src/events/listeners/MailEventSubscriber.js

@@ -1,10 +1,11 @@
 "use strict";
 // #region Imports
+var MailEventSubscriber_1;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MailEventSubscriber = void 0;
 const tslib_1 = require("tslib");
-const common_1 = require("@nestjs/common");
 const archipel_platform_core_1 = require("@breadstone/archipel-platform-core");
+const common_1 = require("@nestjs/common");
 const MailService_1 = require("../../services/MailService");
 const MailEventKeys_1 = require("../MailEventKeys");
 // #endregion
@@ -13,7 +14,7 @@ const MailEventKeys_1 = require("../MailEventKeys");
  *
  * @public
  */
-let MailEventSubscriber = class MailEventSubscriber {
+let MailEventSubscriber = MailEventSubscriber_1 = class MailEventSubscriber {
     // #endregion
     // #region Ctor
     /**
@@ -24,11 +25,16 @@ let MailEventSubscriber = class MailEventSubscriber {
      * @param eventHub The shared event hub that emits verification email requests.
      */
     constructor(mailService, eventHub) {
+        this._logger = new common_1.Logger(MailEventSubscriber_1.name);
         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)}"`);
                 void this.handle(payload);
             },
+            error: (err) => {
+                this._logger.error('Error handling mail event', err);
+            },
         });
     }
     // #endregion
@@ -60,7 +66,7 @@ let MailEventSubscriber = class MailEventSubscriber {
     }
 };
 exports.MailEventSubscriber = MailEventSubscriber;
-exports.MailEventSubscriber = MailEventSubscriber = tslib_1.__decorate([
+exports.MailEventSubscriber = MailEventSubscriber = MailEventSubscriber_1 = tslib_1.__decorate([
     (0, common_1.Injectable)(),
     tslib_1.__metadata("design:paramtypes", [MailService_1.MailService, archipel_platform_core_1.EventHub])
 ], MailEventSubscriber);

package/src/index.d.ts

@@ -3,11 +3,14 @@ export * from './errors/MailDeliveryError';
 export * from './events';
 export * from './MailTokens';
 export * from './models/IMailAttachment';
+export * from './models/IMailTemplate';
+export * from './ports/IMailTemplateRepository';
 export * from './services/MailService';
 export * from './services/MailVerificationService';
 export * from './services/SmtpConnectionVerifier';
 export * from './services/strategies/abstracts/DeliveryStrategyBase';
 export * from './templating/MailTemplateEngine';
 export * from './templating/strategies/abstracts/TemplateFetchStrategyBase';
+export * from './templating/strategies/DatabaseTemplateFetchStrategy';
 export * from './tokens/MailModule';
 export type { IMailModuleOptions } from './tokens/MailModule';

package/src/index.js

@@ -6,11 +6,14 @@ tslib_1.__exportStar(require("./errors/MailDeliveryError"), exports);
 tslib_1.__exportStar(require("./events"), exports);
 tslib_1.__exportStar(require("./MailTokens"), exports);
 tslib_1.__exportStar(require("./models/IMailAttachment"), exports);
+tslib_1.__exportStar(require("./models/IMailTemplate"), exports);
+tslib_1.__exportStar(require("./ports/IMailTemplateRepository"), exports);
 tslib_1.__exportStar(require("./services/MailService"), exports);
 tslib_1.__exportStar(require("./services/MailVerificationService"), exports);
 tslib_1.__exportStar(require("./services/SmtpConnectionVerifier"), exports);
 tslib_1.__exportStar(require("./services/strategies/abstracts/DeliveryStrategyBase"), exports);
 tslib_1.__exportStar(require("./templating/MailTemplateEngine"), exports);
 tslib_1.__exportStar(require("./templating/strategies/abstracts/TemplateFetchStrategyBase"), exports);
+tslib_1.__exportStar(require("./templating/strategies/DatabaseTemplateFetchStrategy"), exports);
 tslib_1.__exportStar(require("./tokens/MailModule"), exports);
 //# sourceMappingURL=index.js.map

package/src/models/IMailTemplate.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Represents a single mail template record stored in a persistent store.
+ *
+ * @public
+ */
+export interface IMailTemplate {
+    /**
+     * Unique template key used to identify this template (e.g. `AuthRegister`, `AppointmentInvitation`).
+     */
+    readonly key: string;
+    /**
+     * Locale identifier (e.g. `de`, `en`). Used for multi-language support.
+     * When `undefined`, it is the default/fallback template.
+     */
+    readonly locale?: string;
+    /**
+     * Default subject line for this template.
+     * Can contain placeholders (e.g. `{{appName}}`).
+     */
+    readonly subject: string;
+    /**
+     * HTML body of the template. Contains Handlebars-style placeholders.
+     */
+    readonly htmlBody?: string;
+    /**
+     * Plain-text body of the template. Contains Handlebars-style placeholders.
+     */
+    readonly txtBody?: string;
+    /**
+     * Human-readable description of this template's purpose.
+     */
+    readonly description?: string;
+    /**
+     * List of placeholder names expected by this template (for documentation/validation).
+     */
+    readonly placeholders?: ReadonlyArray<string>;
+}

package/src/models/IMailTemplate.js

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

package/src/ports/IMailTemplateRepository.d.ts

@@ -0,0 +1,39 @@
+import type { IMailTemplate } from '../models/IMailTemplate';
+/**
+ * Port interface for mail template persistence.
+ *
+ * Applications must implement this interface and register the implementation
+ * via the `MAIL_TEMPLATE_REPOSITORY_TOKEN` when using the `database` template strategy.
+ *
+ * @public
+ */
+export interface IMailTemplateRepository {
+    /**
+     * Finds a template by its unique key and optional locale.
+     * When no locale is provided, returns the default (locale-agnostic) template.
+     *
+     * @param key - The template key (e.g. `AuthRegister`).
+     * @param locale - Optional locale identifier (e.g. `de`, `en`).
+     * @returns The matching template, or `undefined` if not found.
+     */
+    findByKey(key: string, locale?: string): Promise<IMailTemplate | undefined>;
+    /**
+     * Returns all templates available in the store.
+     */
+    findAll(): Promise<Array<IMailTemplate>>;
+    /**
+     * Creates or updates a template. Upsert semantics: if a template with the
+     * same `key` and `locale` exists, it is overwritten.
+     *
+     * @param template - The template to persist.
+     * @returns The persisted template.
+     */
+    upsert(template: IMailTemplate): Promise<IMailTemplate>;
+    /**
+     * Deletes a template by key and locale.
+     *
+     * @param key - The template key.
+     * @param locale - Optional locale. When omitted, deletes the default template.
+     */
+    delete(key: string, locale?: string): Promise<void>;
+}

package/src/ports/IMailTemplateRepository.js

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

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

@@ -0,0 +1,26 @@
+import type { IMailTemplateRepository } from '../../ports/IMailTemplateRepository';
+import { TemplateFetchStrategyBase } from './abstracts/TemplateFetchStrategyBase';
+import type { IMailTemplateVariants } from '../../MailTokens';
+/**
+ * Template fetch strategy that loads templates from a database via the
+ * {@link IMailTemplateRepository} port.
+ *
+ * Applications provide the concrete repository implementation at module
+ * registration time. This strategy loads all templates on module init
+ * and caches them in-memory.
+ *
+ * @public
+ */
+export declare class DatabaseTemplateFetchStrategy extends TemplateFetchStrategyBase {
+    private readonly _repository;
+    private readonly _logger;
+    constructor(repository: IMailTemplateRepository);
+    /**
+     * Loads all templates from the database and returns them grouped by key.
+     * Only the default locale (no locale or first match) is loaded into the
+     * in-memory cache used by `MailTemplateEngine`.
+     *
+     * @public
+     */
+    load(): Promise<Record<string, IMailTemplateVariants>>;
+}

package/src/templating/strategies/DatabaseTemplateFetchStrategy.js

@@ -0,0 +1,65 @@
+"use strict";
+// #region Imports
+var DatabaseTemplateFetchStrategy_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DatabaseTemplateFetchStrategy = void 0;
+const tslib_1 = require("tslib");
+const common_1 = require("@nestjs/common");
+const MailTokens_1 = require("../../MailTokens");
+const TemplateFetchStrategyBase_1 = require("./abstracts/TemplateFetchStrategyBase");
+// #endregion
+/**
+ * Template fetch strategy that loads templates from a database via the
+ * {@link IMailTemplateRepository} port.
+ *
+ * Applications provide the concrete repository implementation at module
+ * registration time. This strategy loads all templates on module init
+ * and caches them in-memory.
+ *
+ * @public
+ */
+let DatabaseTemplateFetchStrategy = DatabaseTemplateFetchStrategy_1 = class DatabaseTemplateFetchStrategy extends TemplateFetchStrategyBase_1.TemplateFetchStrategyBase {
+    // #endregion
+    // #region Ctor
+    constructor(repository) {
+        super();
+        this._logger = new common_1.Logger(DatabaseTemplateFetchStrategy_1.name);
+        this._repository = repository;
+    }
+    // #endregion
+    // #region Methods
+    /**
+     * Loads all templates from the database and returns them grouped by key.
+     * Only the default locale (no locale or first match) is loaded into the
+     * in-memory cache used by `MailTemplateEngine`.
+     *
+     * @public
+     */
+    async load() {
+        const templates = {};
+        const allTemplates = await this._repository.findAll();
+        for (const template of allTemplates) {
+            const key = template.key;
+            if (!templates[key]) {
+                templates[key] = {};
+            }
+            // Only set if not already filled (first match wins — default locale preferred)
+            if (template.htmlBody && !templates[key].html) {
+                templates[key].html = template.htmlBody;
+            }
+            if (template.txtBody && !templates[key].txt) {
+                templates[key].txt = template.txtBody;
+            }
+        }
+        const templateCount = Object.keys(templates).length;
+        this._logger.log(`${templateCount} template(s) loaded from database`);
+        return templates;
+    }
+};
+exports.DatabaseTemplateFetchStrategy = DatabaseTemplateFetchStrategy;
+exports.DatabaseTemplateFetchStrategy = DatabaseTemplateFetchStrategy = DatabaseTemplateFetchStrategy_1 = tslib_1.__decorate([
+    (0, common_1.Injectable)(),
+    tslib_1.__param(0, (0, common_1.Inject)(MailTokens_1.MAIL_TEMPLATE_REPOSITORY_TOKEN)),
+    tslib_1.__metadata("design:paramtypes", [Object])
+], DatabaseTemplateFetchStrategy);
+//# sourceMappingURL=DatabaseTemplateFetchStrategy.js.map

package/src/tokens/MailModule.d.ts

@@ -1,5 +1,6 @@
 import type { IConfigRegistryEntry } from '@breadstone/archipel-platform-configuration';
-import { type DynamicModule } from '@nestjs/common';
+import { type DynamicModule, type Provider } from '@nestjs/common';
+import type { IMailTemplateRepository } from '../ports/IMailTemplateRepository';
 /**
  * Options for configuring the {@link MailModule}.
  *
@@ -16,6 +17,21 @@ export interface IMailModuleOptions {
      * Merged with the platform default entries.
      */
     readonly configEntries?: ReadonlyArray<Omit<IConfigRegistryEntry, 'module'>>;
+    /**
+     * Provider for the `IMailTemplateRepository` port.
+     * Required when `MAIL_TEMPLATE_STRATEGY` is set to `'database'`.
+     *
+     * Example:
+     * ```typescript
+     * MailModule.register({
+     *   templateRepositoryProvider: {
+     *     provide: MAIL_TEMPLATE_REPOSITORY_TOKEN,
+     *     useClass: PrismaMailTemplateRepository,
+     *   }
+     * })
+     * ```
+     */
+    readonly templateRepositoryProvider?: Provider<IMailTemplateRepository>;
 }
 /**
  * Represents the mail module.

package/src/tokens/MailModule.js

@@ -36,14 +36,19 @@ let MailModule = MailModule_1 = class MailModule {
     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);
+        }
         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) => {
+                    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/FileTemplateFetchStrategy')));
@@ -53,9 +58,22 @@ let MailModule = MailModule_1 = class MailModule {
                             const { BlobTemplateFetchStrategy } = await Promise.resolve().then(() => tslib_1.__importStar(require('../templating/strategies/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/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],
+                    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,