@chaosity/location-client-react 0.5.0 → 0.6.0

package/README.md

@@ -116,7 +116,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 +124,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 +142,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()` 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.
@@ -146,14 +151,30 @@ 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()` checks too, and refreshes 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. Needs `@chaosity/location-client` 0.7.0 or later;
+   on older versions the other five steps still work.
+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.
 
 ## Complete Example with MapLibre
 

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
@@ -203,7 +225,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.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
@@ -196,7 +218,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.6.0",
   "description": "React bindings for Chaosity Location Service client",
   "type": "module",
   "main": "dist/cjs/index.js",
@@ -48,7 +48,7 @@
     }
   },
   "devDependencies": {
-    "@chaosity/location-client": "^0.6.0",
+    "@chaosity/location-client": "^0.7.0",
     "@eslint/js": "^10.0.1",
     "@testing-library/react": "^16.0.0",
     "@testing-library/user-event": "^14.0.0",