@chaosity/location-client-react 0.7.0 → 0.8.0

package/README.md

@@ -128,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
@@ -137,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()` 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.
+- `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`.
 
@@ -176,11 +204,46 @@ The provider owns the token lifecycle. There is nothing to manage manually.
    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.
+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
 
@@ -200,24 +263,24 @@ 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 the style with the 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',
         language,
       })
@@ -227,7 +290,7 @@ export default function MapComponent() {
         style,
         center: [-123.12, 49.28],
         zoom: 10,
-        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
@@ -262,7 +325,7 @@ 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>
@@ -277,7 +340,7 @@ 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, {
+const style = await fetchMapStyle(apiUrl, 'Standard', getToken, {
   colorScheme: 'Light',
   terrain: 'Terrain3D',
   buildings: 'Buildings3D',

package/dist/cjs/provider/LocationClientProvider.d.ts

@@ -73,6 +73,14 @@ export interface LocationClient {
 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;
 }
@@ -81,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 {};