@dbx-tools/email 0.3.18 → 0.3.19

package/index.ts

@@ -2,6 +2,7 @@
 // Regenerated from the exporting modules in ./src.
 // Hand edits are overwritten on the next watch; this file is read-only.
 
+export * as brand from "./src/brand";
 export * as config from "./src/config";
 export * as emailHtml from "./src/email-html";
 export * as markdown from "./src/markdown";
@@ -10,6 +11,7 @@ export * as plugin from "./src/plugin";
 export * as sender from "./src/sender";
 export * as tool from "./src/tool";
 export * as transport from "./src/transport";
+export type { EmailBrand } from "./src/brand";
 export type { SmtpConfig, EmailPluginConfig, ResolvedSmtpConfig, ResolvedFileConfig, ResolvedEmailConfig } from "./src/config";
 export type { EmailHtmlOptions } from "./src/email-html";
 export type { EmailToolOptions } from "./src/tool";

package/package.json

@@ -19,15 +19,15 @@
     "juice": "^12.1.1",
     "marked": "^18.0.5",
     "nodemailer": "^7.0.13",
-    "@dbx-tools/shared-core": "0.3.18",
-    "@dbx-tools/shared-email": "0.3.18"
+    "@dbx-tools/shared-core": "0.3.19",
+    "@dbx-tools/shared-email": "0.3.19"
   },
   "main": "index.ts",
   "license": "UNLICENSED",
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.3.18",
+  "version": "0.3.19",
   "types": "index.ts",
   "type": "module",
   "exports": {

package/src/brand.ts

@@ -0,0 +1,64 @@
+/**
+ * Optional brand styling for outbound email. {@link EmailBrand} is the
+ * small, email-safe slice of a brand a message actually needs - an accent
+ * color, a font stack, a display name, and an optional logo image - and
+ * {@link emailBrandFromContext} derives it from the portable `BrandContext`
+ * shared across the UI and libraries.
+ *
+ * Email can't use the `[data-brand]` CSS bridge the browser UI uses (mail
+ * clients strip `<style>` blocks and ignore `var()`), so branding is applied
+ * by inlining these values at render time. A logo is only emitted when it's
+ * a fetchable `http(s):` or `data:` URL - a package-export path (the default
+ * asset form) can't resolve in an inbox, so it's dropped rather than shown
+ * as a broken image.
+ *
+ * @module
+ */
+import { brand, type BrandContext } from "@dbx-tools/shared-core";
+
+/** Email-safe brand values inlined into the message layout at render time. */
+export interface EmailBrand {
+  /** Header-band background and link color. */
+  accent: string;
+  /** Text and logo color rendered on the accent band. Defaults to white. */
+  onAccent?: string;
+  /** Body font stack. */
+  fontFamily: string;
+  /** Product/display name, used as the header text and the logo `alt`. */
+  name?: string;
+  /**
+   * Logo image rendered in the header band. Only an `http(s):` or `data:`
+   * URL renders; other values (e.g. a package-export path) are ignored,
+   * since they can't load in a mail client.
+   */
+  logoUrl?: string;
+}
+
+/** Whether `value` is an image reference a mail client can actually load. */
+function isRenderableImageUrl(value: string | undefined): value is string {
+  return typeof value === "string" && /^(?:https?:|data:)/i.test(value);
+}
+
+/**
+ * Derive the email-safe {@link EmailBrand} from a full brand context: the
+ * primary color as the accent, the sans font stack, the display name, and
+ * the dark-surface logo (the header band is dark) when it's a renderable URL.
+ */
+export function emailBrandFromContext(context: BrandContext): EmailBrand {
+  const logo = context.assets.logo.dark ?? context.assets.logo.light;
+  return {
+    accent: context.colors.primary,
+    onAccent: "#ffffff",
+    fontFamily: context.typography.sans,
+    name: context.name,
+    ...(isRenderableImageUrl(logo) ? { logoUrl: logo } : {}),
+  };
+}
+
+/**
+ * The dbx-tools brand as an {@link EmailBrand}, ready to pass to the email
+ * plugin (`email({ brand: defaultEmailBrand })`). Convenience so a consumer
+ * needs only `@dbx-tools/email`, not the shared brand context, for the
+ * common case of the default brand.
+ */
+export const defaultEmailBrand: EmailBrand = emailBrandFromContext(brand.defaultBrandContext);

package/src/config.ts

@@ -26,6 +26,7 @@ import type { BasePluginConfig } from "@databricks/appkit";
 import type { JSONSchema7 } from "json-schema";
 import { object } from "@dbx-tools/shared-core";
 import { resolve } from "node:path";
+import type { EmailBrand } from "./brand";
 import { parseAllowedSenders } from "./sender";
 
 /** SMTP connection + credentials. All fields fall back to env when unset. */
@@ -74,9 +75,16 @@ export interface EmailPluginConfig extends BasePluginConfig {
    * `EMAIL_ALLOWED_SENDERS`. Omit (or leave empty) for no restriction.
    */
   allowedSenders?: string | string[];
+  /**
+   * Optional brand styling (accent, font, header logo) applied to the
+   * rendered HTML of every message. Omit for the neutral default layout.
+   * Pass {@link emailBrandFromContext} to derive it from a shared
+   * `BrandContext`.
+   */
+  brand?: EmailBrand;
 }
 
-/** Sender source shared by both resolved modes. */
+/** Config shared by both resolved modes. */
 interface ResolvedSender {
   /** Sender domain; present whenever {@link from} is absent. */
   domain?: string;
@@ -87,6 +95,8 @@ interface ResolvedSender {
    * Empty means no restriction.
    */
   allowedSenders: string[];
+  /** Brand styling applied to rendered HTML; absent for the default layout. */
+  brand?: EmailBrand;
 }
 
 /** Resolved config for real SMTP delivery. */
@@ -199,6 +209,7 @@ export function resolveEmailConfig(config: EmailPluginConfig = {}): ResolvedEmai
     ...(domain ? { domain } : {}),
     ...(from ? { from } : {}),
     allowedSenders,
+    ...(config.brand ? { brand: config.brand } : {}),
   };
 
   const hasAllSmtp = Boolean(host && user && pass);

package/src/email-html.ts

@@ -12,15 +12,25 @@
  * 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
  */
 
 import { string } from "@dbx-tools/shared-core";
 import juice from "juice";
+import type { EmailBrand } from "./brand";
 import { markdownToHtml } from "./markdown";
 
-/** Accent color for the header band and links. */
-const ACCENT = "#0b6bcb";
+/** 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`). */
 export const escapeHtml = string.escapeHtml;
@@ -29,12 +39,14 @@ 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.
+ * by juice for clients that honor it. Parameterized by the resolved accent
+ * so body links match the brand.
  */
-const CONTENT_CSS = `
+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 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; }
@@ -52,6 +64,7 @@ const CONTENT_CSS = `
       .container { width: 100% !important; }
       .gutter { padding-left: 20px !important; padding-right: 20px !important; }
     }`;
+}
 
 /** Options for {@link renderEmailHtml}. */
 export interface EmailHtmlOptions {
@@ -67,6 +80,11 @@ export interface EmailHtmlOptions {
   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. */
@@ -89,12 +107,30 @@ function footerRow(footer: string | undefined): string {
           </tr>`;
 }
 
