@chaosity/location-client 0.9.0 → 0.11.0

package/dist/cjs/client/GeoPlacesClient.d.ts

@@ -1,6 +1,7 @@
 import type { RequestOptions } from '../transport/http.js';
 import type { ClientConfig } from '../types/index.js';
 import type { AppConfigClaims } from '../utils/tokenClaims.js';
+import type { VerifyAddressResponse } from './commands.js';
 export type SendOptions = RequestOptions;
 /**
  * GeoPlacesClient — AWS Location Service compatible client with custom auth.
@@ -18,17 +19,19 @@ export declare class GeoPlacesClient {
     constructor(config: ClientConfig);
     /**
      * 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(): AppConfigClaims;
     /** Prefer the getToken callback (live ref) over a static token string. */
@@ -46,5 +49,14 @@ export declare class GeoPlacesClient {
      *   retry loop. Every failure throws LocationServiceException.
      */
     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, at submit, never per keystroke.
+     */
+    verifyAddress(placeId: string, options?: SendOptions): Promise<VerifyAddressResponse>;
     private dispatch;
 }

package/dist/cjs/client/GeoPlacesClient.js

@@ -9,6 +9,7 @@ const endpoints_js_1 = require("../transport/endpoints.js");
 const errors_js_1 = require("../transport/errors.js");
 const http_js_1 = require("../transport/http.js");
 const tokenClaims_js_1 = require("../utils/tokenClaims.js");
