@chaosity/location-client 0.1.3 → 0.1.5

package/README.md

@@ -2,6 +2,20 @@
 
 AWS Location Service compatible client with custom Bearer token authentication.
 
+## ⚠️ Security Warning
+
+**This package contains server-side authentication utilities that require client credentials.**
+
+- `TokenProvider` and `getClientConfig()` are **SERVER-SIDE ONLY**
+- They require `clientId` and `clientSecret` which must **NEVER** be exposed to browsers
+- Only use these in:
+  - Node.js servers
+  - Next.js Server Actions (`'use server'`)
+  - Next.js API routes
+  - Backend services
+
+**For React applications**, use [`@chaosity/location-client-react`](https://www.npmjs.com/package/@chaosity/location-client-react) which handles authentication safely.
+
 ## Installation
 
 ```bash
@@ -148,6 +162,33 @@ import {
 } from '@chaosity/location-client'
 ```
 
+## Logging
+
+The library uses the `debug` package for optional verbose logging. Enable it via the `DEBUG` environment variable:
+
+```bash
+# Enable all location-client logs
+DEBUG=location-client:* npm run dev
+
+# Enable only authentication logs
+DEBUG=location-client:auth npm run dev
+
+# Enable only API request logs
+DEBUG=location-client:api npm run dev
+
+# Enable multiple namespaces
+DEBUG=location-client:*,express:* npm run dev
+```
+
+Example output:
+```
+location-client:auth Initializing TokenProvider for https://api.example.com +0ms
+location-client:auth Fetching new token from https://api.example.com +2ms
+location-client:auth Token acquired successfully (expires in 3600s) +145ms
+location-client:api Sending SuggestCommand request to /address/suggestion +0ms
+location-client:api Request successful: 200 (89ms) +89ms
+```
+
 ## Security Best Practices
 
 ⚠️ **NEVER expose client credentials in browser code!**

package/dist/adapters/GeoPlaces.d.ts

@@ -1,27 +1,19 @@
-import type { FeatureCollection } from 'geojson';
+import type { MaplibreGeocoderApi, MaplibreGeocoderApiConfig, MaplibreGeocoderFeatureResults, MaplibreGeocoderPlaceResults, MaplibreGeocoderSuggestionResults } from '@maplibre/maplibre-gl-geocoder';
 import type { Map } from 'maplibre-gl';
 import { GeoPlacesClient } from '../client/GeoPlacesClient';
 /**
  * GeoPlaces - MapLibre adapter for AWS Location Service
  *
- * Uses AWS Location Client commands and utilities for data conversion.
- * Only auth is custom (Bearer token instead of SigV4).
+ * Implements MaplibreGeocoderApi interface for compatibility with @maplibre/maplibre-gl-geocoder
  */
-export declare class GeoPlaces {
+export declare class GeoPlaces implements MaplibreGeocoderApi {
     private client;
     private map;
     constructor(client: GeoPlacesClient, map: Map);
-    forwardGeocode(config: {
-        query: string;
-        limit?: number;
-    }): Promise<FeatureCollection>;
-    reverseGeocode(config: {
-        query: [number, number];
-        limit?: number;
-        click?: boolean;
-    }): Promise<FeatureCollection>;
-    getSuggestions(config: {
-        query: string;
-    }): Promise<FeatureCollection>;
-    searchByPlaceId(placeId: string): Promise<FeatureCollection>;
+    private normalizeLanguage;
+    forwardGeocode(config: MaplibreGeocoderApiConfig): Promise<MaplibreGeocoderFeatureResults>;
+    reverseGeocode(config: MaplibreGeocoderApiConfig): Promise<MaplibreGeocoderFeatureResults>;
+    getSuggestions(config: MaplibreGeocoderApiConfig): Promise<MaplibreGeocoderSuggestionResults>;
+    searchByPlaceId(config: MaplibreGeocoderApiConfig): Promise<MaplibreGeocoderPlaceResults>;
+    localGeocode(config: MaplibreGeocoderApiConfig): Promise<MaplibreGeocoderFeatureResults>;
 }

package/dist/adapters/GeoPlaces.js

@@ -1,58 +1,147 @@
-import { placeToFeatureCollection } from '@aws/amazon-location-utilities-datatypes';
-import { GetPlaceCommand, ReverseGeocodeCommand, SearchNearbyCommand, SuggestCommand } from '@aws-sdk/client-geo-places';
+import { GeocodeAdditionalFeature, GeocodeCommand, GetPlaceAdditionalFeature, GetPlaceCommand, ReverseGeocodeCommand } from '@aws-sdk/client-geo-places';
+import { geocodeResponseToFeatureCollection, getPlaceResponseToFeatureCollection, reverseGeocodeResponseToFeatureCollection } from '@aws/amazon-location-utilities-datatypes';
 /**
  * GeoPlaces - MapLibre adapter for AWS Location Service
  *
- * Uses AWS Location Client commands and utilities for data conversion.
- * Only auth is custom (Bearer token instead of SigV4).
+ * Implements MaplibreGeocoderApi interface for compatibility with @maplibre/maplibre-gl-geocoder
  */
 export class GeoPlaces {
     constructor(client, map) {
         this.client = client;
         this.map = map;
     }
+    normalizeLanguage(language) {
+        if (Array.isArray(language))
+            return language[0] || 'en';
+        if (typeof language === 'string')
+            return language;
+        return 'en';
+    }
     async forwardGeocode(config) {
+        console.log('[GeoPlaces] forwardGeocode called with:', config);
         const center = this.map.getCenter();
-        const command = new SuggestCommand({
+        const biasPosition = config.proximity && config.proximity.length >= 2
+            ? [config.proximity[0], config.proximity[1]]
+            : [center.lng, center.lat];
+        const commandInput = {
             QueryText: config.query,
-            BiasPosition: [center.lng, center.lat],
+            BiasPosition: biasPosition,
             MaxResults: config.limit || 5,
-            Language: 'en'
-        });
+            Language: this.normalizeLanguage(config.language),
+        };
+        if (config.countries || config.bbox) {
+            commandInput.Filter = {};
+            if (config.countries)
+                commandInput.Filter.IncludeCountries = config.countries;
+            if (config.bbox)
+                commandInput.Filter.BoundingBox = config.bbox;
+        }
+        console.log('[GeoPlaces] Sending SearchTextCommand with:', commandInput);
+        const command = new GeocodeCommand(commandInput);
         const response = await this.client.send(command);
-        return placeToFeatureCollection(response, { flattenProperties: true });
+        console.log('[GeoPlaces] SearchTextCommand response:', response);
+        const result = geocodeResponseToFeatureCollection(response, { flattenProperties: true });
+        console.log('[GeoPlaces] Converted to FeatureCollection:', result);
+        return result;
     }
     async reverseGeocode(config) {
-        const command = config.click
-            ? new ReverseGeocodeCommand({
-                QueryPosition: config.query,
-                MaxResults: config.limit || 1,
-                Language: 'en'
-            })
-            : new SearchNearbyCommand({
-                QueryPosition: config.query,
-                MaxResults: config.limit || 15,
-                Language: 'en'
-            });
+        console.log('[GeoPlaces] reverseGeocode called with:', config);
+        const queryPosition = Array.isArray(config.query) && config.query.length >= 2
+            ? [config.query[0], config.query[1]]
+            : [0, 0];
+        const commandInput = {
+            QueryPosition: queryPosition,
+            MaxResults: config.limit || 1,
+            Language: this.normalizeLanguage(config.language)
+        };
+        if (config.countries) {
+            commandInput.Filter = { IncludeCountries: config.countries };
+        }
+        const command = new ReverseGeocodeCommand(commandInput);
         const response = await this.client.send(command);
-        return placeToFeatureCollection(response, { flattenProperties: true });
+        const maplibreGeocoderFeatureResults = reverseGeocodeResponseToFeatureCollection(response, { flattenProperties: true });
+        maplibreGeocoderFeatureResults.features.forEach(feature => {
+        });
+        console.log('[GeoPlaces] Converted to FeatureCollection:', maplibreGeocoderFeatureResults);
+        return maplibreGeocoderFeatureResults;
     }
     async getSuggestions(config) {
+        // const center = this.map.getCenter()
+        // const biasPosition = config.proximity && config.proximity.length >= 2
+        //   ? [config.proximity[0], config.proximity[1]]
+        //   : [center.lng, center.lat]
+        // const commandInput: any = {
+        //   QueryText: config.query as string,
+        //   BiasPosition: biasPosition,
+        //   MaxResults: config.limit || 5,
+        //   Language: this.normalizeLanguage(config.language),
+        //   AdditionalFeatures: [SuggestAdditionalFeature.CORE],
+        // }
+        // if (config.countries || config.bbox) {
+        //   commandInput.Filter = {}
+        //   if (config.countries) commandInput.Filter.IncludeCountries = config.countries
+        //   if (config.bbox) commandInput.Filter.BoundingBox = config.bbox
+        // }
+        // const command = new SuggestCommand(commandInput)
+        // const response = await this.client.send(command) as SuggestResponse
         const center = this.map.getCenter();
-        const command = new SuggestCommand({
+        const biasPosition = config.proximity && config.proximity.length >= 2
+            ? [config.proximity[0], config.proximity[1]]
+            : [center.lng, center.lat];
+        const commandInput = {
             QueryText: config.query,
-            BiasPosition: [center.lng, center.lat],
-            Language: 'en'
-        });
+            BiasPosition: biasPosition,
+            MaxResults: config.limit || 5,
+            Language: this.normalizeLanguage(config.language),
+            AdditionalFeatures: [GeocodeAdditionalFeature.SECONDARY_ADDRESSES],
+        };
+        if (config.countries || config.bbox) {
+            commandInput.Filter = {};
+            if (config.countries)
+                commandInput.Filter.IncludeCountries = Array.isArray(config.countries) ? config.countries : config.countries.split(',');
+            // if (config.types) commandInput.Filter.IncludePlaceTypes = config.types.split(',').map(type => new GeocodeFilterPlaceType)
+        }
+        console.log('[GeoPlaces] Sending SearchTextCommand with:', commandInput);
+        const command = new GeocodeCommand(commandInput);
         const response = await this.client.send(command);
-        return placeToFeatureCollection(response, { flattenProperties: true });
+        console.log('[GeoPlaces] SearchTextCommand response:', response);
+        const maplibreGeocoderSuggestionResults = { suggestions: [] };
+        response?.ResultItems?.forEach(item => {
+            const text = item?.Title || item?.Address?.Label;
+            const placeId = item?.PlaceId;
+            if (text) {
+                maplibreGeocoderSuggestionResults.suggestions.push({
+                    text,
+                    placeId,
+                });
+            }
+        });
+        console.log('[GeoPlaces] Converted to MaplibreGeocoderSuggestionResults:', maplibreGeocoderSuggestionResults);
+        return maplibreGeocoderSuggestionResults;
     }
-    async searchByPlaceId(placeId) {
+    async searchByPlaceId(config) {
+        console.log('[GeoPlaces] searchByPlaceId called with:', config);
+        const placeId = config.query;
         const command = new GetPlaceCommand({
             PlaceId: placeId,
-            Language: 'en'
+            Language: this.normalizeLanguage(config.language),
+            AdditionalFeatures: [GetPlaceAdditionalFeature.ACCESS, GetPlaceAdditionalFeature.SECONDARY_ADDRESSES, GetPlaceAdditionalFeature.CONTACT, GetPlaceAdditionalFeature.TIME_ZONE],
         });
         const response = await this.client.send(command);
-        return placeToFeatureCollection(response, { flattenProperties: true });
+        const result = getPlaceResponseToFeatureCollection(response, { flattenProperties: true });
+        console.log('[GeoPlaces] GetPlaceCommand response converted to FeatureCollection:', result);
+        const carmenGeojsonFeatures = result.features.map(feature => ({
+            ...feature,
+            text: response.Title || '',
+            place_name: response.Address?.Label || '',
+            place_type: response.PlaceType ? [response.PlaceType] : [],
+            bbox: response.MapView
+        }));
+        console.log('[GeoPlaces] Converted to CarmenGeojsonFeatures:', carmenGeojsonFeatures);
+        return { place: carmenGeojsonFeatures };
+    }
+    async localGeocode(config) {
+        console.log('[GeoPlaces] localGeocode called with:', config);
+        return this.forwardGeocode(config);
     }
 }

package/dist/auth/TokenProvider.d.ts

@@ -1,8 +1,6 @@
 export interface TokenResponse {
     success: boolean;
     token?: string;
-    expiresIn?: number;
-    expiresAt?: number;
     error?: string;
 }
 export interface TokenProviderConfig {
@@ -10,12 +8,43 @@ export interface TokenProviderConfig {
     clientId: string;
     clientSecret: string;
 }
+/**
+ * TokenProvider - SERVER-SIDE ONLY
+ *
+ * ⚠️ WARNING: This class requires client credentials (clientId and clientSecret)
+ * and must NEVER be used in browser/client-side code.
+ *
+ * Use this only in:
+ * - Node.js server environments
+ * - Next.js Server Actions (marked with 'use server')
+ * - Next.js API routes
+ * - Backend services
+ *
+ * For browser usage, use the React provider which receives tokens from server-side code.
+ *
+ * @example
+ * // ✓ Correct: Server-side usage
+ * import { TokenProvider } from '@chaosity/location-client'
+ *
+ * const provider = new TokenProvider({
+ *   apiUrl: process.env.API_URL!,
+ *   clientId: process.env.CLIENT_ID!,
+ *   clientSecret: process.env.CLIENT_SECRET!,
+ * })
+ *
+ * @example
+ * // ✗ Wrong: Never use in browser code
+ * // This would expose your credentials!
+ */
 export declare class TokenProvider {
     private config;
     private cachedToken?;
-    private expiresAt?;
+    private oauth2Client;
+    private tokenPromise?;
     constructor(config: TokenProviderConfig);
     getToken(forceRefresh?: boolean): Promise<TokenResponse>;
+    private fetchToken;
+    private getTokenExpiry;
     private isExpired;
     clearCache(): void;
 }

package/dist/auth/TokenProvider.js

@@ -1,52 +1,115 @@
+import ClientOAuth2 from 'client-oauth2';
+import { decodeJwt } from 'jose';
+import debug from 'debug';
+const log = debug('location-client:auth');
+/**
+ * TokenProvider - SERVER-SIDE ONLY
+ *
+ * ⚠️ WARNING: This class requires client credentials (clientId and clientSecret)
+ * and must NEVER be used in browser/client-side code.
+ *
+ * Use this only in:
+ * - Node.js server environments
+ * - Next.js Server Actions (marked with 'use server')
+ * - Next.js API routes
+ * - Backend services
+ *
+ * For browser usage, use the React provider which receives tokens from server-side code.
+ *
+ * @example
+ * // ✓ Correct: Server-side usage
+ * import { TokenProvider } from '@chaosity/location-client'
+ *
+ * const provider = new TokenProvider({
+ *   apiUrl: process.env.API_URL!,
+ *   clientId: process.env.CLIENT_ID!,
+ *   clientSecret: process.env.CLIENT_SECRET!,
+ * })
+ *
+ * @example
+ * // ✗ Wrong: Never use in browser code
+ * // This would expose your credentials!
+ */
 export class TokenProvider {
     constructor(config) {
+        // Runtime check: prevent usage in browser
+        if (typeof window !== 'undefined') {
+            throw new Error('TokenProvider cannot be used in browser environments. ' +
+                'It requires client credentials that must never be exposed to browsers. ' +
+                'Use @chaosity/location-client-react for browser usage.');
+        }
+        log('Initializing TokenProvider for %s', config.apiUrl);
         this.config = config;
+        this.oauth2Client = new ClientOAuth2({
+            clientId: config.clientId,
+            clientSecret: config.clientSecret,
+            accessTokenUri: `${config.apiUrl}/auth/token`,
+        });
     }
     async getToken(forceRefresh = false) {
-        if (!forceRefresh && this.cachedToken && this.expiresAt && !this.isExpired()) {
+        if (!forceRefresh && this.cachedToken && !this.isExpired()) {
+            const exp = this.getTokenExpiry();
+            log('Using cached token (expires in %ds)', exp ? Math.floor(exp - Date.now() / 1000) : 'unknown');
             return {
                 success: true,
-                token: this.cachedToken,
-                expiresAt: this.expiresAt
+                token: this.cachedToken
             };
         }
+        // If token fetch is already in progress, wait for it
+        if (this.tokenPromise) {
+            log('Token fetch in progress, waiting for existing request...');
+            return this.tokenPromise;
+        }
+        // Start new token fetch
+        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 {
+            const result = await this.tokenPromise;
+            return result;
+        }
+        finally {
+            // Clear promise after completion (success or failure)
+            this.tokenPromise = undefined;
+        }
+    }
+    async fetchToken() {
         try {
-            const response = await fetch(`${this.config.apiUrl}/auth/token`, {
-                method: 'POST',
-                headers: { 'Content-Type': 'application/json' },
-                body: JSON.stringify({
-                    client_id: this.config.clientId,
-                    client_secret: this.config.clientSecret,
-                    grant_type: 'client_credentials',
-                }),
-            });
-            if (!response.ok) {
-                throw new Error(`Failed to get token: ${response.statusText}`);
-            }
-            const data = await response.json();
-            this.cachedToken = data.access_token;
-            this.expiresAt = Date.now() + (data.expires_in * 1000);
+            const token = await this.oauth2Client.credentials.getToken();
+            this.cachedToken = token.accessToken;
+            const exp = this.getTokenExpiry();
+            log('Token acquired successfully (expires in %ds)', exp ? Math.floor(exp - Date.now() / 1000) : 'unknown');
             return {
                 success: true,
-                token: this.cachedToken,
-                expiresIn: data.expires_in,
-                expiresAt: this.expiresAt,
+                token: this.cachedToken
             };
         }
         catch (error) {
+            log('Token acquisition failed: %s', error instanceof Error ? error.message : 'Unknown error');
             return {
                 success: false,
                 error: error instanceof Error ? error.message : 'Failed to get token',
             };
         }
     }
+    getTokenExpiry() {
+        if (!this.cachedToken)
+            return null;
+        try {
+            const decoded = decodeJwt(this.cachedToken);
+            return decoded.exp || null;
+        }
+        catch {
+            return null;
+        }
+    }
     isExpired(bufferSeconds = 60) {
-        if (!this.expiresAt)
+        const exp = this.getTokenExpiry();
+        if (!exp)
             return true;
-        return Date.now() >= (this.expiresAt - bufferSeconds * 1000);
+        return Date.now() / 1000 >= (exp - bufferSeconds);
     }
     clearCache() {
         this.cachedToken = undefined;
-        this.expiresAt = undefined;
     }
 }

package/dist/client/GeoPlacesClient.js

@@ -1,4 +1,6 @@
-import { AutocompleteCommand, GeocodeCommand, GetPlaceCommand, ReverseGeocodeCommand, SearchNearbyCommand, SearchTextCommand, SuggestCommand, } from '@aws-sdk/client-geo-places';
+import debug from 'debug';
+const log = debug('location-client:api');
+const logError = debug('location-client:api:error');
 /**
  * GeoPlacesClient - AWS Location Service compatible client with custom auth
  *
@@ -12,41 +14,65 @@ export class GeoPlacesClient {
     }
     async send(command) {
         const endpoint = this.getEndpoint(command);
-        const response = await fetch(`${this.clientConfig.apiUrl}${endpoint}`, {
+        const url = `${this.clientConfig.apiUrl}${endpoint}`;
+        const commandName = command.constructor.name;
+        const input = command.input;
+        log(`[GeoPlacesClient] Sending ${commandName} to ${endpoint}`);
+        log('[GeoPlacesClient] Request body:', JSON.stringify(input, null, 2));
+        log('Sending %s request to %s', commandName, endpoint);
+        const startTime = Date.now();
+        const response = await fetch(url, {
             method: 'POST',
             headers: {
                 'Content-Type': 'application/json',
                 'Authorization': `Bearer ${this.clientConfig.token}`
             },
-            body: JSON.stringify(command)
+            body: JSON.stringify(input)
         });
+        const duration = Date.now() - startTime;
         if (!response.ok) {
-            throw new Error(`API request failed: ${response.statusText}`);
+            const errorText = await response.text();
+            log(`[GeoPlacesClient] Request failed: ${response.status} ${response.statusText}`, errorText);
+            logError('Request failed: %s %s (%dms)', response.status, response.statusText, duration);
+            // Try to parse error message from response
+            let errorMessage = `API request failed: ${response.statusText}`;
+            try {
+                const errorData = JSON.parse(errorText);
+                if (errorData.message) {
+                    errorMessage = errorData.message;
+                }
+            }
+            catch {
+                // If not JSON, use raw text if available
+                if (errorText)
+                    errorMessage = errorText;
+            }
+            throw new Error(errorMessage);
         }
-        return response.json();
+        const result = await response.json();
+        log(`[GeoPlacesClient] Response (${duration}ms):`, JSON.stringify(result, null, 2));
+        log('Request successful: %s (%dms)', response.status, duration);
+        return result;
     }
     getEndpoint(command) {
-        if (command instanceof AutocompleteCommand) {
-            return '/address/autocomplete';
+        const commandName = command.constructor.name;
+        switch (commandName) {
+            case 'AutocompleteCommand':
+                return '/address/autocomplete';
+            case 'GeocodeCommand':
+                return '/address/geocode';
+            case 'GetPlaceCommand':
+                return '/address/place';
+            case 'ReverseGeocodeCommand':
+                return '/address/search/reverse-geocode';
+            case 'SearchNearbyCommand':
+                return '/address/search/nearby';
+            case 'SearchTextCommand':
+                return '/address/search/text';
+            case 'SuggestCommand':
+                return '/address/suggestion';
+            default:
+                throw new Error(`Unknown command type: ${commandName}`);
         }
-        else if (command instanceof GeocodeCommand) {
-            return '/address/geocode';
-        }
-        else if (command instanceof GetPlaceCommand) {
-            return '/address/place';
-        }
-        else if (command instanceof ReverseGeocodeCommand) {
-            return '/address/search/reverse-geocode';
-        }
-        else if (command instanceof SearchNearbyCommand) {
-            return '/address/search/nearby';
-        }
-        else if (command instanceof SearchTextCommand) {
-            return '/address/search/text';
-        }
-        else if (command instanceof SuggestCommand) {
-            return '/address/suggestion';
-        }
-        throw new Error('Unknown command type');
     }
 }

package/dist/index.d.ts

@@ -4,6 +4,10 @@ export { GeoPlacesClient } from './client/GeoPlacesClient';
 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 type { ClientConfig } from './types';
 export { getClientConfig } from './server/getClientConfig';
 export type { ServerAuthConfig } from './server/getClientConfig';
+export { LocationServiceConnector } from './server/LocationServiceConnector';
+export type { ConnectorConfig } from './server/LocationServiceConnector';

package/dist/index.js

@@ -8,5 +8,9 @@ export * from '@aws-sdk/client-geo-places';
 export * from '@aws/amazon-location-utilities-datatypes';
 // Adapters (Custom - for MapLibre integration)
 export { GeoPlaces } from './adapters/GeoPlaces';
+// Maps utilities
+export { createTransformRequest } from './maps/createTransformRequest';
+export { transformRequest } from './maps/Utils';
 // Server-only utilities
 export { getClientConfig } from './server/getClientConfig';
+export { LocationServiceConnector } from './server/LocationServiceConnector';

package/dist/maps/Utils.d.ts

@@ -0,0 +1,8 @@
+import { ClientConfig } from "../types";
+export declare function transformRequest(url: string, config: ClientConfig): {
+    url: string;
+    headers: Record<string, string>;
+} | {
+    url: string;
+    headers?: undefined;
+};

package/dist/maps/Utils.js

@@ -0,0 +1,24 @@
+export function transformRequest(url, config) {
+    if (url.startsWith(config.apiUrl)) {
+        const headers = {
+            'Authorization': `Bearer ${config.token}`,
+        };
+        if (url.includes('/tiles/')) {
+            headers['Accept'] = 'application/x-protobuf';
+        }
+        else if (url.includes('/glyphs/')) {
+            headers['Accept'] = 'application/x-protobuf';
+        }
+        else if (url.includes('/sprites/') && url.endsWith('.png')) {
+            headers['Accept'] = 'image/png';
+        }
+        else if (url.includes('/sprites/') && url.endsWith('.json')) {
+            headers['Accept'] = 'application/json';
+        }
+        else if (url.includes('/descriptor')) {
+            headers['Accept'] = 'application/json';
+        }
+        return { url, headers };
+    }
+    return { url };
+}

package/dist/maps/createTransformRequest.d.ts

@@ -0,0 +1,10 @@
+import type { RequestTransformFunction } from 'maplibre-gl';
+/**
+ * Creates a transformRequest function for MapLibre that adds authentication
+ * and proper Accept headers for AWS Location Service API requests.
+ *
+ * @param apiUrl - Base URL of the Location Service API
+ * @param getToken - Callback function that returns the current auth token
+ * @returns MapLibre transformRequest function
+ */
+export declare function createTransformRequest(apiUrl: string, getToken: () => string | undefined): RequestTransformFunction;

package/dist/maps/createTransformRequest.js

@@ -0,0 +1,40 @@
+/**
+ * Creates a transformRequest function for MapLibre that adds authentication
+ * and proper Accept headers for AWS Location Service API requests.
+ *
+ * @param apiUrl - Base URL of the Location Service API
+ * @param getToken - Callback function that returns the current auth token
+ * @returns MapLibre transformRequest function
+ */
+export function createTransformRequest(apiUrl, getToken) {
+    return (url, resourceType) => {
+        if (url.startsWith(apiUrl)) {
+            const token = getToken();
+            if (!token) {
+                console.warn('[createTransformRequest] No token available');
+                return { url };
+            }
+            const headers = {
+                'Authorization': `Bearer ${token}`,
+            };
+            // Set appropriate Accept headers based on resource type
+            if (url.includes('/tiles/')) {
+                headers['Accept'] = 'application/x-protobuf';
+            }
+            else if (url.includes('/glyphs/')) {
+                headers['Accept'] = 'application/x-protobuf';
+            }
+            else if (url.includes('/sprites/') && url.endsWith('.png')) {
+                headers['Accept'] = 'image/png';
+            }
+            else if (url.includes('/sprites/') && url.endsWith('.json')) {
+                headers['Accept'] = 'application/json';
+            }
+            else if (url.includes('/descriptor')) {
+                headers['Accept'] = 'application/json';
+            }
+            return { url, headers };
+        }
+        return { url };
+    };
+}

package/dist/server/LocationServiceConnector.d.ts

@@ -0,0 +1,46 @@
+export interface ConnectorConfig {
+    apiUrl?: string;
+    token?: string;
+    getToken?: () => Promise<{
+        token: string;
+    }>;
+}
+export interface SendOptions {
+    headers?: Record<string, string>;
+}
+/**
+ * LocationServiceConnector - Server-side connector for Location Service API
+ *
+ * Optimized for backend-to-backend communication with:
+ * - Automatic configuration from environment variables
+ * - Automatic Origin header handling
+ * - Server-side token management
+ * - Enhanced error handling
+ *
+ * Uses AWS SDK command classes with Bearer token authentication.
+ *
+ * @example
+ * ```typescript
+ * // Auto-detect from environment
+ * const connector = new LocationServiceConnector()
+ *
+ * // Or provide explicit config
+ * const connector = new LocationServiceConnector({
+ *   apiUrl: 'https://api.example.com',
+ *   token: 'your-token'
+ * })
+ *
+ * // Send with custom headers (including Origin)
+ * const result = await connector.send(
+ *   new SearchTextCommand({ QueryText: 'Space Needle' }),
+ *   { headers: { 'Origin': req.headers.origin } }
+ * )
+ * ```
+ */
+export declare class LocationServiceConnector {
+    private configPromise;
+    readonly serviceId: string;
+    constructor(config?: ConnectorConfig);
+    send<TInput, TOutput>(command: TInput, options?: SendOptions): Promise<TOutput>;
+    private getEndpoint;
+}

package/dist/server/LocationServiceConnector.js

@@ -0,0 +1,110 @@
+import debug from 'debug';
+import { getClientConfig } from './getClientConfig';
+const log = debug('location-client:connector');
+/**
+ * LocationServiceConnector - Server-side connector for Location Service API
+ *
+ * Optimized for backend-to-backend communication with:
+ * - Automatic configuration from environment variables
+ * - Automatic Origin header handling
+ * - Server-side token management
+ * - Enhanced error handling
+ *
+ * Uses AWS SDK command classes with Bearer token authentication.
+ *
+ * @example
+ * ```typescript
+ * // Auto-detect from environment
+ * const connector = new LocationServiceConnector()
+ *
+ * // Or provide explicit config
+ * const connector = new LocationServiceConnector({
+ *   apiUrl: 'https://api.example.com',
+ *   token: 'your-token'
+ * })
+ *
+ * // Send with custom headers (including Origin)
+ * const result = await connector.send(
+ *   new SearchTextCommand({ QueryText: 'Space Needle' }),
+ *   { headers: { 'Origin': req.headers.origin } }
+ * )
+ * ```
+ */
+export class LocationServiceConnector {
+    constructor(config) {
+        this.serviceId = 'Geo Places';
+        this.configPromise = config
+            ? Promise.resolve(config)
+            : getClientConfig();
+    }
+    async send(command, options) {
+        const config = await this.configPromise;
+        // Get token - ConnectorConfig may have getToken, ServerClientConfig has static token
+        const token = 'getToken' in config && config.getToken
+            ? (await config.getToken()).token
+            : config.token;
+        if (!token) {
+            throw new Error('No token available');
+        }
+        const endpoint = this.getEndpoint(command);
+        const url = `${config.apiUrl}${endpoint}`;
+        const commandName = command.constructor.name;
+        const input = 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}`
+        };
+        const response = await fetch(url, {
+            method: 'POST',
+            headers,
+            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}`;
+            try {
+                const errorData = JSON.parse(errorText);
+                if (errorData.message) {
+                    errorMessage = errorData.message;
+                }
+            }
+            catch {
+                // If not JSON, use raw text if available
+                if (errorText)
+                    errorMessage = errorText;
+            }
+            throw new Error(errorMessage);
+        }
+        const result = await response.json();
+        log('Request successful: %s (%dms)', response.status, duration);
+        return result;
+    }
+    getEndpoint(command) {
+        const commandName = command.constructor.name;
+        switch (commandName) {
+            case 'AutocompleteCommand':
+                return '/address/autocomplete';
+            case 'GeocodeCommand':
+                return '/address/geocode';
+            case 'GetPlaceCommand':
+                return '/address/place';
+            case 'ReverseGeocodeCommand':
+                return '/address/search/reverse-geocode';
+            case 'SearchNearbyCommand':
+                return '/address/search/nearby';
+            case 'SearchTextCommand':
+                return '/address/search/text';
+            case 'SuggestCommand':
+                return '/address/suggestion';
+            default:
+                throw new Error(`Unknown command type: ${commandName}`);
+        }
+    }
+}

package/dist/server/getClientConfig.d.ts

@@ -1,9 +1,21 @@
 import { ClientConfig } from '../types';
-import { TokenProviderConfig } from '../auth/TokenProvider';
-export type ServerAuthConfig = TokenProviderConfig;
+export interface ServerAuthConfig {
+    apiUrl?: string;
+    clientId?: string;
+    clientSecret?: string;
+}
+export interface ServerClientConfig extends ClientConfig {
+}
 /**
  * Get client configuration with OAuth2 authentication.
  *
+ * 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
@@ -12,5 +24,16 @@ export type ServerAuthConfig = TokenProviderConfig;
  *
  * NEVER call from browser/client code as it exposes credentials.
  * For SPA projects, create your own backend endpoint that calls this.
+ *
+ * @example
+ * // Auto-detect from environment
+ * const config = await getClientConfig()
+ *
+ * // Or override specific values
+ * const config = await getClientConfig({ apiUrl: 'https://custom.api.com' })
+ *
+ * // Use getToken() for automatic caching and refresh
+ * const { token } = await config.getToken()
+ * const connector = new LocationServiceConnector({ apiUrl: config.apiUrl, token })
  */
-export declare function getClientConfig(config: ServerAuthConfig): Promise<ClientConfig>;
+export declare function getClientConfig(config?: ServerAuthConfig): Promise<ServerClientConfig>;

package/dist/server/getClientConfig.js

@@ -1,7 +1,16 @@
+import debug from 'debug';
 import { TokenProvider } from '../auth/TokenProvider';
+const log = debug('location-client:clientConfig');
 /**
  * Get client configuration with OAuth2 authentication.
  *
+ * 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
@@ -10,15 +19,48 @@ import { TokenProvider } from '../auth/TokenProvider';
  *
  * NEVER call from browser/client code as it exposes credentials.
  * For SPA projects, create your own backend endpoint that calls this.
+ *
+ * @example
+ * // Auto-detect from environment
+ * const config = await getClientConfig()
+ *
+ * // Or override specific values
+ * const config = await getClientConfig({ apiUrl: 'https://custom.api.com' })
+ *
+ * // Use getToken() for automatic caching and refresh
+ * const { token } = await config.getToken()
+ * const connector = new LocationServiceConnector({ apiUrl: config.apiUrl, token })
  */
-export async function getClientConfig(config) {
-    const provider = new TokenProvider(config);
+export async function getClientConfig(config = {}) {
+    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 ||
+        process.env.LOCATION_SERVICE_API_URL;
+    const clientId = config.clientId ||
+        process.env.LOCATION_CLIENT_ID ||
+        process.env.LOCATION_SERVICE_CLIENT_ID;
+    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) + '...' });
+    // Validate required values
+    if (!apiUrl || !clientId || !clientSecret) {
+        console.error('[getClientConfig] Missing required configuration');
+        throw new Error('Missing required configuration. Set environment variables: ' +
+            'LOCATION_API_URL, LOCATION_CLIENT_ID, LOCATION_CLIENT_SECRET');
+    }
+    log('[getClientConfig] Creating TokenProvider');
+    const provider = new TokenProvider({ apiUrl, clientId, clientSecret });
+    log('[getClientConfig] Fetching token');
     const result = await provider.getToken();
     if (!result.success || !result.token) {
+        console.error('[getClientConfig] Token fetch failed:', result.error);
         throw new Error(result.error || 'Failed to get token');
     }
+    log('[getClientConfig] Token fetched successfully, length:', result.token.length);
     return {
-        apiUrl: config.apiUrl,
-        token: result.token,
+        apiUrl,
+        token: result.token
     };
 }

package/dist/server/getConnector.d.ts

@@ -0,0 +1,37 @@
+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

@@ -0,0 +1,34 @@
+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);
+}

