@openlup/platform 0.16.0 → 0.18.0

package/src/communications/contracts/index.ts

@@ -0,0 +1,52 @@
+export type * from "./authEmail.js";
+export type * from "./email.js";
+export type * from "./newsletter.js";
+export type * from "./newsletterWebhook.js";
+export type * from "./publicIntake.js";
+export type * from "./transactionalDelivery.js";
+export type * from "./types.js";
+export type * from "./consent.js";
+export type * from "./marketingAutomation.js";
+export * from "./render.js";
+export * from "./blocks.js";
+export * from "./commerceEmailContent.js";
+export * from "./commerceEngagementEmailContent.js";
+export * from "./subscriptionEmailContent.js";
+export * from "./guideCard.js";
+export * from "./abandonedCart.js";
+export * from "./backInStock.js";
+export * from "./checkoutExpired.js";
+export * from "./checkoutRecovery.js";
+export * from "./orderCanceled.js";
+export * from "./orderDraft.js";
+export * from "./orderPaid.js";
+export * from "./orderRefunded.js";
+export * from "./paymentFailed.js";
+export * from "./reorderReminder.js";
+export * from "./returnEmails.js";
+export * from "./reviewEffects.js";
+export * from "./reviewRequest.js";
+export * from "./shipmentDelivered.js";
+export * from "./shipmentDispatched.js";
+export * from "./shipmentException.js";
+export * from "./subscriptionActivationActionRequired.js";
+export * from "./subscriptionAddressChanged.js";
+export * from "./subscriptionCancelled.js";
+export * from "./subscriptionCycleSkipped.js";
+export * from "./subscriptionDeliveryRescheduled.js";
+export * from "./subscriptionPackageChanged.js";
+export * from "./subscriptionPauseReminder.js";
+export * from "./subscriptionPaused.js";
+export * from "./subscriptionPaymentExpired.js";
+export * from "./subscriptionPaymentFailed.js";
+export * from "./subscriptionPaymentRecovered.js";
+export * from "./subscriptionRenewalAtRisk.js";
+export * from "./subscriptionRenewalUpcoming.js";
+export * from "./subscriptionResumed.js";
+export * from "./subscriptionWelcome.js";
+export * from "./subscriptionWinback.js";
+export * from "./invoiceDocumentContent.js";
+export * from "./roleNotificationContent.js";
+export * from "./inquiryContent.js";
+export * from "./optOutContent.js";
+export type * from "./marketingSync.js";

package/src/communications/contracts/inquiryContent.ts

@@ -0,0 +1,53 @@
+import type { Locale } from "./email.js";
+import { button, dataTable, heading, paragraph, type DataRow, type EmailBlock } from "./blocks.js";
+
+export interface InquiryVars {
+  displayName: string;
+  contact: string;
+  /** Host-resolved labels and values; omit optional rows rather than inventing them. */
+  details: DataRow[];
+  operatorUrl: string;
+}
+export interface InquiryCopy {
+  receiptSubject: string;
+  receiptGreeting: (name: string) => string;
+  receiptBody: string;
+  noticeSubject: string;
+  noticeBody: string;
+  nameLabel: string;
+  contactLabel: string;
+  cta: string;
+}
+const defaults: Record<Locale, InquiryCopy> = {
+  pl: {
+    receiptSubject: "Otrzymaliśmy Twoje zapytanie",
+    receiptGreeting: name => `Dziękujemy za kontakt, ${name}.`,
+    receiptBody: "Potwierdzamy otrzymanie Twojego zapytania.",
+    noticeSubject: "Nowe zapytanie", noticeBody: "Otrzymano nowe zapytanie.",
+    nameLabel: "Imię i nazwisko", contactLabel: "Kontakt", cta: "Otwórz zapytanie",
+  },
+  en: {
+    receiptSubject: "We've received your inquiry",
+    receiptGreeting: name => `Thank you for contacting us, ${name}.`,
+    receiptBody: "We confirm receipt of your inquiry.",
+    noticeSubject: "New inquiry", noticeBody: "A new inquiry has been received.",
+    nameLabel: "Name", contactLabel: "Contact", cta: "Open inquiry",
+  },
+};
+
+/** Presentation only: no recipient, sender, response-time promise or country policy. */
+export function createInquiryContentFactory(copy: Record<Locale, InquiryCopy> = defaults) {
+  function inquiryReceiptEmailContent(locale: Locale, vars: InquiryVars, signoff: string): { subject: string; preheader: string; blocks: EmailBlock[] } {
+    const c = copy[locale];
+    return { subject: c.receiptSubject, preheader: c.receiptBody,
+      blocks: [heading(c.receiptSubject), paragraph(c.receiptGreeting(vars.displayName)), paragraph(c.receiptBody), paragraph(signoff)] };
+  }
+  function inquiryNoticeEmailContent(locale: Locale, vars: InquiryVars, signoff: string): { subject: string; preheader: string; blocks: EmailBlock[] } {
+    const c = copy[locale];
+    return { subject: c.noticeSubject, preheader: c.noticeBody,
+      blocks: [heading(c.noticeSubject), paragraph(c.noticeBody),
+        dataTable([{ label: c.nameLabel, value: vars.displayName }, { label: c.contactLabel, value: vars.contact }, ...vars.details]),
+        button(c.cta, vars.operatorUrl), paragraph(signoff)] };
+  }
+  return { inquiryReceiptEmailContent, inquiryNoticeEmailContent };
+}

