@openlup/platform 0.27.0 → 0.29.0

package/src/marketing/contracts/contactLegal.ts

@@ -0,0 +1,41 @@
+export interface OrganizationFacts {
+  name: string;
+  legalName: string;
+  url: string;
+  logo: { url: string; contentUrl: string; width: number; height: number };
+  email: string;
+  vatID: string;
+  taxID: string;
+  areaServed: string;
+  sameAs: string[];
+  contactPoint: { email: string; contactType: string; availableLanguage: string[] };
+  address: {
+    streetAddress: string;
+    addressLocality: string;
+    postalCode: string;
+    addressRegion: string;
+    addressCountry: string;
+  };
+}
+
+export interface ContactContent {
+  organization: OrganizationFacts;
+  supportEmail: string;
+  addressLine: string;
+  registrationIdentifiers: { label: string; value: string }[];
+  registrationAuthority?: string;
+}
+
+export interface LegalDocumentContent {
+  title: string;
+  intro: string;
+  sections: { title: string; body: string }[];
+  lastUpdated?: string;
+}
+
+export interface PrivacyProcessorDisclosure {
+  processorName: string;
+  purpose: string;
+  dataCategories: string[];
+  details?: string;
+}

package/src/marketing/contracts/index.ts

@@ -0,0 +1,17 @@
+export type * from "./acquisition.js";
+export type {
+  MarketingResearchJson,
+  ResearchSurveyType,
+  AdminSurveyResponsesRequest,
+  AdminSurveyResponseRow,
+  AdminSurveyResponsesResponse,
+  ResearchSurveySubmitRequest,
+  ResearchSurveySubmitResponse,
+  MarketingResearchSurveyResponsesReadPort,
+  MarketingResearchSurveyRequestHeaders,
+  MarketingResearchSurveySubmitPort,
+} from "@openlup/core/marketing/research";
+export type * from "./acquisitionPorts.js";
+export type * from "./prelaunch.js";
+export type * from "./analytics.js";
+export type * from "./contactLegal.js";

package/src/marketing/contracts/prelaunch.ts

@@ -0,0 +1,15 @@
+export type PrelaunchAcquisitionListRequest = { view: "prelaunch_acquisition_v1"; cursor?: string | undefined; limit: number };
+export type PrelaunchAcquisitionDetailRequest = { sourceRef: string };
+export type PrelaunchAcquisitionLead = {
+  sourceRef: string;
+  contactRef: string;
+  sourceKind: "tester_application";
+  consent: { consentVersion: string; policyVersion: string; recordedAt: string; locale: "en" | "pl"; sourcePath: "/tester-application" };
+  addressReference: { source: string; reference: string; revision: string; provenance: string } | null;
+  state: "submitted" | "approved" | "active" | "rejected" | "withdrawn";
+  version: number;
+  createdAt: string;
+  updatedAt: string;
+};
+export type PrelaunchAcquisitionListResponse = { contractVersion: "prelaunch_acquisition_v1"; leads: PrelaunchAcquisitionLead[]; nextCursor: string | null };
+export type PrelaunchAcquisitionDetailResponse = { contractVersion: "prelaunch_acquisition_v1"; lead: PrelaunchAcquisitionLead };

package/src/marketing/index.ts

@@ -0,0 +1,16 @@
+export * from "./acquisitionCaseSchemas.js";
+export * from "./acquisitionEvidenceSchemas.js";
+export * from "@openlup/core/marketing/research";
+export * from "./prelaunchAcquisitionSchemas.js";
+export type * from "./contracts/acquisitionPorts.js";
+export * from "./analytics/noop.js";
+export * from "./analytics/dataLayer.js";
+export * from "./analytics/routePolicy.js";
+export * from "./analytics/purchaseFacts.js";
+export * from "./consentEvidence.js";
+export * from "./seo/serializeJsonLd.js";
+export * from "./seo/urls.js";
+export * from "./seo/metadata.js";
+export * from "./seo/jsonLd.js";
+export type * from "./contracts/contactLegal.js";
+export * from "./contactLegal.js";

package/src/marketing/prelaunchAcquisitionSchemas.ts

