@openlup/platform 0.28.0 → 0.29.0

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

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