package/src/communications/contracts/invoiceDocumentContent.ts

@@ -0,0 +1,57 @@
+import type { Locale } from "./email.js";
+import { button, dataTable, heading, paragraph, type EmailBlock } from "./blocks.js";
+
+export interface InvoiceDocumentVars {
+  orderRef: string;
+  documentNumber: string;
+  kind: "invoice" | "correction";
+  accountDocumentsUrl: string;
+}
+
+export interface InvoiceDocumentCopy {
+  subject: (orderRef: string, correction: boolean) => string;
+  preheader: (correction: boolean) => string;
+  heading: (correction: boolean) => string;
+  attachment: (correction: boolean) => string;
+  orderLabel: string;
+  documentLabel: (correction: boolean) => string;
+  cta: string;
+  availability: string;
+}
+
+const defaults: Record<Locale, InvoiceDocumentCopy> = {
+  pl: {
+    subject: (ref, correction) => `${correction ? "Korekta faktury" : "Faktura"} do zamówienia ${ref}`,
+    preheader: correction => `${correction ? "Korektę" : "Dokument"} znajdziesz w załączniku i na swoim koncie.`,
+    heading: correction => correction ? "Korekta faktury jest gotowa" : "Twoja faktura jest gotowa",
+    attachment: correction => correction ? "Korektę faktury przesyłamy w załączniku PDF." : "Fakturę przesyłamy w załączniku PDF.",
+    orderLabel: "Zamówienie",
+    documentLabel: correction => correction ? "Korekta" : "Faktura",
+    cta: "Zobacz dokumenty na koncie",
+    availability: "Dokument pozostaje dostępny na Twoim koncie niezależnie od dostarczenia tej wiadomości.",
+  },
+  en: {
+    subject: (ref, correction) => `${correction ? "Invoice correction" : "Invoice"} for order ${ref}`,
+    preheader: correction => `The ${correction ? "correction" : "document"} is attached and available in your account.`,
+    heading: correction => correction ? "Your invoice correction is ready" : "Your invoice is ready",
+    attachment: correction => correction ? "Your invoice correction is attached as a PDF." : "Your invoice is attached as a PDF.",
+    orderLabel: "Order",
+    documentLabel: correction => correction ? "Correction" : "Invoice",
+    cta: "View documents in your account",
+    availability: "The document remains available in your account regardless of delivery of this message.",
+  },
+};
+
+/** Pure defaults; hosts may replace the complete bilingual copy. */
+export function createInvoiceDocumentContentFactory(copy: Record<Locale, InvoiceDocumentCopy> = defaults) {
+  function invoiceDocumentEmailContent(locale: Locale, vars: InvoiceDocumentVars): { subject: string; preheader: string; blocks: EmailBlock[] } {
+    const c = copy[locale], correction = vars.kind === "correction";
+    return {
+      subject: c.subject(vars.orderRef, correction), preheader: c.preheader(correction),
+      blocks: [heading(c.heading(correction)), paragraph(c.attachment(correction)),
+        dataTable([{ label: c.orderLabel, value: vars.orderRef }, { label: c.documentLabel(correction), value: vars.documentNumber }]),
+        button(c.cta, vars.accountDocumentsUrl), paragraph(c.availability, { muted: true })],
+    };
+  }
+  return { invoiceDocumentEmailContent };
+}

