@chaosity/location-client 0.11.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:
@@ -43,14 +46,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 +77,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 +91,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!,
 })
@@ -96,18 +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'
 
-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(
+const response = await client.send(
   new SuggestCommand({
     QueryText: 'Vancouver',
     MaxResults: 5,
@@ -115,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
@@ -128,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',
@@ -146,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'],
@@ -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
@@ -220,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
@@ -399,10 +435,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 +454,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 +490,21 @@ 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 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
+send, and the refused token is not sent before it.
+
 #### Request options
 
 Every call in this package takes the same options object — `client.send`,
@@ -463,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
 })
 ```
@@ -502,6 +554,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`, its
+`error_description` — so a suspended application's refusal names that cause
+and points to the portal.
+
 #### GeoPlaces Adapter
 
 Implements the `MaplibreGeocoderApi` interface for use with `@maplibre/maplibre-gl-geocoder`. Methods are called automatically by the geocoder control.
@@ -527,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).
@@ -542,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):
 
@@ -655,21 +750,44 @@ 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,
 } from '@chaosity/location-client'
+
+const response = 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 +800,36 @@ 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, 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
@@ -738,8 +886,25 @@ 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. 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`:
 
 ```typescript
 // Managing credentials yourself: an explicit token source wins outright, and
@@ -747,7 +912,7 @@ all of that — it is a fixed string, 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),
 })
 ```
 
@@ -793,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 { 
@@ -47,7 +47,33 @@ 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 {
+    /**
+     * @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;
@@ -97,13 +123,20 @@ 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,
         });
+        // 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;
@@ -118,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,
         });
@@ -131,43 +164,52 @@ 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 } : {}),
                     },
                 }
                 : {}),
         };
-        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;
@@ -190,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;
@@ -42,8 +57,10 @@ 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>;
+    getToken(forceRefresh?: boolean, options?: GetTokenOptions): Promise<TokenResponse>;
     /**
      * Fetch a token, distinguishing transient failure from terminal (#9).
      *
@@ -59,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;
 }