@classytic/primitives 0.26.3 → 0.27.0

package/CHANGELOG.md

@@ -3,6 +3,44 @@
 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.27.0
+
+### Added — `./csv` subpath: one CSV cell escaper for the whole fleet
+
+`escapeCsvCell(value)` and `neutralizeCsvFormula(value)`. Six CSV producers
+across ledger, the spine and the hosts each hand-rolled RFC 4180 quoting, and
+not one neutralized a leading `= + - @ \t \r` — so a customer-supplied payment
+reference or party name reached the accountant's spreadsheet as a live formula.
+Quoting does not help: a spreadsheet strips the quotes and evaluates what is
+left, which is why the two defences ship as one module.
+
+The two functions are separable on purpose. A consumer holding a real CSV
+writer (`csv-stringify`) takes `neutralizeCsvFormula` only, so its quoting is
+not done twice; a hand-rolled `rows.map(...).join(',')` takes `escapeCsvCell`.
+
+**Well-formed numbers are exempt.** Prefixing `-1500` would make every negative
+amount text and break `SUM` in every finance export — a fix that quietly
+corrupts the product is worse than the hole. The exemption requires the WHOLE
+cell to be a number, so `-2+3+cmd|'/c calc'!A0` is still neutralized.
+
+Not for a machine-to-machine upload contract with a fixed column spec (a
+courier's bulk-import CSV): there the receiver is a parser, not a spreadsheet,
+and an added `'` corrupts the payload.
+
+## 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`

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/csv.d.mts

@@ -0,0 +1,36 @@
+//#region src/serialization/csv.d.ts
+/**
+ * `@classytic/primitives/csv` — make one value safe to put in a CSV cell.
+ *
+ * Two defences, deliberately separable because a consumer that already has a
+ * real CSV writer must NOT get its quoting done twice:
+ *
+ *   - `neutralizeCsvFormula` — stops the cell being executed as a formula when
+ *     the file is opened in Excel / Sheets / LibreOffice. Use this when a
+ *     library (`csv-stringify`, `papaparse`, …) is doing the quoting.
+ *   - `escapeCsvCell` — neutralize + RFC 4180 quoting. Use this in a
+ *     hand-rolled `rows.map(...).join(',')` serializer.
+ *
+ * WHY quoting is not enough: a spreadsheet strips the quotes first and
+ * evaluates what is left, so `"=cmd|'/c calc'!A1"` still executes. Only
+ * changing the LEADING character stops it, which is why these are one module
+ * and not a quoting helper someone can use alone.
+ *
+ * Well-formed numbers are exempt. Prefixing `-1500` would make every negative
+ * amount text and break the reader's `SUM` — a fix that quietly corrupts every
+ * finance export is worse than the hole. The exemption is the WHOLE cell
+ * matching a number, so `-2+3+cmd|'/c calc'!A0` is still neutralized.
+ *
+ * NOT for a machine-to-machine upload contract with a fixed column spec (a
+ * courier's bulk-import CSV, say) — there the receiver is a parser, not a
+ * spreadsheet, and an added `'` corrupts the payload.
+ */
+/**
+ * Prefix `'` when the cell would otherwise be evaluated as a formula.
+ * `null`/`undefined` become `''`. Numbers are returned unchanged.
+ */
+declare function neutralizeCsvFormula(value: unknown): string;
+/** `neutralizeCsvFormula` + RFC 4180 quoting. The one-call form. */
+declare function escapeCsvCell(value: unknown): string;
+//#endregion
+export { escapeCsvCell, neutralizeCsvFormula };

package/dist/csv.mjs

@@ -0,0 +1,50 @@
+//#region src/serialization/csv.ts
+/**
+* `@classytic/primitives/csv` — make one value safe to put in a CSV cell.
+*
+* Two defences, deliberately separable because a consumer that already has a
+* real CSV writer must NOT get its quoting done twice:
+*
+*   - `neutralizeCsvFormula` — stops the cell being executed as a formula when
+*     the file is opened in Excel / Sheets / LibreOffice. Use this when a
+*     library (`csv-stringify`, `papaparse`, …) is doing the quoting.
+*   - `escapeCsvCell` — neutralize + RFC 4180 quoting. Use this in a
+*     hand-rolled `rows.map(...).join(',')` serializer.
+*
+* WHY quoting is not enough: a spreadsheet strips the quotes first and
+* evaluates what is left, so `"=cmd|'/c calc'!A1"` still executes. Only
+* changing the LEADING character stops it, which is why these are one module
+* and not a quoting helper someone can use alone.
+*
+* Well-formed numbers are exempt. Prefixing `-1500` would make every negative
+* amount text and break the reader's `SUM` — a fix that quietly corrupts every
+* finance export is worse than the hole. The exemption is the WHOLE cell
+* matching a number, so `-2+3+cmd|'/c calc'!A0` is still neutralized.
+*
+* NOT for a machine-to-machine upload contract with a fixed column spec (a
+* courier's bulk-import CSV, say) — there the receiver is a parser, not a
+* spreadsheet, and an added `'` corrupts the payload.
+*/
+/** Leading characters a spreadsheet may treat as the start of a formula or DDE call. */
+const FORMULA_LEAD = /^[=+\-@\t\r]/;
+/** The WHOLE cell is a plain number — no separators, no currency symbol. */
+const WHOLE_NUMBER = /^[-+]?(?:\d+\.?\d*|\.\d+)(?:[eE][-+]?\d+)?$/;
+/** Characters that force RFC 4180 quoting. */
+const NEEDS_QUOTING = /[",\r\n]/;
+/**
+* Prefix `'` when the cell would otherwise be evaluated as a formula.
+* `null`/`undefined` become `''`. Numbers are returned unchanged.
+*/
+function neutralizeCsvFormula(value) {
+	const text = value == null ? "" : String(value);
+	if (!FORMULA_LEAD.test(text)) return text;
+	if (WHOLE_NUMBER.test(text)) return text;
+	return `'${text}`;
+}
+/** `neutralizeCsvFormula` + RFC 4180 quoting. The one-call form. */
+function escapeCsvCell(value) {
+	const text = neutralizeCsvFormula(value);
+	return NEEDS_QUOTING.test(text) ? `"${text.replace(/"/g, "\"\"")}"` : text;
+}
+//#endregion
+export { escapeCsvCell, neutralizeCsvFormula };

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.3",
+  "version": "0.27.0",
   "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"
@@ -201,6 +205,10 @@
       "types": "./dist/canonical.d.mts",
       "default": "./dist/canonical.mjs"
     },
+    "./csv": {
+      "types": "./dist/csv.d.mts",
+      "default": "./dist/csv.mjs"
+    },
     "./package.json": "./package.json",
     "./state-diagram": {
       "types": "./dist/state-diagram.d.mts",