package/src/communications/contracts/marketingAutomation.ts

@@ -0,0 +1,45 @@
+/** Scope is selected by the host. Remote account state is never local consent authority. */
+export interface MarketingAutomationScope {
+  readonly bindingId: string;
+  readonly accountReference: string;
+  readonly audienceReference: string;
+}
+export interface MarketingAutomationClaim {
+  readonly scope: MarketingAutomationScope;
+  readonly effectId: string;
+  readonly idempotencyKey: string;
+  readonly claimToken: string;
+  readonly generation: number;
+  readonly deadlineMs: number;
+  readonly attempt: number;
+  /** Opaque host reference; no email, profile attributes, tokens or payload bodies. */
+  readonly subjectReference: string;
+}
+export type MarketingAutomationObservation = {
+  readonly effectId: string;
+  readonly generation: number;
+  readonly observedAtMs: number;
+} & (
+  | { readonly status: "accepted"; readonly remoteReference: string }
+  | { readonly status: "ambiguous"; readonly retryAfterMs: number }
+  | { readonly status: "throttled"; readonly retryAfterMs: number }
+  | { readonly status: "refused"; readonly reason: "restricted" | "unsupported" | "deadline" | "scope" }
+);
+export interface MarketingAutomationProviderPort {
+  readonly scope: MarketingAutomationScope;
+  /** Admission is explicit and short lived; scope, deadline and idempotency fences apply at effect time too. */
+  admit(claim: MarketingAutomationClaim, nowMs: number): Promise<"admitted" | "refused">;
+  /** Acknowledgement needs an observation; acceptance does not mean delivery or grant consent. */
+  apply(claim: MarketingAutomationClaim, nowMs: number): Promise<MarketingAutomationObservation>;
+  /** Reconcile ambiguity before retrying an effect that might already have been accepted. */
+  observe(claim: MarketingAutomationClaim, nowMs: number): Promise<MarketingAutomationObservation | null>;
+}
+export interface MarketingAutomationStorePort {
+  /** Unsupported/no-trigger work is not claimed. No runner or schedule is installed by this contract. */
+  claim(scope: MarketingAutomationScope, nowMs: number): Promise<MarketingAutomationClaim | null>;
+  /** Atomic scope + current token + generation + deadline check before provider admission. */
+  isCurrent(claim: MarketingAutomationClaim, nowMs: number): Promise<boolean>;
+  /** Persist observation/history with the same fences; stale workers cannot settle newer work. */
+  settle(claim: MarketingAutomationClaim, observation: MarketingAutomationObservation, nowMs: number): Promise<boolean>;
+  history(scope: MarketingAutomationScope, effectId: string): Promise<readonly MarketingAutomationObservation[]>;
+}

package/src/communications/contracts/marketingSync.ts

