@peabody-soft/mbs-protos 1.1.0 → 1.3.0

package/Attachment.proto

@@ -7,33 +7,19 @@ import "AttachmentType.proto";
 import "Entity.proto";
 
 // A file (a photo of a business, product or package, for example) attached to an entity.
-// Excluded: isPublic, isReadyForSync and isProcessingComplete.
-// Not included because it is derived: storageFileName, the name the file is stored under. A client
-// needs it to fetch the file, so here is exactly how Attachment.getStorageFileName builds it, from
-// the createdAt of this entity, its id, its fileHash and its fileExtension:
-//
-//   "%04d-%02d-%02d-%016X-%s.%s"  (Java Attachment.ATTACHMENT_FILE_NAME_FORMAT)
-//
-//   year, month and day  the createdAt of this entity, read in UTC. The month is the one
-//                        java.util.Calendar gives and is therefore zero based: January is 00 and
-//                        December is 11, so a file created in September 2026 is stored under
-//                        "2026-08-...". Both ends of the protocol do this, so a client must too.
-//   id                   Entity.id, 16 upper case hex digits, zero padded, with no 0x prefix
-//   fileHash             the 16 bytes of fileHash as 32 upper case hex digits
-//   fileExtension        appended after a dot, as it is
-//
-// The case matters: a blob name is case sensitive. The whole name is one flat name, not a path -
-// see UrlAndToken for how a url is built from it.
+// Excluded: isPublic, isReadyForSync, isProcessingComplete.
+// Not included because it is derived: storageFileName, built as "%04d-%02d-%02d-%016X-%s.%s" from
+// this entity's createdAt (UTC, zero based month - September is 08), id (16 upper case hex digits),
+// fileHash (32 upper case hex digits) and fileExtension. Case sensitive; see UrlAndToken for the url.
 message Attachment {
 
   Entity entity = 1;
 
-  // Exposed instead of the raw type id held in the category of this attachment
+  // The type id, exposed instead of the raw value packed into this attachment's category.
   AttachmentType attachmentType = 2;
 
-  // Id of the entity this file is attached to - a business, a product or a package in this
-  // protocol. Nothing nests here, so this is how a client finds the photos of an entity. The
-  // entity type of the owner is the most significant byte of this id (see Constants).
+  // Id of the entity this file is attached to - a business, product or package. The most
+  // significant byte of this id is the owner's entity type (see Constants).
   int64 owningEntityId = 3;
 
   // MD5 hash of the attached file, exactly Constants.ATTACHMENT_FILE_HASH_SIZE_BYTES bytes long.

package/AuthTokens.proto

@@ -5,47 +5,25 @@ option java_package = "com.merabills.server.core.generated";
 
 import "AuthenticationMethod.proto";
 
-// The tokens that prove who is making a request. This is serialized into the authorization header
-// of every request, the way ServiceProxy.setAuthorizationHeader serializes the Java AuthTokens, so
-// it is a credential envelope rather than part of the entity model and never appears in a body.
-//
-// The three tokens answer different questions: authenticationToken says which person is calling,
-// userToken says which MeraBills user that person is, and linkToken says which business they may
-// act against. They are parsed in that order and the first is a prerequisite for the second, so a
-// userToken is never trusted on its own (Authority.parseUserToken parses the authentication token
-// first). A storefront acquires them in that order too - it signs in with an identity provider,
-// exchanges that for a user token by calling the profile sync out, and gets a link token per
-// business from the BusinessLinks that call returns.
-//
-// Not included because the server derives it: the subject id, and the phone number, which
-// Authority.parseAuthenticationToken reads out of authenticationToken rather than trusting a field.
-// A client that knows its own subject id has no reason to send it, and no way to be believed if it
-// did.
-//
-// Every value here is a bearer credential: never log one, never put one in a url, and hold them
-// only for as long as the session lasts.
+// The tokens that prove who is making a request. Serialized into the authorization header of every
+// request, never into a body; every value is a bearer credential - never log or url-encode one.
+// Not included because the server derives it: the subject id and phone number, parsed by the server
+// out of authenticationToken rather than trusted from a field.
 message AuthTokens {
 
   // Which identity provider issued authenticationToken, and so how the server parses it. Always
-  // set - it selects the parser, and a request whose method has none is refused. There is no
-  // unspecified value, because zero is FIREBASE.
+  // set; there is no unspecified value because zero is FIREBASE.
   AuthenticationMethod authenticationMethod = 1;
 
   // The credential from that identity provider - a Firebase id token when the method is FIREBASE.
-  // Always set: every request is parsed for a subject, so there is no anonymous form of this
-  // message. This is not issued by this server, and this server does not renew it; a client
-  // refreshes it with its identity provider.
+  // Always set. Not issued or renewed by this server; refreshed with the identity provider.
   string authenticationToken = 2;
 
-  // Token proving which MeraBills user the subject is, issued and signed by this server, carrying
-  // the user id and the rights of the caller. Absent until a client has called the profile sync out
-  // once, and again once it expires, at which point a client calls that again to be given another
-  // rather than deriving one.
+  // Token proving which MeraBills user the subject is, issued and signed by this server. Absent
+  // until the profile sync out has been called once, and again once it expires.
   optional string userToken = 3;
 
-  // Token authorizing the caller to act against one business - the BusinessLink.linkToken of that
-  // business, which a ProfileSyncOutResponse carries. Absent for a request that names no business,
-  // required for one that does. It is per business, so a client that shows two businesses holds one
-  // of these for each and sends the one that matches the request.
+  // Token authorizing the caller against one business - the BusinessLink.linkToken of that
+  // business. Absent for a request that names no business, required for one that does.
   optional string linkToken = 4;
 }

package/AuthenticationMethod.proto

@@ -10,10 +10,8 @@ option java_package = "com.merabills.server.core.generated";
 // always set, so a client never needs one.
 enum AuthenticationMethod {
 
-  // The authentication token is a Firebase id token, and the subject id the server reads out of it
-  // is a Firebase uid, which is not the same thing as the MeraBills User.entity.id. The userToken
-  // of an AuthTokens is not a Firebase token - it is issued by this server, whatever method
-  // authenticated the subject.
+  // The authentication token is a Firebase id token; the subject id parsed from it is a Firebase
+  // uid, not the same thing as User.entity.id.
   FIREBASE = 0;
 
   // Reserved for internal administrative callers. A storefront never uses this method.

package/Business.proto

@@ -5,15 +5,11 @@ option java_package = "com.merabills.server.core.generated";
 
 import "Entity.proto";
 
-// A business that a customer can buy from.
-// A business contains no other entity: its settings arrive as a Configuration, its photos as
-// Attachments whose owningEntityId is this business, and its catalog as the item entities of a
-// BusinessSyncOutResponse.
-// This is a profile database entity, so it is carried by a ProfileSyncOutResponse - one per business
-// the caller is linked to. A BusinessSyncOutResponse carries it as well, for the one business it is
-// about, because a client that has not signed in has no profile sync out to read it from.
-// Excluded: category (and the BusinessType derived from it), displayNameOld,
-// allowJoinWithoutInvitation, forTraining and all Translations fields.
+// A business that a customer can buy from. Contains no other entity: settings arrive as a
+// Configuration, photos as Attachments whose owningEntityId is this business, and the catalog as
+// the item entities of a BusinessSyncOutResponse.
+// Excluded: category (and the derived BusinessType), displayNameOld, allowJoinWithoutInvitation,
+// forTraining, all Translations fields.
 message Business {
 
   Entity entity = 1;

package/BusinessLink.proto

@@ -6,32 +6,21 @@ option java_package = "com.merabills.server.core.generated";
 import "Entity.proto";
 import "Role.proto";
 
-// Associates an entity - a user or a business - with a business, in a particular role. This is what
-// tells a signed in customer which businesses they are a customer of, and it carries the token that
-// lets them act against each one.
-//
-// A business link lives in a profile database, alongside the User and the Business entities it names,
-// so it is carried by a ProfileSyncOutResponse and never by a BusinessSyncOutResponse.
-//
-// Excluded: invitationDetails - the name of the inviter, the note they wrote and the rest of it are
-// about accepting an invitation, which is not part of a storefront.
-// Not included because they are derived from expiry: isExpirySet and hasExpired.
+// Associates an entity - a user or a business - with a business, in a role, and carries the token
+// that lets it act against that business. Lives in a profile database; carried by a
+// ProfileSyncOutResponse, never by a BusinessSyncOutResponse.
+// Excluded: invitationDetails.
+// Not included because it is derived from expiry: isExpirySet, hasExpired.
 message BusinessLink {
 
   Entity entity = 1;
 
-  // Id of the entity this link is for: a user or a business, and nothing else. The entity type is
-  // the most significant byte of this id (Constants.USER_ENTITY_TYPE_ID or
-  // Constants.BUSINESS_ENTITY_TYPE_ID), which is how a client tells the two apart. For a storefront
-  // this is the User of the caller.
+  // Id of the entity this link is for - a user or a business. The most significant byte of this id
+  // (Constants.USER_ENTITY_TYPE_ID or Constants.BUSINESS_ENTITY_TYPE_ID) says which.
   int64 linkedEntityId = 2;
 
-  // Id of the business this link is to.
-  //
-  // This is an entity id, so it matches Business.entity.id - not Business.businessId, which is the
-  // lower case url friendly string a storefront is reached by. The Java accessors are both called
-  // getBusinessId and return different things (a long here, a String on Business), so this is easy to
-  // get wrong.
+  // Id of the business this link is to - an entity id, matching Business.entity.id, not
+  // Business.businessId (the url friendly string).
   int64 businessId = 3;
 
   // What the linked entity may do with the business. A storefront customer is normally
@@ -39,21 +28,14 @@ message BusinessLink {
   Role role = 4;
 
   // Id of the party record of the linked entity within that business, or Constants.ENTITY_ID_NULL
-  // when there is none. A Party is not generated by this protocol, so this id cannot be resolved by
-  // a storefront; it is here because it is a field of the Java class and because the server needs it.
-  // Every role outside the partner group has one.
+  // when there is none. Not resolvable by a storefront - Party is not generated by this protocol.
   int64 partyId = 5;
 
-  // Token proving that the linked entity may act against this business. This is what goes into
-  // AuthTokens.linkToken of every later request that names the business.
-  //
-  // It is a bearer credential: never log it, never put it in a URL, and never show it to anyone but
-  // the entity it was issued to. It is not one of the stored attributes of the entity - the server
-  // issues it - so a link that arrives without one cannot be used to reach the business.
+  // Bearer credential proving the linked entity may act against this business - goes into
+  // AuthTokens.linkToken of every later request naming it. Never log it or put it in a url.
   optional string linkToken = 6;
 
-  // Time after which this link is no longer valid, in milliseconds since Jan 1, 1970 00:00:00 UTC.
-  // BusinessLink.NO_EXPIRY (0) means it does not expire. A client must compare this against its own
-  // clock, so allow for Constants.MAX_CLOCK_SKEW before deciding a link has expired.
+  // Time this link stops being valid, in milliseconds since Jan 1, 1970 00:00:00 UTC.
+  // 0 (BusinessLink.NO_EXPIRY) means it never expires; allow for Constants.MAX_CLOCK_SKEW.
   int64 expiry = 7;
 }

package/BusinessSyncInRequest.proto

@@ -5,38 +5,18 @@ option java_package = "com.merabills.server.core.generated";
 
 import "Message.proto";
 
-// A request to sync in the entities a customer has changed: their shopping cart, and the orders
-// they place from it. This is the counterpart of BusinessSyncOutRequest and mirrors the Java sync in
-// (Service.businessSyncIn, which takes the Entity[][] that BusinessDb.syncInToMaster authorizes a
-// table at a time): entities travel flat, one array per entity type, and nothing is nested.
-//
-// This writes one business database, which is what it is named after. A message is a business entity
-// even though the customer sent it, so the cart and the orders belong here; the profile of the
-// customer does not, and is written by a sync in of its own.
-//
-// Who is asking is not part of this message: it is in the AuthTokens of the authorization header. The
-// server authorizes each array against the rights of that caller - messages against
-// Right.MESSAGES_MODIFY - so a client cannot push an entity type it has no right to, and a
-// storefront customer may push only their own messages.
-//
-// An entity being synced in carries the id it already has, or Constants.ENTITY_ID_NULL when the
-// client is creating it and the server is to assign one. The update numbers of the incoming
-// entities are the client's own and are not comparable with the server's: the server assigns new
-// ones and returns them in the BusinessSyncInResponse.
+// Pushes the business entities a customer has changed - their shopping cart and the orders placed
+// from it - to one business database, named the same way a BusinessSyncOutRequest names it.
+// An entity being synced in carries the id it already has, or Constants.ENTITY_ID_NULL if the
+// caller is creating it and the server is to assign one; incoming update numbers are the caller's
+// own and are replaced by the server, which returns the new ones in the BusinessSyncInResponse.
 message BusinessSyncInRequest {
 
-  // The business these entities belong to, named by its unique, lower case, url friendly id - the
-  // same Business.businessId that BusinessSyncOutRequest names
-  // (Constants.BUSINESS_ID_MIN_LENGTH to Constants.BUSINESS_ID_MAX_LENGTH)
+  // The business these entities belong to - its unique, lower case, url friendly id
+  // (Constants.BUSINESS_ID_MIN_LENGTH to Constants.BUSINESS_ID_MAX_LENGTH).
   string businessId = 1;
 
-  // The shopping cart of the customer (a message whose payload is a PartyPreferencesPayload) and
-  // the orders they place (a payload of SalesOrderPayload) - entity type
-  // Constants.MESSAGE_ENTITY_TYPE_ID.
-  //
-  // This is the only entity type a storefront may push. A customer does not edit the business, its
-  // settings, its catalog or its photos, and their own User lives in a profile database that this
-  // call does not touch - so there is deliberately no field for any of those types here, rather
-  // than a field the server would reject.
+  // The shopping cart (a PartyPreferencesPayload) and orders (a SalesOrderPayload) of the customer -
+  // entity type Constants.MESSAGE_ENTITY_TYPE_ID, the only entity type a customer may push.
   repeated Message messages = 2;
 }

package/BusinessSyncInResponse.proto

@@ -3,21 +3,19 @@ package com.merabills.storefront;
 option java_multiple_files = true;
 option java_package = "com.merabills.server.core.generated";
 
-// The answer to a BusinessSyncInRequest: the update number the server assigned to the entities that
-// were pushed, one per entity type, the way Java sync in returns the long[] of max incoming update
-// numbers that BusinessDb.syncIn produces, indexed by table entity type id.
-//
-// A client raises its cursor for that entity type to the number below, so that the next
-// BusinessSyncOutRequest does not fetch back what it has just sent. Zero means nothing of that type
-// was accepted, which is what a request that carried none of them gets back.
-//
-// This response carries no entities. A client that needs the server's view of what it pushed - the
-// id assigned to an entity the server created, or the authoritative totals of a shopping list,
-// which are computed with the rounding rules of PriceCalculation - syncs out again afterwards.
+import "AuthTokens.proto";
+
+// The answer to a BusinessSyncInRequest: the update number the server assigned to the pushed
+// entities, one per entity type. Raise the matching cursor to this value so the next sync out does
+// not fetch back what was just sent; 0 means nothing of that type was accepted. Carries no entities
+// - sync out again to see the server's view of what was pushed.
 message BusinessSyncInResponse {
 
-  // The highest update number the server assigned to the messages of the request - entity type
-  // Constants.MESSAGE_ENTITY_TYPE_ID. There is one field per entity type that
-  // BusinessSyncInRequest can carry, and messages are the only one.
-  int64 messageUpdateNumber = 1;
+  // 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;
+
+  // Highest update number assigned to the messages of the request - entity type
+  // Constants.MESSAGE_ENTITY_TYPE_ID, the only entity field this response carries.
+  int64 messageUpdateNumber = 2;
 }

package/BusinessSyncOutRequest.proto

@@ -3,98 +3,40 @@ package com.merabills.storefront;
 option java_multiple_files = true;
 option java_package = "com.merabills.server.core.generated";
 
-// A request to sync out everything a storefront needs of one business: the Business, its settings, its
-// catalog and the messages of the customer. This is an incremental sync, so the request carries a
-// cursor per entity type and the BusinessSyncOutResponse carries only what has changed since, flat,
-// for the client to reassemble.
-//
-// This reads one business database, which is why there is no cursor for the User of the caller and no
-// User in the response: a user lives in a profile database and is read by a ProfileSyncOutRequest, the
-// way Java splits Service.businessSyncOut from Service.profileSyncOut.
-//
-// A Business is a profile database entity too, but it is carried here as well, because a client that
-// has not signed in has no profile sync out to read it from and would otherwise not know the name or
-// the country of the business it is showing. So businessUpdateNumber below and
-// ProfileSyncOutRequest.businessUpdateNumber are cursors over the same entity type kept by two
-// different calls: a client keeps one per call and must not carry a number from one over to the other.
-//
-// Who is asking is not part of this message: it is in the AuthTokens of the authorization header,
-// whose linkToken is the BusinessLink.linkToken of the business named below.
-//
-// The store it is asking on behalf of is, in clientDatabaseId below. A storefront keeps a
-// persistent store, so it is a database in the sync topology and has an id of its own, and the
-// server needs that id to know which changes not to send back. This is the requestingDbId argument
-// of Service.businessSyncOut, which the Java clients pass as the db-id query parameter
-// (HttpQueryParameters.DATABASE_ID) rather than in the body; a storefront carries it here instead,
-// so that one protobuf message says everything a sync out needs.
-//
-// 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 -
-// a first sync therefore leaves every cursor unset.
-//
-// One field below is not a cursor: attachmentBaseUrlExpiry is a time, and it asks for a value rather
-// than for entities. It is here because the files of the attachments of a business are read from a
-// url that expires, and renewing it in this call costs nothing, where a call of its own would cost a
-// round trip on every sync.
-//
-// 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.
-//
-// There is one cursor per entity type that has a table of its own, which is how updateNumbers are
-// kept, and not one per class: the product categories, products, packages, price lists and prices
-// of a catalog are all item entities and all share itemUpdateNumber. Update numbers are only
-// comparable within one entity type, and only against the same server.
+// Reads everything a storefront needs of one business: the Business, its settings, catalog and
+// messages, flat for the client to reassemble. 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. The caller and the
+// business's link token are in the AuthTokens of the authorization header, not in this message.
 message BusinessSyncOutRequest {
 
-  // The business to sync out, named by its unique, lower case, url friendly id - the same
-  // Business.businessId that the storefront was reached by
-  // (Constants.BUSINESS_ID_MIN_LENGTH to Constants.BUSINESS_ID_MAX_LENGTH)
+  // The business to sync out, by its unique, lower case, url friendly id (Constants.BUSINESS_ID_MIN_LENGTH
+  // to Constants.BUSINESS_ID_MAX_LENGTH).
   string businessId = 1;
 
-  // Id of the store this client keeps, which is what makes an incremental sync out incremental in
-  // both directions: the server compares it against the Entity.updateInfo of every candidate
-  // entity and leaves out the ones this client wrote itself, because it already has them.
-  //
-  // A client generates this once and keeps it for the life of its store. It is never
-  // Constants.MASTER_DB_ID, which is the server, and never a reserved id, so a client that sends
-  // zero is claiming to be the server and will be sent its own writes back on every sync.
-  //
-  // The same value goes into the Entity.updateInfo of everything this client pushes in a
-  // BusinessSyncInRequest. There is no such field on that request, because there the id arrives on
-  // each entity instead.
+  // Id of the store this client keeps; never Constants.MASTER_DB_ID or another reserved id. The
+  // server leaves out entities whose Entity.updateInfo matches this, so a client does not get its
+  // own writes back, and this same id goes into every entity a client pushes in a BusinessSyncInRequest.
   int64 clientDatabaseId = 2;
 
-  // The business - entity type Constants.BUSINESS_ENTITY_TYPE_ID
+  // Cursor for the Business entity (Constants.BUSINESS_ENTITY_TYPE_ID). Separate from, and never
+  // mixed with, ProfileSyncOutRequest.businessUpdateNumber.
   int64 businessUpdateNumber = 3;
 
-  // The photos of the business, its products and its packages - entity type
-  // Constants.ATTACHMENT_ENTITY_TYPE_ID
+  // Cursor for photos of the business, its products and its packages (Constants.ATTACHMENT_ENTITY_TYPE_ID).
   int64 attachmentUpdateNumber = 4;
 
-  // The expiry of the attachment base url and token this client is holding - the UrlAndToken.expiry
-  // of the last BusinessSyncOutResponse.attachmentBaseUrl it received, sent back unchanged. Zero,
-  // the default, means this client holds none and is asking for one, which is what a first sync
-  // does.
-  //
-  // The server answers with a new attachmentBaseUrl when this is zero, or within
-  // Constants.ATTACHMENT_BASE_URL_EXPIRY_MARGIN of the time it reads the request, and leaves it
-  // absent otherwise. This is a time and not an update number: it is not comparable with the cursors
-  // around it, it does not rise monotonically, and a client must never derive it from anything but
-  // the UrlAndToken it holds.
+  // The UrlAndToken.expiry of the attachment base url this client is holding, sent back unchanged;
+  // 0 means it holds none. A time, not a cursor - it does not rise monotonically.
   int64 attachmentBaseUrlExpiry = 5;
 
-  // The settings of the business, which are held in a configuration entity - entity type
-  // Constants.CONFIGURATION_ENTITY_TYPE_ID
+  // Cursor for the business's settings (Constants.CONFIGURATION_ENTITY_TYPE_ID).
   int64 configurationUpdateNumber = 6;
 
-  // The orders of the customer and their shopping cart - entity type
-  // Constants.MESSAGE_ENTITY_TYPE_ID
+  // Cursor for the customer's orders and shopping cart (Constants.MESSAGE_ENTITY_TYPE_ID).
   int64 messageUpdateNumber = 7;
 
-  // The whole catalog: product categories, products, packages, price lists and prices, which are
-  // all item entities and share this one cursor - entity type Constants.ITEM_ENTITY_TYPE_ID
+  // Cursor for the whole catalog - product categories, products, packages, price lists and prices,
+  // which all share this one cursor (Constants.ITEM_ENTITY_TYPE_ID).
   int64 itemUpdateNumber = 8;
 }

package/BusinessSyncOutResponse.proto

@@ -4,6 +4,7 @@ option java_multiple_files = true;
 option java_package = "com.merabills.server.core.generated";
 
 import "Attachment.proto";
+import "AuthTokens.proto";
 import "Business.proto";
 import "Configuration.proto";
 import "Message.proto";
@@ -14,96 +15,44 @@ import "Product.proto";
 import "ProductCategory.proto";
 import "UrlAndToken.proto";
 
-// The answer to a BusinessSyncOutRequest: the entities of one business that have changed since the
-// update numbers the request carried, one field per entity type, the way Database.syncOut returns its
-// two dimensional array of entities. Nothing is nested, and no entity contains another, because an
-// incremental sync sends only what changed - a tree could not say which of its collections are
-// complete, where a deleted entity belongs, or that a product has moved to another category.
-//
-// The five repeated item types, the attachments, the configurations and the messages are what Java
-// keeps in a business database (EntityType with DbType.BUSINESS). The Business below is not: like the
-// User and the BusinessLink, it is a profile database entity. It is carried here anyway, because a
-// client that has not signed in has no profile sync out to read it from and would otherwise not know
-// the name or the country of the business it is showing. The User and the BusinessLink are not, because
-// an anonymous client has neither.
-//
-// A type of which there can only ever be one is a single message rather than an array, so that its
-// presence carries the same "changed or not" information an array carries by being empty: the
-// request names one business.
-//
-// Every field below is an entity of that business except one: attachmentBaseUrl is a value, and the
-// only thing here that a client does not put in its cache and does not count against
-// Constants.SYNC_OUT_LIMIT. It answers BusinessSyncOutRequest.attachmentBaseUrlExpiry rather than an
-// update number, it can never be a tombstone, and it says where the files of the attachments are
-// rather than what has changed.
-//
-// A client reconstructs the hierarchy itself, from the ids the entities carry:
-//   Business             the business the request named
-//   Configuration        its settings, by Entity.id
-//   Attachment           its owner is owningEntityId - a business, a product or a package. Its
-//                        file is under attachmentBaseUrl, under the storage file name that
-//                        Attachment says how to build.
-//   Message              its sender is senderId, which names a User of the profile database
-//   ProductCategory      a category of the catalog
-//   Product              its category is Item.parentItemId, or none when that is 0
-//   Package              its product is Item.parentItemId
-//   PriceList            the price list the business sells from. It has no parent, and there is
-//                        only ever one of it in a response.
-//   Price                its package is packageId; its price list is Item.parentItemId
-// Process the arrays in the order they are declared below: a parent always arrives in an earlier
-// array than its children, so nothing has to be resolved twice.
-//
-// An entity may be a tombstone rather than a value: when
-// (updateNumber & Constants.UPDATE_TYPE_MASK) == Constants.UPDATE_TYPE_DELETED the entity has been
-// deleted and the client must drop it and everything it owned. Only the Entity of a tombstone is
-// meaningful.
-//
-// An entity type that has not changed is simply absent - an empty array, or an unset business.
-// Absence says nothing about the entities of that type a client already holds; only an entity that
-// arrives, or a tombstone, changes anything. So a client keeps its previous update number for an
-// absent type.
-//
-// One response carries at most Constants.SYNC_OUT_LIMIT entities across all arrays together. On
-// receiving that many, a client raises each update number to the highest it has seen for that type
-// and requests again, until it receives fewer.
-//
-// Java keys its array of arrays by table entity type id. The five item types below share the item
-// table, and therefore BusinessSyncOutRequest.itemUpdateNumber, but are separate arrays here because a
-// protobuf repeated field cannot hold a mixture of types.
+// The answer to a BusinessSyncOutRequest: the entities of one business that changed since the
+// request's update numbers, one field per entity type, flat - a client rebuilds the hierarchy from
+// Item.parentItemId, Attachment.owningEntityId and Price.packageId, processing the arrays below in
+// order (parent before child). An absent/empty field means that type has not changed; a tombstone
+// (updateNumber's update-type bits = Constants.UPDATE_TYPE_DELETED) means the entity, and what it
+// owned, was deleted. At most Constants.SYNC_OUT_LIMIT entities arrive together - that many means
+// call again with the raised cursors.
 message BusinessSyncOutResponse {
 
-  // The business named by the request. Absent unless it has changed. Also carried, along with the
-  // links to it, by a ProfileSyncOutResponse - the same entity from two calls, each with its own
-  // cursor.
-  Business business = 1;
+  // 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;
 
-  // Photos of the business, its products and its packages
-  repeated Attachment attachments = 2;
+  // The business named by the request. Absent unless it has changed. Also carried by a
+  // ProfileSyncOutResponse, with its own separate cursor - keep the two update numbers apart.
+  Business business = 2;
 
-  // Where the files of those photos are, and the token that authorizes reading them.
-  //
-  // Absent when the expiry in BusinessSyncOutRequest.attachmentBaseUrlExpiry is still further away
-  // than Constants.ATTACHMENT_BASE_URL_EXPIRY_MARGIN, which means the one the client holds is good
-  // and is to be kept. So, unlike an absent entity array, absence here is not "nothing changed" but
-  // "what you have still works". A client that holds none sends zero and always gets one back.
-  //
-  // This is not per attachment: one container holds the files of every attachment of the business,
-  // so one of these serves the whole response and every attachment already cached. A client
-  // therefore stores it once, against the business, and not against a photo.
-  UrlAndToken attachmentBaseUrl = 3;
+  // Photos of the business, its products and its packages.
+  repeated Attachment attachments = 3;
+
+  // Where the files of every attachment of the business are, and the token that authorizes reading
+  // them - one value for the whole business, not per photo. Absent means what the client already
+  // holds still works; a client holding none sends 0 and always gets one back. Never a tombstone and
+  // never counted against Constants.SYNC_OUT_LIMIT.
+  UrlAndToken attachmentBaseUrl = 4;
 
   // The settings of the business. An array because a business can have more than one public
   // configuration, even though only the general settings are typed today.
-  repeated Configuration configurations = 4;
+  repeated Configuration configurations = 5;
 
   // The orders of the customer, and their shopping cart
-  repeated Message messages = 5;
+  repeated Message messages = 6;
 
   // Item entities, in the order a client needs them: a category before its products, a product
   // before its packages, and both a package and a price list before the prices that name them
-  repeated ProductCategory productCategories = 6;
-  repeated Product products = 7;
-  repeated Package packages = 8;
-  repeated PriceList priceLists = 9;
-  repeated Price prices = 10;
+  repeated ProductCategory productCategories = 7;
+  repeated Product products = 8;
+  repeated Package packages = 9;
+  repeated PriceList priceLists = 10;
+  repeated Price prices = 11;
 }

package/Configuration.proto

@@ -6,13 +6,10 @@ option java_package = "com.merabills.server.core.generated";
 import "Entity.proto";
 import "GeneralSettings.proto";
 
-// A setting of a business, and its value. In Java the value is a serialized string whose meaning is
-// determined by the id of the configuration; it is typed here, the same way a Message payload is.
-//
-// Which configuration this is is its Entity.id. Only public configurations - those with an id at or
-// above Configuration.MIN_PUBLIC_CONFIGURATION_ID - are ever sent to a storefront, and of those
-// only the general settings, whose id is 0x0D10000000000000 (941252322120433664). A client does not
-// need that id: it switches on which member of data is set.
+// A setting of a business, identified by Entity.id, with its value typed here rather than left as
+// the serialized string Java stores. Only public configurations (id at or above
+// Configuration.MIN_PUBLIC_CONFIGURATION_ID) are ever sent; a client switches on which member of
+// data is set rather than checking the id.
 message Configuration {
 
   Entity entity = 1;