@chaosity/location-client-react 0.4.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/hooks/useMapLanguage.d.ts

@@ -0,0 +1,16 @@
+import type { MapLike } from '@chaosity/location-client';
+/**
+ * React hook that keeps map label language in sync with the `language` prop.
+ *
+ * Registers a persistent `style.load` listener so language is automatically
+ * reapplied whenever `map.setStyle()` is called (e.g. style or color scheme change).
+ * Also applies immediately if the style is already loaded.
+ *
+ * @param map - MapLibre Map instance, or null while the map is initializing
+ * @param language - ISO 639-1 language code (e.g. 'en', 'fr', 'de', 'ja')
+ *
+ * @example
+ * const [mapInstance, setMapInstance] = useState<maplibregl.Map | null>(null)
+ * useMapLanguage(mapInstance, language)
+ */
+export declare function useMapLanguage(map: MapLike | null, language: string): void;

package/dist/cjs/hooks/useMapLanguage.js

@@ -0,0 +1,34 @@
+"use strict";
+'use client';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useMapLanguage = useMapLanguage;
+const location_client_1 = require("@chaosity/location-client");
+const react_1 = require("react");
+/**
+ * React hook that keeps map label language in sync with the `language` prop.
+ *
+ * Registers a persistent `style.load` listener so language is automatically
+ * reapplied whenever `map.setStyle()` is called (e.g. style or color scheme change).
+ * Also applies immediately if the style is already loaded.
+ *
+ * @param map - MapLibre Map instance, or null while the map is initializing
+ * @param language - ISO 639-1 language code (e.g. 'en', 'fr', 'de', 'ja')
+ *
+ * @example
+ * const [mapInstance, setMapInstance] = useState<maplibregl.Map | null>(null)
+ * useMapLanguage(mapInstance, language)
+ */
+function useMapLanguage(map, language) {
+    (0, react_1.useEffect)(() => {
+        if (!map)
+            return;
+        const applyFn = () => (0, location_client_1.applyMapLanguage)(map, language);
+        if (map.isStyleLoaded()) {
+            applyFn();
+        }
+        map.on('style.load', applyFn);
+        return () => {
+            map.off('style.load', applyFn);
+        };
+    }, [map, language]);
+}

package/dist/cjs/index.d.ts

@@ -0,0 +1,3 @@
+export { LocationClientProvider, useLocationClient, } from './provider/LocationClientProvider.js';
+export type { LocationClient, LocationClientProviderProps, SendOptions, } from './provider/LocationClientProvider.js';
+export { useMapLanguage } from './hooks/useMapLanguage.js';

package/dist/cjs/index.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useMapLanguage = exports.useLocationClient = exports.LocationClientProvider = void 0;
+var LocationClientProvider_js_1 = require("./provider/LocationClientProvider.js");
+Object.defineProperty(exports, "LocationClientProvider", { enumerable: true, get: function () { return LocationClientProvider_js_1.LocationClientProvider; } });
+Object.defineProperty(exports, "useLocationClient", { enumerable: true, get: function () { return LocationClientProvider_js_1.useLocationClient; } });
+var useMapLanguage_js_1 = require("./hooks/useMapLanguage.js");
+Object.defineProperty(exports, "useMapLanguage", { enumerable: true, get: function () { return useMapLanguage_js_1.useMapLanguage; } });

package/dist/cjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

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

