@chaosity/location-client 0.2.1 → 0.4.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/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

@@ -8,11 +8,15 @@ export type { LocationServiceExceptionOptions } from './errors/LocationServiceEx
 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';
 export type { PoiCategory } from './maps/mapPoi';
 export { buildMapStyleUrl, fetchMapStyle } from './maps/mapStyle';
 export type { MapStyleOptions } from './maps/mapStyle';
+export { BUILDINGS, COLOR_SCHEMES, CONTOUR_DENSITIES, LABEL_SIZES, MAP_FEATURE_MODES, MAP_STYLES, SCALE_BAR_UNITS, SPRITE_VARIANTS, STATIC_MAP_STYLES, TERRAINS, TRAFFIC_MODES, TRAVEL_MODES, } from './maps/mapEnums';
+export type { Buildings, ColorScheme, ContourDensity, LabelSize, MapFeatureMode, MapStyle, ScaleBarUnit, SpriteVariant, StaticMapStyle, Terrain, TrafficMode, TravelMode, } from './maps/mapEnums';
 export { transformRequest } from './maps/Utils';
 export type { ClientConfig, GeoPlacesCommand, MapLike } from './types';
+export type { AppConfigClaims } from './utils/tokenClaims';

package/dist/index.js

@@ -17,5 +17,8 @@ export { createTransformRequest } from './maps/createTransformRequest';
 export { applyMapLanguage } from './maps/mapLanguage';
 export { POI_CATEGORIES, setAllPoiVisibility, setPoiVisibility, } from './maps/mapPoi';
 export { buildMapStyleUrl, fetchMapStyle } from './maps/mapStyle';
+// Accepted values for every map parameter, as VALUES so a picker can be built
+// from them, plus the matching types. Case sensitive — see mapEnums.ts.
+export { BUILDINGS, COLOR_SCHEMES, CONTOUR_DENSITIES, LABEL_SIZES, MAP_FEATURE_MODES, MAP_STYLES, SCALE_BAR_UNITS, SPRITE_VARIANTS, STATIC_MAP_STYLES, TERRAINS, TRAFFIC_MODES, TRAVEL_MODES, } from './maps/mapEnums';
 export { transformRequest } from './maps/Utils';
 // Server-only utilities are available via '@chaosity/location-client/server'

package/dist/maps/mapEnums.d.ts

