@openlup/platform 0.16.0 → 0.18.0

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 };
+}

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

@@ -0,0 +1,176 @@
+import type { Locale } from "./email.js";
+import type { CommerceEngagementEmailContent, CommerceRecoveryEmailContent } from "./commerceEngagementEmailContent.js";
+export interface OrderDraftEmailCopy {
+    subject: (orderId: string) => string;
+    preheader: string;
+    heading: string;
+    greeting: (firstName: string | null) => string;
+    intro: (orderId: string) => string;
+    itemsLabel: string;
+    noItems: string;
+    subtotalLabel: string;
+    discountRowLabel: string;
+    totalLabel: string;
+    cta: string;
+    outro: string;
+    personalizedClosing: (name: string) => string;
+}
+export interface OrderPaidEmailCopy {
+    subject: (orderId: string) => string;
+    preheader: string;
+    heading: string;
+    greeting: (firstName: string | null) => string;
+    introOneTime: (orderId: string) => string;
+    introSubscription: (orderId: string) => string;
+    noItems: string;
+    subtotalLabel: string;
+    catalogProductsLabel: string;
+    discountRowLabel: string;
+    firstSubscriptionDiscountRowLabel: string;
+    productPayableLabel: string;
+    shippingLabel: string;
+    shippingFree: string;
+    totalLabel: string;
+    finalPaidLabel: string;
+    cta: string;
+    receiptNote: (name: string | null) => string;
+    outro: string;
+    withdrawalNotice: string;
+    withdrawalLinkLabel: string;
+}
+export interface OrderCanceledEmailCopy {
+    subject: (orderId: string) => string;
+    preheader: string;
+    heading: string;
+    greeting: (firstName: string | null) => string;
+    intro: (orderId: string) => string;
+    detailsLabel: string;
+    details: (amountLabel: string | null) => string[];
+    returnNote: (name: string | null) => string;
+    cta: string;
+    outro: string;
+}
+export interface OrderRefundedEmailCopy {
+    subject: (orderId: string) => string;
+    preheader: string;
+    heading: string;
+    greeting: (firstName: string | null) => string;
+    intro: (orderId: string) => string;
+    detailsLabel: string;
+    details: (amountLabel: string | null) => string[];
+    returnNote: (brandName: string) => string;
+    cta: string;
+    outro: string;
+}
+export interface PaymentFailedEmailCopy {
+    subject: (orderId: string) => string;
+    preheader: string;
+    heading: string;
+    greeting: (firstName: string | null) => string;
+    intro: (orderId: string) => string;
+    detailsLabel: string;
+    details: (amountLabel: string | null, mode: "subscription_cycle" | "one_time") => string[];
+    cta: string;
+    outro: string;
+}
+/**
+ * A guide the mail points the customer at: a document the deployment hosts
+ * under its own site origin, so `path` is site-relative and the content
+ * module joins it with the origin the sender passes in.
+ */
+export interface EmailGuideCardCopy {
+    eyebrow: string;
+    title: string;
+    text: (contextName: string | null) => string;
+    cta: string;
+    /** Site-relative path of the document (leading slash). */
+    path: string;
+    /** Optional illustration, also site-relative. */
+    image?: {
+        path: string;
+        alt: string;
+        widthPx: number;
+        heightPx: number;
+    };
+}
+export interface ShipmentDispatchedEmailCopy {
+    subject: (orderRef: string) => string;
+    preheader: string;
+    heading: string;
+    greeting: (firstName: string | null) => string;
+    intro: (orderRef: string) => string;
+    trackingLabel: string;
+    trackParcel: string;
+    noTracking: string[];
+    noTrackingLabel: string;
+    /** The account guide the customer can read while the parcel travels. */
+    accountGuide: EmailGuideCardCopy;
+    outro: (contextName: string | null) => string;
+}
+export interface ShipmentDeliveredEmailCopy {
+    subject: (orderRef: string) => string;
+    preheader: string;
+    heading: string;
+    greeting: (firstName: string | null) => string;
+    intro: (orderRef: string, contextName: string | null) => string;
+    /** The getting-started guide to read before the first serving. */
+    startGuide: EmailGuideCardCopy;
+    outro: string;
+}
+export interface ShipmentExceptionEmailCopy {
+    subject: (orderRef: string) => string;
+    preheader: string;
+    heading: string;
+    greeting: (firstName: string | null) => string;
+    intro: (orderRef: string) => string;
+    reassuranceLabel: string;
+    reassurance: string[];
+    cta: string;
+    outro: string;
+}
+export interface ReturnApprovedEmailCopy {
+    subject: (orderRef: string) => string;
+    preheader: string;
+    heading: string;
+    greeting: (firstName: string | null) => string;
+    intro: (orderRef: string) => string;
+    returnAddressNotice: string;
+    cta: string;
+}
+export interface ReturnRejectedEmailCopy {
+    subject: (orderRef: string) => string;
+    preheader: string;
+    heading: string;
+    greeting: (firstName: string | null) => string;
+    intro: (orderRef: string) => string;
+    cta: string;
+}
+export interface ReturnRefundedEmailCopy {
+    subject: (orderRef: string) => string;
+    preheader: string;
+    heading: string;
+    greeting: (firstName: string | null) => string;
+    amountKnown: (amountLabel: string, orderRef: string) => string;
+    amountUnknown: (orderRef: string) => string;
+    returnNote: string;
+    cta: string;
+}
+/** Build-time selected transactional-copy owner for commerce mail. */
+export interface CommerceEmailContent extends CommerceRecoveryEmailContent, CommerceEngagementEmailContent {
+    readonly id: string;
+    readonly orderRefPrefix: string;
+    readonly orderDraft: Record<Locale, OrderDraftEmailCopy>;
+    readonly orderPaid: Record<Locale, OrderPaidEmailCopy>;
+    readonly orderCanceled: Record<Locale, OrderCanceledEmailCopy>;
+    readonly orderRefunded: Record<Locale, OrderRefundedEmailCopy>;
+    readonly paymentFailed: Record<Locale, PaymentFailedEmailCopy>;
+    readonly shipmentDispatched: Record<Locale, ShipmentDispatchedEmailCopy>;
+    readonly shipmentDelivered: Record<Locale, ShipmentDeliveredEmailCopy>;
+    readonly shipmentException: Record<Locale, ShipmentExceptionEmailCopy>;
+    readonly returns: {
+        readonly approved: Record<Locale, ReturnApprovedEmailCopy>;
+        readonly rejected: Record<Locale, ReturnRejectedEmailCopy>;
+        readonly refunded: Record<Locale, ReturnRefundedEmailCopy>;
+    };
+}
+export type CommerceFulfillmentEmailContent = Pick<CommerceEmailContent, "shipmentDispatched" | "shipmentDelivered" | "shipmentException" | "returns">;

