@chaosity/location-client 0.8.0 → 0.10.0

package/dist/index.js

@@ -5,9 +5,14 @@ export { DEFAULT_MAX_ATTEMPTS, DEFAULT_OVERALL_TIMEOUT_MS, DEFAULT_TIMEOUT_MS, }
 // Token refresh policy — shared by the server provider and the React provider
 export { TOKEN_REFRESH_BUFFER_SECONDS, readTokenExpiry, } from './auth/tokenRefresh.js';
 // Errors
-export { LocationServiceException } from './errors/LocationServiceException.js';
+export { FEATURE_NOT_ENTITLED, LocationServiceException, } from './errors/LocationServiceException.js';
 // Re-export AWS SDK commands and types
 export * from '@aws-sdk/client-geo-places';
+// …except the seven Places commands and their inputs, which take neither
+// IntendedUse nor Key: the service strips both from every request (#40). A
+// named export wins over the `export *` above, as GeoPlacesClient's does.
+// VerifyAddressCommand is this package's own: its route has no SDK command (#54).
+export { AutocompleteCommand, GeocodeCommand, GetPlaceCommand, ReverseGeocodeCommand, SearchNearbyCommand, SearchTextCommand, SuggestCommand, VerifyAddressCommand, } from './client/commands.js';
 // Re-export AWS Location Utilities (data type conversions)
 export * from '@aws/amazon-location-utilities-datatypes';
 // Adapters (Custom - for MapLibre integration)
@@ -20,6 +25,6 @@ export { buildMapStyleUrl, fetchMapStyle } from './maps/mapStyle.js';
 export { buildStaticMapUrl, fetchStaticMap, staticMapAccept, } from './maps/staticMap.js';
 // 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.js';
+export { BUILDINGS, COLOR_SCHEMES, CONTOUR_DENSITIES, LABEL_SIZES, MAP_FEATURE_MODES, MAP_STYLES, POI_DENSITIES, SCALE_BAR_UNITS, SPRITE_VARIANTS, STATIC_MAP_STYLES, STYLE_POI_CATEGORIES, TERRAINS, TRAFFIC_MODES, TRAVEL_MODES, } from './maps/mapEnums.js';
 export { transformRequest } from './maps/Utils.js';
 // Server-only utilities are available via '@chaosity/location-client/server'

package/dist/maps/mapEnums.d.ts

@@ -40,8 +40,26 @@
  * 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.
