@openlup/platform 0.16.0 → 0.17.0

package/src/communications/contracts/checkoutExpired.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 CheckoutExpiredEmailVars {
+  firstName: string | null;
+  orderId: string;
+  amountLabel: string | null;
+  ctaUrl?: string | null;
+  ctaKind?: "recovery" | "compose";
+}
+
+export interface CheckoutExpiredEmailContent {
+  subject: string;
+  preheader: string;
+  blocks: EmailBlock[];
+}
+
+/** Bind host-selected copy and pure helpers without provider or environment access. */
+export function createCheckoutExpiredContentFactory(input: {
+  commerceEmailContent: Pick<CommerceEmailContent, "checkoutExpired" | "orderRefPrefix">;
+  formatCustomerOrderReference: (orderId: string, prefix: string) => string;
+}) {
+  const { commerceEmailContent, formatCustomerOrderReference } = input;
+
+  function checkoutExpiredEmailContent(
+    locale: Locale,
+    vars: CheckoutExpiredEmailVars,
+    signoff: string,
+  ): CheckoutExpiredEmailContent {
+    const copy = commerceEmailContent.checkoutExpired[
+      vars.ctaKind === "recovery" ? "recovery" : "expired"
+    ][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.details(vars.amountLabel), { label: copy.detailsLabel }),
+    ];
+
+    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 { checkoutExpiredEmailContent };
+}

package/src/communications/contracts/checkoutRecovery.ts

@@ -0,0 +1,68 @@
+import type { CommerceEmailContent } from "./commerceEmailContent.js";
+import type { Locale } from "./email.js";
+import { button, heading, paragraph, type EmailBlock } from "./blocks.js";
+
+export type CheckoutRecoveryReminderHours = 1 | 20;
+export type CheckoutRecoveryMode = "subscription_cycle" | "one_time";
+
+export interface CheckoutRecoveryEmailVars {
+  firstName: string | null;
+  brandName: string;
+  reminderHours: CheckoutRecoveryReminderHours;
+  mode: CheckoutRecoveryMode;
+  /** Absolute signed deep-link to complete payment for this order. */
+  recoveryUrl: string;
+  /** Optional deployment-specific context consumed by the selected copy pack. */
+  contextName?: string | null;
+}
+
+export interface CheckoutRecoveryEmailContent {
+  subject: string;
+  preheader: string;
+  blocks: EmailBlock[];
+}
+
+/** Bind host-selected copy and pure helpers without provider or environment access. */
+export function createCheckoutRecoveryContentFactory(input: {
+  commerceEmailContent: Pick<CommerceEmailContent, "checkoutRecovery">;
+}) {
+  const { commerceEmailContent } = input;
+
+  function checkoutRecoveryEmailContent(
+    locale: Locale,
+    vars: CheckoutRecoveryEmailVars,
+    signoff: string,
+  ): CheckoutRecoveryEmailContent {
+    const copy = commerceEmailContent.checkoutRecovery[locale];
+    const isFinal = vars.reminderHours === 20;
+    // The optional selected-pack context note runs only on the first nudge (1h).
+    // The final reminder (20h) stays businesslike, so it never sits next to the
+    // "order will be canceled" note.
+    const showCheer = !isFinal;
+    const isSubscription = vars.mode === "subscription_cycle";
+    const intro = isSubscription
+      ? copy.introSubscription
+      : showCheer
+        ? `${copy.introOneTime} ${copy.contextCheer(vars.contextName ?? null)}`
+        : copy.introOneTime;
+
+    const blocks: EmailBlock[] = [
+      heading(isFinal ? copy.headingFinal : copy.headingFirst),
+      paragraph(copy.greeting(vars.firstName)),
+      paragraph(intro),
+      button(copy.cta, vars.recoveryUrl),
+    ];
+    if (isSubscription && showCheer) {
+      blocks.push(paragraph(copy.subscriptionCheer(vars.contextName ?? null, vars.brandName)));
+    }
+    if (isFinal) blocks.push(paragraph(copy.finalNote));
+    blocks.push(paragraph(signoff));
+
+    return {
+      subject: isFinal ? copy.subjectFinal : copy.subjectFirst,
+      preheader: copy.preheader,
+      blocks,
+    };
+  }
+  return { checkoutRecoveryEmailContent };
+}

