@chaosity/location-client 0.5.1 → 0.7.0

package/README.md

@@ -22,6 +22,18 @@ AWS Location Service compatible client with custom Bearer token authentication.
 npm install @chaosity/location-client
 ```
 
+The Places commands, the transport and the static-map and style-URL helpers need
+nothing else. The **map** features are optional peer dependencies, so install
+them only if you use them:
+
+```bash
+# interactive map helpers (createTransformRequest, applyMapLanguage, POI toggles)
+npm install maplibre-gl
+
+# the MapLibre geocoder control (the GeoPlaces adapter)
+npm install maplibre-gl @maplibre/maplibre-gl-geocoder
+```
+
 ## Key Features
 
 - **Custom Authentication**: Uses Bearer tokens instead of AWS SigV4
@@ -57,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:
@@ -156,6 +172,8 @@ Available categories: `food_drink`, `entertainment`, `sights`, `transit`, `accom
 
 ### MapLibre Geocoder Integration
 
+Requires the optional peers: `npm install maplibre-gl @maplibre/maplibre-gl-geocoder`
+
 ```typescript
 import { GeoPlacesClient, GeoPlaces } from '@chaosity/location-client'
 import MaplibreGeocoder from '@maplibre/maplibre-gl-geocoder'
@@ -193,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)
@@ -200,6 +219,16 @@ 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 being billed for twice. A 403 is never retried: a new token cannot fix an
+`Origin` the application does not allow.
+
 #### GeoPlaces Adapter
 
 Implements the `MaplibreGeocoderApi` interface for use with `@maplibre/maplibre-gl-geocoder`. Methods are called automatically by the geocoder control.
@@ -337,8 +366,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.
@@ -357,14 +397,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(
@@ -372,9 +416,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/adapters/GeoPlaces.d.ts

@@ -1,6 +1,6 @@
 import type { MaplibreGeocoderApi, MaplibreGeocoderApiConfig, MaplibreGeocoderFeatureResults, MaplibreGeocoderPlaceResults, MaplibreGeocoderSuggestionResults } from '@maplibre/maplibre-gl-geocoder';
 import type { Map } from 'maplibre-gl';
-import type { GeoPlacesClient } from '../client/GeoPlacesClient';
+import type { GeoPlacesClient } from '../client/GeoPlacesClient.js';
 /**
  * GeoPlaces - MapLibre adapter for AWS Location Service
  *

package/dist/auth/TokenProvider.js

@@ -1,7 +1,7 @@
 import debug from 'debug';
-import { LocationServiceException } from '../errors/LocationServiceException';
-import { requestJson } from '../transport/http';
-import { TOKEN_REFRESH_BUFFER_SECONDS, readTokenExpiry } from './tokenRefresh';
+import { LocationServiceException } from '../errors/LocationServiceException.js';
+import { requestJson } from '../transport/http.js';
+import { TOKEN_REFRESH_BUFFER_SECONDS, readTokenExpiry, } from './tokenRefresh.js';
 const log = debug('location-client:auth');
 /**
  * TokenProvider - SERVER-SIDE ONLY

package/dist/cjs/adapters/GeoPlaces.d.ts

@@ -0,0 +1,64 @@
+import type { MaplibreGeocoderApi, MaplibreGeocoderApiConfig, MaplibreGeocoderFeatureResults, MaplibreGeocoderPlaceResults, MaplibreGeocoderSuggestionResults } from '@maplibre/maplibre-gl-geocoder';
+import type { Map } from 'maplibre-gl';
+import type { GeoPlacesClient } from '../client/GeoPlacesClient.js';
+/**
+ * GeoPlaces - MapLibre adapter for AWS Location Service
+ *
+ * Implements MaplibreGeocoderApi interface for compatibility with @maplibre/maplibre-gl-geocoder
+ */
+/**
+ * Extra GetPlace detail, and what each one costs (#3 / T19).
+ *
+ * Measured against Amazon Location on 2026-08-25 by requesting each feature
+ * alone and reading the pricing bucket back:
+ *
+ *   (none)              -> Core      $0.50/1k
+ *   SecondaryAddresses  -> Core      $0.50/1k
+ *   Access              -> Advanced  $1.50/1k
+ *   TimeZone            -> Advanced  $1.50/1k
+ *   Contact             -> Advanced  $1.50/1k
+ *
+ * `secondaryAddresses` is therefore free in bucket terms and the others triple
+ * the price of every lookup. They are opt-in for that reason, not because the
+ * data is unwelcome.
+ *
+ * Worth knowing before enabling `contact`: for a street address it costs
+ * Advanced and returns no contact field at all — only points of interest carry
+ * one. On an address-completion flow that is 3x the price for nothing.
+ */
+export interface GeoPlacesDetailOptions {
+    /** Entrance/exit points. Moves the request to the Advanced bucket. */
+    access?: boolean;
+    /** Unit and sub-address detail. Stays in the Core bucket — free to enable. */
+    secondaryAddresses?: boolean;
+    /** Phone/website, POIs only. Moves the request to the Advanced bucket. */
+    contact?: boolean;
+    /** IANA zone and offset. Moves the request to the Advanced bucket. */
+    timeZone?: boolean;
+}
+export interface GeoPlacesOptions {
+    /**
+     * Extra detail on `searchByPlaceId`. Default: none, which keeps every
+     * lookup in the Core bucket.
+     */
+    details?: GeoPlacesDetailOptions;
+}
+export declare class GeoPlaces implements MaplibreGeocoderApi {
+    private client;
+    private map;
+    private details;
+    constructor(client: GeoPlacesClient, map: Map, options?: GeoPlacesOptions);
+    /**
+     * Build the AdditionalFeatures list from the opt-ins, or omit it entirely.
+     *
+     * Returning `undefined` rather than `[]` matters: an empty array is still a
+     * field on the request, and the point is to send nothing.
+     */
+    private detailFeatures;
+    private normalizeLanguage;
+    forwardGeocode(config: MaplibreGeocoderApiConfig): Promise<MaplibreGeocoderFeatureResults>;
+    reverseGeocode(config: MaplibreGeocoderApiConfig): Promise<MaplibreGeocoderFeatureResults>;
+    getSuggestions(config: MaplibreGeocoderApiConfig): Promise<MaplibreGeocoderSuggestionResults>;
+    searchByPlaceId(config: MaplibreGeocoderApiConfig): Promise<MaplibreGeocoderPlaceResults>;
+    localGeocode(config: MaplibreGeocoderApiConfig): Promise<MaplibreGeocoderFeatureResults>;
+}

package/dist/cjs/adapters/GeoPlaces.js

@@ -0,0 +1,213 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GeoPlaces = void 0;
+const client_geo_places_1 = require("@aws-sdk/client-geo-places");
+const amazon_location_utilities_datatypes_1 = require("@aws/amazon-location-utilities-datatypes");
+const debug_1 = __importDefault(require("debug"));
+const log = (0, debug_1.default)('location-client:geocoder');
+/**
+ * Give the control the fields it renders, not just the ones GeoJSON needs.
+ *
+ * `@maplibre/maplibre-gl-geocoder` is a Carmen-shaped consumer: its result list
+ * calls `item.place_name.split(',')`, the input takes `result.place_name` on
+ * select, and fly-to reads `center` / `bbox`. The AWS converters produce plain
+ * GeoJSON — `properties` and `geometry` only — so a forward geocode used to
+ * hand the control features with no `place_name`. The list renderer threw, the
+ * control caught it and emitted `error`, and with no listener that surfaced as
+ * `Unhandled error. (undefined)` in the console: the Enter key silently did
+ * nothing. Suggestions were unaffected because that path renders `text`.
+ *
+ * The `as MaplibreGeocoderFeatureResults` cast this replaces is what hid it —
+ * `place_name` and `text` are required on the type.
+ */
+function toCarmenFeatures(features) {
+    return features.map((feature) => {
+        const p = (feature.properties ?? {});
+        const title = typeof p.Title === 'string' ? p.Title : '';
+        const label = typeof p['Address.Label'] === 'string' ? p['Address.Label'] : '';
+        // `flattenProperties` flattens nested OBJECTS (Address.Label) but leaves an
+        // array of numbers intact, so MapView is still [minx, miny, maxx, maxy].
+        const view = p.MapView;
+        const bbox = Array.isArray(view) &&
+            view.length === 4 &&
+            view.every((v) => typeof v === 'number')
+            ? view
+            : undefined;
+        const center = feature.geometry?.type === 'Point'
+            ? feature.geometry.coordinates
+            : undefined;
+        return {
+            ...feature,
+            text: title || label,
+            place_name: label || title,
+            place_type: typeof p.PlaceType === 'string' ? [p.PlaceType] : [],
+            ...(bbox ? { bbox } : {}),
+            ...(center ? { center } : {}),
+        };
+    });
+}
+class GeoPlaces {
+    constructor(client, map, options = {}) {
+        this.client = client;
+        this.map = map;
+        this.details = options.details ?? {};
+    }
+    /**
+     * Build the AdditionalFeatures list from the opt-ins, or omit it entirely.
+     *
+     * Returning `undefined` rather than `[]` matters: an empty array is still a
+     * field on the request, and the point is to send nothing.
+     */
+    detailFeatures() {
+        const features = [];
+        if (this.details.access)
+            features.push(client_geo_places_1.GetPlaceAdditionalFeature.ACCESS);
+        if (this.details.secondaryAddresses)
+            features.push(client_geo_places_1.GetPlaceAdditionalFeature.SECONDARY_ADDRESSES);
+        if (this.details.contact)
+            features.push(client_geo_places_1.GetPlaceAdditionalFeature.CONTACT);
+        if (this.details.timeZone)
+            features.push(client_geo_places_1.GetPlaceAdditionalFeature.TIME_ZONE);
+        return features.length ? features : undefined;
+    }
+    normalizeLanguage(language) {
+        if (Array.isArray(language))
+            return language[0] || 'en';
+        if (typeof language === 'string')
+            return language;
+        return 'en';
+    }
+    async forwardGeocode(config) {
+        log('forwardGeocode query=%s', config.query);
+        const center = this.map.getCenter();
+        const biasPosition = config.proximity && config.proximity.length >= 2
+            ? [config.proximity[0], config.proximity[1]]
+            : [center.lng, center.lat];
+        const commandInput = {
+            QueryText: config.query,
+            BiasPosition: biasPosition,
+            MaxResults: config.limit || 5,
+            Language: this.normalizeLanguage(config.language),
+        };
+        if (config.countries) {
+            commandInput.Filter = {
+                IncludeCountries: Array.isArray(config.countries)
+                    ? config.countries
+                    : config.countries.split(','),
+            };
+        }
+        const response = (await this.client.send(new client_geo_places_1.GeocodeCommand(commandInput)));
+        const converted = (0, amazon_location_utilities_datatypes_1.geocodeResponseToFeatureCollection)(response, {
+            flattenProperties: true,
+        });
+        const result = {
+            type: 'FeatureCollection',
+            features: toCarmenFeatures(converted.features),
+        };
+        log('forwardGeocode returned %d results', result.features.length);
+        return result;
+    }
+    async reverseGeocode(config) {
+        log('reverseGeocode query=%o', config.query);
+        const queryPosition = Array.isArray(config.query) && config.query.length >= 2
+            ? [config.query[0], config.query[1]]
+            : [0, 0];
+        const commandInput = {
+            QueryPosition: queryPosition,
+            MaxResults: config.limit || 1,
+            Language: this.normalizeLanguage(config.language),
+        };
+        const response = (await this.client.send(new client_geo_places_1.ReverseGeocodeCommand(commandInput)));
+        const converted = (0, amazon_location_utilities_datatypes_1.reverseGeocodeResponseToFeatureCollection)(response, {
+            flattenProperties: true,
+        });
+        const result = {
+            type: 'FeatureCollection',
+            features: toCarmenFeatures(converted.features),
+        };
+        log('reverseGeocode returned %d results', result.features.length);
+        return result;
+    }
+    async getSuggestions(config) {
+        log('getSuggestions query=%s', config.query);
+        const center = this.map.getCenter();
+        const biasPosition = config.proximity && config.proximity.length >= 2
+            ? [config.proximity[0], config.proximity[1]]
+            : [center.lng, center.lat];
+        const commandInput = {
+            QueryText: config.query,
+            BiasPosition: biasPosition,
+            MaxResults: config.limit || 5,
+            Language: this.normalizeLanguage(config.language),
+            // No AdditionalFeatures (#3 / T19).
+            //
+            // This used to send `[Core]`, which put every keystroke in the Core
+            // bucket at $0.50/1k. The only thing Core adds to a Suggest response is
+            // `Highlights`, and this adapter reads `Title` and `Place.PlaceId` —
+            // nothing else. Verified against Amazon Location on 2026-08-25:
+            //
+            //   with [Core] -> bucket Core   keys: Title, ..., Place, Highlights
+            //   without     -> bucket Label  keys: Title, ..., Place
+            //
+            // Same two fields, $0.20/1k instead of $0.50. Suggest fires per
+            // keystroke, so it is the highest-volume call the library makes.
+            ...(config.countries || config.bbox
+                ? {
+                    Filter: {
+                        ...(config.countries
+                            ? {
+                                IncludeCountries: Array.isArray(config.countries)
+                                    ? config.countries
+                                    : config.countries.split(','),
+                            }
+                            : {}),
+                        ...(config.bbox ? { BoundingBox: config.bbox } : {}),
+                    },
+                }
+                : {}),
+        };
+        const response = (await this.client.send(new client_geo_places_1.SuggestCommand(commandInput)));
+        const suggestions = { suggestions: [] };
+        for (const item of response.ResultItems ?? []) {
+            const text = item.Title;
+            if (!text)
+                continue;
+            const placeId = item.Place?.PlaceId;
+            suggestions.suggestions.push({ text, placeId });
+        }
+        log('getSuggestions returned %d suggestions', suggestions.suggestions.length);
+        return suggestions;
+    }
+    async searchByPlaceId(config) {
+        log('searchByPlaceId placeId=%s', config.query);
+        // Opt-in rather than always-on (#3 / T19). Requesting all four put every
+        // lookup in the Advanced bucket at $1.50/1k; the default now sends none
+        // and stays in Core at $0.50. Callers that want the detail ask for it.
+        const additionalFeatures = this.detailFeatures();
+        const command = new client_geo_places_1.GetPlaceCommand({
+            PlaceId: config.query,
+            Language: this.normalizeLanguage(config.language),
+            ...(additionalFeatures ? { AdditionalFeatures: additionalFeatures } : {}),
+        });
+        const response = (await this.client.send(command));
+        const result = (0, amazon_location_utilities_datatypes_1.getPlaceResponseToFeatureCollection)(response, {
+            flattenProperties: true,
+        });
+        const carmenGeojsonFeatures = result.features.map((feature) => ({
+            ...feature,
+            text: response.Title || '',
+            place_name: response.Address?.Label || '',
+            place_type: response.PlaceType ? [response.PlaceType] : [],
+            bbox: response.MapView,
+        }));
+        log('searchByPlaceId returned %d features', carmenGeojsonFeatures.length);
+        return { place: carmenGeojsonFeatures };
+    }
+    async localGeocode(config) {
+        return this.forwardGeocode(config);
+    }
+}
+exports.GeoPlaces = GeoPlaces;

package/dist/cjs/auth/TokenProvider.d.ts

@@ -0,0 +1,64 @@
+export interface TokenResponse {
+    success: boolean;
+    token?: string;
+    expiresAt?: number;
+    error?: string;
+}
+export interface TokenProviderConfig {
+    apiUrl: string;
+    clientId: string;
+    clientSecret: string;
+}
+/**
+ * TokenProvider - SERVER-SIDE ONLY
+ *
+ * ⚠️ WARNING: This class requires client credentials (clientId and clientSecret)
+ * and must NEVER be used in browser/client-side code.
+ *
+ * Use this only in:
+ * - Node.js server environments
+ * - Next.js Server Actions (marked with 'use server')
+ * - Next.js API routes
+ * - Backend services
+ *
+ * For browser usage, use the React provider which receives tokens from server-side code.
+ *
+ * @example
+ * // ✓ Correct: Server-side usage
+ * import { TokenProvider } from '@chaosity/location-client/server'
+ *
+ * const provider = new TokenProvider({
+ *   apiUrl: process.env.API_URL!,
+ *   clientId: process.env.CLIENT_ID!,
+ *   clientSecret: process.env.CLIENT_SECRET!,
+ * })
+ *
+ * @example
+ * // ✗ Wrong: Never use in browser code
+ * // This would expose your credentials!
+ */
+export declare class TokenProvider {
+    private config;
+    private cachedToken?;
+    private cachedExpiresAt?;
+    private tokenPromise?;
+    constructor(config: TokenProviderConfig);
+    getToken(forceRefresh?: boolean): Promise<TokenResponse>;
+    /**
+     * Fetch a token, distinguishing transient failure from terminal (#9).
+     *
+     * This used to collapse every non-200 into `new Error(message)`: no status,
+     * no OAuth `error`, no `Retry-After`. So `503 temporarily_unavailable` — which
+     * the API returns when its config store is unreachable — was indistinguishable
+     * from `401 unauthorized`, and a customer whose credentials were perfectly
+     * good was told to go and check them.
+     *
+     * The shared transport now does the classifying: it retries 503/429/network
+     * honouring `Retry-After`, never retries 401/400, and throws a typed
+     * LocationServiceException either way. A failure REJECTS rather than resolving
+     * with `success: false`, so a stale token can never be used by accident.
+     */
+    private fetchToken;
+    private isExpired;
+    clearCache(): void;
+}

package/dist/cjs/auth/TokenProvider.js

@@ -0,0 +1,144 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TokenProvider = void 0;
+const debug_1 = __importDefault(require("debug"));
+const LocationServiceException_js_1 = require("../errors/LocationServiceException.js");
+const http_js_1 = require("../transport/http.js");
+const tokenRefresh_js_1 = require("./tokenRefresh.js");
+const log = (0, debug_1.default)('location-client:auth');
+/**
+ * TokenProvider - SERVER-SIDE ONLY
+ *
+ * ⚠️ WARNING: This class requires client credentials (clientId and clientSecret)
+ * and must NEVER be used in browser/client-side code.
+ *
+ * Use this only in:
+ * - Node.js server environments
+ * - Next.js Server Actions (marked with 'use server')
+ * - Next.js API routes
+ * - Backend services
+ *
+ * For browser usage, use the React provider which receives tokens from server-side code.
+ *
+ * @example
+ * // ✓ Correct: Server-side usage
+ * import { TokenProvider } from '@chaosity/location-client/server'
+ *
+ * const provider = new TokenProvider({
+ *   apiUrl: process.env.API_URL!,
+ *   clientId: process.env.CLIENT_ID!,
+ *   clientSecret: process.env.CLIENT_SECRET!,
+ * })
+ *
+ * @example
+ * // ✗ Wrong: Never use in browser code
+ * // This would expose your credentials!
+ */
+class TokenProvider {
+    constructor(config) {
+        // Runtime check: prevent usage in browser
+        if (typeof window !== 'undefined') {
+            throw new Error('TokenProvider cannot be used in browser environments. ' +
+                'It requires client credentials that must never be exposed to browsers. ' +
+                'Use @chaosity/location-client-react for browser usage.');
+        }
+        log('Initializing TokenProvider for %s', config.apiUrl);
+        this.config = config;
+    }
+    async getToken(forceRefresh = false) {
+        if (!forceRefresh && this.cachedToken && !this.isExpired()) {
+            const expiresIn = this.cachedExpiresAt
+                ? Math.floor((this.cachedExpiresAt - Date.now()) / 1000)
+                : 'unknown';
+            log('Using cached token (expires in %ds)', expiresIn);
+            return {
+                success: true,
+                token: this.cachedToken,
+                expiresAt: this.cachedExpiresAt,
+            };
+        }
+        // If token fetch is already in progress, wait for it
+        if (this.tokenPromise) {
+            log('Token fetch in progress, waiting for existing request...');
+            return this.tokenPromise;
+        }
+        // Start new token fetch
+        const reason = forceRefresh
+            ? 'forced refresh'
+            : this.cachedToken
+                ? 'token expired'
+                : 'no cached token';
+        log('Refreshing token (%s) from %s', reason, this.config.apiUrl);
+        this.tokenPromise = this.fetchToken();
+        try {
+            const result = await this.tokenPromise;
+            return result;
+        }
+        finally {
+            // Clear promise after completion (success or failure)
+            this.tokenPromise = undefined;
+        }
+    }
+    /**
+     * Fetch a token, distinguishing transient failure from terminal (#9).
+     *
+     * This used to collapse every non-200 into `new Error(message)`: no status,
+     * no OAuth `error`, no `Retry-After`. So `503 temporarily_unavailable` — which
+     * the API returns when its config store is unreachable — was indistinguishable
+     * from `401 unauthorized`, and a customer whose credentials were perfectly
+     * good was told to go and check them.
+     *
+     * The shared transport now does the classifying: it retries 503/429/network
+     * honouring `Retry-After`, never retries 401/400, and throws a typed
+     * LocationServiceException either way. A failure REJECTS rather than resolving
+     * with `success: false`, so a stale token can never be used by accident.
+     */
+    async fetchToken() {
+        const { clientId, clientSecret, apiUrl } = this.config;
+        const credentials = btoa(`${clientId}:${clientSecret}`);
+        const data = await (0, http_js_1.requestJson)(`${apiUrl}/auth/token`, {
+            method: 'POST',
+            headers: {
+                Authorization: `Basic ${credentials}`,
+                'Content-Type': 'application/x-www-form-urlencoded',
+            },
+            body: new URLSearchParams({
+                grant_type: 'client_credentials',
+            }).toString(),
+        }, { retry: { maxAttempts: 3 } });
+        if (!data.access_token) {
+            throw new LocationServiceException_js_1.LocationServiceException({
+                code: 'InvalidCredentialsException',
+                message: 'Token endpoint returned no access_token',
+                details: { source: 'client' },
+            });
+        }
+        this.cachedToken = data.access_token;
+        // The token's own `exp` claim first — it is the only value that cannot
+        // disagree with what the API will actually accept. `expires_at` and
+        // `expires_in` are what the response CLAIMS, and are kept as fallbacks.
+        this.cachedExpiresAt =
+            (0, tokenRefresh_js_1.readTokenExpiry)(data.access_token) ??
+                data.expires_at ??
+                Date.now() + (data.expires_in ?? 900) * 1000;
+        log('Token acquired successfully (expires in %ds)', Math.floor((this.cachedExpiresAt - Date.now()) / 1000));
+        return {
+            success: true,
+            token: this.cachedToken,
+            expiresAt: this.cachedExpiresAt,
+        };
+    }
+    isExpired(bufferSeconds = tokenRefresh_js_1.TOKEN_REFRESH_BUFFER_SECONDS) {
+        if (!this.cachedExpiresAt)
+            return true;
+        return Date.now() >= this.cachedExpiresAt - bufferSeconds * 1000;
+    }
+    clearCache() {
+        this.cachedToken = undefined;
+        this.cachedExpiresAt = undefined;
+    }
+}
+exports.TokenProvider = TokenProvider;