@chaosity/location-client 0.8.0 → 0.9.0

package/README.md

@@ -485,17 +485,30 @@ const connector = new LocationServiceConnector({
 })
 ```
 
-## Cache-Friendly Position Rounding
-
-`BiasPosition` coordinates are automatically rounded before each API request, to
-whatever precision your application is entitled to — a `biasDecimals` claim on
-the access token, defaulting to **3 decimal places** (~110 m) when the token
-carries none. This maximizes cache hits across nearby users without affecting
-result quality — bias is approximate by nature.
-
-`QueryPosition` (reverse geocode) retains full precision since it represents an exact point the user selected.
-
-This is handled transparently in both `GeoPlacesClient` and `LocationServiceConnector` — no action needed in application code.
+## Coordinates Are Sent As You Supply Them
+
+Both `GeoPlacesClient` and `LocationServiceConnector` put your command input on
+the wire unchanged. `BiasPosition` and `QueryPosition` arrive at the service at
+the precision you passed.
+
+Earlier versions rounded `BiasPosition` to a grid — 3 decimal places by
+default — so that nearby callers could share a cached upstream answer. Requests
+are no longer cached, so the rounding had nothing left to share and only
+lowered the precision the geocoder worked from.
+
+That is not a coarser result, it is a different one. A 3 dp grid moves a
+coordinate by up to ~70 m, depending where in its cell the coordinate falls,
+and the places a search returns change well inside that distance: measured
+against this service, a bias moved ~70 m returned a different set of nearby
+places, not the same set in a different order. If you were relying on the
+rounding to group nearby requests, round before you call.
+
+One coordinate is normalised: a static map's `center`, `bounding-box` and
+`bounded-positions` are rounded to six decimals — ~10 cm, below one pixel of a
+raster render. That is this library's choice, well inside what the service
+accepts: at most fourteen decimals per number, and at most 36 characters for
+the pair. A value straight from `map.getCenter()` carries fifteen or sixteen
+decimals and fails the first of those. A format rule, not a precision policy.
 
 ## Logging
 

package/dist/cjs/client/GeoPlacesClient.d.ts

@@ -18,7 +18,7 @@ export declare class GeoPlacesClient {
     constructor(config: ClientConfig);
     /**
      * This application's own configuration, as carried on the access token
-     * (api#65) — bias precision, and the countries it is scoped to.
+     * (api#65) — today, the countries it is scoped to.
      *
      * Provided so an application can SHOW its own settings: populate a country
      * selector with the markets it actually serves, label a settings screen,

package/dist/cjs/client/GeoPlacesClient.js

@@ -8,7 +8,6 @@ const debug_1 = __importDefault(require("debug"));
 const endpoints_js_1 = require("../transport/endpoints.js");
 const errors_js_1 = require("../transport/errors.js");
 const http_js_1 = require("../transport/http.js");
-const roundPosition_js_1 = require("../utils/roundPosition.js");
 const tokenClaims_js_1 = require("../utils/tokenClaims.js");
 const log = (0, debug_1.default)('location-client:api');
 /**
@@ -26,7 +25,7 @@ class GeoPlacesClient {
     }
     /**
      * This application's own configuration, as carried on the access token
-     * (api#65) — bias precision, and the countries it is scoped to.
+     * (api#65) — today, the countries it is scoped to.
      *
      * Provided so an application can SHOW its own settings: populate a country
      * selector with the markets it actually serves, label a settings screen,
@@ -100,10 +99,11 @@ class GeoPlacesClient {
         }
     }
     dispatch(url, token, cmd, options) {
-        // Resolve the token BEFORE rounding: the precision this application is
-        // entitled to is a claim on it (api#65). Absent claim -> the 3 dp floor.
-        const { biasDecimals } = (0, tokenClaims_js_1.readAppConfigClaims)(token);
-        const input = (0, roundPosition_js_1.roundPositionFields)(cmd.input, biasDecimals);
+        // The caller's input goes out as the caller wrote it. `BiasPosition` used
+        // to be rounded here to a grid sized by a token claim, so nearby callers
+        // shared a server cache entry; with no cache the rounding only lowered the
+        // precision the upstream geocoder had to work with, which moves the
+        // results rather than coarsening them (#51).
         log('Sending %s to %s', cmd.constructor?.name, url);
         return (0, http_js_1.requestJson)(url, {
             method: 'POST',
@@ -111,7 +111,7 @@ class GeoPlacesClient {
                 'Content-Type': 'application/json',
                 Authorization: `Bearer ${token}`,
             },
-            body: JSON.stringify(input),
+            body: JSON.stringify(cmd.input),
         }, options);
     }
 }

package/dist/cjs/server/LocationServiceConnector.d.ts

@@ -77,7 +77,7 @@ export declare class LocationServiceConnector {
     private buildSource;
     /**
      * This application's own configuration, as carried on the access token
-     * (api#65) — bias precision, and the countries it is scoped to.
+     * (api#65) — today, the countries it is scoped to.
      *
      * Provided so an application can SHOW its own settings: populate a country
      * selector with the markets it actually serves, label a settings screen, and

package/dist/cjs/server/LocationServiceConnector.js

@@ -9,7 +9,6 @@ const LocationServiceException_js_1 = require("../errors/LocationServiceExceptio
 const endpoints_js_1 = require("../transport/endpoints.js");
 const errors_js_1 = require("../transport/errors.js");
 const http_js_1 = require("../transport/http.js");
-const roundPosition_js_1 = require("../utils/roundPosition.js");
 const tokenClaims_js_1 = require("../utils/tokenClaims.js");
 const getClientConfig_js_1 = require("./getClientConfig.js");
 const log = (0, debug_1.default)('location-client:connector');
@@ -158,7 +157,7 @@ class LocationServiceConnector {
     }
     /**
      * This application's own configuration, as carried on the access token
-     * (api#65) — bias precision, and the countries it is scoped to.
+     * (api#65) — today, the countries it is scoped to.
      *
      * Provided so an application can SHOW its own settings: populate a country
      * selector with the markets it actually serves, label a settings screen, and
@@ -220,13 +219,12 @@ class LocationServiceConnector {
         }
     }
     dispatch(url, token, cmd, options) {
-        // The token is resolved before the request is shaped, so the precision this
-        // application is entitled to is available (api#65). Absent claim -> the
-        // 3 dp floor, which is what every application gets until one is configured
-        // otherwise. Recomputed per attempt because a refreshed token may carry
-        // different claims.
-        const { biasDecimals } = (0, tokenClaims_js_1.readAppConfigClaims)(token);
-        const input = (0, roundPosition_js_1.roundPositionFields)(cmd.input, biasDecimals);
+        // The caller's input goes out as the caller wrote it — nothing in the body
+        // is derived from the token any more. `BiasPosition` used to be rounded
+        // here to a grid sized by a token claim, so nearby callers shared a server
+        // cache entry; with no cache the rounding only lowered the precision the
+        // upstream geocoder had to work with, which moves the results rather than
+        // coarsening them (#51).
         // Every system header is set exactly ONCE, and the caller's own spelling of
         // each is dropped first.
         //
@@ -251,7 +249,7 @@ class LocationServiceConnector {
             Authorization: `Bearer ${token}`,
         };
         log('Sending %s request to %s', cmd.constructor?.name, url);
-        return (0, http_js_1.requestJson)(url, { method: 'POST', headers, body: JSON.stringify(input) }, options);
+        return (0, http_js_1.requestJson)(url, { method: 'POST', headers, body: JSON.stringify(cmd.input) }, options);
     }
 }
 exports.LocationServiceConnector = LocationServiceConnector;

package/dist/cjs/utils/tokenClaims.d.ts

@@ -1,29 +1,27 @@
 /**
  * Read advisory application config out of the access token (api#65).
  *
- * The API puts an application's own settings — `biasDecimals`, `countries` —
- * into the JWT alongside `allowedDomain` and `allowedResources`, so this
- * library can stop hard-coding values it has no other way of knowing.
+ * The API puts an application's own settings — today just `countries` — into
+ * the JWT alongside `allowedDomain` and `allowedResources`, so this library can
+ * stop hard-coding values it has no other way of knowing.
+ *
+ * `biasDecimals` used to be here too. It sized the grid this library rounded
+ * `BiasPosition` onto, so that nearby callers shared a server cache entry; the
+ * cache is gone, the API issues no such claim, and rounding a coordinate with
+ * nothing to share it with only lowered the precision the upstream geocoder
+ * received (#51).
  *
  * DELIBERATELY UNVERIFIED, and that is safe. This library has no signing key
  * and does not need one: every claim here is re-read from the application row
  * by the API on each request, and the API's answer is the one that counts. A
  * forged token would fail at the authorizer long before any of this mattered.
- * What is read here only decides how the request is SHAPED — a hint, never a
- * permission.
+ * Nothing read here reaches a request at all now — it is displayed, never
+ * acted on, so a forged value misinforms only the caller who forged it.
  *
  * A JWT is signed, not encrypted, so the payload is plain base64url. Nothing
  * secret is in it; these are the caller's own settings.
  */
 export interface AppConfigClaims {
-    /**
-     * Bias precision this application is entitled to.
-     *
-     * Safe to act on: it only changes how a coordinate is rounded before
-     * sending, and the server re-rounds to its own configured value anyway. A
-     * stale value here costs precision, never correctness.
-     */
-    biasDecimals?: number;
     /**
      * Countries this application may search, ISO 3166-1 alpha-2.
      *

package/dist/cjs/utils/tokenClaims.js

@@ -2,16 +2,22 @@
 /**
  * Read advisory application config out of the access token (api#65).
  *
- * The API puts an application's own settings — `biasDecimals`, `countries` —
- * into the JWT alongside `allowedDomain` and `allowedResources`, so this
- * library can stop hard-coding values it has no other way of knowing.
+ * The API puts an application's own settings — today just `countries` — into
+ * the JWT alongside `allowedDomain` and `allowedResources`, so this library can
+ * stop hard-coding values it has no other way of knowing.
+ *
+ * `biasDecimals` used to be here too. It sized the grid this library rounded
+ * `BiasPosition` onto, so that nearby callers shared a server cache entry; the
+ * cache is gone, the API issues no such claim, and rounding a coordinate with
+ * nothing to share it with only lowered the precision the upstream geocoder
+ * received (#51).
  *
  * DELIBERATELY UNVERIFIED, and that is safe. This library has no signing key
  * and does not need one: every claim here is re-read from the application row
  * by the API on each request, and the API's answer is the one that counts. A
  * forged token would fail at the authorizer long before any of this mattered.
- * What is read here only decides how the request is SHAPED — a hint, never a
- * permission.
+ * Nothing read here reaches a request at all now — it is displayed, never
+ * acted on, so a forged value misinforms only the caller who forged it.
  *
  * A JWT is signed, not encrypted, so the payload is plain base64url. Nothing
  * secret is in it; these are the caller's own settings.
@@ -39,15 +45,6 @@ function readAppConfigClaims(token) {
         const json = decodeURIComponent(Array.from(atob(padded), (c) => `%${c.charCodeAt(0).toString(16).padStart(2, '0')}`).join(''));
         const payload = JSON.parse(json);
         const claims = {};
-        if (typeof payload.biasDecimals === 'number') {
-            claims.biasDecimals = payload.biasDecimals;
-        }
-        else if (typeof payload.biasDecimals === 'string' &&
-            payload.biasDecimals.trim() !== '') {
-            const n = Number(payload.biasDecimals);
-            if (Number.isFinite(n))
-                claims.biasDecimals = n;
-        }
         if (Array.isArray(payload.countries)) {
             const list = payload.countries.filter((c) => typeof c === 'string');
             if (list.length)

package/dist/client/GeoPlacesClient.d.ts

@@ -18,7 +18,7 @@ export declare class GeoPlacesClient {
     constructor(config: ClientConfig);
     /**
      * This application's own configuration, as carried on the access token
-     * (api#65) — bias precision, and the countries it is scoped to.
+     * (api#65) — today, the countries it is scoped to.
      *
      * Provided so an application can SHOW its own settings: populate a country
      * selector with the markets it actually serves, label a settings screen,

package/dist/client/GeoPlacesClient.js

@@ -2,7 +2,6 @@ import debug from 'debug';
 import { resolveEndpoint } from '../transport/endpoints.js';
 import { isTokenRejected, noTokenAvailable } from '../transport/errors.js';
 import { requestJson } from '../transport/http.js';
-import { roundPositionFields } from '../utils/roundPosition.js';
 import { readAppConfigClaims } from '../utils/tokenClaims.js';
 const log = debug('location-client:api');
 /**
@@ -20,7 +19,7 @@ export class GeoPlacesClient {
     }
     /**
      * This application's own configuration, as carried on the access token
-     * (api#65) — bias precision, and the countries it is scoped to.
+     * (api#65) — today, the countries it is scoped to.
      *
      * Provided so an application can SHOW its own settings: populate a country
      * selector with the markets it actually serves, label a settings screen,
@@ -94,10 +93,11 @@ export class GeoPlacesClient {
         }
     }
     dispatch(url, token, cmd, options) {
-        // Resolve the token BEFORE rounding: the precision this application is
-        // entitled to is a claim on it (api#65). Absent claim -> the 3 dp floor.
-        const { biasDecimals } = readAppConfigClaims(token);
-        const input = roundPositionFields(cmd.input, biasDecimals);
+        // The caller's input goes out as the caller wrote it. `BiasPosition` used
+        // to be rounded here to a grid sized by a token claim, so nearby callers
+        // shared a server cache entry; with no cache the rounding only lowered the
+        // precision the upstream geocoder had to work with, which moves the
+        // results rather than coarsening them (#51).
         log('Sending %s to %s', cmd.constructor?.name, url);
         return requestJson(url, {
             method: 'POST',
@@ -105,7 +105,7 @@ export class GeoPlacesClient {
                 'Content-Type': 'application/json',
                 Authorization: `Bearer ${token}`,
             },
-            body: JSON.stringify(input),
+            body: JSON.stringify(cmd.input),
         }, options);
     }
 }

package/dist/server/LocationServiceConnector.d.ts

@@ -77,7 +77,7 @@ export declare class LocationServiceConnector {
     private buildSource;
     /**
      * This application's own configuration, as carried on the access token
-     * (api#65) — bias precision, and the countries it is scoped to.
+     * (api#65) — today, the countries it is scoped to.
      *
      * Provided so an application can SHOW its own settings: populate a country
      * selector with the markets it actually serves, label a settings screen, and

package/dist/server/LocationServiceConnector.js

@@ -3,7 +3,6 @@ import { LocationServiceException } from '../errors/LocationServiceException.js'
 import { resolveEndpoint } from '../transport/endpoints.js';
 import { isTokenRejected, noTokenAvailable } from '../transport/errors.js';
 import { requestJson } from '../transport/http.js';
-import { roundPositionFields } from '../utils/roundPosition.js';
 import { readAppConfigClaims } from '../utils/tokenClaims.js';
 import { resolveApiUrl, serverTokenSource } from './getClientConfig.js';
 const log = debug('location-client:connector');
@@ -152,7 +151,7 @@ export class LocationServiceConnector {
     }
     /**
      * This application's own configuration, as carried on the access token
-     * (api#65) — bias precision, and the countries it is scoped to.
+     * (api#65) — today, the countries it is scoped to.
      *
      * Provided so an application can SHOW its own settings: populate a country
      * selector with the markets it actually serves, label a settings screen, and
@@ -214,13 +213,12 @@ export class LocationServiceConnector {
         }
     }
     dispatch(url, token, cmd, options) {
-        // The token is resolved before the request is shaped, so the precision this
-        // application is entitled to is available (api#65). Absent claim -> the
-        // 3 dp floor, which is what every application gets until one is configured
-        // otherwise. Recomputed per attempt because a refreshed token may carry
-        // different claims.
-        const { biasDecimals } = readAppConfigClaims(token);
-        const input = roundPositionFields(cmd.input, biasDecimals);
+        // The caller's input goes out as the caller wrote it — nothing in the body
+        // is derived from the token any more. `BiasPosition` used to be rounded
+        // here to a grid sized by a token claim, so nearby callers shared a server
+        // cache entry; with no cache the rounding only lowered the precision the
+        // upstream geocoder had to work with, which moves the results rather than
+        // coarsening them (#51).
         // Every system header is set exactly ONCE, and the caller's own spelling of
         // each is dropped first.
         //
@@ -245,7 +243,7 @@ export class LocationServiceConnector {
             Authorization: `Bearer ${token}`,
         };
         log('Sending %s request to %s', cmd.constructor?.name, url);
-        return requestJson(url, { method: 'POST', headers, body: JSON.stringify(input) }, options);
+        return requestJson(url, { method: 'POST', headers, body: JSON.stringify(cmd.input) }, options);
     }
 }
 function requireApiUrl(explicit) {

package/dist/utils/tokenClaims.d.ts

@@ -1,29 +1,27 @@
 /**
  * Read advisory application config out of the access token (api#65).
  *
- * The API puts an application's own settings — `biasDecimals`, `countries` —
- * into the JWT alongside `allowedDomain` and `allowedResources`, so this
- * library can stop hard-coding values it has no other way of knowing.
+ * The API puts an application's own settings — today just `countries` — into
+ * the JWT alongside `allowedDomain` and `allowedResources`, so this library can
+ * stop hard-coding values it has no other way of knowing.
+ *
+ * `biasDecimals` used to be here too. It sized the grid this library rounded
+ * `BiasPosition` onto, so that nearby callers shared a server cache entry; the
+ * cache is gone, the API issues no such claim, and rounding a coordinate with
+ * nothing to share it with only lowered the precision the upstream geocoder
+ * received (#51).
  *
  * DELIBERATELY UNVERIFIED, and that is safe. This library has no signing key
  * and does not need one: every claim here is re-read from the application row
  * by the API on each request, and the API's answer is the one that counts. A
  * forged token would fail at the authorizer long before any of this mattered.
- * What is read here only decides how the request is SHAPED — a hint, never a
- * permission.
+ * Nothing read here reaches a request at all now — it is displayed, never
+ * acted on, so a forged value misinforms only the caller who forged it.
  *
  * A JWT is signed, not encrypted, so the payload is plain base64url. Nothing
  * secret is in it; these are the caller's own settings.
  */
 export interface AppConfigClaims {
-    /**
-     * Bias precision this application is entitled to.
-     *
-     * Safe to act on: it only changes how a coordinate is rounded before
-     * sending, and the server re-rounds to its own configured value anyway. A
-     * stale value here costs precision, never correctness.
-     */
-    biasDecimals?: number;
     /**
      * Countries this application may search, ISO 3166-1 alpha-2.
      *

package/dist/utils/tokenClaims.js

@@ -1,16 +1,22 @@
 /**
  * Read advisory application config out of the access token (api#65).
  *
- * The API puts an application's own settings — `biasDecimals`, `countries` —
- * into the JWT alongside `allowedDomain` and `allowedResources`, so this
- * library can stop hard-coding values it has no other way of knowing.
+ * The API puts an application's own settings — today just `countries` — into
+ * the JWT alongside `allowedDomain` and `allowedResources`, so this library can
+ * stop hard-coding values it has no other way of knowing.
+ *
+ * `biasDecimals` used to be here too. It sized the grid this library rounded
+ * `BiasPosition` onto, so that nearby callers shared a server cache entry; the
+ * cache is gone, the API issues no such claim, and rounding a coordinate with
+ * nothing to share it with only lowered the precision the upstream geocoder
+ * received (#51).
  *
  * DELIBERATELY UNVERIFIED, and that is safe. This library has no signing key
  * and does not need one: every claim here is re-read from the application row
  * by the API on each request, and the API's answer is the one that counts. A
  * forged token would fail at the authorizer long before any of this mattered.
- * What is read here only decides how the request is SHAPED — a hint, never a
- * permission.
+ * Nothing read here reaches a request at all now — it is displayed, never
+ * acted on, so a forged value misinforms only the caller who forged it.
  *
  * A JWT is signed, not encrypted, so the payload is plain base64url. Nothing
  * secret is in it; these are the caller's own settings.
@@ -36,15 +42,6 @@ export function readAppConfigClaims(token) {
         const json = decodeURIComponent(Array.from(atob(padded), (c) => `%${c.charCodeAt(0).toString(16).padStart(2, '0')}`).join(''));
         const payload = JSON.parse(json);
         const claims = {};
-        if (typeof payload.biasDecimals === 'number') {
-            claims.biasDecimals = payload.biasDecimals;
-        }
-        else if (typeof payload.biasDecimals === 'string' &&
-            payload.biasDecimals.trim() !== '') {
-            const n = Number(payload.biasDecimals);
-            if (Number.isFinite(n))
-                claims.biasDecimals = n;
-        }
         if (Array.isArray(payload.countries)) {
             const list = payload.countries.filter((c) => typeof c === 'string');
             if (list.length)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chaosity/location-client",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Client library for Chaosity Location Service with AWS Location Service compatibility",
   "type": "module",
   "main": "dist/cjs/index.js",

package/dist/cjs/utils/roundPosition.d.ts

@@ -1,66 +0,0 @@
-/**
- * Round coordinate arrays in command inputs so nearby callers share a server
- * cache entry.
- *
- * `BiasPosition` is a hint about where to look, so collapsing it onto a grid
- * lets two users in the same area reuse one upstream answer. `QueryPosition`
- * is not a hint — reverse-geocode resolves an exact point a user clicked or a
- * device reported, and rounding it returns a neighbour's address. It is left
- * alone (RFC-0001 §2).
- *
- * WHY THE DEFAULT MOVED FROM 2 dp TO 3 dp
- *
- * 2 dp is a ~1.1 km grid, and that is not a coarser answer — it is a wrong
- * one. Measured against Amazon Location directly, `QueryText: "cafe"` from
- * Sydney CBD returns a completely different set of places when the bias moves
- * 111 m:
- *
- *   base      -> Crepe de Paris | Deli Ziosa | CBD Patisserie
- *   +111 m    -> Cafe Chocolat  | Paradiso Cafe | Incanto Coffee
- *
- * So two users a kilometre apart both received whichever places were nearest
- * the FIRST of them, with nothing in the response saying so. The server moved
- * to 3 dp in api#21 — but this library rounds BEFORE sending, on both the
- * browser and server paths, so the precision was already gone by the time the
- * request arrived and that fix never reached anyone using the SDK. This is
- * what makes it reach them.
- *
- * The cost is hit rate: cells shrink 100x in area. RFC-0001 §5 expected only
- * "single-digit to low-double-digit percent" in mixed traffic, so there was
- * little to protect, and a miss costs one upstream call while a wrong answer
- * costs trust.
- */
-/** The server's floor (api#65). A request for less is clamped up to it. */
-export declare const DEFAULT_BIAS_DECIMALS = 3;
-/**
- * The band the server enforces (api#65). Mirrored here so the value this
- * library rounds to is the value the server will actually key its cache by —
- * rounding to something outside the band just means being wrong about what
- * was sent.
- *
- * The floor is correctness: below 3 dp the nearest places are not the ones
- * returned. The ceiling is cost: cells shrink 100x in area per decimal, so
- * finer precision collapses the cache hit rate and every miss is a billable
- * upstream call.
- */
-export declare const MIN_BIAS_DECIMALS = 3;
-export declare const MAX_BIAS_DECIMALS = 5;
-/**
- * Clamp a requested precision into the allowed band.
- *
- * Anything absent or malformed becomes the default rather than throwing: this
- * runs on every request, and a surprising token claim must not break geocoding
- * for an application that is otherwise working.
- */
-export declare function clampBiasDecimals(requested?: unknown): number;
-/**
- * Shallow-clone the input and round position arrays that benefit from caching.
- * Returns the original object if no position fields are present.
- *
- * @param input      the command input
- * @param decimals   precision for this application; defaults to the floor.
- *                   Comes from the `biasDecimals` JWT claim where the token
- *                   carries one (api#65) — an application entitled to finer
- *                   bias gets it without the caller configuring anything.
- */
-export declare function roundPositionFields<T extends object>(input: T, decimals?: number): T;

package/dist/cjs/utils/roundPosition.js

@@ -1,109 +0,0 @@
-"use strict";
-/**
- * Round coordinate arrays in command inputs so nearby callers share a server
- * cache entry.
- *
- * `BiasPosition` is a hint about where to look, so collapsing it onto a grid
- * lets two users in the same area reuse one upstream answer. `QueryPosition`
- * is not a hint — reverse-geocode resolves an exact point a user clicked or a
- * device reported, and rounding it returns a neighbour's address. It is left
- * alone (RFC-0001 §2).
- *
- * WHY THE DEFAULT MOVED FROM 2 dp TO 3 dp
- *
- * 2 dp is a ~1.1 km grid, and that is not a coarser answer — it is a wrong
- * one. Measured against Amazon Location directly, `QueryText: "cafe"` from
- * Sydney CBD returns a completely different set of places when the bias moves
- * 111 m:
- *
- *   base      -> Crepe de Paris | Deli Ziosa | CBD Patisserie
- *   +111 m    -> Cafe Chocolat  | Paradiso Cafe | Incanto Coffee
- *
- * So two users a kilometre apart both received whichever places were nearest
- * the FIRST of them, with nothing in the response saying so. The server moved
- * to 3 dp in api#21 — but this library rounds BEFORE sending, on both the
- * browser and server paths, so the precision was already gone by the time the
- * request arrived and that fix never reached anyone using the SDK. This is
- * what makes it reach them.
- *
- * The cost is hit rate: cells shrink 100x in area. RFC-0001 §5 expected only
- * "single-digit to low-double-digit percent" in mixed traffic, so there was
- * little to protect, and a miss costs one upstream call while a wrong answer
- * costs trust.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.MAX_BIAS_DECIMALS = exports.MIN_BIAS_DECIMALS = exports.DEFAULT_BIAS_DECIMALS = void 0;
-exports.clampBiasDecimals = clampBiasDecimals;
-exports.roundPositionFields = roundPositionFields;
-/** The server's floor (api#65). A request for less is clamped up to it. */
-exports.DEFAULT_BIAS_DECIMALS = 3;
-/**
- * The band the server enforces (api#65). Mirrored here so the value this
- * library rounds to is the value the server will actually key its cache by —
- * rounding to something outside the band just means being wrong about what
- * was sent.
- *
- * The floor is correctness: below 3 dp the nearest places are not the ones
- * returned. The ceiling is cost: cells shrink 100x in area per decimal, so
- * finer precision collapses the cache hit rate and every miss is a billable
- * upstream call.
- */
-exports.MIN_BIAS_DECIMALS = 3;
-exports.MAX_BIAS_DECIMALS = 5;
-/**
- * Clamp a requested precision into the allowed band.
- *
- * Anything absent or malformed becomes the default rather than throwing: this
- * runs on every request, and a surprising token claim must not break geocoding
- * for an application that is otherwise working.
- */
-function clampBiasDecimals(requested) {
-    const n = Number(requested);
-    if ((typeof requested !== 'number' &&
-        !(typeof requested === 'string' && requested.trim() !== '')) ||
-        !Number.isFinite(n)) {
-        return exports.DEFAULT_BIAS_DECIMALS;
-    }
-    const floored = Math.floor(n);
-    if (floored < exports.MIN_BIAS_DECIMALS)
-        return exports.MIN_BIAS_DECIMALS;
-    if (floored > exports.MAX_BIAS_DECIMALS)
-        return exports.MAX_BIAS_DECIMALS;
-    return floored;
-}
-/** Known position field names and whether they should be rounded */
-const POSITION_FIELDS = {
-    BiasPosition: true, // geocode, autocomplete, search — round for cache
-    QueryPosition: false, // reverse geocode — keep full precision
-};
-function roundCoord(value, decimals) {
-    const factor = 10 ** decimals;
-    return Math.round(value * factor) / factor;
-}
-/**
- * Shallow-clone the input and round position arrays that benefit from caching.
- * Returns the original object if no position fields are present.
- *
- * @param input      the command input
- * @param decimals   precision for this application; defaults to the floor.
- *                   Comes from the `biasDecimals` JWT claim where the token
- *                   carries one (api#65) — an application entitled to finer
- *                   bias gets it without the caller configuring anything.
- */
-function roundPositionFields(input, decimals = exports.DEFAULT_BIAS_DECIMALS) {
-    if (!input || typeof input !== 'object')
-        return input;
-    const dp = clampBiasDecimals(decimals);
-    let cloned = null;
-    for (const [field, shouldRound] of Object.entries(POSITION_FIELDS)) {
-        if (!shouldRound)
-            continue;
-        const value = input[field];
-        if (!Array.isArray(value))
-            continue;
-        if (!cloned)
-            cloned = { ...input };
-        cloned[field] = value.map((v) => typeof v === 'number' && Number.isFinite(v) ? roundCoord(v, dp) : v);
-    }
-    return cloned ?? input;
-}

package/dist/utils/roundPosition.d.ts

@@ -1,66 +0,0 @@
-/**
- * Round coordinate arrays in command inputs so nearby callers share a server
- * cache entry.
- *
- * `BiasPosition` is a hint about where to look, so collapsing it onto a grid
- * lets two users in the same area reuse one upstream answer. `QueryPosition`
- * is not a hint — reverse-geocode resolves an exact point a user clicked or a
- * device reported, and rounding it returns a neighbour's address. It is left
- * alone (RFC-0001 §2).
- *
- * WHY THE DEFAULT MOVED FROM 2 dp TO 3 dp
- *
- * 2 dp is a ~1.1 km grid, and that is not a coarser answer — it is a wrong
- * one. Measured against Amazon Location directly, `QueryText: "cafe"` from
- * Sydney CBD returns a completely different set of places when the bias moves
- * 111 m:
- *
- *   base      -> Crepe de Paris | Deli Ziosa | CBD Patisserie
- *   +111 m    -> Cafe Chocolat  | Paradiso Cafe | Incanto Coffee
- *
- * So two users a kilometre apart both received whichever places were nearest
- * the FIRST of them, with nothing in the response saying so. The server moved
- * to 3 dp in api#21 — but this library rounds BEFORE sending, on both the
- * browser and server paths, so the precision was already gone by the time the
- * request arrived and that fix never reached anyone using the SDK. This is
- * what makes it reach them.
- *
- * The cost is hit rate: cells shrink 100x in area. RFC-0001 §5 expected only
- * "single-digit to low-double-digit percent" in mixed traffic, so there was
- * little to protect, and a miss costs one upstream call while a wrong answer
- * costs trust.
- */
-/** The server's floor (api#65). A request for less is clamped up to it. */
-export declare const DEFAULT_BIAS_DECIMALS = 3;
-/**
- * The band the server enforces (api#65). Mirrored here so the value this
- * library rounds to is the value the server will actually key its cache by —
- * rounding to something outside the band just means being wrong about what
- * was sent.
- *
- * The floor is correctness: below 3 dp the nearest places are not the ones
- * returned. The ceiling is cost: cells shrink 100x in area per decimal, so
- * finer precision collapses the cache hit rate and every miss is a billable
- * upstream call.
- */
-export declare const MIN_BIAS_DECIMALS = 3;
-export declare const MAX_BIAS_DECIMALS = 5;
-/**
- * Clamp a requested precision into the allowed band.
- *
- * Anything absent or malformed becomes the default rather than throwing: this
- * runs on every request, and a surprising token claim must not break geocoding
- * for an application that is otherwise working.
- */
-export declare function clampBiasDecimals(requested?: unknown): number;
-/**
- * Shallow-clone the input and round position arrays that benefit from caching.
- * Returns the original object if no position fields are present.
- *
- * @param input      the command input
- * @param decimals   precision for this application; defaults to the floor.
- *                   Comes from the `biasDecimals` JWT claim where the token
- *                   carries one (api#65) — an application entitled to finer
- *                   bias gets it without the caller configuring anything.
- */
-export declare function roundPositionFields<T extends object>(input: T, decimals?: number): T;

package/dist/utils/roundPosition.js

@@ -1,104 +0,0 @@
-/**
- * Round coordinate arrays in command inputs so nearby callers share a server
- * cache entry.
- *
- * `BiasPosition` is a hint about where to look, so collapsing it onto a grid
- * lets two users in the same area reuse one upstream answer. `QueryPosition`
- * is not a hint — reverse-geocode resolves an exact point a user clicked or a
- * device reported, and rounding it returns a neighbour's address. It is left
- * alone (RFC-0001 §2).
- *
- * WHY THE DEFAULT MOVED FROM 2 dp TO 3 dp
- *
- * 2 dp is a ~1.1 km grid, and that is not a coarser answer — it is a wrong
- * one. Measured against Amazon Location directly, `QueryText: "cafe"` from
- * Sydney CBD returns a completely different set of places when the bias moves
- * 111 m:
- *
- *   base      -> Crepe de Paris | Deli Ziosa | CBD Patisserie
- *   +111 m    -> Cafe Chocolat  | Paradiso Cafe | Incanto Coffee
- *
- * So two users a kilometre apart both received whichever places were nearest
- * the FIRST of them, with nothing in the response saying so. The server moved
- * to 3 dp in api#21 — but this library rounds BEFORE sending, on both the
- * browser and server paths, so the precision was already gone by the time the
- * request arrived and that fix never reached anyone using the SDK. This is
- * what makes it reach them.
- *
- * The cost is hit rate: cells shrink 100x in area. RFC-0001 §5 expected only
- * "single-digit to low-double-digit percent" in mixed traffic, so there was
- * little to protect, and a miss costs one upstream call while a wrong answer
- * costs trust.
- */
-/** The server's floor (api#65). A request for less is clamped up to it. */
-export const DEFAULT_BIAS_DECIMALS = 3;
-/**
- * The band the server enforces (api#65). Mirrored here so the value this
- * library rounds to is the value the server will actually key its cache by —
- * rounding to something outside the band just means being wrong about what
- * was sent.
- *
- * The floor is correctness: below 3 dp the nearest places are not the ones
- * returned. The ceiling is cost: cells shrink 100x in area per decimal, so
- * finer precision collapses the cache hit rate and every miss is a billable
- * upstream call.
- */
-export const MIN_BIAS_DECIMALS = 3;
-export const MAX_BIAS_DECIMALS = 5;
-/**
- * Clamp a requested precision into the allowed band.
- *
- * Anything absent or malformed becomes the default rather than throwing: this
- * runs on every request, and a surprising token claim must not break geocoding
- * for an application that is otherwise working.
- */
-export function clampBiasDecimals(requested) {
-    const n = Number(requested);
-    if ((typeof requested !== 'number' &&
-        !(typeof requested === 'string' && requested.trim() !== '')) ||
-        !Number.isFinite(n)) {
-        return DEFAULT_BIAS_DECIMALS;
-    }
-    const floored = Math.floor(n);
-    if (floored < MIN_BIAS_DECIMALS)
-        return MIN_BIAS_DECIMALS;
-    if (floored > MAX_BIAS_DECIMALS)
-        return MAX_BIAS_DECIMALS;
-    return floored;
-}
-/** Known position field names and whether they should be rounded */
-const POSITION_FIELDS = {
-    BiasPosition: true, // geocode, autocomplete, search — round for cache
-    QueryPosition: false, // reverse geocode — keep full precision
-};
-function roundCoord(value, decimals) {
-    const factor = 10 ** decimals;
-    return Math.round(value * factor) / factor;
-}
-/**
- * Shallow-clone the input and round position arrays that benefit from caching.
- * Returns the original object if no position fields are present.
- *
- * @param input      the command input
- * @param decimals   precision for this application; defaults to the floor.
- *                   Comes from the `biasDecimals` JWT claim where the token
- *                   carries one (api#65) — an application entitled to finer
- *                   bias gets it without the caller configuring anything.
- */
-export function roundPositionFields(input, decimals = DEFAULT_BIAS_DECIMALS) {
-    if (!input || typeof input !== 'object')
-        return input;
-    const dp = clampBiasDecimals(decimals);
-    let cloned = null;
-    for (const [field, shouldRound] of Object.entries(POSITION_FIELDS)) {
-        if (!shouldRound)
-            continue;
-        const value = input[field];
-        if (!Array.isArray(value))
-            continue;
-        if (!cloned)
-            cloned = { ...input };
-        cloned[field] = value.map((v) => typeof v === 'number' && Number.isFinite(v) ? roundCoord(v, dp) : v);
-    }
-    return cloned ?? input;
-}