@chaosity/location-client 0.6.0 → 0.8.0

package/README.md

@@ -69,6 +69,10 @@ Set these environment variables:
 LOCATION_API_URL=https://api.chaosity.cloud
 LOCATION_CLIENT_ID=your-client-id
 LOCATION_CLIENT_SECRET=your-client-secret
+
+# Only for LocationServiceConnector: the Origin sent on every data request.
+# The API answers 403 without one it recognises — see below.
+LOCATION_ORIGIN=https://your-allowed-domain.example
 ```
 
 Or pass credentials explicitly:
@@ -207,6 +211,7 @@ const client = new GeoPlacesClient({
   apiUrl: string,
   token: string,
   getToken?: () => string | undefined, // Optional: dynamic token getter
+  refreshToken?: () => Promise<string | undefined>, // Optional: 401 self-heal
 })
 
 await client.send(command)
@@ -214,6 +219,64 @@ await client.send(command)
 
 When `getToken` is provided, it is called on every request so token updates are reflected without recreating the client.
 
+`refreshToken` covers the case `getToken` cannot. `getToken` is synchronous —
+MapLibre's `transformRequest` requires that — so it can only ever return the
+token already in hand, and a token the API stops accepting **before** its `exp`
+(revoked, or issued against a since-rotated secret) fails every request until
+the refresh buffer elapses. `refreshToken` is awaited after a 401, and the
+request is retried **once** with what it returns. Return the same token, or
+nothing, and no retry is sent — a request that is going to fail again is not
+worth a second round trip. A 403 is never retried: a new token cannot fix an
+`Origin` the application does not allow.
+
+#### Request options
+
+Every call in this package takes the same options object — `client.send`,
+`connector.send`, `fetchMapStyle` and `fetchStaticMap` — and every failure
+arrives as a `LocationServiceException`.
+
+```typescript
+await client.send(command, {
+  signal, // AbortSignal — cancels mid-flight AND mid-backoff
+  timeoutMs: 10_000, // per ATTEMPT
+  overallTimeoutMs: 30_000, // the whole call, waits between attempts included
+  retry: { maxAttempts: 3 }, // or `false` for none
+})
+```
+
+`overallTimeoutMs` is the one worth setting deliberately, and it defaults to
+30 s. `timeoutMs` bounds an attempt, not a call: the API answers a spent quota
+with `Retry-After: 60`, and honouring that literally across two retries blocked
+the caller for about two minutes — past any Lambda budget. Now no attempt gets
+more time than the call has left, and a retry that would have to wait longer
+than the remaining budget is not made at all. You get the API's own error back
+instead, `retryAfterMs` intact, so you can queue the work rather than guess.
+
+The map helpers take them as a trailing argument:
+
+```typescript
+const style = await fetchMapStyle(
+  apiUrl,
+  'Standard',
+  getToken,
+  { language: 'fr' },
+  { signal },
+)
+const blob = await fetchStaticMap(
+  apiUrl,
+  { width: 640, height: 400, center },
+  getToken,
+  { signal },
+)
+```
+
+**A call with no token is refused locally rather than sent.** Every path that
+builds an `Authorization` header checks first, so a token source that has not
+produced one yet raises `InvalidCredentialsException` instead of putting
+`Bearer undefined` on the wire — which could only ever come back a 401, a round
+trip spent to be told what you already know. `GeoPlacesClient` asks `refreshToken` first, so a
+client whose token simply has not arrived yet still works.
+
 #### GeoPlaces Adapter
 
 Implements the `MaplibreGeocoderApi` interface for use with `@maplibre/maplibre-gl-geocoder`. Methods are called automatically by the geocoder control.
@@ -351,8 +414,19 @@ import { getClientConfig } from '@chaosity/location-client/server'
 
 const config = await getClientConfig()
 // { apiUrl: string, token: string, expiresAt?: number }
+
+// The API has rejected a token that has not reached its exp — revoked in the
+// portal, or issued against a client secret that has since been rotated.
+const replacement = await getClientConfig({ forceRefresh: true })
 ```
 
+The return value is **plain data** — no methods, no closures — so it can be
+returned straight out of a Next.js Server Action to a Client Component. It is
+therefore a snapshot: the token in it stops working at its `expiresAt`, and the
+caller asks for another. For a long-lived server process that should just keep
+working, use `LocationServiceConnector`, which holds a live token source and
+refreshes for you.
+
 #### TokenProvider
 
 Lower-level token management with caching and deduplication.
