@openlup/core 0.0.0 → 0.6.0

package/dist/pricing/pricingBreakdown.js

@@ -0,0 +1,155 @@
+/**
+ * Pricing breakdown builder — pure functions that emit signed pricing components for
+ * a given (cart, resolved unit price) tuple. Sums always reconcile to the order /
+ * order_line totals via two persistence-ready invariants:
+ *
+ *   perLine:  sum(line_components.amount) = order_line.line_total_minor
+ *   perOrder: sum(all_components.amount)  = order.total_minor (including shipping)
+ *
+ * Current components: base_unit (always), mode_discount (when subscription resolves
+ * below the base unit price), qty_tier (when a quantity tier above 1 matched),
+ * bundle (line-scoped and negative, carrying the share of a composed bundle's
+ * target-price discount that the allocator assigned to this line), shipping
+ * (order-scoped, when a rule or non-zero amount applies), and promo (one negative
+ * order-scoped component per applied discount). loyalty remains a reserved
+ * component type for downstream engines.
+ */
+/** @beta */
+export const PRICING_COMPONENT_TYPES = [
+    "base_unit",
+    "mode_discount",
+    "qty_tier",
+    "bundle",
+    "promo",
+    "loyalty",
+    "shipping",
+];
+const ZERO_SHIPPING = {
+    amount_minor: 0,
+    applied_rule_id: null,
+    carrier_kind: null,
+    vat_rate_bps: null,
+};
+/** @beta */
+export function buildLineBreakdown(input) {
+    const components = [];
+    let sequence = 0;
+    // 1) Base unit price: positive, the cost-floor everything else adjusts against.
+    components.push({
+        sequence: sequence++,
+        component_type: "base_unit",
+        amount_minor: input.base_unit_price_minor * input.line_qty,
+        reason_code: "variant_unit_price",
+        reason_payload: {
+            variant_id: input.variant_id,
+            line_qty: input.line_qty,
+            base_unit_price_minor: input.base_unit_price_minor,
+        },
+    });
+    // 2) Mode discount: negative if subscription got a dedicated entry below `any`.
+    if (input.mode_at_line === "subscription" &&
+        !input.mode_resolved_via_fallback &&
+        input.resolved_unit_price_minor < input.base_unit_price_minor) {
+        const delta = (input.resolved_unit_price_minor - input.base_unit_price_minor) * input.line_qty;
+        components.push({
+            sequence: sequence++,
+            component_type: "mode_discount",
+            amount_minor: delta,
+            reason_code: "subscription_band",
+            reason_payload: {
+                unit_delta_minor: input.resolved_unit_price_minor - input.base_unit_price_minor,
+                line_qty: input.line_qty,
+            },
+        });
+    }
+    // 3) Quantity tier: negative if eligibleCartQty crossed a tier breakpoint above 1.
+    // The qty-tier discount value is encoded in the resolver's matched_tier price already, so
+    // the component only fires when matched_tier_min_qty > 1 AND we have not already applied
+    // the full delta via mode_discount.
+    if (input.matched_tier_min_qty > 1 &&
+        input.resolved_unit_price_minor === input.base_unit_price_minor) {
+        components.push({
+            sequence: sequence++,
+            component_type: "qty_tier",
+            amount_minor: 0,
+            reason_code: `qty_tier_${input.matched_tier_min_qty}`,
+            reason_payload: { matched_tier_min_qty: input.matched_tier_min_qty },
+        });
+    }
+    // 4) Bundle allocation: negative, the share of a bundle's target-price discount the
+    // allocator assigned to this line. It is line-scoped rather than order-scoped because
+    // a bundle prices a subset of the cart, and a refund of one line must return exactly
+    // the money that line was charged.
+    const bundleDiscount = input.bundle_allocated_discount_minor ?? 0;
+    if (bundleDiscount !== 0) {
+        components.push({
+            sequence: sequence++,
+            component_type: "bundle",
+            amount_minor: -bundleDiscount,
+            reason_code: "bundle_target_price",
+            reason_payload: {
+                variant_id: input.variant_id,
+                line_qty: input.line_qty,
+                allocated_discount_minor: bundleDiscount,
+            },
+        });
+    }
+    return components;
+}
+/** @beta */
+export function buildOrderBreakdown(input) {
+    const shipping = input.shipping ?? ZERO_SHIPPING;
+    const lineBreakdowns = input.lines.map((line) => {
+        const components = buildLineBreakdown(line);
+        const line_total_minor = components.reduce((sum, c) => sum + c.amount_minor, 0);
+        return { variant_id: line.variant_id, line_total_minor, components };
+    });
+    const orderComponents = [];
+    let orderSequence = 0;
+    if (shipping.amount_minor !== 0 || shipping.applied_rule_id !== null) {
+        orderComponents.push({
+            sequence: orderSequence++,
+            component_type: "shipping",
+            amount_minor: shipping.amount_minor,
+            reason_code: shipping.applied_rule_id ? `shipping:${shipping.applied_rule_id}` : "shipping:zero",
+            reason_payload: {
+                applied_rule_id: shipping.applied_rule_id,
+                carrier_kind: shipping.carrier_kind,
+                vat_rate_bps: shipping.vat_rate_bps,
+            },
+        });
+    }
+    // Order-scoped promo: one negative component per applied discount so the order total
+    // reconciles to the discounted price. amount_off is positive on the way in; the
+    // component carries it as a negative adjustment against the line + shipping subtotal.
+    for (const discount of input.discounts ?? []) {
+        orderComponents.push({
+            sequence: orderSequence++,
+            component_type: "promo",
+            amount_minor: -discount.amountOffMinor,
+            reason_code: discount.reasonCode,
+            reason_payload: {
+                promotion_id: discount.promotionId,
+                amount_off_minor: discount.amountOffMinor,
+            },
+        });
+    }
+    const lineTotal = lineBreakdowns.reduce((sum, l) => sum + l.line_total_minor, 0);
+    const orderComponentsTotal = orderComponents.reduce((sum, c) => sum + c.amount_minor, 0);
+    return {
+        lineBreakdowns,
+        orderComponents,
+        orderTotalMinor: lineTotal + orderComponentsTotal,
+    };
+}
+/**
+ * Cart-level invariant: every order's total_minor equals the sum of all components
+ * (line + order-level). Callers must assert this before persisting to commerce_orders
+ * to prevent a sale from going out with a hidden price-snapshot drift.
+ */
+/** @beta */
+export function assertBreakdownInvariant(result, orderTotalMinor) {
+    if (result.orderTotalMinor !== orderTotalMinor) {
+        throw new Error(`Pricing breakdown invariant broken: components sum to ${result.orderTotalMinor} but order.total_minor is ${orderTotalMinor}`);
+    }
+}

