@openlup/core 0.0.0 → 0.6.0

package/dist/promo/adjustmentEngine.js

@@ -0,0 +1,194 @@
+import { PROMOTION_ADJUSTMENT_KINDS, PROMOTION_ADJUSTMENT_LANES, PROMOTION_ENGINE_V2, PROMOTION_PURCHASE_SCOPES, } from "./adjustmentTypes.js";
+/** Select at most one product and one shipping adjustment. */
+/** @beta */
+export function evaluatePromotionAdjustmentsV2(context, candidates) {
+    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 !== 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) * 10000n) /
+            BigInt(context.referenceProductMinor)),
+    };
+}
+function validateContext(context) {
+    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) {
+    const runtimeLane = candidate.lane;
+    const runtimeKind = candidate.kind;
+    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)) {
+        throw new RangeError("candidate lane is invalid");
+    }
+    if (!PROMOTION_ADJUSTMENT_KINDS.includes(runtimeKind)) {
+        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) {
+    const rawById = new Map();
+    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, context, lane, floor) {
+    const scored = candidates
+        .map((candidate) => scoreCandidate(candidate, context, lane, floor))
+        .filter((candidate) => candidate.amountOffMinor > 0)
+        .sort(compareScored);
+    return scored[0] ?? null;
+}
+function scoreCandidate(candidate, context, lane, floor) {
+    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, right) {
+    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) {
+    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, applicable, winners) {
+    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();
+    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, value, minimum) {
+    if (!Number.isSafeInteger(value) || (value ?? 0) < minimum) {
+        throw new RangeError(`${name} must be a safe integer >= ${minimum}`);
+    }
+}
+function multiplyDivideFloor(value, multiplier) {
+    return Number((BigInt(value) * BigInt(multiplier)) / 10000n);
+}
+function multiplyDivideCeil(value, multiplier) {
+    const product = BigInt(value) * BigInt(multiplier);
+    return Number((product + 9999n) / 10000n);
+}
+function compareCodeUnits(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}

package/dist/promo/adjustmentTypes.d.ts

@@ -0,0 +1,103 @@
+/** @beta */
+export declare const PROMOTION_ENGINE_V2: "promotion-engine.v2";
+/** @beta */
+export declare const PROMOTION_PURCHASE_SCOPES: readonly ["one_time", "subscription_initial"];
+/** @beta */
+export type PromotionPurchaseScope = (typeof PROMOTION_PURCHASE_SCOPES)[number];
+/** @beta */
+export declare const PROMOTION_ADJUSTMENT_LANES: readonly ["product", "shipping"];
+/** @beta */
+export type PromotionAdjustmentLane = (typeof PROMOTION_ADJUSTMENT_LANES)[number];
+/** @beta */
+export declare const PROMOTION_ADJUSTMENT_KINDS: readonly ["target_percentage", "percentage", "fixed_amount", "free_shipping"];
+/** @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;
+}
+export {};

package/dist/promo/adjustmentTypes.js

@@ -0,0 +1,13 @@
+/** @beta */
+export const PROMOTION_ENGINE_V2 = "promotion-engine.v2";
+/** @beta */
+export const PROMOTION_PURCHASE_SCOPES = ["one_time", "subscription_initial"];
+/** @beta */
+export const PROMOTION_ADJUSTMENT_LANES = ["product", "shipping"];
+/** @beta */
+export const PROMOTION_ADJUSTMENT_KINDS = [
+    "target_percentage",
+    "percentage",
+    "fixed_amount",
+    "free_shipping",
+];

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

@@ -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/dist/promo/promoEvaluator.d.ts

@@ -0,0 +1,25 @@
+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 declare function evaluatePromos(input: EvaluateNowInput): AppliedPromotion[];
+/**
+ * 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 declare function promoEligibilityFailure(promo: PromotionRow, cart: EvaluateNowInput["cart"], now: string): "expired" | "not_eligible" | null;

package/dist/promo/promoEvaluator.js

@@ -0,0 +1,135 @@
+/**
+ * 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) {
+    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 = [];
+    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, cart, now) {
+    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, cart) {
+    return promo.trigger_type !== "coupon_code" || (promo.code !== null && cart.applied_codes.includes(promo.code));
+}
+function isEligibleForCart(promo, cart) {
+    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, cart) {
+    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, amount) {
+    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, cart) {
+    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) {
+    return name.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_|_$/g, "");
+}

package/dist/promo/types.d.ts

@@ -0,0 +1,86 @@
+/** @beta */
+export declare const PROMOTION_TRIGGER_TYPES: readonly ["coupon_code", "automatic", "referral"];
+/** @beta */
+export type PromotionTriggerType = (typeof PROMOTION_TRIGGER_TYPES)[number];
+/** @beta */
+export declare const PROMOTION_DISCOUNT_TYPES: readonly ["percentage", "fixed_amount", "free_shipping"];
+/** @beta */
+export type PromotionDiscountType = (typeof PROMOTION_DISCOUNT_TYPES)[number];
+/** @beta */
+export declare const PROMOTION_APPLIES_TO_KINDS: readonly ["order_total", "line_with_variant", "line_with_category"];
+/** @beta */
+export type PromotionAppliesToKind = (typeof PROMOTION_APPLIES_TO_KINDS)[number];
+/** @beta */
+export declare const PROMOTION_STACKING_RULES: readonly ["exclusive", "stackable_with_any", "stackable_with_loyalty"];
+/** @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/dist/promo/types.js

@@ -0,0 +1,12 @@
+/** @beta */
+export const PROMOTION_TRIGGER_TYPES = ["coupon_code", "automatic", "referral"];
+/** @beta */
+export const PROMOTION_DISCOUNT_TYPES = ["percentage", "fixed_amount", "free_shipping"];
+/** @beta */
+export const PROMOTION_APPLIES_TO_KINDS = ["order_total", "line_with_variant", "line_with_category"];
+/** @beta */
+export const PROMOTION_STACKING_RULES = [
+    "exclusive",
+    "stackable_with_any",
+    "stackable_with_loyalty",
+];

package/dist/risk/core/evaluator.d.ts

@@ -0,0 +1,3 @@
+import type { RiskEvaluationInput, RiskEvaluationOutput } from "./types.js";
+/** @beta */
+export declare function evaluateRisk(input: RiskEvaluationInput): RiskEvaluationOutput;

package/dist/risk/core/evaluator.js

@@ -0,0 +1,32 @@
+import { collectRiskRuleMatches } from "./rules.js";
+const SEVERITY_ORDER = ["low", "medium", "high", "critical"];
+/** @beta */
+export function evaluateRisk(input) {
+    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((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, hasBlocklist) {
+    if (hasBlocklist)
+        return "block";
+    if (score >= 35)
+        return "manual_review";
+    return "allow";
+}

package/dist/risk/core/rules.d.ts

@@ -0,0 +1,3 @@
+import type { RiskEvaluationInput, RiskRuleMatch } from "./types.js";
+/** @beta */
+export declare function collectRiskRuleMatches(input: RiskEvaluationInput): RiskRuleMatch[];