@chaosity/location-client 0.7.0 → 0.9.0

package/README.md

@@ -226,9 +226,57 @@ token already in hand, and a token the API stops accepting **before** its `exp`
 the refresh buffer elapses. `refreshToken` is awaited after a 401, and the
 request is retried **once** with what it returns. Return the same token, or
 nothing, and no retry is sent — a request that is going to fail again is not
-worth being billed for twice. A 403 is never retried: a new token cannot fix an
+worth a second round trip. A 403 is never retried: a new token cannot fix an
 `Origin` the application does not allow.
 
+#### Request options
+
+Every call in this package takes the same options object — `client.send`,
+`connector.send`, `fetchMapStyle` and `fetchStaticMap` — and every failure
+arrives as a `LocationServiceException`.
+
+```typescript
+await client.send(command, {
+  signal, // AbortSignal — cancels mid-flight AND mid-backoff
+  timeoutMs: 10_000, // per ATTEMPT
+  overallTimeoutMs: 30_000, // the whole call, waits between attempts included
+  retry: { maxAttempts: 3 }, // or `false` for none
+})
+```
+
+`overallTimeoutMs` is the one worth setting deliberately, and it defaults to
+30 s. `timeoutMs` bounds an attempt, not a call: the API answers a spent quota
+with `Retry-After: 60`, and honouring that literally across two retries blocked
+the caller for about two minutes — past any Lambda budget. Now no attempt gets
+more time than the call has left, and a retry that would have to wait longer
+than the remaining budget is not made at all. You get the API's own error back
+instead, `retryAfterMs` intact, so you can queue the work rather than guess.
+
+The map helpers take them as a trailing argument:
+
+```typescript
+const style = await fetchMapStyle(
+  apiUrl,
+  'Standard',
+  getToken,
+  { language: 'fr' },
+  { signal },
+)
+const blob = await fetchStaticMap(
+  apiUrl,
+  { width: 640, height: 400, center },
+  getToken,
+  { signal },
+)
+```
+
+**A call with no token is refused locally rather than sent.** Every path that
+builds an `Authorization` header checks first, so a token source that has not
+produced one yet raises `InvalidCredentialsException` instead of putting
+`Bearer undefined` on the wire — which could only ever come back a 401, a round
+trip spent to be told what you already know. `GeoPlacesClient` asks `refreshToken` first, so a
+client whose token simply has not arrived yet still works.
+
 #### GeoPlaces Adapter
 
 Implements the `MaplibreGeocoderApi` interface for use with `@maplibre/maplibre-gl-geocoder`. Methods are called automatically by the geocoder control.
