@chaosity/location-client 0.1.3 → 0.1.4

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/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.3",
+  "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": [