@brilab-mailer/core 0.0.1-beta.47

package/README.md

@@ -0,0 +1,110 @@
+# @brilab-mailer/core
+
+## Overview
+`@brilab-mailer/core` provides the foundational NestJS module responsible for:
+- registering email providers  
+- registering template engines  
+- orchestrating rendering + sending  
+- exposing `MailerService` as a unified high-level interface  
+
+This is the heart of the Brilab Mailer architecture.
+
+---
+
+## High-Level Architecture
+
+```
+                +---------------------+
+                |  NestJS Application |
+                +---------------------+
+                           |
+                           v
+                +---------------------+
+                |    MailerModule     |
+                +---------------------+
+                   |             |
+                   v             v
+     +-------------------+   +-------------------+
+     | MailerProvider    |   | TemplateEngine    |
+     +-------------------+   +-------------------+
+```
+
+---
+
+## Core Responsibilities
+
+### 1. Provider Registration
+You pass `providerClass` in `MailerModule.register()`:
+```ts
+MailerModule.register({
+  providerClass: MailtrapApiProvider,
+});
+```
+
+Core will:
+- instantiate the provider
+- validate that it implements `MailerProvider`
+- expose it through `MAILER_PROVIDER`
+
+---
+
+### 2. Template Engine Registration
+```ts
+MailerModule.register({
+  templateEngineClass: HandlebarsTemplateEngine,
+});
+```
+
+---
+
+### 3. Unified MailerService
+```ts
+await this.mailer.send({
+  to: email,
+  subject: 'Welcome!',
+  html: await this.template.render('welcome', { name }),
+});
+```
+
+---
+
+## API Documentation
+
+### `MailerModule.register(options)`
+```ts
+interface MailerModuleOptions {
+  providerClass: Type<MailerProvider>;
+  templateEngineClass?: Type<MailerTemplateEngine>;
+}
+```
+
+---
+
+### `MailerService`
+
+```ts
+send(options: MailerSendOptions): Promise<void>
+render(template: string, context: any): Promise<string>
+```
+
+---
+
+## Error Handling Strategy
+- missing provider → `MailerMissingProviderException`
+- provider.send() error → wrapped into `MailerProviderException`
+- missing template engine → bypass rendering (raw content)
+
+---
+
+## Lifecycle
+- provider instantiated once per module
+- template engine instantiated once
+- service stateless
+
+---
+
+## Best Practices
+- Always use dynamic module configuration.
+- Use ConfigModule for provider secrets.
+- Keep providers stateless.
+

package/index.d.ts

@@ -0,0 +1,3 @@
+export * from './lib/mailer.service.js';
+export * from './lib/mailer.module.js';
+//# sourceMappingURL=index.d.ts.map

package/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC;AACxC,cAAc,wBAAwB,CAAC"}

package/index.js

@@ -0,0 +1,2 @@
+export * from './lib/mailer.service.js';
+export * from './lib/mailer.module.js';

package/lib/mailer-sender.d.ts

