@openlup/platform 0.17.0 → 0.19.0

package/dist/pricing/commercePricingPolicyErrors.d.ts

@@ -0,0 +1,40 @@
+/** The server cannot assign a policy right now. Caller-independent: retrying an
+ * identical request only succeeds once production configuration changes. */
+export declare class CommercePricingPolicyUnavailableError extends Error {
+    readonly reason: string;
+    constructor(reason: string);
+}
+/**
+ * Every reason a caller-side refusal can carry. ⛔ Each one answers `400`, which
+ * puts it outside every 5xx monitor, so each one owes a dedicated monitor of its
+ * own; a host's observability check can read this tuple and fail when a reason
+ * has none. Adding a member here without adding a monitor is the regression this
+ * tuple exists to prevent: reclassifying `v2_capability_required` from `503` to
+ * `400` once silently removed the only alert on a site-wide unpriceable-quote
+ * outage.
+ */
+export declare const PRICING_POLICY_REQUEST_REASONS: readonly ["v2_capability_required", "v2_visitor_id_required"];
+export type PricingPolicyRequestReason = (typeof PRICING_POLICY_REQUEST_REASONS)[number];
+/** The request itself lacks the context a v2 assignment needs. Caller-fixable,
+ * and never evidence that pricing is down. The reason is typed off
+ * PRICING_POLICY_REQUEST_REASONS so a new one cannot skip its monitor. */
+export declare class CommercePricingPolicyRequestError extends Error {
+    readonly reason: PricingPolicyRequestReason;
+    constructor(reason: PricingPolicyRequestReason);
+}
+export type SafePricingPolicyReason = "v2_capability_required" | "v2_visitor_id_required" | "signing_secret_unavailable" | "v1_assignment_rejected" | "v2_assignment_config_invalid" | "v2_readiness_not_ready" | "other";
+export interface PricingPolicyFailureMapping {
+    code: "BAD_REQUEST" | "UPSTREAM_UNAVAILABLE";
+    details: {
+        reason: "pricing_policy_request_invalid" | "pricing_policy_unavailable";
+        stage: "pricing_policy";
+        policyReason: SafePricingPolicyReason;
+    };
+}
+/**
+ * Single owner of the status a pricing-policy refusal earns, shared by every
+ * route that resolves one. A caller-attributable gap answers `400`; only a
+ * server that genuinely cannot price answers `503`, so a `503` on these routes
+ * stays a truthful outage signal.
+ */
+export declare function mapPricingPolicyFailure(error: unknown): PricingPolicyFailureMapping | null;

package/dist/pricing/commercePricingPolicyErrors.js

@@ -0,0 +1,67 @@
+/** The server cannot assign a policy right now. Caller-independent: retrying an
+ * identical request only succeeds once production configuration changes. */
+export class CommercePricingPolicyUnavailableError extends Error {
+    reason;
+    constructor(reason) {
+        super("commerce_pricing_policy_v2_unavailable");
+        this.reason = reason;
+        this.name = "CommercePricingPolicyUnavailableError";
+    }
+}
+/**
+ * Every reason a caller-side refusal can carry. ⛔ Each one answers `400`, which
+ * puts it outside every 5xx monitor, so each one owes a dedicated monitor of its
+ * own; a host's observability check can read this tuple and fail when a reason
+ * has none. Adding a member here without adding a monitor is the regression this
+ * tuple exists to prevent: reclassifying `v2_capability_required` from `503` to
+ * `400` once silently removed the only alert on a site-wide unpriceable-quote
+ * outage.
+ */
+export const PRICING_POLICY_REQUEST_REASONS = [
+    "v2_capability_required",
+    "v2_visitor_id_required",
+];
+/** The request itself lacks the context a v2 assignment needs. Caller-fixable,
+ * and never evidence that pricing is down. The reason is typed off
+ * PRICING_POLICY_REQUEST_REASONS so a new one cannot skip its monitor. */
+export class CommercePricingPolicyRequestError extends Error {
+    reason;
+    constructor(reason) {
+        super("commerce_pricing_policy_v2_request_invalid");
+        this.reason = reason;
+        this.name = "CommercePricingPolicyRequestError";
+    }
+}
+const SAFE_PRICING_POLICY_REASONS = new Set([
+    "v2_capability_required",
+    "v2_visitor_id_required",
+    "signing_secret_unavailable", // gitleaks:allow — closed-set diagnostic code, never a credential
+    "v1_assignment_rejected",
+    "v2_assignment_config_invalid",
+    "v2_readiness_not_ready",
+    "other",
+]);
+/**
+ * Single owner of the status a pricing-policy refusal earns, shared by every
+ * route that resolves one. A caller-attributable gap answers `400`; only a
+ * server that genuinely cannot price answers `503`, so a `503` on these routes
+ * stays a truthful outage signal.
+ */
+export function mapPricingPolicyFailure(error) {
+    const caller = error instanceof CommercePricingPolicyRequestError;
+    if (!caller && !(error instanceof CommercePricingPolicyUnavailableError))
+        return null;
+    return {
+        code: caller ? "BAD_REQUEST" : "UPSTREAM_UNAVAILABLE",
+        details: {
+            reason: caller ? "pricing_policy_request_invalid" : "pricing_policy_unavailable",
+            stage: "pricing_policy",
+            policyReason: safePricingPolicyReason(error.reason),
+        },
+    };
+}
+function safePricingPolicyReason(value) {
+    return SAFE_PRICING_POLICY_REASONS.has(value)
+        ? value
+        : "other";
+}

