@openlup/platform 0.15.0 → 0.17.0

package/dist/communications/communicationSyncWorker.js

@@ -0,0 +1,218 @@
+import { requiredNewsletterCapabilityForEvent, supportsNewsletterSyncEvent, } from "./newsletterIntegrationContracts.js";
+export const DEFAULT_COMMUNICATION_SYNC_CONFIG = {
+    batchSize: 25,
+    maxAttempts: 8,
+    visibilitySeconds: 300,
+    backoffSeconds: 300,
+};
+export async function runCommunicationSyncDispatch(input) {
+    const config = { ...DEFAULT_COMMUNICATION_SYNC_CONFIG, ...input.config };
+    const registry = input.registry;
+    const events = await input.store.claimBatch({
+        providerKind: input.provider.providerKind,
+        batchSize: clamp(config.batchSize, 1, 100),
+        visibilitySeconds: clamp(config.visibilitySeconds, 60, 3600),
+        maxAttempts: clamp(config.maxAttempts, 1, 20),
+    });
+    if (registry && events.some(event => !registry.has(event.purpose)))
+        throw new Error("unregistered_communication_purpose");
+    const result = {
+        ok: true,
+        checked: events.length,
+        updated: 0,
+        failures: 0,
+        skipped: events.length === 0,
+        reason: events.length === 0 ? "empty_queue" : undefined,
+        providerKind: input.provider.providerKind,
+        sent: 0,
+        retried: 0,
+        skippedEvents: 0,
+    };
+    for (const event of events) {
+        try {
+            if (event.originProviderKind === input.provider.providerKind) {
+                const applied = await input.store.markSent({
+                    eventId: event.id,
+                    claimToken: event.claimToken,
+                    providerKind: input.provider.providerKind,
+                    remoteProfileId: event.remoteProfileId ?? null,
+                    responseSummary: {
+                        status: "skipped",
+                        reason: "origin_provider_echo_loop",
+                        originProviderKind: event.originProviderKind,
+                        originProviderEventId: event.originProviderEventId ?? null,
+                    },
+                });
+                result.updated += applied ? 1 : 0;
+                result.skippedEvents += 1;
+                continue;
+            }
+            if (!supportsNewsletterSyncEvent(input.provider.capabilities, event.eventType)) {
+                const requiredCapability = requiredNewsletterCapabilityForEvent(event.eventType);
+                const applied = await input.store.markSent({
+                    eventId: event.id,
+                    claimToken: event.claimToken,
+                    providerKind: input.provider.providerKind,
+                    remoteProfileId: event.remoteProfileId ?? null,
+                    responseSummary: {
+                        status: "skipped",
+                        reason: "unsupported_provider_capability",
+                        eventType: event.eventType,
+                        requiredCapability,
+                    },
+                });
+                result.updated += applied ? 1 : 0;
+                result.skippedEvents += 1;
+                continue;
+            }
+            const outcome = await input.provider.sync(event);
+            if (outcome.status === "sent" || outcome.status === "skipped") {
+                const applied = await input.store.markSent({
+                    eventId: event.id,
+                    claimToken: event.claimToken,
+                    providerKind: input.provider.providerKind,
+                    remoteProfileId: outcome.status === "sent" ? outcome.remoteProfileId : null,
+                    responseSummary: {
+                        status: outcome.status,
+                        ...(outcome.responseSummary ?? {}),
+                        ...(outcome.status === "skipped" ? { reason: outcome.reason } : {}),
+                    },
+                });
+                result.updated += applied ? 1 : 0;
+                if (outcome.status === "sent")
+                    result.sent += 1;
+                if (outcome.status === "skipped")
+                    result.skippedEvents += 1;
+                continue;
+            }
+            await input.store.markFailed({
+                eventId: event.id,
+                claimToken: event.claimToken,
+                providerKind: input.provider.providerKind,
+                error: outcome.reason,
+                retry: true,
+                backoffSeconds: outcome.retryAfterSeconds ?? config.backoffSeconds,
+            });
+            result.retried += 1;
+            result.failures += 1;
+        }
+        catch (error) {
+            await input.store.markFailed({
+                eventId: event.id,
+                claimToken: event.claimToken,
+                providerKind: input.provider.providerKind,
+                error: safeMessage(error),
+                retry: event.attemptCount + 1 < config.maxAttempts,
+                backoffSeconds: config.backoffSeconds,
+            });
+            result.retried += 1;
+            result.failures += 1;
+        }
+    }
+    result.ok = result.failures === 0;
+    if (!result.ok)
+        result.reason = "communication_sync_failures";
+    return result;
+}
+export async function runCommunicationSyncDispatchForProviders(input) {
+    if (input.providers.length === 0) {
+        return {
+            ok: true,
+            checked: 0,
+            updated: 0,
+            failures: 0,
+            skipped: true,
+            reason: "no_newsletter_providers_enabled",
+            providerKind: "provider_registry",
+            sent: 0,
+            retried: 0,
+            skippedEvents: 0,
+        };
+    }
+    const results = [];
+    for (const provider of input.providers) {
+        results.push(await runCommunicationSyncDispatch({
+            store: input.store,
+            provider,
+            config: input.config,
+            registry: input.registry,
+        }));
+    }
+    return aggregateProviderResults(results);
+}
+export async function runCommunicationSyncReconcile(input = {}) {
+    const providers = input.providers ?? [];
+    if (providers.length === 0) {
+        return {
+            ok: true,
+            checked: 0,
+            updated: 0,
+            failures: 0,
+            skipped: true,
+            reason: "no_newsletter_providers_enabled",
+        };
+    }
+    let checked = 0;
+    let updated = 0;
+    let failures = 0;
+    let skipped = 0;
+    for (const provider of providers) {
+        if (!provider.reconcile) {
+            skipped += 1;
+            continue;
+        }
+        const outcome = await provider.reconcile();
+        if (outcome.status === "skipped") {
+            skipped += 1;
+            continue;
+        }
+        checked += outcome.checked;
+        updated += outcome.updated;
+        failures += outcome.failures;
+    }
+    return {
+        ok: true,
+        checked,
+        updated,
+        failures,
+        skipped: skipped === providers.length,
+        reason: skipped === providers.length ? "provider_neutral_reconcile_noop" : undefined,
+    };
+}
+function aggregateProviderResults(results) {
+    const aggregate = results.reduce((acc, item) => ({
+        ok: acc.ok && item.ok,
+        checked: acc.checked + item.checked,
+        updated: acc.updated + item.updated,
+        failures: acc.failures + item.failures,
+        skipped: acc.skipped && item.skipped,
+        providerKind: "provider_registry",
+        sent: acc.sent + item.sent,
+        retried: acc.retried + item.retried,
+        skippedEvents: acc.skippedEvents + item.skippedEvents,
+        reason: undefined,
+    }), {
+        ok: true,
+        checked: 0,
+        updated: 0,
+        failures: 0,
+        skipped: true,
+        providerKind: "provider_registry",
+        sent: 0,
+        retried: 0,
+        skippedEvents: 0,
+    });
+    if (!aggregate.ok)
+        aggregate.reason = "communication_sync_failures";
+    if (aggregate.skipped)
+        aggregate.reason = "empty_queue";
+    return aggregate;
+}
+function clamp(value, min, max) {
+    if (!Number.isFinite(value))
+        return min;
+    return Math.min(Math.max(Math.trunc(value), min), max);
+}
+function safeMessage(error) {
+    return (error instanceof Error ? error.message : String(error)).slice(0, 300);
+}

