@chaosity/location-client 0.10.0 → 0.12.0

package/dist/auth/tokenHold.js

@@ -0,0 +1,109 @@
+import { LocationServiceException } from '../errors/LocationServiceException.js';
+/**
+ * How long a refusal is remembered: a token the API refused, or a token
+ * request `/auth/token` refused (#38).
+ *
+ * A refusal — a 401 or a 403 — is not something asking again can change. A
+ * suspended application is refused on every data route and on `/auth/token`
+ * alike, and nothing used to remember that, so every request a busy server
+ * served paid for a doomed data request and a doomed token request, all
+ * against the application's own token-route throttle.
+ *
+ * Thirty seconds bounds how long an application that has just been made
+ * active again waits for this side to notice: long enough to turn a request
+ * rate into a trickle, short enough to be a pause rather than an outage. It is
+ * also about how long a newly created application is refused while it goes
+ * live, which is the one refusal that clears itself.
+ */
+export const TOKEN_REFUSAL_HOLD_MS = 30000;
+/**
+ * A 401 or a 403: the server refused, and a retry gets the same answer.
+ *
+ * Wider than `isTokenRejected`, which is the 401 a new token can fix. This is
+ * about the token SOURCE: `/auth/token` refusing the credentials (401), or
+ * the application's key not live on its plan (403), and neither changes by
+ * asking again.
+ */
+export function isTokenRefusal(err) {
+    return (err instanceof LocationServiceException &&
+        (err.statusCode === 401 || err.statusCode === 403));
+}
+/**
+ * How long `err` says asking again cannot help, in milliseconds; 0 when it
+ * says nothing, and the next call may ask at once.
+ *
+ * Only the server's own word counts: a refusal, or a `Retry-After`. A network
+ * fault, a timeout or a 500 carries neither, so it is not remembered, and the
+ * next call tries again as it always has — the transport has already retried
+ * it with backoff inside the call that failed.
+ */
+export function holdFor(err) {
+    if (!(err instanceof LocationServiceException))
+        return 0;
+    return Math.max(isTokenRefusal(err) ? TOKEN_REFUSAL_HOLD_MS : 0, err.retryAfterMs ?? 0);
+}
+/**
+ * One remembered failure, re-thrown instead of asking again until it lapses.
+ *
+ * Shared by every place that used to ask again on every call: the server
+ * `TokenProvider` (a refused or throttled token request), and the two send
+ * paths (a token the API refused, and the refresh that could not replace it,
+ * or — in `GeoPlacesClient` — could not supply a first one). A send path
+ * remembers the failure against the token it concerns, because a DIFFERENT
+ * token is a new situation — a background refresh that landed, or a caller's
+ * own source that moved on — and ends the hold at once.
+ *
+ * `askAgain` is the one case where the source may still be asked: the API
+ * refused the token, and the refresh that followed failed with nothing to say
+ * about when to try again — a network fault, or a rejection that lost its
+ * fields crossing a Server Action boundary, as `@chaosity/location-client-react`
+ * delivers one. The token is still refused, so it is not sent again; the
+ * source is asked on the next send, as it always was.
+ */
+export class TokenHold {
+    /** Remember `err` for as long as it says; a failure that says nothing is not remembered. */
+    remember(err, token, { askAgain = false } = {}) {
+        const ms = holdFor(err);
+        if (ms > 0) {
+            this.held = {
+                error: err,
+                until: Date.now() + ms,
+                token,
+                askAgain,
+            };
+        }
+    }
+    /**
+     * The remembered failure while it stands, as a new exception to throw — for
+     * `token`, if one was remembered with it — and whether the source may still
+     * be asked. Anything else ends the hold.
+     */
+    check(token) {
+        const held = this.held;
+        if (!held)
+            return undefined;
+        const remaining = held.until - Date.now();
+        if (remaining <= 0 || (held.token !== undefined && held.token !== token)) {
+            this.held = undefined;
+            return undefined;
+        }
+        const { error, askAgain } = held;
+        return {
+            askAgain,
+            error: new LocationServiceException({
+                code: error.code,
+                message: error.message,
+                statusCode: error.statusCode,
+                requestId: error.requestId,
+                details: error.details,
+                // What is left of a Retry-After, so a caller that schedules on it waits
+                // the right amount. A refusal carries none, and gains none here.
+                retryAfterMs: error.retryAfterMs === undefined ? undefined : remaining,
+                cause: error,
+            }),
+        };
+    }
+    forget() {
+        this.held = undefined;
+    }
+}

