@openlup/platform 0.16.0 → 0.18.0

package/src/pricing/commerceQuoteBatchHandler.ts

@@ -0,0 +1,129 @@
+import type { ResolvedAcquisitionTerms } from "./contracts/acquisitionTerms.js";
+import { mapAcquisitionTermsFailure } from "./acquisitionQuoteBinding.js";
+import type { HttpRequest, HttpResponse } from "../http/index.js";
+import type { BffResponder } from "../bff/index.js";
+import type { z } from "zod";
+import {
+  type CreateQuoteRequest, type CreateQuoteResponse,
+} from "./contracts/quote.js";
+import { COMMERCE_CONTRACT_VERSION } from "./contracts/index.js";
+import {
+  CommerceQuoteError,
+  type CommerceQuotePort,
+} from "./quotePorts.js";
+import { CommerceQuoteCatalogReadError } from "./commerceQuoteCatalogReadPort.js";
+import { mapPricingPolicyFailure } from "./commercePricingPolicyErrors.js";
+import type { PricingPolicySnapshot } from "./contracts/offerPolicy.js";
+
+export interface CommerceQuoteBatchHandlerDeps<Request extends CreateQuoteRequest = CreateQuoteRequest, Response extends CreateQuoteResponse = CreateQuoteResponse> {
+  responder: BffResponder;
+  acquisition?: { terms(quote: Response["quote"]): ResolvedAcquisitionTerms | undefined };
+  createQuoteBatchRequestSchema: z.ZodType<{ quotes: Request[] }>;
+  publicCreateQuoteBatchResponseSchema: z.ZodType<{ contractVersion: typeof COMMERCE_CONTRACT_VERSION; quotes: Response["quote"][] }>;
+
+  quotePort: CommerceQuotePort<Request, Response>;
+  resolveCustomerEligibility?: (
+    request: Request,
+  ) => Promise<{ clientId: string | null; source: "anonymous" | "resolved_client" }>;
+  resolvePricingPolicy?: (
+    request: Request,
+  ) => PricingPolicySnapshot | undefined | Promise<PricingPolicySnapshot | undefined>;
+}
+
+/**
+ * Batch quote BFF handler: prices N independent quotes in one request so the
+ * configurator stops fanning out one HTTP call per length tile. The injected
+ * `quotePort` is expected to share its catalog + active price-list reads across
+ * the batch (single `atTime` + memoized catalog), so this is one DB warm-up, not
+ * N. Output is identical to calling the single-quote endpoint N times, and order
+ * is preserved (`quotes[i]` ⇔ the i-th request). A failure in any quote fails
+ * the whole batch, mirroring the single-endpoint error mapping.
+ */
+export function createCommerceQuoteBatchHandler<Request extends CreateQuoteRequest, Response extends CreateQuoteResponse>({
+  responder, createQuoteBatchRequestSchema, publicCreateQuoteBatchResponseSchema,
+  quotePort,
+  acquisition,
+  resolveCustomerEligibility,
+  resolvePricingPolicy,
+}: CommerceQuoteBatchHandlerDeps<Request, Response>) {
+  const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = responder;
+  return async function handler(req: HttpRequest, res: HttpResponse): Promise<void> {
+    if (req.method !== "POST") {
+      sendMethodNotAllowed(res, ["POST"]);
+      return;
+    }
+
+    const request = createQuoteBatchRequestSchema.safeParse(req.body);
+    if (!request.success) {
+      sendBffError(res, "BAD_REQUEST", "Invalid commerce quote batch request", {
+        details: request.error.flatten(),
+      });
+      return;
+    }
+
+    try {
+      const results = await Promise.all(
+        request.data.quotes.map(async (quote) => {
+          const eligibility = resolveCustomerEligibility
+            ? await resolveCustomerEligibility(quote)
+            : { clientId: null, source: "anonymous" as const };
+          const pricingPolicy = await resolvePricingPolicy?.(quote);
+          return quotePort.createQuote(quote, {
+            clientId: eligibility.clientId,
+            ...(pricingPolicy ? { pricingPolicy } : {}),
+          });
+        }),
+      );
+      const payload = {
+        contractVersion: COMMERCE_CONTRACT_VERSION,
+        quotes: results.map((result) => result.quote),
+      };
+      const response = publicCreateQuoteBatchResponseSchema.safeParse(payload);
+      if (!response.success) {
+        sendBffError(res, "INVALID_RESPONSE", "Commerce quote batch returned invalid response");
+        return;
+      }
+
+      sendBffSuccess(res, response.data, {
+        contractVersion: COMMERCE_CONTRACT_VERSION,
+      });
+    } catch (error) {
+      const acquisitionFailure = acquisition ? mapAcquisitionTermsFailure(error) : null;
+      if (acquisitionFailure) {
+        sendBffError(res, acquisitionFailure.code, "Acquisition terms unavailable", { details: acquisitionFailure.details });
+        return;
+      }
+      if (error instanceof CommerceQuoteCatalogReadError) {
+        sendBffError(res, "UPSTREAM_UNAVAILABLE", "Commerce catalog is unavailable", {
+          details: { reason: "catalog_unavailable", refusalCode: error.code },
+        });
+        return;
+      }
+      if (error instanceof CommerceQuoteError) {
+        sendBffError(
+          res,
+          error.code === "UNKNOWN_SKU" ? "BAD_REQUEST" : "CONFLICT",
+          error.message,
+          { details: error.details },
+        );
+        return;
+      }
+      // Without this the batch route answered every pricing-policy refusal with
+      // a detail-free 503, so the one route the configurator actually fans out
+      // to said the least about why it refused.
+      const policyFailure = mapPricingPolicyFailure(error);
+      if (policyFailure) {
+        console.error(
+          "[commerce-quote-batch] pricing policy refused:",
+          JSON.stringify(policyFailure.details),
+        );
+        sendBffError(res, policyFailure.code, policyFailure.code === "BAD_REQUEST"
+          ? "Commerce quote batch request is missing offer policy context"
+          : "Commerce quote batch failed", { details: policyFailure.details });
+        return;
+      }
+
+      sendBffError(res, "UPSTREAM_UNAVAILABLE", "Commerce quote batch failed");
+    }
+  };
+}

