@chaosity/location-client 0.12.0 → 0.13.0

package/dist/cjs/maps/staticMap.js

@@ -3,8 +3,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.staticMapAccept = staticMapAccept;
 exports.buildStaticMapUrl = buildStaticMapUrl;
 exports.fetchStaticMap = fetchStaticMap;
-const errors_js_1 = require("../transport/errors.js");
 const http_js_1 = require("../transport/http.js");
+const mapToken_js_1 = require("./mapToken.js");
 /**
  * The Accept header this request must send.
  *
@@ -55,11 +55,14 @@ 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
@@ -69,23 +72,21 @@ function buildStaticMapUrl(apiUrl, options) {
  * }, getToken)
  * const url = URL.createObjectURL(blob)   // remember to revokeObjectURL
  */
-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 (0, errors_js_1.noTokenAvailable)('getToken() returned nothing, so no static map was requested. Check the token provider has finished initialising.');
-    }
+async function fetchStaticMap(apiUrl, options, tokens, request = {}) {
+    const call = (0, http_js_1.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 (0, http_js_1.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 (0, mapToken_js_1.sendWithTokenRefresh)(tokens, 'getToken() returned nothing, so no static map was requested. Check the token provider has finished initialising.', call, (token) => (0, http_js_1.requestBlob)(buildStaticMapUrl(apiUrl, options), {
         headers: {
             Authorization: `Bearer ${token}`,
             Accept: staticMapAccept(options.style),
         },
-    }, request);
+    }, call));
 }

