@peabody-soft/mbs-model-ts 1.0.0

package/dist/CartEditor.js

@@ -0,0 +1,324 @@
+import { Constants as proto_Constants } from "./generated/Constants";
+import { FulfillmentMode as proto_FulfillmentMode } from "./generated/FulfillmentMode";
+import { ReservedPackage as proto_ReservedPackage } from "./generated/ReservedPackage";
+import { MERABILLS_ONLINE_PRICE_LIST_ID } from "./Constants";
+import { InvalidArgumentException } from "./Exceptions";
+import Ids from "./Ids";
+import ShoppingList, { ShoppingListItem } from "./ShoppingList";
+// Builds the cart a customer is filling, in the terms a UI has to hand: packages rather than
+// package ids, quantities rather than quantities multiplied by Constants.QUANTITY_FACTOR, and
+// prices taken off the catalog rather than worked out and passed in. Get one from
+// Business.createCartEditor, edit it, then hand build() to Model.updateCartLocalOnly.
+//
+// Mutable, and deliberately the only mutable thing in this object model: it is a scratch copy of
+// the cart, not the cart. Nothing here writes anything - editing an editor changes no Business, no
+// store and nothing on the server until a built list is pushed. It is also a snapshot: it reads the
+// catalog, settings and cart once, at construction, so a sync arriving mid-edit does not move
+// prices under the customer. Make a fresh one when the Business republishes.
+class CartEditor {
+    // Business.createCartEditor is how a UI gets one of these; this takes the three things it needs
+    // rather than the Business itself, so a caller can build a cart against a catalog and settings
+    // that are not the ones currently published.
+    //
+    // Every line is priced off the catalog now, not off what the cart was holding: a cart lives
+    // until it is ordered, the merchant may have repriced in between, and what an order freezes is
+    // the price at the moment it is placed. Lines the catalog can no longer price - a package
+    // withdrawn, disabled, or left without a price - are dropped, and left in unavailableItems for a
+    // UI to tell the customer about. The charge lines of the list it started from (see
+    // ShoppingListItem.isReservedPackage) are dropped too, being this class's to work out rather
+    // than a customer's to carry: build() puts back whatever the settings now say.
+    constructor(_catalog, _settings, cart) {
+        this._catalog = _catalog;
+        this._settings = _settings;
+        // Insertion ordered, which is what keeps a cart in the order the customer filled it and what
+        // gives each line its shoppingListOrder
+        this._quantities = new Map();
+        this._inventoryLocationId = cart?.inventoryLocationId ?? 0;
+        const unavailableItems = [];
+        for (const item of cart?.existingItems ?? []) {
+            if (item.isReservedPackage)
+                continue;
+            const buyable = this.getBuyablePackage(item.packageId);
+            if (buyable === null)
+                unavailableItems.push(item);
+            else
+                this._quantities.set(buyable.id, item.quantity);
+        }
+        this._unavailableItems = Object.freeze(unavailableItems);
+    }
+    // What the customer has picked, in the order it was picked in, each line priced as it would be
+    // bought right now. Rebuilt on every read, so a line held across an edit is stale.
+    get lines() {
+        const lines = [];
+        for (const [packageId, quantity] of this._quantities) {
+            const buyable = this.getBuyablePackage(packageId);
+            if (buyable === null)
+                continue; // Cannot happen: only a buyable package is ever put in
+            lines.push(new CartLine(buyable, this._catalog.getProduct(buyable.productId), quantity));
+        }
+        return Object.freeze(lines);
+    }
+    // The lines of the cart this editor started from that its catalog can no longer price - see the
+    // note on the constructor. Empty for a cart built from nothing, and never added to by an edit.
+    get unavailableItems() {
+        return this._unavailableItems;
+    }
+    get isEmpty() {
+        return this._quantities.size === 0;
+    }
+    // How many lines the cart has, which is what a cart badge counts - not how many units are in it
+    get lineCount() {
+        return this._quantities.size;
+    }
+    // Every unit of every line added up. Fractional where a package is sold loose.
+    get totalQuantity() {
+        let result = 0;
+        for (const quantity of this._quantities.values())
+            result += quantity;
+        return result;
+    }
+    // Zero for a package that is not in the cart
+    getQuantity(item) {
+        return this._quantities.get(item.id) ?? 0;
+    }
+    // Sets how much of one package the cart holds; zero takes it out. A package a customer cannot
+    // buy - one disabled, or priced in no list this storefront sells from - is refused, as is a
+    // fractional quantity of a package that is not sold loose, and a quantity past what the wire can
+    // carry. Returns this, so edits chain.
+    setQuantity(item, quantity) {
+        if (!Number.isFinite(quantity) || quantity < 0)
+            throw new InvalidArgumentException(`${quantity} is not a quantity`);
+        if (quantity === 0) {
+            this._quantities.delete(item.id);
+            return this;
+        }
+        if (this.getBuyablePackage(item.id) === null)
+            throw new InvalidArgumentException(`Package ${Ids.toStorageHexString(item.id)} cannot be bought from this catalog`);
+        if (!item.isSoldLoose && !Number.isInteger(quantity))
+            throw new InvalidArgumentException(`${item.name} is not sold loose, so it cannot be bought ${quantity} at a time`);
+        // A quantity travels as an int32 multiplied by Constants.QUANTITY_FACTOR, so this is the most
+        // of one package a cart can hold - and it is refused here rather than silently wrapping there.
+        if (quantity > CartEditor.MAX_QUANTITY)
+            throw new InvalidArgumentException(`${quantity} is more than the ${CartEditor.MAX_QUANTITY} the protocol can carry`);
+        if (!this._quantities.has(item.id) &&
+            this._quantities.size >= proto_Constants.SHOPPING_LIST_MAX_ITEMS)
+            throw new InvalidArgumentException(`A cart holds at most ${proto_Constants.SHOPPING_LIST_MAX_ITEMS} lines`);
+        this._quantities.set(item.id, quantity);
+        return this;
+    }
+    // Adds to what the cart already holds of this package, which is what a quantity stepper does.
+    // A negative amount takes away, and never below nothing.
+    add(item, quantity = 1) {
+        return this.setQuantity(item, Math.max(0, this.getQuantity(item) + quantity));
+    }
+    remove(item) {
+        return this.setQuantity(item, 0);
+    }
+    clear() {
+        this._quantities.clear();
+        return this;
+    }
+    // What the packages cost before tax, offers already taken off
+    get itemsTotal() {
+        let result = 0;
+        for (const line of this.lines)
+            result += line.amount;
+        return result;
+    }
+    // What the offers took off, which is what a bill shows as savings. Zero when nothing is on offer.
+    get savings() {
+        let result = 0;
+        for (const line of this.lines)
+            result += line.savings;
+        return result;
+    }
+    get itemsTax() {
+        let result = 0;
+        for (const line of this.lines)
+            result += line.totalTax;
+        return result;
+    }
+    // The packages with their tax, and what the free delivery threshold is measured against - the
+    // same total Java ShoppingCartViewModel.calculateDeliveryCharge compares, less its delivery line
+    get itemsFinalTotal() {
+        let result = 0;
+        for (const line of this.lines)
+            result += line.finalPrice;
+        return result;
+    }
+    // True when this business delivers at all. False means no delivery charge exists to add, whatever
+    // build() is asked for, and a UI has no fulfillment choice to offer either.
+    get isDeliveryOffered() {
+        return this._settings.fulfillmentModes.includes(proto_FulfillmentMode.DELIVERY);
+    }
+    // What delivering this cart would cost before tax: the business's flat charge, or zero where it
+    // has been waived by the cart reaching freeDeliveryTotal, or where the business delivers free
+    // anyway. Always zero when the business does not deliver.
+    get deliveryCharge() {
+        return this.getDeliveryCharge(this.itemsFinalTotal);
+    }
+    // What delivery costs before any waiver - the price a bill strikes through when it reads FREE.
+    // Zero where the business delivers free anyway, in which case there is nothing to strike through.
+    get regularDeliveryCharge() {
+        if (!this.isDeliveryOffered)
+            return 0;
+        // Java clamps a negative charge to zero rather than treating it as a refund, and so does this
+        return Math.max(0, this._settings.deliveryCharge);
+    }
+    // True when delivering this cart costs nothing, whether because the business never charges or
+    // because this cart has reached the threshold
+    get isDeliveryFree() {
+        return this.isDeliveryOffered && this.deliveryCharge === 0;
+    }
+    // How much more the customer would have to add for delivery to stop being charged, which is the
+    // "add X more for free delivery" note. Zero once it is already free, and null when the business
+    // has set no threshold, so there is no amount that would ever make it free.
+    get amountToFreeDelivery() {
+        if (!this.isDeliveryOffered)
+            return null;
+        if (this.regularDeliveryCharge === 0)
+            return 0; // Already free, and free at any total
+        const freeDeliveryTotal = this._settings.freeDeliveryTotal;
+        if (freeDeliveryTotal <= 0)
+            return null; // No threshold: adding more changes nothing
+        return Math.max(0, freeDeliveryTotal - this.itemsFinalTotal);
+    }
+    // Tax on the delivery charge, at the rates GeneralSettings.deliveryChargeTaxes carries - which
+    // are the business's own and have nothing to do with a product's. Zero when delivery is free,
+    // there being nothing to tax.
+    get deliveryTax() {
+        return CartEditor.getTax(this.deliveryCharge, this._settings.deliveryChargeTaxes);
+    }
+    // What the cart comes to. Delivery is left out unless asked for, the way a cart page leaves it
+    // out and a checkout page puts it in - the same choice build() takes.
+    total(withDeliveryCharge = false) {
+        const total = this.itemsFinalTotal;
+        if (!withDeliveryCharge || this.isEmpty)
+            return total;
+        // Worked out from the total already in hand, rather than through the two getters above, each
+        // of which would add the lines up again
+        const charge = this.getDeliveryCharge(total);
+        return total + charge + CartEditor.getTax(charge, this._settings.deliveryChargeTaxes);
+    }
+    // The cart as a list to write: what Model.updateCartLocalOnly and Model.updateCart take, and
+    // what a later Model.createOrder turns into an order.
+    //
+    // withDeliveryCharge decides whether the delivery charge rides along as a line of its own,
+    // carrying ReservedPackage.DELIVERY_CHARGE_PACKAGE and flagged by
+    // ShoppingList.autoAddDeliveryCharge. A cart page has no fulfillment chosen yet and so leaves it
+    // out, which is the default; a checkout page that has settled on delivery asks for it. The line
+    // is added even when the charge has been waived - at zero, with the regular charge as its
+    // priceDiscount - so a bill can show FREE with the original struck through, which is what Java
+    // ShoppingCartViewModel.setDeliveryCharge writes too.
+    //
+    // Nothing is added to an empty cart: a list holding a delivery charge and no goods is not an
+    // order, and Java removes exactly that line when it is all that is left.
+    // The list comes back not final. Making it final is placing an order, which is
+    // Model.createOrder's to do.
+    build(withDeliveryCharge = false) {
+        const items = [];
+        for (const line of this.lines)
+            items.push(line.toShoppingListItem(items.length));
+        const isDeliveryCharged = withDeliveryCharge && items.length > 0 && this.isDeliveryOffered;
+        if (isDeliveryCharged)
+            items.push(this.buildDeliveryChargeItem(items.length));
+        // The total is written off the lines being sent, the way ShoppingList.proto defines it: the
+        // sum of their final prices, tax included. There is no list-wide discount - an offer comes off
+        // a line, and a storefront gives no other.
+        let totalAmountBeforeDiscount = 0;
+        for (const item of items)
+            totalAmountBeforeDiscount += item.finalPrice;
+        return new ShoppingList(false, isDeliveryCharged, false, this._inventoryLocationId, this._catalog.priceList?.id ?? MERABILLS_ONLINE_PRICE_LIST_ID, totalAmountBeforeDiscount, 0, items.length, 0, Object.freeze(items), Object.freeze([]));
+    }
+    // The delivery charge as a line: one of it, at whatever it costs after any waiver, with the
+    // waived amount as its price discount - the same shape as a package bought on offer, which is
+    // what lets a bill render it with no special case beyond its label.
+    buildDeliveryChargeItem(shoppingListOrder) {
+        const charge = this.deliveryCharge;
+        return new ShoppingListItem(Ids.buildId(proto_Constants.PACKAGE_ENTITY_TYPE_ID, BigInt(proto_ReservedPackage.DELIVERY_CHARGE_PACKAGE)), 1, charge, shoppingListOrder, false, false, false, this.regularDeliveryCharge - charge, 0, this._settings.deliveryChargeTaxes, 0, null);
+    }
+    // The charge against a cart that comes to this much, which is the whole of the policy. Takes
+    // the total rather than reading it, every caller here having worked it out already.
+    getDeliveryCharge(itemsFinalTotal) {
+        const charge = this.regularDeliveryCharge;
+        if (charge === 0)
+            return 0; // Free for everyone, or not delivered at all
+        const freeDeliveryTotal = this._settings.freeDeliveryTotal;
+        if (freeDeliveryTotal <= 0)
+            return charge; // Never free, whatever the cart totals
+        return itemsFinalTotal >= freeDeliveryTotal ? 0 : charge;
+    }
+    static getTax(amount, taxes) {
+        let result = 0;
+        for (const tax of taxes)
+            result += (amount * tax.rate) / 100;
+        return result;
+    }
+    // The package this id names, and null unless a customer could actually buy it right now
+    getBuyablePackage(packageId) {
+        const item = this._catalog.getPackage(packageId);
+        return item !== null && item.isBuyable ? item : null;
+    }
+}
+// What an int32 quantity multiplied by Constants.QUANTITY_FACTOR reaches
+CartEditor.MAX_QUANTITY = Math.floor(0x7fffffff / proto_Constants.QUANTITY_FACTOR);
+export default CartEditor;
+// One line of a cart being edited: the package, the product it is a variant of, and how much of it
+// - with the prices the catalog gives it now. A read-only view over what CartEditor holds, rebuilt
+// on every read of CartEditor.lines rather than kept.
+export class CartLine {
+    constructor(_package, _product, _quantity) {
+        this._package = _package;
+        this._product = _product;
+        this._quantity = _quantity;
+    }
+    get package() {
+        return this._package;
+    }
+    // Null only for a package whose product is not in the catalog, which a buyable package's never is
+    get product() {
+        return this._product;
+    }
+    get quantity() {
+        return this._quantity;
+    }
+    // What one unit costs: the offer price where the package is on offer, else the regular price.
+    // A buyable package always has a price, so this is never guessed.
+    get unitPrice() {
+        return this._package.price?.finalPrice ?? 0;
+    }
+    get regularUnitPrice() {
+        return this._package.price?.regularPrice ?? 0;
+    }
+    get isOnOffer() {
+        return this._package.price?.isOnOffer ?? false;
+    }
+    // The taxes of the product this package belongs to, which are what the line is taxed at
+    get taxes() {
+        return this._product?.taxes ?? EMPTY_TAXES;
+    }
+    // What this line costs before tax
+    get amount() {
+        return this.unitPrice * this._quantity;
+    }
+    // What the offer takes off this line
+    get savings() {
+        return (this.regularUnitPrice - this.unitPrice) * this._quantity;
+    }
+    get totalTax() {
+        let result = 0;
+        for (const tax of this.taxes)
+            result += (this.amount * tax.rate) / 100;
+        return result;
+    }
+    // What this line adds to the cart: what it costs plus the tax on it
+    get finalPrice() {
+        return this.amount + this.totalTax;
+    }
+    // This line as the protocol carries it. Only CartEditor.build calls this, which is what assigns
+    // the order.
+    toShoppingListItem(shoppingListOrder) {
+        return new ShoppingListItem(this._package.id, this._quantity, this.unitPrice, shoppingListOrder, false, false, false, this.regularUnitPrice - this.unitPrice, 0, this.taxes, 0, null);
+    }
+}
+const EMPTY_TAXES = Object.freeze([]);

