@mj-biz-apps/orders-core-entities-server 0.0.1 → 5.2.0

package/dist/BundleBehavior.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BundleBehavior.d.ts","sourceRoot":"","sources":["../src/BundleBehavior.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAKH,0CAA0C;AAC1C,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,YAAY,CAAC;AAEzD,4DAA4D;AAC5D,MAAM,WAAW,eAAe;IAC5B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,iBAAiB,CAAC;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,sBAAsB,EAAE,MAAM,GAAG,IAAI,CAAC;CACzC;AAED,oCAAoC;AACpC,MAAM,WAAW,kBAAkB;IAC/B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,4CAA4C;IAC5C,QAAQ,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,MAAM,aAAa,GACnB,YAAY,GACZ,cAAc,GACd,qBAAqB,GACrB,cAAc,GACd,cAAc,CAAC;AAErB,MAAM,WAAW,UAAU;IACvB,QAAQ,EAAE,kBAAkB,EAAE,CAAC;IAC/B,OAAO,EAAE,aAAa,GAAG,IAAI,CAAC;IAC9B,2FAA2F;IAC3F,eAAe,EAAE,OAAO,CAAC;CAC5B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CA2BvE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAC/B,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,eAAe,EAAE,GAC9B;IAAE,YAAY,EAAE,MAAM,EAAE,CAAC;IAAC,eAAe,EAAE,OAAO,CAAA;CAAE,CAqBtD;AAED,kDAAkD;AAClD,MAAM,WAAW,eAAe;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,gFAAgF;IAChF,SAAS,EAAE,MAAM,CAAC;IAClB,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,0FAA0F;IAC1F,SAAS,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAC/B,IAAI,EAAE,eAAe,EACrB,UAAU,EAAE,eAAe,EAAE,GAC9B,UAAU,CAgCZ;AAED,0FAA0F;AAC1F,wBAAgB,aAAa,CAAC,cAAc,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,GAAG,MAAM,CAKvF;AAED,+EAA+E;AAC/E,MAAM,WAAW,WAAW;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,iBAAiB,EAAE,MAAM,CAAC;IAC1B,oBAAoB,EAAE,OAAO,CAAC;IAC9B,eAAe,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,YAAY;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAC9B,cAAc,EAAE,MAAM,EACtB,QAAQ,EAAE,WAAW,EAAE,GACxB,YAAY,EAAE,CAchB;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,KAAK,CAAC;IAAE,cAAc,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG,MAAM,CAE7F"}

package/dist/BundleBehavior.js

