@openlup/platform 0.15.0 → 0.17.0

package/src/communications/contracts/reviewRequest.ts

@@ -0,0 +1,59 @@
+import type { CommerceEmailContent } from "./commerceEmailContent.js";
+import type { Locale } from "./email.js";
+import {
+  button,
+  heading,
+  paragraph,
+  type EmailBlock,
+} from "./blocks.js";
+
+export interface ReviewRequestEmailVars {
+  firstName: string | null;
+  /** Consumer-facing brand label injected by the app/composition root. */
+  brandName: string;
+  /** Absolute CTA URL to the review form (baseUrl + locale review path + token). */
+  reviewUrl: string;
+  /** Absolute signed unsubscribe URL (purpose = 'marketing_newsletter'). */
+  unsubscribeUrl: string;
+  /** Optional product, service, or other review context label. */
+  contextName?: string | null;
+}
+
+export interface ReviewRequestEmailContent {
+  subject: string;
+  preheader: string;
+  blocks: EmailBlock[];
+}
+
+/** Bind host-selected copy and pure helpers without provider or environment access. */
+export function createReviewRequestContentFactory(input: {
+  commerceEmailContent: Pick<CommerceEmailContent, "reviewRequest">;
+  marketingUnsubscribeFooter: (locale: Locale, unsubscribeUrl: string) => EmailBlock[];
+}) {
+  const { commerceEmailContent, marketingUnsubscribeFooter } = input;
+
+  function reviewRequestEmailContent(
+    locale: Locale,
+    vars: ReviewRequestEmailVars,
+    signoff: string,
+  ): ReviewRequestEmailContent {
+    const copy = commerceEmailContent.reviewRequest[locale];
+    const blocks: EmailBlock[] = [
+      heading(copy.heading),
+      paragraph(copy.greeting(vars.firstName)),
+      paragraph(copy.intro(vars.contextName ?? null)),
+      paragraph(copy.body),
+      button(copy.cta, vars.reviewUrl),
+      paragraph(copy.outro),
+      paragraph(signoff),
+      ...marketingUnsubscribeFooter(locale, vars.unsubscribeUrl),
+    ];
+
+    return {
+      subject: copy.subject,
+      preheader: copy.preheader.split("{{brand}}").join(vars.brandName),
+      blocks,
+    };
+  }
+  return { reviewRequestEmailContent };
+}

package/src/communications/contracts/roleNotificationContent.ts

@@ -0,0 +1,65 @@
+import type { Locale } from "./email.js";
+import { button, heading, paragraph, type EmailBlock } from "./blocks.js";
+
+export interface RoleNotificationVars {
+  role: "admin" | "distributor";
+  operatorUrl: string;
+  /** Absent means active membership; present means a pending invitation. */
+  expiresAt?: string;
+}
+export interface RoleNotificationCopy {
+  subject: string;
+  heading: string;
+  status: string;
+  body: string;
+  button: string;
+  footer: string;
+}
+export type RoleNotificationCopyFactory = (role: RoleNotificationVars["role"], expiresAt?: string) => RoleNotificationCopy;
+
+function defaultCopy(locale: Locale, role: RoleNotificationVars["role"], expiresAt?: string): RoleNotificationCopy {
+  return expiresAt === undefined ? (locale === "pl" ? {
+    subject: `Uprawnienia operatora: ${role}`,
+    heading: "Uprawnienia operatora",
+    status: "Twoje uprawnienia operatora są aktywne.",
+    body: `Przyznano Ci rolę ${role}. Otwórz panel operatora, aby się zalogować.`,
+    button: "Otwórz panel operatora",
+    footer: "Jeśli nie oczekujesz tych uprawnień, skontaktuj się z zespołem aplikacji.",
+  } : {
+    subject: `Operator membership: ${role}`,
+    heading: "Operator membership",
+    status: "Your operator membership is active.",
+    body: `You have the ${role} role. Open the operator panel to sign in.`,
+    button: "Open operator panel",
+    footer: "If you did not expect this membership, contact the application team.",
+  }) : locale === "pl" ? {
+    subject: `Zaproszenie operatora: ${role}`,
+    heading: "Zaproszenie operatora",
+    status: `Zaproszenie oczekuje na przyjęcie do ${expiresAt}.`,
+    body: `Zaproszono Cię do roli ${role}. Dostęp rozpocznie się po wejściu do panelu operatora ze zweryfikowanym kontem.`,
+    button: "Otwórz panel operatora",
+    footer: "Jeśli nie oczekujesz tego zaproszenia, skontaktuj się z zespołem aplikacji.",
+  } : {
+    subject: `Operator invitation: ${role}`,
+    heading: "Operator invitation",
+    status: `Your invitation is pending until ${expiresAt}.`,
+    body: `You are invited as ${role}. Access begins when you enter the operator panel with your verified account.`,
+    button: "Open operator panel",
+    footer: "If you did not expect this invitation, contact the application team.",
+  };
+}
+const defaults: Record<Locale, RoleNotificationCopyFactory> = {
+  pl: (role, expiresAt) => defaultCopy("pl", role, expiresAt),
+  en: (role, expiresAt) => defaultCopy("en", role, expiresAt),
+};
+
+/** Pure defaults with the same active/pending semantics in both locales. */
+export function createRoleNotificationContentFactory(copy: Record<Locale, RoleNotificationCopyFactory> = defaults) {
+  function roleNotificationEmailContent(locale: Locale, vars: RoleNotificationVars): { subject: string; preheader: string; blocks: EmailBlock[] } {
+    const c = copy[locale](vars.role, vars.expiresAt);
+    return { subject: c.subject, preheader: c.status,
+      blocks: [heading(c.heading), paragraph(c.status), paragraph(c.body),
+        button(c.button, vars.operatorUrl), paragraph(c.footer, { muted: true })] };
+  }
+  return { roleNotificationEmailContent };
+}

