@peabody-soft/mbs-model-ts 1.4.0 → 1.6.0

package/dist/CartEditor.js

@@ -1,53 +1,58 @@
 import { Constants as proto_Constants } from "./generated/Constants";
 import { FulfillmentMode as proto_FulfillmentMode } from "./generated/FulfillmentMode";
 import { ReservedPackage as proto_ReservedPackage } from "./generated/ReservedPackage";
-import { MERABILLS_ONLINE_PRICE_LIST_ID } from "./Constants";
+import { MERABILLS_ONLINE_PRICE_LIST_ID, amountFromScaledValue, amountToScaledValue, } from "./Constants";
 import { InvalidArgumentException } from "./Exceptions";
 import Ids from "./Ids";
-import ShoppingList, { ShoppingListItem } from "./ShoppingList";
-// Builds the cart a customer is filling, in the terms a UI has to hand: packages rather than
-// package ids, quantities rather than quantities multiplied by Constants.QUANTITY_FACTOR, and
-// prices taken off the catalog rather than worked out and passed in. Get one from
-// Business.createCartEditor, edit it, then hand build() to Model.updateCartLocalOnly.
+import ShoppingList, { ShoppingListItem, validatePricing } from "./ShoppingList";
+import TaxHelper from "./TaxHelper";
+// Builds the cart a customer is filling, in the terms a UI has to hand: packages, quantities as
+// the customer means them (not multiplied by Constants.QUANTITY_FACTOR), prices from the catalog.
+// Get one from Business.createCartEditor, edit it, then hand build() to Model.updateCartLocalOnly.
 //
