@chaosity/location-client 0.1.10 → 0.1.13

package/README.md

@@ -28,6 +28,9 @@ npm install @chaosity/location-client
 - **AWS SDK Commands**: Full access to all AWS Location Service commands
 - **Data Type Utilities**: Built-in GeoJSON conversion utilities
 - **MapLibre Integration**: Adapter for MapLibre GL Geocoder and `createTransformRequest` helper
+- **Map Style Control**: Fetch and customize map style descriptors with terrain, 3D buildings, traffic, and more
+- **Map Language**: Switch map label language client-side with zero API calls
+- **POI Layer Control**: Toggle point-of-interest categories on/off by layer
 - **Server Utilities**: `getClientConfig()` with auto-env detection and token caching
 
 ## Quick Start
@@ -78,28 +81,74 @@ const client = new GeoPlacesClient({
 })
 
 const response = await client.send(
-  new SuggestCommand({ QueryText: 'Vancouver', MaxResults: 5 })
+  new SuggestCommand({ QueryText: 'Vancouver', MaxResults: 5 }),
 )
 ```
 
 ### MapLibre Map Integration
 
-Use `createTransformRequest` to automatically attach Bearer tokens to map tile requests:
+Use `fetchMapStyle` to fetch a style descriptor with authentication and optional customization, and `createTransformRequest` to attach Bearer tokens to all subsequent tile/glyph/sprite requests:
 
 ```typescript
-import { createTransformRequest } from '@chaosity/location-client'
+import {
+  fetchMapStyle,
+  createTransformRequest,
+} from '@chaosity/location-client'
 import maplibregl from 'maplibre-gl'
 
+const style = await fetchMapStyle(apiUrl, 'Standard', getToken, {
+  colorScheme: 'Dark',
+  terrain: 'Terrain3D',
+  buildings: 'Buildings3D',
+  language: 'fr',
+})
+
 const map = new maplibregl.Map({
   container: 'map',
-  style: `${apiUrl}/maps/Standard/descriptor`,
+  style,
   center: [-123.12, 49.28],
   zoom: 10,
+  maxPitch: 85,
   transformRequest: createTransformRequest(apiUrl, getToken),
 })
 ```
 
-`createTransformRequest` handles setting the correct `Accept` headers for tiles (protobuf), glyphs, sprites, and style descriptors.
+### Switching Map Language
+
+Change map label language instantly on the client side — no API calls needed:
+
+```typescript
+import { applyMapLanguage } from '@chaosity/location-client'
+
+// Apply after the style is loaded
+map.once('style.load', () => applyMapLanguage(map, 'fr'))
+
+// Or reapply whenever the user changes language
+applyMapLanguage(map, 'ja')
+```
+
+### Controlling POI Layers
+
+Toggle point-of-interest categories on or off:
+
+```typescript
+import {
+  setPoiVisibility,
+  setAllPoiVisibility,
+  POI_CATEGORIES,
+} from '@chaosity/location-client'
+
+// Hide transit POIs
+setPoiVisibility(map, 'transit', false)
+
+// Hide multiple categories at once
+setPoiVisibility(map, ['shopping', 'business'], false)
+
+// Hide all POIs
+setAllPoiVisibility(map, false)
+```
+
+Available categories: `food_drink`, `entertainment`, `sights`, `transit`, `accommodations`, `leisure`, `shopping`, `business`, `facilities`, `areas`, `parks`.
 
 ### MapLibre Geocoder Integration
 
@@ -172,6 +221,80 @@ import { createTransformRequest } from '@chaosity/location-client'
 const transformRequest = createTransformRequest(apiUrl, () => currentToken)
 ```
 
+#### fetchMapStyle
+
+Fetches the map style descriptor with Bearer auth and applies optional language to the descriptor JSON before MapLibre processes it (eliminates the visual flash that occurs when modifying layers post-load).
+
+```typescript
+import { fetchMapStyle } from '@chaosity/location-client'
+
+const style = await fetchMapStyle(apiUrl, 'Standard', getToken, {
+  colorScheme: 'Dark',
+  terrain: 'Terrain3D',
+  buildings: 'Buildings3D',
+  contourDensity: 'Medium',
+  traffic: 'All',
+  travelModes: ['Truck', 'Transit'],
+  language: 'fr',
+})
+
+const map = new maplibregl.Map({
+  style,
+  transformRequest: createTransformRequest(apiUrl, getToken),
+})
+```
+
+#### buildMapStyleUrl
+
+Builds the style descriptor URL without fetching. Useful when you want to pass the URL directly to MapLibre (e.g. without pre-applying language).
+
+```typescript
+import { buildMapStyleUrl } from '@chaosity/location-client'
+
+const url = buildMapStyleUrl(apiUrl, 'Standard', {
+  colorScheme: 'Dark',
+  terrain: 'Hillshade',
+})
+```
+
+#### MapStyleOptions
+
+```typescript
+interface MapStyleOptions {
+  colorScheme?: 'Light' | 'Dark'
+  politicalView?: string // ISO 3166-1 alpha-3 (e.g. 'IND', 'TUR')
+  terrain?: 'Hillshade' | 'Terrain3D'
+  buildings?: 'Buildings3D'
+  contourDensity?: 'Medium' // Only 'Medium' is supported by the AWS SDK
+  traffic?: 'All'
+  travelModes?: Array<'Truck' | 'Transit'>
+}
+```
+
+#### applyMapLanguage
+
+Modifies symbol layer `text-field` expressions on an existing map to display labels in the specified language. No API call — operates entirely on the client.
+
+```typescript
+import { applyMapLanguage } from '@chaosity/location-client'
+
+applyMapLanguage(map, 'fr')
+```
+
+#### POI Layer Control
+
+```typescript
+import {
+  setPoiVisibility,
+  setAllPoiVisibility,
+  POI_CATEGORIES,
+} from '@chaosity/location-client'
+import type { PoiCategory } from '@chaosity/location-client'
+
+setPoiVisibility(map, 'transit', false)
+setAllPoiVisibility(map, false)
+```
+
 #### Available Commands
 
 All AWS Location Service commands from `@aws-sdk/client-geo-places`:
@@ -240,9 +363,19 @@ const connector = new LocationServiceConnector({
   token: config.token,
 })
 
-const result = await connector.send(new SuggestCommand({ QueryText: 'Vancouver' }))
+const result = await connector.send(
+  new SuggestCommand({ QueryText: 'Vancouver' }),
+)
 ```
 
+## Cache-Friendly Position Rounding
+
+`BiasPosition` coordinates are automatically rounded to 2 decimal places (~1.1 km grid) before each API request. This maximizes cache hits across nearby users without affecting result quality — bias is approximate by nature.
+
+`QueryPosition` (reverse geocode) retains full precision since it represents an exact point the user selected.
+
+This is handled transparently in both `GeoPlacesClient` and `LocationServiceConnector` — no action needed in application code.
+
 ## Logging
 
 The library uses the `debug` package for optional verbose logging:
@@ -266,7 +399,7 @@ Full TypeScript support with types from AWS SDK:
 import type { SuggestCommandOutput } from '@aws-sdk/client-geo-places'
 
 const response: SuggestCommandOutput = await client.send(
-  new SuggestCommand({ QueryText: 'Vancouver' })
+  new SuggestCommand({ QueryText: 'Vancouver' }),
 )
 ```
 

package/dist/adapters/GeoPlaces.d.ts

@@ -1,6 +1,6 @@
 import type { MaplibreGeocoderApi, MaplibreGeocoderApiConfig, MaplibreGeocoderFeatureResults, MaplibreGeocoderPlaceResults, MaplibreGeocoderSuggestionResults } from '@maplibre/maplibre-gl-geocoder';
 import type { Map } from 'maplibre-gl';