@@ -437,17 +485,30 @@ const connector = new LocationServiceConnector({
 })
 ```
 
-## Cache-Friendly Position Rounding
-
-`BiasPosition` coordinates are automatically rounded before each API request, to
-whatever precision your application is entitled to — a `biasDecimals` claim on
-the access token, defaulting to **3 decimal places** (~110 m) when the token
-carries none. This maximizes cache hits across nearby users without affecting
-result quality — bias is approximate by nature.
-
-`QueryPosition` (reverse geocode) retains full precision since it represents an exact point the user selected.
-
-This is handled transparently in both `GeoPlacesClient` and `LocationServiceConnector` — no action needed in application code.
+## Coordinates Are Sent As You Supply Them
+
+Both `GeoPlacesClient` and `LocationServiceConnector` put your command input on
+the wire unchanged. `BiasPosition` and `QueryPosition` arrive at the service at
+the precision you passed.
+
+Earlier versions rounded `BiasPosition` to a grid — 3 decimal places by
+default — so that nearby callers could share a cached upstream answer. Requests
+are no longer cached, so the rounding had nothing left to share and only
+lowered the precision the geocoder worked from.
+
+That is not a coarser result, it is a different one. A 3 dp grid moves a
+coordinate by up to ~70 m, depending where in its cell the coordinate falls,
+and the places a search returns change well inside that distance: measured
+against this service, a bias moved ~70 m returned a different set of nearby
+places, not the same set in a different order. If you were relying on the
+rounding to group nearby requests, round before you call.
+
+One coordinate is normalised: a static map's `center`, `bounding-box` and
+`bounded-positions` are rounded to six decimals — ~10 cm, below one pixel of a
+raster render. That is this library's choice, well inside what the service
+accepts: at most fourteen decimals per number, and at most 36 characters for
+the pair. A value straight from `map.getCenter()` carries fifteen or sixteen
+decimals and fails the first of those. A format rule, not a precision policy.
 
 ## Logging
 

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

@@ -18,7 +18,7 @@ export declare class GeoPlacesClient {
     constructor(config: ClientConfig);
     /**
      * This application's own configuration, as carried on the access token
-     * (api#65) — bias precision, and the countries it is scoped to.
+     * (api#65) — today, the countries it is scoped to.
      *
      * Provided so an application can SHOW its own settings: populate a country
      * selector with the markets it actually serves, label a settings screen,
@@ -34,8 +34,16 @@ export declare class GeoPlacesClient {
     /** Prefer the getToken callback (live ref) over a static token string. */
     private currentToken;
     /**
-     * @param options `signal` to cancel, `timeoutMs` per attempt, `retry: false`
-     *   to disable the retry loop. Every failure throws LocationServiceException.
+     * A token to send, or a refusal — never `undefined`.
+     *
+     * `refreshToken` is asked only when there is nothing at all in hand, so a
+     * client configured the ordinary way pays nothing for this.
+     */
+    private ensureToken;
+    /**
+     * @param options `signal` to cancel, `timeoutMs` per attempt,
+     *   `overallTimeoutMs` for the whole call, `retry: false` to disable the
+     *   retry loop. Every failure throws LocationServiceException.
      */
     send<TInput, TOutput>(command: TInput, options?: SendOptions): Promise<TOutput>;
     private dispatch;

package/dist/cjs/client/GeoPlacesClient.js

@@ -8,7 +8,6 @@ const debug_1 = __importDefault(require("debug"));
 const endpoints_js_1 = require("../transport/endpoints.js");
 const errors_js_1 = require("../transport/errors.js");
 const http_js_1 = require("../transport/http.js");
-const roundPosition_js_1 = require("../utils/roundPosition.js");
 const tokenClaims_js_1 = require("../utils/tokenClaims.js");
 const log = (0, debug_1.default)('location-client:api');
 /**
@@ -26,7 +25,7 @@ class GeoPlacesClient {
     }
     /**
      * This application's own configuration, as carried on the access token
-     * (api#65) — bias precision, and the countries it is scoped to.
+     * (api#65) — today, the countries it is scoped to.
      *
      * Provided so an application can SHOW its own settings: populate a country
      * selector with the markets it actually serves, label a settings screen,
@@ -46,13 +45,39 @@ class GeoPlacesClient {
         return this.clientConfig.getToken?.() ?? this.clientConfig.token;
     }
     /**
-     * @param options `signal` to cancel, `timeoutMs` per attempt, `retry: false`
-     *   to disable the retry loop. Every failure throws LocationServiceException.
+     * A token to send, or a refusal — never `undefined`.
+     *
+     * `refreshToken` is asked only when there is nothing at all in hand, so a
+     * client configured the ordinary way pays nothing for this.
+     */
+    async ensureToken() {
+        // `||`, not `??`: an empty string is a token source with nothing to give,
+        // not a decision to send an empty one. With `??` it survived the coalesce,
+        // skipped `refreshToken`, and then failed the check two lines below — so
+        // `getToken: () => undefined` got the refresh ask and `getToken: () => ''`
+        // did not, which is a distinction no caller means to draw.
+        const token = this.currentToken() || (await this.clientConfig.refreshToken?.());
+        if (!token) {
+            throw (0, errors_js_1.noTokenAvailable)('the client has no token yet. Pass `token`, or a `getToken`/`refreshToken` that has one.');
+        }
+        return token;
+    }
+    /**
+     * @param options `signal` to cancel, `timeoutMs` per attempt,
+     *   `overallTimeoutMs` for the whole call, `retry: false` to disable the
+     *   retry loop. Every failure throws LocationServiceException.
      */
     async send(command, options) {
         const cmd = command;
         const url = `${this.clientConfig.apiUrl}${(0, endpoints_js_1.resolveEndpoint)(cmd)}`;
-        const token = this.currentToken();
+        // The fifth and last place in this package that turns a token into an
+        // `Authorization` header, and the last one that would send `Bearer
+        // undefined` (#37). The 401 self-heal below cannot cover this case — it
+        // needs a request to have been rejected first — so a client whose token
+        // source has not produced one yet spent a whole round trip to learn
+        // something it already knew. Ask the refresh source instead, and refuse if
+        // there is still nothing.
+        const token = await this.ensureToken();
         try {
             return await this.dispatch(url, token, cmd, options);
         }
