@openlup/platform 0.15.0 → 0.17.0

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;

package/dist/communications/originPolicy.js

@@ -0,0 +1,100 @@
+export const EMAIL_DEFAULT_ORIGIN_ENV = "EMAIL_DEFAULT_ORIGIN";
+export const EMAIL_PRODUCTION_ORIGIN_HOSTS_ENV = "EMAIL_PRODUCTION_ORIGIN_HOSTS";
+export const COMMS_PRODUCTION_PROJECT_REF_ENV = "COMMS_PRODUCTION_PROJECT_REF";
+function clean(value) {
+    const trimmed = value?.trim();
+    return trimmed ? trimmed : null;
+}
+function resolveEnvironment(input) {
+    if (input.hiddenPreviewEnabled)
+        return "hidden_preview";
+    const value = clean(input.environment)?.toLowerCase().replace(/-/g, "_");
+    if (value === "hidden_preview" ||
+        value === "preview" ||
+        value === "staging" ||
+        value === "production" ||
+        value === "production_or_default") {
+        return value;
+    }
+    return "production_or_default";
+}
+export function normalizeEmailOrigin(value) {
+    try {
+        const url = new URL(value);
+        if (url.protocol !== "https:" && url.protocol !== "http:")
+            return null;
+        if (!url.hostname)
+            return null;
+        return url.origin.replace(/\/+$/, "");
+    }
+    catch {
+        return null;
+    }
+}
+export function isProductionEmailOrigin(origin, productionHosts) {
+    try {
+        return productionHosts.includes(new URL(origin).hostname.toLowerCase());
+    }
+    catch {
+        return false;
+    }
+}
+export function readEmailOriginConfiguration(env, fallback) {
+    const configuredDefault = env[EMAIL_DEFAULT_ORIGIN_ENV];
+    const configuredHosts = env[EMAIL_PRODUCTION_ORIGIN_HOSTS_ENV];
+    return {
+        defaultOrigin: configuredDefault === undefined ? fallback.defaultOrigin : configuredDefault,
+        productionEmailHosts: configuredHosts === undefined
+            ? fallback.productionEmailHosts
+            : configuredHosts
+                .split(/[,\s;]+/)
+                .map((host) => host.trim().toLowerCase())
+                .filter(Boolean),
+    };
+}
+function requiresExplicitNonProductionOrigin(environment) {
+    return environment === "hidden_preview" || environment === "preview" || environment === "staging";
+}
+export function resolveEmailOrigin(input) {
+    const environment = resolveEnvironment(input);
+    const explicit = clean(input.explicitBaseUrl) ??
+        clean(input.customerAuthRedirectOrigin) ??
+        clean(input.siteUrl);
+    if (!explicit) {
+        if (requiresExplicitNonProductionOrigin(environment)) {
+            return { ok: false, error: "hidden_preview_origin_required" };
+        }
+        const defaultOrigin = normalizeEmailOrigin(input.defaultOrigin);
+        if (!defaultOrigin)
+            return { ok: false, error: "invalid_email_origin" };
+        return {
+            ok: true,
+            origin: defaultOrigin,
+            source: "default",
+            resolved: {
+                origin: defaultOrigin,
+                source: "default",
+                environment,
+                production: isProductionEmailOrigin(defaultOrigin, input.productionEmailHosts),
+            },
+        };
+    }
+    const normalized = normalizeEmailOrigin(explicit);
+    if (!normalized)
+        return { ok: false, error: "invalid_email_origin" };
+    const production = isProductionEmailOrigin(normalized, input.productionEmailHosts);
+    if (requiresExplicitNonProductionOrigin(environment) && production) {
+        return { ok: false, error: "hidden_preview_origin_must_not_be_production" };
+    }
+    return {
+        ok: true,
+        origin: normalized,
+        source: "explicit",
+        resolved: {
+            origin: normalized,
+            source: "explicit",
+            environment,
+            production,
+        },
+    };
+}

package/dist/communications/postgresCommunicationSync.d.ts