package/src/pricing/commerceQuoteCatalogReadPort.ts

@@ -0,0 +1,42 @@
+/** Quote-only facts: no copy, route, price, or inventory authority. */
+export interface CommerceQuoteCatalogItem {
+  skuId: string;
+  skuCode: string;
+  variantId: string;
+  productSlug: string;
+  netWeightG: number;
+  /** Identifies the product primary SKU for offer selection; secondary SKUs are excluded. */
+  isPrimarySku?: boolean;
+  isAddon: boolean;
+  sellability: {
+    oneTime: boolean;
+    subscription: boolean;
+  };
+  documentRevision: {
+    id: string | null;
+    digest: string | null;
+  };
+}
+
+export interface CommerceQuoteCatalogReadPort {
+  listQuoteCatalogItems(): Promise<CommerceQuoteCatalogItem[]>;
+}
+
+export type CommerceQuoteCatalogReadRefusalCode =
+  | "catalog_read_not_configured"
+  | "catalog_authority_unavailable"
+  | "catalog_authority_changed"
+  | "catalog_revision_invalid"
+  | "catalog_document_schema_invalid"
+  | "catalog_document_digest_mismatch"
+  | "catalog_primary_trade_item_invalid"
+  | "catalog_cursor_invalid"
+  | "catalog_cardinality_exceeded";
+
+export class CommerceQuoteCatalogReadError extends Error {
+  constructor(readonly code: CommerceQuoteCatalogReadRefusalCode) {
+    super(code);
+    this.name = "CommerceQuoteCatalogReadError";
+  }
+}
+

package/src/pricing/commerceQuoteHandler.ts

