@peabody-soft/mbs-protos 1.0.0 → 1.2.0

package/ShoppingList.proto

@@ -6,12 +6,9 @@ option java_package = "com.merabills.server.core.generated";
 import "ShoppingListItem.proto";
 
 // A list of packages being bought - a customer's shopping cart, or the contents of an order.
-// In Java the items are serialized into a base64 string; they are typed here.
 // Excluded: transactionTime.
-// Not included because they are computed from the fields below: totalAmount (=
-// totalAmountBeforeDiscount - discount), totalTax (the sum of the taxes of the existing items) and
-// itemCount (= existingItemCount + deletedItemCount). isSaved and the change listener are Java
-// bookkeeping and are not part of this protocol.
+// Not included because it is derived: totalAmount (= totalAmountBeforeDiscount - discount), totalTax,
+// itemCount (= existingItemCount + deletedItemCount), isSaved.
 message ShoppingList {
 
   // True once the customer is done editing this list, after which the business may edit it.
@@ -28,15 +25,12 @@ message ShoppingList {
   // Id of the inventory location the items are drawn from. 0 is the default location.
   int32 inventoryLocationId = 4;
 
-  // Id of the PriceList the prices of the items came from - the one price list a
-  // BusinessSyncOutResponse carries. A client creating a cart that has none yet sends the id built
-  // from Constants.DEFAULT_SALE_PRICE_LIST.
+  // Id of the PriceList the prices came from. A cart with none yet uses the id built from
+  // Constants.DEFAULT_SALE_PRICE_LIST.
   int64 priceListId = 5;
 
-  // Sum of the final prices of the existing items, multiplied by Constants.AMOUNT_FACTOR.
-  // This total is authoritative: it is computed with the rounding rules of PriceCalculation, which
-  // a client is not expected to reproduce. Display it minus the discount below, rather than adding
-  // the items up.
+  // Sum of the final prices of the existing items x Constants.AMOUNT_FACTOR. Authoritative - do not
+  // recompute; display it minus discount rather than summing items yourself.
   int64 totalAmountBeforeDiscount = 6;
 
   // Discount on the whole list, multiplied by Constants.AMOUNT_FACTOR

package/ShoppingListItem.proto

@@ -5,15 +5,14 @@ option java_package = "com.merabills.server.core.generated";
 
 import "Tax.proto";
 
-// A line item in a shopping list: the package being bought, how much of it, and at what price.
+// A line item in a shopping list: the package bought, how much, and at what price.
 // Excluded: batches.
-// Not included because they are computed from the fields below and are not stored in Java:
-// taxes amounts, totalTax and finalPrice (= (unitPrice x quantity) + taxes thereon - discount).
+// Not included because it is derived: tax amounts, totalTax, finalPrice (= unitPrice x quantity +
+// taxes - discount).
 message ShoppingListItem {
 
-  // Id of the package being bought. Four ids are reserved for charge and summary lines rather
-  // than catalog packages, and will not be found in the catalog - see ReservedPackage, which
-  // gives those ids and how to build them. A client must label those lines itself.
+  // Id of the package bought. Four ids are reserved for charge/summary lines (see ReservedPackage)
+  // and will not be found in the catalog - label those yourself.
   int64 packageId = 1;
 
   // Quantity, multiplied by Constants.QUANTITY_FACTOR. 1.5 kg is stored as 1500.

package/UrlAndToken.proto

@@ -3,55 +3,27 @@ package com.merabills.storefront;
 option java_multiple_files = true;
 option java_package = "com.merabills.server.core.generated";
 
-// Where a set of files is, the shared access signature that authorizes reading them, and the moment
-// both stop working. This is the Java UrlAndToken of the repository client: what
-// Service.createAttachmentSasUrl returns, and what BlobClient builds every blob url from.
+// Where a set of files is, the read-only signature that authorizes reading them, and when both
+// expire. Carried once, as BusinessSyncOutResponse.attachmentBaseUrl for a business's photos - not an
+// entity, and never deleted, only expired.
 //
-// This protocol uses it for one thing - BusinessSyncOutResponse.attachmentBaseUrl, the container
-// that holds the photos of a business. It is a value and not an entity: it has no Entity, no id and
-// no update number, because it is generated per caller on demand and stored nowhere. It cannot be
-// deleted either, so there is no tombstone for it; it only expires.
-//
-// A client builds the url of one file the way BlobClient.createBlobUrl does, by putting the storage
-// file name of the attachment in the path and the token in the query string:
-//
-//   resourceUrl + "/" + storage file name + "?" + sasToken
-//
-// The storage file name is derived from the attachment rather than sent - Attachment says how it is
-// built. The container is flat: every file sits directly under resourceUrl, so a storage file name
-// must never be turned into a path of its own.
-//
-// What the token grants is only what a storefront needs, and this is what a server must keep true
-// when it fills this in. CloudDb.createAttachmentSasUrl grants read, grants create only to a caller
-// with Right.ATTACHMENTS_MODIFY, and grants nothing else - no write, no delete, and no list, so
-// holding this cannot be used to enumerate the container. A storefront customer has none of those
-// rights and must be given the read only signature of the public container; the private container
-// requires attachment rights and must never be handed to a storefront.
-//
-// The token is a credential: anyone holding it can read the files of that container until it
-// expires, so it must not be logged. Unlike AuthTokens.userToken and BusinessLink.linkToken, which
-// must never appear in a url, this one is meant to be in a url - a browser fetching an image can
-// pass it no other way. It is safe there because it is scoped to one container, read only, and
+// Build a file's url as resourceUrl + "/" + storage file name + "?" + sasToken (see Attachment for
+// the storage file name). The token is a credential - do not log it - but unlike AuthTokens.userToken
+// and BusinessLink.linkToken it is meant to go in a url: it is scoped to one container, read only and
 // short lived.
 message UrlAndToken {
 
-  // The url of the container the files are in - Java UrlAndToken.mResourceUrl, serialized as "ru".
-  // Always https, and never with a trailing slash or a query string of its own.
+  // The url of the container the files are in. Always https, never with a trailing slash or a query
+  // string of its own.
   string resourceUrl = 1;
 
-  // The shared access signature that authorizes reading a file of that container, ready to use as a
-  // query string ("sv=...&se=...&sig=...") and without the leading question mark - Java
-  // UrlAndToken.mSasToken, serialized as "st". A client appends it as it is; it never parses or
-  // rebuilds it.
+  // The shared access signature that authorizes reading a file, ready to use as a query string
+  // ("sv=...&se=...&sig=...", no leading "?"). Append it as-is; never parse or rebuild it.
   string sasToken = 2;
 
-  // When the two fields above stop working, in milliseconds since Jan 1, 1970 UTC - Java
-  // UrlAndToken.mExpiryUtcMillis, serialized as "ex". After this, every url built from them is
-  // refused by storage, so a client stops using them and asks for new ones - see
-  // BusinessSyncOutRequest.attachmentBaseUrlExpiry, which is where a client sends this value back.
-  //
-  // A client must treat this as reached Constants.ATTACHMENT_BASE_URL_EXPIRY_MARGIN before it
-  // actually is, the way UrlAndTokenFetcher.isTokenInvalid does, so that a url it is about to build
-  // cannot expire between building and fetching.
+  // When the fields above stop working, in milliseconds since Jan 1, 1970 UTC. Send this back as
+  // BusinessSyncOutRequest.attachmentBaseUrlExpiry. Treat it as expired
+  // Constants.ATTACHMENT_BASE_URL_EXPIRY_MARGIN early, so a url being built cannot expire before it
+  // is fetched.
   int64 expiry = 3;
 }

package/User.proto

@@ -6,14 +6,9 @@ option java_package = "com.merabills.server.core.generated";
 import "AddressList.proto";
 import "Entity.proto";
 
-// A user of MeraBills. A customer of a business is represented by a User.
-//
-// A user lives in a profile database, not in a business database, so it is carried by a
-// ProfileSyncOutResponse and not by a BusinessSyncOutResponse, the way Java splits
-// Service.profileSyncOut from Service.businessSyncOut. Do not add it to the business sync out: a
-// client reads the caller once, by signing in, and then reads each business separately.
-//
-// Excluded: referralDetails, isCallingUser and all Translations fields.
+// A user of MeraBills; a customer of a business is represented by one. Carried by a
+// ProfileSyncOutResponse, not by a business sync out - a client reads the caller once, at sign in.
+// Excluded: referralDetails, isCallingUser, all Translations fields.
 // Not included because it is derived: formattedName (firstName + " " + lastName).
 message User {
 

package/WorkingDays.proto

@@ -10,17 +10,12 @@ import "WorkingHours.proto";
 // isOpenAt.
 message WorkingDays {
 
-  // Up to Constants.DAYS_IN_WEEK values: index 0 is Sunday, 1 is Monday ... 6 is Saturday.
-  // A value of true means the business works on that day. A missing value is false. An absent
-  // WorkingDays means the business works on every day of the week, which is the Java default.
+  // Up to Constants.DAYS_IN_WEEK values, index 0 = Sunday. True means the business works that day;
+  // missing means false. An absent WorkingDays means every day is worked (the default).
   repeated bool days = 1;
 
-  // The working hours of each day, indexed exactly as days above: entry 0 is Sunday. Up to
-  // Constants.DAYS_IN_WEEK entries, and fewer - or none at all - is normal.
-  //
-  // An entry that is missing, or that is present with no ranges, means work goes on all day long on
-  // that day. So an empty workingHours means the business works round the clock on each of its
-  // working days. Hours are only meaningful on a day whose days entry is true; on any other day
-  // they must be ignored.
+  // Working hours of each day, indexed as days above (entry 0 = Sunday); up to
+  // Constants.DAYS_IN_WEEK entries, fewer is normal. A missing entry, or one with no ranges, means
+  // work all day; only meaningful on a day whose days entry is true.
   repeated WorkingHours workingHours = 2;
 }

package/WorkingHours.proto

@@ -9,11 +9,7 @@ import "WorkingHoursRange.proto";
 // Not included because they are computed: rangeCount, isAllDay and contains.
 message WorkingHours {
 
-  // The stretches of the day that are worked (at most Constants.WORKING_HOURS_MAX_RANGES). They do
-  // not overlap, they are ordered by openMinute, and two of them never touch - a range closing
-  // exactly when the next opens is sent as one unbroken range.
-  //
-  // No ranges at all means work goes on all day long, which is also what a range covering the whole
-  // day would mean.
+  // Stretches worked in the day (at most Constants.WORKING_HOURS_MAX_RANGES): non-overlapping,
+  // ordered by openMinute, and merged when adjacent. No ranges means work goes on all day.
   repeated WorkingHoursRange ranges = 1;
 }

package/WorkingHoursRange.proto

@@ -3,13 +3,11 @@ package com.merabills.storefront;
 option java_multiple_files = true;
 option java_package = "com.merabills.server.core.generated";
 
-// A single stretch of working hours within one day, in minutes after local midnight. The times are
-// local to the business, not UTC, and this protocol carries no time zone: a client that wants to
-// know whether the business is open now has to use the time zone of the business address.
-//
-// A range never spans midnight. Work that goes on past midnight is two ranges: one closing at
-// Constants.MINUTES_PER_DAY on one day, and one opening at 0 on the day after.
-// Not included because they are computed: isAllDay, contains and overlaps.
+// A single stretch of working hours within a day, in minutes after local midnight (no time zone is
+// carried - resolve using the business address's time zone).
+// A range never spans midnight; work past midnight is two ranges - one closing at
+// Constants.MINUTES_PER_DAY, one opening at 0 the next day.
+// Not included because it is derived: isAllDay, contains, overlaps.
 message WorkingHoursRange {
 
   // Minute at which work starts, from 0 to Constants.MINUTES_PER_DAY - 1. This minute is worked.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peabody-soft/mbs-protos",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "The MeraBills shop wire protocol",
   "author": "Peabody Soft",
   "license": "AGPL-3.0-or-later",