package/dist/communications/consentPolicy.d.ts

@@ -0,0 +1,19 @@
+import type { CommunicationPurposeRegistry } from "./contracts/consent.js";
+import type { CommunicationPermissionState, CommunicationPurpose } from "./contracts/types.js";
+export type CommunicationRecipientKind = "external_contact" | "tester" | "customer" | "lead" | "admin_internal";
+export interface CommunicationPermissionSnapshot {
+    state: CommunicationPermissionState | null;
+    source?: string | null;
+    legacySequencePaused?: boolean | null;
+}
+export interface CommunicationPolicyInput<Purpose extends string = CommunicationPurpose> {
+    purpose: Purpose;
+    recipientKind: CommunicationRecipientKind;
+    permission: CommunicationPermissionSnapshot | null;
+}
+export interface CommunicationPolicyResult {
+    decision: "allowed" | "blocked";
+    reason: string;
+}
+export declare function evaluateCommunicationPolicy<Purpose extends string = CommunicationPurpose>(input: CommunicationPolicyInput<Purpose>, registry?: CommunicationPurposeRegistry<Purpose>): CommunicationPolicyResult;
+export declare function consentStateFromBoolean(value: boolean | null | undefined): CommunicationPermissionState;

package/dist/communications/consentPolicy.js

@@ -0,0 +1,43 @@
+const MARKETING_PURPOSES = new Set([
+    "marketing_launch_offer",
+    "marketing_newsletter",
+]);
+export function evaluateCommunicationPolicy(input, registry) {
+    if (registry && !registry.has(input.purpose))
+        return { decision: "blocked", reason: "unsupported_purpose" };
+    const state = input.permission?.state ?? "unknown";
+    if (input.purpose === "admin_notification") {
+        return { decision: "allowed", reason: "admin_notification" };
+    }
+    if (input.purpose === "transactional" || input.purpose === "subscription_dunning") {
+        return { decision: "allowed", reason: "purpose_allowed_without_marketing_consent" };
+    }
+    if (input.purpose === "tester_program") {
+        if (input.permission?.legacySequencePaused) {
+            return { decision: "blocked", reason: "sequence_paused" };
+        }
+        if (state === "denied" || state === "suppressed") {
+            return { decision: "blocked", reason: `permission_${state}` };
+        }
+        if (state !== "granted") {
+            return { decision: "blocked", reason: "missing_tester_program_permission" };
+        }
+        return { decision: "allowed", reason: "tester_program_granted" };
+    }
+    if (registry ? registry.classification(input.purpose) === "marketing" : MARKETING_PURPOSES.has(input.purpose)) {
+        if (state === "suppressed") {
+            return { decision: "blocked", reason: "permission_suppressed" };
+        }
+        if (state !== "granted") {
+            return { decision: "blocked", reason: "missing_marketing_permission" };
+        }
+        return { decision: "allowed", reason: "marketing_permission_granted" };
+    }
+    if (registry?.classification(input.purpose) === "non-marketing") {
+        return { decision: "allowed", reason: "purpose_allowed_without_marketing_consent" };
+    }
+    return { decision: "blocked", reason: "unsupported_purpose" };
+}
+export function consentStateFromBoolean(value) {
+    return value === true ? "granted" : "denied";
+}

