@chaosity/location-client 0.9.0 → 0.11.0

package/README.md

@@ -34,13 +34,20 @@ npm install maplibre-gl
 npm install maplibre-gl @maplibre/maplibre-gl-geocoder
 ```
 
+The map helpers need `maplibre-gl` 6.4.1 or a later 6.x release. Earlier
+releases carry
+[GHSA-jrc7-96c5-q579](https://github.com/advisories/GHSA-jrc7-96c5-q579), an
+XSS in the attribution control, and none of them has a fix. MapLibre 6 needs
+its worker set up once under a bundler: see [The MapLibre worker](#the-maplibre-worker).
+
 ## Key Features
 
 - **Custom Authentication**: Uses Bearer tokens instead of AWS SigV4
 - **AWS SDK Commands**: Full access to all AWS Location Service commands
+- **Address Verification**: `verifyAddress(placeId)` returns the one Places result you may store — see [Verifying an address](#verifying-an-address)
 - **Data Type Utilities**: Built-in GeoJSON conversion utilities
 - **MapLibre Integration**: Adapter for MapLibre GL Geocoder and `createTransformRequest` helper
-- **Map Style Control**: Fetch and customize map style descriptors with terrain, 3D buildings, traffic, and more
+- **Map Style Control**: Fetch and customize map style descriptors — color scheme, points of interest, label language, and terrain, 3D buildings, traffic and more as [plan features](#plan-features)
 - **Map Language**: Switch map label language client-side with zero API calls
 - **POI Layer Control**: Toggle point-of-interest categories on/off by layer
 - **Server Utilities**: `getClientConfig()` with auto-env detection and token caching
@@ -101,10 +108,78 @@ const client = new GeoPlacesClient({
 })
 
 const response: SuggestCommandOutput = await client.send(
-  new SuggestCommand({ QueryText: 'Vancouver', MaxResults: 5 }),
+  new SuggestCommand({
+    QueryText: 'Vancouver',
+    MaxResults: 5,
+    // Suggest takes exactly one of BiasPosition, Filter.BoundingBox or Filter.Circle.
+    BiasPosition: [-123.1207, 49.2827],
+  }),
 )
 ```
 
+### Verifying an address
+
+`POST /address/verify` resolves one PlaceId to the full place record plus
+`verified`. The PlaceId can come from any suggestion, autocomplete, geocode or
+place result, a unit's included. The answer is **the one Places result you may
+store**; every other result is for display only. The exception is a place in
+Japan, which may not be stored at all.
+
+The flow is suggest, then an optional unit pick, then verify at submit:
+
+```typescript
+import {
+  GetPlaceCommand,
+  SuggestCommand,
+  type GetPlaceCommandOutput,
+  type SuggestCommandOutput,
+} from '@chaosity/location-client'
+
+// 1. While the person types: suggestions, for display.
+const suggestions: SuggestCommandOutput = await client.send(
+  // Suggest takes exactly one of BiasPosition, Filter.BoundingBox or Filter.Circle.
+  new SuggestCommand({
+    QueryText: '100 George St, Sydney',
+    BiasPosition: [151.2093, -33.8688],
+  }),
+)
+const picked = suggestions.ResultItems?.[0]?.Place?.PlaceId
+
+// 2. Optionally, offer the building's units. Each has its own PlaceId.
+const building: GetPlaceCommandOutput = await client.send(
+  new GetPlaceCommand({
+    PlaceId: picked!,
+    AdditionalFeatures: ['SecondaryAddresses'],
+  }),
+)
+const unit = building.SecondaryAddresses?.[0]?.PlaceId
+
+// 3. At submit, once: verify the PlaceId that was chosen.
+const answer = await client.verifyAddress(unit ?? picked!)
+if (answer.verified) {
+  // `answer` is the record you may keep.
+}
+```
+
+- `verified` is `true` for a `PointAddress`, or a `SecondaryAddress` (a unit).
+  It is `false` for anything else: an interpolated address, a street, a
+  locality, a point of interest. A `false` is still a 200, so the call
+  resolves; it does not throw.
+- **Every verify is billed, whether or not the address verifies.** Call it
+  once per chosen PlaceId, at submit. Never call it per keystroke, or on every
+  pick.
+- Only the `PlaceId` is sent. `VerifyAddressCommandInput` has no other field,
+  because the service would drop `Language`, `PoliticalView` and
+  `AdditionalFeatures`. A repeat verify of the same PlaceId may be answered
+  from the service's own store, and is billed all the same.
+- Keep the PlaceId you sent beside the answer. The answer's own `PlaceId` can
+  differ, and for a unit it does. The service does not accept that one back,
+  while the one you sent verifies again.
+- `client.verifyAddress(placeId)` is
+  `client.send(new VerifyAddressCommand({ PlaceId: placeId }))`, typed as
+  `VerifyAddressResponse`. `connector.verifyAddress` does the same on the
+  server.
+
 ### MapLibre Map Integration
 
 Use `fetchMapStyle` to fetch a style descriptor with authentication and optional customization, and `createTransformRequest` to attach Bearer tokens to all subsequent tile/glyph/sprite requests:
