@openlup/platform 0.15.0 → 0.17.0

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

@@ -0,0 +1,26 @@
+import type { Locale } from "./email.js";
+import { 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;
+}
+/** Pure defaults; hosts may replace the complete bilingual copy. */
+export declare function createInvoiceDocumentContentFactory(copy?: Record<Locale, InvoiceDocumentCopy>): {
+    invoiceDocumentEmailContent: (locale: Locale, vars: InvoiceDocumentVars) => {
+        subject: string;
+        preheader: string;
+        blocks: EmailBlock[];
+    };
+};

package/dist/communications/contracts/invoiceDocumentContent.js

@@ -0,0 +1,36 @@
+import { button, dataTable, heading, paragraph } from "./blocks.js";
+const defaults = {
+    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 = defaults) {
+    function invoiceDocumentEmailContent(locale, vars) {
+        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/dist/communications/contracts/marketingAutomation.d.ts

@@ -0,0 +1,52 @@
+/** 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/dist/communications/contracts/marketingAutomation.js

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

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

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

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

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

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

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

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

@@ -0,0 +1,11 @@
+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>>;
+/** Display only; the caller independently verifies and durably records opt-out. */
+export declare function createOptOutContentFactory(copy?: OptOutCopy): {
+    optOutContent: (locale: Locale, outcome: OptOutOutcome, supportEmail: string) => OptOutContent;
+};

package/dist/communications/contracts/optOutContent.js

@@ -0,0 +1,17 @@
+const defaults = {
+    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 = defaults) {
+    function optOutContent(locale, outcome, supportEmail) {
+        const c = copy[outcome][locale];
+        return { title: c.title, message: c.message.split("{supportEmail}").join(supportEmail) };
+    }
+    return { optOutContent };
+}

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

@@ -0,0 +1,25 @@
+import type { CommerceEmailContent } from "./commerceEmailContent.js";
+import type { Locale } from "./email.js";
+import { 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 declare function createOrderCanceledContentFactory(input: {
+    commerceEmailContent: Pick<CommerceEmailContent, "orderCanceled" | "orderRefPrefix">;
+    formatCustomerOrderReference: (orderId: string, prefix: string) => string;
+}): {
+    orderCanceledEmailContent: (locale: Locale, vars: OrderCanceledEmailVars, signoff: string) => OrderCanceledEmailContent;
+};

package/dist/communications/contracts/orderCanceled.js

@@ -0,0 +1,27 @@
+import { accentBox, button, heading, paragraph, } from "./blocks.js";
+/** Bind host-selected copy and pure helpers without provider or environment access. */
+export function createOrderCanceledContentFactory(input) {
+    const { commerceEmailContent, formatCustomerOrderReference } = input;
+    function orderCanceledEmailContent(locale, vars, signoff) {
+        const copy = commerceEmailContent.orderCanceled[locale];
+        const orderRef = formatCustomerOrderReference(vars.orderId, commerceEmailContent.orderRefPrefix);
+        const blocks = [
+            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/dist/communications/contracts/orderDraft.d.ts

@@ -0,0 +1,46 @@
+import type { CommerceEmailContent } from "./commerceEmailContent.js";
+import type { Locale } from "./email.js";
+import { 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 declare function createOrderDraftContentFactory(input: {
+    commerceEmailContent: Pick<CommerceEmailContent, "orderDraft" | "orderRefPrefix">;
+    formatCustomerOrderReference: (orderId: string, prefix: string) => string;
+}): {
+    orderDraftEmailContent: (locale: Locale, vars: OrderDraftEmailVars, signoff: string) => OrderDraftEmailContent;
+};

package/dist/communications/contracts/orderDraft.js

@@ -0,0 +1,46 @@
+import { button, dataTable, heading, list, paragraph, } from "./blocks.js";
+/** Bind host-selected copy and pure helpers without provider or environment access. */
+export function createOrderDraftContentFactory(input) {
+    const { commerceEmailContent, formatCustomerOrderReference } = input;
+    function itemLine(item) {
+        const base = `${item.quantity}× ${item.name}`;
+        return item.lineTotalLabel ? `${base} – ${item.lineTotalLabel}` : base;
+    }
+    function orderDraftEmailContent(locale, vars, signoff) {
+        const copy = commerceEmailContent.orderDraft[locale];
+        const orderRef = formatCustomerOrderReference(vars.orderId, commerceEmailContent.orderRefPrefix);
+        const blocks = [
+            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 = [];
+            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 };
+}

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

@@ -0,0 +1,53 @@
+import type { CommerceEmailContent } from "./commerceEmailContent.js";
+import type { Locale } from "./email.js";
+import { type EmailBlock } from "./blocks.js";
+export interface OrderPaidLineItem {
+    name: string;
+    quantity: number;
+    lineTotalLabel: string;
+}
+export interface OrderPaidTotals {
+    /** null → omit the subtotal row (value unknown); never alias the grand total. */
+    subtotalLabel: string | null;
+    discountLabel: string | null;
+    totalLabel: string;
+    firstSubscription?: {
+        catalogLabel: string;
+        productPayableLabel: string;
+        shippingLabel: string | null;
+        shippingFree: boolean;
+    };
+}
+export interface OrderPaidEmailVars {
+    firstName: string | null;
+    orderId: string;
+    /** "one_time" | "subscription_cycle" (free-form); drives the intro framing. */
+    mode: string;
+    items: OrderPaidLineItem[];
+    totals: OrderPaidTotals | null;
+    /** Absolute CTA URL to the customer's order/account; null/absent → no button. */
+    ctaUrl?: string | null;
+    /**
+     * Absolute URL of the shop terms (which include the §10 withdrawal-right
+     * section and the model withdrawal form). Renders the consumer-law footer
+     * link; the fine-print paragraph itself is always included (durable-medium
+     * confirmation duty, art. 21 ustawy o prawach konsumenta).
+     */
+    termsUrl?: string | null;
+    /** Optional context name for the selected post-receipt note. */
+    contextName?: string | null;
+    /** Adopter-formatted, already-localized note about the parcel; null or absent renders nothing. */
+    parcelNote?: string | null;
+}
+export interface OrderPaidEmailContent {
+    subject: string;
+    preheader: string;
+    blocks: EmailBlock[];
+}
+/** Bind host-selected copy and pure helpers without provider or environment access. */
+export declare function createOrderPaidContentFactory(input: {
+    commerceEmailContent: Pick<CommerceEmailContent, "orderPaid" | "orderRefPrefix">;
+    formatCustomerOrderReference: (orderId: string, prefix: string) => string;
+}): {
+    orderPaidEmailContent: (locale: Locale, vars: OrderPaidEmailVars, signoff: string) => OrderPaidEmailContent;
+};

package/dist/communications/contracts/orderPaid.js

@@ -0,0 +1,71 @@
+import { button, dataTable, heading, linkParagraph, list, paragraph, } from "./blocks.js";
+/** Bind host-selected copy and pure helpers without provider or environment access. */
+export function createOrderPaidContentFactory(input) {
+    const { commerceEmailContent, formatCustomerOrderReference } = input;
+    function itemLine(item) {
+        const base = `${item.quantity}× ${item.name}`;
+        return item.lineTotalLabel ? `${base} – ${item.lineTotalLabel}` : base;
+    }
+    function orderPaidEmailContent(locale, vars, signoff) {
+        const copy = commerceEmailContent.orderPaid[locale];
+        const orderRef = formatCustomerOrderReference(vars.orderId, commerceEmailContent.orderRefPrefix);
+        const intro = vars.mode === "subscription_cycle"
+            ? copy.introSubscription(orderRef)
+            : copy.introOneTime(orderRef);
+        const blocks = [
+            heading(copy.heading),
+            paragraph(copy.greeting(vars.firstName)),
+            paragraph(intro),
+        ];
+        blocks.push(vars.items.length > 0 ? list(vars.items.map(itemLine)) : paragraph(copy.noItems));
+        if (vars.parcelNote)
+            blocks.push(paragraph(vars.parcelNote));
+        if (vars.totals) {
+            const rows = [];
+            if (vars.totals.firstSubscription) {
+                rows.push({ label: copy.catalogProductsLabel, value: vars.totals.firstSubscription.catalogLabel });
+                if (vars.totals.discountLabel) {
+                    rows.push({ label: copy.firstSubscriptionDiscountRowLabel, value: vars.totals.discountLabel });
+                }
+                rows.push({ label: copy.productPayableLabel, value: vars.totals.firstSubscription.productPayableLabel });
+                if (vars.totals.firstSubscription.shippingFree) {
+                    rows.push({ label: copy.shippingLabel, value: copy.shippingFree });
+                }
+                else if (vars.totals.firstSubscription.shippingLabel) {
+                    rows.push({ label: copy.shippingLabel, value: vars.totals.firstSubscription.shippingLabel });
+                }
+            }
+            else if (vars.totals.subtotalLabel) {
+                rows.push({ label: copy.subtotalLabel, value: vars.totals.subtotalLabel });
+            }
+            if (!vars.totals.firstSubscription && vars.totals.discountLabel) {
+                rows.push({ label: copy.discountRowLabel, value: vars.totals.discountLabel });
+            }
+            rows.push({
+                label: vars.totals.firstSubscription ? copy.finalPaidLabel : copy.totalLabel,
+                value: vars.totals.totalLabel,
+            });
+            blocks.push(dataTable(rows));
+        }
+        // Selected post-receipt copy is shown for both one-time and subscription-cycle
+        // receipts, without changing the payment or delivery facts around it.
+        blocks.push(paragraph(copy.receiptNote(vars.contextName ?? null)));
+        if (vars.ctaUrl) {
+            blocks.push(button(copy.cta, vars.ctaUrl));
+        }
+        blocks.push(paragraph(copy.outro));
+        // Durable-medium confirmation (art. 21 uPK): the receipt must carry the
+        // withdrawal-right information alongside a link to the full terms + form.
+        blocks.push(paragraph(copy.withdrawalNotice, { muted: true }));
+        if (vars.termsUrl) {
+            blocks.push(linkParagraph(copy.withdrawalLinkLabel, vars.termsUrl, { muted: true }));
+        }
+        blocks.push(paragraph(signoff));
+        return {
+            subject: copy.subject(orderRef),
+            preheader: copy.preheader,
+            blocks,
+        };
+    }
+    return { orderPaidEmailContent };
+}

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

@@ -0,0 +1,24 @@
+import type { CommerceEmailContent } from "./commerceEmailContent.js";
+import type { Locale } from "./email.js";
+import { type EmailBlock } from "./blocks.js";
+export interface OrderRefundedEmailVars {
+    firstName: string | null;
+    brandName: string;
+    orderId: string;
+    /** Formatted gross refund 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;
+}
+export interface OrderRefundedEmailContent {
+    subject: string;
+    preheader: string;
+    blocks: EmailBlock[];
+}
+/** Bind host-selected copy and pure helpers without provider or environment access. */
+export declare function createOrderRefundedContentFactory(input: {
+    commerceEmailContent: Pick<CommerceEmailContent, "orderRefunded" | "orderRefPrefix">;
+    formatCustomerOrderReference: (orderId: string, prefix: string) => string;
+}): {
+    orderRefundedEmailContent: (locale: Locale, vars: OrderRefundedEmailVars, signoff: string) => OrderRefundedEmailContent;
+};

package/dist/communications/contracts/orderRefunded.js

@@ -0,0 +1,27 @@
+import { accentBox, button, heading, paragraph, } from "./blocks.js";
+/** Bind host-selected copy and pure helpers without provider or environment access. */
+export function createOrderRefundedContentFactory(input) {
+    const { commerceEmailContent, formatCustomerOrderReference } = input;
+    function orderRefundedEmailContent(locale, vars, signoff) {
+        const copy = commerceEmailContent.orderRefunded[locale];
+        const orderRef = formatCustomerOrderReference(vars.orderId, commerceEmailContent.orderRefPrefix);
+        const blocks = [
+            heading(copy.heading),
+            paragraph(copy.greeting(vars.firstName)),
+            paragraph(copy.intro(orderRef)),
+            accentBox(copy.details(vars.amountLabel), { label: copy.detailsLabel }),
+            paragraph(copy.returnNote(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(orderRef),
+            preheader: copy.preheader,
+            blocks,
+        };
+    }
+    return { orderRefundedEmailContent };
+}

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

@@ -0,0 +1,24 @@
+import type { CommerceEmailContent } from "./commerceEmailContent.js";
+import type { Locale } from "./email.js";
+import { type EmailBlock } from "./blocks.js";
+export interface PaymentFailedEmailVars {
+    firstName: string | null;
+    orderId: string;
+    /** Formatted gross total, e.g. "129,99 zł", or null when unknown. */
+    amountLabel: string | null;
+    mode: "subscription_cycle" | "one_time";
+    /** Absolute tokenized /konto/... recovery URL for the same order context. */
+    recoveryUrl: string;
+}
+export interface PaymentFailedEmailContent {
+    subject: string;
+    preheader: string;
+    blocks: EmailBlock[];
+}
+/** Bind host-selected copy and pure helpers without provider or environment access. */
+export declare function createPaymentFailedContentFactory(input: {
+    commerceEmailContent: Pick<CommerceEmailContent, "paymentFailed" | "orderRefPrefix">;
+    formatCustomerOrderReference: (orderId: string, prefix: string) => string;
+}): {
+    paymentFailedEmailContent: (locale: Locale, vars: PaymentFailedEmailVars, signoff: string) => PaymentFailedEmailContent;
+};

package/dist/communications/contracts/paymentFailed.js

@@ -0,0 +1,24 @@
+import { accentBox, button, heading, paragraph, } from "./blocks.js";
+/** Bind host-selected copy and pure helpers without provider or environment access. */
+export function createPaymentFailedContentFactory(input) {
+    const { commerceEmailContent, formatCustomerOrderReference } = input;
+    function paymentFailedEmailContent(locale, vars, signoff) {
+        const copy = commerceEmailContent.paymentFailed[locale];
+        const orderRef = formatCustomerOrderReference(vars.orderId, commerceEmailContent.orderRefPrefix);
+        const blocks = [
+            heading(copy.heading),
+            paragraph(copy.greeting(vars.firstName)),
+            paragraph(copy.intro(orderRef)),
+            accentBox(copy.details(vars.amountLabel, vars.mode), { label: copy.detailsLabel }),
+            button(copy.cta, vars.recoveryUrl),
+        ];
+        blocks.push(paragraph(copy.outro));
+        blocks.push(paragraph(signoff));
+        return {
+            subject: copy.subject(orderRef),
+            preheader: copy.preheader,
+            blocks,
+        };
+    }
+    return { paymentFailedEmailContent };
+}