package/dist/cjs/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`. */
@@ -109,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/cjs/server/LocationServiceConnector.js

@@ -140,7 +140,10 @@ 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;
@@ -162,7 +165,9 @@ 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,
         };
     }
     /**
@@ -200,8 +205,11 @@ class LocationServiceConnector {
         const source = this.source();
         const cmd = command;
         const url = `${source.apiUrl()}${(0, endpoints_js_1.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 = (0, http_js_1.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));
@@ -219,63 +227,14 @@ class LocationServiceConnector {
         return this.send(new commands_js_1.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 (0, http_js_1.withinCall)(source.get(), options);
         if (!token)
             throw (0, errors_js_1.noTokenAvailable)(NO_TOKEN_ADVICE);
-        // This token was refused a moment ago and nothing has replaced it: answer
-        // with that refusal rather than send it, and force the source, again (#38).
-        // A different token from the source 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 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.
-        let fresh;
-        try {
-            fresh = await source.get(true);
-        }
-        catch (refusal) {
-            // A suspended application's /auth/token refuses it as its data routes
-            // refuse its token. Without this, every send asked for another. A
-            // refusal that says nothing — a network fault — 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;
-        }
-        if (!fresh || fresh === token) {
-            this.refused.remember(rejected, token);
-            throw rejected;
-        }
-        log('401 on a token the API no longer accepts — retrying once, refreshed');
-        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;
-        }
+        // Through `sendRetryingOnce`, like every 401 retry here (#38). The forced
+        // refresh is raced against the caller as the first ask was (#62).
+        return (0, tokenHold_js_1.sendRetryingOnce)(this.refused, token, (t) => this.dispatch(url, t, cmd, options), () => (0, http_js_1.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/cjs/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;
     }>;
 }

package/dist/cjs/server/getClientConfig.js

@@ -84,10 +84,10 @@ function resolveApiUrl(explicit) {
  *
  * Two answers qualify. `/auth/token`'s own `Invalid credentials` is a secret
  * that matched nothing. The gateway's 401 (`UnauthorizedException`) is the
- * authorizer refusing the Basic pair before `/auth/token` runs, and it gives
- * the same answer for a wrong secret and for an application that is not
- * active, so the advice for it names both. `Application is not active`, and
- * every 403, is left as the API wrote it.
+ * authorizer refusing the Basic pair before `/auth/token` runs. An application
+ * that is not active is a 403 (`ApplicationNotActiveException`) on either
+ * path, whose sentence names its cause, and it is left as the API wrote it,
+ * like every 403.
  */
 function isCredentialsRefusal(error) {
     if (!(error instanceof LocationServiceException_js_1.LocationServiceException))
@@ -99,11 +99,8 @@ function isCredentialsRefusal(error) {
 }
 /** The API's words as a sentence, so the advice can follow them. */
 const sentence = (text) => (/[.!?]$/.test(text) ? text : `${text}.`);
-function credentialsAdvice(clientId, error) {
-    const check = `Check that LOCATION_CLIENT_ID ("${clientId}") and LOCATION_CLIENT_SECRET match your application in the developer portal`;
-    return error.code === 'UnauthorizedException'
-        ? `${check}, and that the application is active there.`
-        : `${check}.`;
+function credentialsAdvice(clientId) {
+    return `Check that LOCATION_CLIENT_ID ("${clientId}") and LOCATION_CLIENT_SECRET match your application in the developer portal.`;
 }
 function serverTokenSource(config = {}) {
     log('[serverTokenSource] Starting with config:', {
@@ -139,11 +136,11 @@ function serverTokenSource(config = {}) {
     const provider = getTokenProvider(apiUrl, clientId, clientSecret);
     return {
         apiUrl,
-        async getToken(forceRefresh = false) {
+        async getToken(forceRefresh = false, options) {
             log('[serverTokenSource] Fetching token (forceRefresh=%s)', forceRefresh);
             let result;
             try {
-                result = await provider.getToken(forceRefresh);
+                result = await provider.getToken(forceRefresh, options);
             }
             catch (error) {
                 // The API's code and sentence, passed through (#38). Every 401 and 403
@@ -153,7 +150,7 @@ function serverTokenSource(config = {}) {
                 if (isCredentialsRefusal(error)) {
                     throw new LocationServiceException_js_1.LocationServiceException({
                         code: error.code,
-                        message: `${sentence(error.message)} ${credentialsAdvice(clientId, error)}`,
+                        message: `${sentence(error.message)} ${credentialsAdvice(clientId)}`,
                         statusCode: error.statusCode,
                         requestId: error.requestId,
                         details: error.details,

package/dist/cjs/server/index.d.ts

@@ -1,5 +1,5 @@
 export { TokenProvider } from '../auth/TokenProvider.js';
-export type { TokenProviderConfig, TokenResponse, } from '../auth/TokenProvider.js';
+export type { GetTokenOptions, TokenProviderConfig, TokenResponse, } from '../auth/TokenProvider.js';
 export { getClientConfig } from './getClientConfig.js';
 export type { ServerAuthConfig, ServerClientConfig } from './getClientConfig.js';
 export { LocationServiceConnector } from './LocationServiceConnector.js';

package/dist/cjs/transport/http.d.ts

@@ -38,6 +38,24 @@ export interface RequestOptions {
         maxAttempts?: number;
     };
 }
+/**
+ * A call's options once it has begun: `deadline` is when `overallTimeoutMs`
+ * runs out, fixed at the call's entry, so that a wait before the request — a
+ * token — spends the same budget the request then gets the rest of (#62).
+ */
+export interface CallOptions extends RequestOptions {
+    deadline: number;
+}
+/** Fix a call's deadline at its entry (#62). */
+export declare function startCall<T extends RequestOptions>(options?: T): T & CallOptions;
+/**
+ * Wait for `work` within the call: reject with `AbortedException` when the
+ * caller's signal aborts, and with `TimeoutException` when its deadline
+ * passes, whichever comes first (#62). `work` itself is left running, because
+ * it may be shared: one caller's abort must not fail another waiting on the
+ * same token fetch.
+ */
+export declare function withinCall<T>(work: Promise<T>, call: CallOptions): Promise<T>;
 /** Exponential backoff with FULL jitter, so retries never march in lockstep. */
 export declare function backoffMs(attempt: number, random?: () => number): number;
 /**

package/dist/cjs/transport/http.js

@@ -4,6 +4,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_MAX_ATTEMPTS = exports.DEFAULT_OVERALL_TIMEOUT_MS = exports.DEFAULT_TIMEOUT_MS = void 0;
+exports.startCall = startCall;
+exports.withinCall = withinCall;
 exports.backoffMs = backoffMs;
 exports.requestJson = requestJson;
 exports.requestBlob = requestBlob;
@@ -34,6 +36,40 @@ exports.DEFAULT_OVERALL_TIMEOUT_MS = 30000;
 exports.DEFAULT_MAX_ATTEMPTS = 3;
 const BACKOFF_BASE_MS = 250;
 const BACKOFF_CAP_MS = 4000;
+/** Fix a call's deadline at its entry (#62). */
+function startCall(options = {}) {
+    return {
+        ...options,
+        deadline: Date.now() + (options.overallTimeoutMs ?? exports.DEFAULT_OVERALL_TIMEOUT_MS),
+    };
+}
+/**
+ * Wait for `work` within the call: reject with `AbortedException` when the
+ * caller's signal aborts, and with `TimeoutException` when its deadline
+ * passes, whichever comes first (#62). `work` itself is left running, because
+ * it may be shared: one caller's abort must not fail another waiting on the
+ * same token fetch.
+ */
+function withinCall(work, call) {
+    const { signal, deadline } = call;
+    const overallTimeoutMs = call.overallTimeoutMs ?? exports.DEFAULT_OVERALL_TIMEOUT_MS;
+    if (signal?.aborted)
+        return Promise.reject(abortedException(signal));
+    const left = deadline - Date.now();
+    if (left <= 0)
+        return Promise.reject(overallTimeoutException(overallTimeoutMs));
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => finish(() => reject(overallTimeoutException(overallTimeoutMs))), left);
+        const onAbort = () => finish(() => reject(abortedException(signal)));
+        signal?.addEventListener('abort', onAbort, { once: true });
+        function finish(settle) {
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', onAbort);
+            settle();
+        }
+        work.then((value) => finish(() => resolve(value)), (error) => finish(() => reject(error)));
+    });
+}
 /**
  * Combine the caller's signal with a per-attempt timeout.
  *
@@ -115,7 +151,9 @@ async function request(url, init, options, read) {
             details: { source: 'client' },
         });
     }
-    const deadline = Date.now() + overallTimeoutMs;
+    // A call that began before this request (#62) brings its own deadline, so
+    // the request has only what the wait before it left.
+    const deadline = options.deadline ?? Date.now() + overallTimeoutMs;
     let lastError;
     for (let attempt = 0; attempt < maxAttempts; attempt++) {
         // Checked before every attempt: a signal aborted during backoff must not fire one more.

package/dist/cjs/types/index.d.ts

@@ -1,3 +1,4 @@
+import type { VerifyAddressCommand, VerifyAddressResponse } from '../client/commands.js';
 /**
  * At least one of `token`, `getToken` or `refreshToken` must supply a token, or
  * `send` refuses locally with `InvalidCredentialsException` rather than putting
@@ -52,6 +53,30 @@ export interface ClientConfig {
 export interface GeoPlacesCommand {
     readonly input: object;
 }
+/**
+ * The part of an AWS SDK command that carries its output type: the request
+ * handler its `resolveMiddleware` builds resolves with `{ output }`. The SDK's
+ * own `send` reads the output from the command the same way.
+ */
+interface SdkCommandOutputs<O extends object = object> {
+    resolveMiddleware(...args: never[]): (...args: never[]) => Promise<{
+        output: O;
+    }>;
+}
+/**
+ * A command whose output `send` can name (#68): every SDK command, this
+ * package's narrowed Places commands among them, and `VerifyAddressCommand`.
+ */
+export type CommandWithOutput = SdkCommandOutputs | VerifyAddressCommand;
+/**
+ * What `send` resolves with for a command (#68): an SDK command's own
+ * `…CommandOutput`, and `VerifyAddressResponse` for `VerifyAddressCommand`,
+ * which is this package's and has no handler.
+ *
+ * @example
+ * type Out = CommandOutput<AutocompleteCommand> // AutocompleteCommandOutput
+ */
+export type CommandOutput<C extends CommandWithOutput> = C extends SdkCommandOutputs<infer O> ? O : VerifyAddressResponse;
 /**
  * Minimal interface for a MapLibre Map instance.
  * Using a structural type avoids hard coupling to a specific maplibre-gl version.
@@ -69,3 +94,4 @@ export interface MapLike {
     getLayoutProperty(layerId: string, name: string): unknown;
     setLayoutProperty(layerId: string, name: string, value: unknown): void;
 }
+export {};

package/dist/client/GeoPlacesClient.d.ts

@@ -1,5 +1,5 @@
 import type { RequestOptions } from '../transport/http.js';
-import type { ClientConfig } from '../types/index.js';
+import type { ClientConfig, CommandOutput, CommandWithOutput } from '../types/index.js';
 import type { AppConfigClaims } from '../utils/tokenClaims.js';
 import type { VerifyAddressResponse } from './commands.js';
 export type SendOptions = RequestOptions;
@@ -40,6 +40,11 @@ export declare class GeoPlacesClient {
     getAppConfig(): AppConfigClaims;
     /** Prefer the getToken callback (live ref) over a static token string. */
     private currentToken;
+    /**
+     * `refreshToken`, held to the caller's signal and deadline (#62). A slow or
+     * stuck callback used to hold `send` past both.
+     */
+    private askRefreshToken;
     /**
      * A token to send, or a refusal — never `undefined`.
      *
@@ -48,10 +53,21 @@ export declare class GeoPlacesClient {
      */
     private ensureToken;
     /**
+     * Send a command, and resolve with its output:
+     * `await client.send(new AutocompleteCommand(…))` is an
+     * `AutocompleteCommandOutput`, with nothing to annotate (#68).
+     *
      * @param options `signal` to cancel, `timeoutMs` per attempt,
      *   `overallTimeoutMs` for the whole call, `retry: false` to disable the
      *   retry loop. Every failure throws LocationServiceException.
      */
+    send<C extends CommandWithOutput>(command: C, options?: SendOptions): Promise<CommandOutput<C>>;
+    /**
+     * The signature `send` had before it inferred its output (#68). It stays
+     * so that a call naming both type arguments, and a client typed by a
+     * structural `send<TInput, TOutput>` — as `@chaosity/address-form` types
+     * its client — still compile.
+     */
     send<TInput, TOutput>(command: TInput, options?: SendOptions): Promise<TOutput>;
     /**
      * Verify a PlaceId: `send(new VerifyAddressCommand({ PlaceId }))`, typed

package/dist/client/GeoPlacesClient.js

@@ -1,8 +1,8 @@
 import debug from 'debug';
-import { TokenHold, holdFor } from '../auth/tokenHold.js';
+import { TokenHold, sendRetryingOnce } from '../auth/tokenHold.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 { VerifyAddressCommand } from './commands.js';
 const log = debug('location-client:api');
@@ -51,13 +51,21 @@ export 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 ? 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
@@ -74,7 +82,7 @@ export 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);
@@ -85,11 +93,6 @@ export 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}${resolveEndpoint(cmd)}`;
@@ -100,62 +103,15 @@ export 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 (!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 = 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 (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 (isTokenRejected(again))
-                this.refused.remember(again, fresh);
-            throw again;
-        }
+        return 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/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';