@@ -0,0 +1,184 @@
+import type { ResolvedAcquisitionTerms } from "./contracts/acquisitionTerms.js";
+import { mapAcquisitionTermsFailure } from "./acquisitionQuoteBinding.js";
+import type { HttpRequest, HttpResponse } from "../http/index.js";
+import type { BffResponder } from "../bff/index.js";
+import type { z } from "zod";
+import {
+  type CreateQuoteRequest, type CreateQuoteResponse,
+} from "./contracts/quote.js";
+import { COMMERCE_CONTRACT_VERSION } from "./contracts/index.js";
+import {
+  CommerceQuoteError,
+  type CommerceQuotePort,
+} from "./quotePorts.js";
+import type { PricingPolicySnapshot } from "./contracts/offerPolicy.js";
+import { mapPricingPolicyFailure } from "./commercePricingPolicyErrors.js";
+import { CommerceQuoteCatalogReadError } from "./commerceQuoteCatalogReadPort.js";
+
+type CommerceQuoteFailureStage =
+  | "customer_eligibility"
+  | "pricing_policy"
+  | "quote_evaluation"
+  | "promotion_acceptance"
+  | "promotion_fallback";
+
+function commerceQuoteFailureDetails(stage: CommerceQuoteFailureStage) {
+  return { reason: "quote_dependency_failed" as const, stage };
+}
+
+export interface CommerceQuoteHandlerDeps<Request extends CreateQuoteRequest = CreateQuoteRequest, Response extends CreateQuoteResponse = CreateQuoteResponse> {
+  responder: BffResponder;
+  acquisition?: { terms(quote: Response["quote"]): ResolvedAcquisitionTerms | undefined };
+  createQuoteRequestSchema: z.ZodType<Request>;
+  createQuoteResponseSchema: z.ZodType<Response>;
+  publicCreateQuoteRequestSchema: z.ZodType<Request & { promotionAcceptanceToken?: string }>;
+  publicCreateQuoteResponseSchema: z.ZodType<Response & { promotionAcceptanceToken?: string }>;
+
+  quotePort: CommerceQuotePort<Request, Response>;
+  fallbackQuotePort?: CommerceQuotePort<Request, Response>;
+  resolveCustomerEligibility?: (
+    request: Request,
+  ) => Promise<{ clientId: string | null; source: "anonymous" | "resolved_client" }>;
+  resolvePricingPolicy?: (
+    request: Request,
+  ) => PricingPolicySnapshot | undefined | Promise<PricingPolicySnapshot | undefined>;
+  createPromotionAcceptance?: (
+    request: Request,
+    quote: Awaited<ReturnType<CommerceQuotePort<Request, Response>["createQuote"]>>["quote"],
+    acquisitionTerms?: ResolvedAcquisitionTerms,
+  ) => string | null;
+  honorPromotionAcceptance?: (
+    token: string,
+    request: Request,
+    quote: Awaited<ReturnType<CommerceQuotePort<Request, Response>["createQuote"]>>["quote"],
+    acquisitionTerms?: ResolvedAcquisitionTerms,
+  ) => boolean;
+}
+
+export function createCommerceQuoteHandler<Request extends CreateQuoteRequest, Response extends CreateQuoteResponse>({
+  responder, createQuoteRequestSchema, createQuoteResponseSchema, publicCreateQuoteRequestSchema, publicCreateQuoteResponseSchema,
+  quotePort,
+  acquisition,
+  fallbackQuotePort,
+  resolveCustomerEligibility,
+  resolvePricingPolicy,
+  createPromotionAcceptance,
+  honorPromotionAcceptance,
+}: CommerceQuoteHandlerDeps<Request, Response>) {
+  const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = responder;
+  return async function handler(req: HttpRequest, res: HttpResponse): Promise<void> {
+    if (req.method !== "POST") {
+      sendMethodNotAllowed(res, ["POST"]);
+      return;
+    }
+
+    const publicRequest = publicCreateQuoteRequestSchema.safeParse(req.body);
+    if (!publicRequest.success) {
+      sendBffError(res, "BAD_REQUEST", "Invalid commerce quote request", {
+        details: publicRequest.error.flatten(),
+      });
+      return;
+    }
+    const { promotionAcceptanceToken, ...canonicalInput } = publicRequest.data;
+    const request = createQuoteRequestSchema.safeParse(canonicalInput);
+    if (!request.success) {
+      sendBffError(res, "BAD_REQUEST", "Invalid commerce quote request");
+      return;
+    }
+
+    let stage: CommerceQuoteFailureStage = "customer_eligibility";
+    try {
+      const eligibility = resolveCustomerEligibility
+        ? await resolveCustomerEligibility(request.data)
+        : { clientId: null, source: "anonymous" as const };
+      console.info(
+        "commerce_quote_promo_eligibility_context",
+        JSON.stringify({ promoEligibilityContext: eligibility.source }),
+      );
+      stage = "pricing_policy";
+      const pricingPolicy = await resolvePricingPolicy?.(request.data);
+      stage = "quote_evaluation";
+      const rawQuote = await quotePort.createQuote(request.data, {
+        clientId: eligibility.clientId,
+        ...(pricingPolicy ? { pricingPolicy } : {}),
+      });
+      const canonicalQuote = createQuoteResponseSchema.safeParse(rawQuote);
+      if (!canonicalQuote.success) {
+        sendBffError(res, "INVALID_RESPONSE", "Commerce quote returned invalid response");
+        return;
+      }
+      let quote = canonicalQuote.data;
+      stage = "promotion_acceptance";
+      const acquisitionTerms = acquisition?.terms(quote.quote);
+      const honoredToken = promotionAcceptanceToken && honorPromotionAcceptance?.(
+        promotionAcceptanceToken, request.data, quote.quote, acquisitionTerms,
+      ) ? promotionAcceptanceToken : undefined;
+      const issuedToken = honoredToken ?? createPromotionAcceptance?.(request.data, quote.quote, acquisitionTerms) ?? undefined;
+      const containsV2Promotion = quote.quote.discounts.some((discount) =>
+        discount.promotionEngineVersion === "promotion-engine.v2");
+      if ((containsV2Promotion || acquisitionTerms) && !issuedToken) {
+        stage = "promotion_fallback";
+        const fallback = fallbackQuotePort
+          ? createQuoteResponseSchema.safeParse(await fallbackQuotePort.createQuote(request.data, {
+              clientId: eligibility.clientId,
+              ...(pricingPolicy ? { pricingPolicy } : {}),
+            }))
+          : null;
+        if (!fallback?.success || acquisition?.terms(fallback.data.quote) || fallback.data.quote.discounts.some((discount) =>
+          discount.promotionEngineVersion === "promotion-engine.v2")) {
+          sendBffError(res, "CONFLICT", "Promotion quote must be refreshed", {
+            details: { feature: "quote", reason: "promotion_acceptance_refresh_required" },
+          });
+          return;
+        }
+        quote = fallback.data;
+      }
+      const response = publicCreateQuoteResponseSchema.safeParse({
+        ...quote,
+        promotionAcceptanceToken: quote === canonicalQuote.data ? issuedToken : undefined,
+      });
+      if (!response.success) {
+        sendBffError(res, "INVALID_RESPONSE", "Commerce quote returned invalid response");
+        return;
+      }
+
+      sendBffSuccess(res, response.data, {
+        contractVersion: COMMERCE_CONTRACT_VERSION,
+      });
+    } catch (error) {
+      const acquisitionFailure = acquisition ? mapAcquisitionTermsFailure(error) : null;
+      if (acquisitionFailure) {
+        sendBffError(res, acquisitionFailure.code, "Acquisition terms unavailable", { details: acquisitionFailure.details });
+        return;
+      }
+      if (error instanceof CommerceQuoteCatalogReadError) {
+        sendBffError(res, "UPSTREAM_UNAVAILABLE", "Commerce catalog is unavailable", {
+          details: { reason: "catalog_unavailable", refusalCode: error.code },
+        });
+        return;
+      }
+      if (error instanceof CommerceQuoteError) {
+        sendBffError(
+          res,
+          error.code === "UNKNOWN_SKU" ? "BAD_REQUEST" : "CONFLICT",
+          error.message,
+          { details: error.details },
+        );
+        return;
+      }
+
+      const policyFailure = stage === "pricing_policy" ? mapPricingPolicyFailure(error) : null;
+      if (policyFailure) {
+        console.error("[commerce-quote] pricing policy refused:", JSON.stringify(policyFailure.details));
+        sendBffError(res, policyFailure.code, policyFailure.code === "BAD_REQUEST"
+          ? "Commerce quote request is missing offer policy context"
+          : "Commerce quote failed", { details: policyFailure.details });
+        return;
+      }
+
+      const details = commerceQuoteFailureDetails(stage);
+      console.error("[commerce-quote] dependency failed:", JSON.stringify(details));
+      sendBffError(res, "UPSTREAM_UNAVAILABLE", "Commerce quote failed", { details });
+    }
+  };
+}

