@chaosity/location-client 0.9.0 → 0.10.0

package/dist/cjs/maps/mapEnums.js

@@ -41,10 +41,28 @@
  * 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.
  */
 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.STYLE_POI_CATEGORIES = exports.POI_DENSITIES = 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.
+ *
+ * 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
+ */
 exports.MAP_STYLES = [
     'Hybrid',
     'Monochrome',
@@ -56,13 +74,35 @@ exports.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
  */
 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. */
+/**
+ * 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
+ */
 exports.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
+ */
 exports.BUILDINGS = ['Buildings3D'];
 /**
  * Elevation contour line density.
@@ -70,6 +110,11 @@ exports.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
  */
 exports.CONTOUR_DENSITIES = ['High', 'Low', 'Medium'];
 /**
@@ -77,9 +122,21 @@ exports.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
  */
 exports.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
+ */
 exports.TRAVEL_MODES = ['Transit', 'Truck'];
 /** Sprite sheet variant. One value today. */
 exports.SPRITE_VARIANTS = ['Default'];
@@ -101,3 +158,39 @@ exports.SCALE_BAR_UNITS = [
  * `setPoiVisibility` instead.
  */
 exports.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.
+ */
+exports.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.
+ */
+exports.STYLE_POI_CATEGORIES = [
+    'Accommodations',
+    'BusinessAndServices',
+    'Entertainment',
+    'FacilitiesAndBuildings',
+    'FoodAndDrink',
+    'LeisureAndOutdoor',
+    'Shopping',
+    'SightsAndMuseums',
+    'Transportation',
+];

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

@@ -8,13 +8,18 @@ const mapLanguage_js_1 = require("./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)
  */
 function buildMapStyleUrl(apiUrl, mapStyle, options = {}) {
@@ -33,6 +38,10 @@ 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}` : ''}`;
 }
@@ -47,10 +56,24 @@ 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/cjs/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/cjs/maps/staticMap.js

@@ -53,6 +53,10 @@ 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/cjs/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) — today, 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;
 }

package/dist/cjs/server/LocationServiceConnector.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.LocationServiceConnector = void 0;
 const debug_1 = __importDefault(require("debug"));
+const commands_js_1 = require("../client/commands.js");
 const LocationServiceException_js_1 = require("../errors/LocationServiceException.js");
 const endpoints_js_1 = require("../transport/endpoints.js");
 const errors_js_1 = require("../transport/errors.js");