package/dist/pricing/commerceQuoteBatchHandler.d.ts

@@ -0,0 +1,37 @@
+import type { ResolvedAcquisitionTerms } from "./contracts/acquisitionTerms.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 { type CommerceQuotePort } from "./quotePorts.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 declare function createCommerceQuoteBatchHandler<Request extends CreateQuoteRequest, Response extends CreateQuoteResponse>({ responder, createQuoteBatchRequestSchema, publicCreateQuoteBatchResponseSchema, quotePort, acquisition, resolveCustomerEligibility, resolvePricingPolicy, }: CommerceQuoteBatchHandlerDeps<Request, Response>): (req: HttpRequest, res: HttpResponse) => Promise<void>;

package/dist/pricing/commerceQuoteBatchHandler.js

@@ -0,0 +1,83 @@
+import { mapAcquisitionTermsFailure } from "./acquisitionQuoteBinding.js";
+import { COMMERCE_CONTRACT_VERSION } from "./contracts/index.js";
+import { CommerceQuoteError, } from "./quotePorts.js";
+import { CommerceQuoteCatalogReadError } from "./commerceQuoteCatalogReadPort.js";
+import { mapPricingPolicyFailure } from "./commercePricingPolicyErrors.js";
+/**
+ * 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({ responder, createQuoteBatchRequestSchema, publicCreateQuoteBatchResponseSchema, quotePort, acquisition, resolveCustomerEligibility, resolvePricingPolicy, }) {
+    const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = responder;
+    return async function handler(req, res) {
+        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" };
+                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/dist/pricing/commerceQuoteCatalogReadPort.d.ts

@@ -0,0 +1,27 @@
+/** 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 declare class CommerceQuoteCatalogReadError extends Error {
+    readonly code: CommerceQuoteCatalogReadRefusalCode;
+    constructor(code: CommerceQuoteCatalogReadRefusalCode);
+}

package/dist/pricing/commerceQuoteCatalogReadPort.js

@@ -0,0 +1,8 @@
+export class CommerceQuoteCatalogReadError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+        this.name = "CommerceQuoteCatalogReadError";
+    }
+}

package/dist/pricing/commerceQuoteHandler.d.ts

@@ -0,0 +1,35 @@
+import type { ShippingTerms } from "../shipping/index.js";
+import type { ResolvedAcquisitionTerms } from "./contracts/acquisitionTerms.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 { type CommerceQuotePort } from "./quotePorts.js";
+import type { PricingPolicySnapshot } from "./contracts/offerPolicy.js";
+export interface CommerceQuoteHandlerDeps<Request extends CreateQuoteRequest = CreateQuoteRequest, Response extends CreateQuoteResponse = CreateQuoteResponse> {
+    responder: BffResponder;
+    shipping?: {
+        terms(quote: Response["quote"]): ShippingTerms | undefined;
+    };
+    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, shippingTerms?: ShippingTerms) => string | null;
+    honorPromotionAcceptance?: (token: string, request: Request, quote: Awaited<ReturnType<CommerceQuotePort<Request, Response>["createQuote"]>>["quote"], acquisitionTerms?: ResolvedAcquisitionTerms, shippingTerms?: ShippingTerms) => boolean;
+}
+export declare function createCommerceQuoteHandler<Request extends CreateQuoteRequest, Response extends CreateQuoteResponse>({ responder, createQuoteRequestSchema, createQuoteResponseSchema, publicCreateQuoteRequestSchema, publicCreateQuoteResponseSchema, quotePort, acquisition, shipping, fallbackQuotePort, resolveCustomerEligibility, resolvePricingPolicy, createPromotionAcceptance, honorPromotionAcceptance, }: CommerceQuoteHandlerDeps<Request, Response>): (req: HttpRequest, res: HttpResponse) => Promise<void>;

package/dist/pricing/commerceQuoteHandler.js

@@ -0,0 +1,122 @@
+import { mapAcquisitionTermsFailure } from "./acquisitionQuoteBinding.js";
+import { COMMERCE_CONTRACT_VERSION } from "./contracts/index.js";
+import { CommerceQuoteError, } from "./quotePorts.js";
+import { mapPricingPolicyFailure } from "./commercePricingPolicyErrors.js";
+import { CommerceQuoteCatalogReadError } from "./commerceQuoteCatalogReadPort.js";
+function commerceQuoteFailureDetails(stage) {
+    return { reason: "quote_dependency_failed", stage };
+}
+export function createCommerceQuoteHandler({ responder, createQuoteRequestSchema, createQuoteResponseSchema, publicCreateQuoteRequestSchema, publicCreateQuoteResponseSchema, quotePort, acquisition, shipping, fallbackQuotePort, resolveCustomerEligibility, resolvePricingPolicy, createPromotionAcceptance, honorPromotionAcceptance, }) {
+    const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = responder;
+    return async function handler(req, res) {
+        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 = "customer_eligibility";
+        try {
+            const eligibility = resolveCustomerEligibility
+                ? await resolveCustomerEligibility(request.data)
+                : { clientId: null, source: "anonymous" };
+            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 shippingTerms = shipping?.terms(quote.quote);
+            const honoredToken = promotionAcceptanceToken && (shipping
+                ? honorPromotionAcceptance?.(promotionAcceptanceToken, request.data, quote.quote, acquisitionTerms, shippingTerms)
+                : honorPromotionAcceptance?.(promotionAcceptanceToken, request.data, quote.quote, acquisitionTerms))
+                ? promotionAcceptanceToken : undefined;
+            const issuedToken = honoredToken ?? (shipping
+                ? createPromotionAcceptance?.(request.data, quote.quote, acquisitionTerms, shippingTerms)
+                : createPromotionAcceptance?.(request.data, quote.quote, acquisitionTerms)) ?? undefined;
+            const containsV2Promotion = quote.quote.discounts.some((discount) => discount.promotionEngineVersion === "promotion-engine.v2");
+            if (shippingTerms && !issuedToken) {
+                sendBffError(res, "CONFLICT", "Shipping quote must be refreshed", {
+                    details: { feature: "quote", reason: "promotion_acceptance_refresh_required" },
+                });
+                return;
+            }
+            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 || shipping?.terms(fallback.data.quote) || 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/dist/pricing/commerceQuoteSnapshotExpect.d.ts

@@ -0,0 +1,9 @@
+import type { z } from "zod";
+import { type CommerceQuotePort } from "./quotePorts.js";
+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 declare function createExpectedQuote<Request, Response>(quotePort: CommerceQuotePort<Request, Response>, request: Request, messages: QuoteSnapshotExpectMessages, createQuoteResponseSchema: z.ZodType<Response>): Promise<Response>;

package/dist/pricing/commerceQuoteSnapshotExpect.js

@@ -0,0 +1,22 @@
+import { CommerceQuoteError, CommerceQuoteSnapshotError, } from "./quotePorts.js";
+export async function createExpectedQuote(quotePort, request, messages, createQuoteResponseSchema) {
+    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/dist/pricing/contracts/acquisitionTerms.d.ts

@@ -0,0 +1,32 @@
+/** Opt-in protocol identity; financial schedules belong to the injected policy. */
+export declare const ACQUISITION_TERMS_CAPABILITY: "subscription-acquisition.v1";
+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/dist/pricing/contracts/acquisitionTerms.js

