@chaosity/location-client-react 0.6.0 → 0.8.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'
@@ -123,7 +128,8 @@ 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.
+- `getConfig` — Async function that returns `{ apiUrl: string, token: string, expiresAt?: number }`. Called on mount, whenever the token needs refreshing, and to retry a call that failed (see [Token Refresh](#token-refresh)).
+- `configKey` — Optional. What `getConfig` answers for, such as an organisation or application id. When it changes, the provider drops the old client, token and `apiUrl`, calls `getConfig` again and hands out a new client, without remounting its children.
 - `children` — Child components.
 
 There is no `refreshBuffer` prop. It was removed in `0.3.0` — a value shorter
@@ -132,20 +138,47 @@ 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.
 
+#### Switching organisation or application
+
+Either of these is correct:
+
+```tsx
+// Keeps the children mounted: only the client is replaced.
+<LocationClientProvider configKey={orgId} getConfig={getLocationConfig}>
+
+// Remounts everything below the provider, and its state with it.
+<LocationClientProvider key={orgId} getConfig={getLocationConfig}>
+```
+
+Without either, the provider goes on using the old configuration until its
+next token refresh, up to 14 minutes later. A new `getConfig` function is not
+a signal on its own, because it is usually a new function on every render.
+
+After a switch, a client or `getToken` kept from before it refuses: `send()`
+and `verifyAddress()` reject, `getToken()` returns `undefined`, and
+`getAppConfig()` answers `{}`. So one configuration's token never reaches
+another's URL. Build anything that holds
+on to them, such as a MapLibre map or a geocoder, from the context's current
+values, and rebuild it when `client`, `getToken` or `apiUrl` changes, as the
+[complete example](#complete-example-with-maplibre) does. The same happens
+without a `configKey` when `getConfig` starts answering with a different
+`apiUrl`.
+
 ### useLocationClient
 
 Hook to access the location client in any component.
 
 ```tsx
-const { client, getToken, loading, error } = useLocationClient()
+const { client, getToken, apiUrl, 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.
-- `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.
+- `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, for requests the client does not make itself, such as a map's style, tiles and glyphs. It is available before the first token arrives and stays the same function afterwards, so a map built early reads the token once it lands. It returns `undefined` once `configKey` changes.
+- `apiUrl` (`string | null`) — The API `client` talks to, from the same `getConfig` answer as the token. Build map URLs from it rather than restating the URL. `null` until a configuration has loaded.
+- `loading` (`boolean`) — Whether the client is initializing. `true` again while a new `configKey` loads.
+- `error` (`string | null`) — Error message if initialization or a token refresh failed. The provider keeps retrying, and `error` returns to `null` on the first success (see [Token Refresh](#token-refresh)).
 
 **Throws:** Error if used outside `LocationClientProvider`.
 
@@ -158,7 +191,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,15 +200,50 @@ 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
-401, so the cause reads as the token endpoint being unreachable and not as the
-API refusing you.
+7. A failed `getConfig` is retried on the provider's own timer, backing off
+   exponentially from 1 to 30 seconds, with jitter. When `getConfig` rejects
+   with an error that has `retryAfterMs` (milliseconds), it waits that long
+   instead. Until then nothing else asks, neither a map reading its token for
+   every tile nor a `send()`. The tab coming back into view, or the browser
+   coming back online, retries at once, unless the wait was a `retryAfterMs`.
+
+   A Server Action, as in the Quick Start, cannot pass `retryAfterMs` on:
+   React sends a thrown error to the browser without its own fields. To honour
+   a token route's `Retry-After`, call the route from the browser and throw it
+   there:
+
+   ```ts
+   async function getConfig() {
+     const res = await fetch('/api/location-token')
+     if (!res.ok) {
+       const retryAfter = Number(res.headers.get('retry-after'))
+       throw Object.assign(new Error(`token route answered ${res.status}`), {
+         retryAfterMs: retryAfter > 0 ? retryAfter * 1000 : undefined,
+       })
+     }
+     return res.json()
+   }
+   ```
+
+8. That includes the first call. A page whose first `getConfig` fails gets its
+   client when a retry succeeds, without a reload.
+9. A token that arrives already stale by the browser's clock, because that
+   clock runs ahead of the server's, is not asked for again at once: the
+   server would hand back the same one. The provider waits, longer each time,
+   and sends with the token it has. A 401 still replaces it straight away.
+
+A refresh that fails is reported as `error` from `useLocationClient()` until a
+retry succeeds. Meanwhile every request goes out with the token in hand for as
+long as that token is before its own expiry: `send()`, `verifyAddress()` and a
+map's tiles alike, because the API still accepts it. Once it has expired,
+`send()` and `verifyAddress()` reject with the refresh error rather than a 401,
+so the cause reads as the token endpoint being unreachable, not as the API
+refusing you. A token the API refuses (a 401) is never sent again: that
+request rejects with the refresh error too.
 
 ## Complete Example with MapLibre
 
@@ -194,26 +263,25 @@ import {
 import maplibregl from 'maplibre-gl'
 import MaplibreGeocoder from '@maplibre/maplibre-gl-geocoder'
 
-const API_URL = process.env.NEXT_PUBLIC_LOCATION_API_URL!
-
 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()
+  const { client, getToken, apiUrl, loading, error } = useLocationClient()
 
   // Keeps map labels in sync with language — reapplies after every setStyle() call
   useMapLanguage(mapInstance, language)
 
   useEffect(() => {
-    if (!mapContainer.current || map.current || loading || !client) return
+    if (!mapContainer.current || map.current || loading || !client || !apiUrl)
+      return
     ;(async () => {
-      // Fetch style with terrain, 3D buildings, and language baked into the descriptor
-      const style = await fetchMapStyle(API_URL, 'Standard', getToken, {
+      // Fetch the style with the language baked into the descriptor. The URL
+      // comes from the context with the token, so the two always belong together.
+      const style = await fetchMapStyle(apiUrl, 'Standard', getToken, {
         colorScheme: 'Light',
-        terrain: 'Terrain3D',
-        buildings: 'Buildings3D',
         language,
       })
 
@@ -222,18 +290,15 @@ export default function MapComponent() {
         style,
         center: [-123.12, 49.28],
         zoom: 10,
-        maxPitch: 85,
-        transformRequest: createTransformRequest(API_URL, getToken),
+        transformRequest: createTransformRequest(apiUrl, 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 +308,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) {
@@ -254,15 +325,39 @@ export default function MapComponent() {
         setMapInstance(null)
       }
     }
-  }, [client, getToken, loading])
+  }, [client, getToken, apiUrl, 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(apiUrl, '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 +391,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 +467,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,27 +38,49 @@ 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;
 }
 interface LocationClientContextValue {
     client: LocationClient | null;
     getToken: () => string | undefined;
+    /**
+     * The API `client` talks to, from the same `getConfig` answer as the token
+     * `getToken` returns (#14). Build a map's style and tile URLs from this
+     * rather than restating the URL, so a map and its token cannot come from two
+     * different configurations. `null` until a configuration has loaded, and
+     * again while a new `configKey` loads.
+     */
+    apiUrl: string | null;
     loading: boolean;
     error: string | null;
 }
@@ -57,7 +89,20 @@ export interface LocationClientProviderProps {
     getConfig: () => Promise<ClientConfig & {
         expiresAt?: number;
     }>;
+    /**
+     * What `getConfig` answers for: an organisation or application id.
+     *
+     * Changing it drops the old configuration's token, client and `apiUrl` in
+     * the same render, and asks `getConfig` again, without remounting the
+     * children (#14). A client or a `getToken` kept from before the change
+     * refuses from then on, rather than pairing one configuration's token with
+     * the other's URL.
+     *
+     * `getConfig`'s own identity is deliberately not such a signal: it is
+     * usually an inline function, new on every render.
+     */
+    configKey?: string | number;
 }
-export declare function LocationClientProvider({ children, getConfig, }: LocationClientProviderProps): import("react").JSX.Element;
+export declare function LocationClientProvider({ children, getConfig, configKey, }: LocationClientProviderProps): import("react").JSX.Element;
 export declare function useLocationClient(): LocationClientContextValue;
 export {};