Track HiveGrid Cloud planning reference

This commit is contained in:
david committed 2026-06-26 20:48:01 +02:00
1 parent b3d5ea6764
commit e341c5938a
5784 files changed
+1104929 -3

No files matched your search

@@ -0,0 +1,30 @@
{
"name": "@toolctrl/email-templates",
"version": "0.0.0",
"private": true,
"type": "module",
"sideEffects": false,
"exports": {
".": "./src/index.ts",
"./sequences/welcome": "./src/sequences/welcome.tsx",
"./sequences/trial-reminder": "./src/sequences/trial-reminder.tsx",
"./sequences/re-activation": "./src/sequences/re-activation.tsx",
"./sequences/generic-step": "./src/sequences/generic-step.tsx"
},
"scripts": {
"build": "pnpm run typecheck",
"test": "vitest run src",
"typecheck": "tsc -p tsconfig.json --noEmit"
},
"dependencies": {
"react": "19.2.3",
"react-dom": "19.2.3"
},
"devDependencies": {
"@types/node": "^25.0.0",
"@types/react": "^19.0.10",
"@types/react-dom": "^19.0.4",
"typescript": "^5.3.2",
"vitest": "^3.2.4"
}
}
@@ -0,0 +1,67 @@
import type { CSSProperties, ReactNode } from "react";
import { theme } from "../theme.js";
export interface LayoutProps {
readonly previewText?: string;
readonly title?: string;
readonly children: ReactNode;
readonly footer?: ReactNode;
}
const bodyStyle: CSSProperties = {
margin: 0,
padding: 0,
backgroundColor: theme.colors.background,
color: theme.colors.text,
fontFamily: theme.fontFamily,
fontSize: "16px",
lineHeight: "1.5",
};
const containerStyle: CSSProperties = {
width: "100%",
maxWidth: `${theme.containerWidth}px`,
margin: "0 auto",
padding: theme.spacing.md,
};
const cardStyle: CSSProperties = {
backgroundColor: theme.colors.surface,
border: `1px solid ${theme.colors.border}`,
borderRadius: theme.radius,
padding: theme.spacing.lg,
};
const previewStyle: CSSProperties = {
display: "none",
fontSize: "1px",
lineHeight: "1px",
maxHeight: 0,
maxWidth: 0,
opacity: 0,
overflow: "hidden",
msoHide: "all",
} as unknown as CSSProperties;
/**
* Top-level email layout. Renders a 600px centred card. The `previewText`
* is hidden but harvested by Gmail/Apple Mail as the inbox snippet.
*/
export function Layout({ previewText, title, children, footer }: LayoutProps) {
return (
<html lang="en">
<head>
<meta charSet="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
{title ? <title>{title}</title> : null}
</head>
<body style={bodyStyle}>
{previewText ? <div style={previewStyle}>{previewText}</div> : null}
<div style={containerStyle}>
<div style={cardStyle}>{children}</div>
{footer ? <div style={{ padding: `${theme.spacing.md} 0`, color: theme.colors.muted, fontSize: "13px", textAlign: "center" }}>{footer}</div> : null}
</div>
</body>
</html>
);
}
@@ -0,0 +1,62 @@
import type { CSSProperties, ReactNode } from "react";
import { theme } from "../theme.js";
export function Heading({ children, level = 1 }: { children: ReactNode; level?: 1 | 2 | 3 }) {
const sizes = { 1: "26px", 2: "20px", 3: "17px" } as const;
const style: CSSProperties = {
margin: `${theme.spacing.sm} 0`,
color: theme.colors.text,
fontSize: sizes[level],
fontWeight: 600,
lineHeight: "1.2",
};
if (level === 1) return <h1 style={style}>{children}</h1>;
if (level === 2) return <h2 style={style}>{children}</h2>;
return <h3 style={style}>{children}</h3>;
}
export function Paragraph({ children }: { children: ReactNode }) {
const style: CSSProperties = {
margin: `${theme.spacing.sm} 0`,
color: theme.colors.text,
fontSize: "16px",
lineHeight: "1.55",
};
return <p style={style}>{children}</p>;
}
export function Spacer({ size = "md" }: { size?: keyof typeof theme.spacing }) {
return <div style={{ height: theme.spacing[size] }} />;
}
export interface ButtonProps {
readonly href: string;
readonly children: ReactNode;
}
export function Button({ href, children }: ButtonProps) {
const style: CSSProperties = {
display: "inline-block",
backgroundColor: theme.colors.primary,
color: theme.colors.primaryText,
padding: "12px 22px",
borderRadius: theme.radius,
fontWeight: 600,
fontSize: "15px",
textDecoration: "none",
};
return (
<a href={href} style={style} target="_blank" rel="noreferrer">
{children}
</a>
);
}
export function Footer({ children }: { children: ReactNode }) {
const style: CSSProperties = {
color: theme.colors.muted,
fontSize: "12px",
lineHeight: "1.5",
};
return <div style={style}>{children}</div>;
}
@@ -0,0 +1,37 @@
/**
* Marketing-Funnel Phase 3 email-template package (Phase 05 #80).
*
* Ships pre-built React-Email-style templates for the sequence engine.
* `renderEmail(<Template props />)` returns `{ html, text }` ready for
* any `@toolctrl/mail` `SendMailInput`. Theme tokens + layout primitives
* are reusable for additional sequences operators define in the admin
* UI (when wired to a runtime template-registry).
*/
export { theme } from "./theme.js";
export type { EmailTheme } from "./theme.js";
export { Layout } from "./components/Layout.js";
export type { LayoutProps } from "./components/Layout.js";
export {
Heading,
Paragraph,
Spacer,
Button,
Footer,
type ButtonProps,
} from "./components/primitives.js";
export { renderEmail, htmlToPlainText, type RenderedEmail } from "./render.js";
export { WelcomeEmail, type WelcomeEmailProps } from "./sequences/welcome.js";
export {
TrialReminderEmail,
type TrialReminderEmailProps,
} from "./sequences/trial-reminder.js";
export {
ReActivationEmail,
type ReActivationEmailProps,
} from "./sequences/re-activation.js";
export {
GenericStepEmail,
type GenericStepEmailProps,
} from "./sequences/generic-step.js";
@@ -0,0 +1,241 @@
import { describe, it, expect } from "vitest";
import { htmlToPlainText, renderEmail } from "./render.js";
import { WelcomeEmail } from "./sequences/welcome.js";
import { TrialReminderEmail } from "./sequences/trial-reminder.js";
import { ReActivationEmail } from "./sequences/re-activation.js";
import { GenericStepEmail } from "./sequences/generic-step.js";
const COMMON = {
productName: "ToolCtrl",
unsubscribeUrl: "https://app.example.com/unsubscribe/tok",
} as const;
describe("renderEmail", () => {
it("renders a welcome email with html + text", () => {
const { html, text } = renderEmail(
WelcomeEmail({
productName: COMMON.productName,
ctaUrl: "https://app.example.com/onboard",
unsubscribeUrl: COMMON.unsubscribeUrl,
recipientName: "Ada",
})
);
expect(html.startsWith("<!DOCTYPE html>")).toBe(true);
expect(html).toContain("Welcome to ToolCtrl");
expect(html).toContain("Ada");
expect(html).toContain("https://app.example.com/onboard");
expect(text).toContain("Welcome to ToolCtrl");
expect(text).toContain("Hi Ada");
});
it("allows welcome chrome copy to be supplied by the caller", () => {
const { html, text } = renderEmail(
WelcomeEmail({
productName: COMMON.productName,
ctaUrl: "https://app.example.com/onboard",
unsubscribeUrl: COMMON.unsubscribeUrl,
copy: {
defaultCta: "Loslegen",
fallbackRecipient: "du",
preview: (productName) => `Willkommen bei ${productName}`,
title: (productName) => `Willkommen bei ${productName}`,
footerReason: (productName) => `Du bekommst diese E-Mail wegen deiner Registrierung bei ${productName}.`,
unsubscribe: "Abmelden",
heading: (productName) => `Willkommen bei ${productName}`,
greeting: (recipientName) => `Hallo ${recipientName},`,
intro: (productName) => `${productName} hilft deinem Team beim Automatisieren.`,
replyPrompt: "Antworte auf diese E-Mail, wenn du Fragen hast.",
signoff: (_senderName, productName) => `Dein ${productName} Team`,
},
})
);
expect(html).toContain("Loslegen");
expect(html).toContain("Abmelden");
expect(text).toContain("Hallo du,");
expect(text).toContain("Dein ToolCtrl Team");
});
it("renders trial-reminder with correct day-pluralisation", () => {
const single = renderEmail(
TrialReminderEmail({
productName: COMMON.productName,
daysRemaining: 1,
upgradeUrl: "https://app.example.com/upgrade",
unsubscribeUrl: COMMON.unsubscribeUrl,
})
);
expect(single.html).toContain("1 day left");
const multi = renderEmail(
TrialReminderEmail({
productName: COMMON.productName,
daysRemaining: 3,
upgradeUrl: "https://app.example.com/upgrade",
unsubscribeUrl: COMMON.unsubscribeUrl,
})
);
expect(multi.html).toContain("3 days left");
});
it("allows trial-reminder copy to be supplied by the caller", () => {
const { html, text } = renderEmail(
TrialReminderEmail({
productName: COMMON.productName,
daysRemaining: 2,
upgradeUrl: "https://app.example.com/upgrade",
unsubscribeUrl: COMMON.unsubscribeUrl,
copy: {
daySingular: "Tag",
dayPlural: "Tage",
fallbackRecipient: "du",
preview: (productName, daysRemaining, dayWord) => `${productName} endet in ${daysRemaining} ${dayWord}`,
title: (daysRemaining, dayWord) => `${daysRemaining} ${dayWord} verbleiben`,
footerReason: (productName) => `Trial-Erinnerung von ${productName}.`,
unsubscribe: "Abmelden",
heading: (daysRemaining, dayWord) => `${daysRemaining} ${dayWord} im Trial`,
greeting: (recipientName) => `Hallo ${recipientName},`,
intro: (productName, daysRemaining, dayWord) => `Dein ${productName} Trial endet in ${daysRemaining} ${dayWord}.`,
defaultCta: "Plan upgraden",
extensionPrompt: "Antworte auf diese E-Mail, wenn du mehr Zeit brauchst.",
},
})
);
expect(html).toContain("Plan upgraden");
expect(html).toContain("Abmelden");
expect(text).toContain("Hallo du,");
expect(text).toContain("2 Tage im Trial");
});
it("renders re-activation with optional highlight", () => {
const withHighlight = renderEmail(
ReActivationEmail({
productName: COMMON.productName,
returnUrl: "https://app.example.com/back",
highlight: "we shipped Plugin v2",
unsubscribeUrl: COMMON.unsubscribeUrl,
})
);
expect(withHighlight.html).toContain("we shipped Plugin v2");
const noHighlight = renderEmail(
ReActivationEmail({
productName: COMMON.productName,
returnUrl: "https://app.example.com/back",
unsubscribeUrl: COMMON.unsubscribeUrl,
})
);
expect(noHighlight.html).not.toContain("What is new");
});
it("allows re-activation copy to be supplied by the caller", () => {
const { html, text } = renderEmail(
ReActivationEmail({
productName: COMMON.productName,
returnUrl: "https://app.example.com/back",
highlight: "wir haben Automationen verbessert",
unsubscribeUrl: COMMON.unsubscribeUrl,
copy: {
fallbackRecipient: "du",
preview: (productName) => `Zurueck zu ${productName}`,
title: (productName) => `Zurueck zu ${productName}`,
footerReason: (productName) => `Du hattest dich bei ${productName} registriert.`,
unsubscribe: "Abmelden",
heading: (productName) => `Zurueck zu ${productName}`,
greeting: (recipientName) => `Hallo ${recipientName},`,
intro: (productName) => `Seit deinem letzten Besuch bei ${productName} hat sich viel getan.`,
highlightLabel: "Neu:",
defaultCta: "Nochmal ansehen",
replyPrompt: "Antworte mit deinem wichtigsten Wunsch.",
},
})
);
expect(html).toContain("Nochmal ansehen");
expect(html).toContain("Abmelden");
expect(text).toContain("Hallo du,");
expect(text).toContain("Neu: wir haben Automationen verbessert");
});
it("renders generic-step with multiple body paragraphs and CTA", () => {
const { html, text } = renderEmail(
GenericStepEmail({
productName: COMMON.productName,
headline: "Day 3: your first automation",
bodyParagraphs: ["First paragraph here.", "Second paragraph follows."],
ctaUrl: "https://app.example.com/setup",
unsubscribeUrl: COMMON.unsubscribeUrl,
})
);
expect(html).toContain("Day 3: your first automation");
expect(html).toContain("First paragraph here.");
expect(html).toContain("Second paragraph follows.");
expect(text).toContain("First paragraph here.");
expect(text).toContain("Second paragraph follows.");
});
it("allows generic-step chrome copy to be supplied by the caller", () => {
const { html, text } = renderEmail(
GenericStepEmail({
productName: COMMON.productName,
headline: "Day 4",
bodyParagraphs: ["Localized body."],
ctaUrl: "https://app.example.com/setup",
unsubscribeUrl: COMMON.unsubscribeUrl,
copy: {
defaultCta: "Zum Dashboard",
fallbackRecipient: "du",
footerReason: (productName) => `Du bekommst diese E-Mail wegen deiner Registrierung bei ${productName}.`,
unsubscribe: "Abmelden",
greeting: (recipientName) => `Hallo ${recipientName},`,
signoff: (productName) => `Dein ${productName} Team`,
},
})
);
expect(html).toContain("Zum Dashboard");
expect(html).toContain("Abmelden");
expect(text).toContain("Hallo du,");
expect(text).toContain("Dein ToolCtrl Team");
});
it("escapes user-provided variables (no XSS via recipientName)", () => {
const { html } = renderEmail(
WelcomeEmail({
productName: COMMON.productName,
ctaUrl: "https://app.example.com/onboard",
unsubscribeUrl: COMMON.unsubscribeUrl,
recipientName: "<script>alert(1)</script>",
})
);
expect(html).not.toContain("<script>alert(1)</script>");
expect(html).toContain("&lt;script&gt;alert(1)&lt;/script&gt;");
});
it("emits unsubscribe URL in every sequence template", () => {
const url = "https://app.example.com/unsubscribe/abc";
for (const tpl of [
WelcomeEmail({ productName: "X", ctaUrl: "https://e.com/a", unsubscribeUrl: url }),
TrialReminderEmail({ productName: "X", daysRemaining: 7, upgradeUrl: "https://e.com/u", unsubscribeUrl: url }),
ReActivationEmail({ productName: "X", returnUrl: "https://e.com/r", unsubscribeUrl: url }),
GenericStepEmail({ productName: "X", headline: "h", bodyParagraphs: ["p"], unsubscribeUrl: url }),
]) {
const { html } = renderEmail(tpl);
expect(html).toContain(url);
}
});
});
describe("htmlToPlainText", () => {
it("preserves anchor URLs as text", () => {
const text = htmlToPlainText('<p>click <a href="https://x.example.com/y">here</a> now</p>');
expect(text).toContain("here (https://x.example.com/y)");
});
it("collapses excess whitespace and strips scripts/styles", () => {
const text = htmlToPlainText("<style>body{}</style><h1>A</h1><script>X</script><p>B</p>");
expect(text).toContain("A");
expect(text).toContain("B");
expect(text).not.toContain("body{}");
expect(text).not.toContain("<");
});
});
@@ -0,0 +1,57 @@
/**
* Render-helper for sequence templates.
*
* Uses `react-dom/server.renderToStaticMarkup` (already a runtime dep of
* the web app) to emit a self-contained HTML document plus a flat text
* fallback for clients that prefer text/plain. We intentionally avoid the
* full `react-email` package here — that migration is task #75 and
* pulling it forward in V1 would force a 60+MB dep tree onto every worker
* image. See docs/improvement-plan/05-business-features/marketing-funnel-phase-3.md.
*/
import type { ReactElement } from "react";
import { renderToStaticMarkup } from "react-dom/server";
export interface RenderedEmail {
readonly html: string;
readonly text: string;
}
/**
* Convert HTML to a usable plain-text fallback. Strips tags and collapses
* whitespace while preserving anchor URLs as `[text] (url)` for clients
* that fall back to the text alternative.
*/
export function htmlToPlainText(html: string): string {
// Preserve anchor URLs in the text fallback before stripping tags.
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(/<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 renderEmail(element: ReactElement): RenderedEmail {
const body = renderToStaticMarkup(element);
const html = `<!DOCTYPE html>${body}`;
const text = htmlToPlainText(body);
return { html, text };
}
@@ -0,0 +1,86 @@
import type { ReactNode } from "react";
import { Layout } from "../components/Layout.js";
import { Button, Footer, Heading, Paragraph, Spacer } from "../components/primitives.js";
export interface GenericStepEmailCopy {
readonly defaultCta: string;
readonly fallbackRecipient: string;
readonly footerReason: (productName: string) => ReactNode;
readonly unsubscribe: string;
readonly greeting: (recipientName: string) => ReactNode;
readonly signoff: (productName: string) => ReactNode;
}
export interface GenericStepEmailProps {
readonly recipientName?: string;
readonly productName: string;
readonly headline: string;
/**
* Body paragraphs. Each entry is rendered as a separate <Paragraph>.
* Markdown is intentionally NOT supported here — the admin UI passes
* plain text and trusted variables only.
*/
readonly bodyParagraphs: readonly string[];
readonly ctaUrl?: string;
readonly ctaLabel?: string;
readonly unsubscribeUrl: string;
readonly preface?: ReactNode;
readonly copy?: Partial<GenericStepEmailCopy>;
}
const defaultCopy: GenericStepEmailCopy = {
defaultCta: "Open dashboard",
fallbackRecipient: "there",
footerReason: (productName) => `You receive this email because you signed up at ${productName}.`,
unsubscribe: "Unsubscribe",
greeting: (recipientName) => `Hi ${recipientName},`,
signoff: (productName) => `\u2014 The ${productName} team`,
};
/**
* Configurable step template used for the onboarding-drip and for any
* generic-step in an operator-defined sequence. Variables are passed
* pre-substituted by the engine; React escapes everything it renders
* so there is no XSS risk from PII in `bodyParagraphs`.
*/
export function GenericStepEmail({
recipientName,
productName,
headline,
bodyParagraphs,
ctaUrl,
ctaLabel,
unsubscribeUrl,
preface,
copy,
}: GenericStepEmailProps) {
const resolvedCopy = { ...defaultCopy, ...copy };
const greetingTarget = recipientName?.trim() || resolvedCopy.fallbackRecipient;
return (
<Layout
previewText={headline}
title={headline}
footer={
<Footer>
{resolvedCopy.footerReason(productName)}<br />
<a href={unsubscribeUrl}>{resolvedCopy.unsubscribe}</a>
</Footer>
}
>
<Heading level={1}>{headline}</Heading>
<Paragraph>{resolvedCopy.greeting(greetingTarget)}</Paragraph>
{preface ?? null}
{bodyParagraphs.map((line, idx) => (
<Paragraph key={idx}>{line}</Paragraph>
))}
{ctaUrl ? (
<>
<Spacer size="md" />
<Button href={ctaUrl}>{ctaLabel ?? resolvedCopy.defaultCta}</Button>
<Spacer size="md" />
</>
) : null}
<Paragraph>{resolvedCopy.signoff(productName)}</Paragraph>
</Layout>
);
}
@@ -0,0 +1,83 @@
import type { ReactNode } from "react";
import { Layout } from "../components/Layout.js";
import { Button, Footer, Heading, Paragraph, Spacer } from "../components/primitives.js";
export interface ReActivationEmailCopy {
readonly fallbackRecipient: string;
readonly preview: (productName: string) => string;
readonly title: (productName: string) => string;
readonly footerReason: (productName: string) => ReactNode;
readonly unsubscribe: string;
readonly heading: (productName: string) => ReactNode;
readonly greeting: (recipientName: string) => ReactNode;
readonly intro: (productName: string) => ReactNode;
readonly highlightLabel: ReactNode;
readonly defaultCta: string;
readonly replyPrompt: ReactNode;
}
export interface ReActivationEmailProps {
readonly recipientName?: string;
readonly productName: string;
readonly returnUrl: string;
readonly highlight?: string;
readonly unsubscribeUrl: string;
readonly copy?: Partial<ReActivationEmailCopy>;
}
const defaultCopy: ReActivationEmailCopy = {
fallbackRecipient: "there",
preview: (productName) => `We miss you at ${productName}`,
title: (productName) => `We miss you at ${productName}`,
footerReason: (productName) => `We sent this because you previously signed up at ${productName}.`,
unsubscribe: "Unsubscribe",
heading: (productName) => `We miss you at ${productName}`,
greeting: (recipientName) => `Hi ${recipientName},`,
intro: (productName) => `It has been a while since we last saw you at ${productName}. A lot has changed since then.`,
highlightLabel: "What is new:",
defaultCta: "Take another look",
replyPrompt:
"If we are no longer the right fit, no hard feelings - reply with the one feature you wished we had and we will note it.",
};
/**
* "Lost Lead Re-Activation" — triggered by the daily stale-lead cron
* (`lead.stale_60d`). Highlights one new thing since the lead went
* dark and offers a single high-intent CTA to come back.
*/
export function ReActivationEmail({
recipientName,
productName,
returnUrl,
highlight,
unsubscribeUrl,
copy,
}: ReActivationEmailProps) {
const resolvedCopy = { ...defaultCopy, ...copy };
const greetingTarget = recipientName?.trim() || resolvedCopy.fallbackRecipient;
return (
<Layout
previewText={resolvedCopy.preview(productName)}
title={resolvedCopy.title(productName)}
footer={
<Footer>
{resolvedCopy.footerReason(productName)}<br />
<a href={unsubscribeUrl}>{resolvedCopy.unsubscribe}</a>
</Footer>
}
>
<Heading level={1}>{resolvedCopy.heading(productName)}</Heading>
<Paragraph>{resolvedCopy.greeting(greetingTarget)}</Paragraph>
<Paragraph>{resolvedCopy.intro(productName)}</Paragraph>
{highlight ? (
<Paragraph>
<strong>{resolvedCopy.highlightLabel}</strong> {highlight}
</Paragraph>
) : null}
<Spacer size="md" />
<Button href={returnUrl}>{resolvedCopy.defaultCta}</Button>
<Spacer size="md" />
<Paragraph>{resolvedCopy.replyPrompt}</Paragraph>
</Layout>
);
}
@@ -0,0 +1,85 @@
import type { ReactNode } from "react";
import { Layout } from "../components/Layout.js";
import { Button, Footer, Heading, Paragraph, Spacer } from "../components/primitives.js";
export interface TrialReminderEmailCopy {
readonly daySingular: string;
readonly dayPlural: string;
readonly fallbackRecipient: string;
readonly preview: (productName: string, daysRemaining: number, dayWord: string) => string;
readonly title: (daysRemaining: number, dayWord: string) => string;
readonly footerReason: (productName: string) => ReactNode;
readonly unsubscribe: string;
readonly heading: (daysRemaining: number, dayWord: string) => ReactNode;
readonly greeting: (recipientName: string) => ReactNode;
readonly intro: (productName: string, daysRemaining: number, dayWord: string) => ReactNode;
readonly defaultCta: string;
readonly extensionPrompt: ReactNode;
}
export interface TrialReminderEmailProps {
readonly recipientName?: string;
readonly productName: string;
readonly daysRemaining: number;
readonly upgradeUrl: string;
readonly unsubscribeUrl: string;
readonly copy?: Partial<TrialReminderEmailCopy>;
}
const defaultCopy: TrialReminderEmailCopy = {
daySingular: "day",
dayPlural: "days",
fallbackRecipient: "there",
preview: (productName, daysRemaining, dayWord) => `Your ${productName} trial ends in ${daysRemaining} ${dayWord}`,
title: (daysRemaining, dayWord) => `Trial reminder - ${daysRemaining} ${dayWord} left`,
footerReason: (productName) => `Trial reminder from ${productName}.`,
unsubscribe: "Unsubscribe",
heading: (daysRemaining, dayWord) => `${daysRemaining} ${dayWord} left in your trial`,
greeting: (recipientName) => `Hi ${recipientName},`,
intro: (productName, daysRemaining, dayWord) => (
<>
Your {productName} trial ends in <strong>{daysRemaining} {dayWord}</strong>.
Upgrade now to keep your data, integrations and saved workflows.
</>
),
defaultCta: "Upgrade my plan",
extensionPrompt: "Need more time? Reply to this email and we will extend your trial - no questions asked.",
};
/**
* "Trial Expiring" — triggered by `tenant.trial_expiring`. The
* sequence schedules 3 steps (7d, 3d, 1d before expiry) with the same
* template but different `daysRemaining` values.
*/
export function TrialReminderEmail({
recipientName,
productName,
daysRemaining,
upgradeUrl,
unsubscribeUrl,
copy,
}: TrialReminderEmailProps) {
const resolvedCopy = { ...defaultCopy, ...copy };
const greetingTarget = recipientName?.trim() || resolvedCopy.fallbackRecipient;
const dayWord = daysRemaining === 1 ? resolvedCopy.daySingular : resolvedCopy.dayPlural;
return (
<Layout
previewText={resolvedCopy.preview(productName, daysRemaining, dayWord)}
title={resolvedCopy.title(daysRemaining, dayWord)}
footer={
<Footer>
{resolvedCopy.footerReason(productName)}<br />
<a href={unsubscribeUrl}>{resolvedCopy.unsubscribe}</a>
</Footer>
}
>
<Heading level={1}>{resolvedCopy.heading(daysRemaining, dayWord)}</Heading>
<Paragraph>{resolvedCopy.greeting(greetingTarget)}</Paragraph>
<Paragraph>{resolvedCopy.intro(productName, daysRemaining, dayWord)}</Paragraph>
<Spacer size="md" />
<Button href={upgradeUrl}>{resolvedCopy.defaultCta}</Button>
<Spacer size="md" />
<Paragraph>{resolvedCopy.extensionPrompt}</Paragraph>
</Layout>
);
}
@@ -0,0 +1,81 @@
import type { ReactNode } from "react";
import { Layout } from "../components/Layout.js";
import { Button, Footer, Heading, Paragraph, Spacer } from "../components/primitives.js";
export interface WelcomeEmailCopy {
readonly defaultCta: string;
readonly fallbackRecipient: string;
readonly preview: (productName: string) => string;
readonly title: (productName: string) => string;
readonly footerReason: (productName: string) => ReactNode;
readonly unsubscribe: string;
readonly heading: (productName: string) => ReactNode;
readonly greeting: (recipientName: string) => ReactNode;
readonly intro: (productName: string) => ReactNode;
readonly replyPrompt: ReactNode;
readonly signoff: (senderName: string | undefined, productName: string) => ReactNode;
}
export interface WelcomeEmailProps {
readonly recipientName?: string;
readonly productName: string;
readonly ctaUrl: string;
readonly ctaLabel?: string;
readonly unsubscribeUrl: string;
readonly senderName?: string;
readonly copy?: Partial<WelcomeEmailCopy>;
}
const defaultCopy: WelcomeEmailCopy = {
defaultCta: "Get started",
fallbackRecipient: "there",
preview: (productName) => `Welcome to ${productName} - here is what to do next`,
title: (productName) => `Welcome to ${productName}`,
footerReason: (productName) => `You received this email because you signed up at ${productName}.`,
unsubscribe: "Unsubscribe",
heading: (productName) => `Welcome to ${productName}`,
greeting: (recipientName) => `Hi ${recipientName},`,
intro: (productName) =>
`Thanks for joining ${productName}. We help teams ship faster by automating the work that does not need a human. Click the button below to take the first step.`,
replyPrompt: "Reply to this email if you have any questions - a real person is on the other end.",
signoff: (senderName, productName) => `\u2014 ${senderName ?? `The ${productName} team`}`,
};
/**
* "New Lead Welcome" — day-0 introduction email triggered by
* `lead.captured`. Subsequent steps of the same sequence reuse
* `GenericStepEmail` for body variants.
*/
export function WelcomeEmail({
recipientName,
productName,
ctaUrl,
ctaLabel,
unsubscribeUrl,
senderName,
copy,
}: WelcomeEmailProps) {
const resolvedCopy = { ...defaultCopy, ...copy };
const greetingTarget = recipientName?.trim() || resolvedCopy.fallbackRecipient;
return (
<Layout
previewText={resolvedCopy.preview(productName)}
title={resolvedCopy.title(productName)}
footer={
<Footer>
{resolvedCopy.footerReason(productName)}<br />
<a href={unsubscribeUrl}>{resolvedCopy.unsubscribe}</a>
</Footer>
}
>
<Heading level={1}>{resolvedCopy.heading(productName)}</Heading>
<Paragraph>{resolvedCopy.greeting(greetingTarget)}</Paragraph>
<Paragraph>{resolvedCopy.intro(productName)}</Paragraph>
<Spacer size="md" />
<Button href={ctaUrl}>{ctaLabel ?? resolvedCopy.defaultCta}</Button>
<Spacer size="md" />
<Paragraph>{resolvedCopy.replyPrompt}</Paragraph>
<Paragraph>{resolvedCopy.signoff(senderName, productName)}</Paragraph>
</Layout>
);
}
@@ -0,0 +1,35 @@
/**
* Marketing-Funnel Phase 3 — email-template theme tokens.
*
* Inline-style values only. Email clients (Outlook, Gmail in particular)
* strip <style> blocks and external CSS, so every visual primitive in
* this package emits raw inline `style` attributes. Keep this list short
* and aligned with the brand palette in `packages/brand`.
*/
export const theme = {
colors: {
background: "#f4f5f7",
surface: "#ffffff",
text: "#0f172a",
muted: "#475569",
primary: "#2563eb",
primaryText: "#ffffff",
border: "#e2e8f0",
danger: "#dc2626",
},
fontFamily:
"ui-sans-serif, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif",
spacing: {
none: "0",
xs: "8px",
sm: "12px",
md: "20px",
lg: "32px",
xl: "48px",
},
radius: "6px",
containerWidth: 600,
} as const;
export type EmailTheme = typeof theme;
@@ -0,0 +1,14 @@
{
"extends": "../../tsconfig.json",
"compilerOptions": {
"allowJs": false,
"allowImportingTsExtensions": false,
"lib": ["ES2022", "DOM"],
"module": "NodeNext",
"moduleResolution": "NodeNext",
"noEmit": true,
"jsx": "react-jsx",
"types": ["node", "vitest/globals"]
},
"include": ["src/**/*.ts", "src/**/*.tsx"]
}