@openlup/platform 0.16.0 → 0.18.0

package/src/communications/contracts/subscriptionPaymentFailed.ts

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

package/src/communications/contracts/subscriptionPaymentRecovered.ts

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

package/src/communications/contracts/subscriptionRenewalAtRisk.ts

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

package/src/communications/contracts/subscriptionRenewalUpcoming.ts

@@ -0,0 +1,103 @@
+import type { SubscriptionEmailContent } from "./subscriptionEmailContent.js";
+import type { Locale } from "./email.js";
+import type { SubscriptionRenewalUpcomingCopy } from "./subscriptionEmailContent.js";
+import {
+  accentBox,
+  button,
+  heading,
+  paragraph,
+  type EmailBlock,
+} from "./blocks.js";
+
+export interface SubscriptionRenewalUpcomingEmailVars {
+  firstName: string | null;
+  /** Pre-formatted renewal CHARGE date (locale-formatted by the worker). */
+  renewalDateLabel: string | null;
+  /** Pre-formatted estimated delivery window, or null when unavailable. */
+  deliveryWindowLabel?: string | null;
+  /** Localized holiday caveat; present ONLY when a holiday moved the window. */
+  holidayNote?: string | null;
+  /**
+   * Pre-formatted composition edit deadline. Null when unknown OR when the
+   * deadline has already passed at send time — see the module header.
+   */
+  editCutoffLabel?: string | null;
+  /** Formatted gross amount of the upcoming charge, e.g. "129,99 zł", or null. */
+  amountLabel: string | null;
+  /**
+   * Starter-pack acquisition stage of the delivery being announced, or null for
+   * an ordinary renewal. `"graduation"` means the NEXT delivery switches to the
+   * steady package — a size and rhythm change the customer agreed to at checkout
+   * but has not seen since, so it gets its own paragraph rather than a detail
+   * line. `"delivery2"` only marks the discounted repeat; its amount already
+   * rides on `amountLabel`.
+   */
+  starterStage?: "delivery2" | "graduation" | null;
+  /** Units per delivery from the graduation on; renders only with `"graduation"`. */
+  starterSteadyUnitCount?: number | null;
+  /** Days between deliveries from the graduation on; renders only with `"graduation"`. */
+  starterSteadyCadenceDays?: number | null;
+  /** Adopter-formatted steady package, already localized; renders only with `"graduation"`. */
+  starterSteadyDetail?: string | null;
+  /** Absolute "manage subscription" URL; null/absent → no button. */
+  ctaUrl?: string | null;
+  /** Optional consumer context label; absent/null uses the selected pack's fallback. */
+  contextName?: string | null;
+}
+
+export interface SubscriptionRenewalUpcomingEmailContent {
+  subject: string;
+  preheader: string;
+  blocks: EmailBlock[];
+}
+
+/** Bind host-selected copy and pure helpers without provider or environment access. */
+export function createSubscriptionRenewalUpcomingContentFactory(input: {
+  subscriptionEmailContent: Pick<SubscriptionEmailContent, "renewalUpcoming">;
+}) {
+  const { subscriptionEmailContent } = input;
+
+  function subscriptionRenewalUpcomingEmailContent(
+    locale: Locale,
+    vars: SubscriptionRenewalUpcomingEmailVars,
+    signoff: string,
+  ): SubscriptionRenewalUpcomingEmailContent {
+    const copy: SubscriptionRenewalUpcomingCopy = subscriptionEmailContent.renewalUpcoming[locale];
+    const details: string[] = [
+      vars.renewalDateLabel ? copy.dateLine(vars.renewalDateLabel) : copy.noDateLine,
+    ];
+    if (vars.deliveryWindowLabel) details.push(copy.deliveryLine(vars.deliveryWindowLabel));
+    if (vars.holidayNote) details.push(vars.holidayNote);
+    if (vars.amountLabel) details.push(copy.amountLine(vars.amountLabel));
+    // Null when already past — the caller, not this renderer, owns that decision.
+    if (vars.editCutoffLabel) details.push(copy.editCutoffLine(vars.editCutoffLabel));
+
+    const blocks: EmailBlock[] = [
+      heading(copy.heading),
+      paragraph(copy.greeting(vars.firstName)),
+      paragraph(copy.intro(vars.contextName ?? null)),
+      accentBox(details, { label: copy.detailsLabel }),
+    ];
+
+    // The package-size change is the one thing in this email a customer could be
+    // surprised by, so it gets its own paragraph ABOVE the generic self-service
+    // line, and it names moving the delivery first.
+    if (vars.starterStage === "graduation" && vars.starterSteadyUnitCount && vars.starterSteadyCadenceDays) {
+      blocks.push(paragraph(copy.starterGraduationLine(vars.starterSteadyUnitCount, vars.starterSteadyCadenceDays, vars.starterSteadyDetail)));
+    }
+    blocks.push(paragraph(copy.manageLine));
+
+    if (vars.ctaUrl) {
+      blocks.push(button(copy.cta, vars.ctaUrl));
+    }
+
+    blocks.push(paragraph(signoff));
+
+    return {
+      subject: copy.subject,
+      preheader: copy.preheader,
+      blocks,
+    };
+  }
+  return { subscriptionRenewalUpcomingEmailContent };
+}

