@peabody-soft/mbs-model-ts 1.8.0 → 1.9.0

package/dist/Business.js

@@ -57,7 +57,8 @@ export default class Business extends Entity {
         this._orders = value;
     }
     // What this customer has picked and not yet ordered. Null until something is put in a cart, and
-    // null again once the cart is ordered. The cart message itself stays, with no list. Only the list
+    // null again once the cart is ordered. The cart message itself stays, with no list, or with a list
+    // that has no items (the merchant app stores one), which is null here too. Only the list
     // is exposed here. The fulfillment mode is chosen when an order is placed and is stored on the
     // Order (see defaultFulfillmentMode).
     get cart() {

package/dist/Catalog.js

@@ -75,9 +75,9 @@ class Catalog {
         return this._products;
     }
     // The id of the price list packages are priced from, DEFAULT_SALE_PRICE_LIST_ID until the sync
-    // layer sets it. Setting it prices every package from that list, or from its parent where the list
-    // has no price, and keeps the packages, products and categories that can then be bought. An id
-    // that names no list prices nothing, so the catalog holds nothing.
+    // layer sets it. Setting it prices every package from that list (see PriceList.getPrice), and keeps
+    // the packages, products and categories that can then be bought. An id that names no list prices
+    // nothing, so the catalog holds nothing.
     get currentSalePriceListId() {
         return this._currentSalePriceListId;
     }

package/dist/Constants.js

@@ -15,7 +15,8 @@ export function buildPriceListId(priceList) {
 export const DEFAULT_SALE_PRICE_LIST_ID = buildPriceListId(proto_Constants.DEFAULT_SALE_PRICE_LIST);
 // The list a storefront sells from. A business prices a package in several lists (over the counter,
 // on a marketplace), and a response can carry any of its public ones. ProtoMap.buildBusiness sets
-// the catalog to sell from this one, and a package with no price in it is priced from its parent.
+// the catalog to sell from this one, which can take the amounts of a package from its parent (see
+// PriceList.getPrice).
 export const MERABILLS_ONLINE_PRICE_LIST_ID = buildPriceListId(proto_Constants.MERABILLS_ONLINE_PRICE_LIST);
 // The largest amount the protocol can carry (Java Transaction.MAX_AMOUNT). Kept here because it does
 // not fit a protobuf enum value. It is 2^44 - 1, well below 2^53, so an amount is safe as a number.

package/dist/Entity.d.ts

@@ -10,6 +10,7 @@ export default abstract class Entity {
     get isDeleted(): boolean;
     get parent(): Entity | null;
     protected set parent(value: Entity | null);
+    protected get header(): EntityHeader;
     private static readonly UPDATE_TYPE_MASK;
     private readonly _header;
     private _parent;

package/dist/Entity.js

@@ -49,6 +49,10 @@ class Entity {
     set parent(value) {
         this._parent = value;
     }
+    // For a subclass that builds a variant of itself, which has the same id and update number
+    get header() {
+        return this._header;
+    }
 }
 Entity.UPDATE_TYPE_MASK = BigInt(proto_Constants.UPDATE_TYPE_MASK);
 export default Entity;

package/dist/Package.js

@@ -39,8 +39,9 @@ export default class Package extends Item {
         return this._photos;
     }
     // What this package costs, with the taxes of its product included (Product.taxes). It is the
-    // price in the catalog's sale price list, or in that list's parent. Null when neither has one, so
-    // the package cannot be bought.
+    // price in the catalog's sale price list, which can follow that list's parent (see
+    // PriceList.getPrice). It is disabled when the package is not in the list. Null when the list gives
+    // the package no price, so the package cannot be bought.
     get price() {
         return this._price;
     }

package/dist/Price.d.ts

@@ -4,10 +4,13 @@ export default class Price extends Item {
     private readonly _packageId;
     private readonly _regularPrice;
     private readonly _offerPrice;
-    static fromScaledValues(header: EntityHeader, name: string, description: string | null, priceListId: bigint, isDisabled: boolean, packageId: bigint, scaledRegularPrice: bigint, scaledOfferPrice: bigint): Price;
-    constructor(header: EntityHeader, name: string, description: string | null, priceListId: bigint, isDisabled: boolean, _packageId: bigint, _regularPrice: number, _offerPrice: number);
+    private readonly _isPlaceholder;
+    static fromScaledValues(header: EntityHeader, name: string, description: string | null, priceListId: bigint, isDisabled: boolean, packageId: bigint, scaledRegularPrice: bigint, scaledOfferPrice: bigint, isPlaceholder?: boolean): Price;
+    constructor(header: EntityHeader, name: string, description: string | null, priceListId: bigint, isDisabled: boolean, _packageId: bigint, _regularPrice: number, _offerPrice: number, _isPlaceholder?: boolean);
     get packageId(): bigint;
     get priceListId(): bigint;
+    get isPlaceholder(): boolean;
+    withIsDisabled(isDisabled: boolean): Price;
     get regularPrice(): number;
     get offerPrice(): number;
     get finalPrice(): number;

package/dist/Price.js

@@ -9,14 +9,15 @@ import Item from "./Item";
 // stores a price without taxes, so a cart takes them out (CartEditor).
 export default class Price extends Item {
     // For ProtoMap, which sees prices still multiplied by Constants.AMOUNT_FACTOR.
-    static fromScaledValues(header, name, description, priceListId, isDisabled, packageId, scaledRegularPrice, scaledOfferPrice) {
-        return new Price(header, name, description, priceListId, isDisabled, packageId, amountFromScaledValue(scaledRegularPrice), amountFromScaledValue(scaledOfferPrice));
+    static fromScaledValues(header, name, description, priceListId, isDisabled, packageId, scaledRegularPrice, scaledOfferPrice, isPlaceholder = false) {
+        return new Price(header, name, description, priceListId, isDisabled, packageId, amountFromScaledValue(scaledRegularPrice), amountFromScaledValue(scaledOfferPrice), isPlaceholder);
     }
-    constructor(header, name, description, priceListId, isDisabled, _packageId, _regularPrice, _offerPrice) {
+    constructor(header, name, description, priceListId, isDisabled, _packageId, _regularPrice, _offerPrice, _isPlaceholder = false) {
         super(header, name, description, priceListId, isDisabled);
         this._packageId = _packageId;
         this._regularPrice = _regularPrice;
         this._offerPrice = _offerPrice;
+        this._isPlaceholder = _isPlaceholder;
     }
     // The package this price applies to. Nothing nests on the wire, so this is how the catalog finds
     // the price of a package.
@@ -27,6 +28,20 @@ export default class Price extends Item {
     get priceListId() {
         return this.parentItemId;
     }
+    // True when this price has no amounts of its own: the package has the amounts of the price the
+    // list's parent has for it. regularPrice and offerPrice are a copy of those, which can be out of
+    // date, so they are never used. isDisabled says whether the package is in this list. See
+    // PriceList.getPrice, which resolves it. A UI never sees one, because Package.price is never a
+    // placeholder.
+    get isPlaceholder() {
+        return this._isPlaceholder;
+    }
+    // This price with another enabled state: the same entity, amounts and list. For PriceList.getPrice,
+    // which returns a price that is not the one the list holds when the package's state in the list
+    // differs from the state of the price that gives its amounts.
+    withIsDisabled(isDisabled) {
+        return new Price(this.header, this.name, this.description, this.priceListId, isDisabled, this._packageId, this._regularPrice, this._offerPrice, this._isPlaceholder);
+    }
     get regularPrice() {
         return this._regularPrice;
     }

package/dist/PriceList.js

@@ -1,15 +1,15 @@
 import Item from "./Item";
 // A named list of prices, at most one per package. A list can have a parent, named by its
-// parentItemId. A package with no price in the list is priced from the parent. Catalog sets the
-// prices and the parent, once every price list and price has been read.
+// parentItemId, and gets the amounts of some packages from it. See getPrice for the rules. Catalog
+// sets the prices and the parent, once every price list and price has been read.
 export default class PriceList extends Item {
     constructor() {
         super(...arguments);
         this._parentPriceList = null;
         this._prices = new Map();
     }
-    // The id of the list whose prices are used for the packages this list has no price for, or
-    // Constants.ENTITY_ID_NULL when this list has no parent
+    // The id of the list whose prices give the amounts of the packages this list takes them from it
+    // for, or Constants.ENTITY_ID_NULL when this list has no parent
     get parentPriceListId() {
         return this.parentItemId;
     }
@@ -28,10 +28,26 @@ export default class PriceList extends Item {
     set prices(value) {
         this._prices = value;
     }
-    // The price of a package: this list's own, else the parent's own, else null. Only the parent is
-    // consulted, not its parent. A price is returned even when disabled, so a package with a disabled
-    // price here is not priced from the parent.
+    // The price of a package in this list, or null when the list gives it none. Only the parent is
+    // consulted, not its parent.
+    // - A list follows its parent. A package the list has no price for has the parent's price, so its
+    //   amounts and whether it is enabled.
+    // - A price of this list replaces the parent's price, both amounts and enabled state.
+    // - A placeholder replaces only the enabled state. The amounts are the parent's. The placeholder
+    //   holds a copy of them that can be out of date, so it is never used.
+    // - The package is in the list when the price returned is enabled.
+    // - A placeholder gives no price when the parent has none.
+    // The price returned is the one that gives the amounts when it already has the right state, and a
+    // copy of it with the right state (withIsDisabled) otherwise.
     getPrice(packageId) {
-        return this._prices.get(packageId) ?? this._parentPriceList?._prices.get(packageId) ?? null;
+        const ownPrice = this._prices.get(packageId);
+        if (ownPrice !== undefined && !ownPrice.isPlaceholder)
+            return ownPrice;
+        const parentPrice = this._parentPriceList?._prices.get(packageId);
+        if (parentPrice === undefined)
+            return null;
+        if (ownPrice === undefined || ownPrice.isDisabled === parentPrice.isDisabled)
+            return parentPrice;
+        return parentPrice.withIsDisabled(ownPrice.isDisabled);
     }
 }

package/dist/ProtoMap.js

@@ -737,7 +737,7 @@ export function buildBusiness(response) {
         productCategories.push(productCategory);
     }
     // A storefront sells from the MeraBills Online list, picked by id because a response can carry
-    // other public lists. A package with no price in that list is priced from the list's parent.
+    // other public lists. That list can follow its parent (see PriceList.getPrice).
     const catalog = new Catalog(productCategories, products, packages, priceLists, prices);
     catalog.currentSalePriceListId = MERABILLS_ONLINE_PRICE_LIST_ID;
     updatableBusiness.catalog = catalog;
@@ -761,7 +761,8 @@ export function buildBusiness(response) {
     let defaultFulfillmentMode = proto_FulfillmentMode.DELIVERY;
     if (partyPreferences !== null && partyPreferences.payload.oneofKind === "partyPreferences") {
         // An emptied cart is a message whose payload has no shopping list, which is what placing an order
-        // leaves. The cart is null then, the same as for a customer who never had one.
+        // leaves. A list with no items is the same: the merchant app stores its cart whether or not it holds
+        // anything. The cart is null then, the same as for a customer who never had one.
         cart = cartShoppingListFromProto(partyPreferences.payload.partyPreferences, countryCode);
         // Taken as the message has it. DELIVERY comes only from the fallback above, even when the message
         // holds UNSPECIFIED_FULFILLMENT_MODE.
@@ -824,8 +825,9 @@ export function buildShoppingList(message, countryCode) {
 // fulfillment mode. An existing message is amended, since its payload can carry fields a storefront
 // cannot read, and dropping them would overwrite that data. Its id is kept, as the server holds the
 // preferences under it. The derived id is used only when there is nothing to amend.
-// A list with no items is pushed as no list, as Java serializeShoppingList returns null below one
-// item. An emptied cart and a cart never created look the same on the wire.
+// A list with no items is pushed as no list. The merchant app stores its cart with no items too, and
+// both read as no cart (cartShoppingListFromProto), so an emptied cart, a cart with no items and a cart
+// never created are one state to a storefront.
 // fulfillmentMode null keeps the existing value, the ordinary case: a storefront treats that field
 // as the merchant app's data and leaves it alone. createOrder sets it to the mode of the order that
 // emptied the cart.
@@ -925,11 +927,18 @@ function inPackageIdOrder(list) {
         deletedItems: [...list.deletedItems].sort(byPackageId),
     });
 }
-// The list inside a cart message, or absent for an emptied cart
+// The list inside a cart message, or absent for an emptied cart. A list with no items is absent too,
+// as the merchant app stores its cart whether or not it holds anything (see cartShoppingListFromProto)
 function getCartShoppingList(message) {
-    return message.payload.oneofKind === "partyPreferences"
-        ? message.payload.partyPreferences.shoppingList
-        : undefined;
+    if (message.payload.oneofKind !== "partyPreferences")
+        return undefined;
+    const shoppingList = message.payload.partyPreferences.shoppingList;
+    return shoppingList === undefined || holdsNothing(shoppingList) ? undefined : shoppingList;
+}
+// Whether a list on the wire has no items. The items are what is judged, not the counts, as in
+// pushedShoppingList
+function holdsNothing(shoppingList) {
+    return shoppingList.existingItems.length === 0 && shoppingList.deletedItems.length === 0;
 }
 // A shopping list to push, or absent when it holds nothing - see buildPartyPreferencesMessage.
 // Emptiness is judged by the items sent, not the counts, for the reason given at shoppingListToProto.
@@ -1226,7 +1235,7 @@ function priceListFromProto(priceListProto) {
 function priceFromProto(priceProto) {
     const item = getItem(priceProto.item);
     const entity = getEntity(item.entity);
-    return Price.fromScaledValues(toEntityHeader(entity), item.name, stringFromProto(item.description), item.parentItemId, item.isDisabled, priceProto.packageId, priceProto.regularPrice, priceProto.offerPrice);
+    return Price.fromScaledValues(toEntityHeader(entity), item.name, stringFromProto(item.description), item.parentItemId, item.isDisabled, priceProto.packageId, priceProto.regularPrice, priceProto.offerPrice, priceProto.isPlaceholder);
 }
 function packageFromProto(packageProto, photos) {
     const item = getItem(packageProto.item);
@@ -1246,12 +1255,16 @@ function orderFromProto(message, salesOrder, countryCode) {
     return Order.fromScaledValues(toEntityHeader(entity), message.senderId, message.status, stringFromProto(message.senderName), stringFromProto(message.senderPhone), salesOrder.status, salesOrder.fulfillmentMode, shoppingListFromProto(salesOrder.shoppingList, countryCode), salesOrder.shoppingListTotal, salesOrder.shoppingListCount, salesOrder.deliveryAddressId, salesOrder.deliveryAddress === undefined ? null : addressFromProto(salesOrder.deliveryAddress), salesOrder.creationDate, stringFromProto(salesOrder.note), salesOrder.paymentReceived);
 }
 // The one part of a cart message a customer is shown. Null when the cart holds nothing, so a cart
-// emptied by placing an order and one never created both give null. The rest of the message is set by
-// the server or read elsewhere: who sent it, how far the business has read it, and the fulfillment
-// mode, which buildBusiness reads as defaultFulfillmentMode.
+// emptied by placing an order, one never created, and a list with no items (the merchant app stores
+// its cart even when it is empty, with the properties of the list) all give null. The properties of
+// a list with no items are not read: a cart is built again from its items. The rest of the message
+// is set by the server or read elsewhere: who sent it, how far the business has read it, and the
+// fulfillment mode, which buildBusiness reads as defaultFulfillmentMode.
 function cartShoppingListFromProto(partyPreferences, countryCode) {
     const shoppingList = partyPreferences.shoppingList;
-    return shoppingList === undefined ? null : shoppingListFromProto(shoppingList, countryCode);
+    return shoppingList === undefined || holdsNothing(shoppingList)
+        ? null
+        : shoppingListFromProto(shoppingList, countryCode);
 }
 // #endregion
 // #region Photos

package/dist/ShoppingList.js

@@ -60,8 +60,8 @@ class ShoppingList {
     }
     // The id of the price list the cart is priced from. A storefront names
     // Constants.MERABILLS_ONLINE_PRICE_LIST_ID, the list in Catalog.priceList, for every line, including
-    // one priced from that list's parent. CartEditor falls back to that id when the catalog has no
-    // price list.
+    // one with the amounts of that list's parent. CartEditor falls back to that id when the catalog has
+    // no price list.
     get priceListId() {
         return this._priceListId;
     }

package/dist/generated/Price.d.ts

@@ -38,6 +38,15 @@ export interface Price {
      * @generated from protobuf field: int64 offerPrice = 4
      */
     offerPrice: bigint;
+    /**
+     * True when this price has no amounts of its own: the package has the amounts of the price that
+     * the parent of the price list has for it. regularPrice and offerPrice are a copy of those that
+     * can be out of date, so a client must not use them. Item.isDisabled says whether the package is
+     * in this price list. See PriceList.
+     *
+     * @generated from protobuf field: bool isPlaceholder = 5
+     */
+    isPlaceholder: boolean;
 }
 declare class Price$Type extends MessageType<Price> {
     constructor();

package/dist/generated/Price.js

@@ -10,7 +10,8 @@ class Price$Type extends MessageType {
             { no: 1, name: "item", kind: "message", T: () => Item },
             { no: 2, name: "packageId", kind: "scalar", T: 3 /*ScalarType.INT64*/, L: 0 /*LongType.BIGINT*/ },
             { no: 3, name: "regularPrice", kind: "scalar", T: 3 /*ScalarType.INT64*/, L: 0 /*LongType.BIGINT*/ },
-            { no: 4, name: "offerPrice", kind: "scalar", T: 3 /*ScalarType.INT64*/, L: 0 /*LongType.BIGINT*/ }
+            { no: 4, name: "offerPrice", kind: "scalar", T: 3 /*ScalarType.INT64*/, L: 0 /*LongType.BIGINT*/ },
+            { no: 5, name: "isPlaceholder", kind: "scalar", T: 8 /*ScalarType.BOOL*/ }
         ]);
     }
     create(value) {
@@ -18,6 +19,7 @@ class Price$Type extends MessageType {
         message.packageId = 0n;
         message.regularPrice = 0n;
         message.offerPrice = 0n;
+        message.isPlaceholder = false;
         if (value !== undefined)
             reflectionMergePartial(this, message, value);
         return message;
@@ -39,6 +41,9 @@ class Price$Type extends MessageType {
                 case /* int64 offerPrice */ 4:
                     message.offerPrice = reader.int64().toBigInt();
                     break;
+                case /* bool isPlaceholder */ 5:
+                    message.isPlaceholder = reader.bool();
+                    break;
                 default:
                     let u = options.readUnknownField;
                     if (u === "throw")
@@ -63,6 +68,9 @@ class Price$Type extends MessageType {
         /* int64 offerPrice = 4; */
         if (message.offerPrice !== 0n)
             writer.tag(4, WireType.Varint).int64(message.offerPrice);
+        /* bool isPlaceholder = 5; */
+        if (message.isPlaceholder !== false)
+            writer.tag(5, WireType.Varint).bool(message.isPlaceholder);
         let u = options.writeUnknownFields;
         if (u !== false)
             (u == true ? UnknownFieldHandler.onWrite : u)(this.typeName, message, writer);

package/dist/generated/PriceList.d.ts

@@ -7,8 +7,18 @@ import { MessageType } from "@protobuf-ts/runtime";
 import { Item } from "./Item";
 /**
  * A named list of prices. Item.parentItemId is the id of its parent price list, or 0 when it has
- * none. A package that has no price in a list is priced from the parent list. Contains
- * nothing - its prices are the Price entities whose Item.parentItemId is this price list's id.
+ * none. Contains nothing - its prices are the Price entities whose Item.parentItemId is this price
+ * list's id.
+ *
+ * A list with a parent follows it. Only the parent is consulted, never its parent.
+ * - A package with no price in the list has the parent's price: its amounts, and it is in the list
+ *   when that price is enabled.
+ * - A price of the list replaces the parent's price, both the amounts and whether it is enabled.
+ * - A placeholder (Price.isPlaceholder) replaces only whether the package is enabled. The amounts
+ *   are the parent's price: the placeholder holds a copy that can be out of date, so a client must
+ *   not use it.
+ * - A placeholder is no price at all when the parent has no price for the package.
+ *
  * Excluded: isPurchasePriceList - a purchase price list is never sent, so the flag would always be
  * false.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peabody-soft/mbs-model-ts",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "MeraBills storefront client-side model (TypeScript)",
   "author": "Peabody Soft",
   "license": "AGPL-3.0-or-later",
@@ -49,7 +49,7 @@
     "typescript": "^7.0.2"
   },
   "dependencies": {
-    "@peabody-soft/mbs-protos": "^1.12.1",
+    "@peabody-soft/mbs-protos": "^1.13.0",
     "@protobuf-ts/runtime": "^2.11.1"
   }
 }