@sdxc/mail 0.0.0-pre.1

package/dist/components.js

@@ -0,0 +1,293 @@
+import { jsx as _jsx, jsxs as _jsxs } from "remix/ui/jsx-runtime";
+/**
+ * Font stack that resolves to a native UI face in every major mail client. No family
+ * needs quoting, which keeps the inline style free of escaped character references.
+ */
+const FONT_FAMILY = "-apple-system, BlinkMacSystemFont, system-ui, Roboto, Helvetica, Arial, sans-serif";
+/** Page color behind the content card. */
+const PAGE_COLOR = "#f4f4f5";
+/** Content card color. */
+const SURFACE_COLOR = "#ffffff";
+/** Body copy color. */
+const TEXT_COLOR = "#18181b";
+/** Color for de-emphasized copy such as footers. */
+const MUTED_COLOR = "#71717a";
+/** Fill color of a call-to-action button. */
+const ACTION_COLOR = "#18181b";
+/** Label color of a call-to-action button. */
+const ACTION_LABEL_COLOR = "#ffffff";
+/** Hairline color separating the footer from the body. */
+const BORDER_COLOR = "#e4e4e7";
+/** Content width in pixels, the widest that renders without scrolling on mobile. */
+const CONTENT_WIDTH = 600;
+/** Font size in pixels per heading level. */
+const HEADING_SIZES = { 1: 24, 2: 20, 3: 16 };
+/**
+ * The dark counterpart of every color above. A declared color scheme with no
+ * dark rules leaves Apple Mail's promise half kept, so these `!important` classes
+ * override every inline light value for colors the caller left to the kit.
+ */
+const DARK_RULES = [
+    ".mail-page{background-color:#09090b !important;}",
+    ".mail-surface{background-color:#18181b !important;}",
+    ".mail-text{color:#fafafa !important;}",
+    ".mail-muted{color:#a1a1aa !important;}",
+    ".mail-rule{border-color:#3f3f46 !important;}",
+    ".mail-action{background-color:#fafafa !important;}",
+    ".mail-action-label{color:#18181b !important;}",
+    ".mail-code{background-color:#27272a !important;color:#fafafa !important;}",
+    ".mail-tok-comment{color:#8b949e !important;}",
+    ".mail-tok-keyword{color:#ff7b72 !important;}",
+    ".mail-tok-string{color:#a5d6ff !important;}",
+    ".mail-tok-number{color:#79c0ff !important;}",
+    ".mail-tok-function{color:#d2a8ff !important;}",
+    ".mail-tok-punctuation{color:#c9d1d9 !important;}",
+    ".mail-tok-inserted{color:#7ee787 !important;}",
+    ".mail-tok-deleted{color:#ffa198 !important;}",
+].join("");
+/**
+ * Builds the document stylesheet: the kit's dark mode, then whatever the caller
+ * adds. The result is a text node, so the renderer escapes it, ruling out `>` and
+ * `&` and any child combinator; descendant and class selectors cover everything.
+ */
+function stylesheet(fonts, extra) {
+    let faces = fonts.map(fontFace).join("");
+    let dark = `@media (prefers-color-scheme:dark){${DARK_RULES}${extra ?? ""}}`;
+    return `:root{color-scheme:light dark;}${faces}${dark}`;
+}
+/**
+ * One `@font-face` rule. `mso-font-alt` is Outlook's own fallback declaration:
+ * Word ignores the `@font-face` rule but reads that property, keeping an
+ * unavailable family on the stack's chosen fallback instead of Times New Roman.
+ */
+function fontFace(font) {
+    let { family, fallback, src, weight = 400, style = "normal" } = font;
+    let source = src ? `src:url(${src.url}) format('${src.format}');` : "";
+    let alt = fallback.split(",")[0]?.trim() ?? "sans-serif";
+    return `@font-face{font-family:'${family}';font-style:${style};font-weight:${weight};mso-font-alt:'${alt}';${source}}`;
+}
+/**
+ * The font stack a set of web fonts asks for: the first family, then its
+ * fallbacks, left unquoted because a `style` attribute escapes a quote to
+ * `'`, naming a family no font has — CSS has allowed bare names since 2.1.
+ */
+function fontStack(fonts) {
+    let first = fonts[0];
+    if (!first)
+        return undefined;
+    return `${first.family}, ${first.fallback}`;
+}
+/** How much of an inbox snippet a client will show before it stops reading. */
+const PREVIEW_LENGTH = 200;
+/**
+ * Characters that occupy a snippet without printing: no-break space, the zero-width
+ * non-joiner, space, joiner, the two directional marks, and the byte-order mark. Seven
+ * of them, cycled, so no client's duplicate-run collapsing shortens the padding.
+ */
+const BLANKS = " ‌​‍‎‏";
+/**
+ * Pads a preheader to the length a client reads, with characters that render as
+ * nothing, so the inbox snippet stops at the block instead of spilling into the
+ * body — an unpadded six-word preheader reads `... RECOVERED Monitor Book Landing`.
+ */
+function previewPadding(preview) {
+    let missing = PREVIEW_LENGTH - preview.length;
+    if (missing <= 0)
+        return "";
+    return BLANKS.repeat(Math.ceil(missing / BLANKS.length)).slice(0, missing);
+}
+/**
+ * Wraps an email body in a centered, fixed-width card of inline-styled tables,
+ * with colors as props so the kit stays unbranded, and renders the document's
+ * only stylesheet — the dark counterpart of its colors; see {@link DARK_RULES}.
+ *
+ * @example <Email.Layout preview="Your invite is ready"><Email.Text>Hi</Email.Text></Email.Layout>
+ */
+export function Layout(handle) {
+    return () => {
+        let { children, preview, logo, title, lang = "en", background, surface, color, fontFamily, fonts = [], width = CONTENT_WIDTH, darkStyles, } = handle.props;
+        let family = fontFamily ?? fontStack(fonts) ?? FONT_FAMILY;
+        let page = background ?? PAGE_COLOR;
+        let card = surface ?? SURFACE_COLOR;
+        let ink = color ?? TEXT_COLOR;
+        let pageClass = background === undefined ? "mail-page" : undefined;
+        let cardClass = surface === undefined ? "mail-surface" : undefined;
+        let inkClass = color === undefined ? "mail-text" : undefined;
+        return (_jsxs("html", { lang: lang, children: [_jsxs("head", { children: [_jsx("meta", { charset: "utf-8" }), _jsx("meta", { name: "viewport", content: "width=device-width, initial-scale=1" }), _jsx("meta", { name: "color-scheme", content: "light dark" }), _jsx("meta", { name: "supported-color-schemes", content: "light dark" }), _jsx("meta", { name: "x-apple-disable-message-reformatting" }), title ? _jsx("title", { children: title }) : null, _jsx("style", { children: stylesheet(fonts, darkStyles) })] }), _jsxs("body", { class: pageClass, style: `margin:0;padding:0;width:100%;background-color:${page};color:${ink};font-family:${family};`, children: [preview ? (_jsxs("div", { "data-skip-in-text": true, style: "display:none;max-height:0;max-width:0;overflow:hidden;opacity:0;font-size:1px;line-height:1px;", children: [preview, previewPadding(preview)] })) : null, _jsx("table", { role: "presentation", width: "100%", cellPadding: "0", cellSpacing: "0", class: pageClass, style: `width:100%;background-color:${page};`, children: _jsx("tbody", { children: _jsx("tr", { children: _jsx("td", { align: "center", class: inkClass, style: `padding:24px 12px;color:${ink};font-family:${family};`, children: _jsx("table", { role: "presentation", width: width, cellPadding: "0", cellSpacing: "0", class: cardClass, style: `width:100%;max-width:${width}px;background-color:${card};border-radius:8px;`, children: _jsxs("tbody", { children: [logo ? (_jsx("tr", { children: _jsx("td", { style: "padding:24px 24px 0;", children: _jsx("img", { src: logo.src, alt: logo.alt, width: logo.width ?? 32, style: "display:block;border:0;" }) }) })) : null, _jsx("tr", { children: _jsx("td", { class: inkClass, style: `padding:24px;font-family:${family};color:${ink};font-size:16px;line-height:1.6;`, children: children }) })] }) }) }) }) }) })] })] }));
+    };
+}
+/**
+ * Renders a heading with the margin collapsed to zero on top, because mail clients
+ * disagree on default heading margins and an inline reset is the only fix that holds.
+ *
+ * @example <Email.Heading level={2}>You have been invited</Email.Heading>
+ */
+export function Heading(handle) {
+    return () => {
+        let { children, level = 1, color, align = "left" } = handle.props;
+        let className = color === undefined ? "mail-text" : undefined;
+        let style = `margin:0 0 16px;padding:0;font-family:inherit;font-size:${HEADING_SIZES[level]}px;line-height:1.3;font-weight:600;color:${color ?? TEXT_COLOR};text-align:${align};`;
+        if (level === 3)
+            return (_jsx("h3", { class: className, style: style, children: children }));
+        if (level === 2)
+            return (_jsx("h2", { class: className, style: style, children: children }));
+        return (_jsx("h1", { class: className, style: style, children: children }));
+    };
+}
+/**
+ * Renders a paragraph of body copy with an explicit line height, since clients
+ * that strip the document styles fall back to a cramped default otherwise.
+ *
+ * @example <Email.Text muted>This link expires in 24 hours.</Email.Text>
+ */
+export function Text(handle) {
+    return () => {
+        let { children, muted = false, color, size = 16, align = "left" } = handle.props;
+        let resolved = color ?? (muted ? MUTED_COLOR : TEXT_COLOR);
+        let className = color === undefined ? (muted ? "mail-muted" : "mail-text") : undefined;
+        return (_jsx("p", { class: className, style: `margin:0 0 16px;padding:0;font-family:inherit;font-size:${size}px;line-height:1.6;color:${resolved};text-align:${align};`, children: children }));
+    };
+}
+/**
+ * Renders a call-to-action as a link inside a single-cell table so the fill
+ * survives in clients that drop CSS backgrounds on anchors, with the padding
+ * on the cell since Word supports neither inline-block nor padding on an anchor.
+ *
+ * @example <Email.Button href={url}>Accept invite</Email.Button>
+ */
+export function Button(handle) {
+    return () => {
+        let { href, children, background, color, radius = 6 } = handle.props;
+        let fillClass = background === undefined ? "mail-action" : undefined;
+        let labelClass = color === undefined ? "mail-action-label" : undefined;
+        return (_jsx("table", { role: "presentation", cellPadding: "0", cellSpacing: "0", style: "margin:0 0 16px;", children: _jsx("tbody", { children: _jsx("tr", { children: _jsx("td", { align: "center", class: fillClass, style: `padding:12px 20px;background-color:${background ?? ACTION_COLOR};border-radius:${radius}px;`, children: _jsx("a", { href: href, class: labelClass, style: `display:inline-block;font-family:inherit;font-size:16px;line-height:1.2;font-weight:600;color:${color ?? ACTION_LABEL_COLOR};text-decoration:none;`, children: children }) }) }) }) }));
+    };
+}
+/**
+ * A set of facts as a two-column table: label on the left, value against the
+ * right, with hairlines between rows — a scannable column beats one paragraph
+ * per fact, and stays a layout every mail client renders alike.
+ *
+ * @example <Email.Table rows={[{ label: "Status", value: "Up" }]} />
+ */
+export function Table(handle) {
+    return () => {
+        let { rows, borderColor } = handle.props;
+        if (rows.length === 0)
+            return null;
+        let rule = borderColor === undefined ? " mail-rule" : "";
+        return (_jsx("table", { role: "presentation", width: "100%", cellPadding: "0", cellSpacing: "0", style: "width:100%;margin:0 0 16px;border-collapse:collapse;", children: _jsx("tbody", { children: rows.map((row, index) => {
+                    let border = index === 0 ? "none" : `1px solid ${borderColor ?? BORDER_COLOR}`;
+                    return (_jsxs("tr", { children: [_jsx("td", { class: `mail-muted${rule}`, style: `padding:10px 12px 10px 0;border-top:${border};font-family:inherit;font-size:14px;line-height:1.4;color:${MUTED_COLOR};white-space:nowrap;vertical-align:top;`, children: row.label }), _jsx("td", { align: "right", class: `mail-text${rule}`, style: `padding:10px 0;border-top:${border};font-family:inherit;font-size:14px;line-height:1.4;font-weight:600;color:${TEXT_COLOR};text-align:right;word-break:break-word;vertical-align:top;`, children: row.value })] }, row.label));
+                }) }) }));
+    };
+}
+/**
+ * Closes an email with de-emphasized copy under a hairline. Content is entirely a
+ * prop, so the kit never ships a company name, address, or unsubscribe wording.
+ *
+ * @example <Email.Footer>Sent because you were invited to a team.</Email.Footer>
+ */
+export function Footer(handle) {
+    return () => {
+        let { children, color, borderColor } = handle.props;
+        return (_jsx("table", { role: "presentation", width: "100%", cellPadding: "0", cellSpacing: "0", style: "width:100%;", children: _jsx("tbody", { children: _jsx("tr", { children: _jsx("td", { class: borderColor === undefined ? "mail-rule" : undefined, style: `padding:16px 0 0;border-top:1px solid ${borderColor ?? BORDER_COLOR};`, children: _jsx("div", { class: color === undefined ? "mail-muted" : undefined, style: `font-family:inherit;font-size:12px;line-height:1.5;color:${color ?? MUTED_COLOR};`, children: children }) }) }) }) }));
+    };
+}
+/**
+ * A full-width band of content, as a single-cell table. Padding sits on the
+ * cell and the fill on the table — the split Outlook needs, since it drops
+ * padding declared directly on a `<table>`, so the fill paints the whole band.
+ *
+ * @example <Email.Section padding="24px 0"><Email.Text>Grouped copy</Email.Text></Email.Section>
+ */
+export function Section(handle) {
+    return () => {
+        let { children, padding, background, align = "left" } = handle.props;
+        let fill = background ? `background-color:${background};` : "";
+        return (_jsx("table", { role: "presentation", width: "100%", cellPadding: "0", cellSpacing: "0", style: `width:100%;${fill}`, children: _jsx("tbody", { children: _jsx("tr", { children: _jsx("td", { align: align, style: `${padding ? `padding:${padding};` : ""}font-family:inherit;text-align:${align};`, children: children }) }) }) }));
+    };
+}
+/**
+ * Puts its columns side by side as one table row, the one horizontal
+ * arrangement no client gets wrong, since Outlook supports neither flex nor
+ * grid; width stays fixed, so keep the column count low for phones.
+ *
+ * @example <Email.Row><Email.Column width="50%">Left</Email.Column><Email.Column>Right</Email.Column></Email.Row>
+ */
+export function Row(handle) {
+    return () => {
+        let { children, gap = 16 } = handle.props;
+        return (_jsx("table", { role: "presentation", width: "100%", cellPadding: "0", cellSpacing: "0", style: `width:100%;margin:0 0 ${gap}px;border-collapse:collapse;`, children: _jsx("tbody", { children: _jsx("tr", { children: children }) }) }));
+    };
+}
+/**
+ * One cell of a {@link Row}.
+ *
+ * The width is set as both the `width` attribute and a style, because Outlook reads
+ * the attribute and ignores the style while everything newer does the reverse.
+ *
+ * @example <Email.Column width="120" valign="top"><Email.Img src={logo} alt="Acme" /></Email.Column>
+ */
+export function Column(handle) {
+    return () => {
+        let { children, width, align = "left", valign = "top", padding } = handle.props;
+        let length = typeof width === "number" ? `${width}px` : width;
+        return (_jsx("td", { align: align, valign: valign, width: width, style: `${length ? `width:${length};` : ""}${padding ? `padding:${padding};` : ""}font-family:inherit;text-align:${align};vertical-align:${valign};`, children: children }));
+    };
+}
+/**
+ * An inline link, opening in a new tab, whose color is inherited so it always
+ * matches the copy around it and never needs its own entry in the dark rules;
+ * the underline alone marks it as a link, as a mail reader expects.
+ *
+ * @example <Email.Link href={url}>the settings page</Email.Link>
+ */
+export function Link(handle) {
+    return () => {
+        let { href, children, color, underline = true } = handle.props;
+        let decoration = underline ? "underline" : "none";
+        return (_jsx("a", { href: href, target: "_blank", rel: "noopener noreferrer", style: `color:${color ?? "inherit"};text-decoration:${decoration};font-family:inherit;`, children: children }));
+    };
+}
+/**
+ * An image with the four resets an inbox needs: `display:block` so no line-height gap
+ * opens underneath it, and a cleared border, outline and underline so a client that
+ * inherits link styling leaves it unframed.
+ *
+ * @example <Email.Img src="https://acme.com/logo.png" alt="Acme" width={120} />
+ */
+export function Img(handle) {
+    return () => {
+        let { src, alt, width, height, radius, gap } = handle.props;
+        return (_jsx("img", { src: src, alt: alt, width: width, height: height, style: `display:block;border:0;outline:none;text-decoration:none;max-width:100%;${radius ? `border-radius:${radius}px;` : ""}${gap ? `margin:0 0 ${gap}px;` : ""}` }));
+    };
+}
+/**
+ * A horizontal rule drawn as a top border, since clients disagree about what an
+ * `<hr>` looks like by default and several render the native one as an inset
+ * two-tone groove.
+ *
+ * @example <Email.Hr />
+ */
+export function Hr(handle) {
+    return () => {
+        let { color, gap = 24 } = handle.props;
+        return (_jsx("hr", { class: color === undefined ? "mail-rule" : undefined, style: `width:100%;margin:${gap}px 0;padding:0;border:none;border-top:1px solid ${color ?? BORDER_COLOR};` }));
+    };
+}
+/** Monospace stack, chosen so no family needs quoting inside a `style` attribute. */
+export const MONO_FAMILY = "ui-monospace, SFMono-Regular, Menlo, Consolas, Liberation Mono, monospace";
+/** Fill behind code, light enough to sit inside the card without reading as a block. */
+export const CODE_COLOR = "#f4f4f5";
+/**
+ * A short run of code inside a sentence.
+ *
+ * The size is `0.9em` rather than a pixel value so it tracks whatever it is set inside —
+ * a heading, body copy, a footer — instead of turning into body-sized code in a caption.
+ *
+ * @example <Email.Text>Set <Email.CodeInline>DEBUG=1</Email.CodeInline> and retry.</Email.Text>
+ */
+export function CodeInline(handle) {
+    return () => (_jsx("code", { class: "mail-code", style: `font-family:${MONO_FAMILY};font-size:0.9em;padding:2px 5px;border-radius:4px;background-color:${CODE_COLOR};color:${TEXT_COLOR};`, children: handle.props.children }));
+}

