@classytic/primitives 0.26.2 → 0.26.4

package/CHANGELOG.md

@@ -3,6 +3,31 @@
 Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 adhering to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.26.4
+
+### Added — `./price-basis` subpath: measured pricing across physical dimensions
+
+New `PriceBasis` type (`FixedPriceBasis | MeasuredPriceBasis`) models how a quoted price spans a sellable quantity — flat fixed or per-unit-of-measure (mass, duration, volume, length, area). Factory functions `fixedPriceBasis()` and `measuredPriceBasis(dimension, qtyUnit, priceUnit, qtyPerPriceUnit)` construct the two shapes; `isPriceBasis()` is a structural guard for DB/wire boundaries. `resolvePriceBasisTotal(unitPriceMinor, quantity, basis?)` converts a minor-unit price × integer quantity to a final minor-unit total using half-even rounding (`roundedDiv` internally) and throws `PriceBasisError` on unsafe inputs or overflow.
+
+### Added — `./unit-cost-rate` re-exports `RoundingMode`
+
+`RoundingMode` (`'half-even' | 'half-up'`) is now defined in the new internal `rounded-div.ts` and re-exported from `unit-cost-rate`. No breaking change — existing consumers who import `RoundingMode` from `@classytic/primitives/unit-cost-rate` continue to work.
+
+### Changed — `validateAddress` / `isAddressValid` accept `Address` directly
+
+Both functions now accept `Address | PartialAddress | null | undefined`, removing the need for a cast when validating a fully-typed value object.
+
+## 0.26.3
+
+### Added — `PaymentProviderPort.wantsRawBody`
+
+Optional `readonly wantsRawBody?: boolean` on the payment gateway port.
+Providers that verify an HMAC signature (Stripe signs the bytes it transmitted)
+must declare `true` — the transport then hands the raw body rather than the
+parsed object. Absent / `false` preserves the historical behaviour (parsed
+body), which is correct for manual, cash and terminal providers that sign
+nothing.
+
 ## 0.26.2
 
 ### Added — `stockKeyFor` (`/item-identity`): one stock-key precedence for every package

package/dist/address.d.mts

