@classytic/primitives 0.32.0 → 0.34.0

package/CHANGELOG.md

@@ -3,6 +3,26 @@
 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.34.0 — 2026-10-17
+
+### Added — geo distance helpers (`./identity/address`)
+
+- `distanceMeters(a, b)` — great-circle distance in metres (haversine, mean Earth radius 6,371,008.8 m; ~0.5% accurate: fine for geofences, not surveying). Throws `RangeError` on a non-finite or out-of-range WGS84 point.
+- `isWithinRadius(point, center, radiusMeters, { accuracyMeters, mode })` — is a point inside a circle, optionally counting the device's GPS uncertainty: `strict` (default, anti-cheat) needs the whole uncertainty circle inside, `lenient` accepts any overlap. Pinned by `tests/unit/geo-distance.test.ts`.
+
+### Fixed — a malformed signed token is `null`, not an exception (`./signed-token`)
+
+- Reading a token whose base64url body has an impossible length (`len % 4 === 1`) made `atob` throw out of the verifier. It now returns `null`, like every other malformed token.
+
+## 0.33.0 — 2026-10-14
+
+### Changed — `inventory/line-settlement` settles decimal quantities on the 6-dp grid
+- `planSettlement`, `clampSettlement`, `settledTotal`, `outstandingOf`, `settledEntirelyIn` and `shareOfSettled` add, subtract and compare
+  on the grid (`addQuantity` / `subtractQuantity`), so 0.1 + 0.2 settles exactly 0.3 and a weighed line can be received in parts.
+  Whole-unit inputs behave as before.
+- A non-positive or off-grid request is refused with code `not_positive_quantity` (was `not_positive_integer`; no in-repo consumer
+  branches on the old code).
+
 ## 0.32.0 — 2026-10-12
 
 ### Added — `./quantity`: the step and running-sum helpers every package was copying

package/dist/address.d.mts

@@ -39,6 +39,19 @@ interface GeoJsonPoint {
 }
 declare function toGeoJsonPoint(p: GeoPoint): GeoJsonPoint;
 declare function fromGeoJsonPoint(g: GeoJsonPoint): GeoPoint;
+/** Great-circle distance in metres (haversine). Accurate to ~0.5% — fine for geofences, not for surveying. */
+declare function distanceMeters(a: GeoPoint, b: GeoPoint): number;
+interface WithinRadiusOptions {
+  /** GPS accuracy (radius of uncertainty) in metres, as reported by the device. */
+  accuracyMeters?: number;
+  /**
+   * How accuracy counts. `strict`: the whole uncertainty circle must be inside (anti-cheat default).
+   * `lenient`: any overlap counts. Ignored when `accuracyMeters` is absent.
+   */
+  mode?: 'strict' | 'lenient';
+}
+/** Whether `point` lies within `radiusMeters` of `center`, optionally accounting for GPS accuracy. */
+declare function isWithinRadius(point: GeoPoint, center: GeoPoint, radiusMeters: number, options?: WithinRadiusOptions): boolean;
 /**
  * How a country's postal address is CAPTURED — labels, order, requiredness, and
  * which fields come from a subdivision taxonomy rather than free text.
@@ -304,4 +317,4 @@ declare function isAddressValid(address: Address | PartialAddress | null | undef
 /** A readable default message, in the country's own vocabulary. */
 declare function describeAddressError(error: AddressFieldError): string;
 //#endregion
-export { Address, AddressExtensionFieldSpec, AddressFieldError, AddressFieldInput, AddressFieldKey, AddressFieldSpec, AddressFormat, AddressFormatRegistry, AddressTaxonomyPort, AnyAddressFieldSpec, ContactAddress, GeoJsonPoint, GeoPoint, INTERNATIONAL_ADDRESS_FORMAT, PartialAddress, describeAddressError, fieldName, fieldSpec, fromGeoJsonPoint, isAddressValid, isExtensionField, requiredFieldNames, requiredKeys, resolveAddressFormat, supportedCountries, toGeoJsonPoint, validateAddress };
+export { Address, AddressExtensionFieldSpec, AddressFieldError, AddressFieldInput, AddressFieldKey, AddressFieldSpec, AddressFormat, AddressFormatRegistry, AddressTaxonomyPort, AnyAddressFieldSpec, ContactAddress, GeoJsonPoint, GeoPoint, INTERNATIONAL_ADDRESS_FORMAT, PartialAddress, WithinRadiusOptions, describeAddressError, distanceMeters, fieldName, fieldSpec, fromGeoJsonPoint, isAddressValid, isExtensionField, isWithinRadius, requiredFieldNames, requiredKeys, resolveAddressFormat, supportedCountries, toGeoJsonPoint, validateAddress };