@@ -0,0 +1,109 @@
+// Private helpers/symbols, never exported. Brands are not serialization authority.
+declare const subjectBrand: unique symbol, feedbackBrand: unique symbol,
+  receiptBrand: unique symbol, readBrand: unique symbol;
+type Operation = "profile.sync" | "consent.read" | "erasure.request" | "erasure.read";
+type Mutation = "profile.sync" | "erasure.request";
+type SubjectReference = string & { readonly [subjectBrand]: "opaque-subject" };
+export type SyncBinding = Readonly<{ account: string; environment: string; namespace: string; mappingVersion: string }>;
+export type SyncAudience = Readonly<{ kind: "account-wide" } | { kind: "audience"; reference: string }>;
+export type ProfileProjection = Readonly<{
+  email: string; externalReference: string;
+  fields: Readonly<Partial<Record<"givenName" | "familyName" | "locale", string>>>;
+  properties: Readonly<Record<string, string | number | boolean>>;
+}>;
+type Payload = {
+  "profile.sync": { projection: ProfileProjection; consentEvidenceReference: string };
+  "consent.read": Readonly<Record<string, never>>;
+  "erasure.request": { caseReference: string; authorityReference: string };
+  "erasure.read": { receipt: SyncReceipt<"erasure.request"> };
+};
+export type SyncRequest<O extends Operation = Operation> = { [K in O]: Readonly<{
+  binding: SyncBinding; audience: SyncAudience; subjectReference: SubjectReference;
+  requestId: string; generation: number; deadlineMs: number; authorizationReference: string;
+  operation: K; payload: Readonly<Payload[K]>;
+}> }[O];
+export type NegativeFeedback = Readonly<{
+  [feedbackBrand]: "provider-negative"; sourceReference: string; occurredAtMs: number | null; audience: SyncAudience;
+}> & Readonly<
+  | { kind: "unsubscribe" | "complaint" | "manual_block"; outcome: "deny_permission" }
+  | { kind: "hard_bounce" | "invalid_address"; outcome: "deny_delivery" }
+>;
+export type ConsentReadback = Readonly<{
+  audience: SyncAudience; observedAtMs: number;
+  remoteConsent: "subscribed" | "unsubscribed" | "pending" | "never_subscribed" | "unknown";
+  feedback: readonly NegativeFeedback[];
+  // Coverage describes this current-state observation only; never historical completeness.
+  coverage: "complete" | "partial" | "unsupported";
+}>;
+export type SyncFailure<O extends Operation = Operation> =
+  | { kind: "refused"; reason: "invalid_request" | "binding" | "provenance" | "stale" | "deadline" |
+      "unsupported" | "verification_pending" | "restricted" | "identity_conflict" | "provider_refusal" }
+  | { kind: "retryable"; reason: "cooling" | "host" | "provider"; afterSeconds: number }
+  | ({ kind: "unknown"; reason: "dispatch_unresolved" | "acceptance_ambiguous" | "record_failed" } &
+      (O extends Mutation ? { receipt?: SyncReceipt<O> } : { receipt?: never }));
+// Receipt identifies the original admitted mutation; status lives only in the result union.
+export type SyncReceipt<O extends Mutation> = Readonly<{
+  [receiptBrand]: O; operation: O; request: SyncRequest<O>;
+}>;
+type MutationSuccess<O extends Mutation> =
+  { kind: "accepted" | "acknowledged"; receipt: SyncReceipt<O>; journal: "confirmed" | "unknown" };
+type Success = {
+  "profile.sync": MutationSuccess<"profile.sync">;
+  "consent.read": { kind: "completed"; value: ConsentReadback; journal: "confirmed" | "unknown" };
+  "erasure.request": MutationSuccess<"erasure.request">;
+  "erasure.read": MutationSuccess<"erasure.request"> | {
+    kind: "completed"; receipt: SyncReceipt<"erasure.request">; journal: "confirmed" | "unknown";
+    evidence: Readonly<{ [readBrand]: "provider-read"; readRequestId: string; observedAtMs: number;
+      evidenceReference: string; assurance: "provider_record_deleted" | "provider_erasure_confirmed" }>;
+  };
+};
+export type SyncResult<O extends Operation = Operation> = { [K in O]:
+  Readonly<Pick<SyncRequest<K>, "binding" | "operation" | "subjectReference" | "requestId" | "generation">> &
+  Readonly<Success[K] | SyncFailure<K>>
+}[O];
+export type SyncCapabilities = Readonly<{ binding: SyncBinding; audience: SyncAudience; operations: Readonly<Record<Operation,
+  { state: "supported"; evidenceReference: string; maxRequestBytes: number; maxFeedbackItems: number } |
+  { state: "unsupported" | "verification_pending" }>> }>;
+export interface ProfileSyncPort {
+  sync(request: SyncRequest<"profile.sync">): Promise<SyncResult<"profile.sync">>;
+}
+export interface ConsentReadPort {
+  read(request: SyncRequest<"consent.read">): Promise<SyncResult<"consent.read">>;
+}
+export interface ErasurePort {
+  request(request: SyncRequest<"erasure.request">): Promise<SyncResult<"erasure.request">>;
+  read(request: SyncRequest<"erasure.read">): Promise<SyncResult<"erasure.read">>;
+}
+export interface MarketingSyncProvider {
+  readonly capabilities: SyncCapabilities;
+  readonly profiles: ProfileSyncPort; readonly consent: ConsentReadPort; readonly erasure: ErasurePort;
+}
+
+export type ConsentPushRequest = Readonly<
+  Omit<SyncRequest<"profile.sync">, "operation" | "audience" | "payload"> & {
+    operation: "consent.push";
+  } & (
+    { audience: Extract<SyncAudience, { kind: "audience" }>;
+      payload: Readonly<{ action: "grant"; consentEvidenceReference: string }> } |
+    { audience: SyncAudience;
+      payload: Readonly<{ action: "withdraw"; consentEvidenceReference: string }> }
+  )>;
+declare const pushReceiptBrand: unique symbol; // private, same receipt style
+type PushReceipt = Readonly<{ [pushReceiptBrand]: "consent.push";
+  operation: "consent.push"; request: ConsentPushRequest }>;
+type PushFailure = Exclude<SyncFailure, { kind: "unknown" }> |
+  (Omit<Extract<SyncFailure, { kind: "unknown" }>, "receipt"> & { receipt?: PushReceipt });
+export type ConsentPushResult = Readonly<Pick<ConsentPushRequest,
+  "binding" | "operation" | "subjectReference" | "requestId" | "generation">> & Readonly<
+    { kind: "accepted" | "acknowledged"; receipt: PushReceipt;
+      journal: "confirmed" | "unknown"; reconcileRequired: boolean } | PushFailure>;
+export interface ConsentPushPort {
+  readonly capabilities: SyncCapabilities & Readonly<{
+    operations: SyncCapabilities["operations"] & Readonly<{
+      "consent.push": SyncCapabilities["operations"]["profile.sync"] & Readonly<{
+        grantEffect: "audience" | "account-wide";
+      }>;
+    }>;
+  }>;
+  push(request: ConsentPushRequest): Promise<ConsentPushResult>;
+}

