@openlup/platform 0.16.0 → 0.17.0

package/dist/communications/contracts/subscriptionPaymentExpired.d.ts

@@ -0,0 +1,34 @@
+import type { SubscriptionEmailContent } from "./subscriptionEmailContent.js";
+import type { PaymentFailureCustomerCause } from "@openlup/core/payment";
+import type { Locale } from "./email.js";
+import { type EmailBlock } from "./blocks.js";
+export interface SubscriptionPaymentExpiredEmailVars {
+    firstName: string | null;
+    /** Formatted gross amount of the unpaid cycle, e.g. "129,99 zł", or null. */
+    amountLabel: string | null;
+    /**
+     * Why the charges were refused, in the payer-facing vocabulary. This template
+     * needs it most: "after several attempts" without a reason is the one place
+     * the rail asks for trust and offers nothing to trust. Absent or `unknown`
+     * renders no cause sentence.
+     */
+    cause?: PaymentFailureCustomerCause | null;
+    /**
+     * Recovery-link URL for the case's `resume_subscription` token. When present
+     * the template renders the resume CTA; when absent it keeps the support-led
+     * wording, because a button with no destination is worse than no button.
+     */
+    recoveryUrl?: string | null;
+}
+export interface SubscriptionPaymentExpiredEmailContent {
+    subject: string;
+    preheader: string;
+    blocks: EmailBlock[];
+}
+/** Bind host-selected copy and pure helpers without provider or environment access. */
+export declare function createSubscriptionPaymentExpiredContentFactory(input: {
+    subscriptionEmailContent: Pick<SubscriptionEmailContent, "paymentExpired">;
+    subscriptionPaymentCauseSentence: (locale: Locale, cause: PaymentFailureCustomerCause) => string | null;
+}): {
+    subscriptionPaymentExpiredEmailContent: (locale: Locale, vars: SubscriptionPaymentExpiredEmailVars, signoff: string) => SubscriptionPaymentExpiredEmailContent;
+};

package/dist/communications/contracts/subscriptionPaymentExpired.js

@@ -0,0 +1,37 @@
+import { accentBox, button, heading, paragraph, } from "./blocks.js";
+/** Bind host-selected copy and pure helpers without provider or environment access. */
+export function createSubscriptionPaymentExpiredContentFactory(input) {
+    const { subscriptionEmailContent, subscriptionPaymentCauseSentence } = input;
+    function subscriptionPaymentExpiredEmailContent(locale, vars, signoff) {
+        const copy = subscriptionEmailContent.paymentExpired[locale];
+        const recoveryUrl = vars.recoveryUrl?.trim() ? vars.recoveryUrl.trim() : null;
+        const causeSentence = subscriptionPaymentCauseSentence(locale, vars.cause ?? "unknown");
+        const detail = [
+            // Leads the box for the same reason as in the failed notice: it answers the
+            // question the paused subscription raises, before the figures.
+            ...(causeSentence ? [causeSentence] : []),
+            ...(recoveryUrl
+                ? [
+                    vars.amountLabel ? copy.detail(vars.amountLabel)[0] : copy.detail(null)[0],
+                    copy.ctaDetail,
+                ]
+                : copy.detail(vars.amountLabel)),
+        ];
+        const blocks = [
+            heading(copy.heading),
+            paragraph(copy.greeting(vars.firstName)),
+            paragraph(copy.intro),
+            accentBox(detail),
+        ];
+        if (recoveryUrl)
+            blocks.push(button(copy.cta, recoveryUrl));
+        blocks.push(paragraph(copy.outro));
+        blocks.push(paragraph(signoff));
+        return {
+            subject: copy.subject,
+            preheader: recoveryUrl ? copy.preheaderWithCta : copy.preheader,
+            blocks,
+        };
+    }
+    return { subscriptionPaymentExpiredEmailContent };
+}

package/dist/communications/contracts/subscriptionPaymentFailed.d.ts

