@openlup/platform 0.27.0 → 0.29.0

package/src/marketing/acquisitionCaseSchemas.ts

@@ -0,0 +1,75 @@
+import { z } from "./validation.js";
+
+export const ACQUISITION_CASE_CONTRACT_VERSION = "tester_application_v1" as const;
+export const ACQUISITION_CASE_VIEW = "acquisition_case_v1" as const;
+export const ACQUISITION_CASE_SOURCE = "tester_application" as const;
+
+export const acquisitionOpaqueReferenceSchema = z.string().trim().min(8).max(160)
+  .regex(/^[A-Za-z0-9][A-Za-z0-9._:-]*$/);
+const dateTimeSchema = z.string().datetime({ offset: true });
+
+export const acquisitionAddressReferenceSchema = z.object({
+  source: z.string().trim().min(1).max(48).regex(/^[a-z][a-z0-9_-]*$/),
+  reference: acquisitionOpaqueReferenceSchema,
+  revision: z.string().trim().min(1).max(64).regex(/^[A-Za-z0-9][A-Za-z0-9._:-]*$/),
+  provenance: z.string().trim().min(1).max(64).regex(/^[a-z][a-z0-9_-]*$/),
+}).strict();
+
+
+export const acquisitionCaseStateSchema = z.enum([
+  "submitted", "approved", "active", "rejected", "withdrawn",
+]);
+
+export const acquisitionCaseProjectionSchema = z.object({
+  contractVersion: z.literal(ACQUISITION_CASE_CONTRACT_VERSION),
+  caseRef: acquisitionOpaqueReferenceSchema,
+  contactRef: acquisitionOpaqueReferenceSchema,
+  sourceKind: z.literal(ACQUISITION_CASE_SOURCE),
+  consent: z.object({
+    consentVersion: z.string().min(1).max(64),
+    policyVersion: z.string().min(1).max(64),
+    recordedAt: dateTimeSchema,
+    locale: z.enum(["en", "pl"]),
+    sourcePath: z.literal("/tester-application"),
+  }).strict(),
+  addressReference: acquisitionAddressReferenceSchema.nullable(),
+  state: acquisitionCaseStateSchema,
+  version: z.number().int().positive(),
+  createdAt: dateTimeSchema,
+  updatedAt: dateTimeSchema,
+}).strict().superRefine((value, context) => {
+  if (value.state !== "withdrawn" && value.addressReference === null) {
+    context.addIssue({ code: z.ZodIssueCode.custom, path: ["addressReference"], message: "active case requires address reference" });
+  }
+});
+
+export const acquisitionCaseListRequestSchema = z.object({
+  view: z.literal(ACQUISITION_CASE_VIEW),
+  cursor: acquisitionOpaqueReferenceSchema.optional(),
+  limit: z.number().int().min(1).max(100).default(25),
+}).strict();
+
+export const acquisitionCaseListResponseSchema = z.object({
+  contractVersion: z.literal(ACQUISITION_CASE_CONTRACT_VERSION),
+  cases: z.array(acquisitionCaseProjectionSchema).max(100),
+  nextCursor: acquisitionOpaqueReferenceSchema.nullable(),
+}).strict();
+
+
+
+
+export const acquisitionCaseActiveCountResponseSchema = z.object({
+  activeTesterCount: z.number().int().nonnegative(),
+}).strict();
+
+export const acquisitionIdempotencyKeySchema = z.string().trim().min(8).max(200)
+  .regex(/^[A-Za-z0-9][A-Za-z0-9._:-]*$/);
+
+export type AcquisitionOpaqueReference = z.infer<typeof acquisitionOpaqueReferenceSchema>;
+export type AcquisitionAddressReference = z.infer<typeof acquisitionAddressReferenceSchema>;
+export type AcquisitionCaseState = z.infer<typeof acquisitionCaseStateSchema>;
+export type AcquisitionCaseProjection = z.infer<typeof acquisitionCaseProjectionSchema>;
+export type AcquisitionCaseListRequest = z.infer<typeof acquisitionCaseListRequestSchema>;
+export type AcquisitionCaseListResponse = z.infer<typeof acquisitionCaseListResponseSchema>;
+export type AcquisitionCaseActiveCountResponse = z.infer<typeof acquisitionCaseActiveCountResponseSchema>;
+export type AcquisitionIdempotencyKey = z.infer<typeof acquisitionIdempotencyKeySchema>;

package/src/marketing/acquisitionEvidenceSchemas.ts