@@ -0,0 +1,173 @@
+/**
+ * Bundle expansion arithmetic, with no database in sight.
+ *
+ * WHY EXPAND AT ALL. A bundle sold as one line forces ONE of everything: one tax treatment, one
+ * revenue schedule, one GL account, one entitlement, one returnable unit. A bundle of a publication
+ * (often exempt) and a conference registration (not) taxed at the header is simply wrong, and a
+ * bundle spanning a subscription and an event cannot be scheduled from a single line at all. So the
+ * components become real order lines and everything downstream keeps working per line.
+ *
+ * WHAT THE PARENT IS FOR. The customer bought "the Gold Package", not four things, and reporting
+ * needs to know a component came from a bundle — and from WHICH bundle line, since two Gold Packages
+ * on one order produce two indistinguishable sets otherwise. So the parent line survives as the
+ * customer-facing row, carrying `IsRollupParent`, and contributes ZERO to every total. The children
+ * carry the money.
+ *
+ * THE ARITHMETIC THAT BITES. Allocating one bundle price across components by relative standalone
+ * selling price does not divide evenly. Allocate $100 across three equal components and naive
+ * rounding gives 33.33 × 3 = 99.99 — a penny that vanishes, on an order that still balances because
+ * every line agrees with itself. `AllocateBundlePrice` uses largest-remainder so the parts sum to
+ * the whole EXACTLY, and its tests assert that on deliberately awkward numbers.
+ *
+ * CONNECTS TO:
+ *   CODE: BundleEngine (the rows) · OrderEntityServer (the lifecycle point)
+ *   DOC:  plans/archive/bizapps-orders-master.md D32/D41 (bundles), D45 (ParentOrderLineID)
+ */
+/** Round to cents the way the rest of the engine does. */
+const Money = (n) => Math.round((n + Number.EPSILON) * 100) / 100;
+/**
+ * Split `total` across `weights` so the parts sum to `total` EXACTLY.
+ *
+ * Largest-remainder: floor every share to cents, then hand the leftover pennies one at a time to
+ * whichever shares were cut by the most. The naive alternative — round each share independently —
+ * loses or invents money on most inputs, and does it invisibly: each line is individually plausible
+ * and the order still balances against itself.
+ *
+ * Ties break toward the earlier index, so the result is deterministic for a given input rather than
+ * dependent on sort stability.
+ */
+export function SplitExactly(total, weights) {
+    const n = weights.length;
+    if (n === 0)
+        return [];
+    const cents = Math.round(Money(total) * 100);
+    const weightSum = weights.reduce((s, w) => s + w, 0);
+    // No usable weights: split as evenly as cents allow rather than putting it all on the first.
+    if (!(weightSum > 0)) {
+        const base = Math.floor(cents / n);
+        const out = new Array(n).fill(base);
+        for (let i = 0; i < cents - base * n; i++)
+            out[i] += 1;
+        return out.map((c) => c / 100);
+    }
+    const exact = weights.map((w) => (cents * w) / weightSum);
+    const floors = exact.map((e) => Math.floor(e));
+    let remaining = cents - floors.reduce((s, f) => s + f, 0);
+    const order = exact
+        .map((e, i) => ({ i, rem: e - Math.floor(e) }))
+        .sort((a, b) => (b.rem === a.rem ? a.i - b.i : b.rem - a.rem));
+    const out = [...floors];
+    for (let k = 0; k < order.length && remaining > 0; k++, remaining--)
+        out[order[k].i] += 1;
+    return out.map((c) => c / 100);
+}
+/**
+ * Allocate a bundle's price across its components by relative standalone selling price.
+ *
+ * `Bundled` components share the bundle price. `SumOfParts` components are priced on their own and
+ * take no share of it — a bundle may mix the two, which is how "everything in the package plus a
+ * discounted add-on priced separately" is expressed.
+ *
+ * WHEN NO COMPONENT HAS A PRICE the weights are all zero and there is nothing to allocate BY. Rather
+ * than refuse the sale or silently dump the whole amount on the first component, it splits evenly
+ * and says so through `AllocatedEvenly`, so a caller can record that the allocation was arbitrary.
+ * An even split is defensible; a silent lopsided one is not.
+ */
+export function AllocateBundlePrice(bundleTotal, components) {
+    const bundled = components.map((c) => c.PricingMode === 'Bundled');
+    // Weight by the component's standalone value FOR THE WHOLE LINE — its price times how many of
+    // it the bundle contains. Weighting by unit price alone would under-allocate to a component
+    // that appears three times.
+    const weights = components.map((c, i) => bundled[i] ? Math.max(0, Number(c.StandaloneSellingPrice ?? 0)) * Math.max(0, c.Quantity) : 0);
+    const bundledCount = bundled.filter(Boolean).length;
+    const weightSum = weights.reduce((s, w) => s + w, 0);
+    const allocatedEvenly = bundledCount > 0 && !(weightSum > 0);
+    if (allocatedEvenly) {
+        // Even across the BUNDLED ones only; SumOfParts components still take nothing.
+        const evenWeights = components.map((_, i) => (bundled[i] ? 1 : 0));
+        return { PerComponent: SplitExactly(bundleTotal, evenWeights), AllocatedEvenly: true };
+    }
+    return { PerComponent: SplitExactly(bundleTotal, weights), AllocatedEvenly: false };
+}
+/**
+ * Plan the child lines a bundle line expands into.
+ *
+ * ONE LEVEL ONLY. A component that is itself a bundle is refused rather than expanded recursively:
+ * the quantity ripple and the allocation both get considerably harder, and nothing in the catalog
+ * needs it yet. Easy to relax; very hard to un-ship once orders exist that depend on it.
+ */
+export function PlanBundleExpansion(line, components) {
+    const empty = (reason) => ({
+        Children: [],
+        Refusal: reason,
+        AllocatedEvenly: false,
+    });
+    if (!components.length)
+        return empty('NotABundle');
+    if (line.ReversesOrderLineID)
+        return empty('ReversalLine');
+    if (line.HasParent)
+        return empty('NestedBundle');
+    const qty = Number(line.Quantity ?? 0);
+    if (!(qty > 0))
+        return empty('NonPositiveQuantity');
+    // What the whole parent line is worth, which is what gets allocated.
+    const bundleTotal = Money(Money(line.UnitPrice ?? 0) * qty);
+    const { PerComponent, AllocatedEvenly } = AllocateBundlePrice(bundleTotal, components);
+    const children = components.map((c, i) => {
+        const childQty = ChildQuantity(qty, c.Quantity);
+        // The allocation is a TOTAL for the component across the whole line; the line stores a UNIT
+        // price, so divide back out. Dividing by zero would be a NaN that saves cleanly, so guard it.
+        const unitPrice = childQty > 0 ? Money(PerComponent[i] / childQty) : 0;
+        return {
+            ComponentProductID: c.ComponentProductID,
+            Quantity: childQty,
+            UnitPrice: c.PricingMode === 'Bundled' ? unitPrice : Money(c.StandaloneSellingPrice ?? 0),
+            SortOrder: c.SortOrder,
+        };
+    });
+    return { Children: children, Refusal: null, AllocatedEvenly };
+}
+/** A child's quantity: how many bundles times how many of the component each contains. */
+export function ChildQuantity(parentQuantity, componentQuantity) {
+    const q = Number(parentQuantity ?? 0) * Number(componentQuantity ?? 0);
+    // Component quantities are DECIMAL(18,4); keep the same scale rather than rounding to an integer,
+    // since 0.5 hours of a service per bundle is a legitimate thing to sell.
+    return Math.round((q + Number.EPSILON) * 10000) / 10000;
+}
+/**
+ * What a change to the parent's quantity should do to its children.
+ *
+ * A child whose quantity was hand-edited DETACHES from the ripple. Without that, bumping the bundle
+ * quantity silently overwrites a deliberate correction — data loss that looks exactly like
+ * arithmetic, because the number it lands on is the number the formula says it should be.
+ *
+ * Returns only the children that actually change, so a no-op ripple writes nothing.
+ */
+export function PlanQuantityRipple(parentQuantity, children) {
+    const changes = [];
+    for (const child of children) {
+        if (child.IsQuantityOverridden)
+            continue;
+        const target = ChildQuantity(parentQuantity, child.ComponentQuantity);
+        if (target !== child.CurrentQuantity) {
+            changes.push({
+                OrderLineID: child.ID,
+                FromQuantity: child.CurrentQuantity,
+                ToQuantity: target,
+            });
+        }
+    }
+    return changes;
+}
+/**
+ * Does this set of lines total correctly once parents are excluded?
+ *
+ * The invariant every rollup depends on: a rollup parent contributes nothing, so the sum over
+ * non-parent lines is the order's real value. Exported because it is worth asserting from the
+ * outside rather than trusting each rollup to remember.
+ */
+export function RollupTotal(lines) {
+    return Money(lines.filter((l) => !l.IsRollupParent).reduce((s, l) => s + Number(l.Amount ?? 0), 0));
+}
+//# sourceMappingURL=BundleBehavior.js.map

