@openlup/platform 0.16.0 → 0.18.0

package/dist/communications/contracts/guideCard.js

@@ -0,0 +1,26 @@
+// A guide card in a fulfillment mail: the selected copy pack names the guide by
+// a site-relative path, and the sender knows the site origin, so this is the
+// one place the two are joined into the absolute links a mail client needs.
+import { featureCard } from "./blocks.js";
+// Exactly one slash at the seam, whichever side carries it.
+function siteUrl(siteOrigin, path) {
+    return `${siteOrigin.replace(/\/+$/, "")}/${path.replace(/^\/+/, "")}`;
+}
+export function guideCardBlock(copy, siteOrigin, contextName) {
+    return featureCard({
+        eyebrow: copy.eyebrow,
+        title: copy.title,
+        text: copy.text(contextName),
+        cta: { label: copy.cta, href: siteUrl(siteOrigin, copy.path) },
+        ...(copy.image
+            ? {
+                image: {
+                    src: siteUrl(siteOrigin, copy.image.path),
+                    alt: copy.image.alt,
+                    widthPx: copy.image.widthPx,
+                    heightPx: copy.image.heightPx,
+                },
+            }
+            : {}),
+    });
+}

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

@@ -0,0 +1,52 @@
+export type * from "./authEmail.js";
+export type * from "./email.js";
+export type * from "./newsletter.js";
+export type * from "./newsletterWebhook.js";
+export type * from "./publicIntake.js";
+export type * from "./transactionalDelivery.js";
+export type * from "./types.js";
+export type * from "./consent.js";
+export type * from "./marketingAutomation.js";
+export * from "./render.js";
+export * from "./blocks.js";
+export * from "./commerceEmailContent.js";
+export * from "./commerceEngagementEmailContent.js";
+export * from "./subscriptionEmailContent.js";
+export * from "./guideCard.js";
+export * from "./abandonedCart.js";
+export * from "./backInStock.js";
+export * from "./checkoutExpired.js";
+export * from "./checkoutRecovery.js";
+export * from "./orderCanceled.js";
+export * from "./orderDraft.js";
+export * from "./orderPaid.js";
+export * from "./orderRefunded.js";
+export * from "./paymentFailed.js";
+export * from "./reorderReminder.js";
+export * from "./returnEmails.js";
+export * from "./reviewEffects.js";
+export * from "./reviewRequest.js";
+export * from "./shipmentDelivered.js";
+export * from "./shipmentDispatched.js";
+export * from "./shipmentException.js";
+export * from "./subscriptionActivationActionRequired.js";
+export * from "./subscriptionAddressChanged.js";
+export * from "./subscriptionCancelled.js";
+export * from "./subscriptionCycleSkipped.js";
+export * from "./subscriptionDeliveryRescheduled.js";
+export * from "./subscriptionPackageChanged.js";
+export * from "./subscriptionPauseReminder.js";
+export * from "./subscriptionPaused.js";
+export * from "./subscriptionPaymentExpired.js";
+export * from "./subscriptionPaymentFailed.js";
+export * from "./subscriptionPaymentRecovered.js";
+export * from "./subscriptionRenewalAtRisk.js";
+export * from "./subscriptionRenewalUpcoming.js";
+export * from "./subscriptionResumed.js";
+export * from "./subscriptionWelcome.js";
+export * from "./subscriptionWinback.js";
+export * from "./invoiceDocumentContent.js";
+export * from "./roleNotificationContent.js";
+export * from "./inquiryContent.js";
+export * from "./optOutContent.js";
+export type * from "./marketingSync.js";

package/dist/communications/contracts/index.js

