@peabody-soft/mbs-protos 1.0.0

package/BusinessSyncOutResponse.proto

@@ -0,0 +1,109 @@
+syntax = "proto3";
+package com.merabills.storefront;
+option java_multiple_files = true;
+option java_package = "com.merabills.server.core.generated";
+
+import "Attachment.proto";
+import "Business.proto";
+import "Configuration.proto";
+import "Message.proto";
+import "Package.proto";
+import "Price.proto";
+import "PriceList.proto";
+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.
+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;
+
+  // Photos of the business, its products and its packages
+  repeated Attachment attachments = 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;
+
+  // 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;
+
+  // The orders of the customer, and their shopping cart
+  repeated Message messages = 5;
+
+  // 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;
+}

package/Configuration.proto

@@ -0,0 +1,26 @@
+syntax = "proto3";
+package com.merabills.storefront;
+option java_multiple_files = true;
+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.
+message Configuration {
+
+  Entity entity = 1;
+
+  oneof data {
+
+    // The publicly visible settings of the business, held in the configuration whose id is
+    // Configuration.MIN_PUBLIC_CONFIGURATION_ID
+    GeneralSettings generalSettings = 2;
+  }
+}

package/Constants.proto

@@ -0,0 +1,217 @@
+syntax = "proto3";
+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.
+enum Constants {
+
+  option allow_alias = true;
+
+  UNSPECIFIED_CONSTANT = 0;
+
+  // Scaling factors. An amount, a price or a discount is multiplied by AMOUNT_FACTOR, a quantity
+  // by QUANTITY_FACTOR, and a tax rate by TAX_RATE_FACTOR.
+  AMOUNT_FACTOR = 1000;
+  QUANTITY_FACTOR = 1000;
+  TAX_RATE_FACTOR = 10000;
+
+  // User.firstName, User.lastName
+  USER_NAME_MAX_LENGTH = 32;
+
+  // User.preferredLanguageCode
+  USER_LANGUAGE_CODE_MAX_LENGTH = 8;
+
+  // Business.businessId
+  BUSINESS_ID_MIN_LENGTH = 4;
+  BUSINESS_ID_MAX_LENGTH = 64;
+
+  // Business.displayName
+  BUSINESS_DISPLAY_NAME_MIN_LENGTH = 4;
+  BUSINESS_DISPLAY_NAME_MAX_LENGTH = 64;
+
+  // Item.name and Item.description, of a product, category, package, price or price list
+  ITEM_NAME_MAX_LENGTH = 128;
+  ITEM_DESCRIPTION_MAX_LENGTH = 512;
+
+  // Product.brand, Product.manufacturer
+  PRODUCT_BRAND_MAX_LENGTH = 32;
+  PRODUCT_MANUFACTURER_MAX_LENGTH = 32;
+
+  // Product.taxes and ShoppingListItem.taxes
+  MAX_TAXES = 4;
+
+  // Product.features
+  PRODUCT_MAX_FEATURES = 5;
+  PRODUCT_FEATURE_MAX_LENGTH = 255;
+
+  // Package.identifiers and GeneralSettings.businessIdentifiers
+  MAX_IDENTIFIERS = 8;
+
+  // PackageIdentifier.value and BusinessIdentifier.value
+  IDENTIFIER_MAX_LENGTH = 24;
+
+  // Attachment.fileHash - the exact size of an MD5 hash, not a maximum
+  ATTACHMENT_FILE_HASH_SIZE_BYTES = 16;
+
+  // Attachment.fileExtension, Attachment.fileName
+  ATTACHMENT_FILE_EXTENSION_MAX_LENGTH = 4;
+  ATTACHMENT_FILE_NAME_MAX_LENGTH = 16;
+
+  // Message.senderName
+  MESSAGE_SENDER_NAME_MAX_LENGTH = 65;
+
+  // SalesOrderPayload.note
+  SALES_ORDER_NOTE_MAX_LENGTH = 120;
+
+  // ShoppingList.existingItems and ShoppingList.deletedItems, counted together
+  SHOPPING_LIST_MAX_ITEMS = 200;
+
+  // ShoppingListItem.description
+  SHOPPING_LIST_ITEM_DESCRIPTION_MAX_LENGTH = 64;
+
+  // ShoppingListItem.shoppingListOrder, which starts at zero
+  SHOPPING_LIST_ITEM_MAX_ORDER = 255;
+
+  // AddressList.addresses
+  MAX_ADDRESSES = 32;
+
+  // The fields of an Address
+  ADDRESS_UNIT_NUMBER_MAX_LENGTH = 16;
+  ADDRESS_COMMUNITY_MAX_LENGTH = 32;
+  ADDRESS_LINE2_MAX_LENGTH = 64;
+  ADDRESS_CITY_MAX_LENGTH = 32;
+  ADDRESS_STATE_MAX_LENGTH = 32;
+  ADDRESS_PIN_CODE_MAX_LENGTH = 16;
+
+  // GeneralSettings.paymentMethodDetails, GeneralSettings.storeTagline
+  MAX_PAYMENT_METHODS = 8;
+  STORE_TAGLINE_MAX_LENGTH = 64;
+
+  // GeneralSettings.deliveryRadiusKms - this value means there is no limit on the distance
+  NO_RESTRICTIONS_DELIVERY_DISTANCE = 0;
+
+  // PaymentMethodDetail.data
+  PAYMENT_METHOD_DATA_MAX_LENGTH = 320;
+
+  // WorkingDays.days and WorkingDays.workingHours
+  DAYS_IN_WEEK = 7;
+
+  // WorkingHours.ranges (WorkingHours.MAX_RANGES)
+  WORKING_HOURS_MAX_RANGES = 8;
+
+  // The bound on WorkingHoursRange.openMinute and closeMinute, and the value of closeMinute that
+  // 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.
+  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.
+  USER_ENTITY_TYPE_ID = 1;
+  BUSINESS_ENTITY_TYPE_ID = 2;
+  BUSINESS_LINK_ENTITY_TYPE_ID = 3;
+  ATTACHMENT_ENTITY_TYPE_ID = 12;
+  CONFIGURATION_ENTITY_TYPE_ID = 13;
+  MESSAGE_ENTITY_TYPE_ID = 14;
+  ITEM_ENTITY_TYPE_ID = 15;
+  PACKAGE_ENTITY_TYPE_ID = 64;
+  PRODUCT_ENTITY_TYPE_ID = 65;
+  PRODUCT_CATEGORY_ENTITY_TYPE_ID = 66;
+  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.
+  UPDATE_TYPE_MASK = 3;
+  UPDATE_TYPE_MAX_VALUE = 3;
+  UPDATE_TYPE_CREATED = 1;
+  UPDATE_TYPE_MODIFIED = 2;
+  UPDATE_TYPE_DELETED = 3;
+
+  // Entity ids that are never assigned to a real entity. ENTITY_ID_NULL is what a field holds when
+  // it refers to nothing.
+  ENTITY_ID_NULL = 0;
+  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.
+  DEFAULT_SALE_PRICE_LIST = 0;
+  DEFAULT_PURCHASE_PRICE_LIST = 1;
+
+  // The earliest valid Entity.createdAt / updatedAt, in milliseconds since Jan 1, 1970 UTC. Default
+  // entities are created with this time so that a copy from another device always wins a sync.
+  DEFAULT_ENTITY_CREATED_AT = 1;
+
+  // Milliseconds by which a client clock is allowed to differ from the server clock. A time in this
+  // protocol can be up to this far ahead of the reading of the client clock.
+  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.
+  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.
+  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.
+  SYNC_OUT_LIMIT = 5000;
+
+  // Entity.state and the Java attribute numbering of an entity. Neither the state nor the
+  // attribute numbers are part of this protocol; the constants are here for completeness.
+  STATE_MAX_LENGTH = 131072;
+  ENTITY_ATTRIBUTE_COUNT = 5;
+  ATTRIBUTE_NUMBER_ID = 1;
+  ATTRIBUTE_NUMBER_UPDATE_INFO = 3;
+}

