@chaosity/location-client 0.7.0 → 0.9.0

package/dist/types/index.d.ts

@@ -1,12 +1,29 @@
+/**
+ * At least one of `token`, `getToken` or `refreshToken` must supply a token, or
+ * `send` refuses locally with `InvalidCredentialsException` rather than putting
+ * `Bearer undefined` on the wire (#37).
+ *
+ * `token` is optional because a client driven purely by a provider — the shape
+ * `@chaosity/location-client-react` uses — has nothing to put there at
+ * construction time, and was previously forced to invent a placeholder. It is
+ * still required on `ServerClientConfig`, which is a RESULT rather than a
+ * configuration: `getClientConfig` always resolves one.
+ */
 export interface ClientConfig {
     apiUrl: string;
-    token: string;
+    token?: string;
     /** Optional callback to get the current token dynamically. When provided,
      *  called on every request so token updates are reflected without recreating the client. */
     getToken?: () => string | undefined;
     /**
      * Asked for a replacement AFTER the API has rejected the current token with a
-     * 401, so the request can be retried once instead of failing.
+     * 401, so the request can be retried once instead of failing — and, since
+     * #37, asked once BEFORE the first send when neither `getToken` nor `token`
+     * yields anything, so a client whose token has not arrived yet does not spend
+     * a round trip on `Bearer undefined` to learn that. Both calls mean the same
+     * thing to an implementor — "give me a usable token" — so a `refreshToken`
+     * that mints or awaits one needs no change; only one that assumes every
+     * invocation follows a 401 does.
      *
      * Separate from `getToken` because that one is synchronous by contract — it
      * is read while a request is being built and cannot await anything, so it can

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.7.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;
-}