@openlup/platform 0.28.0 → 0.29.0

package/release-gates.json

@@ -599,6 +599,73 @@
       ],
       "entrypoint": "dist/account-support/contracts/index.d.ts",
       "snapshot": "api/account-support-contracts.api.md"
+    },
+    "./marketing": {
+      "role": "capability",
+      "maturity": "experimental",
+      "compatibilityPolicy": "internal-candidate",
+      "packageSmokeEvidence": [
+        "test/packageBoundary.test.ts",
+        "test/marketing/schemas.test.ts",
+        "test/marketing/contracts.test.ts",
+        "test/marketing/browserBoundary.test.ts",
+        "test/marketing/noop.test.ts",
+        "test/marketing/dataLayer.test.ts",
+        "test/marketing/routePolicy.test.ts",
+        "test/marketing/purchaseFacts.test.ts",
+        "test/marketing/consentEvidence.test.ts"
+      ],
+      "entrypoint": "dist/marketing/index.d.ts",
+      "snapshot": "api/marketing.api.md"
+    },
+    "./marketing/contracts": {
+      "role": "capability",
+      "maturity": "experimental",
+      "compatibilityPolicy": "internal-candidate",
+      "packageSmokeEvidence": [
+        "test/packageBoundary.test.ts",
+        "test/marketing/schemas.test.ts",
+        "test/marketing/contracts.test.ts",
+        "test/marketing/browserBoundary.test.ts",
+        "test/marketing/noop.test.ts",
+        "test/marketing/dataLayer.test.ts",
+        "test/marketing/routePolicy.test.ts",
+        "test/marketing/purchaseFacts.test.ts",
+        "test/marketing/consentEvidence.test.ts"
+      ],
+      "entrypoint": "dist/marketing/contracts/index.d.ts",
+      "snapshot": "api/marketing-contracts.api.md"
+    },
+    "./marketing/server": {
+      "role": "capability",
+      "maturity": "experimental",
+      "compatibilityPolicy": "internal-candidate",
+      "packageSmokeEvidence": [
+        "test/packageBoundary.test.ts",
+        "test/marketing/browserBoundary.test.ts",
+        "test/marketing/server/acquisitionCaseHandlers.test.ts",
+        "test/marketing/server/acquisitionCaseDirect.test.ts",
+        "test/marketing/server/prelaunchAcquisitionDirect.test.ts",
+        "test/marketing/server/acquisitionEvidenceDirect.test.ts",
+        "test/marketing/server/research/surveyResponseSubmitHandler.test.ts",
+        "test/marketing/server/research/adminSurveyResponsesHandler.test.ts",
+        "test/marketing/server/research/managedSurveyResponseSubmit.test.ts",
+        "test/marketing/analyticsContext.test.ts"
+      ],
+      "entrypoint": "dist/marketing/server/index.d.ts",
+      "snapshot": "api/marketing-server.api.md"
+    },
+    "./marketing/server/postgres": {
+      "role": "capability",
+      "maturity": "experimental",
+      "compatibilityPolicy": "internal-candidate",
+      "packageSmokeEvidence": [
+        "test/packageBoundary.test.ts",
+        "test/marketing/server/postgres/acquisitionCaseRoutines.test.ts",
+        "test/marketing/server/postgres/acquisitionEvidenceRoutines.test.ts"
+      ],
+      "entrypoint": "dist/marketing/server/postgres/index.d.ts",
+      "snapshot": "api/marketing-server-postgres.api.md"
     }
   },
   "pack": {
@@ -607,15 +674,15 @@
       "maxFiles": 2520
     },
     "docs": {
-      "maxPackedBytes": 57344,
+      "maxPackedBytes": 73728,
       "maxFiles": 10
     },
     "maxPackedBytes": 1925000,
     "maxUnpackedBytes": 8970000,
     "maxFiles": 2580,
     "baseline": {
-      "version": "0.27.0",
-      "packedBytes": 1734781
+      "version": "0.28.0",
+      "packedBytes": 1807006
     },
     "browserEntries": {
       "./catalog/contracts": 4096,
@@ -631,7 +698,8 @@
       "./invoicing/contracts": 32,
       "./commerce/contracts": 32,
       "./pricing/browser": 25600,
-      "./account-support/contracts": 32
+      "./account-support/contracts": 32,
+      "./marketing/contracts": 32
     }
   }
 }

package/src/composition/index.ts

@@ -23,3 +23,4 @@ export { createFulfillmentContribution } from "./fulfillmentContribution.js";
 export { createSubscriptionContribution } from "./subscriptionContribution.js";
 export { createCommerceContribution } from "./commerceContribution.js";
 export { createAccountSupportContribution } from "./accountSupportContribution.js";
+export { createMarketingContribution } from "./marketingContribution.js";

package/src/composition/marketingContribution.ts

@@ -0,0 +1,37 @@
+import type { Contribution, RequiredSchema } from "@openlup/core/readiness";
+
+/** Describe existing selected marketing callables; never install another executor. */
+export function createMarketingContribution(input: {
+  version: string;
+  requiredSchema: RequiredSchema;
+  marketing: Readonly<Record<string, ((...args: never[]) => unknown) | null>>;
+  handlers: Contribution["handlers"];
+  schedules: Contribution["schedules"];
+  routes: Contribution["routes"];
+}) {
+  for (const [kind, names] of [
+    ["handler", input.handlers.map(handler => handler.eventType)],
+    ["schedule", input.schedules.map(schedule => schedule.id)],
+    ["route", input.routes.map(route => route.id)],
+  ] as const) {
+    if (new Set(names).size !== names.length) throw new Error(`marketing_duplicate_${kind}`);
+  }
+  const contribution: Contribution = {
+    manifest: {
+      name: "@openlup/platform", version: input.version, kind: "rail",
+      module: { id: "marketing", kind: "capability", provides: ["./marketing", "./marketing/contracts", "./marketing/server"],
+        // The server entry validates obligations with identity's runtime contract schema.
+        dependsOn: [{ module: "identity", entries: ["./identity/contracts"] }] },
+      emits: [], handles: input.handlers.map(handler => handler.eventType),
+      schedules: input.schedules.map(({ id, cadenceSeconds }) => ({ id, cadenceSeconds })), env: [],
+      requiredPorts: Object.keys(input.marketing), routes: input.routes.map(route => route.id), requiredSchema: input.requiredSchema,
+    },
+    handlers: input.handlers.map(({ eventType, timeoutMs }) => Object.freeze({ eventType, timeoutMs })), schedules: input.schedules, routes: input.routes,
+  };
+  return {
+    contributions: [contribution],
+    ports: Object.fromEntries(Object.entries(input.marketing).filter(([, fn]) => typeof fn === "function").map(([name, fn]) => [`@openlup/platform/marketing:${name}`, fn])),
+    routes: Object.fromEntries(input.routes.map(route => [`@openlup/platform/marketing:${route.id}`, route.handle])),
+    triggers: Object.fromEntries(input.schedules.map(schedule => [`@openlup/platform/marketing:${schedule.id}`, schedule.run])),
+  };
+}

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