@dbx-tools/email 0.6.45 → 0.6.48

package/src/email-html.ts

@@ -1,174 +1,33 @@
-/**
- * Email HTML assembly: render a markdown body into a branded, responsive
- * email layout and inline the stylesheet with `juice`.
- *
- * The layout is the classic email-safe pattern (a centered 600px
- * table-based container with a header band, content card, and optional
- * footer) - the same shape MJML emits, hand-built here because MJML's
- * toolchain pulls fast-moving browser-data deps (caniuse-lite,
- * baseline-browser-mapping) that are awkward to install behind a
- * locked-down registry. Inlining matters because real clients (Gmail,
- * Outlook) strip `<style>` blocks and ignore class selectors; the same
- * renderer feeds both the local outbox preview and the SMTP HTML part,
- * so a browser and an inbox show the same thing.
- *
- * Brand styling (accent color, font, header logo) is optional: pass an
- * {@link EmailBrand} to color the layout, or omit it for the neutral
- * default. Branding is inlined here because the browser UI's `[data-brand]`
- * CSS bridge can't reach an inbox (see `./brand`).
- *
- * @module
- */
-
+/** Node rendering adapters for the shared React Email document. @module */
 import { string } from "@dbx-tools/shared-core";
-import juice from "juice";
-import type { EmailBrand } from "./brand.ts";
-import { markdownToHtml } from "./markdown.ts";
-
-/**
- * Rendered height of the header logo. Fixed rather than intrinsic because
- * mail clients ignore CSS sizing on an image without an `height` attribute.
- */
-const LOGO_HEIGHT_PX = 28;
+import { EmailDocument, type EmailDocumentProps } from "@dbx-tools/shared-email-template";
+import { render } from "@react-email/render";
+import { createElement } from "react";
 
-/** Neutral fallback styling when no brand is supplied. */
-const DEFAULT_BRAND: Required<Pick<EmailBrand, "accent" | "onAccent" | "fontFamily">> = {
-  accent: "#0b6bcb",
-  onAccent: "#ffffff",
-  fontFamily: "-apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif",
-};
-
-/** Escape HTML-significant characters (re-exported from `@dbx-tools/shared-core`). */
+/** Escape HTML-significant characters (re-exported from shared-core). */
 export const escapeHtml = string.escapeHtml;
 
-/**
- * Content stylesheet inlined onto the markdown body (juice maps these
- * onto elements). Outer layout styling is written inline directly so it
- * survives even if inlining is skipped; the `@media` rule is preserved
- * by juice for clients that honor it. Parameterized by the resolved accent
- * so body links match the brand.
- */
-function contentCss(accent: string): string {
-  return `
-    .email-body { font-size: 15px; line-height: 1.55; color: #1a1a1a; }
-    .email-body p { margin: 0 0 1rem; }
-    .email-body a { color: ${accent}; }
-    .email-body h1, .email-body h2, .email-body h3 { margin: 1.4rem 0 0.6rem; line-height: 1.25; }
-    .email-body ul, .email-body ol { margin: 0 0 1rem; padding-left: 1.4rem; }
-    .email-body table { border-collapse: collapse; margin: 1rem 0; width: 100%; font-size: 14px; }
-    .email-body th, .email-body td { border: 1px solid #d0d7de; padding: 6px 10px; text-align: left; }
-    .email-body th { background: #f6f8fa; font-weight: 600; }
-    .email-body code { background: #f1f3f5; padding: 2px 5px; border-radius: 4px; font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 0.9em; }
-    .email-body pre { background: #f1f3f5; padding: 12px; border-radius: 6px; overflow-x: auto; }
-    .email-body pre code { background: none; padding: 0; }
-    .email-body blockquote { margin: 1rem 0; padding: 0 1rem; color: #57606a; border-left: 3px solid #d0d7de; }
-    .email-body img { max-width: 100%; height: auto; }
-    .meta { border-collapse: collapse; font-size: 13px; margin-bottom: 4px; }
-    .meta th { text-align: left; padding: 2px 12px 2px 0; vertical-align: top; color: #6b7280; font-weight: 600; white-space: nowrap; }
-    .meta td { padding: 2px 0; color: #374151; }
-    @media only screen and (max-width: 620px) {
-      .container { width: 100% !important; }
-      .gutter { padding-left: 20px !important; padding-right: 20px !important; }
-    }`;
-}
-
-/** Options for {@link renderEmailHtml}. */
-export interface EmailHtmlOptions {
-  /** Markdown body. Rendered to HTML, then wrapped in the layout. */
-  body: string;
-  /** Header-band title and document `<title>`. Defaults to "Message". */
-  subject?: string;
-  /**
-   * Optional `[label, value]` envelope rows shown above the body (used
-   * by the outbox preview; omitted for SMTP sends, where the mail client
-   * shows the envelope itself).
-   */
-  headers?: ReadonlyArray<readonly [string, string]>;
-  /** Optional small-print footer line. Omitted when unset. */
-  footer?: string;
-  /**
-   * Optional brand styling for the layout (accent, font, header logo).
-   * Omit for the neutral default palette.
-   */
-  brand?: EmailBrand;
-}
-
-/** Render the optional envelope-header table block. */
-function metaBlock(headers: EmailHtmlOptions["headers"]): string {
-  if (!headers || headers.length === 0) return "";
-  const rows = headers
-    .map(([label, value]) => `<tr><th>${escapeHtml(label)}</th><td>${escapeHtml(value)}</td></tr>`)
-    .join("");
-  return `<table role="presentation" class="meta"><tbody>${rows}</tbody></table>`;
-}
+/** Options accepted by the shared React Email document. */
+export type EmailHtmlOptions = EmailDocumentProps;
 
