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

package/dist/Catalog.js

@@ -1,24 +1,22 @@
 import { Constants as proto_Constants } from "./generated/Constants";
 import { EntityHeader } from "./Entity";
 import ProductCategory from "./ProductCategory";
-// The catalog of a business: its categories, and every product in it. Not an entity and not on
-// the wire - the sync layer rebuilds this hierarchy from the flat item entities of a sync response.
+// The catalog of a business: its categories and the products in them. Not an entity and not on the
+// wire. The sync layer rebuilds it from the flat item entities of a sync response.
 class Catalog {
     constructor(categories, products, _priceList) {
         this._priceList = _priceList;
         this._categoryMap = new Map();
         this._productMap = new Map();
         this._packageMap = new Map();
-        // 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 no product ends up in it.
+        // A dummy category for products whose parentItemId is Constants.ENTITY_ID_NULL. Its id is also
+        // ENTITY_ID_NULL, so getCategory(product.productCategoryId) resolves it like a real category.
+        // It is left out below like any other category when it has no products.
         const uncategorized = new ProductCategory(new EntityHeader(BigInt(proto_Constants.ENTITY_ID_NULL), 0n, 0n, 0n, 0n), "", null, BigInt(proto_Constants.ENTITY_ID_NULL), false);
-        // 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.
+        // Only a buyable product is part of a catalog: enabled, not sold only offline, with at least one
+        // buyable package. Any other is left out of products, getProduct and its categories, and its
+        // packages are unreachable by id. Enforced here so no builder can expose a product that cannot
+        // be bought.
         const buyableProducts = [];
         const productsByCategory = new Map();
         for (const product of products) {
@@ -35,10 +33,8 @@ class Catalog {
                 this._packageMap.set(pkg.id, pkg);
         }
         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.
+        // A category that no buyable product reached is left out rather than shown empty. This covers
+        // the dummy too.
         const nonEmptyCategories = [];
         for (const category of [...categories, uncategorized]) {
             const categoryProducts = productsByCategory.get(category.id);
@@ -55,14 +51,13 @@ class Catalog {
     get categories() {
         return this._categories;
     }
-    // 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.
+    // Every buyable product of the business, in a category or not, in no particular order
     get products() {
         return this._products;
     }
-    // The one price list a storefront sells from - MeraBills Online - and null until it arrives.
-    // Every price in this catalog belongs to it; a price in any other list is not sold here and is
-    // left out. A shopping list names this list, or falls back to its id when it has none set.
+    // The one price list a storefront sells from (MeraBills Online). Null until it arrives. Every
+    // price in this catalog belongs to it, and prices in other lists are left out. A shopping list
+    // names this list, or falls back to its id when it has none set.
     get priceList() {
         return this._priceList;
     }
@@ -79,14 +74,13 @@ class Catalog {
     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 or is
-    // not buyable
+    // 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 or is not buyable
     getPackage(packageId) {
         return this._packageMap.get(packageId) ?? null;
     }
-    // Display comparator for packages, matching the merchant app's PackageComparator (minus clauses
-    // a storefront can never exercise: disabled packages and the purchase price list, neither sent)
+    // Display comparator for packages, matching the merchant app's PackageComparator minus the
+    // clauses a storefront cannot exercise (disabled packages and the purchase price list, neither sent)
     static comparePackages(left, right) {
         const byName = Catalog.compareNames(left.name, right.name);
         if (byName !== 0)

package/dist/Constants.js

@@ -1,22 +1,22 @@
 import { Constants as proto_Constants } from "./generated/Constants";
 import Ids from "./Ids";
 // The protocol's limits and scaling factors, and the wire-to-UI value conversions.
-// Limits are re-exported rather than redeclared, so a Java constant has only one place to be wrong.
+// Limits are re-exported so a Java constant has only one place to be wrong.
 export { Constants } from "./generated/Constants";
 // The id of a built-in price list, from the low part Constants carries for it:
 // DEFAULT_SALE_PRICE_LIST, DEFAULT_PURCHASE_PRICE_LIST, MERABILLS_ONLINE_PRICE_LIST,
 // AMAZON_SELLER_PRICE_LIST, FACEBOOK_MARKETPLACE_PRICE_LIST or WHATSAPP_BUSINESS_PRICE_LIST. These
-// are the six ids of Java PriceListIds, built the way it builds them: the low part is a constant
-// of the protocol, the id is not, 64 bits not fitting a protobuf enum value.
+// are the six ids of Java PriceListIds, built the same way. Only the low part is a protocol
+// constant, since a 64-bit id does not fit a protobuf enum value.
 export function buildPriceListId(priceList) {
     return Ids.buildId(proto_Constants.PRICE_LIST_ENTITY_TYPE_ID, BigInt(priceList));
 }
-// The only price list this library reads. A business prices the same package in several lists -
-// what it sells at over the counter, what a marketplace it also sells on charges - and only this
-// one is its storefront's. A price in any other list is passed over; see ProtoMap.buildBusiness.
+// The only price list this library reads. A business prices a package in several lists (over the
+// counter, on a marketplace), and only this one is the storefront's. Prices in other lists are
+// skipped, see ProtoMap.buildBusiness.
 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 since it doesn't fit
-// a protobuf enum value. Unscaled it's well below 2^53, so an amount is always safe as a number.
+// The largest amount the protocol can carry (Java Transaction.MAX_AMOUNT). Kept here because it does
+// not fit a protobuf enum value. Unscaled it is well below 2^53, so an amount is safe as a number.
 export const MAX_SCALED_AMOUNT = 17592186044415n;
 // An amount, price or discount travels multiplied by Constants.AMOUNT_FACTOR, bounded by
 // MAX_SCALED_AMOUNT, so it's safe as a number even though it arrives as an int64.
@@ -33,8 +33,8 @@ export function quantityFromScaledValue(scaledQuantity) {
 export function quantityToScaledValue(quantity) {
     return Math.round(quantity * proto_Constants.QUANTITY_FACTOR);
 }
-// A tax rate travels multiplied by Constants.TAX_RATE_FACTOR, so 18% arrives as 1800. What comes
-// back is a percentage and not a fraction: 18, not 0.18.
+// A tax rate travels multiplied by Constants.TAX_RATE_FACTOR, so 18% arrives as 1800. The result is
+// a percentage (18, not 0.18).
 export function taxRateFromScaledValue(scaledTaxRate) {
     return scaledTaxRate / (proto_Constants.TAX_RATE_FACTOR / 100);
 }

package/dist/ContainerNames.js

@@ -1,21 +1,20 @@
-// What each container of the local store is called: a business container prefixes Business.businessId,
-// a profile container prefixes the subject id. The prefix keeps the two id spaces from ever colliding.
+// Names of the local store's containers. A business container prefixes Business.businessId, a
+// profile container the subject id. The prefixes keep the two id spaces from colliding.
 // One business, holding that business and everything in its business database
 export function forBusiness(nameSuffix) {
     return `${VERSION_PREFIX}${BUSINESS_PREFIX}${nameSuffix}`;
 }
-// One signed in subject, holding their profile database and the tokens that sign their requests.
-// Several can coexist so signing back in after a sign-out is incremental rather than a fresh download.
+// One signed in subject: their profile database and the tokens that sign their requests. Several
+// can coexist, so signing back in after a sign-out is incremental.
 export function forProfile(nameSuffix) {
     return `${VERSION_PREFIX}${PROFILE_PREFIX}${nameSuffix}`;
 }
-// Every name carries the layout version of what is inside it, so that a change to how this library
-// stores a container does not have to be migrated: the new version simply reads and writes names
-// nothing has written before, and what the old one left behind is inert until it is deleted.
-// Bump this whenever a stored blob stops meaning what it used to - a caller cannot be relied on to
-// clear a store it did not know had changed, and a half-understood container is worse than no cache.
+// Every name carries the layout version of its contents, so a change in how a container is stored
+// needs no migration: the new version uses names nothing has written, and the old containers stay
+// inert until deleted. Bump it whenever a stored blob changes meaning, since callers cannot be
+// relied on to clear a store and a half-understood container is worse than no cache.
 const VERSION_PREFIX = "V1.";
-// Neither id space is this library's to constrain, so a subject id that happened to equal a business
-// id would otherwise put a profile and a catalog in one container
+// Neither id space is this library's to constrain, so without a prefix a subject id equal to a
+// business id would put a profile and a catalog in one container
 const BUSINESS_PREFIX = "b.";
 const PROFILE_PREFIX = "p.";

package/dist/Entity.js

@@ -1,8 +1,8 @@
 import { Constants as proto_Constants } from "./generated/Constants";
 import Ids from "./Ids";
-// Something the protocol syncs one at a time: an id, create/update times, an update number, and
-// the database it was last updated in. Rebuilt from the wire rather than edited in place, so the
-// only mutable field is parent, set once containment is rebuilt after a sync (nothing nests on the wire).
+// Something the protocol syncs one at a time: an id, create and update times, an update number, and
+// the database it was last updated in. Rebuilt from the wire, never edited in place. The only
+// mutable field is parent, set once containment is rebuilt after a sync (nothing nests on the wire).
 class Entity {
     constructor(header) {
         this._parent = null;
@@ -17,12 +17,13 @@ class Entity {
     get updatedAt() {
         return new Date(Number(this._header.updatedAt));
     }
-    // Monotonically increasing, and only comparable within the same entity type and database. Basis of a sync cursor.
+    // Increases monotonically, comparable only within one entity type and database. Basis of a sync cursor.
     get updateNumber() {
         return this._header.updateNumber;
     }
-    // The database this entity was last updated in (Constants.MASTER_DB_ID = the server); sync out uses it
-    // to avoid echoing a store's own changes back. Business entities only - always ENTITY_ID_NULL on profile entities.
+    // The database this entity was last updated in (Constants.MASTER_DB_ID is the server). Sync out
+    // uses it to avoid echoing a store's own changes back. Business entities only; always
+    // ENTITY_ID_NULL on profile entities.
     get updateInfo() {
         return this._header.updateInfo;
     }
@@ -34,7 +35,8 @@ class Entity {
     get updateType() {
         return Number(this._header.updateNumber & Entity.UPDATE_TYPE_MASK);
     }
-    // A deleted entity is a tombstone: only the header fields are meaningful. A UI never reaches one.
+    // A deleted entity is a tombstone: it carries what the entity was when deleted. A UI never reaches
+    // one, except an order whose message is deleted, which is an order the business has completed.
     get isDeleted() {
         return this.updateType === proto_Constants.UPDATE_TYPE_DELETED;
     }
@@ -49,8 +51,8 @@ class Entity {
 }
 Entity.UPDATE_TYPE_MASK = BigInt(proto_Constants.UPDATE_TYPE_MASK);
 export default Entity;
-// The fields of the Entity message every entity carries, passed as one value since they're all
-// bigint and would otherwise transpose silently at a call site (the protocol has moved one before).
+// The fields of the Entity message every entity carries. Passed as one value because they are all
+// bigint and could be transposed silently at a call site.
 export class EntityHeader {
     constructor(id, createdAt, updatedAt, updateNumber, updateInfo) {
         this.id = id;

package/dist/Enums.js

@@ -1,5 +1,5 @@
-// Every enum of the protocol, re-exported under its own name so their Java-defined numeric ids
-// have only one place to be wrong, and this file records which enums are part of the library's surface.
+// Every enum of the protocol, re-exported so their Java-defined numeric ids have only one place to
+// be wrong. The list also records which enums are part of the library's surface.
 // TaxType is the exception: the protocol does not carry it, so it is defined in TaxType.ts.
 export { AddressType } from "./generated/AddressType";
 export { AttachmentType } from "./generated/AttachmentType";

package/dist/Exceptions.js

@@ -1,5 +1,5 @@
-// The two failures this library raises; both are programming errors, not conditions a UI recovers
-// from (a sync failure surfaces as a rejected promise instead).
+// The two failures this library raises. Both are programming errors that a UI does not recover
+// from. A sync failure surfaces as a rejected promise.
 // A caller passed something this library cannot work with
 export class InvalidArgumentException extends Error {
 }

package/dist/GeneralSettings.js

@@ -3,10 +3,10 @@ import { amountFromScaledValue } from "./Constants";
 import WorkingDays from "./WorkingDays";
 // The publicly visible settings of a business: tagline, contact info, location, fulfillment,
 // payment and delivery options, and how its online store is presented.
-// Not an entity - it's the value unwrapped from the one public Configuration a storefront is sent; merchant-only fields are excluded.
+// Not an entity: it is unwrapped from the one public Configuration a storefront is sent, so
+// merchant-only fields are absent.
 class GeneralSettings {
-    // Only ProtoMap calls this: it is the one place that sees amounts still multiplied by
-    // Constants.AMOUNT_FACTOR.
+    // For ProtoMap, which sees amounts still multiplied by Constants.AMOUNT_FACTOR.
     static fromScaledValues(paymentMethodDetails, customerServicePhone, isWhatsAppSupported, isSmsSupported, businessAddresses, businessIdentifiers, fulfillmentModes, scaledDeliveryCharge, deliveryChargeTaxes, scaledFreeDeliveryTotal, deliveryRadiusKilometres, storeTagline, workingDays, primaryStoreLocation, googleBusinessCategoryId, googleBusinessCategoryName, onlineStoreThemeId, onlineShoppingEnabled) {
         return new GeneralSettings(paymentMethodDetails, customerServicePhone, isWhatsAppSupported, isSmsSupported, businessAddresses, businessIdentifiers, fulfillmentModes, amountFromScaledValue(scaledDeliveryCharge), deliveryChargeTaxes, amountFromScaledValue(scaledFreeDeliveryTotal), deliveryRadiusKilometres, storeTagline, workingDays, primaryStoreLocation, googleBusinessCategoryId, googleBusinessCategoryName, onlineStoreThemeId, onlineShoppingEnabled);
     }
@@ -53,18 +53,18 @@ class GeneralSettings {
     get fulfillmentModes() {
         return this._fulfillmentModes;
     }
-    // What delivery costs, INCLUDING the taxes in deliveryChargeTaxes, as the price of a package
-    // includes the taxes of its product. CartEditor takes them out when it puts the charge in a list.
+    // What delivery costs, including the taxes in deliveryChargeTaxes, as a package price includes
+    // its product's taxes. CartEditor takes them out when it puts the charge in a list.
     get deliveryCharge() {
         return this._deliveryCharge;
     }
-    // The taxes included in the delivery charge, which are the business's own and not a product's -
-    // at most Constants.MAX_TAXES of them. Empty means the charge includes no tax.
+    // The taxes included in the delivery charge. They are the business's own, at most
+    // Constants.MAX_TAXES. Empty means the charge includes no tax.
     get deliveryChargeTaxes() {
         return this._deliveryChargeTaxes;
     }
-    // Order total at or above which delivery is free, measured on the goods with their taxes in
-    // them and without the delivery charge. Zero means never free, not always free.
+    // Order total at or above which delivery is free. Measured on the goods including taxes, without
+    // the delivery charge. Zero means delivery is never free.
     get freeDeliveryTotal() {
         return this._freeDeliveryTotal;
     }
@@ -75,36 +75,37 @@ class GeneralSettings {
     get storeTagline() {
         return this._storeTagline;
     }
-    // Absent working days default to WorkingDays.ALL_DAYS (Java's default), never left null here.
+    // Absent working days default to WorkingDays.ALL_DAYS (Java's default), so this is never null.
     get workingDays() {
         return this._workingDays;
     }
-    // Where this business is: the coordinates of the first of businessAddresses. Null when the
-    // business has not published them.
+    // Where this business is: the coordinates of the first of businessAddresses. Null when not
+    // published.
     get primaryStoreLocation() {
         return this._primaryStoreLocation;
     }
-    // What kind of business this is, as its Google Business Profile category - "Bakery", say. The
-    // name is the one to show; the id is the stable one to match on.
+    // What kind of business this is, as its Google Business Profile category (for example "Bakery").
+    // Show the name, match on the stable id.
     get googleBusinessCategoryId() {
         return this._googleBusinessCategoryId;
     }
     get googleBusinessCategoryName() {
         return this._googleBusinessCategoryName;
     }
-    // Which of a storefront's own themes this business picked. The themes are the storefront's, so
-    // what an id means is its business and not this library's; null when none was picked.
+    // Which of the storefront's own themes this business picked. What an id means is up to the
+    // storefront, not this library. Null when none was picked.
     get onlineStoreThemeId() {
         return this._onlineStoreThemeId;
     }
-    // Whether the business has turned online shopping on. The server does not refuse a business that has not: Model does,
-    // with a NotFoundException, once it has read everything it is sent and finds that the settings it then holds do not
-    // say so, or that it holds none - see Model.setBusinessId. Also false of a business that has made no settings, which
-    // is what GeneralSettings.EMPTY is.
+    // Whether the business has turned online shopping on. The server does not refuse a business that
+    // has not. Model does, with a NotFoundException, after reading everything it is sent, when the
+    // settings it holds do not say so or it holds none (see Model.setBusinessId). Also false for
+    // GeneralSettings.EMPTY.
     get onlineShoppingEnabled() {
         return this._onlineShoppingEnabled;
     }
 }
-// A business with no published public settings, used instead of null so every field is already the protocol's empty value.
+// A business with no published public settings. Used instead of null so every field is already
+// the protocol's empty value.
 GeneralSettings.EMPTY = new GeneralSettings(Object.freeze([]), null, false, false, AddressList.EMPTY, Object.freeze([]), Object.freeze([]), 0, Object.freeze([]), 0, 0, null, WorkingDays.ALL_DAYS, null, null, null, null, false);
 export default GeneralSettings;

package/dist/HttpStatusCodes.js

@@ -1,16 +1,15 @@
 import { BadRequestException, ConflictException, InternalServerException, MethodNotAllowedException, NotFoundException, ServiceException, ServiceUnavailableException, UnauthorizedException, UpgradeRequiredException, } from "./ServiceExceptions";
-// Which failure a status code stands for, and nothing else - the classes themselves are in
-// ServiceExceptions.ts. Split the same way Java splits HttpStatusCodes from its exception package,
-// so that the one table saying "401 means this" has a single home in each client.
-// Everything from 300 up, this being Java's HttpURLConnection.HTTP_MULT_CHOICE. A redirect counts as
-// a failure because this client asks for one route and follows nothing, so being sent elsewhere
-// means the call did not happen.
+// Which failure a status code stands for. The classes are in ServiceExceptions.ts. The split matches
+// Java's HttpStatusCodes and exception package, so the table of what each code means has one home
+// in each client.
+// Everything from 300 up (Java's HttpURLConnection.HTTP_MULT_CHOICE). A redirect counts as a
+// failure because this client follows none, so being sent elsewhere means the call did not happen.
 export function isError(httpStatusCode) {
     return httpStatusCode >= LOWEST_ERROR_STATUS_CODE;
 }
-// Raises the failure a status code stands for, and does nothing at all for one that is not an error.
-// A code with no class of its own is still a ServiceException carrying the code, so a server that
-// starts answering something new cannot slip past as a success.
+// Raises the failure a status code stands for, and does nothing for a code that is not an error.
+// A code with no class of its own becomes a ServiceException carrying the code, so a new server
+// response cannot pass as a success.
 export function throwOnError(httpStatusCode, message) {
     if (!isError(httpStatusCode))
         return;
@@ -20,8 +19,8 @@ export function throwOnError(httpStatusCode, message) {
     throw create(message);
 }
 const LOWEST_ERROR_STATUS_CODE = 300;
-// Java builds this by reflection over a map of classes; here each entry constructs its own, because
-// a constructor reached through a type is what keeps this checked at compile time.
+// Java builds this by reflection over a map of classes. Here each entry constructs its own class,
+// which keeps it checked at compile time.
 const EXCEPTIONS = new Map([
     [BadRequestException.STATUS_CODE, (message) => new BadRequestException(message)],
     [UnauthorizedException.STATUS_CODE, (message) => new UnauthorizedException(message)],

package/dist/Ids.js

@@ -1,7 +1,7 @@
 import { Constants as proto_Constants } from "./generated/Constants";
 import { ReservedPackage as proto_ReservedPackage } from "./generated/ReservedPackage";
-// Everything this library knows about entity id layout. Ids are built/read only here, since a 64-bit shift written in number arithmetic silently loses the entity type.
-// Some ids below are not entity ids but local-store blob ids; they're negative, which can never collide with a real id (whose sign bit is always clear).
+// All knowledge of entity id layout lives here, since a 64-bit shift in number arithmetic silently loses the entity type.
+// Some ids below are negative local-store blob ids, which cannot collide with a real id (its sign bit is clear).
 class Ids {
     // The most significant byte of an id: one of the *_ENTITY_TYPE_ID values of Constants.
     static getEntityTypeId(id) {
@@ -14,20 +14,16 @@ class Ids {
     static buildId(entityTypeId, lowPart) {
         return (BigInt(entityTypeId) << Ids.ENTITY_TYPE_BIT_SHIFT) | (lowPart & Ids.ID_MASK);
     }
-    // Where the cart of one membership lives: the business link id with the entity type swapped for
-    // the message one, which is Java Message.getPartyPreferencesMessageId. Derived rather than
-    // assigned so that a client always knows the id of its own cart without having been told it - a
-    // sync in answers with an update number and no id, so a cart the server named could not be stored
-    // here at all. One link therefore has one cart, and creating it twice is impossible by
-    // construction rather than by a check.
+    // The cart's message id: the business link id with the entity type swapped for the message one
+    // (Java Message.getPartyPreferencesMessageId). Derived because a sync in answers with an update
+    // number and no id, so a cart the server named could not be stored. One link has one cart.
     static getPartyPreferencesMessageId(businessLinkId) {
         return Ids.buildId(proto_Constants.MESSAGE_ENTITY_TYPE_ID, Ids.getLowPart(businessLinkId));
     }
-    // A fresh id for an entity this client is creating, to the rules of Java
-    // Entity.getRandomLongForId: random, and never in 0-255, which every entity type reserves. Only
-    // the low part is drawn, since buildId masks the rest off anyway, and it is drawn from the
-    // cryptographic generator rather than Math.random - an id is guessable otherwise, and a message id
-    // is a thing a caller could be handed.
+    // A fresh id for an entity this client creates (Java Entity.getRandomLongForId): random, never
+    // in 0-255, which every entity type reserves. Only the low part is drawn, as buildId masks the
+    // rest off. It uses the cryptographic generator because a Math.random id is guessable and a
+    // message id can be handed to a caller.
     static getNewId(entityTypeId) {
         for (;;) {
             const bytes = new Uint8Array(8);
@@ -50,22 +46,20 @@ class Ids {
     static toStorageHexString(id) {
         return (id & Ids.UNSIGNED_64_BIT_MASK).toString(16).toUpperCase().padStart(16, "0");
     }
-    // The number an order is shown under: the least significant 32 bits of the id of the message
-    // carrying it, as upper-case hex, not zero-padded. That is Java MessageBuilder.formatId, and it
-    // has to match character for character - the merchant app shows the same order under the same
-    // number, and a customer quoting one over the phone is the whole point of having it. An order
-    // number is therefore derived and not a field of the protocol.
-    // Java narrows with a cast to signed int and formats with %X, which prints the unsigned 32-bit
-    // twos complement; masking here answers the same string without the sign getting in the way.
-    // The merchant app prefixes the word "Order"; whether to do that is a UI's decision, not this one.
+    // The number an order is shown under: the low 32 bits of the id of the message carrying it, as
+    // upper-case hex without padding. Must match Java MessageBuilder.formatId character for
+    // character, since the merchant app shows the same number and a customer may quote it by phone.
+    // Derived, not a protocol field. Java casts to signed int and formats with %X, which prints the
+    // unsigned 32-bit two's complement, so masking gives the same string.
+    // The "Order" prefix the merchant app adds is a UI decision.
     static toOrderNumberString(orderId) {
         return (orderId & Ids.UNSIGNED_32_BIT_MASK).toString(16).toUpperCase();
     }
-    // Where a container keeps how far its reads of one entity type have got: the cursor the next read
-    // sends for it, which is the eTag of the blob and the whole of it. The store keeps the greater of two
-    // eTags, so a cursor is never lowered, by a page that is stale or sent again or by another tab
-    // writing at the same time. Written in the batch of the page that moved it, so that it cannot get
-    // ahead of the entities it describes. key is one of SyncKeys: the table an entity type counts under.
+    // Where a container keeps how far its reads of one entity type have got. The blob's eTag is the
+    // cursor the next read sends, and the blob holds nothing else. The store keeps the greater eTag,
+    // so a cursor never drops on a stale or repeated page or a write from another tab. Written in
+    // the batch of the page that moved it, so it cannot get ahead of the entities it describes. key
+    // is one of SyncKeys.
     static getSyncCursorBlobId(key) {
         return Ids.SYNC_CURSOR_BLOB_ID_BASE - BigInt(key);
     }
@@ -75,13 +69,13 @@ Ids.ENTITY_TYPE_BIT_SHIFT = BigInt(proto_Constants.ENTITY_TYPE_BIT_SHIFT);
 Ids.ID_MASK = (1n << BigInt(proto_Constants.ENTITY_TYPE_BIT_SHIFT)) - 1n;
 // The configuration holding a business's public settings - the only one sent to a storefront (Java Configuration.MIN_PUBLIC_CONFIGURATION_ID).
 Ids.GENERAL_SETTINGS_CONFIGURATION_ID = 0x0d10000000000000n;
-// A price list id is built by Constants.buildPriceListId rather than named here: which built-in
-// lists exist is a fact of the protocol, and only their low parts are constants of it.
+// A price list id is built by Constants.buildPriceListId, not named here. Only the low parts of
+// the built-in lists are protocol constants.
 // Where a business container keeps that business's attachment base url; its eTag is that url's expiry.
 Ids.ATTACHMENT_BASE_URL_BLOB_ID = -1n;
-// Where a container keeps the credentials that sign its calls - see AuthTokens. Written with a null eTag, since a reissued token is not a later version of an earlier one: the latest simply wins.
+// Where a container keeps the credentials that sign its calls (see AuthTokens). Written with a null eTag, since a reissued token is not a later version of the earlier one. The latest wins.
 Ids.AUTH_TOKENS_BLOB_ID = -2n;
-// The first of a block of fixed blob ids, one per key - see getSyncCursorBlobId. A key is an entity type id, which is below 0x80, so the block runs from -0x100 down to -0x17F and cannot meet the other fixed blobs at -1 and -2.
+// The first of a block of fixed blob ids, one per key (see getSyncCursorBlobId). A key is an entity type id, below 0x80, so the block runs from -0x100 down to -0x17F and cannot meet the fixed blobs at -1 and -2.
 Ids.SYNC_CURSOR_BLOB_ID_BASE = -0x100n;
 Ids.UNSIGNED_64_BIT_MASK = (1n << 64n) - 1n;
 Ids.UNSIGNED_32_BIT_MASK = (1n << 32n) - 1n;

package/dist/Item.js

@@ -1,8 +1,8 @@
 import Entity from "./Entity";
-// Something a business buys or sells, or a category or a price thereof - mirrors the protocol's Item, embedded in each of the five real types.
-// parentItemId is the wire parent (e.g. a product's category), distinct from Entity.parent, the sync layer's containment parent (e.g. the business).
+// Something a business buys or sells, or a category or price of one. Mirrors the protocol's Item, embedded in each of the five real types.
+// parentItemId is the wire parent (a product's category). Entity.parent is the sync layer's containment parent (the business).
 export default class Item extends Entity {
-    // Public rather than protected since ProductCategory/PriceList add nothing of their own; the class stays abstract, so still uninstantiable directly.
+    // Public because ProductCategory and PriceList add nothing of their own. The class is still abstract.
     constructor(header, _name, _description, _parentItemId, _isDisabled) {
         super(header);
         this._name = _name;
@@ -20,10 +20,9 @@ export default class Item extends Entity {
     get parentItemId() {
         return this._parentItemId;
     }
-    // True when the business has disabled this item. Unlike isPublic and Product.isDraft, this can
-    // change after an item exists, so it is sent rather than filtered out once and for all - a
-    // product-level filter (Catalog.getCustomerVisibleProducts) does not, by itself, guarantee that
-    // every package of an otherwise visible product is itself enabled.
+    // True when the business has disabled this item. Unlike isPublic and Product.isDraft, it can
+    // change after an item exists, so it is sent rather than filtered out. A product-level check does
+    // not guarantee that every package of an otherwise visible product is enabled.
     get isDisabled() {
         return this._isDisabled;
     }

package/dist/LatLong.js

@@ -1,6 +1,6 @@
-// A point on Earth. Not an entity - a value on GeneralSettings, where it is the business's own
-// location. Degrees, and nothing here converts or formats them: whether that becomes a map pin, a
-// distance or a link is a UI's decision.
+// A point on Earth, in degrees. Not an entity: a value on GeneralSettings, where it is the
+// business's own location. Converting or formatting it (a map pin, a distance, a link) is a UI
+// decision.
 export default class LatLong {
     constructor(_latitude, _longitude) {
         this._latitude = _latitude;

package/dist/LiveData.js

@@ -1,6 +1,6 @@
-// A value that notifies its observers whenever it is set - the Android LiveData of this library, what every storefront UI binds to.
-// Deliberately skips LifecycleOwner and onActive/onInactive (no web equivalent / no need), and differs from mbl-model's Observations:
-// observe() returns its own unobserve function, holder gives a stable snapshot for React, observers are a Map for O(1) removal, and a value set mid-notification restarts rather than interleaves.
+// A value that notifies its observers whenever it is set. This library's version of Android LiveData, which every storefront UI binds to.
+// Skips LifecycleOwner and onActive/onInactive (no web equivalent, no need). Differs from mbl-model's Observations:
+// observe() returns its own unobserve function, holder gives a stable snapshot for React, observers are a Map for O(1) removal, and a value set mid-notification restarts the notification instead of interleaving.
 class LiveData {
     constructor(value) {
         this._observers = new Map();
@@ -12,14 +12,14 @@ class LiveData {
     get value() {
         return this._holder.value;
     }
-    // Private - only the sync layer (via an UpdatableLiveData cast) can set the value; a UI can only read/observe.
+    // Private. Only the sync layer (through an UpdatableLiveData cast) can set the value; a UI can only read and observe.
     set value(value) {
-        // Always replaces the holder and notifies, even with the same reference - the interior may have changed and this class can't tell.
+        // Always replaces the holder and notifies, even for the same reference, since the interior may have changed and this class cannot tell.
         ++this._version;
         this._holder = new StateHolder(value);
         this.notifyObservers();
     }
-    // The current value, wrapped so its identity changes exactly once per notification; use this instead of value for reference-equality snapshot comparisons.
+    // The current value, wrapped so its identity changes once per notification. Use this instead of value for reference-equality snapshot comparisons.
     get holder() {
         return this._holder;
     }

package/dist/Measures.js

@@ -1,5 +1,5 @@
-// How big a package is, and how much it weighs - grouped together since a UI showing one usually shows both. Neither is an entity; both are values on the Package row.
-// Units are the generated proto enums, so a value displays in whatever unit the merchant entered it in; nothing here converts between units.
+// How big a package is and how much it weighs, grouped since a UI showing one usually shows both. Neither is an entity; both are values on the Package row.
+// Units are the generated proto enums. A value displays in the unit the merchant entered it in, and nothing here converts between units.
 export class Dimensions {
     constructor(_unit, _length, _width, _height) {
         this._unit = _unit;

package/dist/Message.js

@@ -1,6 +1,6 @@
 import Entity from "./Entity";
-// Something a customer sent to a business: an order (sales order) or a shopping cart (party preferences) - the two payloads this library understands.
-// A business entity despite being customer-authored, since Java authorizes the message table via Right.MESSAGES_MODIFY against the business.
+// Something a customer sent to a business: an order (sales order) or a shopping cart (party preferences), the two payloads this library understands.
+// A business entity despite being customer-authored, since Java authorizes the message table through Right.MESSAGES_MODIFY against the business.
 export default class Message extends Entity {
     constructor(header, _senderId, _messageType, _taskStatus, _senderName, _senderPhone) {
         super(header);
@@ -10,16 +10,16 @@ export default class Message extends Entity {
         this._senderName = _senderName;
         this._senderPhone = _senderPhone;
     }
-    // The customer's party id at the business (BusinessLink.partyId), and not the id of their User. A business sync out
-    // sends a customer only the messages whose sender is their own party. senderName/senderPhone below say who it was
-    // without resolving the party.
+    // The customer's party id at the business (BusinessLink.partyId), not the id of their User. A
+    // business sync out sends a customer only messages from their own party. senderName and
+    // senderPhone say who it was without resolving the party.
     get senderId() {
         return this._senderId;
     }
     get messageType() {
         return this._messageType;
     }
-    // How far the business has got with this message. Named after its enum, not the wire field "status", to avoid clashing with Order.status.
+    // How far the business has got with this message. Named after its enum rather than the wire field "status", which would clash with Order.status.
     get taskStatus() {
         return this._taskStatus;
     }

package/dist/MockDatabase.js

@@ -1,5 +1,5 @@
 // A Database that holds everything in a Map, for tests and training mode to run against with no
-// network. Enforces the eTag rule for real (write only if the new eTag is greater), so a test proves the sync is actually idempotent.
+// network. Enforces the eTag rule (write only if the new eTag is greater), so a test proves the sync is idempotent.
 export default class MockDatabase {
     constructor() {
         this._containers = new Map();
@@ -51,7 +51,7 @@ export class MockContainer {
             this._blobs.set(blob.id, blob);
             ++appliedCount;
         }
-        // Unconditional, and after the writes, exactly as the Database contract says
+        // After the writes, as the Database contract says
         for (const id of deletes)
             this._blobs.delete(id);
         return appliedCount;