package/dist/pricing/targetPriceAllocation.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Bundle target-price allocation — the pure kernel that turns ONE operator-set
+ * price for a composed bundle into exact per-component money.
+ *
+ * An operator prices a bundle as a whole; every downstream surface (order lines,
+ * invoices, refunds, tax) needs a per-unit figure that reconciles back to that one
+ * number to the last minor unit. This module derives those figures and nothing else:
+ * integer arithmetic in BigInt, no clock, no randomness, no I/O.
+ *
+ * The split is largest-remainder (Hamilton), weighted by each component's own
+ * reference subtotal (quantity x unit price), with a deterministic tie-break on the
+ * component code so the same input always yields byte-identical output. Two rules
+ * bound the result:
+ *
+ *   floor:    a component never allocates below its minimum payable per unit, and a
+ *             component whose own reference unit price sits below that minimum is
+ *             held to its reference price instead — the reference price is a ceiling,
+ *             so no floor may lift a component above what it is worth.
+ *   ceiling:  a component never allocates above its reference unit price, which is
+ *             what makes the emitted per-line adjustment a discount rather than a
+ *             hidden surcharge.
+ *
+ * Invariant, asserted by the suite over a generated matrix:
+ *   sum(lines[].lineSubtotalMinor) === targetPriceMinor, exactly, always.
+ *
+ * A quantity whose allocated subtotal does not divide evenly emits TWO lines rather
+ * than a rounded unit price, because every consumer of a quote line refines
+ * `unitPrice x quantity === lineSubtotal` and a rounded unit price cannot satisfy it.
+ *
+ * Malformed input throws a RangeError (the idiom this package's other pure engines
+ * use for a caller contract breach); a well-formed request that cannot be priced
+ * returns a discriminated failure with a stable code, because those three cases are
+ * operator decisions rather than programming errors.
+ */
+/** @beta */
+export interface BundleComponentInput {
+    sku: string;
+    unitPriceMinor: number;
+    quantity: number;
+}
+/** @beta */
+export interface AllocateBundleTargetPriceInput {
+    components: ReadonlyArray<BundleComponentInput>;
+    targetPriceMinor: number;
+    minimumUnitPayableMinor?: number;
+}
+/** @beta */
+export declare const BUNDLE_ALLOCATION_FAILURE_CODES: readonly ["REFERENCE_TOTAL_ZERO", "TARGET_ABOVE_COMPONENT_SUM", "TARGET_BELOW_FLOOR"];
+/** @beta */
+export type BundleAllocationFailureCode = (typeof BUNDLE_ALLOCATION_FAILURE_CODES)[number];
+/** @beta */
+export declare const DEFAULT_MINIMUM_UNIT_PAYABLE_MINOR = 1;
+/** @beta */
+export interface BundleAllocationFailure {
+    ok: false;
+    code: BundleAllocationFailureCode;
+}
+/** @beta */
+export interface BundleAllocatedLine {
+    sku: string;
+    quantity: number;
+    effectiveUnitPriceMinor: number;
+    lineSubtotalMinor: number;
+}
+/** @beta */
+export interface BundleComponentAllocation {
+    sku: string;
+    quantity: number;
+    referenceUnitPriceMinor: number;
+    referenceSubtotalMinor: number;
+    targetSubtotalMinor: number;
+    discountAllocatedMinor: number;
+    discountBps: number;
+    hasSplitPricing: boolean;
+}
+/** @beta */
+export interface BundleAllocationResult {
+    ok: true;
+    referenceTotalMinor: number;
+    targetPriceMinor: number;
+    discountTotalMinor: number;
+    discountBps: number;
+    components: BundleComponentAllocation[];
+    lines: BundleAllocatedLine[];
+    floorApplied: boolean;
+}
+/**
+ * Derive per-component money for a bundle sold at one target price.
+ *
+ * Returns a failure when the composition cannot carry the price: nothing to weigh
+ * against (`REFERENCE_TOTAL_ZERO`), a target above the sum of the parts
+ * (`TARGET_ABOVE_COMPONENT_SUM` — a bundle is never priced above its parts, and the
+ * decision lives here as one comparison so relaxing it stays a one-line change), or
+ * a target that cannot cover every component's minimum payable (`TARGET_BELOW_FLOOR`).
+ */
+/** @beta */
+export declare function allocateBundleTargetPrice(input: AllocateBundleTargetPriceInput): BundleAllocationResult | BundleAllocationFailure;

