@openlup/core 0.0.0 → 0.7.0

package/src/promo/adjustmentEngine.ts

@@ -0,0 +1,253 @@
+import {
+  PROMOTION_ADJUSTMENT_KINDS,
+  PROMOTION_ADJUSTMENT_LANES,
+  PROMOTION_ENGINE_V2,
+  PROMOTION_PURCHASE_SCOPES,
+  type AppliedAdjustment,
+  type PromotionAdjustmentCandidate,
+  type PromotionAdjustmentContext,
+  type PromotionAdjustmentLane,
+  type PromotionAdjustmentResult,
+  type PromotionCodeRejection,
+} from "./adjustmentTypes.js";
+
+interface ScoredCandidate {
+  candidate: PromotionAdjustmentCandidate;
+  amountOffMinor: number;
+  beforeMinor: number;
+  afterMinor: number;
+  floorApplied: boolean;
+}
+
+/** Select at most one product and one shipping adjustment. */
+/** @beta */
+export function evaluatePromotionAdjustmentsV2(
+  context: PromotionAdjustmentContext,
+  candidates: readonly PromotionAdjustmentCandidate[],
+): PromotionAdjustmentResult {
+  const minimumProductPayableMinor = validateContext(context);
+  candidates.forEach(validateCandidate);
+  validateCodeIdentity(candidates);
+
+  const applicable = candidates.filter((candidate) => candidate.scopes.includes(context.purchaseScope));
+  const productWinner = pickWinner(
+    applicable.filter((candidate) => candidate.lane === "product"),
+    context,
+    "product",
+    minimumProductPayableMinor,
+  );
+  const shippingWinner = pickWinner(
+    applicable.filter((candidate) => candidate.lane === "shipping"),
+    context,
+    "shipping",
+    minimumProductPayableMinor,
+  );
+  const winners = [productWinner, shippingWinner].filter(
+    (winner): winner is ScoredCandidate => winner !== null,
+  );
+  const productPayableMinor = productWinner?.afterMinor ?? context.currentProductMinor;
+  const shippingPayableMinor = shippingWinner?.afterMinor ?? context.shippingMinor;
+
+  return {
+    engineVersion: PROMOTION_ENGINE_V2,
+    adjustments: winners.map(toAppliedAdjustment),
+    rejectedCodes: rejectedCodes(candidates, applicable, winners),
+    productPayableMinor,
+    shippingPayableMinor,
+    effectiveProductDiscountBps: Number(
+      (BigInt(context.referenceProductMinor - productPayableMinor) * 10_000n) /
+      BigInt(context.referenceProductMinor),
+    ),
+  };
+}
+
+function validateContext(context: PromotionAdjustmentContext): number {
+  const floor = context.minimumProductPayableMinor;
+  if (!PROMOTION_PURCHASE_SCOPES.includes(context.purchaseScope)) {
+    throw new RangeError("purchaseScope is invalid");
+  }
+  assertMinor("referenceProductMinor", context.referenceProductMinor, 1);
+  assertMinor("minimumProductPayableMinor", floor, 1);
+  assertMinor("currentProductMinor", context.currentProductMinor, floor);
+  assertMinor("shippingMinor", context.shippingMinor, 0);
+  if (context.currentProductMinor > context.referenceProductMinor) {
+    throw new RangeError("currentProductMinor cannot exceed referenceProductMinor");
+  }
+  return floor;
+}
+
+function validateCandidate(candidate: PromotionAdjustmentCandidate): void {
+  const runtimeLane = candidate.lane as string;
+  const runtimeKind = candidate.kind as string;
+  if (typeof candidate.promotionId !== "string" || typeof candidate.name !== "string" ||
+      !candidate.promotionId.trim() || !candidate.name.trim()) {
+    throw new RangeError("promotionId and name are required");
+  }
+  if (candidate.source !== "automatic" && candidate.source !== "code") {
+    throw new RangeError("candidate source is invalid");
+  }
+  if (!PROMOTION_ADJUSTMENT_LANES.includes(runtimeLane as PromotionAdjustmentLane)) {
+    throw new RangeError("candidate lane is invalid");
+  }
+  if (!PROMOTION_ADJUSTMENT_KINDS.includes(runtimeKind as (typeof PROMOTION_ADJUSTMENT_KINDS)[number])) {
+    throw new RangeError("candidate kind is invalid");
+  }
+  if (!Array.isArray(candidate.scopes) || candidate.scopes.length === 0 ||
+      candidate.scopes.some((scope) => !PROMOTION_PURCHASE_SCOPES.includes(scope)) ||
+      new Set(candidate.scopes).size !== candidate.scopes.length) {
+    throw new RangeError("candidate scopes are invalid");
+  }
+  if (candidate.source === "code" && (typeof candidate.codeId !== "string" || !candidate.codeId.trim())) {
+    throw new RangeError("code candidates require codeId");
+  }
+  if (candidate.source === "automatic" && (candidate.codeId !== undefined || candidate.code !== undefined)) {
+    throw new RangeError("automatic candidates cannot carry code identity");
+  }
+  if (candidate.kind === "target_percentage" || candidate.kind === "percentage") {
+    assertMinor("valueBps", candidate.valueBps, 1);
+    if ((candidate.valueBps ?? 0) >= 10_000) throw new RangeError("valueBps must be below 10000");
+    if (candidate.valueMinor !== undefined) throw new RangeError("percentage candidates cannot set valueMinor");
+  } else if (candidate.kind === "fixed_amount") {
+    assertMinor("valueMinor", candidate.valueMinor, 1);
+    if (candidate.valueBps !== undefined) throw new RangeError("fixed candidates cannot set valueBps");
+  } else if (candidate.valueBps !== undefined || candidate.valueMinor !== undefined) {
+    throw new RangeError("free_shipping cannot set a value");
+  }
+  if (runtimeLane === "product" && runtimeKind !== "target_percentage" && runtimeKind !== "fixed_amount") {
+    throw new RangeError("product candidate kind is invalid");
+  }
+  if (runtimeLane === "shipping" && runtimeKind === "target_percentage") {
+    throw new RangeError("shipping candidate kind is invalid");
+  }
+}
+
+function validateCodeIdentity(candidates: readonly PromotionAdjustmentCandidate[]): void {
+  const rawById = new Map<string, string | undefined>();
+  for (const candidate of candidates) {
+    if (candidate.source !== "code" || !candidate.codeId) continue;
+    if (rawById.has(candidate.codeId) && rawById.get(candidate.codeId) !== candidate.code) {
+      throw new RangeError("codeId candidates must use one code value");
+    }
+    rawById.set(candidate.codeId, candidate.code);
+  }
+}
+
+function pickWinner(
+  candidates: PromotionAdjustmentCandidate[],
+  context: PromotionAdjustmentContext,
+  lane: PromotionAdjustmentLane,
+  floor: number,
+): ScoredCandidate | null {
+  const scored = candidates
+    .map((candidate) => scoreCandidate(candidate, context, lane, floor))
+    .filter((candidate) => candidate.amountOffMinor > 0)
+    .sort(compareScored);
+  return scored[0] ?? null;
+}
+
+function scoreCandidate(
+  candidate: PromotionAdjustmentCandidate,
+  context: PromotionAdjustmentContext,
+  lane: PromotionAdjustmentLane,
+  floor: number,
+): ScoredCandidate {
+  const beforeMinor = lane === "product" ? context.currentProductMinor : context.shippingMinor;
+  let requestedOffMinor = 0;
+  if (candidate.kind === "free_shipping") {
+    requestedOffMinor = context.shippingMinor;
+  } else if (candidate.kind === "fixed_amount") {
+    requestedOffMinor = candidate.valueMinor ?? 0;
+  } else if (lane === "shipping") {
+    requestedOffMinor = multiplyDivideFloor(context.shippingMinor, candidate.valueBps ?? 0);
+  } else {
+    const targetPayableMinor = multiplyDivideCeil(
+      context.referenceProductMinor,
+      10_000 - (candidate.valueBps ?? 0),
+    );
+    requestedOffMinor = Math.max(0, context.currentProductMinor - targetPayableMinor);
+  }
+  const minimumPayable = lane === "product" ? floor : 0;
+  const amountOffMinor = Math.min(requestedOffMinor, Math.max(0, beforeMinor - minimumPayable));
+  return {
+    candidate,
+    amountOffMinor,
+    beforeMinor,
+    afterMinor: beforeMinor - amountOffMinor,
+    floorApplied: lane === "product" && requestedOffMinor > amountOffMinor,
+  };
+}
+
+function compareScored(left: ScoredCandidate, right: ScoredCandidate): number {
+  if (left.amountOffMinor !== right.amountOffMinor) return right.amountOffMinor - left.amountOffMinor;
+  if (left.candidate.source !== right.candidate.source) {
+    return left.candidate.source === "automatic" ? -1 : 1;
+  }
+  return compareCodeUnits(left.candidate.promotionId, right.candidate.promotionId);
+}
+
+function toAppliedAdjustment(winner: ScoredCandidate): AppliedAdjustment {
+  const candidate = winner.candidate;
+  return {
+    engineVersion: PROMOTION_ENGINE_V2,
+    promotionId: candidate.promotionId,
+    ...(candidate.codeId ? { codeId: candidate.codeId } : {}),
+    ...(candidate.code ? { code: candidate.code } : {}),
+    name: candidate.name,
+    source: candidate.source,
+    lane: candidate.lane,
+    kind: candidate.kind,
+    amountOffMinor: winner.amountOffMinor,
+    beforeMinor: winner.beforeMinor,
+    afterMinor: winner.afterMinor,
+    floorApplied: winner.floorApplied,
+    ...(candidate.kind === "target_percentage"
+      ? { targetEffectiveDiscountBps: candidate.valueBps }
+      : {}),
+  };
+}
+
+function rejectedCodes(
+  all: readonly PromotionAdjustmentCandidate[],
+  applicable: readonly PromotionAdjustmentCandidate[],
+  winners: readonly ScoredCandidate[],
+): PromotionCodeRejection[] {
+  const applicableIds = new Set(applicable.map((candidate) => candidate.codeId));
+  const winnerIds = new Set(
+    winners
+      .filter((winner) => winner.candidate.source === "code")
+      .map((winner) => winner.candidate.codeId),
+  );
+  const codes = new Map<string, PromotionCodeRejection>();
+  for (const candidate of all) {
+    if (candidate.source !== "code" || !candidate.codeId || winnerIds.has(candidate.codeId)) continue;
+    const reason = applicableIds.has(candidate.codeId) ? "better_price_exists" : "scope_not_applicable";
+    const previous = codes.get(candidate.codeId);
+    if (!previous || previous.reason === "scope_not_applicable") {
+      codes.set(candidate.codeId, {
+        codeId: candidate.codeId,
+        ...(candidate.code ? { code: candidate.code } : {}),
+        reason,
+      });
+    }
+  }
+  return [...codes.values()].sort((left, right) => compareCodeUnits(left.codeId ?? "", right.codeId ?? ""));
+}
+
+function assertMinor(name: string, value: number | undefined, minimum: number): void {
+  if (!Number.isSafeInteger(value) || (value ?? 0) < minimum) {
+    throw new RangeError(`${name} must be a safe integer >= ${minimum}`);
+  }
+}
+
+function multiplyDivideFloor(value: number, multiplier: number): number {
+  return Number((BigInt(value) * BigInt(multiplier)) / 10_000n);
+}
+
+function multiplyDivideCeil(value: number, multiplier: number): number {
+  const product = BigInt(value) * BigInt(multiplier);
+  return Number((product + 9_999n) / 10_000n);
+}
+
+function compareCodeUnits(left: string, right: string): number {
+  return left < right ? -1 : left > right ? 1 : 0;
+}

