@visulima/email 1.0.0-alpha.9 → 1.0.1

package/dist/test/index.d.ts

@@ -0,0 +1,155 @@
+import { a as MockEmailEntry } from "../packem_shared/types.d-DCkecJse.js";
+import { E as EmailOptions } from "../packem_shared/types.d-ejzh-xBP.js";
+import { M as Mail } from "../packem_shared/mail.d-B9SSqyy0.js";
+import 'node:buffer';
+import 'ical-generator';
+import 'node:crypto';
+import "../packem_shared/types.d-BId55FW2.js";
+import "../packem_shared/types.d-nyR1ty1Q.js";
+import "../packem_shared/types.d-Mpu0HZoG.js";
+import "../packem_shared/provider.d-J-y6iogK.js";
+/**
+* A test harness around the in-memory mock provider: a ready-to-use {@link Mail} instance plus
+* helpers to inspect, wait on, and reset the captured outbox.
+*/
+interface TestEmail {
+  /**
+  * The {@link Mail} instance wired to the mock provider. Use it exactly like a real one.
+  */
+  mail: Mail;
+  /**
+  * Removes all captured messages.
+  */
+  reset: () => void;
+  /**
+  * Returns the captured messages, oldest first.
+  */
+  sent: () => ReadonlyArray<MockEmailEntry>;
+  /**
+  * Resolves with the first captured message matching `predicate`, polling until `timeout`.
+  * @param predicate The match condition.
+  * @param options Optional `timeout` (ms, default 1000) and `interval` (ms, default 10).
+  * @param options.interval Poll interval in milliseconds.
+  * @param options.timeout Maximum time to wait in milliseconds.
+  */
+  waitFor: (predicate: (message: MockEmailEntry) => boolean, options?: {
+    interval?: number;
+    timeout?: number;
+  }) => Promise<MockEmailEntry>;
+}
+/**
+* Creates a {@link TestEmail} harness backed by the in-memory mock provider.
+*
+* Nothing is sent over the network; every message is captured for assertion via the
+* {@link https://vitest.dev/ Vitest} matchers exported from `@visulima/email/test`.
+* @returns The test harness. See {@link TestEmail}.
+* @example
+* ```ts
+* const email = createTestEmail();
+* await email.mail.send({ from: { email: "a@x.com" }, to: { email: "b@x.com" }, subject: "Hi", text: "yo" });
+* expect(email).toHaveSentTo("b@x.com");
+* ```
+*/
+declare const createTestEmail: () => TestEmail;
+/**
+* The minimal result shape a Vitest/Jest matcher must return.
+*/
+interface MatcherResult {
+  message: () => string;
+  pass: boolean;
+}
+/**
+* A value the email matchers can assert against: a {@link TestEmail} harness or a raw list of captured
+* entries.
+*/
+type MatcherTarget = ReadonlyArray<MockEmailEntry> | TestEmail;
+/**
+* Asserts that at least one captured message was addressed to `address` (in To, Cc, or Bcc).
+* @param target The {@link TestEmail} harness or captured entries.
+* @param address The recipient address to look for (case-insensitive).
+* @returns The matcher result.
+*/
+declare const toHaveSentTo: (target: MatcherTarget, address: string) => MatcherResult;
+/**
+* Asserts that at least one captured message has a subject equal to (or matching) `expected`.
+* @param target The {@link TestEmail} harness or captured entries.
+* @param expected An exact subject string or a `RegExp`.
+* @returns The matcher result.
+*/
+declare const toHaveSentWithSubject: (target: MatcherTarget, expected: RegExp | string) => MatcherResult;
+/**
+* Asserts that at least one captured message carried an attachment (optionally with a given filename).
+* @param target The {@link TestEmail} harness or captured entries.
+* @param filename When provided, requires an attachment with this exact filename.
+* @returns The matcher result.
+*/
+declare const toHaveSentWithAttachment: (target: MatcherTarget, filename?: string) => MatcherResult;
+/**
+* Asserts that at least one captured message matches a predicate or a partial {@link EmailOptions}.
+* @param target The {@link TestEmail} harness or captured entries.
+* @param matcher A predicate over the sent options, or a partial options object to shallow-match.
+* @returns The matcher result.
+*/
+declare const toHaveSentMatching: (target: MatcherTarget, matcher: Partial<EmailOptions> | ((options: EmailOptions) => boolean)) => MatcherResult;
+/**
+* The matcher map, suitable for passing to Vitest/Jest `expect.extend(...)`.
+*/
+declare const emailMatchers: {
+  toHaveSentMatching: typeof toHaveSentMatching;
+  toHaveSentTo: typeof toHaveSentTo;
+  toHaveSentWithAttachment: typeof toHaveSentWithAttachment;
+  toHaveSentWithSubject: typeof toHaveSentWithSubject;
+};
+/**
+* A Vitest/Jest-compatible `expect` exposing `.extend(...)`.
+*/
+interface ExpectLike {
+  extend: (matchers: Record<string, unknown>) => void;
+}
+/**
+* Registers the email matchers with a Vitest/Jest-compatible `expect`.
+*
+* Kept dependency-free by accepting `expect` as an argument rather than importing `vitest` into the
+* shipped bundle. Add the matching type augmentation to a `vitest.d.ts` in your project for typed
+* `expect(...).toHaveSentTo(...)` calls.
+* @param expectInstance The `expect` object exposing `.extend(...)`.
+* @example
+* ```ts
+* import { expect } from "vitest";
+* import { registerEmailMatchers } from "@visulima/email/test";
+*
+* registerEmailMatchers(expect);
+* ```
+*/
+declare const registerEmailMatchers: (expectInstance: ExpectLike) => void;
+/**
+* A stable, snapshot-friendly view of a sent message — volatile fields (message id, timestamp) are
+* omitted so the snapshot doesn't churn between runs.
+*/
+interface EmailSnapshot {
+  attachments?: {
+    contentType?: string;
+    filename: string;
+  }[];
+  bcc?: string[];
+  cc?: string[];
+  from: string;
+  headers?: Record<string, string>;
+  html?: string;
+  replyTo?: string;
+  subject: string;
+  text?: string;
+  to: string[];
+}
+/**
+* Normalizes a captured message (a `createTestEmail` outbox entry or raw {@link EmailOptions}) into a
+* deterministic {@link EmailSnapshot} for use with Vitest/Jest `toMatchSnapshot()`.
+* @param source A mock-provider outbox entry or an `EmailOptions` object.
+* @returns The snapshot view.
+* @example
+* ```ts
+* expect(toEmailSnapshot(email.sent()[0])).toMatchSnapshot();
+* ```
+*/
+declare const toEmailSnapshot: (source: EmailOptions | MockEmailEntry) => EmailSnapshot;
+export { type EmailSnapshot, type MatcherResult, type MatcherTarget, type TestEmail, createTestEmail, emailMatchers, registerEmailMatchers, toEmailSnapshot, toHaveSentMatching, toHaveSentTo, toHaveSentWithAttachment, toHaveSentWithSubject };

