@chaosity/location-client 0.12.0 → 0.13.0

package/README.md

@@ -22,6 +22,9 @@ AWS Location Service compatible client with custom Bearer token authentication.
 npm install @chaosity/location-client
 ```
 
+TypeScript users need TypeScript 5.0 or later: the declarations use
+`export type *`.
+
 The Places commands, the transport and the static-map and style-URL helpers need
 nothing else. The **map** features are optional peer dependencies, so install
 them only if you use them:
@@ -98,17 +101,13 @@ const config = await getClientConfig({
 ### Client-Side: Using the GeoPlacesClient
 
 ```typescript
-import {
-  GeoPlacesClient,
-  SuggestCommand,
-  type SuggestCommandOutput,
-} from '@chaosity/location-client'
+import { GeoPlacesClient, SuggestCommand } from '@chaosity/location-client'
 
 // 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(
+const response = await client.send(
   new SuggestCommand({
     QueryText: 'Vancouver',
     MaxResults: 5,
@@ -116,8 +115,14 @@ const response: SuggestCommandOutput = await client.send(
     BiasPosition: [-123.1207, 49.2827],
   }),
 )
+response.ResultItems
 ```
 
+`send` resolves with the command's own output type — `SuggestCommandOutput`
+here — so there is nothing to annotate, on `GeoPlacesClient` and
+`LocationServiceConnector` alike (since 0.13.0). `CommandOutput<C>` names it
+when you need it.
+
 ### Verifying an address
 
 `POST /address/verify` resolves one PlaceId to the full place record plus
@@ -129,15 +134,10 @@ Japan, which may not be stored at all.
 The flow is suggest, then an optional unit pick, then verify at submit:
 
 ```typescript
-import {
-  GetPlaceCommand,
-  SuggestCommand,
-  type GetPlaceCommandOutput,
-  type SuggestCommandOutput,
-} from '@chaosity/location-client'
+import { GetPlaceCommand, SuggestCommand } from '@chaosity/location-client'
 
 // 1. While the person types: suggestions, for display.
-const suggestions: SuggestCommandOutput = await client.send(
+const suggestions = await client.send(
   // Suggest takes exactly one of BiasPosition, Filter.BoundingBox or Filter.Circle.
   new SuggestCommand({
     QueryText: '100 George St, Sydney',
@@ -147,7 +147,7 @@ const suggestions: SuggestCommandOutput = await client.send(
 const picked = suggestions.ResultItems?.[0]?.Place?.PlaceId
 
 // 2. Optionally, offer the building's units. Each has its own PlaceId.
-const building: GetPlaceCommandOutput = await client.send(
+const building = await client.send(
   new GetPlaceCommand({
     PlaceId: picked!,
     AdditionalFeatures: ['SecondaryAddresses'],
@@ -221,6 +221,41 @@ const style = await fetchMapStyle(apiUrl, 'Standard', getToken, {
 // then `maxPitch: 85` on the map, so the camera can tilt to see them
 ```
 
+#### When the API refuses the map's token
+
+`getToken` is synchronous, so it can only hand over the token already in hand.
+For when the API refuses that token before its `exp` — after the application's
+secret is rotated, for one — pass `{ getToken, refreshToken }` where the map
+helpers take `getToken`, and add `refreshTokenOnUnauthorized` for the tiles
+MapLibre fetches itself:
+
+```typescript
+import {
+  fetchMapStyle,
+  refreshTokenOnUnauthorized,
+} from '@chaosity/location-client'
+
+// refreshToken obtains a new token, and makes getToken return it from then on.
+const tokens = { getToken, refreshToken }
+
+const style = await fetchMapStyle(apiUrl, 'Standard', tokens)
+// ...the map as above, with createTransformRequest(apiUrl, getToken)...
+const stop = refreshTokenOnUnauthorized(map, apiUrl, tokens)
+```
+
+`fetchMapStyle` and `fetchStaticMap` then answer a 401 by asking `refreshToken`
+once and sending again with the new token, within the same `signal` and
+`overallTimeoutMs`. `refreshTokenOnUnauthorized` listens for the map's `error`
+events: on a 401 from your API it asks `refreshToken` once for the burst, and
+reloads the refused tiles when `getToken` returns a different token. The
+tiles receive the new token no other way — they read `getToken` through
+`createTransformRequest` — so a `refreshToken` that leaves `getToken` unchanged
+reloads nothing. A 403 is never retried: a new token cannot change it. A token
+`refreshToken` could not replace is not asked about again for 30 seconds, by
+any helper handed the same `tokens` object. `stop()` removes the listener.
+
+A bare `getToken` works as it always has: one request, and its 401 to you.
+
 ### The MapLibre worker
 
 MapLibre 6 loads and parses its tiles in a Web Worker, and it finds the
@@ -458,10 +493,13 @@ worth a second round trip. A 403 is never retried: a new token cannot fix an
 **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
+refusal without a request, and without asking `refreshToken`. A rotated secret
+is refused by the data route and, through a `refreshToken` that holds the old
+secret, by the token route too, so each send used to cost a refused request
+and a refused refresh. A suspended application is refused 403
+`ApplicationNotActiveException`, which is never retried, so it is not held
+here: each send has the API's answer. 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
@@ -477,7 +515,7 @@ Every call in this package takes the same options object — `client.send`,
 await client.send(command, {
   signal, // AbortSignal — cancels mid-flight AND mid-backoff
   timeoutMs: 10_000, // per ATTEMPT
-  overallTimeoutMs: 30_000, // the whole call, waits between attempts included
+  overallTimeoutMs: 30_000, // the whole call: the wait for a token and between attempts
   retry: { maxAttempts: 3 }, // or `false` for none
 })
 ```
@@ -545,9 +583,9 @@ try {
 }
 ```
 
-`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`.
+`message` is the API's own sentence — on `/auth/token`, its
+`error_description` — so a suspended application's refusal names that cause
+and points to the portal.
 
 #### GeoPlaces Adapter
 
@@ -574,6 +612,13 @@ import { createTransformRequest } from '@chaosity/location-client'
 const transformRequest = createTransformRequest(apiUrl, () => currentToken)
 ```
 
+#### refreshTokenOnUnauthorized
+
+`refreshTokenOnUnauthorized(map, apiUrl, { getToken, refreshToken })` reloads
+the tiles the API refused once `refreshToken` has given `getToken` a new token,
+and returns a function that stops listening. See
+[When the API refuses the map's token](#when-the-api-refuses-the-maps-token).
+
 #### fetchMapStyle
 
 Fetches the map style descriptor with Bearer auth and applies optional language to the descriptor JSON before MapLibre processes it (eliminates the visual flash that occurs when modifying layers post-load).
@@ -589,6 +634,9 @@ const style = await fetchMapStyle(apiUrl, 'Standard', getToken, {
 ```
 
 Hand `style` to `new maplibregl.Map`, with the worker set, as in [MapLibre Map Integration](#maplibre-map-integration).
+Pass `{ getToken, refreshToken }` in place of `getToken` to recover from a
+refused token, as [When the API refuses the map's token](#when-the-api-refuses-the-maps-token)
+shows; `fetchStaticMap` takes the same.
 
 The overlays need the `terrain`, `buildings`, `contours`, `traffic` and `travel-modes` plan features — see [Plan features](#plan-features):
 
@@ -719,10 +767,9 @@ feature:
 import {
   SearchTextCommand,
   searchTextResponseToFeatureCollection,
-  type SearchTextCommandOutput,
 } from '@chaosity/location-client'
 
-const response: SearchTextCommandOutput = await client.send(
+const response = await client.send(
   new SearchTextCommand({
     QueryText: 'coffee',
     // SearchText takes exactly one of BiasPosition, Filter.BoundingBox or Filter.Circle.
@@ -754,14 +801,35 @@ 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
+credentials themselves, a 401, the message goes on to say which variables to
+check, and names the client ID. An application that is not active is refused
+403 `ApplicationNotActiveException`, in a sentence that names that cause, and
+gets no advice added. 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.
 
+When the token goes to a browser, the browser is what sees it refused, and
+only it can say so. `@chaosity/location-client-react`'s provider asks its
+`getConfig` again with `{ refusedToken }` after a 401. Answer it by replacing
+the cached token only when it is the one refused:
+
+```typescript
+'use server'
+import { getClientConfig } from '@chaosity/location-client/server'
+
+export async function getLocationConfig(request?: { refusedToken?: string }) {
+  const config = await getClientConfig()
+  return request?.refusedToken === config.token
+    ? getClientConfig({ forceRefresh: true })
+    : config
+}
+```
+
+Asked again without it, `getClientConfig()` hands back the token it caches:
+the one just refused. The check mints once per refused token, and nothing for a
+report of any other. It does not stop a caller echoing the token it was just
+given to make the server mint again; rate-limit the endpoint if that matters.
+
 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
@@ -818,11 +886,23 @@ 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. 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
+API rejects the one it sent. When that refresh before expiry fails with anything
+but a refusal — a 429 or 503 from the token route, or a network fault — it keeps
+sending the token it has until 5 seconds before that token's own `exp`, and asks
+the token route nothing more while a `Retry-After` stands; past that it rejects
+with the API's error, `retryAfterMs` intact. A `getToken` you supply is asked
+for this with `{ cachedUntilExpiry: true }`, which `TokenProvider.getToken`
+understands. `getClientConfig` never does it: a token that close to its expiry
+is one a browser provider would ask to replace at once.
+
+After the API rejects a token, if no new token can be had, or the new one is
+refused too — a rotated secret's refresh is refused, for one — 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 suspended application is refused 403 on
+every route, which no new token can change: its data requests are not retried,
+and a token request's refusal is remembered the same way. 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`:
 
@@ -832,7 +912,7 @@ and it dies at its own `exp`:
 const connector = new LocationServiceConnector({
   apiUrl,
   origin: 'https://your-allowed-domain.example',
-  getToken: (forceRefresh) => provider.getToken(forceRefresh),
+  getToken: (forceRefresh, options) => provider.getToken(forceRefresh, options),
 })
 ```
 
@@ -878,7 +958,9 @@ DEBUG=location-client:api npm run dev
 
 ## TypeScript Support
 
-Full TypeScript support with types from AWS SDK:
+The request and response types are the AWS SDK's, and `send` resolves with the
+command's own output type. To name it — for a variable declared before the
+call, say — use the SDK's `…CommandOutput` or `CommandOutput<C>`:
 
 ```typescript
 import type { SuggestCommandOutput } from '@chaosity/location-client'

package/dist/adapters/GeoPlaces.d.ts

@@ -74,7 +74,13 @@ export declare class GeoPlaces implements MaplibreGeocoderApi {
     private client;
     private map;
     private details;
-    constructor(client: GeoPlacesClient, map: Map, options?: GeoPlacesOptions);
+    /**
+     * @param client Anything with the client's `send` — the adapter calls
+     *   nothing else (#65). `@chaosity/location-client-react`'s
+     *   `useLocationClient()` hands out an interface, not a `GeoPlacesClient`,
+     *   and a class with private fields admits no other object.
+     */
+    constructor(client: Pick<GeoPlacesClient, 'send'>, map: Map, options?: GeoPlacesOptions);
     /**
      * Build the AdditionalFeatures list from the opt-ins, or omit it entirely.
      *

package/dist/adapters/GeoPlaces.js

@@ -1,4 +1,4 @@
-import { GetPlaceAdditionalFeature, } from '@aws-sdk/client-geo-places';
+import { GetPlaceAdditionalFeature } from '@aws-sdk/client-geo-places';
 import { geocodeResponseToFeatureCollection, getPlaceResponseToFeatureCollection, reverseGeocodeResponseToFeatureCollection, } from '@aws/amazon-location-utilities-datatypes';
 import debug from 'debug';
 import { 
@@ -68,6 +68,12 @@ function insideBox([x, y], bbox) {
     return minX <= maxX ? x >= minX && x <= maxX : x >= minX || x <= maxX;
 }
 export class GeoPlaces {
+    /**
+     * @param client Anything with the client's `send` — the adapter calls
+     *   nothing else (#65). `@chaosity/location-client-react`'s
+     *   `useLocationClient()` hands out an interface, not a `GeoPlacesClient`,
+     *   and a class with private fields admits no other object.
+     */
     constructor(client, map, options = {}) {
         this.client = client;
         this.map = map;
@@ -117,7 +123,7 @@ export class GeoPlaces {
                     : config.countries.split(','),
             };
         }
-        const response = (await this.client.send(new GeocodeCommand(commandInput)));
+        const response = await this.client.send(new GeocodeCommand(commandInput));
         const converted = geocodeResponseToFeatureCollection(response, {
             flattenProperties: true,
         });
@@ -145,7 +151,7 @@ export class GeoPlaces {
             MaxResults: config.limit || 1,
             Language: this.normalizeLanguage(config.language),
         };
-        const response = (await this.client.send(new ReverseGeocodeCommand(commandInput)));
+        const response = await this.client.send(new ReverseGeocodeCommand(commandInput));
         const converted = reverseGeocodeResponseToFeatureCollection(response, {
             flattenProperties: true,
         });
@@ -203,7 +209,7 @@ export class GeoPlaces {
                 }
                 : {}),
         };
-        const response = (await this.client.send(new SuggestCommand(commandInput)));
+        const response = await this.client.send(new SuggestCommand(commandInput));
         const suggestions = { suggestions: [] };
         for (const item of response.ResultItems ?? []) {
             const text = item.Title;
@@ -226,7 +232,7 @@ export class GeoPlaces {
             Language: this.normalizeLanguage(config.language),
             ...(additionalFeatures ? { AdditionalFeatures: additionalFeatures } : {}),
         });
-        const response = (await this.client.send(command));
+        const response = await this.client.send(command);
         const result = getPlaceResponseToFeatureCollection(response, {
             flattenProperties: true,
         });

package/dist/auth/TokenProvider.d.ts

@@ -4,6 +4,21 @@ export interface TokenResponse {
     expiresAt?: number;
     error?: string;
 }
+export interface GetTokenOptions {
+    /**
+     * When a refresh fails with an error that waiting can fix — a 429 or 503
+     * from `/auth/token`, a network fault, or the `Retry-After` such a failure
+     * left standing — return the cached token instead, while it is before its
+     * own `exp` (#63). A refusal (401 or 403) still clears the cache and throws,
+     * and a forced refresh never falls back: it is asked for because the API
+     * refused the cached token.
+     *
+     * For server-side dispatch only. Never set it where the token is handed to
+     * a browser: a token inside `TOKEN_REFRESH_BUFFER_SECONDS` is one the React
+     * provider asks to replace at once, so `getClientConfig` does not.
+     */
+    cachedUntilExpiry?: boolean;
+}
 export interface TokenProviderConfig {
     apiUrl: string;
     clientId: string;
@@ -45,7 +60,7 @@ export declare class TokenProvider {
     /** A refusal or a Retry-After from `/auth/token`, until it lapses (#38). */
     private readonly hold;
     constructor(config: TokenProviderConfig);
-    getToken(forceRefresh?: boolean): Promise<TokenResponse>;
+    getToken(forceRefresh?: boolean, options?: GetTokenOptions): Promise<TokenResponse>;
     /**
      * Fetch a token, distinguishing transient failure from terminal (#9).
      *
@@ -61,6 +76,12 @@ export declare class TokenProvider {
      * with `success: false`, so a stale token can never be used by accident.
      */
     private fetchToken;
+    /**
+     * #63: the cached token, when the caller asked for it and the failure is one
+     * that waiting fixes. A refusal has already cleared the cache in fetchToken,
+     * so it can never be the cached token handed back here.
+     */
+    private fallback;
     private isExpired;
     clearCache(): void;
 }

package/dist/auth/TokenProvider.js

@@ -4,6 +4,11 @@ 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');
+/**
+ * #63: how close to its own `exp` a cached token may still be sent when a
+ * refresh fails. A margin for the clocks of this host and the API to disagree.
+ */
+const EXPIRY_SKEW_MS = 5000;
 /**
  * TokenProvider - SERVER-SIDE ONLY
  *
@@ -45,7 +50,7 @@ export class TokenProvider {
         log('Initializing TokenProvider for %s', config.apiUrl);
         this.config = config;
     }
-    async getToken(forceRefresh = false) {
+    async getToken(forceRefresh = false, options = {}) {
         if (!forceRefresh && this.cachedToken && !this.isExpired()) {
             const expiresIn = this.cachedExpiresAt
                 ? Math.floor((this.cachedExpiresAt - Date.now()) / 1000)
@@ -64,12 +69,20 @@ export class TokenProvider {
         const held = this.hold.check()?.error;
         if (held) {
             log('Token request held: %s', held.message);
+            const fallback = this.fallback(forceRefresh, options, held);
+            if (fallback)
+                return fallback;
             throw held;
         }
         // If token fetch is already in progress, wait for it
         if (this.tokenPromise) {
             log('Token fetch in progress, waiting for existing request...');
-            return this.tokenPromise;
+            return this.tokenPromise.catch((error) => {
+                const fallback = this.fallback(forceRefresh, options, error);
+                if (fallback)
+                    return fallback;
+                throw error;
+            });
         }
         // Start new token fetch
         const reason = forceRefresh
@@ -83,6 +96,12 @@ export class TokenProvider {
             const result = await this.tokenPromise;
             return result;
         }
+        catch (error) {
+            const fallback = this.fallback(forceRefresh, options, error);
+            if (fallback)
+                return fallback;
+            throw error;
+        }
         finally {
             // Clear promise after completion (success or failure)
             this.tokenPromise = undefined;
@@ -154,6 +173,27 @@ export class TokenProvider {
             expiresAt: this.cachedExpiresAt,
         };
     }
+    /**
+     * #63: the cached token, when the caller asked for it and the failure is one
+     * that waiting fixes. A refusal has already cleared the cache in fetchToken,
+     * so it can never be the cached token handed back here.
+     */
+    fallback(forceRefresh, options, error) {
+        if (forceRefresh || !options.cachedUntilExpiry)
+            return undefined;
+        if (isTokenRefusal(error))
+            return undefined;
+        if (!this.cachedToken || !this.cachedExpiresAt)
+            return undefined;
+        if (Date.now() >= this.cachedExpiresAt - EXPIRY_SKEW_MS)
+            return undefined;
+        log('Refresh failed (%s); the cached token is valid for %ds more, sending it', error instanceof Error ? error.message : String(error), Math.floor((this.cachedExpiresAt - Date.now()) / 1000));
+        return {
+            success: true,
+            token: this.cachedToken,
+            expiresAt: this.cachedExpiresAt,
+        };
+    }
     isExpired(bufferSeconds = TOKEN_REFRESH_BUFFER_SECONDS) {
         if (!this.cachedExpiresAt)
             return true;

package/dist/auth/tokenHold.d.ts

@@ -9,11 +9,11 @@ import { LocationServiceException } from '../errors/LocationServiceException.js'
  * 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.
+ * Thirty seconds is short beside the API's own waits: it accepts a
+ * reactivated application again within five minutes, and refuses a newly
+ * created or reactivated one for up to about thirty seconds while its key goes
+ * live. So this side adds at most thirty seconds to either, and turns a
+ * request rate into a trickle meanwhile.
  */
 export declare const TOKEN_REFUSAL_HOLD_MS = 30000;
 /**
@@ -70,3 +70,12 @@ export declare class TokenHold {
     } | undefined;
     forget(): void;
 }
+/**
+ * Send with `token`, and after a 401 once more with `refresh()`'s token when it
+ * is a DIFFERENT one, remembering on `hold` what the API and the source said,
+ * against the token it concerns (#38).
+ *
+ * The one copy of the 401 retry: both send paths and the two map fetches (#72)
+ * call it, so when to ask again is decided here and nowhere else.
+ */
+export declare function sendRetryingOnce<T>(hold: TokenHold, token: string, send: (token: string) => Promise<T>, refresh: () => Promise<string | undefined>, onRetry?: () => void): Promise<T>;

package/dist/auth/tokenHold.js

@@ -1,4 +1,5 @@
 import { LocationServiceException } from '../errors/LocationServiceException.js';
+import { isTokenRejected } from '../transport/errors.js';
 /**
  * How long a refusal is remembered: a token the API refused, or a token
  * request `/auth/token` refused (#38).
@@ -9,11 +10,11 @@ import { LocationServiceException } from '../errors/LocationServiceException.js'
  * 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.
+ * Thirty seconds is short beside the API's own waits: it accepts a
+ * reactivated application again within five minutes, and refuses a newly
+ * created or reactivated one for up to about thirty seconds while its key goes
+ * live. So this side adds at most thirty seconds to either, and turns a
+ * request rate into a trickle meanwhile.
  */
 export const TOKEN_REFUSAL_HOLD_MS = 30000;
 /**
@@ -107,3 +108,67 @@ export class TokenHold {
         this.held = undefined;
     }
 }
+/**
+ * Send with `token`, and after a 401 once more with `refresh()`'s token when it
+ * is a DIFFERENT one, remembering on `hold` what the API and the source said,
+ * against the token it concerns (#38).
+ *
+ * The one copy of the 401 retry: both send paths and the two map fetches (#72)
+ * call it, so when to ask again is decided here and nowhere else.
+ */
+export async function sendRetryingOnce(hold, token, send, refresh, onRetry) {
+    // This token was refused a moment ago and nothing has replaced it: answer
+    // with that refusal rather than send it, and ask the source again. A
+    // different token 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 = hold.check(token);
+    if (held && !held.askAgain)
+        throw held.error;
+    let rejected = held?.error;
+    if (!held) {
+        try {
+            return await send(token);
+        }
+        catch (err) {
+            if (!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
+    // `getToken` that ignores `forceRefresh`, a `refreshToken` that hands back
+    // what it had, and a cached token the API has revoked before its `exp` —
+    // re-sending any of them is a second doomed request for the same answer.
+    let fresh;
+    try {
+        fresh = await refresh();
+    }
+    catch (refusal) {
+        // A rotated secret's token route refuses the refresh as the data route
+        // refused 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)
+            hold.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)
+            hold.remember(rejected, token, { askAgain: true });
+        throw refusal;
+    }
+    if (!fresh || fresh === token) {
+        hold.remember(rejected, token);
+        throw rejected;
+    }
+    onRetry?.();
+    try {
+        return await send(fresh);
+    }
+    catch (again) {
+        if (isTokenRejected(again))
+            hold.remember(again, fresh);
+        throw again;
+    }
+}

package/dist/aws.d.ts

@@ -0,0 +1,4 @@
+export type * from '@aws-sdk/client-geo-places';
+export { $Command, AccessDeniedException, AccessDeniedException$, AccessPoint$, AccessPointType, AccessRestriction$, Address$, AddressComponentMatchScores$, AddressComponentPhonemes$, AddressTranslationComponent, AdminNames$, AdminNamesPreference, Autocomplete$, AutocompleteAdditionalFeature, AutocompleteAddressHighlights$, AutocompleteFilter$, AutocompleteFilterPlaceType, AutocompleteHighlights$, AutocompleteIntendedUse, AutocompleteRequest$, AutocompleteResponse$, AutocompleteResultItem$, BusinessChain$, Category$, ComponentMatchScores$, ContactDetails$, Contacts$, Country$, CountryHighlights$, CrossReference$, FilterCircle$, FoodType$, GeoPlacesServiceException, GeoPlacesServiceException$, Geocode$, GeocodeAdditionalFeature, GeocodeAddressNamesMode, GeocodeFilter$, GeocodeFilterPlaceType, GeocodeIntendedUse, GeocodeParsedQuery$, GeocodeParsedQueryAddressComponents$, GeocodeQueryComponents$, GeocodeRequest$, GeocodeResponse$, GeocodeResultItem$, GetPlace$, GetPlaceAdditionalFeature, GetPlaceAddressNamesMode, GetPlaceIntendedUse, GetPlaceRequest$, GetPlaceResponse$, Highlight$, InternalServerException, InternalServerException$, Intersection$, MatchScoreDetails$, OpeningHours$, OpeningHoursComponents$, ParsedQueryComponent$, ParsedQuerySecondaryAddressComponent$, PhonemeDetails$, PhonemeTranscription$, PlaceAttribute, PlaceType, PostalAuthority, PostalCodeDetails$, PostalCodeMode, PostalCodeType, QueryRefinement$, QueryType, RecordTypeCode, Region$, RegionHighlights$, RelatedPlace$, ReverseGeocode$, ReverseGeocodeAdditionalFeature, ReverseGeocodeAddressNamesMode, ReverseGeocodeFilter$, ReverseGeocodeFilterPlaceType, ReverseGeocodeIntendedUse, ReverseGeocodeRequest$, ReverseGeocodeResponse$, ReverseGeocodeResultItem$, SearchNearby$, SearchNearbyAdditionalFeature, SearchNearbyFilter$, SearchNearbyIntendedUse, SearchNearbyRequest$, SearchNearbyResponse$, SearchNearbyResultItem$, SearchText$, SearchTextAdditionalFeature, SearchTextFilter$, SearchTextIntendedUse, SearchTextRequest$, SearchTextResponse$, SearchTextResultItem$, SearchTextTravelMode, SecondaryAddressComponent$, SecondaryAddressComponentMatchScore$, StreetComponents$, SubRegion$, SubRegionHighlights$, Suggest$, SuggestAdditionalFeature, SuggestAddressHighlights$, SuggestFilter$, SuggestHighlights$, SuggestIntendedUse, SuggestPlaceResult$, SuggestQueryResult$, SuggestRequest$, SuggestResponse$, SuggestResultItem$, SuggestResultItemType, SuggestTravelMode, ThrottlingException, ThrottlingException$, TimeZone$, TranslationDetails$, TranslationName$, TranslationNameType, TypePlacement, UspsZip$, UspsZipPlus4$, ValidationException, ValidationException$, ValidationExceptionField$, ValidationExceptionReason, ZipClassificationCode, __Client, errorTypeRegistries, } from '@aws-sdk/client-geo-places';
+export type * from '@aws/amazon-location-utilities-datatypes';
+export { calculateIsolinesResponseToFeatureCollection, calculateRoutesResponseToFeatureCollections, devicePositionsToFeatureCollection, featureCollectionToGeofence, geocodeResponseToFeatureCollection, geofencesToFeatureCollection, getPlaceResponseToFeatureCollection, optimizeWaypointsResponseToFeatureCollection, placeToFeatureCollection, reverseGeocodeResponseToFeatureCollection, routeToFeatureCollection, searchNearbyResponseToFeatureCollection, searchTextResponseToFeatureCollection, snapToRoadsResponseToFeatureCollection, suggestResponseToFeatureCollection, } from '@aws/amazon-location-utilities-datatypes';

package/dist/aws.js

@@ -0,0 +1,2 @@
+export { $Command, AccessDeniedException, AccessDeniedException$, AccessPoint$, AccessPointType, AccessRestriction$, Address$, AddressComponentMatchScores$, AddressComponentPhonemes$, AddressTranslationComponent, AdminNames$, AdminNamesPreference, Autocomplete$, AutocompleteAdditionalFeature, AutocompleteAddressHighlights$, AutocompleteFilter$, AutocompleteFilterPlaceType, AutocompleteHighlights$, AutocompleteIntendedUse, AutocompleteRequest$, AutocompleteResponse$, AutocompleteResultItem$, BusinessChain$, Category$, ComponentMatchScores$, ContactDetails$, Contacts$, Country$, CountryHighlights$, CrossReference$, FilterCircle$, FoodType$, GeoPlacesServiceException, GeoPlacesServiceException$, Geocode$, GeocodeAdditionalFeature, GeocodeAddressNamesMode, GeocodeFilter$, GeocodeFilterPlaceType, GeocodeIntendedUse, GeocodeParsedQuery$, GeocodeParsedQueryAddressComponents$, GeocodeQueryComponents$, GeocodeRequest$, GeocodeResponse$, GeocodeResultItem$, GetPlace$, GetPlaceAdditionalFeature, GetPlaceAddressNamesMode, GetPlaceIntendedUse, GetPlaceRequest$, GetPlaceResponse$, Highlight$, InternalServerException, InternalServerException$, Intersection$, MatchScoreDetails$, OpeningHours$, OpeningHoursComponents$, ParsedQueryComponent$, ParsedQuerySecondaryAddressComponent$, PhonemeDetails$, PhonemeTranscription$, PlaceAttribute, PlaceType, PostalAuthority, PostalCodeDetails$, PostalCodeMode, PostalCodeType, QueryRefinement$, QueryType, RecordTypeCode, Region$, RegionHighlights$, RelatedPlace$, ReverseGeocode$, ReverseGeocodeAdditionalFeature, ReverseGeocodeAddressNamesMode, ReverseGeocodeFilter$, ReverseGeocodeFilterPlaceType, ReverseGeocodeIntendedUse, ReverseGeocodeRequest$, ReverseGeocodeResponse$, ReverseGeocodeResultItem$, SearchNearby$, SearchNearbyAdditionalFeature, SearchNearbyFilter$, SearchNearbyIntendedUse, SearchNearbyRequest$, SearchNearbyResponse$, SearchNearbyResultItem$, SearchText$, SearchTextAdditionalFeature, SearchTextFilter$, SearchTextIntendedUse, SearchTextRequest$, SearchTextResponse$, SearchTextResultItem$, SearchTextTravelMode, SecondaryAddressComponent$, SecondaryAddressComponentMatchScore$, StreetComponents$, SubRegion$, SubRegionHighlights$, Suggest$, SuggestAdditionalFeature, SuggestAddressHighlights$, SuggestFilter$, SuggestHighlights$, SuggestIntendedUse, SuggestPlaceResult$, SuggestQueryResult$, SuggestRequest$, SuggestResponse$, SuggestResultItem$, SuggestResultItemType, SuggestTravelMode, ThrottlingException, ThrottlingException$, TimeZone$, TranslationDetails$, TranslationName$, TranslationNameType, TypePlacement, UspsZip$, UspsZipPlus4$, ValidationException, ValidationException$, ValidationExceptionField$, ValidationExceptionReason, ZipClassificationCode, __Client, errorTypeRegistries, } from '@aws-sdk/client-geo-places';
+export { calculateIsolinesResponseToFeatureCollection, calculateRoutesResponseToFeatureCollections, devicePositionsToFeatureCollection, featureCollectionToGeofence, geocodeResponseToFeatureCollection, geofencesToFeatureCollection, getPlaceResponseToFeatureCollection, optimizeWaypointsResponseToFeatureCollection, placeToFeatureCollection, reverseGeocodeResponseToFeatureCollection, routeToFeatureCollection, searchNearbyResponseToFeatureCollection, searchTextResponseToFeatureCollection, snapToRoadsResponseToFeatureCollection, suggestResponseToFeatureCollection, } from '@aws/amazon-location-utilities-datatypes';

package/dist/cjs/adapters/GeoPlaces.d.ts

@@ -74,7 +74,13 @@ export declare class GeoPlaces implements MaplibreGeocoderApi {
     private client;
     private map;
     private details;
-    constructor(client: GeoPlacesClient, map: Map, options?: GeoPlacesOptions);
+    /**
+     * @param client Anything with the client's `send` — the adapter calls
+     *   nothing else (#65). `@chaosity/location-client-react`'s
+     *   `useLocationClient()` hands out an interface, not a `GeoPlacesClient`,
+     *   and a class with private fields admits no other object.
+     */
+    constructor(client: Pick<GeoPlacesClient, 'send'>, map: Map, options?: GeoPlacesOptions);
     /**
      * Build the AdditionalFeatures list from the opt-ins, or omit it entirely.
      *