@peabody-soft/mbs-protos 1.0.0

package/ShoppingList.proto

@@ -0,0 +1,57 @@
+syntax = "proto3";
+package com.merabills.storefront;
+option java_multiple_files = true;
+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.
+message ShoppingList {
+
+  // True once the customer is done editing this list, after which the business may edit it.
+  // Only a final list can have deleted items. This flag is never unset.
+  bool isFinal = 1;
+
+  // True when the delivery charge is carried as an item of its own, with the package id
+  // ReservedPackage.DELIVERY_CHARGE_PACKAGE, rather than being added to the total
+  bool autoAddDeliveryCharge = 2;
+
+  // The same, for ReservedPackage.SERVICE_CHARGE_PACKAGE
+  bool autoAddServiceCharge = 3;
+
+  // 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.
+  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.
+  int64 totalAmountBeforeDiscount = 6;
+
+  // Discount on the whole list, multiplied by Constants.AMOUNT_FACTOR
+  int64 discount = 7;
+
+  // Number of existing items - set even when the items themselves are not sent
+  int32 existingItemCount = 8;
+
+  // Number of deleted items - set even when the items themselves are not sent
+  int32 deletedItemCount = 9;
+
+  // The items in this list (this list and the deleted items below hold at most
+  // Constants.SHOPPING_LIST_MAX_ITEMS items in all)
+  repeated ShoppingListItem existingItems = 10;
+
+  // Items that were in this list when it was made final, and have since been deleted or replaced
+  repeated ShoppingListItem deletedItems = 11;
+}

package/ShoppingListItem.proto

@@ -0,0 +1,53 @@
+syntax = "proto3";
+package com.merabills.storefront;
+option java_multiple_files = true;
+option java_package = "com.merabills.server.core.generated";
+
+import "Tax.proto";
+
+// A line item in a shopping list: the package being bought, how much of it, and at what price.
+// Excluded: batches.
+// Not included because they are computed from the fields below and are not stored in Java:
+// taxes amounts, totalTax and finalPrice (= (unitPrice x quantity) + taxes thereon - discount).
+message ShoppingListItem {
+
+  // Id of the package being bought. Four ids are reserved for charge and summary lines rather
+  // than catalog packages, and will not be found in the catalog - see ReservedPackage, which
+  // gives those ids and how to build them. A client must label those lines itself.
+  int64 packageId = 1;
+
+  // Quantity, multiplied by Constants.QUANTITY_FACTOR. 1.5 kg is stored as 1500.
+  int32 quantity = 2;
+
+  // Price of one unit of the package, multiplied by Constants.AMOUNT_FACTOR.
+  // This is the offer price when the package is on offer.
+  int64 unitPrice = 3;
+
+  // Position of this item in the shopping list (0 to Constants.SHOPPING_LIST_ITEM_MAX_ORDER)
+  int32 shoppingListOrder = 4;
+
+  // True if this item was created before the shopping list was made final
+  bool isOriginal = 5;
+
+  // True if this item has been deleted or replaced after the shopping list was made final
+  bool isModified = 6;
+
+  bool isStockKeepingRequired = 7;
+
+  // Discount in the unit price (regularPrice - offerPrice of the package), multiplied by
+  // Constants.AMOUNT_FACTOR
+  int64 priceDiscount = 8;
+
+  // Discount applied to the total price of this line item, including taxes, multiplied by
+  // Constants.AMOUNT_FACTOR
+  int64 discount = 9;
+
+  // Taxes that apply to this line item (at most Constants.MAX_TAXES)
+  repeated Tax taxes = 10;
+
+  // Number of minutes after purchase when this item expires. 0 means it does not expire.
+  int32 expiry = 11;
+
+  // At most Constants.SHOPPING_LIST_ITEM_DESCRIPTION_MAX_LENGTH
+  optional string description = 12;
+}

package/TaskStatus.proto

@@ -0,0 +1,13 @@
+syntax = "proto3";
+package com.merabills.storefront;
+option java_multiple_files = true;
+option java_package = "com.merabills.server.core.generated";
+
+// Processing status of a message.
+// Values match the ids of the corresponding Java enum entries and must never be changed.
+enum TaskStatus {
+
+  NOT_YET_PROCESSED = 0;
+  COMPLETED = 1;
+  REJECTED = 2;
+}

package/Tax.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 "TaxType.proto";
+
+// A tax and the rate at which it applies. Replaces the parallel taxCodes / taxRates arrays in Java.
+message Tax {
+
+  // Exposed instead of the raw tax code
+  TaxType type = 1;
+
+  // Tax rate, multiplied by Constants.TAX_RATE_FACTOR. 18% is stored as 1800.
+  int32 rate = 2;
+}

package/TaxType.proto

@@ -0,0 +1,13 @@
+syntax = "proto3";
+package com.merabills.storefront;
+option java_multiple_files = true;
+option java_package = "com.merabills.server.core.generated";
+
+// A tax that applies to a product or to a line item.
+// Values match the Java tax codes, which are unique within a country: the country of the business
+// that owns the item is needed to interpret them.
+enum TaxType {
+
+  // India: Goods and Services Tax
+  GST = 0;
+}

package/UrlAndToken.proto

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

package/User.proto