+/**
+ * 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 28px tall 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="28" style="height: 28px; 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 `body` (markdown) into a complete, style-inlined email document
- * using the branded responsive layout.
+ * 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>
@@ -102,17 +138,17 @@ export function renderEmailHtml(opts: EmailHtmlOptions): string {
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <meta name="color-scheme" content="light only" />
     <title>${escapeHtml(title)}</title>
-    <style>${CONTENT_CSS}
+    <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: -apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif;">
+          <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};">
-                <span style="color: #ffffff; font-size: 18px; font-weight: 700; line-height: 1.3;">${escapeHtml(title)}</span>
+              <td class="gutter" style="padding: 20px 32px; background-color: ${accent};">
+                ${headerBand(title, brand, onAccent)}
               </td>
             </tr>
             <tr>

package/src/outbox.ts

@@ -17,6 +17,7 @@ import type { EmailMessage } from "@dbx-tools/shared-email";
 import { string } from "@dbx-tools/shared-core";
 import { mkdir, writeFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
+import type { EmailBrand } from "./brand";
 import { renderEmailHtml } from "./email-html";
 
 /** Filesystem-safe slug of the subject for the file name. */
@@ -47,6 +48,7 @@ export async function writeOutboxEmail(
   message: EmailMessage,
   from: string,
   dir: string,
+  brand?: EmailBrand,
 ): Promise<string> {
   const folder = resolve(dir, from);
   await mkdir(folder, { recursive: true });
@@ -56,6 +58,7 @@ export async function writeOutboxEmail(
     headers: headerRows(message, from),
     body: message.body,
     footer: "Local outbox preview - written to disk, not sent (no SMTP credentials configured).",
+    ...(brand ? { brand } : {}),
   });
   await writeFile(path, html, "utf8");
   return path;

package/src/transport.ts

@@ -104,7 +104,7 @@ export async function sendEmail(message: EmailMessage, from: string): Promise<Em
   const recipient = recipientEcho(message.to);
 
   if (config.mode === "file") {
-    const path = await writeOutboxEmail(message, from, config.outDir);
+    const path = await writeOutboxEmail(message, from, config.outDir, config.brand);
     return { sent: true, recipient, from, messageId: path };
   }
 
@@ -115,7 +115,11 @@ export async function sendEmail(message: EmailMessage, from: string): Promise<Em
     to: message.to,
     subject: message.subject,
     text: message.body,
-    html: renderEmailHtml({ subject: message.subject, body: message.body }),
+    html: renderEmailHtml({
+      subject: message.subject,
+      body: message.body,
+      ...(config.brand ? { brand: config.brand } : {}),
+    }),
     ...(message.cc && message.cc.length > 0 ? { cc: message.cc } : {}),
     ...(message.bcc && message.bcc.length > 0 ? { bcc: message.bcc } : {}),
     ...(attachments ? { attachments } : {}),