@chaosity/location-client-react 0.6.0 → 0.7.0

package/README.md

@@ -61,7 +61,12 @@ function SearchComponent() {
   const searchPlaces = async (query: string) => {
     if (!client) return
     const response: SuggestCommandOutput = await client.send(
-      new SuggestCommand({ QueryText: query, MaxResults: 5 }),
+      new SuggestCommand({
+        QueryText: query,
+        MaxResults: 5,
+        // Suggest takes exactly one of BiasPosition, Filter.BoundingBox or Filter.Circle.
+        BiasPosition: [-123.1207, 49.2827],
+      }),
     )
     return response.ResultItems
   }
@@ -77,7 +82,7 @@ function SearchComponent() {
 
 ### useMapLanguage
 
-React hook that keeps map label language in sync. Automatically reapplies after `map.setStyle()` calls (e.g. when switching color schemes or terrain).
+React hook that keeps map label language in sync. Automatically reapplies after `map.setStyle()` calls (e.g. when switching color schemes).
 
 ```tsx
 import { useMapLanguage } from '@chaosity/location-client-react'
@@ -142,7 +147,7 @@ const { client, getToken, loading, error } = useLocationClient()
 
 **Returns:**
 
-- `client` (`LocationClient | null`) — The location client. Not a bare `GeoPlacesClient`: the provider wraps it so `send()` refreshes the token first when it needs to, and retries once if the API rejects it.
+- `client` (`LocationClient | null`) — The location client. Not a bare `GeoPlacesClient`: the provider wraps it so `send()` and `verifyAddress()` refresh the token first when they need to, and retry once if the API rejects it.
 - `getToken` (`() => string | undefined`) — Returns the current token. Useful for direct API calls (e.g., map style fetch).
 - `loading` (`boolean`) — Whether the client is initializing.
 - `error` (`string | null`) — Error message if initialization or token refresh failed.
@@ -158,7 +163,8 @@ The provider owns the token lifecycle. There is nothing to manage manually.
    `exp`. This is what keeps a map alive: MapLibre requests tiles, glyphs and
    sprites directly, never through `send()`, so a refresh that happened only
    inside `send()` would never fire for them.
-3. `send()` checks too, and refreshes first if the token is inside that window.
+3. `send()` and `verifyAddress()` check too, and refresh first if the token is
+   inside that window.
 4. Returning to a backgrounded tab refreshes immediately — a throttled tab's
    timer can be arbitrarily late.
 5. If the API rejects a token **before** its `exp` — revoked from the portal, or
@@ -166,13 +172,13 @@ The provider owns the token lifecycle. There is nothing to manage manually.
    the request is retried once with the new token. Nothing on this side has any
    other reason to replace that token, so without this the failures continue
    until the timer next comes around: for a token with 14 minutes left, 14
-   minutes of a broken page. Needs `@chaosity/location-client` 0.7.0 or later;
-   on older versions the other five steps still work.
+   minutes of a broken page. The core added this in 0.7.0, so every core this
+   package's peer range admits has it.
 6. Concurrent refreshes are deduplicated — everything waiting shares one call to
    `getConfig`.
 
 A refresh that fails is reported as `error` from `useLocationClient()`, and
-rejects the `send()` that triggered it — with the refresh error rather than a
+rejects the `send()` or `verifyAddress()` that triggered it — with the refresh error rather than a
 401, so the cause reads as the token endpoint being unreachable and not as the
 API refusing you.
 
@@ -200,6 +206,7 @@ export default function MapComponent() {
   const mapContainer = useRef<HTMLDivElement>(null)
   const map = useRef<maplibregl.Map | null>(null)
   const [mapInstance, setMapInstance] = useState<maplibregl.Map | null>(null)
+  const [mapError, setMapError] = useState<string | null>(null)
   const [language, setLanguage] = useState('en')
   const { client, getToken, loading, error } = useLocationClient()
 
@@ -209,11 +216,9 @@ export default function MapComponent() {
   useEffect(() => {
     if (!mapContainer.current || map.current || loading || !client) return
     ;(async () => {
-      // Fetch style with terrain, 3D buildings, and language baked into the descriptor
+      // Fetch the style with the language baked into the descriptor
       const style = await fetchMapStyle(API_URL, 'Standard', getToken, {
         colorScheme: 'Light',
-        terrain: 'Terrain3D',
-        buildings: 'Buildings3D',
         language,
       })
 
@@ -222,18 +227,15 @@ export default function MapComponent() {
         style,
         center: [-123.12, 49.28],
         zoom: 10,
-        maxPitch: 85,
         transformRequest: createTransformRequest(API_URL, getToken),
       })
+      // Held at once, so the catch and the cleanup below can remove it
+      map.current = instance
 
       instance.addControl(
         new maplibregl.NavigationControl({ visualizePitch: true }),
         'top-right',
       )
-      instance.addControl(
-        new maplibregl.TerrainControl({ source: 'amazon' }),
-        'top-right',
-      )
 
       const geoPlaces = new GeoPlaces(client, instance)
       const geocoder = new MaplibreGeocoder(geoPlaces, {
@@ -243,9 +245,15 @@ export default function MapComponent() {
       })
       instance.addControl(geocoder, 'top-left')
 
-      map.current = instance
       setMapInstance(instance)
-    })()
+    })().catch((err: unknown) => {
+      // A refused style request lands here, and its message says why — for
+      // an option outside the application's plan, it names the feature.
+      // Anything that failed after the map was built removes it too.
+      map.current?.remove()
+      map.current = null
+      setMapError(err instanceof Error ? err.message : String(err))
+    })
 
     return () => {
       if (map.current) {
@@ -257,12 +265,36 @@ export default function MapComponent() {
   }, [client, getToken, loading])
 
   if (error) return <div>Error: {error}</div>
+  if (mapError) return <div>Map unavailable: {mapError}</div>
   if (loading) return <div>Loading map...</div>
 
   return <div ref={mapContainer} style={{ width: '100%', height: '600px' }} />
 }
 ```
 
+Some map options are features of the application's plan, and a plan without
+one refuses the style request with 403 `FeatureNotEntitledException`, which the
+`catch` above puts on screen. 3D terrain and buildings need the `terrain` and `buildings` plan features:
+
+```tsx
+const style = await fetchMapStyle(API_URL, 'Standard', getToken, {
+  colorScheme: 'Light',
+  terrain: 'Terrain3D',
+  buildings: 'Buildings3D',
+  language,
+})
+
+// …then `maxPitch: 85` on the map, and a control to toggle the terrain. The
+// descriptor names its own elevation source, so read it rather than typing it:
+instance.addControl(
+  new maplibregl.TerrainControl({ source: style.terrain!.source }),
+  'top-right',
+)
+```
+
+`@chaosity/location-client`'s README lists every plan feature and what asks
+for it.
+
 ### useMapLanguage
 
 Hook that keeps map labels in the specified language. Registers a persistent `style.load` listener so language is automatically reapplied after `map.setStyle()` calls.
@@ -296,13 +328,62 @@ function MyComponent() {
 
   const search = async () => {
     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],
+      }),
     )
     return response.ResultItems
   }
 }
 ```
 
+## Verifying an address
+
+`POST /address/verify` resolves the PlaceId a person chose — a building, or a
+unit from its `SecondaryAddresses` — to the full place record plus `verified`.
+It is the one Places result you may store; the core package's README has the
+whole flow. **Needs `@chaosity/location-client` 0.10.0 or later**, which is this
+package's peer range from the release that adds `verifyAddress`.
+
+```tsx
+import { useLocationClient } from '@chaosity/location-client-react'
+
+function useVerifyOnSubmit() {
+  const { client } = useLocationClient()
+
+  // Call it from the submit handler, once per chosen PlaceId.
+  return async (placeId: string) => {
+    const answer = await client!.verifyAddress(placeId)
+    return answer.verified ? answer : undefined // `answer` is what you may keep
+  }
+}
+```
+
+The same request as a command, through `send`:
+
+```tsx
+import {
+  VerifyAddressCommand,
+  type VerifyAddressResponse,
+} from '@chaosity/location-client'
+
+const answer: VerifyAddressResponse = await client!.send(
+  new VerifyAddressCommand({ PlaceId: placeId }),
+)
+```
+
+Either form goes through the provider's pre-send refresh and its 401 retry,
+exactly as `send` does. A `verified: false` resolves; it is not an error.
+
+**Every verify is billed, whether or not the address verifies.** That is why
+there is no `useVerifyAddress` hook. A hook keyed on a PlaceId would call on
+every pick, including picks nobody submits, so the call belongs in your submit
+handler instead. Keeping one answer per PlaceId is up to you: a verify result
+may be stored, so keep it for as long as your form lives.
+
 ## Logging
 
 Enable debug logging with the `DEBUG` environment variable:
@@ -323,7 +404,11 @@ import {
 
 const { client } = useLocationClient()
 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/cjs/provider/LocationClientProvider.d.ts

@@ -1,15 +1,22 @@
-import type { ClientConfig } from '@chaosity/location-client';
+import type { ClientConfig, VerifyAddressResponse } from '@chaosity/location-client';
 import { type AppConfigClaims } from '@chaosity/location-client';
 import type { ReactNode } from 'react';
 /**
  * Per-request transport options.
  *
- * Declared structurally rather than imported so this package builds against the
- * currently published client; it matches `SendOptions` there exactly.
+ * Declared structurally rather than imported, like `LocationClient` below. A
+ * hand copy does not move when the core does — `overallTimeoutMs` reached the
+ * core in 0.8.0 and not this copy (#26) — so `test/core-surface.test.ts` fails
+ * while the core's `SendOptions` has a key this one lacks.
  */
 export interface SendOptions {
+    /** Caller cancellation. Aborting rejects with code `AbortedException`. */
     signal?: AbortSignal;
+    /** Per ATTEMPT, not for the whole call. */
     timeoutMs?: number;
+    /** The whole call: attempts and the waits between them. Core 0.8.0+. */
+    overallTimeoutMs?: number;
+    /** `false` disables retries entirely. */
     retry?: false | {
         maxAttempts?: number;
     };
@@ -21,6 +28,9 @@ export interface SendOptions {
  * real client to refresh tokens first, and a class with private fields is not
  * structurally assignable — which is why this used to be an `Object.create`
  * prototype hack.
+ *
+ * It must carry every public member of the core client this package builds
+ * with: `test/core-surface.test.ts` fails when the core gains one (#26).
  */
 export interface LocationClient {
     readonly config: {
@@ -28,21 +38,35 @@ export interface LocationClient {
     };
     send<TInput, TOutput>(command: TInput, options?: SendOptions): Promise<TOutput>;
     /**
-     * This application's own configuration, read from the access token —
-     * bias precision, and the countries it is scoped to (api#65).
+     * Verify a PlaceId through `POST /address/verify`: the full place record plus
+     * `verified`, the one Places result an integrator may store (#26). A
+     * `verified: false` resolves; it is not an error. Refreshes a stale token
+     * first, as `send` does.
+     *
+     * Needs @chaosity/location-client 0.10.0 or later, the peer range's floor.
+     * `send(new VerifyAddressCommand({ PlaceId }))` is the same request.
+     *
+     * Billed per call, whether or not the address verifies: call it once per
+     * chosen PlaceId, at submit.
+     */
+    verifyAddress(placeId: string, options?: SendOptions): Promise<VerifyAddressResponse>;
+    /**
+     * This application's own configuration, read from the access token
+     * (api#65). The fields are whatever the installed @chaosity/location-client
+     * reads — its `AppConfigClaims` is the list, and this passes that client's
+     * answer through unchanged. So a field the core adds appears here with no
+     * change to this package, and is absent under a core too old to read it;
+     * the peer range cannot say which.
      *
      * Here so a React app can SHOW its own settings: populate a country
      * selector with the markets it serves, label a settings screen. Being a
      * few minutes stale is cosmetic for that.
      *
-     * It is not an entitlement check, and the `countries` value must not be
-     * used to shape requests. The token is a snapshot; the API reads the scope
-     * fresh from the application row on every call. Injecting a stale scope
-     * turns a request that would have succeeded into a 400. See
+     * It is not an entitlement check, and none of it may be used to shape or
+     * refuse requests. The token is a snapshot; the API reads every setting
+     * fresh from the application on every call. Injecting a stale country
+     * scope turns a request that would have succeeded into a 400. See
      * `AppConfigClaims` in @chaosity/location-client for the measurement.
-     *
-     * Returns `{}` when the token carries no application config, which is the
-     * case until one is set in the portal.
      */
     getAppConfig(): AppConfigClaims;
 }

package/dist/cjs/provider/LocationClientProvider.js

@@ -199,6 +199,12 @@ function LocationClientProvider({ children, getConfig, }) {
                     await ensureValidTokenRef.current();
                     return baseClient.send(command, options);
                 },
+                // Behind the same pre-send refresh as `send`: forwarding it bare
+                // would send a stale token that `send` would have replaced (#26).
+                async verifyAddress(placeId, options) {
+                    await ensureValidTokenRef.current();
+                    return baseClient.verifyAddress(placeId, options);
+                },
                 // Reads whatever token the client currently holds. Deliberately not
                 // awaiting a refresh: this is display data, callers expect it to be
                 // synchronous, and a token that is minutes from expiry carries the

package/dist/provider/LocationClientProvider.d.ts

@@ -1,15 +1,22 @@
-import type { ClientConfig } from '@chaosity/location-client';
+import type { ClientConfig, VerifyAddressResponse } from '@chaosity/location-client';
 import { type AppConfigClaims } from '@chaosity/location-client';
 import type { ReactNode } from 'react';
 /**
  * Per-request transport options.
  *
- * Declared structurally rather than imported so this package builds against the
- * currently published client; it matches `SendOptions` there exactly.
+ * Declared structurally rather than imported, like `LocationClient` below. A
+ * hand copy does not move when the core does — `overallTimeoutMs` reached the
+ * core in 0.8.0 and not this copy (#26) — so `test/core-surface.test.ts` fails
+ * while the core's `SendOptions` has a key this one lacks.
  */
 export interface SendOptions {
+    /** Caller cancellation. Aborting rejects with code `AbortedException`. */
     signal?: AbortSignal;
+    /** Per ATTEMPT, not for the whole call. */
     timeoutMs?: number;
+    /** The whole call: attempts and the waits between them. Core 0.8.0+. */
+    overallTimeoutMs?: number;
+    /** `false` disables retries entirely. */
     retry?: false | {
         maxAttempts?: number;
     };
@@ -21,6 +28,9 @@ export interface SendOptions {
  * real client to refresh tokens first, and a class with private fields is not
  * structurally assignable — which is why this used to be an `Object.create`
  * prototype hack.
+ *
+ * It must carry every public member of the core client this package builds
+ * with: `test/core-surface.test.ts` fails when the core gains one (#26).
  */
 export interface LocationClient {
     readonly config: {
@@ -28,21 +38,35 @@ export interface LocationClient {
     };
     send<TInput, TOutput>(command: TInput, options?: SendOptions): Promise<TOutput>;
     /**
-     * This application's own configuration, read from the access token —
-     * bias precision, and the countries it is scoped to (api#65).
+     * Verify a PlaceId through `POST /address/verify`: the full place record plus
+     * `verified`, the one Places result an integrator may store (#26). A
+     * `verified: false` resolves; it is not an error. Refreshes a stale token
+     * first, as `send` does.
+     *
+     * Needs @chaosity/location-client 0.10.0 or later, the peer range's floor.
+     * `send(new VerifyAddressCommand({ PlaceId }))` is the same request.
+     *
+     * Billed per call, whether or not the address verifies: call it once per
+     * chosen PlaceId, at submit.
+     */
+    verifyAddress(placeId: string, options?: SendOptions): Promise<VerifyAddressResponse>;
+    /**
+     * This application's own configuration, read from the access token
+     * (api#65). The fields are whatever the installed @chaosity/location-client
+     * reads — its `AppConfigClaims` is the list, and this passes that client's
+     * answer through unchanged. So a field the core adds appears here with no
+     * change to this package, and is absent under a core too old to read it;
+     * the peer range cannot say which.
      *
      * Here so a React app can SHOW its own settings: populate a country
      * selector with the markets it serves, label a settings screen. Being a
      * few minutes stale is cosmetic for that.
      *
-     * It is not an entitlement check, and the `countries` value must not be
-     * used to shape requests. The token is a snapshot; the API reads the scope
-     * fresh from the application row on every call. Injecting a stale scope
-     * turns a request that would have succeeded into a 400. See
+     * It is not an entitlement check, and none of it may be used to shape or
+     * refuse requests. The token is a snapshot; the API reads every setting
+     * fresh from the application on every call. Injecting a stale country
+     * scope turns a request that would have succeeded into a 400. See
      * `AppConfigClaims` in @chaosity/location-client for the measurement.
-     *
-     * Returns `{}` when the token carries no application config, which is the
-     * case until one is set in the portal.
      */
     getAppConfig(): AppConfigClaims;
 }

package/dist/provider/LocationClientProvider.js

@@ -192,6 +192,12 @@ export function LocationClientProvider({ children, getConfig, }) {
                     await ensureValidTokenRef.current();
                     return baseClient.send(command, options);
                 },
+                // Behind the same pre-send refresh as `send`: forwarding it bare
+                // would send a stale token that `send` would have replaced (#26).
+                async verifyAddress(placeId, options) {
+                    await ensureValidTokenRef.current();
+                    return baseClient.verifyAddress(placeId, options);
+                },
                 // Reads whatever token the client currently holds. Deliberately not
                 // awaiting a refresh: this is display data, callers expect it to be
                 // synchronous, and a token that is minutes from expiry carries the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chaosity/location-client-react",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "React bindings for Chaosity Location Service client",
   "type": "module",
   "main": "dist/cjs/index.js",
@@ -38,7 +38,7 @@
     "debug": "^4.4.3"
   },
   "peerDependencies": {
-    "@chaosity/location-client": ">=0.3.0",
+    "@chaosity/location-client": ">=0.10.0",
     "maplibre-gl": "^5.0.0",
     "react": "^18.0.0 || ^19.0.0"
   },
@@ -48,7 +48,7 @@
     }
   },
   "devDependencies": {
-    "@chaosity/location-client": "^0.7.0",
+    "@chaosity/location-client": "^0.10.0",
     "@eslint/js": "^10.0.1",
     "@testing-library/react": "^16.0.0",
     "@testing-library/user-event": "^14.0.0",