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

package/dist/Address.js

@@ -1,9 +1,7 @@
-// A postal address: a delivery address of a customer, or an address of a business. Not an entity -
-// its id is unique only within the AddressList that holds it.
+// A postal address of a customer or a business. Not an entity: its id is unique only within the
+// AddressList that holds it.
 export default class Address {
-    constructor(
-    // Unique only within the list that holds it, unlike an entity id
-    id, _addressType, _unitNumber, _community, _line2, _city, _state, _pinCode, _countryCode) {
+    constructor(id, _addressType, _unitNumber, _community, _line2, _city, _state, _pinCode, _countryCode) {
         this.id = id;
         this._addressType = _addressType;
         this._unitNumber = _unitNumber;
@@ -42,8 +40,8 @@ export default class Address {
     get countryCode() {
         return this._countryCode;
     }
-    // The set parts, in envelope order, joined with commas; empty when none are set. Country is
-    // deliberately excluded - turning a code into a name is a UI decision, not this library's.
+    // The non-empty parts in envelope order, joined with commas. Country is left out, since naming
+    // it is a UI decision.
     get formattedAddress() {
         const parts = [];
         for (const part of [
@@ -75,8 +73,8 @@ export class AddressList {
     get size() {
         return this._addresses.length;
     }
-    // The address named by defaultAddressId, or the first address if that id names none (default was
-    // deleted). Null only when the list is empty.
+    // The address named by defaultAddressId, or the first one if that id names none (the default was
+    // deleted). Null when the list is empty.
     get defaultAddress() {
         if (this._addresses.length === 0)
             return null;
@@ -92,6 +90,5 @@ export class AddressList {
         return null;
     }
 }
-// An empty list, for a user or a business that has no addresses at all. Frozen and shared,
-// because an AddressList holds nothing that can change.
+// The shared empty list. Frozen, since an AddressList cannot change.
 AddressList.EMPTY = new AddressList(0n, Object.freeze([]));

package/dist/Attachment.js

@@ -1,7 +1,7 @@
 import Entity from "./Entity";
 import Ids from "./Ids";
-// A file attached to an entity - a photo of a business, a product or a package. Not part of this
-// library's public surface; a UI is given a Photo (attachment type + url) built from this instead.
+// A file attached to an entity: a photo of a business, product or package. Not public. A UI is given
+// a Photo (attachment type and url) built from it.
 export default class Attachment extends Entity {
     constructor(header, _attachmentType, _owningEntityId, _fileHash, _fileExtension, _fileName) {
         super(header);
@@ -11,21 +11,20 @@ export default class Attachment extends Entity {
         this._fileExtension = _fileExtension;
         this._fileName = _fileName;
     }
-    // Which photo of the owning entity this is: the main catalog image, one of the lifestyle images,
-    // a photo of the store, and so on
+    // Which photo of the owning entity this is, such as the main catalog image or a store photo
     get attachmentType() {
         return this._attachmentType;
     }
-    // The business, product or package this file is attached to. Nothing nests on the wire, so this
-    // is how the sync layer finds which entity a photo belongs to.
+    // The business, product or package this file is attached to. Nothing nests on the wire, so the
+    // sync layer uses this to place the photo.
     get owningEntityId() {
         return this._owningEntityId;
     }
     get fileName() {
         return this._fileName;
     }
-    // Storage file name, or null if this attachment has no file (deleted). Must exactly match Java
-    // Attachment.getStorageFileName: UTC date with zero-based month, upper-hex id/hash, no 0x prefix.
+    // Storage file name, or null if the attachment has no file (deleted). Must match Java
+    // Attachment.getStorageFileName: UTC date with zero-based month, upper-hex id and hash, no 0x prefix.
     get storageFileName() {
         if (this._fileHash === null || this._fileExtension === null)
             return null;

package/dist/AttachmentBaseUrl.js

@@ -1,40 +1,40 @@
 import { Constants as proto_Constants } from "./generated/Constants";
 import { InvalidArgumentException } from "./Exceptions";
 // Where a business's attachment files live, the signature that reads them, and when both expire.
-// Signature has no getter (only createFileUrl exposes it) - safe in a url only because it is
-// scoped, read-only and short-lived, unlike AuthTokens' userToken/linkToken.
+// The signature has no getter, only createFileUrl exposes it. It is safe in a url because it is
+// scoped, read-only and short-lived, unlike AuthTokens' userToken and linkToken.
 export default class AttachmentBaseUrl {
     constructor(_resourceUrl, _sasToken, expiry) {
         this._resourceUrl = _resourceUrl;
         this._sasToken = _sasToken;
-        // The protobuf promises no trailing slash and no query string; checked rather than trusted,
-        // since violating either silently produces a url that fetches nothing.
+        // The protobuf promises no trailing slash and no query string. Checked, since either would
+        // silently build a url that fetches nothing.
         if (_resourceUrl.length === 0 || _resourceUrl.endsWith("/"))
             throw new InvalidArgumentException(`Not a container url: ${_resourceUrl}`);
         if (_resourceUrl.includes("?"))
             throw new InvalidArgumentException("A container url cannot carry a query string");
         this._expiry = Number(expiry);
     }
-    // The url of the container the files are in, always https and never with a trailing slash
+    // The url of the container the files are in. Https, no trailing slash.
     get resourceUrl() {
         return this._resourceUrl;
     }
     get expiry() {
         return new Date(this._expiry);
     }
-    // True once too close to expiry to be worth using (margin: ATTACHMENT_BASE_URL_EXPIRY_MARGIN),
-    // compared against the client's own clock so a url can't expire between being built and fetched.
+    // True once within ATTACHMENT_BASE_URL_EXPIRY_MARGIN of expiry, by the client's clock, so a url
+    // cannot expire between being built and fetched.
     get hasExpired() {
         return Date.now() + proto_Constants.ATTACHMENT_BASE_URL_EXPIRY_MARGIN >= this._expiry;
     }
-    // The url of one file: storage file name as the path, signature as the query string. Name must
-    // be a flat path segment - a container is not a directory tree.
+    // The url of one file: storage file name as the path, signature as the query string. The name
+    // must be a single path segment, as a container has no directories.
     createFileUrl(storageFileName) {
         if (storageFileName.length === 0 || storageFileName.includes("/"))
             throw new InvalidArgumentException(`Not a storage file name: ${storageFileName}`);
         return new URL(`${this._resourceUrl}/${storageFileName}?${this._sasToken}`);
     }
-    // Redacts the signature, so that logging one of these cannot leak it
+    // Redacts the signature so logging cannot leak it
     toString() {
         return `AttachmentBaseUrl(resourceUrl=${this._resourceUrl}, expiry=${this.expiry.toISOString()}, sasToken=<redacted>)`;
     }

package/dist/AuthTokens.js

@@ -1,5 +1,6 @@
-// The credentials one request is signed with: exactly the fields of the AuthTokens message and nothing derived, so that what this library holds and what the wire carries cannot drift.
-// A class of its own rather than the generated message because these are held and cached rather than only sent; ProtoMap turns one into the message a Service is handed. Every value is a bearer credential - never log one.
+// The credentials a request is signed with: the fields of the AuthTokens message, nothing derived.
+// A class of its own because it is held and cached. ProtoMap turns one into the message a Service
+// is handed. Every value is a bearer credential, so never log one.
 export default class AuthTokens {
     constructor(_authenticationMethod, _authenticationToken, _userToken, _linkToken) {
         this._authenticationMethod = _authenticationMethod;
@@ -7,23 +8,27 @@ export default class AuthTokens {
         this._userToken = _userToken;
         this._linkToken = _linkToken;
     }
-    // Which identity provider issued the authentication token, and so how a server parses it. Always set: zero is FIREBASE, not "unspecified".
+    // The identity provider that issued the authentication token, which tells the server how to
+    // parse it. Always set. Zero is FIREBASE.
     get authenticationMethod() {
         return this._authenticationMethod;
     }
-    // Which person is calling, as their identity provider says. Empty on one read back out of the cache, which deliberately keeps no copy of it - see ProtoMap.authTokensToBlob.
+    // Who is calling, as their identity provider states it. Empty when read back from the cache, which
+    // keeps no copy. See ProtoMap.authTokensToBlob.
     get authenticationToken() {
         return this._authenticationToken;
     }
-    // Which MeraBills user that person is, issued by this server. Null until a profile sync out has been made once, which is the call that earns one.
+    // The MeraBills user, issued by this server. Null until the first profile sync out, which is the
+    // call that returns one.
     get userToken() {
         return this._userToken;
     }
-    // Which business the caller may act against, from the BusinessLink of that business. Null on a call that names none, which the protocol allows.
+    // Authorizes the caller against one business, from that business's BusinessLink. Null on a call
+    // that names no business.
     get linkToken() {
         return this._linkToken;
     }
-    // Redacts all three, so that logging one of these cannot leak a credential
+    // Redacts all three tokens so logging cannot leak them
     toString() {
         return `AuthTokens(authenticationMethod=${this._authenticationMethod}, authenticationToken=<redacted>, userToken=<${this._userToken === null ? "none" : "redacted"}>, linkToken=<${this._linkToken === null ? "none" : "redacted"}>)`;
     }

package/dist/Business.js

@@ -3,9 +3,9 @@ import CartEditor from "./CartEditor";
 import Catalog from "./Catalog";
 import Entity from "./Entity";
 import GeneralSettings from "./GeneralSettings";
-// The business a customer is browsing: its name, settings, photos, catalog, orders, and cart.
-// Rebuilt by the sync layer from flat wire entities and set via UpdatableBusiness, not a public
-// setter - a UI holding a Business can read all of it and change none of it.
+// The business a customer is browsing: name, settings, photos, catalog, orders and cart. The sync
+// layer rebuilds it from flat wire entities and sets it through UpdatableBusiness. A UI can read
+// all of it and change none.
 export default class Business extends Entity {
     constructor(header, _businessId, _displayName, _countryCode) {
         super(header);
@@ -20,8 +20,8 @@ export default class Business extends Entity {
         this._catalog = Catalog.EMPTY;
         this._attachmentBaseUrl = null;
     }
-    // The unique, lower case, url friendly id this storefront was reached by - not the entity id
-    // (see the warning on BusinessLink.businessId, which is this business's entity id)
+    // The unique, lower case, url friendly id the storefront is reached by. The entity id is
+    // BusinessLink.businessId.
     get businessId() {
         return this._businessId;
     }
@@ -47,28 +47,28 @@ export default class Business extends Entity {
     set photos(value) {
         this._photos = value;
     }
-    // The orders this customer has placed
+    // The orders this customer has placed, open and completed (fulfilled or cancelled). Order.status
+    // says how far the business got, and Order.isDeleted that it has completed the order. The library
+    // does not sort them.
     get orders() {
         return this._orders;
     }
     set orders(value) {
         this._orders = value;
     }
-    // What this customer has picked and not yet ordered. Null until they have put something in a
-    // cart, and null again once they have ordered what was in it - the message the cart travels in
-    // outlives being emptied, but nothing of it is a customer's business, so what is exposed is the
-    // list alone. The fulfillment mode is not part of it: that is chosen when an order is placed, and
-    // is a field of the Order - see defaultFulfillmentMode for the one other place it is read.
+    // What this customer has picked and not yet ordered. Null until something is put in a cart, and
+    // null again once it is ordered, although the message carrying the cart outlives that. Only the
+    // list is exposed. The fulfillment mode is chosen when an order is placed and is a field of the
+    // Order (see defaultFulfillmentMode).
     get cart() {
         return this._cart;
     }
     set cart(value) {
         this._cart = value;
     }
-    // What to preselect for this customer's next order: whatever the party preferences message
-    // already carries, which createOrder stamps with the mode an order was just placed under - so
-    // this is that order's own choice, not necessarily today's cart's. DELIVERY when there has never
-    // been a party preferences message to read one from.
+    // What to preselect for the next order. It is the mode in the party preferences message, which
+    // createOrder stamps with the mode of the order just placed, so it is the last order's choice.
+    // DELIVERY when there is no party preferences message.
     get defaultFulfillmentMode() {
         return this._defaultFulfillmentMode;
     }
@@ -82,14 +82,14 @@ export default class Business extends Entity {
     set catalog(value) {
         this._catalog = value;
     }
-    // A scratch copy of the cart to edit, priced off this business's catalog and charged to its
-    // settings - see CartEditor. It reads all three once, here, so a Business republished mid-edit
-    // needs a fresh one; nothing an editor does touches this business until its built list reaches
+    // A scratch copy of the cart to edit, priced from this business's catalog and settings (see
+    // CartEditor). It reads catalog, settings and cart once, so a Business republished mid-edit needs
+    // a new editor. Nothing it does touches this business until its built list reaches
     // Model.updateCartLocalOnly.
     createCartEditor() {
         return new CartEditor(this._catalog, this._settings, this._cart);
     }
-    // Where this business's photo files live; renewed on its own schedule independent of the rest
+    // Where this business's photo files live. Renewed on its own schedule.
     get attachmentBaseUrl() {
         return this._attachmentBaseUrl;
     }

package/dist/BusinessIdentifier.js

@@ -1,5 +1,5 @@
-// An identifier of a business - a GSTIN, for example - and its kind. Same pair-not-a-map reason as
-// PackageIdentifier: Java identifies kinds by string id, so this numbering is protocol-only.
+// An identifier of a business, such as a GSTIN, and its kind. A pair rather than a map, as in
+// PackageIdentifier: Java identifies kinds by string id, so the numbering is protocol-only.
 export default class BusinessIdentifier {
     constructor(_type, _value) {
         this._type = _type;

package/dist/BusinessLink.js

@@ -1,7 +1,7 @@
 import { Constants as proto_Constants } from "./generated/Constants";
 import Entity from "./Entity";
-// What links a customer to a business and authorizes them to act against it. businessId is an
-// entity id (not the url-friendly Business.businessId); never log or url-embed linkToken.
+// Links a customer to a business and authorizes them to act against it. businessId is an entity
+// id, unlike the url-friendly Business.businessId.
 class BusinessLink extends Entity {
     constructor(header, _linkedEntityId, _businessId, _role, _partyId, _linkToken, expiry) {
         super(header);
@@ -12,46 +12,46 @@ class BusinessLink extends Entity {
         this._linkToken = _linkToken;
         this._expiry = Number(expiry);
     }
-    // The entity this link is for - the User of the customer, in a storefront. Its entity type is
-    // the most significant byte of the id, which is how a client tells a user from a business.
+    // The entity this link is for, in a storefront the customer's User. The entity type is the most
+    // significant byte of the id, which tells a user from a business.
     get linkedEntityId() {
         return this._linkedEntityId;
     }
-    // The entity id of the business, matching Business.entity.id - see the comment on this class
+    // The entity id of the business, matching Business.entity.id. See the class comment.
     get businessId() {
         return this._businessId;
     }
-    // What the customer may do, normally Role.CUSTOMER. Group is (role >> 6); actual permissions are
-    // not on the wire, so a UI cannot grey out disallowed actions.
+    // What the customer may do, normally Role.CUSTOMER. The group is role >> 6. Permissions are not
+    // on the wire, so a UI cannot grey out disallowed actions.
     get role() {
         return this._role;
     }
-    // The party record of this customer, or Constants.ENTITY_ID_NULL when none. Party is not part of
-    // this protocol, so a storefront cannot resolve it - exposed only because the server needs it.
+    // The customer's party record, or Constants.ENTITY_ID_NULL when none. Party is not part of this
+    // protocol, so a storefront cannot resolve it. Exposed because the server needs it.
     get partyId() {
         return this._partyId;
     }
-    // The credential that goes into AuthTokens.linkToken of every later request naming this
-    // business. Never log this and never put it in a url.
+    // The credential for AuthTokens.linkToken on later requests that name this business. Never log
+    // it or put it in a url.
     get linkToken() {
         return this._linkToken;
     }
     get expiry() {
         return new Date(this._expiry);
     }
-    // False when this link never expires, which is what BusinessLink.NO_EXPIRY means. That constant
-    // is not in Constants.proto - it is zero, and it is the only meaning zero has for this field.
+    // False when the link never expires (expiry is NO_EXPIRY). NO_EXPIRY is zero and is not in
+    // Constants.proto.
     get isExpirySet() {
         return this._expiry !== BusinessLink.NO_EXPIRY;
     }
-    // True once past expiry by more than Constants.MAX_CLOCK_SKEW - applied opposite to
-    // AttachmentBaseUrl.hasExpired, so a false positive can't lock out a still-entitled customer.
+    // True once past expiry by more than Constants.MAX_CLOCK_SKEW. Applied the opposite way to
+    // AttachmentBaseUrl.hasExpired, so a false positive cannot lock out an entitled customer.
     get hasExpired() {
         if (!this.isExpirySet)
             return false;
         return Date.now() - proto_Constants.MAX_CLOCK_SKEW > this._expiry;
     }
-    // Redacts the link token, so that logging a link cannot leak it
+    // Redacts the link token so logging cannot leak it
     toString() {
         return `BusinessLink(id=${this.id}, businessId=${this._businessId}, role=${this._role}, linkToken=<redacted>)`;
     }

package/dist/BusinessProfile.js

@@ -1,6 +1,6 @@
 import Entity from "./Entity";
 // One business the customer is linked to, as the profile database holds it: url-friendly id, name
-// and country only - deliberately not a Business, which carries data a profile sync can't provide.
+// and country. A Business carries more than a profile sync provides.
 export default class BusinessProfile extends Entity {
     constructor(header, _businessId, _displayName, _countryCode) {
         super(header);
@@ -8,8 +8,8 @@ export default class BusinessProfile extends Entity {
         this._displayName = _displayName;
         this._countryCode = _countryCode;
     }
-    // The unique, lower case, url-friendly id a storefront is reached by; what Model.setBusinessId
-    // takes. Not the entity id - BusinessLink.businessId is the entity id of the same business.
+    // The unique, lower case, url-friendly id a storefront is reached by. It is what
+    // Model.setBusinessId takes. The entity id is BusinessLink.businessId.
     get businessId() {
         return this._businessId;
     }
@@ -17,7 +17,7 @@ export default class BusinessProfile extends Entity {
     get displayName() {
         return this._displayName;
     }
-    // ISO 3166-1 numeric; the only thing that says what currency this business's amounts are in
+    // ISO 3166-1 numeric; the only source of currency for this business's amounts
     get countryCode() {
         return this._countryCode;
     }