@openlup/platform 0.15.0 → 0.17.0

package/src/communications/emailHealthAssessment.ts

@@ -0,0 +1,106 @@
+import type { EmailHealthMetrics } from "./emailHealthMetricsPort.js";
+
+/**
+ * Pure email-health assessment layer: env-derived thresholds plus the
+ * healthy/unhealthy verdict over the delivery metrics. Extracted from
+ * `api/_cron/emailHealthWatchdogJob.ts` (which sat at the 300-LOC source cap)
+ * so the incident-driven `permanent_delivery_failure` breach could land here
+ * with unit coverage and no database in the loop.
+ */
+
+type Env = Record<string, string | undefined>;
+
+export interface EmailHealthThresholds {
+  windowMinutes: number;
+  stuckMinutes: number;
+  minAttemptsForRatio: number;
+  maxFailureRatio: number;
+  maxStuck: number;
+  /**
+   * Absolute ceiling on in-window deliveries that ended `status='failed'`
+   * (handler-final loss of a customer notification: outbox discard,
+   * max-attempts exhaustion). Default 0 — a single lost email breaches.
+   * Bounces/complaints are separate statuses and stay ratio-only.
+   */
+  maxPermanentFailures: number;
+}
+
+export interface EmailHealthBreach {
+  code: string;
+  detail: string;
+}
+
+export interface EmailHealthAssessment {
+  healthy: boolean;
+  failureRatio: number;
+  breaches: EmailHealthBreach[];
+}
+
+export function readEmailHealthThresholds(env: Env): EmailHealthThresholds {
+  return {
+    windowMinutes: positiveInt(env.EMAIL_HEALTH_WINDOW_MINUTES, 60),
+    stuckMinutes: positiveInt(env.EMAIL_HEALTH_STUCK_MINUTES, 30),
+    minAttemptsForRatio: positiveInt(env.EMAIL_HEALTH_MIN_ATTEMPTS_FOR_RATIO, 5),
+    maxFailureRatio: clampRatio(env.EMAIL_HEALTH_MAX_FAILURE_RATIO, 0.5),
+    maxStuck: nonNegativeInt(env.EMAIL_HEALTH_MAX_STUCK, 0),
+    maxPermanentFailures: nonNegativeInt(env.EMAIL_HEALTH_MAX_PERMANENT_FAILURES, 0),
+  };
+}
+
+/**
+ * Pure decision: turn raw counts into a healthy/unhealthy verdict. Kept side
+ * effect-free so the thresholds logic is unit-tested without a database.
+ */
+export function evaluateEmailHealth(
+  metrics: EmailHealthMetrics,
+  thresholds: EmailHealthThresholds,
+): EmailHealthAssessment {
+  const failureRatio = metrics.attempted > 0 ? metrics.failed / metrics.attempted : 0;
+  const breaches: EmailHealthBreach[] = [];
+
+  if (metrics.attempted >= thresholds.minAttemptsForRatio && failureRatio > thresholds.maxFailureRatio) {
+    breaches.push({
+      code: "failure_ratio",
+      detail: `${metrics.failed}/${metrics.attempted} (${(failureRatio * 100).toFixed(1)}%) > ${(thresholds.maxFailureRatio * 100).toFixed(1)}%`,
+    });
+  }
+  // Absolute, ratio-independent: one terminally-failed delivery is one
+  // customer notification we finally did not send. Incident 2026-07-24: a
+  // single discarded payment-recovery email stayed invisible because the
+  // ratio breach needs minAttemptsForRatio sends in the window.
+  if (metrics.permanentFailures > thresholds.maxPermanentFailures) {
+    breaches.push({
+      code: "permanent_delivery_failure",
+      detail: `${metrics.permanentFailures} delivery(ies) terminally failed > ${thresholds.maxPermanentFailures}`,
+    });
+  }
+  if (metrics.stuckProcessing > thresholds.maxStuck) {
+    breaches.push({
+      code: "stuck_processing",
+      detail: `${metrics.stuckProcessing} email(s) stuck in 'processing' > ${thresholds.stuckMinutes}m`,
+    });
+  }
+  if (metrics.stuckScheduled > thresholds.maxStuck) {
+    breaches.push({
+      code: "stuck_scheduled",
+      detail: `${metrics.stuckScheduled} scheduled email(s) overdue and undispatched`,
+    });
+  }
+
+  return { healthy: breaches.length === 0, failureRatio, breaches };
+}
+
+function positiveInt(raw: string | undefined, fallback: number): number {
+  const n = Number(raw);
+  return Number.isFinite(n) && n > 0 ? Math.floor(n) : fallback;
+}
+
+function nonNegativeInt(raw: string | undefined, fallback: number): number {
+  const n = Number(raw);
+  return Number.isFinite(n) && n >= 0 ? Math.floor(n) : fallback;
+}
+
+function clampRatio(raw: string | undefined, fallback: number): number {
+  const n = Number(raw);
+  return Number.isFinite(n) && n >= 0 && n <= 1 ? n : fallback;
+}

