@openlup/platform 0.16.0 → 0.18.0

package/dist/communications/managedTransactionalDeliveryStore.d.ts

@@ -0,0 +1,12 @@
+import type { TransactionalDeliveryReceiptStore } from "./contracts/transactionalDelivery.js";
+export interface ManagedTransactionalDeliveryStoreClient {
+    rpc(functionName: string, args: Record<string, unknown>): PromiseLike<{
+        data: unknown;
+        error: {
+            code?: string;
+            message?: string;
+        } | null;
+    }>;
+}
+/** Managed adapter over the three receipt RPCs; access scope belongs to its binding. */
+export declare function createManagedTransactionalDeliveryStore(client: ManagedTransactionalDeliveryStoreClient): TransactionalDeliveryReceiptStore;

package/dist/communications/managedTransactionalDeliveryStore.js

@@ -0,0 +1,49 @@
+function failure(name, error) {
+    const result = new Error(`${name}_failed: ${error.message ?? error.code ?? "unknown"}`);
+    result.code = error.code;
+    return result;
+}
+function receipt(data) {
+    const value = (Array.isArray(data) ? data[0] : data);
+    if (!value || typeof value !== "object")
+        throw new Error("transactional_delivery_receipt_invalid");
+    const common = {
+        idempotencyKey: String(value.idempotency_key ?? ""),
+        commandFingerprint: String(value.command_fingerprint ?? ""),
+        attemptCount: Number(value.attempt_count ?? 0),
+    };
+    if (value.state === "accepted" && typeof value.delivery_reference === "string" && value.error_code == null) {
+        return { ...common, state: "accepted", deliveryReference: value.delivery_reference, errorCode: null };
+    }
+    if (value.state === "failed" && value.delivery_reference == null && typeof value.error_code === "string") {
+        return { ...common, state: "failed", deliveryReference: null, errorCode: value.error_code };
+    }
+    throw new Error("transactional_delivery_receipt_invalid");
+}
+/** Managed adapter over the three receipt RPCs; access scope belongs to its binding. */
+export function createManagedTransactionalDeliveryStore(client) {
+    const call = async (name, args) => {
+        const { data, error } = await client.rpc(name, args);
+        if (error)
+            throw failure(name, error);
+        return receipt(data);
+    };
+    return {
+        async readReceipt(idempotencyKey) {
+            const { data, error } = await client.rpc("transactional_delivery_read_receipt", { p_idempotency_key: idempotencyKey });
+            if (error)
+                throw failure("transactional_delivery_read_receipt", error);
+            return Array.isArray(data) && data.length === 0 ? null : receipt(data);
+        },
+        recordAccepted: (input) => call("transactional_delivery_record_accepted", {
+            p_idempotency_key: input.idempotencyKey,
+            p_command_fingerprint: input.commandFingerprint,
+            p_delivery_reference: input.deliveryReference,
+        }),
+        recordFailed: (input) => call("transactional_delivery_record_failed", {
+            p_idempotency_key: input.idempotencyKey,
+            p_command_fingerprint: input.commandFingerprint,
+            p_error_code: input.errorCode,
+        }),
+    };
+}

package/dist/communications/nativeOperations.d.ts

