@openlup/platform 0.15.0 → 0.17.0

package/src/communications/contracts/subscriptionEmailContent.ts

@@ -0,0 +1,163 @@
+import type { Locale } from "./email.js";
+
+type Localized<T> = Readonly<Record<Locale, T>>;
+
+export interface SubscriptionBaseCopy {
+  subject: string;
+  preheader: string;
+  heading: string;
+  greeting: (firstName: string | null) => string;
+}
+
+export interface SubscriptionActionCopy extends SubscriptionBaseCopy {
+  intro: string;
+  reassurance: string[];
+  cta: string;
+  outro: string;
+}
+
+export interface SubscriptionActivationCopy extends SubscriptionBaseCopy {
+  intro: string;
+  facts: string[];
+  cta: string;
+  outro: string;
+}
+
+export interface SubscriptionScheduleCopy extends SubscriptionBaseCopy {
+  subjectWithoutDates: string;
+  intro: string;
+  introWithoutDates: string;
+  deliveryLabel: string;
+  chargeLabel: string;
+  dateLine: (window: string, chargeDate: string) => string;
+  reassurance: string[];
+  cta: string;
+  outro: string;
+}
+
+export interface SubscriptionPackageChangedCopy extends SubscriptionBaseCopy {
+  intro: (actionLabel: string | null) => string;
+  reassurance: string[];
+  actionLabels: Readonly<Record<string, string>>;
+  cta: string;
+  outro: string;
+}
+
+export interface SubscriptionPauseReminderCopy extends SubscriptionBaseCopy {
+  intro: (brandName: string) => string;
+  resume: (resumeDate: string) => string;
+  reassurance: string[];
+  cta: string;
+  outro: string;
+}
+
+export interface SubscriptionPausedCopy extends SubscriptionBaseCopy {
+  intro: string;
+  reassurance: (brandName: string) => string[];
+  cta: string;
+  outro: string;
+}
+
+export interface SubscriptionRenewalUpcomingCopy extends SubscriptionBaseCopy {
+  intro: (contextName: string | null) => string;
+  dateLine: (label: string) => string;
+  deliveryLine: (window: string) => string;
+  editCutoffLine: (label: string) => string;
+  noDateLine: string;
+  amountLine: (label: string) => string;
+  starterGraduationLine: (units: number, cadenceDays: number, detail?: string | null) => string;
+  detailsLabel: string;
+  manageLine: string;
+  cta: string;
+}
+
+export interface SubscriptionResumedCopy extends SubscriptionBaseCopy {
+  intro: (contextName: string | null) => string;
+  reassurance: (brandName: string) => string[];
+  cta: string;
+  outro: string;
+}
+
+export interface SubscriptionWelcomeCopy extends SubscriptionBaseCopy {
+  intro: string;
+  cadenceLine: (days: number) => string;
+  deliveryLine: (window: string, chargeDate: string) => string;
+  editCutoffLine: (label: string) => string;
+  fallbackLine: string;
+  starterDelivery2Line: (amount: string) => string;
+  starterSteadyLine: (units: number, cadenceDays: number, detail?: string | null) => string;
+  detailsLabel: string;
+  manageLine: string;
+  cta: string;
+  outro: string;
+}
+
+export interface SubscriptionWinbackCopy extends SubscriptionBaseCopy {
+  intro: string;
+  reasonsLabel?: (brandName: string) => string;
+  reasons: string[];
+  cta: string;
+  outro: string;
+}
+
+export interface SubscriptionPaymentExpiredCopy extends SubscriptionBaseCopy {
+  preheaderWithCta: string;
+  intro: string;
+  detail: (amountLabel: string | null) => string[];
+  ctaDetail: string;
+  cta: string;
+  outro: string;
+}
+
+export interface SubscriptionPaymentFailedCopy extends SubscriptionBaseCopy {
+  intro: string;
+  amountLine: (amountLabel: string) => string;
+  noAmountLine: string;
+  noAmountLineNoRetry: string;
+  methodLine: (scheme: string, lastDigits: string) => string;
+  reassurance: (attempt: number, dateLabel: string | null) => string;
+  noRetryAction: string;
+  cta: string;
+  outro: string;
+}
+
+export interface SubscriptionPaymentRecoveredCopy extends SubscriptionBaseCopy {
+  intro: string;
+  detail: (amountLabel: string | null) => string[];
+  outro: string;
+}
+
+export interface SubscriptionRenewalAtRiskCopy extends SubscriptionBaseCopy {
+  intro: (renewalDateLabel: string | null) => string;
+  consequence: string;
+  cta: string;
+  outro: string;
+}
+
+export interface SubscriptionLifecycleEmailContent {
+  activationActionRequired: Localized<SubscriptionActivationCopy>;
+  addressChanged: Localized<SubscriptionActionCopy>;
+  cancelled: Localized<SubscriptionActionCopy>;
+  cycleSkipped: Localized<SubscriptionScheduleCopy & { manageLine: string }>;
+  deliveryRescheduled: Localized<SubscriptionScheduleCopy>;
+  packageChanged: Localized<SubscriptionPackageChangedCopy>;
+  pauseReminder: Localized<SubscriptionPauseReminderCopy>;
+  paused: Localized<SubscriptionPausedCopy>;
+  renewalUpcoming: Localized<SubscriptionRenewalUpcomingCopy>;
+  resumed: Localized<SubscriptionResumedCopy>;
+  welcome: Localized<SubscriptionWelcomeCopy>;
+  winback: Localized<SubscriptionWinbackCopy>;
+}
+
+export interface SubscriptionDunningEmailContent {
+  paymentExpired: Localized<SubscriptionPaymentExpiredCopy>;
+  paymentFailed: Localized<SubscriptionPaymentFailedCopy>;
+  paymentRecovered: Localized<SubscriptionPaymentRecoveredCopy>;
+  renewalAtRisk: Localized<SubscriptionRenewalAtRiskCopy>;
+}
+
+export interface SubscriptionEmailContent
+  extends SubscriptionLifecycleEmailContent,
+    SubscriptionDunningEmailContent {
+  id: "example" | "deployment-overlay";
+}