package/src/communications/emailHealthMetricsPort.ts

@@ -0,0 +1,17 @@
+export interface EmailHealthMetrics {
+  attempted: number;
+  sent: number;
+  failed: number;
+  delayed: number;
+  /**
+   * In-window rows that ended `status='failed'` — handler-final loss of a
+   * customer notification (outbox discard / max-attempts). Distinct from
+   * `failed` above, which also counts bounces/complaints/missed for the
+   * ratio signal.
+   */
+  permanentFailures: number;
+  /** `processing` rows whose last transition is older than the stuck threshold. */
+  stuckProcessing: number;
+  /** `planned`/`queued` rows past their `expected_send_at` but still not sent. */
+  stuckScheduled: number;
+}

package/src/communications/emailNotificationControl.ts

@@ -0,0 +1,28 @@
+export interface EmailNotificationControlPort {
+  isEnabled(slug: string, signal: AbortSignal): Promise<boolean>;
+}
+
+export interface EmailNotificationControlClient {
+  from(table: string): EmailNotificationControlQueryBuilder;
+}
+
+interface EmailNotificationControlQueryBuilder {
+  select(columns: string): EmailNotificationControlQueryBuilder;
+  eq(column: string, value: unknown): EmailNotificationControlQueryBuilder;
+  maybeSingle(): PromiseLike<{ data: unknown; error: { code?: string; message?: string } | null }>;
+}
+
+export function createEmailNotificationControlPort(
+  client: EmailNotificationControlClient,
+  createPolicy: (client: EmailNotificationControlClient) => { shouldDeliver(input: { slug: string; signal: AbortSignal }): Promise<{ allow: boolean }> },
+): EmailNotificationControlPort {
+  const policy = createPolicy(client);
+  return {
+    isEnabled(slug: string, signal: AbortSignal): Promise<boolean> {
+      return policy.shouldDeliver({ slug, signal }).then((decision) => decision.allow);
+    },
+  };
+}
+
+// Compatibility alias for the pre-neutralization lifecycle consumer.
+export const createSupabaseEmailNotificationControlPort = createEmailNotificationControlPort;

package/src/communications/emailObservation.ts

@@ -0,0 +1,43 @@
+/** An authenticated, decoded, environment-admitted observation. Evidence is opaque. */
+export interface EmailObservation {
+  eventType: string;
+  eventAt: string;
+  metadata: Record<string, unknown>;
+}
+
+export interface EmailObservationPort {
+  findSend(messageId: string): Promise<{ id: string } | null>;
+  applyObservation(observation: EmailObservation & { sendId: string; messageId: string }): Promise<void>;
+  recordAttempt(attempt: EmailObservationDisposition): Promise<void>;
+}
+
+export type EmailObservationDisposition =
+  | { outcome: "send_not_found" }
+  | { outcome: "processed"; sendId: string };
+
+/** Lookup/apply failures propagate; attempt telemetry cannot overturn authoritative success. */
+export async function processEmailObservation(input: {
+  port: EmailObservationPort;
+  messageId: string;
+  // Construct evidence only after a local send is found (including clock reads).
+  observation: () => EmailObservation;
+}): Promise<EmailObservationDisposition> {
+  const send = await input.port.findSend(input.messageId);
+  let disposition: EmailObservationDisposition;
+  if (!send) {
+    disposition = { outcome: "send_not_found" };
+  } else {
+    await input.port.applyObservation({
+      sendId: send.id,
+      messageId: input.messageId,
+      ...input.observation(),
+    });
+    disposition = { outcome: "processed", sendId: send.id };
+  }
+  try {
+    await input.port.recordAttempt(disposition);
+  } catch {
+    // Best-effort telemetry is separate from durable convergence.
+  }
+  return disposition;
+}

package/src/communications/emailTransport.ts

