@chaosity/location-client 0.11.0 → 0.13.0

package/dist/auth/TokenProvider.js

@@ -1,8 +1,14 @@
 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');
+/**
+ * #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
  *
@@ -33,6 +39,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. ' +
@@ -42,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)
@@ -54,10 +62,27 @@ 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);
+            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
@@ -71,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;
@@ -93,16 +124,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 +157,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
@@ -125,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

@@ -0,0 +1,81 @@
+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 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;
+/**
+ * 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;
+}
+/**
+ * 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

@@ -0,0 +1,174 @@
+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).
+ *
+ * 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 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;
+/**
+ * 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;
+    }
+}
+/**
+ * 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.
      *

package/dist/cjs/adapters/GeoPlaces.js

@@ -50,7 +50,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;
+}
 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;
@@ -100,13 +126,20 @@ class GeoPlaces {
                     : config.countries.split(','),
             };
         }
-        const response = (await this.client.send(new commands_js_1.GeocodeCommand(commandInput)));
+        const response = await this.client.send(new commands_js_1.GeocodeCommand(commandInput));
         const converted = (0, amazon_location_utilities_datatypes_1.geocodeResponseToFeatureCollection)(response, {
             flattenProperties: true,
         });
+        // Geocode takes no box, so the geocoder's `bbox` is applied here, to what
+        // comes back (#59). It used to be ignored, and a result picked with Enter
+        // could land outside the box the integrator set.
+        const bbox = boundingBox(config.bbox);
+        const features = bbox
+            ? converted.features.filter((f) => insideBox(f.geometry.coordinates, bbox))
+            : converted.features;
         const result = {
             type: 'FeatureCollection',
-            features: toCarmenFeatures(converted.features),
+            features: toCarmenFeatures(features),
         };
         log('forwardGeocode returned %d results', result.features.length);
         return result;
@@ -121,7 +154,7 @@ class GeoPlaces {
             MaxResults: config.limit || 1,
             Language: this.normalizeLanguage(config.language),
         };
-        const response = (await this.client.send(new commands_js_1.ReverseGeocodeCommand(commandInput)));
+        const response = await this.client.send(new commands_js_1.ReverseGeocodeCommand(commandInput));
         const converted = (0, amazon_location_utilities_datatypes_1.reverseGeocodeResponseToFeatureCollection)(response, {
             flattenProperties: true,
         });
@@ -134,43 +167,52 @@ 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 commands_js_1.SuggestCommand(commandInput)));
+        const response = await this.client.send(new commands_js_1.SuggestCommand(commandInput));
         const suggestions = { suggestions: [] };
         for (const item of response.ResultItems ?? []) {
             const text = item.Title;
@@ -193,7 +235,7 @@ 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 = (0, amazon_location_utilities_datatypes_1.getPlaceResponseToFeatureCollection)(response, {
             flattenProperties: true,
         });

package/dist/cjs/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;
 }