@chaosity/location-client 0.5.1 → 0.7.0

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,42 @@
+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;
+    /** 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.
+     */
+    send<TInput, TOutput>(command: TInput, options?: SendOptions): Promise<TOutput>;
+    private dispatch;
+}

package/dist/cjs/client/GeoPlacesClient.js

@@ -0,0 +1,92 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+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");
+const log = (0, debug_1.default)('location-client:api');
+/**
+ * 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.
+ */
+class GeoPlacesClient {
+    constructor(config) {
+        this.clientConfig = config;
+        this.config = { serviceId: 'Geo Places' };
+    }
+    /**
+     * 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() {
+        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;
+    }
+    /**
+     * @param options `signal` to cancel, `timeoutMs` per attempt, `retry: false`
+     *   to disable the retry loop. Every failure throws LocationServiceException.
+     */
+    async send(command, options) {
+        const cmd = command;
+        const url = `${this.clientConfig.apiUrl}${(0, endpoints_js_1.resolveEndpoint)(cmd)}`;
+        const token = this.currentToken();
+        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, and
+            // be billed identically.
+            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, url);
+        return (0, http_js_1.requestJson)(url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${token}`,
+            },
+            body: JSON.stringify(input),
+        }, options);
+    }
+}
+exports.GeoPlacesClient = GeoPlacesClient;

package/dist/cjs/errors/LocationServiceException.d.ts

@@ -0,0 +1,44 @@
+export interface LocationServiceExceptionOptions {
+    message: string;
+    code: string;
+    /** Absent for failures that never reached the server: network, timeout, abort. */
+    statusCode?: number;
+    requestId?: string;
+    /** Structured extras — `source: 'client'` marks a locally-raised failure. */
+    details?: Record<string, unknown>;
+    cause?: unknown;
+    /** Parsed from the `Retry-After` header, in milliseconds. */
+    retryAfterMs?: number;
+}
+/**
+ * The single error type this package throws.
+ *
+ * Every failure — an API error envelope, a network fault, a timeout, an abort —
+ * arrives as one of these, so a caller writes one `catch` and asks the getters
+ * rather than sniffing at `TypeError` vs `DOMException` vs a bare `Error`.
+ */
+export declare class LocationServiceException extends Error {
+    readonly code: string;
+    readonly statusCode?: number;
+    readonly requestId?: string;
+    readonly details?: Record<string, unknown>;
+    readonly retryAfterMs?: number;
+    constructor(options: LocationServiceExceptionOptions);
+    /**
+     * Worth another attempt.
+     *
+     * Deliberately a explicit list rather than `statusCode >= 500`: a 500 or 501
+     * means the server broke on this request and will break again, while 502/503/
+     * 504 mean it never got there or gave up waiting. Retrying the first kind just
+     * multiplies the damage. Network failures and timeouts are retryable because
+     * nothing was necessarily processed.
+     */
+    get isRetryable(): boolean;
+    get isThrottling(): boolean;
+    get isValidation(): boolean;
+    /** Credentials or entitlements — the caller must act, retrying will not help. */
+    get isAuth(): boolean;
+    get isAborted(): boolean;
+    get isTimeout(): boolean;
+    toString(): string;
+}

package/dist/cjs/errors/LocationServiceException.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocationServiceException = void 0;
+/**
+ * The single error type this package throws.
+ *
+ * Every failure — an API error envelope, a network fault, a timeout, an abort —
+ * arrives as one of these, so a caller writes one `catch` and asks the getters
+ * rather than sniffing at `TypeError` vs `DOMException` vs a bare `Error`.
+ */
+class LocationServiceException extends Error {
+    constructor(options) {
+        super(options.message, { cause: options.cause });
+        this.name = 'LocationServiceException';
+        this.code = options.code;
+        this.statusCode = options.statusCode;
+        this.requestId = options.requestId;
+        this.details = options.details;
+        this.retryAfterMs = options.retryAfterMs;
+    }
+    /**
+     * Worth another attempt.
+     *
+     * Deliberately a explicit list rather than `statusCode >= 500`: a 500 or 501
+     * means the server broke on this request and will break again, while 502/503/
+     * 504 mean it never got there or gave up waiting. Retrying the first kind just
+     * multiplies the damage. Network failures and timeouts are retryable because
+     * nothing was necessarily processed.
+     */
+    get isRetryable() {
+        if (this.code === 'AbortedException')
+            return false;
+        if (this.code === 'NetworkException' || this.code === 'TimeoutException')
+            return true;
+        return (this.statusCode === 429 || [502, 503, 504].includes(this.statusCode ?? 0));
+    }
+    get isThrottling() {
+        return this.code === 'ThrottlingException' || this.statusCode === 429;
+    }
+    get isValidation() {
+        return this.code === 'ValidationException' || this.statusCode === 400;
+    }
+    /** Credentials or entitlements — the caller must act, retrying will not help. */
+    get isAuth() {
+        return this.statusCode === 401 || this.statusCode === 403;
+    }
+    get isAborted() {
+        return this.code === 'AbortedException';
+    }
+    get isTimeout() {
+        return this.code === 'TimeoutException';
+    }
+    toString() {
+        const parts = [`LocationServiceException: [${this.code}] ${this.message}`];
+        if (this.requestId)
+            parts.push(`(requestId: ${this.requestId})`);
+        return parts.join(' ');
+    }
+}
+exports.LocationServiceException = LocationServiceException;

package/dist/cjs/index.d.ts

@@ -0,0 +1,24 @@
+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 type { RequestOptions } from './transport/http.js';
+export { TOKEN_REFRESH_BUFFER_SECONDS, readTokenExpiry, } from './auth/tokenRefresh.js';
+export { LocationServiceException } from './errors/LocationServiceException.js';
+export type { LocationServiceExceptionOptions } from './errors/LocationServiceException.js';
+export * from '@aws-sdk/client-geo-places';
+export * from '@aws/amazon-location-utilities-datatypes';
+export { GeoPlaces } from './adapters/GeoPlaces.js';
+export type { GeoPlacesDetailOptions, GeoPlacesOptions, } from './adapters/GeoPlaces.js';
+export { createTransformRequest } from './maps/createTransformRequest.js';
+export { applyMapLanguage } from './maps/mapLanguage.js';
+export { POI_CATEGORIES, setAllPoiVisibility, setPoiVisibility, } from './maps/mapPoi.js';
+export type { PoiCategory } from './maps/mapPoi.js';
+export { buildMapStyleUrl, fetchMapStyle } from './maps/mapStyle.js';
+export type { MapStyleOptions } from './maps/mapStyle.js';
+export { buildStaticMapUrl, fetchStaticMap, staticMapAccept, } from './maps/staticMap.js';
+export type { StaticMapFileName, StaticMapOptions } from './maps/staticMap.js';
+export { BUILDINGS, COLOR_SCHEMES, CONTOUR_DENSITIES, LABEL_SIZES, MAP_FEATURE_MODES, MAP_STYLES, SCALE_BAR_UNITS, SPRITE_VARIANTS, STATIC_MAP_STYLES, TERRAINS, TRAFFIC_MODES, TRAVEL_MODES, } from './maps/mapEnums.js';
+export type { Buildings, ColorScheme, ContourDensity, LabelSize, MapFeatureMode, MapStyle, ScaleBarUnit, SpriteVariant, StaticMapStyle, Terrain, TrafficMode, TravelMode, } from './maps/mapEnums.js';
+export { transformRequest } from './maps/Utils.js';
+export type { ClientConfig, GeoPlacesCommand, MapLike } from './types/index.js';
+export type { AppConfigClaims } from './utils/tokenClaims.js';

package/dist/cjs/index.js

@@ -0,0 +1,72 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+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;
+// 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
+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_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");
+Object.defineProperty(exports, "TOKEN_REFRESH_BUFFER_SECONDS", { enumerable: true, get: function () { return tokenRefresh_js_1.TOKEN_REFRESH_BUFFER_SECONDS; } });
+Object.defineProperty(exports, "readTokenExpiry", { enumerable: true, get: function () { return tokenRefresh_js_1.readTokenExpiry; } });
+// Errors
+var LocationServiceException_js_1 = require("./errors/LocationServiceException.js");
+Object.defineProperty(exports, "LocationServiceException", { enumerable: true, get: function () { return LocationServiceException_js_1.LocationServiceException; } });
+// Re-export AWS SDK commands and types
+__exportStar(require("@aws-sdk/client-geo-places"), exports);
+// Re-export AWS Location Utilities (data type conversions)
+__exportStar(require("@aws/amazon-location-utilities-datatypes"), exports);
+// Adapters (Custom - for MapLibre integration)
+var GeoPlaces_js_1 = require("./adapters/GeoPlaces.js");
+Object.defineProperty(exports, "GeoPlaces", { enumerable: true, get: function () { return GeoPlaces_js_1.GeoPlaces; } });
+// Maps utilities
+var createTransformRequest_js_1 = require("./maps/createTransformRequest.js");
+Object.defineProperty(exports, "createTransformRequest", { enumerable: true, get: function () { return createTransformRequest_js_1.createTransformRequest; } });
+var mapLanguage_js_1 = require("./maps/mapLanguage.js");
+Object.defineProperty(exports, "applyMapLanguage", { enumerable: true, get: function () { return mapLanguage_js_1.applyMapLanguage; } });
+var mapPoi_js_1 = require("./maps/mapPoi.js");
+Object.defineProperty(exports, "POI_CATEGORIES", { enumerable: true, get: function () { return mapPoi_js_1.POI_CATEGORIES; } });
+Object.defineProperty(exports, "setAllPoiVisibility", { enumerable: true, get: function () { return mapPoi_js_1.setAllPoiVisibility; } });
+Object.defineProperty(exports, "setPoiVisibility", { enumerable: true, get: function () { return mapPoi_js_1.setPoiVisibility; } });
+var mapStyle_js_1 = require("./maps/mapStyle.js");
+Object.defineProperty(exports, "buildMapStyleUrl", { enumerable: true, get: function () { return mapStyle_js_1.buildMapStyleUrl; } });
+Object.defineProperty(exports, "fetchMapStyle", { enumerable: true, get: function () { return mapStyle_js_1.fetchMapStyle; } });
+var staticMap_js_1 = require("./maps/staticMap.js");
+Object.defineProperty(exports, "buildStaticMapUrl", { enumerable: true, get: function () { return staticMap_js_1.buildStaticMapUrl; } });
+Object.defineProperty(exports, "fetchStaticMap", { enumerable: true, get: function () { return staticMap_js_1.fetchStaticMap; } });
+Object.defineProperty(exports, "staticMapAccept", { enumerable: true, get: function () { return staticMap_js_1.staticMapAccept; } });
+// Accepted values for every map parameter, as VALUES so a picker can be built
+// from them, plus the matching types. Case sensitive — see mapEnums.ts.
+var mapEnums_js_1 = require("./maps/mapEnums.js");
+Object.defineProperty(exports, "BUILDINGS", { enumerable: true, get: function () { return mapEnums_js_1.BUILDINGS; } });
+Object.defineProperty(exports, "COLOR_SCHEMES", { enumerable: true, get: function () { return mapEnums_js_1.COLOR_SCHEMES; } });
+Object.defineProperty(exports, "CONTOUR_DENSITIES", { enumerable: true, get: function () { return mapEnums_js_1.CONTOUR_DENSITIES; } });
+Object.defineProperty(exports, "LABEL_SIZES", { enumerable: true, get: function () { return mapEnums_js_1.LABEL_SIZES; } });
+Object.defineProperty(exports, "MAP_FEATURE_MODES", { enumerable: true, get: function () { return mapEnums_js_1.MAP_FEATURE_MODES; } });
+Object.defineProperty(exports, "MAP_STYLES", { enumerable: true, get: function () { return mapEnums_js_1.MAP_STYLES; } });
+Object.defineProperty(exports, "SCALE_BAR_UNITS", { enumerable: true, get: function () { return mapEnums_js_1.SCALE_BAR_UNITS; } });
+Object.defineProperty(exports, "SPRITE_VARIANTS", { enumerable: true, get: function () { return mapEnums_js_1.SPRITE_VARIANTS; } });
+Object.defineProperty(exports, "STATIC_MAP_STYLES", { enumerable: true, get: function () { return mapEnums_js_1.STATIC_MAP_STYLES; } });
+Object.defineProperty(exports, "TERRAINS", { enumerable: true, get: function () { return mapEnums_js_1.TERRAINS; } });
+Object.defineProperty(exports, "TRAFFIC_MODES", { enumerable: true, get: function () { return mapEnums_js_1.TRAFFIC_MODES; } });
+Object.defineProperty(exports, "TRAVEL_MODES", { enumerable: true, get: function () { return mapEnums_js_1.TRAVEL_MODES; } });
+var Utils_js_1 = require("./maps/Utils.js");
+Object.defineProperty(exports, "transformRequest", { enumerable: true, get: function () { return Utils_js_1.transformRequest; } });
+// Server-only utilities are available via '@chaosity/location-client/server'

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

@@ -0,0 +1,2 @@
+import type { ClientConfig } from '../types/index.js';
+export declare function transformRequest(url: string, config: ClientConfig): import("maplibre-gl").RequestParameters | Promise<import("maplibre-gl").RequestParameters> | undefined;

package/dist/cjs/maps/Utils.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.transformRequest = transformRequest;
+const createTransformRequest_js_1 = require("./createTransformRequest.js");
+function transformRequest(url, config) {
+    const token = config.getToken?.() ?? config.token;
+    return (0, createTransformRequest_js_1.createTransformRequest)(config.apiUrl, () => token)(url);
+}

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

@@ -0,0 +1,12 @@
+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
+ */
+export declare function createTransformRequest(apiUrl: string, getToken: () => string | undefined): RequestTransformFunction;

package/dist/cjs/maps/createTransformRequest.js

@@ -0,0 +1,87 @@
+"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 (isOurApi(url, apiUrl)) {
+            const token = getToken();
+            if (!token) {
+                console.warn('[createTransformRequest] No token available');
+                return { url };
+            }
+            const headers = {
+                Authorization: `Bearer ${token}`,
+            };
+            // Set appropriate Accept headers based on resource type
+            if (url.includes('/tiles/')) {
+                headers['Accept'] = 'application/x-protobuf';
+            }
+            else if (url.includes('/glyphs/')) {
+                headers['Accept'] = 'application/x-protobuf';
+            }
+            else if (url.includes('/sprites/') && url.endsWith('.png')) {
+                headers['Accept'] = 'image/png';
+            }
+            else if (url.includes('/sprites/') && url.endsWith('.json')) {
+                headers['Accept'] = 'application/json';
+            }
+            else if (url.includes('/descriptor')) {
+                headers['Accept'] = 'application/json';
+            }
+            return { url, headers };
+        }
+        return { url };
+    };
+}

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

@@ -0,0 +1,102 @@
+/**
+ * The values Amazon Location accepts for each map parameter.
+ *
+ * WHY THESE ARE EXPORTED AS VALUES, NOT JUST TYPES
+ *
+ * A type union gives you compile-time safety and nothing to iterate. Every
+ * consumer that renders a style picker then re-types the same list by hand into
+ * a `<select>`, and those copies drift the moment AWS adds a style. Exporting
+ * the arrays means a dropdown is `MAP_STYLES.map(...)` and cannot disagree with
+ * the type beside it.
+ *
+ * THESE ARE CASE SENSITIVE
+ *
+ * AWS documents them so, and since location-service-api#89 the API enforces it
+ * rather than forwarding a wrong-cased value for Amazon to reject with an
+ * unhelpful 404. `'light'` is not `'Light'`:
+ *
+ *   GET /maps/Standard/descriptor?colorScheme=light
+ *   400  "'colorScheme' is case sensitive — use 'Light', not 'light'"
+ *
+ * So take the values from here rather than typing them, and the case is right
+ * by construction.
+ *
+ * MEMBERSHIP IS NOT THE WHOLE STORY
+ *
+ * A value being in one of these lists does not mean it is legal in every
+ * COMBINATION. `Traffic: 'All'` is valid, and `Style: 'Satellite'` is valid,
+ * but together they are not:
+ *
+ *   400  "Traffic is not supported for style."
+ *
+ * Amazon owns those rules and answers them per request; the API forwards that
+ * message verbatim. Do not try to encode combination rules here — they change
+ * without an SDK release.
+ *
+ * KEEPING THESE HONEST
+ *
+ * The API derives its copy from the AWS SDK's own `enums.d.ts` via
+ * `npm run generate:maps-enums`, so that side cannot drift. This file is the
+ * client-side mirror and every value below was additionally confirmed against
+ * the live geo-maps API on 2026-08-26. If the API starts rejecting something
+ * listed here, its generated list is the authority.
+ */
+/** Map styles for the style descriptor. */
+export declare const MAP_STYLES: readonly ["Hybrid", "Monochrome", "Satellite", "Standard"];
+export type MapStyle = (typeof MAP_STYLES)[number];
+/**
+ * Styles the STATIC map accepts — deliberately narrower than `MAP_STYLES`.
+ *
+ * `/maps/static/*` takes only Satellite and Standard. Passing Hybrid or
+ * Monochrome there is a 400, so the two lists are not interchangeable.
+ */
+export declare const STATIC_MAP_STYLES: readonly ["Satellite", "Standard"];
+export type StaticMapStyle = (typeof STATIC_MAP_STYLES)[number];
+/** Light or dark cartography. Not applicable to the raster styles. */
+export declare const COLOR_SCHEMES: readonly ["Dark", "Light"];
+export type ColorScheme = (typeof COLOR_SCHEMES)[number];
+/** Terrain overlay. `Hillshade` is shaded relief; `Terrain3D` is elevation. */
+export declare const TERRAINS: readonly ["Hillshade", "Terrain3D"];
+export type Terrain = (typeof TERRAINS)[number];
+/** 3D building extrusions. One value today, kept a list for when that changes. */
+export declare const BUILDINGS: readonly ["Buildings3D"];
+export type Buildings = (typeof BUILDINGS)[number];
+/**
+ * Elevation contour line density.
+ *
+ * All three work. An earlier version of this library documented `Medium` as
+ * "the only value currently supported by the AWS SDK", which was wrong — `High`
+ * and `Low` were both confirmed against the live API on 2026-08-26.
+ */
+export declare const CONTOUR_DENSITIES: readonly ["High", "Low", "Medium"];
+export type ContourDensity = (typeof CONTOUR_DENSITIES)[number];
+/**
+ * Traffic overlay.
+ *
+ * `Congestion` was previously missing from this library's types, so it could
+ * not be requested from TypeScript even though the API accepts it.
+ */
+export declare const TRAFFIC_MODES: readonly ["All", "Congestion"];
+export type TrafficMode = (typeof TRAFFIC_MODES)[number];
+/** Routing overlays. Sent as a comma-separated list; each entry is checked. */
+export declare const TRAVEL_MODES: readonly ["Transit", "Truck"];
+export type TravelMode = (typeof TRAVEL_MODES)[number];
+/** Sprite sheet variant. One value today. */
+export declare const SPRITE_VARIANTS: readonly ["Default"];
+export type SpriteVariant = (typeof SPRITE_VARIANTS)[number];
+/** Static map label size. */
+export declare const LABEL_SIZES: readonly ["Large", "Small"];
+export type LabelSize = (typeof LABEL_SIZES)[number];
+/** Static map scale bar units. */
+export declare const SCALE_BAR_UNITS: readonly ["Kilometers", "KilometersMiles", "Miles", "MilesKilometers"];
+export type ScaleBarUnit = (typeof SCALE_BAR_UNITS)[number];
+/**
+ * Static map points-of-interest rendering.
+ *
+ * A MODE, not a list of categories — an easy one to get wrong, and the reason
+ * the static map route returned a confusing error before
+ * location-service-api#35. To filter POIs on an interactive map, use
+ * `setPoiVisibility` instead.
+ */
+export declare const MAP_FEATURE_MODES: readonly ["Disabled", "Enabled"];
+export type MapFeatureMode = (typeof MAP_FEATURE_MODES)[number];