@chaosity/location-client 0.7.0 → 0.9.0

package/dist/maps/mapStyle.js

@@ -1,4 +1,5 @@
-import { parseErrorResponse } from '../transport/errors.js';
+import { noTokenAvailable } from '../transport/errors.js';
+import { requestJson } from '../transport/http.js';
 import { labelsByName, languageExpression } from './mapLanguage.js';
 /**
  * Build a map style descriptor URL for the Location Service API.
@@ -46,38 +47,42 @@ export 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) })
  */
-export async function fetchMapStyle(apiUrl, mapStyle, getToken, options = {}) {
+export 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 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 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 parseErrorResponse(response.status, response.statusText, await response.text(), response.headers);
-    }
-    const style = (await response.json());
+    }, request);
     if (language) {
         applyLanguageToDescriptor(style, language);
     }

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

@@ -1,4 +1,5 @@
-import { parseErrorResponse } from '../transport/errors.js';
+import { noTokenAvailable } from '../transport/errors.js';
+import { requestBlob } from '../transport/http.js';
 /**
  * The Accept header this request must send.
  *
@@ -50,6 +51,7 @@ export 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, {
@@ -58,19 +60,23 @@ export function buildStaticMapUrl(apiUrl, options) {
  * }, getToken)
  * const url = URL.createObjectURL(blob)   // remember to revokeObjectURL
  */
-export async function fetchStaticMap(apiUrl, options, getToken) {
-    const response = await fetch(buildStaticMapUrl(apiUrl, options), {
+export 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 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 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 parseErrorResponse(response.status, response.statusText, await response.text());
-    }
-    return response.blob();
+    }, request);
 }

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

@@ -1,9 +1,8 @@
 import debug from 'debug';
 import { LocationServiceException } from '../errors/LocationServiceException.js';
 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';
 import { resolveApiUrl, serverTokenSource } from './getClientConfig.js';
 const log = debug('location-client:connector');
@@ -27,6 +26,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)
@@ -146,7 +151,7 @@ export 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
@@ -187,7 +192,7 @@ export class LocationServiceConnector {
     async dispatchWithRetry(source, url, cmd, options) {
         const token = await source.get();
         if (!token)
-            throw noTokenAvailable();
+            throw noTokenAvailable(NO_TOKEN_ADVICE);
         try {
             return await this.dispatch(url, token, cmd, options);
         }
@@ -198,8 +203,8 @@ export 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;
@@ -208,13 +213,12 @@ export 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 } = readAppConfigClaims(token);
-        const input = 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.
         //
@@ -239,7 +243,7 @@ export class LocationServiceConnector {
             Authorization: `Bearer ${token}`,
         };
         log('Sending %s request to %s', cmd.constructor?.name, url);
-        return requestJson(url, { method: 'POST', headers, body: JSON.stringify(input) }, options);
+        return requestJson(url, { method: 'POST', headers, body: JSON.stringify(cmd.input) }, options);
     }
 }
 function requireApiUrl(explicit) {
@@ -254,10 +258,3 @@ function requireApiUrl(explicit) {
     }
     return apiUrl;
 }
-function noTokenAvailable() {
-    return new LocationServiceException({
-        code: 'InvalidCredentialsException',
-        message: 'No token available — check clientId/clientSecret configuration',
-        details: { source: 'client' },
-    });
-}

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

@@ -3,9 +3,32 @@ import { createHash } from 'node:crypto';
 import { TokenProvider } from '../auth/TokenProvider.js';
 import { LocationServiceException } from '../errors/LocationServiceException.js';
 const log = debug('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.
+ */
+export const 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
@@ -13,16 +36,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}:${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({ apiUrl, clientId, clientSecret });
-    currentConfig = configKey;
-    return tokenProviderInstance;
+    const provider = new TokenProvider({ apiUrl, clientId, clientSecret });
+    tokenProviders.set(configKey, provider);
+    if (tokenProviders.size > 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.

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

@@ -90,7 +90,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.
@@ -113,3 +115,24 @@ export 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.
+ */
+export function noTokenAvailable(advice) {
+    return new LocationServiceException({
+        code: 'InvalidCredentialsException',
+        message: `No token available — ${advice}`,
+        details: { source: 'client' },
+    });
+}

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

@@ -4,6 +4,24 @@ import { parseErrorResponse, parseRetryAfter } from './errors.js';
 const log = debug('location-client:transport');
 /** Per-attempt timeout. Sits well under the API's own 25 s Lambda ceiling. */
 export 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 const DEFAULT_OVERALL_TIMEOUT_MS = 30000;
 export const DEFAULT_MAX_ATTEMPTS = 3;
 const BACKOFF_BASE_MS = 250;
 const BACKOFF_CAP_MS = 4000;
@@ -40,38 +58,86 @@ export 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.
  */
-export 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 ?? DEFAULT_TIMEOUT_MS;
+    const overallTimeoutMs = options.overallTimeoutMs ?? DEFAULT_OVERALL_TIMEOUT_MS;
     const maxAttempts = options.retry === false
         ? 1
         : (options.retry?.maxAttempts ?? 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({
+            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 = 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 ??
                 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) {
@@ -85,20 +151,48 @@ export 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({
             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.
+ */
+export 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).
+ */
+export function requestBlob(url, init, options = {}) {
+    return request(url, init, options, (response) => response.blob());
+}
 function abortedException(signal) {
     return new LocationServiceException({
         code: 'AbortedException',
@@ -107,6 +201,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({
+        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