package/dist/BundleBehavior.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BundleBehavior.js","sourceRoot":"","sources":["../src/BundleBehavior.ts"],"names":[],"mappings":"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"}

package/dist/BundleEngine.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Expand bundle lines into their components, in memory, before anything is written.
+ *
+ * The ARITHMETIC lives in `BundleBehavior` and is unit-tested without a database. What lives here is
+ * the catalog lookup and the mutation of the pending line collection.
+ *
+ * WHY IT RUNS IN MEMORY, BEFORE THE INSERT. A Confirmed line is frozen by trigger 51003, and because
+ * the CRUD procs run under INSERT-EXEC a trigger rollback surfaces as "Cannot use the ROLLBACK
+ * statement within an INSERT-EXEC statement" — an error naming neither the line nor the rule. So
+ * anything that changes a line's money has to be settled before the row goes down, not corrected
+ * afterwards. Expansion changes a great deal of money: it zeroes the parent and creates children.
+ *
+ * WHY THE PARENT'S ID IS ASSIGNED HERE. A child needs `ParentOrderLineID` at INSERT time for the
+ * same reason — setting it afterwards would be an update to a frozen line. So the parent gets its
+ * ID before either row is written, and the children point at it from the start.
+ *
+ * SNAPSHOT, NOT A LIVE VIEW. Expansion is frozen onto the order when it is placed. Editing
+ * `ProductBundleItem` later must never mutate a historical order, so nothing re-derives children
+ * from the bundle definition after the fact.
+ *
+ * CONNECTS TO:
+ *   PURE: BundleBehavior (+ its unit tests)
+ *   CODE: OrderEntityServer.expandBundles (the lifecycle point)
+ *   DOC:  plans/archive/bizapps-orders-master.md D32/D41, D45
+ */
+import { IMetadataProvider, UserInfo } from '@memberjunction/core';
+import { mjBizAppsOrdersOrderLineEntity } from '@mj-biz-apps/orders-entities';
+/** The subset of an order line this engine reads and writes. Kept structural so there is no import cycle. */
+/**
+ * An order line this engine can expand.
+ *
+ * Was a structural duck-type built on `Get`/`Set` — which meant every field this module touched
+ * was a string literal the compiler could not check. It is the order-line entity; say so.
+ */
+export type ExpandableLine = mjBizAppsOrdersOrderLineEntity;
+export interface BundleExpansionOutcome {
+    /** How many parent lines were expanded. */
+    Expanded: number;
+    /** How many child lines were created. */
+    ChildrenCreated: number;
+    /** Parent line IDs whose allocation had no prices to go on and was split evenly. */
+    ArbitrarilyAllocated: string[];
+}
+/**
+ * Expand every bundle line in `lines`, appending children to the same collection.
+ *
+ * `makeLine` creates a fresh, unsaved order-line entity — supplied by the caller so this module does
+ * not need to know how the host builds one. Returns what happened rather than throwing when there is
+ * nothing to expand, since most orders contain no bundles.
+ */
+export declare function ExpandBundleLines(lines: ExpandableLine[], makeLine: () => Promise<ExpandableLine>, provider: IMetadataProvider, user: UserInfo): Promise<BundleExpansionOutcome>;
+/**
+ * Apply a parent's quantity change to its children.
+ *
+ * Exported for the edit path rather than the confirm path — on a DRAFT order a parent's quantity may
+ * still change, and its children have to follow. A child whose quantity was hand-edited detaches, so
+ * a deliberate correction is not silently overwritten by the formula.
+ */
+export declare function RippleBundleQuantity(parentOrderLineID: string, parentQuantity: number, provider: IMetadataProvider, user: UserInfo): Promise<number>;
+//# sourceMappingURL=BundleEngine.d.ts.map

