@openlup/platform 0.16.0 → 0.18.0

package/src/communications/contracts/subscriptionCycleSkipped.ts

@@ -0,0 +1,80 @@
+import type { SubscriptionEmailContent } from "./subscriptionEmailContent.js";
+import type { Locale } from "./email.js";
+import {
+  accentBox,
+  button,
+  dataTable,
+  heading,
+  paragraph,
+  type EmailBlock,
+} from "./blocks.js";
+
+export interface SubscriptionCycleSkippedEmailVars {
+  firstName: string | null;
+  /** Localized next CHARGE date after the skip, or null when unavailable. */
+  chargeDateLabel?: string | null;
+  /** Localized estimated delivery window after the skip, or null when unavailable. */
+  deliveryWindowLabel?: string | null;
+  /** Localized holiday caveat; present ONLY when a holiday moved the window. */
+  holidayNote?: string | null;
+  /** Absolute CTA URL (manage subscription); null/absent → no button. */
+  ctaUrl?: string | null;
+}
+
+export interface SubscriptionCycleSkippedEmailContent {
+  subject: string;
+  preheader: string;
+  blocks: EmailBlock[];
+}
+
+/** Bind host-selected copy and pure helpers without provider or environment access. */
+export function createSubscriptionCycleSkippedContentFactory(input: {
+  subscriptionEmailContent: Pick<SubscriptionEmailContent, "cycleSkipped">;
+}) {
+  const { subscriptionEmailContent } = input;
+
+  function subscriptionCycleSkippedEmailContent(
+    locale: Locale,
+    vars: SubscriptionCycleSkippedEmailVars,
+    signoff: string,
+  ): SubscriptionCycleSkippedEmailContent {
+    const copy = subscriptionEmailContent.cycleSkipped[locale];
+    const hasSchedule = Boolean(vars.chargeDateLabel && vars.deliveryWindowLabel);
+    const blocks: EmailBlock[] = [
+      heading(copy.heading),
+      paragraph(copy.greeting(vars.firstName)),
+      paragraph(hasSchedule ? copy.intro : copy.introWithoutDates),
+    ];
+
+    if (locale === "pl" && hasSchedule) {
+      blocks.push(dataTable([
+        { label: copy.deliveryLabel, value: vars.deliveryWindowLabel! },
+        { label: copy.chargeLabel, value: vars.chargeDateLabel! },
+      ]));
+    }
+
+    const reassurance = [
+      ...(locale !== "pl" && hasSchedule
+        ? [copy.dateLine(vars.deliveryWindowLabel!, vars.chargeDateLabel!)]
+        : []),
+      ...(vars.holidayNote ? [vars.holidayNote] : []),
+      ...copy.reassurance,
+    ];
+    blocks.push(accentBox(reassurance));
+    blocks.push(paragraph(copy.manageLine));
+
+    if (vars.ctaUrl) {
+      blocks.push(button(copy.cta, vars.ctaUrl));
+    }
+
+    blocks.push(paragraph(copy.outro));
+    blocks.push(paragraph(signoff));
+
+    return {
+      subject: hasSchedule ? copy.subject : copy.subjectWithoutDates,
+      preheader: copy.preheader,
+      blocks,
+    };
+  }
+  return { subscriptionCycleSkippedEmailContent };
+}

package/src/communications/contracts/subscriptionDeliveryRescheduled.ts

@@ -0,0 +1,79 @@
+import type { SubscriptionEmailContent } from "./subscriptionEmailContent.js";
+import type { Locale } from "./email.js";
+import {
+  accentBox,
+  button,
+  dataTable,
+  heading,
+  paragraph,
+  type EmailBlock,
+} from "./blocks.js";
+
+export interface SubscriptionDeliveryRescheduledEmailVars {
+  firstName: string | null;
+  /** Localized new CHARGE date (the date the customer picked), or null. */
+  chargeDateLabel?: string | null;
+  /** Localized estimated delivery window derived from the new charge date, or null. */
+  deliveryWindowLabel?: string | null;
+  /** Localized holiday caveat; present ONLY when a holiday moved the window. */
+  holidayNote?: string | null;
+  /** Absolute CTA URL (manage subscription); null/absent → no button. */
+  ctaUrl?: string | null;
+}
+
+export interface SubscriptionDeliveryRescheduledEmailContent {
+  subject: string;
+  preheader: string;
+  blocks: EmailBlock[];
+}
+
+/** Bind host-selected copy and pure helpers without provider or environment access. */
+export function createSubscriptionDeliveryRescheduledContentFactory(input: {
+  subscriptionEmailContent: Pick<SubscriptionEmailContent, "deliveryRescheduled">;
+}) {
+  const { subscriptionEmailContent } = input;
+
+  function subscriptionDeliveryRescheduledEmailContent(
+    locale: Locale,
+    vars: SubscriptionDeliveryRescheduledEmailVars,
+    signoff: string,
+  ): SubscriptionDeliveryRescheduledEmailContent {
+    const copy = subscriptionEmailContent.deliveryRescheduled[locale];
+    const hasSchedule = Boolean(vars.chargeDateLabel && vars.deliveryWindowLabel);
+    const blocks: EmailBlock[] = [
+      heading(copy.heading),
+      paragraph(copy.greeting(vars.firstName)),
+      paragraph(hasSchedule ? copy.intro : copy.introWithoutDates),
+    ];
+
+    if (locale === "pl" && hasSchedule) {
+      blocks.push(dataTable([
+        { label: copy.deliveryLabel, value: vars.deliveryWindowLabel! },
+        { label: copy.chargeLabel, value: vars.chargeDateLabel! },
+      ]));
+    }
+
+    const reassurance = [
+      ...(locale !== "pl" && hasSchedule
+        ? [copy.dateLine(vars.deliveryWindowLabel!, vars.chargeDateLabel!)]
+        : []),
+      ...(vars.holidayNote ? [vars.holidayNote] : []),
+      ...copy.reassurance,
+    ];
+    blocks.push(accentBox(reassurance));
+
+    if (vars.ctaUrl) {
+      blocks.push(button(copy.cta, vars.ctaUrl));
+    }
+
+    blocks.push(paragraph(copy.outro));
+    blocks.push(paragraph(signoff));
+
+    return {
+      subject: hasSchedule ? copy.subject : copy.subjectWithoutDates,
+      preheader: copy.preheader,
+      blocks,
+    };
+  }
+  return { subscriptionDeliveryRescheduledEmailContent };
+}

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 };
+}