@ultimat3/mail 1.0.0

package/src/layout.ts

@@ -0,0 +1,221 @@
+// Single responsibility: the base email layout and the semantic colour tokens every block
+// resolves through. Colours are declared once here (light + dark) and inlined by the
+// renderer, because email clients drop <style> and templates must never carry a raw hex.
+// Table-based and 600px wide: Outlook still renders with Word's HTML engine.
+
+import { escapeHtml, safeUrl, styleAttr } from './html';
+
+export type ColorScheme = 'light' | 'dark';
+
+export type MailToken =
+  | 'pageBg'
+  | 'surfaceBg'
+  | 'textPrimary'
+  | 'textMuted'
+  | 'borderSubtle'
+  | 'accentBg'
+  | 'accentText'
+  | 'linkText'
+  | 'calloutInfoBg'
+  | 'calloutInfoText'
+  | 'calloutDangerBg'
+  | 'calloutDangerText';
+
+export const MAIL_TOKENS: Readonly<Record<MailToken, Readonly<Record<ColorScheme, string>>>> =
+  Object.freeze({
+    pageBg: { light: '#f4f5f7', dark: '#0b0d10' },
+    surfaceBg: { light: '#ffffff', dark: '#14181d' },
+    textPrimary: { light: '#16191d', dark: '#e7eaee' },
+    textMuted: { light: '#5c6470', dark: '#9aa4b1' },
+    borderSubtle: { light: '#e2e6ea', dark: '#262c33' },
+    accentBg: { light: '#2f6df6', dark: '#4f86ff' },
+    accentText: { light: '#ffffff', dark: '#0b0d10' },
+    linkText: { light: '#2f6df6', dark: '#7aa7ff' },
+    calloutInfoBg: { light: '#eef3ff', dark: '#141c2c' },
+    calloutInfoText: { light: '#1f3f8f', dark: '#b9cdfb' },
+    calloutDangerBg: { light: '#fdeceb', dark: '#2a1416' },
+    calloutDangerText: { light: '#8c2118', dark: '#f5b3ad' },
+  });
+
+/** Resolve a token to a hex value. The only function in the package that returns a colour. */
+export function token(name: MailToken, scheme: ColorScheme = 'light'): string {
+  return MAIL_TOKENS[name][scheme];
+}
+
+export const MAIL_FONT_STACK =
+  '-apple-system,BlinkMacSystemFont,Segoe UI,Roboto,Helvetica,Arial,sans-serif';
+
+export const MAIL_WIDTH_PX = 600;
+
+/** A node's dark-mode role: which CSS property takes which token when the client is dark. */
+export type DarkRule = readonly [role: string, declarations: readonly [string, MailToken][]];
+
+/**
+ * Dark overrides key off short `data-x` role codes rather than class names: base styling
+ * stays fully inlined for the clients that strip <style>, and the codes are deliberately
+ * not token names, so nothing leaks the design vocabulary into delivered HTML.
+ */
+export const DARK_RULES: readonly DarkRule[] = [
+  ['page', [['background-color', 'pageBg']]],
+  [
+    'card',
+    [
+      ['background-color', 'surfaceBg'],
+      ['border-color', 'borderSubtle'],
+    ],
+  ],
+  ['h', [['color', 'textPrimary']]],
+  ['p', [['color', 'textPrimary']]],
+  ['mut', [['color', 'textMuted']]],
+  [
+    'btn',
+    [
+      ['background-color', 'accentBg'],
+      ['color', 'accentText'],
+    ],
+  ],
+  ['hr', [['border-top-color', 'borderSubtle']]],
+  ['a', [['color', 'linkText']]],
+  [
+    'ci',
+    [
+      ['background-color', 'calloutInfoBg'],
+      ['color', 'calloutInfoText'],
+    ],
+  ],
+  [
+    'cd',
+    [
+      ['background-color', 'calloutDangerBg'],
+      ['color', 'calloutDangerText'],
+    ],
+  ],
+];
+
+/** The one `prefers-color-scheme` block. Clients that ignore it keep the inlined light theme. */
+export function darkModeCss(): string {
+  const rules = DARK_RULES.map(([role, declarations]) => {
+    const body = declarations
+      .map(([property, name]) => `${property}:${token(name, 'dark')}!important`)
+      .join(';');
+    return `[data-x="${role}"]{${body}}`;
+  });
+  return `@media (prefers-color-scheme:dark){${rules.join('')}}`;
+}
+
+export interface UnsubscribeSlot {
+  /** Already translated — the layout never touches a catalog. */
+  readonly label: string;
+  readonly url: string;
+}
+
+export interface LayoutInput {
+  readonly subject: string;
+  /** Hidden preview text. Clients show it next to the subject in the inbox list. */
+  readonly preheader: string;
+  /** Rendered block HTML. */
+  readonly content: string;
+  readonly footer: readonly string[];
+  readonly unsubscribe?: UnsubscribeSlot | undefined;
+  readonly locale: string;
+  readonly direction: 'ltr' | 'rtl';
+}
+
+export type MailLayout = (input: LayoutInput) => string;
+
+export const BASE_LAYOUT = 'base';
+
+const BODY_STYLE = styleAttr([
+  'margin:0',
+  'padding:0',
+  'width:100%',
+  `background-color:${token('pageBg')}`,
+  `font-family:${MAIL_FONT_STACK}`,
+  `color:${token('textPrimary')}`,
+  '-webkit-font-smoothing:antialiased',
+]);
+
+const PREHEADER_STYLE = styleAttr([
+  'display:none',
+  'font-size:1px',
+  'line-height:1px',
+  'max-height:0',
+  'max-width:0',
+  'opacity:0',
+  'overflow:hidden',
+  'mso-hide:all',
+]);
+
+const PAGE_STYLE = styleAttr([`background-color:${token('pageBg')}`, 'width:100%']);
+const GUTTER_STYLE = styleAttr(['padding:24px 12px']);
+const SHELL_STYLE = styleAttr([`width:${MAIL_WIDTH_PX}px`, 'max-width:100%']);
+
+const CARD_STYLE = styleAttr([
+  `background-color:${token('surfaceBg')}`,
+  `border:1px solid ${token('borderSubtle')}`,
+  'border-radius:12px',
+  'padding:32px',
+]);
+
+const FOOTER_STYLE = styleAttr([
+  `color:${token('textMuted')}`,
+  'font-size:12px',
+  'line-height:18px',
+  'padding:16px 8px 32px 8px',
+]);
+
+const UNSUBSCRIBE_STYLE = styleAttr([`color:${token('textMuted')}`, 'text-decoration:underline']);
+
+const TABLE_ATTRS = 'role="presentation" cellpadding="0" cellspacing="0" border="0"';
+
+/** The framework's only layout. Apps register their own with `registerLayout`. */
+export const baseLayout: MailLayout = (input) => `<!doctype html>
+<html lang="${escapeHtml(input.locale)}" dir="${input.direction}">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<meta http-equiv="x-ua-compatible" content="ie=edge">
+<meta name="color-scheme" content="light dark">
+<meta name="supported-color-schemes" content="light dark">
+<meta name="format-detection" content="telephone=no,date=no,address=no,email=no">
+<meta name="x-apple-disable-message-reformatting">
+<title>${escapeHtml(input.subject)}</title>
+<style>${darkModeCss()}</style>
+</head>
+<body ${BODY_STYLE} data-x="page">
+<div ${PREHEADER_STYLE}>${escapeHtml(input.preheader)}</div>
+<table ${TABLE_ATTRS} width="100%" data-x="page" ${PAGE_STYLE}>
+<tr><td align="center" ${GUTTER_STYLE}>
+<table ${TABLE_ATTRS} width="${MAIL_WIDTH_PX}" ${SHELL_STYLE}>
+<tr><td data-x="card" ${CARD_STYLE}>${input.content}</td></tr>
+<tr><td data-x="mut" ${FOOTER_STYLE}>${footerHtml(input)}</td></tr>
+</table>
+</td></tr>
+</table>
+</body>
+</html>`;
+
+function footerHtml(input: LayoutInput): string {
+  const lines = input.footer.map((line) => `<div>${escapeHtml(line)}</div>`);
+  const slot = input.unsubscribe;
+  if (slot !== undefined) {
+    const href = escapeHtml(safeUrl(slot.url));
+    const label = escapeHtml(slot.label);
+    lines.push(`<div><a data-x="a" href="${href}" ${UNSUBSCRIBE_STYLE}>${label}</a></div>`);
+  }
+  return lines.join('');
+}
+
+const layouts = new Map<string, MailLayout>([[BASE_LAYOUT, baseLayout]]);
+
+export function registerLayout(name: string, layout: MailLayout): void {
+  layouts.set(name, layout);
+}
+
+export function layoutFor(name: string): MailLayout | undefined {
+  return layouts.get(name);
+}
+
+export function registeredLayouts(): readonly string[] {
+  return [...layouts.keys()].sort();
+}

