@peabody-soft/mbs-protos 1.1.0 → 1.3.0

package/Constants.proto

@@ -3,20 +3,15 @@ package com.merabills.storefront;
 option java_multiple_files = true;
 option java_package = "com.merabills.server.core.generated";
 
-// The limits, scaling factors and other constants that the values in this protocol obey, so that a
-// client can read them programmatically instead of hard coding them. Protobuf has no constants, so
-// they are enum values; every value below is the Java constant of the same meaning, named after it
-// or after the message and field it applies to. Aliases are allowed because several unrelated
-// constants share a value. This is a carrier for constants, not the type of any field.
-//
-// Lengths are in characters, and are maximums unless the name says otherwise. Counts are maximums.
-// An enum value is a signed 32 bit integer, so three kinds of Java constant cannot appear here:
-//   - Transaction.MAX_AMOUNT (17,592,186,044,415), which is the largest amount this protocol can
-//     carry.
-//   - Entity.ID_MASK (0x00FFFFFFFFFFFFFF) and Entity.PARTITION_ID_MASK (0xFF00FFFFFFFFFFFF). Both
-//     are derived from the shifts below: ID_MASK is (1 << ENTITY_TYPE_BIT_SHIFT) - 1.
-//   - The Entity.NAME_* short codes ("id", "ua", "un", "cr", ...), which are strings, and which
-//     name fields of the Java JSON serialization rather than anything in this protocol.
+// The limits, scaling factors and other constants this protocol's values obey, so a client can read
+// them programmatically. Protobuf has no constants, so these are enum values named after the Java
+// constant of the same meaning (allow_alias because several unrelated constants share a value); not
+// the type of any field. Lengths are in characters and are maximums unless the name says otherwise;
+// counts are maximums.
+// Three kinds of Java constant don't fit a signed 32 bit enum value and are left out: Transaction.MAX_AMOUNT
+// (17,592,186,044,415, the largest amount this protocol can carry), Entity.ID_MASK / PARTITION_ID_MASK
+// (64 bit, derivable from the shifts below), and the Entity.NAME_* short codes (strings, not part of
+// this protocol).
 enum Constants {
 
   option allow_alias = true;
@@ -117,23 +112,15 @@ enum Constants {
   // means work stops at midnight (DateTimeHelper.MINUTES_PER_DAY)
   MINUTES_PER_DAY = 1440;
 
-  // The layout of an Entity.id: the most significant byte is the entity type and the byte below it
-  // is the partition id, so the id of an entity of type t with the low part n is
-  // (t << ENTITY_TYPE_BIT_SHIFT) | n. Use 64 bit arithmetic - BigInt in TypeScript - for a shift.
+  // Layout of an Entity.id: top byte is the entity type, next byte is the partition id -
+  // id = (type << ENTITY_TYPE_BIT_SHIFT) | n. Use 64 bit arithmetic (BigInt in TypeScript) for the shift.
   ENTITY_TYPE_BIT_SHIFT = 56;
   PARTITION_ID_SHIFT = 48;
 
-  // The entity type ids that appear in this protocol, so that a client can tell what an id refers
-  // to: (id >> ENTITY_TYPE_BIT_SHIFT) is one of these. The ids of the five item types below all
-  // belong to the item table, which is what BusinessSyncOutRequest.itemUpdateNumber tracks.
-  // These ids are stable and must never be changed or re-used.
-  //
-  // The first three ids below belong to the profile database and the rest to a business database,
-  // which is what decides where each is read from: a ProfileSyncOutRequest has a cursor for USER,
-  // BUSINESS and BUSINESS_LINK, and a BusinessSyncOutRequest for ATTACHMENT, CONFIGURATION, MESSAGE
-  // and ITEM. BUSINESS is the one type both calls carry, because a client that has not signed in has
-  // no profile sync out to read it from; the two cursors over it are separate and must not be mixed.
-  // Ids of the profile types turn up in a business sync out even so - Message.senderId is a user id.
+  // Entity type ids used by this protocol: (id >> ENTITY_TYPE_BIT_SHIFT) is one of these; stable,
+  // never changed or reused. USER, BUSINESS and BUSINESS_LINK are profile-database types (read by a
+  // ProfileSyncOutRequest); the rest are business-database types (read by a BusinessSyncOutRequest).
+  // BUSINESS is read by both, with separate cursors that must not be mixed.
   USER_ENTITY_TYPE_ID = 1;
   BUSINESS_ENTITY_TYPE_ID = 2;
   BUSINESS_LINK_ENTITY_TYPE_ID = 3;
@@ -147,9 +134,8 @@ enum Constants {
   PRICE_ENTITY_TYPE_ID = 67;
   PRICE_LIST_ENTITY_TYPE_ID = 68;
 
-  // The last two bits of Entity.updateNumber are the update type: updateNumber & UPDATE_TYPE_MASK
-  // is one of the three values below. UPDATE_TYPE_DELETED means the entity has been deleted, and
-  // an incremental sync out is the only place a client sees one.
+  // The last two bits of Entity.updateNumber: updateNumber & UPDATE_TYPE_MASK is one of these.
+  // UPDATE_TYPE_DELETED marks a tombstone, seen only in an incremental sync out.
   UPDATE_TYPE_MASK = 3;
   UPDATE_TYPE_MAX_VALUE = 3;
   UPDATE_TYPE_CREATED = 1;
@@ -162,24 +148,12 @@ enum Constants {
   ENTITY_ID_UTILITIES = 1;
   ENTITY_ID_UNASSIGNED = 255;
 
-  // The two price lists every business is created with (PriceList.DEFAULT_SALE_PRICE_LIST_ID and
-  // PriceList.DEFAULT_PURCHASE_PRICE_LIST_ID). They are well known rather than assigned, so that
-  // every device computes the same id for them; the ids from 0 to 255 above are reserved for
-  // exactly this.
-  //
-  // A whole entity id does not fit in an enum value, which is 32 bits, so the values below are the
-  // low parts and a client builds each id as
-  //
-  //   id = (PRICE_LIST_ENTITY_TYPE_ID << ENTITY_TYPE_BIT_SHIFT) | value
-  //
-  // using 64 bit arithmetic - BigInt in TypeScript. That gives 4899916394579099648 for the sale
-  // list and 4899916394579099649 for the purchase one (0x4400000000000000 and
-  // 0x4400000000000001).
-  //
-  // A storefront needs the sale one: it is the price list a business sells from unless it has been
-  // given another, and a client that pushes a shopping cart back has to put a price list id in
-  // ShoppingList.priceListId. The purchase list is here only so that a client can recognise the id
-  // and know that it is not a selling price; it is not public, so a storefront is never sent it.
+  // The two price lists every business is created with (PriceList.DEFAULT_SALE_PRICE_LIST_ID /
+  // DEFAULT_PURCHASE_PRICE_LIST_ID), well known rather than assigned. These are the low parts of a
+  // 64 bit id too big for an enum value: id = (PRICE_LIST_ENTITY_TYPE_ID << ENTITY_TYPE_BIT_SHIFT) |
+  // value, using 64 bit arithmetic. The sale list is what a business sells from unless given
+  // another, and what ShoppingList.priceListId must be set to when pushing a cart with none yet; the
+  // purchase list is not public and is never sent, but its id lets a client recognize and ignore it.
   DEFAULT_SALE_PRICE_LIST = 0;
   DEFAULT_PURCHASE_PRICE_LIST = 1;
 
@@ -192,20 +166,16 @@ enum Constants {
   MAX_CLOCK_SKEW = 900000;
 
   // How long before UrlAndToken.expiry the url and token of
-  // BusinessSyncOutResponse.attachmentBaseUrl must be treated as already expired, in milliseconds.
-  // A client stops using them this early so that a url it is about to build cannot expire between
-  // building and fetching, and a server renews them this early so that a client always has a working
-  // one - the margin UrlAndTokenFetcher.isTokenInvalid applies.
+  // BusinessSyncOutResponse.attachmentBaseUrl must be treated as already expired, in milliseconds -
+  // so a client stops using them, and the server renews them, before they actually run out.
   ATTACHMENT_BASE_URL_EXPIRY_MARGIN = 300000;
 
-  // The database id of the server (Database.MASTER_DB_ID), which is what Entity.updateInfo holds
-  // for an entity the server itself last changed. It is not a valid id for a client store, so a
-  // client that keeps one has an id of its own that is never this.
+  // The database id of the server (Database.MASTER_DB_ID); what Entity.updateInfo holds for an
+  // entity the server itself last changed. Never a valid id for a client's own store.
   MASTER_DB_ID = 0;
 
-  // Largest number of entities one sync out returns, in all entity types together
-  // (Database.SYNC_OUT_LIMIT). A client that gets this many must sync out again with the update
-  // numbers it has just received, until it gets fewer.
+  // Largest number of entities one sync out returns, across all entity types together
+  // (Database.SYNC_OUT_LIMIT). That many means sync out again with the updated cursors.
   SYNC_OUT_LIMIT = 5000;
 
   // Entity.state and the Java attribute numbering of an entity. Neither the state nor the

package/CreateUserRequest.proto

@@ -0,0 +1,16 @@
+syntax = "proto3";
+package com.merabills.storefront;
+option java_multiple_files = true;
+option java_package = "com.merabills.server.core.generated";
+
+import "User.proto";
+
+// Creates a new user, optionally joining it to a business as a customer in the same call.
+message CreateUserRequest {
+
+  // The user to create.
+  User user = 1;
+
+  // The business to join as a customer after creating the user. 0 means none.
+  int64 joinBusinessId = 2;
+}

package/Entity.proto

@@ -4,42 +4,28 @@ option java_multiple_files = true;
 option java_package = "com.merabills.server.core.generated";
 
 // Base of most entities in the MeraBills data model.
-// Excluded: propertyBag and state.
-// Not included because they are derived from the fields below: partitionId and the entity type
-// (both encoded in the most significant bits of id), updateType and isDeleted (the last two bits
-// of updateNumber).
+// Excluded: propertyBag, state.
+// Not included because it is derived: partitionId and the entity type (top bits of id), updateType
+// and isDeleted (bottom two bits of updateNumber).
 message Entity {
 
-  // Globally unique id of this entity. The most significant byte holds the entity type.
-  // Ids use the whole 64 bit range: a client must keep them as a string or a big integer, never
-  // as a JavaScript number.
+  // Globally unique id; the most significant byte holds the entity type. Ids use the whole 64 bit
+  // range, so keep them as a string or big integer on the wire, never as a JavaScript number.
   int64 id = 1;
 
-  // Last updated time, in milliseconds since Jan 1, 1970 00:00:00 UTC
+  // Last updated time, in milliseconds since Jan 1, 1970 00:00:00 UTC.
   int64 updatedAt = 2;
 
-  // Id of the database in which this entity was last updated. Constants.MASTER_DB_ID is the
-  // server; a client that keeps a store of its own has a non-zero id, and that id is what it puts
-  // here.
-  //
-  // This is what stops a sync echoing: a sync out compares this against
-  // BusinessSyncOutRequest.clientDatabaseId and does not return the changes that database itself
-  // made, on the assumption that it already has them. So a client sets this on every entity of a
-  // BusinessSyncInRequest, to the same id it sends as clientDatabaseId, and a sync in stores what
-  // arrives - unlike updateNumber, which the receiving database always replaces with one of its
-  // own. A client that leaves it Constants.MASTER_DB_ID is claiming the server made the change,
-  // and will be sent its own writes back on the next sync out.
-  //
-  // Only the entities of a business database carry one - the attachments, configurations, messages
-  // and items. It is 0 on the profile entities of this protocol (User, Business and BusinessLink),
-  // which are never stamped with it, because other profile entity types reuse this column for
-  // something else entirely.
+  // Id of the database that last updated this entity; Constants.MASTER_DB_ID means the server. A
+  // client stamps its own id here on every entity it pushes, so its own writes are not sent back to
+  // it on the next sync out. Only set on business-database entities (Attachment, Configuration,
+  // Message, Item); always 0 on the profile entities User, Business and BusinessLink.
   int64 updateInfo = 3;
 
-  // Monotonically increasing update number - only meaningful within a single database.
-  // The last two bits hold the update type (01 = created, 10 = modified, 11 = deleted).
+  // Monotonically increasing update number, meaningful only within one database. The last two bits
+  // hold the update type (01 = created, 10 = modified, 11 = deleted).
   int64 updateNumber = 4;
 
-  // Creation time, in milliseconds since Jan 1, 1970 00:00:00 UTC
+  // Creation time, in milliseconds since Jan 1, 1970 00:00:00 UTC.
   int64 createdAt = 5;
 }

package/GeneralSettings.proto

@@ -9,9 +9,8 @@ import "FulfillmentMode.proto";
 import "PaymentMethodDetail.proto";
 import "WorkingDays.proto";
 
-// The publicly visible settings of a business: its tagline, how customers can reach it, how orders
-// are fulfilled and how they can be paid for. This is not an entity: it is the value of the public
-// Configuration entity of the business, and it arrives inside one.
+// The publicly visible settings of a business - tagline, contact info, fulfillment and payment
+// options - held in the value of the business's public Configuration entity.
 // Excluded: onlineShoppingEnabled, and the fields of the StoreSettings base class (authToken,
 // authTokenExpiry, lastSuccessfulSync and fees).
 // Not included because it is a constant: overdueAfterMillis.

package/Item.proto

@@ -12,10 +12,8 @@ message Item {
   Entity entity = 1;
 
   // Id of the parent of this item - the category of a product, the product of a package, or the
-  // price list of a price - or 0 when this item has no parent. Nothing nests in this protocol, so
-  // this is how a client rebuilds the catalog: group the products of a BusinessSyncOutResponse by this
-  // id to get the products of each category, and the packages by this id to get the packages of
-  // each product.
+  // price list of a price - or 0 when it has none. A client rebuilds the catalog hierarchy by
+  // grouping items on this id, since nothing nests on the wire.
   int64 parentItemId = 2;
 
   bool isDisabled = 3;

package/Message.proto

@@ -9,17 +9,15 @@ import "PartyPreferencesPayload.proto";
 import "SalesOrderPayload.proto";
 import "TaskStatus.proto";
 
-// A message sent to a business. An order is a message with a SalesOrderPayload; the shopping cart
-// of a customer is a message with a PartyPreferencesPayload.
-// In Java the payload is a serialized string, whose type is determined by messageType; it is typed
-// here. There is no payload for MONEY_TRANSFER messages in this protocol.
+// A message sent to a business: an order (SalesOrderPayload) or a customer's shopping cart
+// (PartyPreferencesPayload), typed here rather than left as the serialized string Java stores.
+// MONEY_TRANSFER messages have no payload in this protocol.
 message Message {
 
   Entity entity = 1;
 
-  // Id of the entity that sent this message - the User of the customer, for anything a storefront
-  // creates. That user is not carried by a business sync out, so a client that needs more than the
-  // id resolves it against a profile sync out, or against senderName and senderPhone below.
+  // Id of the User that sent this message. Not carried by a business sync out - resolve against a
+  // profile sync out, or use senderName / senderPhone below.
   int64 senderId = 2;
 
   MessageType messageType = 3;

package/Package.proto

@@ -8,12 +8,10 @@ import "Item.proto";
 import "PackageIdentifier.proto";
 import "Weight.proto";
 
-// A package (or variant) of a product: a difference in quantity, colour or size - a 500 gram
-// bottle of mango pickle, for example.
-// The product of a package is its Item.parentItemId. A package contains no other entity: its
-// prices are the prices whose packageId is this package, and its photos are the Attachments whose
-// owningEntityId is this package.
-// Excluded: isLowStockWarningEnabled, lowStockLevel, storeProperties and all Translations fields.
+// A package (or variant) of a product - a 500 gram bottle of mango pickle, for example. Its product
+// is Item.parentItemId; its prices are the Price entities whose packageId names it, and its photos
+// are the Attachments whose owningEntityId names it.
+// Excluded: isLowStockWarningEnabled, lowStockLevel, storeProperties, all Translations fields.
 message Package {
 
   // Base class - carries the Entity of this package

package/PartyPreferencesPayload.proto

@@ -7,7 +7,7 @@ import "FulfillmentMode.proto";
 import "ShoppingList.proto";
 
 // The payload of a PARTY_PREFERENCES message: the preferences of a customer of a business,
-// including their shopping cart. In Java the shopping list is held as a serialized string.
+// including their shopping cart.
 // Excluded: serializedUserSettings.
 message PartyPreferencesPayload {
 

package/Price.proto

@@ -6,17 +6,14 @@ option java_package = "com.merabills.server.core.generated";
 import "Item.proto";
 
 // The price of a package. Item.parentItemId is the id of the PriceList this price belongs to.
-// A storefront is sent only the prices of the price list it sells from, and that price list, so
-// every price it receives for a package can be displayed and its list can always be resolved.
-// Not included because it is derived: finalPrice, which is offerPrice when that is greater than
-// zero and less than regularPrice, and regularPrice otherwise.
+// Not included because it is derived: finalPrice (offerPrice when set and less than regularPrice,
+// regularPrice otherwise).
 message Price {
 
   // Base class - carries the Entity of this price
   Item item = 1;
 
-  // Id of the package this price applies to. Nothing nests in this protocol, so this is how a
-  // client finds the prices of a package.
+  // Id of the package this price applies to.
   int64 packageId = 2;
 
   // The price the package is normally sold at, multiplied by Constants.AMOUNT_FACTOR

package/PriceList.proto

@@ -5,25 +5,10 @@ option java_package = "com.merabills.server.core.generated";
 
 import "Item.proto";
 
-// A named list of prices. A price list contains nothing: the prices of a price list are the
-// prices whose Item.parentItemId is this price list. A price list has no parent of its own, so
-// its own Item.parentItemId is 0.
-//
-// A business keeps at least two, created on its first catalog load with the well known ids
-// Constants.DEFAULT_SALE_PRICE_LIST and Constants.DEFAULT_PURCHASE_PRICE_LIST, and may have more.
-// A storefront sells from exactly one of them and is sent only that one, so that no package ever
-// arrives with two prices to choose between; every Price a client receives therefore belongs to
-// the single price list it also receives.
-//
-// This is carried rather than left as the bare Item.parentItemId of a Price for two reasons: a
-// price list has a name, and a client that pushes a shopping cart back has to name the price list
-// its prices came from in ShoppingList.priceListId.
-//
-// Excluded: isPurchasePriceList, which says whether a list holds the prices the business buys at
-// rather than sells at. A purchase price list is not public and its prices are of no use to a
-// customer, so a storefront is never sent one and the flag would always be false (see the
-// visibility flags, which are left out for the same reason). Java keeps it in the packed category
-// short, which is never sent.
+// A named list of prices; has no parent, so its own Item.parentItemId is 0. Contains nothing - its
+// prices are the Price entities whose Item.parentItemId is this price list's id.
+// Excluded: isPurchasePriceList - a purchase price list is never sent, so the flag would always be
+// false.
 message PriceList {
 
   // Base class - carries the Entity of this price list

package/Product.proto

@@ -8,13 +8,11 @@ import "Item.proto";
 import "ProductType.proto";
 import "Tax.proto";
 
-// A product (goods, service, raw material or fixed asset) in the catalog of a business.
-// A product belongs to at most one product category, whose id is Item.parentItemId (0 when it
-// belongs to none). A product contains no other entity: its packages are the packages whose
-// Item.parentItemId is this product, and its photos are the Attachments whose owningEntityId is
-// this product.
+// A product (goods, service, raw material or fixed asset) in the catalog of a business. Belongs to
+// at most one category (Item.parentItemId, 0 = none); its packages and photos are found the same
+// way, by parentItemId / owningEntityId.
 // Excluded: isDraft, forOfflineSaleOnly, isStockKeepingEnabled, isExpiryTrackingEnabled,
-// storeProperties, defaultExpiry, classifications and all Translations fields.
+// storeProperties, defaultExpiry, classifications, all Translations fields.
 message Product {
 
   // Base class - carries the Entity of this product

package/ProductCategory.proto

@@ -5,10 +5,8 @@ option java_package = "com.merabills.server.core.generated";
 
 import "Item.proto";
 
-// A category that groups products of a catalog. Its name is always set.
-// A category contains nothing: the products of a category are the products whose
-// Item.parentItemId is this category. A product belongs to at most one category, and a product
-// whose parentItemId is 0 belongs to none.
+// A category that groups products of a catalog; its name is always set. Contains nothing - its
+// products are those whose Item.parentItemId is this category's id (0 = none).
 message ProductCategory {
 
   // Base class - carries the Entity of this category

package/ProfileSyncOutRequest.proto

@@ -3,40 +3,21 @@ package com.merabills.storefront;
 option java_multiple_files = true;
 option java_package = "com.merabills.server.core.generated";
 
-// A request to sync out the profile of the caller: who they are, which businesses they are linked to,
-// and those businesses. This is what signs an existing user in, and it is incremental, so the request
-// carries a cursor per entity type and the ProfileSyncOutResponse carries only what has changed since.
-//
-// Who is asking is not part of this message: it is in the AuthTokens of the authorization header. That
-// is also why the request names no business - a profile is not scoped to one, and the response is what
-// tells the caller which businesses exist for them.
-//
-// There is one cursor per entity type this reads, and they are exactly the three entity types that
-// Java puts in a profile database (EntityType with DbType.PROFILE that this protocol carries): USER,
-// BUSINESS and BUSINESS_LINK. A business database is read by a BusinessSyncOutRequest instead, and the
-// two sets of cursors never mix - an update number is only comparable within one entity type, and only
-// against the same database.
-//
-// Each cursor below is the highest Entity.updateNumber of that entity type that this client has
-// already synced out. The server sends back the entities of that type whose updateNumber is greater,
-// so a client stores the highest updateNumber it receives per type and sends it back on the next call.
-// Zero, the default, means this client has nothing yet and asks for everything - signing in for the
-// first time therefore leaves every cursor unset.
-//
-// Sync out is bounded: one call returns at most Constants.SYNC_OUT_LIMIT entities across all types
-// together. On receiving that many, a client must call again with its updated cursors until it
-// receives fewer.
+// Signs an existing user in: returns the caller (from the AuthTokens of the authorization header),
+// the businesses they are linked to, and those businesses. Incremental and bounded: each cursor is
+// the highest Entity.updateNumber of that type already synced (0 asks for everything), and a
+// response of Constants.SYNC_OUT_LIMIT entities means call again with the updated cursors.
 message ProfileSyncOutRequest {
 
-  // The caller themselves - entity type Constants.USER_ENTITY_TYPE_ID
+  // Cursor for the caller's own User entity (Constants.USER_ENTITY_TYPE_ID).
   int64 userUpdateNumber = 1;
 
-  // The businesses the caller is linked to - entity type Constants.BUSINESS_ENTITY_TYPE_ID.
-  // A Business is a profile database entity, which is why it is read here and not by a
-  // BusinessSyncOutRequest - that call returns the contents of one business, not the business itself.
+  // Cursor for the Business entities the caller is linked to (Constants.BUSINESS_ENTITY_TYPE_ID).
   int64 businessUpdateNumber = 2;
 
-  // The links between the caller and those businesses, each carrying the token that lets the caller
-  // act against one of them - entity type Constants.BUSINESS_LINK_ENTITY_TYPE_ID
+  // Cursor for the caller's BusinessLink entities (Constants.BUSINESS_LINK_ENTITY_TYPE_ID).
   int64 businessLinkUpdateNumber = 3;
+
+  // The business to join as a customer, if the caller is not already linked to it. 0 means none.
+  int64 joinBusinessId = 4;
 }

package/ProfileSyncOutResponse.proto

@@ -3,62 +3,27 @@ package com.merabills.storefront;
 option java_multiple_files = true;
 option java_package = "com.merabills.server.core.generated";
 
+import "AuthTokens.proto";
 import "Business.proto";
 import "BusinessLink.proto";
 import "User.proto";
 
-// The answer to a ProfileSyncOutRequest: who the caller is, which businesses they are linked to, and
-// those businesses. This is what signs an existing user in - a client calls it with the credentials in
-// the AuthTokens of the authorization header and gets back everything it needs to know about the
-// customer before it reads any one business.
-//
-// This is the other half of the split the business sync messages leave open: a BusinessSyncOutResponse
-// carries what is in a business database and therefore no User and no BusinessLink, and this carries
-// what is in a profile database. Java splits them the same way, into Service.profileSyncOut and
-// Service.businessSyncOut. A Business is a profile database entity and belongs here; it is also
-// carried by a BusinessSyncOutResponse, so that a client that has not signed in can still learn the
-// business it is showing.
-//
-// How a client uses it:
-//   1. user            who the caller is, and the addresses an order can be delivered to
-//   2. businessLinks   one per business the caller is linked to. Each names its business in
-//                      BusinessLink.businessId and carries the BusinessLink.linkToken that goes into
-//                      AuthTokens.linkToken of every later request about that business.
-//   3. businesses      the businesses those links name, so that a client can show the caller a list
-//                      of shops without a call per shop. Match BusinessLink.businessId against
-//                      Business.entity.id, not against Business.businessId.
-// Nothing is nested, for the same reason nothing is nested in a business sync out: a link and the
-// business it names change independently, so a tree could not say which of them a response is
-// reporting.
-//
-// Every field is optional, as follows. A signed in caller whose profile has not changed gets a
-// response with nothing in it at all, which is valid and means "nothing new".
-// - user is a singular message field, so it has explicit presence: absent means the profile of the
-//   caller has not changed, not that there is no caller.
-// - businessLinks and businesses are repeated, and a proto3 repeated field cannot be marked optional
-//   because it has no presence of its own. An empty array is the absent state, and means no link or
-//   no business has changed - it never means the caller has none. Only an arriving entity, or a
-//   tombstone, changes what a client holds.
-//
-// A tombstone works as it does in a business sync out: an entity whose
-// (updateNumber & Constants.UPDATE_TYPE_MASK) equals Constants.UPDATE_TYPE_DELETED has been deleted,
-// only its Entity is meaningful, and a deleted BusinessLink means the caller may no longer reach that
-// business and its link token must be discarded.
-//
-// This sync out is incremental and bounded, exactly as the business one is: ProfileSyncOutRequest
-// carries a cursor for each of the three entity types below, and one response returns at most
-// Constants.SYNC_OUT_LIMIT entities across all three together. A client that receives that many
-// raises each cursor to the highest updateNumber it has seen for that type and requests again, until
-// it receives fewer. The response carries no cursors of its own: a client computes them from the
-// entities it receives.
+// The answer to a ProfileSyncOutRequest: who the caller is, the businesses they are linked to, and
+// those businesses. Nothing is nested - match BusinessLink.businessId against Business.entity.id.
+// Every field is absent/empty unless that type has changed; a tombstone (updateNumber's update-type
+// bits = Constants.UPDATE_TYPE_DELETED) means the entity, and what it owned, was deleted.
 message ProfileSyncOutResponse {
 
+  // The tokens to send with the next request, when the server has renewed one of them. Absent means
+  // what the client already holds still works - never a signal to drop the tokens it has.
+  optional AuthTokens authTokens = 1;
+
   // The caller. Absent unless their own profile has changed.
-  User user = 1;
+  User user = 2;
 
   // The businesses the caller is linked to, and the token for each. Empty unless a link has changed.
-  repeated BusinessLink businessLinks = 2;
+  repeated BusinessLink businessLinks = 3;
 
-  // The businesses that the links above name. Empty unless a business has changed.
-  repeated Business businesses = 3;
+  // The businesses those links name. Empty unless a business has changed.
+  repeated Business businesses = 4;
 }

package/ReservedPackage.proto

@@ -3,21 +3,9 @@ package com.merabills.storefront;
 option java_multiple_files = true;
 option java_package = "com.merabills.server.core.generated";
 
-// The packages reserved for the charge and summary lines of a shopping list. A ShoppingListItem
-// whose packageId is one of these is not a catalog package and will never be found in the catalog:
-// it carries a charge, a discount or the list total, and a client must label it itself.
-//
-// A reserved package id does not fit in an enum value, which is 32 bits, so the value below is the
-// low part of the id and a client builds the whole id as
-//
-//   id = (Constants.PACKAGE_ENTITY_TYPE_ID << Constants.ENTITY_TYPE_BIT_SHIFT) | value
-//
-// using 64 bit arithmetic - BigInt in TypeScript. The four ids that produces are
-// 4611686018427387904, 4611686018427387905, 4611686018427387906 and 4611686018427387907
-// (0x4000000000000000 to 0x4000000000000003). Conversely, a packageId is a reserved package when
-// its low 56 bits are less than or equal to SERVICE_CHARGE_PACKAGE.
-//
-// This is a carrier for constants, not the type of any field, so zero being a real value is safe.
+// The packages reserved for the charge and summary lines of a shopping list; not catalog packages,
+// so a client must label them itself. Each value is the low part of the actual 64 bit package id:
+// id = (Constants.PACKAGE_ENTITY_TYPE_ID << Constants.ENTITY_TYPE_BIT_SHIFT) | value (BigInt math).
 enum ReservedPackage {
 
   // The total of the shopping list. Present only in a list a merchant has laid out for display;

package/Role.proto

@@ -3,18 +3,9 @@ package com.merabills.storefront;
 option java_multiple_files = true;
 option java_package = "com.merabills.server.core.generated";
 
-// What an entity linked to a business may do with it. This is the role of a BusinessLink.
-//
-// The values are the ids of the Java Role entries and must never change. Each is built from a group
-// and a role within that group, (groupId << 6) | roleId, so they are not consecutive: the group is
-// the upper bits and, within a group, a higher value means fewer rights. The groups are
-// 0 owner, 1 employee, 2 vendor, 3 customer, 4 partner and 63 other. A client that only needs to
-// know which group a role is in can compute it as (role >> 6); a client that needs the actual rights
-// cannot, because the rights are not on the wire.
-//
-// A storefront customer is normally CUSTOMER. The other values are here so that a role a storefront
-// does not expect maps to a name rather than to a number, and so that the numbering cannot drift
-// from Java by having gaps filled in later.
+// What an entity linked to a business may do with it - the role of a BusinessLink. Values are
+// computed ids ((groupId << 6) | roleId), not ordinals, and must never change; a client can recover
+// the group with (role >> 6) but not the rights, which are not on the wire.
 enum Role {
 
   // Owner group. Only a user can be in one of these roles.

package/SalesOrderPayload.proto

@@ -7,10 +7,9 @@ import "FulfillmentMode.proto";
 import "OrderStatus.proto";
 import "ShoppingList.proto";
 
-// The payload of a SALES_ORDER message: an order placed by a customer.
-// Excluded: serviceStationNumber and dueDate.
-// Payments made against an order are not part of this payload - they are payment transactions
-// whose parent is the income transaction of the order.
+// The payload of a SALES_ORDER message: an order placed by a customer. Payments made against it are
+// not part of this payload.
+// Excluded: serviceStationNumber, dueDate.
 message SalesOrderPayload {
 
   OrderStatus status = 1;

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