@openlup/platform 0.17.0 → 0.18.0

package/src/pricing/quoteSchemas.ts

@@ -0,0 +1,230 @@
+import { z } from "zod";
+import type { CommerceQuote } from "./contracts/quote.js";
+import { COMMERCE_CONTRACT_VERSION } from "./contracts/quote.js";
+import { createCommerceQuotePrimitives } from "./quotePrimitives.js";
+import { catalogFactsProvenanceSchema, rejectCatalogFactsFromPublicQuote } from "./catalogFactsSchemas.js";
+import { quoteDiscountSchema } from "./quotePromotionEvidence.js";
+import { quoteCodeRejectionDetailSchema } from "./quoteCodeRejectionDetails.js";
+
+/** Split gross tax-included money into net/VAT using an explicit tax rate. */
+export function splitIncludedVat(grossMinor: number, vatRateBps: number): { netMinor: number; vatMinor: number } {
+  const netMinor = Math.round((grossMinor * 10_000) / (10_000 + vatRateBps));
+  const vatMinor = grossMinor - netMinor;
+  return { netMinor, vatMinor };
+}
+
+/** Backstop: every Money in a quote must use the quote's own currency. */
+export function quoteMoneyCurrenciesMatch(quote: CommerceQuote): boolean {
+  const monies = [
+    quote.subtotalGross,
+    quote.discountTotalGross,
+    ...(quote.shippingGross ? [quote.shippingGross] : []),
+    ...(quote.shippingDiscountGross ? [quote.shippingDiscountGross] : []),
+    quote.totalGross,
+    quote.netTotal,
+    quote.taxTotal,
+    ...quote.lines.flatMap((line) => [
+      line.unitPriceGross,
+      line.lineSubtotalGross,
+      line.tax.netAmount,
+      line.tax.vatAmount,
+      line.tax.grossAmount,
+    ]),
+  ];
+  return monies.every((money) => money.currency === quote.currency);
+}
+
+/** Preserve quote validation while hosts bind currency, product identifiers and context. */
+export function createCommerceQuoteSchemas<Context extends z.ZodType>(input: {
+  currencySchema: z.ZodType<string>;
+  productSlugSchema: z.ZodType<string>;
+  contextSchema: Context;
+}) {
+  const { commerceCurrencySchema, commerceMoneySchema, commerceSkuSchema, commerceTaxCategorySchema,
+    commerceTaxCountrySchema, commerceTaxLegalBasisSchema } = createCommerceQuotePrimitives(input.currencySchema);
+  const commerceProductSlugSchema = input.productSlugSchema;
+  const quoteContextSchema = input.contextSchema;
+  const quotePricingComponentSchema = z
+    .object({
+      scope: z.enum(["line", "order"]),
+      componentType: z.enum(["base_unit", "mode_discount", "qty_tier", "promo", "loyalty", "shipping", "bundle"]),
+      amountMinor: z.number().int(),
+      reasonCode: z.string().trim().min(1).max(120),
+      reasonPayload: z.record(z.string(), z.unknown()).default({}),
+    })
+    .strict();
+  const cartLineInputSchema = z.object({
+    sku: commerceSkuSchema,
+    quantity: z.number().int().min(1).max(99),
+    variantId: z.string().trim().min(1).max(120).optional(),
+    modeAtLine: z.enum(["one_time", "subscription"]).optional(),
+    isAddon: z.boolean().optional(),
+  });
+  const commerceTaxBreakdownSchema = z
+    .object({
+      included: z.literal(true),
+      country: commerceTaxCountrySchema,
+      category: commerceTaxCategorySchema,
+      vatRateBps: z.number().int().min(0).max(10_000),
+      legalBasis: commerceTaxLegalBasisSchema,
+      netAmount: commerceMoneySchema,
+      vatAmount: commerceMoneySchema,
+      grossAmount: commerceMoneySchema,
+    })
+    .refine(
+      (tax) =>
+        tax.netAmount.currency === tax.vatAmount.currency &&
+        tax.netAmount.currency === tax.grossAmount.currency &&
+        tax.netAmount.amountMinor + tax.vatAmount.amountMinor === tax.grossAmount.amountMinor,
+      {
+        message: "tax net and VAT amounts must add up to gross amount",
+        path: ["grossAmount"],
+      },
+    );
+
+  const quoteLineSchema = z
+    .object({
+      sku: commerceSkuSchema,
+      productSlug: commerceProductSlugSchema,
+      quantity: z.number().int().min(1).max(99),
+      unitPriceGross: commerceMoneySchema,
+      lineSubtotalGross: commerceMoneySchema,
+      tax: commerceTaxBreakdownSchema,
+      pricingComponents: z.array(quotePricingComponentSchema).optional(),
+      catalogFacts: catalogFactsProvenanceSchema.optional(),
+    })
+    .refine(
+      (line) =>
+        line.unitPriceGross.currency === line.lineSubtotalGross.currency &&
+        line.lineSubtotalGross.currency === line.tax.grossAmount.currency &&
+        line.unitPriceGross.amountMinor * line.quantity === line.lineSubtotalGross.amountMinor,
+      {
+        message: "quote line subtotal must match unit price and quantity",
+        path: ["lineSubtotalGross"],
+      },
+    );
+
+  const quoteCodeRejectionSchema = z
+    .object({
+      code: z.string().trim().min(1).max(80),
+      reason: z.enum([
+        "not_recognized",
+        "already_used",
+        "not_eligible",
+        "expired",
+        "better_price_exists",
+        "scope_not_applicable",
+      ]),
+    })
+    .strict();
+
+  const commerceQuoteSchema = z
+    .object({
+      currency: commerceCurrencySchema,
+      taxIncluded: z.literal(true),
+      lines: z.array(quoteLineSchema).min(1).max(50),
+      discounts: z.array(quoteDiscountSchema).max(20),
+      codeRejections: z.array(quoteCodeRejectionSchema).max(20).optional(),
+      codeRejectionDetails: z.array(quoteCodeRejectionDetailSchema).max(20).optional(),
+      pricingComponents: z.array(quotePricingComponentSchema).optional(),
+      context: quoteContextSchema.optional(),
+      subtotalGross: commerceMoneySchema,
+      discountTotalGross: commerceMoneySchema,
+      // Shipping/discount tax split uses one quote rate; mixed-tax allocation is out of scope.
+      shippingGross: commerceMoneySchema.optional(),
+      shippingDiscountGross: commerceMoneySchema.optional(),
+      totalGross: commerceMoneySchema,
+      netTotal: commerceMoneySchema,
+      taxTotal: commerceMoneySchema,
+    })
+    .refine((quote) => quote.lines.every((line) => line.tax.vatRateBps === quote.lines[0]?.tax.vatRateBps), {
+      message: "mixed VAT rates are not supported by quote discount and shipping tax allocation",
+      path: ["lines"],
+    })
+    .refine(
+      (quote) => {
+        const subtotal = sumAmounts(quote.lines.map((line) => line.lineSubtotalGross));
+        const lineNet = sumAmounts(quote.lines.map((line) => line.tax.netAmount));
+        const lineVat = sumAmounts(quote.lines.map((line) => line.tax.vatAmount));
+        const vatRateBps = quote.lines[0]?.tax.vatRateBps ?? 0;
+        const singleTaxRate = quote.lines.every((line) => line.tax.vatRateBps === vatRateBps);
+        const discountTotal = quote.discountTotalGross.amountMinor;
+        const orderDiscountSum = quote.discounts
+          .filter((discount) => discount.appliesTo !== "shipping")
+          .reduce((sum, discount) => sum + discount.amountOffMinor, 0);
+        const shippingDiscountSum = quote.discounts
+          .filter((discount) => discount.appliesTo === "shipping")
+          .reduce((sum, discount) => sum + discount.amountOffMinor, 0);
+        const shippingGross = quote.shippingGross?.amountMinor ?? 0;
+        const shippingDiscount = quote.shippingDiscountGross?.amountMinor ?? 0;
+        const { netMinor: discountNet, vatMinor: discountVat } = splitIncludedVat(discountTotal, vatRateBps);
+        const { netMinor: shipNet, vatMinor: shipVat } = splitIncludedVat(shippingGross, vatRateBps);
+        const { netMinor: shipDiscNet, vatMinor: shipDiscVat } = splitIncludedVat(shippingDiscount, vatRateBps);
+
+        return (
+          singleTaxRate &&
+          quote.subtotalGross.amountMinor === subtotal &&
+          discountTotal >= 0 &&
+          discountTotal <= subtotal &&
+          orderDiscountSum === discountTotal &&
+          shippingGross >= 0 &&
+          shippingDiscount >= 0 &&
+          shippingDiscount <= shippingGross &&
+          shippingDiscountSum === shippingDiscount &&
+          quote.totalGross.amountMinor === subtotal - discountTotal + shippingGross - shippingDiscount &&
+          quote.netTotal.amountMinor === lineNet - discountNet + shipNet - shipDiscNet &&
+          quote.taxTotal.amountMinor === lineVat - discountVat + shipVat - shipDiscVat &&
+          quote.netTotal.amountMinor + quote.taxTotal.amountMinor === quote.totalGross.amountMinor
+        );
+      },
+      {
+        message: "quote totals must match quote lines, discounts and shipping",
+        path: ["totalGross"],
+      },
+    )
+    // The currency backstop reads the validated money fields.
+    .refine((quote) => quoteMoneyCurrenciesMatch(quote as CommerceQuote), {
+      message: "all quote money amounts must use the quote currency",
+      path: ["currency"],
+    });
+
+  const createQuoteRequestSchema = z.object({
+    mode: z.enum(["one_time", "subscription"]).default("one_time"),
+    lines: z.array(cartLineInputSchema).min(1).max(50),
+    cadenceDays: z.number().int().positive().max(120).nullable().optional(),
+    promoCodes: z.array(z.string().trim().min(1).max(80)).max(20).default([]),
+  }).superRefine(validateQuoteRequest);
+  const createQuoteResponseSchema = z.object({
+    contractVersion: z.literal(COMMERCE_CONTRACT_VERSION), quote: commerceQuoteSchema,
+  }).strict();
+  const publicCreateQuoteResponseSchema = createQuoteResponseSchema.extend({
+    promotionAcceptanceToken: z.string().min(1).max(8_300).optional(),
+  }).superRefine(rejectCatalogFactsFromPublicQuote);
+  const createQuoteBatchResponseSchema = z.object({
+    contractVersion: z.literal(COMMERCE_CONTRACT_VERSION), quotes: z.array(commerceQuoteSchema),
+  });
+  const publicCreateQuoteBatchResponseSchema = createQuoteBatchResponseSchema
+    .superRefine((response, ctx) => response.quotes.forEach((quote, index) =>
+      rejectCatalogFactsFromPublicQuote({ quote }, ctx, ["quotes", index])));
+  return { createQuoteRequestSchema, quotePricingComponentSchema, cartLineInputSchema, commerceTaxBreakdownSchema, quoteLineSchema,
+    quoteCodeRejectionSchema, commerceQuoteSchema, createQuoteResponseSchema, publicCreateQuoteResponseSchema,
+    createQuoteBatchResponseSchema, publicCreateQuoteBatchResponseSchema };
+}
+
+function sumAmounts(amounts: Array<{ amountMinor?: number }>): number {
+  return amounts.reduce((sum, amount) => sum + (amount.amountMinor ?? 0), 0);
+}
+
+function validateQuoteRequest(
+  request: { mode: "one_time" | "subscription"; cadenceDays?: number | null },
+  ctx: z.RefinementCtx,
+): void {
+    if (request.mode === "subscription" && !request.cadenceDays) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "subscription quote requires cadenceDays",
+        path: ["cadenceDays"],
+      });
+    }
+}
+