package/src/pricing/commerceQuoteSnapshotExpect.ts

@@ -0,0 +1,48 @@
+import type { z } from "zod";
+import {
+  CommerceQuoteError,
+  CommerceQuoteSnapshotError,
+  type CommerceQuotePort,
+} from "./quotePorts.js";
+
+// Shared by the static and DB-backed quote snapshot verifiers. The verify body
+// and request builder differ per verifier; only this re-quote-and-wrap tail is
+// identical apart from two human-facing message strings, which are passed in so
+// each verifier keeps its exact wording (asserted by their tests).
+export interface QuoteSnapshotExpectMessages {
+  /** Thrown when the re-quoted response fails schema validation. */
+  invalidResponseMessage: string;
+  /** Thrown when re-quoting raises a CommerceQuoteError (pricing changed). */
+  catalogMismatchMessage: string;
+}
+
+export async function createExpectedQuote<Request, Response>(
+  quotePort: CommerceQuotePort<Request, Response>,
+  request: Request,
+  messages: QuoteSnapshotExpectMessages,
+  createQuoteResponseSchema: z.ZodType<Response>,
+): Promise<Response> {
+  try {
+    const expected = await quotePort.createQuote(request);
+    const parsed = createQuoteResponseSchema.safeParse(expected);
+    if (!parsed.success) {
+      throw new CommerceQuoteSnapshotError(
+        "QUOTE_SNAPSHOT_MISMATCH",
+        messages.invalidResponseMessage,
+        { reason: "invalid_expected_quote" },
+      );
+    }
+
+    return parsed.data;
+  } catch (error) {
+    if (error instanceof CommerceQuoteSnapshotError) throw error;
+    if (error instanceof CommerceQuoteError) {
+      throw new CommerceQuoteSnapshotError("QUOTE_SNAPSHOT_MISMATCH", messages.catalogMismatchMessage, {
+        reason: error.code,
+        ...error.details,
+      });
+    }
+
+    throw error;
+  }
+}