@@ -114,12 +189,15 @@ import {
   fetchMapStyle,
   createTransformRequest,
 } from '@chaosity/location-client'
-import maplibregl from 'maplibre-gl'
+import * as maplibregl from 'maplibre-gl'
+import 'maplibre-gl/dist/maplibre-gl.css'
+// Vite. For other bundlers, see "The MapLibre worker" below.
+import workerUrl from 'maplibre-gl/dist/maplibre-gl-worker.mjs?worker&url'
+
+maplibregl.setWorkerUrl(workerUrl)
 
 const style = await fetchMapStyle(apiUrl, 'Standard', getToken, {
   colorScheme: 'Dark',
-  terrain: 'Terrain3D',
-  buildings: 'Buildings3D',
   language: 'fr',
 })
 
@@ -128,11 +206,72 @@ const map = new maplibregl.Map({
   style,
   center: [-123.12, 49.28],
   zoom: 10,
-  maxPitch: 85,
   transformRequest: createTransformRequest(apiUrl, getToken),
 })
 ```
 
+3D terrain and buildings need the `terrain` and `buildings` plan features — see [Plan features](#plan-features):
+
+```typescript
+const style = await fetchMapStyle(apiUrl, 'Standard', getToken, {
+  terrain: 'Terrain3D',
+  buildings: 'Buildings3D',
+})
+// then `maxPitch: 85` on the map, so the camera can tilt to see them
+```
+
+### The MapLibre worker
+
+MapLibre 6 loads and parses its tiles in a Web Worker, and it finds the
+worker's file from its own module URL. A bundler rewrites that URL, so an
+application built with one sets the worker's URL once, before the first map.
+Without it the map mounts, draws no tile, and logs "Worker failed to load".
+
+With Vite, import the worker's URL, as in the example above:
+
+```typescript
+import * as maplibregl from 'maplibre-gl'
+import workerUrl from 'maplibre-gl/dist/maplibre-gl-worker.mjs?worker&url'
+
+maplibregl.setWorkerUrl(workerUrl)
+```
+
+With Next.js, serve the worker and the chunk it imports from `public/`. Copy
+them before every build and dev run:
+
+```js
+// scripts/copy-maplibre-worker.mjs
+import { copyFileSync, mkdirSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import path from 'node:path'
+
+const pkg = createRequire(import.meta.url).resolve('maplibre-gl/package.json')
+const dist = path.join(path.dirname(pkg), 'dist')
+const dest = path.join(process.cwd(), 'public', 'maplibre')
+mkdirSync(dest, { recursive: true })
+for (const file of ['maplibre-gl-worker.mjs', 'maplibre-gl-shared.mjs']) {
+  copyFileSync(path.join(dist, file), path.join(dest, file))
+}
+```
+
+```json
+"scripts": {
+  "predev": "node scripts/copy-maplibre-worker.mjs",
+  "prebuild": "node scripts/copy-maplibre-worker.mjs"
+}
+```
+
+Then, in the client component that builds the map:
+
+```typescript
+import * as maplibregl from 'maplibre-gl'
+
+maplibregl.setWorkerUrl('/maplibre/maplibre-gl-worker.mjs')
+```
+
+Other bundlers, and loading MapLibre from a CDN, are covered in MapLibre's own
+[installation guide](https://maplibre.org/maplibre-gl-js/docs/#installation).
+
 ### Switching Map Language
 
 Change map label language instantly on the client side — no API calls needed:
@@ -170,6 +309,74 @@ setAllPoiVisibility(map, false)
 
 Available categories: `food_drink`, `entertainment`, `sights`, `transit`, `accommodations`, `leisure`, `shopping`, `business`, `facilities`, `areas`, `parks`.
 
+### Plan features
+
+Some options are features of the application's plan. An application whose plan
+does not include one is refused **403 `FeatureNotEntitledException`** before
+anything is fetched upstream, so the refusal is not billed, and the message
+names each refused feature and the option that asked for it:
+
+> This application's plan does not include the map feature terrain (terrain=Terrain3D).
+
+| Feature           | What asks for it                                                                                                                      |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `satellite`       | the `Satellite` and `Hybrid` styles, and a static map with no `style` — Satellite is its default                                      |
+| `terrain`         | `terrain` (`Hillshade`, `Terrain3D`)                                                                                                  |
+| `buildings`       | `buildings`                                                                                                                           |
+| `contours`        | `contourDensity`                                                                                                                      |
+| `traffic`         | `traffic`                                                                                                                             |
+| `travel-modes`    | `travelModes`                                                                                                                         |
+| `political-view`  | `politicalView`, on a style or a static map                                                                                           |
+| `rich place data` | `AdditionalFeatures` `Access`, `Contact`, `Phonemes` or `TimeZone` on a Places command, and the `GeoPlaces` details that ask for them |
+
+Everything else is open to every plan: the Standard and Monochrome styles,
+`colorScheme`, `poiDensity`, `poiCategories`, a label language, and the other
+`AdditionalFeatures`. Which plan includes which feature is on the
+[pricing page](https://chaosity.cloud/pricing), and deliberately not here: it can
+change without a release of this package. In the source, every gated option and
+value carries a `@planFeature` tag naming its feature, so your editor shows it.
+
+The token carries no feature list, so there is nothing to check beforehand — the
+403 is how you find out, and it is typed:
+
+```typescript
+import {
+  LocationServiceException,
+  fetchMapStyle,
+} from '@chaosity/location-client'
+
+try {
+  map.setStyle(await fetchMapStyle(apiUrl, 'Standard', getToken, options))
+} catch (err) {
+  if (err instanceof LocationServiceException && err.isFeatureNotEntitled) {
+    showMessage(err.message) // names the refused feature
+  } else throw err
+}
+```
+
+`isAuth` is true for it too, as for every 401 and 403 — but so it is for bad
+credentials, an `Origin` the application does not allow, and a route outside the
+plan, which all need different fixes. Branch on `isFeatureNotEntitled`, or on
+`code` against the exported `FEATURE_NOT_ENTITLED`.
+
+**What MapLibre fetches for itself is refused outside this package.**
+`fetchMapStyle`, `fetchStaticMap` and the Places commands reject with the typed
+error above. A style URL from `buildMapStyleUrl` handed to `setStyle`, and every
+tile, is fetched by MapLibre, so a refusal there arrives as a map `error` event:
+`error.status` is 403 and `error.body` is a `Blob` holding the same
+`{ message, code }` JSON.
+
+```typescript
+import { FEATURE_NOT_ENTITLED } from '@chaosity/location-client'
+
+map.on('error', async ({ error }) => {
+  const { status, body } = error as { status?: number; body?: Blob }
+  if (status !== 403 || !body) return
+  const { code, message } = JSON.parse(await body.text())
+  if (code === FEATURE_NOT_ENTITLED) showMessage(message)
+})
+```
+
 ### MapLibre Geocoder Integration
 
 Requires the optional peers: `npm install maplibre-gl @maplibre/maplibre-gl-geocoder`
@@ -177,7 +384,8 @@ Requires the optional peers: `npm install maplibre-gl @maplibre/maplibre-gl-geoc
 ```typescript
 import { GeoPlacesClient, GeoPlaces } from '@chaosity/location-client'
 import MaplibreGeocoder from '@maplibre/maplibre-gl-geocoder'
-import maplibregl from 'maplibre-gl'
+import '@maplibre/maplibre-gl-geocoder/dist/maplibre-gl-geocoder.css'
+import * as maplibregl from 'maplibre-gl'
 
 // GeoPlaces adapter takes a GeoPlacesClient instance and the map
 const client = new GeoPlacesClient({ apiUrl, token })
@@ -219,6 +427,22 @@ await client.send(command)
 
 When `getToken` is provided, it is called on every request so token updates are reflected without recreating the client.
 
+`client.getAppConfig()` — and `await connector.getAppConfig()` on the server —
+returns the application's own settings as its access token carries them:
+
+```typescript
+{
+  allowedResources?: string[] // e.g. 'GET /maps/static/{fileName}'
+  allowedDomain?: string // the domain its requests must come from
+  countries?: string[] // ISO 3166-1 alpha-2, once a scope is configured
+}
+```
+
+For display — "static maps are not in your plan", the domain to show beside an
+`Origin not allowed` 403 — never for refusing or shaping a request. The token
+can be up to fifteen minutes old, and the API reads all three fresh from the
+application on every request.
+
 `refreshToken` covers the case `getToken` cannot. `getToken` is synchronous —
 MapLibre's `transformRequest` requires that — so it can only ever return the
 token already in hand, and a token the API stops accepting **before** its `exp`
@@ -232,8 +456,8 @@ worth a second round trip. A 403 is never retried: a new token cannot fix an
 #### Request options
 
 Every call in this package takes the same options object — `client.send`,
-`connector.send`, `fetchMapStyle` and `fetchStaticMap` — and every failure
-arrives as a `LocationServiceException`.
+`connector.send`, `verifyAddress` on either, `fetchMapStyle` and
+`fetchStaticMap` — and every failure arrives as a `LocationServiceException`.
 
 ```typescript
 await client.send(command, {
@@ -245,12 +469,13 @@ await client.send(command, {
 ```
 
 `overallTimeoutMs` is the one worth setting deliberately, and it defaults to
-30 s. `timeoutMs` bounds an attempt, not a call: the API answers a spent quota
-with `Retry-After: 60`, and honouring that literally across two retries blocked
-the caller for about two minutes — past any Lambda budget. Now no attempt gets
-more time than the call has left, and a retry that would have to wait longer
-than the remaining budget is not made at all. You get the API's own error back
-instead, `retryAfterMs` intact, so you can queue the work rather than guess.
+30 s. `timeoutMs` bounds an attempt, not a call: nothing bounds the
+`Retry-After` a 429 carries, and honouring one of 60 s literally across two
+retries would have blocked the caller for about two minutes — past any Lambda
+budget. Now no attempt gets more time than the call has left, and a retry that
+would have to wait longer than the remaining budget is not made at all. You get
+the API's own error back instead, `retryAfterMs` intact, so you can queue the
+work rather than guess.
 
 The map helpers take them as a trailing argument:
 
@@ -264,7 +489,7 @@ const style = await fetchMapStyle(
 )
 const blob = await fetchStaticMap(
   apiUrl,
-  { width: 640, height: 400, center },
+  { width: 640, height: 400, center, zoom: 14, style: 'Standard' },
   getToken,
   { signal },
 )
@@ -311,20 +536,29 @@ import { fetchMapStyle } from '@chaosity/location-client'
 
 const style = await fetchMapStyle(apiUrl, 'Standard', getToken, {
   colorScheme: 'Dark',
+  poiDensity: 'Sparse',
+  language: 'fr',
+})
+```
+
+Hand `style` to `new maplibregl.Map`, with the worker set, as in [MapLibre Map Integration](#maplibre-map-integration).
+
+The overlays need the `terrain`, `buildings`, `contours`, `traffic` and `travel-modes` plan features — see [Plan features](#plan-features):
+
+```typescript
+const style = await fetchMapStyle(apiUrl, 'Standard', getToken, {
   terrain: 'Terrain3D',
   buildings: 'Buildings3D',
   contourDensity: 'Medium',
   traffic: 'All',
   travelModes: ['Truck', 'Transit'],
-  language: 'fr',
-})
-
-const map = new maplibregl.Map({
-  style,
-  transformRequest: createTransformRequest(apiUrl, getToken),
 })
 ```
 
+This is the call that surfaces a refusal as `LocationServiceException`; a URL
+MapLibre fetches for itself reports it as a map `error` event instead (see
+[Plan features](#plan-features)).
+
 #### buildMapStyleUrl
 
 Builds the style descriptor URL without fetching. Useful when you want to pass the URL directly to MapLibre (e.g. without pre-applying language).
@@ -334,23 +568,26 @@ import { buildMapStyleUrl } from '@chaosity/location-client'
 
 const url = buildMapStyleUrl(apiUrl, 'Standard', {
   colorScheme: 'Dark',
-  terrain: 'Hillshade',
 })
 ```
 
 #### MapStyleOptions
 
-```typescript
-interface MapStyleOptions {
-  colorScheme?: 'Light' | 'Dark'
-  politicalView?: string // ISO 3166-1 alpha-3 (e.g. 'IND', 'TUR')
-  terrain?: 'Hillshade' | 'Terrain3D'
-  buildings?: 'Buildings3D'
-  contourDensity?: 'Medium' // Only 'Medium' is supported by the AWS SDK
-  traffic?: 'All'
-  travelModes?: Array<'Truck' | 'Transit'>
-}
-```
+The options, the values each accepts, and which of them are plan features are
+documented on the type — `MapStyleOptions` in `src/maps/mapStyle.ts`, with the
+value lists in `src/maps/mapEnums.ts` — and your editor shows them as you type.
+They are not copied here, because the copy that used to be here drifted from the
+source.
+
+Every accepted value is exported as an array (`POI_DENSITIES`,
+`STYLE_POI_CATEGORIES`, `TRAFFIC_MODES`, …) so a picker can be built from it. A
+list tagged `@planFeature` — `MAP_STYLES`, `TERRAINS`, `TRAFFIC_MODES` and the
+others in [Plan features](#plan-features) — holds values some plans are refused,
+so leave those out of a picker or mark them. Values are case sensitive, and some
+combinations are the API's to refuse — for example `traffic: 'All'` on
+Satellite. There is no `language` here:
+`fetchMapStyle` takes `language` separately and applies it to the descriptor
+itself, because the service's style descriptor has no language parameter.
 
 #### applyMapLanguage
 
@@ -378,10 +615,12 @@ setAllPoiVisibility(map, false)
 
 #### Available Commands
 
-All AWS Location Service commands from `@aws-sdk/client-geo-places`:
+The Amazon Location Places commands, with the SDK's inputs minus the two
+fields below:
 
 ```typescript
 import {
+  AutocompleteCommand,
   SuggestCommand,
   GeocodeCommand,
   ReverseGeocodeCommand,
@@ -391,6 +630,29 @@ import {
 } from '@chaosity/location-client'
 ```
 
+**Two SDK fields are not accepted: `IntendedUse` and `Key`.** The service
+removes both from every request — `IntendedUse` would choose the price bucket,
+and `Key` would bill an Amazon Location key that is not the service's — so the
+commands exported here are typed without them, and passing either is a compile
+error rather than a field that is sent and silently ignored. The exported
+`<Name>CommandInput` and `<Name>Request` types are narrowed the same way. At
+runtime nothing is removed: the request body is your input, unchanged, and a
+field cast past the type is stripped by the service all the same.
+
+**`AdditionalFeatures` `Access`, `Contact`, `Phonemes` and `TimeZone` are rich
+place data**, a plan feature. On a plan without it the request
+is refused 403 `FeatureNotEntitledException` — see
+[Plan features](#plan-features). `SecondaryAddresses`, `Intersections`,
+`CrossReferences` and `Core` are open to every plan.
+
+`VerifyAddressCommand` is this package's own: `POST /address/verify` has no
+SDK command. Its input is `{ PlaceId }` and nothing else, and it answers a
+`VerifyAddressResponse` — see [Verifying an address](#verifying-an-address).
+
+```typescript
+import { VerifyAddressCommand } from '@chaosity/location-client'
+```
+
 #### Data Type Utilities
 
 GeoJSON conversion utilities from `@aws/amazon-location-utilities-datatypes`:
@@ -460,7 +722,11 @@ const connector = new LocationServiceConnector({
 })
 
 const result = await connector.send(
-  new SuggestCommand({ QueryText: 'Vancouver' }),
+  new SuggestCommand({
+    QueryText: 'Vancouver',
+    // Suggest takes exactly one of BiasPosition, Filter.BoundingBox or Filter.Circle.
+    BiasPosition: [-123.1207, 49.2827],
+  }),
 )
 ```
 
@@ -533,7 +799,11 @@ Full TypeScript support with types from AWS SDK:
 import type { SuggestCommandOutput } from '@chaosity/location-client'
 
 const response: SuggestCommandOutput = await client.send(
-  new SuggestCommand({ QueryText: 'Vancouver' }),
+  new SuggestCommand({
+    QueryText: 'Vancouver',
+    // Suggest takes exactly one of BiasPosition, Filter.BoundingBox or Filter.Circle.
+    BiasPosition: [-123.1207, 49.2827],
+  }),
 )
 ```
 

package/dist/adapters/GeoPlaces.d.ts

@@ -25,15 +25,42 @@ import type { GeoPlacesClient } from '../client/GeoPlacesClient.js';
  * Worth knowing before enabling `contact`: for a street address it costs
  * Advanced and returns no contact field at all — only points of interest carry
  * one. On an address-completion flow that is 3x the price for nothing.
+ *
+ * `access`, `contact` and `timeZone` are also RICH PLACE DATA, a feature of the
+ * application's plan (#55). On a plan without it, the lookup is refused 403
+ * `FeatureNotEntitledException` — `isFeatureNotEntitled` on the error — and
+ * nothing is returned or billed. `secondaryAddresses` is open to every plan.
+ * Which plans include it: https://chaosity.cloud/pricing.
  */
 export interface GeoPlacesDetailOptions {
-    /** Entrance/exit points. Moves the request to the Advanced bucket. */
+    /**
+     * Entrance/exit points. Moves the request to the Advanced bucket.
+     *
+     * Refused on a plan without it: 403 `FeatureNotEntitledException` (see
+     * `FEATURE_NOT_ENTITLED`).
+     *
+     * @planFeature rich place data
+     */
     access?: boolean;
     /** Unit and sub-address detail. Stays in the Core bucket — free to enable. */
     secondaryAddresses?: boolean;
-    /** Phone/website, POIs only. Moves the request to the Advanced bucket. */
+    /**
+     * Phone/website, POIs only. Moves the request to the Advanced bucket.
+     *
+     * Refused on a plan without it: 403 `FeatureNotEntitledException` (see
+     * `FEATURE_NOT_ENTITLED`).
+     *
+     * @planFeature rich place data
+     */
     contact?: boolean;
-    /** IANA zone and offset. Moves the request to the Advanced bucket. */
+    /**
+     * IANA zone and offset. Moves the request to the Advanced bucket.
+     *
+     * Refused on a plan without it: 403 `FeatureNotEntitledException` (see
+     * `FEATURE_NOT_ENTITLED`).
+     *
+     * @planFeature rich place data
+     */
     timeZone?: boolean;
 }
 export interface GeoPlacesOptions {

package/dist/adapters/GeoPlaces.js

@@ -1,6 +1,10 @@
-import { GeocodeCommand, GetPlaceAdditionalFeature, GetPlaceCommand, ReverseGeocodeCommand, SuggestCommand, } from '@aws-sdk/client-geo-places';
+import { GetPlaceAdditionalFeature, } from '@aws-sdk/client-geo-places';
 import { geocodeResponseToFeatureCollection, getPlaceResponseToFeatureCollection, reverseGeocodeResponseToFeatureCollection, } from '@aws/amazon-location-utilities-datatypes';
 import debug from 'debug';
+import { 
+// The package's own narrowed commands, not the SDK's: an input typed with
+// the SDK's would admit IntendedUse and Key, which the service strips (#40).
+GeocodeCommand, GetPlaceCommand, ReverseGeocodeCommand, SuggestCommand, } from '../client/commands.js';
 const log = debug('location-client:geocoder');
 /**
  * Give the control the fields it renders, not just the ones GeoJSON needs.

package/dist/cjs/adapters/GeoPlaces.d.ts

@@ -25,15 +25,42 @@ import type { GeoPlacesClient } from '../client/GeoPlacesClient.js';
  * Worth knowing before enabling `contact`: for a street address it costs
  * Advanced and returns no contact field at all — only points of interest carry
  * one. On an address-completion flow that is 3x the price for nothing.
+ *
+ * `access`, `contact` and `timeZone` are also RICH PLACE DATA, a feature of the
+ * application's plan (#55). On a plan without it, the lookup is refused 403
+ * `FeatureNotEntitledException` — `isFeatureNotEntitled` on the error — and
+ * nothing is returned or billed. `secondaryAddresses` is open to every plan.
+ * Which plans include it: https://chaosity.cloud/pricing.
  */
 export interface GeoPlacesDetailOptions {
-    /** Entrance/exit points. Moves the request to the Advanced bucket. */
+    /**
+     * Entrance/exit points. Moves the request to the Advanced bucket.
+     *
+     * Refused on a plan without it: 403 `FeatureNotEntitledException` (see
+     * `FEATURE_NOT_ENTITLED`).
+     *
+     * @planFeature rich place data
+     */
     access?: boolean;
     /** Unit and sub-address detail. Stays in the Core bucket — free to enable. */
     secondaryAddresses?: boolean;
-    /** Phone/website, POIs only. Moves the request to the Advanced bucket. */
+    /**
+     * Phone/website, POIs only. Moves the request to the Advanced bucket.
+     *
+     * Refused on a plan without it: 403 `FeatureNotEntitledException` (see
+     * `FEATURE_NOT_ENTITLED`).
+     *
+     * @planFeature rich place data
+     */
     contact?: boolean;
-    /** IANA zone and offset. Moves the request to the Advanced bucket. */
+    /**
+     * IANA zone and offset. Moves the request to the Advanced bucket.
+     *
+     * Refused on a plan without it: 403 `FeatureNotEntitledException` (see
+     * `FEATURE_NOT_ENTITLED`).
+     *
+     * @planFeature rich place data
+     */
     timeZone?: boolean;
 }
 export interface GeoPlacesOptions {

package/dist/cjs/adapters/GeoPlaces.js

@@ -7,6 +7,7 @@ exports.GeoPlaces = void 0;
 const client_geo_places_1 = require("@aws-sdk/client-geo-places");
 const amazon_location_utilities_datatypes_1 = require("@aws/amazon-location-utilities-datatypes");
 const debug_1 = __importDefault(require("debug"));
+const commands_js_1 = require("../client/commands.js");
 const log = (0, debug_1.default)('location-client:geocoder');
 /**
  * Give the control the fields it renders, not just the ones GeoJSON needs.
@@ -99,7 +100,7 @@ class GeoPlaces {
                     : config.countries.split(','),
             };
         }
-        const response = (await this.client.send(new client_geo_places_1.GeocodeCommand(commandInput)));
+        const response = (await this.client.send(new commands_js_1.GeocodeCommand(commandInput)));
         const converted = (0, amazon_location_utilities_datatypes_1.geocodeResponseToFeatureCollection)(response, {
             flattenProperties: true,
         });
@@ -120,7 +121,7 @@ class GeoPlaces {
             MaxResults: config.limit || 1,
             Language: this.normalizeLanguage(config.language),
         };
-        const response = (await this.client.send(new client_geo_places_1.ReverseGeocodeCommand(commandInput)));
+        const response = (await this.client.send(new commands_js_1.ReverseGeocodeCommand(commandInput)));
         const converted = (0, amazon_location_utilities_datatypes_1.reverseGeocodeResponseToFeatureCollection)(response, {
             flattenProperties: true,
         });
@@ -169,7 +170,7 @@ class GeoPlaces {
                 }
                 : {}),
         };
-        const response = (await this.client.send(new client_geo_places_1.SuggestCommand(commandInput)));
+        const response = (await this.client.send(new commands_js_1.SuggestCommand(commandInput)));
         const suggestions = { suggestions: [] };
         for (const item of response.ResultItems ?? []) {
             const text = item.Title;
@@ -187,7 +188,7 @@ class GeoPlaces {
         // lookup in the Advanced bucket at $1.50/1k; the default now sends none
         // and stays in Core at $0.50. Callers that want the detail ask for it.
         const additionalFeatures = this.detailFeatures();
-        const command = new client_geo_places_1.GetPlaceCommand({
+        const command = new commands_js_1.GetPlaceCommand({
             PlaceId: config.query,
             Language: this.normalizeLanguage(config.language),
             ...(additionalFeatures ? { AdditionalFeatures: additionalFeatures } : {}),