@@ -371,14 +445,18 @@ const { success, token, expiresAt } = await provider.getToken()
 
 #### LocationServiceConnector
 
-Server-side connector for backend-to-backend API calls. Can auto-configure from environment variables when no config is passed.
+Server-side connector for backend-to-backend API calls. It **completes** its
+configuration from the environment rather than replacing it, so you supply only
+the parts the environment does not have:
 
 ```typescript
 import { LocationServiceConnector } from '@chaosity/location-client/server'
 
+// apiUrl + credentials from LOCATION_API_URL / LOCATION_CLIENT_ID /
+// LOCATION_CLIENT_SECRET; Origin from here. Set LOCATION_ORIGIN as well and
+// `new LocationServiceConnector()` needs no arguments at all.
 const connector = new LocationServiceConnector({
-  apiUrl: config.apiUrl,
-  token: config.token,
+  origin: 'https://your-allowed-domain.example',
 })
 
 const result = await connector.send(
@@ -386,9 +464,34 @@ const result = await connector.send(
 )
 ```
 
+**Every data request needs an `Origin` the service recognises, and the API
+answers 403 without one** — server-to-server calls included, not just browsers.
+In a browser the browser sets it; here you do, with `origin` above,
+`LOCATION_ORIGIN`, or a per-call header (`send(cmd, { headers: { Origin } })`,
+which wins over both). `/auth/token` is the one endpoint exempt.
+
+A connector configured this way keeps working indefinitely: it holds a live
+token source, refreshes before expiry, and retries once with a new token if the
+API rejects the one it sent. Pass an explicit `token` instead and you opt out of
+all of that — it is a fixed string, and it dies at its own `exp`:
+
+```typescript
+// Managing credentials yourself: an explicit token source wins outright, and
+// the environment is not consulted.
+const connector = new LocationServiceConnector({
+  apiUrl,
+  origin: 'https://your-allowed-domain.example',
+  getToken: (forceRefresh) => provider.getToken(forceRefresh),
+})
+```
+
 ## Cache-Friendly Position Rounding
 
-`BiasPosition` coordinates are automatically rounded to 2 decimal places (~1.1 km grid) before each API request. This maximizes cache hits across nearby users without affecting result quality — bias is approximate by nature.
+`BiasPosition` coordinates are automatically rounded before each API request, to
+whatever precision your application is entitled to — a `biasDecimals` claim on
+the access token, defaulting to **3 decimal places** (~110 m) when the token
+carries none. This maximizes cache hits across nearby users without affecting
+result quality — bias is approximate by nature.
 
 `QueryPosition` (reverse geocode) retains full precision since it represents an exact point the user selected.
 

package/dist/cjs/client/GeoPlacesClient.d.ts