package/src/pricing/contracts/acquisitionTerms.ts

@@ -0,0 +1,26 @@
+/** Opt-in protocol identity; financial schedules belong to the injected policy. */
+export const ACQUISITION_TERMS_CAPABILITY = "subscription-acquisition.v1" as const;
+export type AcquisitionCapability = typeof ACQUISITION_TERMS_CAPABILITY;
+export interface AcquisitionTermsMetadata {
+  schemaVersion: AcquisitionCapability;
+  revision: string;
+  delivery2DiscountBps: number;
+}
+export interface AcquisitionTerms extends AcquisitionTermsMetadata {
+  initialDiscountBps: number;
+  effectiveFrom: string;
+  effectiveTo: string | null;
+}
+export interface ResolvedAcquisitionTerms extends AcquisitionTerms { sourcePromotionId: string }
+export interface AcquisitionTermsExpectation { revision: string; delivery2DiscountBps: number }
+
+import type { CreateQuoteRequest, CommerceQuoteContext, CommerceQuote } from "./quote.js";
+/** Separate opt-in DTOs; incumbent request/response admission is unchanged. */
+export interface AcquisitionQuoteRequest extends CreateQuoteRequest {
+  acquisitionCapability?: AcquisitionCapability;
+}
+export interface AcquisitionQuoteContext extends CommerceQuoteContext {
+  acquisitionCapability?: AcquisitionCapability;
+  atTime?: string;
+}
+export interface AcquisitionQuote extends CommerceQuote { acquisitionTerms?: ResolvedAcquisitionTerms }

package/src/pricing/contracts/authority.ts