package/dist/test/index.js

@@ -0,0 +1 @@
+import{emailMatchers as a,registerEmailMatchers as o,toHaveSentMatching as r,toHaveSentTo as i,toHaveSentWithAttachment as m,toHaveSentWithSubject as h}from"../packem_shared/emailMatchers-DZDkrZ_3.js";import{toEmailSnapshot as c}from"../packem_shared/toEmailSnapshot-DeRqM5SJ.js";import{createTestEmail as s}from"../packem_shared/createTestEmail-D3XPGiHY.js";export{s as createTestEmail,a as emailMatchers,o as registerEmailMatchers,c as toEmailSnapshot,r as toHaveSentMatching,i as toHaveSentTo,m as toHaveSentWithAttachment,h as toHaveSentWithSubject};

package/dist/utils/cache.d.ts

@@ -1,54 +1,55 @@
 /**
- * Generic cache interface for caching any type of data.
- * Implementations can use in-memory cache, LRU cache, Redis, etc.
- */
-export interface Cache<T = unknown> {
-    /**
-     * Clears all cached entries.
-     */
-    clear: () => Promise<void>;
-    /**
-     * Deletes a cached entry.
-     * @param key The cache key.
-     */
-    delete: (key: string) => Promise<void>;
-    /**
-     * Gets a cached value.
-     * @param key The cache key.
-     * @returns The cached value or undefined if not found or expired.
-     */
-    get: (key: string) => Promise<T | undefined>;
-    /**
-     * Sets a cached value.
-     * @param key The cache key.
-     * @param value The value to cache.
-     * @param ttl Time-to-live in milliseconds.
-     */
-    set: (key: string, value: T, ttl: number) => Promise<void>;
+* Generic cache interface for caching any type of data.
+* Implementations can use in-memory cache, LRU cache, Redis, etc.
+*/
+interface Cache<T = unknown> {
+  /**
+  * Clears all cached entries.
+  */
+  clear: () => Promise<void>;
+  /**
+  * Deletes a cached entry.
+  * @param key The cache key.
+  */
+  delete: (key: string) => Promise<void>;
+  /**
+  * Gets a cached value.
+  * @param key The cache key.
+  * @returns The cached value or undefined if not found or expired.
+  */
+  get: (key: string) => Promise<T | undefined>;
+  /**
+  * Sets a cached value.
+  * @param key The cache key.
+  * @param value The value to cache.
+  * @param ttl Time-to-live in milliseconds.
+  */
+  set: (key: string, value: T, ttl: number) => Promise<void>;
 }
 /**
- * Options for creating an in-memory cache.
- */
-export interface InMemoryCacheOptions {
-    /**
-     * Maximum number of entries in the cache.
-     * @default 500
-     */
-    max?: number;
-    /**
-     * Default TTL in milliseconds for entries.
-     * @default 3600000 (1 hour)
-     */
-    ttl?: number;
+* Options for creating an in-memory cache.
+*/
+interface InMemoryCacheOptions {
+  /**
+  * Maximum number of entries in the cache.
+  * @default 500
+  */
+  max?: number;
+  /**
+  * Default TTL in milliseconds for entries.
+  * @default 3600000 (1 hour)
+  */
+  ttl?: number;
 }
 /**
- * Default in-memory cache implementation using LRU cache.
- */
-export declare class InMemoryCache<T extends object = Record<string, unknown>> implements Cache<T> {
-    private readonly cache;
-    constructor(options?: InMemoryCacheOptions);
-    clear: () => Promise<void>;
-    delete: (key: string) => Promise<void>;
-    get: (key: string) => Promise<T | undefined>;
-    set: (key: string, value: T, ttl: number) => Promise<void>;
+* Default in-memory cache implementation using LRU cache.
+*/
+declare class InMemoryCache<T extends object = Record<string, unknown>> implements Cache<T> {
+  private readonly cache;
+  constructor(options?: InMemoryCacheOptions);
+  clear: () => Promise<void>;
+  delete: (key: string) => Promise<void>;
+  get: (key: string) => Promise<T | undefined>;
+  set: (key: string, value: T, ttl: number) => Promise<void>;
 }
+export { Cache, InMemoryCache, InMemoryCacheOptions };

package/dist/utils/cache.js

@@ -1 +1 @@
-var h=Object.defineProperty;var r=(c,e)=>h(c,"name",{value:e,configurable:!0});import{LRUCache as n}from"lru-cache";var l=Object.defineProperty,t=r((c,e)=>l(c,"name",{value:e,configurable:!0}),"t");class m{static{r(this,"InMemoryCache")}static{t(this,"InMemoryCache")}cache;constructor(e={}){const{max:a=500,ttl:s=36e5}=e;this.cache=new n({max:a,ttl:s})}clear=t(async()=>{this.cache.clear()},"clear");delete=t(async e=>{this.cache.delete(e)},"delete");get=t(async e=>this.cache.get(e),"get");set=t(async(e,a,s)=>{this.cache.set(e,a,{ttl:s})},"set")}export{m as InMemoryCache};
+import{LRUCache as a}from"lru-cache";class l{cache;constructor(c={}){const{max:e=500,ttl:t=36e5}=c;this.cache=new a({max:e,ttl:t})}clear=async()=>{this.cache.clear()};delete=async c=>{this.cache.delete(c)};get=async c=>this.cache.get(c);set=async(c,e,t)=>{this.cache.set(c,e,{ttl:t})}}export{l as InMemoryCache};

package/dist/utils/format-email-address.d.ts

@@ -1,9 +1,10 @@
-import type { EmailAddress } from "../types.d.ts";
+import { c as EmailAddress } from "../packem_shared/types.d-ejzh-xBP.js";
+import 'node:buffer';
 /**
- * Formats an email address as "Name <email@example.com>" or just "email@example.com" if no name is provided.
- * @param address The email address object to format.
- * @returns The formatted email address string in RFC 5322 format.
- * @throws {EmailError} When the email address is invalid.
- */
+* Formats an email address as "Name <email@example.com>" or just "email@example.com" if no name is provided.
+* @param address The email address object to format.
+* @returns The formatted email address string in RFC 5322 format.
+* @throws {EmailError} When the email address is invalid.
+*/
 declare const formatEmailAddress: (address: EmailAddress) => string;
-export default formatEmailAddress;
+export { formatEmailAddress as default };

package/dist/utils/format-email-address.js

@@ -1 +1 @@
-var m=Object.defineProperty;var r=(e,a)=>m(e,"name",{value:a,configurable:!0});import o from"../packem_shared/EmailError-zm2ffVav.js";import{s as l}from"../packem_shared/sanitize-header-wWav-Scu.js";import t from"./validation/validate-email.js";var i=Object.defineProperty,n=r((e,a)=>i(e,"name",{value:a,configurable:!0}),"m");const p=n(e=>{if(!t(e.email))throw new o("email",`Invalid email address: ${e.email}`);return e.name?`${l(e.name)} <${e.email}>`:e.email},"formatEmailAddress");export{p as default};
+import{s as m}from"../packem_shared/format-address-DTl-9O70.js";import r from"../packem_shared/EmailError-B-sEf3bp.js";import i from"./validation/validate-email.js";const n=a=>{if(!i(a.email))throw new r("email",`Invalid email address: ${a.email}`);if(a.name){const e=m(a.name);if(e)return`"${e}" <${a.email}>`}return a.email};export{n as default};

package/dist/utils/normalize-email-aliases.d.ts

@@ -1,22 +1,22 @@
 /**
- * Normalizes email aliases for supported email providers.
- * For example: example@gmail.com and example+another@gmail.com point to the same email address.
- * This function normalizes aliases to their canonical form.
- *
- * Supported providers:
- * - Gmail: Removes dots and plus aliases (example+test@gmail.com → example@gmail.com)
- * - Yahoo, Outlook, Hotmail, Live, MSN, iCloud, ProtonMail, Zoho, FastMail, Mail.com, GMX: Removes plus aliases only
- * @param email The email address to normalize.
- * @returns The normalized email address, or the original email if not supported or invalid.
- * @example
- * ```ts
- * import { normalizeEmailAliases } from "@visulima/email/utils/normalize-email-aliases";
- *
- * normalizeEmailAliases("example+test@gmail.com"); // "example@gmail.com"
- * normalizeEmailAliases("ex.ample@gmail.com"); // "example@gmail.com"
- * normalizeEmailAliases("user+tag@yahoo.com"); // "user@yahoo.com"
- * normalizeEmailAliases("user@example.com"); // "user@example.com" (unchanged)
- * ```
- */
+* Normalizes email aliases for supported email providers.
+* For example: example@gmail.com and example+another@gmail.com point to the same email address.
+* This function normalizes aliases to their canonical form.
+*
+* Supported providers:
+* - Gmail: Removes dots and plus aliases (example+test@gmail.com → example@gmail.com)
+* - Yahoo, Outlook, Hotmail, Live, MSN, iCloud, ProtonMail, Zoho, FastMail, Mail.com, GMX: Removes plus aliases only
+* @param email The email address to normalize.
+* @returns The normalized email address, or the original email if not supported or invalid.
+* @example
+* ```ts
+* import { normalizeEmailAliases } from "@visulima/email/utils/normalize-email-aliases";
+*
+* normalizeEmailAliases("example+test@gmail.com"); // "example@gmail.com"
+* normalizeEmailAliases("ex.ample@gmail.com"); // "example@gmail.com"
+* normalizeEmailAliases("user+tag@yahoo.com"); // "user@yahoo.com"
+* normalizeEmailAliases("user@example.com"); // "user@example.com" (unchanged)
+* ```
+*/
 declare const normalizeEmailAliases: (email: string) => string;
-export default normalizeEmailAliases;
+export { normalizeEmailAliases as default };

package/dist/utils/normalize-email-aliases.js

@@ -1 +1 @@
-var a=Object.defineProperty;var l=(o,e)=>a(o,"name",{value:e,configurable:!0});var g=Object.defineProperty,u=l((o,e)=>g(o,"name",{value:e,configurable:!0}),"m");const c=new Map([["fastmail.com",{domain:"fastmail.com",ignoreDots:!1,ignorePlus:!0}],["gmail.com",{domain:"gmail.com",ignoreDots:!0,ignorePlus:!0}],["gmx.com",{domain:"gmx.com",ignoreDots:!1,ignorePlus:!0}],["gmx.de",{domain:"gmx.de",ignoreDots:!1,ignorePlus:!0}],["gmx.net",{domain:"gmx.net",ignoreDots:!1,ignorePlus:!0}],["hotmail.com",{domain:"hotmail.com",ignoreDots:!1,ignorePlus:!0}],["icloud.com",{domain:"icloud.com",ignoreDots:!1,ignorePlus:!0}],["live.com",{domain:"live.com",ignoreDots:!1,ignorePlus:!0}],["mail.com",{domain:"mail.com",ignoreDots:!1,ignorePlus:!0}],["msn.com",{domain:"msn.com",ignoreDots:!1,ignorePlus:!0}],["outlook.com",{domain:"outlook.com",ignoreDots:!1,ignorePlus:!0}],["protonmail.com",{domain:"protonmail.com",ignoreDots:!1,ignorePlus:!0}],["yahoo.com",{domain:"yahoo.com",ignoreDots:!1,ignorePlus:!0}],["zoho.com",{domain:"zoho.com",ignoreDots:!1,ignorePlus:!0}]]),d=u(o=>{if(!o||typeof o!="string")return o;const e=o.trim().toLowerCase(),n=e.indexOf("@");if(n===-1||n===0||n===e.length-1)return o;const m=e.slice(0,n),r=e.slice(n+1);if(!m||!r)return o;const t=c.get(r);if(!t)return e;let i=m;if(t.ignorePlus){const s=i.indexOf("+");s!==-1&&(i=i.slice(0,s))}return t.ignoreDots&&(i=i.replaceAll(".","")),`${i}@${r}`},"normalizeEmailAliases");export{d as default};
+const l=new Map([["fastmail.com",{domain:"fastmail.com",ignoreDots:!1,ignorePlus:!0}],["gmail.com",{domain:"gmail.com",ignoreDots:!0,ignorePlus:!0}],["gmx.com",{domain:"gmx.com",ignoreDots:!1,ignorePlus:!0}],["gmx.de",{domain:"gmx.de",ignoreDots:!1,ignorePlus:!0}],["gmx.net",{domain:"gmx.net",ignoreDots:!1,ignorePlus:!0}],["hotmail.com",{domain:"hotmail.com",ignoreDots:!1,ignorePlus:!0}],["icloud.com",{domain:"icloud.com",ignoreDots:!1,ignorePlus:!0}],["live.com",{domain:"live.com",ignoreDots:!1,ignorePlus:!0}],["mail.com",{domain:"mail.com",ignoreDots:!1,ignorePlus:!0}],["msn.com",{domain:"msn.com",ignoreDots:!1,ignorePlus:!0}],["outlook.com",{domain:"outlook.com",ignoreDots:!1,ignorePlus:!0}],["protonmail.com",{domain:"protonmail.com",ignoreDots:!1,ignorePlus:!0}],["yahoo.com",{domain:"yahoo.com",ignoreDots:!1,ignorePlus:!0}],["zoho.com",{domain:"zoho.com",ignoreDots:!1,ignorePlus:!0}]]),a=o=>{if(!o||typeof o!="string")return o;const i=o.trim().toLowerCase(),n=i.indexOf("@");if(n===-1||n===0||n===i.length-1)return o;const s=i.slice(0,n),r=i.slice(n+1);if(!s||!r)return o;const t=l.get(r);if(!t)return i;let e=s;if(t.ignorePlus){const m=e.indexOf("+");m!==-1&&(e=e.slice(0,m))}return t.ignoreDots&&(e=e.replaceAll(".","")),`${e}@${r}`};export{a as default};

package/dist/utils/parse-address.d.ts

@@ -1,19 +1,20 @@
-import type { EmailAddress } from "../types.d.ts";
+import { c as EmailAddress } from "../packem_shared/types.d-ejzh-xBP.js";
+import 'node:buffer';
 /**
- * Parses a string representation of an email address into an EmailAddress object.
- * Supports formats: "email@example.com", "Name <email@example.com>", "<email@example.com>".
- * @example Parsing an address with a name
- * ```ts
- * const address = parseAddress("John Doe <john@example.com>");
- * // { name: "John Doe", email: "john@example.com" }
- * ```
- * @example Parsing an address without a name
- * ```ts
- * const address = parseAddress("jane@example.com");
- * // { email: "jane@example.com" }
- * ```
- * @param address The string representation of the address to parse.
- * @returns An EmailAddress object if parsing is successful, or undefined if invalid.
- */
+* Parses a string representation of an email address into an EmailAddress object.
+* Supports formats: "email@example.com", "Name &lt;email@example.com>", "&lt;email@example.com>".
+* @example Parsing an address with a name
+* ```ts
+* const address = parseAddress("John Doe <john@example.com>");
+* // { name: "John Doe", email: "john@example.com" }
+* ```
+* @example Parsing an address without a name
+* ```ts
+* const address = parseAddress("jane@example.com");
+* // { email: "jane@example.com" }
+* ```
+* @param address The string representation of the address to parse.
+* @returns An EmailAddress object if parsing is successful, or undefined if invalid.
+*/
 declare const parseAddress: (address: string) => EmailAddress | undefined;
-export default parseAddress;
+export { parseAddress as default };

package/dist/utils/parse-address.js

@@ -1 +1 @@
-var m=Object.defineProperty;var o=(t,e)=>m(t,"name",{value:e,configurable:!0});import d from"./validation/validate-email.js";var h=Object.defineProperty,c=o((t,e)=>h(t,"name",{value:e,configurable:!0}),"l");const g=c(t=>{const e=t.replace(/^"(.+)"$/,"$1");return!(!e||e.length===0||e.includes("..")||e.startsWith(".")||e.endsWith("."))},"isValidLocalPart"),a=c(t=>{const e=t.indexOf("@[");if(e>0&&t.endsWith("]")){const n=t.length-1,l=t.slice(e+2,n);if(l.includes("@["))return!1;const i=t.slice(0,e),s=l;return!s||s.trim().length===0||s.includes("]")?!1:i?g(i):!1}if(t.includes("@[")&&!t.includes("]"))return!1;const r=t.match(/^"((?:[^"\\]|\\.)+)"@(.+)$/);if(r&&r[2]){const n=r[2];return n.startsWith("[")?!1:d(`test@${n}`)}return d(t)},"isValidEmailFormat"),$=c(t=>{if(!t||typeof t!="string")return;const e=t.trim();if(!e)return;const r=e.lastIndexOf("<"),n=e.lastIndexOf(">");if(r!==-1&&n>r){const i=e.slice(0,r).trim(),s=e.slice(r+1,n).trim();if(s&&a(s)){if(i){const f=i.replace(/^"(.+)"$/,"$1");return{email:s,name:f}}return{email:s}}}const l=e.match(/^<([^>]+)>$/);if(l&&l[1]){const i=l[1].trim();return a(i)?{email:i}:void 0}if(!(e.includes("]")&&!e.includes("@["))&&!(e.includes('"')&&!e.startsWith('"')&&e.indexOf('"')<e.indexOf("@"))){if(e.startsWith('"')){let i=1,s=!1;for(;i<e.length;)if(e[i]==="\\"&&i+1<e.length)i+=2;else if(e[i]==='"'){if(i+1<e.length&&e[i+1]==="@"){s=!0;break}i+=1}else i+=1;if(!s&&e.includes("@")){const f=e.indexOf("@"),u=e.slice(1).indexOf('"');if(u===-1||f<u+1)return}}if(a(e))return{email:e}}},"parseAddress");export{$ as default};
+import u from"./validation/validate-email.js";const d=i=>{const e=i.replace(/^"(.+)"$/,"$1");return!(!e||e.length===0||e.includes("..")||e.startsWith(".")||e.endsWith("."))},c=i=>{const e=i.indexOf("@[");if(e>0&&i.endsWith("]")){const n=i.length-1,l=i.slice(e+2,n);if(l.includes("@["))return!1;const t=i.slice(0,e),s=l;return!s||s.trim().length===0||s.includes("]")?!1:t?d(t):!1}if(i.includes("@[")&&!i.includes("]"))return!1;const r=i.match(/^"((?:[^"\\]|\\.)+)"@(.+)$/);if(r?.[2]){const n=r[2];return n.startsWith("[")?!1:u(`test@${n}`)}return u(i)},h=i=>{if(!i||typeof i!="string")return;const e=i.trim();if(!e)return;const r=e.lastIndexOf("<"),n=e.lastIndexOf(">");if(r!==-1&&n>r){const t=e.slice(0,r).trim(),s=e.slice(r+1,n).trim();if(s&&c(s)){if(t){const f=t.replace(/^"(.+)"$/,"$1");return{email:s,name:f}}return{email:s}}}const l=e.match(/^<([^>]+)>$/);if(l?.[1]){const t=l[1].trim();return c(t)?{email:t}:void 0}if(!(e.includes("]")&&!e.includes("@["))&&!(e.includes('"')&&!e.startsWith('"')&&e.indexOf('"')<e.indexOf("@"))){if(e.startsWith('"')){let t=1,s=!1;for(;t<e.length;)if(e[t]==="\\"&&t+1<e.length)t+=2;else if(e[t]==='"'){if(t+1<e.length&&e[t+1]==="@"){s=!0;break}t+=1}else t+=1;if(!s&&e.includes("@")){const f=e.indexOf("@"),a=e.slice(1).indexOf('"');if(a===-1||f<a+1)return}}if(c(e))return{email:e}}};export{h as default};

package/dist/utils/parse-eml.d.ts

@@ -0,0 +1,22 @@
+import { E as EmailOptions } from "../packem_shared/types.d-ejzh-xBP.js";
+import 'node:buffer';
+/**
+* Parses a raw EML / RFC 5322 MIME message back into {@link EmailOptions}.
+*
+* This closes the round-trip story for {@link "../mail".Mail.draft}: serialise a
+* message to EML, persist/transmit it, then `parseEml()` it back into options you
+* can hand to `mail.send()`. It understands the multipart layout produced by this
+* library's own `buildMimeMessage` (text/plain + text/html parts, quoted-printable
+* and base64 transfer encodings, RFC 2047 encoded headers) and common
+* single-part messages.
+*
+* Scope: it extracts `from`, `to`, `cc`, `bcc`, `replyTo`, `subject`, `text`,
+* `html`, `priority`, and remaining custom `headers`. Attachment bodies are not
+* decoded into {@link "../types".Attachment} objects (use a full MIME parser such
+* as `mailparser` for that); attachment parts are skipped.
+* @param eml The raw EML/MIME message string.
+* @returns The parsed email options.
+* @throws {Error} When the message has no `From` or `To`/`Cc`/`Bcc` recipient and therefore cannot satisfy the required {@link EmailOptions} shape.
+*/
+declare const parseEml: (eml: string) => EmailOptions;
+export { parseEml as default };

package/dist/utils/parse-eml.js

@@ -0,0 +1,6 @@
+import y from"./parse-address.js";import{p as v}from"../packem_shared/quoted-printable-nSGDA1tA.js";const T=globalThis.Buffer!==void 0,k=r=>{if(T)return Uint8Array.from(Buffer.from(r,"base64"));const t=atob(r),n=new Uint8Array(t.length);for(let e=0;e<t.length;e+=1)n[e]=t.charCodeAt(e);return n},E=r=>{const t=r.replaceAll("_"," "),n=[];for(let e=0;e<t.length;e+=1){const s=t[e];s==="="&&e+2<t.length?(n.push(Number.parseInt(t.slice(e+1,e+3),16)),e+=2):n.push(s.charCodeAt(0))}return Uint8Array.from(n)},U=/^utf-?8$/i,j=(r,t)=>{if(T&&U.test(t))return Buffer.from(r).toString("utf8");try{return new TextDecoder(t).decode(r)}catch{return new TextDecoder().decode(r)}},D=/=\?([^?]+)\?([bq])\?([^?]*)\?=/gi,M=r=>r.includes("=?")?r.replaceAll(/(\?=)\s+(=\?)/g,"$1$2").replaceAll(D,(t,n,e,s)=>{const o=e.toUpperCase()==="B"?k(s):E(s);return j(o,n)}):r,O=globalThis.Buffer!==void 0,S=/^[ \t]/,q=/boundary=(?:"([^"]+)"|([^";]+))/i,I=/^\r?\n/,L=/[\r\n]+$/,N=/\r?\n$/,P=/\s/g,_=/high|^1|^2/i,F=/low|^4|^5/i,B=r=>{const t=r.replaceAll(`\r
+`,`
+`),n=t.indexOf(`
+
+`),e=n===-1?t:t.slice(0,n),s=n===-1?"":t.slice(n+2),o=[],f=new Map;let i="",c="";const h=()=>{if(i){const a=M(c.trim());o.push([i,a]),f.set(i.toLowerCase(),a)}};for(const a of e.split(`
+`))if(S.test(a)&&i)c+=` ${a.trim()}`;else{h();const u=a.indexOf(":");u===-1?(i="",c=""):(i=a.slice(0,u).trim(),c=a.slice(u+1).trim())}return h(),{body:s,headers:{map:f,raw:o}}},b=r=>{if(!r)return[];const t=[];let n="",e=!1,s=!1;for(const o of r){switch(o){case'"':{e=!e;break}case"<":{s=!0;break}case">":{s=!1;break}}o===","&&!e&&!s?(t.push(n),n=""):n+=o}return n.trim()&&t.push(n),t.map(o=>y(o.trim())).filter(o=>o!==void 0)},G=r=>{if(!r)return;const t=q.exec(r);return t?.[1]??t?.[2]},w=(r,t)=>{const n=(t??"7bit").trim().toLowerCase();if(n==="quoted-printable")return v(r);if(n==="base64"){const e=r.replaceAll(P,"");return O?Buffer.from(e,"base64").toString("utf8"):new TextDecoder().decode(Uint8Array.from(atob(e),s=>s.codePointAt(0)))}return r},W=r=>{const{body:t,headers:n}=B(r),{map:e}=n,s=y(e.get("from")??"");if(!s)throw new Error("Cannot parse EML: missing or invalid `From` header");const o=b(e.get("to")??""),f=b(e.get("cc")??""),i=b(e.get("bcc")??"");if(o.length===0&&f.length===0&&i.length===0)throw new Error("Cannot parse EML: no recipient (`To`/`Cc`/`Bcc`) found");const c={from:s,subject:e.get("subject")??"",to:o.length===1?o[0]:o};f.length>0&&(c.cc=f.length===1?f[0]:f),i.length>0&&(c.bcc=i.length===1?i[0]:i);const h=e.get("reply-to")?y(e.get("reply-to")):void 0;h&&(c.replyTo=h);const a=e.get("content-type"),u=G(a);if(u&&a?.toLowerCase().includes("multipart")){const d=t.split(`--${u}`);for(const l of d){const p=l.replace(I,"");if(!(!p||p.startsWith("--"))){const{body:C,headers:m}=B(p),x=m.map.get("content-type")??"",A=m.map.get("content-transfer-encoding");(m.map.get("content-disposition")??"").toLowerCase().includes("attachment")||(x.toLowerCase().includes("text/plain")?c.text=w(C.replace(L,""),A):x.toLowerCase().includes("text/html")&&(c.html=w(C.replace(L,""),A)))}}}else{const d=e.get("content-transfer-encoding"),l=w(t.replace(N,""),d);a?.toLowerCase().includes("text/html")?c.html=l:l&&(c.text=l)}const $=new Set(["bcc","cc","content-transfer-encoding","content-type","from","mime-version","reply-to","subject","to"]),g={};for(const[d,l]of n.raw){const p=d.toLowerCase();(p==="x-priority"||p==="importance")&&(_.test(l)?c.priority="high":F.test(l)&&(c.priority="low")),$.has(p)||(g[d]=l)}return Object.keys(g).length>0&&(c.headers=g),c};export{W as default};

