@chaosity/location-client 0.11.0 → 0.13.0

package/dist/maps/mapPoi.js

@@ -1,19 +1,28 @@
 /**
  * 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 const 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/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/maps/mapStyle.js

@@ -1,6 +1,6 @@
-import { noTokenAvailable } from '../transport/errors.js';
-import { requestJson } from '../transport/http.js';
+import { requestJson, startCall } from '../transport/http.js';
 import { labelsByName, languageExpression } from './mapLanguage.js';
+import { sendWithTokenRefresh } from './mapToken.js';
 /**
  * Build a map style descriptor URL for the Location Service API.
  *
@@ -63,10 +63,16 @@ export 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
@@ -77,16 +83,10 @@ export 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) })
  */
-export async function fetchMapStyle(apiUrl, mapStyle, getToken, options = {}, request = {}) {
+export 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 noTokenAvailable('getToken() returned nothing, so no style request was sent. Check the token provider has finished initialising.');
-    }
+    const call = 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
@@ -100,12 +100,16 @@ export async function fetchMapStyle(apiUrl, mapStyle, getToken, options = {}, re
     // 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 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 sendWithTokenRefresh(tokens, 'getToken() returned nothing, so no style request was sent. Check the token provider has finished initialising.', call, (token) => requestJson(url, {
         headers: {
             Authorization: `Bearer ${token}`,
             Accept: 'application/json',
         },
-    }, request);
+    }, call));
     if (language) {
         applyLanguageToDescriptor(style, language);
     }

package/dist/maps/mapToken.d.ts

@@ -0,0 +1,84 @@
+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, and a failure that says when to ask again, are not asked
+ * about again until they lapse or the token in hand changes.
+ *
+ * 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 {};

package/dist/maps/mapToken.js