@@ -0,0 +1,49 @@
+import type { SubscriptionEmailContent } from "./subscriptionEmailContent.js";
+import type { PaymentFailureCustomerCause } from "@openlup/core/payment";
+import type { Locale } from "./email.js";
+import { 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 declare function createSubscriptionPaymentFailedContentFactory(input: {
+    subscriptionEmailContent: Pick<SubscriptionEmailContent, "paymentFailed">;
+    subscriptionPaymentCauseSentence: (locale: Locale, cause: PaymentFailureCustomerCause) => string | null;
+}): {
+    subscriptionPaymentFailedEmailContent: (locale: Locale, vars: SubscriptionPaymentFailedEmailVars, signoff: string) => SubscriptionPaymentFailedEmailContent;
+};

package/dist/communications/contracts/subscriptionPaymentFailed.js

@@ -0,0 +1,56 @@
+import { accentBox, button, heading, paragraph, } from "./blocks.js";
+/** Bind host-selected copy and pure helpers without provider or environment access. */
+export function createSubscriptionPaymentFailedContentFactory(input) {
+    const { subscriptionEmailContent, subscriptionPaymentCauseSentence } = input;
+    function subscriptionPaymentFailedEmailContent(locale, vars, signoff) {
+        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 = [
+            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/dist/communications/contracts/subscriptionPaymentRecovered.d.ts

@@ -0,0 +1,19 @@
+import type { SubscriptionEmailContent } from "./subscriptionEmailContent.js";
+import type { Locale } from "./email.js";
+import { 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 declare function createSubscriptionPaymentRecoveredContentFactory(input: {
+    subscriptionEmailContent: Pick<SubscriptionEmailContent, "paymentRecovered">;
+}): {
+    subscriptionPaymentRecoveredEmailContent: (locale: Locale, vars: SubscriptionPaymentRecoveredEmailVars, signoff: string) => SubscriptionPaymentRecoveredEmailContent;
+};

package/dist/communications/contracts/subscriptionPaymentRecovered.js

@@ -0,0 +1,22 @@
+import { accentBox, heading, paragraph, } from "./blocks.js";
+/** Bind host-selected copy and pure helpers without provider or environment access. */
+export function createSubscriptionPaymentRecoveredContentFactory(input) {
+    const { subscriptionEmailContent } = input;
+    function subscriptionPaymentRecoveredEmailContent(locale, vars, signoff) {
+        const copy = subscriptionEmailContent.paymentRecovered[locale];
+        const blocks = [
+            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/dist/communications/contracts/subscriptionRenewalAtRisk.d.ts

@@ -0,0 +1,36 @@
+import type { SubscriptionEmailContent } from "./subscriptionEmailContent.js";
+import type { PaymentFailureCustomerCause } from "@openlup/core/payment";
+import type { Locale } from "./email.js";
+import { 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 declare function createSubscriptionRenewalAtRiskContentFactory(input: {
+    subscriptionEmailContent: Pick<SubscriptionEmailContent, "renewalAtRisk">;
+    subscriptionPaymentCauseSentence: (locale: Locale, cause: PaymentFailureCustomerCause) => string | null;
+}): {
+    subscriptionRenewalAtRiskEmailContent: (locale: Locale, vars: SubscriptionRenewalAtRiskEmailVars, signoff: string) => SubscriptionRenewalAtRiskEmailContent;
+};

package/dist/communications/contracts/subscriptionRenewalAtRisk.js

@@ -0,0 +1,36 @@
+import { accentBox, button, heading, paragraph, } from "./blocks.js";
+/** Bind host-selected copy and pure helpers without provider or environment access. */
+export function createSubscriptionRenewalAtRiskContentFactory(input) {
+    const { subscriptionEmailContent, subscriptionPaymentCauseSentence } = input;
+    /** Render-time only. See the ⛔ above before touching either side of this map. */
+    const SHARED_CAUSE = {
+        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, cause) {
+        return subscriptionPaymentCauseSentence(locale, SHARED_CAUSE[cause]) ?? "";
+    }
+    function subscriptionRenewalAtRiskEmailContent(locale, vars, signoff) {
+        const copy = subscriptionEmailContent.renewalAtRisk[locale];
+        const blocks = [
+            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/dist/communications/contracts/subscriptionRenewalUpcoming.d.ts

@@ -0,0 +1,49 @@
+import type { SubscriptionEmailContent } from "./subscriptionEmailContent.js";
+import type { Locale } from "./email.js";
+import { 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 declare function createSubscriptionRenewalUpcomingContentFactory(input: {
+    subscriptionEmailContent: Pick<SubscriptionEmailContent, "renewalUpcoming">;
+}): {
+    subscriptionRenewalUpcomingEmailContent: (locale: Locale, vars: SubscriptionRenewalUpcomingEmailVars, signoff: string) => SubscriptionRenewalUpcomingEmailContent;
+};

package/dist/communications/contracts/subscriptionRenewalUpcoming.js

@@ -0,0 +1,43 @@
+import { accentBox, button, heading, paragraph, } from "./blocks.js";
+/** Bind host-selected copy and pure helpers without provider or environment access. */
+export function createSubscriptionRenewalUpcomingContentFactory(input) {
+    const { subscriptionEmailContent } = input;
+    function subscriptionRenewalUpcomingEmailContent(locale, vars, signoff) {
+        const copy = subscriptionEmailContent.renewalUpcoming[locale];
+        const details = [
+            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 = [
+            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/dist/communications/contracts/subscriptionResumed.d.ts

@@ -0,0 +1,23 @@
+import type { SubscriptionEmailContent } from "./subscriptionEmailContent.js";
+import type { Locale } from "./email.js";
+import { 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 declare function createSubscriptionResumedContentFactory(input: {
+    subscriptionEmailContent: Pick<SubscriptionEmailContent, "resumed">;
+}): {
+    subscriptionResumedEmailContent: (locale: Locale, vars: SubscriptionResumedEmailVars, signoff: string) => SubscriptionResumedEmailContent;
+};

package/dist/communications/contracts/subscriptionResumed.js

@@ -0,0 +1,25 @@
+import { accentBox, button, heading, paragraph, } from "./blocks.js";
+/** Bind host-selected copy and pure helpers without provider or environment access. */
+export function createSubscriptionResumedContentFactory(input) {
+    const { subscriptionEmailContent } = input;
+    function subscriptionResumedEmailContent(locale, vars, signoff) {
+        const copy = subscriptionEmailContent.resumed[locale];
+        const blocks = [
+            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/dist/communications/contracts/subscriptionWelcome.d.ts

@@ -0,0 +1,44 @@
+import type { SubscriptionEmailContent } from "./subscriptionEmailContent.js";
+import type { Locale } from "./email.js";
+import { 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 declare function createSubscriptionWelcomeContentFactory(input: {
+    subscriptionEmailContent: Pick<SubscriptionEmailContent, "welcome">;
+}): {
+    subscriptionWelcomeEmailContent: (locale: Locale, vars: SubscriptionWelcomeEmailVars, signoff: string) => SubscriptionWelcomeEmailContent;
+};

package/dist/communications/contracts/subscriptionWelcome.js

@@ -0,0 +1,45 @@
+import { accentBox, button, heading, paragraph, } from "./blocks.js";
+/** Bind host-selected copy and pure helpers without provider or environment access. */
+export function createSubscriptionWelcomeContentFactory(input) {
+    const { subscriptionEmailContent } = input;
+    function subscriptionWelcomeEmailContent(locale, vars, signoff) {
+        const copy = subscriptionEmailContent.welcome[locale];
+        const details = [];
+        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 = [
+            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/dist/communications/contracts/subscriptionWinback.d.ts

@@ -0,0 +1,21 @@
+import type { SubscriptionEmailContent } from "./subscriptionEmailContent.js";
+import type { Locale } from "./email.js";
+import { 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 declare function createSubscriptionWinbackContentFactory(input: {
+    subscriptionEmailContent: Pick<SubscriptionEmailContent, "winback">;
+}): {
+    subscriptionWinbackEmailContent: (locale: Locale, vars: SubscriptionWinbackEmailVars, signoff: string) => SubscriptionWinbackEmailContent;
+};

package/dist/communications/contracts/subscriptionWinback.js

@@ -0,0 +1,28 @@
+import { accentBox, button, heading, paragraph, } from "./blocks.js";
+/** Bind host-selected copy and pure helpers without provider or environment access. */
+export function createSubscriptionWinbackContentFactory(input) {
+    const { subscriptionEmailContent } = input;
+    function subscriptionWinbackEmailContent(locale, vars, signoff) {
+        const copy = subscriptionEmailContent.winback[locale];
+        const blocks = [
+            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/dist/communications/contracts/transactionalDelivery.d.ts

@@ -0,0 +1,42 @@
+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/dist/communications/contracts/transactionalDelivery.js

@@ -0,0 +1 @@
+export {};