@chaosity/location-client 0.12.0 → 0.13.1

package/dist/cjs/client/GeoPlacesClient.js

@@ -57,13 +57,21 @@ class GeoPlacesClient {
     currentToken() {
         return this.clientConfig.getToken?.() ?? this.clientConfig.token;
     }
+    /**
+     * `refreshToken`, held to the caller's signal and deadline (#62). A slow or
+     * stuck callback used to hold `send` past both.
+     */
+    askRefreshToken(call) {
+        const asked = this.clientConfig.refreshToken?.();
+        return asked ? (0, http_js_1.withinCall)(asked, call) : Promise.resolve(undefined);
+    }
     /**
      * A token to send, or a refusal — never `undefined`.
      *
      * `refreshToken` is asked only when there is nothing at all in hand, so a
      * client configured the ordinary way pays nothing for this.
      */
-    async ensureToken() {
+    async ensureToken(call) {
         // Truthiness, not `??`: an empty string is a token source with nothing to
         // give, not a decision to send an empty one. With `??` it survived the
         // coalesce, skipped `refreshToken`, and then failed the check below — so
@@ -80,7 +88,7 @@ class GeoPlacesClient {
             throw held;
         let token;
         try {
-            token = await this.clientConfig.refreshToken?.();
+            token = await this.askRefreshToken(call);
         }
         catch (refusal) {
             this.refused.remember(refusal, NO_TOKEN);
@@ -91,11 +99,6 @@ class GeoPlacesClient {
         }
         return token;
     }
-    /**
-     * @param options `signal` to cancel, `timeoutMs` per attempt,
-     *   `overallTimeoutMs` for the whole call, `retry: false` to disable the
-     *   retry loop. Every failure throws LocationServiceException.
-     */
     async send(command, options) {
         const cmd = command;
         const url = `${this.clientConfig.apiUrl}${(0, endpoints_js_1.resolveEndpoint)(cmd)}`;
@@ -106,62 +109,15 @@ class GeoPlacesClient {
         // source has not produced one yet spent a whole round trip to learn
         // something it already knew. Ask the refresh source instead, and refuse if
         // there is still nothing.
-        const token = await this.ensureToken();
-        // This token was refused a moment ago and nothing has replaced it: answer
-        // with that refusal rather than send it, and ask `refreshToken`, again
-        // (#38). A different token from `getToken` ends the hold. When the refresh
-        // that followed said nothing about when to ask again, it is asked now —
-        // but the refused token is still not sent.
-        const held = this.refused.check(token);
-        if (held && !held.askAgain)
-            throw held.error;
-        let rejected = held?.error;
-        if (!held) {
-            try {
-                return await this.dispatch(url, token, cmd, options);
-            }
-            catch (err) {
-                if (!(0, errors_js_1.isTokenRejected)(err))
-                    throw err;
-                rejected = err;
-            }
-        }
-        // One shot. `refreshToken` is the only way to actually obtain a new token
-        // here — `getToken` is synchronous and returns the one already in hand —
-        // but it is re-read as a fallback because a provider that refreshes in the
+        // The call's deadline starts here, before any wait for a token (#62).
+        const call = (0, http_js_1.startCall)(options);
+        const token = await this.ensureToken(call);
+        // One shot, through `sendRetryingOnce` like every 401 retry here (#38).
+        // `refreshToken` is the only way to actually obtain a new token here —
+        // `getToken` is synchronous and returns the one already in hand — but it
+        // is re-read as a fallback because a provider that refreshes in the
         // background may have landed a new one while this request was in flight.
-        let fresh;
-        try {
-            fresh = (await this.clientConfig.refreshToken?.()) ?? this.currentToken();
-        }
-        catch (refusal) {
-            // A suspended application's token route refuses it as its data routes
-            // refuse its token. Without this, every send asked again. A refusal that
-            // says nothing — a network fault, or a Server Action's error without its
-            // fields — leaves the source to be asked again, but not the token sent.
-            if ((0, tokenHold_js_1.holdFor)(refusal) > 0)
-                this.refused.remember(refusal, token);
-            // Only when no hold stands: one already standing keeps its own end, so
-            // the refused token is tried again once per hold rather than never.
-            else if (!held)
-                this.refused.remember(rejected, token, { askAgain: true });
-            throw refusal;
-        }
-        // Nothing new to send. Repeating the request would fail identically — a
-        // second round trip for the same 401.
-        if (!fresh || fresh === token) {
-            this.refused.remember(rejected, token);
-            throw rejected;
-        }
-        log('401 — retrying %s once with a refreshed token', cmd.constructor?.name);
-        try {
-            return await this.dispatch(url, fresh, cmd, options);
-        }
-        catch (again) {
-            if ((0, errors_js_1.isTokenRejected)(again))
-                this.refused.remember(again, fresh);
-            throw again;
-        }
+        return (0, tokenHold_js_1.sendRetryingOnce)(this.refused, token, (t) => this.dispatch(url, t, cmd, call), async () => (await this.askRefreshToken(call)) ?? this.currentToken(), () => log('401 — retrying %s once with a refreshed token', cmd.constructor?.name));
     }
     /**
      * Verify a PlaceId: `send(new VerifyAddressCommand({ PlaceId }))`, typed

package/dist/cjs/index.d.ts

@@ -5,10 +5,9 @@ export type { RequestOptions } from './transport/http.js';
 export { TOKEN_REFRESH_BUFFER_SECONDS, readTokenExpiry, } from './auth/tokenRefresh.js';
 export { FEATURE_NOT_ENTITLED, LocationServiceException, } from './errors/LocationServiceException.js';
 export type { LocationServiceErrorCode, LocationServiceExceptionOptions, } from './errors/LocationServiceException.js';
-export * from '@aws-sdk/client-geo-places';
+export * from './aws.js';
 export { AutocompleteCommand, GeocodeCommand, GetPlaceCommand, ReverseGeocodeCommand, SearchNearbyCommand, SearchTextCommand, SuggestCommand, VerifyAddressCommand, } from './client/commands.js';
 export type { AutocompleteCommandInput, AutocompleteRequest, GeocodeCommandInput, GeocodeRequest, GetPlaceCommandInput, GetPlaceRequest, NeverForwarded, ReverseGeocodeCommandInput, ReverseGeocodeRequest, SearchNearbyCommandInput, SearchNearbyRequest, SearchTextCommandInput, SearchTextRequest, SuggestCommandInput, SuggestRequest, VerifyAddressCommandInput, VerifyAddressResponse, } from './client/commands.js';
-export * from '@aws/amazon-location-utilities-datatypes';
 export { GeoPlaces } from './adapters/GeoPlaces.js';
 export type { GeoPlacesDetailOptions, GeoPlacesOptions, } from './adapters/GeoPlaces.js';
 export { createTransformRequest } from './maps/createTransformRequest.js';
@@ -17,10 +16,12 @@ export { POI_CATEGORIES, setAllPoiVisibility, setPoiVisibility, } from './maps/m
 export type { PoiCategory } from './maps/mapPoi.js';
 export { buildMapStyleUrl, fetchMapStyle } from './maps/mapStyle.js';
 export type { MapStyleOptions } from './maps/mapStyle.js';
+export { refreshTokenOnUnauthorized } from './maps/mapToken.js';
+export type { MapTokenSource, MapTokens, TokenRefreshMap, } from './maps/mapToken.js';
 export { buildStaticMapUrl, fetchStaticMap, staticMapAccept, } from './maps/staticMap.js';
 export type { StaticMapFileName, StaticMapOptions } from './maps/staticMap.js';
 export { BUILDINGS, COLOR_SCHEMES, CONTOUR_DENSITIES, LABEL_SIZES, MAP_FEATURE_MODES, MAP_STYLES, POI_DENSITIES, SCALE_BAR_UNITS, SPRITE_VARIANTS, STATIC_MAP_STYLES, STYLE_POI_CATEGORIES, TERRAINS, TRAFFIC_MODES, TRAVEL_MODES, } from './maps/mapEnums.js';
 export type { Buildings, ColorScheme, ContourDensity, LabelSize, MapFeatureMode, MapStyle, PoiDensity, ScaleBarUnit, SpriteVariant, StaticMapStyle, StylePoiCategory, Terrain, TrafficMode, TravelMode, } from './maps/mapEnums.js';
 export { transformRequest } from './maps/Utils.js';
-export type { ClientConfig, GeoPlacesCommand, MapLike } from './types/index.js';
+export type { ClientConfig, CommandOutput, CommandWithOutput, GeoPlacesCommand, MapLike, } from './types/index.js';
 export type { AppConfigClaims } from './utils/tokenClaims.js';

package/dist/cjs/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.transformRequest = exports.TRAVEL_MODES = exports.TRAFFIC_MODES = exports.TERRAINS = exports.STYLE_POI_CATEGORIES = exports.STATIC_MAP_STYLES = exports.SPRITE_VARIANTS = exports.SCALE_BAR_UNITS = exports.POI_DENSITIES = exports.MAP_STYLES = exports.MAP_FEATURE_MODES = exports.LABEL_SIZES = exports.CONTOUR_DENSITIES = exports.COLOR_SCHEMES = exports.BUILDINGS = exports.staticMapAccept = exports.fetchStaticMap = exports.buildStaticMapUrl = exports.fetchMapStyle = exports.buildMapStyleUrl = exports.setPoiVisibility = exports.setAllPoiVisibility = exports.POI_CATEGORIES = exports.applyMapLanguage = exports.createTransformRequest = exports.GeoPlaces = exports.VerifyAddressCommand = exports.SuggestCommand = exports.SearchTextCommand = exports.SearchNearbyCommand = exports.ReverseGeocodeCommand = exports.GetPlaceCommand = exports.GeocodeCommand = exports.AutocompleteCommand = exports.LocationServiceException = exports.FEATURE_NOT_ENTITLED = exports.readTokenExpiry = exports.TOKEN_REFRESH_BUFFER_SECONDS = exports.DEFAULT_TIMEOUT_MS = exports.DEFAULT_OVERALL_TIMEOUT_MS = exports.DEFAULT_MAX_ATTEMPTS = exports.GeoPlacesClient = void 0;
+exports.transformRequest = exports.TRAVEL_MODES = exports.TRAFFIC_MODES = exports.TERRAINS = exports.STYLE_POI_CATEGORIES = exports.STATIC_MAP_STYLES = exports.SPRITE_VARIANTS = exports.SCALE_BAR_UNITS = exports.POI_DENSITIES = exports.MAP_STYLES = exports.MAP_FEATURE_MODES = exports.LABEL_SIZES = exports.CONTOUR_DENSITIES = exports.COLOR_SCHEMES = exports.BUILDINGS = exports.staticMapAccept = exports.fetchStaticMap = exports.buildStaticMapUrl = exports.refreshTokenOnUnauthorized = exports.fetchMapStyle = exports.buildMapStyleUrl = exports.setPoiVisibility = exports.setAllPoiVisibility = exports.POI_CATEGORIES = exports.applyMapLanguage = exports.createTransformRequest = exports.GeoPlaces = exports.VerifyAddressCommand = exports.SuggestCommand = exports.SearchTextCommand = exports.SearchNearbyCommand = exports.ReverseGeocodeCommand = exports.GetPlaceCommand = exports.GeocodeCommand = exports.AutocompleteCommand = exports.LocationServiceException = exports.FEATURE_NOT_ENTITLED = exports.readTokenExpiry = exports.TOKEN_REFRESH_BUFFER_SECONDS = exports.DEFAULT_TIMEOUT_MS = exports.DEFAULT_OVERALL_TIMEOUT_MS = exports.DEFAULT_MAX_ATTEMPTS = exports.GeoPlacesClient = void 0;
 // Client (Custom - uses our auth instead of AWS SigV4)
 var GeoPlacesClient_js_1 = require("./client/GeoPlacesClient.js");
 Object.defineProperty(exports, "GeoPlacesClient", { enumerable: true, get: function () { return GeoPlacesClient_js_1.GeoPlacesClient; } });
@@ -31,11 +31,16 @@ Object.defineProperty(exports, "readTokenExpiry", { enumerable: true, get: funct
 var LocationServiceException_js_1 = require("./errors/LocationServiceException.js");
 Object.defineProperty(exports, "FEATURE_NOT_ENTITLED", { enumerable: true, get: function () { return LocationServiceException_js_1.FEATURE_NOT_ENTITLED; } });
 Object.defineProperty(exports, "LocationServiceException", { enumerable: true, get: function () { return LocationServiceException_js_1.LocationServiceException; } });
-// Re-export AWS SDK commands and types
-__exportStar(require("@aws-sdk/client-geo-places"), exports);
-// …except the seven Places commands and their inputs, which take neither
-// IntendedUse nor Key: the service strips both from every request (#40). A
-// named export wins over the `export *` above, as GeoPlacesClient's does.
+// The AWS SDK's commands and types, and AWS Location Utilities' converters
+// (#42): generated into ./aws.ts, values by name and types by `export type *`.
+// Not `export *` of the packages themselves, which kept ~93 KB of SDK in the
+// bundle of a consumer importing only a map helper — scripts/sdk-exports.mjs
+// says why. A name this file exports itself is left out of ./aws.ts.
+__exportStar(require("./aws.js"), exports);
+// The seven Places commands and their inputs are this package's own: they take
+// neither IntendedUse nor Key, which the service strips from every request
+// (#40). A named export wins over `export *`, as GeoPlacesClient's does, and
+// ./aws.ts leaves them out.
 // VerifyAddressCommand is this package's own: its route has no SDK command (#54).
 var commands_js_1 = require("./client/commands.js");
 Object.defineProperty(exports, "AutocompleteCommand", { enumerable: true, get: function () { return commands_js_1.AutocompleteCommand; } });
@@ -46,8 +51,6 @@ Object.defineProperty(exports, "SearchNearbyCommand", { enumerable: true, get: f
 Object.defineProperty(exports, "SearchTextCommand", { enumerable: true, get: function () { return commands_js_1.SearchTextCommand; } });
 Object.defineProperty(exports, "SuggestCommand", { enumerable: true, get: function () { return commands_js_1.SuggestCommand; } });
 Object.defineProperty(exports, "VerifyAddressCommand", { enumerable: true, get: function () { return commands_js_1.VerifyAddressCommand; } });
-// Re-export AWS Location Utilities (data type conversions)
-__exportStar(require("@aws/amazon-location-utilities-datatypes"), exports);
 // Adapters (Custom - for MapLibre integration)
 var GeoPlaces_js_1 = require("./adapters/GeoPlaces.js");
 Object.defineProperty(exports, "GeoPlaces", { enumerable: true, get: function () { return GeoPlaces_js_1.GeoPlaces; } });
@@ -63,6 +66,8 @@ Object.defineProperty(exports, "setPoiVisibility", { enumerable: true, get: func
 var mapStyle_js_1 = require("./maps/mapStyle.js");
 Object.defineProperty(exports, "buildMapStyleUrl", { enumerable: true, get: function () { return mapStyle_js_1.buildMapStyleUrl; } });
 Object.defineProperty(exports, "fetchMapStyle", { enumerable: true, get: function () { return mapStyle_js_1.fetchMapStyle; } });
+var mapToken_js_1 = require("./maps/mapToken.js");
+Object.defineProperty(exports, "refreshTokenOnUnauthorized", { enumerable: true, get: function () { return mapToken_js_1.refreshTokenOnUnauthorized; } });
 var staticMap_js_1 = require("./maps/staticMap.js");
 Object.defineProperty(exports, "buildStaticMapUrl", { enumerable: true, get: function () { return staticMap_js_1.buildStaticMapUrl; } });
 Object.defineProperty(exports, "fetchStaticMap", { enumerable: true, get: function () { return staticMap_js_1.fetchStaticMap; } });

package/dist/cjs/maps/createTransformRequest.d.ts

@@ -1,4 +1,29 @@
 import type { RequestTransformFunction } from 'maplibre-gl';
+/**
+ * Does this URL belong to our API?
+ *
+ * This decides who receives the customer's bearer token, and it used to be
+ * `url.startsWith(apiUrl)` — a string test standing in for a URL test. For
+ * `apiUrl = "https://api.example.com"`, the host `api.example.com.evil.test`
+ * is a prefix match, so a style referencing
+ * `https://api.example.com.evil.test/tiles/1/2/3` was handed
+ * `Authorization: Bearer <token>` and the token left the building (#34).
+ *
+ * That is reachable because a style descriptor is DATA: its `sprite`, `glyphs`
+ * and `sources` entries are URLs the style author chose, and MapLibre asks
+ * transformRequest about every one of them. Any style not wholly ours — a
+ * customer's own, or one edited through a tool — can name a host it likes.
+ *
+ * Compared as URLs instead, which also gets host case-folding, default ports
+ * (`https://api.test:443` === `https://api.test`) and userinfo right for free,
+ * and adds a path check so a shared host serving another tenant under a
+ * different base path is not "ours" either.
+ *
+ * Fails CLOSED: anything that will not parse gets no token. The only way to
+ * reach that is a relative `apiUrl` in a runtime with no `location` to resolve
+ * it against — i.e. not a browser, which is the only place MapLibre runs.
+ */
+export declare function isOurApi(url: string, apiUrl: string): boolean;
 /**
  * Creates a transformRequest function for MapLibre that adds authentication
  * and proper Accept headers for AWS Location Service API requests.

package/dist/cjs/maps/createTransformRequest.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.isOurApi = isOurApi;
 exports.createTransformRequest = createTransformRequest;
 /**
  * Does this URL belong to our API?

package/dist/cjs/maps/mapPoi.d.ts

@@ -1,20 +1,25 @@
 import type { Map } from 'maplibre-gl';
 /**
  * Mapping of POI category names to their MapLibre layer IDs in AWS GeoMaps tiles.
- * Layer IDs are stable across Standard, Monochrome, and Hybrid map styles.
+ *
+ * Standard and Hybrid carry the same sixteen `poi*` layers; Monochrome carries
+ * only the three park layers, and Satellite none. A category whose layers a
+ * style does not carry is skipped. AWS publishes no list of these ids, so
+ * `test/map-poi-layers.test.ts` holds this map to each style's layers as the
+ * service served them: every `poi*` layer in exactly one category (#33).
  */
 export declare const POI_CATEGORIES: {
     readonly food_drink: readonly ["poi_100_food_drink"];
     readonly entertainment: readonly ["poi_200_going_out_entertainment"];
     readonly sights: readonly ["poi_300_sights_museums"];
-    readonly transit: readonly ["poi_400_transit"];
+    readonly transit: readonly ["poi_400_transit", "poi_400_transit_small"];
     readonly accommodations: readonly ["poi_500_accommodations"];
     readonly leisure: readonly ["poi_550_leisure_outdoor"];
     readonly shopping: readonly ["poi_600_shopping"];
-    readonly business: readonly ["poi_700_business_services"];
-    readonly facilities: readonly ["poi_800_facilities"];
+    readonly business: readonly ["poi_700_business_services", "poi_700_business_services_generic"];
+    readonly facilities: readonly ["poi_800_facilities", "poi_800_facilities_generic"];
     readonly areas: readonly ["poi_900_areas_buildings"];
-    readonly parks: readonly ["poi_landuse_park", "poi_landuse_public_complex"];
+    readonly parks: readonly ["poi_landuse_park", "poi_landuse_park_lowzoom", "poi_landuse_public_complex"];
 };
 export type PoiCategory = keyof typeof POI_CATEGORIES;
 /**

package/dist/cjs/maps/mapPoi.js

@@ -5,20 +5,29 @@ exports.setPoiVisibility = setPoiVisibility;
 exports.setAllPoiVisibility = setAllPoiVisibility;
 /**
  * Mapping of POI category names to their MapLibre layer IDs in AWS GeoMaps tiles.
- * Layer IDs are stable across Standard, Monochrome, and Hybrid map styles.
+ *
+ * Standard and Hybrid carry the same sixteen `poi*` layers; Monochrome carries
+ * only the three park layers, and Satellite none. A category whose layers a
+ * style does not carry is skipped. AWS publishes no list of these ids, so
+ * `test/map-poi-layers.test.ts` holds this map to each style's layers as the
+ * service served them: every `poi*` layer in exactly one category (#33).
  */
 exports.POI_CATEGORIES = {
     food_drink: ['poi_100_food_drink'],
     entertainment: ['poi_200_going_out_entertainment'],
     sights: ['poi_300_sights_museums'],
-    transit: ['poi_400_transit'],
+    transit: ['poi_400_transit', 'poi_400_transit_small'],
     accommodations: ['poi_500_accommodations'],
     leisure: ['poi_550_leisure_outdoor'],
     shopping: ['poi_600_shopping'],
-    business: ['poi_700_business_services'],
-    facilities: ['poi_800_facilities'],
+    business: ['poi_700_business_services', 'poi_700_business_services_generic'],
+    facilities: ['poi_800_facilities', 'poi_800_facilities_generic'],
     areas: ['poi_900_areas_buildings'],
-    parks: ['poi_landuse_park', 'poi_landuse_public_complex'],
+    parks: [
+        'poi_landuse_park',
+        'poi_landuse_park_lowzoom',
+        'poi_landuse_public_complex',
+    ],
 };
 /**
  * Set the visibility of one or more POI categories on the map.

package/dist/cjs/maps/mapStyle.d.ts

@@ -1,6 +1,7 @@
 import type { StyleSpecification } from 'maplibre-gl';
 import type { RequestOptions } from '../transport/http.js';
 import type { Buildings, ColorScheme, ContourDensity, MapStyle, PoiDensity, StylePoiCategory, Terrain, TrafficMode, TravelMode } from './mapEnums.js';
+import type { MapTokenSource } from './mapToken.js';
 /**
  * Options for building an AWS Location Service map style URL.
  * All parameters map directly to query parameters supported by the style descriptor endpoint.
@@ -137,10 +138,16 @@ export declare function buildMapStyleUrl(apiUrl: string, mapStyle: MapStyle, opt
  * `event.error.status` is 403, and `event.error.body` is a `Blob` holding the
  * same `{ message, code }` JSON.
  *
+ * A REFUSED TOKEN. Given `{ getToken, refreshToken }` in place of a bare
+ * `getToken`, a 401 asks `refreshToken` once and sends again when it brings a
+ * different token, within the same `signal` and `overallTimeoutMs` (#72). A
+ * 403 is never retried: a new token cannot change it.
+ *
  * @param apiUrl - Base URL of the Location Service API
  * @param mapStyle - Map style name: 'Standard' or 'Monochrome', or 'Satellite'
  *   or 'Hybrid', which need the `satellite` plan feature (see `MAP_STYLES`)
- * @param getToken - Callback returning the current auth token
+ * @param tokens - Callback returning the current auth token, or
+ *   `{ getToken, refreshToken }` to recover from a refused one
  * @param options - Style options; `language` is applied to the descriptor, all
  *   others become URL params. Those tagged `@planFeature` need that feature of
  *   the application's plan
@@ -151,6 +158,6 @@ export declare function buildMapStyleUrl(apiUrl: string, mapStyle: MapStyle, opt
  * const style = await fetchMapStyle(API_URL, 'Standard', getToken, { colorScheme: 'Dark', language: 'fr' })
  * const map = new maplibregl.Map({ style, transformRequest: createTransformRequest(API_URL, getToken) })
  */
-export declare function fetchMapStyle(apiUrl: string, mapStyle: MapStyle, getToken: () => string | undefined, options?: MapStyleOptions & {
+export declare function fetchMapStyle(apiUrl: string, mapStyle: MapStyle, tokens: MapTokenSource, options?: MapStyleOptions & {
     language?: string;
 }, request?: RequestOptions): Promise<StyleSpecification>;

package/dist/cjs/maps/mapStyle.js

@@ -2,9 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildMapStyleUrl = buildMapStyleUrl;
 exports.fetchMapStyle = fetchMapStyle;
-const errors_js_1 = require("../transport/errors.js");
 const http_js_1 = require("../transport/http.js");
 const mapLanguage_js_1 = require("./mapLanguage.js");
+const mapToken_js_1 = require("./mapToken.js");
 /**
  * Build a map style descriptor URL for the Location Service API.
  *
@@ -67,10 +67,16 @@ function buildMapStyleUrl(apiUrl, mapStyle, options = {}) {
  * `event.error.status` is 403, and `event.error.body` is a `Blob` holding the
  * same `{ message, code }` JSON.
  *
+ * A REFUSED TOKEN. Given `{ getToken, refreshToken }` in place of a bare
+ * `getToken`, a 401 asks `refreshToken` once and sends again when it brings a
+ * different token, within the same `signal` and `overallTimeoutMs` (#72). A
+ * 403 is never retried: a new token cannot change it.
+ *
  * @param apiUrl - Base URL of the Location Service API
  * @param mapStyle - Map style name: 'Standard' or 'Monochrome', or 'Satellite'
  *   or 'Hybrid', which need the `satellite` plan feature (see `MAP_STYLES`)
- * @param getToken - Callback returning the current auth token
+ * @param tokens - Callback returning the current auth token, or
+ *   `{ getToken, refreshToken }` to recover from a refused one
  * @param options - Style options; `language` is applied to the descriptor, all
  *   others become URL params. Those tagged `@planFeature` need that feature of
  *   the application's plan
@@ -81,16 +87,10 @@ function buildMapStyleUrl(apiUrl, mapStyle, options = {}) {
  * const style = await fetchMapStyle(API_URL, 'Standard', getToken, { colorScheme: 'Dark', language: 'fr' })
  * const map = new maplibregl.Map({ style, transformRequest: createTransformRequest(API_URL, getToken) })
  */
-async function fetchMapStyle(apiUrl, mapStyle, getToken, options = {}, request = {}) {
+async function fetchMapStyle(apiUrl, mapStyle, tokens, options = {}, request = {}) {
     const { language, ...styleOptions } = options;
     const url = buildMapStyleUrl(apiUrl, mapStyle, styleOptions);
-    const token = getToken();
-    // `Bearer undefined` used to go out here, and came back as a 401 the caller
-    // had to work backwards from — a whole round trip for a request that was
-    // never going to succeed (#37).
-    if (!token) {
-        throw (0, errors_js_1.noTokenAvailable)('getToken() returned nothing, so no style request was sent. Check the token provider has finished initialising.');
-    }
+    const call = (0, http_js_1.startCall)(request);
     // Through the shared transport, not a bare fetch: this gets the same
     // per-attempt timeout, overall budget, cancellation and retry as every other
     // call in the package, and the same error type on the way out. It also keeps
@@ -104,12 +104,16 @@ async function fetchMapStyle(apiUrl, mapStyle, getToken, options = {}, request =
     // This used to throw `Failed to fetch map style: 400`, discarding all of it
     // two lines before anyone could read it — the same defect #89 fixed in the
     // API, one layer up.
-    const style = await (0, http_js_1.requestJson)(url, {
+    //
+    // `Bearer undefined` used to go out here, and came back as a 401 the caller
+    // had to work backwards from — a whole round trip for a request that was
+    // never going to succeed (#37). `sendWithTokenRefresh` refuses first.
+    const style = await (0, mapToken_js_1.sendWithTokenRefresh)(tokens, 'getToken() returned nothing, so no style request was sent. Check the token provider has finished initialising.', call, (token) => (0, http_js_1.requestJson)(url, {
         headers: {
             Authorization: `Bearer ${token}`,
             Accept: 'application/json',
         },
-    }, request);
+    }, call));
     if (language) {
         applyLanguageToDescriptor(style, language);
     }

package/dist/cjs/maps/mapToken.d.ts

@@ -0,0 +1,87 @@
+import type { CallOptions } from '../transport/http.js';
+/**
+ * Where a map helper gets its token, and how it gets a new one (#72).
+ *
+ * `getToken` is synchronous by contract: MapLibre's `transformRequest` calls
+ * it for every tile and cannot wait. `refreshToken` is how a map recovers when
+ * the API refuses the token in hand before its `exp` — a rotated secret, for
+ * one — which nothing else in the map path can do. It is the escape hatch
+ * `GeoPlacesClient` takes, under the same name.
+ */
+export interface MapTokens {
+    /** The token in hand, now. */
+    getToken: () => string | undefined;
+    /** Obtain a new token after the API refused the one in hand. */
+    refreshToken?: () => Promise<string | undefined>;
+}
+/** A bare `getToken`, which behaves as it always has, or `MapTokens`. */
+export type MapTokenSource = (() => string | undefined) | MapTokens;
+/**
+ * Send with the token in hand, and after a 401 once more with a different one
+ * from `refreshToken`, all within the call's signal and deadline (#62). A 403
+ * is never retried, and neither is the token the API refused.
+ */
+export declare function sendWithTokenRefresh<T>(source: MapTokenSource, noTokenAdvice: string, call: CallOptions, send: (token: string) => Promise<T>): Promise<T>;
+/** A tile's coordinates, as `map.refreshTiles` takes them. */
+interface TileCoordinates {
+    x: number;
+    y: number;
+    z: number;
+}
+/** What MapLibre's `error` event carries for a refused request. */
+interface MapErrorEvent {
+    error?: {
+        status?: number;
+        url?: string;
+    };
+    sourceId?: string;
+    tile?: {
+        tileID: {
+            canonical: TileCoordinates;
+        };
+    };
+}
+/** The part of a MapLibre `Map` that `refreshTokenOnUnauthorized` uses. */
+export interface TokenRefreshMap {
+    on(type: 'error', listener: (event: MapErrorEvent) => void): unknown;
+    off(type: 'error', listener: (event: MapErrorEvent) => void): unknown;
+    refreshTiles(sourceId: string, tileIds?: TileCoordinates[]): void;
+}
+/**
+ * Recover the tiles MapLibre fetches itself when the API refuses the token
+ * (#72).
+ *
+ * `createTransformRequest` builds each request synchronously and never sees
+ * the answer, so a refused tile used to leave a hole until the page reloaded.
+ * This listens for MapLibre's `error` events. On a 401 from a URL of our API it
+ * asks `refreshToken` once for the whole burst. When `getToken` then returns a
+ * different token, it reloads each refused tile with `map.refreshTiles`, whose
+ * requests carry that token. So `refreshToken` must make `getToken` return
+ * what it obtained: the tiles have no other way to receive it. A refused
+ * request that is not a tile (a glyph, a sprite) has the token replaced for
+ * the next one, and nothing reloaded.
+ *
+ * Tiles are reloaded by id, never a whole source: MapLibre 6 reloads a source's
+ * errored tiles as still loading, and they wait for a load that never comes.
+ *
+ * What it learns is held as the fetch helpers hold it, and shared with them
+ * when they are handed the same `tokens` object (#38): a token `refreshToken`
+ * could not replace, a token it brought that the API refused on a tile
+ * reloaded with it, and a failure that says when to ask again, are not asked
+ * about again until they lapse or the token in hand changes. While the token
+ * a refresh brought is in hand, any other refused tile is reloaded once with
+ * it, without asking.
+ *
+ * Returns a function that stops listening.
+ *
+ * @example
+ * const tokens = { getToken, refreshToken }
+ * const map = new Map({
+ *   container: 'map',
+ *   style: await fetchMapStyle(API_URL, 'Standard', tokens),
+ *   transformRequest: createTransformRequest(API_URL, getToken),
+ * })
+ * refreshTokenOnUnauthorized(map, API_URL, tokens)
+ */
+export declare function refreshTokenOnUnauthorized(map: TokenRefreshMap, apiUrl: string, tokens: Required<MapTokens>): () => void;
+export {};