@sdxc/mail 0.0.0-pre.1

package/dist/cloudflare.js

@@ -0,0 +1,71 @@
+/**
+ * Transport for the Workers email sending binding, whose structured send call takes
+ * the same fields a normalized message already holds, so it maps them across and
+ * assembles no MIME of its own. The binding is injected rather than read from an
+ * ambient global, which keeps the platform surface a single seam this package can be
+ * tested and corrected at.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { failure, isFailure, success, wrap } from "@sdxc/result";
+import { MailError } from "./errors.js";
+import { formatAddress } from "./lib/address.js";
+/** Returns the formatted list, or `undefined` when empty so an absent field is omitted. */
+function optionalAddresses(addresses) {
+    if (addresses.length === 0)
+        return undefined;
+    return addresses.map(formatAddress);
+}
+/**
+ * Maps a normalized message onto the binding's send payload. Only the first
+ * reply-to mailbox survives, since the platform's field holds one address, so
+ * every shipped `Reply-To` is one the platform actually wrote itself.
+ */
+function toPayload(message) {
+    let replyTo = message.replyTo.at(0);
+    return {
+        from: formatAddress(message.from),
+        to: message.to.map(formatAddress),
+        cc: optionalAddresses(message.cc),
+        bcc: optionalAddresses(message.bcc),
+        replyTo: replyTo && formatAddress(replyTo),
+        subject: message.subject,
+        text: message.text,
+        html: message.html,
+        headers: message.headers,
+    };
+}
+/**
+ * Transport that delivers through the Workers email sending binding, which writes
+ * its own `Date` and `Message-ID` and returns the identifier its delivery logs are
+ * keyed by, enforcing sender and destination limits from its configuration on send.
+ *
+ * @example
+ * let transport = new CloudflareTransport(env.EMAIL);
+ * let mailer = new Mailer({ transport, from: SENDER });
+ */
+export class CloudflareTransport {
+    binding;
+    /**
+     * Creates the transport around an app's binding.
+     *
+     * @param binding - The `send_email` binding declared in the app's Wrangler configuration.
+     */
+    constructor(binding) {
+        this.binding = binding;
+    }
+    /**
+     * Hands the message's fields to the binding, which composes and delivers it.
+     *
+     * @param message - The normalized message to deliver.
+     * @returns The identifier the platform assigned on success, a `MailError` on rejection.
+     */
+    async send(message) {
+        let outcome = await wrap(() => this.binding.send(toPayload(message)));
+        if (isFailure(outcome)) {
+            return failure(new MailError("The mail binding rejected the message.", { cause: outcome.error }));
+        }
+        return success({ messageId: outcome.data.messageId });
+    }
+}

package/dist/components.d.ts

