@classytic/primitives 0.33.0 → 0.34.0

package/CHANGELOG.md

@@ -3,6 +3,17 @@
 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

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/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.33.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",