package/DimensionUnit.proto

@@ -0,0 +1,15 @@
+syntax = "proto3";
+package com.merabills.storefront;
+option java_multiple_files = true;
+option java_package = "com.merabills.server.core.generated";
+
+// Unit in which the dimensions of a package are expressed.
+// Values match the ids of the corresponding Java enum entries and must never be changed.
+enum DimensionUnit {
+
+  CENTIMETERS = 0;
+  MILLIMETERS = 1;
+  METERS = 2;
+  INCHES = 3;
+  FEET = 4;
+}

package/Dimensions.proto

@@ -0,0 +1,18 @@
+syntax = "proto3";
+package com.merabills.storefront;
+option java_multiple_files = true;
+option java_package = "com.merabills.server.core.generated";
+
+import "DimensionUnit.proto";
+
+// The dimensions of a package. All three values are greater than zero.
+message Dimensions {
+
+  DimensionUnit unit = 1;
+
+  float length = 2;
+
+  float width = 3;
+
+  float height = 4;
+}

package/Entity.proto

@@ -0,0 +1,45 @@
+syntax = "proto3";
+package com.merabills.storefront;
+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).
+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.
+  int64 id = 1;
+
+  // 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.
+  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).
+  int64 updateNumber = 4;
+
+  // Creation time, in milliseconds since Jan 1, 1970 00:00:00 UTC
+  int64 createdAt = 5;
+}