@@ -0,0 +1,64 @@
+import { z } from "./validation.js";
+
+export const PRELAUNCH_ACQUISITION_VIEW = "prelaunch_acquisition_v1" as const;
+export const PRELAUNCH_ACQUISITION_CONTRACT_VERSION = "prelaunch_acquisition_v1" as const;
+
+const acquisitionCaseRefSchema = z.string().regex(/^acquisition-case:[0-9a-f-]{36}$/);
+const acquisitionContactRefSchema = z.string().regex(/^acquisition-contact:[0-9a-f-]{36}$/);
+const acquisitionOpaqueRefSchema = z.string().trim().min(8).max(160)
+  .regex(/^[A-Za-z0-9][A-Za-z0-9._:-]*$/);
+const acquisitionDateTimeSchema = z.string().datetime({ offset: true });
+
+export const prelaunchAcquisitionListRequestSchema = z.object({
+  view: z.literal(PRELAUNCH_ACQUISITION_VIEW),
+  cursor: acquisitionOpaqueRefSchema.optional(),
+  limit: z.coerce.number().int().min(1).max(100).default(25),
+}).strict();
+
+export const prelaunchAcquisitionDetailRequestSchema = z.object({
+  sourceRef: acquisitionCaseRefSchema,
+}).strict();
+
+export const prelaunchAcquisitionLeadSchema = z.object({
+  sourceRef: acquisitionCaseRefSchema,
+  contactRef: acquisitionContactRefSchema,
+  sourceKind: z.literal("tester_application"),
+  consent: z.object({
+    consentVersion: z.string().min(1).max(64),
+    policyVersion: z.string().min(1).max(64),
+    recordedAt: acquisitionDateTimeSchema,
+    locale: z.enum(["en", "pl"]),
+    sourcePath: z.literal("/tester-application"),
+  }).strict(),
+  addressReference: z.object({
+    source: z.string().trim().min(1).max(48).regex(/^[a-z][a-z0-9_-]*$/),
+    reference: acquisitionOpaqueRefSchema,
+    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().nullable(),
+  state: z.enum(["submitted", "approved", "active", "rejected", "withdrawn"]),
+  version: z.number().int().positive(),
+  createdAt: acquisitionDateTimeSchema,
+  updatedAt: acquisitionDateTimeSchema,
+}).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 prelaunchAcquisitionListResponseSchema = z.object({
+  contractVersion: z.literal(PRELAUNCH_ACQUISITION_CONTRACT_VERSION),
+  leads: z.array(prelaunchAcquisitionLeadSchema).max(100),
+  nextCursor: acquisitionOpaqueRefSchema.nullable(),
+}).strict();
+
+export const prelaunchAcquisitionDetailResponseSchema = z.object({
+  contractVersion: z.literal(PRELAUNCH_ACQUISITION_CONTRACT_VERSION),
+  lead: prelaunchAcquisitionLeadSchema,
+}).strict();
+
+export type PrelaunchAcquisitionListRequest = z.infer<typeof prelaunchAcquisitionListRequestSchema>;
+export type PrelaunchAcquisitionDetailRequest = z.infer<typeof prelaunchAcquisitionDetailRequestSchema>;
+export type PrelaunchAcquisitionLead = z.infer<typeof prelaunchAcquisitionLeadSchema>;
+export type PrelaunchAcquisitionListResponse = z.infer<typeof prelaunchAcquisitionListResponseSchema>;
+export type PrelaunchAcquisitionDetailResponse = z.infer<typeof prelaunchAcquisitionDetailResponseSchema>;

package/src/marketing/seo/jsonLd.ts

@@ -0,0 +1,153 @@
+import type { OrganizationFacts } from "../contracts/contactLegal.js";
+
+export type JsonLdNode = Record<string, unknown> & { "@context"?: string; "@id"?: string };
+
+export function jsonLdGraph(...nodes: JsonLdNode[]) {
+  const seen = new Set<string>();
+  const graph = nodes.flatMap(({ "@context": _context, ...node }) => {
+    if (node["@id"] && seen.has(node["@id"] as string)) return [];
+    if (node["@id"]) seen.add(node["@id"] as string);
+    return [node];
+  });
+  return { "@context": "https://schema.org", "@graph": graph };
+}
+
+export function entityIds(origin: string) {
+  const site = origin.replace(/\/$/, "");
+  return {
+    organization: `${site}/#organization`,
+    website: `${site}/#website`,
+    brand: `${site}/#brand`,
+  };
+}
+
+export function organizationLd(origin: string, type: "Organization" | "OnlineStore", facts: OrganizationFacts) {
+  return {
+    "@context": "https://schema.org",
+    "@id": entityIds(origin).organization,
+    "@type": type,
+    name: facts.name,
+    legalName: facts.legalName,
+    url: facts.url,
+    logo: {
+      "@type": "ImageObject",
+      url: facts.logo.url,
+      contentUrl: facts.logo.contentUrl,
+      width: facts.logo.width,
+      height: facts.logo.height,
+    },
+    email: facts.email,
+    vatID: facts.vatID,
+    taxID: facts.taxID,
+    areaServed: facts.areaServed,
+    sameAs: facts.sameAs,
+    contactPoint: {
+      "@type": "ContactPoint",
+      email: facts.contactPoint.email,
+      contactType: facts.contactPoint.contactType,
+      availableLanguage: facts.contactPoint.availableLanguage,
+    },
+    address: {
+      "@type": "PostalAddress",
+      streetAddress: facts.address.streetAddress,
+      addressLocality: facts.address.addressLocality,
+      postalCode: facts.address.postalCode,
+      addressRegion: facts.address.addressRegion,
+      addressCountry: facts.address.addressCountry,
+    },
+  };
+}
+
+export function brandLd(origin: string, name: string, url: string) {
+  return { "@context": "https://schema.org", "@id": entityIds(origin).brand, "@type": "Brand", name, url };
+}
+
+export function websiteLd(origin: string, name: string, url: string, inLanguage: string[]) {
+  return {
+    "@context": "https://schema.org",
+    "@id": entityIds(origin).website,
+    "@type": "WebSite",
+    name,
+    url,
+    inLanguage,
+    publisher: { "@id": entityIds(origin).organization },
+  };
+}
+
+export function contactPageLd(origin: string, pageUrl: string) {
+  return {
+    "@context": "https://schema.org",
+    "@id": `${pageUrl.replace(/\/$/, "")}#webpage`,
+    "@type": "ContactPage",
+    url: pageUrl,
+    publisher: { "@id": entityIds(origin).organization },
+    mainEntity: { "@id": entityIds(origin).organization },
+  };
+}
+
+export interface NetContent { unscaled: number; scale: number; unit: string }
+
+export function schemaWeight(netContent: NetContent) {
+  const { unscaled, scale, unit } = netContent;
+  const unitCode = unit === "GRAM" || unit === "G" ? "GRM" : unit;
+  return { "@type": "QuantitativeValue", value: unscaled / 10 ** scale, unitCode };
+}
+
+export interface ProductFacts {
+  url: string;
+  name: string;
+  inLanguage: string;
+  brandName: string;
+  category?: string;
+  images: string[];
+  sku?: string;
+  gtin13?: string;
+  netContent?: NetContent;
+}
+
+export function productLd(origin: string, product: ProductFacts) {
+  return {
+    "@context": "https://schema.org",
+    "@id": `${product.url.replace(/\/$/, "")}#product`,
+    "@type": "Product",
+    name: product.name,
+    inLanguage: product.inLanguage,
+    brand: { "@id": entityIds(origin).brand, "@type": "Brand", name: product.brandName },
+    manufacturer: { "@id": entityIds(origin).organization },
+    ...(product.category !== undefined ? { category: product.category } : {}),
+    image: product.images,
+    ...(product.sku !== undefined ? { sku: product.sku } : {}),
+    ...(product.gtin13 !== undefined ? { gtin13: product.gtin13 } : {}),
+    ...(product.netContent ? { weight: schemaWeight(product.netContent) } : {}),
+    url: product.url,
+  };
+}
+
+const pageEntityId = (pageUrl: string, fragment: string) => `${pageUrl.replace(/\/$/, "")}#${fragment}`;
+
+export function faqPageLd(faqs: { question: string; answer: string }[], pageUrl: string) {
+  return {
+    "@context": "https://schema.org",
+    "@id": pageEntityId(pageUrl, "faq"),
+    "@type": "FAQPage",
+    mainEntity: faqs.map((faq) => ({
+      "@type": "Question",
+      name: faq.question,
+      acceptedAnswer: { "@type": "Answer", text: faq.answer },
+    })),
+  };
+}
+
+export function breadcrumbLd(items: { name: string; url?: string }[], pageUrl: string) {
+  return {
+    "@context": "https://schema.org",
+    "@id": pageEntityId(pageUrl, "breadcrumb"),
+    "@type": "BreadcrumbList",
+    itemListElement: items.map((item, index) => ({
+      "@type": "ListItem",
+      position: index + 1,
+      name: item.name,
+      ...(item.url ? { item: item.url } : {}),
+    })),
+  };
+}

package/src/marketing/seo/metadata.ts

@@ -0,0 +1,62 @@
+import { jsonLdGraph, type JsonLdNode } from "./jsonLd.js";
+import { serializeJsonLd } from "./serializeJsonLd.js";
+import { canonicalUrlForRoute, hreflangLinksForRoute, type SiteRoute } from "./urls.js";
+
+export type HeadTag =
+  | { kind: "meta"; name: string; content: string }
+  | { kind: "meta"; property: string; content: string }
+  | { kind: "link"; rel: "canonical" | "alternate"; href: string; hrefLang?: string };
+
+export interface HeadFacts {
+  origin: string;
+  route: SiteRoute;
+  routes: readonly SiteRoute[];
+  xDefaultLocale: string;
+  htmlLang: string;
+  title: string;
+  description: string;
+  siteName: string;
+  ogImage: string;
+  ogImageWidth: number;
+  ogImageHeight: number;
+  ogLocale: string;
+  alternateOgLocale?: string;
+  twitterImage: string;
+  twitterHandle: string;
+  noindex?: boolean;
+  jsonLd?: JsonLdNode | JsonLdNode[];
+}
+
+export function buildHeadDescriptor(facts: HeadFacts): { htmlLang: string; title: string; tags: HeadTag[]; jsonLd: string | null } {
+  const canonicalUrl = canonicalUrlForRoute(facts.origin, facts.route);
+  const nodes = facts.jsonLd ? (Array.isArray(facts.jsonLd) ? facts.jsonLd : [facts.jsonLd]) : [];
+  const tags: HeadTag[] = [
+    { kind: "meta", name: "description", content: facts.description },
+    { kind: "link", rel: "canonical", href: canonicalUrl },
+    ...(facts.noindex ? [{ kind: "meta" as const, name: "robots", content: "noindex, nofollow" }] : []),
+    { kind: "meta", property: "og:title", content: facts.title },
+    { kind: "meta", property: "og:description", content: facts.description },
+    { kind: "meta", property: "og:image", content: facts.ogImage },
+    { kind: "meta", property: "og:image:width", content: String(facts.ogImageWidth) },
+    { kind: "meta", property: "og:image:height", content: String(facts.ogImageHeight) },
+    { kind: "meta", property: "og:type", content: "website" },
+    { kind: "meta", property: "og:site_name", content: facts.siteName },
+    { kind: "meta", property: "og:url", content: canonicalUrl },
+    { kind: "meta", property: "og:locale", content: facts.ogLocale },
+    ...(facts.alternateOgLocale ? [{ kind: "meta" as const, property: "og:locale:alternate", content: facts.alternateOgLocale }] : []),
+    { kind: "meta", name: "twitter:card", content: "summary_large_image" },
+    { kind: "meta", name: "twitter:site", content: facts.twitterHandle },
+    { kind: "meta", name: "twitter:title", content: facts.title },
+    { kind: "meta", name: "twitter:description", content: facts.description },
+    { kind: "meta", name: "twitter:image", content: facts.twitterImage },
+    ...hreflangLinksForRoute(facts.origin, facts.route, facts.routes, facts.xDefaultLocale).map((link) => ({
+      kind: "link" as const, rel: "alternate" as const, hrefLang: link.hrefLang, href: link.href,
+    })),
+  ];
+  return {
+    htmlLang: facts.htmlLang,
+    title: facts.title,
+    tags,
+    jsonLd: nodes.length > 0 ? serializeJsonLd(jsonLdGraph(...nodes)) : null,
+  };
+}

package/src/marketing/seo/serializeJsonLd.ts

@@ -0,0 +1,6 @@
+export function serializeJsonLd(value: object): string {
+  return JSON.stringify(value)
+    .replace(/</g, "\\u003c")
+    .replace(/\u2028/g, "\\u2028")
+    .replace(/\u2029/g, "\\u2029");
+}

package/src/marketing/seo/urls.ts

@@ -0,0 +1,34 @@
+export interface SiteRoute {
+  id: string;
+  locale: string;
+  canonicalPath: string;
+  alternateRouteId?: string;
+}
+
+export interface HreflangLink { hrefLang: string; href: string }
+
+export function normalizeSitePath(pathname: string): string {
+  const path = pathname.startsWith("/") ? pathname : `/${pathname}`;
+  return path.length > 1 ? path.replace(/\/$/, "") : path;
+}
+
+export function absoluteSiteUrl(origin: string, pathname: string): string {
+  const site = origin.replace(/\/$/, "");
+  const path = normalizeSitePath(pathname);
+  return path === "/" ? `${site}/` : `${site}${path}`;
+}
+
+export function canonicalUrlForRoute(origin: string, route: SiteRoute): string {
+  return absoluteSiteUrl(origin, route.canonicalPath);
+}
+
+export function hreflangLinksForRoute(origin: string, route: SiteRoute, routes: readonly SiteRoute[], xDefaultLocale: string): HreflangLink[] {
+  const alternate = route.alternateRouteId ? routes.find((candidate) => candidate.id === route.alternateRouteId) : undefined;
+  if (!alternate) return [];
+  const pair = [route, alternate].sort((a, b) => a.locale.localeCompare(b.locale));
+  const preferred = pair.find((candidate) => candidate.locale === xDefaultLocale);
+  return [
+    ...pair.map((candidate) => ({ hrefLang: candidate.locale, href: canonicalUrlForRoute(origin, candidate) })),
+    { hrefLang: "x-default", href: canonicalUrlForRoute(origin, preferred ?? pair[0]) },
+  ];
+}

package/src/marketing/server/acquisitionCaseDirect.ts

@@ -0,0 +1,67 @@
+import type { HttpRequest, HttpResponse } from "../../http/index.js";
+import type { BffResponder } from "../../bff/index.js";
+import type { AcquisitionCaseDirectDeps, AcquisitionCaseBindingResolver } from "./directPorts.js";
+import { ACQUISITION_CASE_VIEW, acquisitionCaseActiveCountResponseSchema, acquisitionCaseListRequestSchema, acquisitionCaseListResponseSchema } from "../acquisitionCaseSchemas.js";
+import type { AcquisitionCaseFailureKind } from "../contracts/index.js";
+
+export function createAcquisitionCaseListDirectHandler(options: AcquisitionCaseDirectDeps) {
+  const { respond, authorize, resolveBinding, isDirect } = options;
+  const { sendBffSuccess, sendMethodNotAllowed } = respond;
+  return async (req: HttpRequest, res: HttpResponse): Promise<void> => {
+    if (!isDirect() || first(req.query.view) !== ACQUISITION_CASE_VIEW) return unavailable(res, respond);
+    if (req.method !== "GET") return sendMethodNotAllowed(res, ["GET"]);
+    const actorRef = await authorize(req, res);
+    if (!actorRef) return;
+    const request = acquisitionCaseListRequestSchema.safeParse({
+      view: first(req.query.view), cursor: first(req.query.cursor), limit: integer(first(req.query.limit), 25),
+    });
+    if (!request.success) return badRequest(res, respond, request.error.flatten());
+    const binding = await bindingOrError(res, respond, resolveBinding);
+    if (!binding) return;
+    const result = await operationOrError(res, respond, () => binding.handlers.list(actorRef, request.data));
+    if (!result) return;
+    if (result.ok === false) return failure(res, respond, result.error.kind);
+    const response = acquisitionCaseListResponseSchema.safeParse(result.value);
+    if (!response.success) return invalidResponse(res, respond);
+    sendBffSuccess(res, response.data);
+  };
+}
+
+export function createAcquisitionCaseActiveCountDirectHandler(options: AcquisitionCaseDirectDeps) {
+  const { respond, resolveBinding, isDirect } = options;
+  const { sendBffSuccess, sendMethodNotAllowed } = respond;
+  return async (req: HttpRequest, res: HttpResponse): Promise<void> => {
+    if (!isDirect()) return unavailable(res, respond);
+    if (req.method !== "GET") return sendMethodNotAllowed(res, ["GET"]);
+    const binding = await bindingOrError(res, respond, resolveBinding);
+    if (!binding) return;
+    const result = await operationOrError(res, respond, () => binding.handlers.activeCount());
+    if (!result) return;
+    if (result.ok === false) return failure(res, respond, result.error.kind);
+    const response = acquisitionCaseActiveCountResponseSchema.safeParse(result.value);
+    if (!response.success) return invalidResponse(res, respond);
+    sendBffSuccess(res, response.data);
+  };
+}
+
+async function bindingOrError(res: HttpResponse, respond: BffResponder, resolve: AcquisitionCaseBindingResolver) {
+  try { const binding = await resolve(); if (binding) return binding; } catch { /* fail closed below */ }
+  respond.sendBffError(res, "UPSTREAM_UNAVAILABLE", "Acquisition case service unavailable");
+  return null;
+}
+async function operationOrError<T>(res: HttpResponse, respond: BffResponder, operation: () => Promise<T>): Promise<T | null> {
+  try { return await operation(); } catch { respond.sendBffError(res, "UPSTREAM_UNAVAILABLE", "Acquisition case service unavailable"); return null; }
+}
+function first(value: string | string[] | undefined): string | undefined { return Array.isArray(value) ? value[0] : value; }
+function integer(value: string | undefined, fallback: number): number { return value === undefined ? fallback : Number(value); }
+function badRequest(res: HttpResponse, respond: BffResponder, details?: unknown): void { respond.sendBffError(res, "BAD_REQUEST", "Invalid acquisition case request", { details }); }
+function unavailable(res: HttpResponse, respond: BffResponder): void { respond.sendBffError(res, "NOT_FOUND", "Acquisition case unavailable"); }
+function invalidResponse(res: HttpResponse, respond: BffResponder): void { respond.sendBffError(res, "INVALID_RESPONSE", "Acquisition case returned invalid response"); }
+function failure(res: HttpResponse, respond: BffResponder, kind: AcquisitionCaseFailureKind): void {
+  if (kind === "invalid") return badRequest(res, respond);
+  if (kind === "conflict") return respond.sendBffError(res, "CONFLICT", "Acquisition case request conflicts with prior state");
+  if (kind === "rate_limited") return respond.sendBffError(res, "RATE_LIMITED", "Acquisition submission rate limited");
+  if (kind === "not_found") return unavailable(res, respond);
+  respond.sendBffError(res, "UPSTREAM_UNAVAILABLE", "Acquisition case service unavailable");
+}
+

package/src/marketing/server/acquisitionCaseHandlers.ts

@@ -0,0 +1,57 @@
+import { ACQUISITION_CASE_CONTRACT_VERSION, ACQUISITION_CASE_SOURCE } from "../acquisitionCaseSchemas.js";
+import type { AcquisitionCaseListRequest } from "../contracts/index.js";
+import { type AcquisitionCaseSubmitRequest, type AcquisitionCaseTransitionRequest } from "./acquisitionCasePorts.js";
+import type { AcquisitionCasePort } from "./acquisitionCasePorts.js";
+
+const SCOPE = "public_tester_application" as const;
+
+export interface AcquisitionCaseHandlerOptions {
+  now?: () => string;
+}
+
+export function createAcquisitionCaseHandlers(
+  port: AcquisitionCasePort,
+  options: AcquisitionCaseHandlerOptions = {},
+) {
+  const now = options.now ?? (() => new Date().toISOString());
+  return {
+    submit(request: AcquisitionCaseSubmitRequest, context: {
+      idempotencyKey: string;
+      requesterKey: string;
+    }) {
+      return port.submit({
+        scope: SCOPE,
+        sourceKind: ACQUISITION_CASE_SOURCE,
+        idempotencyKey: context.idempotencyKey,
+        requesterKey: `${SCOPE}:${context.requesterKey}`,
+        acceptedAt: now(),
+        sourcePath: "/tester-application",
+        request,
+      });
+    },
+    list(actorRef: string, request: AcquisitionCaseListRequest) {
+      return port.list({
+        actorRef,
+        scope: SCOPE,
+        ...(request.cursor ? { cursor: request.cursor } : {}),
+        limit: request.limit,
+      });
+    },
+    get(actorRef: string, caseRef: string) {
+      return port.get({ actorRef, scope: SCOPE, caseRef });
+    },
+    transition(actorRef: string, idempotencyKey: string, request: AcquisitionCaseTransitionRequest) {
+      return port.transition({ actorRef, scope: SCOPE, idempotencyKey, request });
+    },
+    async activeCount() {
+      const result = await port.activeCount(SCOPE);
+      return result.ok === false ? result : {
+        ok: true as const,
+        value: { activeTesterCount: result.value },
+      };
+    },
+    contractVersion: ACQUISITION_CASE_CONTRACT_VERSION,
+  };
+}
+
+export type AcquisitionCaseHandlers = ReturnType<typeof createAcquisitionCaseHandlers>;

package/src/marketing/server/acquisitionCasePorts.ts

@@ -0,0 +1,42 @@
+import type { AcquisitionCaseProjection, AcquisitionCaseResult, AcquisitionCasePort as PortableAcquisitionCasePort } from "../contracts/index.js";
+import type { AcquisitionAddressReference, AcquisitionCaseProjection as Projection } from "../contracts/index.js";
+
+/** Historical commands retained by the server adapter; public admission routes remain host-owned. */
+export interface AcquisitionCaseSubmitRequest {
+  contact: { email: string };
+  consent: { accepted: true; consentVersion: string; policyVersion: string; locale: Projection["consent"]["locale"] };
+  addressReference: AcquisitionAddressReference;
+}
+export interface AcquisitionCaseTransitionRequest {
+  view: "acquisition_case_v1";
+  caseRef: string;
+  expectedVersion: number;
+  transition: "approve" | "activate" | "reject" | "withdraw";
+  reason?: string | undefined;
+}
+
+export interface AcquisitionCaseSubmitCommand {
+  scope: "public_tester_application";
+  sourceKind: "tester_application";
+  idempotencyKey: string;
+  requesterKey: string;
+  acceptedAt: string;
+  sourcePath: "/tester-application";
+  request: AcquisitionCaseSubmitRequest;
+}
+
+export interface AcquisitionCaseTransitionCommand {
+  actorRef: string;
+  scope: "public_tester_application";
+  idempotencyKey: string;
+  request: AcquisitionCaseTransitionRequest;
+}
+
+export interface AcquisitionCasePort extends PortableAcquisitionCasePort {
+  submit(command: AcquisitionCaseSubmitCommand): Promise<AcquisitionCaseResult<AcquisitionCaseProjection>>;
+  transition(command: AcquisitionCaseTransitionCommand): Promise<AcquisitionCaseResult<AcquisitionCaseProjection>>;
+}
+
+export type {
+  AcquisitionCaseFailureKind, AcquisitionCaseResult, AcquisitionCaseListQuery, AcquisitionCaseGetQuery,
+} from "../contracts/index.js";

package/src/marketing/server/acquisitionEvidenceDirect.ts

@@ -0,0 +1,76 @@
+import { acquisitionNewsletterConsentEventSchema, acquisitionSurveyListQuerySchema, acquisitionSurveySubmitSchema } from "../acquisitionEvidenceSchemas.js";
+import type { HttpRequest, HttpResponse } from "../../http/index.js";
+import type { BffResponder } from "../../bff/index.js";
+import type { AcquisitionEvidenceFailure } from "../contracts/index.js";
+import type { AcquisitionEvidenceDirectDeps, AcquisitionEvidenceBindingResolver } from "./directPorts.js";
+
+export function createAcquisitionSurveySubmitDirectHandler(options: AcquisitionEvidenceDirectDeps) {
+  const { respond, resolveBinding } = options;
+  const { sendBffSuccess, sendMethodNotAllowed } = respond;
+  return async (req: HttpRequest, res: HttpResponse): Promise<void> => {
+    if (req.method !== "POST") return sendMethodNotAllowed(res, ["POST"]);
+    const request = acquisitionSurveySubmitSchema.safeParse(req.body);
+    const idempotencyKey = firstHeader(req.headers["idempotency-key"]);
+    if (!request.success || !idempotencyKey) return badRequest(res, respond, request.success ? undefined : request.error.flatten());
+    const binding = await bindingOrError(res, respond, resolveBinding); if (!binding) return;
+    const result = await safeOperation(() => binding.submitSurvey({ ...request.data, idempotencyKey }));
+    if (!result) return unavailable(res, respond);
+    if (result.ok === false) return failure(res, respond, result.error.kind);
+    sendBffSuccess(res, result.value);
+  };
+}
+
+export function createAcquisitionSurveyListDirectHandler(options: AcquisitionEvidenceDirectDeps) {
+  const { respond, authorize, resolveBinding } = options;
+  const { sendBffSuccess, sendMethodNotAllowed } = respond;
+  return async (req: HttpRequest, res: HttpResponse): Promise<void> => {
+    if (req.method !== "GET") return sendMethodNotAllowed(res, ["GET"]);
+    const actorReference = await authorize(req, res); if (!actorReference) return;
+    const request = acquisitionSurveyListQuerySchema.safeParse({
+      view: first(req.query.view), surveyType: first(req.query.surveyType), limit: first(req.query.limit) ?? "50",
+    });
+    if (!request.success) return badRequest(res, respond, request.error.flatten());
+    const binding = await bindingOrError(res, respond, resolveBinding); if (!binding) return;
+    const result = await safeOperation(() => binding.listSurveys({ ...request.data, actorReference }));
+    if (!result) return unavailable(res, respond);
+    if (result.ok === false) return failure(res, respond, result.error.kind);
+    sendBffSuccess(res, result.value);
+  };
+}
+
+export function createAcquisitionNewsletterConsentDirectHandler(options: AcquisitionEvidenceDirectDeps) {
+  const { respond, resolveBinding } = options;
+  const { sendBffSuccess } = respond;
+  return async (value: unknown, res: HttpResponse): Promise<void> => {
+    const request = acquisitionNewsletterConsentEventSchema.safeParse(value);
+    if (!request.success) return badRequest(res, respond, request.error.flatten());
+    const binding = await bindingOrError(res, respond, resolveBinding); if (!binding) return;
+    const result = await safeOperation(() => binding.applyNewsletterConsent(request.data));
+    if (!result) return unavailable(res, respond);
+    if (result.ok === false) return failure(res, respond, result.error.kind);
+    sendBffSuccess(res, result.value);
+  };
+}
+
+async function bindingOrError(res: HttpResponse, respond: BffResponder, resolve: AcquisitionEvidenceBindingResolver) {
+  try { const binding = await resolve(); if (binding) return binding; }
+  catch { /* fail closed below */ }
+  unavailable(res, respond); return null;
+}
+async function safeOperation<T>(work: () => Promise<T>): Promise<T | null> {
+  try { return await work(); } catch { return null; }
+}
+function failure(res: HttpResponse, respond: BffResponder, kind: AcquisitionEvidenceFailure): void {
+  if (kind === "invalid") return badRequest(res, respond);
+  if (kind === "not_found") return respond.sendBffError(res, "NOT_FOUND", "Acquisition evidence subject not found");
+  if (kind === "conflict") return respond.sendBffError(res, "CONFLICT", "Acquisition evidence request conflicts with prior state");
+  unavailable(res, respond);
+}
+function badRequest(res: HttpResponse, respond: BffResponder, details?: unknown): void {
+  respond.sendBffError(res, "BAD_REQUEST", "Invalid acquisition evidence request", { details });
+}
+function unavailable(res: HttpResponse, respond: BffResponder): void {
+  respond.sendBffError(res, "UPSTREAM_UNAVAILABLE", "Acquisition evidence service unavailable");
+}
+function first(value: string | string[] | undefined): string | undefined { return Array.isArray(value) ? value[0] : value; }
+function firstHeader(value: string | string[] | undefined): string | undefined { return first(value); }