package/dist/BundleEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BundleEngine.d.ts","sourceRoot":"","sources":["../src/BundleEngine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,EAEH,iBAAiB,EAGjB,QAAQ,EACX,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,8BAA8B,EAAE,MAAM,8BAA8B,CAAC;AAc9E,6GAA6G;AAC7G;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,8BAA8B,CAAC;AAE5D,MAAM,WAAW,sBAAsB;IACnC,2CAA2C;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,yCAAyC;IACzC,eAAe,EAAE,MAAM,CAAC;IACxB,oFAAoF;IACpF,oBAAoB,EAAE,MAAM,EAAE,CAAC;CAClC;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACnC,KAAK,EAAE,cAAc,EAAE,EACvB,QAAQ,EAAE,MAAM,OAAO,CAAC,cAAc,CAAC,EACvC,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,EAAE,QAAQ,GACf,OAAO,CAAC,sBAAsB,CAAC,CAkIjC;AAED;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACtC,iBAAiB,EAAE,MAAM,EACzB,cAAc,EAAE,MAAM,EACtB,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,EAAE,QAAQ,GACf,OAAO,CAAC,MAAM,CAAC,CA0DjB"}

package/dist/BundleEngine.js

@@ -0,0 +1,197 @@
+/**
+ * Expand bundle lines into their components, in memory, before anything is written.
+ *
+ * The ARITHMETIC lives in `BundleBehavior` and is unit-tested without a database. What lives here is
+ * the catalog lookup and the mutation of the pending line collection.
+ *
+ * WHY IT RUNS IN MEMORY, BEFORE THE INSERT. A Confirmed line is frozen by trigger 51003, and because
+ * the CRUD procs run under INSERT-EXEC a trigger rollback surfaces as "Cannot use the ROLLBACK
+ * statement within an INSERT-EXEC statement" — an error naming neither the line nor the rule. So
+ * anything that changes a line's money has to be settled before the row goes down, not corrected
+ * afterwards. Expansion changes a great deal of money: it zeroes the parent and creates children.
+ *
+ * WHY THE PARENT'S ID IS ASSIGNED HERE. A child needs `ParentOrderLineID` at INSERT time for the
+ * same reason — setting it afterwards would be an update to a frozen line. So the parent gets its
+ * ID before either row is written, and the children point at it from the start.
+ *
+ * SNAPSHOT, NOT A LIVE VIEW. Expansion is frozen onto the order when it is placed. Editing
+ * `ProductBundleItem` later must never mutate a historical order, so nothing re-derives children
+ * from the bundle definition after the fact.
+ *
+ * CONNECTS TO:
+ *   PURE: BundleBehavior (+ its unit tests)
+ *   CODE: OrderEntityServer.expandBundles (the lifecycle point)
+ *   DOC:  plans/archive/bizapps-orders-master.md D32/D41, D45
+ */
+import { RunView, } from '@memberjunction/core';
+import { PlanBundleExpansion, } from './BundleBehavior.js';
+const PRODUCT_BUNDLE_ITEM_ENTITY = 'MJ_BizApps_Orders: Product Bundle Items';
+const PRODUCT_PRICE_ENTITY = 'MJ_BizApps_Orders: Product Prices';
+const ORDER_LINE_ENTITY = 'MJ_BizApps_Orders: Order Lines';
+const key = (id) => (id ?? '').toLowerCase();
+const quote = (ids) => [...new Set(ids.map((i) => `'${i}'`))].join(',');
+/**
+ * Expand every bundle line in `lines`, appending children to the same collection.
+ *
+ * `makeLine` creates a fresh, unsaved order-line entity — supplied by the caller so this module does
+ * not need to know how the host builds one. Returns what happened rather than throwing when there is
+ * nothing to expand, since most orders contain no bundles.
+ */
+export async function ExpandBundleLines(lines, makeLine, provider, user) {
+    const out = { Expanded: 0, ChildrenCreated: 0, ArbitrarilyAllocated: [] };
+    if (!lines.length)
+        return out;
+    const rv = new RunView(provider);
+    // WHICH of these products are bundles? One query, not one per line.
+    const productIDs = [...new Set(lines.map((l) => l.ProductID))].filter(Boolean);
+    if (!productIDs.length)
+        return out;
+    const items = await rv.RunView({
+        EntityName: PRODUCT_BUNDLE_ITEM_ENTITY,
+        ExtraFilter: `BundleProductID IN (${quote(productIDs)})`,
+        ResultType: 'simple',
+    }, user);
+    const rows = items.Results ?? [];
+    if (!rows.length)
+        return out;
+    const componentsByBundle = new Map();
+    for (const row of rows) {
+        const k = key(row.BundleProductID);
+        if (!componentsByBundle.has(k))
+            componentsByBundle.set(k, []);
+        componentsByBundle.get(k).push(row);
+    }
+    for (const list of componentsByBundle.values())
+        list.sort((a, b) => a.SortOrder - b.SortOrder);
+    // STANDALONE SELLING PRICES for the components, so allocation has something to weight by. Only
+    // Active, undated-or-current rules with no price list — a list-scoped price is a negotiated
+    // price for one customer, not the product's standalone value.
+    const componentIDs = [...new Set(rows.map((r) => r.ComponentProductID))];
+    const prices = await rv.RunView({
+        EntityName: PRODUCT_PRICE_ENTITY,
+        ExtraFilter: `ProductID IN (${quote(componentIDs)}) AND Status = 'Active' ` +
+            `AND PriceListID IS NULL AND MinQuantity IS NULL AND MaxQuantity IS NULL`,
+        ResultType: 'simple',
+    }, user);
+    const sspByProduct = new Map();
+    for (const p of (prices.Results ?? []).sort((a, b) => (b.Priority ?? 0) - (a.Priority ?? 0))) {
+        // Highest priority wins; the ambiguity guard already stops two rules tying.
+        if (!sspByProduct.has(key(p.ProductID)))
+            sspByProduct.set(key(p.ProductID), Number(p.Amount));
+    }
+    // Snapshot the collection: children are appended as we go and must not themselves be scanned.
+    const originals = [...lines];
+    for (const line of originals) {
+        const components = componentsByBundle.get(key(line.ProductID));
+        if (!components?.length)
+            continue;
+        const facts = {
+            ID: line.ID,
+            ProductID: line.ProductID,
+            Quantity: Number(line.Quantity ?? 0),
+            UnitPrice: Number(line.UnitPrice ?? 0),
+            ReversesOrderLineID: line.ReversesOrderLineID ?? null,
+            HasParent: !!line.ParentOrderLineID,
+        };
+        const plan = PlanBundleExpansion(facts, components.map((c) => ({
+            ComponentProductID: c.ComponentProductID,
+            Quantity: Number(c.Quantity ?? 1),
+            PricingMode: c.PricingMode,
+            SortOrder: c.SortOrder,
+            StandaloneSellingPrice: sspByProduct.get(key(c.ComponentProductID)) ?? null,
+        })));
+        if (!plan.Children.length) {
+            // A reversal line is a legitimate non-expansion — the return path unwinds the children
+            // that already exist. A NESTED bundle is not, and saying so beats expanding it wrongly.
+            if (plan.Refusal === 'NestedBundle') {
+                throw new Error(`Order line ${line.ID} is a bundle inside another bundle. Bundles expand ONE level ` +
+                    `only (D45) — the quantity ripple and the price allocation are not defined for ` +
+                    `deeper nesting. Sell the inner bundle's components directly, or sell it as its ` +
+                    `own line.`);
+            }
+            continue;
+        }
+        // THE PARENT KEEPS ITS PRICE FOR DISPLAY AND CONTRIBUTES NOTHING. Every rollup skips a
+        // rollup parent, so leaving money on it would double the order — which is exactly what the
+        // CK_OrderLine_RollupParentIsFree constraint refuses at the database.
+        line.IsRollupParent = true;
+        line.DiscountAmount = 0;
+        line.ChargeAmount = 0;
+        line.LineTax = 0;
+        for (const child of plan.Children) {
+            const row = await makeLine();
+            row.ProductID = child.ComponentProductID;
+            row.Quantity = child.Quantity;
+            row.UnitPrice = child.UnitPrice;
+            row.ParentOrderLineID = line.ID;
+            row.SourceBundleProductID = line.ProductID;
+            row.IsRollupParent = false;
+            row.IsQuantityOverridden = false;
+            lines.push(row);
+            out.ChildrenCreated++;
+        }
+        out.Expanded++;
+        if (plan.AllocatedEvenly)
+            out.ArbitrarilyAllocated.push(line.ID);
+    }
+    if (out.ArbitrarilyAllocated.length) {
+        console.warn(`Bundle line(s) ${out.ArbitrarilyAllocated.join(', ')}: no component carried a standalone ` +
+            `price, so the bundle price was split EVENLY rather than by relative value. The order ` +
+            `totals correctly, but the per-component revenue split is arbitrary. Price the ` +
+            `components to make the allocation meaningful.`);
+    }
+    return out;
+}
+/**
+ * Apply a parent's quantity change to its children.
+ *
+ * Exported for the edit path rather than the confirm path — on a DRAFT order a parent's quantity may
+ * still change, and its children have to follow. A child whose quantity was hand-edited detaches, so
+ * a deliberate correction is not silently overwritten by the formula.
+ */
+export async function RippleBundleQuantity(parentOrderLineID, parentQuantity, provider, user) {
+    const rv = new RunView(provider);
+    const children = await rv.RunView({
+        EntityName: ORDER_LINE_ENTITY,
+        ExtraFilter: `ParentOrderLineID = '${parentOrderLineID}'`,
+        ResultType: 'simple',
+    }, user);
+    const rows = children.Results ?? [];
+    if (!rows.length)
+        return 0;
+    // The per-bundle component quantity is not stored on the child — it is the catalog's, and the
+    // catalog may have changed since. Read it from the SNAPSHOT instead: the child's current
+    // quantity divided by the parent's current quantity is what was agreed at expansion time.
+    // Falls back to the catalog only when the parent's old quantity is unknown.
+    const bundleProductID = rows[0].SourceBundleProductID;
+    const items = bundleProductID
+        ? await rv.RunView({
+            EntityName: PRODUCT_BUNDLE_ITEM_ENTITY,
+            ExtraFilter: `BundleProductID = '${bundleProductID}'`,
+            ResultType: 'simple',
+        }, user)
+        : { Results: [] };
+    const perBundle = new Map((items.Results ?? []).map((i) => [key(i.ComponentProductID), Number(i.Quantity ?? 1)]));
+    let changed = 0;
+    for (const child of rows) {
+        if (child.IsQuantityOverridden)
+            continue;
+        const per = perBundle.get(key(child.ProductID));
+        if (per == null)
+            continue;
+        const target = Math.round((parentQuantity * per + Number.EPSILON) * 10000) / 10000;
+        if (target === Number(child.Quantity))
+            continue;
+        const entity = await provider.GetEntityObject(ORDER_LINE_ENTITY, user);
+        if (!(await entity.Load(child.ID)))
+            continue;
+        entity.Quantity = target;
+        if (!(await entity.Save())) {
+            throw new Error(`Could not ripple quantity ${target} to bundle child ${child.ID}: ` +
+                `${entity.LatestResult?.CompleteMessage ?? 'no reason given'}`);
+        }
+        changed++;
+    }
+    return changed;
+}
+//# sourceMappingURL=BundleEngine.js.map