package/FulfillmentMode.proto

@@ -0,0 +1,21 @@
+syntax = "proto3";
+package com.merabills.storefront;
+option java_multiple_files = true;
+option java_package = "com.merabills.server.core.generated";
+
+// How an order is handed over to the customer. Values match the ids of the corresponding Java enum
+// entries, which are bit flags, and must never be changed.
+enum FulfillmentMode {
+
+  // Java has no zero value: it treats a fulfillment mode of zero as not set
+  UNSPECIFIED_FULFILLMENT_MODE = 0;
+
+  // The customer will pick up the order
+  PICK_UP = 1;
+
+  // The order needs to be delivered to the customer
+  DELIVERY = 2;
+
+  // The order will be received by the customer on the premises, with full service
+  IN_STORE_SERVICE = 4;
+}

package/GeneralSettings.proto

@@ -0,0 +1,56 @@
+syntax = "proto3";
+package com.merabills.storefront;
+option java_multiple_files = true;
+option java_package = "com.merabills.server.core.generated";
+
+import "AddressList.proto";
+import "BusinessIdentifier.proto";
+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.
+// Excluded: onlineShoppingEnabled, and the fields of the StoreSettings base class (authToken,
+// authTokenExpiry, lastSuccessfulSync and fees).
+// Not included because it is a constant: overdueAfterMillis.
+message GeneralSettings {
+
+  // Payment methods this business accepts (at most Constants.MAX_PAYMENT_METHODS)
+  repeated PaymentMethodDetail paymentMethodDetails = 1;
+
+  // E.164 formatted phone number that customers can call
+  optional string customerServicePhone = 2;
+
+  // True if the customer service phone number can be reached on WhatsApp
+  bool isWhatsAppSupported = 3;
+
+  // True if the customer service phone number can be reached by SMS
+  bool isSmsSupported = 4;
+
+  // Addresses of this business, and the id of its default (main) address
+  AddressList businessAddresses = 5;
+
+  // Identifiers of this business, one per kind of identifier (at most Constants.MAX_IDENTIFIERS)
+  repeated BusinessIdentifier businessIdentifiers = 6;
+
+  // Fulfillment modes this business offers. Exposed instead of the bit mask used in Java.
+  repeated FulfillmentMode fulfillmentModes = 7;
+
+  // Charge for delivering an order, multiplied by Constants.AMOUNT_FACTOR
+  int64 deliveryCharge = 8;
+
+  // Order total at or above which delivery is free, multiplied by Constants.AMOUNT_FACTOR.
+  // 0 means delivery is never free.
+  int64 freeDeliveryTotal = 9;
+
+  // Distance, in kilometres, within which this business delivers.
+  // Constants.NO_RESTRICTIONS_DELIVERY_DISTANCE (0) means there is no limit.
+  int32 deliveryRadiusKms = 10;
+
+  // One line description of this business (at most Constants.STORE_TAGLINE_MAX_LENGTH)
+  optional string storeTagline = 11;
+
+  WorkingDays workingDays = 12;
+}

package/Item.proto

@@ -0,0 +1,26 @@
+syntax = "proto3";
+package com.merabills.storefront;
+option java_multiple_files = true;
+option java_package = "com.merabills.server.core.generated";
+
+import "Entity.proto";
+
+// Something that a business buys or sells, or a category or price thereof.
+// Excluded: isPublic, isDisabled, keyValues and all Translations fields.
+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.
+  int64 parentItemId = 2;
+
+  // At most Constants.ITEM_NAME_MAX_LENGTH
+  string name = 3;
+
+  // At most Constants.ITEM_DESCRIPTION_MAX_LENGTH
+  optional string description = 4;
+}