package/src/communications/contracts/newsletter.ts

@@ -0,0 +1,78 @@
+export type NewsletterProviderKind = string;
+export type NewsletterMarketingPurpose = "marketing_launch_offer" | "marketing_newsletter";
+export type NewsletterSyncEventType = "subscribe" | "update" | "unsubscribe" | "suppress";
+export type NewsletterWebhookEventType = "subscribe" | "update" | "unsubscribe" | "suppress" | "complaint" | "bounce" | "email_change" | "profile_update" | "ignored";
+export type NewsletterProviderCapabilityKey =
+  "subscribe" | "unsubscribe" | "suppress" | "unsuppress" | "doubleOptIn" | "emailChange" | "listMembership" | "webhookIdempotency" | "retryAfter";
+
+export type NewsletterProviderCapabilities = Record<NewsletterProviderCapabilityKey, boolean>;
+
+export interface NewsletterWebhookEvent<Purpose extends string = NewsletterMarketingPurpose> {
+  providerKind: NewsletterProviderKind;
+  providerEventId: string;
+  eventType: NewsletterWebhookEventType;
+  email: string | null;
+  remoteProfileId: string | null;
+  remoteListId: string | null;
+  purpose: Purpose | null;
+  explicitOptInEvidence: boolean;
+  doubleOptInStatus: "confirmed" | "pending" | "unknown";
+  occurredAt: string | null;
+  rawPayload: Record<string, unknown>;
+}
+
+
+export interface NewsletterSyncEvent<Purpose extends string = NewsletterMarketingPurpose> {
+  id: string;
+  claimToken: string;
+  contactId: string;
+  normalizedEmail: string;
+  eventType: NewsletterSyncEventType;
+  purpose: Purpose;
+  payload: Record<string, unknown>;
+  attemptCount: number;
+  originProviderKind?: NewsletterProviderKind | null;
+  originProviderEventId?: string | null;
+  remoteProfileId?: string | null;
+  remoteListId?: string | null;
+}
+
+
+export type NewsletterSyncOutcome =
+  | {
+      status: "sent";
+      remoteProfileId?: string | null;
+      responseSummary?: Record<string, unknown>;
+    }
+  | {
+      status: "skipped";
+      reason: string;
+      responseSummary?: Record<string, unknown>;
+    }
+  | {
+      status: "retry";
+      reason: string;
+      retryAfterSeconds?: number;
+    };
+
+export interface NewsletterSyncProviderPort<Purpose extends string = NewsletterMarketingPurpose> {
+  readonly providerKind: string;
+  readonly capabilities: NewsletterProviderCapabilities;
+  sync(event: NewsletterSyncEvent<Purpose>): Promise<NewsletterSyncOutcome>;
+  reconcile?(): Promise<NewsletterSyncReconcileOutcome>;
+}
+
+export type NewsletterSyncReconcileOutcome =
+  | {
+      status: "skipped";
+      reason: string;
+      responseSummary?: Record<string, unknown>;
+    }
+  | {
+      status: "checked";
+      checked: number;
+      updated: number;
+      failures: number;
+      responseSummary?: Record<string, unknown>;
+    };
+