package/dist/Catalog.d.ts

@@ -0,0 +1,28 @@
+import Item from "./Item";
+import Package from "./Package";
+import PriceList from "./PriceList";
+import Product from "./Product";
+import ProductCategory from "./ProductCategory";
+export default class Catalog {
+    private readonly _priceList;
+    constructor(categories: ReadonlyArray<ProductCategory>, products: ReadonlyArray<Product>, _priceList: PriceList | null);
+    get categories(): ReadonlyArray<ProductCategory>;
+    get products(): ReadonlyArray<Product>;
+    get priceList(): PriceList | null;
+    get productCount(): number;
+    get packageCount(): number;
+    getCategory(productCategoryId: bigint): ProductCategory | null;
+    getProduct(productId: bigint): Product | null;
+    getPackage(packageId: bigint): Package | null;
+    static comparePackages(left: Package, right: Package): number;
+    static compareByName(left: Item, right: Item): number;
+    private static compareNames;
+    private static compareIds;
+    private static comparePrices;
+    static readonly EMPTY: Catalog;
+    private readonly _categories;
+    private readonly _products;
+    private readonly _categoryMap;
+    private readonly _productMap;
+    private readonly _packageMap;
+}

package/dist/Catalog.js

@@ -0,0 +1,115 @@
+import { Constants as proto_Constants } from "./generated/Constants";
+import { EntityHeader } from "./Entity";
+import ProductCategory from "./ProductCategory";
+// The catalog of a business: its categories, and every product in it. Not an entity and not on
+// the wire - the sync layer rebuilds this hierarchy from the flat item entities of a sync response.
+class Catalog {
+    constructor(categories, products, _priceList) {
+        this._priceList = _priceList;
+        this._categoryMap = new Map();
+        this._productMap = new Map();
+        this._packageMap = new Map();
+        // A dummy category standing in for a product whose parentItemId is Constants.ENTITY_ID_NULL.
+        // Its own id is that same ENTITY_ID_NULL, so getCategory(product.productCategoryId) resolves
+        // it exactly like a real category - including being left out below, the same as any other
+        // category, when nothing buyable ends up in it.
+        const uncategorized = new ProductCategory(new EntityHeader(BigInt(proto_Constants.ENTITY_ID_NULL), 0n, 0n, 0n, 0n), "", null, BigInt(proto_Constants.ENTITY_ID_NULL), false);
+        this._products = Object.freeze([...products]);
+        // Only a buyable product - one a customer can actually order - counts towards a category. A
+        // product that cannot be bought right now keeps its place in Catalog.products and stays
+        // reachable by getProduct, but does not keep a category alive on its own.
+        const productsByCategory = new Map();
+        for (const product of this._products) {
+            this._productMap.set(product.id, product);
+            if (product.isBuyable) {
+                const productsOfCategory = productsByCategory.get(product.productCategoryId);
+                if (productsOfCategory === undefined)
+                    productsByCategory.set(product.productCategoryId, [product]);
+                else
+                    productsOfCategory.push(product);
+            }
+            for (const pkg of product.packages)
+                this._packageMap.set(pkg.id, pkg);
+        }
+        // A category with nothing a customer can order is left out rather than shown empty - there is
+        // no point showing it to a customer. Nothing here is special-cased for the dummy: it is left
+        // out exactly the same way when nothing buyable is uncategorized.
+        const nonEmptyCategories = [];
+        for (const category of [...categories, uncategorized]) {
+            const categoryProducts = productsByCategory.get(category.id);
+            if (categoryProducts === undefined)
+                continue;
+            category.products = Object.freeze(categoryProducts);
+            nonEmptyCategories.push(category);
+        }
+        this._categories = Object.freeze(nonEmptyCategories);
+        for (const category of this._categories)
+            this._categoryMap.set(category.id, category);
+    }
+    // In no particular order - a UI orders these for display
+    get categories() {
+        return this._categories;
+    }
+    // Every product of the business, whether or not it is in a category, in no particular order
+    get products() {
+        return this._products;
+    }
+    // The one price list a storefront sells from - MeraBills Online - and null until it arrives.
+    // Every price in this catalog belongs to it; a price in any other list is not sold here and is
+    // left out. A shopping list names this list, or falls back to its id when it has none set.
+    get priceList() {
+        return this._priceList;
+    }
+    get productCount() {
+        return this._products.length;
+    }
+    get packageCount() {
+        return this._packageMap.size;
+    }
+    getCategory(productCategoryId) {
+        return this._categoryMap.get(productCategoryId) ?? null;
+    }
+    getProduct(productId) {
+        return this._productMap.get(productId) ?? null;
+    }
+    // Returns null for the four reserved package ids a shopping list uses for its charge and
+    // summary lines (see Ids.isReservedPackageId), and for a package whose product was deleted
+    getPackage(packageId) {
+        return this._packageMap.get(packageId) ?? null;
+    }
+    // Display comparator for packages, matching the merchant app's PackageComparator (minus clauses
+    // a storefront can never exercise: disabled packages and the purchase price list, neither sent)
+    static comparePackages(left, right) {
+        const byName = Catalog.compareNames(left.name, right.name);
+        if (byName !== 0)
+            return byName;
+        const byPrice = Catalog.comparePrices(left.price, right.price);
+        if (byPrice !== 0)
+            return byPrice;
+        return Catalog.compareIds(left, right);
+    }
+    // Display comparator for items generally: case insensitive, numeric, id-tiebroken
+    static compareByName(left, right) {
+        const byName = Catalog.compareNames(left.name, right.name);
+        if (byName !== 0)
+            return byName;
+        return Catalog.compareIds(left, right);
+    }
+    static compareNames(left, right) {
+        return left.localeCompare(right, undefined, { numeric: true, sensitivity: "accent" });
+    }
+    static compareIds(left, right) {
+        return left.id < right.id ? -1 : left.id > right.id ? 1 : 0;
+    }
+    static comparePrices(left, right) {
+        // A package with no price sorts after one with a price: it cannot be bought
+        if (left === null)
+            return right === null ? 0 : 1;
+        if (right === null)
+            return -1;
+        return left.offerPrice - right.offerPrice;
+    }
+}
+// A business whose catalog has not arrived yet
+Catalog.EMPTY = new Catalog(Object.freeze([]), Object.freeze([]), null);
+export default Catalog;