package/dist/cjs/adapters/GeoPlaces.js

@@ -50,6 +50,26 @@ function toCarmenFeatures(features) {
         };
     });
 }
+/**
+ * The geocoder's `bbox` — `[minX, minY, maxX, maxY]`, the order Amazon's
+ * `BoundingBox` takes too — or undefined when it has none, or not four
+ * numbers.
+ */
+function boundingBox(bbox) {
+    return bbox?.length === 4 && bbox.every((v) => typeof v === 'number')
+        ? bbox
+        : undefined;
+}
+/**
+ * Whether `[x, y]` lies in `bbox`, edges included. A box whose `minX` is
+ * greater than its `maxX` crosses the antimeridian.
+ */
+function insideBox([x, y], bbox) {
+    const [minX, minY, maxX, maxY] = bbox;
+    if (y < minY || y > maxY)
+        return false;
+    return minX <= maxX ? x >= minX && x <= maxX : x >= minX || x <= maxX;
+}
 class GeoPlaces {
     constructor(client, map, options = {}) {
         this.client = client;
@@ -104,9 +124,16 @@ class GeoPlaces {
         const converted = (0, amazon_location_utilities_datatypes_1.geocodeResponseToFeatureCollection)(response, {
             flattenProperties: true,
         });
+        // Geocode takes no box, so the geocoder's `bbox` is applied here, to what
+        // comes back (#59). It used to be ignored, and a result picked with Enter
+        // could land outside the box the integrator set.
+        const bbox = boundingBox(config.bbox);
+        const features = bbox
+            ? converted.features.filter((f) => insideBox(f.geometry.coordinates, bbox))
+            : converted.features;
         const result = {
             type: 'FeatureCollection',
-            features: toCarmenFeatures(converted.features),
+            features: toCarmenFeatures(features),
         };
         log('forwardGeocode returned %d results', result.features.length);
         return result;
@@ -134,38 +161,47 @@ class GeoPlaces {
     }
     async getSuggestions(config) {
         log('getSuggestions query=%s', config.query);
+        // Suggest takes exactly ONE of BiasPosition, Filter.BoundingBox and
+        // Filter.Circle, and refuses a request with two: 400 "Exactly one of the
+        // following fields must be set". This sent a bias always, and the box
+        // beside it whenever the geocoder carried one, so a `bbox` made every
+        // suggestion fail (#59). The box, when there is one, is the bias.
+        const bbox = boundingBox(config.bbox);
         const center = this.map.getCenter();
-        const biasPosition = config.proximity && config.proximity.length >= 2
-            ? [config.proximity[0], config.proximity[1]]
-            : [center.lng, center.lat];
+        const biasPosition = bbox
+            ? undefined
+            : config.proximity && config.proximity.length >= 2
+                ? [config.proximity[0], config.proximity[1]]
+                : [center.lng, center.lat];
+        const countries = config.countries
+            ? Array.isArray(config.countries)
+                ? config.countries
+                : config.countries.split(',')
+            : undefined;
         const commandInput = {
             QueryText: config.query,
-            BiasPosition: biasPosition,
+            ...(biasPosition ? { BiasPosition: biasPosition } : {}),
             MaxResults: config.limit || 5,
             Language: this.normalizeLanguage(config.language),
             // No AdditionalFeatures (#3 / T19).
             //
             // This used to send `[Core]`, which put every keystroke in the Core
-            // bucket at $0.50/1k. The only thing Core adds to a Suggest response is
-            // `Highlights`, and this adapter reads `Title` and `Place.PlaceId` —
-            // nothing else. Verified against Amazon Location on 2026-08-25:
+            // bucket at $0.50/1k. What Core adds to a Suggest response is
+            // `Highlights` and the place's `Position` (without it,
+            // `suggestResponseToFeatureCollection` finds no feature: measured
+            // 2026-09-29), and this adapter reads neither — only `Title` and
+            // `Place.PlaceId`. Verified against Amazon Location on 2026-08-25:
             //
             //   with [Core] -> bucket Core   keys: Title, ..., Place, Highlights
             //   without     -> bucket Label  keys: Title, ..., Place
             //
             // Same two fields, $0.20/1k instead of $0.50. Suggest fires per
             // keystroke, so it is the highest-volume call the library makes.
-            ...(config.countries || config.bbox
+            ...(bbox || countries
                 ? {
                     Filter: {
-                        ...(config.countries
-                            ? {
-                                IncludeCountries: Array.isArray(config.countries)
-                                    ? config.countries
-                                    : config.countries.split(','),
-                            }
-                            : {}),
-                        ...(config.bbox ? { BoundingBox: config.bbox } : {}),
+                        ...(bbox ? { BoundingBox: bbox } : {}),
+                        ...(countries ? { IncludeCountries: countries } : {}),
                     },
                 }
                 : {}),

package/dist/cjs/auth/TokenProvider.d.ts

@@ -42,6 +42,8 @@ export declare class TokenProvider {
     private cachedToken?;
     private cachedExpiresAt?;
     private tokenPromise?;
+    /** A refusal or a Retry-After from `/auth/token`, until it lapses (#38). */
+    private readonly hold;
     constructor(config: TokenProviderConfig);
     getToken(forceRefresh?: boolean): Promise<TokenResponse>;
     /**

package/dist/cjs/auth/TokenProvider.js

@@ -7,6 +7,7 @@ exports.TokenProvider = void 0;
 const debug_1 = __importDefault(require("debug"));
 const LocationServiceException_js_1 = require("../errors/LocationServiceException.js");
 const http_js_1 = require("../transport/http.js");
+const tokenHold_js_1 = require("./tokenHold.js");
 const tokenRefresh_js_1 = require("./tokenRefresh.js");
 const log = (0, debug_1.default)('location-client:auth');
 /**
@@ -39,6 +40,8 @@ const log = (0, debug_1.default)('location-client:auth');
  */
 class TokenProvider {
     constructor(config) {
+        /** A refusal or a Retry-After from `/auth/token`, until it lapses (#38). */
+        this.hold = new tokenHold_js_1.TokenHold();
         // Runtime check: prevent usage in browser
         if (typeof window !== 'undefined') {
             throw new Error('TokenProvider cannot be used in browser environments. ' +
@@ -60,6 +63,15 @@ class TokenProvider {
                 expiresAt: this.cachedExpiresAt,
             };
         }
+        // The endpoint refused these credentials, or asked us to wait, a moment
+        // ago: answer with that rather than ask again (#38). Forced or not — a
+        // forced refresh asks for a different token, and these credentials will
+        // not get one until the hold lapses.
+        const held = this.hold.check()?.error;
+        if (held) {
+            log('Token request held: %s', held.message);
+            throw held;
+        }
         // If token fetch is already in progress, wait for it
         if (this.tokenPromise) {
             log('Token fetch in progress, waiting for existing request...');
@@ -99,16 +111,32 @@ class TokenProvider {
     async fetchToken() {
         const { clientId, clientSecret, apiUrl } = this.config;
         const credentials = btoa(`${clientId}:${clientSecret}`);
-        const data = await (0, http_js_1.requestJson)(`${apiUrl}/auth/token`, {
-            method: 'POST',
-            headers: {
-                Authorization: `Basic ${credentials}`,
-                'Content-Type': 'application/x-www-form-urlencoded',
-            },
-            body: new URLSearchParams({
-                grant_type: 'client_credentials',
-            }).toString(),
-        }, { retry: { maxAttempts: 3 } });
+        let data;
+        try {
+            data = await (0, http_js_1.requestJson)(`${apiUrl}/auth/token`, {
+                method: 'POST',
+                headers: {
+                    Authorization: `Basic ${credentials}`,
+                    'Content-Type': 'application/x-www-form-urlencoded',
+                },
+                body: new URLSearchParams({
+                    grant_type: 'client_credentials',
+                }).toString(),
+            }, { retry: { maxAttempts: 3 } });
+        }
+        catch (error) {
+            // Remembered, so the next call is answered without a request (#38), and
+            // a Retry-After is honoured across calls rather than only within this
+            // one (#63).
+            this.hold.remember(error);
+            // A refusal is about the credentials, so every token they minted is
+            // refused too — a suspended application's on its next use, a rotated
+            // secret's at once. Never hand the cached one out again. A Retry-After
+            // says nothing about it, and keeps it.
+            if ((0, tokenHold_js_1.isTokenRefusal)(error))
+                this.clearCache();
+            throw error;
+        }
         if (!data.access_token) {
             throw new LocationServiceException_js_1.LocationServiceException({
                 code: 'InvalidCredentialsException',
@@ -116,6 +144,7 @@ class TokenProvider {
                 details: { source: 'client' },
             });
         }
+        this.hold.forget();
         this.cachedToken = data.access_token;
         // The token's own `exp` claim first — it is the only value that cannot
         // disagree with what the API will actually accept. `expires_at` and

package/dist/cjs/auth/tokenHold.d.ts

@@ -0,0 +1,72 @@
+import { LocationServiceException } from '../errors/LocationServiceException.js';
+/**
+ * How long a refusal is remembered: a token the API refused, or a token
+ * request `/auth/token` refused (#38).
+ *
+ * A refusal — a 401 or a 403 — is not something asking again can change. A
+ * suspended application is refused on every data route and on `/auth/token`
+ * alike, and nothing used to remember that, so every request a busy server
+ * served paid for a doomed data request and a doomed token request, all
+ * against the application's own token-route throttle.
+ *
+ * Thirty seconds bounds how long an application that has just been made
+ * active again waits for this side to notice: long enough to turn a request
+ * rate into a trickle, short enough to be a pause rather than an outage. It is
+ * also about how long a newly created application is refused while it goes
+ * live, which is the one refusal that clears itself.
+ */
+export declare const TOKEN_REFUSAL_HOLD_MS = 30000;
+/**
+ * A 401 or a 403: the server refused, and a retry gets the same answer.
+ *
+ * Wider than `isTokenRejected`, which is the 401 a new token can fix. This is
+ * about the token SOURCE: `/auth/token` refusing the credentials (401), or
+ * the application's key not live on its plan (403), and neither changes by
+ * asking again.
+ */
+export declare function isTokenRefusal(err: unknown): boolean;
+/**
+ * How long `err` says asking again cannot help, in milliseconds; 0 when it
+ * says nothing, and the next call may ask at once.
+ *
+ * Only the server's own word counts: a refusal, or a `Retry-After`. A network
+ * fault, a timeout or a 500 carries neither, so it is not remembered, and the
+ * next call tries again as it always has — the transport has already retried
+ * it with backoff inside the call that failed.
+ */
+export declare function holdFor(err: unknown): number;
+/**
+ * One remembered failure, re-thrown instead of asking again until it lapses.
+ *
+ * Shared by every place that used to ask again on every call: the server
+ * `TokenProvider` (a refused or throttled token request), and the two send
+ * paths (a token the API refused, and the refresh that could not replace it,
+ * or — in `GeoPlacesClient` — could not supply a first one). A send path
+ * remembers the failure against the token it concerns, because a DIFFERENT
+ * token is a new situation — a background refresh that landed, or a caller's
+ * own source that moved on — and ends the hold at once.
+ *
+ * `askAgain` is the one case where the source may still be asked: the API
+ * refused the token, and the refresh that followed failed with nothing to say
+ * about when to try again — a network fault, or a rejection that lost its
+ * fields crossing a Server Action boundary, as `@chaosity/location-client-react`
+ * delivers one. The token is still refused, so it is not sent again; the
+ * source is asked on the next send, as it always was.
+ */
+export declare class TokenHold {
+    private held?;
+    /** Remember `err` for as long as it says; a failure that says nothing is not remembered. */
+    remember(err: unknown, token?: string, { askAgain }?: {
+        askAgain?: boolean | undefined;
+    }): void;
+    /**
+     * The remembered failure while it stands, as a new exception to throw — for
+     * `token`, if one was remembered with it — and whether the source may still
+     * be asked. Anything else ends the hold.
+     */
+    check(token?: string): {
+        error: LocationServiceException;
+        askAgain: boolean;
+    } | undefined;
+    forget(): void;
+}

package/dist/cjs/auth/tokenHold.js

@@ -0,0 +1,115 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TokenHold = exports.TOKEN_REFUSAL_HOLD_MS = void 0;
+exports.isTokenRefusal = isTokenRefusal;
+exports.holdFor = holdFor;
+const LocationServiceException_js_1 = require("../errors/LocationServiceException.js");
+/**
+ * How long a refusal is remembered: a token the API refused, or a token
+ * request `/auth/token` refused (#38).
+ *
+ * A refusal — a 401 or a 403 — is not something asking again can change. A
+ * suspended application is refused on every data route and on `/auth/token`
+ * alike, and nothing used to remember that, so every request a busy server
+ * served paid for a doomed data request and a doomed token request, all
+ * against the application's own token-route throttle.
+ *
+ * Thirty seconds bounds how long an application that has just been made
+ * active again waits for this side to notice: long enough to turn a request
+ * rate into a trickle, short enough to be a pause rather than an outage. It is
+ * also about how long a newly created application is refused while it goes
+ * live, which is the one refusal that clears itself.
+ */
+exports.TOKEN_REFUSAL_HOLD_MS = 30000;
+/**
+ * A 401 or a 403: the server refused, and a retry gets the same answer.
+ *
+ * Wider than `isTokenRejected`, which is the 401 a new token can fix. This is
+ * about the token SOURCE: `/auth/token` refusing the credentials (401), or
+ * the application's key not live on its plan (403), and neither changes by
+ * asking again.
+ */
+function isTokenRefusal(err) {
+    return (err instanceof LocationServiceException_js_1.LocationServiceException &&
+        (err.statusCode === 401 || err.statusCode === 403));
+}
+/**
+ * How long `err` says asking again cannot help, in milliseconds; 0 when it
+ * says nothing, and the next call may ask at once.
+ *
+ * Only the server's own word counts: a refusal, or a `Retry-After`. A network
+ * fault, a timeout or a 500 carries neither, so it is not remembered, and the
+ * next call tries again as it always has — the transport has already retried
+ * it with backoff inside the call that failed.
+ */
+function holdFor(err) {
+    if (!(err instanceof LocationServiceException_js_1.LocationServiceException))
+        return 0;
+    return Math.max(isTokenRefusal(err) ? exports.TOKEN_REFUSAL_HOLD_MS : 0, err.retryAfterMs ?? 0);
+}
+/**
+ * One remembered failure, re-thrown instead of asking again until it lapses.
+ *
+ * Shared by every place that used to ask again on every call: the server
+ * `TokenProvider` (a refused or throttled token request), and the two send
+ * paths (a token the API refused, and the refresh that could not replace it,
+ * or — in `GeoPlacesClient` — could not supply a first one). A send path
+ * remembers the failure against the token it concerns, because a DIFFERENT
+ * token is a new situation — a background refresh that landed, or a caller's
+ * own source that moved on — and ends the hold at once.
+ *
+ * `askAgain` is the one case where the source may still be asked: the API
+ * refused the token, and the refresh that followed failed with nothing to say
+ * about when to try again — a network fault, or a rejection that lost its
+ * fields crossing a Server Action boundary, as `@chaosity/location-client-react`
+ * delivers one. The token is still refused, so it is not sent again; the
+ * source is asked on the next send, as it always was.
+ */
+class TokenHold {
+    /** Remember `err` for as long as it says; a failure that says nothing is not remembered. */
+    remember(err, token, { askAgain = false } = {}) {
+        const ms = holdFor(err);
+        if (ms > 0) {
+            this.held = {
+                error: err,
+                until: Date.now() + ms,
+                token,
+                askAgain,
+            };
+        }
+    }
+    /**
+     * The remembered failure while it stands, as a new exception to throw — for
+     * `token`, if one was remembered with it — and whether the source may still
+     * be asked. Anything else ends the hold.
+     */
+    check(token) {
+        const held = this.held;
+        if (!held)
+            return undefined;
+        const remaining = held.until - Date.now();
+        if (remaining <= 0 || (held.token !== undefined && held.token !== token)) {
+            this.held = undefined;
+            return undefined;
+        }
+        const { error, askAgain } = held;
+        return {
+            askAgain,
+            error: new LocationServiceException_js_1.LocationServiceException({
+                code: error.code,
+                message: error.message,
+                statusCode: error.statusCode,
+                requestId: error.requestId,
+                details: error.details,
+                // What is left of a Retry-After, so a caller that schedules on it waits
+                // the right amount. A refusal carries none, and gains none here.
+                retryAfterMs: error.retryAfterMs === undefined ? undefined : remaining,
+                cause: error,
+            }),
+        };
+    }
+    forget() {
+        this.held = undefined;
+    }
+}
+exports.TokenHold = TokenHold;

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

@@ -6,13 +6,17 @@ export type SendOptions = RequestOptions;
 /**
  * GeoPlacesClient — AWS Location Service compatible client with custom auth.
  *
- * Uses AWS SDK command classes but replaces SigV4 with a Bearer token. All
- * request and response types are identical to AWS Location Service.
+ * Uses AWS SDK command classes but replaces SigV4 with a Bearer token. The
+ * request and response types are the AWS SDK's, except that the Places
+ * commands take neither `IntendedUse` nor `Key` (#40), and `VerifyAddressCommand`
+ * is this package's own (#54).
  *
  * Pass `getToken` in config for live refresh without recreating the client.
  */
 export declare class GeoPlacesClient {
     private clientConfig;
+    /** A token the API refused, and why, until the hold lapses (#38). */
+    private readonly refused;
     readonly config: {
         serviceId: string;
     };

package/dist/cjs/client/GeoPlacesClient.js

@@ -5,22 +5,32 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GeoPlacesClient = void 0;
 const debug_1 = __importDefault(require("debug"));
+const tokenHold_js_1 = require("../auth/tokenHold.js");
 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 tokenClaims_js_1 = require("../utils/tokenClaims.js");
 const commands_js_1 = require("./commands.js");
 const log = (0, debug_1.default)('location-client:api');
+/**
+ * What a hold is kept against when there was no token in hand to key it to.
+ * `ensureToken` treats an empty token as none, so no real token is this.
+ */
+const NO_TOKEN = '';
 /**
  * GeoPlacesClient — AWS Location Service compatible client with custom auth.
  *
- * Uses AWS SDK command classes but replaces SigV4 with a Bearer token. All
- * request and response types are identical to AWS Location Service.
+ * Uses AWS SDK command classes but replaces SigV4 with a Bearer token. The
+ * request and response types are the AWS SDK's, except that the Places
+ * commands take neither `IntendedUse` nor `Key` (#40), and `VerifyAddressCommand`
+ * is this package's own (#54).
  *
  * Pass `getToken` in config for live refresh without recreating the client.
  */
 class GeoPlacesClient {
     constructor(config) {
+        /** A token the API refused, and why, until the hold lapses (#38). */
+        this.refused = new tokenHold_js_1.TokenHold();
         this.clientConfig = config;
         this.config = { serviceId: 'Geo Places' };
     }
@@ -54,12 +64,28 @@ class GeoPlacesClient {
      * 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
+        // Truthiness, 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 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?.());
+        const inHand = this.currentToken();
+        if (inHand)
+            return inHand;
+        // `refreshToken` refused a moment ago, and there is still nothing in hand:
+        // answer with that rather than ask it again on every send (#38). The hold
+        // is kept against "no token", so one arriving from `getToken` ends it.
+        const held = this.refused.check(NO_TOKEN)?.error;
+        if (held)
+            throw held;
+        let token;
+        try {
+            token = await this.clientConfig.refreshToken?.();
+        }
+        catch (refusal) {
+            this.refused.remember(refusal, NO_TOKEN);
+            throw refusal;
+        }
         if (!token) {
             throw (0, errors_js_1.noTokenAvailable)('the client has no token yet. Pass `token`, or a `getToken`/`refreshToken` that has one.');
         }
@@ -81,25 +107,61 @@ class GeoPlacesClient {
         // something it already knew. Ask the refresh source instead, and refuse if
         // there is still nothing.
         const token = await this.ensureToken();
+        // This token was refused a moment ago and nothing has replaced it: answer
+        // with that refusal rather than send it, and ask `refreshToken`, again
+        // (#38). A different token from `getToken` ends the hold. When the refresh
+        // that followed said nothing about when to ask again, it is asked now —
+        // but the refused token is still not sent.
+        const held = this.refused.check(token);
+        if (held && !held.askAgain)
+            throw held.error;
+        let rejected = held?.error;
+        if (!held) {
+            try {
+                return await this.dispatch(url, token, cmd, options);
+            }
+            catch (err) {
+                if (!(0, errors_js_1.isTokenRejected)(err))
+                    throw err;
+                rejected = err;
+            }
+        }
+        // One shot. `refreshToken` is the only way to actually obtain a new token
+        // here — `getToken` is synchronous and returns the one already in hand —
+        // but it is re-read as a fallback because a provider that refreshes in the
+        // background may have landed a new one while this request was in flight.
+        let fresh;
         try {
-            return await this.dispatch(url, token, cmd, options);
+            fresh = (await this.clientConfig.refreshToken?.()) ?? this.currentToken();
+        }
+        catch (refusal) {
+            // A suspended application's token route refuses it as its data routes
+            // refuse its token. Without this, every send asked again. A refusal that
+            // says nothing — a network fault, or a Server Action's error without its
+            // fields — leaves the source to be asked again, but not the token sent.
+            if ((0, tokenHold_js_1.holdFor)(refusal) > 0)
+                this.refused.remember(refusal, token);
+            // Only when no hold stands: one already standing keeps its own end, so
+            // the refused token is tried again once per hold rather than never.
+            else if (!held)
+                this.refused.remember(rejected, token, { askAgain: true });
+            throw refusal;
+        }
+        // Nothing new to send. Repeating the request would fail identically — a
+        // second round trip for the same 401.
+        if (!fresh || fresh === token) {
+            this.refused.remember(rejected, token);
+            throw rejected;
         }
-        catch (err) {
-            if (!(0, errors_js_1.isTokenRejected)(err))
-                throw err;
-            // One shot. `refreshToken` is the only way to actually obtain a new
-            // token here — `getToken` is synchronous and returns the one already in
-            // hand — but it is re-read as a fallback because a provider that
-            // 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 — 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);
+        log('401 — retrying %s once with a refreshed token', cmd.constructor?.name);
+        try {
             return await this.dispatch(url, fresh, cmd, options);
         }
+        catch (again) {
+            if ((0, errors_js_1.isTokenRejected)(again))
+                this.refused.remember(again, fresh);
+            throw again;
+        }
     }
     /**
      * Verify a PlaceId: `send(new VerifyAddressCommand({ PlaceId }))`, typed