package/src/communications/contracts/newsletterWebhook.ts

@@ -0,0 +1,23 @@
+import type { NewsletterMarketingPurpose, NewsletterWebhookEvent } from "./newsletter.js";
+export type NormalizedNewsletterWebhookEvent<Purpose extends string = NewsletterMarketingPurpose> = NewsletterWebhookEvent<Purpose>;
+export interface NewsletterWebhookPort<Purpose extends string = NewsletterMarketingPurpose> {
+  recordProviderEvent(input: NewsletterWebhookEvent<Purpose> & {
+    state: "unknown" | "granted" | "denied" | "suppressed" | null;
+    processingStatus: "received" | "ignored";
+  }): Promise<{ providerEventId: string; contactId: string | null; inserted: boolean }>;
+  recordPermission(input: {
+    contactId: string;
+    providerKind: string;
+    providerEventId: string;
+    purpose: Purpose;
+    state: "granted" | "suppressed";
+    reason: string;
+    metadata: Record<string, unknown>;
+  }): Promise<void>;
+  markProviderEvent(input: {
+    providerEventId: string;
+    status: "processed" | "ignored" | "failed";
+    metadata: Record<string, unknown>;
+  }): Promise<void>;
+}
+

package/src/communications/contracts/optOutContent.ts

@@ -0,0 +1,23 @@
+import type { Locale } from "./email.js";
+
+export type OptOutOutcome = "invalid_link" | "marketing_applied" | "missing_information" | "not_found" | "legacy_applied" | "legacy_replay" | "error";
+export interface OptOutContent { title: string; message: string }
+export type OptOutCopy = Record<OptOutOutcome, Record<Locale, OptOutContent>>;
+const defaults: OptOutCopy = {
+  invalid_link: { pl: {"title": "Link nieprawidłowy lub wygasł", "message": "Nie udało się przetworzyć tej prośby. Skopiuj pełny link z wiadomości lub napisz na {supportEmail}."}, en: {"title": "Invalid or expired link", "message": "We couldn't process this request. Copy the full link from the email or email {supportEmail}."} },
+  marketing_applied: { pl: {"title": "Wypisano", "message": "Nie będziesz już otrzymywać tych wiadomości marketingowych. Wiadomości potrzebne do obsługi konta, zamówień, płatności i subskrypcji mogą nadal przychodzić."}, en: {"title": "You're unsubscribed", "message": "You won't receive these marketing emails anymore. Messages needed to manage your account, orders, payments and subscriptions may still arrive."} },
+  missing_information: { pl: {"title": "Brakuje danych", "message": "Nieprawidłowy link do wypisania."}, en: {"title": "Missing information", "message": "This unsubscribe link is incomplete."} },
+  not_found: { pl: {"title": "Nie znaleziono", "message": "Nie znaleziono takiego zgłoszenia."}, en: {"title": "Not found", "message": "We couldn't find this request."} },
+  legacy_applied: { pl: {"title": "Wypisano", "message": "Zapisaliśmy Twoją rezygnację z wybranych wiadomości. Wiadomości potrzebne do obsługi konta, zamówień, płatności i subskrypcji mogą nadal przychodzić."}, en: {"title": "You're unsubscribed", "message": "We've recorded your opt-out from the selected messages. Messages needed to manage your account, orders, payments and subscriptions may still arrive."} },
+  legacy_replay: { pl: {"title": "Już wypisano", "message": "Twoja rezygnacja z wybranych wiadomości jest już zapisana. Wiadomości potrzebne do obsługi konta, zamówień, płatności i subskrypcji mogą nadal przychodzić."}, en: {"title": "Already unsubscribed", "message": "Your opt-out from the selected messages is already recorded. Messages needed to manage your account, orders, payments and subscriptions may still arrive."} },
+  error: { pl: {"title": "Błąd", "message": "Coś poszło nie tak. Spróbuj ponownie później."}, en: {"title": "Error", "message": "Something went wrong. Try again later."} },
+};
+
+/** Display only; the caller independently verifies and durably records opt-out. */
+export function createOptOutContentFactory(copy: OptOutCopy = defaults) {
+  function optOutContent(locale: Locale, outcome: OptOutOutcome, supportEmail: string): OptOutContent {
+    const c = copy[outcome][locale];
+    return { title: c.title, message: c.message.split("{supportEmail}").join(supportEmail) };
+  }
+  return { optOutContent };
+}

