@openlup/platform 0.17.0 → 0.19.0

package/src/inventory/renewalReservation.ts

@@ -0,0 +1,88 @@
+import type { AutomaticRenewalReservationResult } from "./contracts/reservation.js";
+
+interface PgQueryExecutor {
+  query(text: string, values?: unknown[]): Promise<{ rows: Record<string, unknown>[] }>;
+}
+
+export interface AutomaticRenewalInventoryPort {
+  reserve(input: {
+    operationId: string;
+    claimToken: string;
+    holdSeconds?: number;
+    now: string;
+  }): Promise<AutomaticRenewalReservationResult>;
+  releaseReservation(input: {
+    operationId: string;
+    claimToken: string;
+    reason: string;
+    now: string;
+  }): Promise<Record<string, unknown>>;
+  expireReservations(input: { now: string; limit?: number }): Promise<number>;
+}
+
+const RESERVE_SQL = `SELECT public.fulfillment_reserve_subscription_renewal(
+  $1::uuid, $2::uuid, $3::integer, $4::timestamptz) AS response`;
+const RELEASE_SQL = `SELECT public.fulfillment_release_subscription_renewal(
+  $1::uuid, $2::uuid, $3::text, $4::timestamptz) AS response`;
+const EXPIRE_SQL = `SELECT public.fulfillment_expire_subscription_renewals(
+  $1::timestamptz, $2::integer) AS expired`;
+
+/** ATP/reservation adapter; it can reserve only through the fenced public renewal function. */
+export function createPostgresRenewalReservationPort(
+  executor: PgQueryExecutor,
+): AutomaticRenewalInventoryPort {
+  return {
+    async reserve(input) {
+      const result = await executor.query(RESERVE_SQL, [
+        input.operationId,
+        input.claimToken,
+        input.holdSeconds ?? 900,
+        input.now,
+      ]);
+      const row = requiredRecord(record(result.rows[0])?.response, "reserve_response");
+      const status = text(row.status) as AutomaticRenewalReservationResult["status"];
+      if (!["held", "committed", "consumed", "released", "expired", "refused"].includes(status)) {
+        throw new Error("subscription_renewal_reservation_status_invalid");
+      }
+      return {
+        reserved: row.reserved === true,
+        replayed: row.replayed === true,
+        reservationId: nullableText(row.reservationId),
+        status,
+        reason: nullableText(row.reason),
+      };
+    },
+
+    async releaseReservation(input) {
+      const result = await executor.query(RELEASE_SQL, [
+        input.operationId,
+        input.claimToken,
+        input.reason,
+        input.now,
+      ]);
+      return requiredRecord(record(result.rows[0])?.response, "release_response");
+    },
+
+    async expireReservations(input) {
+      const result = await executor.query(EXPIRE_SQL, [input.now, input.limit ?? 100]);
+      const value = Number(record(result.rows[0])?.expired);
+      if (!Number.isSafeInteger(value) || value < 0) {
+        throw new Error("subscription_renewal_expiry_response_invalid");
+      }
+      return value;
+    },
+  };
+}
+
+function record(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : null;
+}
+function requiredRecord(value: unknown, field: string): Record<string, unknown> {
+  const result = record(value);
+  if (!result) throw new Error(`subscription_renewal_${field}_invalid`);
+  return result;
+}
+function text(value: unknown): string { return typeof value === "string" ? value.trim() : ""; }
+function nullableText(value: unknown): string | null { return text(value) || null; }

package/src/inventory/reservationPolicy.ts

@@ -0,0 +1,27 @@
+import type { ReservationPolicyInput, ReservationPolicy } from "./contracts/reservation.js";
+
+export const MIN_CHECKOUT_RESERVATION_TTL_MINUTES = 24 * 60;
+export const MAX_CHECKOUT_RESERVATION_TTL_MINUTES = 36 * 60;
+export const DEFAULT_CHECKOUT_RESERVATION_TTL_MINUTES = MIN_CHECKOUT_RESERVATION_TTL_MINUTES;
+
+export function reservationPolicyFor(input: ReservationPolicyInput): ReservationPolicy {
+  if (input.reservationKind !== "checkout_payment_window") {
+    return { expiresAt: null, ttlMinutes: null };
+  }
+
+  const ttlMinutes = normalizedTtlMinutes(input.checkoutTtlMinutes);
+  return {
+    expiresAt: new Date(input.now.getTime() + ttlMinutes * 60_000).toISOString(),
+    ttlMinutes,
+  };
+}
+
+export function normalizedTtlMinutes(value: number | null | undefined): number {
+  if (Number.isFinite(value) && value && value > 0) {
+    return Math.min(
+      MAX_CHECKOUT_RESERVATION_TTL_MINUTES,
+      Math.max(MIN_CHECKOUT_RESERVATION_TTL_MINUTES, Math.floor(value)),
+    );
+  }
+  return DEFAULT_CHECKOUT_RESERVATION_TTL_MINUTES;
+}

