@sdxc/mail 0.0.0-pre.1

package/dist/render.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Turns an email body tree into the two parts a message carries. One authored
+ * tree produces both the HTML part and the plain-text alternative derived from
+ * it, so a text part is never a separate piece of copy that can drift.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { RemixElement } from "remix/ui";
+/** The two body parts produced from a single email tree. */
+export interface RenderedEmail {
+    /** Serialized HTML of the tree. */
+    html: string;
+    /** Plain-text alternative derived from that same HTML. */
+    text: string;
+}
+/**
+ * Renders an email body tree to both body parts.
+ *
+ * The text part is parsed from the rendered HTML, keeping link targets and
+ * structure in sync; set `text` on the message to override the heuristic.
+ *
+ * @param element - The body tree to render.
+ * @returns The HTML part and the plain-text alternative derived from it.
+ * @example let { html, text } = await render(<InviteBody url={url} />);
+ */
+export declare function render(element: RemixElement): Promise<RenderedEmail>;

package/dist/render.js

@@ -0,0 +1,33 @@
+/**
+ * Turns an email body tree into the two parts a message carries. One authored
+ * tree produces both the HTML part and the plain-text alternative derived from
+ * it, so a text part is never a separate piece of copy that can drift.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { renderToString } from "remix/ui/server";
+import { htmlToText } from "./lib/html-to-text.js";
+/**
+ * The document type every mail client is calibrated against.
+ *
+ * XHTML 1.0 Transitional, because Outlook renders through Word, which needs
+ * this declaration to avoid a quirks mode that collapses table cell heights.
+ */
+const DOCTYPE = '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">';
+/**
+ * Renders an email body tree to both body parts.
+ *
+ * The text part is parsed from the rendered HTML, keeping link targets and
+ * structure in sync; set `text` on the message to override the heuristic.
+ *
+ * @param element - The body tree to render.
+ * @returns The HTML part and the plain-text alternative derived from it.
+ * @example let { html, text } = await render(<InviteBody url={url} />);
+ */
+export async function render(element) {
+    let html = await renderToString(element);
+    if (html.startsWith("<html"))
+        html = `${DOCTYPE}${html}`;
+    return { html, text: htmlToText(html) };
+}