@@ -65,8 +90,8 @@ class GeoPlacesClient {
             // refreshes in the background may have landed a new one while this
             // request was in flight.
             const fresh = (await this.clientConfig.refreshToken?.()) ?? this.currentToken();
-            // Nothing new to send. Repeating the request would fail identically, and
-            // be billed identically.
+            // Nothing new to send. Repeating the request would fail identically — a
+            // second round trip for the same 401.
             if (!fresh || fresh === token)
                 throw err;
             log('401 — retrying %s once with a refreshed token', cmd.constructor?.name);
@@ -74,10 +99,11 @@ class GeoPlacesClient {
         }
     }
     dispatch(url, token, cmd, options) {
-        // Resolve the token BEFORE rounding: the precision this application is
-        // entitled to is a claim on it (api#65). Absent claim -> the 3 dp floor.
-        const { biasDecimals } = (0, tokenClaims_js_1.readAppConfigClaims)(token);
-        const input = (0, roundPosition_js_1.roundPositionFields)(cmd.input, biasDecimals);
+        // The caller's input goes out as the caller wrote it. `BiasPosition` used
+        // to be rounded here to a grid sized by a token claim, so nearby callers
+        // shared a server cache entry; with no cache the rounding only lowered the
+        // precision the upstream geocoder had to work with, which moves the
+        // results rather than coarsening them (#51).
         log('Sending %s to %s', cmd.constructor?.name, url);
         return (0, http_js_1.requestJson)(url, {
             method: 'POST',
@@ -85,7 +111,7 @@ class GeoPlacesClient {
                 'Content-Type': 'application/json',
                 Authorization: `Bearer ${token}`,
             },
-            body: JSON.stringify(input),
+            body: JSON.stringify(cmd.input),
         }, options);
     }
 }

package/dist/cjs/index.d.ts

@@ -1,6 +1,6 @@
 export { GeoPlacesClient } from './client/GeoPlacesClient.js';
 export type { SendOptions } from './client/GeoPlacesClient.js';
-export { DEFAULT_MAX_ATTEMPTS, DEFAULT_TIMEOUT_MS } from './transport/http.js';
+export { DEFAULT_MAX_ATTEMPTS, DEFAULT_OVERALL_TIMEOUT_MS, DEFAULT_TIMEOUT_MS, } from './transport/http.js';
 export type { RequestOptions } from './transport/http.js';
 export { TOKEN_REFRESH_BUFFER_SECONDS, readTokenExpiry, } from './auth/tokenRefresh.js';
 export { LocationServiceException } from './errors/LocationServiceException.js';

package/dist/cjs/index.js