@@ -0,0 +1,122 @@
+import { TokenHold, holdFor, sendRetryingOnce } from '../auth/tokenHold.js';
+import { LocationServiceException } from '../errors/LocationServiceException.js';
+import { noTokenAvailable } from '../transport/errors.js';
+import { withinCall } from '../transport/http.js';
+import { isOurApi } from './createTransformRequest.js';
+/**
+ * One hold per `MapTokens` object, so the helpers handed the same one share
+ * what the API and `refreshToken` said (#38): a refusal one of them met is not
+ * asked again by the next. A bare `getToken` never asks again, and needs none.
+ */
+const holds = new WeakMap();
+function holdOf(tokens) {
+    let hold = holds.get(tokens);
+    if (!hold)
+        holds.set(tokens, (hold = new TokenHold()));
+    return hold;
+}
+/**
+ * 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 async function sendWithTokenRefresh(source, noTokenAdvice, call, send) {
+    const tokens = typeof source === 'function' ? { getToken: source } : source;
+    const token = tokens.getToken();
+    if (!token)
+        throw noTokenAvailable(noTokenAdvice);
+    const { refreshToken } = tokens;
+    if (!refreshToken)
+        return send(token);
+    return sendRetryingOnce(holdOf(tokens), token, send, async () => (await withinCall(refreshToken(), call)) ?? tokens.getToken());
+}
+/**
+ * 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, and a failure that says when to ask again, are not asked
+ * about again until they lapse or the token in hand changes.
+ *
+ * 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 function refreshTokenOnUnauthorized(map, apiUrl, tokens) {
+    const hold = holdOf(tokens);
+    // Each source's refused tiles, keyed `z/x/y` so a tile refused twice is
+    // reloaded once.
+    const refused = new Map();
+    let asking = false;
+    const onError = ({ error, sourceId, tile }) => {
+        if (error?.status !== 401 || !error.url || !isOurApi(error.url, apiUrl))
+            return;
+        if (sourceId && tile) {
+            const { x, y, z } = tile.tileID.canonical;
+            const tiles = refused.get(sourceId) ?? new Map();
+            refused.set(sourceId, tiles.set(`${z}/${x}/${y}`, { x, y, z }));
+        }
+        if (asking)
+            return;
+        const inHand = tokens.getToken();
+        const held = hold.check(inHand);
+        if (held && !held.askAgain)
+            return;
+        asking = true;
+        // Asked inside an executor, so a `refreshToken` that throws instead of
+        // rejecting lands in the catch below rather than in MapLibre's emitter.
+        new Promise((resolve) => resolve(tokens.refreshToken()))
+            .then(() => {
+            // A reloaded tile takes its token from `getToken`, as every tile does,
+            // so that is the token that must have changed. Reloading on what
+            // `refreshToken` returned alone would send the refused one again, and
+            // its 401 would ask again: a loop of refreshes and reloads.
+            const now = tokens.getToken();
+            if (!now || now === inHand) {
+                // MapLibre's error carries none of the API's fields, so the refusal
+                // is remembered as the 401 it was.
+                hold.remember(new LocationServiceException({
+                    code: 'UnauthorizedException',
+                    message: 'The API refused the token, and getToken has no other since refreshToken settled.',
+                    statusCode: 401,
+                }), inHand);
+                return;
+            }
+            for (const [id, tiles] of refused)
+                map.refreshTiles(id, [...tiles.values()]);
+        })
+            .catch((refusal) => {
+            // Only a failure that says when to ask again is remembered; any other
+            // leaves the next refused tile to ask, as the send paths do.
+            if (holdFor(refusal) > 0)
+                hold.remember(refusal, inHand);
+        })
+            .finally(() => {
+            refused.clear();
+            asking = false;
+        });
+    };
+    map.on('error', onError);
+    return () => map.off('error', onError);
+}

package/dist/maps/staticMap.d.ts

@@ -1,5 +1,6 @@
 import type { RequestOptions } from '../transport/http.js';
 import type { ColorScheme, LabelSize, MapFeatureMode, ScaleBarUnit, StaticMapStyle } from './mapEnums.js';
+import type { MapTokenSource } from './mapToken.js';
 /**
  * Static maps: build the URL, send the right headers, get a Blob.
  *
@@ -110,11 +111,14 @@ export declare function buildStaticMapUrl(apiUrl: string, options: StaticMapOpti
  *
  * A refused plan feature — a Satellite `style`, the default when none is
  * given, or a `politicalView` — rejects with a `LocationServiceException`
- * whose `isFeatureNotEntitled` is true, as `fetchMapStyle` does.
+ * whose `isFeatureNotEntitled` is true, as `fetchMapStyle` does. Given
+ * `{ getToken, refreshToken }`, a refused token is replaced once, as
+ * `fetchMapStyle` does it (#72).
  *
  * @param apiUrl   Base URL of the Location Service API
  * @param options  Render options; exactly one of center / boundingBox / boundedPositions
- * @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 request  Transport options: `signal` to cancel, `timeoutMs`, `overallTimeoutMs`, `retry`
  *
  * @example
@@ -124,4 +128,4 @@ export declare function buildStaticMapUrl(apiUrl: string, options: StaticMapOpti
  * }, getToken)
  * const url = URL.createObjectURL(blob)   // remember to revokeObjectURL
  */
-export declare function fetchStaticMap(apiUrl: string, options: StaticMapOptions, getToken: () => string | undefined, request?: RequestOptions): Promise<Blob>;
+export declare function fetchStaticMap(apiUrl: string, options: StaticMapOptions, tokens: MapTokenSource, request?: RequestOptions): Promise<Blob>;

package/dist/maps/staticMap.js