package/dist/utils/result.d.ts

@@ -0,0 +1,49 @@
+import { R as Result } from "../packem_shared/types.d-ejzh-xBP.js";
+import 'node:buffer';
+/**
+* A successful {@link Result} with its data narrowed to be present.
+*/
+type OkResult<T> = Result<T> & {
+  data: T;
+  success: true;
+};
+/**
+* Returns whether a {@link Result} succeeded, narrowing `data` to be present.
+* @param result The result to test.
+* @returns `true` when the result is successful.
+*/
+declare const isOk: <T>(result: Result<T>) => result is OkResult<T>;
+/**
+* Returns whether a {@link Result} failed.
+* @param result The result to test.
+* @returns `true` when the result is a failure.
+*/
+declare const isErr: <T>(result: Result<T>) => boolean;
+/**
+* Returns the data of a successful {@link Result}, or throws its error.
+* @param result The result to unwrap.
+* @returns The contained data.
+* @throws {EmailError} The result's error (wrapped when it is not already an `Error`).
+*/
+declare const unwrap: <T>(result: Result<T>) => T;
+/**
+* Returns the data of a successful {@link Result}, or a fallback when it failed.
+* @param result The result to unwrap.
+* @param fallback The value to return on failure.
+* @returns The data, or the fallback.
+*/
+declare const unwrapOr: <T>(result: Result<T>, fallback: T) => T;
+/**
+* Maps the data of a successful {@link Result}, passing failures through unchanged.
+* @param result The result to map.
+* @param function_ The mapper applied to the data on success.
+* @returns A new result with the mapped data, or the original failure.
+*/
+declare const mapOk: <T, U>(result: Result<T>, function_: (data: T) => U) => Result<U>;
+/**
+* Runs an async function and captures its outcome as a {@link Result}, never throwing.
+* @param function_ The async function to run.
+* @returns A successful result with the value, or a failed result with the thrown error.
+*/
+declare const tryAsync: <T>(function_: () => Promise<T>) => Promise<Result<T>>;
+export { OkResult, isErr, isOk, mapOk, tryAsync, unwrap, unwrapOr };