@@ -0,0 +1,79 @@
+import type { PostgresDataGatewayOptions } from "../data/index.js";
+import type { DeliveryReconciliationPort } from "./deliveryReconciliation.js";
+import type { CommunicationRecipientKind } from "./consentPolicy.js";
+export interface NativeCommunicationsOptions extends PostgresDataGatewayOptions {
+    binding: string;
+}
+export type NativeObservationKind = "sent" | "delayed" | "delivered" | "bounced" | "complained" | "failed";
+export interface NativeNetworkTarget {
+    sourceKey: string;
+    messageId: string;
+    recipientEmail: string;
+    templateReference: string;
+    acceptedAt: string;
+    /** Only a host that observed a real network acceptance may register this fact. */
+    evidence: "network_accepted";
+}
+export interface NativeDeliveryEvidence {
+    id: string;
+    sourceKey: string;
+    messageId: string;
+    acceptedAt: string;
+    observedState: NativeObservationKind | null;
+    observedAt: string | null;
+    lastPollAt: string | null;
+    notFoundCount: number;
+    abandonedAt: string | null;
+    observations: {
+        key: string;
+        kind: NativeObservationKind;
+        occurredAt: string;
+        source: "poll" | "callback";
+    }[];
+}
+export interface NativeDeliveryStore extends DeliveryReconciliationPort {
+    registerNetworkTarget(input: NativeNetworkTarget): Promise<{
+        id: string;
+    }>;
+    applyObservation(input: {
+        sendId: string;
+        messageId: string;
+        observationKey: string;
+        kind: NativeObservationKind;
+        occurredAt: string;
+        recipientEmail: string | null;
+        source: "poll" | "callback";
+    }): Promise<void>;
+    findByMessageId(messageId: string): Promise<{
+        id: string;
+    } | null>;
+    listEvidence(input: {
+        limit: number;
+    }): Promise<NativeDeliveryEvidence[]>;
+    readEvidence(sendId: string): Promise<NativeDeliveryEvidence | null>;
+    close(): Promise<void>;
+}
+export type NativeNotificationType = "packaging_digest" | "new_signup" | "commerce_payment_critical";
+export interface NativeNotificationRecipient {
+    id: string;
+    email: string;
+    name: string | null;
+    active: boolean;
+    notification_type: NativeNotificationType;
+    created_at: string;
+}
+export interface NativeConsentInput {
+    email: string;
+    purpose: string;
+    recipientKind?: CommunicationRecipientKind;
+    sourceTable?: "testers" | "waitlist" | "clients" | "b2b_inquiries" | "notification_recipients";
+    sourceId?: string | null;
+}
+export interface NativeConsentDecision {
+    allowed: boolean;
+    reason: string;
+    decisionId: string;
+}
+export declare class NativeConsentEvaluationUnavailableError extends Error {
+    constructor(cause: unknown);
+}

package/dist/communications/nativeOperations.js

@@ -0,0 +1,3 @@
+export class NativeConsentEvaluationUnavailableError extends Error {
+    constructor(cause) { super("native_consent_evaluation_unavailable", { cause }); this.name = "ConsentEvaluationUnavailableError"; }
+}

package/dist/communications/newsletterIntegrationContracts.d.ts

