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

package/dist/CartEditor.d.ts

@@ -3,7 +3,7 @@ import GeneralSettings from "./GeneralSettings";
 import Package from "./Package";
 import Product from "./Product";
 import ShoppingList, { ShoppingListItem } from "./ShoppingList";
-import Tax from "./Tax";
+import Tax, { TaxAmount } from "./Tax";
 export default class CartEditor {
     private readonly _catalog;
     private readonly _settings;
@@ -21,7 +21,7 @@ export default class CartEditor {
     get itemsTotal(): number;
     get savings(): number;
     get itemsTax(): number;
-    get itemsFinalTotal(): number;
+    taxes(withDeliveryCharge?: boolean): ReadonlyArray<TaxAmount>;
     get isDeliveryOffered(): boolean;
     get deliveryCharge(): number;
     get regularDeliveryCharge(): number;
@@ -31,10 +31,13 @@ export default class CartEditor {
     total(withDeliveryCharge?: boolean): number;
     build(withDeliveryCharge?: boolean): ShoppingList;
     private buildDeliveryChargeItem;
+    private get regularCharge();
     private getDeliveryCharge;
-    private static getTax;
     private getBuyablePackage;
-    private static readonly MAX_QUANTITY;
+    private tryKeep;
+    private static toWireQuantity;
+    private checkQuantity;
+    private static readonly MAX_WIRE_QUANTITY;
     private readonly _inventoryLocationId;
     private readonly _unavailableItems;
     private readonly _quantities;
@@ -47,13 +50,15 @@ export declare class CartLine {
     get package(): Package;
     get product(): Product | null;
     get quantity(): number;
+    get item(): ShoppingListItem;
+    get taxes(): ReadonlyArray<Tax>;
     get unitPrice(): number;
     get regularUnitPrice(): number;
     get isOnOffer(): boolean;
-    get taxes(): ReadonlyArray<Tax>;
     get amount(): number;
     get savings(): number;
     get totalTax(): number;
     get finalPrice(): number;
     toShoppingListItem(shoppingListOrder: number): ShoppingListItem;
+    private _item;
 }

package/dist/CartEditor.js

@@ -1,10 +1,11 @@
 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";
+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 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
@@ -15,6 +16,15 @@ import ShoppingList, { ShoppingListItem } from "./ShoppingList";
 // 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.
+//
+// EVERY PRICE HERE INCLUDES TAXES. The price of a package includes the taxes of its product, and
+// the delivery charge the taxes the settings name for it, so what a customer sees in the catalog
+// is what they pay, and every total below is a total with its taxes already in it. A shopping list
+// item is the other way round - it stores a price WITHOUT taxes and works the taxes out on top -
+// so building one takes the taxes out of the price, exactly as Java ShoppingListItem
+// .setDetailsFromTaxInclusivePrices does, and all the arithmetic is Java's to the unit (see
+// TaxHelper). The taxes are there to be shown as what the total includes (taxes), never to be
+// 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
@@ -24,9 +34,14 @@ class CartEditor {
     // 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.
+    // UI to tell the customer about. So is a line that cannot be bought as it is, which setQuantity
+    // would have refused, a cart that was read not being known to be one this class could have made:
+    // a quantity that is nothing or is not one, a fraction of what is not sold loose, more than the
+    // wire carries, or that comes to more than the protocol can at today's price, and any line past
+    // the most a cart holds (the first lines are kept, being in the order picked). 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.
     constructor(_catalog, _settings, cart) {
         this._catalog = _catalog;
         this._settings = _settings;
@@ -34,15 +49,14 @@ class CartEditor {
         // gives each line its shoppingListOrder
         this._quantities = new Map();
         this._inventoryLocationId = cart?.inventoryLocationId ?? 0;
+        // In the order of the list, which is the order the customer picked them in: the goods items are in it, and the items
+        // of the list are not, the server sending those by package id, so a cart that is 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);
     }
@@ -84,26 +98,17 @@ class CartEditor {
     // 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.
+    // carry. Whether a package is sold loose is the catalog's word, and not that of the Package
+    // passed in, which may be one held from before the catalog changed. 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 is nothing on the wire - a line of zero, which would cost 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.
@@ -118,52 +123,44 @@ 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 already taken off: the sum of the final
+    // prices of the lines, and what a customer sees to be the price of what is in 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, which is what a bill shows as savings: what they would
+    // have come to at their regular prices, less what they come to. 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 inside itemsTotal, all types together. They are part of the total and are not
+    // added to it: see taxes.
     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 taxes in the delivery charge are
+    // counted only when it is.
+    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.
     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 would cost, taxes included: 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.
     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.
     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
@@ -176,40 +173,45 @@ class CartEditor {
     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.
+    // Tax on the delivery charge: how much of deliveryCharge is the taxes GeneralSettings
+    // .deliveryChargeTaxes carries - which are the business's own and have nothing to do with a
+    // product's. Included in the charge, not added to it. Zero when delivery is free, there being
+    // nothing to tax.
     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, the way a cart
+    // page leaves it out and a checkout page puts it in - the same choice build() takes. It is the
+    // total of the list build() answers, so it is the total an order placed from it carries.
     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);
+        return this.build(withDeliveryCharge).totalAmount;
     }
     // The cart as a list to write: what Model.updateCartLocalOnly and Model.updateCart take, and
-    // what a later Model.createOrder turns into an order.
+    // what a later Model.createOrder turns into an order. It is also the list to SHOW - every price,
+    // total and tax a cart or a checkout page displays can be read off it, which is how a placed
+    // order is shown too.
+    //
+    // Each line is an item that stores the price without taxes, as Java does, and is flagged
+    // original: a customer's lines are created before the list is final (Java ShoppingList.addItem
+    // sets isOriginal to !isFinal(), and the order becomes final only after its items are in it), and
+    // an item that is not original is what the merchant app marks as added by the business.
     //
     // 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.
+    // is added even when the charge has been waived - at zero, with the regular charge (less its
+    // taxes, like every price in an item) as its priceDiscount - so a bill can show FREE with the
+    // original struck through, which is what Java ShoppingCartViewModel.setDeliveryCharge writes
+    // too.
     //
     // 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.
@@ -219,58 +221,128 @@ class CartEditor {
         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));
+        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 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;
+        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 of it, at what it costs now (charge - the regular charge, or
+    // zero once waived), 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.
+    // Null when the business does not deliver. The charge in the settings includes the settings'
+    // 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 rather than treating it as
+    // a 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 against a cart whose goods come to this much, which is the whole of the policy: 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 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 is not a caller's mistake to be refused but one for unavailableItems
+    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 it to that:
+    // NumberHelper.floatToInt), so the least there is is a thousandth. This is a quantity as that,
+    // and what is kept is the quantity the wire will hold, 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, which is what the wire will hold of it - or an
+    // InvalidArgumentException saying why the cart cannot have it: the package is not one the catalog
+    // sells, or it is not sold loose and the quantity is a fraction, or 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 is what the order will be priced from, and not off the caller's.
+    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`);
+        // This is the most of one package a cart can hold, and it is refused here rather than silently
+        // wrapping 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
+        // of them (Java ShoppingList.addItem counts it like any other, and a server refuses a list a
+        // line over). So where the business delivers, one place is kept for it: a cart that could be
+        // 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, which is done before the line is kept rather than when
+        // a list cannot be 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 is the most that a quantity multiplied by
+// Constants.QUANTITY_FACTOR can be
+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.
+// - 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 rather than kept.
+//
+// Everything here is read off item, the line as a shopping list would store it, so the cart page
+// shows exactly what the order will: 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;
@@ -282,43 +354,78 @@ export class CartLine {
     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 the way an order shows it. Its place in the list is not meaningful here.
+    get item() {
+        this._item ?? (this._item = this.toShoppingListItem(0));
+        return this._item;
+    }
+    // The taxes of the product this package belongs to, which its price includes. A rate that is not
+    // greater than zero is no tax, as in Java, and is not here.
+    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 the rounding of taxes that a price with
+    // taxes in it is subject to (a thousandth or two, which no one is shown). A buyable package
+    // always has a price, so this is never guessed.
     get unitPrice() {
-        return this._package.price?.finalPrice ?? 0;
+        return this.item.unitPriceWithTaxes;
     }
+    // The regular price of a unit, taxes included - what is 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, not this.
     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 what a customer pays for it: the price of a unit
+    // multiplied by 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.
+    // 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 is to carry them: only those with a rate, which is what
+// Java does with the taxes of a product (TaxHelper.getTaxCodesAndRates drops the rest).
+function includedTaxes(taxes) {
+    return Object.freeze(taxes.filter((tax) => Number.isFinite(tax.rate) && tax.rate > 0));
+}
+// The one place a price with taxes in it becomes a shopping list item, and so the one place
+// CartEditor takes a tax out of a price. The item stores the prices without them, as Java
+// ShoppingListItem.setDetailsFromTaxInclusivePrices does: the offer price and the regular price
+// each have their taxes removed, and what the offer takes off is the difference of the two - which
+// is not the difference of the prices with taxes. Everything but the price is as Java's
+// ProductSelectionCard leaves a new item: unit quantity or the customer's, no discount of its own,
+// no description (that is for lines that have no package), and no stock keeping or expiry, a
+// storefront being told neither. It is flagged original, for the reason build gives.
+//
+// A price is a whole number of thousandths and each tax is rounded, so some prices cannot be
+// reached: the item then has the price nearest to it (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);
+}

package/dist/Catalog.js

@@ -12,28 +12,33 @@ class Catalog {
         // A dummy category standing in for a product whose parentItemId is Constants.ENTITY_ID_NULL.
         // Its own id is that same ENTITY_ID_NULL, so getCategory(product.productCategoryId) resolves
         // it exactly like a real category - including being left out below, the same as any other
-        // category, when nothing buyable ends up in it.
+        // category, when no product ends up in it.
         const uncategorized = new ProductCategory(new EntityHeader(BigInt(proto_Constants.ENTITY_ID_NULL), 0n, 0n, 0n, 0n), "", null, BigInt(proto_Constants.ENTITY_ID_NULL), false);
-        this._products = Object.freeze([...products]);
-        // Only a buyable product - one a customer can actually order - counts towards a category. A
-        // product that cannot be bought right now keeps its place in Catalog.products and stays
-        // reachable by getProduct, but does not keep a category alive on its own.
+        // Only a buyable product - itself enabled, not one that the business sells only offline, with at
+        // least one buyable package, so one a customer can actually order - is part of a catalog. Any other is left out of products, getProduct and
+        // its categories, and so are its packages: they are not reachable by id either. This is
+        // enforced here, and not left to whoever builds the catalog to have filtered, so that no way
+        // of making one can expose a product that cannot be bought.
+        const buyableProducts = [];
         const productsByCategory = new Map();
-        for (const product of this._products) {
+        for (const product of products) {
+            if (!product.isBuyable)
+                continue;
+            buyableProducts.push(product);
             this._productMap.set(product.id, product);
-            if (product.isBuyable) {
-                const productsOfCategory = productsByCategory.get(product.productCategoryId);
-                if (productsOfCategory === undefined)
-                    productsByCategory.set(product.productCategoryId, [product]);
-                else
-                    productsOfCategory.push(product);
-            }
+            const productsOfCategory = productsByCategory.get(product.productCategoryId);
+            if (productsOfCategory === undefined)
+                productsByCategory.set(product.productCategoryId, [product]);
+            else
+                productsOfCategory.push(product);
             for (const pkg of product.packages)
                 this._packageMap.set(pkg.id, pkg);
         }
-        // A category with nothing a customer can order is left out rather than shown empty - there is
-        // no point showing it to a customer. Nothing here is special-cased for the dummy: it is left
-        // out exactly the same way when nothing buyable is uncategorized.
+        this._products = Object.freeze(buyableProducts);
+        // A category with nothing a customer can order, which is one that no product reached above, is
+        // left out rather than shown empty - there is no point showing it to a customer. Nothing here
+        // is special-cased for the dummy: it is left out exactly the same way when nothing buyable is
+        // uncategorized.
         const nonEmptyCategories = [];
         for (const category of [...categories, uncategorized]) {
             const categoryProducts = productsByCategory.get(category.id);
@@ -50,7 +55,8 @@ class Catalog {
     get categories() {
         return this._categories;
     }
-    // Every product of the business, whether or not it is in a category, in no particular order
+    // Every buyable product of the business - itself enabled, with at least one buyable package -
+    // whether or not it is in a category, in no particular order. A product that is not is not here.
     get products() {
         return this._products;
     }
@@ -69,11 +75,13 @@ class Catalog {
     getCategory(productCategoryId) {
         return this._categoryMap.get(productCategoryId) ?? null;
     }
+    // Null for an unknown id, and for a product that is not buyable, which this catalog does not hold
     getProduct(productId) {
         return this._productMap.get(productId) ?? null;
     }
     // Returns null for the four reserved package ids a shopping list uses for its charge and
-    // summary lines (see Ids.isReservedPackageId), and for a package whose product was deleted
+    // summary lines (see Ids.isReservedPackageId), and for a package whose product was deleted or is
+    // not buyable
     getPackage(packageId) {
         return this._packageMap.get(packageId) ?? null;
     }