package/dist/communications/contracts/commerceEmailContent.js

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

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

@@ -0,0 +1,95 @@
+import type { Locale } from "./email.js";
+export interface AbandonedCartToneEmailCopy {
+    subject: string;
+    preheader: string;
+    heading: string;
+    intro: string;
+    body: string;
+    cta: string;
+}
+export interface AbandonedCartEmailCopy {
+    greeting: (firstName: string | null) => string;
+    first: AbandonedCartToneEmailCopy;
+    gentle: AbandonedCartToneEmailCopy;
+    last: AbandonedCartToneEmailCopy;
+}
+export interface BackInStockEmailCopy {
+    genericLabel: string;
+    subject: (productLabel: string) => string;
+    preheader: string;
+    heading: (productLabel: string) => string;
+    greeting: string;
+    intro: (productLabel: string) => string;
+    hook: string;
+    cta: string;
+}
+export interface CheckoutExpiredEmailCopy {
+    subject: (orderRef: string) => string;
+    preheader: string;
+    heading: string;
+    greeting: (firstName: string | null) => string;
+    intro: (orderRef: string) => string;
+    detailsLabel: string;
+    details: (amountLabel: string | null) => string[];
+    cta: string;
+    outro: string;
+}
+export interface CheckoutRecoveryEmailCopy {
+    greeting: (firstName: string | null) => string;
+    cta: string;
+    subjectFirst: string;
+    subjectFinal: string;
+    preheader: string;
+    headingFirst: string;
+    headingFinal: string;
+    introSubscription: string;
+    introOneTime: string;
+    contextCheer: (contextName: string | null) => string;
+    subscriptionCheer: (contextName: string | null, appName: string) => string;
+    finalNote: string;
+}
+export interface ReorderReminderEmailCopy {
+    subject: string;
+    preheader: string;
+    greeting: (firstName: string | null) => string;
+    heading: string;
+    intro: (appName: string) => string;
+    consistencyNote: string;
+    upsellLabel: string;
+    upsellLines: string[];
+    cta: string;
+}
+export interface ReviewRequestEmailCopy {
+    subject: string;
+    preheader: string;
+    heading: string;
+    greeting: (firstName: string | null) => string;
+    intro: (contextName: string | null) => string;
+    body: string;
+    cta: string;
+    outro: string;
+}
+export interface ReviewEffectsEmailCopy {
+    subject: string;
+    preheader: string;
+    heading: string;
+    greeting: (firstName: string | null) => string;
+    intro: (contextName: string | null, appName: string) => string;
+    body: string;
+    cta: string;
+    outro: string;
+}
+export interface CommerceRecoveryEmailContent {
+    readonly abandonedCart: Record<Locale, AbandonedCartEmailCopy>;
+    readonly checkoutExpired: {
+        readonly expired: Record<Locale, CheckoutExpiredEmailCopy>;
+        readonly recovery: Record<Locale, CheckoutExpiredEmailCopy>;
+    };
+    readonly checkoutRecovery: Record<Locale, CheckoutRecoveryEmailCopy>;
+}
+export interface CommerceEngagementEmailContent {
+    readonly backInStock: Record<Locale, BackInStockEmailCopy>;
+    readonly reorderReminder: Record<Locale, ReorderReminderEmailCopy>;
+    readonly reviewRequest: Record<Locale, ReviewRequestEmailCopy>;
+    readonly reviewEffects: Record<Locale, ReviewEffectsEmailCopy>;
+}