package/src/communications/contracts/subscriptionResumed.ts

@@ -0,0 +1,60 @@
+import type { SubscriptionEmailContent } from "./subscriptionEmailContent.js";
+import type { Locale } from "./email.js";
+import {
+  accentBox,
+  button,
+  heading,
+  paragraph,
+  type EmailBlock,
+} from "./blocks.js";
+
+export interface SubscriptionResumedEmailVars {
+  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;
+  /** Optional consumer context label; absent/null uses the selected pack's fallback. */
+  contextName?: string | null;
+}
+
+export interface SubscriptionResumedEmailContent {
+  subject: string;
+  preheader: string;
+  blocks: EmailBlock[];
+}
+
+/** Bind host-selected copy and pure helpers without provider or environment access. */
+export function createSubscriptionResumedContentFactory(input: {
+  subscriptionEmailContent: Pick<SubscriptionEmailContent, "resumed">;
+}) {
+  const { subscriptionEmailContent } = input;
+
+  function subscriptionResumedEmailContent(
+    locale: Locale,
+    vars: SubscriptionResumedEmailVars,
+    signoff: string,
+  ): SubscriptionResumedEmailContent {
+    const copy = subscriptionEmailContent.resumed[locale];
+    const blocks: EmailBlock[] = [
+      heading(copy.heading),
+      paragraph(copy.greeting(vars.firstName)),
+      paragraph(copy.intro(vars.contextName ?? null)),
+      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 { subscriptionResumedEmailContent };
+}

package/src/communications/contracts/subscriptionWelcome.ts

@@ -0,0 +1,102 @@
+import type { SubscriptionEmailContent } from "./subscriptionEmailContent.js";
+import type { Locale } from "./email.js";
+import type { SubscriptionWelcomeCopy } from "./subscriptionEmailContent.js";
+import {
+  accentBox,
+  button,
+  heading,
+  paragraph,
+  type EmailBlock,
+} from "./blocks.js";
+
+export interface SubscriptionWelcomeEmailVars {
+  firstName: string | null;
+  cadenceDays: number | null;
+  /** Pre-formatted renewal CHARGE date (locale-formatted by the handler), or null. */
+  chargeDateLabel: string | null;
+  /** Pre-formatted estimated delivery window, e.g. "04.08.2026 – 05.08.2026", or null. */
+  deliveryWindowLabel: string | null;
+  /** Pre-formatted composition edit deadline, or null when unknown/already passed. */
+  editCutoffLabel?: string | null;
+  /**
+   * Localized holiday caveat, supplied by the handler ONLY when a public holiday
+   * actually moved the estimated window. Null/absent is the normal case and must
+   * render nothing — a standing "we account for holidays" line is noise.
+   */
+  holidayNote?: string | null;
+  /** Absolute "manage subscription" URL; null/absent → no button. */
+  ctaUrl?: string | null;
+  /**
+   * Starter-pack acquisition facts, present only for a subscription that carries
+   * an acquisition marker. `starterAmountLabel` is the DELIVERY-2 amount — the
+   * discounted repeat that lands on the date already stated above — and the
+   * steady pair describes what delivery 3 onwards looks like. The whole block is
+   * dropped when any of it is unknown; a half-stated plan is worse than none.
+   */
+  starterAmountLabel?: string | null;
+  starterSteadyUnitCount?: number | null;
+  starterSteadyCadenceDays?: number | null;
+  /** Adopter-formatted steady package, already localized; the steady line's third argument. */
+  starterSteadyDetail?: string | null;
+}
+
+export interface SubscriptionWelcomeEmailContent {
+  subject: string;
+  preheader: string;
+  blocks: EmailBlock[];
+}
+
+/** Bind host-selected copy and pure helpers without provider or environment access. */
+export function createSubscriptionWelcomeContentFactory(input: {
+  subscriptionEmailContent: Pick<SubscriptionEmailContent, "welcome">;
+}) {
+  const { subscriptionEmailContent } = input;
+
+  function subscriptionWelcomeEmailContent(
+    locale: Locale,
+    vars: SubscriptionWelcomeEmailVars,
+    signoff: string,
+  ): SubscriptionWelcomeEmailContent {
+    const copy: SubscriptionWelcomeCopy = subscriptionEmailContent.welcome[locale];
+    const details: string[] = [];
+    if (vars.cadenceDays && vars.cadenceDays > 0) details.push(copy.cadenceLine(vars.cadenceDays));
+    // Both labels are derived from the same `next_cycle_at`, so they are present or
+    // absent together; the fallback keeps the pre-existing "we'll confirm" promise.
+    details.push(
+      vars.chargeDateLabel && vars.deliveryWindowLabel
+        ? copy.deliveryLine(vars.deliveryWindowLabel, vars.chargeDateLabel)
+        : copy.fallbackLine,
+    );
+    if (vars.holidayNote) details.push(vars.holidayNote);
+    // Acquisition plan: the delivery-2 amount and the steady rhythm, stated once at
+    // the only moment the customer is actually reading about their plan.
+    if (vars.starterAmountLabel) details.push(copy.starterDelivery2Line(vars.starterAmountLabel));
+    if (vars.starterSteadyUnitCount && vars.starterSteadyCadenceDays) {
+      details.push(copy.starterSteadyLine(vars.starterSteadyUnitCount, vars.starterSteadyCadenceDays, vars.starterSteadyDetail));
+    }
+    if (vars.editCutoffLabel) details.push(copy.editCutoffLine(vars.editCutoffLabel));
+
+    const blocks: EmailBlock[] = [
+      heading(copy.heading),
+      paragraph(copy.greeting(vars.firstName)),
+      paragraph(copy.intro),
+      accentBox(details, { label: copy.detailsLabel }),
+    ];
+
+    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: copy.subject,
+      preheader: copy.preheader,
+      blocks,
+    };
+  }
+  return { subscriptionWelcomeEmailContent };
+}

package/src/communications/contracts/subscriptionWinback.ts

@@ -0,0 +1,62 @@
+import type { SubscriptionEmailContent } from "./subscriptionEmailContent.js";
+import type { Locale } from "./email.js";
+import type { SubscriptionWinbackCopy } from "./subscriptionEmailContent.js";
+import {
+  accentBox,
+  button,
+  heading,
+  paragraph,
+  type EmailBlock,
+} from "./blocks.js";
+
+export interface SubscriptionWinbackEmailVars {
+  firstName: string | null;
+  /** Consumer-facing brand label injected by the app/composition root. */
+  brandName: string;
+  /** Absolute CTA URL (the customer account / "Wznów" button); null/absent → no button. */
+  ctaUrl?: string | null;
+}
+
+export interface SubscriptionWinbackEmailContent {
+  subject: string;
+  preheader: string;
+  blocks: EmailBlock[];
+}
+
+/** Bind host-selected copy and pure helpers without provider or environment access. */
+export function createSubscriptionWinbackContentFactory(input: {
+  subscriptionEmailContent: Pick<SubscriptionEmailContent, "winback">;
+}) {
+  const { subscriptionEmailContent } = input;
+
+  function subscriptionWinbackEmailContent(
+    locale: Locale,
+    vars: SubscriptionWinbackEmailVars,
+    signoff: string,
+  ): SubscriptionWinbackEmailContent {
+    const copy: SubscriptionWinbackCopy = subscriptionEmailContent.winback[locale];
+    const blocks: EmailBlock[] = [
+      heading(copy.heading),
+      paragraph(copy.greeting(vars.firstName)),
+      paragraph(copy.intro),
+    ];
+    if (copy.reasonsLabel) {
+      blocks.push(paragraph(copy.reasonsLabel(vars.brandName)));
+    }
+    blocks.push(accentBox(copy.reasons));
+
+    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 { subscriptionWinbackEmailContent };
+}

package/src/communications/contracts/transactionalDelivery.ts

@@ -0,0 +1,43 @@
+export interface TransactionalDeliveryCommand {
+  readonly idempotencyKey: string;
+  /** Opaque recipient reference; never persisted outside the command fingerprint. */
+  readonly recipientReference: string;
+  /** Opaque template reference; never persisted outside the command fingerprint. */
+  readonly templateReference: string;
+  /** Optional bounded reference to an expiring/revocable access grant. */
+  readonly accessGrantReference?: string;
+}
+
+export type TransactionalDeliveryReceipt = {
+  readonly idempotencyKey: string;
+  readonly commandFingerprint: string;
+  readonly state: "accepted";
+  readonly deliveryReference: string;
+  readonly errorCode: null;
+  readonly attemptCount: number;
+} | {
+  readonly idempotencyKey: string;
+  readonly commandFingerprint: string;
+  readonly state: "failed";
+  readonly deliveryReference: null;
+  readonly errorCode: string;
+  readonly attemptCount: number;
+};
+
+export interface TransactionalDeliveryReceiptStore {
+  readReceipt(idempotencyKey: string): Promise<TransactionalDeliveryReceipt | null>;
+  recordAccepted(input: {
+    idempotencyKey: string;
+    commandFingerprint: string;
+    deliveryReference: string;
+  }): Promise<TransactionalDeliveryReceipt>;
+  recordFailed(input: {
+    idempotencyKey: string;
+    commandFingerprint: string;
+    errorCode: string;
+  }): Promise<TransactionalDeliveryReceipt>;
+}
+
+export interface CapturedTransactionalDeliveryPort {
+  deliver(command: TransactionalDeliveryCommand): Promise<{ deliveryReference: string }>;
+}

package/src/communications/contracts/types.ts

@@ -0,0 +1,58 @@
+type COMMUNICATION_CHANNEL = "email";
+
+type EMAIL_SEND_STATUSES = "queued" | "sent" | "delivered" | "bounced" | "complained" | "failed" | "skipped";
+
+type EMAIL_SEND_SKIP_REASONS = "sequence_paused" | "already_sent" | "template_unavailable" | "race_lost" | "policy_blocked" | "admin_disabled";
+
+
+export type CommunicationChannel = COMMUNICATION_CHANNEL;
+/** The host supplies its persisted provider vocabulary. */
+export type CommunicationProvider<Provider extends string = string> = Provider;
+export type EmailSendStatus = EMAIL_SEND_STATUSES;
+export type EmailSendSkipReason = EMAIL_SEND_SKIP_REASONS;
+
+type COMMUNICATION_PURPOSES = "transactional" | "tester_program" | "marketing_launch_offer" | "marketing_newsletter" | "subscription_dunning" | "admin_notification";
+
+type COMMUNICATION_PERMISSION_STATES = "unknown" | "granted" | "denied" | "suppressed";
+
+type COMMUNICATION_POLICY_DECISIONS = "allowed" | "blocked";
+
+export type CommunicationPurpose = COMMUNICATION_PURPOSES;
+export type CommunicationPermissionState = COMMUNICATION_PERMISSION_STATES;
+export type CommunicationPolicyDecision = COMMUNICATION_POLICY_DECISIONS;
+
+export interface CommunicationRecipientRef {
+  system: "supabase";
+  table: "testers";
+  id: string;
+  email: string | null;
+}
+
+export interface EmailTemplateRef {
+  slug: string;
+  locale: string | null;
+}
+
+export interface EmailSendDedupeKeyInput {
+  recipientId: string;
+  templateSlug: string;
+}
+
+export type EmailSendDecision =
+  | { outcome: "send" }
+  | {
+      outcome: "skip";
+      reason: EmailSendSkipReason;
+      existingMessageId: string | null;
+    };
+
+export interface EmailMessageReadModel<Provider extends string = string> {
+  id: string;
+  channel: CommunicationChannel;
+  recipientId: string;
+  templateSlug: string;
+  status: EmailSendStatus;
+  provider: CommunicationProvider<Provider> | null;
+  providerMessageId: string | null;
+  skippedReason: EmailSendSkipReason | null;
+}