package/src/communications/contracts/shipmentDelivered.ts

@@ -0,0 +1,59 @@
+import type { CommerceEmailContent } from "./commerceEmailContent.js";
+import type { Locale } from "./email.js";
+import { guideCardBlock } from "./guideCard.js";
+import {
+  heading,
+  paragraph,
+  type EmailBlock,
+} from "./blocks.js";
+
+export interface ShipmentDeliveredEmailVars {
+  firstName: string | null;
+  orderId: string;
+  /** Site origin (absolute, no trailing slash) the guide links are built on. */
+  siteOrigin: string;
+  /** Optional deployment-specific context consumed by the selected copy pack. */
+  contextName?: string | null;
+}
+
+export interface ShipmentDeliveredEmailContent {
+  subject: string;
+  preheader: string;
+  blocks: EmailBlock[];
+}
+
+/** Bind host-selected copy and pure helpers without provider or environment access. */
+export function createShipmentDeliveredContentFactory(input: {
+  commerceEmailContent: Pick<CommerceEmailContent, "shipmentDelivered" | "orderRefPrefix">;
+  formatCustomerOrderReference: (orderId: string, prefix: string) => string;
+}) {
+  const { commerceEmailContent, formatCustomerOrderReference } = input;
+
+  function shipmentDeliveredEmailContent(
+    locale: Locale,
+    vars: ShipmentDeliveredEmailVars,
+    signoff: string,
+  ): ShipmentDeliveredEmailContent {
+    const copy = commerceEmailContent.shipmentDelivered[locale];
+    const orderRef = formatCustomerOrderReference(
+      vars.orderId,
+      commerceEmailContent.orderRefPrefix,
+    );
+    const blocks: EmailBlock[] = [
+      heading(copy.heading),
+      paragraph(copy.greeting(vars.firstName)),
+      paragraph(copy.intro(orderRef, vars.contextName ?? null)),
+      guideCardBlock(copy.startGuide, vars.siteOrigin, vars.contextName ?? null),
+    ];
+
+    blocks.push(paragraph(copy.outro));
+    blocks.push(paragraph(signoff));
+
+    return {
+      subject: copy.subject(orderRef),
+      preheader: copy.preheader,
+      blocks,
+    };
+  }
+  return { shipmentDeliveredEmailContent };
+}

package/src/communications/contracts/shipmentDispatched.ts