package/src/communications/contracts/orderCanceled.ts

@@ -0,0 +1,64 @@
+import type { CommerceEmailContent } from "./commerceEmailContent.js";
+import type { Locale } from "./email.js";
+import {
+  accentBox,
+  button,
+  heading,
+  paragraph,
+  type EmailBlock,
+} from "./blocks.js";
+
+export interface OrderCanceledEmailVars {
+  firstName: string | null;
+  orderId: string;
+  /** Formatted gross total, e.g. "129,99 zł", or null when unknown. */
+  amountLabel: string | null;
+  /** Absolute CTA URL (back to shop); null/absent → no button. */
+  ctaUrl?: string | null;
+  /** Optional context name for the selected return note. */
+  contextName?: string | null;
+}
+
+export interface OrderCanceledEmailContent {
+  subject: string;
+  preheader: string;
+  blocks: EmailBlock[];
+}
+
+/** Bind host-selected copy and pure helpers without provider or environment access. */
+export function createOrderCanceledContentFactory(input: {
+  commerceEmailContent: Pick<CommerceEmailContent, "orderCanceled" | "orderRefPrefix">;
+  formatCustomerOrderReference: (orderId: string, prefix: string) => string;
+}) {
+  const { commerceEmailContent, formatCustomerOrderReference } = input;
+
+  function orderCanceledEmailContent(
+    locale: Locale,
+    vars: OrderCanceledEmailVars,
+    signoff: string,
+  ): OrderCanceledEmailContent {
+    const copy = commerceEmailContent.orderCanceled[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 }),
+      paragraph(copy.returnNote(vars.contextName ?? null)),
+    ];
+
+    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 { orderCanceledEmailContent };
+}

package/src/communications/contracts/orderDraft.ts