@@ -0,0 +1,130 @@
+import type { CommunicationPurposeRegistry } from "./contracts/consent.js";
+import { z } from "./validation.js";
+export declare const NEWSLETTER_MARKETING_PURPOSES: readonly ["marketing_launch_offer", "marketing_newsletter"];
+export declare const NEWSLETTER_SYNC_EVENT_TYPES: readonly ["subscribe", "update", "unsubscribe", "suppress"];
+export declare const NEWSLETTER_WEBHOOK_EVENT_TYPES: readonly ["subscribe", "update", "unsubscribe", "suppress", "complaint", "bounce", "email_change", "profile_update", "ignored"];
+export declare const NEWSLETTER_PROVIDER_CAPABILITY_KEYS: readonly ["subscribe", "unsubscribe", "suppress", "unsuppress", "doubleOptIn", "emailChange", "listMembership", "webhookIdempotency", "retryAfter"];
+import type { NewsletterMarketingPurpose } from "./contracts/newsletter.js";
+import type { NewsletterSyncEventType, NewsletterProviderCapabilityKey, NewsletterProviderCapabilities, NewsletterWebhookEvent } from "./contracts/newsletter.js";
+export type { NewsletterProviderKind, NewsletterMarketingPurpose, NewsletterSyncEventType, NewsletterWebhookEventType, NewsletterProviderCapabilityKey, NewsletterProviderCapabilities, NewsletterWebhookEvent, NewsletterSyncEvent } from "./contracts/newsletter.js";
+export declare const defaultNewsletterProviderCapabilities: NewsletterProviderCapabilities;
+export declare const fullNewsletterProviderCapabilities: NewsletterProviderCapabilities;
+export declare const newsletterProviderKindSchema: z.ZodString;
+export declare const newsletterMarketingPurposeSchema: z.ZodEnum<{
+    marketing_launch_offer: "marketing_launch_offer";
+    marketing_newsletter: "marketing_newsletter";
+}>;
+export declare const newsletterSyncEventTypeSchema: z.ZodEnum<{
+    update: "update";
+    subscribe: "subscribe";
+    unsubscribe: "unsubscribe";
+    suppress: "suppress";
+}>;
+export declare const newsletterWebhookEventTypeSchema: z.ZodEnum<{
+    update: "update";
+    email_change: "email_change";
+    subscribe: "subscribe";
+    unsubscribe: "unsubscribe";
+    suppress: "suppress";
+    complaint: "complaint";
+    bounce: "bounce";
+    profile_update: "profile_update";
+    ignored: "ignored";
+}>;
+export declare const newsletterProviderCapabilitiesSchema: z.ZodObject<{
+    subscribe: z.ZodBoolean;
+    unsubscribe: z.ZodBoolean;
+    suppress: z.ZodBoolean;
+    unsuppress: z.ZodBoolean;
+    doubleOptIn: z.ZodBoolean;
+    emailChange: z.ZodBoolean;
+    listMembership: z.ZodBoolean;
+    webhookIdempotency: z.ZodBoolean;
+    retryAfter: z.ZodBoolean;
+}, z.core.$strip>;
+export declare const canonicalNewsletterWebhookEventSchema: z.ZodObject<{
+    providerKind: z.ZodString;
+    providerEventId: z.ZodString;
+    eventType: z.ZodEnum<{
+        update: "update";
+        email_change: "email_change";
+        subscribe: "subscribe";
+        unsubscribe: "unsubscribe";
+        suppress: "suppress";
+        complaint: "complaint";
+        bounce: "bounce";
+        profile_update: "profile_update";
+        ignored: "ignored";
+    }>;
+    email: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    remoteProfileId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    remoteListId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    purpose: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        marketing_launch_offer: "marketing_launch_offer";
+        marketing_newsletter: "marketing_newsletter";
+    }>>>;
+    explicitOptInEvidence: z.ZodOptional<z.ZodBoolean>;
+    doubleOptInStatus: z.ZodOptional<z.ZodEnum<{
+        unknown: "unknown";
+        confirmed: "confirmed";
+        pending: "pending";
+    }>>;
+    occurredAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    payload: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export type CanonicalNewsletterWebhookEvent = z.infer<typeof canonicalNewsletterWebhookEventSchema>;
+export declare function normalizeCanonicalNewsletterWebhookEvent<Purpose extends string = NewsletterMarketingPurpose>(event: Omit<CanonicalNewsletterWebhookEvent, "purpose"> & {
+    purpose?: Purpose | null;
+}): NewsletterWebhookEvent<Purpose>;
+export declare function requiredNewsletterCapabilityForEvent(eventType: NewsletterSyncEventType): NewsletterProviderCapabilityKey;
+export declare function supportsNewsletterSyncEvent(capabilities: NewsletterProviderCapabilities, eventType: NewsletterSyncEventType): boolean;
+/** Explicit registry binding; legacy schemas above retain their two-purpose default. */
+export declare function createNewsletterIntegrationSchemas<Purpose extends string>(registry: CommunicationPurposeRegistry<Purpose>): {
+    purpose: z.ZodCustom<Purpose, Purpose>;
+    webhookEvent: z.ZodObject<{
+        providerKind: z.ZodString;
+        providerEventId: z.ZodString;
+        eventType: z.ZodEnum<{
+            update: "update";
+            email_change: "email_change";
+            subscribe: "subscribe";
+            unsubscribe: "unsubscribe";
+            suppress: "suppress";
+            complaint: "complaint";
+            bounce: "bounce";
+            profile_update: "profile_update";
+            ignored: "ignored";
+        }>;
+        email: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        remoteProfileId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        remoteListId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        explicitOptInEvidence: z.ZodOptional<z.ZodBoolean>;
+        doubleOptInStatus: z.ZodOptional<z.ZodEnum<{
+            unknown: "unknown";
+            confirmed: "confirmed";
+            pending: "pending";
+        }>>;
+        occurredAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        payload: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        purpose: z.ZodOptional<z.ZodNullable<z.ZodCustom<Purpose, Purpose>>>;
+    }, z.core.$strip>;
+    syncEvent: z.ZodObject<{
+        id: z.ZodString;
+        claimToken: z.ZodString;
+        contactId: z.ZodString;
+        normalizedEmail: z.ZodString;
+        eventType: z.ZodEnum<{
+            update: "update";
+            subscribe: "subscribe";
+            unsubscribe: "unsubscribe";
+            suppress: "suppress";
+        }>;
+        purpose: z.ZodCustom<Purpose, Purpose>;
+        payload: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        attemptCount: z.ZodNumber;
+        originProviderKind: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        originProviderEventId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        remoteProfileId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        remoteListId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>;
+};

package/dist/communications/newsletterIntegrationContracts.js

@@ -0,0 +1,128 @@
+import { z } from "./validation.js";
+export const NEWSLETTER_MARKETING_PURPOSES = [
+    "marketing_launch_offer",
+    "marketing_newsletter",
+];
+export const NEWSLETTER_SYNC_EVENT_TYPES = [
+    "subscribe",
+    "update",
+    "unsubscribe",
+    "suppress",
+];
+export const NEWSLETTER_WEBHOOK_EVENT_TYPES = [
+    ...NEWSLETTER_SYNC_EVENT_TYPES,
+    "complaint",
+    "bounce",
+    "email_change",
+    "profile_update",
+    "ignored",
+];
+export const NEWSLETTER_PROVIDER_CAPABILITY_KEYS = [
+    "subscribe",
+    "unsubscribe",
+    "suppress",
+    "unsuppress",
+    "doubleOptIn",
+    "emailChange",
+    "listMembership",
+    "webhookIdempotency",
+    "retryAfter",
+];
+export const defaultNewsletterProviderCapabilities = {
+    subscribe: false,
+    unsubscribe: false,
+    suppress: false,
+    unsuppress: false,
+    doubleOptIn: false,
+    emailChange: false,
+    listMembership: false,
+    webhookIdempotency: false,
+    retryAfter: false,
+};
+export const fullNewsletterProviderCapabilities = {
+    subscribe: true,
+    unsubscribe: true,
+    suppress: true,
+    unsuppress: true,
+    doubleOptIn: true,
+    emailChange: true,
+    listMembership: true,
+    webhookIdempotency: true,
+    retryAfter: true,
+};
+export const newsletterProviderKindSchema = z
+    .string()
+    .trim()
+    .min(1)
+    .max(80)
+    .regex(/^[a-z0-9][a-z0-9_-]*$/);
+export const newsletterMarketingPurposeSchema = z.enum(NEWSLETTER_MARKETING_PURPOSES);
+export const newsletterSyncEventTypeSchema = z.enum(NEWSLETTER_SYNC_EVENT_TYPES);
+export const newsletterWebhookEventTypeSchema = z.enum(NEWSLETTER_WEBHOOK_EVENT_TYPES);
+export const newsletterProviderCapabilitiesSchema = z.object({
+    subscribe: z.boolean(),
+    unsubscribe: z.boolean(),
+    suppress: z.boolean(),
+    unsuppress: z.boolean(),
+    doubleOptIn: z.boolean(),
+    emailChange: z.boolean(),
+    listMembership: z.boolean(),
+    webhookIdempotency: z.boolean(),
+    retryAfter: z.boolean(),
+});
+export const canonicalNewsletterWebhookEventSchema = z.object({
+    providerKind: newsletterProviderKindSchema,
+    providerEventId: z.string().trim().min(1).max(200),
+    eventType: newsletterWebhookEventTypeSchema,
+    email: z.string().trim().email().nullable().optional(),
+    remoteProfileId: z.string().trim().min(1).max(200).nullable().optional(),
+    remoteListId: z.string().trim().min(1).max(200).nullable().optional(),
+    purpose: newsletterMarketingPurposeSchema.nullable().optional(),
+    explicitOptInEvidence: z.boolean().optional(),
+    doubleOptInStatus: z.enum(["confirmed", "pending", "unknown"]).optional(),
+    occurredAt: z.string().datetime({ offset: true }).nullable().optional(),
+    payload: z.record(z.string(), z.unknown()).optional(),
+});
+export function normalizeCanonicalNewsletterWebhookEvent(event) {
+    return {
+        providerKind: event.providerKind,
+        providerEventId: event.providerEventId,
+        eventType: event.eventType,
+        email: event.email ?? null,
+        remoteProfileId: event.remoteProfileId ?? null,
+        remoteListId: event.remoteListId ?? null,
+        purpose: event.purpose ?? null,
+        explicitOptInEvidence: event.explicitOptInEvidence === true,
+        doubleOptInStatus: event.doubleOptInStatus ?? "unknown",
+        occurredAt: event.occurredAt ?? null,
+        rawPayload: event.payload ?? {},
+    };
+}
+export function requiredNewsletterCapabilityForEvent(eventType) {
+    if (eventType === "subscribe")
+        return "subscribe";
+    if (eventType === "unsubscribe")
+        return "unsubscribe";
+    if (eventType === "suppress")
+        return "suppress";
+    return "listMembership";
+}
+export function supportsNewsletterSyncEvent(capabilities, eventType) {
+    return capabilities[requiredNewsletterCapabilityForEvent(eventType)] === true;
+}
+/** Explicit registry binding; legacy schemas above retain their two-purpose default. */
+export function createNewsletterIntegrationSchemas(registry) {
+    const purpose = z.custom((value) => registry.has(value), "unregistered_communication_purpose");
+    return {
+        purpose,
+        webhookEvent: canonicalNewsletterWebhookEventSchema.extend({ purpose: purpose.nullable().optional() }),
+        syncEvent: z.object({
+            id: z.string().min(1), claimToken: z.string().min(1), contactId: z.string().min(1),
+            normalizedEmail: z.string().email(), eventType: newsletterSyncEventTypeSchema,
+            purpose, payload: z.record(z.string(), z.unknown()), attemptCount: z.number().int().min(0),
+            originProviderKind: newsletterProviderKindSchema.nullable().optional(),
+            originProviderEventId: z.string().nullable().optional(), remoteProfileId: z.string().nullable().optional(),
+            remoteListId: z.string().nullable().optional(),
+        }),
+    };
+}

package/dist/communications/newsletterWebhookPort.d.ts

@@ -0,0 +1,11 @@
+import type { NewsletterWebhookPort } from "./contracts/newsletterWebhook.js";
+export interface NewsletterWebhookRpcClient {
+    rpc(functionName: string, args: Record<string, unknown>): PromiseLike<{
+        data: unknown;
+        error: {
+            code?: string;
+            message?: string;
+        } | null;
+    }>;
+}
+export declare function createSupabaseNewsletterWebhookPort(client: NewsletterWebhookRpcClient): NewsletterWebhookPort;

package/dist/communications/newsletterWebhookPort.js

@@ -0,0 +1,84 @@
+export function createSupabaseNewsletterWebhookPort(client) {
+    return {
+        async recordProviderEvent(input) {
+            const { data, error } = await client.rpc("communication_record_provider_event", {
+                p_provider_kind: input.providerKind,
+                p_provider_event_id: input.providerEventId,
+                p_event_type: input.eventType,
+                p_email: input.email,
+                p_remote_profile_id: input.remoteProfileId,
+                p_purpose: input.purpose,
+                p_state: input.state,
+                p_payload: sanitizePayload(input.rawPayload),
+                p_metadata: providerEventMetadata(input),
+                p_processing_status: input.processingStatus,
+            });
+            if (error)
+                throw rpcFailure("communication_record_provider_event", error);
+            const record = isRecord(data) ? data : {};
+            return {
+                providerEventId: readString(record.providerEventId) ?? "",
+                contactId: readString(record.contactId),
+                inserted: record.inserted === true,
+            };
+        },
+        async recordPermission(input) {
+            const { error } = await client.rpc("communication_record_permission_event", {
+                p_contact_id: input.contactId,
+                p_purpose: input.purpose,
+                p_state: input.state,
+                p_source: "newsletter_provider_webhook",
+                p_source_ref: {
+                    providerKind: input.providerKind,
+                    providerEventId: input.providerEventId,
+                },
+                p_reason: input.reason,
+                p_metadata: {
+                    ...input.metadata,
+                    actorType: "provider_webhook",
+                    captureMethod: "newsletter_webhook",
+                    originProviderKind: input.providerKind,
+                    originProviderEventId: input.providerEventId,
+                },
+                p_captured_at: new Date().toISOString(),
+                p_create_sync_event: true,
+            });
+            if (error)
+                throw rpcFailure("communication_record_permission_event", error);
+        },
+        async markProviderEvent(input) {
+            const { error } = await client.rpc("communication_mark_provider_event_processed", {
+                p_provider_event_id: input.providerEventId,
+                p_processing_status: input.status,
+                p_metadata: input.metadata,
+            });
+            if (error)
+                throw rpcFailure("communication_mark_provider_event_processed", error);
+        },
+    };
+}
+function providerEventMetadata(input) {
+    return {
+        occurredAt: input.occurredAt,
+        explicitOptInEvidence: input.explicitOptInEvidence,
+        doubleOptInStatus: input.doubleOptInStatus,
+        remoteListId: input.remoteListId,
+        processingStatus: input.processingStatus,
+    };
+}
+function sanitizePayload(payload) {
+    const sanitized = { ...payload };
+    delete sanitized.apiKey;
+    delete sanitized.token;
+    delete sanitized.secret;
+    return sanitized;
+}
+function rpcFailure(rpcName, error) {
+    return new Error(`${rpcName}_failed: ${error.message ?? error.code ?? "unknown"}`);
+}
+function isRecord(value) {
+    return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+function readString(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : null;
+}

package/dist/communications/newsletterWebhookProcessing.d.ts

@@ -0,0 +1,17 @@
+import type { NewsletterMarketingPurpose, NewsletterWebhookEvent } from "./contracts/newsletter.js";
+import type { NewsletterWebhookPort } from "./contracts/newsletterWebhook.js";
+import type { CommunicationPurposeRegistry } from "./contracts/consent.js";
+export interface NewsletterWebhookProcessResult {
+    provider: string;
+    providerEventId: string;
+    replayed?: boolean;
+    status?: "processed" | "ignored";
+    reason?: string;
+    localState?: "granted" | "suppressed";
+}
+export declare function processNewsletterWebhookEvent<Purpose extends string = NewsletterMarketingPurpose>(input: {
+    providerKind: string;
+    event: NewsletterWebhookEvent<Purpose>;
+    port: NewsletterWebhookPort<Purpose | NewsletterMarketingPurpose>;
+    registry?: CommunicationPurposeRegistry<Purpose>;
+}): Promise<NewsletterWebhookProcessResult>;

package/dist/communications/newsletterWebhookProcessing.js

@@ -0,0 +1,71 @@
+const MARKETING_PURPOSES = ["marketing_launch_offer", "marketing_newsletter"];
+export async function processNewsletterWebhookEvent(input) {
+    const { providerKind, event, port } = input;
+    if (input.registry && event.purpose !== null && !input.registry.has(event.purpose)) {
+        throw new Error("unregistered_communication_purpose");
+    }
+    const action = localAction(event);
+    const providerEvent = await port.recordProviderEvent({
+        ...event,
+        state: action.state,
+        processingStatus: action.kind === "ignore" ? "ignored" : "received",
+    });
+    if (!providerEvent.inserted) {
+        return { provider: providerKind, providerEventId: event.providerEventId, replayed: true };
+    }
+    if (action.kind === "ignore" || !providerEvent.contactId) {
+        await port.markProviderEvent({
+            providerEventId: providerEvent.providerEventId,
+            status: "ignored",
+            metadata: { reason: action.reason },
+        });
+        return {
+            provider: providerKind,
+            providerEventId: event.providerEventId,
+            status: "ignored",
+            reason: action.reason,
+        };
+    }
+    for (const purpose of event.purpose ? [event.purpose] : MARKETING_PURPOSES) {
+        await port.recordPermission({
+            contactId: providerEvent.contactId,
+            providerKind,
+            providerEventId: event.providerEventId,
+            purpose,
+            state: action.state,
+            reason: action.reason,
+            metadata: {
+                source: "newsletter_provider_webhook",
+                providerKind,
+                providerEventId: event.providerEventId,
+                remoteProfileId: event.remoteProfileId,
+                remoteListId: event.remoteListId,
+                doubleOptInStatus: event.doubleOptInStatus,
+                explicitOptInEvidence: event.explicitOptInEvidence,
+            },
+        });
+    }
+    await port.markProviderEvent({
+        providerEventId: providerEvent.providerEventId,
+        status: "processed",
+        metadata: { localState: action.state, reason: action.reason },
+    });
+    return {
+        provider: providerKind,
+        providerEventId: event.providerEventId,
+        status: "processed",
+        localState: action.state,
+    };
+}
+function localAction(event) {
+    if (["unsubscribe", "suppress", "complaint"].includes(event.eventType)) {
+        return { kind: "apply", state: "suppressed", reason: `provider_${event.eventType}` };
+    }
+    if (event.eventType === "subscribe") {
+        if (event.explicitOptInEvidence || event.doubleOptInStatus === "confirmed") {
+            return { kind: "apply", state: "granted", reason: "provider_verified_opt_in" };
+        }
+        return { kind: "ignore", state: null, reason: "provider_subscribe_without_verified_opt_in" };
+    }
+    return { kind: "ignore", state: null, reason: "provider_event_not_permission_mutating" };
+}

package/dist/communications/originPolicy.d.ts

@@ -0,0 +1,40 @@
+export type EmailOriginSource = "explicit" | "default";
+export type EmailEnvironment = "hidden_preview" | "preview" | "staging" | "production" | "production_or_default" | "unknown";
+export type EmailOriginPolicyError = "hidden_preview_origin_required" | "hidden_preview_origin_must_not_be_production" | "invalid_email_origin";
+export interface ResolvedEmailOrigin {
+    origin: string;
+    source: EmailOriginSource;
+    environment: EmailEnvironment;
+    production: boolean;
+}
+export type EmailOriginResolution = {
+    ok: true;
+    origin: string;
+    source: EmailOriginSource;
+    resolved: ResolvedEmailOrigin;
+} | {
+    ok: false;
+    error: EmailOriginPolicyError;
+};
+export interface EmailOriginInput {
+    /** Brand/configured default origin used when no explicit origin is set. */
+    defaultOrigin: string;
+    /** Hosts treated as production by the policy (brand-supplied). */
+    productionEmailHosts: string[];
+    explicitBaseUrl?: string | null;
+    customerAuthRedirectOrigin?: string | null;
+    siteUrl?: string | null;
+    hiddenPreviewEnabled?: boolean;
+    environment?: string | null;
+}
+export declare const EMAIL_DEFAULT_ORIGIN_ENV = "EMAIL_DEFAULT_ORIGIN";
+export declare const EMAIL_PRODUCTION_ORIGIN_HOSTS_ENV = "EMAIL_PRODUCTION_ORIGIN_HOSTS";
+export declare const COMMS_PRODUCTION_PROJECT_REF_ENV = "COMMS_PRODUCTION_PROJECT_REF";
+export interface EmailOriginConfiguration {
+    defaultOrigin: string;
+    productionEmailHosts: string[];
+}
+export declare function normalizeEmailOrigin(value: string): string | null;
+export declare function isProductionEmailOrigin(origin: string, productionHosts: string[]): boolean;
+export declare function readEmailOriginConfiguration(env: Record<string, string | undefined>, fallback: EmailOriginConfiguration): EmailOriginConfiguration;
+export declare function resolveEmailOrigin(input: EmailOriginInput): EmailOriginResolution;