package/src/communications/contracts/subscriptionPackageChanged.ts

@@ -0,0 +1,59 @@
+import type { SubscriptionEmailContent } from "./subscriptionEmailContent.js";
+import type { Locale } from "./email.js";
+import type { SubscriptionPackageChangedCopy } from "./subscriptionEmailContent.js";
+import {
+  accentBox,
+  button,
+  heading,
+  paragraph,
+  type EmailBlock,
+} from "./blocks.js";
+
+export interface SubscriptionPackageChangedEmailVars {
+  firstName: string | null;
+  action?: string | null;
+  /** Absolute CTA URL (manage subscription); null/absent → no button. */
+  ctaUrl?: string | null;
+}
+
+export interface SubscriptionPackageChangedEmailContent {
+  subject: string;
+  preheader: string;
+  blocks: EmailBlock[];
+}
+
+/** Bind host-selected copy and pure helpers without provider or environment access. */
+export function createSubscriptionPackageChangedContentFactory(input: {
+  subscriptionEmailContent: Pick<SubscriptionEmailContent, "packageChanged">;
+}) {
+  const { subscriptionEmailContent } = input;
+
+  function subscriptionPackageChangedEmailContent(
+    locale: Locale,
+    vars: SubscriptionPackageChangedEmailVars,
+    signoff: string,
+  ): SubscriptionPackageChangedEmailContent {
+    const copy: SubscriptionPackageChangedCopy = subscriptionEmailContent.packageChanged[locale];
+    const actionLabel = vars.action ? copy.actionLabels[vars.action] ?? null : null;
+    const blocks: EmailBlock[] = [
+      heading(copy.heading),
+      paragraph(copy.greeting(vars.firstName)),
+      paragraph(copy.intro(actionLabel)),
+      accentBox(copy.reassurance),
+    ];
+
+    if (vars.ctaUrl) {
+      blocks.push(button(copy.cta, vars.ctaUrl));
+    }
+
+    blocks.push(paragraph(copy.outro));
+    blocks.push(paragraph(signoff));
+
+    return {
+      subject: copy.subject,
+      preheader: copy.preheader,
+      blocks,
+    };
+  }
+  return { subscriptionPackageChangedEmailContent };
+}