@@ -0,0 +1,72 @@
+import { z } from "./validation.js";
+
+export const ACQUISITION_SURVEY_VERSION = "acquisition_survey_v1" as const;
+export const ACQUISITION_NEWSLETTER_VERSION = "acquisition_newsletter_consent_v1" as const;
+
+const caseReference = z.string().regex(/^acquisition-case:[0-9a-f-]{36}$/);
+const contactReference = z.string().regex(/^acquisition-contact:[0-9a-f-]{36}$/);
+const commandKey = z.string().min(8).max(200).regex(/^[A-Za-z0-9][A-Za-z0-9._:-]+$/);
+const digest = z.string().regex(/^[0-9a-f]{64}$/);
+
+export const acquisitionSurveySubmitSchema = z.object({
+  view: z.literal(ACQUISITION_SURVEY_VERSION),
+  caseReference,
+  surveyType: z.enum(["producer", "consumer"]),
+  responseData: z.record(z.string(), z.unknown()),
+});
+
+export const acquisitionSurveyEvidenceSchema = z.object({
+  evidenceReference: z.string().regex(/^acquisition-survey:[0-9a-f-]{36}$/),
+  caseReference,
+  contactReference,
+  surveyType: z.enum(["producer", "consumer"]),
+  responseDigest: digest,
+  answerCount: z.number().int().min(1).max(100),
+  recordedAt: z.string().datetime({ offset: true }),
+});
+
+export const acquisitionSurveySubmitResponseSchema = z.object({
+  contractVersion: z.literal(ACQUISITION_SURVEY_VERSION),
+  evidence: acquisitionSurveyEvidenceSchema,
+  replayed: z.boolean(),
+});
+
+export const acquisitionSurveyListQuerySchema = z.object({
+  view: z.literal(ACQUISITION_SURVEY_VERSION),
+  surveyType: z.enum(["producer", "consumer"]).optional(),
+  limit: z.coerce.number().int().min(1).max(100).default(50),
+});
+
+export const acquisitionSurveyListResponseSchema = z.object({
+  contractVersion: z.literal(ACQUISITION_SURVEY_VERSION),
+  rows: z.array(acquisitionSurveyEvidenceSchema),
+  totalCount: z.number().int().min(0),
+});
+
+export const acquisitionNewsletterConsentEventSchema = z.object({
+  contractVersion: z.literal(ACQUISITION_NEWSLETTER_VERSION),
+  caseReference,
+  contactReference,
+  eventReference: commandKey,
+  eventType: z.enum(["subscribe", "unsubscribe", "suppress", "complaint", "update"]),
+  purpose: z.enum(["marketing_launch_offer", "marketing_newsletter"]),
+  explicitOptInEvidence: z.boolean().default(false),
+  occurredAt: z.string().datetime({ offset: true }),
+}).strict();
+
+export const acquisitionNewsletterConsentResponseSchema = z.object({
+  contractVersion: z.literal(ACQUISITION_NEWSLETTER_VERSION),
+  eventReference: commandKey,
+  outcome: z.enum(["applied", "ignored", "stale"]),
+  consentState: z.enum(["granted", "suppressed"]).nullable(),
+  auditReference: z.string().regex(/^acquisition-consent:[0-9a-f-]{36}$/),
+  replayed: z.boolean(),
+});
+
+export type AcquisitionSurveySubmit = z.infer<typeof acquisitionSurveySubmitSchema>;
+export type AcquisitionSurveyEvidence = z.infer<typeof acquisitionSurveyEvidenceSchema>;
+export type AcquisitionSurveySubmitResponse = z.infer<typeof acquisitionSurveySubmitResponseSchema>;
+export type AcquisitionSurveyListQuery = z.infer<typeof acquisitionSurveyListQuerySchema>;
+export type AcquisitionSurveyListResponse = z.infer<typeof acquisitionSurveyListResponseSchema>;
+export type AcquisitionNewsletterConsentEvent = z.infer<typeof acquisitionNewsletterConsentEventSchema>;
+export type AcquisitionNewsletterConsentResponse = z.infer<typeof acquisitionNewsletterConsentResponseSchema>;

package/src/marketing/analytics/dataLayer.ts