@@ -0,0 +1,63 @@
+import type { ClientConfig } 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.
+ */
+export interface SendOptions {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    retry?: false | {
+        maxAttempts?: number;
+    };
+}
+/**
+ * What the provider hands out.
+ *
+ * An interface rather than `GeoPlacesClient` because the provider wraps the
+ * 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.
+ */
+export interface LocationClient {
+    readonly config: {
+        serviceId: string;
+    };
+    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).
+     *
+     * 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
+     * `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;
+    loading: boolean;
+    error: string | null;
+}
+export interface LocationClientProviderProps {
+    children: ReactNode;
+    getConfig: () => Promise<ClientConfig & {
+        expiresAt?: number;
+    }>;
+}
+export declare function LocationClientProvider({ children, getConfig, }: LocationClientProviderProps): import("react").JSX.Element;
+export declare function useLocationClient(): LocationClientContextValue;
+export {};

package/dist/cjs/provider/LocationClientProvider.js

@@ -0,0 +1,237 @@
+"use strict";
+'use client';
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocationClientProvider = LocationClientProvider;
+exports.useLocationClient = useLocationClient;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const location_client_1 = require("@chaosity/location-client");
+const debug_1 = __importDefault(require("debug"));
+const react_1 = require("react");
+const log = (0, debug_1.default)('location-client-react:provider');
+const LocationClientContext = (0, react_1.createContext)(undefined);
+const DEFAULT_LIFETIME_MS = 900000;
+/**
+ * When this token needs replacing.
+ *
+ * The `exp` claim first — it is the only value that cannot disagree with what
+ * the API will accept, and the server-side TokenProvider reads the same one.
+ * `expiresAt` is whatever `getConfig` chose to report, and the final fallback
+ * is a guess used only when the token cannot be parsed at all.
+ */
+function expiryOf(cfg) {
+    return ((0, location_client_1.readTokenExpiry)(cfg.token) ??
+        cfg.expiresAt ??
+        Date.now() + DEFAULT_LIFETIME_MS);
+}
+function LocationClientProvider({ children, getConfig, }) {
+    const [client, setClient] = (0, react_1.useState)(null);
+    const [loading, setLoading] = (0, react_1.useState)(true);
+    const [error, setError] = (0, react_1.useState)(null);
+    const tokenRef = (0, react_1.useRef)(undefined);
+    const expiresAtRef = (0, react_1.useRef)(null);
+    const getConfigRef = (0, react_1.useRef)(getConfig);
+    const refreshPromiseRef = (0, react_1.useRef)(null);
+    const timerRef = (0, react_1.useRef)(null);
+    const mountedRef = (0, react_1.useRef)(true);
+    (0, react_1.useEffect)(() => {
+        getConfigRef.current = getConfig;
+    }, [getConfig]);
+    const isTokenExpired = (0, react_1.useCallback)(() => {
+        if (!expiresAtRef.current)
+            return true;
+        return (Date.now() >= expiresAtRef.current - location_client_1.TOKEN_REFRESH_BUFFER_SECONDS * 1000);
+    }, []);
+    /**
+     * Refresh once, however many callers ask at the same moment.
+     *
+     * REJECTS on failure. It used to swallow the error into state and resolve,
+     * so `send` carried on with the token it already had — guaranteeing a 401 on
+     * the very next call and reporting it as an API error rather than a refresh
+     * failure.
+     */
+    const refreshToken = (0, react_1.useCallback)(async () => {
+        if (refreshPromiseRef.current)
+            return refreshPromiseRef.current;
+        refreshPromiseRef.current = (async () => {
+            const cfg = await getConfigRef.current();
+            tokenRef.current = cfg.token;
+            expiresAtRef.current = expiryOf(cfg);
+            log('Token refreshed (expires in %ds)', Math.floor((expiresAtRef.current - Date.now()) / 1000));
+            if (mountedRef.current)
+                setError(null);
+        })();
+        try {
+            await refreshPromiseRef.current;
+            scheduleRefreshRef.current();
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : 'Failed to refresh token';
+            log('Token refresh failed: %s', message);
+            if (mountedRef.current)
+                setError(message);
+            throw err;
+        }
+        finally {
+            refreshPromiseRef.current = null;
+        }
+    }, []);
+    /**
+     * Refresh AHEAD of expiry, on a timer.
+     *
+     * This is the whole fix for the map path. MapLibre's `transformRequest` is
+     * synchronous by contract, so `getToken` cannot await anything — the token it
+     * reads has to be valid already. Refresh used to happen only inside the `send`
+     * wrapper, which the map never calls: it requests tiles, glyphs and sprites
+     * directly. So after 15 minutes every map request failed, for as long as the
+     * page stayed open, and no amount of panning recovered it.
+     */
+    const scheduleRefresh = (0, react_1.useCallback)(() => {
+        if (timerRef.current)
+            clearTimeout(timerRef.current);
+        if (!expiresAtRef.current)
+            return;
+        const delay = Math.max(0, expiresAtRef.current - location_client_1.TOKEN_REFRESH_BUFFER_SECONDS * 1000 - Date.now());
+        log('Next refresh in %ds', Math.floor(delay / 1000));
+        timerRef.current = setTimeout(() => {
+            // Errors are already surfaced onto state by refreshToken; swallow here so
+            // a failed background refresh cannot become an unhandled rejection.
+            void refreshToken().catch(() => { });
+        }, delay);
+    }, [refreshToken]);
+    // refreshToken and scheduleRefresh reference each other; a ref breaks the cycle
+    // without recreating either callback on every render.
+    const scheduleRefreshRef = (0, react_1.useRef)(() => { });
+    (0, react_1.useEffect)(() => {
+        scheduleRefreshRef.current = scheduleRefresh;
+    }, [scheduleRefresh]);
+    /**
+     * Synchronous read for the map path.
+     *
+     * If the token is already stale — a timer that never fired because the tab was
+     * backgrounded and throttled — this kicks off a refresh but cannot wait for it.
+     * The current read still returns the stale value; the point is that the NEXT
+     * one will not.
+     */
+    const getToken = (0, react_1.useCallback)(() => {
+        // `tokenRef.current` guards the pre-initialisation window: until the first
+        // config load lands there is no expiry to judge, and firing here would race
+        // the initial fetch and request a second token nobody asked for.
+        if (tokenRef.current && isTokenExpired() && !refreshPromiseRef.current) {
+            log('Stale token read — refreshing in the background');
+            void refreshToken().catch(() => { });
+        }
+        return tokenRef.current;
+    }, [isTokenExpired, refreshToken]);
+    const ensureValidToken = (0, react_1.useCallback)(async () => {
+        if (!isTokenExpired())
+            return;
+        await refreshToken();
+    }, [isTokenExpired, refreshToken]);
+    const ensureValidTokenRef = (0, react_1.useRef)(ensureValidToken);
+    (0, react_1.useEffect)(() => {
+        ensureValidTokenRef.current = ensureValidToken;
+    }, [ensureValidToken]);
+    /**
+     * A backgrounded tab has its timers throttled, so the scheduled refresh can be
+     * arbitrarily late. Refresh on the way back in, before the user touches the map.
+     */
+    (0, react_1.useEffect)(() => {
+        if (typeof document === 'undefined')
+            return;
+        const onVisible = () => {
+            if (document.visibilityState === 'visible' &&
+                tokenRef.current &&
+                isTokenExpired()) {
+                log('Tab visible again with a stale token — refreshing');
+                void refreshToken().catch(() => { });
+            }
+        };
+        document.addEventListener('visibilitychange', onVisible);
+        return () => document.removeEventListener('visibilitychange', onVisible);
+    }, [isTokenExpired, refreshToken]);
+    (0, react_1.useEffect)(() => {
+        mountedRef.current = true;
+        log('Initializing LocationClientProvider');
+        getConfigRef
+            .current()
+            .then((cfg) => {
+            if (!mountedRef.current)
+                return;
+            tokenRef.current = cfg.token;
+            expiresAtRef.current = expiryOf(cfg);
+            const baseClient = new location_client_1.GeoPlacesClient({
+                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
+            // the client gained `signal`/`timeoutMs`, every option passed through
+            // this provider would have been silently discarded.
+            const refreshing = {
+                config: baseClient.config,
+                async send(command, options) {
+                    await ensureValidTokenRef.current();
+                    return baseClient.send(command, 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
+                // same application config as its replacement will.
+                getAppConfig() {
+                    return baseClient.getAppConfig();
+                },
+            };
+            setClient(refreshing);
+            scheduleRefreshRef.current();
+            log('Client initialized (token expires in %ds)', Math.floor((expiresAtRef.current - Date.now()) / 1000));
+            setLoading(false);
+        })
+            .catch((err) => {
+            if (!mountedRef.current)
+                return;
+            const message = err instanceof Error ? err.message : 'Failed to initialize client';
+            log('Initialization failed: %s', message);
+            setError(message);
+            setLoading(false);
+        });
+        return () => {
+            mountedRef.current = false;
+            if (timerRef.current)
+                clearTimeout(timerRef.current);
+        };
+    }, [getToken, refreshToken]);
+    return ((0, jsx_runtime_1.jsx)(LocationClientContext.Provider, { value: { client, getToken, loading, error }, children: children }));
+}
+function useLocationClient() {
+    const context = (0, react_1.useContext)(LocationClientContext);
+    if (context === undefined) {
+        throw new Error('useLocationClient must be used within LocationClientProvider');
+    }
+    return context;
+}

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-export { LocationClientProvider, useLocationClient, } from './provider/LocationClientProvider';
-export type { LocationClient, LocationClientProviderProps, SendOptions, } from './provider/LocationClientProvider';
-export { useMapLanguage } from './hooks/useMapLanguage';
+export { LocationClientProvider, useLocationClient, } from './provider/LocationClientProvider.js';
+export type { LocationClient, LocationClientProviderProps, SendOptions, } from './provider/LocationClientProvider.js';
+export { useMapLanguage } from './hooks/useMapLanguage.js';

package/dist/index.js

@@ -1,2 +1,2 @@
-export { LocationClientProvider, useLocationClient, } from './provider/LocationClientProvider';
-export { useMapLanguage } from './hooks/useMapLanguage';
+export { LocationClientProvider, useLocationClient, } from './provider/LocationClientProvider.js';
+export { useMapLanguage } from './hooks/useMapLanguage.js';

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,20 +1,21 @@
 {
   "name": "@chaosity/location-client-react",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "React bindings for Chaosity Location Service client",
   "type": "module",
-  "main": "dist/index.js",
+  "main": "dist/cjs/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && tsc -p tsconfig.cjs.json && node scripts/finish-cjs.mjs",
     "dev": "tsc --watch",
     "lint": "eslint . && prettier --check .",
     "lint:fix": "eslint --fix . && prettier --write .",
     "format": "prettier --write .",
     "test": "vitest run",
     "test:watch": "vitest",
-    "prepublishOnly": "npm run build",
-    "prepare": "husky"
+    "prepublishOnly": "npm run build && npm run smoke",
+    "prepare": "husky",
+    "smoke": "node scripts/smoke.mjs"
   },
   "keywords": [
     "react",
@@ -47,7 +48,7 @@
     }
   },
   "devDependencies": {
-    "@chaosity/location-client": "^0.4.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",
@@ -71,5 +72,22 @@
   "files": [
     "dist",
     "README.md"
-  ]
+  ],
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    }
+  },
+  "module": "dist/index.js",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  }
 }