package/dist/communications/contracts/commerceEngagementEmailContent.js

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

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

@@ -0,0 +1,12 @@
+import type { CommunicationPurpose } from "./types.js";
+export type CommunicationPurposeClassification = "marketing" | "non-marketing";
+export interface CommunicationPurposeDefinition<Purpose extends string = CommunicationPurpose> {
+    readonly id: Purpose;
+    readonly classification: CommunicationPurposeClassification;
+}
+/** Immutable, explicitly composed identifiers; registration is never permission. */
+export interface CommunicationPurposeRegistry<Purpose extends string = CommunicationPurpose> {
+    readonly purposes: readonly CommunicationPurposeDefinition<Purpose>[];
+    has(value: unknown): value is Purpose;
+    classification(purpose: Purpose): CommunicationPurposeClassification | undefined;
+}

package/dist/communications/contracts/consent.js

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

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

@@ -0,0 +1,182 @@
+export type Locale = "pl" | "en";
+export interface ParagraphBlock {
+    kind: "paragraph";
+    /**
+     * Plain text. A literal "\n" becomes a <br> in HTML and stays a newline in
+     * text. Two inline markers are honoured in HTML: `**bold**` and
+     * Markdown link syntax — see inlineHtml in render.ts for why only those two.
+     */
+    text: string;
+    /** Render in the muted/secondary colour at a smaller size (fine print). */
+    muted?: boolean;
+    /**
+     * Render BELOW the white content card, above the footer, as centred 11px
+     * fine print. For notices that must be delivered on a durable medium but must
+     * not compete with the message — the consumer-withdrawal paragraph on the
+     * paid-order mail, the marketing unsubscribe line. Ignored in the text part,
+     * where ordering already carries the same meaning.
+     */
+    afterCard?: boolean;
+}
+export interface HeadingBlock {
+    kind: "heading";
+    text: string;
+}
+export interface ListBlock {
+    kind: "list";
+    items: string[];
+}
+export interface AccentBoxBlock {
+    kind: "accentBox";
+    /** Optional uppercase eyebrow label in the brand colour. */
+    label?: string;
+    /** Body lines, rendered one per line. */
+    lines: string[];
+}
+export interface DataRow {
+    label: string;
+    value: string;
+}
+export interface DataTableBlock {
+    kind: "dataTable";
+    /** Rendered inside an accent box as "label: <strong>value</strong>" lines. */
+    rows: DataRow[];
+    /** Optional text link rendered as the box's last line (a carrier tracking page next to its number). */
+    link?: {
+        label: string;
+        href: string;
+    };
+}
+export interface FeatureCardImage {
+    /** Absolute HTTPS URL of the illustration. */
+    src: string;
+    /** Blocked-image fallback, rendered in the card's accent colour. */
+    alt: string;
+    widthPx: number;
+    heightPx: number;
+}
+export interface FeatureCardBlock {
+    kind: "featureCard";
+    /** Optional uppercase eyebrow above the title. */
+    eyebrow?: string;
+    title: string;
+    /** Body copy; the paragraph inline markers apply. */
+    text: string;
+    cta: {
+        label: string;
+        href: string;
+    };
+    /**
+     * Optional illustration. It sits beside the copy on a wide client and above
+     * it on a narrow one - a fluid layout with no media query, so it also holds
+     * in clients that drop <style>.
+     */
+    image?: FeatureCardImage;
+}
+export interface ButtonBlock {
+    kind: "button";
+    label: string;
+    href: string;
+}
+export interface LinkParagraphBlock {
+    kind: "linkParagraph";
+    /** Inline copy rendered as a single clickable <a href> inside a paragraph. */
+    text: string;
+    href: string;
+    /** Render in the muted/secondary colour at fine-print size (footer links). */
+    muted?: boolean;
+    /** See ParagraphBlock.afterCard. */
+    afterCard?: boolean;
+}
+export interface DividerBlock {
+    kind: "divider";
+}
+export type EmailBlock = ParagraphBlock | HeadingBlock | ListBlock | AccentBoxBlock | DataTableBlock | FeatureCardBlock | ButtonBlock | LinkParagraphBlock | DividerBlock;
+export interface EmailTheme {
+    /** Outer page background (warm cream). */
+    bodyBg: string;
+    /** Content card background. */
+    cardBg: string;
+    /** Accent-box background (light teal tint). */
+    accentBg: string;
+    /** Accent-box / divider hairline. */
+    hairline: string;
+    /** Primary brand colour (teal): logo, links, buttons, accent border. */
+    brand: string;
+    /** Text colour on top of the brand colour (e.g. button label). */
+    onBrand: string;
+    /** Heading text. */
+    textHeading: string;
+    /** Body copy. */
+    textBody: string;
+    /** Muted/secondary text (footer, fine print). */
+    textMuted: string;
+    /** Font stack — system fonts only, for broad client support. */
+    fontFamily: string;
+    /** Text logo rendered in the header, and the alt/fallback shown when an image
+     *  logo is set but blocked by the client. */
+    logoText: string;
+    /** Optional hosted logo image URL (absolute HTTPS). When set, the header
+     *  renders an <img> (with logoText as the alt fallback) instead of the text
+     *  wordmark. Left undefined by forks that prefer the text logo. */
+    logoImageUrl?: string;
+    /** Displayed logo height in px (width auto-scales). Used for the width/height
+     *  attributes that keep layout stable when the image is blocked. */
+    logoImageHeightPx?: number;
+    /** Displayed logo width in px (paired with logoImageHeightPx for the attrs). */
+    logoImageWidthPx?: number;
+    /** Optional feature-card background; falls back to accentBg. Set it when the
+     *  card's illustration carries its own background that must match. */
+    featureCardBg?: string;
+    /** Optional feature-card eyebrow and alt-text colour; falls back to brand. */
+    featureCardAccent?: string;
+    /** Content card corner radius, px. */
+    cardRadiusPx: number;
+    /** Button corner radius, px. */
+    buttonRadiusPx: number;
+    /** Max content width, px. */
+    maxWidthPx: number;
+}
+export interface EmailChromeStrings {
+    /** Optional footer tagline under the content card. Left undefined by brands
+     *  that show only the legal fine print (see footerLegalLines). */
+    footerTagline?: string;
+    /** Accessible alt text for the logo (also the fallback when an image logo is
+     *  blocked). */
+    logoAlt: string;
+    /** Optional hosted hero-banner image URL (absolute HTTPS), rendered full-width
+     *  under the header. Each locale can carry different artwork. */
+    bannerImageUrl?: string;
+    /** Alt text for the banner image (shown when the image is blocked). */
+    bannerImageAlt?: string;
+    /** Optional legal fine-print lines rendered in the footer (company
+     *  identification, e.g. art. 206 KSH). Each entry is one line. */
+    footerLegalLines?: string[];
+}
+export interface EmailBrand {
+    /** Brand label used in email copy when it intentionally differs from logo rendering. */
+    copyBrandName: string;
+    /**
+     * Softer, mixed-case brand label for in-body copy (e.g. "openlup"). Distinct from
+     * the all-caps chrome/sign-off form (copyBrandName, "OPENLUP"). Optional: callers
+     * fall back to copyBrandName when a brand does not define a cased variant.
+     */
+    copyBrandNameCased?: string;
+    theme: EmailTheme;
+    chrome: Record<Locale, EmailChromeStrings>;
+}
+export interface RenderEmailInput {
+    /** Brand look + per-locale chrome, injected by the app layer (APP_EMAIL_BRAND). */
+    brand: EmailBrand;
+    locale: Locale;
+    subject: string;
+    /** Inbox preview text; hidden in the body. */
+    preheader?: string;
+    blocks: EmailBlock[];
+}
+export interface RenderedEmail {
+    subject: string;
+    html: string;
+    text: string;
+}
+export type EmailRenderer = (input: RenderEmailInput) => RenderedEmail;

package/dist/communications/contracts/email.js

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

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

@@ -0,0 +1,3 @@
+import type { EmailGuideCardCopy } from "./commerceEmailContent.js";
+import { type FeatureCardBlock } from "./blocks.js";
+export declare function guideCardBlock(copy: EmailGuideCardCopy, siteOrigin: string, contextName: string | null): FeatureCardBlock;