@brilab-mailer/contracts 0.2.1 → 0.2.2

package/cjs/index.js

@@ -0,0 +1,23 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./lib/mailer-contracts.js"), exports);
+__exportStar(require("./lib/mailer-provider.js"), exports);
+__exportStar(require("./lib/mailer-send-result.js"), exports);
+__exportStar(require("./lib/mailer-send-error.js"), exports);
+__exportStar(require("./lib/mailer-templates.js"), exports);
+__exportStar(require("./lib/mailer-config-properties.js"), exports);
+__exportStar(require("./lib/mailer-messages.js"), exports);

package/cjs/lib/mailer-config-properties.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAILER_RETRY_BACKOFF_MS = exports.MAILER_RETRY_ATTEMPTS = void 0;
+// MAILER
+exports.MAILER_RETRY_ATTEMPTS = 'MAILER_RETRY_ATTEMPTS';
+exports.MAILER_RETRY_BACKOFF_MS = 'MAILER_RETRY_BACKOFF_MS';

package/cjs/lib/mailer-contracts.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAILER_TEMPLATE_ENGINE_OPTIONS = exports.MAILER_TEMPLATE_ENGINE = exports.MAILER_PROVIDER_NATIVE_CLIENT = exports.MAILER_PROVIDER_OPTIONS = exports.MAILER_PROVIDER = exports.MAILER_OPTIONS = exports.MAILER_ASYNC = void 0;
+exports.MAILER_ASYNC = Symbol('MAILER_ASYNC');
+exports.MAILER_OPTIONS = Symbol('MAILER_OPTIONS');
+exports.MAILER_PROVIDER = Symbol('MAILER_PROVIDER');
+exports.MAILER_PROVIDER_OPTIONS = Symbol('MAILER_PROVIDER_OPTIONS');
+exports.MAILER_PROVIDER_NATIVE_CLIENT = Symbol('MAILER_PROVIDER_NATIVE_CLIENT');
+exports.MAILER_TEMPLATE_ENGINE = Symbol('MAILER_TEMPLATE_ENGINE');
+exports.MAILER_TEMPLATE_ENGINE_OPTIONS = Symbol('MAILER_TEMPLATE_ENGINE_OPTIONS');

package/cjs/lib/mailer-messages.js