-import { GeoPlacesClient } from '../client/GeoPlacesClient';
+import type { GeoPlacesClient } from '../client/GeoPlacesClient';
 /**
  * GeoPlaces - MapLibre adapter for AWS Location Service
  *

package/dist/adapters/GeoPlaces.js

@@ -33,11 +33,15 @@ export class GeoPlaces {
         };
         if (config.countries) {
             commandInput.Filter = {
-                IncludeCountries: Array.isArray(config.countries) ? config.countries : config.countries.split(','),
+                IncludeCountries: Array.isArray(config.countries)
+                    ? config.countries
+                    : config.countries.split(','),
             };
         }
-        const response = await this.client.send(new GeocodeCommand(commandInput));
-        const result = geocodeResponseToFeatureCollection(response, { flattenProperties: true });
+        const response = (await this.client.send(new GeocodeCommand(commandInput)));
+        const result = geocodeResponseToFeatureCollection(response, {
+            flattenProperties: true,
+        });
         log('forwardGeocode returned %d results', result.features?.length ?? 0);
         return result;
     }
@@ -51,8 +55,10 @@ export class GeoPlaces {
             MaxResults: config.limit || 1,
             Language: this.normalizeLanguage(config.language),
         };
-        const response = await this.client.send(new ReverseGeocodeCommand(commandInput));
-        const result = reverseGeocodeResponseToFeatureCollection(response, { flattenProperties: true });
+        const response = (await this.client.send(new ReverseGeocodeCommand(commandInput)));
+        const result = reverseGeocodeResponseToFeatureCollection(response, {
+            flattenProperties: true,
+        });
         log('reverseGeocode returned %d results', result.features?.length ?? 0);
         return result;
     }
@@ -68,14 +74,22 @@ export class GeoPlaces {
             MaxResults: config.limit || 5,
             Language: this.normalizeLanguage(config.language),
             AdditionalFeatures: [SuggestAdditionalFeature.CORE],
-            ...(config.countries || config.bbox ? {
-                Filter: {
-                    ...(config.countries ? { IncludeCountries: Array.isArray(config.countries) ? config.countries : config.countries.split(',') } : {}),
-                    ...(config.bbox ? { BoundingBox: config.bbox } : {}),
-                },
-            } : {}),
+            ...(config.countries || config.bbox
+                ? {
+                    Filter: {
+                        ...(config.countries
+                            ? {
+                                IncludeCountries: Array.isArray(config.countries)
+                                    ? config.countries
+                                    : config.countries.split(','),
+                            }
+                            : {}),
+                        ...(config.bbox ? { BoundingBox: config.bbox } : {}),
+                    },
+                }
+                : {}),
         };
-        const response = await this.client.send(new SuggestCommand(commandInput));
+        const response = (await this.client.send(new SuggestCommand(commandInput)));
         const suggestions = { suggestions: [] };
         for (const item of response.ResultItems ?? []) {
             const text = item.Title;
@@ -99,9 +113,11 @@ export class GeoPlaces {
                 GetPlaceAdditionalFeature.TIME_ZONE,
             ],
         });
-        const response = await this.client.send(command);
-        const result = getPlaceResponseToFeatureCollection(response, { flattenProperties: true });
-        const carmenGeojsonFeatures = result.features.map(feature => ({
+        const response = (await this.client.send(command));
+        const result = getPlaceResponseToFeatureCollection(response, {
+            flattenProperties: true,
+        });
+        const carmenGeojsonFeatures = result.features.map((feature) => ({
             ...feature,
             text: response.Title || '',
             place_name: response.Address?.Label || '',

package/dist/auth/TokenProvider.js

@@ -41,12 +41,14 @@ export class TokenProvider {
     }
     async getToken(forceRefresh = false) {
         if (!forceRefresh && this.cachedToken && !this.isExpired()) {
-            const expiresIn = this.cachedExpiresAt ? Math.floor((this.cachedExpiresAt - Date.now()) / 1000) : 'unknown';
+            const expiresIn = this.cachedExpiresAt
+                ? Math.floor((this.cachedExpiresAt - Date.now()) / 1000)
+                : 'unknown';
             log('Using cached token (expires in %ds)', expiresIn);
             return {
                 success: true,
                 token: this.cachedToken,
-                expiresAt: this.cachedExpiresAt
+                expiresAt: this.cachedExpiresAt,
             };
         }
         // If token fetch is already in progress, wait for it
@@ -55,7 +57,11 @@ export class TokenProvider {
             return this.tokenPromise;
         }
         // Start new token fetch
-        const reason = forceRefresh ? 'forced refresh' : (this.cachedToken ? 'token expired' : 'no cached token');
+        const reason = forceRefresh
+            ? 'forced refresh'
+            : this.cachedToken
+                ? 'token expired'
+                : 'no cached token';
         log('Refreshing token (%s) from %s', reason, this.config.apiUrl);
         this.tokenPromise = this.fetchToken();
         try {
@@ -74,10 +80,12 @@ export class TokenProvider {
             const response = await fetch(`${apiUrl}/auth/token`, {
                 method: 'POST',
                 headers: {
-                    'Authorization': `Basic ${credentials}`,
+                    Authorization: `Basic ${credentials}`,
                     'Content-Type': 'application/x-www-form-urlencoded',
                 },
-                body: new URLSearchParams({ grant_type: 'client_credentials' }).toString(),
+                body: new URLSearchParams({
+                    grant_type: 'client_credentials',
+                }).toString(),
             });
             if (!response.ok) {
                 const errorText = await response.text();
@@ -89,13 +97,16 @@ export class TokenProvider {
                     else if (errorData.error)
                         errorMessage = errorData.error;
                 }
-                catch { /* use statusText */ }
+                catch {
+                    /* use statusText */
+                }
                 throw new Error(errorMessage);
             }
             const data = await response.json();
             this.cachedToken = data.access_token;
             // Prefer absolute expires_at (ms) from response, fall back to expires_in (seconds)
