Reorganize repo structure and standards references

This commit is contained in:
david committed 2026-06-29 05:03:42 +02:00
1 parent 3cb93a81be
commit be2054274d
5885 files changed
+2588 -195

No files matched your search

@@ -0,0 +1,73 @@
import type { CSSProperties, ReactNode } from "react";
import { Header } from "./Header.js";
import { Footer } from "./Footer.js";
import type { MailBrand } from "./theme.js";
/**
* BaseLayout — root layout for transactional emails. Renders a 560px
* centred card with brand-themed header and footer, plus a hidden
* preview-text harvested by Gmail/Apple Mail as the inbox snippet.
*/
export interface BaseLayoutProps {
readonly brand: MailBrand;
readonly title: string;
readonly previewText?: string;
readonly unsubscribeUrl?: string;
readonly children: ReactNode;
}
const bodyStyle = (brand: MailBrand): CSSProperties => ({
margin: 0,
padding: 0,
backgroundColor: brand.backgroundColor,
color: brand.textColor,
fontFamily: brand.fontFamily,
fontSize: "16px",
lineHeight: "1.5",
});
const containerStyle: CSSProperties = {
width: "100%",
maxWidth: "560px",
margin: "0 auto",
padding: "24px 16px",
};
const cardStyle = (brand: MailBrand): CSSProperties => ({
backgroundColor: brand.surfaceColor,
border: `1px solid ${brand.borderColor}`,
borderRadius: "20px",
padding: "32px",
});
const previewStyle: CSSProperties = {
display: "none",
fontSize: "1px",
lineHeight: "1px",
maxHeight: 0,
maxWidth: 0,
opacity: 0,
overflow: "hidden",
} as CSSProperties;
export function BaseLayout({ brand, title, previewText, unsubscribeUrl, children }: BaseLayoutProps) {
return (
<html lang="en">
<head>
<meta charSet="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>{title}</title>
</head>
<body style={bodyStyle(brand)}>
{previewText ? <div style={previewStyle}>{previewText}</div> : null}
<div style={containerStyle}>
<div style={cardStyle(brand)}>
<Header brand={brand} />
{children}
<Footer brand={brand} unsubscribeUrl={unsubscribeUrl} />
</div>
</div>
</body>
</html>
);
}
@@ -0,0 +1,53 @@
import type { CSSProperties, ReactNode } from "react";
import type { MailBrand } from "./theme.js";
/**
* Button — CTA-Button with brand-color theming. Validates href as
* https:// or mailto: to block javascript:/data: URL injection
* (magic-link phishing class).
*/
export interface ButtonProps {
readonly href: string;
readonly brand: MailBrand;
readonly children: ReactNode;
}
const ALLOWED_PROTOCOLS = ["https:", "mailto:"] as const;
export class InvalidActionUrlError extends Error {
constructor(public readonly url: string) {
super(`Refusing to render unsafe action URL: ${url}. Only https:// and mailto: are allowed.`);
this.name = "InvalidActionUrlError";
}
}
export function assertSafeUrl(url: string): void {
let parsed: URL;
try {
parsed = new URL(url);
} catch {
throw new InvalidActionUrlError(url);
}
if (!ALLOWED_PROTOCOLS.includes(parsed.protocol as (typeof ALLOWED_PROTOCOLS)[number])) {
throw new InvalidActionUrlError(url);
}
}
export function Button({ href, brand, children }: ButtonProps) {
assertSafeUrl(href);
const style: CSSProperties = {
display: "inline-block",
backgroundColor: brand.primaryColor,
color: brand.primaryTextColor,
padding: "12px 22px",
borderRadius: "999px",
fontWeight: 700,
fontSize: "15px",
textDecoration: "none",
};
return (
<a href={href} style={style} target="_blank" rel="noopener noreferrer">
{children}
</a>
);
}
@@ -0,0 +1,24 @@
import type { CSSProperties } from "react";
import type { MailBrand } from "./theme.js";
/**
* Eyebrow — small uppercase label rendered above the main heading.
* Used to communicate category (e.g. "Welcome", "Password reset").
*/
export interface EyebrowProps {
readonly brand: MailBrand;
readonly children: string;
}
const style = (brand: MailBrand): CSSProperties => ({
color: brand.mutedTextColor,
fontSize: "13px",
fontWeight: 700,
letterSpacing: "0.08em",
textTransform: "uppercase",
marginBottom: "8px",
});
export function Eyebrow({ brand, children }: EyebrowProps) {
return <div style={style(brand)}>{children}</div>;
}
@@ -0,0 +1,66 @@
import type { CSSProperties } from "react";
import type { MailBrand } from "./theme.js";
/**
* Footer — legal links (privacy, terms, imprint) and support contact.
* Required for DSGVO/CAN-SPAM compliance.
*/
export interface FooterProps {
readonly brand: MailBrand;
readonly unsubscribeUrl?: string;
}
const wrapperStyle: CSSProperties = {
marginTop: "24px",
paddingTop: "16px",
borderTop: "1px solid",
fontSize: "12px",
lineHeight: "1.5",
};
const linkStyle = (color: string): CSSProperties => ({
textDecoration: "underline",
color,
});
export function Footer({ brand, unsubscribeUrl }: FooterProps) {
return (
<div style={{ ...wrapperStyle, borderTopColor: brand.borderColor, color: brand.mutedTextColor }}>
<div>
{brand.privacyUrl ? (
<a href={brand.privacyUrl} style={linkStyle(brand.linkColor)}>
Privacy
</a>
) : null}
{brand.privacyUrl && brand.termsUrl ? <span style={{ margin: "0 6px" }}>·</span> : null}
{brand.termsUrl ? (
<a href={brand.termsUrl} style={linkStyle(brand.linkColor)}>
Terms
</a>
) : null}
{(brand.privacyUrl || brand.termsUrl) && brand.imprintUrl ? (
<span style={{ margin: "0 6px" }}>·</span>
) : null}
{brand.imprintUrl ? (
<a href={brand.imprintUrl} style={linkStyle(brand.linkColor)}>
Imprint
</a>
) : null}
</div>
{unsubscribeUrl ? (
<div style={{ marginTop: "8px" }}>
<a href={unsubscribeUrl} style={linkStyle(brand.linkColor)}>
Unsubscribe
</a>
</div>
) : null}
<div style={{ marginTop: "8px" }}>
Questions? Email us at{" "}
<a href={`mailto:${brand.supportEmail}`} style={linkStyle(brand.linkColor)}>
{brand.supportEmail}
</a>
.
</div>
</div>
);
}
@@ -0,0 +1,42 @@
import type { CSSProperties } from "react";
import type { MailBrand } from "./theme.js";
/**
* Header — brand logo (if configured) or product-name wordmark.
* Stays inline-styled to survive Outlook/Gmail HTML scrubbers.
*/
export interface HeaderProps {
readonly brand: MailBrand;
}
const headerStyle: CSSProperties = {
paddingBottom: "16px",
textAlign: "left",
};
const logoStyle: CSSProperties = {
display: "block",
border: 0,
borderRadius: "12px",
};
export function Header({ brand }: HeaderProps) {
if (brand.logoUrl) {
return (
<div style={headerStyle}>
<img
src={brand.logoUrl}
alt={brand.productName}
width={48}
height={48}
style={logoStyle}
/>
</div>
);
}
return (
<div style={headerStyle}>
<strong style={{ color: brand.textColor, fontSize: "18px" }}>{brand.productName}</strong>
</div>
);
}
@@ -0,0 +1,28 @@
import type { CSSProperties, ReactNode } from "react";
import type { MailBrand } from "./theme.js";
/**
* InfoBox — boxed section for important notices (e.g. "this link expires
* in 15 minutes", "if you didn't request this, ignore the email").
*/
export interface InfoBoxProps {
readonly brand: MailBrand;
readonly tone?: "info" | "warning";
readonly children: ReactNode;
}
const baseStyle: CSSProperties = {
marginTop: "20px",
padding: "14px 16px",
borderRadius: "10px",
fontSize: "14px",
lineHeight: "1.55",
};
export function InfoBox({ brand, tone = "info", children }: InfoBoxProps) {
const style: CSSProperties =
tone === "warning"
? { ...baseStyle, backgroundColor: "#fef3c7", color: "#92400e", border: "1px solid #fde68a" }
: { ...baseStyle, backgroundColor: "#f1f5f9", color: brand.textColor, border: `1px solid ${brand.borderColor}` };
return <div style={style}>{children}</div>;
}
@@ -0,0 +1,14 @@
// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
exports[`BaseLayout > applies tenant brand overrides (logo + primary color) 1`] = `"<!DOCTYPE html><html lang="en"><head><meta charSet="utf-8"/><meta name="viewport" content="width=device-width, initial-scale=1"/><link rel="preload" as="image" href="https://cdn.acme.test/logo.png"/><title>Hi</title></head><body style="margin:0;padding:0;background-color:#f4f5f7;color:#0f172a;font-family:ui-sans-serif, -apple-system, BlinkMacSystemFont, &#x27;Segoe UI&#x27;, Roboto, &#x27;Helvetica Neue&#x27;, Arial, sans-serif;font-size:16px;line-height:1.5"><div style="display:none;font-size:1px;line-height:1px;max-height:0;max-width:0;opacity:0;overflow:hidden">snippet</div><div style="width:100%;max-width:560px;margin:0 auto;padding:24px 16px"><div style="background-color:#ffffff;border:1px solid #e2e8f0;border-radius:20px;padding:32px"><div style="padding-bottom:16px;text-align:left"><img src="https://cdn.acme.test/logo.png" alt="Acme" width="48" height="48" style="display:block;border:0;border-radius:12px"/></div><p>Body</p><div style="margin-top:24px;padding-top:16px;border-top:1px solid;font-size:12px;line-height:1.5;border-top-color:#e2e8f0;color:#475569"><div><a href="https://tool-ctrl.de/privacy" style="text-decoration:underline;color:#2563eb">Privacy</a><span style="margin:0 6px">·</span><a href="https://tool-ctrl.de/terms" style="text-decoration:underline;color:#2563eb">Terms</a><span style="margin:0 6px">·</span><a href="https://tool-ctrl.de/imprint" style="text-decoration:underline;color:#2563eb">Imprint</a></div><div style="margin-top:8px">Questions? Email us at <a href="mailto:info@tool-ctrl.de" style="text-decoration:underline;color:#2563eb">info@tool-ctrl.de</a>.</div></div></div></div></body></html>"`;
exports[`BaseLayout > renders default-brand snapshot 1`] = `"<!DOCTYPE html><html lang="en"><head><meta charSet="utf-8"/><meta name="viewport" content="width=device-width, initial-scale=1"/><title>Hello</title></head><body style="margin:0;padding:0;background-color:#f4f5f7;color:#0f172a;font-family:ui-sans-serif, -apple-system, BlinkMacSystemFont, &#x27;Segoe UI&#x27;, Roboto, &#x27;Helvetica Neue&#x27;, Arial, sans-serif;font-size:16px;line-height:1.5"><div style="display:none;font-size:1px;line-height:1px;max-height:0;max-width:0;opacity:0;overflow:hidden">A preview</div><div style="width:100%;max-width:560px;margin:0 auto;padding:24px 16px"><div style="background-color:#ffffff;border:1px solid #e2e8f0;border-radius:20px;padding:32px"><div style="padding-bottom:16px;text-align:left"><strong style="color:#0f172a;font-size:18px">ToolCTRL</strong></div><div style="color:#475569;font-size:13px;font-weight:700;letter-spacing:0.08em;text-transform:uppercase;margin-bottom:8px">Eyebrow</div><h1>Title</h1><div style="margin-top:24px;padding-top:16px;border-top:1px solid;font-size:12px;line-height:1.5;border-top-color:#e2e8f0;color:#475569"><div><a href="https://tool-ctrl.de/privacy" style="text-decoration:underline;color:#2563eb">Privacy</a><span style="margin:0 6px">·</span><a href="https://tool-ctrl.de/terms" style="text-decoration:underline;color:#2563eb">Terms</a><span style="margin:0 6px">·</span><a href="https://tool-ctrl.de/imprint" style="text-decoration:underline;color:#2563eb">Imprint</a></div><div style="margin-top:8px">Questions? Email us at <a href="mailto:info@tool-ctrl.de" style="text-decoration:underline;color:#2563eb">info@tool-ctrl.de</a>.</div></div></div></div></body></html>"`;
exports[`BaseLayout > renders default-brand snapshot 2`] = `
"A preview
ToolCTRL
Eyebrow
Title
Privacy (https://tool-ctrl.de/privacy)·Terms (https://tool-ctrl.de/terms)·Imprint (https://tool-ctrl.de/imprint)
Questions? Email us at info@tool-ctrl.de (mailto:info@tool-ctrl.de)."
`;
@@ -0,0 +1,7 @@
export { BaseLayout, type BaseLayoutProps } from "./BaseLayout.js";
export { Header, type HeaderProps } from "./Header.js";
export { Footer, type FooterProps } from "./Footer.js";
export { Button, InvalidActionUrlError, assertSafeUrl, type ButtonProps } from "./Button.js";
export { InfoBox, type InfoBoxProps } from "./InfoBox.js";
export { Eyebrow, type EyebrowProps } from "./Eyebrow.js";
export { defaultMailBrand, withBrandDefaults, type MailBrand } from "./theme.js";
@@ -0,0 +1,98 @@
import { describe, expect, test } from "vitest";
import { renderReactEmail } from "../render-helpers.js";
import { BaseLayout } from "./BaseLayout.js";
import { Button, InvalidActionUrlError } from "./Button.js";
import { Eyebrow } from "./Eyebrow.js";
import { InfoBox } from "./InfoBox.js";
import { defaultMailBrand, withBrandDefaults } from "./theme.js";
describe("BaseLayout", () => {
test("renders default-brand snapshot", () => {
const result = renderReactEmail(
<BaseLayout brand={defaultMailBrand} title="Hello" previewText="A preview">
<Eyebrow brand={defaultMailBrand}>Eyebrow</Eyebrow>
<h1>Title</h1>
</BaseLayout>
);
expect(result.html).toMatchSnapshot();
expect(result.text).toMatchSnapshot();
});
test("applies tenant brand overrides (logo + primary color)", () => {
const brand = withBrandDefaults({
productName: "Acme",
logoUrl: "https://cdn.acme.test/logo.png",
primaryColor: "#123456",
tenantName: "Acme Inc",
});
const result = renderReactEmail(
<BaseLayout brand={brand} title="Hi" previewText="snippet">
<p>Body</p>
</BaseLayout>
);
expect(result.html).toContain("https://cdn.acme.test/logo.png");
expect(result.html).toContain("Acme");
expect(result.html).toMatchSnapshot();
});
});
describe("Button safety", () => {
test("renders https CTA", () => {
const { html } = renderReactEmail(
<Button brand={defaultMailBrand} href="https://example.com/go">
Go
</Button>
);
expect(html).toContain('href="https://example.com/go"');
});
test("allows mailto: CTA", () => {
const { html } = renderReactEmail(
<Button brand={defaultMailBrand} href="mailto:hi@example.com">
Mail
</Button>
);
expect(html).toContain('href="mailto:hi@example.com"');
});
test.each(["javascript:alert(1)", "http://insecure.test", "data:text/html,<script>", "not a url"])(
"rejects unsafe href %s",
(href) => {
expect(() =>
renderReactEmail(
<Button brand={defaultMailBrand} href={href}>
X
</Button>
)
).toThrow(InvalidActionUrlError);
}
);
});
describe("InfoBox", () => {
test("renders info tone", () => {
const { html } = renderReactEmail(
<InfoBox brand={defaultMailBrand}>Note</InfoBox>
);
expect(html).toContain("Note");
});
test("renders warning tone with accent palette", () => {
const { html } = renderReactEmail(
<InfoBox brand={defaultMailBrand} tone="warning">
Heads up
</InfoBox>
);
expect(html).toContain("Heads up");
expect(html).toMatch(/#fef3c7/i);
});
});
describe("Eyebrow", () => {
test("uppercases via CSS, not value", () => {
const { html } = renderReactEmail(<Eyebrow brand={defaultMailBrand}>welcome</Eyebrow>);
// The visible text is unchanged; transform happens via CSS.
expect(html).toContain(">welcome<");
expect(html).toContain("text-transform:uppercase");
});
});
@@ -0,0 +1,51 @@
/**
* Default brand-theme tokens for React-Email transactional templates.
*
* Templates accept a `brand` prop derived from `@toolctrl/brand`'s
* `BrandTokens`. When undefined we fall back to these defaults so
* preview/storybook renders stay deterministic regardless of tenant
* configuration. Keep this aligned with `packages/brand/src/index.ts`.
*/
export interface MailBrand {
readonly productName: string;
readonly logoUrl?: string;
readonly primaryColor: string;
readonly primaryTextColor: string;
readonly textColor: string;
readonly mutedTextColor: string;
readonly backgroundColor: string;
readonly surfaceColor: string;
readonly borderColor: string;
readonly linkColor: string;
readonly fontFamily: string;
readonly supportEmail: string;
readonly supportFromName: string;
readonly privacyUrl?: string;
readonly termsUrl?: string;
readonly imprintUrl?: string;
readonly tenantName?: string;
}
export const defaultMailBrand: MailBrand = {
productName: "ToolCTRL",
primaryColor: "#2563eb",
primaryTextColor: "#ffffff",
textColor: "#0f172a",
mutedTextColor: "#475569",
backgroundColor: "#f4f5f7",
surfaceColor: "#ffffff",
borderColor: "#e2e8f0",
linkColor: "#2563eb",
fontFamily:
"ui-sans-serif, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif",
supportEmail: "info@tool-ctrl.de",
supportFromName: "ToolCTRL Support",
privacyUrl: "https://tool-ctrl.de/privacy",
termsUrl: "https://tool-ctrl.de/terms",
imprintUrl: "https://tool-ctrl.de/imprint",
} as const;
export function withBrandDefaults(override?: Partial<MailBrand>): MailBrand {
if (!override) return defaultMailBrand;
return { ...defaultMailBrand, ...override };
}
@@ -0,0 +1,28 @@
import { describe, expect, test } from "vitest";
import { htmlToPlainText } from "./render-helpers.js";
describe("htmlToPlainText", () => {
test("preserves anchor labels with hrefs for text-mode email clients", () => {
const text = htmlToPlainText(
'<p>Hello Ada,</p><p><a href="https://app.example.com/invite"><strong>Join workspace</strong></a></p>'
);
expect(text).toBe("Hello Ada,\nJoin workspace (https://app.example.com/invite)");
});
test("removes non-body markup and decodes common entities deterministically", () => {
const text = htmlToPlainText(
[
"<head><title>Ignored</title></head>",
"<style>.hidden { display: none; }</style>",
'<script>alert("ignored")</script>',
"<div>ToolCTRL&nbsp;&amp;&nbsp;friends</div>",
"<div>&lt;safe&gt; &#39;quoted&#39; &quot;copy&quot;</div>",
"<br><p>Done</p>",
].join("")
);
expect(text).toBe("ToolCTRL & friends\n<safe> 'quoted' \"copy\"\n\nDone");
});
});
@@ -0,0 +1,54 @@
/**
* Internal render helpers for React-Email transactional templates.
*
* Uses `react-dom/server.renderToStaticMarkup` for deterministic
* SSR output and a small HTML-to-text fallback so we emit a clean
* plain-text alternative without pulling in the full `@react-email/render`
* runtime (which inflates worker images by ~60MB and pins a different
* react-version). See `docs/architecture/email-templates.md`.
*/
import type { ReactElement } from "react";
import { renderToStaticMarkup } from "react-dom/server";
export interface RenderedEmail {
readonly html: string;
readonly text: string;
}
/**
* Convert rendered HTML to a plain-text fallback. Preserves anchor URLs
* as `label (url)` so text-mode clients still get the CTA target.
*/
export function htmlToPlainText(html: string): string {
const withAnchorUrls = html.replace(
/<a\s+[^>]*href="([^"]+)"[^>]*>([\s\S]*?)<\/a>/giu,
(_, href: string, label: string) => `${label.replace(/<[^>]+>/gu, "").trim()} (${href})`
);
return withAnchorUrls
.replace(/<style[\s\S]*?<\/style>/giu, "")
.replace(/<script[\s\S]*?<\/script>/giu, "")
.replace(/<head[\s\S]*?<\/head>/giu, "")
.replace(/<br\s*\/?>(\r?\n)?/giu, "\n")
.replace(/<\/(p|h1|h2|h3|li|div|tr)>/giu, "\n")
.replace(/<[^>]+>/gu, "")
.replace(/&nbsp;/giu, " ")
.replace(/&amp;/giu, "&")
.replace(/&lt;/giu, "<")
.replace(/&gt;/giu, ">")
.replace(/&#39;/giu, "'")
.replace(/&quot;/giu, '"')
.replace(/[ \t]+\n/gu, "\n")
.replace(/\n{3,}/gu, "\n\n")
.trim();
}
/**
* Render a React element to `{ html, text }`. The HTML is prefixed with
* a DOCTYPE so mail clients render in standards mode.
*/
export function renderReactEmail(element: ReactElement): RenderedEmail {
const body = renderToStaticMarkup(element);
const html = `<!DOCTYPE html>${body}`;
const text = htmlToPlainText(body);
return { html, text };
}
@@ -0,0 +1,59 @@
import { describe, expect, test } from "vitest";
import {
reactTransactionalTemplateNames,
renderTransactionalEmail,
withBrandDefaults,
} from "./render.js";
const brand = withBrandDefaults();
describe("renderTransactionalEmail", () => {
test("exposes all 8 template names", () => {
const names = reactTransactionalTemplateNames();
expect(names).toEqual([
"welcome",
"magic-link",
"password-reset",
"invitation",
"subscription-success",
"subscription-failed",
"invoice-sent",
"tenant-notification",
]);
});
test("renders welcome via dispatch", () => {
const result = renderTransactionalEmail("welcome", {
brand,
recipientName: "Ada",
actionUrl: "https://app.example.com/login",
});
expect(result.html).toContain("Welcome to ToolCTRL, Ada!");
expect(result.text).toContain("Welcome to ToolCTRL, Ada!");
});
test("renders invitation via dispatch", () => {
const result = renderTransactionalEmail("invitation", {
brand,
senderName: "Grace",
senderOrganization: "Example Org",
actionUrl: "https://app.example.com/invite",
});
expect(result.html).toContain("Grace invited you to ToolCTRL");
expect(result.text).toContain("Join Example Org");
});
test("throws on unknown template", () => {
expect(() =>
renderTransactionalEmail("unknown" as Parameters<typeof renderTransactionalEmail>[0], {} as never)
).toThrow(/Unknown React transactional template/);
});
test("returns html with <!DOCTYPE html> prefix for SSR mode", () => {
const { html } = renderTransactionalEmail("welcome", {
brand,
actionUrl: "https://app.example.com/login",
});
expect(html.startsWith("<!DOCTYPE html>")).toBe(true);
});
});
@@ -0,0 +1,95 @@
/**
* Public entry-point for React-Email transactional templates.
*
* Dispatches a template-name plus props to the matching React component
* and renders `{ html, text }` deterministically via react-dom/server.
* The canonical entry-point for transactional mail rendering. Called
* directly from the host application's mail wrapper (see
* `apps/web/app/modules/emails/utils/EmailTemplates.ts`).
*
* Each entry intentionally accepts a small, explicit prop shape — we
* do not pipe arbitrary objects into the templates, so a malicious
* caller cannot inject extra React props.
*/
import { createElement, type ReactElement } from "react";
import { renderReactEmail } from "./render-helpers.js";
import { withBrandDefaults, type MailBrand } from "./_layout/theme.js";
import { WelcomeEmail, type WelcomeEmailProps } from "./transactional/Welcome.js";
import { MagicLinkEmail, type MagicLinkEmailProps } from "./transactional/MagicLink.js";
import { PasswordResetEmail, type PasswordResetEmailProps } from "./transactional/PasswordReset.js";
import { InvitationEmail, type InvitationEmailProps } from "./transactional/Invitation.js";
import {
SubscriptionSuccessEmail,
type SubscriptionSuccessEmailProps,
} from "./transactional/SubscriptionSuccess.js";
import {
SubscriptionFailedEmail,
type SubscriptionFailedEmailProps,
} from "./transactional/SubscriptionFailed.js";
import { InvoiceSentEmail, type InvoiceSentEmailProps } from "./transactional/InvoiceSent.js";
import { TenantNotificationEmail, type TenantNotificationEmailProps } from "./transactional/TenantNotification.js";
export type ReactTransactionalTemplateName =
| "welcome"
| "magic-link"
| "password-reset"
| "invitation"
| "subscription-success"
| "subscription-failed"
| "invoice-sent"
| "tenant-notification";
export type ReactTemplatePropsMap = {
welcome: WelcomeEmailProps;
"magic-link": MagicLinkEmailProps;
"password-reset": PasswordResetEmailProps;
invitation: InvitationEmailProps;
"subscription-success": SubscriptionSuccessEmailProps;
"subscription-failed": SubscriptionFailedEmailProps;
"invoice-sent": InvoiceSentEmailProps;
"tenant-notification": TenantNotificationEmailProps;
};
export interface RenderedReactEmail {
readonly html: string;
readonly text: string;
}
type AnyTemplateProps = ReactTemplatePropsMap[ReactTransactionalTemplateName];
const COMPONENTS: { [K in ReactTransactionalTemplateName]: (props: ReactTemplatePropsMap[K]) => ReactElement } = {
welcome: WelcomeEmail,
"magic-link": MagicLinkEmail,
"password-reset": PasswordResetEmail,
invitation: InvitationEmail,
"subscription-success": SubscriptionSuccessEmail,
"subscription-failed": SubscriptionFailedEmail,
"invoice-sent": InvoiceSentEmail,
"tenant-notification": TenantNotificationEmail,
};
export function renderTransactionalEmail<K extends ReactTransactionalTemplateName>(
template: K,
props: ReactTemplatePropsMap[K]
): RenderedReactEmail {
const component = COMPONENTS[template] as (p: AnyTemplateProps) => ReactElement;
if (!component) {
throw new Error(`Unknown React transactional template: ${template}`);
}
const element = createElement<AnyTemplateProps>(
component as (p: AnyTemplateProps) => ReactElement,
props as AnyTemplateProps
);
return renderReactEmail(element);
}
export function reactTransactionalTemplateNames(): readonly ReactTransactionalTemplateName[] {
return Object.keys(COMPONENTS) as ReactTransactionalTemplateName[];
}
export function buildBrand(override?: Partial<MailBrand>): MailBrand {
return withBrandDefaults(override);
}
export { withBrandDefaults, defaultMailBrand } from "./_layout/theme.js";
export type { MailBrand } from "./_layout/theme.js";
@@ -0,0 +1,55 @@
import { describe, expect, test } from "vitest";
import { renderReactEmail } from "../render-helpers.js";
import { defaultMailBrand, withBrandDefaults } from "../_layout/theme.js";
import { InvitationEmail } from "./Invitation.js";
describe("InvitationEmail", () => {
test("renders default snapshot", () => {
const result = renderReactEmail(
<InvitationEmail
brand={defaultMailBrand}
recipientName="Ada"
senderName="Grace"
senderOrganization="Example Org"
actionUrl="https://app.example.com/invite/abc"
/>
);
expect(result.html).toMatchSnapshot("html");
expect(result.text).toMatchSnapshot("text");
});
test("uses tenant brand for invite (logo + color)", () => {
const brand = withBrandDefaults({
productName: "Acme",
logoUrl: "https://cdn.acme.test/logo.png",
primaryColor: "#ff5500",
tenantName: "Acme Inc",
});
const { html } = renderReactEmail(
<InvitationEmail
brand={brand}
senderName="Grace"
senderOrganization="Acme Inc"
actionUrl="https://app.acme.test/invite/abc"
/>
);
expect(html).toContain("Grace invited you to Acme");
expect(html).toContain("Join Acme Inc");
expect(html).toContain("#ff5500");
expect(html).toContain("https://cdn.acme.test/logo.png");
});
test("escapes user-supplied sender/org names", () => {
const { html } = renderReactEmail(
<InvitationEmail
brand={defaultMailBrand}
senderName="<script>alert(1)</script>"
senderOrganization="Org & Co"
actionUrl="https://app.example.com/invite/abc"
/>
);
expect(html).not.toContain("<script>alert(1)</script>");
expect(html).toContain("&lt;script&gt;");
expect(html).toContain("Org &amp; Co");
});
});
@@ -0,0 +1,54 @@
import { TransactionalScaffold } from "./shared.js";
import type { MailBrand } from "../_layout/theme.js";
/**
* Invitation email — sent when a workspace member invites a new user.
* Uses tenant brand overrides (logo/primary-color) so the invite
* reflects the inviting org, not the platform default.
*/
export interface InvitationEmailProps {
readonly brand: MailBrand;
readonly recipientName?: string;
readonly senderName: string;
readonly senderOrganization: string;
readonly actionUrl: string;
readonly subject?: string;
readonly eyebrow?: string;
readonly title?: string;
readonly intro?: string;
readonly actionLabel?: string;
readonly unsubscribeUrl?: string;
readonly signoffThanks?: string;
}
export function InvitationEmail({
brand,
recipientName,
senderName,
senderOrganization,
actionUrl,
subject,
eyebrow,
title,
intro,
actionLabel,
unsubscribeUrl,
signoffThanks,
}: InvitationEmailProps) {
const resolvedSubject = subject ?? `${senderName} invited you to ${brand.productName}`;
const resolvedTitle = title ?? (recipientName ? `Hello, ${recipientName}!` : "Hello!");
const resolvedIntro = intro ?? `${senderName} with ${senderOrganization} has invited you to use ${brand.productName} to collaborate with them.`;
return (
<TransactionalScaffold
brand={brand}
subject={resolvedSubject}
eyebrow={eyebrow ?? "Invitation"}
title={resolvedTitle}
intro={resolvedIntro}
actionUrl={actionUrl}
actionLabel={actionLabel ?? `Join ${senderOrganization}`}
unsubscribeUrl={unsubscribeUrl}
signoffThanks={signoffThanks}
/>
);
}
@@ -0,0 +1,80 @@
import { TransactionalScaffold } from "./shared.js";
import { InfoBox } from "../_layout/InfoBox.js";
import type { MailBrand } from "../_layout/theme.js";
/**
* InvoiceSentEmail — notifies a customer that a Stripe invoice PDF
* has been issued. CTA points to the hosted-invoice URL so the user
* can download the PDF without authenticating.
*/
export interface InvoiceSentEmailProps {
readonly brand: MailBrand;
readonly recipientName?: string;
readonly invoiceNumber: string;
readonly amountFormatted: string;
readonly issueDate: string;
readonly dueDate?: string;
readonly actionUrl: string;
readonly unsubscribeUrl?: string;
readonly subject?: string;
readonly eyebrow?: string;
readonly titleText?: string;
readonly intro?: string;
readonly actionLabel?: string;
readonly fieldLabels?: {
readonly invoiceNumber?: string;
readonly amount?: string;
readonly issued?: string;
readonly due?: string;
};
readonly signoffThanks?: string;
}
export function InvoiceSentEmail({
brand,
recipientName,
invoiceNumber,
amountFormatted,
issueDate,
dueDate,
actionUrl,
unsubscribeUrl,
subject,
eyebrow,
titleText,
intro,
actionLabel,
fieldLabels,
signoffThanks,
}: InvoiceSentEmailProps) {
const resolvedSubject = subject ?? `Invoice ${invoiceNumber} from ${brand.productName}`;
const resolvedTitle = titleText ?? (recipientName ? `Hello, ${recipientName}!` : "Your invoice is ready");
const resolvedIntro = intro ?? `Your invoice ${invoiceNumber} for ${amountFormatted} is now available.`;
return (
<TransactionalScaffold
brand={brand}
subject={resolvedSubject}
eyebrow={eyebrow ?? "Invoice"}
title={resolvedTitle}
intro={resolvedIntro}
actionUrl={actionUrl}
actionLabel={actionLabel ?? "View invoice PDF"}
unsubscribeUrl={unsubscribeUrl}
signoffThanks={signoffThanks}
>
<InfoBox brand={brand}>
<strong>{fieldLabels?.invoiceNumber ?? "Invoice number:"}</strong> {invoiceNumber}
<br />
<strong>{fieldLabels?.amount ?? "Amount:"}</strong> {amountFormatted}
<br />
<strong>{fieldLabels?.issued ?? "Issued:"}</strong> {issueDate}
{dueDate ? (
<>
<br />
<strong>{fieldLabels?.due ?? "Due:"}</strong> {dueDate}
</>
) : null}
</InfoBox>
</TransactionalScaffold>
);
}
@@ -0,0 +1,126 @@
import { describe, expect, test } from "vitest";
import { renderReactEmail } from "../render-helpers.js";
import { defaultMailBrand } from "../_layout/theme.js";
import { InvoiceSentEmail } from "./InvoiceSent.js";
import { TenantNotificationEmail } from "./TenantNotification.js";
describe("InvoiceSentEmail", () => {
test("renders default snapshot with due date", () => {
const result = renderReactEmail(
<InvoiceSentEmail
brand={defaultMailBrand}
recipientName="Ada"
invoiceNumber="INV-2026-0001"
amountFormatted="€99.00"
issueDate="2026-05-17"
dueDate="2026-06-17"
actionUrl="https://invoice.stripe.com/i/abc"
/>
);
expect(result.html).toMatchSnapshot("html");
expect(result.text).toMatchSnapshot("text");
});
test("supports unicode amounts and invoice numbers", () => {
const { html } = renderReactEmail(
<InvoiceSentEmail
brand={defaultMailBrand}
invoiceNumber="INV-€-001"
amountFormatted="€99.00 🎉"
issueDate="2026-05-17"
actionUrl="https://invoice.stripe.com/i/abc"
/>
);
expect(html).toContain("INV-€-001");
expect(html).toContain("€99.00 🎉");
});
test("accepts localized invoice copy overrides", () => {
const { html } = renderReactEmail(
<InvoiceSentEmail
brand={defaultMailBrand}
recipientName="Ada"
invoiceNumber="RE-2026-0001"
amountFormatted="99,00 €"
issueDate="17.05.2026"
dueDate="17.06.2026"
actionUrl="https://invoice.stripe.com/i/abc"
subject="Rechnung RE-2026-0001 von ToolCTRL"
eyebrow="Rechnung"
titleText="Hallo, Ada!"
intro="Deine Rechnung RE-2026-0001 über 99,00 € ist jetzt verfügbar."
actionLabel="Rechnungs-PDF öffnen"
fieldLabels={{ invoiceNumber: "Rechnungsnummer:", amount: "Betrag:", issued: "Ausgestellt:", due: "Fällig:" }}
signoffThanks="Danke,"
/>
);
expect(html).toContain("Rechnungs-PDF öffnen");
expect(html).toContain("Rechnungsnummer:");
expect(html).toContain("Fällig:");
expect(html).toContain("Danke,");
});
});
describe("TenantNotificationEmail", () => {
test("renders default snapshot with action", () => {
const result = renderReactEmail(
<TenantNotificationEmail
brand={defaultMailBrand}
recipientName="Ada"
title="New comment on Ticket #42"
body="Grace mentioned you in a comment on Ticket #42."
actionUrl="https://app.example.com/tickets/42"
actionLabel="View ticket"
/>
);
expect(result.html).toMatchSnapshot("html");
expect(result.text).toMatchSnapshot("text");
});
test("falls back to support mailto when actionUrl missing", () => {
const { html } = renderReactEmail(
<TenantNotificationEmail
brand={defaultMailBrand}
title="Weekly digest"
body="You have 3 unread notifications."
/>
);
expect(html).toContain(`mailto:${defaultMailBrand.supportEmail}`);
expect(html).toContain("Contact support");
});
test("accepts localized notification chrome overrides", () => {
const { html } = renderReactEmail(
<TenantNotificationEmail
brand={defaultMailBrand}
recipientName="Ada"
title="Neue Benachrichtigung"
body="Grace hat dich erwähnt."
actionUrl="https://app.example.com/notifications"
eyebrow="Benachrichtigung"
headline="Hallo, Ada!"
defaultActionLabel="Öffnen"
supportActionLabel="Support kontaktieren"
signoffThanks="Danke,"
/>
);
expect(html).toContain("Benachrichtigung");
expect(html).toContain("Hallo, Ada!");
expect(html).toContain("Öffnen");
expect(html).toContain("Danke,");
});
test("escapes html-like content in body", () => {
const { html } = renderReactEmail(
<TenantNotificationEmail
brand={defaultMailBrand}
title="Heads up"
body="<script>alert(1)</script> and <b>bold</b>"
/>
);
expect(html).not.toContain("<script>alert(1)</script>");
expect(html).toContain("&lt;script&gt;");
});
});
@@ -0,0 +1,28 @@
import { describe, expect, test } from "vitest";
import { renderReactEmail } from "../render-helpers.js";
import { defaultMailBrand } from "../_layout/theme.js";
import { InvalidActionUrlError } from "../_layout/Button.js";
import { MagicLinkEmail } from "./MagicLink.js";
describe("MagicLinkEmail", () => {
test("renders default snapshot", () => {
const result = renderReactEmail(
<MagicLinkEmail brand={defaultMailBrand} recipientName="Ada" actionUrl="https://app.example.com/magic/abc" />
);
expect(result.html).toMatchSnapshot("html");
expect(result.text).toMatchSnapshot("text");
});
test("emits expiry InfoBox copy", () => {
const { html } = renderReactEmail(
<MagicLinkEmail brand={defaultMailBrand} actionUrl="https://app.example.com/magic/abc" expiresInMinutes={10} />
);
expect(html).toContain("expires in 10 minutes");
});
test("rejects javascript: action URL", () => {
expect(() =>
renderReactEmail(<MagicLinkEmail brand={defaultMailBrand} actionUrl="javascript:alert(1)" />)
).toThrow(InvalidActionUrlError);
});
});
@@ -0,0 +1,63 @@
import { TransactionalScaffold } from "./shared.js";
import { InfoBox } from "../_layout/InfoBox.js";
import type { MailBrand } from "../_layout/theme.js";
/**
* MagicLink email — passwordless sign-in flow.
* Includes a short expiry-warning InfoBox plus the standard CTA.
*/
export interface MagicLinkEmailProps {
readonly brand: MailBrand;
readonly recipientName?: string;
readonly actionUrl: string;
readonly expiresInMinutes?: number;
readonly subject?: string;
readonly previewText?: string;
readonly eyebrow?: string;
readonly title?: string;
readonly intro?: string;
readonly actionLabel?: string;
readonly outro?: string;
readonly expiresText?: string;
readonly unsubscribeUrl?: string;
readonly signoffThanks?: string;
}
export function MagicLinkEmail({
brand,
recipientName,
actionUrl,
expiresInMinutes = 15,
subject,
previewText,
eyebrow,
title,
intro,
actionLabel,
outro,
expiresText,
unsubscribeUrl,
signoffThanks,
}: MagicLinkEmailProps) {
const resolvedSubject = subject ?? `Your sign-in link for ${brand.productName}`;
const resolvedTitle = title ?? (recipientName ? `Hello, ${recipientName}!` : "Hello!");
return (
<TransactionalScaffold
brand={brand}
subject={resolvedSubject}
previewText={previewText ?? `Click to sign in to ${brand.productName}`}
eyebrow={eyebrow ?? "Magic link"}
title={resolvedTitle}
intro={intro ?? `Click the button below to sign in to your ${brand.productName} account. No password required.`}
actionUrl={actionUrl}
actionLabel={actionLabel ?? "Sign in"}
outro={outro ?? "If you didn't request this email, you can safely ignore it."}
unsubscribeUrl={unsubscribeUrl}
signoffThanks={signoffThanks}
>
<InfoBox brand={brand} tone="warning">
{expiresText ?? `This link expires in ${expiresInMinutes} minutes and can only be used once.`}
</InfoBox>
</TransactionalScaffold>
);
}
@@ -0,0 +1,28 @@
import { describe, expect, test } from "vitest";
import { renderReactEmail } from "../render-helpers.js";
import { defaultMailBrand } from "../_layout/theme.js";
import { InvalidActionUrlError } from "../_layout/Button.js";
import { PasswordResetEmail } from "./PasswordReset.js";
describe("PasswordResetEmail", () => {
test("renders default snapshot", () => {
const result = renderReactEmail(
<PasswordResetEmail brand={defaultMailBrand} recipientName="Ada" actionUrl="https://app.example.com/reset?t=abc" />
);
expect(result.html).toMatchSnapshot("html");
expect(result.text).toMatchSnapshot("text");
});
test("includes the ignore-if-not-requested outro", () => {
const { html } = renderReactEmail(
<PasswordResetEmail brand={defaultMailBrand} actionUrl="https://app.example.com/reset?t=abc" />
);
expect(html).toContain("If you did not request a password reset");
});
test("rejects http://", () => {
expect(() =>
renderReactEmail(<PasswordResetEmail brand={defaultMailBrand} actionUrl="http://insecure.example.com/reset" />)
).toThrow(InvalidActionUrlError);
});
});
@@ -0,0 +1,53 @@
import { TransactionalScaffold } from "./shared.js";
import type { MailBrand } from "../_layout/theme.js";
/**
* PasswordReset email — sent on user-initiated password-reset request.
* The outro reminds the recipient to ignore the message if they did
* not request a reset.
*/
export interface PasswordResetEmailProps {
readonly brand: MailBrand;
readonly recipientName?: string;
readonly actionUrl: string;
readonly subject?: string;
readonly eyebrow?: string;
readonly title?: string;
readonly intro?: string;
readonly actionLabel?: string;
readonly outro?: string;
readonly unsubscribeUrl?: string;
readonly signoffThanks?: string;
}
export function PasswordResetEmail({
brand,
recipientName,
actionUrl,
subject,
eyebrow,
title,
intro,
actionLabel,
outro,
unsubscribeUrl,
signoffThanks,
}: PasswordResetEmailProps) {
const resolvedSubject = subject ?? `Set up a new password for ${brand.productName}`;
const resolvedTitle = title ?? (recipientName ? `Hello, ${recipientName}!` : "Hello!");
const resolvedIntro = intro ?? `You recently requested to reset your password for your ${brand.productName} account.`;
return (
<TransactionalScaffold
brand={brand}
subject={resolvedSubject}
eyebrow={eyebrow ?? "Password reset"}
title={resolvedTitle}
intro={resolvedIntro}
actionUrl={actionUrl}
actionLabel={actionLabel ?? "Reset password"}
outro={outro ?? "If you did not request a password reset, please ignore this email or contact support if you have questions."}
unsubscribeUrl={unsubscribeUrl}
signoffThanks={signoffThanks}
/>
);
}
@@ -0,0 +1,116 @@
import { describe, expect, test } from "vitest";
import { renderReactEmail } from "../render-helpers.js";
import { defaultMailBrand } from "../_layout/theme.js";
import { SubscriptionSuccessEmail } from "./SubscriptionSuccess.js";
import { SubscriptionFailedEmail } from "./SubscriptionFailed.js";
describe("SubscriptionSuccessEmail", () => {
test("renders default snapshot with next-billing", () => {
const result = renderReactEmail(
<SubscriptionSuccessEmail
brand={defaultMailBrand}
recipientName="Ada"
planName="Pro"
amountFormatted="$29.00"
nextBillingDate="2026-06-01"
actionUrl="https://app.example.com/billing"
/>
);
expect(result.html).toMatchSnapshot("html");
expect(result.text).toMatchSnapshot("text");
});
test("omits next-billing row when undefined", () => {
const { html } = renderReactEmail(
<SubscriptionSuccessEmail
brand={defaultMailBrand}
planName="Pro"
amountFormatted="$29.00"
actionUrl="https://app.example.com/billing"
/>
);
expect(html).not.toContain("Next billing:");
});
test("accepts localized copy overrides", () => {
const { html, text } = renderReactEmail(
<SubscriptionSuccessEmail
brand={defaultMailBrand}
recipientName="Ada"
planName="Pro"
amountFormatted="29,00 €"
nextBillingDate="01.06.2026"
actionUrl="https://app.example.com/billing"
subject="Dein ToolCTRL-Abo ist aktiv"
eyebrow="Abo"
title="Danke, Ada!"
intro="Dein Pro-Abo ist jetzt aktiv. Willkommen!"
actionLabel="Dashboard öffnen"
fieldLabels={{ plan: "Tarif:", amount: "Betrag:", nextBilling: "Nächste Abrechnung:" }}
signoffThanks="Danke,"
/>
);
expect(html).toContain("Dein ToolCTRL-Abo ist aktiv");
expect(html).toContain("Dashboard öffnen");
expect(html).toContain("Tarif:");
expect(html).toContain("Nächste Abrechnung:");
expect(text).toContain("Danke,");
});
});
describe("SubscriptionFailedEmail", () => {
test("renders default snapshot with reason + retry", () => {
const result = renderReactEmail(
<SubscriptionFailedEmail
brand={defaultMailBrand}
recipientName="Ada"
planName="Pro"
amountFormatted="$29.00"
failureReason="Card declined"
retryAt="2026-05-20"
actionUrl="https://app.example.com/billing"
/>
);
expect(result.html).toMatchSnapshot("html");
expect(result.text).toMatchSnapshot("text");
});
test("uses warning-tone InfoBox", () => {
const { html } = renderReactEmail(
<SubscriptionFailedEmail
brand={defaultMailBrand}
planName="Pro"
amountFormatted="$29.00"
actionUrl="https://app.example.com/billing"
/>
);
expect(html).toMatch(/#fef3c7/i);
});
test("accepts localized failure copy overrides", () => {
const { html } = renderReactEmail(
<SubscriptionFailedEmail
brand={defaultMailBrand}
recipientName="Ada"
planName="Pro"
amountFormatted="29,00 €"
failureReason="Karte abgelehnt"
retryAt="20.05.2026"
actionUrl="https://app.example.com/billing"
subject="Aktion erforderlich: Zahlung fehlgeschlagen"
eyebrow="Zahlung fehlgeschlagen"
title="Hallo Ada,"
intro="Aktualisiere bitte deine Zahlungsmethode."
actionLabel="Zahlungsmethode aktualisieren"
fieldLabels={{ plan: "Tarif:", amount: "Betrag:", reason: "Grund:", nextRetry: "Nächster Versuch:" }}
signoffThanks="Danke,"
/>
);
expect(html).toContain("Zahlungsmethode aktualisieren");
expect(html).toContain("Grund:");
expect(html).toContain("Nächster Versuch:");
expect(html).toContain("Danke,");
});
});
@@ -0,0 +1,85 @@
import { TransactionalScaffold } from "./shared.js";
import { InfoBox } from "../_layout/InfoBox.js";
import type { MailBrand } from "../_layout/theme.js";
/**
* SubscriptionFailedEmail — sent after a Stripe `invoice.payment_failed`
* webhook. Surfaces the failure reason and a direct CTA to the
* billing portal so the customer can fix the card before dunning.
*/
export interface SubscriptionFailedEmailProps {
readonly brand: MailBrand;
readonly recipientName?: string;
readonly planName: string;
readonly amountFormatted: string;
readonly failureReason?: string;
readonly retryAt?: string;
readonly actionUrl: string;
readonly unsubscribeUrl?: string;
readonly subject?: string;
readonly eyebrow?: string;
readonly title?: string;
readonly intro?: string;
readonly actionLabel?: string;
readonly fieldLabels?: {
readonly plan?: string;
readonly amount?: string;
readonly reason?: string;
readonly nextRetry?: string;
};
readonly signoffThanks?: string;
}
export function SubscriptionFailedEmail({
brand,
recipientName,
planName,
amountFormatted,
failureReason,
retryAt,
actionUrl,
unsubscribeUrl,
subject,
eyebrow,
title,
intro,
actionLabel,
fieldLabels,
signoffThanks,
}: SubscriptionFailedEmailProps) {
const resolvedSubject = subject ?? `Action required: payment failed for ${brand.productName}`;
const resolvedTitle = title ?? (recipientName ? `Hi ${recipientName},` : "We couldn't charge your card");
const resolvedIntro =
intro ?? `We were unable to charge your card for the ${planName} subscription. Please update your payment method to avoid service interruption.`;
return (
<TransactionalScaffold
brand={brand}
subject={resolvedSubject}
eyebrow={eyebrow ?? "Payment failed"}
title={resolvedTitle}
intro={resolvedIntro}
actionUrl={actionUrl}
actionLabel={actionLabel ?? "Update payment method"}
unsubscribeUrl={unsubscribeUrl}
signoffThanks={signoffThanks}
>
<InfoBox brand={brand} tone="warning">
<strong>{fieldLabels?.plan ?? "Plan:"}</strong> {planName}
<br />
<strong>{fieldLabels?.amount ?? "Amount:"}</strong> {amountFormatted}
{failureReason ? (
<>
<br />
<strong>{fieldLabels?.reason ?? "Reason:"}</strong> {failureReason}
</>
) : null}
{retryAt ? (
<>
<br />
<strong>{fieldLabels?.nextRetry ?? "Next retry:"}</strong> {retryAt}
</>
) : null}
</InfoBox>
</TransactionalScaffold>
);
}
@@ -0,0 +1,76 @@
import { TransactionalScaffold } from "./shared.js";
import { InfoBox } from "../_layout/InfoBox.js";
import type { MailBrand } from "../_layout/theme.js";
/**
* SubscriptionSuccessEmail — sent after Stripe checkout completion.
* Surfaces the active plan and next-billing date so customers can
* verify they were charged correctly without opening the billing
* portal.
*/
export interface SubscriptionSuccessEmailProps {
readonly brand: MailBrand;
readonly recipientName?: string;
readonly planName: string;
readonly amountFormatted: string;
readonly nextBillingDate?: string;
readonly actionUrl: string;
readonly unsubscribeUrl?: string;
readonly subject?: string;
readonly eyebrow?: string;
readonly title?: string;
readonly intro?: string;
readonly actionLabel?: string;
readonly fieldLabels?: {
readonly plan?: string;
readonly amount?: string;
readonly nextBilling?: string;
};
readonly signoffThanks?: string;
}
export function SubscriptionSuccessEmail({
brand,
recipientName,
planName,
amountFormatted,
nextBillingDate,
actionUrl,
unsubscribeUrl,
subject,
eyebrow,
title,
intro,
actionLabel,
fieldLabels,
signoffThanks,
}: SubscriptionSuccessEmailProps) {
const resolvedSubject = subject ?? `Your ${brand.productName} subscription is active`;
const resolvedTitle = title ?? (recipientName ? `Thanks, ${recipientName}!` : "Thanks for subscribing!");
const resolvedIntro = intro ?? `Your ${planName} subscription is now active. Welcome aboard!`;
return (
<TransactionalScaffold
brand={brand}
subject={resolvedSubject}
eyebrow={eyebrow ?? "Subscription"}
title={resolvedTitle}
intro={resolvedIntro}
actionUrl={actionUrl}
actionLabel={actionLabel ?? "Open your dashboard"}
unsubscribeUrl={unsubscribeUrl}
signoffThanks={signoffThanks}
>
<InfoBox brand={brand}>
<strong>{fieldLabels?.plan ?? "Plan:"}</strong> {planName}
<br />
<strong>{fieldLabels?.amount ?? "Amount:"}</strong> {amountFormatted}
{nextBillingDate ? (
<>
<br />
<strong>{fieldLabels?.nextBilling ?? "Next billing:"}</strong> {nextBillingDate}
</>
) : null}
</InfoBox>
</TransactionalScaffold>
);
}
@@ -0,0 +1,59 @@
import { TransactionalScaffold } from "./shared.js";
import type { MailBrand } from "../_layout/theme.js";
/**
* TenantNotificationEmail — generic tenant notification used to deliver
* in-app notifications via email digest. The `body` is treated as
* plain text (React's default escaping handles XSS); raw HTML is
* intentionally not supported.
*/
export interface TenantNotificationEmailProps {
readonly brand: MailBrand;
readonly recipientName?: string;
readonly title: string;
readonly body: string;
readonly actionUrl?: string;
readonly actionLabel?: string;
readonly unsubscribeUrl?: string;
readonly eyebrow?: string;
readonly headline?: string;
readonly defaultActionLabel?: string;
readonly supportActionLabel?: string;
readonly signoffThanks?: string;
}
export function TenantNotificationEmail({
brand,
recipientName,
title,
body,
actionUrl,
actionLabel,
unsubscribeUrl,
eyebrow,
headline,
defaultActionLabel,
supportActionLabel,
signoffThanks,
}: TenantNotificationEmailProps) {
const subject = title;
const resolvedHeadline = headline ?? (recipientName ? `Hello, ${recipientName}!` : title);
// Generic notifications may omit the CTA. We always render the
// scaffold's button slot so the visual rhythm is consistent — fall
// back to a no-op support mailto when no action URL was supplied.
const resolvedActionUrl = actionUrl ?? `mailto:${brand.supportEmail}`;
const resolvedActionLabel = actionLabel ?? (actionUrl ? (defaultActionLabel ?? "Open") : (supportActionLabel ?? "Contact support"));
return (
<TransactionalScaffold
brand={brand}
subject={subject}
eyebrow={eyebrow ?? "Notification"}
title={resolvedHeadline}
intro={body}
actionUrl={resolvedActionUrl}
actionLabel={resolvedActionLabel}
unsubscribeUrl={unsubscribeUrl}
signoffThanks={signoffThanks}
/>
);
}
@@ -0,0 +1,47 @@
import { describe, expect, test } from "vitest";
import { renderReactEmail } from "../render-helpers.js";
import { defaultMailBrand, withBrandDefaults } from "../_layout/theme.js";
import { InvalidActionUrlError } from "../_layout/Button.js";
import { WelcomeEmail } from "./Welcome.js";
describe("WelcomeEmail", () => {
test("renders default-brand named welcome (snapshot)", () => {
const result = renderReactEmail(
<WelcomeEmail brand={defaultMailBrand} recipientName="Ada" actionUrl="https://app.example.com/login" />
);
expect(result.html).toMatchSnapshot("html");
expect(result.text).toMatchSnapshot("text");
});
test("falls back to anonymous greeting when name missing", () => {
const { html } = renderReactEmail(
<WelcomeEmail brand={defaultMailBrand} actionUrl="https://app.example.com/login" />
);
expect(html).toContain("Welcome!");
expect(html).not.toContain("Welcome, ");
});
test("applies tenant brand overrides", () => {
const brand = withBrandDefaults({ productName: "Acme", primaryColor: "#123456", logoUrl: "https://cdn.acme.test/l.png" });
const { html } = renderReactEmail(
<WelcomeEmail brand={brand} recipientName="Ada" actionUrl="https://app.acme.test/login" />
);
expect(html).toContain("Welcome to Acme, Ada!");
expect(html).toContain("#123456");
expect(html).toContain("https://cdn.acme.test/l.png");
});
test("escapes user content via React (XSS-safe)", () => {
const { html } = renderReactEmail(
<WelcomeEmail brand={defaultMailBrand} recipientName="<script>alert(1)</script>" actionUrl="https://app.example.com/login" />
);
expect(html).not.toContain("<script>alert(1)</script>");
expect(html).toContain("&lt;script&gt;");
});
test("rejects insecure action URLs", () => {
expect(() =>
renderReactEmail(<WelcomeEmail brand={defaultMailBrand} actionUrl="javascript:alert(1)" />)
).toThrow(InvalidActionUrlError);
});
});
@@ -0,0 +1,51 @@
import { TransactionalScaffold } from "./shared.js";
import type { MailBrand } from "../_layout/theme.js";
/**
* Welcome transactional email — sent after account activation. Also
* doubles as the post-checkout "account-setup" variant via overridable
* subject/title/intro/actionLabel props (see EmailTemplates wrapper).
*/
export interface WelcomeEmailProps {
readonly brand: MailBrand;
readonly recipientName?: string;
readonly actionUrl: string;
readonly subject?: string;
readonly eyebrow?: string;
readonly title?: string;
readonly intro?: string;
readonly actionLabel?: string;
readonly unsubscribeUrl?: string;
readonly signoffThanks?: string;
}
export function WelcomeEmail({
brand,
recipientName,
actionUrl,
subject,
eyebrow,
title,
intro,
actionLabel,
unsubscribeUrl,
signoffThanks,
}: WelcomeEmailProps) {
const resolvedSubject =
subject ?? (recipientName ? `Welcome to ${brand.productName}, ${recipientName}!` : `Welcome to ${brand.productName}!`);
const resolvedTitle = title ?? (recipientName ? `Welcome, ${recipientName}!` : "Welcome!");
const resolvedIntro = intro ?? `Thanks for trying ${brand.productName}.`;
return (
<TransactionalScaffold
brand={brand}
subject={resolvedSubject}
eyebrow={eyebrow ?? "Welcome"}
title={resolvedTitle}
intro={resolvedIntro}
actionUrl={actionUrl}
actionLabel={actionLabel ?? "Click here to log in"}
unsubscribeUrl={unsubscribeUrl}
signoffThanks={signoffThanks}
/>
);
}
@@ -0,0 +1,16 @@
// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
exports[`InvitationEmail > renders default snapshot > html 1`] = `"<!DOCTYPE html><html lang="en"><head><meta charSet="utf-8"/><meta name="viewport" content="width=device-width, initial-scale=1"/><title>Grace invited you to ToolCTRL</title></head><body style="margin:0;padding:0;background-color:#f4f5f7;color:#0f172a;font-family:ui-sans-serif, -apple-system, BlinkMacSystemFont, &#x27;Segoe UI&#x27;, Roboto, &#x27;Helvetica Neue&#x27;, Arial, sans-serif;font-size:16px;line-height:1.5"><div style="display:none;font-size:1px;line-height:1px;max-height:0;max-width:0;opacity:0;overflow:hidden">Grace invited you to ToolCTRL</div><div style="width:100%;max-width:560px;margin:0 auto;padding:24px 16px"><div style="background-color:#ffffff;border:1px solid #e2e8f0;border-radius:20px;padding:32px"><div style="padding-bottom:16px;text-align:left"><strong style="color:#0f172a;font-size:18px">ToolCTRL</strong></div><div style="color:#475569;font-size:13px;font-weight:700;letter-spacing:0.08em;text-transform:uppercase;margin-bottom:8px">Invitation</div><h1 style="margin:8px 0 16px;font-size:28px;line-height:1.2;color:#0f172a;font-weight:700">Hello, Ada!</h1><p style="margin:0 0 24px;font-size:16px;line-height:1.6;color:#0f172a">Grace with Example Org has invited you to use ToolCTRL to collaborate with them.</p><a href="https://app.example.com/invite/abc" style="display:inline-block;background-color:#2563eb;color:#ffffff;padding:12px 22px;border-radius:999px;font-weight:700;font-size:15px;text-decoration:none" target="_blank" rel="noopener noreferrer">Join Example Org</a><p style="margin:24px 0 0;font-size:14px;line-height:1.6;color:#0f172a">Thanks,<br/>-<br/>ToolCTRL Support</p><div style="margin-top:24px;padding-top:16px;border-top:1px solid;font-size:12px;line-height:1.5;border-top-color:#e2e8f0;color:#475569"><div><a href="https://tool-ctrl.de/privacy" style="text-decoration:underline;color:#2563eb">Privacy</a><span style="margin:0 6px">·</span><a href="https://tool-ctrl.de/terms" style="text-decoration:underline;color:#2563eb">Terms</a><span style="margin:0 6px">·</span><a href="https://tool-ctrl.de/imprint" style="text-decoration:underline;color:#2563eb">Imprint</a></div><div style="margin-top:8px">Questions? Email us at <a href="mailto:info@tool-ctrl.de" style="text-decoration:underline;color:#2563eb">info@tool-ctrl.de</a>.</div></div></div></div></body></html>"`;
exports[`InvitationEmail > renders default snapshot > text 1`] = `
"Grace invited you to ToolCTRL
ToolCTRL
Invitation
Hello, Ada!
Grace with Example Org has invited you to use ToolCTRL to collaborate with them.
Join Example Org (https://app.example.com/invite/abc)Thanks,
-
ToolCTRL Support
Privacy (https://tool-ctrl.de/privacy)·Terms (https://tool-ctrl.de/terms)·Imprint (https://tool-ctrl.de/imprint)
Questions? Email us at info@tool-ctrl.de (mailto:info@tool-ctrl.de)."
`;
@@ -0,0 +1,35 @@
// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
exports[`InvoiceSentEmail > renders default snapshot with due date > html 1`] = `"<!DOCTYPE html><html lang="en"><head><meta charSet="utf-8"/><meta name="viewport" content="width=device-width, initial-scale=1"/><title>Invoice INV-2026-0001 from ToolCTRL</title></head><body style="margin:0;padding:0;background-color:#f4f5f7;color:#0f172a;font-family:ui-sans-serif, -apple-system, BlinkMacSystemFont, &#x27;Segoe UI&#x27;, Roboto, &#x27;Helvetica Neue&#x27;, Arial, sans-serif;font-size:16px;line-height:1.5"><div style="display:none;font-size:1px;line-height:1px;max-height:0;max-width:0;opacity:0;overflow:hidden">Invoice INV-2026-0001 from ToolCTRL</div><div style="width:100%;max-width:560px;margin:0 auto;padding:24px 16px"><div style="background-color:#ffffff;border:1px solid #e2e8f0;border-radius:20px;padding:32px"><div style="padding-bottom:16px;text-align:left"><strong style="color:#0f172a;font-size:18px">ToolCTRL</strong></div><div style="color:#475569;font-size:13px;font-weight:700;letter-spacing:0.08em;text-transform:uppercase;margin-bottom:8px">Invoice</div><h1 style="margin:8px 0 16px;font-size:28px;line-height:1.2;color:#0f172a;font-weight:700">Hello, Ada!</h1><p style="margin:0 0 24px;font-size:16px;line-height:1.6;color:#0f172a">Your invoice INV-2026-0001 for €99.00 is now available.</p><a href="https://invoice.stripe.com/i/abc" style="display:inline-block;background-color:#2563eb;color:#ffffff;padding:12px 22px;border-radius:999px;font-weight:700;font-size:15px;text-decoration:none" target="_blank" rel="noopener noreferrer">View invoice PDF</a><div style="margin-top:20px;padding:14px 16px;border-radius:10px;font-size:14px;line-height:1.55;background-color:#f1f5f9;color:#0f172a;border:1px solid #e2e8f0"><strong>Invoice number:</strong> INV-2026-0001<br/><strong>Amount:</strong> €99.00<br/><strong>Issued:</strong> 2026-05-17<br/><strong>Due:</strong> 2026-06-17</div><p style="margin:24px 0 0;font-size:14px;line-height:1.6;color:#0f172a">Thanks,<br/>-<br/>ToolCTRL Support</p><div style="margin-top:24px;padding-top:16px;border-top:1px solid;font-size:12px;line-height:1.5;border-top-color:#e2e8f0;color:#475569"><div><a href="https://tool-ctrl.de/privacy" style="text-decoration:underline;color:#2563eb">Privacy</a><span style="margin:0 6px">·</span><a href="https://tool-ctrl.de/terms" style="text-decoration:underline;color:#2563eb">Terms</a><span style="margin:0 6px">·</span><a href="https://tool-ctrl.de/imprint" style="text-decoration:underline;color:#2563eb">Imprint</a></div><div style="margin-top:8px">Questions? Email us at <a href="mailto:info@tool-ctrl.de" style="text-decoration:underline;color:#2563eb">info@tool-ctrl.de</a>.</div></div></div></div></body></html>"`;
exports[`InvoiceSentEmail > renders default snapshot with due date > text 1`] = `
"Invoice INV-2026-0001 from ToolCTRL
ToolCTRL
Invoice
Hello, Ada!
Your invoice INV-2026-0001 for €99.00 is now available.
View invoice PDF (https://invoice.stripe.com/i/abc)Invoice number: INV-2026-0001
Amount: €99.00
Issued: 2026-05-17
Due: 2026-06-17
Thanks,
-
ToolCTRL Support
Privacy (https://tool-ctrl.de/privacy)·Terms (https://tool-ctrl.de/terms)·Imprint (https://tool-ctrl.de/imprint)
Questions? Email us at info@tool-ctrl.de (mailto:info@tool-ctrl.de)."
`;
exports[`TenantNotificationEmail > renders default snapshot with action > html 1`] = `"<!DOCTYPE html><html lang="en"><head><meta charSet="utf-8"/><meta name="viewport" content="width=device-width, initial-scale=1"/><title>New comment on Ticket #42</title></head><body style="margin:0;padding:0;background-color:#f4f5f7;color:#0f172a;font-family:ui-sans-serif, -apple-system, BlinkMacSystemFont, &#x27;Segoe UI&#x27;, Roboto, &#x27;Helvetica Neue&#x27;, Arial, sans-serif;font-size:16px;line-height:1.5"><div style="display:none;font-size:1px;line-height:1px;max-height:0;max-width:0;opacity:0;overflow:hidden">New comment on Ticket #42</div><div style="width:100%;max-width:560px;margin:0 auto;padding:24px 16px"><div style="background-color:#ffffff;border:1px solid #e2e8f0;border-radius:20px;padding:32px"><div style="padding-bottom:16px;text-align:left"><strong style="color:#0f172a;font-size:18px">ToolCTRL</strong></div><div style="color:#475569;font-size:13px;font-weight:700;letter-spacing:0.08em;text-transform:uppercase;margin-bottom:8px">Notification</div><h1 style="margin:8px 0 16px;font-size:28px;line-height:1.2;color:#0f172a;font-weight:700">Hello, Ada!</h1><p style="margin:0 0 24px;font-size:16px;line-height:1.6;color:#0f172a">Grace mentioned you in a comment on Ticket #42.</p><a href="https://app.example.com/tickets/42" style="display:inline-block;background-color:#2563eb;color:#ffffff;padding:12px 22px;border-radius:999px;font-weight:700;font-size:15px;text-decoration:none" target="_blank" rel="noopener noreferrer">View ticket</a><p style="margin:24px 0 0;font-size:14px;line-height:1.6;color:#0f172a">Thanks,<br/>-<br/>ToolCTRL Support</p><div style="margin-top:24px;padding-top:16px;border-top:1px solid;font-size:12px;line-height:1.5;border-top-color:#e2e8f0;color:#475569"><div><a href="https://tool-ctrl.de/privacy" style="text-decoration:underline;color:#2563eb">Privacy</a><span style="margin:0 6px">·</span><a href="https://tool-ctrl.de/terms" style="text-decoration:underline;color:#2563eb">Terms</a><span style="margin:0 6px">·</span><a href="https://tool-ctrl.de/imprint" style="text-decoration:underline;color:#2563eb">Imprint</a></div><div style="margin-top:8px">Questions? Email us at <a href="mailto:info@tool-ctrl.de" style="text-decoration:underline;color:#2563eb">info@tool-ctrl.de</a>.</div></div></div></div></body></html>"`;
exports[`TenantNotificationEmail > renders default snapshot with action > text 1`] = `
"New comment on Ticket #42
ToolCTRL
Notification
Hello, Ada!
Grace mentioned you in a comment on Ticket #42.
View ticket (https://app.example.com/tickets/42)Thanks,
-
ToolCTRL Support
Privacy (https://tool-ctrl.de/privacy)·Terms (https://tool-ctrl.de/terms)·Imprint (https://tool-ctrl.de/imprint)
Questions? Email us at info@tool-ctrl.de (mailto:info@tool-ctrl.de)."
`;
@@ -0,0 +1,18 @@
// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
exports[`MagicLinkEmail > renders default snapshot > html 1`] = `"<!DOCTYPE html><html lang="en"><head><meta charSet="utf-8"/><meta name="viewport" content="width=device-width, initial-scale=1"/><title>Your sign-in link for ToolCTRL</title></head><body style="margin:0;padding:0;background-color:#f4f5f7;color:#0f172a;font-family:ui-sans-serif, -apple-system, BlinkMacSystemFont, &#x27;Segoe UI&#x27;, Roboto, &#x27;Helvetica Neue&#x27;, Arial, sans-serif;font-size:16px;line-height:1.5"><div style="display:none;font-size:1px;line-height:1px;max-height:0;max-width:0;opacity:0;overflow:hidden">Click to sign in to ToolCTRL</div><div style="width:100%;max-width:560px;margin:0 auto;padding:24px 16px"><div style="background-color:#ffffff;border:1px solid #e2e8f0;border-radius:20px;padding:32px"><div style="padding-bottom:16px;text-align:left"><strong style="color:#0f172a;font-size:18px">ToolCTRL</strong></div><div style="color:#475569;font-size:13px;font-weight:700;letter-spacing:0.08em;text-transform:uppercase;margin-bottom:8px">Magic link</div><h1 style="margin:8px 0 16px;font-size:28px;line-height:1.2;color:#0f172a;font-weight:700">Hello, Ada!</h1><p style="margin:0 0 24px;font-size:16px;line-height:1.6;color:#0f172a">Click the button below to sign in to your ToolCTRL account. No password required.</p><a href="https://app.example.com/magic/abc" style="display:inline-block;background-color:#2563eb;color:#ffffff;padding:12px 22px;border-radius:999px;font-weight:700;font-size:15px;text-decoration:none" target="_blank" rel="noopener noreferrer">Sign in</a><p style="margin:24px 0 0;font-size:14px;line-height:1.6;color:#475569">If you didn&#x27;t request this email, you can safely ignore it.</p><div style="margin-top:20px;padding:14px 16px;border-radius:10px;font-size:14px;line-height:1.55;background-color:#fef3c7;color:#92400e;border:1px solid #fde68a">This link expires in 15 minutes and can only be used once.</div><p style="margin:24px 0 0;font-size:14px;line-height:1.6;color:#0f172a">Thanks,<br/>-<br/>ToolCTRL Support</p><div style="margin-top:24px;padding-top:16px;border-top:1px solid;font-size:12px;line-height:1.5;border-top-color:#e2e8f0;color:#475569"><div><a href="https://tool-ctrl.de/privacy" style="text-decoration:underline;color:#2563eb">Privacy</a><span style="margin:0 6px">·</span><a href="https://tool-ctrl.de/terms" style="text-decoration:underline;color:#2563eb">Terms</a><span style="margin:0 6px">·</span><a href="https://tool-ctrl.de/imprint" style="text-decoration:underline;color:#2563eb">Imprint</a></div><div style="margin-top:8px">Questions? Email us at <a href="mailto:info@tool-ctrl.de" style="text-decoration:underline;color:#2563eb">info@tool-ctrl.de</a>.</div></div></div></div></body></html>"`;
exports[`MagicLinkEmail > renders default snapshot > text 1`] = `
"Click to sign in to ToolCTRL
ToolCTRL
Magic link
Hello, Ada!
Click the button below to sign in to your ToolCTRL account. No password required.
Sign in (https://app.example.com/magic/abc)If you didn&#x27;t request this email, you can safely ignore it.
This link expires in 15 minutes and can only be used once.
Thanks,
-
ToolCTRL Support
Privacy (https://tool-ctrl.de/privacy)·Terms (https://tool-ctrl.de/terms)·Imprint (https://tool-ctrl.de/imprint)
Questions? Email us at info@tool-ctrl.de (mailto:info@tool-ctrl.de)."
`;
@@ -0,0 +1,17 @@
// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
exports[`PasswordResetEmail > renders default snapshot > html 1`] = `"<!DOCTYPE html><html lang="en"><head><meta charSet="utf-8"/><meta name="viewport" content="width=device-width, initial-scale=1"/><title>Set up a new password for ToolCTRL</title></head><body style="margin:0;padding:0;background-color:#f4f5f7;color:#0f172a;font-family:ui-sans-serif, -apple-system, BlinkMacSystemFont, &#x27;Segoe UI&#x27;, Roboto, &#x27;Helvetica Neue&#x27;, Arial, sans-serif;font-size:16px;line-height:1.5"><div style="display:none;font-size:1px;line-height:1px;max-height:0;max-width:0;opacity:0;overflow:hidden">Set up a new password for ToolCTRL</div><div style="width:100%;max-width:560px;margin:0 auto;padding:24px 16px"><div style="background-color:#ffffff;border:1px solid #e2e8f0;border-radius:20px;padding:32px"><div style="padding-bottom:16px;text-align:left"><strong style="color:#0f172a;font-size:18px">ToolCTRL</strong></div><div style="color:#475569;font-size:13px;font-weight:700;letter-spacing:0.08em;text-transform:uppercase;margin-bottom:8px">Password reset</div><h1 style="margin:8px 0 16px;font-size:28px;line-height:1.2;color:#0f172a;font-weight:700">Hello, Ada!</h1><p style="margin:0 0 24px;font-size:16px;line-height:1.6;color:#0f172a">You recently requested to reset your password for your ToolCTRL account.</p><a href="https://app.example.com/reset?t=abc" style="display:inline-block;background-color:#2563eb;color:#ffffff;padding:12px 22px;border-radius:999px;font-weight:700;font-size:15px;text-decoration:none" target="_blank" rel="noopener noreferrer">Reset password</a><p style="margin:24px 0 0;font-size:14px;line-height:1.6;color:#475569">If you did not request a password reset, please ignore this email or contact support if you have questions.</p><p style="margin:24px 0 0;font-size:14px;line-height:1.6;color:#0f172a">Thanks,<br/>-<br/>ToolCTRL Support</p><div style="margin-top:24px;padding-top:16px;border-top:1px solid;font-size:12px;line-height:1.5;border-top-color:#e2e8f0;color:#475569"><div><a href="https://tool-ctrl.de/privacy" style="text-decoration:underline;color:#2563eb">Privacy</a><span style="margin:0 6px">·</span><a href="https://tool-ctrl.de/terms" style="text-decoration:underline;color:#2563eb">Terms</a><span style="margin:0 6px">·</span><a href="https://tool-ctrl.de/imprint" style="text-decoration:underline;color:#2563eb">Imprint</a></div><div style="margin-top:8px">Questions? Email us at <a href="mailto:info@tool-ctrl.de" style="text-decoration:underline;color:#2563eb">info@tool-ctrl.de</a>.</div></div></div></div></body></html>"`;
exports[`PasswordResetEmail > renders default snapshot > text 1`] = `
"Set up a new password for ToolCTRL
ToolCTRL
Password reset
Hello, Ada!
You recently requested to reset your password for your ToolCTRL account.
Reset password (https://app.example.com/reset?t=abc)If you did not request a password reset, please ignore this email or contact support if you have questions.
Thanks,
-
ToolCTRL Support
Privacy (https://tool-ctrl.de/privacy)·Terms (https://tool-ctrl.de/terms)·Imprint (https://tool-ctrl.de/imprint)
Questions? Email us at info@tool-ctrl.de (mailto:info@tool-ctrl.de)."
`;
@@ -0,0 +1,38 @@
// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
exports[`SubscriptionFailedEmail > renders default snapshot with reason + retry > html 1`] = `"<!DOCTYPE html><html lang="en"><head><meta charSet="utf-8"/><meta name="viewport" content="width=device-width, initial-scale=1"/><title>Action required: payment failed for ToolCTRL</title></head><body style="margin:0;padding:0;background-color:#f4f5f7;color:#0f172a;font-family:ui-sans-serif, -apple-system, BlinkMacSystemFont, &#x27;Segoe UI&#x27;, Roboto, &#x27;Helvetica Neue&#x27;, Arial, sans-serif;font-size:16px;line-height:1.5"><div style="display:none;font-size:1px;line-height:1px;max-height:0;max-width:0;opacity:0;overflow:hidden">Action required: payment failed for ToolCTRL</div><div style="width:100%;max-width:560px;margin:0 auto;padding:24px 16px"><div style="background-color:#ffffff;border:1px solid #e2e8f0;border-radius:20px;padding:32px"><div style="padding-bottom:16px;text-align:left"><strong style="color:#0f172a;font-size:18px">ToolCTRL</strong></div><div style="color:#475569;font-size:13px;font-weight:700;letter-spacing:0.08em;text-transform:uppercase;margin-bottom:8px">Payment failed</div><h1 style="margin:8px 0 16px;font-size:28px;line-height:1.2;color:#0f172a;font-weight:700">Hi Ada,</h1><p style="margin:0 0 24px;font-size:16px;line-height:1.6;color:#0f172a">We were unable to charge your card for the Pro subscription. Please update your payment method to avoid service interruption.</p><a href="https://app.example.com/billing" style="display:inline-block;background-color:#2563eb;color:#ffffff;padding:12px 22px;border-radius:999px;font-weight:700;font-size:15px;text-decoration:none" target="_blank" rel="noopener noreferrer">Update payment method</a><div style="margin-top:20px;padding:14px 16px;border-radius:10px;font-size:14px;line-height:1.55;background-color:#fef3c7;color:#92400e;border:1px solid #fde68a"><strong>Plan:</strong> Pro<br/><strong>Amount:</strong> $29.00<br/><strong>Reason:</strong> Card declined<br/><strong>Next retry:</strong> 2026-05-20</div><p style="margin:24px 0 0;font-size:14px;line-height:1.6;color:#0f172a">Thanks,<br/>-<br/>ToolCTRL Support</p><div style="margin-top:24px;padding-top:16px;border-top:1px solid;font-size:12px;line-height:1.5;border-top-color:#e2e8f0;color:#475569"><div><a href="https://tool-ctrl.de/privacy" style="text-decoration:underline;color:#2563eb">Privacy</a><span style="margin:0 6px">·</span><a href="https://tool-ctrl.de/terms" style="text-decoration:underline;color:#2563eb">Terms</a><span style="margin:0 6px">·</span><a href="https://tool-ctrl.de/imprint" style="text-decoration:underline;color:#2563eb">Imprint</a></div><div style="margin-top:8px">Questions? Email us at <a href="mailto:info@tool-ctrl.de" style="text-decoration:underline;color:#2563eb">info@tool-ctrl.de</a>.</div></div></div></div></body></html>"`;
exports[`SubscriptionFailedEmail > renders default snapshot with reason + retry > text 1`] = `
"Action required: payment failed for ToolCTRL
ToolCTRL
Payment failed
Hi Ada,
We were unable to charge your card for the Pro subscription. Please update your payment method to avoid service interruption.
Update payment method (https://app.example.com/billing)Plan: Pro
Amount: $29.00
Reason: Card declined
Next retry: 2026-05-20
Thanks,
-
ToolCTRL Support
Privacy (https://tool-ctrl.de/privacy)·Terms (https://tool-ctrl.de/terms)·Imprint (https://tool-ctrl.de/imprint)
Questions? Email us at info@tool-ctrl.de (mailto:info@tool-ctrl.de)."
`;
exports[`SubscriptionSuccessEmail > renders default snapshot with next-billing > html 1`] = `"<!DOCTYPE html><html lang="en"><head><meta charSet="utf-8"/><meta name="viewport" content="width=device-width, initial-scale=1"/><title>Your ToolCTRL subscription is active</title></head><body style="margin:0;padding:0;background-color:#f4f5f7;color:#0f172a;font-family:ui-sans-serif, -apple-system, BlinkMacSystemFont, &#x27;Segoe UI&#x27;, Roboto, &#x27;Helvetica Neue&#x27;, Arial, sans-serif;font-size:16px;line-height:1.5"><div style="display:none;font-size:1px;line-height:1px;max-height:0;max-width:0;opacity:0;overflow:hidden">Your ToolCTRL subscription is active</div><div style="width:100%;max-width:560px;margin:0 auto;padding:24px 16px"><div style="background-color:#ffffff;border:1px solid #e2e8f0;border-radius:20px;padding:32px"><div style="padding-bottom:16px;text-align:left"><strong style="color:#0f172a;font-size:18px">ToolCTRL</strong></div><div style="color:#475569;font-size:13px;font-weight:700;letter-spacing:0.08em;text-transform:uppercase;margin-bottom:8px">Subscription</div><h1 style="margin:8px 0 16px;font-size:28px;line-height:1.2;color:#0f172a;font-weight:700">Thanks, Ada!</h1><p style="margin:0 0 24px;font-size:16px;line-height:1.6;color:#0f172a">Your Pro subscription is now active. Welcome aboard!</p><a href="https://app.example.com/billing" style="display:inline-block;background-color:#2563eb;color:#ffffff;padding:12px 22px;border-radius:999px;font-weight:700;font-size:15px;text-decoration:none" target="_blank" rel="noopener noreferrer">Open your dashboard</a><div style="margin-top:20px;padding:14px 16px;border-radius:10px;font-size:14px;line-height:1.55;background-color:#f1f5f9;color:#0f172a;border:1px solid #e2e8f0"><strong>Plan:</strong> Pro<br/><strong>Amount:</strong> $29.00<br/><strong>Next billing:</strong> 2026-06-01</div><p style="margin:24px 0 0;font-size:14px;line-height:1.6;color:#0f172a">Thanks,<br/>-<br/>ToolCTRL Support</p><div style="margin-top:24px;padding-top:16px;border-top:1px solid;font-size:12px;line-height:1.5;border-top-color:#e2e8f0;color:#475569"><div><a href="https://tool-ctrl.de/privacy" style="text-decoration:underline;color:#2563eb">Privacy</a><span style="margin:0 6px">·</span><a href="https://tool-ctrl.de/terms" style="text-decoration:underline;color:#2563eb">Terms</a><span style="margin:0 6px">·</span><a href="https://tool-ctrl.de/imprint" style="text-decoration:underline;color:#2563eb">Imprint</a></div><div style="margin-top:8px">Questions? Email us at <a href="mailto:info@tool-ctrl.de" style="text-decoration:underline;color:#2563eb">info@tool-ctrl.de</a>.</div></div></div></div></body></html>"`;
exports[`SubscriptionSuccessEmail > renders default snapshot with next-billing > text 1`] = `
"Your ToolCTRL subscription is active
ToolCTRL
Subscription
Thanks, Ada!
Your Pro subscription is now active. Welcome aboard!
Open your dashboard (https://app.example.com/billing)Plan: Pro
Amount: $29.00
Next billing: 2026-06-01
Thanks,
-
ToolCTRL Support
Privacy (https://tool-ctrl.de/privacy)·Terms (https://tool-ctrl.de/terms)·Imprint (https://tool-ctrl.de/imprint)
Questions? Email us at info@tool-ctrl.de (mailto:info@tool-ctrl.de)."
`;
@@ -0,0 +1,16 @@
// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
exports[`WelcomeEmail > renders default-brand named welcome (snapshot) > html 1`] = `"<!DOCTYPE html><html lang="en"><head><meta charSet="utf-8"/><meta name="viewport" content="width=device-width, initial-scale=1"/><title>Welcome to ToolCTRL, Ada!</title></head><body style="margin:0;padding:0;background-color:#f4f5f7;color:#0f172a;font-family:ui-sans-serif, -apple-system, BlinkMacSystemFont, &#x27;Segoe UI&#x27;, Roboto, &#x27;Helvetica Neue&#x27;, Arial, sans-serif;font-size:16px;line-height:1.5"><div style="display:none;font-size:1px;line-height:1px;max-height:0;max-width:0;opacity:0;overflow:hidden">Welcome to ToolCTRL, Ada!</div><div style="width:100%;max-width:560px;margin:0 auto;padding:24px 16px"><div style="background-color:#ffffff;border:1px solid #e2e8f0;border-radius:20px;padding:32px"><div style="padding-bottom:16px;text-align:left"><strong style="color:#0f172a;font-size:18px">ToolCTRL</strong></div><div style="color:#475569;font-size:13px;font-weight:700;letter-spacing:0.08em;text-transform:uppercase;margin-bottom:8px">Welcome</div><h1 style="margin:8px 0 16px;font-size:28px;line-height:1.2;color:#0f172a;font-weight:700">Welcome, Ada!</h1><p style="margin:0 0 24px;font-size:16px;line-height:1.6;color:#0f172a">Thanks for trying ToolCTRL.</p><a href="https://app.example.com/login" style="display:inline-block;background-color:#2563eb;color:#ffffff;padding:12px 22px;border-radius:999px;font-weight:700;font-size:15px;text-decoration:none" target="_blank" rel="noopener noreferrer">Click here to log in</a><p style="margin:24px 0 0;font-size:14px;line-height:1.6;color:#0f172a">Thanks,<br/>-<br/>ToolCTRL Support</p><div style="margin-top:24px;padding-top:16px;border-top:1px solid;font-size:12px;line-height:1.5;border-top-color:#e2e8f0;color:#475569"><div><a href="https://tool-ctrl.de/privacy" style="text-decoration:underline;color:#2563eb">Privacy</a><span style="margin:0 6px">·</span><a href="https://tool-ctrl.de/terms" style="text-decoration:underline;color:#2563eb">Terms</a><span style="margin:0 6px">·</span><a href="https://tool-ctrl.de/imprint" style="text-decoration:underline;color:#2563eb">Imprint</a></div><div style="margin-top:8px">Questions? Email us at <a href="mailto:info@tool-ctrl.de" style="text-decoration:underline;color:#2563eb">info@tool-ctrl.de</a>.</div></div></div></div></body></html>"`;
exports[`WelcomeEmail > renders default-brand named welcome (snapshot) > text 1`] = `
"Welcome to ToolCTRL, Ada!
ToolCTRL
Welcome
Welcome, Ada!
Thanks for trying ToolCTRL.
Click here to log in (https://app.example.com/login)Thanks,
-
ToolCTRL Support
Privacy (https://tool-ctrl.de/privacy)·Terms (https://tool-ctrl.de/terms)·Imprint (https://tool-ctrl.de/imprint)
Questions? Email us at info@tool-ctrl.de (mailto:info@tool-ctrl.de)."
`;
@@ -0,0 +1,90 @@
import type { CSSProperties, ReactNode } from "react";
import { BaseLayout } from "../_layout/BaseLayout.js";
import { Button } from "../_layout/Button.js";
import { Eyebrow } from "../_layout/Eyebrow.js";
import type { MailBrand } from "../_layout/theme.js";
/**
* Shared visual scaffold for all transactional templates.
*
* Every transactional email follows the same shape: eyebrow → headline →
* intro paragraph → CTA → optional outro paragraph → support sign-off.
* Concentrating that into one component keeps per-template files small
* and ensures brand-theme application is uniform.
*/
export interface TransactionalScaffoldProps {
readonly brand: MailBrand;
readonly subject: string;
readonly previewText?: string;
readonly eyebrow: string;
readonly title: string;
readonly intro: ReactNode;
readonly actionUrl: string;
readonly actionLabel: string;
readonly outro?: ReactNode;
readonly children?: ReactNode;
readonly unsubscribeUrl?: string;
readonly signoffThanks?: string;
}
const titleStyle = (brand: MailBrand): CSSProperties => ({
margin: "8px 0 16px",
fontSize: "28px",
lineHeight: 1.2,
color: brand.textColor,
fontWeight: 700,
});
const paragraphStyle = (brand: MailBrand): CSSProperties => ({
margin: "0 0 24px",
fontSize: "16px",
lineHeight: 1.6,
color: brand.textColor,
});
const outroStyle = (brand: MailBrand): CSSProperties => ({
margin: "24px 0 0",
fontSize: "14px",
lineHeight: 1.6,
color: brand.mutedTextColor,
});
const signoffStyle = (brand: MailBrand): CSSProperties => ({
margin: "24px 0 0",
fontSize: "14px",
lineHeight: 1.6,
color: brand.textColor,
});
export function TransactionalScaffold({
brand,
subject,
previewText,
eyebrow,
title,
intro,
actionUrl,
actionLabel,
outro,
children,
unsubscribeUrl,
signoffThanks,
}: TransactionalScaffoldProps) {
return (
<BaseLayout brand={brand} title={subject} previewText={previewText ?? subject} unsubscribeUrl={unsubscribeUrl}>
<Eyebrow brand={brand}>{eyebrow}</Eyebrow>
<h1 style={titleStyle(brand)}>{title}</h1>
<p style={paragraphStyle(brand)}>{intro}</p>
<Button brand={brand} href={actionUrl}>
{actionLabel}
</Button>
{outro ? <p style={outroStyle(brand)}>{outro}</p> : null}
{children}
<p style={signoffStyle(brand)}>
{signoffThanks ?? "Thanks,"}
<br />-<br />
{brand.supportFromName}
</p>
</BaseLayout>
);
}