package/dist/BundleEngine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BundleEngine.js","sourceRoot":"","sources":["../src/BundleEngine.ts"],"names":[],"mappings":"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"}

package/dist/CancelSubscriptionOperation.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Orders.CancelSubscription — cancel a subscription atomically, by POLICY (design §5).
+ *
+ * WHY THIS IS AN OPERATION AND NOT A FORM
+ * The mechanics already worked: a reversal order line with a negative quantity produces mirrored
+ * journal entries through the ordinary booking path (D16). What did not work was asking a human to
+ * do it. Amith's case — a subscription running 1/1–12/31, cancelled on 7/1 — needs a line of
+ * quantity `-0.5`. That is correct double-entry and terrible data entry, and it silently ignores
+ * the `SubscriptionType`'s own rules about WHEN coverage may end and WHETHER money comes back.
+ *
+ * So the caller supplies a subscription, a date and a reason. `SubscriptionBehavior` decides what
+ * the rules permit; this operation performs it in ONE transaction:
+ *
+ *   1. resolve the affected term (the one whose window covers the request, else the latest)
+ *   2. ask the behaviour what the rules say — effective date, refund, reversal fraction
+ *   3. when there is something to reverse, emit a reversal ORDER whose single line carries the
+ *      negative quantity and points at the original line, and confirm it — booking mirrors the JEs
+ *   4. stamp the term (Canceled/Completed, CanceledAt, CancellationEffectiveDate)
+ *   5. stamp the subscription (Canceled, EndDate = access-through, so grace is visible)
+ *   6. revoke standing grants when access-through has already passed; leave them when
+ *      grace remains — the read evaluator honours `subscription.EndDate` either way
+ *   7. log a `SubscriptionEvent` — the lifecycle record that made the table worth having
+ *
+ * ATOMICITY: everything above shares one transaction opened here. The reversal order's own
+ * `OrderEntityServer.Save` nests inside it as savepoints (the same composition booking already
+ * relies on), so a failure anywhere leaves the subscription exactly as it was — never a reversed
+ * ledger with a still-active subscription, or vice versa.
+ *
+ * FAILURE MODEL: logical failures (unknown subscription, already cancelled, no term) come back
+ * INSIDE the output as `Success: false` with a message — the same contract accounting's operations
+ * use. Only genuine faults throw.
+ *
+ * CONNECTS TO:
+ *   POLICY: SubscriptionBehavior.DecideCancellation (./SubscriptionBehavior.ts)
+ *   BOOKING: OrderEntityServer.Save (./OrderEntityServer.ts) — the reversal order goes through it
+ *   TABLES: __mj_BizAppsOrders.{Subscription,SubscriptionTerm,SubscriptionEvent,OrderHeader,OrderLine}
+ */
+import { BaseRemotableOperation, IMetadataProvider, UserInfo } from '@memberjunction/core';
+import { type CancellationDecision } from './SubscriptionBehavior.js';
+export interface CancelSubscriptionInput {
+    SubscriptionID: string;
+    /** When the customer asked. Defaults to today. The RULES decide when coverage actually ends. */
+    RequestDate?: Date | string;
+    /** Free text, stored on the lifecycle event. */
+    Reason?: string;
+    /**
+     * Compute and return the decision WITHOUT writing anything — for a confirmation screen that
+     * shows "you will be refunded $X, coverage ends Y" before the user commits.
+     */
+    Preview?: boolean;
+}
+export interface CancelSubscriptionOutput {
+    Success: boolean;
+    Message?: string;
+    /** What the rules decided. Present even on a preview. */
+    Decision?: CancellationDecision;
+    /** The term that was (or would be) cancelled. */
+    SubscriptionTermID?: string;
+    /** The reversal order, when one was needed. Absent when nothing was refunded. */
+    ReversalOrderID?: string;
+    ReversalOrderNumber?: string;
+}
+export declare class CancelSubscriptionOperation extends BaseRemotableOperation<CancelSubscriptionInput, CancelSubscriptionOutput> {
+    OperationKey: string;
+    protected InternalExecute(input: CancelSubscriptionInput, provider: IMetadataProvider, user: UserInfo): Promise<CancelSubscriptionOutput>;
+    private loadSubscription;
+    private loadRules;
+    /**
+     * The term the request lands in, or — when the request falls outside every window (an early
+     * cancellation of a future term, or a late one after everything lapsed) — the latest term.
+     * Cancelling always has to act on SOMETHING for the reversal to point at.
+     */
+    private resolveTerm;
+    /**
+     * A reversal order carrying ONE line: the negative slice of the original purchase.
+     *
+     * It goes through the ordinary confirm path rather than writing journal entries directly, so the
+     * mirrored ledger, the GL account resolution and the all-or-none guarantee are the SAME code
+     * that booked the original. `ReversesOrderLineID` is what makes a negative quantity legal
+     * (OrderLineEntityServer validates exactly that).
+     */
+    private emitReversalOrder;
+    private loadOriginalLine;
+    private stampTerm;
+    private stampSubscription;
+    private logEvent;
+    /**
+     * Stored grant Status is a lie after cancel unless we revoke when access has already
+     * ended. Grace (AccessThroughDate still in the future) leaves the rows standing — the
+     * evaluator honours subscription.EndDate rather than the original ValidTo.
+     */
+    private syncGrantsOnCancel;
+    /** The base behaviour, or the type's registered subclass when it names one (D45). */
+    private behaviorFor;
+}
+/** Tree-shaking anchor — called from the server bootstrap so the registration is retained. */
+export declare function LoadCancelSubscriptionOperation(): void;
+//# sourceMappingURL=CancelSubscriptionOperation.d.ts.map