@@ -0,0 +1,44 @@
+import type { ResolvedPrice } from "@openlup/core/pricing";
+import type { SubscriptionPricePolicyRevision } from "./policy.js";
+
+/** Exact settlement context for a current quote price; tiers and open-mode fallbacks are excluded. */
+export interface CommercePriceAuthorityQuery {
+  variantId: string;
+  mode: "one_time" | "subscription";
+  regionCode: string;
+  currency: string;
+  channel: string;
+  atTime?: string;
+}
+
+export interface CommerceBasePriceObservation {
+  /** The sole active/effective `one_time`, `min_qty=1` entry. */
+  base: ResolvedPrice;
+  unitPriceMinor: number;
+}
+
+export type CommercePriceAuthorityResult =
+  | (CommerceBasePriceObservation & { kind: "one_time" })
+  | (CommerceBasePriceObservation & {
+      kind: "subscription_policy";
+      policy: SubscriptionPricePolicyRevision;
+    })
+  | (CommerceBasePriceObservation & {
+      /** Explicit compatibility observation allowed only before this context has policy history. */
+      kind: "subscription_legacy";
+      legacyResolved: ResolvedPrice;
+    });
+
+export type CommercePriceAuthorityRefusal =
+  | "active_price_list_not_found"
+  | "active_price_list_ambiguous"
+  | "base_price_not_found"
+  | "base_price_ambiguous"
+  | "base_price_amount_kind_invalid"
+  | "legacy_subscription_price_not_found"
+  | "legacy_subscription_price_ambiguous"
+  | "subscription_price_policy_not_effective"
+  | "subscription_price_policy_ambiguous"
+  | "subscription_price_policy_invalid"
+  | "subscription_price_policy_digest_mismatch";
+

package/src/pricing/contracts/evidence.ts

@@ -0,0 +1,25 @@
+/** UI-safe, additive explanation for a frozen `codeRejections` item. */
+export type CommerceCodeRejectionDetail =
+  | { code: string; reason: "scope_not_applicable"; allowedScopes: Array<"one_time" | "subscription_initial"> }
+  | { code: string; reason: "minimum_not_met"; minimumReferenceMinor: number }
+  | { code: string; reason: "not_yet_active"; validFrom: string }
+  | { code: string; reason: "global_limit_reached" };
+
+
+export interface QuotePromotionEvidence {
+  promotionId: string;
+  code?: string | null;
+  reasonCode: string;
+  promotionEngineVersion?: "promotion-engine.v2";
+  promotionCodeId?: string;
+  promotionCodeRevision?: number;
+  promotionDefinitionFingerprint?: string;
+  promotionCodeScopes?: Array<"one_time" | "subscription_initial">;
+  promotionMinimumReferenceMinor?: number;
+  promotionCodeValidTo?: string | null;
+  promotionBenefitKind?: "target_percentage" | "percentage" | "fixed_amount" | "free_shipping";
+  promotionBenefitValueBps?: number;
+  promotionBenefitValueMinor?: number;
+  floorApplied?: boolean;
+}
+

package/src/pricing/contracts/index.ts

@@ -0,0 +1,17 @@
+export type { CommercePriceAuthorityQuery, CommerceBasePriceObservation, CommercePriceAuthorityResult, CommercePriceAuthorityRefusal } from "./authority.js";
+export { SUBSCRIPTION_PRICE_POLICY_SCHEMA_VERSION, SUBSCRIPTION_PRICE_POLICY_DEFAULT_DISCOUNT_BPS, SUBSCRIPTION_PRICE_POLICY_DEFAULT_QUANTUM_MINOR } from "./policy.js";
+export type { SubscriptionPricePolicySemantics, SubscriptionPricePolicyCanonicalInput, SubscriptionPricePolicyRevision, SubscriptionPricePolicyDigestRefusal } from "./policy.js";
+export { OFFER_POLICY_V1, OFFER_POLICY_V2, PROMOTION_ENGINE_V1, PROMOTION_ENGINE_V2, OFFER_POLICY_V2_CAPABILITY } from "./offerPolicy.js";
+export type { OfferPolicyVersion, PromotionEngineVersion, PricingPolicyRequest, PricingPolicySnapshot } from "./offerPolicy.js";
+export type { CommerceCurrency, CommerceTaxCountry, CommerceTaxCategory, CommerceTaxLegalBasis, CommerceMoney, CartLineInput, CommerceTaxProfile, CommerceTaxBreakdown } from "./money.js";
+export { COMMERCE_CONTRACT_VERSION } from "./quote.js";
+export type { CommerceQuotePricingComponent, CommerceQuoteContext, CommerceQuoteLine, CommercePromotionCustomerSemantic, CommerceQuoteDiscount, CommerceCodeRejectionReason, CommerceCodeRejection, CommerceQuote, CreateQuoteRequest, CreateQuoteResponse } from "./quote.js";
+export type { QuotePromotionEvidence, CommerceCodeRejectionDetail } from "./evidence.js";
+export { CATALOG_FACTS_PROVENANCE_VERSION, CATALOG_FACTS_POLICY_PROVENANCE_VERSION } from "./provenance.js";
+export type { CatalogFactsProvenance } from "./provenance.js";
+export { COMMERCE_OFFER_PRICING_CONTRACT_VERSION, COMMERCE_OFFER_PRICING_V2_CONTRACT_VERSION } from "./offer.js";
+export type { CommerceOfferPrice, CommerceProductOfferPricing, CommerceOfferPricingResponse } from "./offer.js";
+export { ACQUISITION_TERMS_CAPABILITY } from "./acquisitionTerms.js";
+export type { AcquisitionQuoteRequest, AcquisitionQuoteContext, AcquisitionQuote, AcquisitionCapability, AcquisitionTermsMetadata, AcquisitionTerms, ResolvedAcquisitionTerms, AcquisitionTermsExpectation } from "./acquisitionTerms.js";
+export { COMMERCE_OFFER_PRICING_V3_CONTRACT_VERSION } from "./offer.js";
+export type { AcquisitionOfferPricingResponse } from "./offer.js";

