@chaosity/location-client-react 0.1.6 → 0.1.8

package/README.md

@@ -1,6 +1,6 @@
 # @chaosity/location-client-react
 
-React bindings for [@chaosity/location-client](https://www.npmjs.com/package/@chaosity/location-client) - AWS Location Service compatible client.
+React bindings for [@chaosity/location-client](https://www.npmjs.com/package/@chaosity/location-client) with automatic token refresh.
 
 ## Installation
 
@@ -10,34 +10,58 @@ npm install @chaosity/location-client-react @chaosity/location-client
 
 ## Quick Start
 
+### 1. Create a Server Action to fetch config
+
+```typescript
+// app/actions/location.ts
+'use server'
+
+import { getClientConfig } from '@chaosity/location-client/server'
+
+export async function getLocationConfig() {
+  // Auto-reads LOCATION_API_URL, LOCATION_CLIENT_ID, LOCATION_CLIENT_SECRET
+  return await getClientConfig()
+}
+```
+
+### 2. Wrap your app with the provider
+
 ```tsx
-import { LocationClientProvider, useLocationClient } from '@chaosity/location-client-react'
-import { SuggestCommand } from '@chaosity/location-client'
+// app/layout.tsx
+'use client'
+
+import { LocationClientProvider } from '@chaosity/location-client-react'
+import { getLocationConfig } from './actions/location'
 
-// 1. Wrap your app with the provider
-function App() {
+export default function RootLayout({ children }: { children: React.ReactNode }) {
   return (
     <LocationClientProvider getConfig={getLocationConfig}>
-      <MapComponent />
+      {children}
     </LocationClientProvider>
   )
 }
+```
+
+### 3. Use the client in any component
+
+```tsx
+import { useLocationClient } from '@chaosity/location-client-react'
+import { SuggestCommand } from '@chaosity/location-client'
+
+function SearchComponent() {
+  const { client, loading, error } = useLocationClient()
 
-// 2. Use the client in any component
-function MapComponent() {
-  const { client, config, loading, error } = useLocationClient()
-  
   const searchPlaces = async (query: string) => {
     if (!client) return
-    
-    const command = new SuggestCommand({
-      QueryText: query,
-      MaxResults: 5
-    })
-    const response = await client.send(command)
+    const response = await client.send(
+      new SuggestCommand({ QueryText: query, MaxResults: 5 })
+    )
     return response.ResultItems
   }
-  
+
+  if (loading) return <div>Loading...</div>
+  if (error) return <div>Error: {error}</div>
+
   return <div>...</div>
 }
 ```
@@ -46,128 +70,96 @@ function MapComponent() {
 
 ### LocationClientProvider
 
-Provides the location client to all child components.
+Provides the location client and automatic token refresh to all child components.
 
 ```tsx
-<LocationClientProvider getConfig={getLocationConfig}>
+<LocationClientProvider
+  getConfig={getLocationConfig}
+  refreshBuffer={60}
+>
   {children}
 </LocationClientProvider>
 ```
 
 **Props:**
-- `getConfig` (function, required) - Async function that returns `{ apiUrl: string, token: string }`
-- `children` (ReactNode, required) - Child components
+- `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.
 
 ### useLocationClient
 
 Hook to access the location client in any component.
 
 ```tsx
-const { client, config, loading, error } = useLocationClient()
+const { client, getToken, loading, error } = useLocationClient()
 ```
 
 **Returns:**
-- `client` (GeoPlacesClient | null) - The location client instance
-- `config` (ClientConfig | null) - The client configuration (apiUrl, token)
-- `loading` (boolean) - Whether the client is initializing
-- `error` (string | null) - Error message if initialization failed
-
-**Throws:** Error if used outside `LocationClientProvider`
+- `client` (`GeoPlacesClient | null`) — The location client instance. Automatically refreshes the token before each `send()` call if needed.
+- `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.
 
-## Usage with Next.js Server Actions
+**Throws:** Error if used outside `LocationClientProvider`.
 
-```tsx
-// app/actions/location.ts (Server-side)
-'use server'
-
-export async function getLocationConfig() {
-  const response = await fetch('https://api.example.com/auth/token', {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({
-      grant_type: 'client_credentials',
-      client_id: process.env.LOCATION_CLIENT_ID!,
-      client_secret: process.env.LOCATION_CLIENT_SECRET!
-    })
-  })
-  
-  const data = await response.json()
-  return {
-    apiUrl: 'https://api.example.com',
-    token: data.access_token
-  }
-}
+## Token Refresh
 
-// app/layout.tsx (Client-side)
-'use client'
+The provider automatically handles token lifecycle:
 
-import { LocationClientProvider } from '@chaosity/location-client-react'
-import { getLocationConfig } from './actions/location'
+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
 
-export default function RootLayout({ children }) {
-  return (
-    <LocationClientProvider getConfig={getLocationConfig}>
-      {children}
-    </LocationClientProvider>
-  )
-}
-```
+No manual token management needed. The `client` always uses a valid token.
 
 ## Complete Example with MapLibre
 
 ```tsx
 'use client'
 
+import { useEffect, useRef } from 'react'
 import { useLocationClient } from '@chaosity/location-client-react'
-import { GeoPlaces } from '@chaosity/location-client'
+import { GeoPlaces, createTransformRequest } from '@chaosity/location-client'
 import maplibregl from 'maplibre-gl'
 import MaplibreGeocoder from '@maplibre/maplibre-gl-geocoder'
-import { useEffect, useRef } from 'react'
+
+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 { config, client, loading, error } = useLocationClient()
+  const { client, getToken, loading, error } = useLocationClient()
 
   useEffect(() => {
-    if (!mapContainer.current || map.current || loading || !config || !client) return
+    if (!mapContainer.current || map.current || loading || !client) return
+
+    const token = getToken()
+    if (!token) return
 
-    // Initialize map
     const mapInstance = new maplibregl.Map({
       container: mapContainer.current,
-      style: `${config.apiUrl}/maps/Standard/descriptor`,
+      style: `${API_URL}/maps/Standard/descriptor`,
       center: [-123.12, 49.28],
       zoom: 10,
-      transformRequest: (url) => {
-        if (url.startsWith(config.apiUrl)) {
-          return {
-            url,
-            headers: { 'Authorization': `Bearer ${config.token}` }
-          }
-        }
-        return { url }
-      }
+      transformRequest: createTransformRequest(API_URL, getToken),
     })
 
-    // Add navigation controls
     mapInstance.addControl(new maplibregl.NavigationControl(), 'top-right')
 
-    // Add geocoder
-    const geoPlaces = new GeoPlaces(config.apiUrl, config.token, mapInstance)
+    // GeoPlaces adapter takes the client instance (not raw apiUrl/token)
+    const geoPlaces = new GeoPlaces(client, mapInstance)
     const geocoder = new MaplibreGeocoder(geoPlaces, {
       maplibregl,
       showResultsWhileTyping: true,
-      limit: 30
+      limit: 30,
     })
     mapInstance.addControl(geocoder, 'top-left')
 
-    // Handle result selection
-    geocoder.on('result', async (event) => {
-      const { id, result_type } = event.result
-      if (result_type === 'Place') {
-        const details = await geoPlaces.searchByPlaceId(id)
-        console.log('Place details:', details)
-      }
+    // The geocoder resolves places internally via searchByPlaceId.
+    // The 'result' event fires with the resolved place feature.
+    geocoder.on('result', (event: any) => {
+      console.log('Selected place:', event.result)
     })
 
     map.current = mapInstance
@@ -178,15 +170,10 @@ export default function MapComponent() {
         map.current = null
       }
     }
-  }, [config, client, loading])
-
-  if (error) {
-    return <div>Error: {error}</div>
-  }
+  }, [client, getToken, loading])
 
-  if (loading) {
-    return <div>Loading map...</div>
-  }
+  if (error) return <div>Error: {error}</div>
+  if (loading) return <div>Loading map...</div>
 
   return <div ref={mapContainer} style={{ width: '100%', height: '600px' }} />
 }
@@ -203,14 +190,14 @@ import {
   ReverseGeocodeCommand,
   GetPlaceCommand,
   SearchTextCommand,
-  SearchNearbyCommand
+  SearchNearbyCommand,
 } from '@chaosity/location-client'
 
 function MyComponent() {
   const { client } = useLocationClient()
 
-  const searchPlaces = async () => {
-    const response = await client.send(
+  const search = async () => {
+    const response = await client!.send(
       new SuggestCommand({ QueryText: 'Vancouver', MaxResults: 5 })
     )
     return response.ResultItems
@@ -218,6 +205,14 @@ function MyComponent() {
 }
 ```
 
+## Logging
+
+Enable debug logging with the `DEBUG` environment variable:
+
+```bash
+DEBUG=location-client-react:* npm run dev
+```
+
 ## TypeScript Support
 
 Full TypeScript support with types from AWS SDK:
@@ -226,21 +221,11 @@ Full TypeScript support with types from AWS SDK:
 import type { SuggestCommandOutput } from '@aws-sdk/client-geo-places'
 
 const { client } = useLocationClient()
-
-const response: SuggestCommandOutput = await client.send(
+const response: SuggestCommandOutput = await client!.send(
   new SuggestCommand({ QueryText: 'Vancouver' })
 )
 ```
 
-## Security Best Practices
-
-⚠️ **NEVER expose client credentials in browser code!**
-
-- The `getConfig` function should call a server-side API or Server Action
-- Store `client_id` and `client_secret` in server environment variables only
-- Only the JWT token should be sent to the browser
-- Tokens should be short-lived and refreshed as needed
-
 ## License
 
 MIT

package/dist/hooks/useMapLanguage.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Minimal interface describing the MapLibre Map methods used by this hook.
+ * Using a structural type avoids maplibre-gl version conflicts between packages.
+ */
+interface MapLike {
+    isStyleLoaded(): boolean;
+    on(event: string, listener: (...args: unknown[]) => void): void;
+    off(event: string, listener: (...args: unknown[]) => void): void;
+}
+/**
+ * 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;
+export {};

package/dist/hooks/useMapLanguage.js

@@ -0,0 +1,32 @@
+'use client';
+import { useEffect } from 'react';
+import { applyMapLanguage } 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 function useMapLanguage(map, language) {
+    useEffect(() => {
+        if (!map)
+            return;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const applyFn = () => applyMapLanguage(map, language);
+        if (map.isStyleLoaded()) {
+            applyFn();
+        }
+        map.on('style.load', applyFn);
+        return () => {
+            map.off('style.load', applyFn);
+        };
+    }, [map, language]);
+}

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/provider/LocationClientProvider.d.ts

@@ -1,10 +1,8 @@
 import type { ReactNode } from 'react';
 import { GeoPlacesClient, ClientConfig } from '@chaosity/location-client';
 interface LocationClientContextValue {
-    config: ClientConfig | null;
     client: GeoPlacesClient | null;
     getToken: () => string | undefined;
-    ensureValidToken: () => Promise<void>;
     loading: boolean;
     error: string | null;
 }
@@ -13,6 +11,7 @@ export interface LocationClientProviderProps {
     getConfig: () => Promise<ClientConfig & {
         expiresAt?: number;
     }>;
+    /** Seconds before expiry to proactively refresh (default: 60) */
     refreshBuffer?: number;
 }
 export declare function LocationClientProvider({ children, getConfig, refreshBuffer }: LocationClientProviderProps): import("react/jsx-runtime").JSX.Element;

package/dist/provider/LocationClientProvider.js

@@ -3,95 +3,92 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { createContext, useContext, useEffect, useState, useRef, useCallback } from 'react';
 import { GeoPlacesClient } from '@chaosity/location-client';
 import debug from 'debug';
-import { jwtDecode } from 'jwt-decode';
 const log = debug('location-client-react:provider');
 const LocationClientContext = createContext(undefined);
 export function LocationClientProvider({ children, getConfig, refreshBuffer = 60 }) {
-    const [config, setConfig] = useState(null);
     const [client, setClient] = useState(null);
     const [loading, setLoading] = useState(true);
     const [error, setError] = useState(null);
+    // Refs hold live values without triggering re-renders
     const tokenRef = useRef(undefined);
     const expiresAtRef = useRef(null);
     const getConfigRef = useRef(getConfig);
-    const tokenGenerationCount = useRef(0);
-    // Update ref when getConfig changes
+    const refreshPromiseRef = useRef(null);
+    const ensureValidTokenRef = useRef(async () => { });
+    // Keep getConfig ref current without recreating callbacks
     useEffect(() => {
         getConfigRef.current = getConfig;
     }, [getConfig]);
-    // Token getter function (stable reference)
+    // Stable token getter — passed into GeoPlacesClient so it always reads the live ref
     const getToken = useCallback(() => tokenRef.current, []);
-    // Check if token is expired or about to expire
+    // Returns true when the token is expired or within the refresh buffer window.
+    // Treats unknown expiry as expired so we always refresh on first use.
     const isTokenExpired = useCallback(() => {
         if (!expiresAtRef.current)
-            return false;
+            return true;
         return Date.now() >= (expiresAtRef.current - refreshBuffer * 1000);
     }, [refreshBuffer]);
-    // Refresh token if needed
+    // Refreshes the token exactly once even when called concurrently.
+    // All concurrent callers await the same in-flight promise — same pattern as
+    // server-side TokenProvider.tokenPromise deduplication.
     const ensureValidToken = useCallback(async () => {
         if (!isTokenExpired())
             return;
-        const timeUntilExpiry = expiresAtRef.current ? Math.floor((expiresAtRef.current - Date.now()) / 1000) : 0;
-        log('Token expired or expiring soon (expires in %ds), refreshing...', timeUntilExpiry);
-        tokenGenerationCount.current++;
-        try {
+        // Deduplicate: if a refresh is already in flight, wait for it instead of firing another
+        if (refreshPromiseRef.current) {
+            log('Token refresh already in progress, waiting...');
+            return refreshPromiseRef.current;
+        }
+        const timeUntilExpiry = expiresAtRef.current
+            ? Math.floor((expiresAtRef.current - Date.now()) / 1000)
+            : 0;
+        log('Token expired or expiring soon (in %ds), refreshing...', timeUntilExpiry);
+        refreshPromiseRef.current = (async () => {
             const cfg = await getConfigRef.current();
-            setConfig(cfg);
             tokenRef.current = cfg.token;
-            expiresAtRef.current = null;
-            const baseClient = new GeoPlacesClient(cfg);
-            const wrappedClient = new Proxy(baseClient, {
-                get(target, prop) {
-                    if (prop === 'send') {
-                        return async (command) => {
-                            await ensureValidToken();
-                            return target.send(command);
-                        };
-                    }
-                    return target[prop];
-                }
-            });
-            setClient(wrappedClient);
-            const decoded = jwtDecode(cfg.token);
-            expiresAtRef.current = decoded.exp * 1000;
-            const newExpiry = Math.floor((decoded.exp * 1000 - Date.now()) / 1000);
-            log('Token refreshed successfully (new token expires in %ds)', newExpiry);
+            expiresAtRef.current = cfg.expiresAt ?? (Date.now() + 900000);
+            const newExpiry = Math.floor((expiresAtRef.current - Date.now()) / 1000);
+            log('Token refreshed (expires in %ds)', newExpiry);
+        })();
+        try {
+            await refreshPromiseRef.current;
         }
         catch (err) {
             log('Token refresh failed: %s', err instanceof Error ? err.message : 'Unknown error');
             setError(err instanceof Error ? err.message : 'Failed to refresh token');
         }
+        finally {
+            refreshPromiseRef.current = null;
+        }
     }, [isTokenExpired]);
-    // Initial load
+    // Keep ensureValidToken ref current so the send wrapper always uses the latest version
+    useEffect(() => {
+        ensureValidTokenRef.current = ensureValidToken;
+    }, [ensureValidToken]);
+    // Initial load — create the client once.
+    // getToken is passed as a callback so the client always reads the live token ref.
+    // ensureValidToken is called before each send so expiring tokens are refreshed
+    // transparently without recreating the client or causing re-renders.
     useEffect(() => {
         log('Initializing LocationClientProvider');
-        tokenGenerationCount.current++;
-        getConfig()
+        getConfigRef.current()
             .then((cfg) => {
-            setConfig(cfg);
             tokenRef.current = cfg.token;
-            const baseClient = new GeoPlacesClient(cfg);
-            const wrappedClient = new Proxy(baseClient, {
-                get(target, prop) {
-                    if (prop === 'send') {
-                        return async (command) => {
-                            await ensureValidToken();
-                            return target.send(command);
-                        };
-                    }
-                    return target[prop];
-                }
-            });
-            setClient(wrappedClient);
-            try {
-                const decoded = jwtDecode(cfg.token);
-                expiresAtRef.current = decoded.exp * 1000;
-                const expiry = Math.floor((decoded.exp * 1000 - Date.now()) / 1000);
-                log('Client initialized (token expires in %ds)', expiry);
-            }
-            catch (err) {
-                log('Failed to decode token, no expiry info');
-            }
+            expiresAtRef.current = cfg.expiresAt ?? (Date.now() + 900000);
+            // GeoPlacesClient.send() calls getToken() synchronously for the token value,
+            // but token refresh is async. We create a thin send wrapper that:
+            // 1. awaits ensureValidToken (via ref — always latest, race-safe)
+            // 2. delegates to baseClient which reads the now-fresh token from getToken()
+            // The client instance is created once and never recreated on token refresh.
+            const baseClient = new GeoPlacesClient({ apiUrl: cfg.apiUrl, token: cfg.token, getToken });
+            const wrappingClient = Object.create(baseClient);
+            wrappingClient.send = async (command) => {
+                await ensureValidTokenRef.current();
+                return baseClient.send(command);
+            };
+            setClient(wrappingClient);
+            const expiry = Math.floor((expiresAtRef.current - Date.now()) / 1000);
+            log('Client initialized (token expires in %ds)', expiry);
             setLoading(false);
         })
             .catch((err) => {
@@ -99,14 +96,8 @@ export function LocationClientProvider({ children, getConfig, refreshBuffer = 60
             setError(err instanceof Error ? err.message : 'Failed to initialize client');
             setLoading(false);
         });
-    }, [ensureValidToken]);
-    // Check token validity on every state change
-    useEffect(() => {
-        if (!loading && config) {
-            ensureValidToken();
-        }
-    }, [config, loading, ensureValidToken]);
-    return (_jsx(LocationClientContext.Provider, { value: { config, client, getToken, ensureValidToken, loading, error }, children: children }));
+    }, [getToken]);
+    return (_jsx(LocationClientContext.Provider, { value: { client, getToken, loading, error }, children: children }));
 }
 export function useLocationClient() {
     const context = useContext(LocationClientContext);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chaosity/location-client-react",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "React bindings for Chaosity Location Service client",
   "type": "module",
   "main": "dist/index.js",
@@ -8,6 +8,8 @@
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "prepublishOnly": "npm run build"
   },
   "keywords": [
@@ -28,18 +30,31 @@
     "url": "https://github.com/chaosity-io/location-service-client-react/issues"
   },
   "dependencies": {
-    "@chaosity/location-client": "^0.1.5",
-    "debug": "^4.4.3",
-    "jwt-decode": "^4.0.0"
+    "@chaosity/location-client": "file:../location-service-client",
+    "debug": "^4.4.3"
   },
   "peerDependencies": {
+    "maplibre-gl": "^5.0.0",
     "react": "^18.0.0 || ^19.0.0"
   },
+  "peerDependenciesMeta": {
+    "maplibre-gl": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "@testing-library/react": "^16.0.0",
+    "@testing-library/user-event": "^14.0.0",
     "@types/debug": "^4.1.12",
     "@types/react": "^19.0.0",
+    "happy-dom": "^17.0.0",
+    "maplibre-gl": "^5.0.0",
     "react": "^19.0.0",
-    "typescript": "^5.0.0"
+    "typescript": "^5.0.0",
+    "vitest": "^3.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
   },
   "files": [
     "dist",