@@ -0,0 +1,346 @@
+/**
+ * Layout kit for email bodies, built for the constraints mail clients impose:
+ * table layout, inline styles, and no external stylesheet. It carries no product
+ * branding — colors, logo, and footer content are props — so every app styles its
+ * own mail without forking the components.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Handle, RemixNode } from "remix/ui";
+/**
+ * A web font to load, and what to use instead everywhere it does not arrive. It
+ * is a prop of {@link Layout} instead of its own component because `@font-face`
+ * only works inside `<head>`, which only the layout renders in the document.
+ */
+export interface Font {
+    /** Family name, as the `@font-face` rule declares it and the copy asks for it. */
+    family: string;
+    /**
+     * What to fall back to, as a CSS font list. It is required because most readers get
+     * it: `@font-face` is unsupported in Gmail, Yahoo, and Outlook on Windows, which is
+     * most of any list, so this is the font the email is actually set in.
+     */
+    fallback: string;
+    /** Where to fetch the font, omitted for a family the reader is assumed to have. */
+    src?: {
+        /** Absolute URL of the font file. */
+        url: string;
+        /** Format at that URL, which the rule has to name for the client to accept it. */
+        format: "woff" | "woff2" | "truetype" | "opentype" | "embedded-opentype" | "svg";
+    };
+    /** Weight this file provides. */
+    weight?: number;
+    /** Style this file provides. */
+    style?: "normal" | "italic";
+}
+export declare namespace Layout {
+    /** Props accepted by {@link Layout}. */
+    interface Props {
+        /** Body of the email, usually headings, text, and a button. */
+        children?: RemixNode;
+        /**
+         * Preheader shown beside the subject in inbox previews. It is hidden in the
+         * body and dropped from the plain-text part, so it never reads as duplicate copy.
+         */
+        preview?: string;
+        /** Logo rendered above the content; omitted means no logo. */
+        logo?: {
+            src: string;
+            alt: string;
+            width?: number;
+        };
+        /** Document title, which some clients show when the email is opened in a browser. */
+        title?: string;
+        /** Language of the copy, so screen readers pronounce it correctly. */
+        lang?: string;
+        /** Page color behind the content card. */
+        background?: string;
+        /** Content card color. */
+        surface?: string;
+        /** Body copy color. */
+        color?: string;
+        /**
+         * Font stack applied to the whole document. Omitted with `fonts` set, the stack is
+         * built from the first of those; omitted with neither, the kit's own stack is used.
+         */
+        fontFamily?: string;
+        /** Web fonts to declare, in preference order. */
+        fonts?: Font[];
+        /** Content width in pixels. */
+        width?: number;
+        /**
+         * CSS appended inside the kit's `prefers-color-scheme: dark` block, for the dark
+         * counterpart of colors the app's own components paint with. It is escaped as a
+         * text node, so it cannot contain `>` or `&`.
+         */
+        darkStyles?: string;
+    }
+}
+/**
+ * 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 declare function Layout(handle: Handle<Layout.Props>): () => import("remix/ui").RemixElement;
+export declare namespace Heading {
+    /** Props accepted by {@link Heading}. */
+    interface Props {
+        /** Heading copy. */
+        children?: RemixNode;
+        /** Outline level, which also picks the font size. */
+        level?: 1 | 2 | 3;
+        /** Heading color. */
+        color?: string;
+        /** Horizontal alignment of the copy. */
+        align?: "left" | "center" | "right";
+    }
+}
+/**
+ * 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 declare function Heading(handle: Handle<Heading.Props>): () => import("remix/ui").RemixElement;
+export declare namespace Text {
+    /** Props accepted by {@link Text}. */
+    interface Props {
+        /** Paragraph copy. */
+        children?: RemixNode;
+        /** Copy color; defaults to the body color, or the muted one when `muted` is set. */
+        color?: string;
+        /** Renders the paragraph in the de-emphasized color. */
+        muted?: boolean;
+        /** Font size in pixels. */
+        size?: number;
+        /** Horizontal alignment of the copy. */
+        align?: "left" | "center" | "right";
+    }
+}
+/**
+ * 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 declare function Text(handle: Handle<Text.Props>): () => import("remix/ui").RemixElement;
+export declare namespace Button {
+    /** Props accepted by {@link Button}. */
+    interface Props {
+        /** Target of the call to action. */
+        href: string;
+        /** Button label. */
+        children?: RemixNode;
+        /** Fill color of the button. */
+        background?: string;
+        /** Label color of the button. */
+        color?: string;
+        /** Corner radius in pixels. */
+        radius?: number;
+    }
+}
+/**
+ * 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 declare function Button(handle: Handle<Button.Props>): () => import("remix/ui").RemixElement;
+export declare namespace Table {
+    /** One row: what is being reported, and what it says. */
+    interface Row {
+        /** Name of the thing reported, rendered in the de-emphasized color. */
+        label: string;
+        /** The value as the reader sees it, already formatted and translated. */
+        value: RemixNode;
+    }
+    /** Props accepted by {@link Table}. */
+    interface Props {
+        /** Rows in reading order. Rendering nothing for an empty list is deliberate. */
+        rows: Row[];
+        /** Color of the hairlines between rows. */
+        borderColor?: string;
+    }
+}
+/**
+ * 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 declare function Table(handle: Handle<Table.Props>): () => import("remix/ui").RemixElement | null;
+export declare namespace Footer {
+    /** Props accepted by {@link Footer}. */
+    interface Props {
+        /** Footer content, such as an address, an unsubscribe link, or a legal note. */
+        children?: RemixNode;
+        /** Footer copy color. */
+        color?: string;
+        /** Color of the hairline above the footer. */
+        borderColor?: string;
+    }
+}
+/**
+ * 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 declare function Footer(handle: Handle<Footer.Props>): () => import("remix/ui").RemixElement;
+export declare namespace Section {
+    /** Props accepted by {@link Section}. */
+    interface Props {
+        /** Content of the section. */
+        children?: RemixNode;
+        /** Padding shorthand applied inside the section, in CSS syntax. */
+        padding?: string;
+        /** Fill behind the section; omitted means it inherits whatever it sits on. */
+        background?: string;
+        /** Horizontal alignment of the content. */
+        align?: "left" | "center" | "right";
+    }
+}
+/**
+ * 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 declare function Section(handle: Handle<Section.Props>): () => import("remix/ui").RemixElement;
+export declare namespace Row {
+    /** Props accepted by {@link Row}. */
+    interface Props {
+        /** The row's cells, which should be {@link Column} elements. */
+        children?: RemixNode;
+        /** Space below the row in pixels. */
+        gap?: number;
+    }
+}
+/**
+ * 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 declare function Row(handle: Handle<Row.Props>): () => import("remix/ui").RemixElement;
+export declare namespace Column {
+    /** Props accepted by {@link Column}. */
+    interface Props {
+        /** Content of the cell. */
+        children?: RemixNode;
+        /**
+         * Width as a CSS length or percentage; a bare number is read as pixels. Omitted
+         * lets the table divide the space.
+         */
+        width?: string | number;
+        /** Horizontal alignment of the content. */
+        align?: "left" | "center" | "right";
+        /** Vertical alignment of the content against the tallest cell in the row. */
+        valign?: "top" | "middle" | "bottom";
+        /** Padding shorthand inside the cell, in CSS syntax. */
+        padding?: string;
+    }
+}
+/**
+ * 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 declare function Column(handle: Handle<Column.Props>): () => import("remix/ui").RemixElement;
+export declare namespace Link {
+    /** Props accepted by {@link Link}. */
+    interface Props {
+        /** Where the link goes. */
+        href: string;
+        /** Link text. */
+        children?: RemixNode;
+        /** Link color; omitted inherits the surrounding copy, so dark mode carries it. */
+        color?: string;
+        /** Whether the link is underlined. */
+        underline?: boolean;
+    }
+}
+/**
+ * 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 declare function Link(handle: Handle<Link.Props>): () => import("remix/ui").RemixElement;
+export declare namespace Img {
+    /** Props accepted by {@link Img}. */
+    interface Props {
+        /** Absolute URL of the image; a relative one resolves against nothing in an inbox. */
+        src: string;
+        /**
+         * What the image says, for the reader who never sees it. Required since most
+         * readers are that reader — every major client blocks remote images until
+         * asked — so pass an empty string for an image that carries no meaning.
+         */
+        alt: string;
+        /** Width in pixels. */
+        width?: number;
+        /** Height in pixels; omitted lets the image keep its ratio. */
+        height?: number;
+        /** Corner radius in pixels. */
+        radius?: number;
+        /** Space below the image in pixels. */
+        gap?: number;
+    }
+}
+/**
+ * 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 declare function Img(handle: Handle<Img.Props>): () => import("remix/ui").RemixElement;
+export declare namespace Hr {
+    /** Props accepted by {@link Hr}. */
+    interface Props {
+        /** Rule color. */
+        color?: string;
+        /** Space above and below the rule in pixels. */
+        gap?: number;
+    }
+}
+/**
+ * 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 declare function Hr(handle: Handle<Hr.Props>): () => import("remix/ui").RemixElement;
+/** Monospace stack, chosen so no family needs quoting inside a `style` attribute. */
+export declare 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 declare const CODE_COLOR = "#f4f4f5";
+export declare namespace CodeInline {
+    /** Props accepted by {@link CodeInline}. */
+    interface Props {
+        /** The code, as text. */
+        children?: RemixNode;
+    }
+}
+/**
+ * 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 declare function CodeInline(handle: Handle<CodeInline.Props>): () => import("remix/ui").RemixElement;