@@ -0,0 +1,100 @@
+import type { AnalyticsSinkAttemptMask, AnalyticsSinkAdmission, AnalyticsCookieConsent, AnalyticsDataLayerOptions } from "../contracts/analytics.js";
+export type { AnalyticsSinkAttemptMask, AnalyticsSinkAdmission, AnalyticsCookieConsent, AnalyticsBrowserWindow, AnalyticsDataLayerOptions } from "../contracts/analytics.js";
+import { trackDeploymentEvent } from "./noop.js";
+import type { AnalyticsEventMap, AnalyticsEventName } from "./noop.js";
+
+type ConsentState = "granted" | "denied";
+
+/** Each instance owns loader state; the host supplies browser and deployment policy. */
+export function createAnalyticsDataLayer<StepName extends string = string>(options: AnalyticsDataLayerOptions<StepName> = {}) {
+  const { consentStorageKey = "", consentChangeEvent = "", consentSignalNames, eventPrefix = "",
+    readContainerId = () => null, getWindow = () => undefined } = options;
+  const deploymentSink = options.trackDeploymentEvent ?? trackDeploymentEvent;
+  let analyticsLoaderReady = false;
+  const readinessListeners = new Set<() => void>();
+  function readCookieConsent(): AnalyticsCookieConsent | null {
+    const browser = getWindow();
+    if (!browser) return null;
+    try {
+      const parsed: unknown = JSON.parse(browser.localStorage.getItem(consentStorageKey) ?? "");
+      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+      const value = parsed as Record<string, unknown>;
+      if (typeof value.necessary !== "boolean" || typeof value.functional !== "boolean"
+        || typeof value.analytics !== "boolean" || typeof value.marketing !== "boolean") return null;
+      return { necessary: value.necessary, functional: value.functional,
+        analytics: value.analytics, marketing: value.marketing };
+    } catch { return null; }
+  }
+  function hasAnalyticsConsent(consent = readCookieConsent()): boolean { return consent?.analytics === true; }
+  function configuredContainerId(): string | null { return readContainerId(); }
+  function subscribeToAnalyticsConsent(listener: () => void): () => void {
+    const browser = getWindow();
+    if (!browser) return () => undefined;
+    const onStorage = (event: StorageEvent) => { if (event.key === consentStorageKey) listener(); };
+    browser.addEventListener("storage", onStorage);
+    browser.addEventListener(consentChangeEvent, listener);
+    return () => {
+      browser.removeEventListener("storage", onStorage);
+      browser.removeEventListener(consentChangeEvent, listener);
+    };
+  }
+  function isAnalyticsLoaderReady(): boolean { return analyticsLoaderReady; }
+  function subscribeToAnalyticsLoaderReadiness(listener: () => void): () => void {
+    readinessListeners.add(listener);
+    return () => readinessListeners.delete(listener);
+  }
+  function markAnalyticsLoaderReady(): void {
+    if (analyticsLoaderReady) return;
+    analyticsLoaderReady = true;
+    for (const listener of readinessListeners) listener();
+  }
+  function resetAnalyticsLoaderReadiness(): void { analyticsLoaderReady = false; }
+  function pushAnalyticsConsentDefault(): void {
+    pushConsentCommand("default", "denied", "denied");
+  }
+  function pushAnalyticsConsentUpdate(granted: boolean): void {
+    const analyticsState: ConsentState = granted ? "granted" : "denied";
+    // Read the separate advertising grant at push time; revocation denies all signals.
+    const adState: ConsentState = granted && readCookieConsent()?.marketing === true ? "granted" : "denied";
+    pushConsentCommand("update", analyticsState, adState);
+  }
+  function pushAnalyticsEvent<K extends AnalyticsEventName>(event: K, properties: AnalyticsEventMap<StepName>[K]): boolean {
+    const browser = getWindow();
+    if (!consentSignalNames || !browser || !configuredContainerId() || !hasAnalyticsConsent()) return false;
+    if (!browser.dataLayer) {
+      browser.dataLayer = [];
+      pushAnalyticsConsentDefault();
+      pushAnalyticsConsentUpdate(true);
+    }
+    browser.dataLayer.push({ event: `${eventPrefix}${event}`, ...properties });
+    return true;
+  }
+  function emitAnalyticsEvent<K extends AnalyticsEventName>(event: K, properties: AnalyticsEventMap<StepName>[K],
+    attempts: AnalyticsSinkAttemptMask = { deployment: true, optional: true }): AnalyticsSinkAdmission {
+    let deployment = false;
+    let optional = false;
+    if (attempts.deployment) {
+      try { deployment = deploymentSink(event, properties); } catch { /* Sink failure never gates the product. */ }
+    }
+    if (attempts.optional) {
+      try { optional = pushAnalyticsEvent(event, properties); } catch { /* Independent best-effort admission. */ }
+    }
+    return { deployment, optional };
+  }
+  function pushConsentCommand(action: "default" | "update", analyticsState: ConsentState, adState: ConsentState): void {
+    const browser = getWindow();
+    if (!consentSignalNames || !browser?.dataLayer) return;
+    const settings: Record<string, ConsentState> = { [consentSignalNames.analytics]: analyticsState };
+    for (const name of consentSignalNames.advertising) settings[name] = adState;
+    function consentCommand(..._args: unknown[]) {
+      // Consent commands use the array-like arguments object, not an event object.
+      // eslint-disable-next-line prefer-rest-params
+      browser?.dataLayer?.push(arguments);
+    }
+    consentCommand("consent", action, settings);
+  }
+  return { readCookieConsent, hasAnalyticsConsent, configuredContainerId, subscribeToAnalyticsConsent,
+    isAnalyticsLoaderReady, subscribeToAnalyticsLoaderReadiness, markAnalyticsLoaderReady,
+    resetAnalyticsLoaderReadiness, pushAnalyticsConsentDefault, pushAnalyticsConsentUpdate,
+    pushAnalyticsEvent, emitAnalyticsEvent };
+}

