@chaosity/location-client 0.8.0 → 0.10.0

package/README.md

@@ -38,9 +38,10 @@ npm install maplibre-gl @maplibre/maplibre-gl-geocoder
 
 - **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 +102,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:
@@ -118,8 +187,6 @@ import maplibregl from 'maplibre-gl'
 
 const style = await fetchMapStyle(apiUrl, 'Standard', getToken, {
   colorScheme: 'Dark',
-  terrain: 'Terrain3D',
-  buildings: 'Buildings3D',
   language: 'fr',
 })
 
@@ -128,11 +195,20 @@ 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
+```
+
 ### Switching Map Language
 
 Change map label language instantly on the client side — no API calls needed:
@@ -170,6 +246,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`
@@ -219,6 +363,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 +392,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 +405,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 +425,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,11 +472,7 @@ import { fetchMapStyle } from '@chaosity/location-client'
 
 const style = await fetchMapStyle(apiUrl, 'Standard', getToken, {
   colorScheme: 'Dark',
-  terrain: 'Terrain3D',
-  buildings: 'Buildings3D',
-  contourDensity: 'Medium',
-  traffic: 'All',
-  travelModes: ['Truck', 'Transit'],
+  poiDensity: 'Sparse',
   language: 'fr',
 })
 
@@ -325,6 +482,22 @@ const map = new maplibregl.Map({
 })
 ```
 
+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'],
+})
+```
+
+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 +507,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 +554,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 +569,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 +661,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],
+  }),
 )
 ```
 
@@ -485,17 +690,30 @@ const connector = new LocationServiceConnector({
 })
 ```
 
-## Cache-Friendly Position Rounding
+## Coordinates Are Sent As You Supply Them
+
+Both `GeoPlacesClient` and `LocationServiceConnector` put your command input on
+the wire unchanged. `BiasPosition` and `QueryPosition` arrive at the service at
+the precision you passed.
 
-`BiasPosition` coordinates are automatically rounded before each API request, to
-whatever precision your application is entitled to — a `biasDecimals` claim on
-the access token, defaulting to **3 decimal places** (~110 m) when the token
-carries none. This maximizes cache hits across nearby users without affecting
-result quality — bias is approximate by nature.
+Earlier versions rounded `BiasPosition` to a grid — 3 decimal places by
+default — so that nearby callers could share a cached upstream answer. Requests
+are no longer cached, so the rounding had nothing left to share and only
+lowered the precision the geocoder worked from.
 
-`QueryPosition` (reverse geocode) retains full precision since it represents an exact point the user selected.
+That is not a coarser result, it is a different one. A 3 dp grid moves a
+coordinate by up to ~70 m, depending where in its cell the coordinate falls,
+and the places a search returns change well inside that distance: measured
+against this service, a bias moved ~70 m returned a different set of nearby
+places, not the same set in a different order. If you were relying on the
+rounding to group nearby requests, round before you call.
 
-This is handled transparently in both `GeoPlacesClient` and `LocationServiceConnector` — no action needed in application code.
+One coordinate is normalised: a static map's `center`, `bounding-box` and
+`bounded-positions` are rounded to six decimals — ~10 cm, below one pixel of a
+raster render. That is this library's choice, well inside what the service
+accepts: at most fourteen decimals per number, and at most 36 characters for
+the pair. A value straight from `map.getCenter()` carries fifteen or sixteen
+decimals and fails the first of those. A format rule, not a precision policy.
 
 ## Logging
 
@@ -520,7 +738,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 } : {}),

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) — 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;
 }