@@ -0,0 +1,112 @@
+import type { CommerceEmailContent } from "./commerceEmailContent.js";
+import type { Locale } from "./email.js";
+import {
+  button,
+  dataTable,
+  heading,
+  list,
+  paragraph,
+  type EmailBlock,
+} from "./blocks.js";
+
+export interface OrderDraftLineItem {
+  /** Resolved, localized product name (or slug/sku fallback). */
+  name: string;
+  quantity: number;
+  /** Formatted gross line total, e.g. "129,98 zł"; "" when price unknown. */
+  lineTotalLabel: string;
+}
+
+export interface OrderDraftTotals {
+  /** null → omit the subtotal row (value unknown); never alias the grand total. */
+  subtotalLabel: string | null;
+  /** Already sign-prefixed, e.g. "-20,00 zł"; null → no discount row. */
+  discountLabel: string | null;
+  totalLabel: string;
+}
+
+export interface OrderDraftEmailVars {
+  firstName: string | null;
+  /** Technical order id from outbox, e.g. "order_<uuid>". */
+  orderId: string;
+  /** Itemized order lines (name × qty + line total). */
+  items: OrderDraftLineItem[];
+  /** Money breakdown, or null when totals are unknown. */
+  totals: OrderDraftTotals | null;
+  /** Absolute CTA URL back to the configurator; null/absent → no button. */
+  ctaUrl?: string | null;
+  /**
+   * Dog's name from the owner's survey, when known. Drives an optional warm
+   * closing line. Absent/null (e.g. anonymous drafts) → the line is omitted.
+   * Never inflect the copy by gender: the name doesn't reveal it.
+   */
+  contextName?: string | null;
+}
+
+export interface OrderDraftEmailContent {
+  subject: string;
+  preheader: string;
+  blocks: EmailBlock[];
+}
+
+/** Bind host-selected copy and pure helpers without provider or environment access. */
+export function createOrderDraftContentFactory(input: {
+  commerceEmailContent: Pick<CommerceEmailContent, "orderDraft" | "orderRefPrefix">;
+  formatCustomerOrderReference: (orderId: string, prefix: string) => string;
+}) {
+  const { commerceEmailContent, formatCustomerOrderReference } = input;
+
+  function itemLine(item: OrderDraftLineItem): string {
+    const base = `${item.quantity}× ${item.name}`;
+    return item.lineTotalLabel ? `${base} – ${item.lineTotalLabel}` : base;
+  }
+
+  function orderDraftEmailContent(
+    locale: Locale,
+    vars: OrderDraftEmailVars,
+    signoff: string,
+  ): OrderDraftEmailContent {
+    const copy = commerceEmailContent.orderDraft[locale];
+    const orderRef = formatCustomerOrderReference(vars.orderId, commerceEmailContent.orderRefPrefix);
+    const blocks: EmailBlock[] = [
+      heading(copy.heading),
+      paragraph(copy.greeting(vars.firstName)),
+      paragraph(copy.intro(orderRef)),
+    ];
+
+    blocks.push(
+      vars.items.length > 0
+        ? list(vars.items.map(itemLine))
+        : paragraph(copy.noItems),
+    );
+
+    if (vars.totals) {
+      const rows: Array<{ label: string; value: string }> = [];
+      if (vars.totals.subtotalLabel) {
+        rows.push({ label: copy.subtotalLabel, value: vars.totals.subtotalLabel });
+      }
+      if (vars.totals.discountLabel) {
+        rows.push({ label: copy.discountRowLabel, value: vars.totals.discountLabel });
+      }
+      rows.push({ label: copy.totalLabel, value: vars.totals.totalLabel });
+      blocks.push(dataTable(rows));
+    }
+
+    if (vars.ctaUrl) {
+      blocks.push(button(copy.cta, vars.ctaUrl));
+    }
+
+    blocks.push(paragraph(copy.outro));
+    if (vars.contextName) {
+      blocks.push(paragraph(copy.personalizedClosing(vars.contextName)));
+    }
+    blocks.push(paragraph(signoff));
+
+    return {
+      subject: copy.subject(orderRef),
+      preheader: copy.preheader,
+      blocks,
+    };
+  }
+  return { orderDraftEmailContent };
+}