@@ -0,0 +1,77 @@
+import type { CommerceEmailContent } from "./commerceEmailContent.js";
+import type { Locale } from "./email.js";
+import { guideCardBlock } from "./guideCard.js";
+import {
+  accentBox,
+  dataTable,
+  heading,
+  linkParagraph,
+  paragraph,
+  type EmailBlock,
+} from "./blocks.js";
+
+export interface ShipmentDispatchedEmailVars {
+  firstName: string | null;
+  orderId: string;
+  /** Opaque carrier tracking number, or null when none is available. */
+  trackingNumber: string | null;
+  /** Absolute tracking URL (carrier page); rendered as a "track parcel" link. */
+  trackingUrl?: string | null;
+  /** Site origin (absolute, no trailing slash) the guide links are built on. */
+  siteOrigin: string;
+  /** Optional deployment-specific context consumed by the selected copy pack. */
+  contextName?: string | null;
+}
+
+export interface ShipmentDispatchedEmailContent {
+  subject: string;
+  preheader: string;
+  blocks: EmailBlock[];
+}
+
+/** Bind host-selected copy and pure helpers without provider or environment access. */
+export function createShipmentDispatchedContentFactory(input: {
+  commerceEmailContent: Pick<CommerceEmailContent, "shipmentDispatched" | "orderRefPrefix">;
+  formatCustomerOrderReference: (orderId: string, prefix: string) => string;
+}) {
+  const { commerceEmailContent, formatCustomerOrderReference } = input;
+
+  function shipmentDispatchedEmailContent(
+    locale: Locale,
+    vars: ShipmentDispatchedEmailVars,
+    signoff: string,
+  ): ShipmentDispatchedEmailContent {
+    const copy = commerceEmailContent.shipmentDispatched[locale];
+    const orderRef = formatCustomerOrderReference(
+      vars.orderId,
+      commerceEmailContent.orderRefPrefix,
+    );
+    const blocks: EmailBlock[] = [
+      heading(copy.heading),
+      paragraph(copy.greeting(vars.firstName)),
+      paragraph(copy.intro(orderRef)),
+    ];
+
+    // Tracking is the job-to-be-done of this message: the number and the
+    // carrier page share one box, and the guide card is the only button.
+    const trackLink = vars.trackingUrl ? { label: copy.trackParcel, href: vars.trackingUrl } : undefined;
+    if (vars.trackingNumber) {
+      blocks.push(dataTable([{ label: copy.trackingLabel, value: vars.trackingNumber }], { link: trackLink }));
+    } else {
+      blocks.push(accentBox(copy.noTracking, { label: copy.noTrackingLabel }));
+      if (trackLink) blocks.push(linkParagraph(trackLink.label, trackLink.href));
+    }
+
+    blocks.push(guideCardBlock(copy.accountGuide, vars.siteOrigin, vars.contextName ?? null));
+
+    blocks.push(paragraph(copy.outro(vars.contextName ?? null)));
+    blocks.push(paragraph(signoff));
+
+    return {
+      subject: copy.subject(orderRef),
+      preheader: copy.preheader,
+      blocks,
+    };
+  }
+  return { shipmentDispatchedEmailContent };
+}

package/src/communications/contracts/shipmentException.ts

@@ -0,0 +1,62 @@
+import type { CommerceEmailContent } from "./commerceEmailContent.js";
+import type { Locale } from "./email.js";
+import {
+  accentBox,
+  button,
+  heading,
+  paragraph,
+  type EmailBlock,
+} from "./blocks.js";
+
+export interface ShipmentExceptionEmailVars {
+  firstName: string | null;
+  orderId: string;
+  /** Absolute URL to the customer's order/account page; null/absent → no button. */
+  ctaUrl?: string | null;
+}
+
+export interface ShipmentExceptionEmailContent {
+  subject: string;
+  preheader: string;
+  blocks: EmailBlock[];
+}
+
+/** Bind host-selected copy and pure helpers without provider or environment access. */
+export function createShipmentExceptionContentFactory(input: {
+  commerceEmailContent: Pick<CommerceEmailContent, "shipmentException" | "orderRefPrefix">;
+  formatCustomerOrderReference: (orderId: string, prefix: string) => string;
+}) {
+  const { commerceEmailContent, formatCustomerOrderReference } = input;
+
+  function shipmentExceptionEmailContent(
+    locale: Locale,
+    vars: ShipmentExceptionEmailVars,
+    signoff: string,
+  ): ShipmentExceptionEmailContent {
+    const copy = commerceEmailContent.shipmentException[locale];
+    const orderRef = formatCustomerOrderReference(
+      vars.orderId,
+      commerceEmailContent.orderRefPrefix,
+    );
+    const blocks: EmailBlock[] = [
+      heading(copy.heading),
+      paragraph(copy.greeting(vars.firstName)),
+      paragraph(copy.intro(orderRef)),
+      accentBox(copy.reassurance, { label: copy.reassuranceLabel }),
+    ];
+
+    if (vars.ctaUrl) {
+      blocks.push(button(copy.cta, vars.ctaUrl));
+    }
+
+    blocks.push(paragraph(copy.outro));
+    blocks.push(paragraph(signoff));
+
+    return {
+      subject: copy.subject(orderRef),
+      preheader: copy.preheader,
+      blocks,
+    };
+  }
+  return { shipmentExceptionEmailContent };
+}

package/src/communications/contracts/subscriptionActivationActionRequired.ts

