components/email/email.ts

Functions

Imports

It imports components/email/colours.ts. Imported by components/email/specimen/samples.ts.

Source

1// Email templates: one definition makes the HTML and the text, so the two cannot disagree.
2// Pure functions with no dependency, no filesystem and no fetch: they run in a Worker, in
3// Node and in a test. Every value that reaches the HTML is escaped here, and a template
4// author never writes markup. Colours are literal hexes from the family generator
5// (colours.ts), because mail clients ignore custom properties.
6import { emailColours, type EmailColours, type EmailFamily } from "./colours.ts";
7
8export type { EmailFamily };
9
10export interface Brand {
11  /** The product's name, set in type at the top of the mail. There is no logo image. */
12  name: string;
13  family: EmailFamily;
14}
15
16/** A line of the footer slot: plain text, or a text with a link (an unsubscribe link is the product's own). */
17export type FooterLine = string | { text: string; url: string };
18
19export type Block =
20  | { type: "heading"; text: string }
21  | { type: "paragraph"; text: string }
22  | { type: "button"; label: string; url: string }
23  | { type: "code"; text: string }
24  | { type: "note"; text: string; level?: AlertLevel }
25  | { type: "fine"; text: string };
26
27export type AlertLevel = "crit" | "warn" | "info";
28
29/** Wording a product may replace, per template. Strings only; escaped like any value. */
30export interface Copy {
31  subject?: string;
32  heading?: string;
33  intro?: string;
34  button?: string;
35  ignore?: string;
36}
37
38export interface Common {
39  brand: Brand;
40  /** Who the mail is for; the footer says it was sent to this address. */
41  to: string;
42  copy?: Copy;
43  footer?: FooterLine[];
44  /** The document's language. Default "en". */
45  lang?: string;
46}
47
48export interface Template<D> {
49  name: string;
50  subject(data: D & Common): string;
51  blocks(data: D & Common): Block[];
52}
53
54export interface Rendered {
55  subject: string;
56  html: string;
57  text: string;
58}
59
60// ---- escaping and links ------------------------------------------------------------------
61
62const ENTITIES: Record<string, string> = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" };
63
64export const escapeHtml = (value: string): string => value.replace(/[&<>"']/g, (c) => ENTITIES[c] ?? c);
65
66/** One line: line breaks and runs of space become one space, so a value cannot add a header or a line. */
67const oneLine = (value: string): string => value.replace(/\s+/g, " ").trim();
68
69/**
70 * A link is accepted only as https: or mailto:, with no space or control character in it and no
71 * user or password before the host, which would let `https://trusted.example@evil.example/` read as the trusted name.
72 * Anything else throws; the caller must not swallow it. The string comes back untouched, so
73 * a token in the address is never rewritten.
74 */
75export function checkUrl(url: string): string {
76  if (/[\u0000- \u007f-\u009f"<>\\^`{|}]/.test(url)) throw new Error("email: a link may not hold a space, a control character or any of \" < > \\ ^ ` { | }");
77  let parsed: URL;
78  try {
79    parsed = new URL(url);
80  } catch {
81    throw new Error("email: a link must be an absolute https: or mailto: address");
82  }
83  if (parsed.protocol !== "https:" && parsed.protocol !== "mailto:") throw new Error(`email: a link must be https: or mailto:, got ${parsed.protocol}`);
84  if (parsed.username || parsed.password) throw new Error("email: a link may not hold a user or password before the host");
85  return url;
86}
87
88// ---- the colours ---------------------------------------------------------------------------
89
90function coloursFor(family: EmailFamily): { light: EmailColours; dark: EmailColours } {
91  const c = emailColours[family];
92  if (!c) throw new Error(`email: unknown family "${String(family)}"`);
93  return c;
94}
95
96const LEVEL_WORD: Record<AlertLevel, string> = { crit: "Critical", warn: "Warning", info: "Notice" };
97const FONT = "-apple-system, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif";
98const MONO = "ui-monospace, SFMono-Regular, Menlo, Consolas, monospace";
99
100// ---- the frame -------------------------------------------------------------------------------
101
102function darkRules(d: EmailColours): string {
103  return [
104    `.e-ground{background-color:${d.ground} !important}`,
105    `.e-card{background-color:${d.surface} !important;border-color:${d.line} !important}`,
106    `.e-text{color:${d.text} !important}`,
107    `.e-muted{color:${d.muted} !important}`,
108    `.e-link{color:${d["accent-text"]} !important}`,
109    `.e-btn{background-color:${d.primary} !important;color:${d["primary-fg"]} !important}`,
110    `.e-rule{border-color:${d.line} !important}`,
111    ...(["crit", "warn", "info"] as const).map((l) => `.e-${l}{background-color:${d[`${l}-soft`]} !important;color:${d[l]} !important}`),
112  ].join("\n");
113}
114
115function blockHtml(b: Block, c: EmailColours): string {
116  const text = `font-family:${FONT};font-size:16px;line-height:24px;color:${c.text};`;
117  switch (b.type) {
118    case "heading":
119      return `<tr><td class="e-text" style="${text}font-size:22px;line-height:30px;font-weight:700;padding:0 0 16px 0;"><h1 style="margin:0;font-size:22px;line-height:30px;font-weight:700;">${escapeHtml(b.text)}</h1></td></tr>`;
120    case "paragraph":
121      return `<tr><td class="e-text" style="${text}padding:0 0 16px 0;">${escapeHtml(b.text)}</td></tr>`;
122    case "button": {
123      const url = escapeHtml(checkUrl(b.url));
124      return `<tr><td style="padding:8px 0 24px 0;"><a class="e-btn" href="${url}" style="display:inline-block;background-color:${c.primary};color:${c["primary-fg"]};font-family:${FONT};font-size:16px;line-height:20px;font-weight:600;text-decoration:none;padding:14px 24px;border-radius:6px;">${escapeHtml(b.label)}</a></td></tr>`;
125    }
126    case "code":
127      return `<tr><td class="e-text" style="${text}font-family:${MONO};font-size:20px;line-height:28px;letter-spacing:2px;font-weight:700;padding:0 0 16px 0;">${escapeHtml(b.text)}</td></tr>`;
128    case "note": {
129      const level = b.level;
130      const style = level ? `background-color:${c[`${level}-soft`]};color:${c[level]};` : `color:${c.text};`;
131      const word = level ? `<strong>${LEVEL_WORD[level]}.</strong> ` : "";
132      return `<tr><td style="padding:0 0 16px 0;"><div class="${level ? `e-${level}` : "e-text"}" style="${style}font-family:${FONT};font-size:16px;line-height:24px;padding:12px 16px;border-radius:6px;">${word}${escapeHtml(b.text)}</div></td></tr>`;
133    }
134    case "fine":
135      return `<tr><td class="e-muted" style="font-family:${FONT};font-size:16px;line-height:24px;color:${c.muted};padding:0 0 8px 0;">${escapeHtml(b.text)}</td></tr>`;
136  }
137}
138
139function footerHtml(lines: FooterLine[], c: EmailColours): string {
140  return lines
141    .map((l) => {
142      const style = `font-family:${FONT};font-size:14px;line-height:22px;color:${c.muted};padding:0 0 4px 0;`;
143      if (typeof l === "string") return `<tr><td class="e-muted" style="${style}">${escapeHtml(l)}</td></tr>`;
144      return `<tr><td class="e-muted" style="${style}"><a class="e-link" href="${escapeHtml(checkUrl(l.url))}" style="color:${c["accent-text"]};text-decoration:underline;">${escapeHtml(l.text)}</a></td></tr>`;
145    })
146    .join("\n");
147}
148
149function blockText(b: Block): string {
150  switch (b.type) {
151    case "heading":
152      return b.text;
153    case "button":
154      return `${b.label}:\n${checkUrl(b.url)}`;
155    case "code":
156      return `    ${b.text}`;
157    case "note":
158      return b.level ? `${LEVEL_WORD[b.level]}. ${b.text}` : b.text;
159    default:
160      return b.text;
161  }
162}
163
164/** Renders one template to a subject, an HTML part and a text part, from the same blocks. */
165export function renderEmail<D>(template: Template<D>, data: D & Common): Rendered {
166  const { brand, to } = data;
167  const colours = coloursFor(brand.family);
168  const c = colours.light;
169  const subject = oneLine(template.subject(data));
170  const blocks = template.blocks(data);
171  const footer: FooterLine[] = [`This message was sent to ${oneLine(to)}.`, ...(data.footer ?? [])];
172
173  const body = blocks.map((b) => blockHtml(b, c)).join("\n");
174  const html = `<!doctype html>
175<html lang="${escapeHtml(data.lang ?? "en")}">
176<head>
177<meta charset="utf-8">
178<meta name="viewport" content="width=device-width, initial-scale=1">
179<meta name="color-scheme" content="light dark">
180<meta name="supported-color-schemes" content="light dark">
181<title>${escapeHtml(subject)}</title>
182<style>
183:root{color-scheme:light dark;supported-color-schemes:light dark}
184@media (prefers-color-scheme: dark){
185${darkRules(colours.dark)}
186}
187</style>
188</head>
189<body class="e-ground" style="margin:0;padding:0;background-color:${c.ground};">
190<table role="presentation" class="e-ground" width="100%" cellpadding="0" cellspacing="0" border="0" style="background-color:${c.ground};">
191<tr><td align="center" style="padding:24px 12px;">
192<table role="presentation" width="600" cellpadding="0" cellspacing="0" border="0" style="width:100%;max-width:600px;">
193<tr><td class="e-text" style="font-family:${FONT};font-size:18px;line-height:24px;font-weight:700;color:${c.text};padding:0 4px 16px 4px;">${escapeHtml(oneLine(brand.name))}</td></tr>
194<tr><td>
195<table role="presentation" class="e-card" width="100%" cellpadding="0" cellspacing="0" border="0" style="background-color:${c.surface};border:1px solid ${c.line};border-radius:8px;">
196<tr><td style="padding:28px 24px 12px 24px;">
197<table role="presentation" width="100%" cellpadding="0" cellspacing="0" border="0">
198${body}
199</table>
200</td></tr>
201</table>
202</td></tr>
203<tr><td style="padding:16px 4px 0 4px;">
204<table role="presentation" width="100%" cellpadding="0" cellspacing="0" border="0">
205${footerHtml(footer, c)}
206</table>
207</td></tr>
208</table>
209</td></tr>
210</table>
211</body>
212</html>
213`;
214
215  const textFooter = footer.map((l) => (typeof l === "string" ? l : `${l.text}: ${checkUrl(l.url)}`));
216  const text = `${oneLine(brand.name)}\n\n${blocks.map(blockText).join("\n\n")}\n\n--\n${textFooter.join("\n")}\n`;
217  return { subject, html, text };
218}
219
220// ---- the templates ---------------------------------------------------------------------------
221
222interface LinkData {
223  url: string;
224  /** How long the link works, in words: "15 minutes". */
225  expiresIn: string;
226}
227
228const linkBlocks = (d: LinkData & Common, defaults: { heading: string; intro: string; button: string; ignore: string }): Block[] => {
229  const k = d.copy ?? {};
230  return [
231    { type: "heading", text: k.heading ?? defaults.heading },
232    { type: "paragraph", text: k.intro ?? defaults.intro },
233    { type: "button", label: k.button ?? defaults.button, url: d.url },
234    { type: "fine", text: `The link works once and expires in ${d.expiresIn}.` },
235    { type: "fine", text: k.ignore ?? defaults.ignore },
236  ];
237};
238
239/** Sign in with one link. */
240export const magicLink: Template<LinkData> = {
241  name: "magic-link",
242  subject: (d) => d.copy?.subject ?? `Your sign-in link for ${d.brand.name}`,
243  blocks: (d) =>
244    linkBlocks(d, {
245      heading: `Sign in to ${d.brand.name}`,
246      intro: `Someone asked to sign in to ${d.brand.name} as ${d.to}. Use the button to finish.`,
247      button: "Sign in",
248      ignore: "If this was not you, ignore this message. Nothing happens unless the link is used.",
249    }),
250};
251
252/** Confirm an address. */
253export const verification: Template<LinkData> = {
254  name: "verification",
255  subject: (d) => d.copy?.subject ?? `Confirm your email address for ${d.brand.name}`,
256  blocks: (d) =>
257    linkBlocks(d, {
258      heading: "Confirm your email address",
259      intro: `Someone used ${d.to} to register with ${d.brand.name}. Confirm the address to finish.`,
260      button: "Confirm email address",
261      ignore: "If this was not you, ignore this message. The address stays unconfirmed.",
262    }),
263};
264
265/** Reset a password. */
266export const reset: Template<LinkData> = {
267  name: "reset",
268  subject: (d) => d.copy?.subject ?? `Reset your ${d.brand.name} password`,
269  blocks: (d) =>
270    linkBlocks(d, {
271      heading: "Reset your password",
272      intro: `Someone asked to reset the password for ${d.to} on ${d.brand.name}. Use the button to choose a new one.`,
273      button: "Reset password",
274      ignore: "If this was not you, ignore this message. Your password has not changed.",
275    }),
276};
277
278/** Something needs attention: a health check, a watchdog, a budget. The level is a word, never colour alone. */
279export const alert: Template<{ level: AlertLevel; what: string; when: string; details?: string[]; url?: string }> = {
280  name: "alert",
281  subject: (d) => d.copy?.subject ?? `${LEVEL_WORD[d.level]}: ${d.what}`,
282  blocks: (d) => {
283    const k = d.copy ?? {};
284    const out: Block[] = [
285      { type: "heading", text: k.heading ?? d.what },
286      { type: "note", level: d.level, text: k.intro ?? `${d.what} at ${d.when}.` },
287      ...(d.details ?? []).map((text): Block => ({ type: "paragraph", text })),
288    ];
289    if (d.url) out.push({ type: "button", label: k.button ?? "Open", url: d.url });
290    return out;
291  },
292};
293
294/** A plain message: a decision, a digest line, a change of terms. */
295export const notice: Template<{ title: string; body: string[]; action?: { label: string; url: string } }> = {
296  name: "notice",
297  subject: (d) => d.copy?.subject ?? d.title,
298  blocks: (d) => {
299    const k = d.copy ?? {};
300    const out: Block[] = [
301      { type: "heading", text: k.heading ?? d.title },
302      ...(k.intro === undefined ? d.body : [k.intro, ...d.body.slice(1)]).map((text): Block => ({ type: "paragraph", text })),
303    ];
304    if (d.action) out.push({ type: "button", label: k.button ?? d.action.label, url: d.action.url });
305    return out;
306  },
307};