@chaosity/location-client 0.11.0 → 0.12.0

package/README.md

@@ -43,14 +43,15 @@ its worker set up once under a bundler: see [The MapLibre worker](#the-maplibre-
 ## Key Features
 
 - **Custom Authentication**: Uses Bearer tokens instead of AWS SigV4
-- **AWS SDK Commands**: Full access to all AWS Location Service commands
+- **Places Commands**: the seven Amazon Location Places commands from `@aws-sdk/client-geo-places`, plus `VerifyAddressCommand`
 - **Address Verification**: `verifyAddress(placeId)` returns the one Places result you may store — see [Verifying an address](#verifying-an-address)
-- **Data Type Utilities**: Built-in GeoJSON conversion utilities
+- **Data Type Utilities**: GeoJSON converters for the Places responses
 - **MapLibre Integration**: Adapter for MapLibre GL Geocoder and `createTransformRequest` helper
 - **Map Style Control**: Fetch and customize map style descriptors — color scheme, points of interest, label language, and terrain, 3D buildings, traffic and more as [plan features](#plan-features)
 - **Map Language**: Switch map label language client-side with zero API calls
 - **POI Layer Control**: Toggle point-of-interest categories on/off by layer
 - **Server Utilities**: `getClientConfig()` with auto-env detection and token caching
+- **Typed Errors**: every failure is a `LocationServiceException` whose `code` is a `LocationServiceErrorCode`
 
 ## Quick Start
 
@@ -73,7 +74,8 @@ export async function getLocationConfig() {
 Set these environment variables:
 
 ```bash
-LOCATION_API_URL=https://api.chaosity.cloud
+# The API URL on your application's page in the developer portal
+LOCATION_API_URL=https://your-api-url.example
 LOCATION_CLIENT_ID=your-client-id
 LOCATION_CLIENT_SECRET=your-client-secret
 
@@ -86,7 +88,7 @@ Or pass credentials explicitly:
 
 ```typescript
 const config = await getClientConfig({
-  apiUrl: 'https://api.chaosity.cloud',
+  apiUrl: process.env.MY_API_URL!,
   clientId: process.env.MY_CLIENT_ID!,
   clientSecret: process.env.MY_SECRET!,
 })
@@ -102,10 +104,9 @@ import {
   type SuggestCommandOutput,
 } from '@chaosity/location-client'
 
-const client = new GeoPlacesClient({
-  apiUrl: 'https://api.chaosity.cloud',
-  token: 'your-bearer-token',
-})
+// apiUrl and token as getLocationConfig() above returns them
+const { apiUrl, token } = await getLocationConfig()
+const client = new GeoPlacesClient({ apiUrl, token })
 
 const response: SuggestCommandOutput = await client.send(
   new SuggestCommand({
@@ -172,9 +173,9 @@ if (answer.verified) {
   because the service would drop `Language`, `PoliticalView` and
   `AdditionalFeatures`. A repeat verify of the same PlaceId may be answered
   from the service's own store, and is billed all the same.
-- Keep the PlaceId you sent beside the answer. The answer's own `PlaceId` can
-  differ, and for a unit it does. The service does not accept that one back,
-  while the one you sent verifies again.
+- The answer's `PlaceId` is the one you sent, for a unit as for a building,
+  so a stored verification can be verified, or looked up with
+  `GetPlaceCommand`, again by its own `PlaceId`.
 - `client.verifyAddress(placeId)` is
   `client.send(new VerifyAddressCommand({ PlaceId: placeId }))`, typed as
   `VerifyAddressResponse`. `connector.verifyAddress` does the same on the
@@ -399,10 +400,11 @@ const geocoder = new MaplibreGeocoder(geoPlaces, {
 
 map.addControl(geocoder, 'top-left')
 
-// The geocoder calls getSuggestions → searchByPlaceId internally.
-// The 'result' event fires with the resolved place feature.
-geocoder.on('result', (event) => {
-  console.log('Selected place:', event.result)
+// Picking a suggestion calls searchByPlaceId, and the geocoder emits
+// 'results' with the resolved place on `place`. It emits 'result' only when a
+// typed query is geocoded (forwardGeocode) and one of its features is chosen.
+geocoder.on('results', (event) => {
+  if (event.place) console.log('Selected place:', event.place[0])
 })
 ```
 
@@ -417,7 +419,7 @@ Client for executing AWS Location Service commands with Bearer token auth.
 ```typescript
 const client = new GeoPlacesClient({
   apiUrl: string,
-  token: string,
+  token?: string, // at least one of token, getToken and refreshToken
   getToken?: () => string | undefined, // Optional: dynamic token getter
   refreshToken?: () => Promise<string | undefined>, // Optional: 401 self-heal
 })
@@ -453,6 +455,18 @@ nothing, and no retry is sent — a request that is going to fail again is not
 worth a second round trip. A 403 is never retried: a new token cannot fix an
 `Origin` the application does not allow.
 
+**A refused token is not sent again for 30 seconds.** When the API refuses a
+token and `refreshToken` cannot replace it — it rejects with a 401 or 403, or
+returns the same token — the next sends with that token reject with the same
+refusal without a request, and without asking `refreshToken`. A suspended
+application is refused on every route and by its token route alike, so each
+send used to cost a refused request and a refused refresh. A different token
+from `getToken` ends the wait at once. A `refreshToken` that fails with a
+`Retry-After` is held for that long instead. One that fails with nothing to
+say about when to try again — a network fault, or a Server Action's error,
+which reaches the browser without its fields — is asked again on the next
+send, and the refused token is not sent before it.
+
 #### Request options
 
 Every call in this package takes the same options object — `client.send`,
@@ -502,6 +516,39 @@ produced one yet raises `InvalidCredentialsException` instead of putting
 trip spent to be told what you already know. `GeoPlacesClient` asks `refreshToken` first, so a
 client whose token simply has not arrived yet still works.
 
+#### Errors
+
+Every failure is a `LocationServiceException`. Its `code` is typed
+`LocationServiceErrorCode`: every code the API documents at
+[docs.chaosity.cloud/api/errors](https://docs.chaosity.cloud/api/errors), the
+Amazon Location names it passes through, and the four this package raises for
+a failure that never reached the API (`AbortedException`, `NetworkException`,
+`ServiceException`, `UnknownCommandException`). A code the API adds later
+arrives all the same, so treat an unknown one as you would its status.
+
+```typescript
+import {
+  LocationServiceException,
+  type LocationServiceErrorCode,
+} from '@chaosity/location-client'
+
+try {
+  await client.send(command)
+} catch (err) {
+  if (!(err instanceof LocationServiceException)) throw err
+  const code: LocationServiceErrorCode | (string & {}) = err.code
+  if (code === 'RateLimitExceededException') {
+    // this application's own rate: wait `err.retryAfterMs`
+  } else if (code === 'ApplicationNotActiveException') {
+    // new, suspended, or off its plan: see the application in the portal
+  }
+}
+```
+
+`message` is the API's own sentence. On `/auth/token` that is its
+`error_description`, so a suspended application's refusal reads
+`Application is not active`.
+
 #### GeoPlaces Adapter
 
 Implements the `MaplibreGeocoderApi` interface for use with `@maplibre/maplibre-gl-geocoder`. Methods are called automatically by the geocoder control.
@@ -655,21 +702,45 @@ import { VerifyAddressCommand } from '@chaosity/location-client'
 
 #### Data Type Utilities
 
-GeoJSON conversion utilities from `@aws/amazon-location-utilities-datatypes`:
+GeoJSON converters from `@aws/amazon-location-utilities-datatypes`, one per
+Places response that carries positions. A result with no position becomes no
+feature:
+
+| Converter                                   | Takes the response of                                                                                                    |
+| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `geocodeResponseToFeatureCollection`        | `GeocodeCommand`                                                                                                         |
+| `reverseGeocodeResponseToFeatureCollection` | `ReverseGeocodeCommand`                                                                                                  |
+| `getPlaceResponseToFeatureCollection`       | `GetPlaceCommand`                                                                                                        |
+| `suggestResponseToFeatureCollection`        | `SuggestCommand` with `AdditionalFeatures: ['Core']`. Without it, Suggest results carry no position, and it returns none |
+| `searchTextResponseToFeatureCollection`     | `SearchTextCommand`                                                                                                      |
+| `searchNearbyResponseToFeatureCollection`   | `SearchNearbyCommand`                                                                                                    |
 
 ```typescript
 import {
-  placeToFeatureCollection,
-  routeToFeatureCollection,
-  devicePositionsToFeatureCollection,
+  SearchTextCommand,
+  searchTextResponseToFeatureCollection,
+  type SearchTextCommandOutput,
 } from '@chaosity/location-client'
+
+const response: SearchTextCommandOutput = await client.send(
+  new SearchTextCommand({
+    QueryText: 'coffee',
+    // SearchText takes exactly one of BiasPosition, Filter.BoundingBox or Filter.Circle.
+    BiasPosition: [-123.1207, 49.2827],
+  }),
+)
+const geojson = searchTextResponseToFeatureCollection(response)
 ```
 
+Autocomplete has no converter: its results carry no position. The package
+re-exports the rest of that package's converters too, but they take responses
+from other Amazon Location APIs, which this service does not serve.
+
 ### Server Exports (`@chaosity/location-client/server`)
 
 #### getClientConfig
 
-Gets a client config with a fresh token. Uses a singleton `TokenProvider` internally — safe to call repeatedly (tokens are cached and refreshed automatically).
+Gets a client config with a fresh token. It keeps one `TokenProvider` per application, for the applications used most recently, so it is safe to call repeatedly: tokens are cached and refreshed automatically.
 
 ```typescript
 import { getClientConfig } from '@chaosity/location-client/server'
@@ -682,6 +753,15 @@ const config = await getClientConfig()
 const replacement = await getClientConfig({ forceRefresh: true })
 ```
 
+A refusal arrives with the API's code and sentence. Where the API refused the
+credentials themselves, the message goes on to say which variables to check,
+and names the client ID. An application that is not active reads
+`Application is not active`, although once the API's authorizer has
+refused it the sentence is the same as for a wrong secret, and the advice then
+says to check both. A refusal is remembered for 30 seconds, and a
+`Retry-After` for as long as it asks: calls in that time reject at once,
+without asking `/auth/token` again.
+
 The return value is **plain data** — no methods, no closures — so it can be
 returned straight out of a Next.js Server Action to a Client Component. It is
 therefore a snapshot: the token in it stops working at its `expiresAt`, and the
@@ -738,8 +818,13 @@ which wins over both). `/auth/token` is the one endpoint exempt.
 
 A connector configured this way keeps working indefinitely: it holds a live
 token source, refreshes before expiry, and retries once with a new token if the
-API rejects the one it sent. Pass an explicit `token` instead and you opt out of
-all of that — it is a fixed string, and it dies at its own `exp`:
+API rejects the one it sent. If the new token is refused too, as a suspended
+application's is, the refusal is remembered for 30 seconds: sends in that time
+reject with it at once, without a data request or a token request. A refresh
+that fails with nothing to say about when to try again, a network fault for
+one, is asked again on the next send, without the refused token first. Pass an
+explicit `token` instead and you opt out of all of that — it is a fixed string,
+and it dies at its own `exp`:
 
 ```typescript
 // Managing credentials yourself: an explicit token source wins outright, and

package/dist/adapters/GeoPlaces.js

@@ -47,6 +47,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;
+}
 export class GeoPlaces {
     constructor(client, map, options = {}) {
         this.client = client;
@@ -101,9 +121,16 @@ export class GeoPlaces {
         const converted = 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;
@@ -131,38 +158,47 @@ export 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/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/auth/TokenProvider.js

@@ -1,6 +1,7 @@
 import debug from 'debug';
 import { LocationServiceException } from '../errors/LocationServiceException.js';
 import { requestJson } from '../transport/http.js';
+import { TokenHold, isTokenRefusal } from './tokenHold.js';
 import { TOKEN_REFRESH_BUFFER_SECONDS, readTokenExpiry, } from './tokenRefresh.js';
 const log = debug('location-client:auth');
 /**
@@ -33,6 +34,8 @@ const log = debug('location-client:auth');
  */
 export class TokenProvider {
     constructor(config) {
+        /** A refusal or a Retry-After from `/auth/token`, until it lapses (#38). */
+        this.hold = new TokenHold();
         // Runtime check: prevent usage in browser
         if (typeof window !== 'undefined') {
             throw new Error('TokenProvider cannot be used in browser environments. ' +
@@ -54,6 +57,15 @@ export 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...');
@@ -93,16 +105,32 @@ export class TokenProvider {
     async fetchToken() {
         const { clientId, clientSecret, apiUrl } = this.config;
         const credentials = btoa(`${clientId}:${clientSecret}`);
-        const data = await 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 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 (isTokenRefusal(error))
+                this.clearCache();
+            throw error;
+        }
         if (!data.access_token) {
             throw new LocationServiceException({
                 code: 'InvalidCredentialsException',
@@ -110,6 +138,7 @@ export 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/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/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;
+    }
+}