package/dist/types.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Delivery contracts shared by the mailer and every transport: the message a
+ * caller writes, the normalized message a transport receives, the authoring
+ * interface an email class implements, and the transport adapter itself.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Result } from "@sdxc/result";
+import type { RemixElement } from "remix/ui";
+import type { MailError } from "./errors.js";
+/** A single mailbox, optionally with the display name clients show instead of it. */
+export interface Address {
+    /** Addr-spec of the mailbox, e.g. `no-reply@example.com`. */
+    email: string;
+    /** Display name shown by mail clients in place of the bare address. */
+    name?: string;
+}
+/**
+ * A message as callers write it. Everything the mailer can supply a default for
+ * is optional, so a caller only states what is specific to this message.
+ */
+export interface Message {
+    /** Sender mailbox; omitted means the mailer's configured sender. */
+    from?: Address;
+    /** Primary recipients; at least one is required. */
+    to: Address | Address[];
+    /** Carbon-copy recipients. */
+    cc?: Address | Address[];
+    /** Blind carbon-copy recipients, kept hidden from the other recipients. */
+    bcc?: Address | Address[];
+    /** Where replies go; omitted means the mailer's configured reply-to. */
+    replyTo?: Address | Address[];
+    /** Subject line, already in the recipient's language. */
+    subject: string;
+    /** HTML body; when it is the only body part the mailer derives the text one. */
+    html?: string;
+    /** Plain-text body; supply it to override the mailer's derived version. */
+    text?: string;
+    /** Extra headers merged over the mailer's configured headers. */
+    headers?: Record<string, string>;
+    /** Explicit `Date` header value; omitted means "now". Set it to keep tests deterministic. */
+    date?: Date;
+    /** Explicit `Message-ID` value; omitted means generated. Set it to keep tests deterministic. */
+    messageId?: string;
+}
+/**
+ * A message after normalization: defaults applied, every address list coerced to
+ * an array, and a plain-text part derived when only HTML was authored. Transports
+ * receive this shape fully resolved, with defaults applied and validation done.
+ */
+export interface NormalizedMessage {
+    /** Sender mailbox, resolved from the message or the mailer configuration. */
+    from: Address;
+    /** Primary recipients, guaranteed to hold at least one address. */
+    to: Address[];
+    /** Carbon-copy recipients; empty when none were given. */
+    cc: Address[];
+    /** Blind carbon-copy recipients; empty when none were given. */
+    bcc: Address[];
+    /** Reply-to mailboxes; empty when neither the message nor the mailer set one. */
+    replyTo: Address[];
+    /** Subject line, already in the recipient's language. */
+    subject: string;
+    /** HTML body; at least one of `html` and `text` is a non-empty string. */
+    html?: string;
+    /** Plain-text body; derived from `html` unless the caller supplied one. */
+    text?: string;
+    /** Headers to add, with per-message values winning over configured ones. */
+    headers: Record<string, string>;
+    /** Value for the `Date` header, defaulted to the moment of normalization. */
+    date: Date;
+    /** Value for the `Message-ID` header, generated when the caller omitted it. */
+    messageId: string;
+    /**
+     * The email object this message was produced from, when it came from one.
+     * It exists so tests can identify a sent message by its type.
+     */
+    email?: Email;
+}
+/** Identifier a provider assigns to an accepted message. */
+export interface SentMessage {
+    /** Provider identifier when it returns one, otherwise the message's `Message-ID`. */
+    messageId: string;
+}
+/**
+ * Adapter that puts a normalized message on the wire for one provider. Delivery
+ * outcome is a value: a transport reports provider rejections through the
+ * returned `Result`.
+ */
+export interface Transport {
+    /**
+     * Delivers an already normalized message.
+     *
+     * @param message - The message to deliver, with defaults applied.
+     * @returns The provider's identifier on success, a `MailError` on rejection.
+     */
+    send(message: NormalizedMessage): Promise<Result<SentMessage, MailError>>;
+}
+/**
+ * An email authored as a class: who it goes to, what it says, and what it looks
+ * like. Sender identity lives on the mailer, and a subject arrives already
+ * translated from the caller's locale handling.
+ */
+export interface Email {
+    /** Recipient this email is addressed to, derived from the data it was constructed with. */
+    readonly to: Address | Address[];
+    /** Subject line, already translated. */
+    readonly subject: string;
+    /** Body tree, rendered by the mailer into HTML and plain text. */
+    body(): RemixElement;
+    /** Per-email reply-to override; the mailer's configuration supplies the default. */
+    readonly replyTo?: Address | Address[];
+    /** Per-email headers, merged over the mailer's configured headers. */
+    readonly headers?: Record<string, string>;
+}

package/dist/types.js

@@ -0,0 +1,8 @@
+/**
+ * Delivery contracts shared by the mailer and every transport: the message a
+ * caller writes, the normalized message a transport receives, the authoring
+ * interface an email class implements, and the transport adapter itself.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */

package/package.json

@@ -0,0 +1,30 @@
+{
+	"name": "@sdxc/mail",
+	"version": "0.0.0-pre.1",
+	"description": "Transport-agnostic transactional email with pluggable transports and remix/ui rendering",
+	"license": "MIT",
+	"type": "module",
+	"exports": {
+		".": "./dist/index.js",
+		"./markdown": "./dist/markdown.js",
+		"./memory": "./dist/memory.js",
+		"./middleware": "./dist/middleware.js",
+		"./cloudflare": "./dist/cloudflare.js"
+	},
+	"dependencies": {
+		"@sdxc/highlight": "0.0.0-pre.1",
+		"@sdxc/logger": "2026.9.11",
+		"@sdxc/markdown": "0.0.0-pre.1",
+		"@sdxc/result": "2026.9.11",
+		"remix": "3.0.0-rc.2"
+	},
+	"gitHead": "e96a064f9208eb667923f57374e2cdaac73c72fb",
+	"publishConfig": {
+		"access": "public"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/sergiodxa/monorepo.git",
+		"directory": "packages/mail"
+	}
+}