package/dist/CancelSubscriptionOperation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CancelSubscriptionOperation.d.ts","sourceRoot":"","sources":["../src/CancelSubscriptionOperation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,OAAO,EAEH,sBAAsB,EAGtB,iBAAiB,EAIjB,QAAQ,EACX,MAAM,sBAAsB,CAAC;AAW9B,OAAO,EAEH,KAAK,oBAAoB,EAE5B,MAAM,2BAA2B,CAAC;AASnC,MAAM,WAAW,uBAAuB;IACpC,cAAc,EAAE,MAAM,CAAC;IACvB,gGAAgG;IAChG,WAAW,CAAC,EAAE,IAAI,GAAG,MAAM,CAAC;IAC5B,gDAAgD;IAChD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,wBAAwB;IACrC,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,QAAQ,CAAC,EAAE,oBAAoB,CAAC;IAChC,iDAAiD;IACjD,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,iFAAiF;IACjF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAChC;AAgCD,qBACa,2BAA4B,SAAQ,sBAAsB,CACnE,uBAAuB,EACvB,wBAAwB,CAC3B;IACU,YAAY,SAA+B;cAElC,eAAe,CAC3B,KAAK,EAAE,uBAAuB,EAC9B,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,EAAE,QAAQ,GACf,OAAO,CAAC,wBAAwB,CAAC;YAuFtB,gBAAgB;YA6BhB,SAAS;IAavB;;;;OAIG;YACW,WAAW;IA6BzB;;;;;;;OAOG;YACW,iBAAiB;YAgEjB,gBAAgB;YAmBhB,SAAS;YAmBT,iBAAiB;YAwBjB,QAAQ;IA8BtB;;;;OAIG;YACW,kBAAkB;IAgBhC,qFAAqF;IACrF,OAAO,CAAC,WAAW;CAatB;AAED,8FAA8F;AAC9F,wBAAgB,+BAA+B,IAAI,IAAI,CAEtD"}