package/dist/communications/consentPurposeRegistry.d.ts

@@ -0,0 +1,4 @@
+import type { CommunicationPurpose } from "./contracts/types.js";
+import type { CommunicationPurposeDefinition, CommunicationPurposeRegistry } from "./contracts/consent.js";
+export declare function createCommunicationPurposeRegistry<const Purpose extends string = never>(additions?: readonly CommunicationPurposeDefinition<Purpose>[]): CommunicationPurposeRegistry<CommunicationPurpose | Purpose>;
+export declare const defaultCommunicationPurposeRegistry: CommunicationPurposeRegistry<"transactional" | "marketing_launch_offer" | "marketing_newsletter" | "tester_program" | "subscription_dunning" | "admin_notification">;

package/dist/communications/consentPurposeRegistry.js

@@ -0,0 +1,24 @@
+const builtins = [
+    { id: "transactional", classification: "non-marketing" },
+    { id: "tester_program", classification: "non-marketing" },
+    { id: "marketing_launch_offer", classification: "marketing" },
+    { id: "marketing_newsletter", classification: "marketing" },
+    { id: "subscription_dunning", classification: "non-marketing" },
+    { id: "admin_notification", classification: "non-marketing" },
+];
+export function createCommunicationPurposeRegistry(additions = []) {
+    const definitions = new Map();
+    for (const definition of [...builtins, ...additions]) {
+        if (typeof definition.id !== "string" || !definition.id.trim() || definition.id !== definition.id.trim()
+            || !["marketing", "non-marketing"].includes(definition.classification) || definitions.has(definition.id)) {
+            throw new Error("communication_purpose_definition_invalid");
+        }
+        definitions.set(definition.id, Object.freeze({ id: definition.id, classification: definition.classification }));
+    }
+    return Object.freeze({
+        purposes: Object.freeze([...definitions.values()]),
+        has: (value) => typeof value === "string" && definitions.has(value),
+        classification: (purpose) => definitions.get(purpose)?.classification,
+    });
+}
+export const defaultCommunicationPurposeRegistry = createCommunicationPurposeRegistry();

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

