@final-commerce/common 2.1.1 → 2.2.0-beta.1

package/dist/index.mjs

@@ -228,6 +228,7 @@ var InventorySpecificActionType = /* @__PURE__ */ ((InventorySpecificActionType2
   InventorySpecificActionType2["REFUND_RESTOCK_RETURN"] = "REFUND_RESTOCK_RETURN";
   InventorySpecificActionType2["REFUND_DAMAGE"] = "REFUND_DAMAGE";
   InventorySpecificActionType2["SALE"] = "SALE";
+  InventorySpecificActionType2["COMPOSED_FOR_SALE"] = "COMPOSED_FOR_SALE";
   InventorySpecificActionType2["TRANSFER"] = "TRANSFER";
   InventorySpecificActionType2["BULK_RECOUNT"] = "BULK_RECOUNT";
   InventorySpecificActionType2["APPLIED_FROM_WOO"] = "APPLIED_FROM_WOO";
@@ -717,6 +718,252 @@ function amountToString(amount) {
   return majorValue.toFixed(amount.minorUnits);
 }
 
+// units/system-units.ts
+var SYSTEM_FAMILY_IDS = {
+  COUNT: "count",
+  WEIGHT: "weight-metric",
+  WEIGHT_IMPERIAL: "weight-imperial",
+  VOLUME: "volume-metric",
+  VOLUME_IMPERIAL: "volume-imperial",
+  LENGTH: "length-metric",
+  LENGTH_IMPERIAL: "length-imperial",
+  AREA: "area-metric",
+  AREA_IMPERIAL: "area-imperial"
+};
+var SYSTEM_UNIT_IDS = {
+  EACH: "EA",
+  GRAM: "GRM",
+  KILOGRAM: "KGM",
+  /** 100 g is a hectogram; the merchant-facing name stays "100 g". */
+  HECTOGRAM: "HGM",
+  MILLILITRE: "MLT",
+  LITRE: "LTR"
+};
+var SYSTEM_FAMILIES = [
+  {
+    familyId: SYSTEM_FAMILY_IDS.COUNT,
+    companyId: null,
+    name: "Count",
+    base: { name: "Piece", abbreviation: "ea", ratioToBase: 1, precision: 0 }
+  },
+  {
+    familyId: SYSTEM_FAMILY_IDS.WEIGHT,
+    companyId: null,
+    name: "Weight",
+    base: { name: "Gram", abbreviation: "g", ratioToBase: 1, precision: 0 }
+  },
+  {
+    familyId: SYSTEM_FAMILY_IDS.WEIGHT_IMPERIAL,
+    companyId: null,
+    name: "Weight (imperial)",
+    base: { name: "Hundred-thousandth of an ounce", abbreviation: "10\u207B\u2075 oz", ratioToBase: 1, precision: 0 }
+  },
+  {
+    familyId: SYSTEM_FAMILY_IDS.VOLUME,
+    companyId: null,
+    name: "Volume",
+    base: { name: "Millilitre", abbreviation: "ml", ratioToBase: 1, precision: 0 }
+  },
+  {
+    // Cubic inches, not fluid ounces: a US gallon is 231 in³ and 128 fl oz, and 231 = 3 × 7 × 11.
+    // With an ounce base the board foot lands on 6144000/77 — and lumber is the reason this family
+    // exists at all.
+    familyId: SYSTEM_FAMILY_IDS.VOLUME_IMPERIAL,
+    companyId: null,
+    name: "Volume (imperial)",
+    base: { name: "1/128000 cubic inch", abbreviation: "\xB5in\xB3", ratioToBase: 1, precision: 0 }
+  },
+  {
+    familyId: SYSTEM_FAMILY_IDS.LENGTH,
+    companyId: null,
+    name: "Length",
+    base: { name: "Millimetre", abbreviation: "mm", ratioToBase: 1, precision: 0 }
+  },
+  {
+    familyId: SYSTEM_FAMILY_IDS.LENGTH_IMPERIAL,
+    companyId: null,
+    name: "Length (imperial)",
+    base: { name: "Millionth of an inch", abbreviation: "\xB5in", ratioToBase: 1, precision: 0 }
+  },
+  {
+    familyId: SYSTEM_FAMILY_IDS.AREA,
+    companyId: null,
+    name: "Area",
+    base: { name: "Square millimetre", abbreviation: "mm\xB2", ratioToBase: 1, precision: 0 }
+  },
+  {
+    familyId: SYSTEM_FAMILY_IDS.AREA_IMPERIAL,
+    companyId: null,
+    name: "Area (imperial)",
+    base: { name: "Thousandth of a square inch", abbreviation: "m-sq in", ratioToBase: 1, precision: 0 }
+  }
+];
+var unit = (unitId, familyId, name, abbreviation, ratioToBase, precision) => ({ unitId, companyId: null, familyId, name, abbreviation, ratioToBase, precision });
+var SELLABLE_UNITS = [
+  // ── Count ────────────────────────────────────────────────────────────────
+  unit("EA", SYSTEM_FAMILY_IDS.COUNT, "Each", "ea", 1, 0),
+  unit("PR", SYSTEM_FAMILY_IDS.COUNT, "Pair", "pr", 2, 0),
+  unit("DZN", SYSTEM_FAMILY_IDS.COUNT, "Dozen", "dz", 12, 0),
+  unit("GRO", SYSTEM_FAMILY_IDS.COUNT, "Gross", "gro", 144, 0),
+  unit("CEN", SYSTEM_FAMILY_IDS.COUNT, "Hundred", "C", 100, 0),
+  unit("MIL", SYSTEM_FAMILY_IDS.COUNT, "Thousand", "M", 1e3, 0),
+  // ── Weight, metric ───────────────────────────────────────────────────────
+  unit("GRM", SYSTEM_FAMILY_IDS.WEIGHT, "Gram", "g", 1, 0),
+  unit("HGM", SYSTEM_FAMILY_IDS.WEIGHT, "100 g", "100g", 100, 2),
+  unit("KGM", SYSTEM_FAMILY_IDS.WEIGHT, "Kilogram", "kg", 1e3, 3),
+  unit("TNE", SYSTEM_FAMILY_IDS.WEIGHT, "Tonne", "t", 1e6, 3),
+  // ── Weight, imperial ─────────────────────────────────────────────────────
+  unit("ONZ", SYSTEM_FAMILY_IDS.WEIGHT_IMPERIAL, "Ounce", "oz", 1e5, 2),
+  unit("LBR", SYSTEM_FAMILY_IDS.WEIGHT_IMPERIAL, "Pound", "lb", 16e5, 2),
+  unit("STI", SYSTEM_FAMILY_IDS.WEIGHT_IMPERIAL, "Stone", "st", 224e5, 2),
+  // `(US)` is not decoration: Rec 20 also carries `CWI`, the UK hundredweight, at 112 lb — 12 % more.
+  // The code here is the right one; an unqualified "cwt" on screen is what would be ambiguous.
+  unit("CWA", SYSTEM_FAMILY_IDS.WEIGHT_IMPERIAL, "Hundredweight (US)", "cwt (US)", 16e7, 2),
+  unit("STN", SYSTEM_FAMILY_IDS.WEIGHT_IMPERIAL, "Ton (short)", "tn", 32e8, 3),
+  // ── Volume, metric ───────────────────────────────────────────────────────
+  unit("MLT", SYSTEM_FAMILY_IDS.VOLUME, "Millilitre", "ml", 1, 0),
+  unit("CLT", SYSTEM_FAMILY_IDS.VOLUME, "Centilitre", "cl", 10, 1),
+  unit("LTR", SYSTEM_FAMILY_IDS.VOLUME, "Litre", "l", 1e3, 3),
+  unit("HLT", SYSTEM_FAMILY_IDS.VOLUME, "Hectolitre", "hl", 1e5, 3),
+  unit("MTQ", SYSTEM_FAMILY_IDS.VOLUME, "Cubic metre", "m\xB3", 1e6, 3),
+  // ── Volume, imperial ─────────────────────────────────────────────────────
+  unit("OZA", SYSTEM_FAMILY_IDS.VOLUME_IMPERIAL, "Fluid ounce", "fl oz", 231e3, 2),
+  unit("PTL", SYSTEM_FAMILY_IDS.VOLUME_IMPERIAL, "Pint", "pt", 3696e3, 2),
+  unit("QTL", SYSTEM_FAMILY_IDS.VOLUME_IMPERIAL, "Quart", "qt", 7392e3, 2),
+  unit("GLL", SYSTEM_FAMILY_IDS.VOLUME_IMPERIAL, "Gallon", "gal", 29568e3, 3),
+  unit("INQ", SYSTEM_FAMILY_IDS.VOLUME_IMPERIAL, "Cubic inch", "in\xB3", 128e3, 2),
+  unit("BFT", SYSTEM_FAMILY_IDS.VOLUME_IMPERIAL, "Board foot", "fbm", 18432e3, 2),
+  unit("FTQ", SYSTEM_FAMILY_IDS.VOLUME_IMPERIAL, "Cubic foot", "ft\xB3", 221184e3, 3),
+  unit("YDQ", SYSTEM_FAMILY_IDS.VOLUME_IMPERIAL, "Cubic yard", "yd\xB3", 5971968e3, 3),
+  // ── Length, metric ───────────────────────────────────────────────────────
+  unit("MMT", SYSTEM_FAMILY_IDS.LENGTH, "Millimetre", "mm", 1, 0),
+  unit("CMT", SYSTEM_FAMILY_IDS.LENGTH, "Centimetre", "cm", 10, 1),
+  unit("MTR", SYSTEM_FAMILY_IDS.LENGTH, "Metre", "m", 1e3, 3),
+  unit("KMT", SYSTEM_FAMILY_IDS.LENGTH, "Kilometre", "km", 1e6, 3),
+  // ── Length, imperial ─────────────────────────────────────────────────────
+  // `INH` carries four decimals, not three: an eighth of an inch is 0.125 but a sixteenth is
+  // 0.0625, and sixteenths are the everyday fraction on a tape measure. A thirty-second needs five,
+  // which is the ceiling; a sixty-fourth has no decimal form at all and is a question about
+  // fraction input, not about precision.
+  unit("INH", SYSTEM_FAMILY_IDS.LENGTH_IMPERIAL, "Inch", "in", 1e6, 4),
+  unit("FOT", SYSTEM_FAMILY_IDS.LENGTH_IMPERIAL, "Foot", "ft", 12e6, 3),
+  unit("LF", SYSTEM_FAMILY_IDS.LENGTH_IMPERIAL, "Linear foot", "lin ft", 12e6, 2),
+  unit("YRD", SYSTEM_FAMILY_IDS.LENGTH_IMPERIAL, "Yard", "yd", 36e6, 3),
+  unit("SMI", SYSTEM_FAMILY_IDS.LENGTH_IMPERIAL, "Mile", "mi", 6336e7, 3),
+  // ── Area, metric ─────────────────────────────────────────────────────────
+  unit("MMK", SYSTEM_FAMILY_IDS.AREA, "Square millimetre", "mm\xB2", 1, 0),
+  unit("CMK", SYSTEM_FAMILY_IDS.AREA, "Square centimetre", "cm\xB2", 100, 2),
+  unit("MTK", SYSTEM_FAMILY_IDS.AREA, "Square metre", "m\xB2", 1e6, 3),
+  unit("HAR", SYSTEM_FAMILY_IDS.AREA, "Hectare", "ha", 1e10, 3),
+  // ── Area, imperial ───────────────────────────────────────────────────────
+  unit("INK", SYSTEM_FAMILY_IDS.AREA_IMPERIAL, "Square inch", "sq in", 1e3, 2),
+  unit("FTK", SYSTEM_FAMILY_IDS.AREA_IMPERIAL, "Square foot", "sq ft", 144e3, 2),
+  unit("YDK", SYSTEM_FAMILY_IDS.AREA_IMPERIAL, "Square yard", "sq yd", 1296e3, 2),
+  // A roofing square is exactly 100 square feet — a trade unit with a precise definition, which is
+  // why it is a real row and not a label.
+  unit("SQR", SYSTEM_FAMILY_IDS.AREA_IMPERIAL, "Square (roofing)", "sq", 144e5, 2),
+  unit("ACR", SYSTEM_FAMILY_IDS.AREA_IMPERIAL, "Acre", "ac", 627264e4, 2)
+];
+var BASE_UNITS = SYSTEM_FAMILIES.filter(
+  (family) => !SELLABLE_UNITS.some((u) => u.familyId === family.familyId && u.ratioToBase === 1)
+).map((family) => ({
+  unitId: `${family.familyId}-base`,
+  companyId: null,
+  familyId: family.familyId,
+  name: family.base.name,
+  abbreviation: family.base.abbreviation,
+  ratioToBase: 1,
+  precision: 0,
+  sellable: false
+}));
+var SYSTEM_UNITS = [...SELLABLE_UNITS, ...BASE_UNITS];
+var DEFAULT_UNIT_ID = SYSTEM_UNIT_IDS.EACH;
+
+// units/convert.ts
+var EPSILON = 1e-9;
+function isWhole(value) {
+  return Math.abs(value - Math.round(value)) <= EPSILON * Math.max(1, Math.abs(value));
+}
+var MAX_PRECISION = 5;
+function resolveUnit(unitId, companyUnits = []) {
+  const unit2 = SYSTEM_UNITS.find((u) => u.unitId === unitId) ?? companyUnits.find((u) => u.unitId === unitId);
+  if (!unit2) throw new Error(`Unknown measurement unit: ${unitId}`);
+  return unit2;
+}
+function resolveFamily(familyId, companyFamilies = []) {
+  const family = SYSTEM_FAMILIES.find((f) => f.familyId === familyId) ?? companyFamilies.find((f) => f.familyId === familyId);
+  if (!family) throw new Error(`Unknown measurement unit family: ${familyId}`);
+  return family;
+}
+function baseOf(familyId, companyFamilies = []) {
+  return resolveFamily(familyId, companyFamilies).base;
+}
+function baseFor(unit2, companyFamilies = []) {
+  return baseOf(unit2.familyId, companyFamilies);
+}
+function sameFamily(a, b) {
+  return a.familyId === b.familyId;
+}
+function assertUnitSane(unit2) {
+  const { ratioToBase, precision, name } = unit2;
+  if (!Number.isInteger(ratioToBase) || ratioToBase < 1)
+    throw new Error(`Unit "${name}": ratioToBase must be a positive integer, got ${ratioToBase}`);
+  if (!Number.isInteger(precision) || precision < 0 || precision > MAX_PRECISION)
+    throw new Error(`Unit "${name}": precision must be an integer 0\u2013${MAX_PRECISION}, got ${precision}`);
+  if (ratioToBase % 10 ** precision !== 0)
+    throw new Error(
+      `Unit "${name}": precision ${precision} is finer than a ratio of ${ratioToBase} allows \u2014 at most ${maxPrecisionFor(ratioToBase)}. For anything finer the family needs a smaller base unit.`
+    );
+}
+function maxPrecisionFor(ratioToBase) {
+  if (!Number.isInteger(ratioToBase) || ratioToBase < 1)
+    throw new Error(`ratioToBase must be a positive integer, got ${ratioToBase}`);
+  let precision = 0;
+  while (precision < MAX_PRECISION && ratioToBase % 10 ** (precision + 1) === 0) precision++;
+  return precision;
+}
+function isValidQuantity(quantity, unit2) {
+  if (!Number.isFinite(quantity) || quantity < 0) return false;
+  return isWhole(quantity * 10 ** unit2.precision);
+}
+function toBase(quantity, unit2) {
+  const exact = quantity * unit2.ratioToBase;
+  const whole = Math.round(exact);
+  if (!isWhole(exact))
+    throw new Error(
+      `${quantity} ${unit2.abbreviation} is ${exact} base units \u2014 not whole. Check the quantity against precision ${unit2.precision}.`
+    );
+  return whole;
+}
+function fromBase(baseQuantity, unit2) {
+  return baseQuantity / unit2.ratioToBase;
+}
+function availableIn(baseQuantity, unit2) {
+  const step = unit2.ratioToBase / 10 ** unit2.precision;
+  return Math.floor(baseQuantity / step) / 10 ** unit2.precision;
+}
+function formatQuantity(baseQuantity, unit2) {
+  return fromBase(baseQuantity, unit2).toFixed(unit2.precision);
+}
+function formatInUnit(quantity, unit2) {
+  return quantity.toFixed(unit2.precision);
+}
+function roundToPrecision(quantity, precision) {
+  const scale = 10 ** precision;
+  return Math.round(quantity * scale) / scale;
+}
+function extendPrice(priceMinor, quantity) {
+  const scale = 10 ** MAX_PRECISION;
+  const scaled = BigInt(Math.round(priceMinor)) * BigInt(Math.round(quantity * scale));
+  const divisor = BigInt(scale);
+  return Number((scaled + divisor / 2n) / divisor);
+}
+function extendPriceFor(priceMinor, quantity, unit2) {
+  if (!isValidQuantity(quantity, unit2))
+    throw new Error(`${quantity} ${unit2.abbreviation} has more decimals than precision ${unit2.precision} allows.`);
+  return extendPrice(priceMinor, quantity);
+}
+
 // utils/order-totals.util.ts
 function toMinorUnits2(value) {
   return Number(value) || 0;
@@ -734,7 +981,7 @@ function getSettlementTotal(payments, tipTotal) {
   return toMinorUnits2(payments?.cardTotal) + toMinorUnits2(payments?.cashTotal) + toMinorUnits2(payments?.customTotal) + toMinorUnits2(tipTotal);
 }
 function getLineSubtotal(price, quantity) {
-  return toMinorUnits2(price) * toMinorUnits2(quantity);
+  return extendPrice(toMinorUnits2(price), toMinorUnits2(quantity));
 }
 function getGoodsPortion(total, totalTax) {
   return toMinorUnits2(total) - toMinorUnits2(totalTax);
@@ -1058,6 +1305,31 @@ function normalizeMongoIdString(value) {
   return null;
 }
 
+// units/family-code.ts
+var MAX_SLUG_LENGTH = 32;
+var FALLBACK_SLUG = "family";
+var SYSTEM_FAMILY_CODES = new Set(SYSTEM_FAMILIES.map((family) => family.familyId));
+function slugify(name) {
+  const slug = name.normalize("NFKD").replace(/\p{Diacritic}/gu, "").toLowerCase().replace(/[^a-z0-9]+/g, "-").slice(0, MAX_SLUG_LENGTH).replace(/^-+|-+$/g, "");
+  return slug || FALLBACK_SLUG;
+}
+function deriveFamilyCode(name, companyId, takenCodes = []) {
+  if (!companyId) throw new Error(`Cannot derive a family code for "${name}" without a companyId.`);
+  const taken = new Set(takenCodes);
+  const slug = slugify(name);
+  for (let attempt = 1; ; attempt++) {
+    const code = attempt === 1 ? `${slug}-${companyId}` : `${slug}-${attempt}-${companyId}`;
+    if (!taken.has(code) && !isSystemFamilyCode(code)) return code;
+  }
+}
+function isSystemFamilyCode(code) {
+  return SYSTEM_FAMILY_CODES.has(code);
+}
+function deriveUnitId(abbreviation, documentId) {
+  if (!documentId) throw new Error(`Cannot derive a unit id for "${abbreviation}" without a document id.`);
+  return `${slugify(abbreviation)}-${documentId}`;
+}
+
 // order-state-machine/types.ts
 var PAYMENT_STATES = [
   "unpaid",
@@ -2487,6 +2759,7 @@ export {
   DEFAULT_CROSS_AXIS_RULES,
   DEFAULT_DISPLAY_STATE_MAP,
   DEFAULT_RESOLVED_CONFIG,
+  DEFAULT_UNIT_ID,
   DualWriteStrategy,
   EUFixedRates,
   EUROPE,
@@ -2499,6 +2772,7 @@ export {
   InvoiceStatus,
   LegacyWriteStrategy,
   LibraryItemType,
+  MAX_PRECISION,
   MenuProject,
   NAFixedRates,
   NORTH_AMERICA,
@@ -2531,6 +2805,10 @@ export {
   ResidualStatus,
   STATE_SCHEMA,
   STRIPE_SUPPORTED_COUNTRIES,
+  SYSTEM_FAMILIES,
+  SYSTEM_FAMILY_IDS,
+  SYSTEM_UNITS,
+  SYSTEM_UNIT_IDS,
   StationStatus,
   StripeCurrencyCode,
   StripeStatus,
@@ -2539,7 +2817,11 @@ export {
   UserTypes,
   addAmounts,
   amountToString,
+  assertUnitSane,
+  availableIn,
+  baseFor,
   baseFulfillmentDefinitions,
+  baseOf,
   basePaymentDefinitions,
   buildOrderContext,
   buildPosPresetConfig,
@@ -2551,12 +2833,19 @@ export {
   createAmount,
   crossAxisRuleApplies,
   deriveDisplayState,
+  deriveFamilyCode,
+  deriveUnitId,
   displayRuleMatchesPair,
   divideAmount,
   evaluateCondition,
   evaluateConditionSet,
+  extendPrice,
+  extendPriceFor,
   formatCurrency,
+  formatInUnit,
   formatMinorUnitsToString,
+  formatQuantity,
+  fromBase,
   fromMinorUnits,
   generateMongoID,
   getAvailableTransitions,
@@ -2578,7 +2867,11 @@ export {
   isFulfillmentState,
   isPaymentState,
   isSupportedCurrency,
+  isSystemFamilyCode,
+  isValidQuantity,
+  isWhole,
   mapToLegacyStatus,
+  maxPrecisionFor,
   mergeFragment,
   multiplyAmount,
   normalizeMongoIdString,
@@ -2586,11 +2879,16 @@ export {
   parseCurrencyCode,
   parseStripeCurrencyCode,
   removeFragment,
+  resolveFamily,
   resolveTemplate,
+  resolveUnit,
+  roundToPrecision,
+  sameFamily,
   setOrderState,
   signReportForDisplay,
   stringifyMinorUnits,
   subtractAmounts,
+  toBase,
   toMinorUnits,
   validateConfig,
   validateFragmentCompatibility,