package/src/promo/adjustmentTypes.ts

@@ -0,0 +1,94 @@
+/** @beta */
+export const PROMOTION_ENGINE_V2 = "promotion-engine.v2" as const;
+
+/** @beta */
+export const PROMOTION_PURCHASE_SCOPES = ["one_time", "subscription_initial"] as const;
+/** @beta */
+export type PromotionPurchaseScope = (typeof PROMOTION_PURCHASE_SCOPES)[number];
+
+/** @beta */
+export const PROMOTION_ADJUSTMENT_LANES = ["product", "shipping"] as const;
+/** @beta */
+export type PromotionAdjustmentLane = (typeof PROMOTION_ADJUSTMENT_LANES)[number];
+
+/** @beta */
+export const PROMOTION_ADJUSTMENT_KINDS = [
+  "target_percentage",
+  "percentage",
+  "fixed_amount",
+  "free_shipping",
+] as const;
+/** @beta */
+export type PromotionAdjustmentKind = (typeof PROMOTION_ADJUSTMENT_KINDS)[number];
+
+/** @beta */
+export type PromotionAdjustmentSource = "automatic" | "code";
+
+interface PromotionAdjustmentCandidateBase {
+  promotionId: string;
+  name: string;
+  scopes: readonly PromotionPurchaseScope[];
+}
+
+type PromotionAdjustmentTrigger =
+  | { source: "automatic"; codeId?: never; code?: never }
+  | { source: "code"; codeId: string; code?: string };
+
+/** An already eligibility-filtered benefit considered by the pure v2 engine. */
+/** @beta */
+export type PromotionAdjustmentCandidate = PromotionAdjustmentCandidateBase & PromotionAdjustmentTrigger & (
+  | { lane: "product"; kind: "target_percentage"; valueBps: number; valueMinor?: never }
+  | { lane: "product"; kind: "fixed_amount"; valueMinor: number; valueBps?: never }
+  | { lane: "shipping"; kind: "percentage"; valueBps: number; valueMinor?: never }
+  | { lane: "shipping"; kind: "fixed_amount"; valueMinor: number; valueBps?: never }
+  | { lane: "shipping"; kind: "free_shipping"; valueBps?: never; valueMinor?: never }
+);
+
+/** @beta */
+export interface PromotionAdjustmentContext {
+  purchaseScope: PromotionPurchaseScope;
+  /** Product price before bundle, subscription, or acquisition benefits. */
+  referenceProductMinor: number;
+  /** Product price after automatic pricing benefits, before a v2 promotion. */
+  currentProductMinor: number;
+  shippingMinor: number;
+  /** Required adopter policy, expressed in the checkout currency's minor units. */
+  minimumProductPayableMinor: number;
+}
+
+/** @beta */
+export interface AppliedAdjustment {
+  engineVersion: typeof PROMOTION_ENGINE_V2;
+  promotionId: string;
+  codeId?: string;
+  code?: string;
+  name: string;
+  source: PromotionAdjustmentSource;
+  lane: PromotionAdjustmentLane;
+  kind: PromotionAdjustmentKind;
+  amountOffMinor: number;
+  beforeMinor: number;
+  afterMinor: number;
+  floorApplied: boolean;
+  targetEffectiveDiscountBps?: number;
+}
+
+/** @beta */
+export type PromotionCodeRejectionReason = "scope_not_applicable" | "better_price_exists";
+
+/** @beta */
+export interface PromotionCodeRejection {
+  codeId?: string;
+  code?: string;
+  reason: PromotionCodeRejectionReason;
+}
+
+/** @beta */
+export interface PromotionAdjustmentResult {
+  engineVersion: typeof PROMOTION_ENGINE_V2;
+  adjustments: AppliedAdjustment[];
+  rejectedCodes: PromotionCodeRejection[];
+  productPayableMinor: number;
+  shippingPayableMinor: number;
+  effectiveProductDiscountBps: number;
+}