package/src/communications/contracts/subscriptionPauseReminder.ts

@@ -0,0 +1,63 @@
+import type { SubscriptionEmailContent } from "./subscriptionEmailContent.js";
+import type { Locale } from "./email.js";
+import {
+  accentBox,
+  button,
+  heading,
+  paragraph,
+  type EmailBlock,
+} from "./blocks.js";
+
+export interface SubscriptionPauseReminderEmailVars {
+  firstName: string | null;
+  /** Consumer-facing brand label injected by the app/composition root. */
+  brandName: string;
+  /** Pre-formatted resume date, or null when unknown. */
+  resumeDateLabel: string | null;
+  /** Absolute CTA URL to manage the subscription. */
+  ctaUrl: string;
+}
+
+export interface SubscriptionPauseReminderEmailContent {
+  subject: string;
+  preheader: string;
+  blocks: EmailBlock[];
+}
+
+/** Bind host-selected copy and pure helpers without provider or environment access. */
+export function createSubscriptionPauseReminderContentFactory(input: {
+  subscriptionEmailContent: Pick<SubscriptionEmailContent, "pauseReminder">;
+}) {
+  const { subscriptionEmailContent } = input;
+
+  function subscriptionPauseReminderEmailContent(
+    locale: Locale,
+    vars: SubscriptionPauseReminderEmailVars,
+    signoff: string,
+  ): SubscriptionPauseReminderEmailContent {
+    const copy = subscriptionEmailContent.pauseReminder[locale];
+    const resumeDate = vars.resumeDateLabel
+      ? locale === "en"
+        ? ` on ${vars.resumeDateLabel}`
+        : ` ${vars.resumeDateLabel}`
+      : "";
+
+    const blocks: EmailBlock[] = [
+      heading(copy.heading),
+      paragraph(copy.greeting(vars.firstName)),
+      paragraph(copy.intro(vars.brandName)),
+      paragraph(copy.resume(resumeDate)),
+      accentBox(copy.reassurance),
+      button(copy.cta, vars.ctaUrl),
+      paragraph(copy.outro),
+      paragraph(signoff),
+    ];
+
+    return {
+      subject: copy.subject,
+      preheader: copy.preheader,
+      blocks,
+    };
+  }
+  return { subscriptionPauseReminderEmailContent };
+}

package/src/communications/contracts/subscriptionPaused.ts

@@ -0,0 +1,58 @@
+import type { SubscriptionEmailContent } from "./subscriptionEmailContent.js";
+import type { Locale } from "./email.js";
+import {
+  accentBox,
+  button,
+  heading,
+  paragraph,
+  type EmailBlock,
+} from "./blocks.js";
+
+export interface SubscriptionPausedEmailVars {
+  firstName: string | null;
+  /** Consumer-facing brand label injected by the app/composition root. */
+  brandName: string;
+  /** Absolute CTA URL (manage subscription); null/absent → no button. */
+  ctaUrl?: string | null;
+}
+
+export interface SubscriptionPausedEmailContent {
+  subject: string;
+  preheader: string;
+  blocks: EmailBlock[];
+}
+
+/** Bind host-selected copy and pure helpers without provider or environment access. */
+export function createSubscriptionPausedContentFactory(input: {
+  subscriptionEmailContent: Pick<SubscriptionEmailContent, "paused">;
+}) {
+  const { subscriptionEmailContent } = input;
+
+  function subscriptionPausedEmailContent(
+    locale: Locale,
+    vars: SubscriptionPausedEmailVars,
+    signoff: string,
+  ): SubscriptionPausedEmailContent {
+    const copy = subscriptionEmailContent.paused[locale];
+    const blocks: EmailBlock[] = [
+      heading(copy.heading),
+      paragraph(copy.greeting(vars.firstName)),
+      paragraph(copy.intro),
+      accentBox(copy.reassurance(vars.brandName)),
+    ];
+
+    if (vars.ctaUrl) {
+      blocks.push(button(copy.cta, vars.ctaUrl));
+    }
+
+    blocks.push(paragraph(copy.outro));
+    blocks.push(paragraph(signoff));
+
+    return {
+      subject: copy.subject,
+      preheader: copy.preheader,
+      blocks,
+    };
+  }
+  return { subscriptionPausedEmailContent };
+}