@@ -0,0 +1,42 @@
+export * from "./render.js";
+export * from "./blocks.js";
+export * from "./commerceEmailContent.js";
+export * from "./commerceEngagementEmailContent.js";
+export * from "./subscriptionEmailContent.js";
+export * from "./guideCard.js";
+export * from "./abandonedCart.js";
+export * from "./backInStock.js";
+export * from "./checkoutExpired.js";
+export * from "./checkoutRecovery.js";
+export * from "./orderCanceled.js";
+export * from "./orderDraft.js";
+export * from "./orderPaid.js";
+export * from "./orderRefunded.js";
+export * from "./paymentFailed.js";
+export * from "./reorderReminder.js";
+export * from "./returnEmails.js";
+export * from "./reviewEffects.js";
+export * from "./reviewRequest.js";
+export * from "./shipmentDelivered.js";
+export * from "./shipmentDispatched.js";
+export * from "./shipmentException.js";
+export * from "./subscriptionActivationActionRequired.js";
+export * from "./subscriptionAddressChanged.js";
+export * from "./subscriptionCancelled.js";
+export * from "./subscriptionCycleSkipped.js";
+export * from "./subscriptionDeliveryRescheduled.js";
+export * from "./subscriptionPackageChanged.js";
+export * from "./subscriptionPauseReminder.js";
+export * from "./subscriptionPaused.js";
+export * from "./subscriptionPaymentExpired.js";
+export * from "./subscriptionPaymentFailed.js";
+export * from "./subscriptionPaymentRecovered.js";
+export * from "./subscriptionRenewalAtRisk.js";
+export * from "./subscriptionRenewalUpcoming.js";
+export * from "./subscriptionResumed.js";
+export * from "./subscriptionWelcome.js";
+export * from "./subscriptionWinback.js";
+export * from "./invoiceDocumentContent.js";
+export * from "./roleNotificationContent.js";
+export * from "./inquiryContent.js";
+export * from "./optOutContent.js";

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

@@ -0,0 +1,32 @@
+import type { Locale } from "./email.js";
+import { type DataRow, type EmailBlock } from "./blocks.js";
+export interface InquiryVars {
+    displayName: string;
+    contact: string;
+    /** Host-resolved labels and values; omit optional rows rather than inventing them. */
+    details: DataRow[];
+    operatorUrl: string;
+}
+export interface InquiryCopy {
+    receiptSubject: string;
+    receiptGreeting: (name: string) => string;
+    receiptBody: string;
+    noticeSubject: string;
+    noticeBody: string;
+    nameLabel: string;
+    contactLabel: string;
+    cta: string;
+}
+/** Presentation only: no recipient, sender, response-time promise or country policy. */
+export declare function createInquiryContentFactory(copy?: Record<Locale, InquiryCopy>): {
+    inquiryReceiptEmailContent: (locale: Locale, vars: InquiryVars, signoff: string) => {
+        subject: string;
+        preheader: string;
+        blocks: EmailBlock[];
+    };
+    inquiryNoticeEmailContent: (locale: Locale, vars: InquiryVars, signoff: string) => {
+        subject: string;
+        preheader: string;
+        blocks: EmailBlock[];
+    };
+};

package/dist/communications/contracts/inquiryContent.js

@@ -0,0 +1,33 @@
+import { button, dataTable, heading, paragraph } from "./blocks.js";
+const defaults = {
+    pl: {
+        receiptSubject: "Otrzymaliśmy Twoje zapytanie",
+        receiptGreeting: name => `Dziękujemy za kontakt, ${name}.`,
+        receiptBody: "Potwierdzamy otrzymanie Twojego zapytania.",
+        noticeSubject: "Nowe zapytanie", noticeBody: "Otrzymano nowe zapytanie.",
+        nameLabel: "Imię i nazwisko", contactLabel: "Kontakt", cta: "Otwórz zapytanie",
+    },
+    en: {
+        receiptSubject: "We've received your inquiry",
+        receiptGreeting: name => `Thank you for contacting us, ${name}.`,
+        receiptBody: "We confirm receipt of your inquiry.",
+        noticeSubject: "New inquiry", noticeBody: "A new inquiry has been received.",
+        nameLabel: "Name", contactLabel: "Contact", cta: "Open inquiry",
+    },
+};
+/** Presentation only: no recipient, sender, response-time promise or country policy. */
+export function createInquiryContentFactory(copy = defaults) {
+    function inquiryReceiptEmailContent(locale, vars, signoff) {
+        const c = copy[locale];
+        return { subject: c.receiptSubject, preheader: c.receiptBody,
+            blocks: [heading(c.receiptSubject), paragraph(c.receiptGreeting(vars.displayName)), paragraph(c.receiptBody), paragraph(signoff)] };
+    }
+    function inquiryNoticeEmailContent(locale, vars, signoff) {
+        const c = copy[locale];
+        return { subject: c.noticeSubject, preheader: c.noticeBody,
+            blocks: [heading(c.noticeSubject), paragraph(c.noticeBody),
+                dataTable([{ label: c.nameLabel, value: vars.displayName }, { label: c.contactLabel, value: vars.contact }, ...vars.details]),
+                button(c.cta, vars.operatorUrl), paragraph(signoff)] };
+    }
+    return { inquiryReceiptEmailContent, inquiryNoticeEmailContent };
+}

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/marketingSync.d.ts

