@chaosity/location-client-react 0.5.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'
@@ -116,7 +121,7 @@ function MapComponent() {
 Provides the location client and automatic token refresh to all child components.
 
 ```tsx
-<LocationClientProvider getConfig={getLocationConfig} refreshBuffer={60}>
+<LocationClientProvider getConfig={getLocationConfig}>
   {children}
 </LocationClientProvider>
 ```
@@ -124,9 +129,14 @@ Provides the location client and automatic token refresh to all child components
 **Props:**
 
 - `getConfig` — Async function that returns `{ apiUrl: string, token: string, expiresAt?: number }`. Called on init and whenever the token needs refreshing.
-- `refreshBuffer` (optional, default: `60`) — Seconds before token expiry to proactively refresh. Prevents mid-request expiration.
 - `children` — Child components.
 
+There is no `refreshBuffer` prop. It was removed in `0.3.0` — a value shorter
+than the server's own re-mint window made the client judge a token stale that
+the server would not yet replace, and the two spun against each other. Both
+sides now apply the same buffer to the token's own `exp`. Passing it does
+nothing.
+
 ### useLocationClient
 
 Hook to access the location client in any component.
@@ -137,7 +147,7 @@ const { client, getToken, loading, error } = useLocationClient()
 
 **Returns:**
 
-- `client` (`GeoPlacesClient | null`) — The location client instance. Automatically refreshes the token before each `send()` call if needed.
+- `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.
@@ -146,14 +156,31 @@ const { client, getToken, loading, error } = useLocationClient()
 
 ## Token Refresh
 
-The provider automatically handles token lifecycle:
-
-1. Fetches an initial token via `getConfig` on mount
-2. Before each `client.send()` call, checks if the token is expired or within the `refreshBuffer` window
-3. If expired, calls `getConfig` again to get a fresh token
-4. Concurrent refresh requests are deduplicated — multiple `send()` calls wait for the same refresh
-
-No manual token management needed. The `client` always uses a valid token.
+The provider owns the token lifecycle. There is nothing to manage manually.
+
+1. `getConfig` is called on mount for the initial token.
+2. A timer refreshes **ahead of expiry**, 60 seconds before the token's own
+   `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()` 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
+   minted against a client secret since rotated — the 401 triggers a refresh and
+   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. 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()` 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.
 
 ## Complete Example with MapLibre
 
@@ -179,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()
 
@@ -188,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,
       })
 
@@ -201,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, {
@@ -222,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) {
@@ -236,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.
@@ -275,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:
@@ -302,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

@@ -166,6 +166,28 @@ function LocationClientProvider({ children, getConfig, }) {
                 apiUrl: cfg.apiUrl,
                 token: cfg.token,
                 getToken,
+                /**
+                 * The 401 escape hatch (#19).
+                 *
+                 * Covers what the timer cannot: a token revoked from the portal, or
+                 * minted against a client secret since rotated, is refused by the API
+                 * while still minutes from its own `exp` — so nothing on this side has
+                 * any reason to replace it, and every request fails until the buffer
+                 * finally comes around. `getToken` cannot help, being synchronous.
+                 *
+                 * The client awaits this after a 401 and retries the request once with
+                 * what it returns; the same token, or nothing, means no retry, so a
+                 * doomed request is never sent — or billed — twice.
+                 *
+                 * It REJECTS when the refresh itself fails, and that is left to
+                 * propagate out of `send` deliberately: the consumer learns the token
+                 * endpoint is down rather than being told the API rejected them. Same
+                 * answer the pre-flight `ensureValidToken` path already gives.
+                 */
+                refreshToken: async () => {
+                    await refreshToken();
+                    return tokenRef.current;
+                },
             });
             // A plain object, not Object.create(baseClient): the prototype hack was
             // opaque, and its `send` dropped the second argument entirely — so once
@@ -177,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
@@ -203,7 +231,7 @@ function LocationClientProvider({ children, getConfig, }) {
             if (timerRef.current)
                 clearTimeout(timerRef.current);
         };
-    }, [getToken]);
+    }, [getToken, refreshToken]);
     return ((0, jsx_runtime_1.jsx)(LocationClientContext.Provider, { value: { client, getToken, loading, error }, children: children }));
 }
 function useLocationClient() {

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

@@ -159,6 +159,28 @@ export function LocationClientProvider({ children, getConfig, }) {
                 apiUrl: cfg.apiUrl,
                 token: cfg.token,
                 getToken,
+                /**
+                 * The 401 escape hatch (#19).
+                 *
+                 * Covers what the timer cannot: a token revoked from the portal, or
+                 * minted against a client secret since rotated, is refused by the API
+                 * while still minutes from its own `exp` — so nothing on this side has
+                 * any reason to replace it, and every request fails until the buffer
+                 * finally comes around. `getToken` cannot help, being synchronous.
+                 *
+                 * The client awaits this after a 401 and retries the request once with
+                 * what it returns; the same token, or nothing, means no retry, so a
+                 * doomed request is never sent — or billed — twice.
+                 *
+                 * It REJECTS when the refresh itself fails, and that is left to
+                 * propagate out of `send` deliberately: the consumer learns the token
+                 * endpoint is down rather than being told the API rejected them. Same
+                 * answer the pre-flight `ensureValidToken` path already gives.
+                 */
+                refreshToken: async () => {
+                    await refreshToken();
+                    return tokenRef.current;
+                },
             });
             // A plain object, not Object.create(baseClient): the prototype hack was
             // opaque, and its `send` dropped the second argument entirely — so once
@@ -170,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
@@ -196,7 +224,7 @@ export function LocationClientProvider({ children, getConfig, }) {
             if (timerRef.current)
                 clearTimeout(timerRef.current);
         };
-    }, [getToken]);
+    }, [getToken, refreshToken]);
     return (_jsx(LocationClientContext.Provider, { value: { client, getToken, loading, error }, children: children }));
 }
 export function useLocationClient() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chaosity/location-client-react",
-  "version": "0.5.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.6.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",