@chaosity/location-client 0.9.0 → 0.10.0

package/dist/server/LocationServiceConnector.js

@@ -1,4 +1,5 @@
 import debug from 'debug';
+import { VerifyAddressCommand } from '../client/commands.js';
 import { LocationServiceException } from '../errors/LocationServiceException.js';
 import { resolveEndpoint } from '../transport/endpoints.js';
 import { isTokenRejected, noTokenAvailable } from '../transport/errors.js';
@@ -88,7 +89,13 @@ function explainMissingOrigin(err, sentOrigin) {
  * ```typescript
  * // Credentials and apiUrl from the environment, Origin supplied here
  * const connector = new LocationServiceConnector({ origin: 'https://app.example.com' })
- * const result = await connector.send(new SearchTextCommand({ QueryText: 'Space Needle' }))
+ * const result = await connector.send(
+ *   new SearchTextCommand({
+ *     QueryText: 'Space Needle',
+ *     // SearchText takes exactly one of BiasPosition, Filter.BoundingBox or Filter.Circle.
+ *     BiasPosition: [-122.3493, 47.6205],
+ *   }),
+ * )
  * ```
  */
 export class LocationServiceConnector {
@@ -151,17 +158,19 @@ export class LocationServiceConnector {
     }
     /**
      * This application's own configuration, as carried on the access token
-     * (api#65) — today, the countries it is scoped to.
+     * (api#65): the routes it may call, the domain its requests must come from,
+     * and the countries it is scoped to (#40).
      *
      * Provided so an application can SHOW its own settings: populate a country
      * selector with the markets it actually serves, label a settings screen, and
      * so on. Being a few minutes stale is cosmetic for that.
      *
      * It is not an entitlement check. See AppConfigClaims for why acting on
-     * `countries` client-side makes requests fail that would otherwise succeed.
+     * any of it client-side makes requests fail that would otherwise succeed.
      *
-     * Returns `{}` when the token carries no application config, which is the
-     * case until one is configured in the portal.
+     * Every token the API issues carries `allowedResources` and `allowedDomain`;
+     * `countries` only once a scope is configured in the portal. Returns `{}`
+     * for a token carrying none of them.
      */
     async getAppConfig() {
         return readAppConfigClaims(await this.source().get());
@@ -189,6 +198,17 @@ export class LocationServiceConnector {
             throw explainMissingOrigin(err, this.effectiveOrigin(options));
         }
     }
+    /**
+     * Verify a PlaceId: `send(new VerifyAddressCommand({ PlaceId }))`, typed
+     * (#54). Resolves the full place record plus `verified`, and resolves a
+     * `verified: false` too — see VerifyAddressResponse for what may be stored.
+     *
+     * Billed per call, whether or not the address verifies: call it once per
+     * chosen PlaceId, never per keystroke.
+     */
+    verifyAddress(placeId, options) {
+        return this.send(new VerifyAddressCommand({ PlaceId: placeId }), options);
+    }
     async dispatchWithRetry(source, url, cmd, options) {
         const token = await source.get();
         if (!token)

package/dist/transport/endpoints.js

@@ -1,4 +1,5 @@
 import { AutocompleteCommand, GeocodeCommand, GetPlaceCommand, ReverseGeocodeCommand, SearchNearbyCommand, SearchTextCommand, SuggestCommand, } from '@aws-sdk/client-geo-places';
+import { VerifyAddressCommand } from '../client/commands.js';
 import { LocationServiceException } from '../errors/LocationServiceException.js';
 /**
  * Command class -> API path.
@@ -17,6 +18,8 @@ const ENDPOINTS = new Map([
     [SearchNearbyCommand, '/address/search/nearby'],
     [SearchTextCommand, '/address/search/text'],
     [SuggestCommand, '/address/suggestion'],
+    // This package's own: the route has no AWS command (#54).
+    [VerifyAddressCommand, '/address/verify'],
 ]);
 export function resolveEndpoint(command) {
     for (const [CommandClass, endpoint] of ENDPOINTS) {

package/dist/transport/http.d.ts

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

package/dist/transport/http.js

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

package/dist/types/index.d.ts

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

package/dist/utils/tokenClaims.d.ts

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

package/dist/utils/tokenClaims.js

@@ -1,9 +1,11 @@
 /**
  * Read advisory application config out of the access token (api#65).
  *
- * The API puts an application's own settings — today just `countries` — into
- * the JWT alongside `allowedDomain` and `allowedResources`, so this library can
- * stop hard-coding values it has no other way of knowing.
+ * The API puts an application's own settings into the JWT — `countries`,
+ * `allowedResources` and `allowedDomain` — so this library can stop
+ * hard-coding values it has no other way of knowing. The last two were in the
+ * token all along and were not surfaced until #40, so an application could
+ * only learn it lacked a route from the 403.
  *
  * `biasDecimals` used to be here too. It sized the grid this library rounded
  * `BiasPosition` onto, so that nearby callers shared a server cache entry; the
@@ -21,6 +23,21 @@
  * A JWT is signed, not encrypted, so the payload is plain base64url. Nothing
  * secret is in it; these are the caller's own settings.
  */
+/** 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.
  *
@@ -47,6 +64,14 @@ export function readAppConfigClaims(token) {
             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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chaosity/location-client",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Client library for Chaosity Location Service with AWS Location Service compatibility",
   "type": "module",
   "main": "dist/cjs/index.js",