@@ -0,0 +1,194 @@
+declare const subjectBrand: unique symbol, feedbackBrand: unique symbol, receiptBrand: unique symbol, readBrand: unique symbol;
+type Operation = "profile.sync" | "consent.read" | "erasure.request" | "erasure.read";
+type Mutation = "profile.sync" | "erasure.request";
+type SubjectReference = string & {
+    readonly [subjectBrand]: "opaque-subject";
+};
+export type SyncBinding = Readonly<{
+    account: string;
+    environment: string;
+    namespace: string;
+    mappingVersion: string;
+}>;
+export type SyncAudience = Readonly<{
+    kind: "account-wide";
+} | {
+    kind: "audience";
+    reference: string;
+}>;
+export type ProfileProjection = Readonly<{
+    email: string;
+    externalReference: string;
+    fields: Readonly<Partial<Record<"givenName" | "familyName" | "locale", string>>>;
+    properties: Readonly<Record<string, string | number | boolean>>;
+}>;
+type Payload = {
+    "profile.sync": {
+        projection: ProfileProjection;
+        consentEvidenceReference: string;
+    };
+    "consent.read": Readonly<Record<string, never>>;
+    "erasure.request": {
+        caseReference: string;
+        authorityReference: string;
+    };
+    "erasure.read": {
+        receipt: SyncReceipt<"erasure.request">;
+    };
+};
+export type SyncRequest<O extends Operation = Operation> = {
+    [K in O]: Readonly<{
+        binding: SyncBinding;
+        audience: SyncAudience;
+        subjectReference: SubjectReference;
+        requestId: string;
+        generation: number;
+        deadlineMs: number;
+        authorizationReference: string;
+        operation: K;
+        payload: Readonly<Payload[K]>;
+    }>;
+}[O];
+export type NegativeFeedback = Readonly<{
+    [feedbackBrand]: "provider-negative";
+    sourceReference: string;
+    occurredAtMs: number | null;
+    audience: SyncAudience;
+}> & Readonly<{
+    kind: "unsubscribe" | "complaint" | "manual_block";
+    outcome: "deny_permission";
+} | {
+    kind: "hard_bounce" | "invalid_address";
+    outcome: "deny_delivery";
+}>;
+export type ConsentReadback = Readonly<{
+    audience: SyncAudience;
+    observedAtMs: number;
+    remoteConsent: "subscribed" | "unsubscribed" | "pending" | "never_subscribed" | "unknown";
+    feedback: readonly NegativeFeedback[];
+    coverage: "complete" | "partial" | "unsupported";
+}>;
+export type SyncFailure<O extends Operation = Operation> = {
+    kind: "refused";
+    reason: "invalid_request" | "binding" | "provenance" | "stale" | "deadline" | "unsupported" | "verification_pending" | "restricted" | "identity_conflict" | "provider_refusal";
+} | {
+    kind: "retryable";
+    reason: "cooling" | "host" | "provider";
+    afterSeconds: number;
+} | ({
+    kind: "unknown";
+    reason: "dispatch_unresolved" | "acceptance_ambiguous" | "record_failed";
+} & (O extends Mutation ? {
+    receipt?: SyncReceipt<O>;
+} : {
+    receipt?: never;
+}));
+export type SyncReceipt<O extends Mutation> = Readonly<{
+    [receiptBrand]: O;
+    operation: O;
+    request: SyncRequest<O>;
+}>;
+type MutationSuccess<O extends Mutation> = {
+    kind: "accepted" | "acknowledged";
+    receipt: SyncReceipt<O>;
+    journal: "confirmed" | "unknown";
+};
+type Success = {
+    "profile.sync": MutationSuccess<"profile.sync">;
+    "consent.read": {
+        kind: "completed";
+        value: ConsentReadback;
+        journal: "confirmed" | "unknown";
+    };
+    "erasure.request": MutationSuccess<"erasure.request">;
+    "erasure.read": MutationSuccess<"erasure.request"> | {
+        kind: "completed";
+        receipt: SyncReceipt<"erasure.request">;
+        journal: "confirmed" | "unknown";
+        evidence: Readonly<{
+            [readBrand]: "provider-read";
+            readRequestId: string;
+            observedAtMs: number;
+            evidenceReference: string;
+            assurance: "provider_record_deleted" | "provider_erasure_confirmed";
+        }>;
+    };
+};
+export type SyncResult<O extends Operation = Operation> = {
+    [K in O]: Readonly<Pick<SyncRequest<K>, "binding" | "operation" | "subjectReference" | "requestId" | "generation">> & Readonly<Success[K] | SyncFailure<K>>;
+}[O];
+export type SyncCapabilities = Readonly<{
+    binding: SyncBinding;
+    audience: SyncAudience;
+    operations: Readonly<Record<Operation, {
+        state: "supported";
+        evidenceReference: string;
+        maxRequestBytes: number;
+        maxFeedbackItems: number;
+    } | {
+        state: "unsupported" | "verification_pending";
+    }>>;
+}>;
+export interface ProfileSyncPort {
+    sync(request: SyncRequest<"profile.sync">): Promise<SyncResult<"profile.sync">>;
+}
+export interface ConsentReadPort {
+    read(request: SyncRequest<"consent.read">): Promise<SyncResult<"consent.read">>;
+}
+export interface ErasurePort {
+    request(request: SyncRequest<"erasure.request">): Promise<SyncResult<"erasure.request">>;
+    read(request: SyncRequest<"erasure.read">): Promise<SyncResult<"erasure.read">>;
+}
+export interface MarketingSyncProvider {
+    readonly capabilities: SyncCapabilities;
+    readonly profiles: ProfileSyncPort;
+    readonly consent: ConsentReadPort;
+    readonly erasure: ErasurePort;
+}
+export type ConsentPushRequest = Readonly<Omit<SyncRequest<"profile.sync">, "operation" | "audience" | "payload"> & {
+    operation: "consent.push";
+} & ({
+    audience: Extract<SyncAudience, {
+        kind: "audience";
+    }>;
+    payload: Readonly<{
+        action: "grant";
+        consentEvidenceReference: string;
+    }>;
+} | {
+    audience: SyncAudience;
+    payload: Readonly<{
+        action: "withdraw";
+        consentEvidenceReference: string;
+    }>;
+})>;
+declare const pushReceiptBrand: unique symbol;
+type PushReceipt = Readonly<{
+    [pushReceiptBrand]: "consent.push";
+    operation: "consent.push";
+    request: ConsentPushRequest;
+}>;
+type PushFailure = Exclude<SyncFailure, {
+    kind: "unknown";
+}> | (Omit<Extract<SyncFailure, {
+    kind: "unknown";
+}>, "receipt"> & {
+    receipt?: PushReceipt;
+});
+export type ConsentPushResult = Readonly<Pick<ConsentPushRequest, "binding" | "operation" | "subjectReference" | "requestId" | "generation">> & Readonly<{
+    kind: "accepted" | "acknowledged";
+    receipt: PushReceipt;
+    journal: "confirmed" | "unknown";
+    reconcileRequired: boolean;
+} | PushFailure>;
+export interface ConsentPushPort {
+    readonly capabilities: SyncCapabilities & Readonly<{
+        operations: SyncCapabilities["operations"] & Readonly<{
+            "consent.push": SyncCapabilities["operations"]["profile.sync"] & Readonly<{
+                grantEffect: "audience" | "account-wide";
+            }>;
+        }>;
+    }>;
+    push(request: ConsentPushRequest): Promise<ConsentPushResult>;
+}
+export {};

package/dist/communications/contracts/marketingSync.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 };
+}