@openlup/platform 0.16.0 → 0.17.0

package/dist/communications/authSendEmailHook.js

@@ -0,0 +1,250 @@
+import { readEmailOriginConfiguration, resolveEmailOrigin } from "./originPolicy.js";
+import { buildAuthVerifyUrl } from "../identity/index.js";
+import { AuthEmailContentUnavailableError, } from "./authEmailPorts.js";
+import { guardAuthEmailTransport } from "./emailEgress.js";
+import { verifyStandardWebhookSignature } from "./standardWebhooks.js";
+const CORS_HEADERS = {
+    "access-control-allow-origin": "*",
+    "access-control-allow-headers": "authorization, x-client-info, apikey, content-type",
+};
+const KNOWN_ACTION_TYPES = new Set([
+    "magiclink", "signup", "recovery", "invite", "email_change",
+    "email_change_current", "email_change_new", "email",
+]);
+function json(res, status, body) {
+    for (const [key, value] of Object.entries(CORS_HEADERS))
+        res.setHeader(key, value);
+    res.status(status).json(body);
+}
+function hookError(res, httpCode, message) {
+    json(res, httpCode, { error: { http_code: httpCode, message } });
+}
+async function readRawBody(req) {
+    const chunks = [];
+    for await (const chunk of req)
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    return Buffer.concat(chunks).toString("utf8");
+}
+function resolveRedirectTarget(data, defaultRedirectTo) {
+    if (data?.redirect_to?.trim())
+        return { redirectTo: data.redirect_to, source: "redirect_to" };
+    if (data?.site_url?.trim())
+        return { redirectTo: data.site_url, source: "site_url" };
+    return { redirectTo: defaultRedirectTo ?? "", source: "default_redirect" };
+}
+/**
+ * An email carries no base URL, so a relative action link is not a degraded
+ * link - it is an unclickable one. The Edge runtime supplied this origin for
+ * free; a Node deployment must be configured with it, and one that is not must
+ * refuse rather than send mail whose only working path is the OTP fallback.
+ */
+function absoluteAuthServiceUrl(value) {
+    try {
+        const url = new URL(value);
+        return url.protocol === "https:" || url.protocol === "http:";
+    }
+    catch {
+        return false;
+    }
+}
+function uuidOrNull(value) {
+    return value && /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value)
+        ? value
+        : null;
+}
+function deliveryMode(result, env, recipient, defaultSandboxRecipient) {
+    // Preserve the existing Auth-hook audit vocabulary even though the Node
+    // transport's lower-level egress seam uses a richer set of route names.
+    if (result.outcome.egressMode === "production")
+        return "standard";
+    if ((env.EMAIL_DELIVERY_PROFILE ?? "").trim().toLowerCase() !== "production_like")
+        return "standard";
+    const sandboxRecipients = parseEmailList(env.EMAIL_SANDBOX_RECIPIENTS ?? env.COMMS_SANDBOX_SINK_ADDRESS ?? defaultSandboxRecipient);
+    return result.outcome.egressMode === "sandbox_sink"
+        || (result.outcome.adminDisabled === true && sandboxRecipients.has(recipient.trim().toLowerCase()))
+        ? "sandbox_recipient"
+        : "production_like_real";
+}
+function parseEmailList(value) {
+    return new Set((value ?? "")
+        .split(/[,\s;]+/)
+        .map((item) => item.trim().toLowerCase())
+        .filter(Boolean));
+}
+function selectFromEmail(deps, recipient) {
+    const env = deps.env;
+    if ((env.EMAIL_DELIVERY_PROFILE ?? "").trim().toLowerCase() !== "production_like")
+        return deps.fromEmail;
+    const sandboxRecipients = parseEmailList(env.EMAIL_SANDBOX_RECIPIENTS ?? env.COMMS_SANDBOX_SINK_ADDRESS ?? deps.defaultSandboxRecipient);
+    if (sandboxRecipients.has(recipient.trim().toLowerCase()))
+        return deps.fromEmail;
+    return env.EMAIL_REAL_DELIVERY_FROM_EMAIL?.trim()
+        || env.AUTH_EMAIL_REAL_DELIVERY_FROM_EMAIL?.trim()
+        || deps.fromEmail;
+}
+function validateAuthEmailRedirectOrigin(deps, redirectTo, host) {
+    const env = deps.env;
+    const originConfiguration = readEmailOriginConfiguration(env, {
+        defaultOrigin: deps.defaultOrigin,
+        productionEmailHosts: deps.productionEmailHosts,
+    });
+    const environment = env.EMAIL_ENVIRONMENT ?? host.readObservedEnvironment(env);
+    const configured = resolveEmailOrigin({
+        ...originConfiguration,
+        explicitBaseUrl: env.APP_BASE_URL?.trim() || deps.legacyBaseUrl,
+        customerAuthRedirectOrigin: env.CUSTOMER_AUTH_REDIRECT_ORIGIN,
+        siteUrl: env.SITE_URL,
+        hiddenPreviewEnabled: host.readHiddenPreviewEnabled(env),
+        environment,
+    });
+    if (configured.ok === false)
+        return { ok: false, error: configured.error };
+    const redirect = resolveEmailOrigin({
+        ...originConfiguration,
+        explicitBaseUrl: redirectTo,
+        hiddenPreviewEnabled: host.readHiddenPreviewEnabled(env),
+        environment,
+    });
+    if (redirect.ok === false)
+        return { ok: false, error: redirect.error };
+    return {
+        ok: true,
+        environment: configured.resolved.environment,
+        origin: redirect.origin,
+        production: configured.resolved.production,
+    };
+}
+function persistenceOutcome(result) {
+    return {
+        ok: result.outcome.ok,
+        messageId: result.outcome.messageId,
+        providerError: result.outcome.providerError,
+        aborted: result.outcome.aborted,
+        skipReason: result.outcome.adminDisabled === true
+            ? "admin_disabled"
+            : result.outcome.suppressed === "drop" ? "egress_suppressed" : null,
+    };
+}
+export function createAuthSendEmailHookCandidate(deps, host) {
+    return async function authSendEmailHookCandidate(req, res) {
+        if (req.method === "OPTIONS") {
+            for (const [key, value] of Object.entries(CORS_HEADERS))
+                res.setHeader(key, value);
+            res.status(200).send("ok");
+            return;
+        }
+        if (req.method !== "POST")
+            return hookError(res, 405, "Method not allowed");
+        if (!deps.hookSecret) {
+            console.error("[auth-send-email] SEND_EMAIL_HOOK_SECRET not configured");
+            return hookError(res, 500, "Hook secret not configured");
+        }
+        if (!absoluteAuthServiceUrl(deps.authServiceUrl)) {
+            console.error("[auth-send-email] auth service URL not configured");
+            return hookError(res, 500, "Auth service URL not configured");
+        }
+        let rawBody;
+        try {
+            rawBody = await readRawBody(req);
+        }
+        catch {
+            return hookError(res, 400, "Invalid JSON payload");
+        }
+        const valid = await verifyStandardWebhookSignature({
+            headers: {
+                id: typeof req.headers["webhook-id"] === "string" ? req.headers["webhook-id"] : null,
+                timestamp: typeof req.headers["webhook-timestamp"] === "string" ? req.headers["webhook-timestamp"] : null,
+                signature: typeof req.headers["webhook-signature"] === "string" ? req.headers["webhook-signature"] : null,
+            },
+            rawBody,
+            secret: deps.hookSecret,
+            now: deps.now,
+        });
+        if (!valid)
+            return hookError(res, 401, "Invalid signature");
+        let payload;
+        try {
+            payload = JSON.parse(rawBody);
+        }
+        catch {
+            return hookError(res, 400, "Invalid JSON payload");
+        }
+        const email = payload.user?.email;
+        const data = payload.email_data;
+        const actionType = data?.email_action_type;
+        const tokenHash = data?.token_hash;
+        const redirect = resolveRedirectTarget(data, deps.defaultRedirectTo);
+        if (!email || !actionType || !tokenHash)
+            return hookError(res, 400, "Missing user email or email_data");
+        const redirectPolicy = validateAuthEmailRedirectOrigin(deps, redirect.redirectTo, host);
+        if (redirectPolicy.ok === false)
+            return hookError(res, 500, `Email origin policy failed: ${redirectPolicy.error}`);
+        if (!KNOWN_ACTION_TYPES.has(actionType))
+            console.warn("[auth-send-email] unknown email_action_type:", actionType);
+        let content;
+        try {
+            content = deps.content.buildAuthEmailContent({
+                actionType, userMetadata: payload.user?.user_metadata, redirectTo: redirect.redirectTo,
+                actionLink: buildAuthVerifyUrl(deps.authServiceUrl, actionType, tokenHash, redirect.redirectTo),
+                otp: data?.token ?? null,
+            });
+        }
+        catch (error) {
+            if (error instanceof AuthEmailContentUnavailableError)
+                return hookError(res, 503, error.message);
+            throw error;
+        }
+        const rendered = host.renderEmail({
+            brand: deps.emailBrandForOrigin(redirectPolicy.origin), locale: content.locale,
+            subject: content.subject, preheader: content.preheader, blocks: content.blocks,
+        });
+        const sendAttemptId = crypto.randomUUID();
+        const authUserId = uuidOrNull(payload.user?.id);
+        const aggregateId = authUserId ?? crypto.randomUUID();
+        // Match the hosted hook's ordering: persistence/control failure is a
+        // retryable refusal before any email side effect, never a post-send false 5xx.
+        const templateSlug = `auth-${actionType}`;
+        const enabled = await deps.persistence.isTemplateEnabled(templateSlug, new AbortController().signal);
+        const sendResult = enabled
+            ? await guardAuthEmailTransport(deps.transport).send({
+                sender: selectFromEmail(deps, email), recipient: email,
+                subject: rendered.subject, html: rendered.html, text: rendered.text,
+            })
+            : {
+                outcome: { ok: true, messageId: null, providerError: null, aborted: false, adminDisabled: true },
+                providerResponse: { skipped: "admin_disabled" },
+            };
+        const mode = deliveryMode(sendResult, deps.env, email, deps.defaultSandboxRecipient);
+        const originMetadata = {
+            emailBaseUrl: redirectPolicy.origin,
+            emailOriginSource: redirect.source,
+            emailEnvironment: redirectPolicy.environment,
+        };
+        await deps.persistence.recordSend({
+            templateSlug,
+            recipientEmail: email,
+            authUserId,
+            aggregateId,
+            dedupeKey: `auth-send-email:${actionType}:${sendAttemptId}`,
+            providerKind: deps.transport.providerKind,
+            outcome: persistenceOutcome(sendResult),
+            providerResponse: sendResult.providerResponse,
+            metadata: {
+                ...originMetadata,
+                authEmailDeliveryMode: mode,
+                deliveryMode: mode,
+                triggerSource: "auth-send-email",
+                triggerReason: actionType,
+                providerKind: deps.transport.providerKind,
+                sendAttemptId,
+                aggregateType: "auth_user",
+                aggregateId,
+            },
+        });
+        if (!sendResult.outcome.ok) {
+            console.error("[auth-send-email] transport send failed:", sendResult.outcome.providerError);
+            return hookError(res, 502, "Email delivery failed");
+        }
+        json(res, 200, {});
+    };
+}