@@ -0,0 +1,36 @@
+syntax = "proto3";
+package com.merabills.storefront;
+option java_multiple_files = true;
+option java_package = "com.merabills.server.core.generated";
+
+import "AddressList.proto";
+import "Entity.proto";
+
+// A user of MeraBills. A customer of a business is represented by a User.
+//
+// A user lives in a profile database, not in a business database, so it is carried by a
+// ProfileSyncOutResponse and not by a BusinessSyncOutResponse, the way Java splits
+// Service.profileSyncOut from Service.businessSyncOut. Do not add it to the business sync out: a
+// client reads the caller once, by signing in, and then reads each business separately.
+//
+// Excluded: referralDetails, isCallingUser and all Translations fields.
+// Not included because it is derived: formattedName (firstName + " " + lastName).
+message User {
+
+  Entity entity = 1;
+
+  // At most Constants.USER_NAME_MAX_LENGTH
+  string firstName = 2;
+
+  // At most Constants.USER_NAME_MAX_LENGTH
+  optional string lastName = 3;
+
+  // E.164 formatted mobile phone number
+  string mobilePhoneNumber = 4;
+
+  // Delivery addresses of this user, and the id of the default one
+  AddressList addresses = 5;
+
+  // BCP 47 / ISO 639 language code (at most Constants.USER_LANGUAGE_CODE_MAX_LENGTH)
+  optional string preferredLanguageCode = 6;
+}

package/Weight.proto

@@ -0,0 +1,14 @@
+syntax = "proto3";
+package com.merabills.storefront;
+option java_multiple_files = true;
+option java_package = "com.merabills.server.core.generated";
+
+import "WeightUnit.proto";
+
+// The weight of a package. The value is greater than zero.
+message Weight {
+
+  WeightUnit unit = 1;
+
+  float value = 2;
+}

package/WeightUnit.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 weight of a package is expressed.
+// Values match the ids of the corresponding Java enum entries and must never be changed.
+enum WeightUnit {
+
+  GRAMS = 0;
+  MILLIGRAMS = 1;
+  KILOGRAMS = 2;
+  OUNCES = 3;
+  POUNDS = 4;
+}

package/WorkingDays.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 "WorkingHours.proto";
+
+// The days of the week on which a business works, and the hours it works on each of them.
+// Not included because it is derived: includesAllDaysOfWeek, isWorkingDay, isOpenAllDay and
+// isOpenAt.
+message WorkingDays {
+
+  // Up to Constants.DAYS_IN_WEEK values: index 0 is Sunday, 1 is Monday ... 6 is Saturday.
+  // A value of true means the business works on that day. A missing value is false. An absent
+  // WorkingDays means the business works on every day of the week, which is the Java default.
+  repeated bool days = 1;
+
+  // The working hours of each day, indexed exactly as days above: entry 0 is Sunday. Up to
+  // Constants.DAYS_IN_WEEK entries, and fewer - or none at all - is normal.
+  //
+  // An entry that is missing, or that is present with no ranges, means work goes on all day long on
+  // that day. So an empty workingHours means the business works round the clock on each of its
+  // working days. Hours are only meaningful on a day whose days entry is true; on any other day
+  // they must be ignored.
+  repeated WorkingHours workingHours = 2;
+}

package/WorkingHours.proto

@@ -0,0 +1,19 @@
+syntax = "proto3";
+package com.merabills.storefront;
+option java_multiple_files = true;
+option java_package = "com.merabills.server.core.generated";
+
+import "WorkingHoursRange.proto";
+
+// The working hours of a single day.
+// Not included because they are computed: rangeCount, isAllDay and contains.
+message WorkingHours {
+
+  // The stretches of the day that are worked (at most Constants.WORKING_HOURS_MAX_RANGES). They do
+  // not overlap, they are ordered by openMinute, and two of them never touch - a range closing
+  // exactly when the next opens is sent as one unbroken range.
+  //
+  // No ranges at all means work goes on all day long, which is also what a range covering the whole
+  // day would mean.
+  repeated WorkingHoursRange ranges = 1;
+}

package/WorkingHoursRange.proto

@@ -0,0 +1,22 @@
+syntax = "proto3";
+package com.merabills.storefront;
+option java_multiple_files = true;
+option java_package = "com.merabills.server.core.generated";
+
+// A single stretch of working hours within one day, in minutes after local midnight. The times are
+// local to the business, not UTC, and this protocol carries no time zone: a client that wants to
+// know whether the business is open now has to use the time zone of the business address.
+//
+// A range never spans midnight. Work that goes on past midnight is two ranges: one closing at
+// Constants.MINUTES_PER_DAY on one day, and one opening at 0 on the day after.
+// Not included because they are computed: isAllDay, contains and overlaps.
+message WorkingHoursRange {
+
+  // Minute at which work starts, from 0 to Constants.MINUTES_PER_DAY - 1. This minute is worked.
+  int32 openMinute = 1;
+
+  // Minute at which work stops, from 1 to Constants.MINUTES_PER_DAY, and always greater than
+  // openMinute. This minute is not worked, so Constants.MINUTES_PER_DAY means work stops at
+  // midnight.
+  int32 closeMinute = 2;
+}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@peabody-soft/mbs-protos",
+  "version": "1.0.0",
+  "description": "The MeraBills shop wire protocol",
+  "author": "Peabody Soft",
+  "license": "AGPL-3.0-or-later",
+  "homepage": "https://merabills.com",
+  "keywords": [
+    "MeraBills",
+    "MeraBills Shop",
+    "Peabody Soft",
+    "ProtoBuf"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "*.proto",
+    "!Prompt.txt"
+  ],
+  "scripts": {
+    "publish:protos": "npm publish",
+    "publish:protos:dry-run": "npm publish --dry-run"
+  }
+}