@chaosity/location-client 0.1.2 → 0.1.4

package/README.md

@@ -1,23 +1,20 @@
 # @chaosity/location-client
 
-AWS Location Service compatible client with custom authentication.
+AWS Location Service compatible client with custom Bearer token authentication.
 
-## Built on AWS Official Libraries
+## ⚠️ Security Warning
 
-This client uses:
-- [`@aws/amazon-location-client`](https://github.com/aws-geospatial/amazon-location-client-js) - AWS Location Client with all commands
-- [`@aws/amazon-location-utilities-datatypes`](https://github.com/aws-geospatial/amazon-location-utilities-datatypes-js) - Data type conversions (GeoJSON, etc.)
+**This package contains server-side authentication utilities that require client credentials.**
 
-## Key Difference from AWS SDK
+- `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
 
-**Only difference**: Authentication method
-- AWS SDK: Uses AWS SigV4 (IAM credentials)
-- This client: Uses Bearer token (OAuth2)
-
-**Everything else is identical**:
-- Same command classes from AWS Location Client
-- Same request/response types
-- Same data type conversions
+**For React applications**, use [`@chaosity/location-client-react`](https://www.npmjs.com/package/@chaosity/location-client-react) which handles authentication safely.
 
 ## Installation
 
@@ -25,20 +22,26 @@ This client uses:
 npm install @chaosity/location-client
 ```
 
-## Usage
+## Key Features
+
+- **Custom Authentication**: Uses Bearer tokens instead of AWS SigV4
+- **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
 
-### Basic Client
+## Quick Start
+
+### Basic Client Usage
 
 ```typescript
-import { GeoPlacesClient, places } from '@chaosity/location-client'
+import { GeoPlacesClient, SuggestCommand } from '@chaosity/location-client'
 
 const client = new GeoPlacesClient({
   apiUrl: 'https://api.example.com',
   token: 'your-bearer-token'
 })
 
-// Use AWS Location Client commands
-const command = new places.SuggestCommand({
+const command = new SuggestCommand({
   QueryText: 'Vancouver',
   MaxResults: 5
 })
@@ -46,173 +49,212 @@ const command = new places.SuggestCommand({
 const response = await client.send(command)
 ```
 
-### MapLibre Integration
+### Server-Side Authentication (Next.js Server Action)
 
 ```typescript
-import { GeoPlacesClient, GeoPlaces, placeToFeatureCollection } from '@chaosity/location-client'
-import maplibregl from 'maplibre-gl'
-
-const map = new maplibregl.Map({ /* ... */ })
-const client = new GeoPlacesClient({ apiUrl, token })
-const geoPlaces = new GeoPlaces(client, map)
-
-// Use with MapLibre Geocoder
-const results = await geoPlaces.forwardGeocode({ query: 'Vancouver' })
+// app/actions/location.ts
+'use server'
 
-// Or use AWS utilities directly for data conversion
-const featureCollection = placeToFeatureCollection(response)
+export async function getLocationConfig() {
+  const response = await fetch('https://api.example.com/auth/token', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      client_id: process.env.LOCATION_CLIENT_ID!,
+      client_secret: process.env.LOCATION_CLIENT_SECRET!,
+      grant_type: 'client_credentials'
+    })
+  })
+  
+  const data = await response.json()
+  return {
+    apiUrl: 'https://api.example.com',
+    token: data.access_token
+  }
+}
 ```
 
-## Available Commands
+### MapLibre Integration
 
-All commands from AWS Location Client:
-- `places.AutocompleteCommand`
-- `places.GeocodeCommand`
-- `places.GetPlaceCommand`
-- `places.ReverseGeocodeCommand`
-- `places.SearchNearbyCommand`
-- `places.SearchTextCommand`
-- `places.SuggestCommand`
-- `maps.*` - All Maps commands
-- `routes.*` - All Routes commands
+```typescript
+import { GeoPlaces } from '@chaosity/location-client'
+import MaplibreGeocoder from '@maplibre/maplibre-gl-geocoder'
+import maplibregl from 'maplibre-gl'
 
-## Data Type Utilities
+const map = new maplibregl.Map({ /* ... */ })
+const geoPlaces = new GeoPlaces(apiUrl, token, map)
 
-All utilities from `@aws/amazon-location-utilities-datatypes`:
-- `placeToFeatureCollection` - Convert places to GeoJSON
-- `routeToFeatureCollection` - Convert routes to GeoJSON
-- `devicePositionsToFeatureCollection` - Convert device positions to GeoJSON
-- `geofencesToFeatureCollection` - Convert geofences to GeoJSON
-- `featureCollectionToGeofence` - Convert GeoJSON to geofences
+// Add geocoder control
+const geocoder = new MaplibreGeocoder(geoPlaces, {
+  maplibregl,
+  showResultsWhileTyping: true,
+  limit: 30
+})
 
-Refer to [AWS Location Client docs](https://github.com/aws-geospatial/amazon-location-client-js) and [Data Types docs](https://github.com/aws-geospatial/amazon-location-utilities-datatypes-js) for complete documentation.
+map.addControl(geocoder, 'top-left')
 
-## ⚠️ Security Notice
+// 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)
+  }
+})
+```
 
-**NEVER expose `client_id` and `client_secret` in browser code!**
+## API Reference
 
-- `TokenProvider` is for **server-side use only** (Next.js Server Actions, API routes, backend services)
-- Client credentials must be stored in environment variables on the server
-- Browser code should only receive the JWT token from your backend
+### GeoPlacesClient
 
-## Installation
+Main client for executing commands.
 
-```bash
-npm install @chaosity/location-client maplibre-gl
+```typescript
+const client = new GeoPlacesClient({
+  apiUrl: string,
+  token: string
+})
+
+await client.send(command)
 ```
 
-## Quick Start
+### GeoPlaces Adapter
 
-### Recommended: Server Action (Next.js)
+MapLibre Geocoder adapter for search and geocoding.
 
 ```typescript
-// lib/actions/location-auth.ts (Server-side only)
-'use server'
-
-export async function getLocationToken() {
-  const response = await fetch('https://api.locationservice.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 { token: data.access_token, apiUrl: 'https://api.locationservice.com' }
-}
+const geoPlaces = new GeoPlaces(apiUrl, token, map)
 
-// components/Map.tsx (Client-side)
-'use client'
-import { GeoPlaces } from '@chaosity/location-client'
-import { getLocationToken } from '@/lib/actions/location-auth'
+// Forward geocoding (search)
+await geoPlaces.forwardGeocode({ query: 'Vancouver' })
 
-const { token, apiUrl } = await getLocationToken()
-const geoPlaces = new GeoPlaces(apiUrl, token)
+// Reverse geocoding (coordinates to address)
+await geoPlaces.reverseGeocode({ query: [-123.12, 49.28] })
 
-// Use with MapLibre Geocoder
-const geocoder = new MaplibreGeocoder(geoPlaces, { maplibregl })
-map.addControl(geocoder)
+// Get place details by ID
+await geoPlaces.searchByPlaceId('place-id')
 ```
 
-### Alternative: Using AuthClient (Server-side only)
+### Available Commands
 
-```typescript
-// lib/actions/location-auth.ts (Server-side only)
-'use server'
-import { AuthClient } from '@chaosity/location-client'
+All AWS Location Service commands from `@aws-sdk/client-geo-places`:
 
-export async function getLocationToken() {
-  const authClient = new AuthClient()
-  const tokenResponse = await authClient.fetchToken({
-    client_id: process.env.LOCATION_CLIENT_ID!,
-    client_secret: process.env.LOCATION_CLIENT_SECRET!
-  })
-  
-  return { token: tokenResponse.access_token, apiUrl: 'https://api.locationservice.com' }
-}
+```typescript
+import {
+  SuggestCommand,
+  GeocodeCommand,
+  ReverseGeocodeCommand,
+  GetPlaceCommand,
+  SearchTextCommand,
+  SearchNearbyCommand
+} from '@chaosity/location-client'
 ```
 
-## API Reference
-
-### AuthHelper
+### Data Type Utilities
 
-Manages authentication tokens.
+GeoJSON conversion utilities from `@aws/amazon-location-utilities-datatypes`:
 
 ```typescript
-const authHelper = new AuthHelper(token: string, apiUrl: string)
-authHelper.setToken(newToken: string)
-authHelper.getToken(): string
-authHelper.getClientConfig(): ClientConfig
+import {
+  placeToFeatureCollection,
+  routeToFeatureCollection,
+  devicePositionsToFeatureCollection
+} from '@chaosity/location-client'
 ```
 
-### AuthClient
+## Logging
 
-⚠️ **SERVER-SIDE ONLY** - Never use in browser code!
+The library uses the `debug` package for optional verbose logging. Enable it via the `DEBUG` environment variable:
 
-Fetches tokens using OAuth2 client credentials flow.
+```bash
+# Enable all location-client logs
+DEBUG=location-client:* npm run dev
 
-```typescript
-const authClient = new AuthClient(authEndpoint?: string)
-const tokenResponse = await authClient.fetchToken({
-  client_id: string,
-  client_secret: string
-})
-// Returns: { access_token, token_type, expires_in }
-```
+# Enable only authentication logs
+DEBUG=location-client:auth npm run dev
 
-### GeoPlacesClient
+# Enable only API request logs
+DEBUG=location-client:api npm run dev
 
-Executes commands against the API.
+# Enable multiple namespaces
+DEBUG=location-client:*,express:* npm run dev
+```
 
-```typescript
-const client = new GeoPlacesClient(config: ClientConfig)
-await client.send(command: Command)
+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
 ```
 
-### GeoPlaces
+## Security Best Practices
+
+⚠️ **NEVER expose client credentials in browser code!**
+
+- Store `client_id` and `client_secret` in server environment variables
+- Use Server Actions or API routes to fetch tokens
+- Only send the JWT token to the browser
+- Tokens should be short-lived and refreshed as needed
 
-MapLibre Geocoder adapter (browser-safe).
+## Example: Complete MapLibre Setup
 
 ```typescript
-const geoPlaces = new GeoPlaces(apiUrl: string, token: string)
-await geoPlaces.forwardGeocode(config)
-await geoPlaces.reverseGeocode(config)
-await geoPlaces.getSuggestions(config)
-await geoPlaces.searchByPlaceId(placeId)
+'use client'
+
+import { GeoPlaces } from '@chaosity/location-client'
+import { getLocationConfig } from '@/lib/actions/location'
+import maplibregl from 'maplibre-gl'
+import MaplibreGeocoder from '@maplibre/maplibre-gl-geocoder'
+
+export default function MapComponent() {
+  useEffect(() => {
+    async function initMap() {
+      // Get config from server
+      const { apiUrl, token } = await getLocationConfig()
+      
+      // Initialize map
+      const map = new maplibregl.Map({
+        container: 'map',
+        style: `${apiUrl}/maps/Standard/descriptor`,
+        center: [-123.12, 49.28],
+        zoom: 10,
+        transformRequest: (url) => {
+          if (url.startsWith(apiUrl)) {
+            return {
+              url,
+              headers: { 'Authorization': `Bearer ${token}` }
+            }
+          }
+          return { url }
+        }
+      })
+      
+      // Add geocoder
+      const geoPlaces = new GeoPlaces(apiUrl, token, map)
+      const geocoder = new MaplibreGeocoder(geoPlaces, { maplibregl })
+      map.addControl(geocoder, 'top-left')
+    }
+    
+    initMap()
+  }, [])
+  
+  return <div id="map" style={{ width: '100%', height: '600px' }} />
+}
 ```
 
-## Commands
+## TypeScript Support
+
+Full TypeScript support with types from AWS SDK:
 
-### Places Commands
+```typescript
+import type { SuggestCommandOutput } from '@aws-sdk/client-geo-places'
 
-- `SearchTextCommand` - Search for places by text
-- `SuggestCommand` - Get autocomplete suggestions
-- `ReverseGeocodeCommand` - Get place from coordinates
-- `SearchNearbyCommand` - Search nearby places
-- `GetPlaceCommand` - Get place details by ID
+const response: SuggestCommandOutput = await client.send(
+  new SuggestCommand({ QueryText: 'Vancouver' })
+)
+```
 
 ## License
 

package/dist/auth/TokenProvider.d.ts

@@ -10,10 +10,39 @@ 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;
     constructor(config: TokenProviderConfig);
     getToken(forceRefresh?: boolean): Promise<TokenResponse>;
     private isExpired;

package/dist/auth/TokenProvider.js

@@ -1,39 +1,78 @@
+import ClientOAuth2 from 'client-oauth2';
+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()) {
+            log('Using cached token (expires in %ds)', Math.floor((this.expiresAt - Date.now()) / 1000));
             return {
                 success: true,
                 token: this.cachedToken,
                 expiresAt: this.expiresAt
             };
         }
+        const reason = forceRefresh ? 'forced refresh' : (this.cachedToken ? 'token expired' : 'no cached token');
+        log('Refreshing token (%s) from %s', reason, this.config.apiUrl);
         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();
+            const expiresIn = typeof token.data?.expires_in === 'number'
+                ? token.data.expires_in
+                : parseInt(token.data?.expires_in || '3600');
+            this.cachedToken = token.accessToken;
+            this.expiresAt = Date.now() + (expiresIn * 1000);
+            log('Token acquired successfully (expires in %ds)', expiresIn);
             return {
                 success: true,
                 token: this.cachedToken,
-                expiresIn: data.expires_in,
+                expiresIn,
                 expiresAt: this.expiresAt,
             };
         }
         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',

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');
 /**
  * GeoPlacesClient - AWS Location Service compatible client with custom auth
  *
@@ -12,7 +14,10 @@ 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}`;
+        log('Sending %s request to %s', command.constructor.name, endpoint);
+        const startTime = Date.now();
+        const response = await fetch(url, {
             method: 'POST',
             headers: {
                 'Content-Type': 'application/json',
@@ -20,9 +25,12 @@ export class GeoPlacesClient {
             },
             body: JSON.stringify(command)
         });
+        const duration = Date.now() - startTime;
         if (!response.ok) {
+            log('Request failed: %s %s (%dms)', response.status, response.statusText, duration);
             throw new Error(`API request failed: ${response.statusText}`);
         }
+        log('Request successful: %s (%dms)', response.status, duration);
         return response.json();
     }
     getEndpoint(command) {

package/dist/server/getClientConfig.d.ts

@@ -13,4 +13,6 @@ 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.
  */
-export declare function getClientConfig(config: ServerAuthConfig): Promise<ClientConfig>;
+export declare function getClientConfig(config: ServerAuthConfig): Promise<ClientConfig & {
+    expiresAt?: number;
+}>;

package/dist/server/getClientConfig.js

@@ -20,5 +20,6 @@ export async function getClientConfig(config) {
     return {
         apiUrl: config.apiUrl,
         token: result.token,
+        expiresAt: result.expiresAt,
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chaosity/location-client",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Client library for Chaosity Location Service with AWS Location Service compatibility",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -30,7 +30,9 @@
   },
   "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",
+    "client-oauth2": "^4.3.3",
+    "debug": "^4.4.3"
   },
   "peerDependencies": {
     "maplibre-gl": "^4.0.0"
@@ -41,6 +43,7 @@
     }
   },
   "devDependencies": {
+    "@types/debug": "^4.1.12",
     "typescript": "^5.0.0"
   },
   "files": [