package/dist/Constants.d.ts

@@ -0,0 +1,10 @@
+export { Constants } from "./generated/Constants";
+export declare function buildPriceListId(priceList: number): bigint;
+export declare const MERABILLS_ONLINE_PRICE_LIST_ID: bigint;
+export declare const MAX_SCALED_AMOUNT: bigint;
+export declare function amountFromScaledValue(scaledAmount: bigint): number;
+export declare function amountToScaledValue(amount: number): bigint;
+export declare function quantityFromScaledValue(scaledQuantity: number): number;
+export declare function quantityToScaledValue(quantity: number): number;
+export declare function taxRateFromScaledValue(scaledTaxRate: number): number;
+export declare function taxRateToScaledValue(taxRate: number): number;

package/dist/Constants.js

@@ -0,0 +1,43 @@
+import { Constants as proto_Constants } from "./generated/Constants";
+import Ids from "./Ids";
+// The protocol's limits and scaling factors, and the wire-to-UI value conversions.
+// Limits are re-exported rather than redeclared, so a Java constant has only one place to be wrong.
+export { Constants } from "./generated/Constants";
+// The id of a built-in price list, from the low part Constants carries for it:
+// DEFAULT_SALE_PRICE_LIST, DEFAULT_PURCHASE_PRICE_LIST, MERABILLS_ONLINE_PRICE_LIST,
+// AMAZON_SELLER_PRICE_LIST, FACEBOOK_MARKETPLACE_PRICE_LIST or WHATSAPP_BUSINESS_PRICE_LIST. These
+// are the six ids of Java PriceListIds, built the way it builds them: the low part is a constant
+// of the protocol, the id is not, 64 bits not fitting a protobuf enum value.
+export function buildPriceListId(priceList) {
+    return Ids.buildId(proto_Constants.PRICE_LIST_ENTITY_TYPE_ID, BigInt(priceList));
+}
+// The only price list this library reads. A business prices the same package in several lists -
+// what it sells at over the counter, what a marketplace it also sells on charges - and only this
+// one is its storefront's. A price in any other list is passed over; see ProtoMap.buildBusiness.
+export const MERABILLS_ONLINE_PRICE_LIST_ID = buildPriceListId(proto_Constants.MERABILLS_ONLINE_PRICE_LIST);
+// The largest amount the protocol can carry (Java Transaction.MAX_AMOUNT); kept here since it doesn't fit
+// a protobuf enum value. Unscaled it's well below 2^53, so an amount is always safe as a number.
+export const MAX_SCALED_AMOUNT = 17592186044415n;
+// An amount, price or discount travels multiplied by Constants.AMOUNT_FACTOR, bounded by
+// MAX_SCALED_AMOUNT, so it's safe as a number even though it arrives as an int64.
+export function amountFromScaledValue(scaledAmount) {
+    return Number(scaledAmount) / proto_Constants.AMOUNT_FACTOR;
+}
+export function amountToScaledValue(amount) {
+    return BigInt(Math.round(amount * proto_Constants.AMOUNT_FACTOR));
+}
+// A quantity travels multiplied by Constants.QUANTITY_FACTOR, so 1.5 kg arrives as 1500
+export function quantityFromScaledValue(scaledQuantity) {
+    return scaledQuantity / proto_Constants.QUANTITY_FACTOR;
+}
+export function quantityToScaledValue(quantity) {
+    return Math.round(quantity * proto_Constants.QUANTITY_FACTOR);
+}
+// A tax rate travels multiplied by Constants.TAX_RATE_FACTOR, so 18% arrives as 1800. What comes
+// back is a percentage and not a fraction: 18, not 0.18.
+export function taxRateFromScaledValue(scaledTaxRate) {
+    return scaledTaxRate / (proto_Constants.TAX_RATE_FACTOR / 100);
+}
+export function taxRateToScaledValue(taxRate) {
+    return Math.round(taxRate * (proto_Constants.TAX_RATE_FACTOR / 100));
+}