@@ -0,0 +1,102 @@
+/**
+ * The values Amazon Location accepts for each map parameter.
+ *
+ * WHY THESE ARE EXPORTED AS VALUES, NOT JUST TYPES
+ *
+ * A type union gives you compile-time safety and nothing to iterate. Every
+ * consumer that renders a style picker then re-types the same list by hand into
+ * a `<select>`, and those copies drift the moment AWS adds a style. Exporting
+ * the arrays means a dropdown is `MAP_STYLES.map(...)` and cannot disagree with
+ * the type beside it.
+ *
+ * THESE ARE CASE SENSITIVE
+ *
+ * AWS documents them so, and since location-service-api#89 the API enforces it
+ * rather than forwarding a wrong-cased value for Amazon to reject with an
+ * unhelpful 404. `'light'` is not `'Light'`:
+ *
+ *   GET /maps/Standard/descriptor?colorScheme=light
+ *   400  "'colorScheme' is case sensitive — use 'Light', not 'light'"
+ *
+ * So take the values from here rather than typing them, and the case is right
+ * by construction.
+ *
+ * MEMBERSHIP IS NOT THE WHOLE STORY
+ *
+ * A value being in one of these lists does not mean it is legal in every
+ * COMBINATION. `Traffic: 'All'` is valid, and `Style: 'Satellite'` is valid,
+ * but together they are not:
+ *
+ *   400  "Traffic is not supported for style."
+ *
+ * Amazon owns those rules and answers them per request; the API forwards that
+ * message verbatim. Do not try to encode combination rules here — they change
+ * without an SDK release.
+ *
+ * KEEPING THESE HONEST
+ *
+ * The API derives its copy from the AWS SDK's own `enums.d.ts` via
+ * `npm run generate:maps-enums`, so that side cannot drift. This file is the
+ * client-side mirror and every value below was additionally confirmed against
+ * the live geo-maps API on 2026-08-26. If the API starts rejecting something
+ * listed here, its generated list is the authority.
+ */
+/** Map styles for the style descriptor. */
+export declare const MAP_STYLES: readonly ["Hybrid", "Monochrome", "Satellite", "Standard"];
+export type MapStyle = (typeof MAP_STYLES)[number];
+/**
+ * Styles the STATIC map accepts — deliberately narrower than `MAP_STYLES`.
+ *
+ * `/maps/static/*` takes only Satellite and Standard. Passing Hybrid or
+ * Monochrome there is a 400, so the two lists are not interchangeable.
+ */
+export declare const STATIC_MAP_STYLES: readonly ["Satellite", "Standard"];
+export type StaticMapStyle = (typeof STATIC_MAP_STYLES)[number];
+/** Light or dark cartography. Not applicable to the raster styles. */
+export declare const COLOR_SCHEMES: readonly ["Dark", "Light"];
+export type ColorScheme = (typeof COLOR_SCHEMES)[number];
+/** Terrain overlay. `Hillshade` is shaded relief; `Terrain3D` is elevation. */
+export declare const TERRAINS: readonly ["Hillshade", "Terrain3D"];
+export type Terrain = (typeof TERRAINS)[number];
+/** 3D building extrusions. One value today, kept a list for when that changes. */
+export declare const BUILDINGS: readonly ["Buildings3D"];
+export type Buildings = (typeof BUILDINGS)[number];
+/**
+ * Elevation contour line density.
+ *
+ * All three work. An earlier version of this library documented `Medium` as
+ * "the only value currently supported by the AWS SDK", which was wrong — `High`
+ * and `Low` were both confirmed against the live API on 2026-08-26.
+ */
+export declare const CONTOUR_DENSITIES: readonly ["High", "Low", "Medium"];
+export type ContourDensity = (typeof CONTOUR_DENSITIES)[number];
+/**
+ * Traffic overlay.
+ *
+ * `Congestion` was previously missing from this library's types, so it could
+ * not be requested from TypeScript even though the API accepts it.
+ */
+export declare const TRAFFIC_MODES: readonly ["All", "Congestion"];
+export type TrafficMode = (typeof TRAFFIC_MODES)[number];
+/** Routing overlays. Sent as a comma-separated list; each entry is checked. */
+export declare const TRAVEL_MODES: readonly ["Transit", "Truck"];
+export type TravelMode = (typeof TRAVEL_MODES)[number];
+/** Sprite sheet variant. One value today. */
+export declare const SPRITE_VARIANTS: readonly ["Default"];
+export type SpriteVariant = (typeof SPRITE_VARIANTS)[number];
+/** Static map label size. */
+export declare const LABEL_SIZES: readonly ["Large", "Small"];
+export type LabelSize = (typeof LABEL_SIZES)[number];
+/** Static map scale bar units. */
+export declare const SCALE_BAR_UNITS: readonly ["Kilometers", "KilometersMiles", "Miles", "MilesKilometers"];
+export type ScaleBarUnit = (typeof SCALE_BAR_UNITS)[number];
+/**
+ * Static map points-of-interest rendering.
+ *
+ * A MODE, not a list of categories — an easy one to get wrong, and the reason
+ * the static map route returned a confusing error before
+ * location-service-api#35. To filter POIs on an interactive map, use
+ * `setPoiVisibility` instead.
+ */
+export declare const MAP_FEATURE_MODES: readonly ["Disabled", "Enabled"];
+export type MapFeatureMode = (typeof MAP_FEATURE_MODES)[number];

package/dist/maps/mapEnums.js