@@ -0,0 +1,79 @@
+import type { SqlExecutor } from "@openlup/core/readiness";
+import type { PostgresDataGatewayEnv } from "../data/index.js";
+import type { CommunicationSyncStore } from "./communicationSyncWorker.js";
+import type { NewsletterSyncEventType, NewsletterMarketingPurpose } from "./contracts/newsletter.js";
+import type { NativeCommunicationsOptions } from "./nativeOperations.js";
+/** Structural seam for the existing outbox store, scoped to this operation's transaction. */
+export interface NativeSyncRail {
+    claimBatch(input: {
+        eventTypes: string[];
+        knownEventTypes: string[];
+        batchSize: number;
+        visibilitySeconds: number;
+        maxAttempts: number;
+    }): Promise<{
+        id: string;
+        attempts: number;
+        metadata: Record<string, unknown>;
+    }[]>;
+    markProcessed(input: {
+        eventId: string;
+        claimToken: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<{
+        applied: boolean;
+    }>;
+    markFailed(input: {
+        eventId: string;
+        claimToken: string;
+        error: string;
+        outcome: "retry" | "discard";
+        baseDelaySeconds: number;
+        maxDelaySeconds: number;
+        maxAttempts: number;
+        snoozeSeconds: number;
+    }): Promise<{
+        status: string;
+    }>;
+}
+export interface NativeSyncRegistration {
+    sourceKey: string;
+    contactId: string;
+    normalizedEmail: string;
+    eventType: NewsletterSyncEventType;
+    purpose: NewsletterMarketingPurpose;
+    payload?: Record<string, unknown>;
+    originProviderKind?: string | null;
+    originProviderEventId?: string | null;
+    remoteProfileId?: string | null;
+    remoteListId?: string | null;
+}
+export interface NativeSyncOptions extends NativeCommunicationsOptions {
+    providerKind: string;
+    rail: (db: SqlExecutor) => NativeSyncRail;
+}
+export interface NativeCommunicationSyncStore extends CommunicationSyncStore {
+    registerWork(input: NativeSyncRegistration): Promise<{
+        id: string;
+    }>;
+    registerPreference(input: {
+        email: string;
+        purpose: "tester_program" | NewsletterMarketingPurpose;
+        state: "denied" | "suppressed";
+    }): Promise<{
+        updated: true;
+        email: string;
+        purpose: "tester_program" | NewsletterMarketingPurpose;
+        state: "denied" | "suppressed";
+        workId: string | null;
+        alreadySuppressed: boolean;
+    }>;
+    close(): Promise<void>;
+}
+export declare const nativeSyncEventType: (binding: string) => string;
+/** Trusted host transaction seam; registration validation remains shared with the standalone store. */
+export declare function registerNativeSyncWorkInTransaction(db: SqlExecutor, options: Pick<NativeSyncOptions, "binding" | "providerKind">, input: NativeSyncRegistration): Promise<{
+    id: string;
+}>;
+/** No sidecar claim/lease/drainer. Only runCommunicationSyncDispatch executes membership effects. */
+export declare function createPostgresCommunicationSyncStore(env: PostgresDataGatewayEnv, options: NativeSyncOptions): NativeCommunicationSyncStore;

package/dist/communications/postgresCommunicationSync.js

@@ -0,0 +1,111 @@
+import { nativeEmail, nativeFingerprint, nativeInteger, nativeJson, nativeStamp, nativeText, nativeTransactions } from "./postgresNativeOperations.js";
+export const nativeSyncEventType = (binding) => `communication.native.sync.${nativeFingerprint(nativeText(binding))}`;
+function nativeSyncRegistration(options, input) {
+    const binding = nativeText(options.binding), provider = nativeText(options.providerKind), eventType = nativeSyncEventType(binding);
+    const email = nativeEmail(input.normalizedEmail), source = nativeText(input.sourceKey), contact = nativeText(input.contactId);
+    if (!["subscribe", "update", "unsubscribe", "suppress"].includes(input.eventType) || !["marketing_launch_offer", "marketing_newsletter"].includes(input.purpose))
+        throw new Error("native_sync_event_invalid");
+    const payload = nativeJson(input.payload ?? {});
+    const refs = [input.originProviderKind ?? null, input.originProviderEventId ?? null, input.remoteProfileId ?? null, input.remoteListId ?? null].map(value => value === null ? null : nativeText(value));
+    const fact = nativeFingerprint(JSON.stringify([provider, contact, email, input.eventType, input.purpose, payload, ...refs]));
+    // Reuse the rail's ordering barrier for successive preferences of one contact/target.
+    const aggregate = nativeFingerprint(JSON.stringify([binding, provider, contact])).slice(0, 32);
+    return async (db) => {
+        // One rail identity for each source event and exact target binding.
+        await db.query(`INSERT INTO public.outbox_events (aggregate_type,aggregate_id,event_type,idempotency_key,payload)
+          VALUES ('communication_native_sync',$4::uuid,$1,$2,$3::jsonb) ON CONFLICT (event_type,idempotency_key) DO NOTHING`, [eventType, source, payload, aggregate]);
+        const work = (await db.query("SELECT id FROM public.outbox_events WHERE event_type=$1 AND idempotency_key=$2 FOR UPDATE", [eventType, source])).rows[0];
+        await db.query(`INSERT INTO public.communication_native_sync_state
+          (work_id,binding,provider_kind,contact_id,normalized_email,purpose,event_kind,origin_provider_kind,origin_provider_event_id,remote_profile_id,remote_list_id,command_fingerprint)
+          VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12) ON CONFLICT (work_id) DO NOTHING`, [work.id, binding, provider, contact, email, input.purpose, input.eventType, ...refs, fact]);
+        const state = (await db.query("SELECT command_fingerprint FROM public.communication_native_sync_state WHERE work_id=$1", [work.id])).rows[0];
+        if (state?.command_fingerprint !== fact)
+            throw new Error("native_sync_registration_conflict");
+        return { id: nativeText(work.id) };
+    };
+}
+/** Trusted host transaction seam; registration validation remains shared with the standalone store. */
+export async function registerNativeSyncWorkInTransaction(db, options, input) {
+    return nativeSyncRegistration(options, input)(db);
+}
+/** No sidecar claim/lease/drainer. Only runCommunicationSyncDispatch executes membership effects. */
+export function createPostgresCommunicationSyncStore(env, options) {
+    const binding = nativeText(options.binding), provider = nativeText(options.providerKind), eventType = nativeSyncEventType(binding);
+    const lane = nativeTransactions(env, options, ["public.communication_native_sync_state", "public.outbox_events", "public.communication_recipient_consents"]);
+    const checkProvider = (value) => { if (value !== provider)
+        throw new Error("native_sync_binding_conflict"); };
+    return {
+        close: lane.close,
+        async registerWork(input) {
+            const register = nativeSyncRegistration(options, input);
+            return lane.run(db => register(db));
+        },
+        registerPreference(input) {
+            const email = nativeEmail(input.email), fingerprint = nativeFingerprint(email), purpose = nativeText(input.purpose);
+            if (!["tester_program", "marketing_launch_offer", "marketing_newsletter"].includes(purpose) || !["denied", "suppressed"].includes(input.state))
+                throw new Error("native_preference_invalid");
+            return lane.run(async (db) => {
+                await db.query("SELECT pg_advisory_xact_lock(hashtextextended($1,0))", [JSON.stringify([fingerprint, purpose])]);
+                const old = (await db.query("SELECT state,updated_at FROM public.communication_recipient_consents WHERE recipient_fingerprint=$1 AND purpose=$2 FOR UPDATE", [fingerprint, purpose])).rows[0];
+                const row = old?.state === input.state ? old : (await db.query(`INSERT INTO public.communication_recipient_consents (recipient_fingerprint,purpose,state)
+          VALUES ($1,$2,$3) ON CONFLICT (recipient_fingerprint,purpose) DO UPDATE SET state=excluded.state,updated_at=clock_timestamp() RETURNING state,updated_at`, [fingerprint, purpose, input.state])).rows[0];
+                let workId = null;
+                if (purpose !== "tester_program") {
+                    const sourceKey = nativeFingerprint(JSON.stringify([fingerprint, purpose, input.state, nativeStamp(row.updated_at)]));
+                    workId = (await registerNativeSyncWorkInTransaction(db, options, { sourceKey, contactId: fingerprint, normalizedEmail: email, eventType: input.state === "suppressed" ? "suppress" : "unsubscribe", purpose: purpose })).id;
+                }
+                return { updated: true, email, purpose: purpose, state: input.state, workId, alreadySuppressed: old?.state === input.state };
+            });
+        },
+        claimBatch(input) {
+            checkProvider(input.providerKind);
+            nativeInteger(input.batchSize, 1, 100);
+            nativeInteger(input.visibilitySeconds, 60, 3600);
+            nativeInteger(input.maxAttempts, 1, 20);
+            return lane.run(async (db) => {
+                const work = await options.rail(db).claimBatch({ eventTypes: [eventType], knownEventTypes: [eventType], batchSize: input.batchSize, visibilitySeconds: input.visibilitySeconds, maxAttempts: input.maxAttempts });
+                const events = [];
+                for (const row of work) {
+                    const state = (await db.query("UPDATE public.communication_native_sync_state SET max_attempts=$4 WHERE work_id=$1 AND binding=$2 AND provider_kind=$3 RETURNING *", [row.id, binding, provider, input.maxAttempts])).rows[0];
+                    if (!state)
+                        throw new Error("native_sync_sidecar_missing");
+                    const payload = (await db.query("SELECT payload FROM public.outbox_events WHERE id=$1", [row.id])).rows[0].payload;
+                    nativeJson(payload);
+                    events.push({ id: nativeText(row.id), claimToken: nativeText(row.metadata.claimToken), contactId: nativeText(state.contact_id), normalizedEmail: nativeEmail(state.normalized_email), eventType: state.event_kind,
+                        purpose: state.purpose, payload: payload, attemptCount: nativeInteger(row.attempts - 1, 0, 19),
+                        originProviderKind: state.origin_provider_kind, originProviderEventId: state.origin_provider_event_id, remoteProfileId: state.remote_profile_id, remoteListId: state.remote_list_id });
+                }
+                return events;
+            });
+        },
+        markSent(input) {
+            checkProvider(input.providerKind);
+            const summary = nativeJson(input.responseSummary ?? {}), remote = input.remoteProfileId == null ? null : nativeText(input.remoteProfileId);
+            return lane.run(async (db) => {
+                const row = (await db.query(`SELECT e.id FROM public.outbox_events e JOIN public.communication_native_sync_state s ON s.work_id=e.id
+          WHERE e.id=$1 AND s.binding=$2 AND s.provider_kind=$3 AND e.event_type=$4 AND e.status='processing' AND e.metadata->>'claimToken'=$5 FOR UPDATE OF e,s`, [input.eventId, binding, provider, eventType, input.claimToken])).rows[0];
+                if (!row)
+                    return false;
+                if (!(await options.rail(db).markProcessed({ eventId: input.eventId, claimToken: input.claimToken })).applied)
+                    throw new Error("native_sync_ack_lost");
+                await db.query("UPDATE public.communication_native_sync_state SET remote_profile_id=$2,response_summary=$3::jsonb WHERE work_id=$1", [input.eventId, remote, summary]);
+                return true;
+            });
+        },
+        markFailed(input) {
+            checkProvider(input.providerKind);
+            nativeInteger(input.backoffSeconds, 0, 86400);
+            return lane.run(async (db) => {
+                const row = (await db.query(`SELECT s.max_attempts FROM public.outbox_events e JOIN public.communication_native_sync_state s ON s.work_id=e.id
+          WHERE e.id=$1 AND s.binding=$2 AND s.provider_kind=$3 AND e.event_type=$4 AND e.status='processing' AND e.metadata->>'claimToken'=$5 FOR UPDATE OF e,s`, [input.eventId, binding, provider, eventType, input.claimToken])).rows[0];
+                if (!row)
+                    return false;
+                const result = await options.rail(db).markFailed({ eventId: input.eventId, claimToken: input.claimToken, error: nativeText(input.error, 2000), outcome: input.retry ? "retry" : "discard", baseDelaySeconds: input.backoffSeconds, maxDelaySeconds: input.backoffSeconds, maxAttempts: nativeInteger(Number(row.max_attempts), 1, 20), snoozeSeconds: 300 });
+                if (!["failed", "discarded"].includes(result.status))
+                    throw new Error("native_sync_ack_lost");
+                await db.query("UPDATE public.communication_native_sync_state SET response_summary=$2::jsonb WHERE work_id=$1", [input.eventId, JSON.stringify({ status: result.status })]);
+                return true;
+            });
+        },
+    };
+}

package/dist/communications/postgresConsentEvaluator.d.ts

@@ -0,0 +1,19 @@
+import type { PostgresDataGatewayEnv, PostgresDataGatewayOptions } from "../data/index.js";
+import type { CommunicationPurposeRegistry } from "./contracts/consent.js";
+import { type NativeConsentDecision, type NativeConsentInput } from "./nativeOperations.js";
+export interface NativeConsentOptions extends PostgresDataGatewayOptions {
+    registry?: CommunicationPurposeRegistry<string>;
+    /** Host-owned authoritative tester pause, read in the decision transaction. Missing means unpaused. */
+    testerPaused?: (db: import("../data/index.js").PgQueryExecutor, input: NativeConsentInput) => Promise<boolean>;
+}
+export interface NativeConsentEvaluator {
+    evaluate(input: NativeConsentInput): Promise<NativeConsentDecision>;
+    close(): Promise<void>;
+    readonly guarantees: {
+        readonly managedFrequencyCaps: false;
+        readonly legacyContactTouching: false;
+        readonly sendTimeFence: false;
+    };
+}
+/** Bounded P4 policy, authoritative native permission and durable decision. Evaluation never sends. */
+export declare function createPostgresConsentEvaluator(env: PostgresDataGatewayEnv, options?: NativeConsentOptions): NativeConsentEvaluator;