package/dist/utils/result.js

@@ -0,0 +1 @@
+import e from"../packem_shared/EmailError-B-sEf3bp.js";const c=s=>s.success,t=s=>!s.success,u=s=>{if(s.success)return s.data;throw s.error instanceof Error?s.error:new e("result","Called unwrap() on a failed result",{cause:s.error})},o=(s,r)=>s.success?s.data:r,n=(s,r)=>s.success?{data:r(s.data),success:!0}:{error:s.error,success:!1},d=async s=>{try{return{data:await s(),success:!0}}catch(r){return{error:r,success:!1}}};export{t as isErr,c as isOk,n as mapOk,d as tryAsync,u as unwrap,o as unwrapOr};

package/dist/utils/validation/check-feature-support.d.ts

@@ -0,0 +1,53 @@
+import { F as FeatureFlags, E as EmailOptions } from "../../packem_shared/types.d-ejzh-xBP.js";
+import 'node:buffer';
+/**
+* A single capability that a message uses but the target provider cannot represent.
+*/
+interface FeatureViolation {
+  /**
+  * The provider capability flag that is not supported.
+  */
+  feature: keyof FeatureFlags;
+  /**
+  * The message field that triggered the check.
+  */
+  field: string;
+  /**
+  * Human-readable explanation of the violation.
+  */
+  message: string;
+}
+/**
+* Result of a fail-fast provider capability check.
+*/
+interface FeatureSupportResult {
+  /**
+  * True when the message uses no capability the provider has explicitly disabled.
+  */
+  supported: boolean;
+  /**
+  * The list of capabilities the message uses that the provider cannot represent.
+  */
+  violations: FeatureViolation[];
+}
+/**
+* Performs a fail-fast field-support check for a message against a provider's declared capabilities.
+*
+* A capability counts as a violation only when the message actually uses it **and** the provider
+* has explicitly declared it unsupported (`features[capability] === false`). Capabilities left
+* `undefined` are treated as "unknown" and never raise a violation, so providers that publish a
+* partial (or no) {@link FeatureFlags} map are never falsely rejected.
+* @param options The normalized email options about to be sent.
+* @param features The target provider's declared capabilities. When omitted the check is a no-op.
+* @returns A {@link FeatureSupportResult} describing any unsupported capabilities in use.
+* @example
+* ```ts
+* const { supported, violations } = checkFeatureSupport(message, provider.features);
+*
+* if (!supported) {
+*     throw new Error(violations.map((v) => v.message).join(", "));
+* }
+* ```
+*/
+declare function checkFeatureSupport(options: EmailOptions, features?: FeatureFlags): FeatureSupportResult;
+export { FeatureSupportResult, FeatureViolation, checkFeatureSupport as default };

