@chaosity/location-client 0.5.1 → 0.6.0

package/dist/cjs/client/GeoPlacesClient.js

@@ -0,0 +1,68 @@
+"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 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() {
+        const token = this.clientConfig.getToken?.() ?? this.clientConfig.token;
+        return (0, tokenClaims_js_1.readAppConfigClaims)(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 endpoint = (0, endpoints_js_1.resolveEndpoint)(cmd);
+        // Prefer the getToken callback (live ref) over a static token string.
+        const token = this.clientConfig.getToken?.() ?? this.clientConfig.token;
+        // Resolve the token BEFORE rounding: the precision this application is
+        // entitled to is a claim on it (api#65). Absent claim -> the 3 dp floor.
+        const { biasDecimals } = (0, tokenClaims_js_1.readAppConfigClaims)(token);
+        const input = (0, roundPosition_js_1.roundPositionFields)(cmd.input, biasDecimals);
+        log('Sending %s to %s', cmd.constructor?.name, endpoint);
+        return (0, http_js_1.requestJson)(`${this.clientConfig.apiUrl}${endpoint}`, {
+            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,10 @@
+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.
+ *
+ * @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,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTransformRequest = createTransformRequest;
+/**
+ * Creates a transformRequest function for MapLibre that adds authentication
+ * and proper Accept headers for AWS Location Service API requests.
+ *
+ * @param apiUrl - Base URL of the Location Service API
+ * @param getToken - Callback function that returns the current auth token
+ * @returns MapLibre transformRequest function
+ */
+function createTransformRequest(apiUrl, getToken) {
+    return (url, _resourceType) => {
+        if (url.startsWith(apiUrl)) {
+            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];

package/dist/cjs/maps/mapEnums.js

@@ -0,0 +1,103 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAP_FEATURE_MODES = exports.SCALE_BAR_UNITS = exports.LABEL_SIZES = exports.SPRITE_VARIANTS = exports.TRAVEL_MODES = exports.TRAFFIC_MODES = exports.CONTOUR_DENSITIES = exports.BUILDINGS = exports.TERRAINS = exports.COLOR_SCHEMES = exports.STATIC_MAP_STYLES = exports.MAP_STYLES = void 0;
+/** Map styles for the style descriptor. */
+exports.MAP_STYLES = [
+    'Hybrid',
+    'Monochrome',
+    'Satellite',
+    'Standard',
+];
+/**
+ * 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.
+ */
+exports.STATIC_MAP_STYLES = ['Satellite', 'Standard'];
+/** Light or dark cartography. Not applicable to the raster styles. */
+exports.COLOR_SCHEMES = ['Dark', 'Light'];
+/** Terrain overlay. `Hillshade` is shaded relief; `Terrain3D` is elevation. */
+exports.TERRAINS = ['Hillshade', 'Terrain3D'];
+/** 3D building extrusions. One value today, kept a list for when that changes. */
+exports.BUILDINGS = ['Buildings3D'];
+/**
+ * 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.
+ */
+exports.CONTOUR_DENSITIES = ['High', 'Low', 'Medium'];
+/**
+ * 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.
+ */
+exports.TRAFFIC_MODES = ['All', 'Congestion'];
+/** Routing overlays. Sent as a comma-separated list; each entry is checked. */
+exports.TRAVEL_MODES = ['Transit', 'Truck'];
+/** Sprite sheet variant. One value today. */
+exports.SPRITE_VARIANTS = ['Default'];
+/** Static map label size. */
+exports.LABEL_SIZES = ['Large', 'Small'];
+/** Static map scale bar units. */
+exports.SCALE_BAR_UNITS = [
+    'Kilometers',
+    'KilometersMiles',
+    'Miles',
+    'MilesKilometers',
+];
+/**
+ * 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.
+ */
+exports.MAP_FEATURE_MODES = ['Disabled', 'Enabled'];

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

@@ -0,0 +1,43 @@
+import type { MapLike } from '../types/index.js';
+/**
+ * The `text-field` expression that prefers `language`, then English, then the
+ * feature's default name.
+ *
+ * Based on the approach documented at:
+ * https://docs.aws.amazon.com/location/latest/developerguide/how-to-set-preferred-language-map.html
+ */
+export declare function languageExpression(language: string): unknown[];
+/**
+ * Whether a `text-field` reads a name property — the only kind of label a
+ * language rewrite makes sense for (#28).
+ *
+ * The AWS Standard style has 62 symbol layers with a text-field and 30 of
+ * them do NOT label by name: `building_label_number` reads
+ * `addr_housenumber`, and the 29 `shield_*` layers read `shield_text` or
+ * `ref`. Replacing those with a `name:<lang>` coalesce points them at a
+ * property their features do not carry, and the house numbers and road
+ * shields disappear — for `en` too. Measured against the live sandbox on
+ * 2026-08-29; the testbed showed it as "one map has house numbers, the
+ * others don't".
+ *
+ * Serialising the expression is the simplest exact test: `name`, `name:en`,
+ * `name_en` and a literal `{name}` template all contain it, and none of the
+ * non-name properties do.
+ */
+export declare function labelsByName(textField: unknown): boolean;
+/**
+ * Apply a preferred display language to the name labels on a MapLibre map.
+ *
+ * AWS GeoMaps vector tiles carry `name:${lang}` properties (`name:en`,
+ * `name:fr`, `name:ja`, …). Every symbol layer whose `text-field` reads a
+ * name is rewritten to prefer the requested language, falling back to
+ * English then the default name. Layers that label by something else — house
+ * numbers, road shields — are left exactly as the style declared them.
+ *
+ * @param map - MapLibre Map instance (or any object matching the MapLike interface)
+ * @param language - ISO 639-1 language code (e.g. 'en', 'fr', 'de', 'ja', 'zh', 'ar')
+ *
+ * @example
+ * map.once('style.load', () => applyMapLanguage(map, 'fr'))
+ */
+export declare function applyMapLanguage(map: MapLike, language: string): void;