@chaosity/location-client 0.8.0 → 0.10.0

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

@@ -1,29 +1,29 @@
 /**
  * Read advisory application config out of the access token (api#65).
  *
- * The API puts an application's own settings — `biasDecimals`, `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
+ * cache is gone, the API issues no such claim, and rounding a coordinate with
+ * nothing to share it with only lowered the precision the upstream geocoder
+ * received (#51).
  *
  * DELIBERATELY UNVERIFIED, and that is safe. This library has no signing key
  * and does not need one: every claim here is re-read from the application row
  * by the API on each request, and the API's answer is the one that counts. A
  * forged token would fail at the authorizer long before any of this mattered.
- * What is read here only decides how the request is SHAPED — a hint, never a
- * permission.
+ * Nothing read here reaches a request at all now — it is displayed, never
+ * acted on, so a forged value misinforms only the caller who forged it.
  *
  * A JWT is signed, not encrypted, so the payload is plain base64url. Nothing
  * secret is in it; these are the caller's own settings.
  */
 export interface AppConfigClaims {
-    /**
-     * Bias precision this application is entitled to.
-     *
-     * Safe to act on: it only changes how a coordinate is rounded before
-     * sending, and the server re-rounds to its own configured value anyway. A
-     * stale value here costs precision, never correctness.
-     */
-    biasDecimals?: number;
     /**
      * Countries this application may search, ISO 3166-1 alpha-2.
      *
@@ -44,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.

package/dist/cjs/utils/tokenClaims.js

@@ -2,22 +2,45 @@
 /**
  * Read advisory application config out of the access token (api#65).
  *
- * The API puts an application's own settings — `biasDecimals`, `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
+ * cache is gone, the API issues no such claim, and rounding a coordinate with
+ * nothing to share it with only lowered the precision the upstream geocoder
+ * received (#51).
  *
  * DELIBERATELY UNVERIFIED, and that is safe. This library has no signing key
  * and does not need one: every claim here is re-read from the application row
  * by the API on each request, and the API's answer is the one that counts. A
  * forged token would fail at the authorizer long before any of this mattered.
- * What is read here only decides how the request is SHAPED — a hint, never a
- * permission.
+ * Nothing read here reaches a request at all now — it is displayed, never
+ * acted on, so a forged value misinforms only the caller who forged it.
  *
  * A JWT is signed, not encrypted, so the payload is plain base64url. Nothing
  * secret is in it; these are the caller's own settings.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.readAppConfigClaims = readAppConfigClaims;
+/** A list of strings, whether the claim carries it as a list or JSON-encoded. */
+function readStringList(value) {
+    let list = value;
+    if (typeof list === 'string') {
+        try {
+            list = JSON.parse(list);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    if (!Array.isArray(list))
+        return undefined;
+    return list.filter((v) => typeof v === 'string');
+}
 /**
  * Decode a JWT payload without verifying it.
  *
@@ -39,20 +62,19 @@ function readAppConfigClaims(token) {
         const json = decodeURIComponent(Array.from(atob(padded), (c) => `%${c.charCodeAt(0).toString(16).padStart(2, '0')}`).join(''));
         const payload = JSON.parse(json);
         const claims = {};
-        if (typeof payload.biasDecimals === 'number') {
-            claims.biasDecimals = payload.biasDecimals;
-        }
-        else if (typeof payload.biasDecimals === 'string' &&
-            payload.biasDecimals.trim() !== '') {
-            const n = Number(payload.biasDecimals);
-            if (Number.isFinite(n))
-                claims.biasDecimals = n;
-        }
         if (Array.isArray(payload.countries)) {
             const list = payload.countries.filter((c) => typeof c === 'string');
             if (list.length)
                 claims.countries = list;
         }
+        // Kept when empty, unlike countries: no countries means "search the
+        // world", but no resources means an application entitled to nothing.
+        const resources = readStringList(payload.allowedResources);
+        if (resources)
+            claims.allowedResources = resources;
+        if (typeof payload.allowedDomain === 'string' && payload.allowedDomain) {
+            claims.allowedDomain = payload.allowedDomain;
+        }
         return claims;
     }
     catch {

package/dist/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) — 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(): 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/client/GeoPlacesClient.js

@@ -2,8 +2,8 @@ import debug from 'debug';
 import { resolveEndpoint } from '../transport/endpoints.js';
 import { isTokenRejected, noTokenAvailable } from '../transport/errors.js';
 import { requestJson } from '../transport/http.js';
-import { roundPositionFields } from '../utils/roundPosition.js';
 import { readAppConfigClaims } from '../utils/tokenClaims.js';
+import { VerifyAddressCommand } from './commands.js';
 const log = debug('location-client:api');
 /**
  * GeoPlacesClient — AWS Location Service compatible client with custom auth.
@@ -20,17 +20,19 @@ export class GeoPlacesClient {
     }
     /**
      * 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() {
         return readAppConfigClaims(this.currentToken());
@@ -93,11 +95,23 @@ export 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 VerifyAddressCommand({ PlaceId: placeId }), options);
+    }
     dispatch(url, token, cmd, options) {
-        // Resolve the token BEFORE rounding: the precision this application is
-        // entitled to is a claim on it (api#65). Absent claim -> the 3 dp floor.
-        const { biasDecimals } = readAppConfigClaims(token);
-        const input = roundPositionFields(cmd.input, biasDecimals);
+        // 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
+        // shared a server cache entry; with no cache the rounding only lowered the
+        // precision the upstream geocoder had to work with, which moves the
+        // results rather than coarsening them (#51).
         log('Sending %s to %s', cmd.constructor?.name, url);
         return requestJson(url, {
             method: 'POST',
@@ -105,7 +119,7 @@ export class GeoPlacesClient {
                 'Content-Type': 'application/json',
                 Authorization: `Bearer ${token}`,
             },
-            body: JSON.stringify(input),
+            body: JSON.stringify(cmd.input),
         }, options);
     }
 }

package/dist/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/client/commands.js

@@ -0,0 +1,97 @@
+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';
+export class AutocompleteCommand extends SdkAutocompleteCommand {
+    constructor(input) {
+        super(input);
+    }
+}
+/**
+ * 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 class GeocodeCommand extends SdkGeocodeCommand {
+    constructor(input) {
+        super(input);
+    }
+}
+/**
+ * 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 class GetPlaceCommand extends SdkGetPlaceCommand {
+    constructor(input) {
+        super(input);
+    }
+}
+/**
+ * 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 class ReverseGeocodeCommand extends SdkReverseGeocodeCommand {
+    constructor(input) {
+        super(input);
+    }
+}
+/**
+ * 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 class SearchNearbyCommand extends SdkSearchNearbyCommand {
+    constructor(input) {
+        super(input);
+    }
+}
+/**
+ * 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 class SearchTextCommand extends SdkSearchTextCommand {
+    constructor(input) {
+        super(input);
+    }
+}
+/**
+ * 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 class SuggestCommand extends SdkSuggestCommand {
+    constructor(input) {
+        super(input);
+    }
+}
+/**
+ * `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 class VerifyAddressCommand {
+    constructor(input) {
+        this.input = input;
+    }
+}

package/dist/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/errors/LocationServiceException.js

@@ -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 const FEATURE_NOT_ENTITLED = 'FeatureNotEntitledException';
 /**
  * The single error type this package throws.
  *
@@ -37,10 +51,25 @@ export 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 === FEATURE_NOT_ENTITLED;
+    }
     get isAborted() {
         return this.code === 'AbortedException';
     }

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