package/src/communications/contracts/subscriptionPaymentExpired.ts

@@ -0,0 +1,83 @@
+import type { SubscriptionEmailContent } from "./subscriptionEmailContent.js";
+import type { PaymentFailureCustomerCause } from "@openlup/core/payment";
+import type { Locale } from "./email.js";
+import {
+  accentBox,
+  button,
+  heading,
+  paragraph,
+  type EmailBlock,
+} from "./blocks.js";
+
+export interface SubscriptionPaymentExpiredEmailVars {
+  firstName: string | null;
+  /** Formatted gross amount of the unpaid cycle, e.g. "129,99 zł", or null. */
+  amountLabel: string | null;
+  /**
+   * Why the charges were refused, in the payer-facing vocabulary. This template
+   * needs it most: "after several attempts" without a reason is the one place
+   * the rail asks for trust and offers nothing to trust. Absent or `unknown`
+   * renders no cause sentence.
+   */
+  cause?: PaymentFailureCustomerCause | null;
+  /**
+   * Recovery-link URL for the case's `resume_subscription` token. When present
+   * the template renders the resume CTA; when absent it keeps the support-led
+   * wording, because a button with no destination is worse than no button.
+   */
+  recoveryUrl?: string | null;
+}
+
+export interface SubscriptionPaymentExpiredEmailContent {
+  subject: string;
+  preheader: string;
+  blocks: EmailBlock[];
+}
+
+/** Bind host-selected copy and pure helpers without provider or environment access. */
+export function createSubscriptionPaymentExpiredContentFactory(input: {
+  subscriptionEmailContent: Pick<SubscriptionEmailContent, "paymentExpired">;
+  subscriptionPaymentCauseSentence: (locale: Locale, cause: PaymentFailureCustomerCause) => string | null;
+}) {
+  const { subscriptionEmailContent, subscriptionPaymentCauseSentence } = input;
+
+  function subscriptionPaymentExpiredEmailContent(
+    locale: Locale,
+    vars: SubscriptionPaymentExpiredEmailVars,
+    signoff: string,
+  ): SubscriptionPaymentExpiredEmailContent {
+    const copy = subscriptionEmailContent.paymentExpired[locale];
+    const recoveryUrl = vars.recoveryUrl?.trim() ? vars.recoveryUrl.trim() : null;
+    const causeSentence = subscriptionPaymentCauseSentence(locale, vars.cause ?? "unknown");
+    const detail = [
+      // Leads the box for the same reason as in the failed notice: it answers the
+      // question the paused subscription raises, before the figures.
+      ...(causeSentence ? [causeSentence] : []),
+      ...(recoveryUrl
+        ? [
+            vars.amountLabel ? copy.detail(vars.amountLabel)[0] : copy.detail(null)[0],
+            copy.ctaDetail,
+          ]
+        : copy.detail(vars.amountLabel)),
+    ];
+
+    const blocks: EmailBlock[] = [
+      heading(copy.heading),
+      paragraph(copy.greeting(vars.firstName)),
+      paragraph(copy.intro),
+      accentBox(detail),
+    ];
+
+    if (recoveryUrl) blocks.push(button(copy.cta, recoveryUrl));
+
+    blocks.push(paragraph(copy.outro));
+    blocks.push(paragraph(signoff));
+
+    return {
+      subject: copy.subject,
+      preheader: recoveryUrl ? copy.preheaderWithCta : copy.preheader,
+      blocks,
+    };
+  }
+  return { subscriptionPaymentExpiredEmailContent };
+}