@@ -0,0 +1,100 @@
+/**
+ * The values Amazon Location accepts for each map parameter.
+ *
+ * WHY THESE ARE EXPORTED AS VALUES, NOT JUST TYPES
+ *
+ * A type union gives you compile-time safety and nothing to iterate. Every
+ * consumer that renders a style picker then re-types the same list by hand into
+ * a `<select>`, and those copies drift the moment AWS adds a style. Exporting
+ * the arrays means a dropdown is `MAP_STYLES.map(...)` and cannot disagree with
+ * the type beside it.
+ *
+ * THESE ARE CASE SENSITIVE
+ *
+ * AWS documents them so, and since location-service-api#89 the API enforces it
+ * rather than forwarding a wrong-cased value for Amazon to reject with an
+ * unhelpful 404. `'light'` is not `'Light'`:
+ *
+ *   GET /maps/Standard/descriptor?colorScheme=light
+ *   400  "'colorScheme' is case sensitive — use 'Light', not 'light'"
+ *
+ * So take the values from here rather than typing them, and the case is right
+ * by construction.
+ *
+ * MEMBERSHIP IS NOT THE WHOLE STORY
+ *
+ * A value being in one of these lists does not mean it is legal in every
+ * COMBINATION. `Traffic: 'All'` is valid, and `Style: 'Satellite'` is valid,
+ * but together they are not:
+ *
+ *   400  "Traffic is not supported for style."
+ *
+ * Amazon owns those rules and answers them per request; the API forwards that
+ * message verbatim. Do not try to encode combination rules here — they change
+ * without an SDK release.
+ *
+ * KEEPING THESE HONEST
+ *
+ * The API derives its copy from the AWS SDK's own `enums.d.ts` via
+ * `npm run generate:maps-enums`, so that side cannot drift. This file is the
+ * client-side mirror and every value below was additionally confirmed against
+ * the live geo-maps API on 2026-08-26. If the API starts rejecting something
+ * listed here, its generated list is the authority.
+ */
+/** Map styles for the style descriptor. */
+export const MAP_STYLES = [
+    'Hybrid',
+    'Monochrome',
+    'Satellite',
+    'Standard',
+];
+/**
+ * Styles the STATIC map accepts — deliberately narrower than `MAP_STYLES`.
+ *
+ * `/maps/static/*` takes only Satellite and Standard. Passing Hybrid or
+ * Monochrome there is a 400, so the two lists are not interchangeable.
+ */
+export const STATIC_MAP_STYLES = ['Satellite', 'Standard'];
+/** Light or dark cartography. Not applicable to the raster styles. */
+export const COLOR_SCHEMES = ['Dark', 'Light'];
+/** Terrain overlay. `Hillshade` is shaded relief; `Terrain3D` is elevation. */
+export const TERRAINS = ['Hillshade', 'Terrain3D'];
+/** 3D building extrusions. One value today, kept a list for when that changes. */
+export const BUILDINGS = ['Buildings3D'];
+/**
+ * Elevation contour line density.
+ *
+ * All three work. An earlier version of this library documented `Medium` as
+ * "the only value currently supported by the AWS SDK", which was wrong — `High`
+ * and `Low` were both confirmed against the live API on 2026-08-26.
+ */
+export const CONTOUR_DENSITIES = ['High', 'Low', 'Medium'];
+/**
+ * Traffic overlay.
+ *
+ * `Congestion` was previously missing from this library's types, so it could
+ * not be requested from TypeScript even though the API accepts it.
+ */
+export const TRAFFIC_MODES = ['All', 'Congestion'];
+/** Routing overlays. Sent as a comma-separated list; each entry is checked. */
+export const TRAVEL_MODES = ['Transit', 'Truck'];
+/** Sprite sheet variant. One value today. */
+export const SPRITE_VARIANTS = ['Default'];
+/** Static map label size. */
+export const LABEL_SIZES = ['Large', 'Small'];
+/** Static map scale bar units. */
+export const SCALE_BAR_UNITS = [
+    'Kilometers',
+    'KilometersMiles',
+    'Miles',
+    'MilesKilometers',
+];
+/**
+ * Static map points-of-interest rendering.
+ *
+ * A MODE, not a list of categories — an easy one to get wrong, and the reason
+ * the static map route returned a confusing error before
+ * location-service-api#35. To filter POIs on an interactive map, use
+ * `setPoiVisibility` instead.
+ */
+export const MAP_FEATURE_MODES = ['Disabled', 'Enabled'];