@@ -0,0 +1,167 @@
+import { admitPolicyEnforcedEmailTransport } from "./emailEgress.js";
+/** Provider-agnostic transport contract, outcome projection and capture transport. */
+export interface EmailMessage {
+  from: string;
+  to: string;
+  subject: string;
+  html: string;
+  /** Optional plain-text alternative; omitted from the outbound payload when absent. */
+  text?: string;
+  /** Optional reply mailbox; omitted entirely when the caller does not set it. */
+  replyTo?: string;
+  /** Stable outbound request key retained by the concrete transport for a limited window. */
+  idempotencyKey?: string;
+  /** Base64 content only; remote URLs and filesystem paths are not supported. */
+  attachments?: ReadonlyArray<{ filename: string; content: string }>;
+  /** Cancels the in-flight send when the worker's per-row timeout fires. */
+  signal?: AbortSignal;
+}
+
+/** Transport results preserve existing reference wire shapes. */
+export interface EmailSendOutcome {
+  ok: boolean;
+  /** Legacy identifier retained for reference result compatibility. */
+  resendId: string | null;
+  httpStatus: number;
+  providerError: string | null;
+  providerErrorCode?: string | null;
+  aborted: boolean;
+  suppressed?: "drop" | null;
+  egressMode?: "production" | "sandbox_direct" | "sandbox_sink" | "drop";
+  egressReason?: string;
+}
+export interface EmailSendResult {
+  outcome: EmailSendOutcome;
+  providerResponse: Record<string, unknown>;
+}
+
+export type EmailSendSkipReason = "admin_disabled" | "egress_suppressed";
+
+export interface EmailSendOutcomeLike {
+  ok: boolean;
+  resendId: string | null;
+  providerError: string | null;
+  aborted?: boolean;
+  adminDisabled?: boolean;
+  suppressed?: "drop" | null;
+  skipReason?: EmailSendSkipReason | null;
+}
+
+/** Converts the transport's legacy identifier field at the transport boundary. */
+export function emailTransportMessageId(outcome: EmailSendOutcomeLike): string | null {
+  return outcome.resendId;
+}
+
+/** Maps the neutral message identifier onto the deployed ledger's legacy field. */
+export function emailTransportLedgerIdentifier(messageId: string | null): Record<string, string | null> {
+  return { resend_id: messageId };
+}
+
+/** Synthesizes the canonical terminal transport shape when `send` throws. */
+export function failedEmailTransportResult(): EmailSendResult {
+  return {
+    outcome: { ok: false, resendId: null, httpStatus: 0, providerError: "provider_transport_threw", aborted: false },
+    providerResponse: { exception: true },
+  };
+}
+
+export interface EmailSendOutcomeProjection {
+  skipReason: EmailSendSkipReason | null;
+  timelineStatus: "sent" | "skipped" | "delivery_delayed" | "failed";
+  ledgerStatus: "sent" | "skipped" | "failed";
+  sentAtEligible: boolean;
+  lastErrorCode: string | null;
+}
+
+/** One truth projection for every Node email ledger, timeline and caller. */
+export function classifyEmailSendOutcome(outcome: EmailSendOutcomeLike): EmailSendOutcomeProjection {
+  const skipReason = outcome.skipReason
+    ?? (outcome.adminDisabled ? "admin_disabled" : null)
+    ?? (outcome.suppressed === "drop" ? "egress_suppressed" : null);
+  if (skipReason) {
+    return {
+      skipReason,
+      timelineStatus: "skipped",
+      ledgerStatus: "skipped",
+      sentAtEligible: false,
+      lastErrorCode: skipReason,
+    };
+  }
+  // `ok` deliberately remains the transport-acceptance contract. In particular,
+  // this wave does not turn a historical 2xx-without-id answer into a retry.
+  if (outcome.ok) {
+    return {
+      skipReason: null,
+      timelineStatus: "sent",
+      ledgerStatus: "sent",
+      sentAtEligible: true,
+      lastErrorCode: null,
+    };
+  }
+  if (outcome.aborted) {
+    return {
+      skipReason: null,
+      timelineStatus: "delivery_delayed",
+      ledgerStatus: "failed",
+      sentAtEligible: false,
+      lastErrorCode: "provider_request_aborted",
+    };
+  }
+  return {
+    skipReason: null,
+    timelineStatus: "failed",
+    ledgerStatus: "failed",
+    sentAtEligible: false,
+    lastErrorCode: normalizeEmailFailureCode(outcome.providerError),
+  };
+}
+
+/** Adds a provider-neutral skip reason without changing ordinary wire shapes. */
+export function withEmailSendSkipReason<T extends EmailSendOutcomeLike>(outcome: T): T {
+  const skipReason = classifyEmailSendOutcome(outcome).skipReason;
+  return skipReason ? { ...outcome, skipReason } : outcome;
+}
+
+function normalizeEmailFailureCode(value: string | null): string {
+  if (!value) return "provider_send_failed";
+  const normalized = value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "_")
+    .replace(/^_+|_+$/g, "")
+    .slice(0, 80);
+  return normalized || "provider_send_failed";
+}
+
+export interface EmailTransport {
+  /** Stable provider tag for ledgers/observability (e.g. "mailProvider", "in-memory"). */
+  readonly providerKind: string;
+  send(message: EmailMessage): Promise<EmailSendResult>;
+}
+
+export interface InMemoryEmailTransport extends EmailTransport {
+  /** Every message handed to send(), in order — for tests and dry runs. */
+  readonly sent: ReadonlyArray<EmailMessage>;
+}
+
+/**
+ * Reference capture transport: captures sends in memory and never makes a
+ * network call. Proves the seam is real — a port wired to this sends email with
+ * no HTTP client — and doubles as the substitute an OSS fork starts from
+ * before writing its own SES/SMTP adapter.
+ */
+export function createInMemoryEmailTransport(opts?: { idPrefix?: string }): InMemoryEmailTransport {
+  const sent: EmailMessage[] = [];
+  const prefix = opts?.idPrefix ?? "in-memory";
+  return admitPolicyEnforcedEmailTransport({
+    providerKind: "in-memory",
+    sent,
+    async send(message) {
+      sent.push(message);
+      const id = `${prefix}-${sent.length}`;
+      return {
+        outcome: { ok: true, resendId: id, httpStatus: 200, providerError: null, aborted: false },
+        providerResponse: { id },
+      };
+    },
+  });
+}