package/src/communications/contracts/commerceEmailContent.ts

@@ -0,0 +1,189 @@
+import type { Locale } from "./email.js";
+import type { CommerceEngagementEmailContent, CommerceRecoveryEmailContent } from "./commerceEngagementEmailContent.js";
+
+
+export interface OrderDraftEmailCopy {
+  subject: (orderId: string) => string;
+  preheader: string;
+  heading: string;
+  greeting: (firstName: string | null) => string;
+  intro: (orderId: string) => string;
+  itemsLabel: string;
+  noItems: string;
+  subtotalLabel: string;
+  discountRowLabel: string;
+  totalLabel: string;
+  cta: string;
+  outro: string;
+  personalizedClosing: (name: string) => string;
+}
+
+export interface OrderPaidEmailCopy {
+  subject: (orderId: string) => string;
+  preheader: string;
+  heading: string;
+  greeting: (firstName: string | null) => string;
+  introOneTime: (orderId: string) => string;
+  introSubscription: (orderId: string) => string;
+  noItems: string;
+  subtotalLabel: string;
+  catalogProductsLabel: string;
+  discountRowLabel: string;
+  firstSubscriptionDiscountRowLabel: string;
+  productPayableLabel: string;
+  shippingLabel: string;
+  shippingFree: string;
+  totalLabel: string;
+  finalPaidLabel: string;
+  cta: string;
+  receiptNote: (name: string | null) => string;
+  outro: string;
+  withdrawalNotice: string;
+  withdrawalLinkLabel: string;
+}
+
+export interface OrderCanceledEmailCopy {
+  subject: (orderId: string) => string;
+  preheader: string;
+  heading: string;
+  greeting: (firstName: string | null) => string;
+  intro: (orderId: string) => string;
+  detailsLabel: string;
+  details: (amountLabel: string | null) => string[];
+  returnNote: (name: string | null) => string;
+  cta: string;
+  outro: string;
+}
+
+export interface OrderRefundedEmailCopy {
+  subject: (orderId: string) => string;
+  preheader: string;
+  heading: string;
+  greeting: (firstName: string | null) => string;
+  intro: (orderId: string) => string;
+  detailsLabel: string;
+  details: (amountLabel: string | null) => string[];
+  returnNote: (brandName: string) => string;
+  cta: string;
+  outro: string;
+}
+
+export interface PaymentFailedEmailCopy {
+  subject: (orderId: string) => string;
+  preheader: string;
+  heading: string;
+  greeting: (firstName: string | null) => string;
+  intro: (orderId: string) => string;
+  detailsLabel: string;
+  details: (amountLabel: string | null, mode: "subscription_cycle" | "one_time") => string[];
+  cta: string;
+  outro: string;
+}
+
+/**
+ * A guide the mail points the customer at: a document the deployment hosts
+ * under its own site origin, so `path` is site-relative and the content
+ * module joins it with the origin the sender passes in.
+ */
+export interface EmailGuideCardCopy {
+  eyebrow: string;
+  title: string;
+  text: (contextName: string | null) => string;
+  cta: string;
+  /** Site-relative path of the document (leading slash). */
+  path: string;
+  /** Optional illustration, also site-relative. */
+  image?: { path: string; alt: string; widthPx: number; heightPx: number };
+}
+
+export interface ShipmentDispatchedEmailCopy {
+  subject: (orderRef: string) => string;
+  preheader: string;
+  heading: string;
+  greeting: (firstName: string | null) => string;
+  intro: (orderRef: string) => string;
+  trackingLabel: string;
+  trackParcel: string;
+  noTracking: string[];
+  noTrackingLabel: string;
+  /** The account guide the customer can read while the parcel travels. */
+  accountGuide: EmailGuideCardCopy;
+  outro: (contextName: string | null) => string;
+}
+
+export interface ShipmentDeliveredEmailCopy {
+  subject: (orderRef: string) => string;
+  preheader: string;
+  heading: string;
+  greeting: (firstName: string | null) => string;
+  intro: (orderRef: string, contextName: string | null) => string;
+  /** The getting-started guide to read before the first serving. */
+  startGuide: EmailGuideCardCopy;
+  outro: string;
+}
+
+export interface ShipmentExceptionEmailCopy {
+  subject: (orderRef: string) => string;
+  preheader: string;
+  heading: string;
+  greeting: (firstName: string | null) => string;
+  intro: (orderRef: string) => string;
+  reassuranceLabel: string;
+  reassurance: string[];
+  cta: string;
+  outro: string;
+}
+
+export interface ReturnApprovedEmailCopy {
+  subject: (orderRef: string) => string;
+  preheader: string;
+  heading: string;
+  greeting: (firstName: string | null) => string;
+  intro: (orderRef: string) => string;
+  returnAddressNotice: string;
+  cta: string;
+}
+
+export interface ReturnRejectedEmailCopy {
+  subject: (orderRef: string) => string;
+  preheader: string;
+  heading: string;
+  greeting: (firstName: string | null) => string;
+  intro: (orderRef: string) => string;
+  cta: string;
+}
+
+export interface ReturnRefundedEmailCopy {
+  subject: (orderRef: string) => string;
+  preheader: string;
+  heading: string;
+  greeting: (firstName: string | null) => string;
+  amountKnown: (amountLabel: string, orderRef: string) => string;
+  amountUnknown: (orderRef: string) => string;
+  returnNote: string;
+  cta: string;
+}
+
+/** Build-time selected transactional-copy owner for commerce mail. */
+export interface CommerceEmailContent extends CommerceRecoveryEmailContent, CommerceEngagementEmailContent {
+  readonly id: string;
+  readonly orderRefPrefix: string;
+  readonly orderDraft: Record<Locale, OrderDraftEmailCopy>;
+  readonly orderPaid: Record<Locale, OrderPaidEmailCopy>;
+  readonly orderCanceled: Record<Locale, OrderCanceledEmailCopy>;
+  readonly orderRefunded: Record<Locale, OrderRefundedEmailCopy>;
+  readonly paymentFailed: Record<Locale, PaymentFailedEmailCopy>;
+  readonly shipmentDispatched: Record<Locale, ShipmentDispatchedEmailCopy>;
+  readonly shipmentDelivered: Record<Locale, ShipmentDeliveredEmailCopy>;
+  readonly shipmentException: Record<Locale, ShipmentExceptionEmailCopy>;
+  readonly returns: {
+    readonly approved: Record<Locale, ReturnApprovedEmailCopy>;
+    readonly rejected: Record<Locale, ReturnRejectedEmailCopy>;
+    readonly refunded: Record<Locale, ReturnRefundedEmailCopy>;
+  };
+}
+
+export type CommerceFulfillmentEmailContent = Pick<
+  CommerceEmailContent,
+  "shipmentDispatched" | "shipmentDelivered" | "shipmentException" | "returns"
+>;