package/src/marketing/analytics/noop.ts

@@ -0,0 +1,14 @@
+import type { AnalyticsEventMap, AnalyticsEventName } from "../contracts/analytics.js";
+export type { AnalyticsStepName, AnalyticsCheckoutItem, AnalyticsPurchaseItem, AnalyticsCheckoutMode, AnalyticsPaymentWaitOutcome, AnalyticsEventMap, AnalyticsEventName } from "../contracts/analytics.js";
+import type { AnalyticsPort } from "@openlup/core/platform-runtime";
+
+export function initializeDeploymentAnalytics(): void {}
+export function trackDeploymentEvent<K extends AnalyticsEventName>(
+  _event: K, _properties: AnalyticsEventMap[K],
+): boolean { return false; }
+export function syncAdvertisingConsent(): void {}
+export function trackAdvertisingPurchase(_payload: AnalyticsEventMap["purchase"]): boolean { return false; }
+/** Inert composition satisfies the existing platform runtime port. */
+export function createNoopAnalytics(): AnalyticsPort {
+  return { trackPageView() {}, trackEvent() {} };
+}

package/src/marketing/analytics/purchaseFacts.ts

@@ -0,0 +1,63 @@
+import type { PurchaseOrder, PurchaseSuppressionReason } from "../contracts/analytics.js";
+export type { PurchaseOrder, PurchaseSuppressionReason } from "../contracts/analytics.js";
+import type { AnalyticsEventMap, AnalyticsPurchaseItem } from "./noop.js";
+
+const MAX_ITEMS = 200;
+
+export function projectPaidPurchase(recap: PurchaseOrder,
+  suppressPurchase: (reason: PurchaseSuppressionReason) => null = () => null,
+): AnalyticsEventMap["purchase"] | null {
+  if (recap.status !== "paid") return suppressPurchase("order_not_paid");
+  if (recap.paymentStatus !== "succeeded") return suppressPurchase("payment_not_succeeded");
+  if (recap.checkoutKind !== "one_time" && recap.checkoutKind !== "subscription_initial"
+    && recap.checkoutKind !== "subscription_renewal") return suppressPurchase("checkout_kind_unsupported");
+  if (!recap.moneyReconciled) return suppressPurchase("money_unreconciled");
+  if (recap.items.length === 0) return suppressPurchase("items_empty");
+  let effectiveNet = 0;
+  const items: AnalyticsPurchaseItem[] = [];
+  for (const item of recap.items) {
+    if (!item.sku) return suppressPurchase("sku_missing");
+    if (!Number.isSafeInteger(item.quantity) || item.quantity <= 0) return suppressPurchase("quantity_invalid");
+    if (item.quantity > MAX_ITEMS) return suppressPurchase("item_limit_exceeded");
+    if (!isNonNegativeSafeInteger(item.catalogTotalGross) || !isNonNegativeSafeInteger(item.effectiveNet)
+      || !isNonNegativeSafeInteger(item.vatRateBps) || item.vatRateBps > 10_000) return suppressPurchase("line_money_invalid");
+    const catalogNet = netFromGross(item.catalogTotalGross, item.vatRateBps);
+    const netDiscount = catalogNet - item.effectiveNet;
+    if (netDiscount < 0) return suppressPurchase("net_discount_invalid");
+    const projected = allocateLineItems({ sku: item.sku, variantCode: item.variantCode,
+      quantity: item.quantity, effectiveNet: item.effectiveNet, netDiscount });
+    if (items.length + projected.length > MAX_ITEMS) return suppressPurchase("item_limit_exceeded");
+    items.push(...projected);
+    effectiveNet += item.effectiveNet;
+  }
+  const tax = recap.totals.tax.amountMinor;
+  const total = recap.totals.total.amountMinor;
+  const effectiveShippingNet = total - tax - effectiveNet;
+  if (!isNonNegativeSafeInteger(effectiveShippingNet)) return suppressPurchase("shipping_net_invalid");
+  return { transaction_id: recap.orderId, currency: recap.totals.total.currency, value: effectiveNet / 100,
+    shipping: effectiveShippingNet / 100, tax: tax / 100,
+    checkout_mode: recap.checkoutKind === "one_time" ? "one_time" : "subscription", items };
+}
+function allocateLineItems(input: { sku: string; variantCode: string | null; quantity: number;
+  effectiveNet: number; netDiscount: number }): AnalyticsPurchaseItem[] {
+  const priceBase = Math.floor(input.effectiveNet / input.quantity);
+  const priceRemainder = input.effectiveNet % input.quantity;
+  const discountBase = Math.floor(input.netDiscount / input.quantity);
+  const discountRemainder = input.netDiscount % input.quantity;
+  const grouped = new Map<string, { priceMinor: number; discountMinor: number; quantity: number }>();
+  for (let position = 0; position < input.quantity; position += 1) {
+    const priceMinor = priceBase + (position < priceRemainder ? 1 : 0);
+    const discountMinor = discountBase + (position < discountRemainder ? 1 : 0);
+    const key = `${priceMinor}:${discountMinor}`;
+    const current = grouped.get(key);
+    if (current) current.quantity += 1;
+    else grouped.set(key, { priceMinor, discountMinor, quantity: 1 });
+  }
+  return [...grouped.values()].map(group => ({ item_id: input.sku,
+    ...(input.variantCode ? { item_variant: input.variantCode } : {}), price: group.priceMinor / 100,
+    discount: group.discountMinor / 100, quantity: group.quantity }));
+}
+function netFromGross(grossMinor: number, vatRateBps: number): number {
+  return Math.round(grossMinor * 10_000 / (10_000 + vatRateBps));
+}
+function isNonNegativeSafeInteger(value: number): boolean { return Number.isSafeInteger(value) && value >= 0; }

