@openlup/platform 0.16.0 → 0.17.0

package/src/communications/communicationSyncWorker.ts

@@ -0,0 +1,302 @@
+import type { CommunicationPurposeRegistry } from "./contracts/consent.js";
+import type { NewsletterMarketingPurpose } from "./contracts/newsletter.js";
+import type {
+  NewsletterSyncEvent,
+  NewsletterSyncProviderPort,
+} from "./contracts/newsletter.js";
+import {
+  requiredNewsletterCapabilityForEvent,
+  supportsNewsletterSyncEvent,
+} from "./newsletterIntegrationContracts.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 const DEFAULT_COMMUNICATION_SYNC_CONFIG: CommunicationSyncConfig = {
+  batchSize: 25,
+  maxAttempts: 8,
+  visibilitySeconds: 300,
+  backoffSeconds: 300,
+};
+
+export async function runCommunicationSyncDispatch<Purpose extends string = NewsletterMarketingPurpose>(input: {
+  store: CommunicationSyncStore<Purpose>;
+  provider: NewsletterSyncProviderPort<Purpose>;
+  config?: Partial<CommunicationSyncConfig>;
+  registry?: CommunicationPurposeRegistry<Purpose>;
+}): Promise<CommunicationSyncRunResult> {
+  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: CommunicationSyncRunResult = {
+    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<Purpose extends string = NewsletterMarketingPurpose>(input: {
+  store: CommunicationSyncStore<Purpose>;
+  providers: NewsletterSyncProviderPort<Purpose>[];
+  config?: Partial<CommunicationSyncConfig>;
+  registry?: CommunicationPurposeRegistry<Purpose>;
+}): Promise<CommunicationSyncRunResult> {
+  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: CommunicationSyncRunResult[] = [];
+  for (const provider of input.providers) {
+    results.push(await runCommunicationSyncDispatch({
+      store: input.store,
+      provider,
+      config: input.config,
+      registry: input.registry,
+    }));
+  }
+  return aggregateProviderResults(results);
+}
+
+export interface CommunicationReconcileRunResult {
+  ok: boolean;
+  checked: number;
+  updated: number;
+  failures: number;
+  skipped: boolean;
+  reason?: string;
+}
+
+export async function runCommunicationSyncReconcile(input: {
+  providers?: NewsletterSyncProviderPort[];
+} = {}): Promise<CommunicationReconcileRunResult> {
+  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: CommunicationSyncRunResult[]): CommunicationSyncRunResult {
+  const aggregate = results.reduce<CommunicationSyncRunResult>((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: number, min: number, max: number): number {
+  if (!Number.isFinite(value)) return min;
+  return Math.min(Math.max(Math.trunc(value), min), max);
+}
+
+function safeMessage(error: unknown): string {
+  return (error instanceof Error ? error.message : String(error)).slice(0, 300);
+}

package/src/communications/consentPolicy.ts

@@ -0,0 +1,82 @@
+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;
+}
+
+const MARKETING_PURPOSES = new Set<CommunicationPurpose>([
+  "marketing_launch_offer",
+  "marketing_newsletter",
+]);
+
+export function evaluateCommunicationPolicy<Purpose extends string = CommunicationPurpose>(
+  input: CommunicationPolicyInput<Purpose>,
+  registry?: CommunicationPurposeRegistry<Purpose>,
+): CommunicationPolicyResult {
+  if (registry && !registry.has(input.purpose)) return { decision: "blocked", reason: "unsupported_purpose" };
+  const state = input.permission?.state ?? "unknown";
+
+  if (input.purpose === "admin_notification") {
+    return { decision: "allowed", reason: "admin_notification" };
+  }
+
+  if (input.purpose === "transactional" || input.purpose === "subscription_dunning") {
+    return { decision: "allowed", reason: "purpose_allowed_without_marketing_consent" };
+  }
+
+  if (input.purpose === "tester_program") {
+    if (input.permission?.legacySequencePaused) {
+      return { decision: "blocked", reason: "sequence_paused" };
+    }
+    if (state === "denied" || state === "suppressed") {
+      return { decision: "blocked", reason: `permission_${state}` };
+    }
+    if (state !== "granted") {
+      return { decision: "blocked", reason: "missing_tester_program_permission" };
+    }
+    return { decision: "allowed", reason: "tester_program_granted" };
+  }
+
+  if (registry ? registry.classification(input.purpose) === "marketing" : MARKETING_PURPOSES.has(input.purpose as CommunicationPurpose)) {
+    if (state === "suppressed") {
+      return { decision: "blocked", reason: "permission_suppressed" };
+    }
+    if (state !== "granted") {
+      return { decision: "blocked", reason: "missing_marketing_permission" };
+    }
+    return { decision: "allowed", reason: "marketing_permission_granted" };
+  }
+
+  if (registry?.classification(input.purpose) === "non-marketing") {
+    return { decision: "allowed", reason: "purpose_allowed_without_marketing_consent" };
+  }
+  return { decision: "blocked", reason: "unsupported_purpose" };
+}
+
+export function consentStateFromBoolean(value: boolean | null | undefined): CommunicationPermissionState {
+  return value === true ? "granted" : "denied";
+}

package/src/communications/consentPurposeRegistry.ts

@@ -0,0 +1,31 @@
+import type { CommunicationPurpose } from "./contracts/types.js";
+import type { CommunicationPurposeDefinition, CommunicationPurposeRegistry } from "./contracts/consent.js";
+
+const builtins: readonly CommunicationPurposeDefinition[] = [
+  { id: "transactional", classification: "non-marketing" },
+  { id: "tester_program", classification: "non-marketing" },
+  { id: "marketing_launch_offer", classification: "marketing" },
+  { id: "marketing_newsletter", classification: "marketing" },
+  { id: "subscription_dunning", classification: "non-marketing" },
+  { id: "admin_notification", classification: "non-marketing" },
+];
+
+export function createCommunicationPurposeRegistry<const Purpose extends string = never>(
+  additions: readonly CommunicationPurposeDefinition<Purpose>[] = [],
+): CommunicationPurposeRegistry<CommunicationPurpose | Purpose> {
+  const definitions = new Map<string, CommunicationPurposeDefinition<CommunicationPurpose | Purpose>>();
+  for (const definition of [...builtins, ...additions]) {
+    if (typeof definition.id !== "string" || !definition.id.trim() || definition.id !== definition.id.trim()
+      || !["marketing", "non-marketing"].includes(definition.classification) || definitions.has(definition.id)) {
+      throw new Error("communication_purpose_definition_invalid");
+    }
+    definitions.set(definition.id, Object.freeze({ id: definition.id, classification: definition.classification }));
+  }
+  return Object.freeze({
+    purposes: Object.freeze([...definitions.values()]),
+    has: (value: unknown): value is CommunicationPurpose | Purpose => typeof value === "string" && definitions.has(value),
+    classification: (purpose: CommunicationPurpose | Purpose) => definitions.get(purpose)?.classification,
+  });
+}
+
+export const defaultCommunicationPurposeRegistry = createCommunicationPurposeRegistry();

package/src/communications/contracts/abandonedCart.ts

@@ -0,0 +1,64 @@
+import type { CommerceEmailContent } from "./commerceEmailContent.js";
+import type { Locale } from "./email.js";
+import {
+  button,
+  heading,
+  paragraph,
+  type EmailBlock,
+} from "./blocks.js";
+
+/** 1 = light same-session nudge, 24 = gentle nudge, 72 = final last-nudge. */
+export type AbandonedCartReminderHours = 1 | 24 | 72;
+
+export interface AbandonedCartEmailVars {
+  firstName: string | null;
+  /** Consumer-facing brand label injected by the app/composition root. */
+  brandName: string;
+  reminderHours: AbandonedCartReminderHours;
+  /** Absolute CTA URL back to the configurator. */
+  ctaUrl: string;
+  /** Absolute signed unsubscribe URL (purpose 'marketing_newsletter'). */
+  unsubscribeUrl: string;
+}
+
+export interface AbandonedCartEmailContent {
+  subject: string;
+  preheader: string;
+  blocks: EmailBlock[];
+}
+
+/** Bind host-selected copy and pure helpers without provider or environment access. */
+export function createAbandonedCartContentFactory(input: {
+  commerceEmailContent: Pick<CommerceEmailContent, "abandonedCart">;
+  marketingUnsubscribeFooter: (locale: Locale, unsubscribeUrl: string) => EmailBlock[];
+}) {
+  const { commerceEmailContent, marketingUnsubscribeFooter } = input;
+
+  function abandonedCartEmailContent(
+    locale: Locale,
+    vars: AbandonedCartEmailVars,
+    signoff: string,
+  ): AbandonedCartEmailContent {
+    const copy = commerceEmailContent.abandonedCart[locale];
+    const tone =
+      vars.reminderHours === 72 ? copy.last : vars.reminderHours === 1 ? copy.first : copy.gentle;
+    const withBrand = (text: string) => text.split("{{brand}}").join(vars.brandName);
+
+    const blocks: EmailBlock[] = [
+      heading(withBrand(tone.heading)),
+      paragraph(copy.greeting(vars.firstName)),
+      paragraph(withBrand(tone.intro)),
+      paragraph(withBrand(tone.body)),
+      button(tone.cta, vars.ctaUrl),
+      paragraph(signoff),
+      ...marketingUnsubscribeFooter(locale, vars.unsubscribeUrl),
+    ];
+
+    return {
+      subject: withBrand(tone.subject),
+      preheader: withBrand(tone.preheader),
+      blocks,
+    };
+  }
+  return { abandonedCartEmailContent };
+}

package/src/communications/contracts/authEmail.ts

@@ -0,0 +1,73 @@
+import type { EmailBlock, Locale } from "./email.js";
+// Generic server-side auth ports. OSS core: no provider client, secrets, or
+// brand literals. The product app supplies concrete adapters outside this domain.
+
+
+export type AuthEmailLocale = Locale;
+
+export interface AuthEmailContentPort {
+  buildAuthEmailContent(input: {
+    actionType: string;
+    userMetadata: Record<string, unknown> | null | undefined;
+    redirectTo: string;
+    actionLink: string;
+    otp: string | null;
+  }): {
+    locale: AuthEmailLocale;
+    subject: string;
+    preheader: string;
+    blocks: EmailBlock[];
+  };
+}
+
+export type AuthEmailPersistenceSkipReason = "admin_disabled" | "egress_suppressed";
+
+export interface AuthEmailMessage {
+  sender: string;
+  recipient: string;
+  subject: string;
+  html: string;
+  text?: string;
+}
+
+export interface AuthEmailTransportResult {
+  outcome: {
+    ok: boolean;
+    messageId: string | null;
+    providerError: string | null;
+    aborted?: boolean;
+    adminDisabled?: boolean;
+    suppressed?: "drop" | null;
+    egressMode?: "production" | "sandbox_direct" | "sandbox_sink" | "drop";
+  };
+  providerResponse: Record<string, unknown>;
+}
+
+/** Provider-neutral outbound seam supplied by the API composition root. */
+export interface AuthEmailTransportPort {
+  readonly providerKind: string;
+  send(message: AuthEmailMessage): Promise<AuthEmailTransportResult>;
+}
+
+/** Provider-neutral send observation owned by the Auth email candidate. */
+export interface AuthEmailPersistencePort {
+  isTemplateEnabled(templateSlug: string, signal: AbortSignal): Promise<boolean>;
+  recordSend(input: {
+    templateSlug: string;
+    recipientEmail: string;
+    authUserId: string | null;
+    aggregateId: string;
+    dedupeKey: string;
+    providerKind: string;
+    outcome: {
+      ok: boolean;
+      messageId: string | null;
+      providerError: string | null;
+      aborted?: boolean;
+      skipReason?: AuthEmailPersistenceSkipReason | null;
+    };
+    providerResponse: Record<string, unknown>;
+    metadata: Record<string, unknown>;
+  }): Promise<void>;
+}
+

package/src/communications/contracts/backInStock.ts

@@ -0,0 +1,69 @@
+import type { CommerceEmailContent } from "./commerceEmailContent.js";
+import type { Locale } from "./email.js";
+import {
+  button,
+  heading,
+  paragraph,
+  type EmailBlock,
+} from "./blocks.js";
+
+export interface BackInStockEmailVars {
+  /** Consumer-facing brand label injected by the app/composition root. */
+  brandName: string;
+  /** The sku that came back. Used for context/keying – never shown in copy. */
+  sku: string;
+  /**
+   * Resolved, localized product name. When unknown (catalog miss / failure) the
+   * copy falls back to a generic localized label – a raw sku must never surface
+   * in a customer-facing subject or body.
+   */
+  productName?: string | null;
+  /** Absolute CTA URL (product page or configurator). null/absent → no button. */
+  ctaUrl?: string | null;
+}
+
+export interface BackInStockEmailContent {
+  subject: string;
+  preheader: string;
+  blocks: EmailBlock[];
+}
+
+/** Bind host-selected copy and pure helpers without provider or environment access. */
+export function createBackInStockContentFactory(input: {
+  commerceEmailContent: Pick<CommerceEmailContent, "backInStock">;
+}) {
+  const { commerceEmailContent } = input;
+
+  function backInStockEmailContent(
+    locale: Locale,
+    vars: BackInStockEmailVars,
+    signoff: string,
+  ): BackInStockEmailContent {
+    const copy = commerceEmailContent.backInStock[locale];
+    const productLabel =
+      vars.productName && vars.productName.trim() !== ""
+        ? vars.productName.trim()
+        : copy.genericLabel;
+    const withBrand = (text: string) => text.split("{{brand}}").join(vars.brandName);
+
+    const blocks: EmailBlock[] = [
+      heading(copy.heading(productLabel)),
+      paragraph(copy.greeting),
+      paragraph(copy.intro(productLabel)),
+      paragraph(withBrand(copy.hook)),
+    ];
+
+    if (vars.ctaUrl) {
+      blocks.push(button(copy.cta, vars.ctaUrl));
+    }
+
+    blocks.push(paragraph(signoff));
+
+    return {
+      subject: withBrand(copy.subject(productLabel)),
+      preheader: copy.preheader,
+      blocks,
+    };
+  }
+  return { backInStockEmailContent };
+}

package/src/communications/contracts/blocks.ts

@@ -0,0 +1,47 @@
+import type { ParagraphBlock, HeadingBlock, ListBlock, AccentBoxBlock, DataRow, DataTableBlock, FeatureCardBlock, ButtonBlock, LinkParagraphBlock, DividerBlock } from "./email.js";
+export type { ParagraphBlock, HeadingBlock, ListBlock, AccentBoxBlock, DataRow, DataTableBlock, FeatureCardImage, FeatureCardBlock, ButtonBlock, LinkParagraphBlock, DividerBlock, EmailBlock } from "./email.js";
+
+export const paragraph = (
+  text: string,
+  opts: { muted?: boolean; afterCard?: boolean } = {},
+): ParagraphBlock => ({
+  kind: "paragraph",
+  text,
+  muted: opts.muted ?? false,
+  ...(opts.afterCard ? { afterCard: true } : {}),
+});
+
+export const heading = (text: string): HeadingBlock => ({ kind: "heading", text });
+
+export const list = (items: string[]): ListBlock => ({ kind: "list", items });
+
+export const accentBox = (
+  lines: string[],
+  opts: { label?: string } = {},
+): AccentBoxBlock => ({ kind: "accentBox", label: opts.label, lines });
+
+export const dataTable = (
+  rows: DataRow[],
+  opts: { link?: { label: string; href: string } } = {},
+): DataTableBlock => ({ kind: "dataTable", rows, ...(opts.link ? { link: opts.link } : {}) });
+
+export const featureCard = (card: Omit<FeatureCardBlock, "kind">): FeatureCardBlock => ({
+  kind: "featureCard",
+  ...card,
+});
+
+export const button = (label: string, href: string): ButtonBlock => ({ kind: "button", label, href });
+
+export const linkParagraph = (
+  text: string,
+  href: string,
+  opts: { muted?: boolean; afterCard?: boolean } = {},
+): LinkParagraphBlock => ({
+  kind: "linkParagraph",
+  text,
+  href,
+  muted: opts.muted ?? false,
+  ...(opts.afterCard ? { afterCard: true } : {}),
+});
+
+export const divider = (): DividerBlock => ({ kind: "divider" });