package/dist/address.mjs

@@ -12,6 +12,30 @@ function fromGeoJsonPoint(g) {
 		latitude
 	};
 }
+/** Mean Earth radius (IUGG), metres. */
+const EARTH_RADIUS_M = 6371008.8;
+const toRad = (deg) => deg * Math.PI / 180;
+function assertValidPoint(p, label) {
+	if (!Number.isFinite(p.latitude) || !Number.isFinite(p.longitude) || Math.abs(p.latitude) > 90 || Math.abs(p.longitude) > 180) throw new RangeError(`${label} is not a valid WGS84 point`);
+}
+/** Great-circle distance in metres (haversine). Accurate to ~0.5% — fine for geofences, not for surveying. */
+function distanceMeters(a, b) {
+	assertValidPoint(a, "a");
+	assertValidPoint(b, "b");
+	const dLat = toRad(b.latitude - a.latitude);
+	const dLon = toRad(b.longitude - a.longitude);
+	const h = Math.sin(dLat / 2) ** 2 + Math.cos(toRad(a.latitude)) * Math.cos(toRad(b.latitude)) * Math.sin(dLon / 2) ** 2;
+	return 2 * EARTH_RADIUS_M * Math.asin(Math.min(1, Math.sqrt(h)));
+}
+/** Whether `point` lies within `radiusMeters` of `center`, optionally accounting for GPS accuracy. */
+function isWithinRadius(point, center, radiusMeters, options = {}) {
+	if (!Number.isFinite(radiusMeters) || radiusMeters < 0) throw new RangeError("radiusMeters must be >= 0");
+	const d = distanceMeters(point, center);
+	const acc = options.accuracyMeters;
+	if (acc === void 0) return d <= radiusMeters;
+	if (!Number.isFinite(acc) || acc < 0) throw new RangeError("accuracyMeters must be >= 0");
+	return (options.mode ?? "strict") === "strict" ? d + acc <= radiusMeters : d - acc <= radiusMeters;
+}
 /** The key a spec writes to, canonical or extension. */
 function fieldName(spec) {
 	return "extension" in spec ? spec.name : spec.key;
@@ -203,4 +227,4 @@ function describeAddressError(error) {
 	}
 }
 //#endregion
-export { INTERNATIONAL_ADDRESS_FORMAT, describeAddressError, fieldName, fieldSpec, fromGeoJsonPoint, isAddressValid, isExtensionField, requiredFieldNames, requiredKeys, resolveAddressFormat, supportedCountries, toGeoJsonPoint, validateAddress };
+export { INTERNATIONAL_ADDRESS_FORMAT, describeAddressError, distanceMeters, fieldName, fieldSpec, fromGeoJsonPoint, isAddressValid, isExtensionField, isWithinRadius, requiredFieldNames, requiredKeys, resolveAddressFormat, supportedCountries, toGeoJsonPoint, validateAddress };

package/dist/line-settlement.d.mts

@@ -10,7 +10,8 @@ import { Result } from "./result.mjs";
  * kernel's vocabulary; the arithmetic, the over-settlement guard and the state
  * derivation are this file's, so no two kernels can answer differently.
  *
