@chaosity/location-client 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Chaosity
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,219 @@
+# @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
+
+## Installation
+
+```bash
+npm install @chaosity/location-client
+```
+
+## Usage
+
+### Basic Client
+
+```typescript
+import { GeoPlacesClient, places } 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({
+  QueryText: 'Vancouver',
+  MaxResults: 5
+})
+
+const response = await client.send(command)
+```
+
+### MapLibre Integration
+
+```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)
+'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' }
+}
+
+// components/Map.tsx (Client-side)
+'use client'
+import { GeoPlaces } from '@chaosity/location-client'
+import { getLocationToken } from '@/lib/actions/location-auth'
+
+const { token, apiUrl } = await getLocationToken()
+const geoPlaces = new GeoPlaces(apiUrl, token)
+
+// Use with MapLibre Geocoder
+const geocoder = new MaplibreGeocoder(geoPlaces, { maplibregl })
+map.addControl(geocoder)
+```
+
+### Alternative: Using AuthClient (Server-side only)
+
+```typescript
+// lib/actions/location-auth.ts (Server-side only)
+'use server'
+import { AuthClient } from '@chaosity/location-client'
+
+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' }
+}
+```
+
+## API Reference
+
+### AuthHelper
+
+Manages authentication tokens.
+
+```typescript
+const authHelper = new AuthHelper(token: string, apiUrl: string)
+authHelper.setToken(newToken: string)
+authHelper.getToken(): string
+authHelper.getClientConfig(): ClientConfig
+```
+
+### AuthClient
+
+⚠️ **SERVER-SIDE ONLY** - Never use in browser code!
+
+Fetches tokens using OAuth2 client credentials flow.
+
+```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 }
+```
+
+### GeoPlacesClient
+
+Executes commands against the API.
+
+```typescript
+const client = new GeoPlacesClient(config: ClientConfig)
+await client.send(command: Command)
+```
+
+### GeoPlaces
+
+MapLibre Geocoder adapter (browser-safe).
+
+```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)
+```
+
+## Commands
+
+### Places Commands
+
+- `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
+
+## License
+
+MIT

package/dist/adapters/GeoPlaces.d.ts

@@ -0,0 +1,27 @@
+import type { FeatureCollection } from 'geojson';
+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).
+ */
+export declare class GeoPlaces {
+    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>;
+}

package/dist/adapters/GeoPlaces.js

@@ -0,0 +1,58 @@
+import { placeToFeatureCollection } from '@aws/amazon-location-utilities-datatypes';
+import { GetPlaceCommand, ReverseGeocodeCommand, SearchNearbyCommand, SuggestCommand } from '@aws-sdk/client-geo-places';
+/**
+ * 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).
+ */
+export class GeoPlaces {
+    constructor(client, map) {
+        this.client = client;
+        this.map = map;
+    }
+    async forwardGeocode(config) {
+        const center = this.map.getCenter();
+        const command = new SuggestCommand({
+            QueryText: config.query,
+            BiasPosition: [center.lng, center.lat],
+            MaxResults: config.limit || 5,
+            Language: 'en'
+        });
+        const response = await this.client.send(command);
+        return placeToFeatureCollection(response, { flattenProperties: true });
+    }
+    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'
+            });
+        const response = await this.client.send(command);
+        return placeToFeatureCollection(response, { flattenProperties: true });
+    }
+    async getSuggestions(config) {
+        const center = this.map.getCenter();
+        const command = new SuggestCommand({
+            QueryText: config.query,
+            BiasPosition: [center.lng, center.lat],
+            Language: 'en'
+        });
+        const response = await this.client.send(command);
+        return placeToFeatureCollection(response, { flattenProperties: true });
+    }
+    async searchByPlaceId(placeId) {
+        const command = new GetPlaceCommand({
+            PlaceId: placeId,
+            Language: 'en'
+        });
+        const response = await this.client.send(command);
+        return placeToFeatureCollection(response, { flattenProperties: true });
+    }
+}

package/dist/auth/AuthClient.d.ts

@@ -0,0 +1,6 @@
+import { OAuth2Credentials, TokenResponse } from '../types';
+export declare class AuthClient {
+    private authEndpoint;
+    constructor(authEndpoint?: string);
+    fetchToken(credentials: OAuth2Credentials): Promise<TokenResponse>;
+}

package/dist/auth/AuthClient.js

@@ -0,0 +1,23 @@
+export class AuthClient {
+    constructor(authEndpoint = 'https://api.locationservice.com/auth') {
+        this.authEndpoint = authEndpoint;
+    }
+    async fetchToken(credentials) {
+        const response = await fetch(`${this.authEndpoint}/token`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json'
+            },
+            body: JSON.stringify({
+                grant_type: 'client_credentials',
+                client_id: credentials.client_id,
+                client_secret: credentials.client_secret
+            })
+        });
+        if (!response.ok) {
+            const error = await response.json();
+            throw new Error(error.error_description || 'Failed to fetch token');
+        }
+        return await response.json();
+    }
+}

package/dist/auth/AuthHelper.d.ts

@@ -0,0 +1,9 @@
+import { ClientConfig } from '../types';
+export declare class AuthHelper {
+    private token;
+    private apiUrl;
+    constructor(token: string, apiUrl: string);
+    setToken(token: string): void;
+    getToken(): string;
+    getClientConfig(): ClientConfig;
+}

package/dist/auth/AuthHelper.js

@@ -0,0 +1,18 @@
+export class AuthHelper {
+    constructor(token, apiUrl) {
+        this.token = token;
+        this.apiUrl = apiUrl;
+    }
+    setToken(token) {
+        this.token = token;
+    }
+    getToken() {
+        return this.token;
+    }
+    getClientConfig() {
+        return {
+            apiUrl: this.apiUrl,
+            token: this.token
+        };
+    }
+}

package/dist/auth/TokenProvider.d.ts

@@ -0,0 +1,21 @@
+export interface TokenResponse {
+    success: boolean;
+    token?: string;
+    expiresIn?: number;
+    expiresAt?: number;
+    error?: string;
+}
+export interface TokenProviderConfig {
+    apiUrl: string;
+    clientId: string;
+    clientSecret: string;
+}
+export declare class TokenProvider {
+    private config;
+    private cachedToken?;
+    private expiresAt?;
+    constructor(config: TokenProviderConfig);
+    getToken(forceRefresh?: boolean): Promise<TokenResponse>;
+    private isExpired;
+    clearCache(): void;
+}

package/dist/auth/TokenProvider.js

@@ -0,0 +1,52 @@
+export class TokenProvider {
+    constructor(config) {
+        this.config = config;
+    }
+    async getToken(forceRefresh = false) {
+        if (!forceRefresh && this.cachedToken && this.expiresAt && !this.isExpired()) {
+            return {
+                success: true,
+                token: this.cachedToken,
+                expiresAt: this.expiresAt
+            };
+        }
+        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);
+            return {
+                success: true,
+                token: this.cachedToken,
+                expiresIn: data.expires_in,
+                expiresAt: this.expiresAt,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: error instanceof Error ? error.message : 'Failed to get token',
+            };
+        }
+    }
+    isExpired(bufferSeconds = 60) {
+        if (!this.expiresAt)
+            return true;
+        return Date.now() >= (this.expiresAt - bufferSeconds * 1000);
+    }
+    clearCache() {
+        this.cachedToken = undefined;
+        this.expiresAt = undefined;
+    }
+}

package/dist/client/GeoPlacesClient.d.ts

@@ -0,0 +1,16 @@
+import { ClientConfig } from '../types';
+/**
+ * GeoPlacesClient - AWS Location Service compatible client with custom auth
+ *
+ * Uses AWS Location Client command classes but replaces SigV4 auth with Bearer token.
+ * All request/response types are identical to AWS Location Service.
+ */
+export declare class GeoPlacesClient {
+    private clientConfig;
+    readonly config: {
+        serviceId: string;
+    };
+    constructor(config: ClientConfig);
+    send<TInput, TOutput>(command: TInput): Promise<TOutput>;
+    private getEndpoint;
+}

package/dist/client/GeoPlacesClient.js

@@ -0,0 +1,52 @@
+import { AutocompleteCommand, GeocodeCommand, GetPlaceCommand, ReverseGeocodeCommand, SearchNearbyCommand, SearchTextCommand, SuggestCommand, } from '@aws-sdk/client-geo-places';
+/**
+ * GeoPlacesClient - AWS Location Service compatible client with custom auth
+ *
+ * Uses AWS Location Client command classes but replaces SigV4 auth with Bearer token.
+ * All request/response types are identical to AWS Location Service.
+ */
+export class GeoPlacesClient {
+    constructor(config) {
+        this.clientConfig = config;
+        this.config = { serviceId: 'Geo Places' };
+    }
+    async send(command) {
+        const endpoint = this.getEndpoint(command);
+        const response = await fetch(`${this.clientConfig.apiUrl}${endpoint}`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${this.clientConfig.token}`
+            },
+            body: JSON.stringify(command)
+        });
+        if (!response.ok) {
+            throw new Error(`API request failed: ${response.statusText}`);
+        }
+        return response.json();
+    }
+    getEndpoint(command) {
+        if (command instanceof AutocompleteCommand) {
+            return '/address/autocomplete';
+        }
+        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

@@ -0,0 +1,9 @@
+export { TokenProvider } from './auth/TokenProvider';
+export type { TokenResponse, TokenProviderConfig } from './auth/TokenProvider';
+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 type { ClientConfig } from './types';
+export { getClientConfig } from './server/getClientConfig';
+export type { ServerAuthConfig } from './server/getClientConfig';

package/dist/index.js

@@ -0,0 +1,12 @@
+// Auth (Custom - only difference from AWS SDK)
+export { TokenProvider } from './auth/TokenProvider';
+// Client (Custom - uses our auth instead of AWS SigV4)
+export { GeoPlacesClient } from './client/GeoPlacesClient';
+// Re-export AWS SDK commands and types
+export * from '@aws-sdk/client-geo-places';
+// Re-export AWS Location Utilities (data type conversions)
+export * from '@aws/amazon-location-utilities-datatypes';
+// Adapters (Custom - for MapLibre integration)
+export { GeoPlaces } from './adapters/GeoPlaces';
+// Server-only utilities
+export { getClientConfig } from './server/getClientConfig';

package/dist/server/getClientConfig.d.ts

@@ -0,0 +1,16 @@
+import { ClientConfig } from '../types';
+import { TokenProviderConfig } from '../auth/TokenProvider';
+export type ServerAuthConfig = TokenProviderConfig;
+/**
+ * Get client configuration with OAuth2 authentication.
+ *
+ * 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.
+ * For SPA projects, create your own backend endpoint that calls this.
+ */
+export declare function getClientConfig(config: ServerAuthConfig): Promise<ClientConfig>;

package/dist/server/getClientConfig.js

@@ -0,0 +1,24 @@
+import { TokenProvider } from '../auth/TokenProvider';
+/**
+ * Get client configuration with OAuth2 authentication.
+ *
+ * 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.
+ * For SPA projects, create your own backend endpoint that calls this.
+ */
+export async function getClientConfig(config) {
+    const provider = new TokenProvider(config);
+    const result = await provider.getToken();
+    if (!result.success || !result.token) {
+        throw new Error(result.error || 'Failed to get token');
+    }
+    return {
+        apiUrl: config.apiUrl,
+        token: result.token,
+    };
+}

package/dist/types/index.d.ts

@@ -0,0 +1,4 @@
+export interface ClientConfig {
+    apiUrl: string;
+    token: string;
+}

package/dist/types/index.js

@@ -0,0 +1,2 @@
+// Custom types not provided by AWS SDK
+export {};

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@chaosity/location-client",
+  "version": "0.1.0",
+  "description": "Client library for Chaosity Location Service with AWS Location Service compatibility",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "jest",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "aws",
+    "location",
+    "maps",
+    "geocoding",
+    "maplibre",
+    "places"
+  ],
+  "author": "Chaosity",
+  "license": "MIT",
+  "dependencies": {
+    "@aws-sdk/client-geo-places": "^3.0.0",
+    "@aws/amazon-location-utilities-datatypes": "^1.0.0"
+  },
+  "peerDependencies": {
+    "maplibre-gl": "^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "maplibre-gl": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ]
+}