package/dist/server/index.d.ts

@@ -0,0 +1,4 @@
+export { getClientConfig } from './getClientConfig';
+export type { ServerAuthConfig, ServerClientConfig } from './getClientConfig';
+export { LocationServiceConnector } from './LocationServiceConnector';
+export type { ConnectorConfig, SendOptions } from './LocationServiceConnector';

package/dist/server/index.js

@@ -0,0 +1,2 @@
+export { getClientConfig } from './getClientConfig';
+export { LocationServiceConnector } from './LocationServiceConnector';

package/package.json

@@ -1,9 +1,20 @@
 {
   "name": "@chaosity/location-client",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Client library for Chaosity Location Service with AWS Location Service compatibility",
+  "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "default": "./dist/server/index.js"
+    }
+  },
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",
@@ -30,10 +41,14 @@
   },
   "dependencies": {
     "@aws-sdk/client-geo-places": "^3.0.0",
-    "@aws/amazon-location-utilities-datatypes": "^1.0.0"
+    "@aws/amazon-location-utilities-datatypes": "^1.0.0",
+    "@maplibre/maplibre-gl-geocoder": "^1.9.4",
+    "client-oauth2": "^4.3.3",
+    "debug": "^4.4.3",
+    "jose": "^5.0.0"
   },
   "peerDependencies": {
-    "maplibre-gl": "^4.0.0"
+    "maplibre-gl": "^5.0.0"
   },
   "peerDependenciesMeta": {
     "maplibre-gl": {
@@ -41,6 +56,9 @@
     }
   },
   "devDependencies": {
+    "@types/debug": "^4.1.12",
+    "@types/node": "^25.0.3",
+    "maplibre-gl": "^5.0.0",
     "typescript": "^5.0.0"
   },
   "files": [