@chaosity/location-client 0.3.0 → 0.4.0

package/dist/index.d.ts

@@ -15,6 +15,8 @@ export { POI_CATEGORIES, setAllPoiVisibility, setPoiVisibility, } from './maps/m
 export type { PoiCategory } from './maps/mapPoi';
 export { buildMapStyleUrl, fetchMapStyle } from './maps/mapStyle';
 export type { MapStyleOptions } from './maps/mapStyle';
+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';
+export type { Buildings, ColorScheme, ContourDensity, LabelSize, MapFeatureMode, MapStyle, ScaleBarUnit, SpriteVariant, StaticMapStyle, Terrain, TrafficMode, TravelMode, } from './maps/mapEnums';
 export { transformRequest } from './maps/Utils';
 export type { ClientConfig, GeoPlacesCommand, MapLike } from './types';
 export type { AppConfigClaims } from './utils/tokenClaims';

package/dist/index.js

@@ -17,5 +17,8 @@ export { createTransformRequest } from './maps/createTransformRequest';
 export { applyMapLanguage } from './maps/mapLanguage';
 export { POI_CATEGORIES, setAllPoiVisibility, setPoiVisibility, } from './maps/mapPoi';
 export { buildMapStyleUrl, fetchMapStyle } from './maps/mapStyle';
+// 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.
+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';
 export { transformRequest } from './maps/Utils';
 // Server-only utilities are available via '@chaosity/location-client/server'

package/dist/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/maps/mapEnums.js

@@ -0,0 +1,100 @@
+/**
+ * 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 const 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.
+ */
+export const STATIC_MAP_STYLES = ['Satellite', 'Standard'];
+/** Light or dark cartography. Not applicable to the raster styles. */
+export const COLOR_SCHEMES = ['Dark', 'Light'];
+/** Terrain overlay. `Hillshade` is shaded relief; `Terrain3D` is elevation. */
+export const TERRAINS = ['Hillshade', 'Terrain3D'];
+/** 3D building extrusions. One value today, kept a list for when that changes. */
+export const 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.
+ */
+export const 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.
+ */
+export const TRAFFIC_MODES = ['All', 'Congestion'];
+/** Routing overlays. Sent as a comma-separated list; each entry is checked. */
+export const TRAVEL_MODES = ['Transit', 'Truck'];
+/** Sprite sheet variant. One value today. */
+export const SPRITE_VARIANTS = ['Default'];
+/** Static map label size. */
+export const LABEL_SIZES = ['Large', 'Small'];
+/** Static map scale bar units. */
+export const 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.
+ */
+export const MAP_FEATURE_MODES = ['Disabled', 'Enabled'];

package/dist/maps/mapStyle.d.ts

@@ -1,23 +1,42 @@
 import type { StyleSpecification } from 'maplibre-gl';
+import type { Buildings, ColorScheme, ContourDensity, MapStyle, Terrain, TrafficMode, TravelMode } from './mapEnums';
 /**
  * Options for building an AWS Location Service map style URL.
  * All parameters map directly to query parameters supported by the style descriptor endpoint.
+ *
+ * Values are CASE SENSITIVE — the API rejects a wrong-cased one with a 400 that
+ * names the right spelling. Import the arrays from `mapEnums` to build pickers
+ * rather than typing the values, and the case is right by construction.
  */
 export interface MapStyleOptions {
     /** Color scheme for the map (default: Light). Not applicable to Satellite/Hybrid styles. */
-    colorScheme?: 'Light' | 'Dark';
+    colorScheme?: ColorScheme;
     /** ISO 3166-1 alpha-3 country code for political boundary perspective (e.g. 'IND', 'TUR'). */
     politicalView?: string;
     /** Terrain overlay type. */
-    terrain?: 'Hillshade' | 'Terrain3D';
+    terrain?: Terrain;
     /** Enable 3D building extrusions. */
-    buildings?: 'Buildings3D';
-    /** Elevation contour line density. Only 'Medium' is currently supported by the AWS SDK. */
-    contourDensity?: 'Medium';
-    /** Enable real-time traffic flow visualization. */
-    traffic?: 'All';
+    buildings?: Buildings;
+    /**
+     * Elevation contour line density.
+     *
+     * All of High, Low and Medium work. This was previously typed as `'Medium'`
+     * alone, documented as "the only value currently supported by the AWS SDK",
+     * which was wrong — the other two were confirmed against the live API.
+     */
+    contourDensity?: ContourDensity;
+    /**
+     * Traffic overlay.
+     *
+     * `Congestion` was previously missing here, so it could not be requested from
+     * TypeScript even though the API accepts it.
+     *
+     * Valid on its own, but NOT with every style: `Satellite` + `All` answers
+     * 400 "Traffic is not supported for style." Amazon owns that rule.
+     */
+    traffic?: TrafficMode;
     /** Travel mode overlays for routing-specific features. */
-    travelModes?: Array<'Truck' | 'Transit'>;
+    travelModes?: TravelMode[];
 }
 /**
  * Build a map style descriptor URL for the Location Service API.
@@ -31,7 +50,7 @@ export interface MapStyleOptions {
  * const url = buildMapStyleUrl(API_URL, 'Standard', { colorScheme: 'Dark', terrain: 'Hillshade' })
  * map.setStyle(url)
  */
-export declare function buildMapStyleUrl(apiUrl: string, mapStyle: string, options?: MapStyleOptions): string;
+export declare function buildMapStyleUrl(apiUrl: string, mapStyle: MapStyle, options?: MapStyleOptions): string;
 /**
  * Fetch the map style descriptor with authentication and apply descriptor-level modifications.
  *
@@ -53,6 +72,6 @@ export declare function buildMapStyleUrl(apiUrl: string, mapStyle: string, optio
  * const style = await fetchMapStyle(API_URL, 'Standard', getToken, { colorScheme: 'Dark', language: 'fr' })
  * const map = new maplibregl.Map({ style, transformRequest: createTransformRequest(API_URL, getToken) })
  */
-export declare function fetchMapStyle(apiUrl: string, mapStyle: string, getToken: () => string | undefined, options?: MapStyleOptions & {
+export declare function fetchMapStyle(apiUrl: string, mapStyle: MapStyle, getToken: () => string | undefined, options?: MapStyleOptions & {
     language?: string;
 }): Promise<StyleSpecification>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chaosity/location-client",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Client library for Chaosity Location Service with AWS Location Service compatibility",
   "type": "module",
   "main": "dist/index.js",