@chaosity/location-client 0.1.2 → 0.1.3

package/README.md

@@ -1,23 +1,6 @@
 # @chaosity/location-client
 
-AWS Location Service compatible client with custom authentication.
-
-## Built on AWS Official Libraries
-
-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.)
-
-## Key Difference from AWS SDK
-
-**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
+AWS Location Service compatible client with custom Bearer token authentication.
 
 ## Installation
 
@@ -25,20 +8,26 @@ This client uses:
 npm install @chaosity/location-client
 ```
 
-## Usage
+## Key Features
 
-### Basic Client
+- **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
+
+## 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 +35,185 @@ 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' })
-
-// Or use AWS utilities directly for data conversion
-const featureCollection = placeToFeatureCollection(response)
-```
-
-## Available Commands
-
-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
-
-## Data Type Utilities
-
-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
-
-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.
-
-## ⚠️ Security Notice
-
-**NEVER expose `client_id` and `client_secret` in browser code!**
-
-- `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
-
-## Installation
-
-```bash
-npm install @chaosity/location-client maplibre-gl
-```
-
-## Quick Start
-
-### Recommended: Server Action (Next.js)
-
-```typescript
-// lib/actions/location-auth.ts (Server-side only)
+// app/actions/location.ts
 'use server'
 
-export async function getLocationToken() {
-  const response = await fetch('https://api.locationservice.com/auth/token', {
+export async function getLocationConfig() {
+  const response = await fetch('https://api.example.com/auth/token', {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
     body: JSON.stringify({
-      grant_type: 'client_credentials',
       client_id: process.env.LOCATION_CLIENT_ID!,
-      client_secret: process.env.LOCATION_CLIENT_SECRET!
+      client_secret: process.env.LOCATION_CLIENT_SECRET!,
+      grant_type: 'client_credentials'
     })
   })
   
   const data = await response.json()
-  return { token: data.access_token, apiUrl: 'https://api.locationservice.com' }
+  return {
+    apiUrl: 'https://api.example.com',
+    token: data.access_token
+  }
 }
+```
 
-// components/Map.tsx (Client-side)
-'use client'
-import { GeoPlaces } from '@chaosity/location-client'
-import { getLocationToken } from '@/lib/actions/location-auth'
+### MapLibre Integration
 
-const { token, apiUrl } = await getLocationToken()
-const geoPlaces = new GeoPlaces(apiUrl, token)
+```typescript
+import { GeoPlaces } from '@chaosity/location-client'
+import MaplibreGeocoder from '@maplibre/maplibre-gl-geocoder'
+import maplibregl from 'maplibre-gl'
 
-// Use with MapLibre Geocoder
-const geocoder = new MaplibreGeocoder(geoPlaces, { maplibregl })
-map.addControl(geocoder)
-```
+const map = new maplibregl.Map({ /* ... */ })
+const geoPlaces = new GeoPlaces(apiUrl, token, map)
 
-### Alternative: Using AuthClient (Server-side only)
+// Add geocoder control
+const geocoder = new MaplibreGeocoder(geoPlaces, {
+  maplibregl,
+  showResultsWhileTyping: true,
+  limit: 30
+})
 
-```typescript
-// lib/actions/location-auth.ts (Server-side only)
-'use server'
-import { AuthClient } from '@chaosity/location-client'
+map.addControl(geocoder, 'top-left')
 
-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' }
-}
+// 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)
+  }
+})
 ```
 
 ## API Reference
 
-### AuthHelper
+### GeoPlacesClient
 
-Manages authentication tokens.
+Main client for executing commands.
 
 ```typescript
-const authHelper = new AuthHelper(token: string, apiUrl: string)
-authHelper.setToken(newToken: string)
-authHelper.getToken(): string
-authHelper.getClientConfig(): ClientConfig
+const client = new GeoPlacesClient({
+  apiUrl: string,
+  token: string
+})
+
+await client.send(command)
 ```
 
-### AuthClient
+### GeoPlaces Adapter
+
+MapLibre Geocoder adapter for search and geocoding.
+
+```typescript
+const geoPlaces = new GeoPlaces(apiUrl, token, map)
+
+// Forward geocoding (search)
+await geoPlaces.forwardGeocode({ query: 'Vancouver' })
+
+// Reverse geocoding (coordinates to address)
+await geoPlaces.reverseGeocode({ query: [-123.12, 49.28] })
+
+// Get place details by ID
+await geoPlaces.searchByPlaceId('place-id')
+```
 
-⚠️ **SERVER-SIDE ONLY** - Never use in browser code!
+### Available Commands
 
-Fetches tokens using OAuth2 client credentials flow.
+All AWS Location Service commands from `@aws-sdk/client-geo-places`:
 
 ```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 }
+import {
+  SuggestCommand,
+  GeocodeCommand,
+  ReverseGeocodeCommand,
+  GetPlaceCommand,
+  SearchTextCommand,
+  SearchNearbyCommand
+} from '@chaosity/location-client'
 ```
 
-### GeoPlacesClient
+### Data Type Utilities
 
-Executes commands against the API.
+GeoJSON conversion utilities from `@aws/amazon-location-utilities-datatypes`:
 
 ```typescript
-const client = new GeoPlacesClient(config: ClientConfig)
-await client.send(command: Command)
+import {
+  placeToFeatureCollection,
+  routeToFeatureCollection,
+  devicePositionsToFeatureCollection
+} from '@chaosity/location-client'
 ```
 
-### 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chaosity/location-client",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Client library for Chaosity Location Service with AWS Location Service compatibility",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",