@@ -298,9 +298,9 @@ interface AddressFieldError {
  * `'   '` satisfies a naive truthiness check and then prints as a blank line on
  * a courier label. Required means a value, not a character.
  */
-declare function validateAddress(address: PartialAddress | null | undefined, format: AddressFormat): AddressFieldError[];
+declare function validateAddress(address: Address | PartialAddress | null | undefined, format: AddressFormat): AddressFieldError[];
 /** Convenience for a submit gate. */
-declare function isAddressValid(address: PartialAddress | null | undefined, format: AddressFormat): boolean;
+declare function isAddressValid(address: Address | PartialAddress | null | undefined, format: AddressFormat): boolean;
 /** A readable default message, in the country's own vocabulary. */
 declare function describeAddressError(error: AddressFieldError): string;
 //#endregion

package/dist/address.mjs

@@ -162,7 +162,8 @@ function supportedCountries(registry) {
 */
 function validateAddress(address, format) {
 	const errors = [];
-	const value = (k) => String(address?.[k] ?? "").trim();
+	const values = address;
+	const value = (k) => String(values?.[k] ?? "").trim();
 	/**
 	* Canonical and extension fields are checked IDENTICALLY, keyed by
 	* `fieldName`. A required Delivery Area is enforced exactly as a required

package/dist/payment-gateway.d.mts

@@ -277,6 +277,25 @@ interface PaymentProviderPort {
    * without this cannot be auto-reconciled — the engine then RETAINS the reservation.
    */
   getRefundStatus?(query: RefundStatusQuery, command?: PaymentCommandContext): Promise<PaymentResult>;
+  /**
+   * Does this provider need the EXACT transmitted bytes, rather than the
+   * parsed body?
+   *
+   * `true` for anything that verifies an HMAC signature — Stripe signs the
+   * bytes it sent, and a re-serialized object differs in key order, spacing and
+   * unicode escaping, so a check against the parsed form can never pass.
+   *
+   * Declared by the provider rather than decided by the transport, because the
+   * transport cannot know. Handing raw bytes to every provider breaks the ones
+   * that read `payload.sessionId` — they get a string and silently see
+   * `undefined`, so the webhook resolves to no transaction and the payment
+   * never applies. Handing the parsed body to every provider breaks signature
+   * verification. Only the provider knows which it is.
+   *
+   * Absent means `false`: the historical behaviour, and correct for manual,
+   * cash and terminal providers that sign nothing.
+   */
+  readonly wantsRawBody?: boolean;
   handleWebhook(payload: unknown, headers?: Record<string, string>): Promise<WebhookEvent>;
   /**
    * Reject a forged webhook. Returning `true` unconditionally is only acceptable for a

package/dist/price-basis.d.mts

@@ -0,0 +1,31 @@
+//#region src/money/price-basis.d.ts
+/** How a quoted price extends across a sellable quantity. */
+type PriceBasis = FixedPriceBasis | MeasuredPriceBasis;
+interface FixedPriceBasis {
+  readonly kind: 'fixed';
+}
+type MeasureDimension = 'mass' | 'duration' | 'volume' | 'length' | 'area';
+interface MeasuredPriceBasis {
+  readonly kind: 'measured';
+  readonly dimension: MeasureDimension;
+  /** Integer unit carried by the line quantity, such as `gram` or `minute`. */
+  readonly quantityUnit: string;
+  /** Unit named by the quoted price, such as `kilogram` or `hour`. */
+  readonly priceUnit: string;
+  /** Number of quantity units represented by one quoted price unit. */
+  readonly quantityPerPriceUnit: number;
+}
+type PriceBasisErrorCode = 'INVALID_PRICE' | 'INVALID_QUANTITY' | 'INVALID_DENOMINATOR' | 'INVALID_UNIT' | 'UNSAFE_TOTAL';
+declare class PriceBasisError extends Error {
+  readonly name = "PriceBasisError";
+  readonly code: PriceBasisErrorCode;
+  constructor(code: PriceBasisErrorCode, message: string);
+}
+declare function fixedPriceBasis(): FixedPriceBasis;
+declare function measuredPriceBasis(dimension: MeasureDimension, quantityUnit: string, priceUnit: string, quantityPerPriceUnit: number): MeasuredPriceBasis;
+/** Structural guard for database and wire boundaries. */
+declare function isPriceBasis(value: unknown): value is PriceBasis;
+/** Extend a minor-unit price using integer quantity and exact half-even rounding. */
+declare function resolvePriceBasisTotal(unitPriceMinor: number, quantity: number, basis?: PriceBasis): number;
+//#endregion
+export { FixedPriceBasis, MeasureDimension, MeasuredPriceBasis, PriceBasis, PriceBasisError, PriceBasisErrorCode, fixedPriceBasis, isPriceBasis, measuredPriceBasis, resolvePriceBasisTotal };

package/dist/price-basis.mjs

@@ -0,0 +1,51 @@
+import { t as roundedDiv } from "./rounded-div-BWJb98Ws.mjs";
+//#region src/money/price-basis.ts
+var PriceBasisError = class extends Error {
+	name = "PriceBasisError";
+	code;
+	constructor(code, message) {
+		super(message);
+		this.code = code;
+	}
+};
+function fixedPriceBasis() {
+	return { kind: "fixed" };
+}
+function measuredPriceBasis(dimension, quantityUnit, priceUnit, quantityPerPriceUnit) {
+	if (quantityUnit.trim() === "" || priceUnit.trim() === "") throw new PriceBasisError("INVALID_UNIT", "quantityUnit and priceUnit must not be empty");
+	if (!Number.isSafeInteger(quantityPerPriceUnit) || quantityPerPriceUnit <= 0) throw new PriceBasisError("INVALID_DENOMINATOR", "quantityPerPriceUnit must be a positive safe integer");
+	return {
+		kind: "measured",
+		dimension,
+		quantityUnit,
+		priceUnit,
+		quantityPerPriceUnit
+	};
+}
+const MEASURE_DIMENSIONS = /* @__PURE__ */ new Set([
+	"mass",
+	"duration",
+	"volume",
+	"length",
+	"area"
+]);
+/** Structural guard for database and wire boundaries. */
+function isPriceBasis(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const candidate = value;
+	if (candidate.kind === "fixed") return true;
+	return candidate.kind === "measured" && MEASURE_DIMENSIONS.has(candidate.dimension) && typeof candidate.quantityUnit === "string" && candidate.quantityUnit.trim() !== "" && typeof candidate.priceUnit === "string" && candidate.priceUnit.trim() !== "" && typeof candidate.quantityPerPriceUnit === "number" && Number.isSafeInteger(candidate.quantityPerPriceUnit) && candidate.quantityPerPriceUnit > 0;
+}
+/** Extend a minor-unit price using integer quantity and exact half-even rounding. */
+function resolvePriceBasisTotal(unitPriceMinor, quantity, basis = fixedPriceBasis()) {
+	if (!Number.isSafeInteger(unitPriceMinor) || unitPriceMinor < 0) throw new PriceBasisError("INVALID_PRICE", "unitPriceMinor must be a non-negative safe integer");
+	if (!Number.isSafeInteger(quantity) || quantity < 0) throw new PriceBasisError("INVALID_QUANTITY", "quantity must be a non-negative safe integer");
+	const numerator = BigInt(unitPriceMinor) * BigInt(quantity);
+	const denominator = basis.kind === "measured" ? BigInt(basis.quantityPerPriceUnit) : 1n;
+	const rounded = roundedDiv(numerator, denominator, "half-even");
+	const total = Number(rounded);
+	if (!Number.isSafeInteger(total)) throw new PriceBasisError("UNSAFE_TOTAL", "resolved total exceeds Number.MAX_SAFE_INTEGER");
+	return total;
+}
+//#endregion
+export { PriceBasisError, fixedPriceBasis, isPriceBasis, measuredPriceBasis, resolvePriceBasisTotal };

package/dist/rounded-div-BWJb98Ws.mjs

@@ -0,0 +1,13 @@
+//#region src/money/rounded-div.ts
+/** Exact signed integer division rounded at the rational boundary. */
+function roundedDiv(numerator, denominator, mode) {
+	if (denominator <= 0n) throw new RangeError("denominator must be positive");
+	const negative = numerator < 0n;
+	const magnitude = negative ? -numerator : numerator;
+	const quotient = magnitude / denominator;
+	const twiceRemainder = magnitude % denominator * 2n;
+	const rounded = twiceRemainder > denominator || twiceRemainder === denominator && (mode === "half-up" || quotient % 2n !== 0n) ? quotient + 1n : quotient;
+	return negative ? -rounded : rounded;
+}
+//#endregion
+export { roundedDiv as t };

package/dist/unit-cost-rate.d.mts

@@ -1,9 +1,10 @@
 import { t as MinorUnits, w as CurrencyCode } from "./money-CfAvfNiM.mjs";
+//#region src/money/rounded-div.d.ts
+type RoundingMode = 'half-even' | 'half-up';
+//#endregion
 //#region src/money/unit-cost-rate.d.ts
 /** Fixed, ecosystem-wide rate scale: 6 decimal places below the minor unit. */
 declare const RATE_SCALE = 1000000;
-/** Half-to-even (banker's) is the default; half-up available for legacy parity. */
-type RoundingMode = 'half-even' | 'half-up';
 /**
  * Minor units per unit, stored as an integer scaled by {@link RATE_SCALE}.
  * `scale` is carried so a value is self-describing on the wire even if
@@ -67,5 +68,10 @@ declare function weightedAverageScaledRate(onHandQuantity: number, onHandScaledR
 declare function rateMinorPerUnit(rate: UnitCostRate): number;
 /** Structural guard. */
 declare function isUnitCostRate(value: unknown): value is UnitCostRate;
+/**
+ * Rounded integer division of two bigints, `numerator / denominator`
+ * (`denominator > 0`), honouring the rounding mode at the exact half.
+ * Sign-safe for negative numerators.
+ */
 //#endregion
-export { RATE_SCALE, RoundingMode, UnitCostRate, UnitCostRateError, UnitCostRateErrorCode, extendedAmount, isUnitCostRate, rateMinorPerUnit, unitCostRate, unitCostRateFromTotal, weightedAverageScaledRate };
+export { RATE_SCALE, type RoundingMode, UnitCostRate, UnitCostRateError, UnitCostRateErrorCode, extendedAmount, isUnitCostRate, rateMinorPerUnit, unitCostRate, unitCostRateFromTotal, weightedAverageScaledRate };

package/dist/unit-cost-rate.mjs

@@ -1,4 +1,5 @@
 import { MinorUnits } from "./money.mjs";
+import { t as roundedDiv } from "./rounded-div-BWJb98Ws.mjs";
 //#region src/money/unit-cost-rate.ts
 /** Fixed, ecosystem-wide rate scale: 6 decimal places below the minor unit. */
 const RATE_SCALE = 1e6;
@@ -127,19 +128,5 @@ function isUnitCostRate(value) {
 * (`denominator > 0`), honouring the rounding mode at the exact half.
 * Sign-safe for negative numerators.
 */
-function roundedDiv(numerator, denominator, mode) {
-	const neg = numerator < 0n;
-	const n = neg ? -numerator : numerator;
-	const q = n / denominator;
-	const remainder = n - q * denominator;
-	if (remainder === 0n) return neg ? -q : q;
-	const twiceRem = remainder * 2n;
-	let up;
-	if (twiceRem > denominator) up = true;
-	else if (twiceRem < denominator) up = false;
-	else up = mode === "half-up" ? true : q % 2n !== 0n;
-	const result = up ? q + 1n : q;
-	return neg ? -result : result;
-}
 //#endregion
 export { RATE_SCALE, UnitCostRateError, extendedAmount, isUnitCostRate, rateMinorPerUnit, unitCostRate, unitCostRateFromTotal, weightedAverageScaledRate };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/primitives",
-  "version": "0.26.2",
+  "version": "0.26.4",
   "description": "Framework-agnostic TypeScript primitives shared across Classytic packages — Money, events, pagination, tenant config, and other building blocks.",
   "author": "Classytic",
   "license": "MIT",
@@ -33,6 +33,10 @@
       "types": "./dist/unit-cost-rate.d.mts",
       "default": "./dist/unit-cost-rate.mjs"
     },
+    "./price-basis": {
+      "types": "./dist/price-basis.d.mts",
+      "default": "./dist/price-basis.mjs"
+    },
     "./address": {
       "types": "./dist/address.d.mts",
       "default": "./dist/address.mjs"