@@ -1,5 +1,5 @@
-import { noTokenAvailable } from '../transport/errors.js';
-import { requestBlob } from '../transport/http.js';
+import { requestBlob, startCall } from '../transport/http.js';
+import { sendWithTokenRefresh } from './mapToken.js';
 /**
  * The Accept header this request must send.
  *
@@ -50,11 +50,14 @@ export function buildStaticMapUrl(apiUrl, options) {
  *
  * A refused plan feature — a Satellite `style`, the default when none is
  * given, or a `politicalView` — rejects with a `LocationServiceException`
- * whose `isFeatureNotEntitled` is true, as `fetchMapStyle` does.
+ * whose `isFeatureNotEntitled` is true, as `fetchMapStyle` does. Given
+ * `{ getToken, refreshToken }`, a refused token is replaced once, as
+ * `fetchMapStyle` does it (#72).
  *
  * @param apiUrl   Base URL of the Location Service API
  * @param options  Render options; exactly one of center / boundingBox / boundedPositions
- * @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 request  Transport options: `signal` to cancel, `timeoutMs`, `overallTimeoutMs`, `retry`
  *
  * @example
@@ -64,23 +67,21 @@ export function buildStaticMapUrl(apiUrl, options) {
  * }, getToken)
  * const url = URL.createObjectURL(blob)   // remember to revokeObjectURL
  */