package/src/inventory/schemas.ts

@@ -0,0 +1,128 @@
+import { z } from "zod";
+import { INVENTORY_CONTRACT_VERSION, inventoryStockLineSchema } from "@openlup/core/inventory";
+z.config({ jitless: true });
+
+const inventoryReservationStatusSchema = z.enum([
+  "reserved",
+  "released",
+  "consumed",
+  "expired",
+]);
+
+const inventoryReservationKindSchema = z.enum([
+  "checkout_payment_window",
+  "subscription_retry_window",
+  "manual_ops",
+]);
+
+const uuidSchema = z.guid();
+
+const datetimeSchema = z.string().datetime({ offset: true });
+
+const quantitySchema = z.number().int().nonnegative();
+
+export const adminInventoryStockRequestSchema = z.object({
+  page: z.coerce.number().int().min(1).default(1),
+  pageSize: z.coerce.number().int().min(1).max(100).default(25),
+  skuId: uuidSchema.optional(),
+  locationId: uuidSchema.optional(),
+  includeZero: z.coerce.boolean().default(false),
+}).strict();
+
+export const adminInventoryReservationsRequestSchema = z.object({
+  page: z.coerce.number().int().min(1).default(1),
+  pageSize: z.coerce.number().int().min(1).max(100).default(25),
+  status: inventoryReservationStatusSchema.optional(),
+  orderId: uuidSchema.optional(),
+}).strict();
+
+export const adminInventoryStockAdjustmentRequestSchema = z.object({
+  idempotencyKey: z.string().trim().min(8).max(120),
+  skuId: uuidSchema,
+  locationId: uuidSchema,
+  lotId: uuidSchema.nullable().optional(),
+  quantityDelta: z.number().int(),
+  reason: z.string().trim().min(1).max(120),
+  note: z.string().trim().max(1000).optional(),
+}).strict();
+
+export const adminInventorySubscriptionForecastRequestSchema = z.object({
+  horizonDays: z.coerce.number().int().min(1).max(180).default(60),
+  protectionDays: z.coerce.number().int().min(1).max(180).default(45),
+}).strict().refine((request) => request.protectionDays <= request.horizonDays, {
+  message: "protectionDays must be less than or equal to horizonDays",
+  path: ["protectionDays"],
+});
+
+const inventoryReservationSummarySchema = z.object({
+  id: uuidSchema,
+  orderId: uuidSchema,
+  subscriptionCycleId: uuidSchema.nullable(),
+  status: inventoryReservationStatusSchema,
+  kind: inventoryReservationKindSchema,
+  expiresAt: datetimeSchema.nullable(),
+  createdAt: datetimeSchema,
+}).strict();
+
+export const inventoryStockListResponseSchema = z.object({
+  contractVersion: z.literal(INVENTORY_CONTRACT_VERSION),
+  stock: z.array(inventoryStockLineSchema.extend({ availableNow: quantitySchema })),
+  totalCount: z.number().int().min(0),
+  page: z.number().int().min(1),
+  pageSize: z.number().int().min(1),
+}).strict();
+
+export const inventoryReservationsListResponseSchema = z.object({
+  contractVersion: z.literal(INVENTORY_CONTRACT_VERSION),
+  reservations: z.array(inventoryReservationSummarySchema),
+  totalCount: z.number().int().min(0),
+  page: z.number().int().min(1),
+  pageSize: z.number().int().min(1),
+}).strict();
+
+const inventorySubscriptionForecastStockStatusSchema = z.enum(["fresh", "stale", "missing"]);
+
+const inventorySubscriptionForecastSkuSchema = z.object({
+  skuId: uuidSchema,
+  sku: z.string().trim().min(1),
+  providerCurrentForSale: quantitySchema.nullable(),
+  providerStockLastSyncedAt: datetimeSchema.nullable(),
+  providerStockStaleAfter: datetimeSchema.nullable(),
+  stockStatus: inventorySubscriptionForecastStockStatusSchema,
+  openHardReservations: quantitySchema,
+  safetyStock: quantitySchema,
+  sellableNow: quantitySchema,
+  activeSubscriptionDemand30: quantitySchema,
+  activeSubscriptionDemand45: quantitySchema,
+  activeSubscriptionDemand60: quantitySchema,
+  plannedSupply: quantitySchema,
+  coverageDays: z.number().int().nonnegative().nullable(),
+  shortageDate: datetimeSchema.nullable(),
+  horizonMissingQty: quantitySchema,
+  protectionMissingQty: quantitySchema,
+  missingQty: quantitySchema,
+  recommendedProductionQty: quantitySchema,
+}).strict();
+
+const inventorySubscriptionForecastTotalsSchema = z.object({
+  activeSubscriptionCount: quantitySchema,
+  excludedSubscriptionCount: quantitySchema,
+  missingProviderStockSkuCount: quantitySchema,
+  staleProviderStockSkuCount: quantitySchema,
+  horizonShortageSkuCount: quantitySchema,
+  protectionShortageSkuCount: quantitySchema,
+  shortageSkuCount: quantitySchema,
+  recommendedProductionQty: quantitySchema,
+}).strict();
+
+export function createInventorySubscriptionForecastResponseSchema(providerSchema: z.ZodType<string>) {
+return z.object({
+  contractVersion: z.literal(INVENTORY_CONTRACT_VERSION),
+  generatedAt: datetimeSchema,
+  stockMasterProvider: providerSchema,
+  horizonDays: z.number().int().min(1),
+  protectionDays: z.number().int().min(1),
+  skus: z.array(inventorySubscriptionForecastSkuSchema),
+  totals: inventorySubscriptionForecastTotalsSchema,
+}).strict();
+}