package/dist/utils/validation/check-feature-support.js

@@ -0,0 +1 @@
+import{s as o}from"../../packem_shared/headers-to-record-De1Eg951.js";const r=e=>Array.isArray(e)&&e.length>0,d=(e,s)=>s.find(t=>e[t]!==void 0),i=[{detect:e=>r(e.attachments)?"attachments":void 0,feature:"attachments",label:"attachments"},{detect:e=>typeof e.html=="string"&&e.html.length>0?"html":void 0,feature:"html",label:"HTML content"},{detect:e=>e.replyTo?"replyTo":void 0,feature:"replyTo",label:"a reply-to address"},{detect:e=>e.headers!==void 0&&Object.keys(o(e.headers)).length>0?"headers":void 0,feature:"customHeaders",label:"custom headers"},{detect:e=>r(e.tags)?"tags":void 0,feature:"tagging",label:"tags"},{detect:e=>d(e,["scheduledAt","sendAt"]),feature:"scheduling",label:"scheduled delivery"},{detect:e=>d(e,["templateId","template"]),feature:"templates",label:"provider templates"}];function u(e,s){if(!s)return{supported:!0,violations:[]};const t=[];for(const a of i){if(s[a.feature]!==!1)continue;const l=a.detect(e);l!==void 0&&t.push({feature:a.feature,field:l,message:`Message uses ${a.label} (field "${l}") but the provider does not support the "${a.feature}" capability`})}return{supported:t.length===0,violations:t}}export{u as default};