@@ -0,0 +1,27 @@
+import type { CommerceEmailContent } from "./commerceEmailContent.js";
+import type { Locale } from "./email.js";
+import { type EmailBlock } from "./blocks.js";
+/** 1 = light same-session nudge, 24 = gentle nudge, 72 = final last-nudge. */
+export type AbandonedCartReminderHours = 1 | 24 | 72;
+export interface AbandonedCartEmailVars {
+    firstName: string | null;
+    /** Consumer-facing brand label injected by the app/composition root. */
+    brandName: string;
+    reminderHours: AbandonedCartReminderHours;
+    /** Absolute CTA URL back to the configurator. */
+    ctaUrl: string;
+    /** Absolute signed unsubscribe URL (purpose 'marketing_newsletter'). */
+    unsubscribeUrl: string;
+}
+export interface AbandonedCartEmailContent {
+    subject: string;
+    preheader: string;
+    blocks: EmailBlock[];
+}
+/** Bind host-selected copy and pure helpers without provider or environment access. */
+export declare function createAbandonedCartContentFactory(input: {
+    commerceEmailContent: Pick<CommerceEmailContent, "abandonedCart">;
+    marketingUnsubscribeFooter: (locale: Locale, unsubscribeUrl: string) => EmailBlock[];
+}): {
+    abandonedCartEmailContent: (locale: Locale, vars: AbandonedCartEmailVars, signoff: string) => AbandonedCartEmailContent;
+};

package/dist/communications/contracts/abandonedCart.js

@@ -0,0 +1,25 @@
+import { button, heading, paragraph, } from "./blocks.js";
+/** Bind host-selected copy and pure helpers without provider or environment access. */
+export function createAbandonedCartContentFactory(input) {
+    const { commerceEmailContent, marketingUnsubscribeFooter } = input;
+    function abandonedCartEmailContent(locale, vars, signoff) {
+        const copy = commerceEmailContent.abandonedCart[locale];
+        const tone = vars.reminderHours === 72 ? copy.last : vars.reminderHours === 1 ? copy.first : copy.gentle;
+        const withBrand = (text) => text.split("{{brand}}").join(vars.brandName);
+        const blocks = [
+            heading(withBrand(tone.heading)),
+            paragraph(copy.greeting(vars.firstName)),
+            paragraph(withBrand(tone.intro)),
+            paragraph(withBrand(tone.body)),
+            button(tone.cta, vars.ctaUrl),
+            paragraph(signoff),
+            ...marketingUnsubscribeFooter(locale, vars.unsubscribeUrl),
+        ];
+        return {
+            subject: withBrand(tone.subject),
+            preheader: withBrand(tone.preheader),
+            blocks,
+        };
+    }
+    return { abandonedCartEmailContent };
+}

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