package/src/communications/contracts/commerceEngagementEmailContent.ts

@@ -0,0 +1,106 @@
+import type { Locale } from "./email.js";
+
+
+export interface AbandonedCartToneEmailCopy {
+  subject: string;
+  preheader: string;
+  heading: string;
+  intro: string;
+  body: string;
+  cta: string;
+}
+
+export interface AbandonedCartEmailCopy {
+  greeting: (firstName: string | null) => string;
+  first: AbandonedCartToneEmailCopy;
+  gentle: AbandonedCartToneEmailCopy;
+  last: AbandonedCartToneEmailCopy;
+}
+
+export interface BackInStockEmailCopy {
+  genericLabel: string;
+  subject: (productLabel: string) => string;
+  preheader: string;
+  heading: (productLabel: string) => string;
+  greeting: string;
+  intro: (productLabel: string) => string;
+  hook: string;
+  cta: string;
+}
+
+export interface CheckoutExpiredEmailCopy {
+  subject: (orderRef: string) => string;
+  preheader: string;
+  heading: string;
+  greeting: (firstName: string | null) => string;
+  intro: (orderRef: string) => string;
+  detailsLabel: string;
+  details: (amountLabel: string | null) => string[];
+  cta: string;
+  outro: string;
+}
+
+export interface CheckoutRecoveryEmailCopy {
+  greeting: (firstName: string | null) => string;
+  cta: string;
+  subjectFirst: string;
+  subjectFinal: string;
+  preheader: string;
+  headingFirst: string;
+  headingFinal: string;
+  introSubscription: string;
+  introOneTime: string;
+  contextCheer: (contextName: string | null) => string;
+  subscriptionCheer: (contextName: string | null, appName: string) => string;
+  finalNote: string;
+}
+
+export interface ReorderReminderEmailCopy {
+  subject: string;
+  preheader: string;
+  greeting: (firstName: string | null) => string;
+  heading: string;
+  intro: (appName: string) => string;
+  consistencyNote: string;
+  upsellLabel: string;
+  upsellLines: string[];
+  cta: string;
+}
+
+export interface ReviewRequestEmailCopy {
+  subject: string;
+  preheader: string;
+  heading: string;
+  greeting: (firstName: string | null) => string;
+  intro: (contextName: string | null) => string;
+  body: string;
+  cta: string;
+  outro: string;
+}
+
+export interface ReviewEffectsEmailCopy {
+  subject: string;
+  preheader: string;
+  heading: string;
+  greeting: (firstName: string | null) => string;
+  intro: (contextName: string | null, appName: string) => string;
+  body: string;
+  cta: string;
+  outro: string;
+}
+
+export interface CommerceRecoveryEmailContent {
+  readonly abandonedCart: Record<Locale, AbandonedCartEmailCopy>;
+  readonly checkoutExpired: {
+    readonly expired: Record<Locale, CheckoutExpiredEmailCopy>;
+    readonly recovery: Record<Locale, CheckoutExpiredEmailCopy>;
+  };
+  readonly checkoutRecovery: Record<Locale, CheckoutRecoveryEmailCopy>;
+}
+
+export interface CommerceEngagementEmailContent {
+  readonly backInStock: Record<Locale, BackInStockEmailCopy>;
+  readonly reorderReminder: Record<Locale, ReorderReminderEmailCopy>;
+  readonly reviewRequest: Record<Locale, ReviewRequestEmailCopy>;
+  readonly reviewEffects: Record<Locale, ReviewEffectsEmailCopy>;
+}