package/src/inventory/sql.ts

@@ -0,0 +1,5 @@
+/** Sparse projections of canonical units, never an install chain. */
+export const INVENTORY_MIGRATIONS = [
+  { id: "20260814000000_fulfillment_stock_evidence", catalogPath: "db/platform/migrations/20260814000000_fulfillment_stock_evidence.sql", position: 27, sha256: "df20c2491cb0196b4e28d19e7578c95bfa5c87b8f89fb0b6284c0e0695a3cc1d", url: new URL("../../sql/20260814000000_fulfillment_stock_evidence.sql", import.meta.url) },
+  { id: "20260815120000_automatic_subscription_renewal", catalogPath: "db/platform/migrations/20260815120000_automatic_subscription_renewal.sql", position: 33, sha256: "edef131f4f483a009e0bb6728a071ab78b6c9ac2aa8047aa7107646a11baec73", url: new URL("../../sql/20260815120000_automatic_subscription_renewal.sql", import.meta.url) },
+] as const;

package/src/inventory/subscriptionForecastCalculation.ts

@@ -0,0 +1,157 @@
+import type { SubscriptionForecastCalculationInput, SubscriptionForecastCounts, SubscriptionForecastSku, SubscriptionForecastTotals, SubscriptionForecastDemandLine, SubscriptionForecastSupplyLine } from "./contracts/forecast.js";
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+export function calculateSubscriptionForecastSkus(
+  input: SubscriptionForecastCalculationInput,
+): SubscriptionForecastSku[] {
+  const generatedAtMs = Date.parse(input.generatedAt);
+  const horizonAtMs = generatedAtMs + input.horizonDays * DAY_MS;
+  const protectionAtMs = generatedAtMs + input.protectionDays * DAY_MS;
+  const demand = input.demand
+    .filter((line) => !["skipped", "cancelled"].includes(line.status))
+    .filter((line) => Date.parse(line.dueAt) <= horizonAtMs);
+  const plannedSupply = input.supply
+    .filter((line) => line.status === "planned")
+    .filter((line) => Date.parse(line.expectedAt) <= horizonAtMs);
+
+  const providerBySku = new Map(input.providerCurrent.map((line) => [line.skuId, line]));
+  const skuIds = new Set<string>([
+    ...input.providerCurrent.map((line) => line.skuId),
+    ...input.openHardReservations.map((line) => line.skuId),
+    ...input.stock.map((line) => line.skuId),
+    ...demand.map((line) => line.skuId),
+    ...plannedSupply.map((line) => line.skuId),
+  ]);
+
+  const skus = [...skuIds].map<SubscriptionForecastSku>((skuId) => {
+    const provider = providerBySku.get(skuId) ?? null;
+    const stockLines = input.stock.filter((line) => line.skuId === skuId);
+    const demandLines = demand.filter((line) => line.skuId === skuId);
+    const supplyLines = plannedSupply.filter((line) => line.skuId === skuId);
+    const sku = provider?.sku ?? stockLines[0]?.sku ?? demandLines[0]?.sku ?? "unknown";
+    const stockStatus = provider === null
+      ? "missing"
+      : Date.parse(provider.staleAfter) <= generatedAtMs
+        ? "stale"
+        : "fresh";
+    const openHardReservations = sum(input.openHardReservations
+      .filter((line) => line.skuId === skuId)
+      .map((line) => line.quantity));
+    const safetyStock = sum(stockLines
+      .filter((line) => line.fulfillable && line.locationStatus === "active")
+      .map((line) => line.safetyStock));
+    const sellableNow = stockStatus === "fresh" && provider
+      ? Math.max(0, provider.forSaleQuantity - openHardReservations - safetyStock)
+      : 0;
+    const shortage = simulateSubscriptionCoverage({
+      generatedAtMs,
+      protectionAtMs,
+      sellableNow,
+      demand: demandLines,
+      supply: supplyLines,
+    });
+
+    return {
+      skuId,
+      sku,
+      providerCurrentForSale: provider?.forSaleQuantity ?? null,
+      providerStockLastSyncedAt: provider?.lastSyncedAt ?? null,
+      providerStockStaleAfter: provider?.staleAfter ?? null,
+      stockStatus,
+      openHardReservations,
+      safetyStock,
+      sellableNow,
+      activeSubscriptionDemand30: demandQuantityWithin(demandLines, generatedAtMs + 30 * DAY_MS),
+      activeSubscriptionDemand45: demandQuantityWithin(demandLines, generatedAtMs + 45 * DAY_MS),
+      activeSubscriptionDemand60: demandQuantityWithin(demandLines, generatedAtMs + 60 * DAY_MS),
+      plannedSupply: sum(supplyLines.map((line) => line.quantity)),
+      coverageDays: shortage.shortageDate
+        ? Math.max(0, Math.ceil((Date.parse(shortage.shortageDate) - generatedAtMs) / DAY_MS))
+        : null,
+      shortageDate: shortage.shortageDate,
+      horizonMissingQty: shortage.horizonMissingQty,
+      protectionMissingQty: shortage.protectionMissingQty,
+      missingQty: shortage.protectionMissingQty,
+      recommendedProductionQty: shortage.protectionMissingQty,
+    };
+  }).sort((a, b) => a.sku.localeCompare(b.sku));
+
+  return skus;
+}
+
+/** Kept separate so native envelopes can read their metadata before count getters. */
+export function calculateSubscriptionForecastTotals(
+  input: SubscriptionForecastCounts,
+  skus: SubscriptionForecastSku[],
+): SubscriptionForecastTotals {
+  return {
+    activeSubscriptionCount: input.activeSubscriptionCount,
+    excludedSubscriptionCount: input.excludedSubscriptionCount,
+    missingProviderStockSkuCount: skus.filter((line) => line.stockStatus === "missing").length,
+    staleProviderStockSkuCount: skus.filter((line) => line.stockStatus === "stale").length,
+    horizonShortageSkuCount: skus.filter((line) => line.shortageDate !== null).length,
+    protectionShortageSkuCount: skus.filter((line) => line.protectionMissingQty > 0).length,
+    shortageSkuCount: skus.filter((line) => line.shortageDate !== null).length,
+    recommendedProductionQty: sum(skus.map((line) => line.recommendedProductionQty)),
+  };
+}
+
+function simulateSubscriptionCoverage(input: {
+  generatedAtMs: number;
+  protectionAtMs: number;
+  sellableNow: number;
+  demand: SubscriptionForecastDemandLine[];
+  supply: SubscriptionForecastSupplyLine[];
+}): { shortageDate: string | null; horizonMissingQty: number; protectionMissingQty: number } {
+  let available = input.sellableNow;
+  let shortageDate: string | null = null;
+  let horizonMissingQty = 0;
+  let protectionMissingQty = 0;
+  const events = [
+    ...input.supply.map((line) => ({
+      type: "supply" as const,
+      at: line.expectedAt,
+      quantity: line.quantity,
+    })),
+    ...input.demand.map((line) => ({
+      type: "demand" as const,
+      at: line.dueAt,
+      quantity: line.quantity,
+    })),
+  ].sort((a, b) => {
+    const dateDelta = Date.parse(a.at) - Date.parse(b.at);
+    if (dateDelta !== 0) return dateDelta;
+    return a.type === "supply" && b.type === "demand" ? -1 : 1;
+  });
+
+  for (const event of events) {
+    if (event.type === "supply") {
+      available += event.quantity;
+      continue;
+    }
+
+    if (available >= event.quantity) {
+      available -= event.quantity;
+      continue;
+    }
+
+    const missing = event.quantity - available;
+    available = 0;
+    shortageDate ??= event.at;
+    horizonMissingQty += missing;
+    if (Date.parse(event.at) <= input.protectionAtMs) protectionMissingQty += missing;
+  }
+
+  return { shortageDate, horizonMissingQty, protectionMissingQty };
+}
+
+function demandQuantityWithin(lines: SubscriptionForecastDemandLine[], dueAtOrBeforeMs: number): number {
+  return sum(lines
+    .filter((line) => Date.parse(line.dueAt) <= dueAtOrBeforeMs)
+    .map((line) => line.quantity));
+}
+
+function sum(values: number[]): number {
+  return values.reduce((total, value) => total + value, 0);
+}