package/src/marketing/analytics/routePolicy.ts

@@ -0,0 +1,55 @@
+import type { AnalyticsRoutePolicyInput } from "../contracts/analytics.js";
+export type { AnalyticsRoutePolicyInput } from "../contracts/analytics.js";
+const CAMPAIGN_KEYS = ["utm_source", "utm_medium", "utm_campaign", "utm_content", "utm_term"] as const;
+const CAMPAIGN_VALUE = /^[A-Za-z0-9_-]{1,100}$/;
+const NO_ADDITIONAL_PATHS: ReadonlySet<string> = new Set();
+
+export function normalizeAnalyticsPathname(pathname: string): string {
+  const withLeadingSlash = pathname.startsWith("/") ? pathname : `/${pathname}`;
+  const withoutTrailingSlash = withLeadingSlash.length > 1
+    ? withLeadingSlash.replace(/\/+$/, "") : withLeadingSlash;
+  return withoutTrailingSlash.toLowerCase();
+}
+
+/** Route manifests and sensitive paths are explicit host policy. */
+export function createAnalyticsRoutePolicy(input: AnalyticsRoutePolicyInput) {
+  const manifestPaths = new Set(input.publicPaths.map(normalizeAnalyticsPathname));
+  const redirectPaths = new Set(input.redirectSources.filter(source => !source.includes(":"))
+    .map(normalizeAnalyticsPathname));
+  function isSensitiveAnalyticsPath(pathname: string): boolean {
+    const capabilityPath = pathname.toLowerCase();
+    return input.privatePathPrefixes.some(prefix => pathname === prefix || pathname.startsWith(`${prefix}/`))
+      || input.privateAuthPaths.includes(pathname)
+      || input.capabilityPathPrefixes.some(prefix => capabilityPath === prefix || capabilityPath.startsWith(`${prefix}/`));
+  }
+  function isOptionalAnalyticsRouteEligible(pathname: string): boolean {
+    return !isSensitiveAnalyticsPath(pathname);
+  }
+  function isDeploymentAnalyticsRouteEligible(pathname: string,
+    additionalPublicPaths: ReadonlySet<string> = NO_ADDITIONAL_PATHS): boolean {
+    const path = normalizeAnalyticsPathname(pathname);
+    if (isSensitiveAnalyticsPath(path)) return false;
+    return manifestPaths.has(path) || redirectPaths.has(path) || additionalPublicPaths.has(path);
+  }
+  function sanitizeDeploymentAnalyticsUrl(rawUrl: string, currentOrigin: string,
+    additionalPublicPaths?: ReadonlySet<string>): string | null {
+    let base: URL;
+    let url: URL;
+    try { base = new URL(currentOrigin); url = new URL(rawUrl, base); } catch { return null; }
+    if ((url.protocol !== "http:" && url.protocol !== "https:") || url.username || url.password
+      || url.origin !== base.origin) return null;
+    const pathname = normalizeAnalyticsPathname(url.pathname);
+    if (!isDeploymentAnalyticsRouteEligible(pathname, additionalPublicPaths)) return null;
+    const campaign = new URLSearchParams();
+    for (const key of CAMPAIGN_KEYS) {
+      const values = url.searchParams.getAll(key);
+      if (values.length === 1 && CAMPAIGN_VALUE.test(values[0]!)) campaign.set(key, values[0]!);
+    }
+    url.pathname = pathname;
+    url.search = campaign.toString();
+    url.hash = "";
+    return url.href;
+  }
+  return { isSensitiveAnalyticsPath, isOptionalAnalyticsRouteEligible,
+    isDeploymentAnalyticsRouteEligible, sanitizeDeploymentAnalyticsUrl };
+}

