@openlup/platform 0.16.0 → 0.18.0

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"; }
+}

package/src/communications/newsletterIntegrationContracts.ts

@@ -0,0 +1,154 @@
+import type { CommunicationPurposeRegistry } from "./contracts/consent.js";
+import { z } from "./validation.js";
+
+export const NEWSLETTER_MARKETING_PURPOSES = [
+  "marketing_launch_offer",
+  "marketing_newsletter",
+] as const;
+
+export const NEWSLETTER_SYNC_EVENT_TYPES = [
+  "subscribe",
+  "update",
+  "unsubscribe",
+  "suppress",
+] as const;
+
+export const NEWSLETTER_WEBHOOK_EVENT_TYPES = [
+  ...NEWSLETTER_SYNC_EVENT_TYPES,
+  "complaint",
+  "bounce",
+  "email_change",
+  "profile_update",
+  "ignored",
+] as const;
+
+export const NEWSLETTER_PROVIDER_CAPABILITY_KEYS = [
+  "subscribe",
+  "unsubscribe",
+  "suppress",
+  "unsuppress",
+  "doubleOptIn",
+  "emailChange",
+  "listMembership",
+  "webhookIdempotency",
+  "retryAfter",
+] as const;
+
+import type { NewsletterMarketingPurpose } from "./contracts/newsletter.js";
+import type { NewsletterProviderKind, NewsletterSyncEventType, NewsletterWebhookEventType, NewsletterProviderCapabilityKey, NewsletterProviderCapabilities, NewsletterWebhookEvent, NewsletterSyncEvent } from "./contracts/newsletter.js";
+export type { NewsletterProviderKind, NewsletterMarketingPurpose, NewsletterSyncEventType, NewsletterWebhookEventType, NewsletterProviderCapabilityKey, NewsletterProviderCapabilities, NewsletterWebhookEvent, NewsletterSyncEvent } from "./contracts/newsletter.js";
+export const defaultNewsletterProviderCapabilities: NewsletterProviderCapabilities = {
+  subscribe: false,
+  unsubscribe: false,
+  suppress: false,
+  unsuppress: false,
+  doubleOptIn: false,
+  emailChange: false,
+  listMembership: false,
+  webhookIdempotency: false,
+  retryAfter: false,
+};
+
+export const fullNewsletterProviderCapabilities: NewsletterProviderCapabilities = {
+  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 type CanonicalNewsletterWebhookEvent = z.infer<
+  typeof canonicalNewsletterWebhookEventSchema
+>;
+
+export function normalizeCanonicalNewsletterWebhookEvent<Purpose extends string = NewsletterMarketingPurpose>(
+  event: Omit<CanonicalNewsletterWebhookEvent, "purpose"> & { purpose?: Purpose | null },
+): NewsletterWebhookEvent<Purpose> {
+  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: NewsletterSyncEventType,
+): NewsletterProviderCapabilityKey {
+  if (eventType === "subscribe") return "subscribe";
+  if (eventType === "unsubscribe") return "unsubscribe";
+  if (eventType === "suppress") return "suppress";
+  return "listMembership";
+}
+
+export function supportsNewsletterSyncEvent(
+  capabilities: NewsletterProviderCapabilities,
+  eventType: NewsletterSyncEventType,
+): boolean {
+  return capabilities[requiredNewsletterCapabilityForEvent(eventType)] === true;
+}
+
+/** Explicit registry binding; legacy schemas above retain their two-purpose default. */
+export function createNewsletterIntegrationSchemas<Purpose extends string>(registry: CommunicationPurposeRegistry<Purpose>) {
+  const purpose = z.custom<Purpose>((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/src/communications/newsletterWebhookPort.ts

@@ -0,0 +1,104 @@
+import type {
+  NewsletterWebhookPort,
+  NormalizedNewsletterWebhookEvent,
+} from "./contracts/newsletterWebhook.js";
+
+export interface NewsletterWebhookRpcClient {
+  rpc(
+    functionName: string,
+    args: Record<string, unknown>,
+  ): PromiseLike<{ data: unknown; error: { code?: string; message?: string } | null }>;
+}
+
+export function createSupabaseNewsletterWebhookPort(
+  client: NewsletterWebhookRpcClient,
+): NewsletterWebhookPort {
+  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: NormalizedNewsletterWebhookEvent & { processingStatus: "received" | "ignored" },
+): Record<string, unknown> {
+  return {
+    occurredAt: input.occurredAt,
+    explicitOptInEvidence: input.explicitOptInEvidence,
+    doubleOptInStatus: input.doubleOptInStatus,
+    remoteListId: input.remoteListId,
+    processingStatus: input.processingStatus,
+  };
+}
+
+function sanitizePayload(payload: Record<string, unknown>): Record<string, unknown> {
+  const sanitized = { ...payload };
+  delete sanitized.apiKey;
+  delete sanitized.token;
+  delete sanitized.secret;
+  return sanitized;
+}
+
+function rpcFailure(rpcName: string, error: { code?: string; message?: string }): Error {
+  return new Error(`${rpcName}_failed: ${error.message ?? error.code ?? "unknown"}`);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+
+function readString(value: unknown): string | null {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}

package/src/communications/newsletterWebhookProcessing.ts

@@ -0,0 +1,102 @@
+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";
+}
+
+const MARKETING_PURPOSES = ["marketing_launch_offer", "marketing_newsletter"] as const;
+
+export async function processNewsletterWebhookEvent<Purpose extends string = NewsletterMarketingPurpose>(input: {
+  providerKind: string;
+  event: NewsletterWebhookEvent<Purpose>;
+  port: NewsletterWebhookPort<Purpose | NewsletterMarketingPurpose>;
+  registry?: CommunicationPurposeRegistry<Purpose>;
+}): Promise<NewsletterWebhookProcessResult> {
+  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<Purpose extends string>(
+  event: NewsletterWebhookEvent<Purpose>,
+): { kind: "apply"; state: "granted" | "suppressed"; reason: string } | {
+  kind: "ignore";
+  state: null;
+  reason: string;
+} {
+  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/src/communications/originPolicy.ts

@@ -0,0 +1,151 @@
+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 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";
+
+export interface EmailOriginConfiguration {
+  defaultOrigin: string;
+  productionEmailHosts: string[];
+}
+
+function clean(value: string | null | undefined): string | null {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : null;
+}
+
+function resolveEnvironment(input: EmailOriginInput): EmailEnvironment {
+  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: string): string | null {
+  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: string, productionHosts: string[]): boolean {
+  try {
+    return productionHosts.includes(new URL(origin).hostname.toLowerCase());
+  } catch {
+    return false;
+  }
+}
+
+export function readEmailOriginConfiguration(
+  env: Record<string, string | undefined>,
+  fallback: EmailOriginConfiguration,
+): EmailOriginConfiguration {
+  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: EmailEnvironment): boolean {
+  return environment === "hidden_preview" || environment === "preview" || environment === "staging";
+}
+
+export function resolveEmailOrigin(input: EmailOriginInput): EmailOriginResolution {
+  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,
+    },
+  };
+}