package/src/promo/index.ts

@@ -0,0 +1,8 @@
+/** @beta */
+export * from "./types.js";
+/** @beta */
+export * from "./promoEvaluator.js";
+/** @beta */
+export * from "./adjustmentTypes.js";
+/** @beta */
+export * from "./adjustmentEngine.js";

package/src/promo/promoEvaluator.ts

@@ -0,0 +1,137 @@
+import type { AppliedPromotion, EvaluateNowInput, PromotionRow } from "./types.js";
+
+/**
+ * Deterministic promotion evaluator shared by preview and finalization callers.
+ * The same `(cart, candidates, now)` triple always yields the same
+ * `AppliedPromotion[]`, so downstream quote/order layers can compare the
+ * previewed discount with the persisted one.
+ *
+ * Two independent lanes:
+ *   - order_total lane (percentage / fixed_amount): exclusivity applies.
+ *   - shipping lane (free_shipping): evaluated separately so an order-total
+ *     promo never suppresses free shipping.
+ *
+ * Within each lane, candidates are filtered to active, in-window, in-region,
+ * eligible-for-this-cart; coupon promotions additionally require the code in
+ * `cart.applied_codes`.
+ */
+/** @beta */
+export function evaluatePromos(input: EvaluateNowInput): AppliedPromotion[] {
+  const { cart, candidates, now } = input;
+  const eligible = candidates.filter((p) => promoEligibilityFailure(p, cart, now) === null && couponCodePresent(p, cart));
+
+  const shippingLane = eligible.filter((p) => p.discount_type === "free_shipping");
+  const orderLane = eligible.filter((p) => p.discount_type !== "free_shipping");
+
+  const applied: AppliedPromotion[] = [];
+
+  let exclusiveBlocked = false;
+  for (const promo of sortByPriority(orderLane, cart)) {
+    if (exclusiveBlocked) break;
+    const amount = computeAmountOff(promo, cart);
+    if (amount <= 0) continue;
+    applied.push(toApplied(promo, amount));
+    if (promo.stacking_rule === "exclusive") exclusiveBlocked = true;
+  }
+
+  const shippingPromo = sortByPriority(shippingLane, cart)[0];
+  if (shippingPromo) {
+    const amount = computeAmountOff(shippingPromo, cart);
+    if (amount > 0) applied.push(toApplied(shippingPromo, amount));
+  }
+
+  return applied;
+}
+
+/**
+ * Why a promo does not apply to this cart, or `null` if it would apply. Used by
+ * quote/finalization layers to classify rejected coupon codes. A promo that is
+ * eligible but merely loses to a larger exclusive promo returns `null` here.
+ */
+/** @beta */
+export function promoEligibilityFailure(
+  promo: PromotionRow,
+  cart: EvaluateNowInput["cart"],
+  now: string,
+): "expired" | "not_eligible" | null {
+  if (promo.status !== "active") return "not_eligible";
+  if (!promo.region_availability.includes(cart.region_code)) return "not_eligible";
+  if (!(promo.valid_from <= now && (promo.valid_to === null || promo.valid_to >= now))) return "expired";
+  if (!isEligibleForCart(promo, cart)) return "not_eligible";
+  return null;
+}
+
+function couponCodePresent(promo: PromotionRow, cart: EvaluateNowInput["cart"]): boolean {
+  return promo.trigger_type !== "coupon_code" || (promo.code !== null && cart.applied_codes.includes(promo.code));
+}
+
+function isEligibleForCart(promo: PromotionRow, cart: EvaluateNowInput["cart"]): boolean {
+  const elig = promo.eligibility;
+  const isFirstOrderPromo =
+    elig.first_purchase === true ||
+    elig.first_subscription_purchase === true ||
+    elig.first_onetime_purchase === true;
+  if (
+    isFirstOrderPromo &&
+    cart.device_first_order_redeemed === true &&
+    cart.email_eligibility_confirmed !== true
+  ) {
+    return false;
+  }
+  if (typeof elig.first_purchase === "boolean") {
+    if (elig.first_purchase === true && cart.client_orders_count !== 0) return false;
+    if (elig.first_purchase === false && cart.client_orders_count === 0) return false;
+  }
+  if (elig.first_subscription_purchase === true && (cart.client_subscription_orders_count ?? 0) !== 0) return false;
+  if (elig.first_onetime_purchase === true && (cart.client_onetime_orders_count ?? 0) !== 0) return false;
+  if (typeof elig.returning_customer === "boolean") {
+    if (elig.returning_customer === true && cart.client_orders_count === 0) return false;
+    if (elig.returning_customer === false && cart.client_orders_count !== 0) return false;
+  }
+  if (typeof elig.min_cart_minor === "number") {
+    if (cart.cart_subtotal_minor < elig.min_cart_minor) return false;
+  }
+  const cartModeMatch = promo.applies_to_payload.cart_mode;
+  if (typeof cartModeMatch === "string" && cartModeMatch !== cart.cart_mode) return false;
+  return true;
+}
+
+function computeAmountOff(promo: PromotionRow, cart: EvaluateNowInput["cart"]): number {
+  switch (promo.discount_type) {
+    case "percentage":
+      return Math.floor((cart.cart_subtotal_minor * promo.discount_value) / 100);
+    case "fixed_amount":
+      return Math.min(promo.discount_value, cart.cart_subtotal_minor);
+    case "free_shipping":
+      return cart.shipping_amount_minor;
+    default:
+      return 0;
+  }
+}
+
+function toApplied(promo: PromotionRow, amount: number): AppliedPromotion {
+  return {
+    promotion_id: promo.id,
+    code: promo.code,
+    name: promo.name,
+    amount_off_minor: amount,
+    applies_to: promo.applies_to_kind,
+    discount_type: promo.discount_type,
+    reason_code: promo.code ? `promo:${promo.code}` : `promo:${normalizeReasonName(promo.name)}`,
+  };
+}
+
+function sortByPriority(promos: PromotionRow[], cart: EvaluateNowInput["cart"]): PromotionRow[] {
+  return [...promos].sort((a, b) => {
+    if (a.stacking_rule === "exclusive" && b.stacking_rule !== "exclusive") return -1;
+    if (a.stacking_rule !== "exclusive" && b.stacking_rule === "exclusive") return 1;
+    const amountA = computeAmountOff(a, cart);
+    const amountB = computeAmountOff(b, cart);
+    if (amountA !== amountB) return amountB - amountA;
+    return a.name.localeCompare(b.name);
+  });
+}
+
+function normalizeReasonName(name: string): string {
+  return name.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_|_$/g, "");
+}