@@ -0,0 +1,37 @@
+import type { SubscriptionEmailContent } from "./subscriptionEmailContent.js";
+import type { Locale } from "./email.js";
+import { accentBox, button, heading, paragraph, type EmailBlock } from "./blocks.js";
+
+export interface SubscriptionActivationActionRequiredVars {
+  firstName: string | null;
+  ctaUrl: string;
+}
+
+/** Bind host-selected copy and pure helpers without provider or environment access. */
+export function createSubscriptionActivationActionRequiredContentFactory(input: {
+  subscriptionEmailContent: Pick<SubscriptionEmailContent, "activationActionRequired">;
+}) {
+  const { subscriptionEmailContent } = input;
+
+  function subscriptionActivationActionRequiredEmailContent(
+    locale: Locale,
+    vars: SubscriptionActivationActionRequiredVars,
+    signoff: string,
+  ): { subject: string; preheader: string; blocks: EmailBlock[] } {
+    const copy = subscriptionEmailContent.activationActionRequired[locale];
+    return {
+      subject: copy.subject,
+      preheader: copy.preheader,
+      blocks: [
+        heading(copy.heading),
+        paragraph(copy.greeting(vars.firstName)),
+        paragraph(copy.intro),
+        accentBox(copy.facts),
+        button(copy.cta, vars.ctaUrl),
+        paragraph(copy.outro),
+        paragraph(signoff),
+      ],
+    };
+  }
+  return { subscriptionActivationActionRequiredEmailContent };
+}

package/src/communications/contracts/subscriptionAddressChanged.ts

@@ -0,0 +1,56 @@
+import type { SubscriptionEmailContent } from "./subscriptionEmailContent.js";
+import type { Locale } from "./email.js";
+import {
+  accentBox,
+  button,
+  heading,
+  paragraph,
+  type EmailBlock,
+} from "./blocks.js";
+
+export interface SubscriptionAddressChangedEmailVars {
+  firstName: string | null;
+  /** Absolute CTA URL (manage subscription); null/absent → no button. */
+  ctaUrl?: string | null;
+}
+
+export interface SubscriptionAddressChangedEmailContent {
+  subject: string;
+  preheader: string;
+  blocks: EmailBlock[];
+}
+
+/** Bind host-selected copy and pure helpers without provider or environment access. */
+export function createSubscriptionAddressChangedContentFactory(input: {
+  subscriptionEmailContent: Pick<SubscriptionEmailContent, "addressChanged">;
+}) {
+  const { subscriptionEmailContent } = input;
+
+  function subscriptionAddressChangedEmailContent(
+    locale: Locale,
+    vars: SubscriptionAddressChangedEmailVars,
+    signoff: string,
+  ): SubscriptionAddressChangedEmailContent {
+    const copy = subscriptionEmailContent.addressChanged[locale];
+    const blocks: EmailBlock[] = [
+      heading(copy.heading),
+      paragraph(copy.greeting(vars.firstName)),
+      paragraph(copy.intro),
+      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 { subscriptionAddressChangedEmailContent };
+}

package/src/communications/contracts/subscriptionCancelled.ts

@@ -0,0 +1,57 @@
+import type { SubscriptionEmailContent } from "./subscriptionEmailContent.js";
+import type { Locale } from "./email.js";
+import {
+  accentBox,
+  button,
+  heading,
+  paragraph,
+  type EmailBlock,
+} from "./blocks.js";
+
+export interface SubscriptionCancelledEmailVars {
+  firstName: string | null;
+  /** Absolute CTA URL (back to shop / re-subscribe); null/absent → no button. */
+  ctaUrl?: string | null;
+}
+
+export interface SubscriptionCancelledEmailContent {
+  subject: string;
+  preheader: string;
+  blocks: EmailBlock[];
+}
+
+/** Bind host-selected copy and pure helpers without provider or environment access. */
+export function createSubscriptionCancelledContentFactory(input: {
+  subscriptionEmailContent: Pick<SubscriptionEmailContent, "cancelled">;
+}) {
+  const { subscriptionEmailContent } = input;
+
+  function subscriptionCancelledEmailContent(
+    locale: Locale,
+    vars: SubscriptionCancelledEmailVars,
+    signoff: string,
+  ): SubscriptionCancelledEmailContent {
+    const copy = subscriptionEmailContent.cancelled[locale];
+    const blocks: EmailBlock[] = [
+      heading(copy.heading),
+      paragraph(copy.greeting(vars.firstName)),
+      paragraph(copy.intro),
+      accentBox(copy.reassurance),
+    ];
+
+    blocks.push(paragraph(copy.outro));
+
+    if (vars.ctaUrl) {
+      blocks.push(button(copy.cta, vars.ctaUrl));
+    }
+
+    blocks.push(paragraph(signoff));
+
+    return {
+      subject: copy.subject,
+      preheader: copy.preheader,
+      blocks,
+    };
+  }
+  return { subscriptionCancelledEmailContent };
+}

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