-export async function fetchStaticMap(apiUrl, options, getToken, request = {}) {
-    const token = getToken();
-    // The same guard as fetchMapStyle and the server connector: a render is not
-    // worth requesting without a token to send (#37).
-    if (!token) {
-        throw noTokenAvailable('getToken() returned nothing, so no static map was requested. Check the token provider has finished initialising.');
-    }
+export async function fetchStaticMap(apiUrl, options, tokens, request = {}) {
+    const call = startCall(request);
     // Through the shared transport, so a static map gets the timeout, budget,
     // cancellation and retry every other call has -- and its failures arrive as
     // LocationServiceException rather than as a raw TypeError. The API's own
     // {message, code, requestId} survives, which matters here: the messages are
     // specific and actionable -- "'width' and 'height' are required", "Only one
     // of center, bounding-box or bounded-positions may be set".
-    return requestBlob(buildStaticMapUrl(apiUrl, options), {
+    //
+    // The same guard as fetchMapStyle and the server connector: a render is not
+    // worth requesting without a token to send (#37).
+    return sendWithTokenRefresh(tokens, 'getToken() returned nothing, so no static map was requested. Check the token provider has finished initialising.', call, (token) => requestBlob(buildStaticMapUrl(apiUrl, options), {
         headers: {
             Authorization: `Bearer ${token}`,
             Accept: staticMapAccept(options.style),
         },
-    }, request);
+    }, call));
 }

package/dist/server/LocationServiceConnector.d.ts

@@ -1,5 +1,7 @@
+import type { GetTokenOptions } from '../auth/TokenProvider.js';
 import type { VerifyAddressResponse } from '../client/commands.js';
 import type { RequestOptions } from '../transport/http.js';
+import type { CommandOutput, CommandWithOutput } from '../types/index.js';
 import type { AppConfigClaims } from '../utils/tokenClaims.js';
 export interface ConnectorConfig {
     /** Falls back to `LOCATION_API_URL` / `LOCATION_SERVICE_API_URL`. */
@@ -14,10 +16,13 @@ export interface ConnectorConfig {
      * a long-lived connector survive expiry.
      *
      * `forceRefresh` is passed as `true` when the API has just rejected the token
-     * this returned — the signature is `TokenProvider.getToken`'s exactly, so
-     * `getToken: (f) => provider.getToken(f)` is a complete implementation.
+     * this returned, and `options` always asks for `cachedUntilExpiry` (#63): a
+     * source that can keep sending its cached token through a throttled refresh
+     * should, since a connector's token never reaches a browser. The signature
+     * is `TokenProvider.getToken`'s, so
+     * `getToken: (f, o) => provider.getToken(f, o)` is a complete implementation.
      */
-    getToken?: (forceRefresh?: boolean) => Promise<string | {
+    getToken?: (forceRefresh?: boolean, options?: GetTokenOptions) => Promise<string | {
         token?: string;
     } | undefined>;
     /** Falls back to `LOCATION_CLIENT_ID` / `LOCATION_SERVICE_CLIENT_ID`. */
@@ -70,6 +75,8 @@ export declare class LocationServiceConnector {
     private readonly config;
     private tokenSource?;
     private readonly origin?;
+    /** A token the API refused, and why, until the hold lapses (#38). */
+    private readonly refused;
     readonly serviceId: string;
     constructor(config?: ConnectorConfig);
     /**
@@ -107,6 +114,16 @@ export declare class LocationServiceConnector {
      * header beats the connector default, whatever the caller capitalised.
      */
     private effectiveOrigin;
+    /**
+     * Send a command, and resolve with its output:
+     * `await connector.send(new SearchTextCommand(…))` is a
+     * `SearchTextCommandOutput`, with nothing to annotate (#68).
+     */
+    send<C extends CommandWithOutput>(command: C, options?: SendOptions): Promise<CommandOutput<C>>;
+    /**
+     * The signature `send` had before it inferred its output (#68), kept for
+     * calls naming both type arguments, as `GeoPlacesClient.send` keeps it.
+     */
     send<TInput, TOutput>(command: TInput, options?: SendOptions): Promise<TOutput>;
     /**
      * Verify a PlaceId: `send(new VerifyAddressCommand({ PlaceId }))`, typed

package/dist/server/LocationServiceConnector.js

@@ -1,9 +1,10 @@
 import debug from 'debug';
+import { TokenHold, sendRetryingOnce } from '../auth/tokenHold.js';
 import { VerifyAddressCommand } from '../client/commands.js';
 import { LocationServiceException } from '../errors/LocationServiceException.js';
 import { resolveEndpoint } from '../transport/endpoints.js';
-import { isTokenRejected, noTokenAvailable } from '../transport/errors.js';
-import { requestJson } from '../transport/http.js';
+import { noTokenAvailable } from '../transport/errors.js';
+import { requestJson, startCall, withinCall } from '../transport/http.js';
 import { readAppConfigClaims } from '../utils/tokenClaims.js';
 import { resolveApiUrl, serverTokenSource } from './getClientConfig.js';
 const log = debug('location-client:connector');
@@ -100,6 +101,8 @@ function explainMissingOrigin(err, sentOrigin) {
  */
 export class LocationServiceConnector {
     constructor(config = {}) {
+        /** A token the API refused, and why, until the hold lapses (#38). */
+        this.refused = new TokenHold();
         this.serviceId = 'Geo Places';
         this.config = config;
         // `||`, not `??`, to match the other four env-completed fields: an empty
@@ -131,7 +134,10 @@ export class LocationServiceConnector {
             return {
                 apiUrl: () => requireApiUrl(apiUrl),
                 get: async (forceRefresh) => {
-                    const result = await getToken(forceRefresh);
+                    // As the environment source below asks its provider (#63).
+                    const result = await getToken(forceRefresh, {
+                        cachedUntilExpiry: true,
+                    });
                     if (!result)
                         return undefined;
                     return typeof result === 'string' ? result : result.token;
@@ -153,7 +159,9 @@ export class LocationServiceConnector {
             // Already validated by serverTokenSource, which cannot resolve
             // credentials without it.
             apiUrl: () => env.apiUrl,
-            get: async (forceRefresh) => (await env.getToken(forceRefresh)).token,
+            // A throttled refresh keeps the cached token in use until its own exp
+            // (#63): this is a server dispatch, never a token handed to a browser.
+            get: async (forceRefresh) => (await env.getToken(forceRefresh, { cachedUntilExpiry: true })).token,
         };
     }
     /**
@@ -191,8 +199,11 @@ export class LocationServiceConnector {
         const source = this.source();
         const cmd = command;
         const url = `${source.apiUrl()}${resolveEndpoint(cmd)}`;
+        // The call's deadline starts here, before the token is waited for, so the
+        // caller's `overallTimeoutMs` and `signal` bound the whole call (#62).
+        const call = startCall(options);
         try {
-            return await this.dispatchWithRetry(source, url, cmd, options);
+            return await this.dispatchWithRetry(source, url, cmd, call);
         }
         catch (err) {
             throw explainMissingOrigin(err, this.effectiveOrigin(options));
@@ -210,27 +221,14 @@ export class LocationServiceConnector {
         return this.send(new VerifyAddressCommand({ PlaceId: placeId }), options);
     }
     async dispatchWithRetry(source, url, cmd, options) {
-        const token = await source.get();
+        // Raced against the caller's signal and deadline, not given them: the
+        // token fetch may be shared with other calls (#62).
+        const token = await withinCall(source.get(), options);
         if (!token)
             throw noTokenAvailable(NO_TOKEN_ADVICE);
-        try {
-            return await this.dispatch(url, token, cmd, options);
-        }
-        catch (err) {
-            if (!isTokenRejected(err))
-                throw err;
-            // One retry, and only when the replacement is genuinely a different
-            // token. That single comparison covers every source: a fixed `token`
-            // string, a caller `getToken` that ignores `forceRefresh`, and a cached
-            // token the API has revoked before its `exp` all hand back what we
-            // already sent — and re-sending it would be a second doomed request for
-            // the same answer.
-            const fresh = await source.get(true);
-            if (!fresh || fresh === token)
-                throw err;
-            log('401 on a token the API no longer accepts — retrying once, refreshed');
-            return await this.dispatch(url, fresh, cmd, options);
-        }
+        // Through `sendRetryingOnce`, like every 401 retry here (#38). The forced
+        // refresh is raced against the caller as the first ask was (#62).
+        return sendRetryingOnce(this.refused, token, (t) => this.dispatch(url, t, cmd, options), () => withinCall(source.get(true), options), () => log('401 on a token the API no longer accepts — retrying once, refreshed'));
     }
     dispatch(url, token, cmd, options) {
         // The caller's input goes out as the caller wrote it — nothing in the body

package/dist/server/getClientConfig.d.ts

@@ -1,4 +1,4 @@
-import type { TokenResponse } from '../auth/TokenProvider.js';
+import type { GetTokenOptions, TokenResponse } from '../auth/TokenProvider.js';
 import type { ClientConfig } from '../types/index.js';
 export interface ServerAuthConfig {
     apiUrl?: string;
@@ -60,8 +60,12 @@ export declare function resolveApiUrl(explicit?: string): string | undefined;
  */
 export interface ServerTokenSource {
     apiUrl: string;
-    /** Resolves with a token or rejects; it never resolves tokenless. */
-    getToken(forceRefresh?: boolean): Promise<TokenResponse & {
+    /**
+     * Resolves with a token or rejects; it never resolves tokenless. The options
+     * are `TokenProvider.getToken`'s: the connector asks for `cachedUntilExpiry`
+     * (#63), and `getClientConfig` never does.
+     */
+    getToken(forceRefresh?: boolean, options?: GetTokenOptions): Promise<TokenResponse & {
         token: string;
     }>;
 }
@@ -104,8 +108,9 @@ export declare function serverTokenSource(config?: ServerAuthConfig): ServerToke
  * // Auto-detect from environment
  * const config = await getClientConfig()
  *
- * // Or override specific values
- * const config = await getClientConfig({ apiUrl: 'https://custom.api.com' })
+ * // Or override specific values — the API URL is the one on the
+ * // application's page in the developer portal
+ * const config = await getClientConfig({ apiUrl: 'https://your-api-url.example' })
  *
  * // The API rejected the token before its exp — revoked, or secret rotated
  * const fresh = await getClientConfig({ forceRefresh: true })