package/src/promo/types.ts

@@ -0,0 +1,97 @@
+/** @beta */
+export const PROMOTION_TRIGGER_TYPES = ["coupon_code", "automatic", "referral"] as const;
+/** @beta */
+export type PromotionTriggerType = (typeof PROMOTION_TRIGGER_TYPES)[number];
+
+/** @beta */
+export const PROMOTION_DISCOUNT_TYPES = ["percentage", "fixed_amount", "free_shipping"] as const;
+/** @beta */
+export type PromotionDiscountType = (typeof PROMOTION_DISCOUNT_TYPES)[number];
+
+/** @beta */
+export const PROMOTION_APPLIES_TO_KINDS = ["order_total", "line_with_variant", "line_with_category"] as const;
+/** @beta */
+export type PromotionAppliesToKind = (typeof PROMOTION_APPLIES_TO_KINDS)[number];
+
+/** @beta */
+export const PROMOTION_STACKING_RULES = [
+  "exclusive",
+  "stackable_with_any",
+  "stackable_with_loyalty",
+] as const;
+/** @beta */
+export type PromotionStackingRule = (typeof PROMOTION_STACKING_RULES)[number];
+
+/** @beta */
+export interface PromotionRow {
+  id: string;
+  code: string | null;
+  name: string;
+  trigger_type: PromotionTriggerType;
+  discount_type: PromotionDiscountType;
+  discount_value: number;
+  applies_to_kind: PromotionAppliesToKind;
+  applies_to_payload: Record<string, unknown>;
+  stacking_rule: PromotionStackingRule;
+  eligibility: Record<string, unknown>;
+  valid_from: string;
+  valid_to: string | null;
+  status: string;
+  region_availability: string[];
+  /**
+   * Redemption caps. Enforced at quote-evaluation time by the caller before the
+   * candidate set reaches `evaluatePromos`, never by failing a paid order.
+   * Null = uncapped. Optional so non-DB callers/fixtures need not set them.
+   */
+  redemption_limit_global?: number | null;
+  redemption_limit_per_customer?: number | null;
+}
+
+/** @beta */
+export interface PromoEvaluationCart {
+  region_code: string;
+  cart_mode: "one_time" | "subscription";
+  cart_subtotal_minor: number;
+  shipping_amount_minor: number;
+  /** All paid orders in any mode. Kept for the legacy `first_purchase` eligibility key. */
+  client_orders_count: number;
+  /** Paid subscription orders. Drives `first_subscription_purchase`. Optional for fixtures. */
+  client_subscription_orders_count?: number;
+  /** Paid one-time orders. Drives `first_onetime_purchase`. Optional for fixtures. */
+  client_onetime_orders_count?: number;
+  /**
+   * True when this device's first-party visitor id already has a paid first-order
+   * redemption. Denies any first-order promo regardless of client/email.
+   * Optional; absent means no device guard.
+   *
+   * Demoted to advisory when {@link email_eligibility_confirmed} is true: an
+   * account-level email signal outranks the device cookie.
+   */
+  device_first_order_redeemed?: boolean;
+  /**
+   * True when eligibility was resolved from a customer-provided email. When true,
+   * the email-derived order counts are authoritative and the device guard is
+   * advisory only. Optional; absent means the device guard stays in force.
+   */
+  email_eligibility_confirmed?: boolean;
+  applied_codes: string[];
+}
+
+/** @beta */
+export interface AppliedPromotion {
+  promotion_id: string;
+  code: string | null;
+  /** Human-facing promotion name, surfaced as the quote discount label. */
+  name: string;
+  amount_off_minor: number;
+  applies_to: PromotionAppliesToKind;
+  discount_type: PromotionDiscountType;
+  reason_code: string;
+}
+
+/** @beta */
+export interface EvaluateNowInput {
+  cart: PromoEvaluationCart;
+  candidates: ReadonlyArray<PromotionRow>;
+  now: string;
+}