package/src/marketing/consentEvidence.ts

@@ -0,0 +1,36 @@
+import type { MarketingHistoricalConsentCommand, MarketingHistoricalConsentState, MarketingHistoricalConsentResult } from "./contracts/analytics.js";
+export type { MarketingHistoricalConsentCommand, MarketingHistoricalConsentState, MarketingHistoricalConsentResult } from "./contracts/analytics.js";
+import { z } from "./validation.js";
+
+const historicalTimestamp = z.string().max(80).datetime({ offset: true });
+const HISTORICAL_MIN_AGE_MS = 5 * 60 * 1000;
+
+/** Transport chronology after authorization; never changes the local consent grant. */
+export function selectMarketingHistoricalConsentTime(input: {
+  command: MarketingHistoricalConsentCommand; state: MarketingHistoricalConsentState; now: Date;
+}): MarketingHistoricalConsentResult {
+  const { command, state, now } = input;
+  if (!Number.isFinite(now.getTime())) return { kind: "hold", reason: "consent_time_invalid" };
+  let selected = command.consentedAt;
+  if (state.consent === "SUBSCRIBED") {
+    const native = historicalTimestamp.safeParse(state.nativeConsentAt);
+    if (!native.success || !Number.isFinite(Date.parse(native.data)) || Date.parse(native.data) >= now.getTime()) {
+      return { kind: "hold", reason: "provider_state_unknown" };
+    }
+    const overriding = state.suppressions.some(item => item.reason === "UNSUBSCRIBE"
+      && (item.listId === null || item.listId === command.listId));
+    if (!overriding) selected = native.data;
+    else if (Date.parse(command.consentedAt ?? "") > Date.parse(native.data)) {
+      return { kind: "hold", reason: "provider_state_unknown" };
+    }
+  }
+  const parsed = historicalTimestamp.safeParse(selected);
+  if (!parsed.success || !Number.isFinite(Date.parse(parsed.data)) || Date.parse(parsed.data) >= now.getTime()) {
+    return { kind: "hold", reason: "consent_time_invalid" };
+  }
+  // Parsing truncates fractional milliseconds; round only the age boundary up.
+  const discarded = /\.\d{3}(\d+)(?:Z|[+-]\d{2}:\d{2})$/.exec(parsed.data)?.[1];
+  const matureAt = Date.parse(parsed.data) + (discarded && /[1-9]/.test(discarded) ? 1 : 0) + HISTORICAL_MIN_AGE_MS;
+  return now.getTime() < matureAt ? { kind: "defer", retryAt: new Date(matureAt).toISOString() }
+    : { kind: "ready", providerConsentedAt: parsed.data };
+}

package/src/marketing/contactLegal.ts

@@ -0,0 +1,22 @@
+import type { ContactContent, LegalDocumentContent } from "./contracts/contactLegal.js";
+
+export function contactContent(facts: ContactContent) {
+  return {
+    supportEmail: facts.supportEmail,
+    companyLines: [
+      facts.organization.legalName,
+      facts.addressLine,
+      facts.registrationIdentifiers.map(({ label, value }) => `${label} ${value}`).join(" · "),
+      ...(facts.registrationAuthority !== undefined ? [facts.registrationAuthority] : []),
+    ],
+  };
+}
+
+export function legalDocumentContent(content: LegalDocumentContent) {
+  return {
+    title: content.title,
+    intro: content.intro,
+    sections: content.sections.map(({ title, body }) => ({ title, body })),
+    ...(content.lastUpdated !== undefined ? { lastUpdated: content.lastUpdated } : {}),
+  };
+}

package/src/marketing/contracts/acquisition.ts