package/src/communications/contracts/consent.ts

@@ -0,0 +1,13 @@
+import type { CommunicationPurpose } from "./types.js";
+
+export type CommunicationPurposeClassification = "marketing" | "non-marketing";
+export interface CommunicationPurposeDefinition<Purpose extends string = CommunicationPurpose> {
+  readonly id: Purpose;
+  readonly classification: CommunicationPurposeClassification;
+}
+/** Immutable, explicitly composed identifiers; registration is never permission. */
+export interface CommunicationPurposeRegistry<Purpose extends string = CommunicationPurpose> {
+  readonly purposes: readonly CommunicationPurposeDefinition<Purpose>[];
+  has(value: unknown): value is Purpose;
+  classification(purpose: Purpose): CommunicationPurposeClassification | undefined;
+}

package/src/communications/contracts/email.ts

@@ -0,0 +1,210 @@
+export type Locale = "pl" | "en";
+
+// Content blocks — the public contract a business domain (commerce,
+// subscription, accounting, …) uses to compose an email body. A content module
+// returns ordered blocks; the renderer turns them into branded HTML + text.
+// Domains import ONLY these builders/types cross-domain (see the architecture
+// guardrail whitelist for the `email` segment) — never render.ts internals.
+//
+// Builders are thin typed constructors: they keep call sites readable and let
+// the block shape evolve without touching every content module.
+
+export interface ParagraphBlock {
+  kind: "paragraph";
+  /**
+   * Plain text. A literal "\n" becomes a <br> in HTML and stays a newline in
+   * text. Two inline markers are honoured in HTML: `**bold**` and
+   * Markdown link syntax — see inlineHtml in render.ts for why only those two.
+   */
+  text: string;
+  /** Render in the muted/secondary colour at a smaller size (fine print). */
+  muted?: boolean;
+  /**
+   * Render BELOW the white content card, above the footer, as centred 11px
+   * fine print. For notices that must be delivered on a durable medium but must
+   * not compete with the message — the consumer-withdrawal paragraph on the
+   * paid-order mail, the marketing unsubscribe line. Ignored in the text part,
+   * where ordering already carries the same meaning.
+   */
+  afterCard?: boolean;
+}
+
+export interface HeadingBlock {
+  kind: "heading";
+  text: string;
+}
+
+export interface ListBlock {
+  kind: "list";
+  items: string[];
+}
+
+export interface AccentBoxBlock {
+  kind: "accentBox";
+  /** Optional uppercase eyebrow label in the brand colour. */
+  label?: string;
+  /** Body lines, rendered one per line. */
+  lines: string[];
+}
+
+export interface DataRow {
+  label: string;
+  value: string;
+}
+
+export interface DataTableBlock {
+  kind: "dataTable";
+  /** Rendered inside an accent box as "label: <strong>value</strong>" lines. */
+  rows: DataRow[];
+  /** Optional text link rendered as the box's last line (a carrier tracking page next to its number). */
+  link?: { label: string; href: string };
+}
+
+export interface FeatureCardImage {
+  /** Absolute HTTPS URL of the illustration. */
+  src: string;
+  /** Blocked-image fallback, rendered in the card's accent colour. */
+  alt: string;
+  widthPx: number;
+  heightPx: number;
+}
+
+export interface FeatureCardBlock {
+  kind: "featureCard";
+  /** Optional uppercase eyebrow above the title. */
+  eyebrow?: string;
+  title: string;
+  /** Body copy; the paragraph inline markers apply. */
+  text: string;
+  cta: { label: string; href: string };
+  /**
+   * Optional illustration. It sits beside the copy on a wide client and above
+   * it on a narrow one - a fluid layout with no media query, so it also holds
+   * in clients that drop <style>.
+   */
+  image?: FeatureCardImage;
+}
+
+export interface ButtonBlock {
+  kind: "button";
+  label: string;
+  href: string;
+}
+
+export interface LinkParagraphBlock {
+  kind: "linkParagraph";
+  /** Inline copy rendered as a single clickable <a href> inside a paragraph. */
+  text: string;
+  href: string;
+  /** Render in the muted/secondary colour at fine-print size (footer links). */
+  muted?: boolean;
+  /** See ParagraphBlock.afterCard. */
+  afterCard?: boolean;
+}
+
+export interface DividerBlock {
+  kind: "divider";
+}
+
+export type EmailBlock =
+  | ParagraphBlock
+  | HeadingBlock
+  | ListBlock
+  | AccentBoxBlock
+  | DataTableBlock
+  | FeatureCardBlock
+  | ButtonBlock
+  | LinkParagraphBlock
+  | DividerBlock;
+
+
+export interface EmailTheme {
+  /** Outer page background (warm cream). */
+  bodyBg: string;
+  /** Content card background. */
+  cardBg: string;
+  /** Accent-box background (light teal tint). */
+  accentBg: string;
+  /** Accent-box / divider hairline. */
+  hairline: string;
+  /** Primary brand colour (teal): logo, links, buttons, accent border. */
+  brand: string;
+  /** Text colour on top of the brand colour (e.g. button label). */
+  onBrand: string;
+  /** Heading text. */
+  textHeading: string;
+  /** Body copy. */
+  textBody: string;
+  /** Muted/secondary text (footer, fine print). */
+  textMuted: string;
+  /** Font stack — system fonts only, for broad client support. */
+  fontFamily: string;
+  /** Text logo rendered in the header, and the alt/fallback shown when an image
+   *  logo is set but blocked by the client. */
+  logoText: string;
+  /** Optional hosted logo image URL (absolute HTTPS). When set, the header
+   *  renders an <img> (with logoText as the alt fallback) instead of the text
+   *  wordmark. Left undefined by forks that prefer the text logo. */
+  logoImageUrl?: string;
+  /** Displayed logo height in px (width auto-scales). Used for the width/height
+   *  attributes that keep layout stable when the image is blocked. */
+  logoImageHeightPx?: number;
+  /** Displayed logo width in px (paired with logoImageHeightPx for the attrs). */
+  logoImageWidthPx?: number;
+  /** Optional feature-card background; falls back to accentBg. Set it when the
+   *  card's illustration carries its own background that must match. */
+  featureCardBg?: string;
+  /** Optional feature-card eyebrow and alt-text colour; falls back to brand. */
+  featureCardAccent?: string;
+  /** Content card corner radius, px. */
+  cardRadiusPx: number;
+  /** Button corner radius, px. */
+  buttonRadiusPx: number;
+  /** Max content width, px. */
+  maxWidthPx: number;
+}
+export interface EmailChromeStrings {
+  /** Optional footer tagline under the content card. Left undefined by brands
+   *  that show only the legal fine print (see footerLegalLines). */
+  footerTagline?: string;
+  /** Accessible alt text for the logo (also the fallback when an image logo is
+   *  blocked). */
+  logoAlt: string;
+  /** Optional hosted hero-banner image URL (absolute HTTPS), rendered full-width
+   *  under the header. Each locale can carry different artwork. */
+  bannerImageUrl?: string;
+  /** Alt text for the banner image (shown when the image is blocked). */
+  bannerImageAlt?: string;
+  /** Optional legal fine-print lines rendered in the footer (company
+   *  identification, e.g. art. 206 KSH). Each entry is one line. */
+  footerLegalLines?: string[];
+}
+export interface EmailBrand {
+  /** Brand label used in email copy when it intentionally differs from logo rendering. */
+  copyBrandName: string;
+  /**
+   * Softer, mixed-case brand label for in-body copy (e.g. "openlup"). Distinct from
+   * the all-caps chrome/sign-off form (copyBrandName, "OPENLUP"). Optional: callers
+   * fall back to copyBrandName when a brand does not define a cased variant.
+   */
+  copyBrandNameCased?: string;
+  theme: EmailTheme;
+  chrome: Record<Locale, EmailChromeStrings>;
+}
+export interface RenderEmailInput {
+  /** Brand look + per-locale chrome, injected by the app layer (APP_EMAIL_BRAND). */
+  brand: EmailBrand;
+  locale: Locale;
+  subject: string;
+  /** Inbox preview text; hidden in the body. */
+  preheader?: string;
+  blocks: EmailBlock[];
+}
+
+export interface RenderedEmail {
+  subject: string;
+  html: string;
+  text: string;
+}
+
+export type EmailRenderer = (input: RenderEmailInput) => RenderedEmail;