@@ -0,0 +1,62 @@
+import type { EmailBlock, Locale } from "./email.js";
+export type AuthEmailLocale = Locale;
+export interface AuthEmailContentPort {
+    buildAuthEmailContent(input: {
+        actionType: string;
+        userMetadata: Record<string, unknown> | null | undefined;
+        redirectTo: string;
+        actionLink: string;
+        otp: string | null;
+    }): {
+        locale: AuthEmailLocale;
+        subject: string;
+        preheader: string;
+        blocks: EmailBlock[];
+    };
+}
+export type AuthEmailPersistenceSkipReason = "admin_disabled" | "egress_suppressed";
+export interface AuthEmailMessage {
+    sender: string;
+    recipient: string;
+    subject: string;
+    html: string;
+    text?: string;
+}
+export interface AuthEmailTransportResult {
+    outcome: {
+        ok: boolean;
+        messageId: string | null;
+        providerError: string | null;
+        aborted?: boolean;
+        adminDisabled?: boolean;
+        suppressed?: "drop" | null;
+        egressMode?: "production" | "sandbox_direct" | "sandbox_sink" | "drop";
+    };
+    providerResponse: Record<string, unknown>;
+}
+/** Provider-neutral outbound seam supplied by the API composition root. */
+export interface AuthEmailTransportPort {
+    readonly providerKind: string;
+    send(message: AuthEmailMessage): Promise<AuthEmailTransportResult>;
+}
+/** Provider-neutral send observation owned by the Auth email candidate. */
+export interface AuthEmailPersistencePort {
+    isTemplateEnabled(templateSlug: string, signal: AbortSignal): Promise<boolean>;
+    recordSend(input: {
+        templateSlug: string;
+        recipientEmail: string;
+        authUserId: string | null;
+        aggregateId: string;
+        dedupeKey: string;
+        providerKind: string;
+        outcome: {
+            ok: boolean;
+            messageId: string | null;
+            providerError: string | null;
+            aborted?: boolean;
+            skipReason?: AuthEmailPersistenceSkipReason | null;
+        };
+        providerResponse: Record<string, unknown>;
+        metadata: Record<string, unknown>;
+    }): Promise<void>;
+}

package/dist/communications/contracts/authEmail.js

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

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

@@ -0,0 +1,28 @@
+import type { CommerceEmailContent } from "./commerceEmailContent.js";
+import type { Locale } from "./email.js";
+import { type EmailBlock } from "./blocks.js";
+export interface BackInStockEmailVars {
+    /** Consumer-facing brand label injected by the app/composition root. */
+    brandName: string;
+    /** The sku that came back. Used for context/keying – never shown in copy. */
+    sku: string;
+    /**
+     * Resolved, localized product name. When unknown (catalog miss / failure) the
+     * copy falls back to a generic localized label – a raw sku must never surface
+     * in a customer-facing subject or body.
+     */
+    productName?: string | null;
+    /** Absolute CTA URL (product page or configurator). null/absent → no button. */
+    ctaUrl?: string | null;
+}
+export interface BackInStockEmailContent {
+    subject: string;
+    preheader: string;
+    blocks: EmailBlock[];
+}
+/** Bind host-selected copy and pure helpers without provider or environment access. */
+export declare function createBackInStockContentFactory(input: {
+    commerceEmailContent: Pick<CommerceEmailContent, "backInStock">;
+}): {
+    backInStockEmailContent: (locale: Locale, vars: BackInStockEmailVars, signoff: string) => BackInStockEmailContent;
+};

package/dist/communications/contracts/backInStock.js

@@ -0,0 +1,28 @@
+import { button, heading, paragraph, } from "./blocks.js";
+/** Bind host-selected copy and pure helpers without provider or environment access. */
+export function createBackInStockContentFactory(input) {
+    const { commerceEmailContent } = input;
+    function backInStockEmailContent(locale, vars, signoff) {
+        const copy = commerceEmailContent.backInStock[locale];
+        const productLabel = vars.productName && vars.productName.trim() !== ""
+            ? vars.productName.trim()
+            : copy.genericLabel;
+        const withBrand = (text) => text.split("{{brand}}").join(vars.brandName);
+        const blocks = [
+            heading(copy.heading(productLabel)),
+            paragraph(copy.greeting),
+            paragraph(copy.intro(productLabel)),
+            paragraph(withBrand(copy.hook)),
+        ];
+        if (vars.ctaUrl) {
+            blocks.push(button(copy.cta, vars.ctaUrl));
+        }
+        blocks.push(paragraph(signoff));
+        return {
+            subject: withBrand(copy.subject(productLabel)),
+            preheader: copy.preheader,
+            blocks,
+        };
+    }
+    return { backInStockEmailContent };
+}

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