package/src/pricing/acquisitionFinancialPolicy.ts

@@ -0,0 +1,26 @@
+import type { AcquisitionTermsMetadata } from "./contracts/acquisitionTerms.js";
+export type AcquisitionRowFacts = Readonly<{
+  id: string;
+  active: boolean;
+  regionCodes: readonly string[];
+  validFrom: string;
+  validTo: string | null;
+  mirrorOf: unknown;
+  metadataPresent: boolean;
+  metadata: unknown;
+}>;
+export type AcquisitionClassification = Readonly<{
+  baselineLegacy: boolean;
+  target: boolean;
+  canonicalRow: boolean;
+  unconfiguredLegacyEligible: boolean;
+}>;
+/** Required host policy. No financial predicates or schedules are inferred. */
+export interface AcquisitionFinancialPolicy<Row> {
+  facts(row: Row): AcquisitionRowFacts;
+  classify(row: Row): AcquisitionClassification;
+  validateMetadata(row: Row, terms: AcquisitionTermsMetadata): void;
+  pairMatches(legacy: Row, mirror: Row): boolean;
+  initialDiscountBps(row: Row, purpose: "resolved_target" | "filter_validation"): unknown;
+  unconfiguredTerms(legacy: Row, mirror: Row): AcquisitionTermsMetadata;
+}