package/dist/communications/capturedTransactionalDelivery.d.ts

@@ -0,0 +1,13 @@
+import type { CapturedTransactionalDeliveryPort, TransactionalDeliveryCommand } from "./contracts/transactionalDelivery.js";
+export type CapturedTransactionalDeliveryOutcome = {
+    readonly state: "accepted";
+    readonly deliveryReference?: string;
+} | {
+    readonly state: "failed";
+};
+/** Injected only by tests and the parity proof to demonstrate durable recovery. */
+export type CapturedTransactionalDeliveryOutcomeSource = (command: TransactionalDeliveryCommand) => Promise<CapturedTransactionalDeliveryOutcome> | CapturedTransactionalDeliveryOutcome;
+/** Deterministic no-egress delivery adapter for the portable direct action. */
+export declare function createCapturedTransactionalDelivery(options?: {
+    outcome?: CapturedTransactionalDeliveryOutcomeSource;
+}): CapturedTransactionalDeliveryPort;

package/dist/communications/capturedTransactionalDelivery.js

@@ -0,0 +1,14 @@
+/** Deterministic no-egress delivery adapter for the portable direct action. */
+export function createCapturedTransactionalDelivery(options = {}) {
+    return {
+        async deliver(command) {
+            const outcome = await (options.outcome?.(command) ?? { state: "accepted" });
+            if (outcome.state === "failed")
+                throw new Error("captured_delivery_failed");
+            const deliveryReference = outcome.deliveryReference
+                ?? `captured:${createHash("sha256").update(command.idempotencyKey).digest("hex")}`;
+            return { deliveryReference };
+        },
+    };
+}
+import { createHash } from "node:crypto";