+const commands_js_1 = require("./commands.js");
 const log = (0, debug_1.default)('location-client:api');
 /**
  * GeoPlacesClient — AWS Location Service compatible client with custom auth.
@@ -25,17 +26,19 @@ class GeoPlacesClient {
     }
     /**
      * 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() {
         return (0, tokenClaims_js_1.readAppConfigClaims)(this.currentToken());
@@ -98,6 +101,17 @@ class GeoPlacesClient {
             return await this.dispatch(url, fresh, cmd, 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, at submit, never per keystroke.
+     */
+    verifyAddress(placeId, options) {
+        return this.send(new commands_js_1.VerifyAddressCommand({ PlaceId: placeId }), options);
+    }
     dispatch(url, token, cmd, options) {
         // The caller's input goes out as the caller wrote it. `BiasPosition` used
         // to be rounded here to a grid sized by a token claim, so nearby callers

package/dist/cjs/client/commands.d.ts

@@ -0,0 +1,159 @@
+import type { GetPlaceResponse, AutocompleteCommandInput as SdkAutocompleteCommandInput, AutocompleteRequest as SdkAutocompleteRequest, GeocodeCommandInput as SdkGeocodeCommandInput, GeocodeRequest as SdkGeocodeRequest, GetPlaceCommandInput as SdkGetPlaceCommandInput, GetPlaceRequest as SdkGetPlaceRequest, ReverseGeocodeCommandInput as SdkReverseGeocodeCommandInput, ReverseGeocodeRequest as SdkReverseGeocodeRequest, SearchNearbyCommandInput as SdkSearchNearbyCommandInput, SearchNearbyRequest as SdkSearchNearbyRequest, SearchTextCommandInput as SdkSearchTextCommandInput, SearchTextRequest as SdkSearchTextRequest, SuggestCommandInput as SdkSuggestCommandInput, SuggestRequest as SdkSuggestRequest } from '@aws-sdk/client-geo-places';
+import { AutocompleteCommand as SdkAutocompleteCommand, GeocodeCommand as SdkGeocodeCommand, GetPlaceCommand as SdkGetPlaceCommand, ReverseGeocodeCommand as SdkReverseGeocodeCommand, SearchNearbyCommand as SdkSearchNearbyCommand, SearchTextCommand as SdkSearchTextCommand, SuggestCommand as SdkSuggestCommand } from '@aws-sdk/client-geo-places';
+/**
+ * Request fields the Location Service removes from every request (#40).
+ *
+ * `IntendedUse` chooses the price bucket the service pays, and `Key` is an
+ * Amazon Location API key that would bill someone else's account, so neither
+ * ever reaches Amazon. The SDK's inputs declare both, and this package used to
+ * re-export those commands as they were: `IntendedUse: 'Storage'` compiled,
+ * was sent, was stripped, and came back as a result with no storage rights.
+ *
+ * So the root exports every Places command as a subclass whose constructor
+ * takes the input WITHOUT these fields. Narrowing only the input types would
+ * not have been enough — the SDK's constructor references the SDK's own type,
+ * so `new SearchTextCommand({ IntendedUse })` would still have compiled.
+ *
+ * Types only. Nothing is removed at runtime: a request body is the caller's
+ * input, unchanged, and the service does the stripping. A caller who casts
+ * past the type still sends the field and still has it ignored.
+ *
+ * `test/places-commands.test.ts` reads the command list from the SDK itself,
+ * so a command the SDK adds fails there until it is narrowed here.
+ */
+export type NeverForwarded = 'IntendedUse' | 'Key';
+export type AutocompleteRequest = Omit<SdkAutocompleteRequest, NeverForwarded>;
+export type AutocompleteCommandInput = Omit<SdkAutocompleteCommandInput, NeverForwarded>;
+export declare class AutocompleteCommand extends SdkAutocompleteCommand {
+    constructor(input: AutocompleteCommandInput);
+}
+export type GeocodeRequest = Omit<SdkGeocodeRequest, NeverForwarded>;
+export type GeocodeCommandInput = Omit<SdkGeocodeCommandInput, NeverForwarded>;
+/**
+ * Accepts rich place data, a plan feature: on a plan without it these
+ * `AdditionalFeatures` are refused 403 `FeatureNotEntitledException`
+ * (`isFeatureNotEntitled` on the error; see `FEATURE_NOT_ENTITLED`).
+ *
+ * @planFeature rich place data — Access, TimeZone
+ */
+export declare class GeocodeCommand extends SdkGeocodeCommand {
+    constructor(input: GeocodeCommandInput);
+}
+export type GetPlaceRequest = Omit<SdkGetPlaceRequest, NeverForwarded>;
+export type GetPlaceCommandInput = Omit<SdkGetPlaceCommandInput, NeverForwarded>;
+/**
+ * Accepts rich place data, a plan feature: on a plan without it these
+ * `AdditionalFeatures` are refused 403 `FeatureNotEntitledException`
+ * (`isFeatureNotEntitled` on the error; see `FEATURE_NOT_ENTITLED`).
+ *
+ * @planFeature rich place data — Access, Contact, Phonemes, TimeZone
+ */
+export declare class GetPlaceCommand extends SdkGetPlaceCommand {
+    constructor(input: GetPlaceCommandInput);
+}
+export type ReverseGeocodeRequest = Omit<SdkReverseGeocodeRequest, NeverForwarded>;
+export type ReverseGeocodeCommandInput = Omit<SdkReverseGeocodeCommandInput, NeverForwarded>;
+/**
+ * Accepts rich place data, a plan feature: on a plan without it these
+ * `AdditionalFeatures` are refused 403 `FeatureNotEntitledException`
+ * (`isFeatureNotEntitled` on the error; see `FEATURE_NOT_ENTITLED`).
+ *
+ * @planFeature rich place data — Access, TimeZone
+ */
+export declare class ReverseGeocodeCommand extends SdkReverseGeocodeCommand {
+    constructor(input: ReverseGeocodeCommandInput);
+}
+export type SearchNearbyRequest = Omit<SdkSearchNearbyRequest, NeverForwarded>;
+export type SearchNearbyCommandInput = Omit<SdkSearchNearbyCommandInput, NeverForwarded>;
+/**
+ * Accepts rich place data, a plan feature: on a plan without it these
+ * `AdditionalFeatures` are refused 403 `FeatureNotEntitledException`
+ * (`isFeatureNotEntitled` on the error; see `FEATURE_NOT_ENTITLED`).
+ *
+ * @planFeature rich place data — Access, Contact, Phonemes, TimeZone
+ */
+export declare class SearchNearbyCommand extends SdkSearchNearbyCommand {
+    constructor(input: SearchNearbyCommandInput);
+}
+export type SearchTextRequest = Omit<SdkSearchTextRequest, NeverForwarded>;
+export type SearchTextCommandInput = Omit<SdkSearchTextCommandInput, NeverForwarded>;
+/**
+ * Accepts rich place data, a plan feature: on a plan without it these
+ * `AdditionalFeatures` are refused 403 `FeatureNotEntitledException`
+ * (`isFeatureNotEntitled` on the error; see `FEATURE_NOT_ENTITLED`).
+ *
+ * @planFeature rich place data — Access, Contact, Phonemes, TimeZone
+ */
+export declare class SearchTextCommand extends SdkSearchTextCommand {
+    constructor(input: SearchTextCommandInput);
+}
+export type SuggestRequest = Omit<SdkSuggestRequest, NeverForwarded>;
+export type SuggestCommandInput = Omit<SdkSuggestCommandInput, NeverForwarded>;
+/**
+ * Accepts rich place data, a plan feature: on a plan without it these
+ * `AdditionalFeatures` are refused 403 `FeatureNotEntitledException`
+ * (`isFeatureNotEntitled` on the error; see `FEATURE_NOT_ENTITLED`).
+ *
+ * @planFeature rich place data — Access, Phonemes, TimeZone
+ */
+export declare class SuggestCommand extends SdkSuggestCommand {
+    constructor(input: SuggestCommandInput);
+}
+/**
+ * A PlaceId, and nothing else: the service forwards `PlaceId` alone to this
+ * route, so `Language`, `PoliticalView` and `AdditionalFeatures` would be
+ * dropped rather than honoured. The type refuses them instead (#54).
+ */
+export interface VerifyAddressCommandInput {
+    /**
+     * From an autocomplete, suggestion, geocode or place result — including a
+     * unit's, from a place's `SecondaryAddresses`.
+     */
+    PlaceId: string;
+}
+/**
+ * The answer to a verify: the record `GetPlaceCommand` returns — the
+ * building's units in `SecondaryAddresses` included, `$metadata` not — plus
+ * `verified`.
+ *
+ * `verified` is true for a `PointAddress`, or a `SecondaryAddress` (a unit),
+ * and false for anything else: an interpolated address, a street, a locality,
+ * a point of interest. A `false` is still a 200 and still billed, so it
+ * resolves; it never throws.
+ *
+ * This is the one Places result an integrator may store, except a place in
+ * Japan, which may not be stored at all. Every other Places result is for
+ * display.
+ *
+ * Keep the PlaceId you sent beside it. The answer's own `PlaceId` can differ,
+ * and for a unit it does: the service fails that one on every Places route,
+ * while the one you sent verifies again.
+ */
+export type VerifyAddressResponse = Omit<GetPlaceResponse, 'PricingBucket'> & {
+    /**
+     * The bucket the stored record belongs to (`Stored`), not what this call
+     * was billed at. Every verify is billed on its own meter, whether the
+     * service answered it from its store or not.
+     */
+    PricingBucket: string | undefined;
+    /** `PointAddress` or `SecondaryAddress`: the address is verified. */
+    verified: boolean;
+};
+/**
+ * `POST /address/verify` (#54): resolve one PlaceId to the full place record
+ * plus `verified`. `GeoPlacesClient.verifyAddress` and
+ * `LocationServiceConnector.verifyAddress` send this.
+ *
+ * Billed per call, whether or not the address verifies. Send it once per
+ * chosen PlaceId — at submit — never per keystroke. A repeat verify of the
+ * same PlaceId may be answered from the service's own store, and is billed
+ * all the same.
+ *
+ * Not an SDK command: the route has none. It extends nothing on purpose —
+ * `ENDPOINTS` matches by `instanceof`, so a subclass of `GetPlaceCommand`
+ * would match that entry and go to `/address/place`.
+ */
+export declare class VerifyAddressCommand {
+    readonly input: VerifyAddressCommandInput;
+    constructor(input: VerifyAddressCommandInput);
+}

package/dist/cjs/client/commands.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VerifyAddressCommand = exports.SuggestCommand = exports.SearchTextCommand = exports.SearchNearbyCommand = exports.ReverseGeocodeCommand = exports.GetPlaceCommand = exports.GeocodeCommand = exports.AutocompleteCommand = void 0;
+const client_geo_places_1 = require("@aws-sdk/client-geo-places");
+class AutocompleteCommand extends client_geo_places_1.AutocompleteCommand {
+    constructor(input) {
+        super(input);
+    }
+}
+exports.AutocompleteCommand = AutocompleteCommand;
+/**
+ * Accepts rich place data, a plan feature: on a plan without it these
+ * `AdditionalFeatures` are refused 403 `FeatureNotEntitledException`
+ * (`isFeatureNotEntitled` on the error; see `FEATURE_NOT_ENTITLED`).
+ *
+ * @planFeature rich place data — Access, TimeZone
+ */
+class GeocodeCommand extends client_geo_places_1.GeocodeCommand {
+    constructor(input) {
+        super(input);
+    }
+}
+exports.GeocodeCommand = GeocodeCommand;
+/**
+ * Accepts rich place data, a plan feature: on a plan without it these
+ * `AdditionalFeatures` are refused 403 `FeatureNotEntitledException`
+ * (`isFeatureNotEntitled` on the error; see `FEATURE_NOT_ENTITLED`).
+ *
+ * @planFeature rich place data — Access, Contact, Phonemes, TimeZone
+ */
+class GetPlaceCommand extends client_geo_places_1.GetPlaceCommand {
+    constructor(input) {
+        super(input);
+    }
+}
+exports.GetPlaceCommand = GetPlaceCommand;
+/**
+ * Accepts rich place data, a plan feature: on a plan without it these
+ * `AdditionalFeatures` are refused 403 `FeatureNotEntitledException`
+ * (`isFeatureNotEntitled` on the error; see `FEATURE_NOT_ENTITLED`).
+ *
+ * @planFeature rich place data — Access, TimeZone
+ */
+class ReverseGeocodeCommand extends client_geo_places_1.ReverseGeocodeCommand {
+    constructor(input) {
+        super(input);
+    }
+}
+exports.ReverseGeocodeCommand = ReverseGeocodeCommand;
+/**
+ * Accepts rich place data, a plan feature: on a plan without it these
+ * `AdditionalFeatures` are refused 403 `FeatureNotEntitledException`
+ * (`isFeatureNotEntitled` on the error; see `FEATURE_NOT_ENTITLED`).
+ *
+ * @planFeature rich place data — Access, Contact, Phonemes, TimeZone
+ */
+class SearchNearbyCommand extends client_geo_places_1.SearchNearbyCommand {
+    constructor(input) {
+        super(input);
+    }
+}
+exports.SearchNearbyCommand = SearchNearbyCommand;
+/**
+ * Accepts rich place data, a plan feature: on a plan without it these
+ * `AdditionalFeatures` are refused 403 `FeatureNotEntitledException`
+ * (`isFeatureNotEntitled` on the error; see `FEATURE_NOT_ENTITLED`).
+ *
+ * @planFeature rich place data — Access, Contact, Phonemes, TimeZone
+ */
+class SearchTextCommand extends client_geo_places_1.SearchTextCommand {
+    constructor(input) {
+        super(input);
+    }
+}
+exports.SearchTextCommand = SearchTextCommand;
+/**
+ * Accepts rich place data, a plan feature: on a plan without it these
+ * `AdditionalFeatures` are refused 403 `FeatureNotEntitledException`
+ * (`isFeatureNotEntitled` on the error; see `FEATURE_NOT_ENTITLED`).
+ *
+ * @planFeature rich place data — Access, Phonemes, TimeZone
+ */
+class SuggestCommand extends client_geo_places_1.SuggestCommand {
+    constructor(input) {
+        super(input);
+    }
+}
+exports.SuggestCommand = SuggestCommand;
+/**
+ * `POST /address/verify` (#54): resolve one PlaceId to the full place record
+ * plus `verified`. `GeoPlacesClient.verifyAddress` and
+ * `LocationServiceConnector.verifyAddress` send this.
+ *
+ * Billed per call, whether or not the address verifies. Send it once per
+ * chosen PlaceId — at submit — never per keystroke. A repeat verify of the
+ * same PlaceId may be answered from the service's own store, and is billed
+ * all the same.
+ *
+ * Not an SDK command: the route has none. It extends nothing on purpose —
+ * `ENDPOINTS` matches by `instanceof`, so a subclass of `GetPlaceCommand`
+ * would match that entry and go to `/address/place`.
+ */
+class VerifyAddressCommand {
+    constructor(input) {
+        this.input = input;
+    }
+}
+exports.VerifyAddressCommand = VerifyAddressCommand;

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

@@ -1,3 +1,17 @@
+/**
+ * The code of a 403 for an option the application's plan does not include
+ * (#55): a map feature such as `satellite` or `terrain`, or rich place data.
+ * The options that can earn it are tagged `@planFeature` in their
+ * documentation.
+ *
+ * The service refuses before calling upstream, so the refusal is not billed,
+ * and its message names each refused feature and the option that asked for
+ * it. It never names a plan: which plan includes which feature can change
+ * without a release of this package — see https://chaosity.cloud/pricing.
+ * Nothing in the token lists the features either, so this 403 is the first a
+ * caller hears of it; there is no check to make beforehand.
+ */
+export declare const FEATURE_NOT_ENTITLED = "FeatureNotEntitledException";
 export interface LocationServiceExceptionOptions {
     message: string;
     code: string;
@@ -36,8 +50,21 @@ export declare class LocationServiceException extends Error {
     get isRetryable(): boolean;
     get isThrottling(): boolean;
     get isValidation(): boolean;
-    /** Credentials or entitlements — the caller must act, retrying will not help. */
+    /**
+     * Any 401 or 403 — the caller must act, and retrying will not help.
+     *
+     * That is several failures with different remedies: bad or expired
+     * credentials, an `Origin` the application does not allow, a route its plan
+     * does not include, an option its plan does not include. Branch on `code`,
+     * or on `isFeatureNotEntitled` for the last, to tell them apart.
+     */
     get isAuth(): boolean;
+    /**
+     * The application's plan does not include an option this request asked for
+     * (`FEATURE_NOT_ENTITLED`). The message names the feature; drop the option,
+     * or move the application to a plan that includes it.
+     */
+    get isFeatureNotEntitled(): boolean;
     get isAborted(): boolean;
     get isTimeout(): boolean;
     toString(): string;

package/dist/cjs/errors/LocationServiceException.js

@@ -1,6 +1,20 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LocationServiceException = void 0;
+exports.LocationServiceException = exports.FEATURE_NOT_ENTITLED = void 0;
+/**
+ * The code of a 403 for an option the application's plan does not include
+ * (#55): a map feature such as `satellite` or `terrain`, or rich place data.
+ * The options that can earn it are tagged `@planFeature` in their
+ * documentation.
+ *
+ * The service refuses before calling upstream, so the refusal is not billed,
+ * and its message names each refused feature and the option that asked for
+ * it. It never names a plan: which plan includes which feature can change
+ * without a release of this package — see https://chaosity.cloud/pricing.
+ * Nothing in the token lists the features either, so this 403 is the first a
+ * caller hears of it; there is no check to make beforehand.
+ */
+exports.FEATURE_NOT_ENTITLED = 'FeatureNotEntitledException';
 /**
  * The single error type this package throws.
  *
@@ -40,10 +54,25 @@ class LocationServiceException extends Error {
     get isValidation() {
         return this.code === 'ValidationException' || this.statusCode === 400;
     }
-    /** Credentials or entitlements — the caller must act, retrying will not help. */
+    /**
+     * Any 401 or 403 — the caller must act, and retrying will not help.
+     *
+     * That is several failures with different remedies: bad or expired
+     * credentials, an `Origin` the application does not allow, a route its plan
+     * does not include, an option its plan does not include. Branch on `code`,
+     * or on `isFeatureNotEntitled` for the last, to tell them apart.
+     */
     get isAuth() {
         return this.statusCode === 401 || this.statusCode === 403;
     }
+    /**
+     * The application's plan does not include an option this request asked for
+     * (`FEATURE_NOT_ENTITLED`). The message names the feature; drop the option,
+     * or move the application to a plan that includes it.
+     */
+    get isFeatureNotEntitled() {
+        return this.code === exports.FEATURE_NOT_ENTITLED;
+    }
     get isAborted() {
         return this.code === 'AbortedException';
     }

package/dist/cjs/index.d.ts

@@ -3,9 +3,11 @@ export type { SendOptions } from './client/GeoPlacesClient.js';
 export { DEFAULT_MAX_ATTEMPTS, DEFAULT_OVERALL_TIMEOUT_MS, 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 { FEATURE_NOT_ENTITLED, LocationServiceException, } from './errors/LocationServiceException.js';
 export type { LocationServiceExceptionOptions } from './errors/LocationServiceException.js';
 export * from '@aws-sdk/client-geo-places';
+export { AutocompleteCommand, GeocodeCommand, GetPlaceCommand, ReverseGeocodeCommand, SearchNearbyCommand, SearchTextCommand, SuggestCommand, VerifyAddressCommand, } from './client/commands.js';
+export type { AutocompleteCommandInput, AutocompleteRequest, GeocodeCommandInput, GeocodeRequest, GetPlaceCommandInput, GetPlaceRequest, NeverForwarded, ReverseGeocodeCommandInput, ReverseGeocodeRequest, SearchNearbyCommandInput, SearchNearbyRequest, SearchTextCommandInput, SearchTextRequest, SuggestCommandInput, SuggestRequest, VerifyAddressCommandInput, VerifyAddressResponse, } from './client/commands.js';
 export * from '@aws/amazon-location-utilities-datatypes';
 export { GeoPlaces } from './adapters/GeoPlaces.js';
 export type { GeoPlacesDetailOptions, GeoPlacesOptions, } from './adapters/GeoPlaces.js';
@@ -17,8 +19,8 @@ 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 { 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 type { Buildings, ColorScheme, ContourDensity, LabelSize, MapFeatureMode, MapStyle, PoiDensity, ScaleBarUnit, SpriteVariant, StaticMapStyle, StylePoiCategory, 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

@@ -14,7 +14,7 @@ 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_OVERALL_TIMEOUT_MS = exports.DEFAULT_MAX_ATTEMPTS = exports.GeoPlacesClient = void 0;
+exports.transformRequest = exports.TRAVEL_MODES = exports.TRAFFIC_MODES = exports.TERRAINS = exports.STYLE_POI_CATEGORIES = exports.STATIC_MAP_STYLES = exports.SPRITE_VARIANTS = exports.SCALE_BAR_UNITS = exports.POI_DENSITIES = 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.VerifyAddressCommand = exports.SuggestCommand = exports.SearchTextCommand = exports.SearchNearbyCommand = exports.ReverseGeocodeCommand = exports.GetPlaceCommand = exports.GeocodeCommand = exports.AutocompleteCommand = exports.LocationServiceException = exports.FEATURE_NOT_ENTITLED = exports.readTokenExpiry = exports.TOKEN_REFRESH_BUFFER_SECONDS = exports.DEFAULT_TIMEOUT_MS = exports.DEFAULT_OVERALL_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; } });
@@ -29,9 +29,23 @@ Object.defineProperty(exports, "TOKEN_REFRESH_BUFFER_SECONDS", { enumerable: tru
 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, "FEATURE_NOT_ENTITLED", { enumerable: true, get: function () { return LocationServiceException_js_1.FEATURE_NOT_ENTITLED; } });
 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);
+// …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).
+var commands_js_1 = require("./client/commands.js");
+Object.defineProperty(exports, "AutocompleteCommand", { enumerable: true, get: function () { return commands_js_1.AutocompleteCommand; } });
+Object.defineProperty(exports, "GeocodeCommand", { enumerable: true, get: function () { return commands_js_1.GeocodeCommand; } });
+Object.defineProperty(exports, "GetPlaceCommand", { enumerable: true, get: function () { return commands_js_1.GetPlaceCommand; } });
+Object.defineProperty(exports, "ReverseGeocodeCommand", { enumerable: true, get: function () { return commands_js_1.ReverseGeocodeCommand; } });
+Object.defineProperty(exports, "SearchNearbyCommand", { enumerable: true, get: function () { return commands_js_1.SearchNearbyCommand; } });
+Object.defineProperty(exports, "SearchTextCommand", { enumerable: true, get: function () { return commands_js_1.SearchTextCommand; } });
+Object.defineProperty(exports, "SuggestCommand", { enumerable: true, get: function () { return commands_js_1.SuggestCommand; } });
+Object.defineProperty(exports, "VerifyAddressCommand", { enumerable: true, get: function () { return commands_js_1.VerifyAddressCommand; } });
 // Re-export AWS Location Utilities (data type conversions)
 __exportStar(require("@aws/amazon-location-utilities-datatypes"), exports);
 // Adapters (Custom - for MapLibre integration)
@@ -62,9 +76,11 @@ Object.defineProperty(exports, "CONTOUR_DENSITIES", { enumerable: true, get: fun
 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, "POI_DENSITIES", { enumerable: true, get: function () { return mapEnums_js_1.POI_DENSITIES; } });
 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, "STYLE_POI_CATEGORIES", { enumerable: true, get: function () { return mapEnums_js_1.STYLE_POI_CATEGORIES; } });
 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; } });

package/dist/cjs/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];