package/dist/pricing/targetPriceAllocation.js

@@ -0,0 +1,202 @@
+/**
+ * Bundle target-price allocation — the pure kernel that turns ONE operator-set
+ * price for a composed bundle into exact per-component money.
+ *
+ * An operator prices a bundle as a whole; every downstream surface (order lines,
+ * invoices, refunds, tax) needs a per-unit figure that reconciles back to that one
+ * number to the last minor unit. This module derives those figures and nothing else:
+ * integer arithmetic in BigInt, no clock, no randomness, no I/O.
+ *
+ * The split is largest-remainder (Hamilton), weighted by each component's own
+ * reference subtotal (quantity x unit price), with a deterministic tie-break on the
+ * component code so the same input always yields byte-identical output. Two rules
+ * bound the result:
+ *
+ *   floor:    a component never allocates below its minimum payable per unit, and a
+ *             component whose own reference unit price sits below that minimum is
+ *             held to its reference price instead — the reference price is a ceiling,
+ *             so no floor may lift a component above what it is worth.
+ *   ceiling:  a component never allocates above its reference unit price, which is
+ *             what makes the emitted per-line adjustment a discount rather than a
+ *             hidden surcharge.
+ *
+ * Invariant, asserted by the suite over a generated matrix:
+ *   sum(lines[].lineSubtotalMinor) === targetPriceMinor, exactly, always.
+ *
+ * A quantity whose allocated subtotal does not divide evenly emits TWO lines rather
+ * than a rounded unit price, because every consumer of a quote line refines
+ * `unitPrice x quantity === lineSubtotal` and a rounded unit price cannot satisfy it.
+ *
+ * Malformed input throws a RangeError (the idiom this package's other pure engines
+ * use for a caller contract breach); a well-formed request that cannot be priced
+ * returns a discriminated failure with a stable code, because those three cases are
+ * operator decisions rather than programming errors.
+ */
+/** @beta */
+export const BUNDLE_ALLOCATION_FAILURE_CODES = [
+    "REFERENCE_TOTAL_ZERO",
+    "TARGET_ABOVE_COMPONENT_SUM",
+    "TARGET_BELOW_FLOOR",
+];
+/** @beta */
+export const DEFAULT_MINIMUM_UNIT_PAYABLE_MINOR = 1;
+/**
+ * Derive per-component money for a bundle sold at one target price.
+ *
+ * Returns a failure when the composition cannot carry the price: nothing to weigh
+ * against (`REFERENCE_TOTAL_ZERO`), a target above the sum of the parts
+ * (`TARGET_ABOVE_COMPONENT_SUM` — a bundle is never priced above its parts, and the
+ * decision lives here as one comparison so relaxing it stays a one-line change), or
+ * a target that cannot cover every component's minimum payable (`TARGET_BELOW_FLOOR`).
+ */
+/** @beta */
+export function allocateBundleTargetPrice(input) {
+    const components = validateInput(input);
+    const minimumUnitPayableMinor = input.minimumUnitPayableMinor ?? DEFAULT_MINIMUM_UNIT_PAYABLE_MINOR;
+    const target = BigInt(input.targetPriceMinor);
+    const references = components.map((item) => BigInt(item.quantity) * BigInt(item.unitPriceMinor));
+    const referenceTotal = references.reduce(add, 0n);
+    assertSafe("referenceTotalMinor", referenceTotal);
+    if (referenceTotal === 0n)
+        return { ok: false, code: "REFERENCE_TOTAL_ZERO" };
+    if (target > referenceTotal)
+        return { ok: false, code: "TARGET_ABOVE_COMPONENT_SUM" };
+    const floors = components.map((item) => BigInt(item.quantity) * BigInt(Math.min(minimumUnitPayableMinor, item.unitPriceMinor)));
+    if (target < floors.reduce(add, 0n))
+        return { ok: false, code: "TARGET_BELOW_FLOOR" };
+    const codes = components.map((item) => item.sku);
+    const { subtotals, floorApplied } = splitAgainstFloors(target, references, floors, codes);
+    const allocations = components.map((item, index) => describe(item, references[index], subtotals[index]));
+    return {
+        ok: true,
+        referenceTotalMinor: Number(referenceTotal),
+        targetPriceMinor: input.targetPriceMinor,
+        discountTotalMinor: Number(referenceTotal - target),
+        discountBps: roundedBps(referenceTotal - target, referenceTotal),
+        components: allocations.map(({ allocation }) => allocation),
+        lines: allocations.flatMap(({ lines }) => lines),
+        floorApplied,
+    };
+}
+/**
+ * Split `target` over the open components, pin every component whose share landed
+ * under its floor, and re-split the rest until no further component is pinned.
+ * Terminates: each round either pins at least one component or is the last one, and
+ * at least one component always survives, because a round where every open share
+ * fell under its floor would mean the shares sum below a floor total the caller
+ * already proved the target covers.
+ */
+function splitAgainstFloors(target, references, floors, codes) {
+    const subtotals = references.map(() => 0n);
+    const pinned = references.map(() => false);
+    let floorApplied = false;
+    for (;;) {
+        const open = references.map((_, index) => index).filter((index) => !pinned[index]);
+        const pinnedTotal = references.reduce((total, _, index) => (pinned[index] ? total + floors[index] : total), 0n);
+        const shares = largestRemainder(target - pinnedTotal, open.map((index) => references[index]), open.map((index) => codes[index]));
+        const underFloor = open.filter((index, slot) => shares[slot] < floors[index]);
+        if (underFloor.length > 0) {
+            for (const index of underFloor)
+                pinned[index] = true;
+            floorApplied = true;
+            continue;
+        }
+        open.forEach((index, slot) => { subtotals[index] = shares[slot]; });
+        pinned.forEach((isPinned, index) => { if (isPinned)
+            subtotals[index] = floors[index]; });
+        return { subtotals, floorApplied };
+    }
+}
+/**
+ * Hamilton split: proportional floor first, then hand the rounding deficit to the
+ * largest remainders, ties broken by ascending component code so the outcome never
+ * depends on input order or host collation.
+ */
+function largestRemainder(amount, weights, codes) {
+    const total = weights.reduce(add, 0n);
+    const shares = weights.map((weight) => (amount * weight) / total);
+    const remainders = weights.map((weight) => (amount * weight) % total);
+    const order = weights
+        .map((_, index) => index)
+        .sort((left, right) => (remainders[left] === remainders[right]
+        ? compareCodeUnits(codes[left], codes[right])
+        : (remainders[left] > remainders[right] ? -1 : 1)));
+    let deficit = amount - shares.reduce(add, 0n);
+    for (const index of order) {
+        if (deficit === 0n)
+            break;
+        shares[index] += 1n;
+        deficit -= 1n;
+    }
+    return shares;
+}
+function describe(item, reference, subtotal) {
+    const quantity = BigInt(item.quantity);
+    const unit = subtotal / quantity;
+    const remainder = subtotal - unit * quantity;
+    const lines = remainder === 0n
+        ? [line(item.sku, quantity, unit)]
+        : [line(item.sku, remainder, unit + 1n), line(item.sku, quantity - remainder, unit)];
+    return {
+        allocation: {
+            sku: item.sku,
+            quantity: item.quantity,
+            referenceUnitPriceMinor: item.unitPriceMinor,
+            referenceSubtotalMinor: Number(reference),
+            targetSubtotalMinor: Number(subtotal),
+            discountAllocatedMinor: Number(reference - subtotal),
+            discountBps: roundedBps(reference - subtotal, reference),
+            hasSplitPricing: remainder !== 0n,
+        },
+        lines,
+    };
+}
+function line(sku, quantity, unit) {
+    return {
+        sku,
+        quantity: Number(quantity),
+        effectiveUnitPriceMinor: Number(unit),
+        lineSubtotalMinor: Number(quantity * unit),
+    };
+}
+function validateInput(input) {
+    if (!Array.isArray(input.components) || input.components.length === 0) {
+        throw new RangeError("components must be a non-empty array");
+    }
+    assertMinor("targetPriceMinor", input.targetPriceMinor, 0);
+    assertMinor("minimumUnitPayableMinor", input.minimumUnitPayableMinor ?? DEFAULT_MINIMUM_UNIT_PAYABLE_MINOR, 0);
+    const seen = new Set();
+    for (const item of input.components) {
+        if (typeof item.sku !== "string" || !item.sku.trim()) {
+            throw new RangeError("every component requires a code");
+        }
+        if (seen.has(item.sku))
+            throw new RangeError(`duplicate component code ${item.sku}`);
+        seen.add(item.sku);
+        assertMinor("quantity", item.quantity, 1);
+        assertMinor("unitPriceMinor", item.unitPriceMinor, 0);
+    }
+    return [...input.components];
+}
+function assertMinor(name, value, minimum) {
+    if (!Number.isSafeInteger(value) || value < minimum) {
+        throw new RangeError(`${name} must be a safe integer >= ${minimum}`);
+    }
+}
+function assertSafe(name, value) {
+    if (value > BigInt(Number.MAX_SAFE_INTEGER)) {
+        throw new RangeError(`${name} must stay inside the safe integer range`);
+    }
+}
+function roundedBps(amount, reference) {
+    if (reference === 0n)
+        return 0;
+    return Number((amount * 20000n + reference) / (reference * 2n));
+}
+function add(total, value) {
+    return total + value;
+}
+// Component codes are unique by validation, so an equal pair never reaches the sort.
+function compareCodeUnits(left, right) {
+    return left < right ? -1 : 1;
+}