@@ -0,0 +1,2 @@
+/** Opt-in protocol identity; financial schedules belong to the injected policy. */
+export const ACQUISITION_TERMS_CAPABILITY = "subscription-acquisition.v1";

package/dist/pricing/contracts/authority.d.ts

@@ -0,0 +1,27 @@
+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/dist/pricing/contracts/authority.js

@@ -0,0 +1 @@
+export {};

package/dist/pricing/contracts/evidence.d.ts

@@ -0,0 +1,33 @@
+/** 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/dist/pricing/contracts/evidence.js

@@ -0,0 +1 @@
+export {};

package/dist/pricing/contracts/index.d.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/dist/pricing/contracts/index.js

@@ -0,0 +1,7 @@
+export { SUBSCRIPTION_PRICE_POLICY_SCHEMA_VERSION, SUBSCRIPTION_PRICE_POLICY_DEFAULT_DISCOUNT_BPS, SUBSCRIPTION_PRICE_POLICY_DEFAULT_QUANTUM_MINOR } from "./policy.js";
+export { OFFER_POLICY_V1, OFFER_POLICY_V2, PROMOTION_ENGINE_V1, PROMOTION_ENGINE_V2, OFFER_POLICY_V2_CAPABILITY } from "./offerPolicy.js";
+export { COMMERCE_CONTRACT_VERSION } from "./quote.js";
+export { CATALOG_FACTS_PROVENANCE_VERSION, CATALOG_FACTS_POLICY_PROVENANCE_VERSION } from "./provenance.js";
+export { COMMERCE_OFFER_PRICING_CONTRACT_VERSION, COMMERCE_OFFER_PRICING_V2_CONTRACT_VERSION } from "./offer.js";
+export { ACQUISITION_TERMS_CAPABILITY } from "./acquisitionTerms.js";
+export { COMMERCE_OFFER_PRICING_V3_CONTRACT_VERSION } from "./offer.js";

package/dist/pricing/contracts/money.d.ts

@@ -0,0 +1,27 @@
+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/dist/pricing/contracts/money.js

@@ -0,0 +1 @@
+export {};