-            this.cachedExpiresAt = data.expires_at ?? (Date.now() + ((data.expires_in ?? 900) * 1000));
+            this.cachedExpiresAt =
+                data.expires_at ?? Date.now() + (data.expires_in ?? 900) * 1000;
             const expiresInSec = Math.floor((this.cachedExpiresAt - Date.now()) / 1000);
             log('Token acquired successfully (expires in %ds)', expiresInSec);
             return {
@@ -115,7 +126,7 @@ export class TokenProvider {
     isExpired(bufferSeconds = 60) {
         if (!this.cachedExpiresAt)
             return true;
-        return Date.now() >= (this.cachedExpiresAt - bufferSeconds * 1000);
+        return Date.now() >= this.cachedExpiresAt - bufferSeconds * 1000;
     }
     clearCache() {
         this.cachedToken = undefined;

package/dist/client/GeoPlacesClient.d.ts

@@ -1,4 +1,4 @@
-import { ClientConfig } from '../types';
+import type { ClientConfig, GeoPlacesCommand } from '../types';
 /**
  * GeoPlacesClient - AWS Location Service compatible client with custom auth
  *
@@ -13,6 +13,6 @@ export declare class GeoPlacesClient {
         serviceId: string;
     };
     constructor(config: ClientConfig);
-    send<TInput, TOutput>(command: TInput): Promise<TOutput>;
+    send<TOutput>(command: GeoPlacesCommand): Promise<TOutput>;
     private getEndpoint;
 }

package/dist/client/GeoPlacesClient.js

@@ -1,5 +1,7 @@
-import debug from 'debug';
 import { AutocompleteCommand, GeocodeCommand, GetPlaceCommand, ReverseGeocodeCommand, SearchNearbyCommand, SearchTextCommand, SuggestCommand, } from '@aws-sdk/client-geo-places';
+import debug from 'debug';
+import { LocationServiceException } from '../errors/LocationServiceException';
+import { roundPositionFields } from '../utils/roundPosition';
 const log = debug('location-client:api');
 const logError = debug('location-client:api:error');
 // Minification-safe endpoint map — uses constructor identity, not class name strings
@@ -29,7 +31,7 @@ export class GeoPlacesClient {
         const endpoint = this.getEndpoint(command);
         const url = `${this.clientConfig.apiUrl}${endpoint}`;
         const commandName = command.constructor.name;
-        const input = command.input;
+        const input = roundPositionFields(command.input);
         // Prefer getToken callback (live ref) over static token string
         const token = this.clientConfig.getToken?.() ?? this.clientConfig.token;
         log('Sending %s to %s', commandName, endpoint);
@@ -38,7 +40,7 @@ export class GeoPlacesClient {
             method: 'POST',
             headers: {
                 'Content-Type': 'application/json',
-                'Authorization': `Bearer ${token}`,
+                Authorization: `Bearer ${token}`,
             },
             body: JSON.stringify(input),
         });
@@ -47,16 +49,27 @@ export class GeoPlacesClient {
             const errorText = await response.text();
             logError('Request failed: %s %s (%dms)', response.status, response.statusText, duration);
             let errorMessage = `API request failed: ${response.statusText}`;
+            let errorCode = 'ServiceException';
+            let requestId;
             try {
                 const errorData = JSON.parse(errorText);
                 if (errorData.message)
                     errorMessage = errorData.message;
+                if (errorData.code)
+                    errorCode = errorData.code;
+                if (errorData.requestId)
+                    requestId = errorData.requestId;
             }
             catch {
                 if (errorText)
                     errorMessage = errorText;
             }
-            throw new Error(errorMessage);
+            throw new LocationServiceException({
+                message: errorMessage,
+                code: errorCode,
+                statusCode: response.status,
+                requestId,
+            });
         }
         const result = await response.json();
         log('Request successful: %s (%dms)', response.status, duration);

package/dist/errors/LocationServiceException.d.ts

@@ -0,0 +1,16 @@
+export interface LocationServiceExceptionOptions {
+    message: string;
+    code: string;
+    statusCode: number;
+    requestId?: string;
+}
+export declare class LocationServiceException extends Error {
+    readonly code: string;
+    readonly statusCode: number;
+    readonly requestId?: string;
+    constructor(options: LocationServiceExceptionOptions);
+    get isRetryable(): boolean;
+    get isThrottling(): boolean;
+    get isValidation(): boolean;
+    toString(): string;
+}

package/dist/errors/LocationServiceException.js

@@ -0,0 +1,24 @@
+export class LocationServiceException extends Error {
+    constructor(options) {
+        super(options.message);
+        this.name = 'LocationServiceException';
+        this.code = options.code;
+        this.statusCode = options.statusCode;
+        this.requestId = options.requestId;
+    }
+    get isRetryable() {
+        return this.statusCode === 429 || this.statusCode >= 500;
+    }
+    get isThrottling() {
+        return this.code === 'ThrottlingException' || this.statusCode === 429;
+    }
+    get isValidation() {
+        return this.code === 'ValidationException' || this.statusCode === 400;
+    }
+    toString() {
+        const parts = [`LocationServiceException: [${this.code}] ${this.message}`];
+        if (this.requestId)
+            parts.push(`(requestId: ${this.requestId})`);
+        return parts.join(' ');
+    }
+}

package/dist/index.d.ts

@@ -1,12 +1,14 @@
 export { GeoPlacesClient } from './client/GeoPlacesClient';
+export { LocationServiceException } from './errors/LocationServiceException';
+export type { LocationServiceExceptionOptions } from './errors/LocationServiceException';
 export * from '@aws-sdk/client-geo-places';
 export * from '@aws/amazon-location-utilities-datatypes';
 export { GeoPlaces } from './adapters/GeoPlaces';
 export { createTransformRequest } from './maps/createTransformRequest';
-export { transformRequest } from './maps/Utils';
-export { buildMapStyleUrl, fetchMapStyle } from './maps/mapStyle';
-export type { MapStyleOptions } from './maps/mapStyle';
 export { applyMapLanguage } from './maps/mapLanguage';
-export { setPoiVisibility, setAllPoiVisibility, POI_CATEGORIES } from './maps/mapPoi';
+export { POI_CATEGORIES, setAllPoiVisibility, setPoiVisibility, } from './maps/mapPoi';
 export type { PoiCategory } from './maps/mapPoi';
-export type { ClientConfig } from './types';
+export { buildMapStyleUrl, fetchMapStyle } from './maps/mapStyle';
+export type { MapStyleOptions } from './maps/mapStyle';
+export { transformRequest } from './maps/Utils';
+export type { ClientConfig, GeoPlacesCommand, MapLike } from './types';

package/dist/index.js

@@ -1,5 +1,7 @@
 // Client (Custom - uses our auth instead of AWS SigV4)
 export { GeoPlacesClient } from './client/GeoPlacesClient';
+// Errors
+export { LocationServiceException } from './errors/LocationServiceException';
 // Re-export AWS SDK commands and types
 export * from '@aws-sdk/client-geo-places';
 // Re-export AWS Location Utilities (data type conversions)
@@ -8,8 +10,8 @@ export * from '@aws/amazon-location-utilities-datatypes';
 export { GeoPlaces } from './adapters/GeoPlaces';
 // Maps utilities
 export { createTransformRequest } from './maps/createTransformRequest';
-export { transformRequest } from './maps/Utils';
-export { buildMapStyleUrl, fetchMapStyle } from './maps/mapStyle';
 export { applyMapLanguage } from './maps/mapLanguage';
-export { setPoiVisibility, setAllPoiVisibility, POI_CATEGORIES } from './maps/mapPoi';
+export { POI_CATEGORIES, setAllPoiVisibility, setPoiVisibility, } from './maps/mapPoi';
+export { buildMapStyleUrl, fetchMapStyle } from './maps/mapStyle';
+export { transformRequest } from './maps/Utils';
 // Server-only utilities are available via '@chaosity/location-client/server'

package/dist/maps/Utils.d.ts

@@ -1,2 +1,2 @@
-import { ClientConfig } from "../types";
-export declare function transformRequest(url: string, config: ClientConfig): import("maplibre-gl").RequestParameters | undefined;
+import type { ClientConfig } from '../types';
+export declare function transformRequest(url: string, config: ClientConfig): import("maplibre-gl").RequestParameters | Promise<import("maplibre-gl").RequestParameters> | undefined;

package/dist/maps/Utils.js

@@ -1,4 +1,4 @@
-import { createTransformRequest } from "./createTransformRequest";
+import { createTransformRequest } from './createTransformRequest';
 export function transformRequest(url, config) {
     const token = config.getToken?.() ?? config.token;
     return createTransformRequest(config.apiUrl, () => token)(url);

package/dist/maps/createTransformRequest.js

@@ -15,7 +15,7 @@ export function createTransformRequest(apiUrl, getToken) {
                 return { url };
             }
             const headers = {
-                'Authorization': `Bearer ${token}`,
+                Authorization: `Bearer ${token}`,
             };
             // Set appropriate Accept headers based on resource type
             if (url.includes('/tiles/')) {

package/dist/maps/mapLanguage.d.ts

@@ -1,4 +1,4 @@
-import type { Map } from 'maplibre-gl';
+import type { MapLike } from '../types';
 /**
  * Apply a preferred display language to all symbol layers on a MapLibre map.
  *
@@ -10,10 +10,10 @@ import type { Map } from 'maplibre-gl';
  * Based on the approach documented at:
  * https://docs.aws.amazon.com/location/latest/developerguide/how-to-set-preferred-language-map.html
  *
- * @param map - MapLibre Map instance
+ * @param map - MapLibre Map instance (or any object matching the MapLike interface)
  * @param language - ISO 639-1 language code (e.g. 'en', 'fr', 'de', 'ja', 'zh', 'ar')
  *
  * @example
  * map.once('style.load', () => applyMapLanguage(map, 'fr'))
  */
-export declare function applyMapLanguage(map: Map, language: string): void;
+export declare function applyMapLanguage(map: MapLike, language: string): void;

package/dist/maps/mapLanguage.js

@@ -9,7 +9,7 @@
  * Based on the approach documented at:
  * https://docs.aws.amazon.com/location/latest/developerguide/how-to-set-preferred-language-map.html
  *
- * @param map - MapLibre Map instance
+ * @param map - MapLibre Map instance (or any object matching the MapLike interface)
  * @param language - ISO 639-1 language code (e.g. 'en', 'fr', 'de', 'ja', 'zh', 'ar')
  *
  * @example
@@ -19,8 +19,13 @@ export function applyMapLanguage(map, language) {
     try {
         const expression = language === 'en'
             ? ['coalesce', ['get', 'name:en'], ['get', 'name']]
-            : ['coalesce', ['get', `name:${language}`], ['get', 'name:en'], ['get', 'name']];
-        map.getStyle().layers.forEach(layer => {
+            : [
+                'coalesce',
+                ['get', `name:${language}`],
+                ['get', 'name:en'],
+                ['get', 'name'],
+            ];
+        map.getStyle().layers.forEach((layer) => {
             if (layer.type === 'symbol') {
                 const textField = map.getLayoutProperty(layer.id, 'text-field');
                 if (textField !== undefined && textField !== null) {

package/dist/maps/mapStyle.js

@@ -56,14 +56,14 @@ export async function fetchMapStyle(apiUrl, mapStyle, getToken, options = {}) {
     const token = getToken();
     const response = await fetch(url, {
         headers: {
-            'Authorization': `Bearer ${token}`,
-            'Accept': 'application/json',
-        }
+            Authorization: `Bearer ${token}`,
+            Accept: 'application/json',
+        },
     });
     if (!response.ok) {
         throw new Error(`Failed to fetch map style: ${response.status} ${response.statusText}`);
     }
-    const style = await response.json();
+    const style = (await response.json());
     if (language) {
         applyLanguageToDescriptor(style, language);
     }
@@ -76,7 +76,12 @@ export async function fetchMapStyle(apiUrl, mapStyle, getToken, options = {}) {
 function applyLanguageToDescriptor(style, language) {
     const expression = language === 'en'
         ? ['coalesce', ['get', 'name:en'], ['get', 'name']]
-        : ['coalesce', ['get', `name:${language}`], ['get', 'name:en'], ['get', 'name']];
+        : [
+            'coalesce',
+            ['get', `name:${language}`],
+            ['get', 'name:en'],
+            ['get', 'name'],
+        ];
     for (const layer of style.layers) {
         if (layer.type === 'symbol') {
             const layout = layer.layout;

package/dist/server/LocationServiceConnector.d.ts

@@ -1,3 +1,4 @@
+import type { GeoPlacesCommand } from '../types';
 export interface ConnectorConfig {
     apiUrl?: string;
     token?: string;
@@ -41,6 +42,6 @@ export declare class LocationServiceConnector {
     private configPromise;
     readonly serviceId: string;
     constructor(config?: ConnectorConfig);
-    send<TInput, TOutput>(command: TInput, options?: SendOptions): Promise<TOutput>;
+    send<TOutput>(command: GeoPlacesCommand, options?: SendOptions): Promise<TOutput>;
     private getEndpoint;
 }

package/dist/server/LocationServiceConnector.js

@@ -1,5 +1,7 @@
 import { AutocompleteCommand, GeocodeCommand, GetPlaceCommand, ReverseGeocodeCommand, SearchNearbyCommand, SearchTextCommand, SuggestCommand, } from '@aws-sdk/client-geo-places';
 import debug from 'debug';
+import { LocationServiceException } from '../errors/LocationServiceException';
+import { roundPositionFields } from '../utils/roundPosition';
 import { getClientConfig } from './getClientConfig';
 const log = debug('location-client:connector');
 /**
@@ -34,9 +36,7 @@ const log = debug('location-client:connector');
 export class LocationServiceConnector {
     constructor(config) {
         this.serviceId = 'Geo Places';
-        this.configPromise = config
-            ? Promise.resolve(config)
-            : getClientConfig();
+        this.configPromise = config ? Promise.resolve(config) : getClientConfig();
     }
     async send(command, options) {
         const config = await this.configPromise;
@@ -44,7 +44,11 @@ export class LocationServiceConnector {
         let token;
         if ('getToken' in config && typeof config.getToken === 'function') {
             const result = await config.getToken();
-            token = result ? (typeof result === 'string' ? result : result.token) : undefined;
+            token = result
+                ? typeof result === 'string'
+                    ? result
+                    : result.token
+                : undefined;
         }
         else {
             token = config.token;
@@ -55,38 +59,46 @@ export class LocationServiceConnector {
         const endpoint = this.getEndpoint(command);
         const url = `${config.apiUrl}${endpoint}`;
         const commandName = command.constructor.name;
-        const input = command.input;
+        const input = roundPositionFields(command.input);
         log('Sending %s request to %s', commandName, endpoint);
         const startTime = Date.now();
         // Merge headers: user headers, then system headers override
         const headers = {
             ...(options?.headers || {}),
             'Content-Type': 'application/json',
-            'Authorization': `Bearer ${token}`
+            Authorization: `Bearer ${token}`,
         };
         const response = await fetch(url, {
             method: 'POST',
             headers,
-            body: JSON.stringify(input)
+            body: JSON.stringify(input),
         });
         const duration = Date.now() - startTime;
         if (!response.ok) {
             const errorText = await response.text();
             log('Request failed: %s %s (%dms)', response.status, response.statusText, duration);
-            // Try to parse error message from response
             let errorMessage = `API request failed: ${response.statusText}`;
+            let errorCode = 'ServiceException';
+            let requestId;
             try {
                 const errorData = JSON.parse(errorText);
-                if (errorData.message) {
+                if (errorData.message)
                     errorMessage = errorData.message;
-                }
+                if (errorData.code)
+                    errorCode = errorData.code;
+                if (errorData.requestId)
+                    requestId = errorData.requestId;
             }
             catch {
-                // If not JSON, use raw text if available
                 if (errorText)
                     errorMessage = errorText;
             }
-            throw new Error(errorMessage);
+            throw new LocationServiceException({
+                message: errorMessage,
+                code: errorCode,
+                statusCode: response.status,
+                requestId,
+            });
         }
         const result = await response.json();
         log('Request successful: %s (%dms)', response.status, duration);

package/dist/server/getClientConfig.d.ts

@@ -1,4 +1,4 @@
-import { ClientConfig } from '../types';
+import type { ClientConfig } from '../types';
 export interface ServerAuthConfig {
     apiUrl?: string;
     clientId?: string;

package/dist/server/getClientConfig.js

@@ -48,7 +48,10 @@ function getTokenProvider(apiUrl, clientId, clientSecret) {
  * const connector = new LocationServiceConnector({ apiUrl: config.apiUrl, token })
  */
 export async function getClientConfig(config = {}) {
-    log('[getClientConfig] Starting with config:', { hasApiUrl: !!config.apiUrl, hasClientId: !!config.clientId });
+    log('[getClientConfig] Starting with config:', {
+        hasApiUrl: !!config.apiUrl,
+        hasClientId: !!config.clientId,
+    });
     // Auto-detect from environment with fallbacks
     const apiUrl = config.apiUrl ||
         process.env.LOCATION_API_URL ||
@@ -59,7 +62,10 @@ export async function getClientConfig(config = {}) {
     const clientSecret = config.clientSecret ||
         process.env.LOCATION_CLIENT_SECRET ||
         process.env.LOCATION_SERVICE_CLIENT_SECRET;
-    log('[getClientConfig] Resolved config:', { apiUrl, clientId: clientId?.substring(0, 10) + '...' });
+    log('[getClientConfig] Resolved config:', {
+        apiUrl,
+        clientId: clientId?.substring(0, 10) + '...',
+    });
     // Validate required values
     if (!apiUrl || !clientId || !clientSecret) {
         console.error('[getClientConfig] Missing required configuration');
@@ -77,12 +83,12 @@ export async function getClientConfig(config = {}) {
         throw new Error(isAuthError
             ? `Authentication failed for client ID "${clientId}". ` +
                 `Verify LOCATION_CLIENT_ID and LOCATION_CLIENT_SECRET match your application in the developer portal.`
-            : (result.error || 'Failed to get token'));
+            : result.error || 'Failed to get token');
     }
     log('[getClientConfig] Token fetched successfully, length:', result.token.length);
     return {
         apiUrl,
         token: result.token,
-        expiresAt: result.expiresAt
+        expiresAt: result.expiresAt,
     };
 }

package/dist/server/index.d.ts

@@ -1,6 +1,6 @@
+export { TokenProvider } from '../auth/TokenProvider';
+export type { TokenProviderConfig, TokenResponse } from '../auth/TokenProvider';
 export { getClientConfig } from './getClientConfig';
 export type { ServerAuthConfig, ServerClientConfig } from './getClientConfig';
 export { LocationServiceConnector } from './LocationServiceConnector';
 export type { ConnectorConfig, SendOptions } from './LocationServiceConnector';
-export { TokenProvider } from '../auth/TokenProvider';
-export type { TokenProviderConfig, TokenResponse } from '../auth/TokenProvider';

package/dist/server/index.js

@@ -1,3 +1,3 @@
+export { TokenProvider } from '../auth/TokenProvider';
 export { getClientConfig } from './getClientConfig';
 export { LocationServiceConnector } from './LocationServiceConnector';
-export { TokenProvider } from '../auth/TokenProvider';

package/dist/types/index.d.ts

@@ -5,3 +5,30 @@ export interface ClientConfig {
      *  called on every request so token updates are reflected without recreating the client. */
     getToken?: () => string | undefined;
 }
+/**
+ * Minimal interface for AWS SDK command objects.
+ * All AWS SDK commands (AutocompleteCommand, SearchTextCommand, etc.) extend
+ * Smithy's Command base class which has an `input` property containing the
+ * request parameters. This interface captures what we actually need from
+ * commands without coupling to Smithy internals.
+ */
+export interface GeoPlacesCommand {
+    readonly input: object;
+}
+/**
+ * Minimal interface for a MapLibre Map instance.
+ * Using a structural type avoids hard coupling to a specific maplibre-gl version.
+ */
+export interface MapLike {
+    isStyleLoaded(): boolean | void;
+    on(event: string, listener: (...args: unknown[]) => void): void;
+    off(event: string, listener: (...args: unknown[]) => void): void;
+    getStyle(): {
+        layers: Array<{
+            id: string;
+            type: string;
+        }>;
+    };
+    getLayoutProperty(layerId: string, name: string): unknown;
+    setLayoutProperty(layerId: string, name: string, value: unknown): void;
+}

package/dist/utils/roundPosition.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Round coordinate arrays in command inputs for better API cache hits.
+ *
+ * BiasPosition is rounded to 2 decimal places (~1.1 km precision) —
+ * sufficient for spatial biasing while maximizing cache reuse across
+ * nearby users.
+ *
+ * QueryPosition (reverse geocode) keeps full precision since it
+ * represents an exact point the user clicked or their device reported.
+ */
+/**
+ * Shallow-clone the input and round position arrays that benefit from caching.
+ * Returns the original object if no position fields are present.
+ */
+export declare function roundPositionFields<T extends object>(input: T): T;

package/dist/utils/roundPosition.js

@@ -0,0 +1,38 @@
+/**
+ * Round coordinate arrays in command inputs for better API cache hits.
+ *
+ * BiasPosition is rounded to 2 decimal places (~1.1 km precision) —
+ * sufficient for spatial biasing while maximizing cache reuse across
+ * nearby users.
+ *
+ * QueryPosition (reverse geocode) keeps full precision since it
+ * represents an exact point the user clicked or their device reported.
+ */
+const BIAS_DECIMALS = 2; // ~1.1 km grid
+const BIAS_FACTOR = 10 ** BIAS_DECIMALS;
+/** Known position field names and whether they should be rounded */
+const POSITION_FIELDS = {
+    BiasPosition: true, // geocode, autocomplete, search — round for cache
+    QueryPosition: false, // reverse geocode — keep full precision
+};
+function roundCoord(value) {
+    return Math.round(value * BIAS_FACTOR) / BIAS_FACTOR;
+}
+/**
+ * Shallow-clone the input and round position arrays that benefit from caching.
+ * Returns the original object if no position fields are present.
+ */
+export function roundPositionFields(input) {
+    if (!input || typeof input !== 'object')
+        return input;
+    let modified = false;
+    const result = { ...input };
+    for (const [field, shouldRound] of Object.entries(POSITION_FIELDS)) {
+        const value = result[field];
+        if (!shouldRound || !Array.isArray(value) || value.length < 2)
+            continue;
+        result[field] = value.map(roundCoord);
+        modified = true;
+    }
+    return modified ? result : input;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chaosity/location-client",
-  "version": "0.1.10",
+  "version": "0.1.13",
   "description": "Client library for Chaosity Location Service with AWS Location Service compatibility",
   "type": "module",
   "main": "dist/index.js",
@@ -18,9 +18,14 @@
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",
-    "test": "vitest run",
+    "lint": "eslint . && prettier --check .",
+    "lint:fix": "eslint --fix . && prettier --write .",
+    "format": "prettier --write .",
+    "test": "vitest run --passWithNoTests",
     "test:watch": "vitest",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "prepare": "husky",
+    "postversion": "git push --follow-tags"
   },
   "keywords": [
     "aws",
@@ -55,10 +60,17 @@
     }
   },
   "devDependencies": {
+    "@eslint/js": "^10.0.1",
     "@types/debug": "^4.1.12",
     "@types/node": "^25.0.3",
+    "@vitest/coverage-v8": "^3.0.0",
+    "eslint": "^10.1.0",
+    "husky": "^9.0.0",
     "maplibre-gl": "^5.0.0",
+    "prettier": "^3.8.1",
+    "prettier-plugin-organize-imports": "^4.3.0",
     "typescript": "^5.0.0",
+    "typescript-eslint": "^8.57.1",
     "vitest": "^3.0.0"
   },
   "publishConfig": {

package/dist/server/getConnector.d.ts

@@ -1,37 +0,0 @@
-import { LocationServiceConnector } from './LocationServiceConnector';
-export interface ServerAuthConfig {
-    apiUrl?: string;
-    clientId?: string;
-    clientSecret?: string;
-}
-/**
- * Get LocationServiceConnector with automatic token management.
- *
- * Automatically reads from environment variables:
- * - LOCATION_API_URL or LOCATION_SERVICE_API_URL
- * - LOCATION_CLIENT_ID or LOCATION_SERVICE_CLIENT_ID
- * - LOCATION_CLIENT_SECRET or LOCATION_SERVICE_CLIENT_SECRET
- *
- * You can override any value by passing it explicitly.
- *
- * WARNING: This function uses client credentials (clientId/clientSecret).
- * Only call this from:
- * - Next.js Server Components/Actions
- * - Node.js backend servers
- * - API routes
- *
- * NEVER call from browser/client code as it exposes credentials.
- *
- * @example
- * // Server Action for React provider
- * 'use server'
- * export async function getLocationConnector() {
- *   return getConnector()
- * }
- *
- * // Or with custom config
- * export async function getLocationConnector() {
- *   return getConnector({ apiUrl: 'https://custom.api.com' })
- * }
- */
-export declare function getConnector(config?: ServerAuthConfig): LocationServiceConnector;

package/dist/server/getConnector.js

@@ -1,34 +0,0 @@
-import { LocationServiceConnector } from './LocationServiceConnector';
-/**
- * Get LocationServiceConnector with automatic token management.
- *
- * Automatically reads from environment variables:
- * - LOCATION_API_URL or LOCATION_SERVICE_API_URL
- * - LOCATION_CLIENT_ID or LOCATION_SERVICE_CLIENT_ID
- * - LOCATION_CLIENT_SECRET or LOCATION_SERVICE_CLIENT_SECRET
- *
- * You can override any value by passing it explicitly.
- *
- * WARNING: This function uses client credentials (clientId/clientSecret).
- * Only call this from:
- * - Next.js Server Components/Actions
- * - Node.js backend servers
- * - API routes
- *
- * NEVER call from browser/client code as it exposes credentials.
- *
- * @example
- * // Server Action for React provider
- * 'use server'
- * export async function getLocationConnector() {
- *   return getConnector()
- * }
- *
- * // Or with custom config
- * export async function getLocationConnector() {
- *   return getConnector({ apiUrl: 'https://custom.api.com' })
- * }
- */
-export function getConnector(config) {
-    return new LocationServiceConnector(config);
-}