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

package/dist/Order.js

@@ -2,12 +2,14 @@ import { MessageType as proto_MessageType } from "./generated/MessageType";
 import { amountFromScaledValue } from "./Constants";
 import Message from "./Message";
 // An order a customer has placed: a message carrying a sales order payload.
-// deliveryAddressId is an id into the customer's address list, not an address; deliveryAddress is
-// a full address sent directly instead, and takes precedence over deliveryAddressId when both are
-// present. paymentReceived is set only by an operator of the business, never by this library.
+// The business completes an order (fulfilling or cancelling it) by deleting its message, so
+// isDeleted is true of a completed order. That message is still the whole order: status and what
+// the customer ordered are there to show, as for an open one. status says how far the business
+// got with it.
+// deliveryAddressId is an id into the customer's address list. deliveryAddress is a full address
+// sent directly, and takes precedence over deliveryAddressId when both are present.
 export default class Order extends Message {
-    // Only ProtoMap calls this: it is the one place that sees a total still multiplied by
-    // Constants.AMOUNT_FACTOR.
+    // For ProtoMap, which sees a total still multiplied by Constants.AMOUNT_FACTOR.
     static fromScaledValues(header, senderId, taskStatus, senderName, senderPhone, status, fulfillmentMode, shoppingList, scaledShoppingListTotal, shoppingListCount, deliveryAddressId, deliveryAddress, creationDate, note, scaledPaymentReceived) {
         return new Order(header, senderId, taskStatus, senderName, senderPhone, status, fulfillmentMode, shoppingList, amountFromScaledValue(scaledShoppingListTotal), shoppingListCount, deliveryAddressId, deliveryAddress, creationDate, note, scaledPaymentReceived === undefined ? null : amountFromScaledValue(scaledPaymentReceived));
     }
@@ -24,34 +26,35 @@ export default class Order extends Message {
         this._paymentReceived = _paymentReceived;
         this._creationDate = Number(creationDate);
     }
-    // How far the business has got with fulfilling this order, as opposed to taskStatus, which is
-    // how far it has got with reading the message
+    // How far the business has got with fulfilling this order. taskStatus is how far it has got with
+    // reading the message.
     get status() {
         return this._status;
     }
     get fulfillmentMode() {
         return this._fulfillmentMode;
     }
-    // What was ordered. A fulfilled order can have had its list cleared, in which case the totals
-    // below are all that is left of it.
+    // What was ordered. An order completed before the business kept the list with it (an older
+    // merchant app moved the list into a record of the sale, which a customer never sees) holds
+    // ShoppingList.EMPTY, which has no lines. The totals below are then all that is left.
     get shoppingList() {
         return this._shoppingList;
     }
-    // The authoritative total to display; survives the shopping list being cleared, unlike a total
-    // read off the list itself.
+    // The authoritative total to display. Unlike a total read off the list, it survives the order
+    // having no list.
     get shoppingListTotal() {
         return this._shoppingListTotal;
     }
     get shoppingListCount() {
         return this._shoppingListCount;
     }
-    // Names an address in the address list of the customer, and Constants.ENTITY_ID_NULL when the
-    // order has no delivery address - which is normal for one to be picked up
+    // Names an address in the customer's address list. Constants.ENTITY_ID_NULL when the order has no
+    // delivery address, as is normal for a pickup.
     get deliveryAddressId() {
         return this._deliveryAddressId;
     }
-    // A full address sent directly rather than by id, and null when none was. Takes precedence over
-    // deliveryAddressId for display when it is not null - see the comment on this class.
+    // A full address sent directly rather than by id. Null when none was. Takes precedence over
+    // deliveryAddressId when not null.
     get deliveryAddress() {
         return this._deliveryAddress;
     }
@@ -62,8 +65,8 @@ export default class Order extends Message {
     get note() {
         return this._note;
     }
-    // What the business has recorded as received against this order so far, and null when it has
-    // recorded nothing - only a business operator sets this, never this library.
+    // What the business has recorded as received against this order so far. Null when nothing is
+    // recorded. Only a business operator sets it.
     get paymentReceived() {
         return this._paymentReceived;
     }

package/dist/Package.js

@@ -1,6 +1,6 @@
 import Item from "./Item";
-// A package, or variant, of a product - a 500 gram bottle of mango pickle, for example - and the
-// thing a customer actually buys. Built complete, with photos and price already resolved, so everything here is readonly.
+// A package, or variant, of a product (a 500 gram bottle of mango pickle, say) and the thing a
+// customer buys. Built complete, with photos and price resolved, so everything here is readonly.
 export default class Package extends Item {
     constructor(header, name, description, productId, isDisabled, _isSoldLoose, _itemCode, _identifiers, _dimensions, _weight, _photos, _price) {
         super(header, name, description, productId, isDisabled);
@@ -37,15 +37,14 @@ export default class Package extends Item {
     get photos() {
         return this._photos;
     }
-    // What this package costs, with the taxes of its product included (Product.taxes); null when the
-    // business has not priced it, in which case it cannot be bought.
+    // What this package costs, with the taxes of its product included (Product.taxes). Null when the
+    // business has not priced it, so it cannot be bought.
     get price() {
         return this._price;
     }
-    // True when this package is enabled and has a price that is itself enabled. isDisabled is
-    // checked directly rather than trusted to have been filtered out: a product-level filter does
-    // not, by itself, guarantee that every package - or every price - of an otherwise visible
-    // product is itself enabled.
+    // True when this package is enabled and has an enabled price. Checked here because a
+    // product-level filter does not guarantee that every package, or every price, of an otherwise
+    // visible product is enabled.
     get isBuyable() {
         return !this.isDisabled && this._price !== null && !this._price.isDisabled;
     }

package/dist/PackageIdentifier.js

@@ -1,5 +1,5 @@
-// An identifier of a package - a GTIN, for example - and the kind of identifier it is. Java keys
-// these by string id, not ordinal, so map through PackageIdentifierType.proto's comments, never the enum ordinal.
+// An identifier of a package, such as a GTIN, and its kind. Java keys kinds by string id, so map
+// through the comments in PackageIdentifierType.proto, never the enum ordinal.
 export default class PackageIdentifier {
     constructor(_type, _value) {
         this._type = _type;

package/dist/PaymentMethodDetail.js

@@ -1,8 +1,8 @@
-// A payment method a business accepts, and what a customer needs in order to use it - the UPI id
-// of the business, for example.
+// A payment method a business accepts, and what a customer needs to use it (the UPI id of the
+// business, say).
 //
-// The data is null rather than empty when the business has given none, which is normal for a
-// method that needs nothing, such as cash.
+// The data is null, not empty, when the business has given none. That is normal for a method that
+// needs nothing, such as cash.
 export default class PaymentMethodDetail {
     constructor(_method, _data) {
         this._method = _method;

package/dist/Photo.js

@@ -1,9 +1,8 @@
-// A photo of a business, product or package: which one it belongs to, and where to fetch it from.
-// All that's exposed of an Attachment - nothing else on it is useful to a UI.
+// A photo of a business, product or package: its attachment type and where to fetch it from.
+// All that a UI needs of an Attachment.
 export default class Photo {
-    // The base url is the one in effect when this photo was built, not looked up at read time - a
-    // photo is rebuilt by the next sync rather than edited in place, so there is nothing to keep in
-    // sync with a later renewal.
+    // The base url is the one in effect when this photo was built. A photo is rebuilt by the next
+    // sync, not edited in place, so a later renewal needs no handling.
     constructor(_attachment, _attachmentBaseUrl) {
         this._attachment = _attachment;
         this._attachmentBaseUrl = _attachmentBaseUrl;
@@ -12,8 +11,8 @@ export default class Photo {
     get attachmentType() {
         return this._attachment.attachmentType;
     }
-    // Where to fetch this photo from, or null if there's nothing to fetch (deleted attachment, or the
-    // owning business's base url hadn't arrived when this photo was built). May be expired; cached
+    // Where to fetch this photo from. Null if there is nothing to fetch (deleted attachment, or the
+    // owning business's base url had not arrived when this photo was built). May be expired. Cached
     // once built.
     get url() {
         if (this._url !== null)

package/dist/Price.js

@@ -3,12 +3,11 @@ import Item from "./Item";
 // What one package costs: the regular price and the offer price. Exposed unscaled as numbers; they
 // travel multiplied by Constants.AMOUNT_FACTOR and stay well below 2^53, so nothing is lost.
 //
-// BOTH INCLUDE TAXES: the taxes of the product the package belongs to (Product.taxes) are in the
-// price, not added to it, so this is what a customer pays and what a catalog shows. A shopping
-// list stores a price without them, which is why a cart takes the taxes out of one (CartEditor).
+// BOTH INCLUDE TAXES: the taxes of the package's product (Product.taxes) are in the price, not
+// added to it, so this is what a customer pays and what a catalog shows. A shopping list stores a
+// price without them, so a cart takes the taxes out (CartEditor).
 export default class Price extends Item {
-    // Only ProtoMap calls this: it is the one place that sees prices still multiplied by
-    // Constants.AMOUNT_FACTOR.
+    // 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));
     }
@@ -34,8 +33,8 @@ export default class Price extends Item {
     get offerPrice() {
         return this._offerPrice;
     }
-    // What a customer actually pays, taxes included: the offer price when there is one, else the
-    // regular price. Computed here (not sent), matching the "on offer" definition from Price.proto.
+    // What a customer pays, taxes included: the offer price when there is one, else the regular
+    // price. Computed here, not sent, using the "on offer" definition from Price.proto.
     get finalPrice() {
         return this.isOnOffer ? this._offerPrice : this._regularPrice;
     }
@@ -46,8 +45,8 @@ export default class Price extends Item {
     get discount() {
         return this._regularPrice - this.finalPrice;
     }
-    // Discount as an exact, unrounded percentage of the regular price - rounding is left to the UI.
-    // Zero when the regular price is zero.
+    // Discount as an unrounded percentage of the regular price. Rounding is left to the UI. Zero
+    // when the regular price is zero.
     get discountPercent() {
         if (this._regularPrice <= 0)
             return 0;

package/dist/PriceList.js

@@ -1,5 +1,5 @@
 import Item from "./Item";
-// A named list of prices. A storefront sells from exactly one, so no package ever has two prices
-// to choose between; it's carried (not just a bare id) because a client naming a cart needs it.
+// A named list of prices. A storefront sells from one, so no package has two prices to choose
+// between. Carried as an object, not a bare id, because a client naming a cart needs it.
 export default class PriceList extends Item {
 }

package/dist/Product.js

@@ -1,6 +1,6 @@
 import Item from "./Item";
 // A product in the catalog: goods, a service, a raw material or a fixed asset. Built complete
-// (photos/packages resolved first) so everything here is readonly except category (via parentItemId).
+// (photos and packages resolved first), so everything here is readonly.
 export default class Product extends Item {
     constructor(header, name, description, productCategoryId, isDisabled, _productType, _brand, _isManufacturedByBusiness, _manufacturer, _manufacturerAddress, _taxes, _features, _isForOfflineSaleOnly, _photos, packages) {
         super(header, name, description, productCategoryId, isDisabled);
@@ -13,8 +13,7 @@ export default class Product extends Item {
         this._features = _features;
         this._isForOfflineSaleOnly = _isForOfflineSaleOnly;
         this._photos = _photos;
-        // A package that cannot be bought is of no use to anyone who has this product, so it is not
-        // kept - whoever builds a product, and whatever they hand it
+        // A package that cannot be bought is not kept, whoever builds the product and whatever they pass in
         this._packages = Object.freeze(packages.filter((pkg) => pkg.isBuyable));
     }
     // The category this product is in, or Constants.ENTITY_ID_NULL when it is in none
@@ -27,8 +26,8 @@ export default class Product extends Item {
     get brand() {
         return this._brand;
     }
-    // False only when the business says it does not make this product itself: what is sent is false,
-    // or nothing, which Product.proto says is true.
+    // False only when the business says it does not make this product itself. Absent on the wire
+    // means true (Product.proto).
     get isManufacturedByBusiness() {
         return this._isManufacturedByBusiness;
     }
@@ -38,8 +37,8 @@ export default class Product extends Item {
     get manufacturerAddress() {
         return this._manufacturerAddress;
     }
-    // The taxes INCLUDED in the price of every package of this product (Price) - not added to it.
-    // A UI shows a price as it is, and shows these only as what a bill's total includes.
+    // The taxes included in the price of every package of this product (see Price), not added to it.
+    // A UI shows a price as is, and shows these only as part of what a bill's total includes.
     get taxes() {
         return this._taxes;
     }
@@ -47,26 +46,23 @@ export default class Product extends Item {
     get features() {
         return this._features;
     }
-    // True when the business sells this product only offline: the server sends such a product like any
-    // other, flagged, and it is for this model to not offer it to a customer - see isBuyable. A catalog
-    // never holds one, so only a product that is built by hand, not one that is read from a catalog,
-    // can be seen to say so.
+    // True when the business sells this product only offline. The server sends such a product like
+    // any other, flagged, and this model must not offer it to a customer (see isBuyable). A catalog
+    // never holds one, so only a hand-built product can report true.
     get isForOfflineSaleOnly() {
         return this._isForOfflineSaleOnly;
     }
     get photos() {
         return this._photos;
     }
-    // Every buyable variant of this product, in the order they arrived - ordering them for display
-    // is a UI decision, see Catalog.comparePackages. A variant that cannot be bought is not here, and
-    // a product with none cannot be bought.
+    // Every buyable variant of this product, in the order they arrived. Ordering for display is a UI
+    // decision, see Catalog.comparePackages. A product with no buyable variant cannot be bought.
     get packages() {
         return this._packages;
     }
     // The cheapest final price across variants (what a listing shows as "from"), or null if there
-    // are no variants. Compares final price, not regular, since that's what a customer would
-    // actually pay. Every variant is taxed at this product's rates, so prices with taxes in them
-    // order the variants as prices without would.
+    // are no variants. Compares final price, since that is what a customer pays. Every variant is
+    // taxed at this product's rates, so prices with taxes order the variants as prices without would.
     get lowestPrice() {
         let result = null;
         for (const pkg of this._packages) {
@@ -85,11 +81,10 @@ export default class Product extends Item {
                 return true;
         return false;
     }
-    // True when this product itself is enabled, is not one that the business sells only offline, and
-    // it has at least one buyable variant, which is to say any variant, since it keeps no other. The
-    // server still filters out draft and non-public products before they ever arrive, but isDisabled
-    // can change after an item exists, and the server does not filter out what is sold only offline
-    // (it sends the flag), so both are checked here rather than trusted to have been filtered.
+    // True when this product is enabled, is not sold only offline, and has at least one variant (it
+    // keeps only buyable ones). The server filters out draft and non-public products before they
+    // arrive. isDisabled can change after an item exists and offline-only products are sent flagged,
+    // so both are checked here.
     get isBuyable() {
         return !this.isDisabled && !this._isForOfflineSaleOnly && this._packages.length > 0;
     }

package/dist/ProductCategory.js

@@ -1,8 +1,7 @@
 import Item from "./Item";
-// A category that groups products, real or the dummy one a Catalog builds to stand in for a
-// product with no category of its own. Products are set once by the Catalog that builds this, not
-// passed to the constructor - the full set isn't known until every product has been read. A
-// Catalog never builds one of these with an empty products array - see Catalog for why.
+// A category that groups products, real or the dummy one a Catalog builds for products with no
+// category. The Catalog sets the products once, after reading every product, so they are not
+// constructor arguments. A Catalog never builds one with an empty products array (see Catalog).
 export default class ProductCategory extends Item {
     constructor() {
         super(...arguments);

package/dist/Profile.js

@@ -6,8 +6,8 @@ export default class Profile {
         this._user = _user;
         this._businessMap = new Map();
         this._businessLinkMap = new Map();
-        // A business is listed only when its link is still held; a revoked link is removed by the
-        // sync but the business it named is not, so filtering here hides it without discarding it.
+        // A business is listed only when its link is still held. A revoked link is removed by the sync
+        // but its business is not, so filtering here hides the business without discarding it.
         const linkedBusinessIds = new Set();
         for (const businessLink of businessLinks)
             linkedBusinessIds.add(businessLink.businessId);
@@ -15,10 +15,10 @@ export default class Profile {
         this._businesses = Object.freeze(businesses.filter((business) => linkedBusinessIds.has(business.id)));
         for (const business of this._businesses)
             this._businessMap.set(business.id, business);
-        // One link per business is reached through, and it is the one that names this customer. A profile can hold more
-        // than one link to a business - one that is not this customer's is not what a customer writes to a business with, nor
-        // what a link token of theirs signs - so a link that does not name this customer does not take the place of one that
-        // does, whichever comes last. Where none names them (no user is held yet), the last is kept.
+        // One link is kept per business: the one that names this customer. A profile can hold several
+        // links to a business, and another user's link is not what this customer writes with. A link
+        // that does not name this customer never replaces one that does, whichever comes last. If none
+        // names them (no user is held yet), the last is kept.
         const isOwn = (link) => this._user !== null && link.linkedEntityId === this._user.id;
         for (const businessLink of this._businessLinks) {
             const held = this._businessLinkMap.get(businessLink.businessId);
@@ -45,14 +45,14 @@ export default class Profile {
     getBusiness(businessEntityId) {
         return this._businessMap.get(businessEntityId) ?? null;
     }
-    // BusinessLink.businessId is an entity id, matching Business.entity.id and not the url friendly
-    // businessId - this join spares a caller from having to remember which one it is holding
+    // Takes the entity id (BusinessLink.businessId, matching Business.entity.id), not the url friendly
+    // businessId. See getBusinessLinkFor.
     getBusinessLink(businessEntityId) {
         return this._businessLinkMap.get(businessEntityId) ?? null;
     }
-    // The same, by the url friendly business id a storefront is reached by - however it is written in the url, which
-    // the server finds a business by whatever its case, and which the one here is not to fail: a customer who has joined
-    // it is not to be taken for one who has not, and asked to join it again
+    // The same, by the url friendly business id a storefront is reached by, however it is written in
+    // the url. The server finds a business whatever the case, so this must too, or a customer who
+    // has joined would be asked to join again.
     getBusinessLinkFor(businessId) {
         const wanted = canonicalizeBusinessId(businessId);
         for (const business of this._businesses)
@@ -64,20 +64,19 @@ export default class Profile {
         return `Profile(profileId=${this._profileId}, user=${this._user?.formattedName ?? "none"}, businesses=${this._businesses.length})`;
     }
 }
-// A business id as the server makes it canonical (Java Business.canonicalizeBusinessId) to find one by it: with its spaces
-// normalized the way Java StringHelper.normalizeSpace does, and in lower case. A url is typed, and linked to, in any case, and a
-// business is the same business in all of them.
-// The spaces are not only those at either end, because a business id can hold some: Java makes one out of the display name when
-// none is given ("Warm Loaf_1a2b3c4d"), and takes whatever is typed, so a url that has two spaces where the id has one is still
-// that business. normalizeSpace is followed step for step, so as to give what Java gives for every string, quirks included: it
-// leaves a string alone that has no whitespace at either end and none twice in a row, and a non-breaking space is not whitespace
-// to it, so one between two words stays as it was, and is made a plain space only when something else of the string is normalized.
-// What Java then refuses, an id that is not between four and sixty-four characters long, is not refused here, since this is only
-// the comparison: the server answers a read of one with a NotFoundException, as it does for a business that does not exist.
+// A business id in the canonical form the server finds it by (Java Business.canonicalizeBusinessId):
+// spaces normalized as Java StringHelper.normalizeSpace does, then lower case. So a url typed in any
+// case or spacing names one business. Inner spaces count, as an id can hold some (Java builds one
+// from the display name, "Warm Loaf_1a2b3c4d", or takes what is typed).
+// normalizeSpace is followed step for step, quirks included: a string with no whitespace at either
+// end and none twice in a row is left alone, and a non-breaking space is not whitespace to it, so
+// one between words stays unless something else in the string is normalized.
+// Java refuses an id not four to sixty-four characters long. This is only a comparison and does
+// not. The server answers a read of such an id with NotFoundException, as for a missing business.
 export function canonicalizeBusinessId(businessId) {
     return normalizeSpace(businessId).toLowerCase();
 }
-// Java StringHelper.normalizeSpace, which answers null where this answers an empty string: a string of nothing but whitespace
+// Java StringHelper.normalizeSpace. Where Java answers null (a string of only whitespace), this answers an empty string.
 function normalizeSpace(input) {
     if (!needsNormalization(input))
         return input;
@@ -99,8 +98,8 @@ function normalizeSpace(input) {
     }
     if (isAtStart)
         return "";
-    // Java String.trim, which takes every character up to a space off either end, and not the trim of a script, which takes the
-    // spaces of Unicode. The space that stands for whitespace at the end goes with it: Java drops that one first, to the same end
+    // Java String.trim removes every character up to a space from either end, unlike a script's trim, which removes
+    // Unicode spaces. The space standing for trailing whitespace goes with it (Java drops that one first, same result)
     let first = 0;
     let last = result.length;
     while (first < last && result.charCodeAt(first) <= SPACE)
@@ -124,9 +123,9 @@ function needsNormalization(input) {
     }
     return false;
 }
-// Java Character.isWhitespace: the spaces of Unicode that do not hold a place (so not the no-break ones, U+00A0, U+2007 and
-// U+202F) and the controls that are spaces. Not what a regular expression's \s is, which has the no-break spaces and the
-// byte order mark, and has not the four separators U+001C to U+001F
+// Java Character.isWhitespace: the Unicode spaces that do not hold a place (not the no-break ones U+00A0, U+2007 and
+// U+202F) and the control characters that are spaces. A regular expression's \s differs: it includes the no-break
+// spaces and the byte order mark, and excludes U+001C to U+001F
 function isWhitespace(unit) {
     if (unit === SPACE)
         return true;

package/dist/ProtoMap.d.ts

@@ -41,7 +41,10 @@ export declare function getMessageId(message: proto_Message): bigint;
 export declare function partyPreferencesToBlob(partyPreferences: proto_Message, heldETag: bigint | null): StoredBlob;
 export declare function businessResponseFromBlobs(blobs: ReadonlyArray<StoredBlob>): proto_BusinessSyncOutResponse | null;
 export declare function profileResponseFromBlobs(blobs: ReadonlyArray<StoredBlob>): proto_ProfileSyncOutResponse | null;
+export declare function deletedBusinessResponseFromBlobs(blobs: ReadonlyArray<StoredBlob>): proto_BusinessSyncOutResponse | null;
+export declare function deletedProfileResponseFromBlobs(blobs: ReadonlyArray<StoredBlob>): proto_ProfileSyncOutResponse | null;
 export declare function orderMessagesFromBlobs(blobs: ReadonlyArray<StoredBlob>): ReadonlyArray<proto_Message>;
+export declare function deletedOrderMessagesFromBlobs(blobs: ReadonlyArray<StoredBlob>): ReadonlyArray<proto_Message>;
 export declare function partyPreferencesMessageFromMessages(messages: ReadonlyArray<proto_Message>): proto_Message | null;
 export declare function partyPreferencesMessageFromBlobs(blobs: ReadonlyArray<StoredBlob>): proto_Message | null;
 export declare function buildBusinessSyncOutRequest(business: string | bigint, syncInState: SyncState, attachmentBaseUrlExpiry: bigint): proto_BusinessSyncOutRequest;