package/src/communications/contracts/subscriptionPaymentFailed.ts

@@ -0,0 +1,117 @@
+import type { SubscriptionEmailContent } from "./subscriptionEmailContent.js";
+import type { PaymentFailureCustomerCause } from "@openlup/core/payment";
+import type { Locale } from "./email.js";
+import {
+  accentBox,
+  button,
+  heading,
+  paragraph,
+  type EmailBlock,
+} from "./blocks.js";
+
+export interface SubscriptionPaymentFailedEmailVars {
+  firstName: string | null;
+  /** Formatted gross amount that failed, e.g. "129,99 zł", or null when unknown. */
+  amountLabel: string | null;
+  /** Dunning retry attempt: 1 (gentle), 2 (reminder), 3+ (final retry announced). */
+  retryAttempt: number;
+  /** Absolute recovery URL (localized); null/absent → no button. */
+  recoveryUrl?: string | null;
+  /**
+   * Pre-formatted calendar day of the scheduled next charge, in the merchant's
+   * zone (e.g. "11.08.2026"). The dunning row that selects THIS template always
+   * carries a scheduled retry, so in production this is present; null keeps the
+   * pre-date sentence rather than printing a placeholder date.
+   */
+  nextRetryDateLabel?: string | null;
+  /** Card scheme as stored on the method's consent snapshot, e.g. "visa". */
+  methodScheme?: string | null;
+  /** Trailing digits of the stored method, e.g. "4242". */
+  methodLastDigits?: string | null;
+  /**
+   * Why the charge was refused, in the payer-facing vocabulary. Absent or
+   * `unknown` renders no cause sentence at all — see `subscriptionPaymentCauseCopy`.
+   */
+  cause?: PaymentFailureCustomerCause | null;
+  /**
+   * Whether the ladder scheduled a further charge for this cycle. Absent or
+   * `true` is today's rail and today's copy. `false` states that no further
+   * attempt is coming and leaves the CTA as the only remedy; any
+   * `nextRetryDateLabel` supplied alongside it is ignored rather than printed,
+   * because a date is only ever printed as part of a retry promise.
+   */
+  retryScheduled?: boolean;
+}
+
+export interface SubscriptionPaymentFailedEmailContent {
+  subject: string;
+  preheader: string;
+  blocks: EmailBlock[];
+}
+
+/** Bind host-selected copy and pure helpers without provider or environment access. */
+export function createSubscriptionPaymentFailedContentFactory(input: {
+  subscriptionEmailContent: Pick<SubscriptionEmailContent, "paymentFailed">;
+  subscriptionPaymentCauseSentence: (locale: Locale, cause: PaymentFailureCustomerCause) => string | null;
+}) {
+  const { subscriptionEmailContent, subscriptionPaymentCauseSentence } = input;
+
+  function subscriptionPaymentFailedEmailContent(
+    locale: Locale,
+    vars: SubscriptionPaymentFailedEmailVars,
+    signoff: string,
+  ): SubscriptionPaymentFailedEmailContent {
+    const copy = subscriptionEmailContent.paymentFailed[locale];
+    // Method facts are additive and BOTH halves must be present: "karta Visa ••••"
+    // with no digits identifies nothing, and bare digits with no scheme is worse.
+    // Absent facts drop the sentence rather than render a placeholder.
+    const scheme = vars.methodScheme?.trim() || null;
+    const lastDigits = vars.methodLastDigits?.trim() || null;
+    // The cause leads the box: it is the answer to the question the subject line
+    // just raised, and the amount means little until the reader knows why. It is
+    // also why it is PREPENDED and never appended — the retry sentence must stay
+    // last (see below).
+    const causeSentence = subscriptionPaymentCauseSentence(locale, vars.cause ?? "unknown");
+    // Only an explicit `false` turns the promises off. Absent means "no producer
+    // told us", and the only rail that exists always schedules a retry, so absent
+    // must keep rendering today's copy rather than the safer-sounding new copy:
+    // telling a customer no attempt is coming when one is would push them to
+    // cancel a subscription that was about to recover on its own.
+    const retryScheduled = vars.retryScheduled !== false;
+    const detail = [
+      ...(causeSentence ? [causeSentence] : []),
+      vars.amountLabel
+        ? copy.amountLine(vars.amountLabel)
+        : retryScheduled
+          ? copy.noAmountLine
+          : copy.noAmountLineNoRetry,
+      ...(scheme && lastDigits ? [copy.methodLine(scheme, lastDigits)] : []),
+      // Kept LAST in the box on purpose: the retry sentence is the one the
+      // characterization pins read off the end of `accentBox.lines`. Its
+      // no-retry replacement takes the same position for the same reason.
+      retryScheduled
+        ? copy.reassurance(vars.retryAttempt, vars.nextRetryDateLabel?.trim() || null)
+        : copy.noRetryAction,
+    ];
+    const blocks: EmailBlock[] = [
+      heading(copy.heading),
+      paragraph(copy.greeting(vars.firstName)),
+      paragraph(copy.intro),
+      accentBox(detail),
+    ];
+
+    if (vars.recoveryUrl) {
+      blocks.push(button(copy.cta, vars.recoveryUrl));
+    }
+
+    blocks.push(paragraph(copy.outro));
+    blocks.push(paragraph(signoff));
+
+    return {
+      subject: copy.subject,
+      preheader: copy.preheader,
+      blocks,
+    };
+  }
+  return { subscriptionPaymentFailedEmailContent };
+}