package/dist/errors.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The single error type the mail package reports. Every failure a caller can
+ * branch on — invalid message, failed render, rejected delivery — arrives as a
+ * `MailError` inside a `Result`, so no send path throws.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/**
+ * Error carried by a failed send. The original provider or render error is kept
+ * as `cause`, so a log line can report the root problem directly from it.
+ */
+export declare class MailError extends Error {
+    name: string;
+    /**
+     * Creates a mail error.
+     *
+     * @param message - Human-readable description of what went wrong.
+     * @param options - Standard error options; pass `cause` to keep the original error.
+     */
+    constructor(message: string, options?: ErrorOptions);
+}

package/dist/errors.js

@@ -0,0 +1,24 @@
+/**
+ * The single error type the mail package reports. Every failure a caller can
+ * branch on — invalid message, failed render, rejected delivery — arrives as a
+ * `MailError` inside a `Result`, so no send path throws.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/**
+ * Error carried by a failed send. The original provider or render error is kept
+ * as `cause`, so a log line can report the root problem directly from it.
+ */
+export class MailError extends Error {
+    name = "MailError";
+    /**
+     * Creates a mail error.
+     *
+     * @param message - Human-readable description of what went wrong.
+     * @param options - Standard error options; pass `cause` to keep the original error.
+     */
+    constructor(message, options) {
+        super(message, options);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Transport-agnostic transactional mail: the message contract, the mailer that
+ * normalizes and delivers it, the rendering layer that turns a `remix/ui` tree into
+ * both body parts, and the unbranded layout kit for authoring one. Transports live
+ * behind their own subpaths so importing one never pulls another's dependency.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Email as EmailContract } from "./types.js";
+import * as EmailComponents from "./components.js";
+export type { Address, Message, NormalizedMessage, SentMessage, Transport } from "./types.js";
+export type { MailerOptions, SendOptions } from "./mailer.js";
+export type { RenderedEmail } from "./render.js";
+/**
+ * One row of an `Email.Table`. Exported under its own name because `Email` is a type
+ * alias in type space and a namespace object in value space, so `Email.Table.Row` only
+ * resolves in the second of those and an author writing the rows out needs the first.
+ */
+export type EmailTableRow = EmailComponents.Table.Row;
+/** A web font for `Email.Layout` to declare, named here for the same reason as above. */
+export type EmailFont = EmailComponents.Font;
+export { MailError } from "./errors.js";
+export { formatAddress, toAddressList } from "./lib/address.js";
+export { htmlToText } from "./lib/html-to-text.js";
+export { isEmail, Mailer } from "./mailer.js";
+export { buildMimeMessage } from "./mime.js";
+export { render } from "./render.js";
+/**
+ * An email authored as a class: who it goes to, what it says, and what it
+ * looks like, handed straight to `send()` or `later()`. Declared as an alias
+ * so it can share the `Email` identifier with the layout kit below.
+ */
+export type Email = EmailContract;
+/**
+ * Layout kit for email bodies, addressed as `Email.*` because this namespace
+ * shares its identifier with the `Email` type contract above. `Markdown` and
+ * `CodeBlock` live behind `@sdxc/mail/markdown` instead, shipped only where imported.
+ */
+export declare const Email: typeof EmailComponents;

package/dist/index.js

@@ -0,0 +1,22 @@
+/**
+ * Transport-agnostic transactional mail: the message contract, the mailer that
+ * normalizes and delivers it, the rendering layer that turns a `remix/ui` tree into
+ * both body parts, and the unbranded layout kit for authoring one. Transports live
+ * behind their own subpaths so importing one never pulls another's dependency.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import * as EmailComponents from "./components.js";
+export { MailError } from "./errors.js";
+export { formatAddress, toAddressList } from "./lib/address.js";
+export { htmlToText } from "./lib/html-to-text.js";
+export { isEmail, Mailer } from "./mailer.js";
+export { buildMimeMessage } from "./mime.js";
+export { render } from "./render.js";
+/**
+ * Layout kit for email bodies, addressed as `Email.*` because this namespace
+ * shares its identifier with the `Email` type contract above. `Markdown` and
+ * `CodeBlock` live behind `@sdxc/mail/markdown` instead, shipped only where imported.
+ */
+export const Email = EmailComponents;

package/dist/lib/address.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Address helpers used by the mailer's normalization and by transports that talk
+ * in address strings. They keep the single-or-list shape of the public `Message`
+ * out of every consumer and centralize how a display name is quoted.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Address } from "../types.js";
+/**
+ * Coerces the single-or-list shape callers write into the list shape transports
+ * read. A missing value normalizes to an empty list, keeping an omitted
+ * recipient a valid input.
+ *
+ * @param value - One address, several addresses, or nothing.
+ * @returns A new array; never the caller's own array, so later mutation cannot leak.
+ */
+export declare function toAddressList(value: Address | Address[] | undefined): Address[];
+/**
+ * Formats an address as an RFC 5322 mailbox. A display name is quoted only when
+ * it contains characters that would otherwise change how the mailbox parses, so
+ * ordinary names stay readable in raw headers.
+ *
+ * @param address - The mailbox to format.
+ * @returns `user@example.com` without a name, `Name <user@example.com>` with one.
+ * @example formatAddress({ email: "a@b.com", name: "Ada" }); // 'Ada <a@b.com>'
+ */
+export declare function formatAddress(address: Address): string;
+/**
+ * Reports whether an address is routable enough to hand to a provider. The check
+ * is structural: it rejects the mistakes that produce silent non-delivery — empty,
+ * unsplit, or whitespace-bearing values — while accepting any domain shape.
+ *
+ * @param address - The mailbox to check.
+ * @returns `true` when the address has a local part and a domain around one `@`.
+ */
+export declare function isValidAddress(address: Address): boolean;

package/dist/lib/address.js

@@ -0,0 +1,56 @@
+/**
+ * Address helpers used by the mailer's normalization and by transports that talk
+ * in address strings. They keep the single-or-list shape of the public `Message`
+ * out of every consumer and centralize how a display name is quoted.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/** Characters that force a display name to be quoted in a mailbox string. */
+const SPECIAL_CHARACTERS = /[()<>[\]:;@\\,."]/;
+/** Shape of an address that a provider can route: one `@`, no whitespace, both sides present. */
+const MAILBOX = /^[^\s@]+@[^\s@]+$/;
+/**
+ * Coerces the single-or-list shape callers write into the list shape transports
+ * read. A missing value normalizes to an empty list, keeping an omitted
+ * recipient a valid input.
+ *
+ * @param value - One address, several addresses, or nothing.
+ * @returns A new array; never the caller's own array, so later mutation cannot leak.
+ */
+export function toAddressList(value) {
+    if (value === undefined)
+        return [];
+    if (Array.isArray(value))
+        return [...value];
+    return [value];
+}
+/**
+ * Formats an address as an RFC 5322 mailbox. A display name is quoted only when
+ * it contains characters that would otherwise change how the mailbox parses, so
+ * ordinary names stay readable in raw headers.
+ *
+ * @param address - The mailbox to format.
+ * @returns `user@example.com` without a name, `Name <user@example.com>` with one.
+ * @example formatAddress({ email: "a@b.com", name: "Ada" }); // 'Ada <a@b.com>'
+ */
+export function formatAddress(address) {
+    let name = address.name?.trim();
+    if (!name)
+        return address.email;
+    if (!SPECIAL_CHARACTERS.test(name))
+        return `${name} <${address.email}>`;
+    let quoted = name.replaceAll("\\", "\\\\").replaceAll('"', '\\"');
+    return `"${quoted}" <${address.email}>`;
+}
+/**
+ * Reports whether an address is routable enough to hand to a provider. The check
+ * is structural: it rejects the mistakes that produce silent non-delivery — empty,
+ * unsplit, or whitespace-bearing values — while accepting any domain shape.
+ *
+ * @param address - The mailbox to check.
+ * @returns `true` when the address has a local part and a domain around one `@`.
+ */
+export function isValidAddress(address) {
+    return MAILBOX.test(address.email);
+}

package/dist/lib/html-to-text.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Derives the plain-text alternative of an email from its rendered HTML, so every
+ * message ships both parts without a second authoring step. The conversion is
+ * heuristic by design: it keeps link targets and block structure, and drops
+ * anything a reader cannot act on.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/**
+ * Converts rendered email HTML into its plain-text alternative, preserving link
+ * targets as `label (href)`, image alt text, and block structure as blank lines
+ * so the text part carries the same content the HTML conveys visually.
+ *
+ * @param html - Rendered HTML of an email body.
+ * @returns The plain-text alternative, trimmed and with runs of blank lines collapsed.
+ * @example htmlToText('<p>Hi <a href="https://x.dev">here</a></p>'); // "Hi here (https://x.dev)"
+ */
+export declare function htmlToText(html: string): string;