package/dist/pricing/types.d.ts

@@ -0,0 +1,32 @@
+/** @beta */
+export declare const PRICING_MODES: readonly ["one_time", "subscription", "any"];
+/** @beta */
+export type PricingMode = (typeof PRICING_MODES)[number];
+/** @beta */
+export declare const PRICING_AMOUNT_KINDS: readonly ["gross", "net"];
+/** @beta */
+export type PricingAmountKind = (typeof PRICING_AMOUNT_KINDS)[number];
+/** @beta */
+export interface PricingRegion {
+    regionCode: string;
+    currency: string;
+}
+/** @beta */
+export interface ResolvedPrice {
+    variantId: string;
+    mode: PricingMode;
+    matchedMinQty: number;
+    unitPriceMinor: number;
+    amountKind: PricingAmountKind;
+    priceListId: string;
+    priceEntryId: string;
+    resolvedAt: string;
+}
+/** @beta */
+export interface ResolvePriceQuery extends PricingRegion {
+    variantId: string;
+    mode: PricingMode;
+    lineQty: number;
+    eligibleCartQty: number;
+    atTime?: string;
+}

package/dist/pricing/types.js

@@ -0,0 +1,4 @@
+/** @beta */
+export const PRICING_MODES = ["one_time", "subscription", "any"];
+/** @beta */
+export const PRICING_AMOUNT_KINDS = ["gross", "net"];

package/dist/promo/adjustmentEngine.d.ts

@@ -0,0 +1,4 @@
+import { type PromotionAdjustmentCandidate, type PromotionAdjustmentContext, type PromotionAdjustmentResult } from "./adjustmentTypes.js";
+/** Select at most one product and one shipping adjustment. */
+/** @beta */
+export declare function evaluatePromotionAdjustmentsV2(context: PromotionAdjustmentContext, candidates: readonly PromotionAdjustmentCandidate[]): PromotionAdjustmentResult;