@chaosity/location-client 0.5.1 → 0.6.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
@@ -156,6 +168,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'

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;

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

@@ -0,0 +1,37 @@
+/**
+ * How long before expiry a token is treated as needing replacement.
+ *
+ * ONE number, used by both sides: the server-side `TokenProvider` deciding
+ * whether its cached token is still good, and the React provider deciding
+ * whether to ask for a new one. Both apply it to the same `exp` claim, so they
+ * cannot reach different answers about the same token.
+ *
+ * It used to be two separate `60`s — a private literal in `isExpired()` and a
+ * public `refreshBuffer` prop default — with nothing tying them together. On
+ * 2026-08-23 a consumer passed `refreshBuffer={800}` against a 900 s token: the
+ * client judged it stale after 100 s, the server still considered it fresh for
+ * another 840 s and returned the same one, and the client asked again
+ * immediately — roughly 110 requests per second from an idle page.
+ *
+ * Not configurable per consumer, deliberately. A settable client-side buffer is
+ * precisely what allowed that disagreement, and no amount of capping or backing
+ * off fixes it as cleanly as the two sides simply sharing the number.
+ */
+export declare const TOKEN_REFRESH_BUFFER_SECONDS = 60;
+/**
+ * Read the `exp` claim out of a JWT, in milliseconds.
+ *
+ * The expiry is IN THE TOKEN, so neither side needs to be told it. Both used to
+ * take it on trust from elsewhere — the server from the response body's
+ * `expires_at`, the React provider from whatever `getConfig` returned, falling
+ * back to inventing `Date.now() + 900_000` when that was absent. An invented
+ * expiry is how the two ended up disagreeing about the same token.
+ *
+ * Deliberately NOT verified. This is only used to decide *when to refresh*;
+ * nothing is authorised on the strength of it, and the API verifies the
+ * signature on every request regardless. Trusting `exp` for scheduling is safe
+ * in a way that trusting it for access would not be.
+ *
+ * Returns undefined for anything unparseable, so callers keep their fallback.
+ */
+export declare function readTokenExpiry(token: string | undefined): number | undefined;

package/dist/cjs/auth/tokenRefresh.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TOKEN_REFRESH_BUFFER_SECONDS = void 0;
+exports.readTokenExpiry = readTokenExpiry;
+/**
+ * How long before expiry a token is treated as needing replacement.
+ *
+ * ONE number, used by both sides: the server-side `TokenProvider` deciding
+ * whether its cached token is still good, and the React provider deciding
+ * whether to ask for a new one. Both apply it to the same `exp` claim, so they
+ * cannot reach different answers about the same token.
+ *
+ * It used to be two separate `60`s — a private literal in `isExpired()` and a
+ * public `refreshBuffer` prop default — with nothing tying them together. On
+ * 2026-08-23 a consumer passed `refreshBuffer={800}` against a 900 s token: the
+ * client judged it stale after 100 s, the server still considered it fresh for
+ * another 840 s and returned the same one, and the client asked again
+ * immediately — roughly 110 requests per second from an idle page.
+ *
+ * Not configurable per consumer, deliberately. A settable client-side buffer is
+ * precisely what allowed that disagreement, and no amount of capping or backing
+ * off fixes it as cleanly as the two sides simply sharing the number.
+ */
+exports.TOKEN_REFRESH_BUFFER_SECONDS = 60;
+/**
+ * Read the `exp` claim out of a JWT, in milliseconds.
+ *
+ * The expiry is IN THE TOKEN, so neither side needs to be told it. Both used to
+ * take it on trust from elsewhere — the server from the response body's
+ * `expires_at`, the React provider from whatever `getConfig` returned, falling
+ * back to inventing `Date.now() + 900_000` when that was absent. An invented
+ * expiry is how the two ended up disagreeing about the same token.
+ *
+ * Deliberately NOT verified. This is only used to decide *when to refresh*;
+ * nothing is authorised on the strength of it, and the API verifies the
+ * signature on every request regardless. Trusting `exp` for scheduling is safe
+ * in a way that trusting it for access would not be.
+ *
+ * Returns undefined for anything unparseable, so callers keep their fallback.
+ */
+function readTokenExpiry(token) {
+    if (!token)
+        return undefined;
+    const payload = token.split('.')[1];
+    if (!payload)
+        return undefined;
+    try {
+        const base64 = payload.replace(/-/g, '+').replace(/_/g, '/');
+        const json = typeof atob === 'function'
+            ? atob(base64)
+            : Buffer.from(base64, 'base64').toString('utf8');
+        const exp = JSON.parse(json)?.exp;
+        return typeof exp === 'number' ? exp * 1000 : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

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

@@ -0,0 +1,39 @@
+import type { RequestOptions } from '../transport/http.js';
+import type { ClientConfig } from '../types/index.js';
+import type { AppConfigClaims } from '../utils/tokenClaims.js';
+export type SendOptions = RequestOptions;
+/**
+ * GeoPlacesClient — AWS Location Service compatible client with custom auth.
+ *
+ * Uses AWS SDK command classes but replaces SigV4 with a Bearer token. All
+ * request and response types are identical to AWS Location Service.
+ *
+ * Pass `getToken` in config for live refresh without recreating the client.
+ */
+export declare class GeoPlacesClient {
+    private clientConfig;
+    readonly config: {
+        serviceId: string;
+    };
+    constructor(config: ClientConfig);
+    /**
+     * This application's own configuration, as carried on the access token
+     * (api#65) — bias precision, and the countries it is scoped to.
+     *
+     * Provided so an application can SHOW its own settings: populate a country
+     * selector with the markets it actually serves, label a settings screen,
+     * and so on. Being a few minutes stale is cosmetic for that.
+     *
+     * It is not an entitlement check. See AppConfigClaims for why acting on
+     * `countries` client-side makes requests fail that would otherwise succeed.
+     *
+     * Returns `{}` when the token carries no application config, which is the
+     * case until one is configured in the portal.
+     */
+    getAppConfig(): AppConfigClaims;
+    /**
+     * @param options `signal` to cancel, `timeoutMs` per attempt, `retry: false`
+     *   to disable the retry loop. Every failure throws LocationServiceException.
+     */
+    send<TInput, TOutput>(command: TInput, options?: SendOptions): Promise<TOutput>;
+}