@@ -14,13 +14,14 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.transformRequest = exports.TRAVEL_MODES = exports.TRAFFIC_MODES = exports.TERRAINS = exports.STATIC_MAP_STYLES = exports.SPRITE_VARIANTS = exports.SCALE_BAR_UNITS = exports.MAP_STYLES = exports.MAP_FEATURE_MODES = exports.LABEL_SIZES = exports.CONTOUR_DENSITIES = exports.COLOR_SCHEMES = exports.BUILDINGS = exports.staticMapAccept = exports.fetchStaticMap = exports.buildStaticMapUrl = exports.fetchMapStyle = exports.buildMapStyleUrl = exports.setPoiVisibility = exports.setAllPoiVisibility = exports.POI_CATEGORIES = exports.applyMapLanguage = exports.createTransformRequest = exports.GeoPlaces = exports.LocationServiceException = exports.readTokenExpiry = exports.TOKEN_REFRESH_BUFFER_SECONDS = exports.DEFAULT_TIMEOUT_MS = exports.DEFAULT_MAX_ATTEMPTS = exports.GeoPlacesClient = void 0;
+exports.transformRequest = exports.TRAVEL_MODES = exports.TRAFFIC_MODES = exports.TERRAINS = exports.STATIC_MAP_STYLES = exports.SPRITE_VARIANTS = exports.SCALE_BAR_UNITS = exports.MAP_STYLES = exports.MAP_FEATURE_MODES = exports.LABEL_SIZES = exports.CONTOUR_DENSITIES = exports.COLOR_SCHEMES = exports.BUILDINGS = exports.staticMapAccept = exports.fetchStaticMap = exports.buildStaticMapUrl = exports.fetchMapStyle = exports.buildMapStyleUrl = exports.setPoiVisibility = exports.setAllPoiVisibility = exports.POI_CATEGORIES = exports.applyMapLanguage = exports.createTransformRequest = exports.GeoPlaces = exports.LocationServiceException = exports.readTokenExpiry = exports.TOKEN_REFRESH_BUFFER_SECONDS = exports.DEFAULT_TIMEOUT_MS = exports.DEFAULT_OVERALL_TIMEOUT_MS = exports.DEFAULT_MAX_ATTEMPTS = exports.GeoPlacesClient = void 0;
 // Client (Custom - uses our auth instead of AWS SigV4)
 var GeoPlacesClient_js_1 = require("./client/GeoPlacesClient.js");
 Object.defineProperty(exports, "GeoPlacesClient", { enumerable: true, get: function () { return GeoPlacesClient_js_1.GeoPlacesClient; } });
-// Transport options — cancellation, per-attempt timeout, retry policy
+// Transport options — cancellation, per-attempt timeout, overall budget, retry
 var http_js_1 = require("./transport/http.js");
 Object.defineProperty(exports, "DEFAULT_MAX_ATTEMPTS", { enumerable: true, get: function () { return http_js_1.DEFAULT_MAX_ATTEMPTS; } });
+Object.defineProperty(exports, "DEFAULT_OVERALL_TIMEOUT_MS", { enumerable: true, get: function () { return http_js_1.DEFAULT_OVERALL_TIMEOUT_MS; } });
 Object.defineProperty(exports, "DEFAULT_TIMEOUT_MS", { enumerable: true, get: function () { return http_js_1.DEFAULT_TIMEOUT_MS; } });
 // Token refresh policy — shared by the server provider and the React provider
 var tokenRefresh_js_1 = require("./auth/tokenRefresh.js");

package/dist/cjs/maps/mapStyle.d.ts

@@ -1,4 +1,5 @@
 import type { StyleSpecification } from 'maplibre-gl';
+import type { RequestOptions } from '../transport/http.js';
 import type { Buildings, ColorScheme, ContourDensity, MapStyle, Terrain, TrafficMode, TravelMode } from './mapEnums.js';
 /**
  * Options for building an AWS Location Service map style URL.
@@ -66,6 +67,7 @@ export declare function buildMapStyleUrl(apiUrl: string, mapStyle: MapStyle, opt
  * @param mapStyle - Map style name (e.g. 'Standard', 'Monochrome', 'Satellite', 'Hybrid')
  * @param getToken - Callback returning the current auth token
  * @param options - Style options; `language` is applied to the descriptor, all others become URL params
+ * @param request - Transport options: `signal` to cancel, `timeoutMs`, `overallTimeoutMs`, `retry`
  * @returns Modified MapLibre StyleSpecification object
  *
  * @example
@@ -74,4 +76,4 @@ export declare function buildMapStyleUrl(apiUrl: string, mapStyle: MapStyle, opt
  */
 export declare function fetchMapStyle(apiUrl: string, mapStyle: MapStyle, getToken: () => string | undefined, options?: MapStyleOptions & {
     language?: string;
-}): Promise<StyleSpecification>;
+}, request?: RequestOptions): Promise<StyleSpecification>;

package/dist/cjs/maps/mapStyle.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildMapStyleUrl = buildMapStyleUrl;
 exports.fetchMapStyle = fetchMapStyle;
 const errors_js_1 = require("../transport/errors.js");