@@ -0,0 +1,176 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatAddressList = exports.formatAddress = exports.resolveBodies = exports.normalizeDataBodyString = exports.MailerMessagesBuilder = void 0;
+class MailerMessagesBuilder {
+    draft = {
+        to: [],
+        cc: [],
+        bcc: [],
+        meta: {},
+        headers: {},
+        attachments: [],
+        tags: {},
+    };
+    generateDraft() {
+        return this.draft;
+    }
+    prepare() {
+        const draft = this.generateDraft();
+        if (!draft.from?.email)
+            throw new Error('[Mailer] from.email is required');
+        if (!draft.to?.length)
+            throw new Error('[Mailer] to[] is required');
+        if (!draft.subject)
+            throw new Error('[Mailer] subject is required');
+        const text = typeof draft.text === 'string' ? draft.text : draft.text?.toString();
+        const html = typeof draft.html === 'string' ? draft.html : draft.html?.toString();
+        if (!text && !html)
+            throw new Error('[Mailer] message has no content (text or html)');
+        const content = text && html
+            ? { kind: 'mixed', text, html }
+            : html
+                ? { kind: 'html', html }
+                : { kind: 'text', text: text };
+        return {
+            ...draft,
+            from: draft.from,
+            to: draft.to,
+            subject: draft.subject,
+            content,
+        };
+    }
+    setFrom(fromOrEmail, name) {
+        const fromEmail = typeof fromOrEmail === 'string' ? fromOrEmail : fromOrEmail.email;
+        const fromName = typeof fromOrEmail === 'string' ? name : fromOrEmail.name;
+        this.draft.from = { email: fromEmail, name: fromName };
+        return this;
+    }
+    setReplyTo(replyToOrEmail, name) {
+        this.draft.replyTo = typeof replyToOrEmail === 'string'
+            ? { email: replyToOrEmail, name }
+            : replyToOrEmail;
+        return this;
+    }
+    resolveAddress(input) {
+        return typeof input === 'string' ? { email: input } : input;
+    }
+    toAddressList(input) {
+        const arr = Array.isArray(input) ? input : [input];
+        return arr.map((i) => this.resolveAddress(i));
+    }
+    /** Merge new recipients into an existing list, de-duplicating by email. */
+    mergeAddresses(prev, next) {
+        const result = [...prev];
+        for (const addr of next) {
+            const idx = result.findIndex((p) => p.email === addr.email);
+            if (idx !== -1)
+                result[idx] = { ...result[idx], ...addr };
+            else
+                result.push(addr);
+        }
+        return result;
+    }
+    addTo(input) {
+        this.draft.to = this.mergeAddresses(this.draft.to || [], this.toAddressList(input));
+        return this;
+    }
+    setTo(input) {
+        this.draft.to = this.toAddressList(input);
+        return this;
+    }
+    addCc(input) {
+        this.draft.cc = this.mergeAddresses(this.draft.cc || [], this.toAddressList(input));
+        return this;
+    }
+    setCc(input) {
+        this.draft.cc = this.toAddressList(input);
+        return this;
+    }
+    addBcc(input) {
+        this.draft.bcc = this.mergeAddresses(this.draft.bcc || [], this.toAddressList(input));
+        return this;
+    }
+    setBcc(input) {
+        this.draft.bcc = this.toAddressList(input);
+        return this;
+    }
+    setSubject(subject) {
+        this.draft.subject = subject;
+        return this;
+    }
+    setHeader(name, value) {
+        this.draft.headers = { ...(this.draft.headers || {}), [name]: value };
+        return this;
+    }
+    setHeaders(headers) {
+        this.draft.headers = { ...(this.draft.headers || {}), ...headers };
+        return this;
+    }
+    addAttachment(attachment) {
+        this.draft.attachments = [...(this.draft.attachments || []), attachment];
+        return this;
+    }
+    setTag(name, value) {
+        this.draft.tags = { ...(this.draft.tags || {}), [name]: value };
+        return this;
+    }
+    setIdempotencyKey(key) {
+        this.draft.idempotencyKey = key;
+        return this;
+    }
+    setText(text) {
+        this.draft.text = text;
+        return this;
+    }
+    setHtml(html) {
+        this.draft.html = html;
+        return this;
+    }
+}
+exports.MailerMessagesBuilder = MailerMessagesBuilder;
+/** Normalizes a string/Buffer body to a plain string. */
+const normalizeDataBodyString = (body) => {
+    if (!body)
+        return '';
+    if (typeof body === 'string')
+        return body;
+    return body.toString();
+};
+exports.normalizeDataBodyString = normalizeDataBodyString;
+/** Resolves the message content into plain `text`/`html` strings. */
+const resolveBodies = (resolved) => {
+    const content = resolved.content;
+    switch (content.kind) {
+        case 'text':
+            return { text: (0, exports.normalizeDataBodyString)(content.text) };
+        case 'html':
+            return { html: (0, exports.normalizeDataBodyString)(content.html) };
+        case 'mixed':
+            return {
+                text: (0, exports.normalizeDataBodyString)(content.text),
+                html: (0, exports.normalizeDataBodyString)(content.html),
+            };
+        default:
+            return {};
+    }
+};
+exports.resolveBodies = resolveBodies;
+/**
+ * Formats an address into an RFC 5322 string, quoting the display name when it
+ * contains special characters. Used by providers that take `"Name <email>"`.
+ */
+const formatAddress = (address) => {
+    if (!address.name)
+        return address.email;
+    const needsQuote = /[",:;<>@\[\]\\]/.test(address.name);
+    const name = needsQuote ? `"${address.name.replace(/"/g, '\\"')}"` : address.name;
+    return `${name} <${address.email}>`;
+};
+exports.formatAddress = formatAddress;
+/** Formats a list of addresses into a comma-separated RFC 5322 string. */
+const formatAddressList = (addresses) => {
+    if (!addresses?.length)
+        return undefined;
+    return addresses.map(exports.formatAddress).join(', ');
+};
+exports.formatAddressList = formatAddressList;

package/cjs/lib/mailer-provider.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/cjs/lib/mailer-send-error.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toMailerSendError = exports.MailerSendError = void 0;
+/**
+ * Normalized provider error. Carries a `retryable` flag so the retry layer can
+ * skip permanent failures (4xx validation) and only retry transient ones
+ * (network, 429, 5xx).
+ */
+class MailerSendError extends Error {
+    provider;
+    code;
+    statusCode;
+    retryable;
+    cause;
+    constructor(params) {
+        super(`[${params.provider}] ${params.message}`);
+        this.name = 'MailerSendError';
+        this.provider = params.provider;
+        this.code = params.code;
+        this.statusCode = params.statusCode;
+        this.cause = params.cause;
+        this.retryable = params.retryable ?? deriveRetryable(params.statusCode);
+    }
+}
+exports.MailerSendError = MailerSendError;
+/** 429 and 5xx are transient; other classified statuses are permanent. */
+const deriveRetryable = (statusCode) => {
+    if (statusCode === undefined)
+        return true; // network/unknown → retry
+    if (statusCode === 429)
+        return true;
+    return statusCode >= 500;
+};
+/** Best-effort extraction of a status code from an arbitrary SDK error. */
+const extractStatusCode = (err) => {
+    const candidate = err?.statusCode ??
+        err?.status ??
+        err?.response?.statusCode ??
+        err?.response?.status ??
+        err?.$metadata?.httpStatusCode;
+    return typeof candidate === 'number' ? candidate : undefined;
+};
+/** Wraps any thrown SDK error into a normalized `MailerSendError`. */
+const toMailerSendError = (provider, err) => {
+    if (err instanceof MailerSendError)
+        return err;
+    const e = err;
+    const message = e?.message ?? String(err);
+    return new MailerSendError({
+        provider,
+        message,
+        code: e?.code ?? e?.name,
+        statusCode: extractStatusCode(e),
+        cause: err,
+    });
+};
+exports.toMailerSendError = toMailerSendError;

package/cjs/lib/mailer-send-result.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/cjs/lib/mailer-templates.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/cjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@brilab-mailer/contracts",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "author": "Bohdan Radchenko <radchenkobs@gmail.com>",
   "type": "module",
-  "main": "./index.js",
+  "main": "./cjs/index.js",
   "module": "./index.js",
   "types": "./index.d.ts",
   "exports": {
@@ -11,7 +11,7 @@
     ".": {
       "types": "./index.d.ts",
       "import": "./index.js",
-      "default": "./index.js"
+      "require": "./cjs/index.js"
     }
   },
   "files": [