- * Quantities are whole units. A bucket that is absent counts as zero.
+ * Quantities are decimals on the 6-dp grid (`./quantity`): whole units for a countable item, 2.35 for a weighed one.
+ * Every sum and comparison is exact on the grid. A bucket that is absent counts as zero.
  */
 interface SettlementLine<B extends string> {
   /** What the line promised to move. */
@@ -34,7 +35,7 @@ declare const documentSettlementState: <B extends string>(lines: ReadonlyArray<S
 /** `true` when every line is settled entirely through `bucket` (e.g. all received, nothing lost). */
 declare const settledEntirelyIn: <B extends string>(lines: ReadonlyArray<SettlementLine<B>>, bucket: B) => boolean;
 type SettlementRefusal = {
-  readonly code: "not_positive_integer";
+  readonly code: "not_positive_quantity";
   readonly requested: number;
 } | {
   readonly code: "exceeds_outstanding";
@@ -44,7 +45,7 @@ type SettlementRefusal = {
 /**
  * Settle `quantity` more units into `bucket`, or refuse.
  *
- * Refuses a non-positive or fractional quantity and anything above what is
+ * Refuses a non-positive quantity, one off the 6-dp grid, and anything above what is
  * outstanding — an over-settlement is an input error, never silently trimmed.
  * Use {@link clampSettlement} only where the surface's CONTRACT is "take what fits".
  */
@@ -61,7 +62,7 @@ declare const clampSettlement: <B extends string>(line: SettlementLine<B>, bucke
  * The share of a line-level amount (a value or a cost, integer MINOR units) owed by one
  * settlement batch, given how many units the whole line had settled before and after it.
  *
- * `floor(total·after/q) − floor(total·before/q)` TELESCOPES: however a line is split into
+ * `floor(total·after/q) − floor(total·before/q)` (units on the 6-dp grid) TELESCOPES: however a line is split into
  * batches, and across every outcome bucket, the shares sum to exactly `total` once the line
  * is fully settled — no remainder to chase, no batch-order dependence.
  */

package/dist/line-settlement.mjs

@@ -1,13 +1,14 @@
+import { QUANTITY_SCALE, addQuantity, compareQuantity, isOnQuantityGrid, quantityToGrid, snapQuantity, subtractQuantity } from "./quantity.mjs";
 import { err, ok } from "./result.mjs";
 //#region src/inventory/line-settlement.ts
 /** Sum of every bucket. */
-const settledTotal = (line) => Object.values(line.settled).reduce((sum, n) => sum + (n ?? 0), 0);
+const settledTotal = (line) => Object.values(line.settled).reduce((sum, n) => addQuantity(sum, n ?? 0), 0);
 /**
 * `quantity − Σ buckets`. NOT clamped at zero: a negative means the line was
 * over-settled by data written outside {@link planSettlement}, and hiding it
 * would erase the only signal that happened.
 */
-const outstandingOf = (line) => line.quantity - settledTotal(line);
+const outstandingOf = (line) => subtractQuantity(line.quantity, settledTotal(line));
 /** `open` — nothing settled; `settled` — nothing outstanding; otherwise `partial`. */
 const settlementState = (line) => {
 	if (outstandingOf(line) <= 0) return "settled";
@@ -21,21 +22,21 @@ const documentSettlementState = (lines) => {
 	return "partial";
 };
 /** `true` when every line is settled entirely through `bucket` (e.g. all received, nothing lost). */
-const settledEntirelyIn = (lines, bucket) => lines.every((l) => (l.settled[bucket] ?? 0) >= l.quantity);
+const settledEntirelyIn = (lines, bucket) => lines.every((l) => compareQuantity(l.settled[bucket] ?? 0, l.quantity) >= 0);
 /**
 * Settle `quantity` more units into `bucket`, or refuse.
 *
-* Refuses a non-positive or fractional quantity and anything above what is
+* Refuses a non-positive quantity, one off the 6-dp grid, and anything above what is
 * outstanding — an over-settlement is an input error, never silently trimmed.
 * Use {@link clampSettlement} only where the surface's CONTRACT is "take what fits".
 */
 const planSettlement = (line, bucket, quantity) => {
-	if (!Number.isInteger(quantity) || quantity <= 0) return err({
-		code: "not_positive_integer",
+	if (!(quantity > 0) || !isOnQuantityGrid(quantity)) return err({
+		code: "not_positive_quantity",
 		requested: quantity
 	});
 	const outstanding = outstandingOf(line);
-	if (quantity > outstanding) return err({
+	if (compareQuantity(quantity, outstanding) > 0) return err({
 		code: "exceeds_outstanding",
 		requested: quantity,
 		outstanding
@@ -47,7 +48,10 @@ const planSettlement = (line, bucket, quantity) => {
 * `applied` is what was actually settled; `0` leaves the line unchanged.
 */
 const clampSettlement = (line, bucket, requested) => {
-	const applied = Math.max(0, Math.min(Math.trunc(requested), outstandingOf(line)));
+	const wanted = requested > 0 ? isOnQuantityGrid(requested) ? requested : Math.floor(requested * QUANTITY_SCALE) / QUANTITY_SCALE : 0;
+	const fits = snapQuantity(wanted);
+	const outstanding = outstandingOf(line);
+	const applied = compareQuantity(fits, outstanding) <= 0 ? fits : Math.max(0, outstanding);
 	return {
 		line: applied > 0 ? withBucket(line, bucket, applied) : line,
 		applied
@@ -57,22 +61,23 @@ const clampSettlement = (line, bucket, requested) => {
 * The share of a line-level amount (a value or a cost, integer MINOR units) owed by one
 * settlement batch, given how many units the whole line had settled before and after it.
 *
-* `floor(total·after/q) − floor(total·before/q)` TELESCOPES: however a line is split into
+* `floor(total·after/q) − floor(total·before/q)` (units on the 6-dp grid) TELESCOPES: however a line is split into
 * batches, and across every outcome bucket, the shares sum to exactly `total` once the line
 * is fully settled — no remainder to chase, no batch-order dependence.
 */
 const shareOfSettled = (total, quantity, settledBefore, settledAfter) => {
 	if (!Number.isInteger(total) || total < 0) throw new RangeError(`total must be a non-negative integer, got ${total}`);
-	if (!Number.isInteger(quantity) || quantity <= 0) throw new RangeError(`quantity must be a positive integer, got ${quantity}`);
-	if (!(0 <= settledBefore && settledBefore <= settledAfter && settledAfter <= quantity)) throw new RangeError(`need 0 <= before (${settledBefore}) <= after (${settledAfter}) <= quantity (${quantity})`);
-	const at = (n) => Number(BigInt(total) * BigInt(n) / BigInt(quantity));
+	if (!(quantity > 0) || !isOnQuantityGrid(quantity)) throw new RangeError(`quantity must be positive with at most 6 decimals, got ${quantity}`);
+	if (!(0 <= settledBefore && compareQuantity(settledBefore, settledAfter) <= 0 && compareQuantity(settledAfter, quantity) <= 0)) throw new RangeError(`need 0 <= before (${settledBefore}) <= after (${settledAfter}) <= quantity (${quantity})`);
+	const q = quantityToGrid(quantity);
+	const at = (n) => Number(BigInt(total) * quantityToGrid(n) / q);
 	return at(settledAfter) - at(settledBefore);
 };
 const withBucket = (line, bucket, quantity) => ({
 	quantity: line.quantity,
 	settled: {
 		...line.settled,
-		[bucket]: (line.settled[bucket] ?? 0) + quantity
+		[bucket]: addQuantity(line.settled[bucket] ?? 0, quantity)
 	}
 });
 //#endregion

package/dist/signed-token.mjs

@@ -28,7 +28,12 @@ function toBase64Url(bytes) {
 }
 function fromBase64Url(text) {
 	if (!/^[A-Za-z0-9_-]*$/.test(text)) return null;
-	const binary = atob(text.replace(/-/g, "+").replace(/_/g, "/"));
+	let binary;
+	try {
+		binary = atob(text.replace(/-/g, "+").replace(/_/g, "/"));
+	} catch {
+		return null;
+	}
 	const bytes = new Uint8Array(new ArrayBuffer(binary.length));
 	for (let i = 0; i < binary.length; i += 1) bytes[i] = binary.charCodeAt(i);
 	return bytes;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/primitives",
-  "version": "0.32.0",
+  "version": "0.34.0",
   "description": "Framework-agnostic TypeScript primitives shared across Classytic packages — Money, events, pagination, tenant config, and other building blocks.",
   "author": "Classytic",
   "license": "MIT",