package/src/pricing/acquisitionOfferPricing.ts

@@ -0,0 +1,38 @@
+import { projectCommerceOfferPricing, type CommerceOfferPricingDeps } from "./commerceOfferPricing.js";
+import { COMMERCE_OFFER_PRICING_V2_CONTRACT_VERSION, COMMERCE_OFFER_PRICING_V3_CONTRACT_VERSION, type AcquisitionOfferPricingResponse } from "./contracts/offer.js";
+import { ACQUISITION_TERMS_CAPABILITY, type AcquisitionTerms } from "./contracts/acquisitionTerms.js";
+import type { CommerceQuoteCatalogItem } from "./commerceQuoteCatalogReadPort.js";
+import type { CreateQuoteRequest } from "./contracts/quote.js";
+import { ACQUISITION_PROJECTION_MAX_AGE_MS, acquisitionProjectionFreshnessSchema } from "./acquisitionOfferPricingSchemas.js";
+
+export function acquisitionProjectionFreshness(acquisitionTerms: AcquisitionTerms, observedAt: string, nextBoundaryAt?: string | null) {
+  const boundary = nextBoundaryAt ?? acquisitionTerms.effectiveTo;
+  const validUntil = new Date(Math.min(Date.parse(observedAt) + ACQUISITION_PROJECTION_MAX_AGE_MS,
+    boundary == null ? Infinity : Date.parse(boundary))).toISOString();
+  return acquisitionProjectionFreshnessSchema.parse({ acquisitionTerms, observedAt, validUntil });
+}
+
+/** Explicit opt-in projection; the incumbent projector receives no new defaults. */
+export async function projectAcquisitionOfferPricing<Item extends CommerceQuoteCatalogItem, ScopeV1 extends string, ScopeV2 extends string>(
+  input: Omit<CommerceOfferPricingDeps<Item, ScopeV1, ScopeV2>, "requestFor"> & {
+    acquisitionTerms: AcquisitionTerms;
+    observedAt: string;
+    nextBoundaryAt?: string | null;
+    requestFor(product: Item, mode: "one_time" | "subscription", acquisition: {
+      acquisitionCapability: typeof ACQUISITION_TERMS_CAPABILITY; atTime: string;
+    }): CreateQuoteRequest;
+  },
+): Promise<AcquisitionOfferPricingResponse<ScopeV2>> {
+  const freshness = acquisitionProjectionFreshness(input.acquisitionTerms, input.observedAt, input.nextBoundaryAt);
+  if (input.pricingPolicy?.offerPolicyVersion !== "commerce.offer-policy.v2" ||
+    input.pricingPolicy.promotionEngineVersion !== "promotion-engine.v2") {
+    throw new Error("commerce_acquisition_projection_policy_invalid");
+  }
+  const projection = await projectCommerceOfferPricing({ ...input,
+    requestFor: (product, mode) => input.requestFor(product, mode, {
+      acquisitionCapability: ACQUISITION_TERMS_CAPABILITY, atTime: input.observedAt,
+    }),
+  });
+  if (projection.contractVersion !== COMMERCE_OFFER_PRICING_V2_CONTRACT_VERSION) throw new Error("commerce_acquisition_projection_policy_invalid");
+  return { ...projection, contractVersion: COMMERCE_OFFER_PRICING_V3_CONTRACT_VERSION, ...freshness };
+}