package/src/mail.d.ts

@@ -0,0 +1,67 @@
+import { type StandardSchemaV1 } from '@ultimat3/schema';
+import type { MailTemplate } from './blocks';
+import { type MailMessage, type SendResult } from './driver';
+import { type RenderableMail } from './render';
+export interface MailDefinition<I> extends RenderableMail<I> {
+    readonly id: string;
+    /** An i18n key, never a literal subject line. */
+    readonly subject: string;
+    readonly template: MailTemplate<I>;
+    readonly input: StandardSchemaV1<unknown, I>;
+    readonly layout: string;
+}
+export interface MailInit<I> {
+    readonly id: string;
+    readonly subject: string;
+    readonly template: MailTemplate<I>;
+    readonly input: StandardSchemaV1<unknown, I>;
+    /** Defaults to the framework's `base` layout. */
+    readonly layout?: string | undefined;
+}
+export interface SendOptions {
+    readonly to: string | readonly string[];
+    /** BCP-47. Required — there is no ambient fallback for a message the user reads later. */
+    readonly locale: string;
+    /** IANA zone for every date in the body. Defaults to the request context, then UTC. */
+    readonly tz?: string | undefined;
+    readonly replyTo?: string | undefined;
+    readonly cc?: readonly string[] | undefined;
+    readonly bcc?: readonly string[] | undefined;
+    readonly unsubscribeUrl?: string | undefined;
+    readonly idempotencyKey?: string | undefined;
+    /** Deliver inline instead of through the queue. Tests and CLI one-shots only. */
+    readonly sync?: boolean | undefined;
+}
+/**
+ * The registry erases the payload type so heterogeneous mails share one map. `template`
+ * stays assignable because `never` flows into any `TemplateArgs<I>`; `input` widens to
+ * `unknown` on the output side, which is exactly what `parse` re-establishes at send time.
+ */
+export interface AnyMailDefinition {
+    readonly id: string;
+    readonly subject: string;
+    readonly layout: string;
+    readonly input: StandardSchemaV1<unknown, unknown>;
+    readonly template: MailTemplate<never>;
+}
+export declare function defineMail<I>(init: MailInit<I>): MailDefinition<I>;
+export declare function mailFor(id: string): AnyMailDefinition | undefined;
+export declare function registeredMails(): readonly AnyMailDefinition[];
+export declare function registeredMailIds(): readonly string[];
+/** Test/CLI seam: drop every registered mail. */
+export declare function resetMails(): void;
+/**
+ * Validate, render, and build the envelope — everything `send` does before it decides
+ * between the queue and the transport. Exported so `x mail preview` and tests can render
+ * without delivering anything.
+ */
+export declare function renderMessage<I>(mail: MailDefinition<I>, data: I, options: SendOptions): MailMessage;
+/**
+ * Enqueues by default so a slow SMTP host never blocks a request. Falls back to an inline
+ * send when no job driver is configured (a script, a test, `x` one-shots) — the alternative
+ * would be silently dropping mail in exactly the setups where it is easiest to miss.
+ */
+export declare function send<I>(mail: MailDefinition<I>, data: I, options: SendOptions): Promise<SendResult>;
+/** Send by id — what the CLI, MCP tools and generated code use. `data` is parsed, not trusted. */
+export declare function sendById(id: string, data: unknown, options: SendOptions): Promise<SendResult>;
+//# sourceMappingURL=mail.d.ts.map