package/dist/ContainerNames.d.ts

@@ -0,0 +1,2 @@
+export declare function forBusiness(nameSuffix: string): string;
+export declare function forProfile(nameSuffix: string): string;

package/dist/ContainerNames.js

@@ -0,0 +1,21 @@
+// What each container of the local store is called: a business container prefixes Business.businessId,
+// a profile container prefixes the subject id. The prefix keeps the two id spaces from ever colliding.
+// One business, holding that business and everything in its business database
+export function forBusiness(nameSuffix) {
+    return `${VERSION_PREFIX}${BUSINESS_PREFIX}${nameSuffix}`;
+}
+// One signed in subject, holding their profile database and the tokens that sign their requests.
+// Several can coexist so signing back in after a sign-out is incremental rather than a fresh download.
+export function forProfile(nameSuffix) {
+    return `${VERSION_PREFIX}${PROFILE_PREFIX}${nameSuffix}`;
+}
+// Every name carries the layout version of what is inside it, so that a change to how this library
+// stores a container does not have to be migrated: the new version simply reads and writes names
+// nothing has written before, and what the old one left behind is inert until it is deleted.
+// Bump this whenever a stored blob stops meaning what it used to - a caller cannot be relied on to
+// clear a store it did not know had changed, and a half-understood container is worse than no cache.
+const VERSION_PREFIX = "V1.";
+// Neither id space is this library's to constrain, so a subject id that happened to equal a business
+// id would otherwise put a profile and a catalog in one container
+const BUSINESS_PREFIX = "b.";
+const PROFILE_PREFIX = "p.";