package/src/communications/errors.ts

@@ -0,0 +1,34 @@
+export class CommunicationRecipientNotFoundError extends Error {
+  constructor(message = "Communication recipient not found") {
+    super(message);
+    this.name = "CommunicationRecipientNotFoundError";
+  }
+}
+
+export class CommunicationTemplateNotFoundError extends Error {
+  constructor(message = "Communication template not found") {
+    super(message);
+    this.name = "CommunicationTemplateNotFoundError";
+  }
+}
+
+export class CommunicationConflictError extends Error {
+  constructor(message = "Communication request conflicts with current state") {
+    super(message);
+    this.name = "CommunicationConflictError";
+  }
+}
+
+export class CommunicationValidationError extends Error {
+  constructor(message = "Communication request is invalid") {
+    super(message);
+    this.name = "CommunicationValidationError";
+  }
+}
+
+export class CommunicationUnavailableError extends Error {
+  constructor(message = "Communication capability is unavailable") {
+    super(message);
+    this.name = "CommunicationUnavailableError";
+  }
+}

package/src/communications/index.ts

@@ -0,0 +1,46 @@
+export * from "./accountingDocumentDelivery.js";
+export * from "./authEmailError.js";
+export * from "./authSendEmailHook.js";
+export * from "./capturedTransactionalDelivery.js";
+export * from "./communicationSync.js";
+export * from "./communicationSyncWorker.js";
+export * from "./consentPolicy.js";
+export * from "./deliveryReconciliation.js";
+export * from "./contribution.js";
+export * from "./emailHealthAssessment.js";
+export * from "./emailHealthMetricsPort.js";
+export * from "./emailNotificationControl.js";
+export * from "./emailObservation.js";
+export * from "./emailTransport.js";
+export * from "./emailEgress.js";
+export * from "./errors.js";
+export * from "./integrationEventSignature.js";
+export * from "./managedTransactionalDeliveryStore.js";
+export * from "./newsletterIntegrationContracts.js";
+export * from "./newsletterWebhookPort.js";
+export * from "./originPolicy.js";
+export * from "./postgresTransactionalDeliveryStore.js";
+export * from "./preferencesToken.js";
+export * from "./publicPreferenceToken.js";
+export * from "./shipmentNotifications.js";
+export * from "./sql.js";
+export * from "./standardWebhooks.js";
+export * from "./status.js";
+export * from "./transactionalDelivery.js";
+export * from "./transactionalDeliveryIdentifier.js";
+export * from "./unsubscribeToken.js";
+export type * from "./contracts/authEmail.js";
+export type * from "./contracts/email.js";
+export type * from "./contracts/publicIntake.js";
+export type * from "./contracts/transactionalDelivery.js";
+export type * from "./contracts/newsletterWebhook.js";
+export type { NewsletterSyncProviderPort, NewsletterSyncOutcome, NewsletterSyncReconcileOutcome } from "./contracts/newsletter.js";
+export * from "./consentPurposeRegistry.js";
+export type * from "./contracts/consent.js";
+export type * from "./contracts/marketingAutomation.js";
+export * from "./newsletterWebhookProcessing.js";
+export * from "./nativeOperations.js";
+export * from "./postgresDeliveryReconciliation.js";
+export * from "./postgresCommunicationSync.js";
+export * from "./postgresNotificationRecipients.js";
+export * from "./postgresConsentEvaluator.js";