package/dist/maps/mapStyle.d.ts

@@ -1,23 +1,42 @@
 import type { StyleSpecification } from 'maplibre-gl';
+import type { Buildings, ColorScheme, ContourDensity, MapStyle, Terrain, TrafficMode, TravelMode } from './mapEnums';
 /**
  * Options for building an AWS Location Service map style URL.
  * All parameters map directly to query parameters supported by the style descriptor endpoint.
+ *
+ * Values are CASE SENSITIVE — the API rejects a wrong-cased one with a 400 that
+ * names the right spelling. Import the arrays from `mapEnums` to build pickers
+ * rather than typing the values, and the case is right by construction.
  */
 export interface MapStyleOptions {
     /** Color scheme for the map (default: Light). Not applicable to Satellite/Hybrid styles. */
-    colorScheme?: 'Light' | 'Dark';
+    colorScheme?: ColorScheme;
     /** ISO 3166-1 alpha-3 country code for political boundary perspective (e.g. 'IND', 'TUR'). */
     politicalView?: string;
     /** Terrain overlay type. */
-    terrain?: 'Hillshade' | 'Terrain3D';
+    terrain?: Terrain;
     /** Enable 3D building extrusions. */
-    buildings?: 'Buildings3D';
-    /** Elevation contour line density. Only 'Medium' is currently supported by the AWS SDK. */
-    contourDensity?: 'Medium';
-    /** Enable real-time traffic flow visualization. */
-    traffic?: 'All';
+    buildings?: Buildings;
+    /**
+     * Elevation contour line density.
+     *
+     * All of High, Low and Medium work. This was previously typed as `'Medium'`
+     * alone, documented as "the only value currently supported by the AWS SDK",
+     * which was wrong — the other two were confirmed against the live API.
+     */
+    contourDensity?: ContourDensity;
+    /**
+     * Traffic overlay.
+     *
+     * `Congestion` was previously missing here, so it could not be requested from
+     * TypeScript even though the API accepts it.
+     *
+     * Valid on its own, but NOT with every style: `Satellite` + `All` answers
+     * 400 "Traffic is not supported for style." Amazon owns that rule.
+     */
+    traffic?: TrafficMode;
     /** Travel mode overlays for routing-specific features. */
-    travelModes?: Array<'Truck' | 'Transit'>;
+    travelModes?: TravelMode[];
 }
 /**
  * Build a map style descriptor URL for the Location Service API.
@@ -31,7 +50,7 @@ export interface MapStyleOptions {
  * const url = buildMapStyleUrl(API_URL, 'Standard', { colorScheme: 'Dark', terrain: 'Hillshade' })
  * map.setStyle(url)
  */
-export declare function buildMapStyleUrl(apiUrl: string, mapStyle: string, options?: MapStyleOptions): string;
+export declare function buildMapStyleUrl(apiUrl: string, mapStyle: MapStyle, options?: MapStyleOptions): string;
 /**
  * Fetch the map style descriptor with authentication and apply descriptor-level modifications.
  *
@@ -53,6 +72,6 @@ export declare function buildMapStyleUrl(apiUrl: string, mapStyle: string, optio
  * const style = await fetchMapStyle(API_URL, 'Standard', getToken, { colorScheme: 'Dark', language: 'fr' })
  * const map = new maplibregl.Map({ style, transformRequest: createTransformRequest(API_URL, getToken) })
  */
-export declare function fetchMapStyle(apiUrl: string, mapStyle: string, getToken: () => string | undefined, options?: MapStyleOptions & {
+export declare function fetchMapStyle(apiUrl: string, mapStyle: MapStyle, getToken: () => string | undefined, options?: MapStyleOptions & {
     language?: string;
 }): Promise<StyleSpecification>;

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.1",
+  "version": "0.4.0",
   "description": "Client library for Chaosity Location Service with AWS Location Service compatibility",
   "type": "module",
   "main": "dist/index.js",