package/src/mail.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mail.d.ts","sourceRoot":"","sources":["mail.ts"],"names":[],"mappings":"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"}

package/src/mail.js

@@ -0,0 +1,119 @@
+// Single responsibility: the `defineMail` primitive, the mail registry, and `send`.
+// `locale` is required by the TYPE, not by a runtime check alone: an email in the wrong
+// language is a real, unnoticed production bug, and the ambient request locale is the one
+// piece of context that a background send cannot recover after the fact.
+import { assert, DEFAULT_TIME_ZONE, tryUseContext } from '@ultimat3/core';
+import { jobDriver } from '@ultimat3/jobs';
+import { parse } from '@ultimat3/schema';
+import { mailDriver } from './driver';
+import { localeMissing, mailDuplicate, templateUnknown } from './errors';
+import { mailIdempotencyKey, sendMailJob } from './job';
+import { BASE_LAYOUT } from './layout';
+import { renderMail } from './render';
+const registry = new Map();
+export function defineMail(init) {
+    if (registry.has(init.id))
+        throw mailDuplicate(init.id);
+    const definition = {
+        id: init.id,
+        subject: init.subject,
+        template: init.template,
+        input: init.input,
+        layout: init.layout ?? BASE_LAYOUT,
+    };
+    registry.set(init.id, definition);
+    return definition;
+}
+export function mailFor(id) {
+    return registry.get(id);
+}
+export function registeredMails() {
+    return [...registry.values()].sort((a, b) => a.id.localeCompare(b.id));
+}
+export function registeredMailIds() {
+    return [...registry.keys()].sort();
+}
+/** Test/CLI seam: drop every registered mail. */
+export function resetMails() {
+    registry.clear();
+}
+/**
+ * Validate, render, and build the envelope — everything `send` does before it decides
+ * between the queue and the transport. Exported so `x mail preview` and tests can render
+ * without delivering anything.
+ */
+export function renderMessage(mail, data, options) {
+    assertLocale(mail.id, options.locale);
+    if (registry.get(mail.id) === undefined)
+        throw templateUnknown(mail.id, registeredMailIds());
+    const to = typeof options.to === 'string' ? [options.to] : [...options.to];
+    assert(to.length > 0, `send(${mail.id}, ...) was called with an empty recipient list`, 'pass { to: user.email } — one address, or a non-empty array of addresses');
+    const input = parse(mail.input, data, `${mail.id}.input`);
+    const tz = options.tz ?? tryUseContext()?.tz ?? DEFAULT_TIME_ZONE;
+    const rendered = renderMail(mail, input, {
+        locale: options.locale,
+        tz,
+        unsubscribeUrl: options.unsubscribeUrl,
+    });
+    return {
+        mailId: mail.id,
+        to,
+        subject: rendered.subject,
+        html: rendered.html,
+        text: rendered.text,
+        locale: options.locale,
+        tz,
+        replyTo: options.replyTo,
+        cc: options.cc,
+        bcc: options.bcc,
+        unsubscribeUrl: options.unsubscribeUrl,
+        idempotencyKey: options.idempotencyKey,
+    };
+}
+/**
+ * Enqueues by default so a slow SMTP host never blocks a request. Falls back to an inline
+ * send when no job driver is configured (a script, a test, `x` one-shots) — the alternative
+ * would be silently dropping mail in exactly the setups where it is easiest to miss.
+ */
+export async function send(mail, data, options) {
+    const message = renderMessage(mail, data, options);
+    const key = mailIdempotencyKey(message);
+    const queue = jobDriver();
+    if (options.sync === true || queue === undefined) {
+        // The key is reported even inline, so a caller can dedupe its own retries either way.
+        return { ...(await mailDriver().send(message)), idempotencyKey: key };
+    }
+    const enqueued = await queue.enqueue({
+        name: sendMailJob.name,
+        queue: sendMailJob.queue,
+        input: message,
+        idempotencyKey: key,
+        maxAttempts: sendMailJob.retry.attempts,
+        onConflict: 'dedupe',
+    });
+    return {
+        id: enqueued.id,
+        driver: 'queue',
+        accepted: [...message.to, ...(message.cc ?? []), ...(message.bcc ?? [])],
+        queued: true,
+        idempotencyKey: key,
+    };
+}
+/** Send by id — what the CLI, MCP tools and generated code use. `data` is parsed, not trusted. */
+export async function sendById(id, data, options) {
+    const mail = registry.get(id);
+    if (mail === undefined)
+        throw templateUnknown(id, registeredMailIds());
+    // The one cast in the package: the registry erased `I`, and `send` re-parses `data`
+    // through the mail's own schema before it reaches the template.
+    return await send(mail, data, options);
+}
+/**
+ * The runtime backstop for JS callers and generated code — TypeScript already forbids
+ * omitting `locale`, so reaching this throw means the type was cast away somewhere.
+ */
+function assertLocale(mailId, locale) {
+    if (typeof locale !== 'string' || locale.trim() === '')
+        throw localeMissing(mailId);
+}
+//# sourceMappingURL=mail.js.map