package/dist/Database.d.ts

@@ -0,0 +1,15 @@
+export default interface Database {
+    getContainer(name: string): Promise<Container>;
+    getContainerNames(): Promise<ReadonlyArray<string>>;
+    deleteContainer(name: string): Promise<void>;
+}
+export interface Container {
+    read(id: bigint): Promise<StoredBlob | null>;
+    readAll(): Promise<ReadonlyArray<StoredBlob>>;
+    write(blobs: ReadonlyArray<StoredBlob>, deletes: ReadonlyArray<bigint>): Promise<number>;
+}
+export interface StoredBlob {
+    readonly id: bigint;
+    readonly eTag: bigint | null;
+    readonly bytes: Uint8Array;
+}

package/dist/Database.js

@@ -0,0 +1 @@
+export {};

package/dist/Entity.d.ts

@@ -0,0 +1,27 @@
+export default abstract class Entity {
+    protected constructor(header: EntityHeader);
+    get id(): bigint;
+    get createdAt(): Date;
+    get updatedAt(): Date;
+    get updateNumber(): bigint;
+    get updateInfo(): bigint;
+    get entityType(): number;
+    get updateType(): number;
+    get isDeleted(): boolean;
+    get parent(): Entity | null;
+    protected set parent(value: Entity | null);
+    private static readonly UPDATE_TYPE_MASK;
+    private readonly _header;
+    private _parent;
+}
+export declare class EntityHeader {
+    readonly id: bigint;
+    readonly createdAt: bigint;
+    readonly updatedAt: bigint;
+    readonly updateNumber: bigint;
+    readonly updateInfo: bigint;
+    constructor(id: bigint, createdAt: bigint, updatedAt: bigint, updateNumber: bigint, updateInfo: bigint);
+}
+export declare class UpdatableEntity extends Entity {
+    static setParent(child: Entity, parent: Entity | null): void;
+}