@@ -31,9 +31,20 @@ export declare class GeoPlacesClient {
      * case until one is configured in the portal.
      */
     getAppConfig(): AppConfigClaims;
+    /** Prefer the getToken callback (live ref) over a static token string. */
+    private currentToken;
     /**
-     * @param options `signal` to cancel, `timeoutMs` per attempt, `retry: false`
-     *   to disable the retry loop. Every failure throws LocationServiceException.
+     * 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.
+     */
+    private ensureToken;
+    /**
+     * @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<TInput, TOutput>(command: TInput, options?: SendOptions): Promise<TOutput>;
+    private dispatch;
 }

package/dist/cjs/client/GeoPlacesClient.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.GeoPlacesClient = void 0;
 const debug_1 = __importDefault(require("debug"));
 const endpoints_js_1 = require("../transport/endpoints.js");
+const errors_js_1 = require("../transport/errors.js");
 const http_js_1 = require("../transport/http.js");
 const roundPosition_js_1 = require("../utils/roundPosition.js");
 const tokenClaims_js_1 = require("../utils/tokenClaims.js");
@@ -38,24 +39,73 @@ class GeoPlacesClient {
      * case until one is configured in the portal.
      */
     getAppConfig() {
-        const token = this.clientConfig.getToken?.() ?? this.clientConfig.token;
-        return (0, tokenClaims_js_1.readAppConfigClaims)(token);
+        return (0, tokenClaims_js_1.readAppConfigClaims)(this.currentToken());
+    }
+    /** Prefer the getToken callback (live ref) over a static token string. */
+    currentToken() {
+        return this.clientConfig.getToken?.() ?? this.clientConfig.token;
+    }
+    /**
+     * 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() {
+        // `||`, 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 two lines below — so
+        // `getToken: () => undefined` got the refresh ask and `getToken: () => ''`
+        // did not, which is a distinction no caller means to draw.
+        const token = this.currentToken() || (await this.clientConfig.refreshToken?.());
+        if (!token) {
+            throw (0, errors_js_1.noTokenAvailable)('the client has no token yet. Pass `token`, or a `getToken`/`refreshToken` that has one.');
+        }
+        return token;
     }
     /**
-     * @param options `signal` to cancel, `timeoutMs` per attempt, `retry: false`
-     *   to disable the retry loop. Every failure throws LocationServiceException.
+     * @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 endpoint = (0, endpoints_js_1.resolveEndpoint)(cmd);
-        // Prefer the getToken callback (live ref) over a static token string.
-        const token = this.clientConfig.getToken?.() ?? this.clientConfig.token;
+        const url = `${this.clientConfig.apiUrl}${(0, endpoints_js_1.resolveEndpoint)(cmd)}`;
+        // The fifth and last place in this package that turns a token into an
+        // `Authorization` header, and the last one that would send `Bearer
+        // undefined` (#37). The 401 self-heal below cannot cover this case — it
+        // needs a request to have been rejected first — so a client whose token
+        // 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();
+        try {
+            return await this.dispatch(url, token, cmd, options);
+        }
+        catch (err) {
+            if (!(0, errors_js_1.isTokenRejected)(err))
+                throw 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 background may have landed a new one while this
+            // request was in flight.
+            const fresh = (await this.clientConfig.refreshToken?.()) ?? this.currentToken();
+            // Nothing new to send. Repeating the request would fail identically — a
+            // second round trip for the same 401.
+            if (!fresh || fresh === token)
+                throw err;
+            log('401 — retrying %s once with a refreshed token', cmd.constructor?.name);
+            return await this.dispatch(url, fresh, cmd, options);
+        }
+    }
+    dispatch(url, token, cmd, options) {
         // Resolve the token BEFORE rounding: the precision this application is
         // entitled to is a claim on it (api#65). Absent claim -> the 3 dp floor.
         const { biasDecimals } = (0, tokenClaims_js_1.readAppConfigClaims)(token);
         const input = (0, roundPosition_js_1.roundPositionFields)(cmd.input, biasDecimals);
-        log('Sending %s to %s', cmd.constructor?.name, endpoint);
-        return (0, http_js_1.requestJson)(`${this.clientConfig.apiUrl}${endpoint}`, {
+        log('Sending %s to %s', cmd.constructor?.name, url);
+        return (0, http_js_1.requestJson)(url, {
             method: 'POST',
             headers: {
                 'Content-Type': 'application/json',

package/dist/cjs/index.d.ts

@@ -1,6 +1,6 @@
 export { GeoPlacesClient } from './client/GeoPlacesClient.js';
 export type { SendOptions } from './client/GeoPlacesClient.js';
-export { DEFAULT_MAX_ATTEMPTS, DEFAULT_TIMEOUT_MS } from './transport/http.js';
+export { DEFAULT_MAX_ATTEMPTS, DEFAULT_OVERALL_TIMEOUT_MS, DEFAULT_TIMEOUT_MS, } from './transport/http.js';
 export type { RequestOptions } from './transport/http.js';
 export { TOKEN_REFRESH_BUFFER_SECONDS, readTokenExpiry, } from './auth/tokenRefresh.js';
 export { LocationServiceException } from './errors/LocationServiceException.js';

package/dist/cjs/index.js

@@ -14,13 +14,14 @@ 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.STATIC_MAP_STYLES = exports.SPRITE_VARIANTS = exports.SCALE_BAR_UNITS = 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.LocationServiceException = exports.readTokenExpiry = exports.TOKEN_REFRESH_BUFFER_SECONDS = exports.DEFAULT_TIMEOUT_MS = exports.DEFAULT_MAX_ATTEMPTS = exports.GeoPlacesClient = void 0;
+exports.transformRequest = exports.TRAVEL_MODES = exports.TRAFFIC_MODES = exports.TERRAINS = exports.STATIC_MAP_STYLES = exports.SPRITE_VARIANTS = exports.SCALE_BAR_UNITS = 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.LocationServiceException = 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; } });
-// Transport options — cancellation, per-attempt timeout, retry policy
+// Transport options — cancellation, per-attempt timeout, overall budget, retry
 var http_js_1 = require("./transport/http.js");
 Object.defineProperty(exports, "DEFAULT_MAX_ATTEMPTS", { enumerable: true, get: function () { return http_js_1.DEFAULT_MAX_ATTEMPTS; } });
+Object.defineProperty(exports, "DEFAULT_OVERALL_TIMEOUT_MS", { enumerable: true, get: function () { return http_js_1.DEFAULT_OVERALL_TIMEOUT_MS; } });
 Object.defineProperty(exports, "DEFAULT_TIMEOUT_MS", { enumerable: true, get: function () { return http_js_1.DEFAULT_TIMEOUT_MS; } });
 // Token refresh policy — shared by the server provider and the React provider
 var tokenRefresh_js_1 = require("./auth/tokenRefresh.js");

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

@@ -3,6 +3,8 @@ import type { RequestTransformFunction } from 'maplibre-gl';
  * Creates a transformRequest function for MapLibre that adds authentication
  * and proper Accept headers for AWS Location Service API requests.
  *
+ * The token is attached to our own API and nowhere else — see isOurApi.
+ *
  * @param apiUrl - Base URL of the Location Service API
  * @param getToken - Callback function that returns the current auth token
  * @returns MapLibre transformRequest function

package/dist/cjs/maps/createTransformRequest.js

@@ -1,17 +1,61 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createTransformRequest = createTransformRequest;
+/**
+ * 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.
+ */
+function isOurApi(url, apiUrl) {
+    const base = typeof location === 'undefined' ? undefined : location.href;
+    let ours;
+    let theirs;
+    try {
+        ours = new URL(apiUrl, base);
+        theirs = new URL(url, base);
+    }
+    catch {
+        return false;
+    }
+    if (theirs.origin !== ours.origin)
+        return false;
+    // Trailing slashes normalised so `/v1` and `/v1/` behave the same; the `/`
+    // boundary is what stops `/v1` from matching `/v1-internal`.
+    const basePath = ours.pathname.replace(/\/+$/, '');
+    return (theirs.pathname === basePath || theirs.pathname.startsWith(`${basePath}/`));
+}
 /**
  * Creates a transformRequest function for MapLibre that adds authentication
  * and proper Accept headers for AWS Location Service API requests.
  *
+ * The token is attached to our own API and nowhere else — see isOurApi.
+ *
  * @param apiUrl - Base URL of the Location Service API
  * @param getToken - Callback function that returns the current auth token
  * @returns MapLibre transformRequest function
  */
 function createTransformRequest(apiUrl, getToken) {
     return (url, _resourceType) => {
-        if (url.startsWith(apiUrl)) {
+        if (isOurApi(url, apiUrl)) {
             const token = getToken();
             if (!token) {
                 console.warn('[createTransformRequest] No token available');

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

@@ -1,4 +1,5 @@
 import type { StyleSpecification } from 'maplibre-gl';
+import type { RequestOptions } from '../transport/http.js';
 import type { Buildings, ColorScheme, ContourDensity, MapStyle, Terrain, TrafficMode, TravelMode } from './mapEnums.js';
 /**
  * Options for building an AWS Location Service map style URL.
@@ -66,6 +67,7 @@ export declare function buildMapStyleUrl(apiUrl: string, mapStyle: MapStyle, opt
  * @param mapStyle - Map style name (e.g. 'Standard', 'Monochrome', 'Satellite', 'Hybrid')
  * @param getToken - Callback returning the current auth token
  * @param options - Style options; `language` is applied to the descriptor, all others become URL params
+ * @param request - Transport options: `signal` to cancel, `timeoutMs`, `overallTimeoutMs`, `retry`
  * @returns Modified MapLibre StyleSpecification object
  *
  * @example
@@ -74,4 +76,4 @@ export declare function buildMapStyleUrl(apiUrl: string, mapStyle: MapStyle, opt
  */
 export declare function fetchMapStyle(apiUrl: string, mapStyle: MapStyle, getToken: () => string | undefined, options?: MapStyleOptions & {
     language?: string;
-}): Promise<StyleSpecification>;
+}, request?: RequestOptions): Promise<StyleSpecification>;

package/dist/cjs/maps/mapStyle.js

@@ -3,6 +3,7 @@ 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");
 /**
  * Build a map style descriptor URL for the Location Service API.
@@ -50,38 +51,42 @@ function buildMapStyleUrl(apiUrl, mapStyle, options = {}) {
  * @param mapStyle - Map style name (e.g. 'Standard', 'Monochrome', 'Satellite', 'Hybrid')
  * @param getToken - Callback returning the current auth token
  * @param options - Style options; `language` is applied to the descriptor, all others become URL params
+ * @param request - Transport options: `signal` to cancel, `timeoutMs`, `overallTimeoutMs`, `retry`
  * @returns Modified MapLibre StyleSpecification object
  *
  * @example
  * 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 = {}) {
+async function fetchMapStyle(apiUrl, mapStyle, getToken, options = {}, request = {}) {
     const { language, ...styleOptions } = options;
     const url = buildMapStyleUrl(apiUrl, mapStyle, styleOptions);
     const token = getToken();
-    const response = await fetch(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).
+    if (!token) {
+        throw (0, errors_js_1.noTokenAvailable)('getToken() returned nothing, so no style request was sent. Check the token provider has finished initialising.');
+    }
+    // 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
+    // the API's own message, which is the whole point of reading the body — for
+    // a style request that sentence is Amazon's, forwarded verbatim by
+    // location-service-api#89:
+    //
+    //   400 "Traffic is not supported for style."
+    //   400 "light is not a supported color scheme for style Standard."
+    //
+    // 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, {
         headers: {
             Authorization: `Bearer ${token}`,
             Accept: 'application/json',
         },
-    });
-    if (!response.ok) {
-        // Read the body. The API sends `{message, code, requestId}` and the message
-        // is the whole point of it — for a style request it is Amazon's own
-        // sentence, forwarded verbatim by location-service-api#89:
-        //
-        //   400 "Traffic is not supported for style."
-        //   400 "light is not a supported color scheme for style Standard."
-        //
-        // 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. Reuses parseErrorResponse so a style failure arrives as
-        // the same LocationServiceException as every other call in this package,
-        // with `code`, `statusCode` and `requestId` intact.
-        throw (0, errors_js_1.parseErrorResponse)(response.status, response.statusText, await response.text(), response.headers);
-    }
-    const style = (await response.json());
+    }, request);
     if (language) {
         applyLanguageToDescriptor(style, language);
     }

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

@@ -1,3 +1,4 @@
+import type { RequestOptions } from '../transport/http.js';
 import type { ColorScheme, LabelSize, MapFeatureMode, ScaleBarUnit, StaticMapStyle } from './mapEnums.js';
 /**
  * Static maps: build the URL, send the right headers, get a Blob.
@@ -74,6 +75,7 @@ export declare function buildStaticMapUrl(apiUrl: string, options: StaticMapOpti
  * @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 request  Transport options: `signal` to cancel, `timeoutMs`, `overallTimeoutMs`, `retry`
  *
  * @example
  * const blob = await fetchStaticMap(API_URL, {
@@ -82,4 +84,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): Promise<Blob>;
+export declare function fetchStaticMap(apiUrl: string, options: StaticMapOptions, getToken: () => string | undefined, request?: RequestOptions): Promise<Blob>;

package/dist/cjs/maps/staticMap.js

@@ -4,6 +4,7 @@ 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");
 /**
  * The Accept header this request must send.
  *
@@ -55,6 +56,7 @@ function buildStaticMapUrl(apiUrl, options) {
  * @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 request  Transport options: `signal` to cancel, `timeoutMs`, `overallTimeoutMs`, `retry`
  *
  * @example
  * const blob = await fetchStaticMap(API_URL, {
@@ -63,19 +65,23 @@ function buildStaticMapUrl(apiUrl, options) {
  * }, getToken)
  * const url = URL.createObjectURL(blob)   // remember to revokeObjectURL
  */
-async function fetchStaticMap(apiUrl, options, getToken) {
-    const response = await fetch(buildStaticMapUrl(apiUrl, options), {
+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.');
+    }
+    // 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), {
         headers: {
-            Authorization: `Bearer ${getToken()}`,
+            Authorization: `Bearer ${token}`,
             Accept: staticMapAccept(options.style),
         },
-    });
-    if (!response.ok) {
-        // Same treatment as fetchMapStyle: the API's {message, code, requestId} is
-        // the useful part, and a bare "failed: 400" throws it away. The messages
-        // here are specific and actionable -- "'width' and 'height' are required",
-        // "Only one of center, bounding-box or bounded-positions may be set".
-        throw (0, errors_js_1.parseErrorResponse)(response.status, response.statusText, await response.text());
-    }
-    return response.blob();
+    }, request);
 }

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

@@ -1,15 +1,35 @@
 import type { RequestOptions } from '../transport/http.js';
 import type { AppConfigClaims } from '../utils/tokenClaims.js';
 export interface ConnectorConfig {
+    /** Falls back to `LOCATION_API_URL` / `LOCATION_SERVICE_API_URL`. */
     apiUrl?: string;
+    /**
+     * A fixed token. Nothing can refresh it, so it dies at its own `exp` — pass
+     * `getToken` instead, or nothing at all, for a connector that keeps working.
+     */
     token?: string;
-    getToken?: () => Promise<{
-        token: string;
-    }>;
+    /**
+     * Where a token comes from. Called for every request, so this is what makes
+     * 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.
+     */
+    getToken?: (forceRefresh?: boolean) => Promise<string | {
+        token?: string;
+    } | undefined>;
+    /** Falls back to `LOCATION_CLIENT_ID` / `LOCATION_SERVICE_CLIENT_ID`. */
+    clientId?: string;
+    /** Falls back to `LOCATION_CLIENT_SECRET` / `LOCATION_SERVICE_CLIENT_SECRET`. */
+    clientSecret?: string;
     /**
      * Sent as the `Origin` header on every request. The API requires an Origin it
      * recognises on every data request and answers 403 without one, so every
      * caller was setting it by hand on each `send`; this does it once.
+     *
+     * Falls back to `LOCATION_ORIGIN` / `LOCATION_SERVICE_ORIGIN`, so the
+     * zero-argument connector can be made to work from the environment alone.
      */
     origin?: string;
 }
@@ -23,19 +43,38 @@ export interface SendOptions extends RequestOptions {
  * token management, and the same transport (timeout, cancellation, retry) as the
  * browser client.
  *
+ * Configuration is COMPLETED from the environment rather than replaced by it.
+ * The constructor used to be all-or-nothing — any argument at all took the
+ * "caller supplies everything" branch — so `new LocationServiceConnector()` had
+ * credentials but could never send an Origin (403 on every data request) and
+ * `new LocationServiceConnector({ origin })` had an Origin but no credentials
+ * (#45). Now an explicit `token`/`getToken` still wins outright, and anything
+ * short of that is filled in from `LOCATION_API_URL` / `LOCATION_CLIENT_ID` /
+ * `LOCATION_CLIENT_SECRET` / `LOCATION_ORIGIN`.
+ *
  * @example
  * ```typescript
+ * // Credentials and apiUrl from the environment, Origin supplied here
  * const connector = new LocationServiceConnector({ origin: 'https://app.example.com' })
  * const result = await connector.send(new SearchTextCommand({ QueryText: 'Space Needle' }))
  * ```
  */
 export declare class LocationServiceConnector {
-    private configPromise;
-    private origin?;
+    private readonly config;
+    private tokenSource?;
+    private readonly origin?;
     readonly serviceId: string;
     constructor(config?: ConnectorConfig);
-    /** One place that knows how a token is obtained, so nothing can drift. */
-    private resolveToken;
+    /**
+     * One place that knows how a token is obtained, so nothing can drift.
+     *
+     * Built on first use rather than in the constructor: resolving the
+     * environment path used to start a `/auth/token` round trip from `new`, whose
+     * rejection nothing was awaiting yet — an unhandled rejection for a
+     * misconfigured process, before it had made a single request.
+     */
+    private source;
+    private buildSource;
     /**
      * This application's own configuration, as carried on the access token
      * (api#65) — bias precision, and the countries it is scoped to.
@@ -51,5 +90,15 @@ export declare class LocationServiceConnector {
      * case until one is configured in the portal.
      */
     getAppConfig(): Promise<AppConfigClaims>;
+    /**
+     * The Origin this request will actually carry.
+     *
+     * ONE definition, for the two readers that must never disagree about it: the
+     * header merge in `dispatch`, and the 403 explanation in `send`. A per-call
+     * header beats the connector default, whatever the caller capitalised.
+     */
+    private effectiveOrigin;
     send<TInput, TOutput>(command: TInput, options?: SendOptions): Promise<TOutput>;
+    private dispatchWithRetry;
+    private dispatch;
 }