-// Mutable, and deliberately the only mutable thing in this object model: it is a scratch copy of
-// the cart, not the cart. Nothing here writes anything - editing an editor changes no Business, no
-// store and nothing on the server until a built list is pushed. It is also a snapshot: it reads the
-// catalog, settings and cart once, at construction, so a sync arriving mid-edit does not move
-// prices under the customer. Make a fresh one when the Business republishes.
+// Mutable, and the only mutable thing in this object model. It is a scratch copy: editing it
+// changes no Business, store or server until a built list is handed to Model. It is also a
+// snapshot, read once at construction, so a sync mid-edit does not move prices under the customer.
+// Make a fresh one when the Business republishes.
+//
+// EVERY PRICE HERE INCLUDES TAXES: a package's includes its product's taxes, the delivery charge
+// the taxes the settings name for it, so a customer pays what the catalog shows. A shopping list
+// item stores a price WITHOUT taxes, so building one takes them out, as Java
+// ShoppingListItem.setDetailsFromTaxInclusivePrices does (to the unit, see TaxHelper). Taxes are
+// shown as what a total includes (taxes), never added to it.
 class CartEditor {
-    // Business.createCartEditor is how a UI gets one of these; this takes the three things it needs
-    // rather than the Business itself, so a caller can build a cart against a catalog and settings
-    // that are not the ones currently published.
+    // Business.createCartEditor is how a UI gets one. It takes the catalog, settings and cart, not
+    // the Business, so a caller can build a cart against ones that are not currently published.
     //
-    // Every line is priced off the catalog now, not off what the cart was holding: a cart lives
-    // until it is ordered, the merchant may have repriced in between, and what an order freezes is
-    // the price at the moment it is placed. Lines the catalog can no longer price - a package
-    // withdrawn, disabled, or left without a price - are dropped, and left in unavailableItems for a
-    // UI to tell the customer about. The charge lines of the list it started from (see
-    // ShoppingListItem.isReservedPackage) are dropped too, being this class's to work out rather
-    // than a customer's to carry: build() puts back whatever the settings now say.
+    // Every line is priced off the catalog, not off what the cart held: the merchant may have
+    // repriced since, and an order freezes the price when it is placed. A line goes to
+    // unavailableItems, for a UI to tell the customer about, when the catalog can no longer price it
+    // (package withdrawn, disabled or without a price) or setQuantity would refuse it (a cart that
+    // was read is not known to be one this class could have made): a zero or invalid quantity, a
+    // fraction of a package not sold loose, more than the wire or the protocol carries at today's
+    // price, or a line past the most a cart holds (the first lines are kept, in pick order).
+    // The charge lines of the starting list (see ShoppingListItem.isReservedPackage) are dropped, not
+    // listed, since build() puts back what the settings now say.
     constructor(_catalog, _settings, cart) {
         this._catalog = _catalog;
         this._settings = _settings;
-        // Insertion ordered, which is what keeps a cart in the order the customer filled it and what
-        // gives each line its shoppingListOrder
+        // Insertion ordered: keeps the cart in the order the customer filled it and gives each line its
+        // shoppingListOrder
         this._quantities = new Map();
         this._inventoryLocationId = cart?.inventoryLocationId ?? 0;
+        // goodsItems is in the order the customer picked. existingItems is not, the server sending it
+        // by package id, so a cart read back would reorder itself
         const unavailableItems = [];
-        for (const item of cart?.existingItems ?? []) {
+        for (const item of cart?.goodsItems ?? []) {
             if (item.isReservedPackage)
                 continue;
-            const buyable = this.getBuyablePackage(item.packageId);
-            if (buyable === null)
+            if (!this.tryKeep(item))
                 unavailableItems.push(item);
-            else
-                this._quantities.set(buyable.id, item.quantity);
         }
         this._unavailableItems = Object.freeze(unavailableItems);
     }
-    // What the customer has picked, in the order it was picked in, each line priced as it would be
-    // bought right now. Rebuilt on every read, so a line held across an edit is stale.
+    // What the customer has picked, in pick order, each line priced as it would be bought now.
+    // Rebuilt on every read, so a line held across an edit is stale.
     get lines() {
         const lines = [];
         for (const [packageId, quantity] of this._quantities) {
@@ -58,15 +63,15 @@ class CartEditor {
         }
         return Object.freeze(lines);
     }
-    // The lines of the cart this editor started from that its catalog can no longer price - see the
-    // note on the constructor. Empty for a cart built from nothing, and never added to by an edit.
+    // The lines of the starting cart that the catalog can no longer price (see the constructor).
+    // Empty for a cart built from nothing, and no edit adds to it.
     get unavailableItems() {
         return this._unavailableItems;
     }
     get isEmpty() {
         return this._quantities.size === 0;
     }
-    // How many lines the cart has, which is what a cart badge counts - not how many units are in it
+    // The number of lines, which is what a cart badge counts
     get lineCount() {
         return this._quantities.size;
     }
@@ -81,33 +86,24 @@ class CartEditor {
     getQuantity(item) {
         return this._quantities.get(item.id) ?? 0;
     }
-    // Sets how much of one package the cart holds; zero takes it out. A package a customer cannot
-    // buy - one disabled, or priced in no list this storefront sells from - is refused, as is a
-    // fractional quantity of a package that is not sold loose, and a quantity past what the wire can
-    // carry. Returns this, so edits chain.
+    // Sets how much of one package the cart holds; zero takes it out. Refuses a package a customer
+    // cannot buy (disabled, or priced in no list this storefront sells from), a fractional quantity
+    // of a package that is not sold loose, and a quantity past what the wire can carry. Sold loose is
+    // read from the catalog's package, since the Package passed in may predate a catalog change.
+    // Returns this, so edits chain.
     setQuantity(item, quantity) {
-        if (!Number.isFinite(quantity) || quantity < 0)
-            throw new InvalidArgumentException(`${quantity} is not a quantity`);
-        if (quantity === 0) {
+        const wireQuantity = CartEditor.toWireQuantity(quantity);
+        // Less than half a thousandth rounds to zero on the wire, a line that costs nothing, so it
+        // takes the line out as zero does
+        if (wireQuantity === 0) {
             this._quantities.delete(item.id);
             return this;
         }
-        if (this.getBuyablePackage(item.id) === null)
-            throw new InvalidArgumentException(`Package ${Ids.toStorageHexString(item.id)} cannot be bought from this catalog`);
-        if (!item.isSoldLoose && !Number.isInteger(quantity))
-            throw new InvalidArgumentException(`${item.name} is not sold loose, so it cannot be bought ${quantity} at a time`);
-        // A quantity travels as an int32 multiplied by Constants.QUANTITY_FACTOR, so this is the most
-        // of one package a cart can hold - and it is refused here rather than silently wrapping there.
-        if (quantity > CartEditor.MAX_QUANTITY)
-            throw new InvalidArgumentException(`${quantity} is more than the ${CartEditor.MAX_QUANTITY} the protocol can carry`);
-        if (!this._quantities.has(item.id) &&
-            this._quantities.size >= proto_Constants.SHOPPING_LIST_MAX_ITEMS)
-            throw new InvalidArgumentException(`A cart holds at most ${proto_Constants.SHOPPING_LIST_MAX_ITEMS} lines`);
-        this._quantities.set(item.id, quantity);
+        this._quantities.set(item.id, this.checkQuantity(item.id, quantity, wireQuantity));
         return this;
     }
-    // Adds to what the cart already holds of this package, which is what a quantity stepper does.
-    // A negative amount takes away, and never below nothing.
+    // Adds to what the cart holds of this package, as a quantity stepper does. A negative amount
+    // takes away, down to zero at the lowest.
     add(item, quantity = 1) {
         return this.setQuantity(item, Math.max(0, this.getQuantity(item) + quantity));
     }
@@ -118,207 +114,289 @@ class CartEditor {
         this._quantities.clear();
         return this;
     }
-    // What the packages cost before tax, offers already taken off
+    // What the packages come to, taxes included and offers taken off: the sum of the lines' final
+    // prices, which a customer sees as the price of the cart. Delivery is not in it.
     get itemsTotal() {
-        let result = 0;
-        for (const line of this.lines)
-            result += line.amount;
-        return result;
+        return ShoppingList.sumOfFinalPrices(this.lines.map((line) => line.item));
     }
-    // What the offers took off, which is what a bill shows as savings. Zero when nothing is on offer.
+    // What the offers took off the packages, shown on a bill as savings: the total at regular prices
+    // less the total. Zero when nothing is on offer. Taxes are included on both sides.
     get savings() {
-        let result = 0;
-        for (const line of this.lines)
-            result += line.savings;
-        return result;
+        return this.build().savings;
     }
+    // The taxes already inside itemsTotal, all types together. See taxes for the split by type.
     get itemsTax() {
-        let result = 0;
-        for (const line of this.lines)
-            result += line.totalTax;
-        return result;
+        return this.build().computedTotalTax;
     }
-    // The packages with their tax, and what the free delivery threshold is measured against - the
-    // same total Java ShoppingCartViewModel.calculateDeliveryCharge compares, less its delivery line
-    get itemsFinalTotal() {
-        let result = 0;
-        for (const line of this.lines)
-            result += line.finalPrice;
-        return result;
+    // The taxes the cart's total includes, one entry per TYPE of tax. A bill shows a line for each
+    // that is not zero. withDeliveryCharge is as for total: the delivery charge's taxes count only
+    // when it is true.
+    taxes(withDeliveryCharge = false) {
+        return this.build(withDeliveryCharge).computedTaxes;
     }
-    // True when this business delivers at all. False means no delivery charge exists to add, whatever
-    // build() is asked for, and a UI has no fulfillment choice to offer either.
+    // True when this business delivers. When false there is no delivery charge for build() to add,
+    // and no fulfillment choice for a UI to offer.
     get isDeliveryOffered() {
         return this._settings.fulfillmentModes.includes(proto_FulfillmentMode.DELIVERY);
     }
-    // What delivering this cart would cost before tax: the business's flat charge, or zero where it
-    // has been waived by the cart reaching freeDeliveryTotal, or where the business delivers free
-    // anyway. Always zero when the business does not deliver.
+    // What delivering this cart costs, taxes included: the business's flat charge, or zero when the
+    // cart has reached freeDeliveryTotal or the business delivers free. Zero when the business does
+    // not deliver.
     get deliveryCharge() {
-        return this.getDeliveryCharge(this.itemsFinalTotal);
+        return this.buildDeliveryChargeItem(this.getDeliveryCharge(this.itemsTotal), 0)?.finalPrice ?? 0;
     }
-    // What delivery costs before any waiver - the price a bill strikes through when it reads FREE.
-    // Zero where the business delivers free anyway, in which case there is nothing to strike through.
+    // What delivery costs before any waiver, which a bill strikes through when it reads FREE. Zero
+    // where the business delivers free, so there is nothing to strike through.
     get regularDeliveryCharge() {
-        if (!this.isDeliveryOffered)
-            return 0;
-        // Java clamps a negative charge to zero rather than treating it as a refund, and so does this
-        return Math.max(0, this._settings.deliveryCharge);
+        return this.buildDeliveryChargeItem(this.regularCharge, 0)?.finalPrice ?? 0;
     }
-    // True when delivering this cart costs nothing, whether because the business never charges or
-    // because this cart has reached the threshold
+    // True when delivering this cart costs nothing, because the business never charges or the cart
+    // has reached the threshold
     get isDeliveryFree() {
         return this.isDeliveryOffered && this.deliveryCharge === 0;
     }
-    // How much more the customer would have to add for delivery to stop being charged, which is the
-    // "add X more for free delivery" note. Zero once it is already free, and null when the business
-    // has set no threshold, so there is no amount that would ever make it free.
+    // How much more the customer must add for free delivery, for the "add X more for free delivery"
+    // note. Zero when delivery is already free. Null when the business does not deliver or has set no
+    // threshold, so no amount would make it free.
     get amountToFreeDelivery() {
         if (!this.isDeliveryOffered)
             return null;
-        if (this.regularDeliveryCharge === 0)
+        if (this.regularCharge === 0)
             return 0; // Already free, and free at any total
         const freeDeliveryTotal = this._settings.freeDeliveryTotal;
         if (freeDeliveryTotal <= 0)
             return null; // No threshold: adding more changes nothing
-        return Math.max(0, freeDeliveryTotal - this.itemsFinalTotal);
+        const remaining = amountToScaledValue(freeDeliveryTotal) - amountToScaledValue(this.itemsTotal);
+        return remaining > 0n ? amountFromScaledValue(remaining) : 0;
     }
-    // Tax on the delivery charge, at the rates GeneralSettings.deliveryChargeTaxes carries - which
-    // are the business's own and have nothing to do with a product's. Zero when delivery is free,
-    // there being nothing to tax.
+    // The tax inside deliveryCharge, from GeneralSettings.deliveryChargeTaxes. Those are the
+    // business's own, unrelated to a product's. Included in the charge, not added to it. Zero when
+    // delivery is free.
     get deliveryTax() {
-        return CartEditor.getTax(this.deliveryCharge, this._settings.deliveryChargeTaxes);
+        return this.buildDeliveryChargeItem(this.getDeliveryCharge(this.itemsTotal), 0)?.totalTax ?? 0;
     }
-    // What the cart comes to. Delivery is left out unless asked for, the way a cart page leaves it
-    // out and a checkout page puts it in - the same choice build() takes.
+    // What the cart comes to, taxes included. Delivery is left out unless asked for: a cart page
+    // leaves it out and a checkout page puts it in, as in build(). It is the total of the list
+    // build() answers, and so of an order placed from it.
     total(withDeliveryCharge = false) {
-        const total = this.itemsFinalTotal;
-        if (!withDeliveryCharge || this.isEmpty)
-            return total;
-        // Worked out from the total already in hand, rather than through the two getters above, each
-        // of which would add the lines up again
-        const charge = this.getDeliveryCharge(total);
-        return total + charge + CartEditor.getTax(charge, this._settings.deliveryChargeTaxes);
-    }
-    // The cart as a list to write: what Model.updateCartLocalOnly and Model.updateCart take, and
-    // what a later Model.createOrder turns into an order.
-    //
-    // withDeliveryCharge decides whether the delivery charge rides along as a line of its own,
-    // carrying ReservedPackage.DELIVERY_CHARGE_PACKAGE and flagged by
-    // ShoppingList.autoAddDeliveryCharge. A cart page has no fulfillment chosen yet and so leaves it
-    // out, which is the default; a checkout page that has settled on delivery asks for it. The line
-    // is added even when the charge has been waived - at zero, with the regular charge as its
-    // priceDiscount - so a bill can show FREE with the original struck through, which is what Java
-    // ShoppingCartViewModel.setDeliveryCharge writes too.
+        return this.build(withDeliveryCharge).totalAmount;
+    }
+    // The cart as a list, to write (Model.updateCartLocalOnly, Model.updateCart, Model.createOrder)
+    // and to SHOW: every price, total and tax a cart or checkout page displays can be read off it.
+    // Each line stores its price without taxes and is flagged original, as Java ShoppingList.addItem
+    // does before a list is final. The list comes back not final: Model.createOrder makes it so.
     //
-    // Nothing is added to an empty cart: a list holding a delivery charge and no goods is not an
-    // order, and Java removes exactly that line when it is all that is left.
-    // The list comes back not final. Making it final is placing an order, which is
-    // Model.createOrder's to do.
+    // withDeliveryCharge adds the delivery charge as a line (ReservedPackage.DELIVERY_CHARGE_PACKAGE)
+    // and sets ShoppingList.autoAddDeliveryCharge. A cart page leaves it out (the default), a checkout
+    // page that has settled on delivery asks for it. The line is added even when the charge is
+    // waived: at zero, with the regular charge (less its taxes) as its priceDiscount, so a bill can
+    // show FREE with the original struck through (Java ShoppingCartViewModel.setDeliveryCharge).
+    // An empty cart gets no line: a list holding only a delivery charge is not an order, and Java
+    // removes that line when it is all that is left.
     build(withDeliveryCharge = false) {
         const items = [];
         for (const line of this.lines)
             items.push(line.toShoppingListItem(items.length));
-        const isDeliveryCharged = withDeliveryCharge && items.length > 0 && this.isDeliveryOffered;
-        if (isDeliveryCharged)
-            items.push(this.buildDeliveryChargeItem(items.length));
-        // The total is written off the lines being sent, the way ShoppingList.proto defines it: the
-        // sum of their final prices, tax included. There is no list-wide discount - an offer comes off
-        // a line, and a storefront gives no other.
-        let totalAmountBeforeDiscount = 0;
-        for (const item of items)
-            totalAmountBeforeDiscount += item.finalPrice;
-        return new ShoppingList(false, isDeliveryCharged, false, this._inventoryLocationId, this._catalog.priceList?.id ?? MERABILLS_ONLINE_PRICE_LIST_ID, totalAmountBeforeDiscount, 0, items.length, 0, Object.freeze(items), Object.freeze([]));
-    }
-    // The delivery charge as a line: one of it, at whatever it costs after any waiver, with the
-    // waived amount as its price discount - the same shape as a package bought on offer, which is
-    // what lets a bill render it with no special case beyond its label.
-    buildDeliveryChargeItem(shoppingListOrder) {
-        const charge = this.deliveryCharge;
-        return new ShoppingListItem(Ids.buildId(proto_Constants.PACKAGE_ENTITY_TYPE_ID, BigInt(proto_ReservedPackage.DELIVERY_CHARGE_PACKAGE)), 1, charge, shoppingListOrder, false, false, false, this.regularDeliveryCharge - charge, 0, this._settings.deliveryChargeTaxes, 0, null);
-    }
-    // The charge against a cart that comes to this much, which is the whole of the policy. Takes
-    // the total rather than reading it, every caller here having worked it out already.
-    getDeliveryCharge(itemsFinalTotal) {
-        const charge = this.regularDeliveryCharge;
+        const delivery = withDeliveryCharge && items.length > 0
+            ? this.buildDeliveryChargeItem(this.getDeliveryCharge(ShoppingList.sumOfFinalPrices(items)), items.length)
+            : null;
+        if (delivery !== null)
+            items.push(delivery);
+        // The total is the sum of the final prices of the lines sent, tax included, as ShoppingList.proto
+        // defines it. There is no list-wide discount: an offer comes off a line, and a storefront gives
+        // no other.
+        return new ShoppingList(false, delivery !== null, false, this._inventoryLocationId, this._catalog.priceList?.id ?? MERABILLS_ONLINE_PRICE_LIST_ID, ShoppingList.sumOfFinalPrices(items), 0, items.length, 0, Object.freeze(items), Object.freeze([]));
+    }
+    // The delivery charge as a line: one unit at what it costs now (charge: the regular charge, or
+    // zero once waived), with the waived amount as its price discount. That is the shape of a package
+    // bought on offer, so a bill renders it with no special case beyond its label. Null when the
+    // business does not deliver. The settings' charge includes the delivery charge taxes, so they
+    // come out of it like those of any other price.
+    buildDeliveryChargeItem(charge, shoppingListOrder) {
+        if (!this.isDeliveryOffered)
+            return null;
+        return buildItem(Ids.buildId(proto_Constants.PACKAGE_ENTITY_TYPE_ID, BigInt(proto_ReservedPackage.DELIVERY_CHARGE_PACKAGE)), 1, charge, this.regularCharge, this._settings.deliveryChargeTaxes, shoppingListOrder);
+    }
+    // The charge before any waiver. Java clamps a negative charge to zero (no refund), and so does
+    // this. Zero when the business does not deliver.
+    get regularCharge() {
+        if (!this.isDeliveryOffered)
+            return 0;
+        return Math.max(0, this._settings.deliveryCharge);
+    }
+    // The charge for a cart whose goods come to itemsTotal: the regular charge, or nothing once the
+    // goods reach the threshold. Java ShoppingCartViewModel.calculateDeliveryCharge compares the same
+    // total, taxes included and the delivery line left out.
+    getDeliveryCharge(itemsTotal) {
+        const charge = this.regularCharge;
         if (charge === 0)
             return 0; // Free for everyone, or not delivered at all
         const freeDeliveryTotal = this._settings.freeDeliveryTotal;
         if (freeDeliveryTotal <= 0)
-            return charge; // Never free, whatever the cart totals
-        return itemsFinalTotal >= freeDeliveryTotal ? 0 : charge;
-    }
-    static getTax(amount, taxes) {
-        let result = 0;
-        for (const tax of taxes)
-            result += (amount * tax.rate) / 100;
-        return result;
+            return charge; // Never free, at any total
+        return itemsTotal >= freeDeliveryTotal ? 0 : charge;
     }
     // The package this id names, and null unless a customer could actually buy it right now
     getBuyablePackage(packageId) {
         const item = this._catalog.getPackage(packageId);
         return item !== null && item.isBuyable ? item : null;
     }
+    // Keeps a line of a cart that was read, as setQuantity would, and says whether it could. A line
+    // that cannot be kept goes to unavailableItems, as it is not the caller's mistake.
+    tryKeep(item) {
+        try {
+            const wireQuantity = CartEditor.toWireQuantity(item.quantity);
+            if (wireQuantity === 0)
+                return false; // A line of nothing is no line
+            this._quantities.set(item.packageId, this.checkQuantity(item.packageId, item.quantity, wireQuantity));
+            return true;
+        }
+        catch (error) {
+            if (error instanceof InvalidArgumentException)
+                return false;
+            throw error;
+        }
+    }
+    // A quantity travels as an int32 multiplied by Constants.QUANTITY_FACTOR (Java rounds to it with
+    // NumberHelper.floatToInt), so the least is a thousandth. This converts a quantity to that. What
+    // is kept is the quantity the wire holds, so getQuantity never reports one the order will not
+    // have.
+    static toWireQuantity(quantity) {
+        if (!Number.isFinite(quantity) || quantity < 0)
+            throw new InvalidArgumentException(`${quantity} is not a quantity`);
+        return Math.round(quantity * proto_Constants.QUANTITY_FACTOR);
+    }
+    // The quantity to keep for this much of a package, as the wire holds it, or an
+    // InvalidArgumentException saying why the cart cannot have it: the catalog does not sell the
+    // package, it is not sold loose and the quantity is a fraction, the quantity or what it comes to
+    // is more than the protocol carries, or the cart is full. All of it is read off the catalog's
+    // package, which the order is priced from.
+    checkQuantity(packageId, quantity, wireQuantity) {
+        const buyable = this.getBuyablePackage(packageId);
+        if (buyable === null)
+            throw new InvalidArgumentException(`Package ${Ids.toStorageHexString(packageId)} cannot be bought from this catalog`);
+        if (!buyable.isSoldLoose && !Number.isInteger(quantity))
+            throw new InvalidArgumentException(`${buyable.name} is not sold loose, so it cannot be bought ${quantity} at a time`);
+        // The most of one package a cart can hold. Refused here so it does not wrap silently on the wire
+        if (wireQuantity > CartEditor.MAX_WIRE_QUANTITY)
+            throw new InvalidArgumentException(`${quantity} is more than the ${CartEditor.MAX_WIRE_QUANTITY / proto_Constants.QUANTITY_FACTOR} the protocol can carry`);
+        // A list holds at most Constants.SHOPPING_LIST_MAX_ITEMS items, and the delivery charge is one
+        // (Java ShoppingList.addItem counts it like any other, and a server refuses a list one line
+        // over). Where the business delivers, one place is kept for it: a cart filled to the limit
+        // could not be ordered for delivery.
+        const maxLines = proto_Constants.SHOPPING_LIST_MAX_ITEMS - (this.isDeliveryOffered ? 1 : 0);
+        if (!this._quantities.has(packageId) && this._quantities.size >= maxLines)
+            throw new InvalidArgumentException(`A cart holds at most ${maxLines} lines`);
+        // Java refuses an amount past Transaction.MAX_AMOUNT (validateAmount) in the item that comes to
+        // it, and so does pricing an item here. It is priced before the line is kept, so the failure
+        // does not wait until a list is written.
+        const stored = wireQuantity / proto_Constants.QUANTITY_FACTOR;
+        try {
+            validatePricing(new CartLine(buyable, this._catalog.getProduct(buyable.productId), stored).item);
+        }
+        catch (error) {
+            if (error instanceof InvalidArgumentException)
+                throw new InvalidArgumentException(`${quantity} of ${buyable.name} comes to more than the protocol can carry (${error.message})`);
+            throw error;
+        }
+        return stored;
+    }
 }
-// What an int32 quantity multiplied by Constants.QUANTITY_FACTOR reaches
-CartEditor.MAX_QUANTITY = Math.floor(0x7fffffff / proto_Constants.QUANTITY_FACTOR);
+// The most an int32 holds, which bounds a quantity multiplied by Constants.QUANTITY_FACTOR
+CartEditor.MAX_WIRE_QUANTITY = 0x7fffffff;
 export default CartEditor;
-// One line of a cart being edited: the package, the product it is a variant of, and how much of it
-// - with the prices the catalog gives it now. A read-only view over what CartEditor holds, rebuilt
-// on every read of CartEditor.lines rather than kept.
+// One line of a cart being edited: the package, the product it is a variant of, and how much of it,
+// with the prices the catalog gives it now, taxes included. A read-only view over what CartEditor
+// holds, rebuilt on every read of CartEditor.lines.
+//
+// Everything is read off item, the line as a shopping list would store it, so the cart page shows
+// what the order will and no price is worked out twice.
 export class CartLine {
     constructor(_package, _product, _quantity) {
         this._package = _package;
         this._product = _product;
         this._quantity = _quantity;
+        this._item = null;
     }
     get package() {
         return this._package;
     }
-    // Null only for a package whose product is not in the catalog, which a buyable package's never is
+    // Null when the package's product is not in the catalog, which a buyable package never has
     get product() {
         return this._product;
     }
     get quantity() {
         return this._quantity;
     }
-    // What one unit costs: the offer price where the package is on offer, else the regular price.
-    // A buyable package always has a price, so this is never guessed.
+    // This line as a shopping list holds it: priced without taxes, with the taxes beside it. Show
+    // this to show the line as an order does. Its place in the list means nothing here.
+    get item() {
+        this._item ?? (this._item = this.toShoppingListItem(0));
+        return this._item;
+    }
+    // The taxes of the package's product, which its price includes. A rate not greater than zero is
+    // no tax, as in Java, and is left out.
+    get taxes() {
+        return includedTaxes(this._product?.taxes ?? []);
+    }
+    // What one unit costs, taxes included: the offer price where the package is on offer, else the
+    // regular price. This is the catalog's price to within tax rounding (a thousandth or two, which
+    // no one is shown). A buyable package always has a price, so nothing is guessed.
     get unitPrice() {
-        return this._package.price?.finalPrice ?? 0;
+        return this.item.unitPriceWithTaxes;
     }
+    // The regular price of a unit, taxes included. Struck through when it is on offer
     get regularUnitPrice() {
-        return this._package.price?.regularPrice ?? 0;
+        return this.item.regularUnitPriceWithTaxes;
     }
     get isOnOffer() {
         return this._package.price?.isOnOffer ?? false;
     }
-    // The taxes of the product this package belongs to, which are what the line is taxed at
-    get taxes() {
-        return this._product?.taxes ?? EMPTY_TAXES;
-    }
-    // What this line costs before tax
+    // What this line costs before its taxes: its tax base. A bill that shows prices with taxes shows
+    // finalPrice.
     get amount() {
-        return this.unitPrice * this._quantity;
+        return this.item.amount;
     }
-    // What the offer takes off this line
+    // What the offer takes off this line, taxes included
     get savings() {
-        return (this.regularUnitPrice - this.unitPrice) * this._quantity;
+        const saved = amountToScaledValue(this.item.finalPriceWithoutDiscounts) -
+            amountToScaledValue(this.item.finalPrice);
+        return saved > 0n ? amountFromScaledValue(saved) : 0;
     }
+    // The taxes inside finalPrice
     get totalTax() {
-        let result = 0;
-        for (const tax of this.taxes)
-            result += (this.amount * tax.rate) / 100;
-        return result;
+        return this.item.totalTax;
     }
-    // What this line adds to the cart: what it costs plus the tax on it
+    // What this line adds to the cart and a customer pays for it: the unit price times the quantity,
+    // with its taxes already in it
     get finalPrice() {
-        return this.amount + this.totalTax;
+        return this.item.finalPrice;
     }
-    // This line as the protocol carries it. Only CartEditor.build calls this, which is what assigns
-    // the order.
+    // This line as the protocol carries it. CartEditor.build calls it and assigns the order. Taxes
+    // come out of the price on the way (see buildItem).
     toShoppingListItem(shoppingListOrder) {
-        return new ShoppingListItem(this._package.id, this._quantity, this.unitPrice, shoppingListOrder, false, false, false, this.regularUnitPrice - this.unitPrice, 0, this.taxes, 0, null);
+        const price = this._package.price;
+        return buildItem(this._package.id, this._quantity, price?.finalPrice ?? 0, price?.regularPrice ?? 0, this._product?.taxes ?? [], shoppingListOrder);
     }
 }
-const EMPTY_TAXES = Object.freeze([]);
+// The taxes a price includes, as an item carries them: only those with a rate, as Java does with a
+// product's taxes (TaxHelper.getTaxCodesAndRates drops the rest).
+function includedTaxes(taxes) {
+    return Object.freeze(taxes.filter((tax) => Number.isFinite(tax.rate) && tax.rate > 0));
+}
+// Where a price with taxes in it becomes a shopping list item, and so where CartEditor takes a tax
+// out of a price, as Java ShoppingListItem.setDetailsFromTaxInclusivePrices does. The offer price
+// and the regular price each have their taxes removed, and the price discount is the difference of
+// those two, which is not the difference of the prices with taxes. The rest is as Java's
+// ProductSelectionCard leaves a new item: no discount of its own, no description (that is for
+// lines with no package), no stock keeping or expiry (a storefront is not told). It is flagged
+// original, as in build.
+// A price is a whole number of thousandths and each tax is rounded, so some prices cannot be
+// reached. The item then has the nearest price (TaxHelper.removeTaxes).
+function buildItem(packageId, quantity, offerPriceWithTaxes, regularPriceWithTaxes, taxes, shoppingListOrder) {
+    const included = includedTaxes(taxes);
+    const rates = TaxHelper.scaledRatesOf(included);
+    const offerPrice = TaxHelper.removeTaxes(amountToScaledValue(offerPriceWithTaxes), rates);
+    const regularPrice = TaxHelper.removeTaxes(amountToScaledValue(regularPriceWithTaxes), rates);
+    return new ShoppingListItem(packageId, quantity, amountFromScaledValue(offerPrice), shoppingListOrder, true, false, false, amountFromScaledValue(regularPrice > offerPrice ? regularPrice - offerPrice : 0n), 0, included, 0, null);
+}