@@ -0,0 +1,24 @@
+import type { ParagraphBlock, HeadingBlock, ListBlock, AccentBoxBlock, DataRow, DataTableBlock, FeatureCardBlock, ButtonBlock, LinkParagraphBlock, DividerBlock } from "./email.js";
+export type { ParagraphBlock, HeadingBlock, ListBlock, AccentBoxBlock, DataRow, DataTableBlock, FeatureCardImage, FeatureCardBlock, ButtonBlock, LinkParagraphBlock, DividerBlock, EmailBlock } from "./email.js";
+export declare const paragraph: (text: string, opts?: {
+    muted?: boolean;
+    afterCard?: boolean;
+}) => ParagraphBlock;
+export declare const heading: (text: string) => HeadingBlock;
+export declare const list: (items: string[]) => ListBlock;
+export declare const accentBox: (lines: string[], opts?: {
+    label?: string;
+}) => AccentBoxBlock;
+export declare const dataTable: (rows: DataRow[], opts?: {
+    link?: {
+        label: string;
+        href: string;
+    };
+}) => DataTableBlock;
+export declare const featureCard: (card: Omit<FeatureCardBlock, "kind">) => FeatureCardBlock;
+export declare const button: (label: string, href: string) => ButtonBlock;
+export declare const linkParagraph: (text: string, href: string, opts?: {
+    muted?: boolean;
+    afterCard?: boolean;
+}) => LinkParagraphBlock;
+export declare const divider: () => DividerBlock;

package/dist/communications/contracts/blocks.js

@@ -0,0 +1,23 @@
+export const paragraph = (text, opts = {}) => ({
+    kind: "paragraph",
+    text,
+    muted: opts.muted ?? false,
+    ...(opts.afterCard ? { afterCard: true } : {}),
+});
+export const heading = (text) => ({ kind: "heading", text });
+export const list = (items) => ({ kind: "list", items });
+export const accentBox = (lines, opts = {}) => ({ kind: "accentBox", label: opts.label, lines });
+export const dataTable = (rows, opts = {}) => ({ kind: "dataTable", rows, ...(opts.link ? { link: opts.link } : {}) });
+export const featureCard = (card) => ({
+    kind: "featureCard",
+    ...card,
+});
+export const button = (label, href) => ({ kind: "button", label, href });
+export const linkParagraph = (text, href, opts = {}) => ({
+    kind: "linkParagraph",
+    text,
+    href,
+    muted: opts.muted ?? false,
+    ...(opts.afterCard ? { afterCard: true } : {}),
+});
+export const divider = () => ({ kind: "divider" });

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

@@ -0,0 +1,22 @@
+import type { CommerceEmailContent } from "./commerceEmailContent.js";
+import type { Locale } from "./email.js";
+import { type EmailBlock } from "./blocks.js";
+export interface CheckoutExpiredEmailVars {
+    firstName: string | null;
+    orderId: string;
+    amountLabel: string | null;
+    ctaUrl?: string | null;
+    ctaKind?: "recovery" | "compose";
+}
+export interface CheckoutExpiredEmailContent {
+    subject: string;
+    preheader: string;
+    blocks: EmailBlock[];
+}
+/** Bind host-selected copy and pure helpers without provider or environment access. */
+export declare function createCheckoutExpiredContentFactory(input: {
+    commerceEmailContent: Pick<CommerceEmailContent, "checkoutExpired" | "orderRefPrefix">;
+    formatCustomerOrderReference: (orderId: string, prefix: string) => string;
+}): {
+    checkoutExpiredEmailContent: (locale: Locale, vars: CheckoutExpiredEmailVars, signoff: string) => CheckoutExpiredEmailContent;
+};