+const http_js_1 = require("../transport/http.js");
 const mapLanguage_js_1 = require("./mapLanguage.js");
 /**
  * Build a map style descriptor URL for the Location Service API.
@@ -50,38 +51,42 @@ function buildMapStyleUrl(apiUrl, mapStyle, options = {}) {
  * @param mapStyle - Map style name (e.g. 'Standard', 'Monochrome', 'Satellite', 'Hybrid')
  * @param getToken - Callback returning the current auth token
  * @param options - Style options; `language` is applied to the descriptor, all others become URL params
+ * @param request - Transport options: `signal` to cancel, `timeoutMs`, `overallTimeoutMs`, `retry`
  * @returns Modified MapLibre StyleSpecification object
  *
  * @example
  * const style = await fetchMapStyle(API_URL, 'Standard', getToken, { colorScheme: 'Dark', language: 'fr' })
  * const map = new maplibregl.Map({ style, transformRequest: createTransformRequest(API_URL, getToken) })
  */
-async function fetchMapStyle(apiUrl, mapStyle, getToken, options = {}) {
+async function fetchMapStyle(apiUrl, mapStyle, getToken, options = {}, request = {}) {
     const { language, ...styleOptions } = options;
     const url = buildMapStyleUrl(apiUrl, mapStyle, styleOptions);
     const token = getToken();
-    const response = await fetch(url, {
+    // `Bearer undefined` used to go out here, and came back as a 401 the caller
+    // had to work backwards from — a whole round trip for a request that was
+    // never going to succeed (#37).
+    if (!token) {
+        throw (0, errors_js_1.noTokenAvailable)('getToken() returned nothing, so no style request was sent. Check the token provider has finished initialising.');
+    }
+    // Through the shared transport, not a bare fetch: this gets the same
+    // per-attempt timeout, overall budget, cancellation and retry as every other
+    // call in the package, and the same error type on the way out. It also keeps
+    // the API's own message, which is the whole point of reading the body — for
+    // a style request that sentence is Amazon's, forwarded verbatim by
+    // location-service-api#89:
+    //
+    //   400 "Traffic is not supported for style."
+    //   400 "light is not a supported color scheme for style Standard."
+    //
+    // This used to throw `Failed to fetch map style: 400`, discarding all of it
+    // two lines before anyone could read it — the same defect #89 fixed in the
+    // API, one layer up.
+    const style = await (0, http_js_1.requestJson)(url, {
         headers: {
             Authorization: `Bearer ${token}`,
             Accept: 'application/json',
         },
-    });
-    if (!response.ok) {
-        // Read the body. The API sends `{message, code, requestId}` and the message
-        // is the whole point of it — for a style request it is Amazon's own
-        // sentence, forwarded verbatim by location-service-api#89:
-        //
-        //   400 "Traffic is not supported for style."
-        //   400 "light is not a supported color scheme for style Standard."
-        //
-        // This used to throw `Failed to fetch map style: 400`, discarding all of it
-        // two lines before anyone could read it — the same defect #89 fixed in the
-        // API, one layer up. Reuses parseErrorResponse so a style failure arrives as
-        // the same LocationServiceException as every other call in this package,
-        // with `code`, `statusCode` and `requestId` intact.
-        throw (0, errors_js_1.parseErrorResponse)(response.status, response.statusText, await response.text(), response.headers);
-    }
-    const style = (await response.json());
+    }, request);
     if (language) {
         applyLanguageToDescriptor(style, language);
     }

package/dist/cjs/maps/staticMap.d.ts

@@ -1,3 +1,4 @@
+import type { RequestOptions } from '../transport/http.js';
 import type { ColorScheme, LabelSize, MapFeatureMode, ScaleBarUnit, StaticMapStyle } from './mapEnums.js';
 /**
  * Static maps: build the URL, send the right headers, get a Blob.
@@ -74,6 +75,7 @@ export declare function buildStaticMapUrl(apiUrl: string, options: StaticMapOpti
  * @param apiUrl   Base URL of the Location Service API
  * @param options  Render options; exactly one of center / boundingBox / boundedPositions
  * @param getToken Callback returning the current auth token
+ * @param request  Transport options: `signal` to cancel, `timeoutMs`, `overallTimeoutMs`, `retry`
  *
  * @example
  * const blob = await fetchStaticMap(API_URL, {
@@ -82,4 +84,4 @@ export declare function buildStaticMapUrl(apiUrl: string, options: StaticMapOpti
  * }, getToken)
  * const url = URL.createObjectURL(blob)   // remember to revokeObjectURL
  */
-export declare function fetchStaticMap(apiUrl: string, options: StaticMapOptions, getToken: () => string | undefined): Promise<Blob>;
+export declare function fetchStaticMap(apiUrl: string, options: StaticMapOptions, getToken: () => string | undefined, request?: RequestOptions): Promise<Blob>;

package/dist/cjs/maps/staticMap.js

@@ -4,6 +4,7 @@ exports.staticMapAccept = staticMapAccept;
 exports.buildStaticMapUrl = buildStaticMapUrl;
 exports.fetchStaticMap = fetchStaticMap;
 const errors_js_1 = require("../transport/errors.js");
+const http_js_1 = require("../transport/http.js");
 /**
  * The Accept header this request must send.
  *
@@ -55,6 +56,7 @@ function buildStaticMapUrl(apiUrl, options) {
  * @param apiUrl   Base URL of the Location Service API
  * @param options  Render options; exactly one of center / boundingBox / boundedPositions
  * @param getToken Callback returning the current auth token
+ * @param request  Transport options: `signal` to cancel, `timeoutMs`, `overallTimeoutMs`, `retry`
  *
  * @example
  * const blob = await fetchStaticMap(API_URL, {
@@ -63,19 +65,23 @@ function buildStaticMapUrl(apiUrl, options) {
  * }, getToken)
  * const url = URL.createObjectURL(blob)   // remember to revokeObjectURL
  */
-async function fetchStaticMap(apiUrl, options, getToken) {
-    const response = await fetch(buildStaticMapUrl(apiUrl, options), {
+async function fetchStaticMap(apiUrl, options, getToken, request = {}) {
+    const token = getToken();
+    // The same guard as fetchMapStyle and the server connector: a render is not
+    // worth requesting without a token to send (#37).
+    if (!token) {
+        throw (0, errors_js_1.noTokenAvailable)('getToken() returned nothing, so no static map was requested. Check the token provider has finished initialising.');
+    }
+    // Through the shared transport, so a static map gets the timeout, budget,
+    // cancellation and retry every other call has -- and its failures arrive as
+    // LocationServiceException rather than as a raw TypeError. The API's own
+    // {message, code, requestId} survives, which matters here: the messages are
+    // specific and actionable -- "'width' and 'height' are required", "Only one
+    // of center, bounding-box or bounded-positions may be set".
+    return (0, http_js_1.requestBlob)(buildStaticMapUrl(apiUrl, options), {
         headers: {
-            Authorization: `Bearer ${getToken()}`,
+            Authorization: `Bearer ${token}`,
             Accept: staticMapAccept(options.style),
         },
-    });
-    if (!response.ok) {
-        // Same treatment as fetchMapStyle: the API's {message, code, requestId} is
-        // the useful part, and a bare "failed: 400" throws it away. The messages
-        // here are specific and actionable -- "'width' and 'height' are required",
-        // "Only one of center, bounding-box or bounded-positions may be set".
-        throw (0, errors_js_1.parseErrorResponse)(response.status, response.statusText, await response.text());
-    }
-    return response.blob();
+    }, request);
 }

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

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

package/dist/cjs/server/LocationServiceConnector.js

@@ -9,7 +9,6 @@ const LocationServiceException_js_1 = require("../errors/LocationServiceExceptio
 const endpoints_js_1 = require("../transport/endpoints.js");
 const errors_js_1 = require("../transport/errors.js");
 const http_js_1 = require("../transport/http.js");
-const roundPosition_js_1 = require("../utils/roundPosition.js");
 const tokenClaims_js_1 = require("../utils/tokenClaims.js");
 const getClientConfig_js_1 = require("./getClientConfig.js");
 const log = (0, debug_1.default)('location-client:connector');
@@ -33,6 +32,12 @@ function headerValue(headers, name) {
  * spelling of it survives the merge.
  */
 const SYSTEM_HEADERS = ['origin', 'content-type', 'authorization'];
+/**
+ * What to check when the token source comes up empty. The guard itself is
+ * shared with the map fetches (`noTokenAvailable`); only the advice differs,
+ * and on this path the answer is always the credentials.
+ */
+const NO_TOKEN_ADVICE = 'check clientId/clientSecret configuration';
 /** The caller's headers minus `names`, however they capitalised them. */
 function withoutHeaders(headers, names) {
     if (!headers)
@@ -152,7 +157,7 @@ class LocationServiceConnector {
     }
     /**
      * This application's own configuration, as carried on the access token
-     * (api#65) — bias precision, and the countries it is scoped to.
+     * (api#65) — today, the countries it is scoped to.
      *
      * Provided so an application can SHOW its own settings: populate a country
      * selector with the markets it actually serves, label a settings screen, and
@@ -193,7 +198,7 @@ class LocationServiceConnector {
     async dispatchWithRetry(source, url, cmd, options) {
         const token = await source.get();
         if (!token)
-            throw noTokenAvailable();
+            throw (0, errors_js_1.noTokenAvailable)(NO_TOKEN_ADVICE);
         try {
             return await this.dispatch(url, token, cmd, options);
         }
@@ -204,8 +209,8 @@ class LocationServiceConnector {
             // token. That single comparison covers every source: a fixed `token`
             // string, a caller `getToken` that ignores `forceRefresh`, and a cached
             // token the API has revoked before its `exp` all hand back what we
-            // already sent — and re-sending it would be a second doomed request, and
-            // a second billed one.
+            // already sent — and re-sending it would be a second doomed request for
+            // the same answer.
             const fresh = await source.get(true);
             if (!fresh || fresh === token)
                 throw err;
@@ -214,13 +219,12 @@ class LocationServiceConnector {
         }
     }
     dispatch(url, token, cmd, options) {
-        // The token is resolved before the request is shaped, so the precision this
-        // application is entitled to is available (api#65). Absent claim -> the
-        // 3 dp floor, which is what every application gets until one is configured
-        // otherwise. Recomputed per attempt because a refreshed token may carry
-        // different claims.
-        const { biasDecimals } = (0, tokenClaims_js_1.readAppConfigClaims)(token);
-        const input = (0, roundPosition_js_1.roundPositionFields)(cmd.input, biasDecimals);
+        // The caller's input goes out as the caller wrote it — nothing in the body
+        // is derived from the token any more. `BiasPosition` used to be rounded
+        // here to a grid sized by a token claim, so nearby callers shared a server
+        // cache entry; with no cache the rounding only lowered the precision the
+        // upstream geocoder had to work with, which moves the results rather than
+        // coarsening them (#51).
         // Every system header is set exactly ONCE, and the caller's own spelling of
         // each is dropped first.
         //
@@ -245,7 +249,7 @@ class LocationServiceConnector {
             Authorization: `Bearer ${token}`,
         };
         log('Sending %s request to %s', cmd.constructor?.name, url);
-        return (0, http_js_1.requestJson)(url, { method: 'POST', headers, body: JSON.stringify(input) }, options);
+        return (0, http_js_1.requestJson)(url, { method: 'POST', headers, body: JSON.stringify(cmd.input) }, options);
     }
 }
 exports.LocationServiceConnector = LocationServiceConnector;
@@ -261,10 +265,3 @@ function requireApiUrl(explicit) {
     }
     return apiUrl;
 }
-function noTokenAvailable() {
-    return new LocationServiceException_js_1.LocationServiceException({
-        code: 'InvalidCredentialsException',
-        message: 'No token available — check clientId/clientSecret configuration',
-        details: { source: 'client' },
-    });
-}

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

@@ -14,7 +14,26 @@ export interface ServerAuthConfig {
      */
     forceRefresh?: boolean;
 }
+/**
+ * How many applications one process keeps token providers for.
+ *
+ * A provider holds a URL, a client id, a secret and one cached JWT, so the
+ * ceiling is about memory containment rather than a tuned working set — 64 is
+ * far above what a single-tenant service needs and far below anything worth
+ * worrying about. An agency past it pays a re-mint for the least recently used
+ * application, which is exactly the behaviour this replaced, but only for the
+ * coldest one instead of for every alternation.
+ */
+export declare const MAX_CACHED_PROVIDERS = 64;
 export interface ServerClientConfig extends ClientConfig {
+    /**
+     * Narrowed back to required. `ClientConfig.token` is optional because a
+     * client can be driven by `getToken`/`refreshToken` alone, but this type is
+     * what `getClientConfig` RESOLVES — it either has a token or it threw — and
+     * widening it would push a needless `string | undefined` onto every consumer
+     * that reads `config.token`.
+     */
+    token: string;
     expiresAt?: number;
 }
 /**

package/dist/cjs/server/getClientConfig.js

@@ -3,6 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_CACHED_PROVIDERS = void 0;
 exports.resolveApiUrl = resolveApiUrl;
 exports.serverTokenSource = serverTokenSource;
 exports.getClientConfig = getClientConfig;
@@ -11,9 +12,32 @@ const node_crypto_1 = require("node:crypto");
 const TokenProvider_js_1 = require("../auth/TokenProvider.js");
 const LocationServiceException_js_1 = require("../errors/LocationServiceException.js");
 const log = (0, debug_1.default)('location-client:clientConfig');
-// Singleton instance to prevent race conditions
-let tokenProviderInstance = null;
-let currentConfig = null;
+/**
+ * How many applications one process keeps token providers for.
+ *
+ * A provider holds a URL, a client id, a secret and one cached JWT, so the
+ * ceiling is about memory containment rather than a tuned working set — 64 is
+ * far above what a single-tenant service needs and far below anything worth
+ * worrying about. An agency past it pays a re-mint for the least recently used
+ * application, which is exactly the behaviour this replaced, but only for the
+ * coldest one instead of for every alternation.
+ */
+exports.MAX_CACHED_PROVIDERS = 64;
+/**
+ * One provider per configuration, most-recently-used last.
+ *
+ * This used to be TWO module-level variables holding a single provider, and a
+ * process serving more than one application therefore evicted the cache on
+ * every alternation: A→B→A→B took a full `/auth/token` round trip per call,
+ * each writing a jti row, all against the one shared token-endpoint throttle.
+ * The hit rate under alternating load was 0% (#39). Nothing leaked between
+ * tenants — each caller closes over the provider it asked for — so what this
+ * fixes is availability and cost, not confidentiality.
+ *
+ * A `Map` iterates in insertion order, so re-inserting on a hit makes the first
+ * key the least recently used, and an LRU needs no other bookkeeping.
+ */
+const tokenProviders = new Map();
 function getTokenProvider(apiUrl, clientId, clientSecret) {
     // The SECRET is part of the key. Without it, rotating a client secret while
     // keeping the same clientId left this process reusing a provider built on the
@@ -21,16 +45,26 @@ function getTokenProvider(apiUrl, clientId, clientSecret) {
     // rather than concatenated so the key is never a secret in its own right, and
     // never ends up in a log line (#5).
     const configKey = `${apiUrl}:${clientId}:${(0, node_crypto_1.createHash)('sha256').update(clientSecret).digest('hex').slice(0, 16)}`;
-    // Reuse existing instance if config matches
-    if (tokenProviderInstance && currentConfig === configKey) {
+    const cached = tokenProviders.get(configKey);
+    if (cached) {
         log('[getTokenProvider] Reusing existing TokenProvider instance');
-        return tokenProviderInstance;
+        // Re-insert to mark it most recently used.
+        tokenProviders.delete(configKey);
+        tokenProviders.set(configKey, cached);
+        return cached;
     }
-    // Create new instance if config changed
     log('[getTokenProvider] Creating new TokenProvider instance');
-    tokenProviderInstance = new TokenProvider_js_1.TokenProvider({ apiUrl, clientId, clientSecret });
-    currentConfig = configKey;
-    return tokenProviderInstance;
+    const provider = new TokenProvider_js_1.TokenProvider({ apiUrl, clientId, clientSecret });
+    tokenProviders.set(configKey, provider);
+    if (tokenProviders.size > exports.MAX_CACHED_PROVIDERS) {
+        const leastRecentlyUsed = tokenProviders.keys().next().value;
+        /* c8 ignore next — size > 0 here, so the iterator always yields */
+        if (leastRecentlyUsed !== undefined) {
+            log('[getTokenProvider] Evicting the least recently used TokenProvider');
+            tokenProviders.delete(leastRecentlyUsed);
+        }
+    }
+    return provider;
 }
 /**
  * Where the API lives, from the argument or the environment.