package/src/pricing/subscriptionPricePolicy.ts

@@ -0,0 +1,113 @@
+import { SUBSCRIPTION_PRICE_POLICY_SCHEMA_VERSION, type SubscriptionPricePolicySemantics, type SubscriptionPricePolicyCanonicalInput, type SubscriptionPricePolicyRevision, type SubscriptionPricePolicyDigestRefusal } from "./contracts/index.js";
+
+import { z } from "./validation.js";
+
+const uuidSchema = z.guid();
+const sha256DigestSchema = z.string().regex(/^[a-f0-9]{64}$/u);
+const currencySchema = z.string().regex(/^[A-Z]{3}$/u);
+const channelSchema = z.string().trim().min(1).max(64).regex(/^[A-Za-z0-9._:-]+$/);
+
+export const subscriptionPricePolicySemanticsSchema = z.object({
+  discountBps: z.number().int().min(0).max(10_000),
+  roundingQuantumMinor: z.number().int().positive().refine(Number.isSafeInteger, "rounding quantum must be a safe integer"),
+  roundingRule: z.enum(["FLOOR_TO_QUANTUM"]),
+}).strict();
+
+const subscriptionPricePolicyRevisionFields = {
+  id: uuidSchema,
+  revisionNo: z.number().int().positive(),
+  priceListId: uuidSchema,
+  regionCode: z.string().regex(/^[A-Z]{2,3}$/u),
+  currency: currencySchema,
+  channel: channelSchema,
+  effectiveFrom: z.string().datetime({ offset: true }),
+  effectiveTo: z.string().datetime({ offset: true }).nullable(),
+  ...subscriptionPricePolicySemanticsSchema.shape,
+};
+
+export const subscriptionPricePolicyCanonicalInputSchema = z.object(subscriptionPricePolicyRevisionFields).strict().superRefine((policy, context) => {
+  if (policy.effectiveTo && policy.effectiveTo <= policy.effectiveFrom) {
+    context.addIssue({ code: z.ZodIssueCode.custom, path: ["effectiveTo"], message: "effectiveTo must be later than effectiveFrom" });
+  }
+});
+
+export const subscriptionPricePolicyRevisionSchema = subscriptionPricePolicyCanonicalInputSchema.extend({
+  digest: sha256DigestSchema,
+}).strict();
+
+
+export class SubscriptionPricePolicyDigestError extends Error {
+  constructor(readonly code: SubscriptionPricePolicyDigestRefusal) {
+    super(code);
+    this.name = "SubscriptionPricePolicyDigestError";
+  }
+}
+
+/** The exact tuple whose canonical digest is persisted with a policy revision. */
+export function canonicalSubscriptionPricePolicyTuple(
+  policy: SubscriptionPricePolicyCanonicalInput | SubscriptionPricePolicyRevision,
+): string {
+  const value = parseCanonicalPolicyInput(policy);
+  return JSON.stringify({
+    schemaVersion: SUBSCRIPTION_PRICE_POLICY_SCHEMA_VERSION,
+    id: value.id,
+    revisionNo: value.revisionNo,
+    priceListId: value.priceListId,
+    regionCode: value.regionCode,
+    currency: value.currency,
+    channel: value.channel,
+    effectiveFrom: value.effectiveFrom,
+    effectiveTo: value.effectiveTo,
+    discountBps: value.discountBps,
+    roundingQuantumMinor: value.roundingQuantumMinor,
+    roundingRule: value.roundingRule,
+  });
+}
+
+/** Hashes application-owned canonical UTF-8 bytes; never a database JSON rendering. */
+export async function digestSubscriptionPricePolicy(
+  policy: SubscriptionPricePolicyCanonicalInput | SubscriptionPricePolicyRevision,
+): Promise<string> {
+  const bytes = new TextEncoder().encode(canonicalSubscriptionPricePolicyTuple(policy));
+  const crypto = globalThis.crypto;
+  if (!crypto?.subtle) throw new Error("Web Crypto SHA-256 is unavailable");
+  const digest = await crypto.subtle.digest("SHA-256", bytes);
+  return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+/** Parses a persisted revision and refuses a digest outside its canonical UTF-8 tuple. */
+export async function assertSubscriptionPricePolicyDigest(value: unknown): Promise<SubscriptionPricePolicyRevision> {
+  const revision = subscriptionPricePolicyRevisionSchema.parse(value);
+  const actual = await digestSubscriptionPricePolicy(revision);
+  if (actual !== revision.digest) {
+    throw new SubscriptionPricePolicyDigestError("subscription_price_policy_digest_mismatch");
+  }
+  return revision;
+}
+
+/** Resolves a subscription unit price from a base unit price and a policy revision. */
+export function deriveSubscriptionUnitPrice(
+  baseUnitAmountMinor: number,
+  semantics: SubscriptionPricePolicySemantics | SubscriptionPricePolicyCanonicalInput | SubscriptionPricePolicyRevision,
+): number {
+  if (!Number.isSafeInteger(baseUnitAmountMinor) || baseUnitAmountMinor < 0) {
+    throw new RangeError("baseUnitAmountMinor must be a non-negative safe integer");
+  }
+  const policy = subscriptionPricePolicySemanticsSchema.parse({
+    discountBps: semantics.discountBps,
+    roundingQuantumMinor: semantics.roundingQuantumMinor,
+    roundingRule: semantics.roundingRule,
+  });
+  const discounted = (BigInt(baseUnitAmountMinor) * BigInt(10_000 - policy.discountBps)) / 10_000n;
+  const quantum = BigInt(policy.roundingQuantumMinor);
+  const resolved = (discounted / quantum) * quantum;
+  if (resolved > BigInt(Number.MAX_SAFE_INTEGER)) {
+    throw new RangeError("resolved subscription price exceeds Number.MAX_SAFE_INTEGER");
+  }
+  return Number(resolved);
+}
+
+function parseCanonicalPolicyInput(value: unknown): SubscriptionPricePolicyCanonicalInput {
+  const persisted = subscriptionPricePolicyRevisionSchema.safeParse(value);
+  return persisted.success ? persisted.data : subscriptionPricePolicyCanonicalInputSchema.parse(value);
+}

package/src/pricing/taxProfileGuard.ts

@@ -0,0 +1,33 @@
+import type { CommerceTaxProfile } from "./contracts/money.js";
+import { CommerceQuoteError } from "./quotePorts.js";
+
+export function assertSupportedCommerceTaxProfile(
+  taxProfile: CommerceTaxProfile,
+  supportedTaxProfiles: readonly CommerceTaxProfile[],
+): void {
+  if (
+    !Number.isInteger(taxProfile.vatRateBps) ||
+    taxProfile.vatRateBps < 0 ||
+    taxProfile.vatRateBps > 10_000
+  ) {
+    throw new CommerceQuoteError("UNSUPPORTED_TAX_PROFILE", "Unsupported commerce tax profile", {
+      reason: "vatRateBps must be an integer between 0 and 10000",
+      vatRateBps: taxProfile.vatRateBps,
+    });
+  }
+  const supported = supportedTaxProfiles.some((candidate) =>
+    candidate.included === taxProfile.included &&
+    candidate.country === taxProfile.country &&
+    candidate.category === taxProfile.category &&
+    candidate.vatRateBps === taxProfile.vatRateBps &&
+    candidate.legalBasis === taxProfile.legalBasis,
+  );
+  if (!supported) {
+    throw new CommerceQuoteError("UNSUPPORTED_TAX_PROFILE", "Unsupported commerce tax profile", {
+      country: taxProfile.country,
+      category: taxProfile.category,
+      vatRateBps: taxProfile.vatRateBps,
+      reason: "taxProfile must be declared in supportedTaxProfiles",
+    });
+  }
+}

package/src/pricing/validation.ts

@@ -0,0 +1,3 @@
+import { z } from "zod";
+z.config({ jitless: true });
+export { z };

package/src/promotions/adminBindings.ts

@@ -0,0 +1,53 @@
+import type { z } from "zod";
+import type { HttpRequest, HttpResponse } from "../http/index.js";
+import type { BffResponder } from "../bff/index.js";
+import type { createPromotionCodePreview } from "./promotionCodePreview.js";
+
+/** Structural inputs to the existing host admin kit; no kit implementation lives here. */
+export type AdminAuthorization =
+  | { ok: true; userId: string; role: "admin" | "distributor"; isMachineActor: boolean }
+  | { ok: false; code: "UNAUTHORIZED" | "FORBIDDEN"; message: string; identityCode?: string };
+export type AuthorizeAdmin = () => Promise<AdminAuthorization>;
+export interface AgentDomainQuerySpec<T> {
+  readonly key: string;
+  readonly requestSchema: z.ZodType<T, unknown>;
+  readonly gate: "read";
+  readonly allowedActorKinds: readonly ("human" | "machine")[];
+}
+export interface AgentDomainMutationSpec<T> extends Omit<AgentDomainQuerySpec<T>, "gate"> {
+  readonly gate: "mutation";
+  readonly lifecycleMarkers: readonly never[];
+}
+type Handler = (req: HttpRequest, res: HttpResponse) => Promise<void>;
+type ErrorMapper = (res: HttpResponse, error: unknown, failureMessage: string) => void;
+interface ReadOptions<T> {
+  readonly authorizeAdmin: AuthorizeAdmin;
+  readonly toResponse: (value: T) => Record<string, unknown>;
+  readonly responseSchema: { safeParse(value: unknown): { success: boolean; data?: unknown } };
+  readonly invalidResponseMessage: string;
+  readonly failureMessage: string;
+}
+interface MutationOptions<Request, Result> extends Omit<ReadOptions<Result>, "responseSchema" | "invalidResponseMessage"> {
+  readonly mutation: AgentDomainMutationSpec<Request>;
+  readonly invoke: (actorId: string, request: Request) => Promise<Result>;
+  readonly responseSchema?: ReadOptions<Result>["responseSchema"];
+  readonly invalidResponseMessage?: string;
+  readonly invalidRequestMessage: string;
+  readonly mapError?: ErrorMapper;
+}
+interface QueryOptions<Request, Result> extends ReadOptions<Result> {
+  readonly query: AgentDomainQuerySpec<Request>;
+  readonly load: (actorId: string, request: Request) => Promise<Result>;
+  readonly invalidRequestMessage: string;
+  readonly mapError?: ErrorMapper;
+}
+export interface PromotionAdminBindings extends BffResponder, Pick<ReturnType<typeof createPromotionCodePreview>,
+  "generatePromotionCode" | "normalizePromotionCode" | "previewPromotionCode" | "verifyPromotionPreviewProof"> {
+  createAdminMutationHandler<Request, Result>(options: MutationOptions<Request, Result>): Handler;
+  createAdminReadHandler<Result>(options: ReadOptions<Result> & { load(): Promise<Result> }): Handler;
+  createAdminParameterizedReadHandler<Request, Result>(options: QueryOptions<Request, Result>): Handler;
+  mapRpcError: ErrorMapper;
+  resolveAdmin(authorize: AuthorizeAdmin, res: HttpResponse): Promise<Omit<Extract<AdminAuthorization, { ok: true }>, "ok"> | null>;
+  /** The host constructor is passed by identity, preserving instanceof and SQLSTATE mapping. */
+  DomainRpcError: new (sqlstate: string | undefined, pgMessage: string) => Error & { sqlstate: string | undefined; pgMessage: string };
+}

package/src/promotions/adminPromotionCodesContracts.ts

@@ -0,0 +1,244 @@
+import { z } from "./validation.js";
+
+import { COMMERCE_CONTRACT_VERSION } from "../pricing/index.js";
+
+export const PROMOTION_CODE_STATUSES = ["draft", "active", "paused", "archived"] as const;
+export const PROMOTION_CODE_EFFECTIVE_STATUSES = [
+  "active",
+  "draft",
+  "paused",
+  "scheduled",
+  "expired",
+  "archived",
+] as const;
+export const PROMOTION_CODE_STATUS_FILTERS = [
+  ...PROMOTION_CODE_EFFECTIVE_STATUSES,
+  "expired_or_archived",
+] as const;
+export const PROMOTION_CODE_SCOPES = ["one_time", "subscription_initial"] as const;
+
+const nullablePositiveInteger = z.number().int().positive().nullable();
+const maximumPromotionFixedMinor = 2_147_483_647;
+const optionalDateTime = z.string().datetime({ offset: true }).nullable();
+const scopesSchema = z
+  .array(z.enum(PROMOTION_CODE_SCOPES))
+  .min(1)
+  .max(2)
+  .refine((scopes) => new Set(scopes).size === scopes.length, {
+    message: "Purchase scopes must be unique",
+  });
+
+const productTargetBenefitSchema = z.union([
+  z.object({ lane: z.literal("product"), kind: z.literal("target_percentage"), valueBps: z.number().int().min(1).max(9_999) }).strict(),
+  z.object({ lane: z.literal("product"), kind: z.literal("fixed_amount"), valueMinor: z.number().int().positive().max(maximumPromotionFixedMinor) }).strict(),
+]);
+const shippingBenefitSchema = z.union([
+  z.object({ lane: z.literal("shipping"), kind: z.literal("percentage"), valueBps: z.number().int().min(1).max(9_999) }).strict(),
+  z.object({ lane: z.literal("shipping"), kind: z.literal("fixed_amount"), valueMinor: z.number().int().positive().max(maximumPromotionFixedMinor) }).strict(),
+  z.object({ lane: z.literal("shipping"), kind: z.literal("free_shipping") }).strict(),
+]);
+export const promotionCodeBenefitSchema = z.union([
+  productTargetBenefitSchema,
+  shippingBenefitSchema,
+  z.object({ lane: z.literal("product"), kind: z.literal("percentage"), valueBps: z.number().int().min(0) }).strict(),
+  z.object({ lane: z.literal("shipping"), kind: z.literal("percentage"), valueBps: z.number().int().min(0) }).strict(),
+  z.object({ lane: z.literal("product"), kind: z.literal("fixed_amount"), valueMinor: z.number().int().nonnegative() }).strict(),
+  z.object({ lane: z.literal("shipping"), kind: z.literal("fixed_amount"), valueMinor: z.number().int().nonnegative() }).strict(),
+  z.object({
+    lane: z.enum(["product", "shipping"]),
+    kind: z.enum(["percentage", "fixed_amount"]),
+    validationState: z.literal("unsupported_legacy_value"),
+  }).strict(),
+]);
+const createBenefitSchema = z.union([productTargetBenefitSchema, shippingBenefitSchema]);
+
+const benefitsSchema = z
+  .array(promotionCodeBenefitSchema)
+  .min(1)
+  .max(2)
+  .refine((benefits) => new Set(benefits.map((benefit) => benefit.lane)).size === benefits.length, {
+    message: "Only one benefit per adjustment lane is allowed",
+  });
+const createBenefitsSchema = z
+  .array(createBenefitSchema)
+  .min(1)
+  .max(2)
+  .refine((benefits) => new Set(benefits.map((benefit) => benefit.lane)).size === benefits.length, {
+    message: "Only one benefit per adjustment lane is allowed",
+  });
+
+export const promotionCodePreviewContextSchema = z
+  .object({
+    referenceProductMinor: z.number().int().positive(),
+    oneTimeProductMinor: z.number().int().positive(),
+    subscriptionProductMinor: z.number().int().positive(),
+    shippingMinor: z.number().int().nonnegative(),
+  })
+  .strict()
+  .refine((value) => value.oneTimeProductMinor <= value.referenceProductMinor, {
+    message: "One-time product price cannot exceed the reference price",
+  })
+  .refine((value) => value.subscriptionProductMinor <= value.referenceProductMinor, {
+    message: "Subscription product price cannot exceed the reference price",
+  });
+
+export const promotionCodePreviewRequestSchema = z
+  .object({
+    benefits: benefitsSchema,
+    scopes: scopesSchema,
+    promotionEngineVersion: z.enum(["promotion-engine.v1", "promotion-engine.v2"]).default("promotion-engine.v2"),
+    minimumReferenceMinor: z.number().int().nonnegative().default(0),
+    context: promotionCodePreviewContextSchema,
+  })
+  .strict();
+
+export const promotionCodePreviewResultSchema = z.object({
+  scope: z.enum(PROMOTION_CODE_SCOPES),
+  productPayableMinor: z.number().int().nonnegative(),
+  shippingPayableMinor: z.number().int().nonnegative(),
+  effectiveProductDiscountBps: z.number().int().min(0).max(10_000),
+  winner: z.enum(["code", "automatic"]),
+  floorApplied: z.boolean(),
+  adjustments: z.array(
+    z.object({
+      lane: z.enum(["product", "shipping"]),
+      kind: z.enum(["target_percentage", "percentage", "fixed_amount", "free_shipping"]),
+      amountOffMinor: z.number().int().nonnegative(),
+      beforeMinor: z.number().int().nonnegative(),
+      afterMinor: z.number().int().nonnegative(),
+    }),
+  ),
+});
+
+export const promotionCodePreviewResponseSchema = z.object({
+  contractVersion: z.literal(COMMERCE_CONTRACT_VERSION),
+  promotionEngineVersion: z.enum(["promotion-engine.v1", "promotion-engine.v2"]),
+  previewProof: z.string().regex(/^[A-Za-z0-9_-]{43}$/),
+  results: z.array(promotionCodePreviewResultSchema).length(2),
+});
+
+export const promotionCodeCreateRequestSchema = z
+  .object({
+    name: z.string().trim().min(1).max(120),
+    description: z.string().trim().max(500).nullable().default(null),
+    code: z.discriminatedUnion("kind", [
+      z.object({ kind: z.literal("automatic") }).strict(),
+      z.object({ kind: z.literal("manual"), value: z.string().trim().min(3).max(64).regex(/^[A-Za-z0-9_-]+$/) }).strict(),
+    ]),
+    benefits: createBenefitsSchema,
+    scopes: scopesSchema,
+    validFrom: z.string().datetime({ offset: true }),
+    validTo: optionalDateTime,
+    minimumReferenceMinor: z.number().int().nonnegative().default(0),
+    redemptionLimitGlobal: nullablePositiveInteger.default(null),
+    redemptionLimitPerCustomer: nullablePositiveInteger.default(null),
+    status: z.enum(["draft", "active"]).default("draft"),
+    previewContext: promotionCodePreviewContextSchema.optional(),
+    previewProof: z.string().regex(/^[A-Za-z0-9_-]{43}$/).optional(),
+    idempotencyKey: z.string().uuid(),
+  })
+  .strict()
+  .refine((value) => value.validTo === null || Date.parse(value.validTo) > Date.parse(value.validFrom), {
+    message: "validTo must be after validFrom",
+  })
+  .refine(
+    (value) => value.status !== "active" || Boolean(value.previewContext && value.previewProof),
+    { message: "Active codes require a successful backend preview" },
+  );
+
+export const promotionCodeCreateResponseSchema = z.object({
+  contractVersion: z.literal(COMMERCE_CONTRACT_VERSION),
+  id: z.string().uuid(),
+  code: z.string().min(3).max(64),
+  status: z.enum(PROMOTION_CODE_STATUSES),
+  revision: z.number().int().positive(),
+  idempotent: z.boolean(),
+});
+
+export const promotionCodeUpdateRequestSchema = z
+  .object({
+    id: z.string().uuid(),
+    expectedRevision: z.number().int().positive(),
+    updates: z
+      .object({
+        status: z.enum(PROMOTION_CODE_STATUSES).optional(),
+        validFrom: z.string().datetime({ offset: true }).optional(),
+        validTo: optionalDateTime.optional(),
+        redemptionLimitGlobal: nullablePositiveInteger.optional(),
+        redemptionLimitPerCustomer: nullablePositiveInteger.optional(),
+      })
+      .strict()
+      .refine((updates) => Object.values(updates).some((value) => value !== undefined), {
+        message: "At least one field is required",
+      }),
+    previewContext: promotionCodePreviewContextSchema.optional(),
+    previewProof: z.string().regex(/^[A-Za-z0-9_-]{43}$/).optional(),
+    idempotencyKey: z.string().uuid(),
+  })
+  .strict()
+  ;
+
+export const promotionCodeUpdateResponseSchema = z.object({
+  contractVersion: z.literal(COMMERCE_CONTRACT_VERSION),
+  id: z.string().uuid(),
+  status: z.enum(PROMOTION_CODE_STATUSES),
+  revision: z.number().int().positive(),
+  idempotent: z.boolean(),
+});
+
+export const promotionCodesListRequestSchema = z
+  .object({
+    q: z.string().trim().min(1).max(80).optional(),
+    status: z.enum([...PROMOTION_CODE_STATUS_FILTERS, "all"]).default("active"),
+    scope: z.enum([...PROMOTION_CODE_SCOPES, "both", "shipping", "all"]).default("all"),
+    cursor: z.string().max(500).optional(),
+    limit: z.coerce.number().int().min(1).max(100).default(25),
+  })
+  .strict();
+
+export const promotionCodeSummarySchema = z.object({
+  id: z.string().uuid(),
+  code: z.string(),
+  name: z.string(),
+  description: z.string().nullable(),
+  benefits: benefitsSchema,
+  promotionEngineVersion: z.enum(["promotion-engine.v1", "promotion-engine.v2"]),
+  scopes: scopesSchema,
+  status: z.enum(PROMOTION_CODE_STATUSES),
+  effectiveStatus: z.enum(PROMOTION_CODE_EFFECTIVE_STATUSES),
+  validFrom: z.string(),
+  validTo: z.string().nullable(),
+  minimumReferenceMinor: z.number().int().nonnegative(),
+  redemptionLimitGlobal: z.number().int().positive().nullable(),
+  redemptionLimitPerCustomer: z.number().int().positive().nullable(),
+  redeemedCount: z.number().int().nonnegative(),
+  reservedCount: z.number().int().nonnegative(),
+  remainingCount: z.number().int().nonnegative().nullable(),
+  createdAt: z.string(),
+  revision: z.number().int().positive(),
+});
+
+export const promotionCodesListResponseSchema = z.object({
+  contractVersion: z.literal(COMMERCE_CONTRACT_VERSION),
+  codes: z.array(promotionCodeSummarySchema),
+  nextCursor: z.string().nullable(),
+  capabilities: z.object({
+    mutationsEnabled: z.boolean(),
+  }).strict(),
+  legacyCompatibility: z.object({
+    ready: z.boolean(),
+    unprojectedCount: z.number().int().nonnegative(),
+    collisionGroupCount: z.number().int().nonnegative(),
+  }).strict(),
+});
+
+export type PromotionCodeBenefit = z.infer<typeof promotionCodeBenefitSchema>;
+export type PromotionCodePreviewRequest = z.infer<typeof promotionCodePreviewRequestSchema>;
+export type PromotionCodePreviewResponse = z.infer<typeof promotionCodePreviewResponseSchema>;
+export type PromotionCodeCreateRequest = z.infer<typeof promotionCodeCreateRequestSchema>;
+export type PromotionCodeCreateResponse = z.infer<typeof promotionCodeCreateResponseSchema>;
+export type PromotionCodeUpdateRequest = z.infer<typeof promotionCodeUpdateRequestSchema>;
+export type PromotionCodeUpdateResponse = z.infer<typeof promotionCodeUpdateResponseSchema>;
+export type PromotionCodesListRequest = z.infer<typeof promotionCodesListRequestSchema>;
+export type PromotionCodeSummary = z.infer<typeof promotionCodeSummarySchema>;
+export type PromotionCodesListResponse = z.infer<typeof promotionCodesListResponseSchema>;