package/src/risk/core/evaluator.ts

@@ -0,0 +1,41 @@
+import type { RiskDecision, RiskSeverity } from "../types.js";
+import { collectRiskRuleMatches } from "./rules.js";
+import type { RiskEvaluationInput, RiskEvaluationOutput } from "./types.js";
+
+const SEVERITY_ORDER: RiskSeverity[] = ["low", "medium", "high", "critical"];
+
+/** @beta */
+export function evaluateRisk(input: RiskEvaluationInput): RiskEvaluationOutput {
+  const matchedRules = collectRiskRuleMatches(input);
+  const score = Math.min(100, matchedRules.reduce((sum, rule) => sum + rule.score, 0));
+  const hasBlocklist = matchedRules.some((rule) => rule.code === "exact_blocklist_match");
+  const decision = decide(score, hasBlocklist);
+  const severity = matchedRules.reduce<RiskSeverity>(
+    (max, rule) => (SEVERITY_ORDER.indexOf(rule.severity) > SEVERITY_ORDER.indexOf(max) ? rule.severity : max),
+    "low",
+  );
+  const checkoutBlocked =
+    input.source === "checkout" && input.mode === "checkout_blocklist" && hasBlocklist;
+  const holdRequested =
+    input.source !== "checkout" && input.mode === "hold" && (decision === "manual_review" || decision === "block");
+
+  return {
+    decision,
+    score,
+    severity,
+    reasonCodes: matchedRules.map((rule) => rule.code),
+    matchedRules,
+    enforcement: {
+      mode: input.mode,
+      applied: input.mode !== "shadow" && (checkoutBlocked || holdRequested),
+      checkoutBlocked,
+      holdRequested,
+    },
+  };
+}
+
+function decide(score: number, hasBlocklist: boolean): RiskDecision {
+  if (hasBlocklist) return "block";
+  if (score >= 35) return "manual_review";
+  return "allow";
+}