package/src/communications/integrationEventSignature.ts

@@ -0,0 +1,49 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+export const COMMUNICATION_INTEGRATION_SIGNATURE_TOLERANCE_SECONDS = 300;
+export const COMMUNICATION_INTEGRATION_SIGNATURE_HEADER = "x-openlup-communications-signature";
+export const COMMUNICATION_INTEGRATION_TIMESTAMP_HEADER = "x-openlup-communications-timestamp";
+
+export function verifyCommunicationIntegrationEventSignature(input: {
+  rawBody: string;
+  signatureHeader: string | undefined;
+  timestampHeader: string | undefined;
+  secret: string;
+  now?: () => number;
+}): boolean {
+  if (!input.secret || !input.signatureHeader || !input.timestampHeader) return false;
+  const timestamp = Number(input.timestampHeader);
+  if (!Number.isFinite(timestamp)) return false;
+  const now = input.now ?? (() => Math.floor(Date.now() / 1000));
+  const age = now() - timestamp;
+  if (age > COMMUNICATION_INTEGRATION_SIGNATURE_TOLERANCE_SECONDS) return false;
+  if (age < -COMMUNICATION_INTEGRATION_SIGNATURE_TOLERANCE_SECONDS) return false;
+
+  const signature = normalizeSignature(input.signatureHeader);
+  const expected = signCommunicationIntegrationEvent({
+    rawBody: input.rawBody,
+    timestamp,
+    secret: input.secret,
+  });
+  return safeEqual(signature, expected);
+}
+
+export function signCommunicationIntegrationEvent(input: {
+  rawBody: string;
+  timestamp: number;
+  secret: string;
+}): string {
+  return createHmac("sha256", input.secret)
+    .update(`${input.timestamp}.${input.rawBody}`)
+    .digest("hex");
+}
+
+function normalizeSignature(value: string): string {
+  return value.trim().replace(/^sha256=/i, "");
+}
+
+function safeEqual(left: string, right: string): boolean {
+  const leftBuffer = Buffer.from(left);
+  const rightBuffer = Buffer.from(right);
+  return leftBuffer.length === rightBuffer.length && timingSafeEqual(leftBuffer, rightBuffer);
+}

package/src/communications/managedTransactionalDeliveryStore.ts

@@ -0,0 +1,59 @@
+import type { TransactionalDeliveryReceipt, TransactionalDeliveryReceiptStore } from "./contracts/transactionalDelivery.js";
+export interface ManagedTransactionalDeliveryStoreClient {
+  rpc(
+    functionName: string,
+    args: Record<string, unknown>,
+  ): PromiseLike<{ data: unknown; error: { code?: string; message?: string } | null }>;
+}
+
+function failure(name: string, error: { code?: string; message?: string }): Error & { code?: string } {
+  const result = new Error(`${name}_failed: ${error.message ?? error.code ?? "unknown"}`) as Error & { code?: string };
+  result.code = error.code;
+  return result;
+}
+
+function receipt(data: unknown): TransactionalDeliveryReceipt {
+  const value = (Array.isArray(data) ? data[0] : data) as Record<string, unknown> | undefined;
+  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: ManagedTransactionalDeliveryStoreClient,
+): TransactionalDeliveryReceiptStore {
+  const call = async (name: string, args: Record<string, unknown>): Promise<TransactionalDeliveryReceipt> => {
+    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/src/communications/nativeOperations.ts

@@ -0,0 +1,40 @@
+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 class NativeConsentEvaluationUnavailableError extends Error {
+  constructor(cause: unknown) { super("native_consent_evaluation_unavailable", { cause }); this.name = "ConsentEvaluationUnavailableError"; }
+}