package/src/pricing/contracts/money.ts

@@ -0,0 +1,32 @@
+export type CommerceCurrency = string;
+export type CommerceTaxCountry = string;
+export type CommerceTaxCategory = string;
+export type CommerceTaxLegalBasis = string;
+
+export interface CommerceMoney {
+  amountMinor: number;
+  currency: CommerceCurrency;
+}
+
+export interface CartLineInput {
+  sku: string;
+  quantity: number;
+  variantId?: string;
+  modeAtLine?: "one_time" | "subscription";
+  isAddon?: boolean;
+}
+
+export interface CommerceTaxProfile {
+  included: true;
+  country: CommerceTaxCountry;
+  category: CommerceTaxCategory;
+  vatRateBps: number;
+  legalBasis: CommerceTaxLegalBasis;
+}
+
+export interface CommerceTaxBreakdown extends CommerceTaxProfile {
+  netAmount: CommerceMoney;
+  vatAmount: CommerceMoney;
+  grossAmount: CommerceMoney;
+}
+

package/src/pricing/contracts/offer.ts

@@ -0,0 +1,42 @@
+import type { CommerceMoney } from "./money.js";
+import type { PricingPolicySnapshot } from "./offerPolicy.js";
+export const COMMERCE_OFFER_PRICING_CONTRACT_VERSION = "commerce.offer-pricing.v1" as const;
+export const COMMERCE_OFFER_PRICING_V2_CONTRACT_VERSION = "commerce.offer-pricing.v2" as const;
+export interface CommerceOfferPrice {
+  packageGross: CommerceMoney;
+  unitGross: CommerceMoney;
+}
+export interface CommerceProductOfferPricing {
+  productSlug: string;
+  unitCount: number;
+  oneTime: CommerceOfferPrice;
+  subscriptionInitial: CommerceOfferPrice;
+  subscriptionRecurring: CommerceOfferPrice;
+  catalogAnchorUnitGross: CommerceMoney;
+  initialDiscountPercent: number;
+  recurringDiscountPercent: number;
+}
+export type CommerceOfferPricingResponse<ScopeV1 extends string = string, ScopeV2 extends string = string> = {
+  contractVersion: typeof COMMERCE_OFFER_PRICING_CONTRACT_VERSION;
+  scope: ScopeV1;
+  products: CommerceProductOfferPricing[];
+  minimum: { oneTime: CommerceProductOfferPricing; subscription: CommerceProductOfferPricing };
+} | {
+  contractVersion: typeof COMMERCE_OFFER_PRICING_V2_CONTRACT_VERSION;
+  scope: ScopeV2;
+  products: CommerceProductOfferPricing[];
+  minimum: { oneTime: CommerceProductOfferPricing; subscription: CommerceProductOfferPricing };
+  pricingPolicy: PricingPolicySnapshot;
+  shipping: { gross: CommerceMoney; discountGross: CommerceMoney; payable: CommerceMoney };
+  minimumProductPayable: CommerceMoney;
+};
+
+/** Complete opt-in v3 response; the incumbent v1/v2 union stays unchanged. */
+export const COMMERCE_OFFER_PRICING_V3_CONTRACT_VERSION = "commerce.offer-pricing.v3" as const;
+export type AcquisitionOfferPricingResponse<ScopeV2 extends string = string> =
+  Omit<Extract<CommerceOfferPricingResponse<string, ScopeV2>, { contractVersion: typeof COMMERCE_OFFER_PRICING_V2_CONTRACT_VERSION }>, "contractVersion"> & {
+    contractVersion: typeof COMMERCE_OFFER_PRICING_V3_CONTRACT_VERSION;
+    acquisitionTerms: import("./acquisitionTerms.js").AcquisitionTerms;
+    observedAt: string;
+    validUntil: string;
+  };