package/dist/Entity.js

@@ -0,0 +1,69 @@
+import { Constants as proto_Constants } from "./generated/Constants";
+import Ids from "./Ids";
+// Something the protocol syncs one at a time: an id, create/update times, an update number, and
+// the database it was last updated in. Rebuilt from the wire rather than edited in place, so the
+// only mutable field is parent, set once containment is rebuilt after a sync (nothing nests on the wire).
+class Entity {
+    constructor(header) {
+        this._parent = null;
+        this._header = header;
+    }
+    get id() {
+        return this._header.id;
+    }
+    get createdAt() {
+        return new Date(Number(this._header.createdAt));
+    }
+    get updatedAt() {
+        return new Date(Number(this._header.updatedAt));
+    }
+    // Monotonically increasing, and only comparable within the same entity type and database. Basis of a sync cursor.
+    get updateNumber() {
+        return this._header.updateNumber;
+    }
+    // The database this entity was last updated in (Constants.MASTER_DB_ID = the server); sync out uses it
+    // to avoid echoing a store's own changes back. Business entities only - always ENTITY_ID_NULL on profile entities.
+    get updateInfo() {
+        return this._header.updateInfo;
+    }
+    // One of the Constants.*_ENTITY_TYPE_ID values, read from the id's most significant byte (not on the wire).
+    get entityType() {
+        return Ids.getEntityTypeId(this.id);
+    }
+    // One of Constants.UPDATE_TYPE_CREATED, _MODIFIED or _DELETED, held in the update number's last two bits.
+    get updateType() {
+        return Number(this._header.updateNumber & Entity.UPDATE_TYPE_MASK);
+    }
+    // A deleted entity is a tombstone: only the header fields are meaningful. A UI never reaches one.
+    get isDeleted() {
+        return this.updateType === proto_Constants.UPDATE_TYPE_DELETED;
+    }
+    // What contains this entity, once the sync layer has rebuilt containment (e.g. the Business of a
+    // Configuration). Null while being built, and on Business itself, which is the root.
+    get parent() {
+        return this._parent;
+    }
+    set parent(value) {
+        this._parent = value;
+    }
+}
+Entity.UPDATE_TYPE_MASK = BigInt(proto_Constants.UPDATE_TYPE_MASK);
+export default Entity;
+// The fields of the Entity message every entity carries, passed as one value since they're all
+// bigint and would otherwise transpose silently at a call site (the protocol has moved one before).
+export class EntityHeader {
+    constructor(id, createdAt, updatedAt, updateNumber, updateInfo) {
+        this.id = id;
+        this.createdAt = createdAt;
+        this.updatedAt = updatedAt;
+        this.updateNumber = updateNumber;
+        this.updateInfo = updateInfo;
+    }
+}
+// Lets the sync layer set an entity's parent via casting, kept off the surface a UI sees.
+// Static because the setter it reaches is protected.
+export class UpdatableEntity extends Entity {
+    static setParent(child, parent) {
+        child.parent = parent;
+    }
+}