@chaosity/location-client 0.10.0 → 0.12.0

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

@@ -125,9 +125,8 @@ export interface VerifyAddressCommandInput {
  * Japan, which may not be stored at all. Every other Places result is for
  * display.
  *
- * Keep the PlaceId you sent beside it. The answer's own `PlaceId` can differ,
- * and for a unit it does: the service fails that one on every Places route,
- * while the one you sent verifies again.
+ * Its `PlaceId` is the one sent, for a unit as for a building, so a stored
+ * verification can be verified, or looked up, again by its own `PlaceId`.
  */
 export type VerifyAddressResponse = Omit<GetPlaceResponse, 'PricingBucket'> & {
     /**

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

@@ -12,9 +12,36 @@
  * caller hears of it; there is no check to make beforehand.
  */
 export declare const FEATURE_NOT_ENTITLED = "FeatureNotEntitledException";
+/**
+ * Every `code` the API sends (#38): its error contract, published at
+ * https://docs.chaosity.cloud/api/errors, plus the Amazon Location exception
+ * names it passes through from upstream.
+ *
+ * A few are worth knowing apart. `RateLimitExceededException` is the
+ * application's own throttle; `ThrottlingException` is Amazon Location
+ * throttling the service; `IpRateLimitExceededException` is the per-address
+ * limit in front of `/auth/token`. `ApplicationNotActiveException` (403) is an
+ * application that is new, suspended or off its plan.
+ * `TokenExpiredException` is in the contract but never sent: an expired token
+ * arrives as `UnauthorizedException`.
+ */
+export declare const API_ERROR_CODES: readonly ["AccessDeniedException", "ApplicationNotActiveException", "ClientException", "FeatureNotEntitledException", "ForbiddenException", "InternalException", "InternalServerException", "InvalidCredentialsException", "IpRateLimitExceededException", "NotAcceptableException", "NotFoundException", "OriginNotAllowedException", "RateLimitExceededException", "ResourceNotFoundException", "ServiceUnavailableException", "ThrottlingException", "TimeoutException", "TokenExpiredException", "UnauthorizedException", "UpstreamException", "ValidationException"];
+/**
+ * The codes only this package raises, for failures that never reached the
+ * API. It raises some of the API's codes too — `TimeoutException` for its own
+ * timeout, `InvalidCredentialsException` for a missing token — and those are
+ * in the list above.
+ */
+export declare const CLIENT_ERROR_CODES: readonly ["AbortedException", "NetworkException", "ServiceException", "UnknownCommandException"];
+export declare const LOCATION_SERVICE_ERROR_CODES: readonly ["AccessDeniedException", "ApplicationNotActiveException", "ClientException", "FeatureNotEntitledException", "ForbiddenException", "InternalException", "InternalServerException", "InvalidCredentialsException", "IpRateLimitExceededException", "NotAcceptableException", "NotFoundException", "OriginNotAllowedException", "RateLimitExceededException", "ResourceNotFoundException", "ServiceUnavailableException", "ThrottlingException", "TimeoutException", "TokenExpiredException", "UnauthorizedException", "UpstreamException", "ValidationException", "AbortedException", "NetworkException", "ServiceException", "UnknownCommandException"];
+/**
+ * A `LocationServiceException`'s `code`: one of these, or a code the API adds
+ * after this release, which arrives all the same.
+ */
+export type LocationServiceErrorCode = (typeof LOCATION_SERVICE_ERROR_CODES)[number];
 export interface LocationServiceExceptionOptions {
     message: string;
-    code: string;
+    code: LocationServiceErrorCode | (string & {});
     /** Absent for failures that never reached the server: network, timeout, abort. */
     statusCode?: number;
     requestId?: string;
@@ -32,7 +59,8 @@ export interface LocationServiceExceptionOptions {
  * rather than sniffing at `TypeError` vs `DOMException` vs a bare `Error`.
  */
 export declare class LocationServiceException extends Error {
-    readonly code: string;
+    /** See `LocationServiceErrorCode`: typed, and open to a code added later. */
+    readonly code: LocationServiceErrorCode | (string & {});
     readonly statusCode?: number;
     readonly requestId?: string;
     readonly details?: Record<string, unknown>;

package/dist/cjs/errors/LocationServiceException.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LocationServiceException = exports.FEATURE_NOT_ENTITLED = void 0;
+exports.LocationServiceException = exports.LOCATION_SERVICE_ERROR_CODES = exports.CLIENT_ERROR_CODES = exports.API_ERROR_CODES = exports.FEATURE_NOT_ENTITLED = void 0;
 /**
  * The code of a 403 for an option the application's plan does not include
  * (#55): a map feature such as `satellite` or `terrain`, or rich place data.
@@ -15,6 +15,58 @@ exports.LocationServiceException = exports.FEATURE_NOT_ENTITLED = void 0;
  * caller hears of it; there is no check to make beforehand.
  */
 exports.FEATURE_NOT_ENTITLED = 'FeatureNotEntitledException';
+/**
+ * Every `code` the API sends (#38): its error contract, published at
+ * https://docs.chaosity.cloud/api/errors, plus the Amazon Location exception
+ * names it passes through from upstream.
+ *
+ * A few are worth knowing apart. `RateLimitExceededException` is the
+ * application's own throttle; `ThrottlingException` is Amazon Location
+ * throttling the service; `IpRateLimitExceededException` is the per-address
+ * limit in front of `/auth/token`. `ApplicationNotActiveException` (403) is an
+ * application that is new, suspended or off its plan.
+ * `TokenExpiredException` is in the contract but never sent: an expired token
+ * arrives as `UnauthorizedException`.
+ */
+exports.API_ERROR_CODES = [
+    'AccessDeniedException',
+    'ApplicationNotActiveException',
+    'ClientException',
+    'FeatureNotEntitledException',
+    'ForbiddenException',
+    'InternalException',
+    'InternalServerException',
+    'InvalidCredentialsException',
+    'IpRateLimitExceededException',
+    'NotAcceptableException',
+    'NotFoundException',
+    'OriginNotAllowedException',
+    'RateLimitExceededException',
+    'ResourceNotFoundException',
+    'ServiceUnavailableException',
+    'ThrottlingException',
+    'TimeoutException',
+    'TokenExpiredException',
+    'UnauthorizedException',
+    'UpstreamException',
+    'ValidationException',
+];
+/**
+ * The codes only this package raises, for failures that never reached the
+ * API. It raises some of the API's codes too — `TimeoutException` for its own
+ * timeout, `InvalidCredentialsException` for a missing token — and those are
+ * in the list above.
+ */
+exports.CLIENT_ERROR_CODES = [
+    'AbortedException',
+    'NetworkException',
+    'ServiceException',
+    'UnknownCommandException',
+];
+exports.LOCATION_SERVICE_ERROR_CODES = [
+    ...exports.API_ERROR_CODES,
+    ...exports.CLIENT_ERROR_CODES,
+];
 /**
  * The single error type this package throws.
  *

package/dist/cjs/index.d.ts

@@ -4,7 +4,7 @@ export { DEFAULT_MAX_ATTEMPTS, DEFAULT_OVERALL_TIMEOUT_MS, DEFAULT_TIMEOUT_MS, }
 export type { RequestOptions } from './transport/http.js';
 export { TOKEN_REFRESH_BUFFER_SECONDS, readTokenExpiry, } from './auth/tokenRefresh.js';
 export { FEATURE_NOT_ENTITLED, LocationServiceException, } from './errors/LocationServiceException.js';
-export type { LocationServiceExceptionOptions } from './errors/LocationServiceException.js';
+export type { LocationServiceErrorCode, LocationServiceExceptionOptions, } from './errors/LocationServiceException.js';
 export * from '@aws-sdk/client-geo-places';
 export { AutocompleteCommand, GeocodeCommand, GetPlaceCommand, ReverseGeocodeCommand, SearchNearbyCommand, SearchTextCommand, SuggestCommand, VerifyAddressCommand, } from './client/commands.js';
 export type { AutocompleteCommandInput, AutocompleteRequest, GeocodeCommandInput, GeocodeRequest, GetPlaceCommandInput, GetPlaceRequest, NeverForwarded, ReverseGeocodeCommandInput, ReverseGeocodeRequest, SearchNearbyCommandInput, SearchNearbyRequest, SearchTextCommandInput, SearchTextRequest, SuggestCommandInput, SuggestRequest, VerifyAddressCommandInput, VerifyAddressResponse, } from './client/commands.js';

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

@@ -70,6 +70,8 @@ export declare class LocationServiceConnector {
     private readonly config;
     private tokenSource?;
     private readonly origin?;
+    /** A token the API refused, and why, until the hold lapses (#38). */
+    private readonly refused;
     readonly serviceId: string;
     constructor(config?: ConnectorConfig);
     /**

package/dist/cjs/server/LocationServiceConnector.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.LocationServiceConnector = void 0;
 const debug_1 = __importDefault(require("debug"));
+const tokenHold_js_1 = require("../auth/tokenHold.js");
 const commands_js_1 = require("../client/commands.js");
 const LocationServiceException_js_1 = require("../errors/LocationServiceException.js");
 const endpoints_js_1 = require("../transport/endpoints.js");
@@ -106,6 +107,8 @@ function explainMissingOrigin(err, sentOrigin) {
  */
 class LocationServiceConnector {
     constructor(config = {}) {
+        /** A token the API refused, and why, until the hold lapses (#38). */
+        this.refused = new tokenHold_js_1.TokenHold();
         this.serviceId = 'Geo Places';
         this.config = config;
         // `||`, not `??`, to match the other four env-completed fields: an empty
@@ -219,24 +222,60 @@ class LocationServiceConnector {
         const token = await source.get();
         if (!token)
             throw (0, errors_js_1.noTokenAvailable)(NO_TOKEN_ADVICE);
+        // This token was refused a moment ago and nothing has replaced it: answer
+        // with that refusal rather than send it, and force the source, again (#38).
+        // A different token from the source 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 retry, and only when the replacement is genuinely a different 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 for the same answer.
+        let fresh;
         try {
-            return await this.dispatch(url, token, cmd, options);
+            fresh = await source.get(true);
         }
-        catch (err) {
-            if (!(0, errors_js_1.isTokenRejected)(err))
-                throw err;
-            // One retry, and only when the replacement is genuinely a different
-            // 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 for
-            // the same answer.
-            const fresh = await source.get(true);
-            if (!fresh || fresh === token)
-                throw err;
-            log('401 on a token the API no longer accepts — retrying once, refreshed');
+        catch (refusal) {
+            // A suspended application's /auth/token refuses it as its data routes
+            // refuse its token. Without this, every send asked for another. A
+            // refusal that says nothing — a network fault — 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;
+        }
+        if (!fresh || fresh === token) {
+            this.refused.remember(rejected, token);
+            throw rejected;
+        }
+        log('401 on a token the API no longer accepts — retrying once, refreshed');
+        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;
+        }
     }
     dispatch(url, token, cmd, options) {
         // The caller's input goes out as the caller wrote it — nothing in the body

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

@@ -104,8 +104,9 @@ export declare function serverTokenSource(config?: ServerAuthConfig): ServerToke
  * // Auto-detect from environment
  * const config = await getClientConfig()
  *
- * // Or override specific values
- * const config = await getClientConfig({ apiUrl: 'https://custom.api.com' })
+ * // Or override specific values — the API URL is the one on the
+ * // application's page in the developer portal
+ * const config = await getClientConfig({ apiUrl: 'https://your-api-url.example' })
  *
  * // The API rejected the token before its exp — revoked, or secret rotated
  * const fresh = await getClientConfig({ forceRefresh: true })

package/dist/cjs/server/getClientConfig.js

@@ -78,6 +78,33 @@ function resolveApiUrl(explicit) {
         process.env.LOCATION_API_URL ||
         process.env.LOCATION_SERVICE_API_URL);
 }
+/**
+ * A refusal of the client credentials themselves, as opposed to a refusal
+ * whose sentence already names its cause.
+ *
+ * Two answers qualify. `/auth/token`'s own `Invalid credentials` is a secret
+ * that matched nothing. The gateway's 401 (`UnauthorizedException`) is the
+ * authorizer refusing the Basic pair before `/auth/token` runs, and it gives
+ * the same answer for a wrong secret and for an application that is not
+ * active, so the advice for it names both. `Application is not active`, and
+ * every 403, is left as the API wrote it.
+ */
+function isCredentialsRefusal(error) {
+    if (!(error instanceof LocationServiceException_js_1.LocationServiceException))
+        return false;
+    if (error.statusCode !== 401)
+        return false;
+    return (error.code === 'UnauthorizedException' ||
+        error.message === 'Invalid credentials');
+}
+/** The API's words as a sentence, so the advice can follow them. */
+const sentence = (text) => (/[.!?]$/.test(text) ? text : `${text}.`);
+function credentialsAdvice(clientId, error) {
+    const check = `Check that LOCATION_CLIENT_ID ("${clientId}") and LOCATION_CLIENT_SECRET match your application in the developer portal`;
+    return error.code === 'UnauthorizedException'
+        ? `${check}, and that the application is active there.`
+        : `${check}.`;
+}
 function serverTokenSource(config = {}) {
     log('[serverTokenSource] Starting with config:', {
         hasApiUrl: !!config.apiUrl,
@@ -119,21 +146,20 @@ function serverTokenSource(config = {}) {
                 result = await provider.getToken(forceRefresh);
             }
             catch (error) {
-                // The provider now rejects rather than resolving with success:false, and
-                // the rejection is typed — so a store outage (503) can be reported as a
-                // store outage instead of as bad credentials.
-                if (error instanceof LocationServiceException_js_1.LocationServiceException) {
-                    if (error.isAuth) {
-                        throw new LocationServiceException_js_1.LocationServiceException({
-                            code: 'InvalidCredentialsException',
-                            message: `Authentication failed for client ID "${clientId}". ` +
-                                `Verify LOCATION_CLIENT_ID and LOCATION_CLIENT_SECRET match your application in the developer portal.`,
-                            statusCode: error.statusCode,
-                            requestId: error.requestId,
-                            cause: error,
-                        });
-                    }
-                    throw error;
+                // The API's code and sentence, passed through (#38). Every 401 and 403
+                // used to become "Verify LOCATION_CLIENT_ID and LOCATION_CLIENT_SECRET",
+                // which sent a suspended application to check a secret that was fine.
+                // The advice is added only where the credentials are what was refused.
+                if (isCredentialsRefusal(error)) {
+                    throw new LocationServiceException_js_1.LocationServiceException({
+                        code: error.code,
+                        message: `${sentence(error.message)} ${credentialsAdvice(clientId, error)}`,
+                        statusCode: error.statusCode,
+                        requestId: error.requestId,
+                        details: error.details,
+                        retryAfterMs: error.retryAfterMs,
+                        cause: error,
+                    });
                 }
                 throw error;
             }
@@ -190,8 +216,9 @@ function serverTokenSource(config = {}) {
  * // Auto-detect from environment
  * const config = await getClientConfig()
  *
- * // Or override specific values
- * const config = await getClientConfig({ apiUrl: 'https://custom.api.com' })
+ * // Or override specific values — the API URL is the one on the
+ * // application's page in the developer portal
+ * const config = await getClientConfig({ apiUrl: 'https://your-api-url.example' })
  *
  * // The API rejected the token before its exp — revoked, or secret rotated
  * const fresh = await getClientConfig({ forceRefresh: true })

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

@@ -2,14 +2,20 @@ import { LocationServiceException } from '../errors/LocationServiceException.js'
 /**
  * Turn a non-2xx response into a LocationServiceException.
  *
- * The API does not yet speak one error shape — that is api#29 (T23) — so this
- * tolerates the three it currently emits and synthesises a `code` for each.
- * RFC-0002 calls this legacy tolerance, and it is what lets the client ship
- * before the API contract lands. Delete the fallbacks once T23 is deployed.
- *
- *   { message, code, requestId }         service Lambdas — already correct
- *   { error, error_description }         /auth/token, OAuth shape
- *   { message: "Unauthorized" }          API Gateway's own responses
+ * The API answers every failure with a `code`, in one of three envelopes:
+ *
+ *   { message, code, requestId }                    data routes; the gateway
+ *   { error, error_description, code, requestId }   /auth/token (OAuth 2.0)
+ *   { code, message }                               the per-address limit
+ *
+ * The sentence is in `message`, or on /auth/token in `error_description`, and
+ * both are read whatever else the body carries (#38). The description used to
+ * be read only from a body with no `code`, and /auth/token has sent one since,
+ * so every refusal from it arrived as "Request failed: Unauthorized": a
+ * suspended application read exactly like a wrong secret.
+ *
+ * A body with no `code` — a proxy's, or an older deployment's — still gets
+ * one: from its OAuth `error`, else from the status.
  */
 export declare function parseErrorResponse(status: number, statusText: string, body: string, headers?: Headers): LocationServiceException;
 /**

package/dist/cjs/transport/errors.js

@@ -8,14 +8,20 @@ const LocationServiceException_js_1 = require("../errors/LocationServiceExceptio
 /**
  * Turn a non-2xx response into a LocationServiceException.
  *
- * The API does not yet speak one error shape — that is api#29 (T23) — so this
- * tolerates the three it currently emits and synthesises a `code` for each.
- * RFC-0002 calls this legacy tolerance, and it is what lets the client ship
- * before the API contract lands. Delete the fallbacks once T23 is deployed.
+ * The API answers every failure with a `code`, in one of three envelopes:
  *
- *   { message, code, requestId }         service Lambdas — already correct
- *   { error, error_description }         /auth/token, OAuth shape
- *   { message: "Unauthorized" }          API Gateway's own responses
+ *   { message, code, requestId }                    data routes; the gateway
+ *   { error, error_description, code, requestId }   /auth/token (OAuth 2.0)
+ *   { code, message }                               the per-address limit
+ *
+ * The sentence is in `message`, or on /auth/token in `error_description`, and
+ * both are read whatever else the body carries (#38). The description used to
+ * be read only from a body with no `code`, and /auth/token has sent one since,
+ * so every refusal from it arrived as "Request failed: Unauthorized": a
+ * suspended application read exactly like a wrong secret.
+ *
+ * A body with no `code` — a proxy's, or an older deployment's — still gets
+ * one: from its OAuth `error`, else from the status.
  */
 function parseErrorResponse(status, statusText, body, headers) {
     let message = `Request failed: ${statusText || status}`;
@@ -24,17 +30,19 @@ function parseErrorResponse(status, statusText, body, headers) {
     let details;
     try {
         const data = JSON.parse(body);
-        if (typeof data.message === 'string')
-            message = data.message;
-        if (typeof data.code === 'string')
-            code = data.code;
-        if (typeof data.requestId === 'string')
-            requestId = data.requestId;
-        // OAuth envelope from /auth/token
-        if (!code && typeof data.error === 'string') {
-            message = data.error_description ?? data.error;
-            code = oauthCode(data.error, status);
-            details = { oauthError: data.error };
+        const text = (value) => typeof value === 'string' ? value : undefined;
+        message =
+            text(data.error_description) ??
+                text(data.message) ??
+                text(data.error) ??
+                message;
+        code = text(data.code);
+        requestId = text(data.requestId);
+        // OAuth `error`, from /auth/token and the gateway's 401 on it
+        const oauthError = text(data.error);
+        if (oauthError) {
+            code ?? (code = oauthCode(oauthError, status));
+            details = { oauthError };
         }
     }
     catch {

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

@@ -1,20 +1,30 @@
 import debug from 'debug';
+import { TokenHold, holdFor } from '../auth/tokenHold.js';
 import { resolveEndpoint } from '../transport/endpoints.js';
 import { isTokenRejected, noTokenAvailable } from '../transport/errors.js';
 import { requestJson } from '../transport/http.js';
 import { readAppConfigClaims } from '../utils/tokenClaims.js';
 import { VerifyAddressCommand } from './commands.js';
 const log = debug('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.
  */
 export class GeoPlacesClient {
     constructor(config) {
+        /** A token the API refused, and why, until the hold lapses (#38). */
+        this.refused = new TokenHold();
         this.clientConfig = config;
         this.config = { serviceId: 'Geo Places' };
     }
@@ -48,12 +58,28 @@ export 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 noTokenAvailable('the client has no token yet. Pass `token`, or a `getToken`/`refreshToken` that has one.');
         }
@@ -75,25 +101,61 @@ export 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 (!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 (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 (!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 (isTokenRejected(again))
+                this.refused.remember(again, fresh);
+            throw again;
+        }
     }
     /**
      * Verify a PlaceId: `send(new VerifyAddressCommand({ PlaceId }))`, typed

package/dist/client/commands.d.ts

@@ -125,9 +125,8 @@ export interface VerifyAddressCommandInput {
  * Japan, which may not be stored at all. Every other Places result is for
  * display.
  *
- * Keep the PlaceId you sent beside it. The answer's own `PlaceId` can differ,
- * and for a unit it does: the service fails that one on every Places route,
- * while the one you sent verifies again.
+ * Its `PlaceId` is the one sent, for a unit as for a building, so a stored
+ * verification can be verified, or looked up, again by its own `PlaceId`.
  */
 export type VerifyAddressResponse = Omit<GetPlaceResponse, 'PricingBucket'> & {
     /**