package/src/pricing/contracts/offerPolicy.ts

@@ -0,0 +1,17 @@
+export const OFFER_POLICY_V1 = "commerce.offer-policy.v1" as const;
+export const OFFER_POLICY_V2 = "commerce.offer-policy.v2" as const;
+export const PROMOTION_ENGINE_V1 = "promotion-engine.v1" as const;
+export const PROMOTION_ENGINE_V2 = "promotion-engine.v2" as const;
+export const OFFER_POLICY_V2_CAPABILITY = OFFER_POLICY_V2;
+
+export type OfferPolicyVersion = typeof OFFER_POLICY_V1 | typeof OFFER_POLICY_V2;
+export type PromotionEngineVersion = typeof PROMOTION_ENGINE_V1 | typeof PROMOTION_ENGINE_V2;
+export interface PricingPolicyRequest {
+  capability?: typeof OFFER_POLICY_V2_CAPABILITY;
+  token?: string;
+}
+export interface PricingPolicySnapshot {
+  offerPolicyVersion: OfferPolicyVersion;
+  promotionEngineVersion: PromotionEngineVersion;
+  pricingPolicyToken?: string;
+}

package/src/pricing/contracts/policy.ts

@@ -0,0 +1,26 @@
+export const SUBSCRIPTION_PRICE_POLICY_SCHEMA_VERSION = "subscription-price-policy.v1";
+export const SUBSCRIPTION_PRICE_POLICY_DEFAULT_DISCOUNT_BPS = 1_000;
+export const SUBSCRIPTION_PRICE_POLICY_DEFAULT_QUANTUM_MINOR = 10;
+
+export interface SubscriptionPricePolicySemantics {
+  discountBps: number;
+  roundingQuantumMinor: number;
+  roundingRule: "FLOOR_TO_QUANTUM";
+}
+
+export interface SubscriptionPricePolicyCanonicalInput extends SubscriptionPricePolicySemantics {
+  id: string;
+  revisionNo: number;
+  priceListId: string;
+  regionCode: string;
+  currency: string;
+  channel: string;
+  effectiveFrom: string;
+  effectiveTo: string | null;
+}
+
+export interface SubscriptionPricePolicyRevision extends SubscriptionPricePolicyCanonicalInput {
+  digest: string;
+}
+
+export type SubscriptionPricePolicyDigestRefusal = "subscription_price_policy_digest_mismatch";

package/src/pricing/contracts/provenance.ts

@@ -0,0 +1,19 @@
+export const CATALOG_FACTS_PROVENANCE_VERSION = "catalog_facts_v1" as const;
+export const CATALOG_FACTS_POLICY_PROVENANCE_VERSION = "catalog_facts_v2" as const;
+
+interface CatalogFactsFields {
+  skuId: string;
+  documentRevisionId: string;
+  documentDigest: string;
+  basePriceEntryId: string;
+  atTime: string;
+  currency: string;
+  resolvedUnitAmountMinor: number;
+  resolvedLineAmountMinor: number;
+  baseUnitAmountMinor: number;
+}
+
+export type CatalogFactsProvenance = CatalogFactsFields & (
+  | { version: typeof CATALOG_FACTS_PROVENANCE_VERSION; resolvedPriceEntryId: string; mode: "one_time" | "subscription" }
+  | { version: typeof CATALOG_FACTS_POLICY_PROVENANCE_VERSION; policyRevisionId: string; policyDigest: string; mode: "subscription" }
+);