@chaosity/location-client 0.7.0 → 0.9.0

package/dist/cjs/transport/errors.d.ts

@@ -19,7 +19,9 @@ export declare function parseErrorResponse(status: number, statusText: string, b
  * expired, and API Gateway turns that into a 401. Its other refusals — no
  * domain configured for the application, an Origin the application does not
  * allow — are a Deny policy or a service 403, and a fresh token changes
- * neither. Retrying those would send, and bill, the same doomed request twice.
+ * neither. Retrying those sends the same doomed request twice, for the same
+ * answer — which is the whole cost, since the service meters successful
+ * requests and no error response is billed whatever its status.
  *
  * Shared by both send paths so the browser client and the server connector
  * cannot come to different conclusions about the same response.
@@ -30,3 +32,18 @@ export declare function isTokenRejected(err: unknown): boolean;
  * API sends the first; a date is handled so a proxy or gateway cannot surprise us.
  */
 export declare function parseRetryAfter(value: string | null | undefined): number | undefined;
+/**
+ * No token to send, so nothing is sent.
+ *
+ * Every send path resolves a token before it builds a request, and every one of
+ * them can come up empty — a provider that has not initialised, a server action
+ * that returned nothing, credentials that are not configured. Sending anyway
+ * puts the literal string `Bearer undefined` on the wire, which the API answers
+ * with a 401 the caller then has to work backwards from — a whole round trip,
+ * paid for out of the caller's own deadline, to be told what it already knew.
+ * The map fetches did exactly that until #37.
+ *
+ * `advice` says what to check, because that differs by path: a server connector
+ * wants its client credentials looked at, a browser map wants its token source.
+ */
+export declare function noTokenAvailable(advice: string): LocationServiceException;

package/dist/cjs/transport/errors.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseErrorResponse = parseErrorResponse;
 exports.isTokenRejected = isTokenRejected;
 exports.parseRetryAfter = parseRetryAfter;
+exports.noTokenAvailable = noTokenAvailable;
 const LocationServiceException_js_1 = require("../errors/LocationServiceException.js");
 /**
  * Turn a non-2xx response into a LocationServiceException.
@@ -95,7 +96,9 @@ function statusCode(status) {
  * expired, and API Gateway turns that into a 401. Its other refusals — no
  * domain configured for the application, an Origin the application does not
  * allow — are a Deny policy or a service 403, and a fresh token changes
- * neither. Retrying those would send, and bill, the same doomed request twice.
+ * neither. Retrying those sends the same doomed request twice, for the same
+ * answer — which is the whole cost, since the service meters successful
+ * requests and no error response is billed whatever its status.
  *
  * Shared by both send paths so the browser client and the server connector
  * cannot come to different conclusions about the same response.
@@ -118,3 +121,24 @@ function parseRetryAfter(value) {
         return Math.max(0, date - Date.now());
     return undefined;
 }
+/**
+ * No token to send, so nothing is sent.
+ *
+ * Every send path resolves a token before it builds a request, and every one of
+ * them can come up empty — a provider that has not initialised, a server action
+ * that returned nothing, credentials that are not configured. Sending anyway
+ * puts the literal string `Bearer undefined` on the wire, which the API answers
+ * with a 401 the caller then has to work backwards from — a whole round trip,
+ * paid for out of the caller's own deadline, to be told what it already knew.
+ * The map fetches did exactly that until #37.
+ *
+ * `advice` says what to check, because that differs by path: a server connector
+ * wants its client credentials looked at, a browser map wants its token source.
+ */
+function noTokenAvailable(advice) {
+    return new LocationServiceException_js_1.LocationServiceException({
+        code: 'InvalidCredentialsException',
+        message: `No token available — ${advice}`,
+        details: { source: 'client' },
+    });
+}

package/dist/cjs/transport/http.d.ts

@@ -1,11 +1,38 @@
 /** Per-attempt timeout. Sits well under the API's own 25 s Lambda ceiling. */
 export declare const DEFAULT_TIMEOUT_MS = 10000;
+/**
+ * Ceiling for the WHOLE call — every attempt plus every wait between them.
+ *
+ * `timeoutMs` bounds an attempt, not a call, and the gap between those two is
+ * where the caller's own deadline disappears. The API answers a spent quota
+ * with `Retry-After: 60`, which the retry loop honoured literally: two waits of
+ * a minute each, so one call could sit for ~120 s — past any Lambda budget,
+ * past any HTTP gateway, and until now uncancellable (#37).
+ *
+ * 30 s is picked to sit just under the old worst case: three default attempts
+ * that all time out, plus their backoff, came to ~30.75 s. The overlap is not
+ * quite nothing — when both earlier attempts burn their full 10 s, the third is
+ * clamped to the ~9.25 s that remain, so a response arriving in its final
+ * ~0.75 s used to succeed and now times out. That window is why this ships in a
+ * MINOR rather than a patch. What it buys is that no call can be made to sit
+ * out a retry hint longer than the caller has.
+ */
+export declare const DEFAULT_OVERALL_TIMEOUT_MS = 30000;
 export declare const DEFAULT_MAX_ATTEMPTS = 3;
 export interface RequestOptions {
     /** Caller cancellation. Aborting rejects with code `AbortedException`. */
     signal?: AbortSignal;
     /** Per ATTEMPT, not for the whole call. Default 10 s. */
     timeoutMs?: number;
+    /**
+     * The whole call — attempts and the waits between them. Default 30 s.
+     *
+     * No attempt is given more than what is left of it, and a retry that would
+     * have to wait longer than what is left is not made at all: the API's own
+     * error comes back instead, `retryAfterMs` intact, so the caller can decide
+     * whether to queue the work or drop it.
+     */
+    overallTimeoutMs?: number;
     /** `false` disables retries entirely. Default 3 attempts = 2 retries. */
     retry?: false | {
         maxAttempts?: number;
@@ -22,3 +49,12 @@ export declare function backoffMs(attempt: number, random?: () => number): numbe
  * `details.source = 'client'` so it is distinguishable from the API's own 504.
  */
 export declare function requestJson<T>(url: string, init: RequestInit, options?: RequestOptions): Promise<T>;
+/**
+ * One request answered as a Blob — the static map path.
+ *
+ * Exists so the two map fetches are not the only calls in the package without
+ * a timeout, a retry or a signal: they used their own bare `fetch`, so a
+ * network fault there escaped as a raw `TypeError` while the identical fault on
+ * any other call arrived as `NetworkException` (#37).
+ */
+export declare function requestBlob(url: string, init: RequestInit, options?: RequestOptions): Promise<Blob>;

package/dist/cjs/transport/http.js

@@ -3,15 +3,34 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_MAX_ATTEMPTS = exports.DEFAULT_TIMEOUT_MS = void 0;
+exports.DEFAULT_MAX_ATTEMPTS = exports.DEFAULT_OVERALL_TIMEOUT_MS = exports.DEFAULT_TIMEOUT_MS = void 0;
 exports.backoffMs = backoffMs;
 exports.requestJson = requestJson;
+exports.requestBlob = requestBlob;
 const debug_1 = __importDefault(require("debug"));
 const LocationServiceException_js_1 = require("../errors/LocationServiceException.js");
 const errors_js_1 = require("./errors.js");
 const log = (0, debug_1.default)('location-client:transport');
 /** Per-attempt timeout. Sits well under the API's own 25 s Lambda ceiling. */
 exports.DEFAULT_TIMEOUT_MS = 10000;
+/**
+ * Ceiling for the WHOLE call — every attempt plus every wait between them.
+ *
+ * `timeoutMs` bounds an attempt, not a call, and the gap between those two is
+ * where the caller's own deadline disappears. The API answers a spent quota
+ * with `Retry-After: 60`, which the retry loop honoured literally: two waits of
+ * a minute each, so one call could sit for ~120 s — past any Lambda budget,
+ * past any HTTP gateway, and until now uncancellable (#37).
+ *
+ * 30 s is picked to sit just under the old worst case: three default attempts
+ * that all time out, plus their backoff, came to ~30.75 s. The overlap is not
+ * quite nothing — when both earlier attempts burn their full 10 s, the third is
+ * clamped to the ~9.25 s that remain, so a response arriving in its final
+ * ~0.75 s used to succeed and now times out. That window is why this ships in a
+ * MINOR rather than a patch. What it buys is that no call can be made to sit
+ * out a retry hint longer than the caller has.
+ */
+exports.DEFAULT_OVERALL_TIMEOUT_MS = 30000;
 exports.DEFAULT_MAX_ATTEMPTS = 3;
 const BACKOFF_BASE_MS = 250;
 const BACKOFF_CAP_MS = 4000;
@@ -48,38 +67,86 @@ function backoffMs(attempt, random = Math.random) {
     const ceiling = Math.min(BACKOFF_CAP_MS, BACKOFF_BASE_MS * 2 ** attempt);
     return Math.floor(random() * ceiling);
 }
-const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 /**
- * One JSON request, with timeout, cancellation and retry.
+ * Sleep, unless the caller aborts first.
  *
- * Every failure leaves as a LocationServiceException — a fetch rejection
- * becomes `NetworkException` with the original as `cause`, an abort becomes
- * `AbortedException`, a timeout becomes `TimeoutException` with
- * `details.source = 'client'` so it is distinguishable from the API's own 504.
+ * The timer used to be uncancellable, so an `abort()` during backoff was
+ * ignored until it elapsed — up to a whole `Retry-After` — and the loop only
+ * noticed at the top of the next attempt (#37). Resolving early is all that is
+ * needed: the loop's own pre-attempt check is what raises `AbortedException`,
+ * so exactly one place decides what an abort means.
  */
-async function requestJson(url, init, options = {}) {
+function sleep(ms, signal) {
+    if (ms <= 0 || signal?.aborted)
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        const done = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', done);
+            resolve();
+        };
+        const timer = setTimeout(done, ms);
+        signal?.addEventListener('abort', done, { once: true });
+    });
+}
+/**
+ * One request, with timeout, cancellation and retry.
+ *
+ * The body is read INSIDE the attempt loop deliberately: a truncated or
+ * malformed body is a failed attempt like any other and earns the same
+ * wrapping and the same retry as a dropped socket. Handing the `Response` back
+ * for the caller to read would move that outside the loop, where a bare
+ * `SyntaxError` escapes as itself.
+ */
+async function request(url, init, options, read) {
     const timeoutMs = options.timeoutMs ?? exports.DEFAULT_TIMEOUT_MS;
+    const overallTimeoutMs = options.overallTimeoutMs ?? exports.DEFAULT_OVERALL_TIMEOUT_MS;
     const maxAttempts = options.retry === false
         ? 1
         : (options.retry?.maxAttempts ?? exports.DEFAULT_MAX_ATTEMPTS);
+    // A request budget of zero attempts is a caller mistake, not a policy. It
+    // used to fall straight through the loop and raise `InternalException` for a
+    // request that was never made — an error about our own internals, for their
+    // typo (#37).
+    if (!Number.isInteger(maxAttempts) || maxAttempts < 1) {
+        throw new LocationServiceException_js_1.LocationServiceException({
+            code: 'ValidationException',
+            message: `retry.maxAttempts must be a whole number of at least 1; received ${maxAttempts}`,
+            details: { source: 'client' },
+        });
+    }
+    const deadline = Date.now() + overallTimeoutMs;
     let lastError;
     for (let attempt = 0; attempt < maxAttempts; attempt++) {
         // Checked before every attempt: a signal aborted during backoff must not fire one more.
         if (options.signal?.aborted)
             throw abortedException(options.signal);
-        const { signal, cleanup } = attemptSignal(options.signal, timeoutMs);
+        const budget = deadline - Date.now();
+        if (budget <= 0)
+            throw lastError ?? overallTimeoutException(overallTimeoutMs);
+        // Never longer than what is left of the call, so the per-attempt timeout
+        // cannot overrun the budget it sits inside.
+        const { signal, cleanup } = attemptSignal(options.signal, Math.min(timeoutMs, budget));
         try {
             const response = await fetch(url, { ...init, signal });
             if (response.ok)
-                return (await response.json());
+                return await read(response);
             const error = (0, errors_js_1.parseErrorResponse)(response.status, response.statusText, await response.text(), response.headers);
             lastError = error;
             if (!error.isRetryable || attempt === maxAttempts - 1)
                 throw error;
-            log('attempt %d failed (%s), retrying', attempt + 1, error.code);
-            await sleep(error.retryAfterMs ??
+            const wait = error.retryAfterMs ??
                 (0, errors_js_1.parseRetryAfter)(response.headers.get('retry-after')) ??
-                backoffMs(attempt));
+                backoffMs(attempt);
+            // Sitting out a 60 s `Retry-After` inside a 30 s budget only delivers the
+            // same failure after the caller has already given up. Stop now and hand
+            // back what the API said, `retryAfterMs` and all.
+            if (wait >= deadline - Date.now()) {
+                log('not retrying: a %d ms wait outlasts the remaining budget', wait);
+                break;
+            }
+            log('attempt %d failed (%s), retrying', attempt + 1, error.code);
+            await sleep(wait, options.signal);
         }
         catch (err) {
             if (err instanceof LocationServiceException_js_1.LocationServiceException) {
@@ -93,20 +160,48 @@ async function requestJson(url, init, options = {}) {
             lastError = wrapped;
             if (!wrapped.isRetryable || attempt === maxAttempts - 1)
                 throw wrapped;
+            const wait = backoffMs(attempt);
+            if (wait >= deadline - Date.now()) {
+                log('not retrying: a %d ms wait outlasts the remaining budget', wait);
+                break;
+            }
             log('attempt %d failed (%s), retrying', attempt + 1, wrapped.code);
-            await sleep(backoffMs(attempt));
+            await sleep(wait, options.signal);
         }
         finally {
             cleanup();
         }
     }
-    /* c8 ignore next */
+    // Reached when the budget ran out before another attempt could be made, so
+    // `lastError` is the API's own answer and is the useful thing to throw.
     throw (lastError ??
         new LocationServiceException_js_1.LocationServiceException({
             code: 'InternalException',
             message: 'Request failed',
         }));
 }
+/**
+ * One JSON request, with timeout, cancellation and retry.
+ *
+ * Every failure leaves as a LocationServiceException — a fetch rejection
+ * becomes `NetworkException` with the original as `cause`, an abort becomes
+ * `AbortedException`, a timeout becomes `TimeoutException` with
+ * `details.source = 'client'` so it is distinguishable from the API's own 504.
+ */
+function requestJson(url, init, options = {}) {
+    return request(url, init, options, (response) => response.json());
+}
+/**
+ * One request answered as a Blob — the static map path.
+ *
+ * Exists so the two map fetches are not the only calls in the package without
+ * a timeout, a retry or a signal: they used their own bare `fetch`, so a
+ * network fault there escaped as a raw `TypeError` while the identical fault on
+ * any other call arrived as `NetworkException` (#37).
+ */
+function requestBlob(url, init, options = {}) {
+    return request(url, init, options, (response) => response.blob());
+}
 function abortedException(signal) {
     return new LocationServiceException_js_1.LocationServiceException({
         code: 'AbortedException',
@@ -115,6 +210,14 @@ function abortedException(signal) {
         cause: signal?.reason,
     });
 }
+/** The call's own budget elapsed, rather than one attempt's timeout. */
+function overallTimeoutException(overallTimeoutMs) {
+    return new LocationServiceException_js_1.LocationServiceException({
+        code: 'TimeoutException',
+        message: `Request exceeded its overall timeout of ${overallTimeoutMs} ms`,
+        details: { source: 'client' },
+    });
+}
 /**
  * fetch rejects with a raw `TypeError` for a network fault and a `DOMException`
  * named AbortError for both cancellation and timeout — indistinguishable from

package/dist/cjs/types/index.d.ts

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

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

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

package/dist/cjs/utils/tokenClaims.js

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

package/dist/client/GeoPlacesClient.d.ts

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

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

package/dist/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/index.js

@@ -1,7 +1,7 @@
 // Client (Custom - uses our auth instead of AWS SigV4)
 export { GeoPlacesClient } from './client/GeoPlacesClient.js';
-// Transport options — cancellation, per-attempt timeout, retry policy
-export { DEFAULT_MAX_ATTEMPTS, DEFAULT_TIMEOUT_MS } from './transport/http.js';
+// Transport options — cancellation, per-attempt timeout, overall budget, retry
+export { DEFAULT_MAX_ATTEMPTS, DEFAULT_OVERALL_TIMEOUT_MS, DEFAULT_TIMEOUT_MS, } from './transport/http.js';
 // Token refresh policy — shared by the server provider and the React provider
 export { TOKEN_REFRESH_BUFFER_SECONDS, readTokenExpiry, } from './auth/tokenRefresh.js';
 // Errors

package/dist/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>;