@chaosity/location-client 0.2.0 → 0.3.0

package/dist/adapters/GeoPlaces.d.ts

@@ -6,10 +6,55 @@ import type { GeoPlacesClient } from '../client/GeoPlacesClient';
  *
  * Implements MaplibreGeocoderApi interface for compatibility with @maplibre/maplibre-gl-geocoder
  */
+/**
+ * Extra GetPlace detail, and what each one costs (#3 / T19).
+ *
+ * Measured against Amazon Location on 2026-08-25 by requesting each feature
+ * alone and reading the pricing bucket back:
+ *
+ *   (none)              -> Core      $0.50/1k
+ *   SecondaryAddresses  -> Core      $0.50/1k
+ *   Access              -> Advanced  $1.50/1k
+ *   TimeZone            -> Advanced  $1.50/1k
+ *   Contact             -> Advanced  $1.50/1k
+ *
+ * `secondaryAddresses` is therefore free in bucket terms and the others triple
+ * the price of every lookup. They are opt-in for that reason, not because the
+ * data is unwelcome.
+ *
+ * Worth knowing before enabling `contact`: for a street address it costs
+ * Advanced and returns no contact field at all — only points of interest carry
+ * one. On an address-completion flow that is 3x the price for nothing.
+ */
+export interface GeoPlacesDetailOptions {
+    /** Entrance/exit points. Moves the request to the Advanced bucket. */
+    access?: boolean;
+    /** Unit and sub-address detail. Stays in the Core bucket — free to enable. */
+    secondaryAddresses?: boolean;
+    /** Phone/website, POIs only. Moves the request to the Advanced bucket. */
+    contact?: boolean;
+    /** IANA zone and offset. Moves the request to the Advanced bucket. */
+    timeZone?: boolean;
+}
+export interface GeoPlacesOptions {
+    /**
+     * Extra detail on `searchByPlaceId`. Default: none, which keeps every
+     * lookup in the Core bucket.
+     */
+    details?: GeoPlacesDetailOptions;
+}
 export declare class GeoPlaces implements MaplibreGeocoderApi {
     private client;
     private map;
-    constructor(client: GeoPlacesClient, map: Map);
+    private details;
+    constructor(client: GeoPlacesClient, map: Map, options?: GeoPlacesOptions);
+    /**
+     * Build the AdditionalFeatures list from the opt-ins, or omit it entirely.
+     *
+     * Returning `undefined` rather than `[]` matters: an empty array is still a
+     * field on the request, and the point is to send nothing.
+     */
+    private detailFeatures;
     private normalizeLanguage;
     forwardGeocode(config: MaplibreGeocoderApiConfig): Promise<MaplibreGeocoderFeatureResults>;
     reverseGeocode(config: MaplibreGeocoderApiConfig): Promise<MaplibreGeocoderFeatureResults>;

package/dist/adapters/GeoPlaces.js

@@ -1,16 +1,30 @@
-import { GeocodeCommand, GetPlaceAdditionalFeature, GetPlaceCommand, ReverseGeocodeCommand, SuggestAdditionalFeature, SuggestCommand, } from '@aws-sdk/client-geo-places';
+import { GeocodeCommand, GetPlaceAdditionalFeature, GetPlaceCommand, ReverseGeocodeCommand, SuggestCommand, } from '@aws-sdk/client-geo-places';
 import { geocodeResponseToFeatureCollection, getPlaceResponseToFeatureCollection, reverseGeocodeResponseToFeatureCollection, } from '@aws/amazon-location-utilities-datatypes';
 import debug from 'debug';
 const log = debug('location-client:geocoder');
-/**
- * GeoPlaces - MapLibre adapter for AWS Location Service
- *
- * Implements MaplibreGeocoderApi interface for compatibility with @maplibre/maplibre-gl-geocoder
- */
 export class GeoPlaces {
-    constructor(client, map) {
+    constructor(client, map, options = {}) {
         this.client = client;
         this.map = map;
+        this.details = options.details ?? {};
+    }
+    /**
+     * Build the AdditionalFeatures list from the opt-ins, or omit it entirely.
+     *
+     * Returning `undefined` rather than `[]` matters: an empty array is still a
+     * field on the request, and the point is to send nothing.
+     */
+    detailFeatures() {
+        const features = [];
+        if (this.details.access)
+            features.push(GetPlaceAdditionalFeature.ACCESS);
+        if (this.details.secondaryAddresses)
+            features.push(GetPlaceAdditionalFeature.SECONDARY_ADDRESSES);
+        if (this.details.contact)
+            features.push(GetPlaceAdditionalFeature.CONTACT);
+        if (this.details.timeZone)
+            features.push(GetPlaceAdditionalFeature.TIME_ZONE);
+        return features.length ? features : undefined;
     }
     normalizeLanguage(language) {
         if (Array.isArray(language))
@@ -73,7 +87,18 @@ export class GeoPlaces {
             BiasPosition: biasPosition,
             MaxResults: config.limit || 5,
             Language: this.normalizeLanguage(config.language),
-            AdditionalFeatures: [SuggestAdditionalFeature.CORE],
+            // No AdditionalFeatures (#3 / T19).
+            //
+            // This used to send `[Core]`, which put every keystroke in the Core
+            // bucket at $0.50/1k. The only thing Core adds to a Suggest response is
+            // `Highlights`, and this adapter reads `Title` and `Place.PlaceId` —
+            // nothing else. Verified against Amazon Location on 2026-08-25:
+            //
+            //   with [Core] -> bucket Core   keys: Title, ..., Place, Highlights
+            //   without     -> bucket Label  keys: Title, ..., Place
+            //
+            // Same two fields, $0.20/1k instead of $0.50. Suggest fires per
+            // keystroke, so it is the highest-volume call the library makes.
             ...(config.countries || config.bbox
                 ? {
                     Filter: {
@@ -103,15 +128,14 @@ export class GeoPlaces {
     }
     async searchByPlaceId(config) {
         log('searchByPlaceId placeId=%s', config.query);
+        // Opt-in rather than always-on (#3 / T19). Requesting all four put every
+        // lookup in the Advanced bucket at $1.50/1k; the default now sends none
+        // and stays in Core at $0.50. Callers that want the detail ask for it.
+        const additionalFeatures = this.detailFeatures();
         const command = new GetPlaceCommand({
             PlaceId: config.query,
             Language: this.normalizeLanguage(config.language),
-            AdditionalFeatures: [
-                GetPlaceAdditionalFeature.ACCESS,
-                GetPlaceAdditionalFeature.SECONDARY_ADDRESSES,
-                GetPlaceAdditionalFeature.CONTACT,
-                GetPlaceAdditionalFeature.TIME_ZONE,
-            ],
+            ...(additionalFeatures ? { AdditionalFeatures: additionalFeatures } : {}),
         });
         const response = (await this.client.send(command));
         const result = getPlaceResponseToFeatureCollection(response, {

package/dist/auth/TokenProvider.js

@@ -1,6 +1,7 @@
 import debug from 'debug';
 import { LocationServiceException } from '../errors/LocationServiceException';
 import { requestJson } from '../transport/http';
+import { TOKEN_REFRESH_BUFFER_SECONDS, readTokenExpiry } from './tokenRefresh';
 const log = debug('location-client:auth');
 /**
  * TokenProvider - SERVER-SIDE ONLY
@@ -110,9 +111,13 @@ export class TokenProvider {
             });
         }
         this.cachedToken = data.access_token;
-        // Prefer the absolute expires_at (ms); fall back to expires_in (seconds).
+        // The token's own `exp` claim first — it is the only value that cannot
+        // disagree with what the API will actually accept. `expires_at` and
+        // `expires_in` are what the response CLAIMS, and are kept as fallbacks.
         this.cachedExpiresAt =
-            data.expires_at ?? Date.now() + (data.expires_in ?? 900) * 1000;
+            readTokenExpiry(data.access_token) ??
+                data.expires_at ??
+                Date.now() + (data.expires_in ?? 900) * 1000;
         log('Token acquired successfully (expires in %ds)', Math.floor((this.cachedExpiresAt - Date.now()) / 1000));
         return {
             success: true,
@@ -120,7 +125,7 @@ export class TokenProvider {
             expiresAt: this.cachedExpiresAt,
         };
     }
-    isExpired(bufferSeconds = 60) {
+    isExpired(bufferSeconds = TOKEN_REFRESH_BUFFER_SECONDS) {
         if (!this.cachedExpiresAt)
             return true;
         return Date.now() >= this.cachedExpiresAt - bufferSeconds * 1000;

package/dist/auth/tokenRefresh.d.ts

@@ -0,0 +1,37 @@
+/**
+ * How long before expiry a token is treated as needing replacement.
+ *
+ * ONE number, used by both sides: the server-side `TokenProvider` deciding
+ * whether its cached token is still good, and the React provider deciding
+ * whether to ask for a new one. Both apply it to the same `exp` claim, so they
+ * cannot reach different answers about the same token.
+ *
+ * It used to be two separate `60`s — a private literal in `isExpired()` and a
+ * public `refreshBuffer` prop default — with nothing tying them together. On
+ * 2026-08-23 a consumer passed `refreshBuffer={800}` against a 900 s token: the
+ * client judged it stale after 100 s, the server still considered it fresh for
+ * another 840 s and returned the same one, and the client asked again
+ * immediately — roughly 110 requests per second from an idle page.
+ *
+ * Not configurable per consumer, deliberately. A settable client-side buffer is
+ * precisely what allowed that disagreement, and no amount of capping or backing
+ * off fixes it as cleanly as the two sides simply sharing the number.
+ */
+export declare const TOKEN_REFRESH_BUFFER_SECONDS = 60;
+/**
+ * Read the `exp` claim out of a JWT, in milliseconds.
+ *
+ * The expiry is IN THE TOKEN, so neither side needs to be told it. Both used to
+ * take it on trust from elsewhere — the server from the response body's
+ * `expires_at`, the React provider from whatever `getConfig` returned, falling
+ * back to inventing `Date.now() + 900_000` when that was absent. An invented
+ * expiry is how the two ended up disagreeing about the same token.
+ *
+ * Deliberately NOT verified. This is only used to decide *when to refresh*;
+ * nothing is authorised on the strength of it, and the API verifies the
+ * signature on every request regardless. Trusting `exp` for scheduling is safe
+ * in a way that trusting it for access would not be.
+ *
+ * Returns undefined for anything unparseable, so callers keep their fallback.
+ */
+export declare function readTokenExpiry(token: string | undefined): number | undefined;

package/dist/auth/tokenRefresh.js

@@ -0,0 +1,54 @@
+/**
+ * How long before expiry a token is treated as needing replacement.
+ *
+ * ONE number, used by both sides: the server-side `TokenProvider` deciding
+ * whether its cached token is still good, and the React provider deciding
+ * whether to ask for a new one. Both apply it to the same `exp` claim, so they
+ * cannot reach different answers about the same token.
+ *
+ * It used to be two separate `60`s — a private literal in `isExpired()` and a
+ * public `refreshBuffer` prop default — with nothing tying them together. On
+ * 2026-08-23 a consumer passed `refreshBuffer={800}` against a 900 s token: the
+ * client judged it stale after 100 s, the server still considered it fresh for
+ * another 840 s and returned the same one, and the client asked again
+ * immediately — roughly 110 requests per second from an idle page.
+ *
+ * Not configurable per consumer, deliberately. A settable client-side buffer is
+ * precisely what allowed that disagreement, and no amount of capping or backing
+ * off fixes it as cleanly as the two sides simply sharing the number.
+ */
+export const TOKEN_REFRESH_BUFFER_SECONDS = 60;
+/**
+ * Read the `exp` claim out of a JWT, in milliseconds.
+ *
+ * The expiry is IN THE TOKEN, so neither side needs to be told it. Both used to
+ * take it on trust from elsewhere — the server from the response body's
+ * `expires_at`, the React provider from whatever `getConfig` returned, falling
+ * back to inventing `Date.now() + 900_000` when that was absent. An invented
+ * expiry is how the two ended up disagreeing about the same token.
+ *
+ * Deliberately NOT verified. This is only used to decide *when to refresh*;
+ * nothing is authorised on the strength of it, and the API verifies the
+ * signature on every request regardless. Trusting `exp` for scheduling is safe
+ * in a way that trusting it for access would not be.
+ *
+ * Returns undefined for anything unparseable, so callers keep their fallback.
+ */
+export function readTokenExpiry(token) {
+    if (!token)
+        return undefined;
+    const payload = token.split('.')[1];
+    if (!payload)
+        return undefined;
+    try {
+        const base64 = payload.replace(/-/g, '+').replace(/_/g, '/');
+        const json = typeof atob === 'function'
+            ? atob(base64)
+            : Buffer.from(base64, 'base64').toString('utf8');
+        const exp = JSON.parse(json)?.exp;
+        return typeof exp === 'number' ? exp * 1000 : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/client/GeoPlacesClient.d.ts

@@ -1,5 +1,6 @@
 import type { RequestOptions } from '../transport/http';
 import type { ClientConfig } from '../types';
+import type { AppConfigClaims } from '../utils/tokenClaims';
 export type SendOptions = RequestOptions;
 /**
  * GeoPlacesClient — AWS Location Service compatible client with custom auth.
@@ -15,6 +16,21 @@ export declare class GeoPlacesClient {
         serviceId: string;
     };
     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.
+     *
+     * Provided so an application can SHOW its own settings: populate a country
+     * selector with the markets it actually serves, label a settings screen,
+     * and so on. Being a few minutes stale is cosmetic for that.
+     *
+     * It is not an entitlement check. See AppConfigClaims for why acting on
+     * `countries` client-side makes requests fail that would otherwise succeed.
+     *
+     * Returns `{}` when the token carries no application config, which is the
+     * case until one is configured in the portal.
+     */
+    getAppConfig(): AppConfigClaims;
     /**
      * @param options `signal` to cancel, `timeoutMs` per attempt, `retry: false`
      *   to disable the retry loop. Every failure throws LocationServiceException.

package/dist/client/GeoPlacesClient.js

@@ -2,6 +2,7 @@ import debug from 'debug';
 import { resolveEndpoint } from '../transport/endpoints';
 import { requestJson } from '../transport/http';
 import { roundPositionFields } from '../utils/roundPosition';
+import { readAppConfigClaims } from '../utils/tokenClaims';
 const log = debug('location-client:api');
 /**
  * GeoPlacesClient — AWS Location Service compatible client with custom auth.
@@ -16,6 +17,24 @@ export class GeoPlacesClient {
         this.clientConfig = config;
         this.config = { serviceId: 'Geo Places' };
     }
+    /**
+     * This application's own configuration, as carried on the access token
+     * (api#65) — bias precision, and 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 so on. Being a few minutes stale is cosmetic for that.
+     *
+     * It is not an entitlement check. See AppConfigClaims for why acting on
+     * `countries` client-side makes requests fail that would otherwise succeed.
+     *
+     * Returns `{}` when the token carries no application config, which is the
+     * case until one is configured in the portal.
+     */
+    getAppConfig() {
+        const token = this.clientConfig.getToken?.() ?? this.clientConfig.token;
+        return readAppConfigClaims(token);
+    }
     /**
      * @param options `signal` to cancel, `timeoutMs` per attempt, `retry: false`
      *   to disable the retry loop. Every failure throws LocationServiceException.
@@ -23,9 +42,12 @@ export class GeoPlacesClient {
     async send(command, options) {
         const cmd = command;
         const endpoint = resolveEndpoint(cmd);
-        const input = roundPositionFields(cmd.input);
         // Prefer the getToken callback (live ref) over a static token string.
         const token = this.clientConfig.getToken?.() ?? this.clientConfig.token;
+        // 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);
         log('Sending %s to %s', cmd.constructor?.name, endpoint);
         return requestJson(`${this.clientConfig.apiUrl}${endpoint}`, {
             method: 'POST',

package/dist/index.d.ts

@@ -2,11 +2,13 @@ export { GeoPlacesClient } from './client/GeoPlacesClient';
 export type { SendOptions } from './client/GeoPlacesClient';
 export { DEFAULT_MAX_ATTEMPTS, DEFAULT_TIMEOUT_MS } from './transport/http';
 export type { RequestOptions } from './transport/http';
+export { TOKEN_REFRESH_BUFFER_SECONDS, readTokenExpiry, } from './auth/tokenRefresh';
 export { LocationServiceException } from './errors/LocationServiceException';
 export type { LocationServiceExceptionOptions } from './errors/LocationServiceException';
 export * from '@aws-sdk/client-geo-places';
 export * from '@aws/amazon-location-utilities-datatypes';
 export { GeoPlaces } from './adapters/GeoPlaces';
+export type { GeoPlacesDetailOptions, GeoPlacesOptions, } from './adapters/GeoPlaces';
 export { createTransformRequest } from './maps/createTransformRequest';
 export { applyMapLanguage } from './maps/mapLanguage';
 export { POI_CATEGORIES, setAllPoiVisibility, setPoiVisibility, } from './maps/mapPoi';
@@ -15,3 +17,4 @@ export { buildMapStyleUrl, fetchMapStyle } from './maps/mapStyle';
 export type { MapStyleOptions } from './maps/mapStyle';
 export { transformRequest } from './maps/Utils';
 export type { ClientConfig, GeoPlacesCommand, MapLike } from './types';
+export type { AppConfigClaims } from './utils/tokenClaims';

package/dist/index.js

@@ -2,6 +2,8 @@
 export { GeoPlacesClient } from './client/GeoPlacesClient';
 // Transport options — cancellation, per-attempt timeout, retry policy
 export { DEFAULT_MAX_ATTEMPTS, DEFAULT_TIMEOUT_MS } from './transport/http';
+// Token refresh policy — shared by the server provider and the React provider
+export { TOKEN_REFRESH_BUFFER_SECONDS, readTokenExpiry, } from './auth/tokenRefresh';
 // Errors
 export { LocationServiceException } from './errors/LocationServiceException';
 // Re-export AWS SDK commands and types

package/dist/server/LocationServiceConnector.d.ts

@@ -1,4 +1,5 @@
 import type { RequestOptions } from '../transport/http';
+import type { AppConfigClaims } from '../utils/tokenClaims';
 export interface ConnectorConfig {
     apiUrl?: string;
     token?: string;
@@ -33,5 +34,22 @@ export declare class LocationServiceConnector {
     private origin?;
     readonly serviceId: string;
     constructor(config?: ConnectorConfig);
+    /** One place that knows how a token is obtained, so nothing can drift. */
+    private resolveToken;
+    /**
+     * This application's own configuration, as carried on the access token
+     * (api#65) — bias precision, and 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
+     * so on. Being a few minutes stale is cosmetic for that.
+     *
+     * It is not an entitlement check. See AppConfigClaims for why acting on
+     * `countries` client-side makes requests fail that would otherwise succeed.
+     *
+     * Returns `{}` when the token carries no application config, which is the
+     * case until one is configured in the portal.
+     */
+    getAppConfig(): Promise<AppConfigClaims>;
     send<TInput, TOutput>(command: TInput, options?: SendOptions): Promise<TOutput>;
 }

package/dist/server/LocationServiceConnector.js

@@ -3,6 +3,7 @@ import { LocationServiceException } from '../errors/LocationServiceException';
 import { resolveEndpoint } from '../transport/endpoints';
 import { requestJson } from '../transport/http';
 import { roundPositionFields } from '../utils/roundPosition';
+import { readAppConfigClaims } from '../utils/tokenClaims';
 import { getClientConfig } from './getClientConfig';
 const log = debug('location-client:connector');
 /**
@@ -24,20 +25,36 @@ export class LocationServiceConnector {
         this.configPromise = config ? Promise.resolve(config) : getClientConfig();
         this.origin = config?.origin;
     }
-    async send(command, options) {
+    /** One place that knows how a token is obtained, so nothing can drift. */
+    async resolveToken() {
         const config = await this.configPromise;
-        let token;
         if ('getToken' in config && typeof config.getToken === 'function') {
             const result = await config.getToken();
-            token = result
-                ? typeof result === 'string'
-                    ? result
-                    : result.token
-                : undefined;
-        }
-        else {
-            token = config.token;
+            if (!result)
+                return undefined;
+            return typeof result === 'string' ? result : result.token;
         }
+        return config.token;
+    }
+    /**
+     * This application's own configuration, as carried on the access token
+     * (api#65) — bias precision, and 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
+     * so on. Being a few minutes stale is cosmetic for that.
+     *
+     * It is not an entitlement check. See AppConfigClaims for why acting on
+     * `countries` client-side makes requests fail that would otherwise succeed.
+     *
+     * Returns `{}` when the token carries no application config, which is the
+     * case until one is configured in the portal.
+     */
+    async getAppConfig() {
+        return readAppConfigClaims(await this.resolveToken());
+    }
+    async send(command, options) {
+        const token = await this.resolveToken();
         if (!token) {
             throw new LocationServiceException({
                 code: 'InvalidCredentialsException',
@@ -47,7 +64,12 @@ export class LocationServiceConnector {
         }
         const cmd = command;
         const endpoint = resolveEndpoint(cmd);
-        const input = roundPositionFields(cmd.input);
+        // The token is already resolved above, so the precision this application
+        // is entitled to is available before the request is shaped (api#65).
+        // Absent claim -> the 3 dp floor, which is what every application gets
+        // until one is configured otherwise.
+        const { biasDecimals } = readAppConfigClaims(token);
+        const input = roundPositionFields(cmd.input, biasDecimals);
         // Caller headers first so the system ones below cannot be overridden, but an
         // explicit per-call Origin still beats the connector-wide default.
         const headers = {
@@ -57,6 +79,6 @@ export class LocationServiceConnector {
             Authorization: `Bearer ${token}`,
         };
         log('Sending %s request to %s', cmd.constructor?.name, endpoint);
-        return requestJson(`${config.apiUrl}${endpoint}`, { method: 'POST', headers, body: JSON.stringify(input) }, options);
+        return requestJson(`${(await this.configPromise).apiUrl}${endpoint}`, { method: 'POST', headers, body: JSON.stringify(input) }, options);
     }
 }

package/dist/utils/roundPosition.d.ts

@@ -1,15 +1,66 @@
 /**
- * Round coordinate arrays in command inputs for better API cache hits.
+ * Round coordinate arrays in command inputs so nearby callers share a server
+ * cache entry.
  *
- * BiasPosition is rounded to 2 decimal places (~1.1 km precision) —
- * sufficient for spatial biasing while maximizing cache reuse across
- * nearby users.
+ * `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).
  *
- * QueryPosition (reverse geocode) keeps full precision since it
- * represents an exact point the user clicked or their device reported.
+ * 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): T;
+export declare function roundPositionFields<T extends object>(input: T, decimals?: number): T;

package/dist/utils/roundPosition.js

@@ -1,38 +1,104 @@
 /**
- * Round coordinate arrays in command inputs for better API cache hits.
+ * Round coordinate arrays in command inputs so nearby callers share a server
+ * cache entry.
  *
- * BiasPosition is rounded to 2 decimal places (~1.1 km precision) —
- * sufficient for spatial biasing while maximizing cache reuse across
- * nearby users.
+ * `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).
  *
- * QueryPosition (reverse geocode) keeps full precision since it
- * represents an exact point the user clicked or their device reported.
+ * 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.
  */
-const BIAS_DECIMALS = 2; // ~1.1 km grid
-const BIAS_FACTOR = 10 ** BIAS_DECIMALS;
+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) {
-    return Math.round(value * BIAS_FACTOR) / BIAS_FACTOR;
+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) {
+export function roundPositionFields(input, decimals = DEFAULT_BIAS_DECIMALS) {
     if (!input || typeof input !== 'object')
         return input;
-    let modified = false;
-    const result = { ...input };
+    const dp = clampBiasDecimals(decimals);
+    let cloned = null;
     for (const [field, shouldRound] of Object.entries(POSITION_FIELDS)) {
-        const value = result[field];
-        if (!shouldRound || !Array.isArray(value) || value.length < 2)
+        if (!shouldRound)
+            continue;
+        const value = input[field];
+        if (!Array.isArray(value))
             continue;
-        result[field] = value.map(roundCoord);
-        modified = true;
+        if (!cloned)
+            cloned = { ...input };
+        cloned[field] = value.map((v) => typeof v === 'number' && Number.isFinite(v) ? roundCoord(v, dp) : v);
     }
-    return modified ? result : input;
+    return cloned ?? input;
 }

package/dist/utils/tokenClaims.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * 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.
+     *
+     * READ THIS, DO NOT ACT ON IT. It is here to be displayed — a country
+     * selector, a settings screen, a "this application serves AU and NZ" label.
+     *
+     * Do not inject it into requests and do not reject requests with it. The
+     * token is a snapshot up to fifteen minutes old; the API reads the scope
+     * fresh from the application row on every request. Acting on a stale value
+     * makes things WORSE, in both directions:
+     *
+     *   app is now scoped to NZ, token still says AU
+     *     send nothing         -> API injects [NZ]  -> 200
+     *     inject stale [AU]    -> outside scope     -> 400
+     *
+     * So a request that would have succeeded fails instead. Rejecting locally
+     * has the mirror-image bug: refusing something the API would now allow.
+     * Sending nothing and letting the API scope the request is always correct.
+     */
+    countries?: string[];
+}
+/**
+ * Decode a JWT payload without verifying it.
+ *
+ * Returns `{}` for anything unparseable. This runs on every request, so a
+ * surprising token must degrade to "no claims" rather than break geocoding
+ * for an application that is otherwise working.
+ */
+export declare function readAppConfigClaims(token?: string | null): AppConfigClaims;

package/dist/utils/tokenClaims.js

@@ -0,0 +1,58 @@
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * A JWT is signed, not encrypted, so the payload is plain base64url. Nothing
+ * secret is in it; these are the caller's own settings.
+ */
+/**
+ * Decode a JWT payload without verifying it.
+ *
+ * Returns `{}` for anything unparseable. This runs on every request, so a
+ * surprising token must degrade to "no claims" rather than break geocoding
+ * for an application that is otherwise working.
+ */
+export function readAppConfigClaims(token) {
+    if (typeof token !== 'string')
+        return {};
+    const parts = token.split('.');
+    if (parts.length !== 3)
+        return {};
+    try {
+        // base64url -> base64: JWT omits padding and swaps two characters.
+        const b64 = parts[1].replace(/-/g, '+').replace(/_/g, '/');
+        const padded = b64.padEnd(b64.length + ((4 - (b64.length % 4)) % 4), '=');
+        // `atob` exists in browsers and in Node 16+, so one path serves both.
+        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)
+                claims.countries = list;
+        }
+        return claims;
+    }
+    catch {
+        return {};
+    }
+}

package/package.json

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