package/dist/communications/contracts/checkoutExpired.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 createCheckoutExpiredContentFactory(input) {
+    const { commerceEmailContent, formatCustomerOrderReference } = input;
+    function checkoutExpiredEmailContent(locale, vars, signoff) {
+        const copy = commerceEmailContent.checkoutExpired[vars.ctaKind === "recovery" ? "recovery" : "expired"][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 }),
+        ];
+        if (vars.ctaUrl)
+            blocks.push(button(copy.cta, vars.ctaUrl));
+        blocks.push(paragraph(copy.outro));
+        blocks.push(paragraph(signoff));
+        return {
+            subject: copy.subject(orderRef),
+            preheader: copy.preheader,
+            blocks,
+        };
+    }
+    return { checkoutExpiredEmailContent };
+}

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

@@ -0,0 +1,26 @@
+import type { CommerceEmailContent } from "./commerceEmailContent.js";
+import type { Locale } from "./email.js";
+import { type EmailBlock } from "./blocks.js";
+export type CheckoutRecoveryReminderHours = 1 | 20;
+export type CheckoutRecoveryMode = "subscription_cycle" | "one_time";
+export interface CheckoutRecoveryEmailVars {
+    firstName: string | null;
+    brandName: string;
+    reminderHours: CheckoutRecoveryReminderHours;
+    mode: CheckoutRecoveryMode;
+    /** Absolute signed deep-link to complete payment for this order. */
+    recoveryUrl: string;
+    /** Optional deployment-specific context consumed by the selected copy pack. */
+    contextName?: string | null;
+}
+export interface CheckoutRecoveryEmailContent {
+    subject: string;
+    preheader: string;
+    blocks: EmailBlock[];
+}
+/** Bind host-selected copy and pure helpers without provider or environment access. */
+export declare function createCheckoutRecoveryContentFactory(input: {
+    commerceEmailContent: Pick<CommerceEmailContent, "checkoutRecovery">;
+}): {
+    checkoutRecoveryEmailContent: (locale: Locale, vars: CheckoutRecoveryEmailVars, signoff: string) => CheckoutRecoveryEmailContent;
+};

package/dist/communications/contracts/checkoutRecovery.js

@@ -0,0 +1,37 @@
+import { button, heading, paragraph } from "./blocks.js";
+/** Bind host-selected copy and pure helpers without provider or environment access. */
+export function createCheckoutRecoveryContentFactory(input) {
+    const { commerceEmailContent } = input;
+    function checkoutRecoveryEmailContent(locale, vars, signoff) {
+        const copy = commerceEmailContent.checkoutRecovery[locale];
+        const isFinal = vars.reminderHours === 20;
+        // The optional selected-pack context note runs only on the first nudge (1h).
+        // The final reminder (20h) stays businesslike, so it never sits next to the
+        // "order will be canceled" note.
+        const showCheer = !isFinal;
+        const isSubscription = vars.mode === "subscription_cycle";
+        const intro = isSubscription
+            ? copy.introSubscription
+            : showCheer
+                ? `${copy.introOneTime} ${copy.contextCheer(vars.contextName ?? null)}`
+                : copy.introOneTime;
+        const blocks = [
+            heading(isFinal ? copy.headingFinal : copy.headingFirst),
+            paragraph(copy.greeting(vars.firstName)),
+            paragraph(intro),
+            button(copy.cta, vars.recoveryUrl),
+        ];
+        if (isSubscription && showCheer) {
+            blocks.push(paragraph(copy.subscriptionCheer(vars.contextName ?? null, vars.brandName)));
+        }
+        if (isFinal)
+            blocks.push(paragraph(copy.finalNote));
+        blocks.push(paragraph(signoff));
+        return {
+            subject: isFinal ? copy.subjectFinal : copy.subjectFirst,
+            preheader: copy.preheader,
+            blocks,
+        };
+    }
+    return { checkoutRecoveryEmailContent };
+}