package/src/communications/contracts/subscriptionPaymentRecovered.ts

@@ -0,0 +1,50 @@
+import type { SubscriptionEmailContent } from "./subscriptionEmailContent.js";
+import type { Locale } from "./email.js";
+import {
+  accentBox,
+  heading,
+  paragraph,
+  type EmailBlock,
+} from "./blocks.js";
+
+export interface SubscriptionPaymentRecoveredEmailVars {
+  firstName: string | null;
+  /** Formatted gross amount of the recovered cycle, e.g. "129,99 zł", or null. */
+  amountLabel: string | null;
+}
+
+export interface SubscriptionPaymentRecoveredEmailContent {
+  subject: string;
+  preheader: string;
+  blocks: EmailBlock[];
+}
+
+/** Bind host-selected copy and pure helpers without provider or environment access. */
+export function createSubscriptionPaymentRecoveredContentFactory(input: {
+  subscriptionEmailContent: Pick<SubscriptionEmailContent, "paymentRecovered">;
+}) {
+  const { subscriptionEmailContent } = input;
+
+  function subscriptionPaymentRecoveredEmailContent(
+    locale: Locale,
+    vars: SubscriptionPaymentRecoveredEmailVars,
+    signoff: string,
+  ): SubscriptionPaymentRecoveredEmailContent {
+    const copy = subscriptionEmailContent.paymentRecovered[locale];
+    const blocks: EmailBlock[] = [
+      heading(copy.heading),
+      paragraph(copy.greeting(vars.firstName)),
+      paragraph(copy.intro),
+      accentBox(copy.detail(vars.amountLabel)),
+      paragraph(copy.outro),
+      paragraph(signoff),
+    ];
+
+    return {
+      subject: copy.subject,
+      preheader: copy.preheader,
+      blocks,
+    };
+  }
+  return { subscriptionPaymentRecoveredEmailContent };
+}