@@ -0,0 +1,10 @@
+import { MailerProvider, MailerMessagesBuilder } from '@brilab-mailer/contracts';
+import { MailerService } from "./mailer.service.js";
+type MailerProviderType<MessagePayload> = MailerProvider<any, any, MessagePayload>;
+export declare class MailerSender<MessagePayload = object, Provider extends MailerProviderType<MessagePayload> = MailerProviderType<MessagePayload>> extends MailerMessagesBuilder {
+    private readonly _send;
+    constructor(_send: MailerService<Provider>['send']);
+    send(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=mailer-sender.d.ts.map

package/lib/mailer-sender.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mailer-sender.d.ts","sourceRoot":"","sources":["../../src/lib/mailer-sender.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,cAAc,EACd,qBAAqB,EACrB,MAAM,0BAA0B,CAAA;AACjC,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD,KAAK,kBAAkB,CAAC,cAAc,IAAI,cAAc,CAAC,GAAG,EAAE,GAAG,EAAE,cAAc,CAAC,CAAA;AAElF,qBAAa,YAAY,CACxB,cAAc,GAAG,MAAM,EACvB,QAAQ,SAAS,kBAAkB,CAAC,cAAc,CAAC,GAAG,kBAAkB,CAAC,cAAc,CAAC,CACvF,SAAQ,qBAAqB;IAE7B,OAAO,CAAC,QAAQ,CAAC,KAAK;gBAAL,KAAK,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC;IAK3C,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAIlC"}

package/lib/mailer-sender.js

@@ -0,0 +1,12 @@
+import { MailerMessagesBuilder, } from '@brilab-mailer/contracts';
+export class MailerSender extends MailerMessagesBuilder {
+    _send;
+    constructor(_send) {
+        super();
+        this._send = _send;
+    }
+    async send() {
+        const resolved = this.prepare();
+        return this._send(resolved);
+    }
+}

package/lib/mailer.constants.d.ts

@@ -0,0 +1,3 @@
+export declare const MAILER_RETRY_ATTEMPTS_DEFAULT = 3;
+export declare const MAILER_RETRY_BACKOFF_MS_DEFAULT: number[];
+//# sourceMappingURL=mailer.constants.d.ts.map

package/lib/mailer.constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mailer.constants.d.ts","sourceRoot":"","sources":["../../src/lib/mailer.constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,6BAA6B,IAAI,CAAC;AAC/C,eAAO,MAAM,+BAA+B,UAAoB,CAAC"}

package/lib/mailer.constants.js

@@ -0,0 +1,2 @@
+export const MAILER_RETRY_ATTEMPTS_DEFAULT = 3;
+export const MAILER_RETRY_BACKOFF_MS_DEFAULT = [500, 1000, 2000];

package/lib/mailer.module.d.ts

@@ -0,0 +1,6 @@
+import { DynamicModule } from '@nestjs/common';
+import type { MailerModuleParams } from './types.js';
+export declare class MailerModule {
+    static register(params: MailerModuleParams): DynamicModule;
+}
+//# sourceMappingURL=mailer.module.d.ts.map

package/lib/mailer.module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mailer.module.d.ts","sourceRoot":"","sources":["../../src/lib/mailer.module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAU,MAAM,gBAAgB,CAAC;AAavD,OAAO,KAAK,EAAuB,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAEzE,qBACa,YAAY;IACxB,MAAM,CAAC,QAAQ,CAAC,MAAM,EAAE,kBAAkB,GAAG,aAAa;CAoD1D"}

package/lib/mailer.module.js

@@ -0,0 +1,60 @@
+var MailerModule_1;
+import { __decorate } from "tslib";
+import { Module } from '@nestjs/common';
+import { ConfigModule, ConfigService } from '@nestjs/config';
+import { MAILER_OPTIONS, MAILER_PROVIDER, MAILER_PROVIDER_NATIVE_CLIENT, MAILER_PROVIDER_OPTIONS, MAILER_RETRY_ATTEMPTS, MAILER_RETRY_BACKOFF_MS, } from '@brilab-mailer/contracts';
+import { MailerService } from './mailer.service.js';
+import { MAILER_RETRY_ATTEMPTS_DEFAULT, MAILER_RETRY_BACKOFF_MS_DEFAULT } from "./mailer.constants.js";
+let MailerModule = MailerModule_1 = class MailerModule {
+    static register(params) {
+        if (!params?.providerClass) {
+            throw new Error('[MailerModule] providerClass is required. ' +
+                'Example: MailerModule.register({ providerClass: MailtrapApiProvider, templateEngineClass: HandlebarsTemplateEngine })');
+        }
+        return {
+            module: MailerModule_1,
+            imports: [ConfigModule],
+            providers: [
+                {
+                    provide: MAILER_OPTIONS,
+                    useFactory: (config) => {
+                        const maxAttempts = config.get(MAILER_RETRY_ATTEMPTS) ?? MAILER_RETRY_ATTEMPTS_DEFAULT;
+                        const backoffConfig = config.get(MAILER_RETRY_BACKOFF_MS);
+                        const backoffMs = backoffConfig
+                            ? backoffConfig.split(',').map((v) => Number(v.trim()) || 0)
+                            : MAILER_RETRY_BACKOFF_MS_DEFAULT;
+                        return {
+                            maxAttempts: params.options?.maxAttempts ?? maxAttempts,
+                            backoffMs: (params.options?.backoffMs ?? backoffMs),
+                        };
+                    },
+                    inject: [ConfigService],
+                },
+                {
+                    provide: MAILER_PROVIDER_OPTIONS,
+                    useValue: params.providerOptions || {},
+                },
+                {
+                    provide: MAILER_PROVIDER,
+                    useClass: params.providerClass,
+                },
+                {
+                    provide: MAILER_PROVIDER_NATIVE_CLIENT,
+                    useFactory: (provider) => provider?.getClient?.(),
+                    inject: [MAILER_PROVIDER],
+                },
+                MailerService,
+            ],
+            exports: [
+                MailerService,
+                MAILER_OPTIONS,
+                MAILER_PROVIDER_NATIVE_CLIENT,
+                MAILER_PROVIDER
+            ]
+        };
+    }
+};
+MailerModule = MailerModule_1 = __decorate([
+    Module({})
+], MailerModule);
+export { MailerModule };

package/lib/mailer.service.d.ts

@@ -0,0 +1,17 @@
+import { ConfigService } from '@nestjs/config';
+import { MailerMessagesResolved } from '@brilab-mailer/contracts';
+import type { MailerProvider, MailerNativeClientType } from '@brilab-mailer/contracts';
+import type { MailerModuleOptions } from "./types.js";
+import { MailerSender } from "./mailer-sender.js";
+export declare class MailerService<Provider extends MailerProvider<any, any, any> = MailerProvider> {
+    private readonly config;
+    private readonly options;
+    private readonly provider;
+    private readonly native_client?;
+    constructor(config: ConfigService, options: MailerModuleOptions, provider: Provider, native_client?: MailerNativeClientType<Provider> | undefined);
+    get nativeClient(): MailerNativeClientType<Provider>;
+    sender(): MailerSender<object, Provider>;
+    send(resolved: MailerMessagesResolved): Promise<void>;
+    private withRetry;
+}
+//# sourceMappingURL=mailer.service.d.ts.map

package/lib/mailer.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mailer.service.d.ts","sourceRoot":"","sources":["../../src/lib/mailer.service.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAGyB,sBAAsB,EACrD,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EACX,cAAc,EACd,sBAAsB,EACtB,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACtD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,qBACa,aAAa,CAAC,QAAQ,SAAS,cAAc,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,cAAc;IAExF,OAAO,CAAC,QAAQ,CAAC,MAAM;IAEvB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAExB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAGzB,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC;gBAPd,MAAM,EAAE,aAAa,EAErB,OAAO,EAAE,mBAAmB,EAE5B,QAAQ,EAAE,QAAQ,EAGlB,aAAa,CAAC,EAAE,sBAAsB,CAAC,QAAQ,CAAC,YAAA;IAKlE,IAAW,YAAY,IAAI,sBAAsB,CAAC,QAAQ,CAAC,CAQ1D;IAEM,MAAM,IAAI,YAAY,CAAC,MAAM,EAAE,QAAQ,CAAC;IAMlC,IAAI,CAAC,QAAQ,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC;YAUpD,SAAS;CAsBvB"}

package/lib/mailer.service.js

@@ -0,0 +1,66 @@
+import { __decorate, __metadata, __param } from "tslib";
+import { Inject, Injectable, Optional } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { MAILER_OPTIONS, MAILER_PROVIDER, MAILER_PROVIDER_NATIVE_CLIENT, } from '@brilab-mailer/contracts';
+import { MailerSender } from "./mailer-sender.js";
+let MailerService = class MailerService {
+    config;
+    options;
+    provider;
+    native_client;
+    constructor(config, options, provider, native_client) {
+        this.config = config;
+        this.options = options;
+        this.provider = provider;
+        this.native_client = native_client;
+        console.log('this.config', this.config);
+    }
+    get nativeClient() {
+        const injected = this.native_client;
+        if (injected)
+            return injected;
+        const fromProvider = this.provider.getClient?.();
+        if (fromProvider)
+            return fromProvider;
+        throw new Error('[MailerService] Native client is not available');
+    }
+    sender() {
+        return new MailerSender((...rest) => this.send.call(this, ...rest));
+    }
+    async send(resolved) {
+        const payload = this.provider.createPayload(resolved);
+        const run = async () => {
+            await this.provider.send(payload);
+        };
+        return this.withRetry(run);
+    }
+    async withRetry(fn) {
+        let attempt = 0;
+        let lastError;
+        const { maxAttempts, backoffMs } = this.options;
+        while (attempt < maxAttempts) {
+            try {
+                await fn();
+                return;
+            }
+            catch (err) {
+                lastError = err;
+                attempt++;
+                if (attempt >= maxAttempts)
+                    break;
+                const delay = backoffMs[Math.min(attempt - 1, backoffMs.length - 1)];
+                await new Promise(res => setTimeout(res, delay));
+            }
+        }
+        throw lastError;
+    }
+};
+MailerService = __decorate([
+    Injectable(),
+    __param(1, Inject(MAILER_OPTIONS)),
+    __param(2, Inject(MAILER_PROVIDER)),
+    __param(3, Optional()),
+    __param(3, Inject(MAILER_PROVIDER_NATIVE_CLIENT)),
+    __metadata("design:paramtypes", [ConfigService, Object, Object, Object])
+], MailerService);
+export { MailerService };

package/lib/mailer_templater.module.d.ts

@@ -0,0 +1,10 @@
+import { DynamicModule, Type } from '@nestjs/common';
+import { MailerProvider, MailerTemplateEngine } from '@brilab-mailer/contracts';
+export interface MailerModuleOptions {
+    providerClass: Type<MailerProvider>;
+    templateEngineClass: Type<MailerTemplateEngine>;
+}
+export declare class MailerModule {
+    static register(options: MailerModuleOptions): DynamicModule;
+}
+//# sourceMappingURL=mailer_templater.module.d.ts.map

package/lib/mailer_templater.module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mailer_templater.module.d.ts","sourceRoot":"","sources":["../../src/lib/mailer_templater.module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAU,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAE7D,OAAO,EAGN,cAAc,EACd,oBAAoB,EACpB,MAAM,0BAA0B,CAAC;AAGlC,MAAM,WAAW,mBAAmB;IACnC,aAAa,EAAE,IAAI,CAAC,cAAc,CAAC,CAAC;IACpC,mBAAmB,EAAE,IAAI,CAAC,oBAAoB,CAAC,CAAC;CAChD;AAED,qBACa,YAAY;IACxB,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,mBAAmB,GAAG,aAAa;CAgC5D"}

package/lib/mailer_templater.module.js

@@ -0,0 +1,38 @@
+var MailerModule_1;
+import { __decorate } from "tslib";
+import { Module } from '@nestjs/common';
+import { ConfigModule } from '@nestjs/config';
+import { MAILER_PROVIDER, MAILER_TEMPLATE_ENGINE, } from '@brilab-mailer/contracts';
+import { MailerService } from './mailer.service.js';
+let MailerModule = MailerModule_1 = class MailerModule {
+    static register(options) {
+        if (!options?.providerClass) {
+            throw new Error('[MailerModule] providerClass is required. ' +
+                'Example: MailerModule.register({ providerClass: MailtrapApiProvider, templateEngineClass: HandlebarsTemplateEngine })');
+        }
+        if (!options?.templateEngineClass) {
+            throw new Error('[MailerModule] templateEngineClass is required. ' +
+                'Example: MailerModule.register({ providerClass: MailtrapApiProvider, templateEngineClass: HandlebarsTemplateEngine })');
+        }
+        return {
+            module: MailerModule_1,
+            imports: [ConfigModule],
+            providers: [
+                {
+                    provide: MAILER_PROVIDER,
+                    useClass: options.providerClass,
+                },
+                {
+                    provide: MAILER_TEMPLATE_ENGINE,
+                    useClass: options.templateEngineClass,
+                },
+                MailerService,
+            ],
+            exports: [MailerService],
+        };
+    }
+};
+MailerModule = MailerModule_1 = __decorate([
+    Module({})
+], MailerModule);
+export { MailerModule };

package/lib/types.d.ts

@@ -0,0 +1,12 @@
+import { Type } from "@nestjs/common";
+import { MailerProvider, type MailerProviderOptionsType } from "@brilab-mailer/contracts";
+export interface MailerModuleOptions {
+    maxAttempts: number;
+    backoffMs: [number, number, number];
+}
+export interface MailerModuleParams {
+    providerClass: Type<MailerProvider<any, any>>;
+    providerOptions?: MailerProviderOptionsType;
+    options?: Partial<MailerModuleOptions>;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/lib/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AACtC,OAAO,EACN,cAAc,EACd,KAAK,yBAAyB,EAC9B,MAAM,0BAA0B,CAAC;AAElC,MAAM,WAAW,mBAAmB;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,kBAAkB;IAClC,aAAa,EAAE,IAAI,CAAC,cAAc,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;IAC9C,eAAe,CAAC,EAAE,yBAAyB,CAAC;IAC5C,OAAO,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC,CAAC;CACvC"}

package/lib/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@brilab-mailer/core",
+  "version": "0.0.1-beta.47",
+  "author": "Bohdan Radchenko <radchenkobs@gmail.com>",
+  "type": "module",
+  "main": "./index.js",
+  "module": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js",
+      "default": "./index.js"
+    }
+  },
+  "files": [
+    "**/*",
+    "!**/*.tsbuildinfo"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "directory": "dist"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^10.0.0",
+    "@nestjs/config": "^3.0.0"
+  },
+  "dependencies": {
+    "@brilab-mailer/contracts": "^0.0.1"
+  }
+}