+ *
+ * SOME VALUES ARE PLAN FEATURES
+ *
+ * A list tagged `@planFeature <feature>` holds values the application's plan
+ * must include — every value, or only the ones named after the dash (#55). A
+ * value the plan lacks is refused 403 `FeatureNotEntitledException`, naming
+ * the feature, so a picker built from `MAP_STYLES` offers Satellite to an
+ * application that will be refused it. Leave those out of a picker, or mark
+ * them. Which plan includes which feature is not this file's to say — it can
+ * change without a release: see https://chaosity.cloud/pricing. A list with no
+ * tag is open to every plan.
+ */
+/**
+ * Map styles for the style descriptor.
+ *
+ * Refused on a plan without it: 403 `FeatureNotEntitledException`, see
+ * `FEATURE_NOT_ENTITLED` and the note at the top of this file.
+ *
+ * @planFeature satellite — Hybrid, Satellite
  */
-/** Map styles for the style descriptor. */
 export declare const MAP_STYLES: readonly ["Hybrid", "Monochrome", "Satellite", "Standard"];
 export type MapStyle = (typeof MAP_STYLES)[number];
 /**
@@ -49,16 +67,38 @@ export type MapStyle = (typeof MAP_STYLES)[number];
  *
  * `/maps/static/*` takes only Satellite and Standard. Passing Hybrid or
  * Monochrome there is a 400, so the two lists are not interchangeable.
+ *
+ * A static map with no `style` is a Satellite render, so it needs the
+ * `satellite` feature as well.
+ *
+ * Refused on a plan without it: 403 `FeatureNotEntitledException`, see
+ * `FEATURE_NOT_ENTITLED` and the note at the top of this file.
+ *
+ * @planFeature satellite — Satellite
  */
 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. */
+/**
+ * Terrain overlay. `Hillshade` is shaded relief; `Terrain3D` is elevation.
+ *
+ * Refused on a plan without it: 403 `FeatureNotEntitledException`, see
+ * `FEATURE_NOT_ENTITLED` and the note at the top of this file.
+ *
+ * @planFeature terrain
+ */
 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. */
+/**
+ * 3D building extrusions. A list, like the others, for when Amazon adds a value.
+ *
+ * Refused on a plan without it: 403 `FeatureNotEntitledException`, see
+ * `FEATURE_NOT_ENTITLED` and the note at the top of this file.
+ *
+ * @planFeature buildings
+ */
 export declare const BUILDINGS: readonly ["Buildings3D"];
 export type Buildings = (typeof BUILDINGS)[number];
 /**
@@ -67,6 +107,11 @@ export type Buildings = (typeof BUILDINGS)[number];
  * 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.
+ *
+ * Refused on a plan without it: 403 `FeatureNotEntitledException`, see
+ * `FEATURE_NOT_ENTITLED` and the note at the top of this file.
+ *
+ * @planFeature contours
  */
 export declare const CONTOUR_DENSITIES: readonly ["High", "Low", "Medium"];
 export type ContourDensity = (typeof CONTOUR_DENSITIES)[number];
@@ -75,10 +120,22 @@ export type ContourDensity = (typeof CONTOUR_DENSITIES)[number];
  *
  * `Congestion` was previously missing from this library's types, so it could
  * not be requested from TypeScript even though the API accepts it.
+ *
+ * Refused on a plan without it: 403 `FeatureNotEntitledException`, see
+ * `FEATURE_NOT_ENTITLED` and the note at the top of this file.
+ *
+ * @planFeature traffic
  */
 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. */
+/**
+ * Routing overlays. Sent as a comma-separated list; each entry is checked.
+ *
+ * Refused on a plan without it: 403 `FeatureNotEntitledException`, see
+ * `FEATURE_NOT_ENTITLED` and the note at the top of this file.
+ *
+ * @planFeature travel-modes
+ */
 export declare const TRAVEL_MODES: readonly ["Transit", "Truck"];
 export type TravelMode = (typeof TRAVEL_MODES)[number];
 /** Sprite sheet variant. One value today. */
@@ -100,3 +157,24 @@ export type ScaleBarUnit = (typeof SCALE_BAR_UNITS)[number];
  */
 export declare const MAP_FEATURE_MODES: readonly ["Disabled", "Enabled"];
 export type MapFeatureMode = (typeof MAP_FEATURE_MODES)[number];
+/**
+ * How many points of interest the style descriptor draws (#40). `Off` removes
+ * the poi layers outright; the others thin them out or add more.
+ *
+ * Standard and Hybrid accept it; Monochrome and Satellite answer 400 naming
+ * the parameter, as they do for `STYLE_POI_CATEGORIES`. That is the API's rule
+ * to answer, like every combination rule above.
+ */
+export declare const POI_DENSITIES: readonly ["Default", "Dense", "Off", "Sparse", "VeryDense", "VerySparse"];
+export type PoiDensity = (typeof POI_DENSITIES)[number];
+/**
+ * The categories of point of interest a style descriptor can be limited to
+ * (#40). Sent as a comma-separated list; only the named categories are drawn.
+ *
+ * Not `PoiCategory`: that name is already this package's type for
+ * `setPoiVisibility`'s layer groups, which hide categories on a map already
+ * loaded. This one asks the API for a descriptor that draws only these — the
+ * SDK's name qualified the way `TRAFFIC_MODES` and `SPRITE_VARIANTS` are.
+ */
+export declare const STYLE_POI_CATEGORIES: readonly ["Accommodations", "BusinessAndServices", "Entertainment", "FacilitiesAndBuildings", "FoodAndDrink", "LeisureAndOutdoor", "Shopping", "SightsAndMuseums", "Transportation"];
+export type StylePoiCategory = (typeof STYLE_POI_CATEGORIES)[number];

package/dist/maps/mapEnums.js

@@ -40,8 +40,26 @@
  * 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.
+ *
+ * SOME VALUES ARE PLAN FEATURES
+ *
+ * A list tagged `@planFeature <feature>` holds values the application's plan
+ * must include — every value, or only the ones named after the dash (#55). A
+ * value the plan lacks is refused 403 `FeatureNotEntitledException`, naming
+ * the feature, so a picker built from `MAP_STYLES` offers Satellite to an
+ * application that will be refused it. Leave those out of a picker, or mark
+ * them. Which plan includes which feature is not this file's to say — it can
+ * change without a release: see https://chaosity.cloud/pricing. A list with no
+ * tag is open to every plan.
+ */
+/**
+ * Map styles for the style descriptor.
+ *
+ * Refused on a plan without it: 403 `FeatureNotEntitledException`, see
+ * `FEATURE_NOT_ENTITLED` and the note at the top of this file.
+ *
+ * @planFeature satellite — Hybrid, Satellite
  */
-/** Map styles for the style descriptor. */
 export const MAP_STYLES = [
     'Hybrid',
     'Monochrome',
@@ -53,13 +71,35 @@ export const MAP_STYLES = [
  *
  * `/maps/static/*` takes only Satellite and Standard. Passing Hybrid or
  * Monochrome there is a 400, so the two lists are not interchangeable.
+ *
+ * A static map with no `style` is a Satellite render, so it needs the
+ * `satellite` feature as well.
+ *
+ * Refused on a plan without it: 403 `FeatureNotEntitledException`, see
+ * `FEATURE_NOT_ENTITLED` and the note at the top of this file.
+ *
+ * @planFeature satellite — Satellite
  */
 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. */
+/**
+ * Terrain overlay. `Hillshade` is shaded relief; `Terrain3D` is elevation.
+ *
+ * Refused on a plan without it: 403 `FeatureNotEntitledException`, see
+ * `FEATURE_NOT_ENTITLED` and the note at the top of this file.
+ *
+ * @planFeature terrain
+ */
 export const TERRAINS = ['Hillshade', 'Terrain3D'];
-/** 3D building extrusions. One value today, kept a list for when that changes. */
+/**
+ * 3D building extrusions. A list, like the others, for when Amazon adds a value.
+ *
+ * Refused on a plan without it: 403 `FeatureNotEntitledException`, see
+ * `FEATURE_NOT_ENTITLED` and the note at the top of this file.
+ *
+ * @planFeature buildings
+ */
 export const BUILDINGS = ['Buildings3D'];
 /**
  * Elevation contour line density.
@@ -67,6 +107,11 @@ export const BUILDINGS = ['Buildings3D'];
  * 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.
+ *
+ * Refused on a plan without it: 403 `FeatureNotEntitledException`, see
+ * `FEATURE_NOT_ENTITLED` and the note at the top of this file.
+ *
+ * @planFeature contours
  */
 export const CONTOUR_DENSITIES = ['High', 'Low', 'Medium'];
 /**
@@ -74,9 +119,21 @@ export const CONTOUR_DENSITIES = ['High', 'Low', 'Medium'];
  *
  * `Congestion` was previously missing from this library's types, so it could
  * not be requested from TypeScript even though the API accepts it.
+ *
+ * Refused on a plan without it: 403 `FeatureNotEntitledException`, see
+ * `FEATURE_NOT_ENTITLED` and the note at the top of this file.
+ *
+ * @planFeature traffic
  */
 export const TRAFFIC_MODES = ['All', 'Congestion'];
-/** Routing overlays. Sent as a comma-separated list; each entry is checked. */
+/**
+ * Routing overlays. Sent as a comma-separated list; each entry is checked.
+ *
+ * Refused on a plan without it: 403 `FeatureNotEntitledException`, see
+ * `FEATURE_NOT_ENTITLED` and the note at the top of this file.
+ *
+ * @planFeature travel-modes
+ */
 export const TRAVEL_MODES = ['Transit', 'Truck'];
 /** Sprite sheet variant. One value today. */
 export const SPRITE_VARIANTS = ['Default'];
@@ -98,3 +155,39 @@ export const SCALE_BAR_UNITS = [
  * `setPoiVisibility` instead.
  */
 export const MAP_FEATURE_MODES = ['Disabled', 'Enabled'];
+/**
+ * How many points of interest the style descriptor draws (#40). `Off` removes
+ * the poi layers outright; the others thin them out or add more.
+ *
+ * Standard and Hybrid accept it; Monochrome and Satellite answer 400 naming
+ * the parameter, as they do for `STYLE_POI_CATEGORIES`. That is the API's rule
+ * to answer, like every combination rule above.
+ */
+export const POI_DENSITIES = [
+    'Default',
+    'Dense',
+    'Off',
+    'Sparse',
+    'VeryDense',
+    'VerySparse',
+];
+/**
+ * The categories of point of interest a style descriptor can be limited to
+ * (#40). Sent as a comma-separated list; only the named categories are drawn.
+ *
+ * Not `PoiCategory`: that name is already this package's type for
+ * `setPoiVisibility`'s layer groups, which hide categories on a map already
+ * loaded. This one asks the API for a descriptor that draws only these — the
+ * SDK's name qualified the way `TRAFFIC_MODES` and `SPRITE_VARIANTS` are.
+ */
+export const STYLE_POI_CATEGORIES = [
+    'Accommodations',
+    'BusinessAndServices',
+    'Entertainment',
+    'FacilitiesAndBuildings',
+    'FoodAndDrink',
+    'LeisureAndOutdoor',
+    'Shopping',
+    'SightsAndMuseums',
+    'Transportation',
+];

package/dist/maps/mapStyle.d.ts

@@ -1,6 +1,6 @@
 import type { StyleSpecification } from 'maplibre-gl';
 import type { RequestOptions } from '../transport/http.js';
-import type { Buildings, ColorScheme, ContourDensity, MapStyle, Terrain, TrafficMode, TravelMode } from './mapEnums.js';
+import type { Buildings, ColorScheme, ContourDensity, MapStyle, PoiDensity, StylePoiCategory, Terrain, TrafficMode, TravelMode } from './mapEnums.js';
 /**
  * Options for building an AWS Location Service map style URL.
  * All parameters map directly to query parameters supported by the style descriptor endpoint.
@@ -8,15 +8,46 @@ import type { Buildings, ColorScheme, ContourDensity, MapStyle, Terrain, Traffic
  * 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.
+ *
+ * The options tagged `@planFeature` are PLAN FEATURES, each tag naming its
+ * feature (#55). An application whose plan does not include one is
+ * refused 403 `FeatureNotEntitledException` — `isFeatureNotEntitled` on the
+ * error — before anything is drawn, and the message names the feature and the
+ * option that asked for it. `colorScheme`, `poiDensity` and `poiCategories`
+ * are open to every plan, as are the Standard and Monochrome styles. Which plan
+ * includes which feature is not this package's to say, since it can change
+ * without a release: see https://chaosity.cloud/pricing.
  */
 export interface MapStyleOptions {
     /** Color scheme for the map (default: Light). Not applicable to Satellite/Hybrid styles. */
     colorScheme?: ColorScheme;
-    /** ISO 3166-1 alpha-3 country code for political boundary perspective (e.g. 'IND', 'TUR'). */
+    /**
+     * ISO 3166-1 alpha-3 country code for political boundary perspective
+     * (e.g. 'IND', 'TUR').
+     *
+     * Refused on a plan without it: 403 `FeatureNotEntitledException` (see
+     * `FEATURE_NOT_ENTITLED`).
+     *
+     * @planFeature political-view
+     */
     politicalView?: string;
-    /** Terrain overlay type. */
+    /**
+     * Terrain overlay type.
+     *
+     * Refused on a plan without it: 403 `FeatureNotEntitledException` (see
+     * `FEATURE_NOT_ENTITLED`).
+     *
+     * @planFeature terrain
+     */
     terrain?: Terrain;
-    /** Enable 3D building extrusions. */
+    /**
+     * Enable 3D building extrusions.
+     *
+     * Refused on a plan without it: 403 `FeatureNotEntitledException` (see
+     * `FEATURE_NOT_ENTITLED`).
+     *
+     * @planFeature buildings
+     */
     buildings?: Buildings;
     /**
      * Elevation contour line density.
@@ -24,6 +55,11 @@ export interface MapStyleOptions {
      * 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.
+     *
+     * Refused on a plan without it: 403 `FeatureNotEntitledException` (see
+     * `FEATURE_NOT_ENTITLED`).
+     *
+     * @planFeature contours
      */
     contourDensity?: ContourDensity;
     /**
@@ -34,21 +70,48 @@ export interface MapStyleOptions {
      *
      * Valid on its own, but NOT with every style: `Satellite` + `All` answers
      * 400 "Traffic is not supported for style." Amazon owns that rule.
+     *
+     * Refused on a plan without it: 403 `FeatureNotEntitledException` (see
+     * `FEATURE_NOT_ENTITLED`).
+     *
+     * @planFeature traffic
      */
     traffic?: TrafficMode;
-    /** Travel mode overlays for routing-specific features. */
+    /**
+     * Travel mode overlays for routing-specific features.
+     *
+     * Refused on a plan without it: 403 `FeatureNotEntitledException` (see
+     * `FEATURE_NOT_ENTITLED`).
+     *
+     * @planFeature travel-modes
+     */
     travelModes?: TravelMode[];
+    /**
+     * How many points of interest to draw; `Off` draws none. Standard and
+     * Hybrid only — Monochrome and Satellite answer 400.
+     */
+    poiDensity?: PoiDensity;
+    /**
+     * Draw only these categories of point of interest. Standard and Hybrid
+     * only, like `poiDensity`.
+     */
+    poiCategories?: StylePoiCategory[];
 }
 /**
  * Build a map style descriptor URL for the Location Service API.
  *
+ * MapLibre fetches this URL itself, so a refusal of it never reaches this
+ * package's error type — see `fetchMapStyle` for what it looks like instead.
+ *
  * @param apiUrl - Base URL of the Location Service API
- * @param mapStyle - Map style name (e.g. 'Standard', 'Monochrome', 'Satellite', 'Hybrid')
- * @param options - Optional style parameters
+ * @param mapStyle - Map style name: 'Standard' or 'Monochrome', or 'Satellite'
+ *   or 'Hybrid', which need the `satellite` plan feature (see `MAP_STYLES`)
+ * @param options - Optional style parameters; those tagged `@planFeature` need
+ *   that feature of the application's plan
  * @returns Full style descriptor URL
  *
  * @example
- * const url = buildMapStyleUrl(API_URL, 'Standard', { colorScheme: 'Dark', terrain: 'Hillshade' })
+ * const url = buildMapStyleUrl(API_URL, 'Standard', { colorScheme: 'Dark' })
  * map.setStyle(url)
  */
 export declare function buildMapStyleUrl(apiUrl: string, mapStyle: MapStyle, options?: MapStyleOptions): string;
@@ -63,10 +126,24 @@ export declare function buildMapStyleUrl(apiUrl: string, mapStyle: MapStyle, opt
  * `map.setStyle()`. Tile, glyph, and sprite requests still go through `transformRequest`
  * for authentication — this only pre-processes the descriptor itself.
  *
+ * A REFUSED OPTION. This is the path that surfaces a plan refusal as this
+ * package's error: an option tagged `@planFeature` that the application's plan
+ * does not include rejects with a `LocationServiceException` whose
+ * `isFeatureNotEntitled` is true (code `FeatureNotEntitledException`, status
+ * 403), and whose message names the feature and the option. What MapLibre
+ * fetches for itself — a URL from `buildMapStyleUrl` handed to `setStyle`, and
+ * the tiles — is refused the same way when it asks for a feature the plan
+ * lacks, but the refusal arrives as a MapLibre `error` event instead:
+ * `event.error.status` is 403, and `event.error.body` is a `Blob` holding the
+ * same `{ message, code }` JSON.
+ *
  * @param apiUrl - Base URL of the Location Service API
- * @param mapStyle - Map style name (e.g. 'Standard', 'Monochrome', 'Satellite', 'Hybrid')
+ * @param mapStyle - Map style name: 'Standard' or 'Monochrome', or 'Satellite'
+ *   or 'Hybrid', which need the `satellite` plan feature (see `MAP_STYLES`)
  * @param getToken - Callback returning the current auth token
- * @param options - Style options; `language` is applied to the descriptor, all others become URL params
+ * @param options - Style options; `language` is applied to the descriptor, all
+ *   others become URL params. Those tagged `@planFeature` need that feature of
+ *   the application's plan
  * @param request - Transport options: `signal` to cancel, `timeoutMs`, `overallTimeoutMs`, `retry`
  * @returns Modified MapLibre StyleSpecification object
  *

package/dist/maps/mapStyle.js

@@ -4,13 +4,18 @@ import { labelsByName, languageExpression } from './mapLanguage.js';
 /**
  * Build a map style descriptor URL for the Location Service API.
  *
+ * MapLibre fetches this URL itself, so a refusal of it never reaches this
+ * package's error type — see `fetchMapStyle` for what it looks like instead.
+ *
  * @param apiUrl - Base URL of the Location Service API
- * @param mapStyle - Map style name (e.g. 'Standard', 'Monochrome', 'Satellite', 'Hybrid')
- * @param options - Optional style parameters
+ * @param mapStyle - Map style name: 'Standard' or 'Monochrome', or 'Satellite'
+ *   or 'Hybrid', which need the `satellite` plan feature (see `MAP_STYLES`)
+ * @param options - Optional style parameters; those tagged `@planFeature` need
+ *   that feature of the application's plan
  * @returns Full style descriptor URL
  *
  * @example
- * const url = buildMapStyleUrl(API_URL, 'Standard', { colorScheme: 'Dark', terrain: 'Hillshade' })
+ * const url = buildMapStyleUrl(API_URL, 'Standard', { colorScheme: 'Dark' })
  * map.setStyle(url)
  */
 export function buildMapStyleUrl(apiUrl, mapStyle, options = {}) {
@@ -29,6 +34,10 @@ export function buildMapStyleUrl(apiUrl, mapStyle, options = {}) {
         params.set('traffic', options.traffic);
     if (options.travelModes?.length)
         params.set('travel-modes', options.travelModes.join(','));
+    if (options.poiDensity)
+        params.set('poi-density', options.poiDensity);
+    if (options.poiCategories?.length)
+        params.set('poi-categories', options.poiCategories.join(','));
     const qs = params.toString();
     return `${apiUrl}/maps/${mapStyle}/descriptor${qs ? `?${qs}` : ''}`;
 }
@@ -43,10 +52,24 @@ export function buildMapStyleUrl(apiUrl, mapStyle, options = {}) {
  * `map.setStyle()`. Tile, glyph, and sprite requests still go through `transformRequest`
  * for authentication — this only pre-processes the descriptor itself.
  *
+ * A REFUSED OPTION. This is the path that surfaces a plan refusal as this
+ * package's error: an option tagged `@planFeature` that the application's plan
+ * does not include rejects with a `LocationServiceException` whose
+ * `isFeatureNotEntitled` is true (code `FeatureNotEntitledException`, status
+ * 403), and whose message names the feature and the option. What MapLibre
+ * fetches for itself — a URL from `buildMapStyleUrl` handed to `setStyle`, and
+ * the tiles — is refused the same way when it asks for a feature the plan
+ * lacks, but the refusal arrives as a MapLibre `error` event instead:
+ * `event.error.status` is 403, and `event.error.body` is a `Blob` holding the
+ * same `{ message, code }` JSON.
+ *
  * @param apiUrl - Base URL of the Location Service API
- * @param mapStyle - Map style name (e.g. 'Standard', 'Monochrome', 'Satellite', 'Hybrid')
+ * @param mapStyle - Map style name: 'Standard' or 'Monochrome', or 'Satellite'
+ *   or 'Hybrid', which need the `satellite` plan feature (see `MAP_STYLES`)
  * @param getToken - Callback returning the current auth token
- * @param options - Style options; `language` is applied to the descriptor, all others become URL params
+ * @param options - Style options; `language` is applied to the descriptor, all
+ *   others become URL params. Those tagged `@planFeature` need that feature of
+ *   the application's plan
  * @param request - Transport options: `signal` to cancel, `timeoutMs`, `overallTimeoutMs`, `retry`
  * @returns Modified MapLibre StyleSpecification object
  *

package/dist/maps/staticMap.d.ts

@@ -31,6 +31,17 @@ import type { ColorScheme, LabelSize, MapFeatureMode, ScaleBarUnit, StaticMapSty
  */
 /** `map`, or `map@2x` for a retina render. There is no file extension. */
 export type StaticMapFileName = 'map' | 'map@2x';
+/**
+ * Render options for `buildStaticMapUrl` and `fetchStaticMap`.
+ *
+ * The options tagged `@planFeature` are PLAN FEATURES (#55): a Satellite
+ * `style` — which is also what an omitted `style` renders — needs `satellite`,
+ * and `politicalView` needs `political-view`. An application whose plan does
+ * not include one is refused 403 `FeatureNotEntitledException` —
+ * `isFeatureNotEntitled` on the error — and the message names the feature and
+ * the option. Every other option is open to every plan. Which plan includes
+ * which feature: https://chaosity.cloud/pricing.
+ */
 export interface StaticMapOptions {
     /** Pixels, 64-1500. */
     width: number;
@@ -46,6 +57,16 @@ export interface StaticMapOptions {
     radius?: number;
     padding?: number;
     cropLabels?: boolean;
+    /**
+     * `Standard` or `Satellite`. Omitted, the render is Satellite — the
+     * service's default — so pass `'Standard'` for a render every plan may
+     * request.
+     *
+     * Satellite is refused on a plan without it: 403
+     * `FeatureNotEntitledException` (see `FEATURE_NOT_ENTITLED`).
+     *
+     * @planFeature satellite — Satellite
+     */
     style?: StaticMapStyle;
     colorScheme?: ColorScheme;
     labelSize?: LabelSize;
@@ -58,6 +79,21 @@ export interface StaticMapOptions {
     scaleBarUnit?: ScaleBarUnit;
     /** Defaults to `map`. */
     fileName?: StaticMapFileName;
+    /**
+     * ISO 3166-1 alpha-3 country whose view of disputed borders to draw.
+     *
+     * Refused on a plan without it: 403 `FeatureNotEntitledException` (see
+     * `FEATURE_NOT_ENTITLED`).
+     *
+     * @planFeature political-view
+     */
+    politicalView?: string;
+    /** Label language, a BCP-47 tag such as `fr` or `zh-Hant`. */
+    language?: string;
+    /** Markers and lines in Amazon Location's compact overlay syntax. */
+    compactOverlay?: string;
+    /** A GeoJSON FeatureCollection to draw, as JSON text. */
+    geoJsonOverlay?: string;
 }
 /**
  * The Accept header this request must send.
@@ -72,6 +108,10 @@ export declare function buildStaticMapUrl(apiUrl: string, options: StaticMapOpti
 /**
  * Fetch a static map as a Blob.
  *
+ * A refused plan feature — a Satellite `style`, the default when none is
+ * given, or a `politicalView` — rejects with a `LocationServiceException`
+ * whose `isFeatureNotEntitled` is true, as `fetchMapStyle` does.
+ *
  * @param apiUrl   Base URL of the Location Service API
  * @param options  Render options; exactly one of center / boundingBox / boundedPositions
  * @param getToken Callback returning the current auth token

package/dist/maps/staticMap.js

@@ -48,6 +48,10 @@ export function buildStaticMapUrl(apiUrl, options) {
 /**
  * Fetch a static map as a Blob.
  *
+ * A refused plan feature — a Satellite `style`, the default when none is
+ * given, or a `politicalView` — rejects with a `LocationServiceException`
+ * whose `isFeatureNotEntitled` is true, as `fetchMapStyle` does.
+ *
  * @param apiUrl   Base URL of the Location Service API
  * @param options  Render options; exactly one of center / boundingBox / boundedPositions
  * @param getToken Callback returning the current auth token

package/dist/server/LocationServiceConnector.d.ts

@@ -1,3 +1,4 @@
+import type { VerifyAddressResponse } from '../client/commands.js';
 import type { RequestOptions } from '../transport/http.js';
 import type { AppConfigClaims } from '../utils/tokenClaims.js';
 export interface ConnectorConfig {
@@ -56,7 +57,13 @@ export interface SendOptions extends RequestOptions {
  * ```typescript
  * // Credentials and apiUrl from the environment, Origin supplied here
  * const connector = new LocationServiceConnector({ origin: 'https://app.example.com' })
- * const result = await connector.send(new SearchTextCommand({ QueryText: 'Space Needle' }))
+ * const result = await connector.send(
+ *   new SearchTextCommand({
+ *     QueryText: 'Space Needle',
+ *     // SearchText takes exactly one of BiasPosition, Filter.BoundingBox or Filter.Circle.
+ *     BiasPosition: [-122.3493, 47.6205],
+ *   }),
+ * )
  * ```
  */
 export declare class LocationServiceConnector {
@@ -77,17 +84,19 @@ export declare class LocationServiceConnector {
     private buildSource;
     /**
      * This application's own configuration, as carried on the access token
-     * (api#65) — bias precision, and the countries it is scoped to.
+     * (api#65): the routes it may call, the domain its requests must come from,
+     * and the countries it is scoped to (#40).
      *
      * 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.
+     * any of it 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.
+     * Every token the API issues carries `allowedResources` and `allowedDomain`;
+     * `countries` only once a scope is configured in the portal. Returns `{}`
+     * for a token carrying none of them.
      */
     getAppConfig(): Promise<AppConfigClaims>;
     /**
@@ -99,6 +108,15 @@ export declare class LocationServiceConnector {
      */
     private effectiveOrigin;
     send<TInput, TOutput>(command: TInput, options?: SendOptions): Promise<TOutput>;
+    /**
+     * Verify a PlaceId: `send(new VerifyAddressCommand({ PlaceId }))`, typed
+     * (#54). Resolves the full place record plus `verified`, and resolves a
+     * `verified: false` too — see VerifyAddressResponse for what may be stored.
+     *
+     * Billed per call, whether or not the address verifies: call it once per
+     * chosen PlaceId, never per keystroke.
+     */
+    verifyAddress(placeId: string, options?: SendOptions): Promise<VerifyAddressResponse>;
     private dispatchWithRetry;
     private dispatch;
 }