@@ -0,0 +1,50 @@
+export type AcquisitionOpaqueReference = string;
+export type AcquisitionAddressReference = { source: string; reference: string; revision: string; provenance: string };
+export type AcquisitionCaseState = "submitted" | "approved" | "active" | "rejected" | "withdrawn";
+export type AcquisitionCaseProjection = {
+  contractVersion: "tester_application_v1";
+  caseRef: string;
+  contactRef: string;
+  sourceKind: "tester_application";
+  consent: { consentVersion: string; policyVersion: string; recordedAt: string; locale: "en" | "pl"; sourcePath: "/tester-application" };
+  addressReference: AcquisitionAddressReference | null;
+  state: AcquisitionCaseState;
+  version: number;
+  createdAt: string;
+  updatedAt: string;
+};
+export type AcquisitionCaseListRequest = { view: "acquisition_case_v1"; cursor?: string | undefined; limit: number };
+export type AcquisitionCaseListResponse = { contractVersion: "tester_application_v1"; cases: AcquisitionCaseProjection[]; nextCursor: string | null };
+export type AcquisitionCaseActiveCountResponse = { activeTesterCount: number };
+export type AcquisitionIdempotencyKey = string;
+export type AcquisitionSurveySubmit = { view: "acquisition_survey_v1"; caseReference: string; surveyType: "producer" | "consumer"; responseData: Record<string, unknown> };
+export type AcquisitionSurveyEvidence = {
+  evidenceReference: string;
+  caseReference: string;
+  contactReference: string;
+  surveyType: "producer" | "consumer";
+  responseDigest: string;
+  answerCount: number;
+  recordedAt: string;
+};
+export type AcquisitionSurveySubmitResponse = { contractVersion: "acquisition_survey_v1"; evidence: AcquisitionSurveyEvidence; replayed: boolean };
+export type AcquisitionSurveyListQuery = { view: "acquisition_survey_v1"; surveyType?: "producer" | "consumer" | undefined; limit: number };
+export type AcquisitionSurveyListResponse = { contractVersion: "acquisition_survey_v1"; rows: AcquisitionSurveyEvidence[]; totalCount: number };
+export type AcquisitionNewsletterConsentEvent = {
+  contractVersion: "acquisition_newsletter_consent_v1";
+  caseReference: string;
+  contactReference: string;
+  eventReference: string;
+  eventType: "subscribe" | "unsubscribe" | "suppress" | "complaint" | "update";
+  purpose: "marketing_launch_offer" | "marketing_newsletter";
+  explicitOptInEvidence: boolean;
+  occurredAt: string;
+};
+export type AcquisitionNewsletterConsentResponse = {
+  contractVersion: "acquisition_newsletter_consent_v1";
+  eventReference: string;
+  outcome: "applied" | "ignored" | "stale";
+  consentState: "granted" | "suppressed" | null;
+  auditReference: string;
+  replayed: boolean;
+};

package/src/marketing/contracts/acquisitionPorts.ts

@@ -0,0 +1,48 @@
+import type {
+  AcquisitionCaseListResponse, AcquisitionCaseProjection, AcquisitionNewsletterConsentEvent,
+  AcquisitionNewsletterConsentResponse, AcquisitionSurveyListQuery, AcquisitionSurveyListResponse,
+  AcquisitionSurveySubmit, AcquisitionSurveySubmitResponse,
+} from "./acquisition.js";
+
+export type AcquisitionCaseFailureKind =
+  | "conflict"
+  | "invalid"
+  | "not_found"
+  | "rate_limited"
+  | "unavailable";
+
+export type AcquisitionCaseResult<T> =
+  | { ok: true; value: T; replayed?: boolean }
+  | { ok: false; error: { kind: AcquisitionCaseFailureKind } };
+
+export interface AcquisitionCaseListQuery {
+  actorRef: string;
+  scope: "public_tester_application";
+  cursor?: string;
+  limit: number;
+}
+
+export interface AcquisitionCaseGetQuery {
+  actorRef: string;
+  scope: "public_tester_application";
+  caseRef: string;
+}
+
+export interface AcquisitionCasePort {
+  list(query: AcquisitionCaseListQuery): Promise<AcquisitionCaseResult<AcquisitionCaseListResponse>>;
+  get(query: AcquisitionCaseGetQuery): Promise<AcquisitionCaseResult<AcquisitionCaseProjection>>;
+  activeCount(scope: "public_tester_application"): Promise<AcquisitionCaseResult<number>>;
+  close(): Promise<void>;
+}
+
+export type AcquisitionEvidenceFailure = "invalid" | "not_found" | "conflict" | "unavailable";
+export type AcquisitionEvidenceResult<T> =
+  | { ok: true; value: T }
+  | { ok: false; error: { kind: AcquisitionEvidenceFailure } };
+
+export interface AcquisitionEvidencePort {
+  submitSurvey(input: AcquisitionSurveySubmit & { idempotencyKey: string }): Promise<AcquisitionEvidenceResult<AcquisitionSurveySubmitResponse>>;
+  listSurveys(input: AcquisitionSurveyListQuery & { actorReference: string }): Promise<AcquisitionEvidenceResult<AcquisitionSurveyListResponse>>;
+  applyNewsletterConsent(input: AcquisitionNewsletterConsentEvent): Promise<AcquisitionEvidenceResult<AcquisitionNewsletterConsentResponse>>;
+  close(): Promise<void>;
+}

package/src/marketing/contracts/analytics.ts