package/src/communications/contracts/subscriptionRenewalAtRisk.ts

@@ -0,0 +1,85 @@
+import type { SubscriptionEmailContent } from "./subscriptionEmailContent.js";
+import type { PaymentFailureCustomerCause } from "@openlup/core/payment";
+import type { Locale } from "./email.js";
+import {
+  accentBox,
+  button,
+  heading,
+  paragraph,
+  type EmailBlock,
+} from "./blocks.js";
+
+/**
+ * Which of the two unchargeable states produced this notice.
+ *
+ * ⛔ THESE TWO TOKENS ARE LEDGER IDENTITY, NOT COPY KEYS. The producer's dedupe
+ * key AND its two-send cap are one string, `<subscriptionId>:<cause>:<day>`, and
+ * the cap is read back by matching this token as a LIKE prefix. Renaming either
+ * value — including "aligning" it with the shared cause vocabulary below —
+ * silently resets every cap ever recorded, because the new prefix matches
+ * nothing. The mapping to the shared vocabulary therefore happens at RENDER
+ * time, here, and never in the producer.
+ */
+export type SubscriptionRenewalAtRiskCause = "mandate" | "missing";
+
+export interface SubscriptionRenewalAtRiskEmailVars {
+  firstName: string | null;
+  /** Calendar day of the scheduled renewal in the merchant zone, or null. */
+  renewalDateLabel: string | null;
+  cause: SubscriptionRenewalAtRiskCause;
+  /** Account payments deep link; the same one the activation-gap email uses. */
+  ctaUrl: string;
+}
+
+export interface SubscriptionRenewalAtRiskEmailContent {
+  subject: string;
+  preheader: string;
+  blocks: EmailBlock[];
+}
+
+/** Bind host-selected copy and pure helpers without provider or environment access. */
+export function createSubscriptionRenewalAtRiskContentFactory(input: {
+  subscriptionEmailContent: Pick<SubscriptionEmailContent, "renewalAtRisk">;
+  subscriptionPaymentCauseSentence: (locale: Locale, cause: PaymentFailureCustomerCause) => string | null;
+}) {
+  const { subscriptionEmailContent, subscriptionPaymentCauseSentence } = input;
+
+  /** Render-time only. See the ⛔ above before touching either side of this map. */
+  const SHARED_CAUSE: Record<SubscriptionRenewalAtRiskCause, PaymentFailureCustomerCause> = {
+    mandate: "method_cannot_recur",
+    missing: "method_missing",
+  };
+
+  /**
+   * Both of this rail's causes state something about the stored method, so both
+   * have a shared sentence and neither can be `unknown`. The non-null assertion is
+   * carried by the `SHARED_CAUSE` map's exhaustive typing, not by an assumption.
+   */
+  function causeSentence(locale: Locale, cause: SubscriptionRenewalAtRiskCause): string {
+    return subscriptionPaymentCauseSentence(locale, SHARED_CAUSE[cause]) ?? "";
+  }
+
+  function subscriptionRenewalAtRiskEmailContent(
+    locale: Locale,
+    vars: SubscriptionRenewalAtRiskEmailVars,
+    signoff: string,
+  ): SubscriptionRenewalAtRiskEmailContent {
+    const copy = subscriptionEmailContent.renewalAtRisk[locale];
+    const blocks: EmailBlock[] = [
+      heading(copy.heading),
+      paragraph(copy.greeting(vars.firstName)),
+      paragraph(copy.intro(vars.renewalDateLabel)),
+      accentBox([causeSentence(locale, vars.cause), copy.consequence]),
+      button(copy.cta, vars.ctaUrl),
+      paragraph(copy.outro),
+      paragraph(signoff),
+    ];
+
+    return {
+      subject: copy.subject,
+      preheader: copy.preheader,
+      blocks,
+    };
+  }
+  return { subscriptionRenewalAtRiskEmailContent };
+}