package/src/pricing/acquisitionOfferPricingHandler.ts

@@ -0,0 +1,157 @@
+import type { HttpRequest, HttpResponse } from "../http/index.js";
+import type { BffResponder } from "../bff/index.js";
+import type { z } from "zod";
+import { COMMERCE_OFFER_PRICING_V3_CONTRACT_VERSION, type AcquisitionOfferPricingResponse, type CommerceOfferPricingResponse } from "./contracts/offer.js";
+import type { AcquisitionCapability } from "./contracts/acquisitionTerms.js";
+import { acquisitionCapabilitySchema } from "./acquisitionTermsSchemas.js";
+import { pricingPolicyRequestSchema } from "./offerPolicySchemas.js";
+import type { PricingPolicyRequest, PricingPolicySnapshot } from "./contracts/offerPolicy.js";
+import { mapPricingPolicyFailure } from "./commercePricingPolicyErrors.js";
+import { COMMERCE_OFFER_PRICING_ASSIGNED_CACHE_CONTROL, COMMERCE_OFFER_PRICING_CACHE_CONTROL,
+  OFFER_POLICY_CAPABILITY_HEADER, OFFER_POLICY_TOKEN_HEADER, OFFER_POLICY_VISITOR_HEADER } from "./commerceOfferPricingHandler.js";
+export const ACQUISITION_CAPABILITY_HEADER = "x-commerce-acquisition-capability";
+const ROUTER_QUERY_KEYS = new Set(["path", "__bffPath"]);
+
+export interface AcquisitionOfferPricingHandlerDeps {
+  responder: BffResponder;
+  commerceOfferPricingResponseSchema: z.ZodType<AcquisitionOfferPricingResponse | CommerceOfferPricingResponse>;
+  incumbentHandler(req: HttpRequest, res: HttpResponse): Promise<void>;
+  readOfferPricing(pricingPolicy?: PricingPolicySnapshot, acquisitionCapability?: AcquisitionCapability): Promise<AcquisitionOfferPricingResponse | CommerceOfferPricingResponse>;
+  requirePricingPolicy?: boolean;
+  resolvePricingPolicy?(request: {
+    visitorId: string;
+    pricingPolicy: PricingPolicyRequest;
+  }): PricingPolicySnapshot | undefined | Promise<PricingPolicySnapshot | undefined>;
+}
+
+export function createAcquisitionOfferPricingHandler({
+  responder, commerceOfferPricingResponseSchema, incumbentHandler,
+  readOfferPricing,
+  resolvePricingPolicy,
+  requirePricingPolicy = false,
+}: AcquisitionOfferPricingHandlerDeps) {
+  const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = responder;
+  return async function handler(
+    req: HttpRequest,
+    res: HttpResponse,
+  ): Promise<void> {
+    if (req.headers?.[ACQUISITION_CAPABILITY_HEADER] === undefined) return incumbentHandler(req, res);
+    if (req.method !== "GET") {
+      sendMethodNotAllowed(res, ["GET"]);
+      return;
+    }
+    const userQueryKeys = Object.keys(req.query ?? {}).filter(
+      (key) => !ROUTER_QUERY_KEYS.has(key),
+    );
+    if (userQueryKeys.length > 0) {
+      sendBffError(res, "BAD_REQUEST", "Commerce offer pricing does not accept query parameters");
+      return;
+    }
+
+    let failureReason = "offer_pricing_policy_unavailable";
+    try {
+      const acquisitionCapability = readAcquisitionCapability(req);
+      if (acquisitionCapability === null) {
+        sendBffError(res, "BAD_REQUEST", "Commerce acquisition capability is invalid");
+        return;
+      }
+      const policyRequest = readPolicyRequest(req);
+      if (policyRequest === null) {
+        sendBffError(res, "BAD_REQUEST", "Commerce offer pricing policy capability is invalid");
+        return;
+      }
+      if (!policyRequest && requirePricingPolicy) {
+        // A caller that sent no capability headers is an incomplete request,
+        // not an unavailable origin — the same attribution the missing-visitor
+        // branch above already applies.
+        sendBffError(
+          res,
+          "BAD_REQUEST",
+          "Commerce offer pricing requires offer policy v2",
+          {
+            details: {
+              reason: "pricing_policy_request_invalid",
+              stage: "pricing_policy",
+              policyReason: "v2_capability_required",
+            },
+          },
+        );
+        return;
+      }
+      const pricingPolicy = policyRequest && resolvePricingPolicy
+        ? await resolvePricingPolicy(policyRequest)
+        : undefined;
+      if (acquisitionCapability && pricingPolicy?.offerPolicyVersion !== "commerce.offer-policy.v2") {
+        sendBffError(res, "BAD_REQUEST", "Commerce acquisition pricing requires offer policy v2");
+        return;
+      }
+      failureReason = "offer_pricing_projection_unavailable";
+      const parsed = commerceOfferPricingResponseSchema.safeParse(
+        await (acquisitionCapability ? readOfferPricing(pricingPolicy, acquisitionCapability) : readOfferPricing(pricingPolicy)),
+      );
+      if (!parsed.success || Boolean(acquisitionCapability) !==
+          (parsed.data.contractVersion === COMMERCE_OFFER_PRICING_V3_CONTRACT_VERSION)) {
+        sendBffError(
+          res,
+          "INVALID_RESPONSE",
+          "Commerce offer pricing returned invalid response",
+        );
+        return;
+      }
+      res.setHeader("Vary", [ACQUISITION_CAPABILITY_HEADER, OFFER_POLICY_CAPABILITY_HEADER,
+        OFFER_POLICY_TOKEN_HEADER, OFFER_POLICY_VISITOR_HEADER].join(", "));
+      sendBffSuccess(
+        res,
+        parsed.data,
+        { contractVersion: parsed.data.contractVersion },
+        {
+          cacheControl: policyRequest
+            ? COMMERCE_OFFER_PRICING_ASSIGNED_CACHE_CONTROL
+            : COMMERCE_OFFER_PRICING_CACHE_CONTROL,
+        },
+      );
+    } catch (error) {
+      const policyFailure = failureReason === "offer_pricing_policy_unavailable"
+        ? mapPricingPolicyFailure(error) : null;
+      sendBffError(
+        res,
+        "UPSTREAM_UNAVAILABLE",
+        "Commerce offer pricing is unavailable",
+        {
+          details: {
+            reason: failureReason,
+            ...(policyFailure ? { policyReason: policyFailure.details.policyReason } : {}),
+          },
+        },
+      );
+    }
+  };
+}
+
+export function readAcquisitionCapability(req: HttpRequest): AcquisitionCapability | undefined | null {
+  const raw = req.headers?.[ACQUISITION_CAPABILITY_HEADER];
+  if (raw === undefined) return undefined;
+  const parsed = acquisitionCapabilitySchema.safeParse(typeof raw === "string" ? raw.trim() : raw);
+  return parsed.success ? parsed.data : null;
+}
+
+function readPolicyRequest(req: HttpRequest): {
+  visitorId: string;
+  pricingPolicy: PricingPolicyRequest;
+} | undefined | null {
+  const capability = singleHeader(req, OFFER_POLICY_CAPABILITY_HEADER);
+  const token = singleHeader(req, OFFER_POLICY_TOKEN_HEADER);
+  if (!capability && !token) return undefined;
+  const visitorId = singleHeader(req, OFFER_POLICY_VISITOR_HEADER);
+  if (!visitorId || visitorId.length > 120) return null;
+  const parsed = pricingPolicyRequestSchema.safeParse({
+    ...(capability ? { capability } : {}),
+    ...(token ? { token } : {}),
+  });
+  return parsed.success ? { visitorId, pricingPolicy: parsed.data } : null;
+}
+
+function singleHeader(req: HttpRequest, name: string): string | undefined {
+  const value = req.headers?.[name];
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}