package/src/communications/contracts/guideCard.ts

@@ -0,0 +1,34 @@
+// A guide card in a fulfillment mail: the selected copy pack names the guide by
+// a site-relative path, and the sender knows the site origin, so this is the
+// one place the two are joined into the absolute links a mail client needs.
+
+import type { EmailGuideCardCopy } from "./commerceEmailContent.js";
+import { featureCard, type FeatureCardBlock } from "./blocks.js";
+
+// Exactly one slash at the seam, whichever side carries it.
+function siteUrl(siteOrigin: string, path: string): string {
+  return `${siteOrigin.replace(/\/+$/, "")}/${path.replace(/^\/+/, "")}`;
+}
+
+export function guideCardBlock(
+  copy: EmailGuideCardCopy,
+  siteOrigin: string,
+  contextName: string | null,
+): FeatureCardBlock {
+  return featureCard({
+    eyebrow: copy.eyebrow,
+    title: copy.title,
+    text: copy.text(contextName),
+    cta: { label: copy.cta, href: siteUrl(siteOrigin, copy.path) },
+    ...(copy.image
+      ? {
+          image: {
+            src: siteUrl(siteOrigin, copy.image.path),
+            alt: copy.image.alt,
+            widthPx: copy.image.widthPx,
+            heightPx: copy.image.heightPx,
+          },
+        }
+      : {}),
+  });
+}