package/src/mail.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mail.js","sourceRoot":"","sources":["mail.ts"],"names":[],"mappings":"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"}

package/src/mail.ts

@@ -0,0 +1,195 @@
+// Single responsibility: the `defineMail` primitive, the mail registry, and `send`.
+// `locale` is required by the TYPE, not by a runtime check alone: an email in the wrong
+// language is a real, unnoticed production bug, and the ambient request locale is the one
+// piece of context that a background send cannot recover after the fact.
+
+import { assert, DEFAULT_TIME_ZONE, tryUseContext } from '@ultimat3/core';
+import { jobDriver } from '@ultimat3/jobs';
+import { parse, type StandardSchemaV1 } from '@ultimat3/schema';
+import type { MailTemplate } from './blocks';
+import { type MailMessage, mailDriver, type SendResult } from './driver';
+import { localeMissing, mailDuplicate, templateUnknown } from './errors';
+import { mailIdempotencyKey } from './idempotency';
+import { sendMailJob } from './job';
+import { BASE_LAYOUT } from './layout';
+import { type RenderableMail, renderMail } from './render';
+
+export interface MailDefinition<I> extends RenderableMail<I> {
+  readonly id: string;
+  /** An i18n key, never a literal subject line. */
+  readonly subject: string;
+  readonly template: MailTemplate<I>;
+  readonly input: StandardSchemaV1<unknown, I>;
+  readonly layout: string;
+}
+
+export interface MailInit<I> {
+  readonly id: string;
+  readonly subject: string;
+  readonly template: MailTemplate<I>;
+  readonly input: StandardSchemaV1<unknown, I>;
+  /** Defaults to the framework's `base` layout. */
+  readonly layout?: string | undefined;
+}
+
+export interface SendOptions {
+  readonly to: string | readonly string[];
+  /** BCP-47. Required — there is no ambient fallback for a message the user reads later. */
+  readonly locale: string;
+  /** IANA zone for every date in the body. Defaults to the request context, then UTC. */
+  readonly tz?: string | undefined;
+  readonly replyTo?: string | undefined;
+  readonly cc?: readonly string[] | undefined;
+  readonly bcc?: readonly string[] | undefined;
+  readonly unsubscribeUrl?: string | undefined;
+  readonly idempotencyKey?: string | undefined;
+  /** Deliver inline instead of through the queue. Tests and CLI one-shots only. */
+  readonly sync?: boolean | undefined;
+}
+
+/**
+ * The registry erases the payload type so heterogeneous mails share one map. `template`
+ * stays assignable because `never` flows into any `TemplateArgs<I>`; `input` widens to
+ * `unknown` on the output side, which is exactly what `parse` re-establishes at send time.
+ */
+export interface AnyMailDefinition {
+  readonly id: string;
+  readonly subject: string;
+  readonly layout: string;
+  readonly input: StandardSchemaV1<unknown, unknown>;
+  readonly template: MailTemplate<never>;
+}
+
+const registry = new Map<string, AnyMailDefinition>();
+
+export function defineMail<I>(init: MailInit<I>): MailDefinition<I> {
+  if (registry.has(init.id)) throw mailDuplicate(init.id);
+  const definition: MailDefinition<I> = {
+    id: init.id,
+    subject: init.subject,
+    template: init.template,
+    input: init.input,
+    layout: init.layout ?? BASE_LAYOUT,
+  };
+  registry.set(init.id, definition);
+  return definition;
+}
+
+export function mailFor(id: string): AnyMailDefinition | undefined {
+  return registry.get(id);
+}
+
+export function registeredMails(): readonly AnyMailDefinition[] {
+  return [...registry.values()].sort((a, b) => a.id.localeCompare(b.id));
+}
+
+export function registeredMailIds(): readonly string[] {
+  return [...registry.keys()].sort();
+}
+
+/** Test/CLI seam: drop every registered mail. */
+export function resetMails(): void {
+  registry.clear();
+}
+
+/**
+ * Validate, render, and build the envelope — everything `send` does before it decides
+ * between the queue and the transport. Exported so `x mail preview` and tests can render
+ * without delivering anything.
+ */
+export function renderMessage<I>(
+  mail: MailDefinition<I>,
+  data: I,
+  options: SendOptions,
+): MailMessage {
+  assertLocale(mail.id, options.locale);
+  if (registry.get(mail.id) === undefined) throw templateUnknown(mail.id, registeredMailIds());
+
+  const to = typeof options.to === 'string' ? [options.to] : [...options.to];
+  assert(
+    to.length > 0,
+    `send(${mail.id}, ...) was called with an empty recipient list`,
+    'pass { to: user.email } — one address, or a non-empty array of addresses',
+  );
+
+  const input = parse(mail.input, data, `${mail.id}.input`);
+  const tz = options.tz ?? tryUseContext()?.tz ?? DEFAULT_TIME_ZONE;
+  const rendered = renderMail(mail, input, {
+    locale: options.locale,
+    tz,
+    unsubscribeUrl: options.unsubscribeUrl,
+  });
+
+  return {
+    mailId: mail.id,
+    to,
+    subject: rendered.subject,
+    html: rendered.html,
+    text: rendered.text,
+    locale: options.locale,
+    tz,
+    replyTo: options.replyTo,
+    cc: options.cc,
+    bcc: options.bcc,
+    unsubscribeUrl: options.unsubscribeUrl,
+    idempotencyKey: options.idempotencyKey,
+  };
+}
+
+/**
+ * Enqueues by default so a slow SMTP host never blocks a request. Falls back to an inline
+ * send when no job driver is configured (a script, a test, `x` one-shots) — the alternative
+ * would be silently dropping mail in exactly the setups where it is easiest to miss.
+ */
+export async function send<I>(
+  mail: MailDefinition<I>,
+  data: I,
+  options: SendOptions,
+): Promise<SendResult> {
+  const message = renderMessage(mail, data, options);
+  const key = mailIdempotencyKey(message);
+  const queue = jobDriver();
+
+  if (options.sync === true || queue === undefined) {
+    // The key is reported even inline, so a caller can dedupe its own retries either way.
+    return { ...(await mailDriver().send(message)), idempotencyKey: key };
+  }
+
+  const enqueued = await queue.enqueue({
+    name: sendMailJob.name,
+    queue: sendMailJob.queue,
+    input: message,
+    idempotencyKey: key,
+    maxAttempts: sendMailJob.retry.attempts,
+    onConflict: 'dedupe',
+  });
+
+  return {
+    id: enqueued.id,
+    driver: 'queue',
+    accepted: [...message.to, ...(message.cc ?? []), ...(message.bcc ?? [])],
+    queued: true,
+    idempotencyKey: key,
+  };
+}
+
+/** Send by id — what the CLI, MCP tools and generated code use. `data` is parsed, not trusted. */
+export async function sendById(
+  id: string,
+  data: unknown,
+  options: SendOptions,
+): Promise<SendResult> {
+  const mail = registry.get(id);
+  if (mail === undefined) throw templateUnknown(id, registeredMailIds());
+  // The one cast in the package: the registry erased `I`, and `send` re-parses `data`
+  // through the mail's own schema before it reaches the template.
+  return await send(mail as MailDefinition<unknown>, data, options);
+}
+
+/**
+ * The runtime backstop for JS callers and generated code — TypeScript already forbids
+ * omitting `locale`, so reaching this throw means the type was cast away somewhere.
+ */
+function assertLocale(mailId: string, locale: unknown): asserts locale is string {
+  if (typeof locale !== 'string' || locale.trim() === '') throw localeMissing(mailId);
+}