package/src/pricing/acquisitionOfferPricingSchemas.ts

@@ -0,0 +1,35 @@
+import { z } from "zod";
+import { acquisitionTermsSchema } from "./acquisitionTermsSchemas.js";
+import { COMMERCE_OFFER_PRICING_V2_CONTRACT_VERSION, COMMERCE_OFFER_PRICING_V3_CONTRACT_VERSION, type AcquisitionOfferPricingResponse, type CommerceOfferPricingResponse } from "./contracts/offer.js";
+export const ACQUISITION_PROJECTION_MAX_AGE_MS = 60_000;
+export const acquisitionProjectionFreshnessShape = {
+  acquisitionTerms: acquisitionTermsSchema,
+  observedAt: z.string().datetime({ offset: true }),
+  validUntil: z.string().datetime({ offset: true }),
+};
+export const acquisitionProjectionFreshnessSchema = z.object(acquisitionProjectionFreshnessShape).strict().refine((value) => {
+  const observed = Date.parse(value.observedAt);
+  const until = Date.parse(value.validUntil);
+  return until > observed && until <= observed + ACQUISITION_PROJECTION_MAX_AGE_MS
+    && (value.acquisitionTerms.effectiveFrom == null || Date.parse(value.acquisitionTerms.effectiveFrom) <= observed)
+    && (value.acquisitionTerms.effectiveTo == null || until <= Date.parse(value.acquisitionTerms.effectiveTo));
+}, "acquisition projection must be current and expire by its next boundary or 60 seconds");
+
+
+/** Validate against the host's existing v2 scope, product and settlement schemas. */
+export function createAcquisitionOfferPricingSchema<ScopeV2 extends string>(
+  v2Schema: z.ZodType<Extract<CommerceOfferPricingResponse<string, ScopeV2>, { contractVersion: typeof COMMERCE_OFFER_PRICING_V2_CONTRACT_VERSION }>>,
+): z.ZodType<AcquisitionOfferPricingResponse<ScopeV2>> {
+  return z.unknown().transform((value, ctx) => {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      ctx.addIssue({ code: "custom", message: "Invalid acquisition offer" }); return z.NEVER;
+    }
+    const { contractVersion, acquisitionTerms, observedAt, validUntil, ...base } = value as Record<string, unknown>;
+    const pricing = v2Schema.safeParse({ ...base, contractVersion: COMMERCE_OFFER_PRICING_V2_CONTRACT_VERSION });
+    const freshness = acquisitionProjectionFreshnessSchema.safeParse({ acquisitionTerms, observedAt, validUntil });
+    if (contractVersion !== COMMERCE_OFFER_PRICING_V3_CONTRACT_VERSION || !pricing.success || !freshness.success) {
+      ctx.addIssue({ code: "custom", message: "Invalid acquisition offer" }); return z.NEVER;
+    }
+    return { ...pricing.data, contractVersion: COMMERCE_OFFER_PRICING_V3_CONTRACT_VERSION, ...freshness.data };
+  });
+}