-/** Render the optional footer row. */
-function footerRow(footer: string | undefined): string {
-  if (!footer) return "";
-  return `
-          <tr>
-            <td class="gutter" style="padding: 16px 32px; border-top: 1px solid #eaecef; color: #9aa0a6; font-size: 12px; line-height: 1.5;">
-              ${escapeHtml(footer)}
-            </td>
-          </tr>`;
+/** Render a complete responsive React Email document. */
+export async function renderEmailHtml(options: EmailHtmlOptions): Promise<string> {
+  return render(createElement(EmailDocument, options), { pretty: true });
 }
 
-/**
- * Render the header-band content: the brand logo (when the brand supplies a
- * renderable image) above the title, or just the title. The logo is capped
- * at {@link LOGO_HEIGHT_PX} and tinted implicitly by its own artwork; the
- * title always shows so the band is never empty.
- */
-function headerBand(title: string, brand: EmailBrand, onAccent: string): string {
-  const logo = brand.logoUrl
-    ? `<img src="${escapeHtml(brand.logoUrl)}" alt="${escapeHtml(brand.name ?? title)}" height="${LOGO_HEIGHT_PX}" style="height: ${LOGO_HEIGHT_PX}px; width: auto; display: block; margin-bottom: 8px;" />`
-    : "";
-  return `${logo}<span style="color: ${onAccent}; font-size: 18px; font-weight: 700; line-height: 1.3;">${escapeHtml(title)}</span>`;
+/** Render the same React Email document as its plain-text alternative. */
+export async function renderEmailText(options: EmailHtmlOptions): Promise<string> {
+  return render(createElement(EmailDocument, options), { plainText: true });
 }
 
-/**
- * Render `body` (markdown) into a complete, style-inlined email document
- * using the responsive layout. When `opts.brand` is set its accent, font,
- * and logo style the layout; otherwise a neutral default palette is used.
- */
-export function renderEmailHtml(opts: EmailHtmlOptions): string {
-  const title = opts.subject?.trim() || "Message";
-  const accent = opts.brand?.accent ?? DEFAULT_BRAND.accent;
-  const onAccent = opts.brand?.onAccent ?? DEFAULT_BRAND.onAccent;
-  const fontFamily = opts.brand?.fontFamily ?? DEFAULT_BRAND.fontFamily;
-  const brand: EmailBrand = opts.brand ?? { accent, onAccent, fontFamily };
-  const doc = `<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <meta name="color-scheme" content="light only" />
-    <title>${escapeHtml(title)}</title>
-    <style>${contentCss(accent)}
-    </style>
-  </head>
-  <body style="margin: 0; padding: 0; background-color: #f4f5f7; -webkit-text-size-adjust: 100%;">
-    <table role="presentation" width="100%" cellpadding="0" cellspacing="0" style="background-color: #f4f5f7;">
-      <tr>
-        <td align="center" style="padding: 24px 12px;">
-          <table role="presentation" class="container" width="600" cellpadding="0" cellspacing="0" style="width: 600px; max-width: 100%; background-color: #ffffff; border-radius: 10px; overflow: hidden; box-shadow: 0 1px 3px rgba(0,0,0,0.08); font-family: ${fontFamily};">
-            <tr>
-              <td class="gutter" style="padding: 20px 32px; background-color: ${accent};">
-                ${headerBand(title, brand, onAccent)}
-              </td>
-            </tr>
-            <tr>
-              <td class="gutter" style="padding: 24px 32px 8px;">
-                ${metaBlock(opts.headers)}
-                <div class="email-body">${markdownToHtml(opts.body)}</div>
-              </td>
-            </tr>${footerRow(opts.footer)}
-          </table>
-        </td>
-      </tr>
-    </table>
-  </body>
-</html>
-`;
-  return juice(doc);
+/** Render both MIME alternatives from one shared React Email component tree. */
+export async function renderEmail(
+  options: EmailHtmlOptions,
+): Promise<{ html: string; text: string }> {
+  const element = createElement(EmailDocument, options);
+  const [html, text] = await Promise.all([
+    render(element, { pretty: true }),
+    render(element, { plainText: true }),
+  ]);
+  return { html, text };
 }

package/src/markdown.ts

@@ -1,94 +1,14 @@
-/**
- * Server-side markdown -> HTML rendering for email bodies. The model
- * drafts bodies in markdown; this turns them into real HTML (GFM tables,
- * lists, code, links). {@link normalizeMarkdown} first repairs the two
- * structures LLMs most often emit as plain text instead of markdown -
- * `=====` divider rules and pipe tables missing their `| --- |`
- * separator row - so they render as a `<hr>` / `<table>` rather than
- * literal text. The prompt steers the model away from ASCII art; this is
- * the belt-and-suspenders fallback.
- *
- * @module
- */
-
-import { marked } from "marked";
-
-/** A line of only `=` or `_` (length >= 3): an ASCII divider rule. */
-function isAsciiRule(line: string): boolean {
-  return /^[ \t]*[=_]{3,}[ \t]*$/.test(line);
-}
-
-/** A line that participates in a markdown pipe table (has a `|`). */
-function isPipeRow(line: string): boolean {
-  return line.includes("|") && line.trim().length > 0;
-}
-
-/** A markdown table separator row, e.g. `| --- | :--: |`. */
-function isSeparatorRow(line: string): boolean {
-  return /^[ \t]*\|?[ \t]*:?-{2,}:?[ \t]*(\|[ \t]*:?-{2,}:?[ \t]*)+\|?[ \t]*$/.test(line);
-}
-
-/** Column count of a pipe row (outer pipes optional). */
-function pipeColumns(line: string): number {
-  return line.trim().replace(/^\|/, "").replace(/\|$/, "").split("|").length;
-}
-
-/** A GFM separator row with `columns` cells. */
-function separatorRow(columns: number): string {
-  return `| ${Array.from({ length: columns }, () => "---").join(" | ")} |`;
-}
-
-/**
- * Repair common LLM "looks-like-markdown-but-isn't" output: convert
- * standalone `=====` / `_____` rules to a `---` thematic break (leaving
- * genuine setext-heading underlines intact), and insert a `| --- |`
- * separator after the first row of a pipe block that lacks one so GFM
- * renders it as a table.
- */
-export function normalizeMarkdown(src: string): string {
-  const lines = src.split("\n");
-  const out: string[] = [];
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i]!;
-    const prev = i > 0 ? lines[i - 1]! : "";
-    const next = i + 1 < lines.length ? lines[i + 1]! : "";
-
-    if (isAsciiRule(line)) {
-      // A run of `=` directly under a non-blank text line is a setext H1
-      // underline - keep it. Anything else is a decorative divider.
-      const isSetextUnderline =
-        /^[ \t]*={3,}[ \t]*$/.test(line) && prev.trim() !== "" && !isPipeRow(prev);
-      out.push(isSetextUnderline ? line : "---");
-      continue;
-    }
-
-    // First row of a pipe block (prev is not itself a pipe row) followed
-    // by another aligned pipe row, with no separator and no `###` bar-
-    // chart fill: treat as a table header and inject the separator.
-    const startsPipeBlock = isPipeRow(line) && !isPipeRow(prev);
-    if (
-      startsPipeBlock &&
-      isPipeRow(next) &&
-      !isSeparatorRow(next) &&
-      !/#{3,}/.test(line) &&
-      pipeColumns(line) >= 2 &&
-      pipeColumns(line) === pipeColumns(next)
-    ) {
-      out.push(line);
-      out.push(separatorRow(pipeColumns(line)));
-      continue;
-    }
-
-    out.push(line);
-  }
-  return out.join("\n");
-}
-
-/** Render a markdown body to an HTML fragment (GFM tables enabled). */
-export function markdownToHtml(body: string): string {
-  return marked.parse(normalizeMarkdown(body), {
-    async: false,
-    gfm: true,
-    breaks: true,
+/** Compatibility helpers backed by the shared React Email body. @module */
+import { EmailBody, normalizeEmailMarkdown } from "@dbx-tools/shared-email-template";
+import { render } from "@react-email/render";
+import { createElement } from "react";
+
+/** Normalize indentation in authored content. */
+export const normalizeMarkdown = normalizeEmailMarkdown;
+
+/** Render a standalone message body through React Email. */
+export async function markdownToHtml(body: string): Promise<string> {
+  return render(createElement(EmailBody, { body: normalizeEmailMarkdown(body) }), {
+    pretty: true,
   });
 }

package/src/outbox.ts

@@ -59,7 +59,7 @@ export async function writeOutboxEmail(
   const folder = resolve(dir, from);
   await mkdir(folder, { recursive: true });
   const path = join(folder, `${Date.now()}-${subjectSlug(message.subject)}.html`);
-  const html = renderEmailHtml({
+  const html = await renderEmailHtml({
     subject: message.subject,
     headers: headerRows(message, from),
     body: message.body,

package/src/tool.ts

@@ -29,7 +29,7 @@ const logger = log.logger("email/tool/send-email");
 /**
  * The model-facing description of the send capability, shared by the Mastra
  * {@link emailTool} and the AppKit `email.send` tool so both agents get the
- * same guidance about approval, scope, and body formatting.
+ * same guidance about approval and scope.
  */
 export const SEND_EMAIL_DESCRIPTION = string.toDescription(`
   Send an email on the user's behalf. Pass one or more recipient
@@ -37,11 +37,9 @@ export const SEND_EMAIL_DESCRIPTION = string.toDescription(`
   and a body; the user is prompted to approve the send before it goes
   out (this tool is approval-gated). Use it only when the user
   explicitly asks to send / forward / share something via email -
-  never autonomously. Keep subjects short and bodies self-contained:
-  the recipient has none of the chat context. Write the body in
-  GitHub-Flavored Markdown - headings, lists, and real Markdown
-  tables - not ASCII art (no "=====" dividers or space/pipe-drawn
-  tables); it is rendered to HTML before sending.
+  never autonomously. Compose whatever subject and body best fulfill
+  the user's request; the configured React Email template handles the
+  responsive layout, rich presentation, and brand styling.
 `);
 
 /** Options accepted by {@link emailTool}. */

package/src/transport.ts

@@ -23,13 +23,12 @@
  */
 
 import {
-  AppKitError,
   ConfigurationError,
   ExecutionError,
   ValidationError,
   type ExecutionResult,
 } from "@databricks/appkit";
-import { async, error, log } from "@dbx-tools/shared-core";
+import { execution, log } from "@dbx-tools/shared-core";
 import type { EmailAttachment, EmailMessage, EmailResult } from "@dbx-tools/shared-email";
 import nodemailer, { type SendMailOptions, type Transporter } from "nodemailer";
 import { resolveEmailConfig, type EmailPluginConfig, type ResolvedEmailConfig } from "./config.ts";
@@ -41,7 +40,7 @@ import {
   MAX_BODY_CHARS,
   type EmailExecutionSettings,
 } from "./defaults.ts";
-import { renderEmailHtml } from "./email-html.ts";
+import { renderEmail } from "./email-html.ts";
 import { writeOutboxEmail } from "./outbox.ts";
 import { assertSenderAllowed } from "./sender.ts";
 
@@ -70,17 +69,7 @@ export interface EmailRuntime {
  * directly, mapping a throw onto the same {@link ExecutionResult} shape so
  * call sites branch on `ok` either way.
  */
-const directExecute: EmailExecutor = async (fn) => {
-  try {
-    return { ok: true, data: await fn() };
-  } catch (err) {
-    return {
-      ok: false,
-      status: err instanceof AppKitError ? err.statusCode : 500,
-      message: error.errorMessage(err),
-    };
-  }
-};
+const directExecute = execution.directExecutor<EmailExecutionSettings>();
 
 let runtime: EmailRuntime | undefined;
 
@@ -157,20 +146,23 @@ export async function executeWrite<T>(
   signal?: AbortSignal,
 ): Promise<T> {
   const { execute } = getEmailRuntime();
-  const result = await execute(
-    (executeSignal) => fn(async.combineAbortSignals(executeSignal, signal)),
-    settings,
-  );
-  if (result.ok) return result.data;
-  // A caller that cancelled is not a failure worth reporting as one.
-  if (signal?.aborted) throw ExecutionError.canceled();
-  logger.warn("execution-failed", {
+  return execution.run({
     operation,
-    status: result.status,
-    error: result.message,
-  });
-  throw new ExecutionError(`email: ${operation} failed`, {
-    context: { operation, status: result.status },
+    settings,
+    execute,
+    fn,
+    signal,
+    canceled: ExecutionError.canceled,
+    failed: (failure) => {
+      logger.warn("execution-failed", {
+        operation: failure.operation,
+        status: failure.status,
+        error: failure.message,
+      });
+      return new ExecutionError(`email: ${failure.operation} failed`, {
+        context: { operation: failure.operation, status: failure.status },
+      });
+    },
   });
 }
 
@@ -340,17 +332,18 @@ async function dispatch(
     );
   }
   const attachments = toMailAttachments(message.attachments);
+  const rendered = await renderEmail({
+    subject: message.subject,
+    body: message.body,
+    brand: config.brand,
+  });
   const info = await abortable(
     transporter.sendMail({
       from,
       to: message.to,
       subject: message.subject,
-      text: message.body,
-      html: renderEmailHtml({
-        subject: message.subject,
-        body: message.body,
-        ...(config.brand ? { brand: config.brand } : {}),
-      }),
+      text: rendered.text,
+      html: rendered.html,
       ...(message.cc && message.cc.length > 0 ? { cc: message.cc } : {}),
       ...(message.bcc && message.bcc.length > 0 ? { bcc: message.bcc } : {}),
       ...(attachments ? { attachments } : {}),
@@ -369,8 +362,8 @@ async function dispatch(
  * Send (SMTP mode) or persist (file/outbox mode) one message from the
  * resolved `from` address. `to` (and optional `cc` / `bcc`) each accept
  * one or more addresses, and `attachments` are forwarded as files. The
- * body is markdown: SMTP sends it as both a plain-text part (the raw
- * source) and an HTML part (rendered), and the outbox embeds the
+ * body is rendered by React Email into matching plain-text and HTML MIME
+ * alternatives, and the outbox embeds the
  * rendered HTML in a document. In file mode the returned `messageId` is
  * the path written. Throws when `to` carries no recipient, when the body
  * or attachments exceed the plugin's caps, or when `from` is not permitted

package/src/juice.d.ts

@@ -1,17 +0,0 @@
-// Minimal ambient types for `juice` (no `@types/juice` is published).
-// We only use the default export: inline a stylesheet found in the
-// document's <style> tags into element `style` attributes.
-declare module "juice" {
-  interface JuiceOptions {
-    applyStyleTags?: boolean;
-    removeStyleTags?: boolean;
-    preserveImportant?: boolean;
-    preserveMediaQueries?: boolean;
-    preserveFontFaces?: boolean;
-    inlinePseudoElements?: boolean;
-    xmlMode?: boolean;
-    [option: string]: unknown;
-  }
-  function juice(html: string, options?: JuiceOptions): string;
-  export = juice;
-}