package/dist/utils/validation/validate-email.d.ts

@@ -1,7 +1,7 @@
 /**
- * Validates an email address format according to basic RFC standards.
- * @param email The email address string to validate.
- * @returns True if the email address is valid, false otherwise.
- */
+* Validates an email address format according to basic RFC standards.
+* @param email The email address string to validate.
+* @returns True if the email address is valid, false otherwise.
+*/
 declare const validateEmail: (email: string) => boolean;
-export default validateEmail;
+export { validateEmail as default };

package/dist/utils/validation/validate-email.js

@@ -1 +1 @@
-var l=Object.defineProperty;var i=(t,e)=>l(t,"name",{value:e,configurable:!0});var f=Object.defineProperty,u=i((t,e)=>f(t,"name",{value:e,configurable:!0}),"i");const c=u(t=>{if(!/^[^\s@]+@[^\s@][^\s.@]*\.[^\s@]+$/.test(t))return!1;const e=t.split("@");if(e.length!==2)return!1;const[r,s]=e;if(!r||!s||t.includes("..")||r.startsWith(".")||r.endsWith(".")||!s.includes(".")||s.startsWith("-")||s.endsWith("-"))return!1;const a=s.split(".");for(const n of a)if(n.startsWith("-")||n.endsWith("-")||n.length===0)return!1;return!0},"validateEmail");export{c as default};
+const f=s=>{if(!/^[^\s@]+@[^\s@][^\s.@]*\.[^\s@]+$/.test(s))return!1;const r=s.split("@");if(r.length!==2)return!1;const[e,t]=r;if(!e||!t||s.includes("..")||e.startsWith(".")||e.endsWith(".")||!t.includes(".")||t.startsWith("-")||t.endsWith("-"))return!1;const i=t.split(".");for(const n of i)if(n.startsWith("-")||n.endsWith("-")||n.length===0)return!1;return!0};export{f as default};