@@ -0,0 +1,88 @@
+/** The host supplies its own literal step vocabulary. */
+export type AnalyticsStepName<StepName extends string = string> = StepName;
+export interface AnalyticsCheckoutItem { item_id: string; quantity: number }
+export interface AnalyticsPurchaseItem extends AnalyticsCheckoutItem {
+  item_variant?: string;
+  price: number;
+  discount: number;
+}
+export type AnalyticsCheckoutMode = "one_time" | "subscription";
+/** No answer describes an ended wait, without asserting payment failure. */
+export type AnalyticsPaymentWaitOutcome = "confirmed" | "refused" | "no_answer";
+export interface AnalyticsEventMap<StepName extends string = string> {
+  page_view: { page_path: string };
+  configurator_start: { entry_view: "hero" | "configurator" };
+  configurator_step_view: { step_number: number; step_name: AnalyticsStepName<StepName> };
+  begin_checkout: { checkout_mode: AnalyticsCheckoutMode; items: AnalyticsCheckoutItem[] };
+  purchase: {
+    transaction_id: string;
+    currency: string;
+    value: number;
+    shipping: number;
+    tax: number;
+    checkout_mode: AnalyticsCheckoutMode;
+    items: AnalyticsPurchaseItem[];
+  };
+  // Wait observations carry no identity, amount, currency or payment method.
+  payment_wait_start: { checkoutMode: AnalyticsCheckoutMode };
+  payment_wait_end: { outcome: AnalyticsPaymentWaitOutcome; checkoutMode: AnalyticsCheckoutMode };
+  configurator_draft_restored: { draft_context: "public" };
+  configurator_draft_save_failed: { draft_context: "public"; reason: "unavailable" | "quota" | "conflict" };
+  configurator_draft_reset: { draft_context: "public" };
+}
+export type AnalyticsEventName = keyof AnalyticsEventMap;
+
+export interface AnalyticsSinkAttemptMask { deployment: boolean; optional: boolean }
+/** Synchronous local acceptance only; never transport delivery or business acknowledgement. */
+export interface AnalyticsSinkAdmission { deployment: boolean; optional: boolean }
+export interface AnalyticsCookieConsent {
+  necessary: boolean; functional: boolean; analytics: boolean; marketing: boolean;
+}
+export type AnalyticsBrowserWindow = Pick<Window, "localStorage" | "addEventListener" | "removeEventListener"> & {
+  dataLayer?: unknown[];
+};
+export interface AnalyticsDataLayerOptions<StepName extends string = string> {
+  consentStorageKey?: string;
+  consentChangeEvent?: string;
+  /** Host wire names, analytics first then advertising in supplied order. Omission disables consent commands and optional event admission. */
+  consentSignalNames?: { analytics: string; advertising: readonly string[] };
+  eventPrefix?: string;
+  readContainerId?: () => string | null;
+  trackDeploymentEvent?: <K extends AnalyticsEventName>(event: K, properties: AnalyticsEventMap<StepName>[K]) => boolean;
+  getWindow?: () => AnalyticsBrowserWindow | undefined;
+}
+
+export interface AnalyticsRoutePolicyInput {
+  publicPaths: readonly string[];
+  redirectSources: readonly string[];
+  privatePathPrefixes: readonly string[];
+  privateAuthPaths: readonly string[];
+  capabilityPathPrefixes: readonly string[];
+}
+
+/** Only paid recap facts read by the projection; money remains the host's truth. */
+export interface PurchaseOrder {
+  orderId: string;
+  status: string;
+  paymentStatus: string | null;
+  checkoutKind: "one_time" | "subscription_initial" | "subscription_renewal" | null;
+  moneyReconciled: boolean;
+  items: Array<{ sku: string | null; variantCode: string | null; quantity: number;
+    catalogTotalGross: number; effectiveNet: number; vatRateBps: number }>;
+  totals: { tax: { amountMinor: number }; total: { amountMinor: number; currency: string } };
+}
+export type PurchaseSuppressionReason = "order_not_paid" | "payment_not_succeeded"
+  | "checkout_kind_unsupported" | "money_unreconciled" | "items_empty" | "sku_missing"
+  | "quantity_invalid" | "line_money_invalid" | "net_discount_invalid"
+  | "item_limit_exceeded" | "shipping_net_invalid";
+
+export interface MarketingHistoricalConsentCommand { consentedAt: string | null; listId: string | null }
+/** Native state literals are compatibility inputs supplied by the host adapter. */
+export interface MarketingHistoricalConsentState {
+  consent: "SUBSCRIBED" | "UNSUBSCRIBED" | "NEVER_SUBSCRIBED" | "unknown";
+  nativeConsentAt?: string | null;
+  suppressions: Array<{ reason: "UNSUBSCRIBE" | "SPAM_REPORT" | "USER_SUPPRESSED" | "HARD_BOUNCE" | "INVALID_EMAIL" | "unknown";
+    listId: string | null }>;
+}
+export type MarketingHistoricalConsentResult = { kind: "ready"; providerConsentedAt: string }
+  | { kind: "defer"; retryAt: string } | { kind: "hold"; reason: string };