package/dist/communications/communicationSync.d.ts

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

package/dist/communications/communicationSync.js

@@ -0,0 +1,79 @@
+function rpcFailure(rpcName, error) {
+    return new Error(`${rpcName}_failed: ${error.message ?? error.code ?? "unknown"}`);
+}
+export function createSupabaseCommunicationSyncStore(client) {
+    return {
+        async claimBatch(input) {
+            const { data, error } = await client.rpc("communication_claim_sync_outbox", {
+                p_provider_kind: input.providerKind,
+                p_batch_size: input.batchSize,
+                p_visibility_seconds: input.visibilitySeconds,
+                p_max_attempts: input.maxAttempts,
+            });
+            if (error)
+                throw rpcFailure("communication_claim_sync_outbox", error);
+            return Array.isArray(data) ? data.map(mapClaimedEvent).filter(isEvent) : [];
+        },
+        async markSent(input) {
+            const { data, error } = await client.rpc("communication_mark_sync_outbox_sent", {
+                p_outbox_id: input.eventId,
+                p_claim_token: input.claimToken,
+                p_provider_kind: input.providerKind,
+                p_remote_profile_id: input.remoteProfileId ?? null,
+                p_response_summary: input.responseSummary ?? {},
+            });
+            if (error)
+                throw rpcFailure("communication_mark_sync_outbox_sent", error);
+            return data === true;
+        },
+        async markFailed(input) {
+            const { data, error } = await client.rpc("communication_mark_sync_outbox_failed", {
+                p_outbox_id: input.eventId,
+                p_claim_token: input.claimToken,
+                p_provider_kind: input.providerKind,
+                p_error: input.error,
+                p_retry: input.retry,
+                p_backoff_seconds: input.backoffSeconds,
+            });
+            if (error)
+                throw rpcFailure("communication_mark_sync_outbox_failed", error);
+            return data === true;
+        },
+    };
+}
+function mapClaimedEvent(row) {
+    if (!row || typeof row !== "object" || Array.isArray(row))
+        return null;
+    const record = row;
+    if (typeof record.id !== "string" ||
+        typeof record.claim_token !== "string" ||
+        typeof record.contact_id !== "string" ||
+        typeof record.normalized_email !== "string" ||
+        typeof record.event_type !== "string" ||
+        typeof record.purpose !== "string") {
+        return null;
+    }
+    return {
+        id: record.id,
+        claimToken: record.claim_token,
+        contactId: record.contact_id,
+        normalizedEmail: record.normalized_email,
+        eventType: record.event_type,
+        purpose: record.purpose,
+        payload: isRecord(record.payload) ? record.payload : {},
+        attemptCount: typeof record.attempt_count === "number" ? record.attempt_count : 0,
+        originProviderKind: readNullableString(record.origin_provider_kind),
+        originProviderEventId: readNullableString(record.origin_provider_event_id),
+        remoteProfileId: readNullableString(record.remote_profile_id),
+        remoteListId: readNullableString(record.remote_list_id),
+    };
+}
+function isEvent(event) {
+    return Boolean(event);
+}
+function isRecord(value) {
+    return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+function readNullableString(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : null;
+}

package/dist/communications/communicationSyncWorker.d.ts

@@ -0,0 +1,68 @@
+import type { CommunicationPurposeRegistry } from "./contracts/consent.js";
+import type { NewsletterMarketingPurpose } from "./contracts/newsletter.js";
+import type { NewsletterSyncEvent, NewsletterSyncProviderPort } from "./contracts/newsletter.js";
+export interface CommunicationSyncStore<Purpose extends string = NewsletterMarketingPurpose> {
+    claimBatch(input: {
+        providerKind: string;
+        batchSize: number;
+        visibilitySeconds: number;
+        maxAttempts: number;
+    }): Promise<NewsletterSyncEvent<Purpose>[]>;
+    markSent(input: {
+        eventId: string;
+        claimToken: string;
+        providerKind: string;
+        remoteProfileId?: string | null;
+        responseSummary?: Record<string, unknown>;
+    }): Promise<boolean>;
+    markFailed(input: {
+        eventId: string;
+        claimToken: string;
+        providerKind: string;
+        error: string;
+        retry: boolean;
+        backoffSeconds: number;
+    }): Promise<boolean>;
+}
+export interface CommunicationSyncConfig {
+    batchSize: number;
+    maxAttempts: number;
+    visibilitySeconds: number;
+    backoffSeconds: number;
+}
+export interface CommunicationSyncRunResult {
+    ok: boolean;
+    checked: number;
+    updated: number;
+    failures: number;
+    skipped: boolean;
+    reason?: string;
+    providerKind: string;
+    sent: number;
+    retried: number;
+    skippedEvents: number;
+}
+export declare const DEFAULT_COMMUNICATION_SYNC_CONFIG: CommunicationSyncConfig;
+export declare function runCommunicationSyncDispatch<Purpose extends string = NewsletterMarketingPurpose>(input: {
+    store: CommunicationSyncStore<Purpose>;
+    provider: NewsletterSyncProviderPort<Purpose>;
+    config?: Partial<CommunicationSyncConfig>;
+    registry?: CommunicationPurposeRegistry<Purpose>;
+}): Promise<CommunicationSyncRunResult>;
+export declare function runCommunicationSyncDispatchForProviders<Purpose extends string = NewsletterMarketingPurpose>(input: {
+    store: CommunicationSyncStore<Purpose>;
+    providers: NewsletterSyncProviderPort<Purpose>[];
+    config?: Partial<CommunicationSyncConfig>;
+    registry?: CommunicationPurposeRegistry<Purpose>;
+}): Promise<CommunicationSyncRunResult>;
+export interface CommunicationReconcileRunResult {
+    ok: boolean;
+    checked: number;
+    updated: number;
+    failures: number;
+    skipped: boolean;
+    reason?: string;
+}
+export declare function runCommunicationSyncReconcile(input?: {
+    providers?: NewsletterSyncProviderPort[];
+}): Promise<CommunicationReconcileRunResult>;

package/dist/communications/communicationSyncWorker.js

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

package/dist/communications/consentPolicy.d.ts

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