@brilab-mailer/contracts 0.0.5-5 → 0.1.0

package/index.d.ts

@@ -1,5 +1,7 @@
 export * from './lib/mailer-contracts.js';
 export * from './lib/mailer-provider.js';
+export * from './lib/mailer-send-result.js';
+export * from './lib/mailer-send-error.js';
 export * from './lib/mailer-templates.js';
 export * from './lib/mailer-config-properties.js';
 export * from './lib/mailer-messages.js';

package/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,2BAA2B,CAAC;AAC1C,cAAc,0BAA0B,CAAC;AACzC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,mCAAmC,CAAC;AAClD,cAAc,0BAA0B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,2BAA2B,CAAC;AAC1C,cAAc,0BAA0B,CAAC;AACzC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,mCAAmC,CAAC;AAClD,cAAc,0BAA0B,CAAC"}

package/index.js

@@ -1,5 +1,7 @@
 export * from './lib/mailer-contracts.js';
 export * from './lib/mailer-provider.js';
+export * from './lib/mailer-send-result.js';
+export * from './lib/mailer-send-error.js';
 export * from './lib/mailer-templates.js';
 export * from './lib/mailer-config-properties.js';
 export * from './lib/mailer-messages.js';

package/lib/mailer-messages.d.ts

@@ -1,15 +1,35 @@
-type MailerSender = {
+/** An email address with an optional display name. */
+export type MailerAddress = {
     email: string;
     name?: string;
 };
-type MailerRecipient = {
-    email: string;
+/** Backwards-compatible aliases. */
+export type MailerSender = MailerAddress;
+export type MailerRecipient = MailerAddress;
+export type MailerAttachment = {
+    filename: string;
+    /** File content as a Buffer or base64 string. Mutually exclusive with `path`. */
+    content?: string | Buffer;
+    /** Local/remote path to a hosted file. Mutually exclusive with `content`. */
+    path?: string;
+    contentType?: string;
+    /** Content-ID for inline images referenced via `cid:`. */
+    contentId?: string;
+    disposition?: 'attachment' | 'inline';
 };
 export type MailerMessagesBuilderDraft = {
-    from?: MailerSender;
-    to?: MailerRecipient[];
+    from?: MailerAddress;
+    to?: MailerAddress[];
+    cc?: MailerAddress[];
+    bcc?: MailerAddress[];
+    replyTo?: MailerAddress;
     subject?: string;
     headers?: Record<string, string>;
+    attachments?: MailerAttachment[];
+    /** Provider-level tags/categories (e.g. Resend tags, SendGrid categories). */
+    tags?: Record<string, string>;
+    /** Stable key for safe retries on providers that support idempotency. */
+    idempotencyKey?: string;
     meta: Record<string, any>;
     text?: string | Buffer;
     html?: string | Buffer;
@@ -26,8 +46,8 @@ export type MailerMessagesContent = {
     html?: string | Buffer;
 };
 export type MailerMessagesResolved = Omit<MailerMessagesBuilderDraft, 'text' | 'html' | 'from' | 'to'> & {
-    from: MailerSender;
-    to: MailerRecipient[];
+    from: MailerAddress;
+    to: MailerAddress[];
     subject: string;
     content: MailerMessagesContent;
 };
@@ -35,25 +55,41 @@ export declare class MailerMessagesBuilder {
     private readonly draft;
     protected generateDraft(): MailerMessagesBuilderDraft;
     protected prepare(): MailerMessagesResolved;
-    setFrom(email: MailerSender["email"], name?: MailerSender['name']): this;
-    setFrom(from: MailerSender): this;
-    private resolveRecipientToItem;
-    addTo(email: MailerRecipient["email"]): this;
-    addTo(emails: MailerRecipient["email"][]): this;
-    addTo(recipient: MailerRecipient): this;
-    addTo(recipients: MailerRecipient[]): this;
-    setTo(email: MailerRecipient["email"]): this;
-    setTo(emails: MailerRecipient["email"][]): this;
-    setTo(recipient: MailerRecipient): this;
-    setTo(recipients: MailerRecipient[]): this;
+    setFrom(email: MailerAddress["email"], name?: MailerAddress['name']): this;
+    setFrom(from: MailerAddress): this;
+    setReplyTo(email: MailerAddress["email"], name?: MailerAddress['name']): this;
+    setReplyTo(replyTo: MailerAddress): this;
+    private resolveAddress;
+    private toAddressList;
+    /** Merge new recipients into an existing list, de-duplicating by email. */
+    private mergeAddresses;
+    addTo(input: MailerAddress[] | MailerAddress | string[] | string): this;
+    setTo(input: MailerAddress[] | MailerAddress | string[] | string): this;
+    addCc(input: MailerAddress[] | MailerAddress | string[] | string): this;
+    setCc(input: MailerAddress[] | MailerAddress | string[] | string): this;
+    addBcc(input: MailerAddress[] | MailerAddress | string[] | string): this;
+    setBcc(input: MailerAddress[] | MailerAddress | string[] | string): this;
     setSubject(subject: string): this;
+    setHeader(name: string, value: string): this;
+    setHeaders(headers: Record<string, string>): this;
+    addAttachment(attachment: MailerAttachment): this;
+    setTag(name: string, value: string): this;
+    setIdempotencyKey(key: string): this;
     setText(text: string | Buffer): this;
     setHtml(html: string | Buffer): this;
 }
+/** Normalizes a string/Buffer body to a plain string. */
 export declare const normalizeDataBodyString: <Body extends string | Buffer>(body?: Body) => string;
-export declare const segmentedDataContentPayload: <Response extends Base, Keys extends {
-    text: keyof Response;
-    html: keyof Response;
-}, Base extends Partial<Response> = Partial<Response>>(resolved: MailerMessagesResolved, keys: Keys | null, normalizer: null | (<Body extends string | Buffer>(body?: Body) => string), base?: Base) => Response;
-export {};
+/** Resolves the message content into plain `text`/`html` strings. */
+export declare const resolveBodies: (resolved: MailerMessagesResolved) => {
+    text?: string;
+    html?: string;
+};
+/**
+ * Formats an address into an RFC 5322 string, quoting the display name when it
+ * contains special characters. Used by providers that take `"Name <email>"`.
+ */
+export declare const formatAddress: (address: MailerAddress) => string;
+/** Formats a list of addresses into a comma-separated RFC 5322 string. */
+export declare const formatAddressList: (addresses?: MailerAddress[]) => string | undefined;
 //# sourceMappingURL=mailer-messages.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"mailer-messages.d.ts","sourceRoot":"","sources":["../../src/lib/mailer-messages.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"mailer-messages.d.ts","sourceRoot":"","sources":["../../src/lib/mailer-messages.ts"],"names":[],"mappings":"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"}

package/lib/mailer-messages.js

@@ -1,8 +1,12 @@
 export class MailerMessagesBuilder {
     draft = {
         to: [],
+        cc: [],
+        bcc: [],
         meta: {},
         headers: {},
+        attachments: [],
+        tags: {},
     };
     generateDraft() {
         return this.draft;
@@ -10,13 +14,15 @@ export class MailerMessagesBuilder {
     prepare() {
         const draft = this.generateDraft();
         if (!draft.from?.email)
-            throw new Error('from.email is required');
+            throw new Error('[Mailer] from.email is required');
         if (!draft.to?.length)
-            throw new Error('to[] required');
+            throw new Error('[Mailer] to[] is required');
         if (!draft.subject)
-            throw new Error('subject required');
+            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
@@ -33,50 +39,82 @@ export class MailerMessagesBuilder {
     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
-        };
+        this.draft.from = { email: fromEmail, name: fromName };
+        return this;
+    }
+    setReplyTo(replyToOrEmail, name) {
+        this.draft.replyTo = typeof replyToOrEmail === 'string'
+            ? { email: replyToOrEmail, name }
+            : replyToOrEmail;
         return this;
     }
-    resolveRecipientToItem(emailOrRecipient) {
-        if (typeof emailOrRecipient === 'string')
-            return { email: emailOrRecipient };
-        return emailOrRecipient;
+    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) {
-        const prevTo = this.draft.to || [];
-        const newTo = (() => {
-            const isArr = Array.isArray(input);
-            const recipients = isArr
-                ? input.map(this.resolveRecipientToItem)
-                : [this.resolveRecipientToItem(input)];
-            const remaining = [];
-            for (const r of recipients) {
-                const idx = prevTo.findIndex(p => p.email === r.email);
-                if (idx !== -1) {
-                    prevTo[idx] = { ...prevTo[idx], ...r };
-                }
-                else {
-                    remaining.push(r);
-                }
-            }
-            return remaining;
-        })();
-        this.draft.to = [...prevTo, ...newTo];
+        this.draft.to = this.mergeAddresses(this.draft.to || [], this.toAddressList(input));
         return this;
     }
     setTo(input) {
-        const isArr = Array.isArray(input);
-        this.draft.to = isArr
-            ? input.map(this.resolveRecipientToItem)
-            : [this.resolveRecipientToItem(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;
@@ -86,6 +124,7 @@ export class MailerMessagesBuilder {
         return this;
     }
 }
+/** Normalizes a string/Buffer body to a plain string. */
 export const normalizeDataBodyString = (body) => {
     if (!body)
         return '';
@@ -93,25 +132,37 @@ export const normalizeDataBodyString = (body) => {
         return body;
     return body.toString();
 };
-export const segmentedDataContentPayload = (resolved, keys, normalizer, base = {}) => {
-    const { text: keyText, html: keyHtml } = keys || { text: 'text', html: 'html' };
-    const normalize = normalizer || normalizeDataBodyString;
-    switch (resolved.content.kind) {
+/** Resolves the message content into plain `text`/`html` strings. */
+export const resolveBodies = (resolved) => {
+    const content = resolved.content;
+    switch (content.kind) {
         case 'text':
-            return { ...base, [keyText]: normalize(resolved.content.text) };
+            return { text: normalizeDataBodyString(content.text) };
         case 'html':
-            return { ...base, [keyHtml]: normalize(resolved.content.html) };
+            return { html: normalizeDataBodyString(content.html) };
         case 'mixed':
             return {
-                ...base,
-                [keyText]: normalize(resolved.content.text),
-                [keyHtml]: normalize(resolved.content.html),
+                text: normalizeDataBodyString(content.text),
+                html: normalizeDataBodyString(content.html),
             };
         default:
-            return {
-                ...base,
-                [keyText]: normalize(''),
-                [keyHtml]: normalize(''),
-            };
+            return {};
     }
 };
+/**
+ * Formats an address into an RFC 5322 string, quoting the display name when it
+ * contains special characters. Used by providers that take `"Name <email>"`.
+ */
+export 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}>`;
+};
+/** Formats a list of addresses into a comma-separated RFC 5322 string. */
+export const formatAddressList = (addresses) => {
+    if (!addresses?.length)
+        return undefined;
+    return addresses.map(formatAddress).join(', ');
+};

package/lib/mailer-provider.d.ts

@@ -1,11 +1,15 @@
 import { MailerMessagesResolved } from "./mailer-messages.js";
+import { MailerSendResult, MailerSendOptions } from "./mailer-send-result.js";
 export type MailerProviderOptionsType = Record<string, any> | undefined;
 export type MailerNativeClientType<P> = P extends {
     getClient: (...args: any[]) => infer C;
 } ? C : never;
 export interface MailerProvider<Options = object, NativeClient = unknown, Payload = object> {
+    /** Returns the underlying SDK client. Always available across providers. */
     getClient(): NativeClient;
+    /** Maps the normalized message onto the provider-native payload. */
     createPayload(resolved: MailerMessagesResolved): Payload;
-    send(payload: Payload): Promise<void>;
+    /** Sends the payload and normalizes the provider response. */
+    send(payload: Payload, options?: MailerSendOptions): Promise<MailerSendResult>;
 }
 //# sourceMappingURL=mailer-provider.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"mailer-provider.d.ts","sourceRoot":"","sources":["../../src/lib/mailer-provider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAE9D,MAAM,MAAM,yBAAyB,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CAAC;AAExE,MAAM,MAAM,sBAAsB,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,SAAS,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,MAAM,CAAC,CAAA;CAAE,GAAG,CAAC,GAAG,KAAK,CAAC;AAEzG,MAAM,WAAW,cAAc,CAC9B,OAAO,GAAG,MAAM,EAChB,YAAY,GAAG,OAAO,EACtB,OAAO,GAAG,MAAM;IAEhB,SAAS,IAAI,YAAY,CAAC;IAC1B,aAAa,CAAC,QAAQ,EAAE,sBAAsB,GAAG,OAAO,CAAC;IACzD,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACtC"}
+{"version":3,"file":"mailer-provider.d.ts","sourceRoot":"","sources":["../../src/lib/mailer-provider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAE9E,MAAM,MAAM,yBAAyB,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CAAC;AAExE,MAAM,MAAM,sBAAsB,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,SAAS,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,MAAM,CAAC,CAAA;CAAE,GAAG,CAAC,GAAG,KAAK,CAAC;AAEzG,MAAM,WAAW,cAAc,CAC9B,OAAO,GAAG,MAAM,EAChB,YAAY,GAAG,OAAO,EACtB,OAAO,GAAG,MAAM;IAEhB,4EAA4E;IAC5E,SAAS,IAAI,YAAY,CAAC;IAC1B,oEAAoE;IACpE,aAAa,CAAC,QAAQ,EAAE,sBAAsB,GAAG,OAAO,CAAC;IACzD,8DAA8D;IAC9D,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;CAC/E"}

package/lib/mailer-send-error.d.ts

@@ -0,0 +1,25 @@
+export interface MailerSendErrorParams {
+    provider: string;
+    message: string;
+    code?: string | number;
+    statusCode?: number;
+    /** Explicit override; when omitted it is derived from `statusCode`. */
+    retryable?: boolean;
+    cause?: unknown;
+}
+/**
+ * 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).
+ */
+export declare class MailerSendError extends Error {
+    readonly provider: string;
+    readonly code?: string | number;
+    readonly statusCode?: number;
+    readonly retryable: boolean;
+    readonly cause?: unknown;
+    constructor(params: MailerSendErrorParams);
+}
+/** Wraps any thrown SDK error into a normalized `MailerSendError`. */
+export declare const toMailerSendError: (provider: string, err: unknown) => MailerSendError;
+//# sourceMappingURL=mailer-send-error.d.ts.map

package/lib/mailer-send-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mailer-send-error.d.ts","sourceRoot":"","sources":["../../src/lib/mailer-send-error.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,qBAAqB;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uEAAuE;IACvE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;;GAIG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACzC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAChC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,SAAkB,KAAK,CAAC,EAAE,OAAO,CAAC;gBAEtB,MAAM,EAAE,qBAAqB;CASzC;AAoBD,sEAAsE;AACtE,eAAO,MAAM,iBAAiB,GAAI,UAAU,MAAM,EAAE,KAAK,OAAO,KAAG,eAWlE,CAAC"}

package/lib/mailer-send-error.js

@@ -0,0 +1,52 @@
+/**
+ * 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).
+ */
+export 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);
+    }
+}
+/** 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`. */
+export 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,
+    });
+};

package/lib/mailer-send-result.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Provider-agnostic result of a single send.
+ *
+ * Every provider maps its native response onto this shape so callers can
+ * rely on one contract regardless of the underlying transport.
+ */
+export interface MailerSendResult {
+    /** Provider message identifier, when the provider exposes one. */
+    messageId?: string;
+    /** Recipients the provider/transport accepted (e.g. SMTP `accepted`). */
+    accepted?: string[];
+    /** Recipients the provider/transport rejected (e.g. SMTP `rejected`). */
+    rejected?: string[];
+    /** Raw, untyped provider response for advanced/debug access. */
+    raw?: unknown;
+}
+/**
+ * Per-send request options, separate from the message payload.
+ * Threaded from `MailerService.send` into `MailerProvider.send`.
+ */
+export interface MailerSendOptions {
+    /**
+     * Stable key for safe retries — providers that support it (e.g. Resend)
+     * use it to deduplicate identical requests. A key is generated per logical
+     * send so the retry loop never produces duplicate emails.
+     */
+    idempotencyKey?: string;
+}
+//# sourceMappingURL=mailer-send-result.d.ts.map

package/lib/mailer-send-result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mailer-send-result.d.ts","sourceRoot":"","sources":["../../src/lib/mailer-send-result.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAChC,kEAAkE;IAClE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yEAAyE;IACzE,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,yEAAyE;IACzE,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,gEAAgE;IAChE,GAAG,CAAC,EAAE,OAAO,CAAC;CACd;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IACjC;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACxB"}

package/lib/mailer-send-result.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brilab-mailer/contracts",
-  "version": "0.0.5-5",
+  "version": "0.1.0",
   "author": "Bohdan Radchenko <radchenkobs@gmail.com>",
   "type": "module",
   "main": "./index.js",