@@ -94,7 +95,13 @@ function explainMissingOrigin(err, sentOrigin) {
  * ```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],
+ *   }),
+ * )
  * ```
  */
 class LocationServiceConnector {
@@ -157,17 +164,19 @@ class LocationServiceConnector {
     }
     /**
      * This application's own configuration, as carried on the access token
-     * (api#65) — today, 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.
      */
     async getAppConfig() {
         return (0, tokenClaims_js_1.readAppConfigClaims)(await this.source().get());
@@ -195,6 +204,17 @@ class LocationServiceConnector {
             throw explainMissingOrigin(err, this.effectiveOrigin(options));
         }
     }
+    /**
+     * 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, options) {
+        return this.send(new commands_js_1.VerifyAddressCommand({ PlaceId: placeId }), options);
+    }
     async dispatchWithRetry(source, url, cmd, options) {
         const token = await source.get();
         if (!token)

package/dist/cjs/transport/endpoints.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveEndpoint = resolveEndpoint;
 const client_geo_places_1 = require("@aws-sdk/client-geo-places");
+const commands_js_1 = require("../client/commands.js");
 const LocationServiceException_js_1 = require("../errors/LocationServiceException.js");
 /**
  * Command class -> API path.
@@ -20,6 +21,8 @@ const ENDPOINTS = new Map([
     [client_geo_places_1.SearchNearbyCommand, '/address/search/nearby'],
     [client_geo_places_1.SearchTextCommand, '/address/search/text'],
     [client_geo_places_1.SuggestCommand, '/address/suggestion'],
+    // This package's own: the route has no AWS command (#54).
+    [commands_js_1.VerifyAddressCommand, '/address/verify'],
 ]);
 function resolveEndpoint(command) {
     for (const [CommandClass, endpoint] of ENDPOINTS) {

package/dist/cjs/transport/http.d.ts

@@ -4,8 +4,8 @@ export declare const DEFAULT_TIMEOUT_MS = 10000;
  * Ceiling for the WHOLE call — every attempt plus every wait between them.
  *
  * `timeoutMs` bounds an attempt, not a call, and the gap between those two is
- * where the caller's own deadline disappears. The API answers a spent quota
- * with `Retry-After: 60`, which the retry loop honoured literally: two waits of
+ * where the caller's own deadline disappears. Nothing bounds the `Retry-After`
+ * a 429 carries, and the retry loop honoured one of 60 s literally: two waits of
  * a minute each, so one call could sit for ~120 s — past any Lambda budget,
  * past any HTTP gateway, and until now uncancellable (#37).
  *

package/dist/cjs/transport/http.js

@@ -17,8 +17,8 @@ exports.DEFAULT_TIMEOUT_MS = 10000;
  * Ceiling for the WHOLE call — every attempt plus every wait between them.
  *
  * `timeoutMs` bounds an attempt, not a call, and the gap between those two is
- * where the caller's own deadline disappears. The API answers a spent quota
- * with `Retry-After: 60`, which the retry loop honoured literally: two waits of
+ * where the caller's own deadline disappears. Nothing bounds the `Retry-After`
+ * a 429 carries, and the retry loop honoured one of 60 s literally: two waits of
  * a minute each, so one call could sit for ~120 s — past any Lambda budget,
  * past any HTTP gateway, and until now uncancellable (#37).
  *

package/dist/cjs/types/index.d.ts

@@ -42,11 +42,12 @@ export interface ClientConfig {
     refreshToken?: () => Promise<string | undefined>;
 }
 /**
- * Minimal interface for AWS SDK command objects.
- * All AWS SDK commands (AutocompleteCommand, SearchTextCommand, etc.) extend
- * Smithy's Command base class which has an `input` property containing the
- * request parameters. This interface captures what we actually need from
- * commands without coupling to Smithy internals.
+ * Minimal interface for a command object: the AWS SDK's, and this package's
+ * own `VerifyAddressCommand` (#54). The SDK's commands (AutocompleteCommand,
+ * SearchTextCommand, etc.) extend Smithy's Command base class, which has an
+ * `input` property containing the request parameters; `VerifyAddressCommand`
+ * has the same `input` and nothing else. This interface captures what we
+ * actually need from commands without coupling to Smithy internals.
  */
 export interface GeoPlacesCommand {
     readonly input: object;

package/dist/cjs/utils/tokenClaims.d.ts

@@ -1,9 +1,11 @@
 /**
  * Read advisory application config out of the access token (api#65).
  *
- * The API puts an application's own settings — today just `countries` — into
- * the JWT alongside `allowedDomain` and `allowedResources`, so this library can
- * stop hard-coding values it has no other way of knowing.
+ * The API puts an application's own settings into the JWT — `countries`,
+ * `allowedResources` and `allowedDomain` — so this library can stop
+ * hard-coding values it has no other way of knowing. The last two were in the
+ * token all along and were not surfaced until #40, so an application could
+ * only learn it lacked a route from the 403.
  *
  * `biasDecimals` used to be here too. It sized the grid this library rounded
  * `BiasPosition` onto, so that nearby callers shared a server cache entry; the
@@ -42,6 +44,30 @@ export interface AppConfigClaims {
      * Sending nothing and letting the API scope the request is always correct.
      */
     countries?: string[];
+    /**
+     * The routes this application may call, as the API names them — method and
+     * route template, such as `POST /address/autocomplete` or
+     * `GET /maps/static/{fileName}` (#40).
+     *
+     * So an application can ask "may I call the static-map route?" before it
+     * offers one, rather than only learning from the 403. It answers for the
+     * route, not for the options sent on it: a plan feature (`@planFeature`) is
+     * answered only by its own 403, and a static map's default Satellite render
+     * is one (#55). The same rule as `countries`
+     * applies, for the same reason: show it, never refuse with it. A route
+     * granted since the token was minted is answered by the API, which reads the
+     * entitlement fresh on every request.
+     *
+     * The API issues this claim JSON-encoded — a string holding the list —
+     * because it copies the application's stored setting. Both forms are read.
+     */
+    allowedResources?: string[];
+    /**
+     * The domain this application's requests must come from (#40). A request
+     * whose `Origin` is neither this host nor one of its subdomains is refused
+     * 403, so this is what to show next to "Origin not allowed".
+     */
+    allowedDomain?: string;
 }
 /**
  * Decode a JWT payload without verifying it.