@chaosity/location-client 0.5.1 → 0.7.0

package/dist/server/getClientConfig.js

@@ -1,7 +1,7 @@
 import debug from 'debug';
 import { createHash } from 'node:crypto';
-import { TokenProvider } from '../auth/TokenProvider';
-import { LocationServiceException } from '../errors/LocationServiceException';
+import { TokenProvider } from '../auth/TokenProvider.js';
+import { LocationServiceException } from '../errors/LocationServiceException.js';
 const log = debug('location-client:clientConfig');
 // Singleton instance to prevent race conditions
 let tokenProviderInstance = null;
@@ -24,6 +24,92 @@ function getTokenProvider(apiUrl, clientId, clientSecret) {
     currentConfig = configKey;
     return tokenProviderInstance;
 }
+/**
+ * Where the API lives, from the argument or the environment.
+ *
+ * Separate from the credentials because the two are independently overridable:
+ * a caller can hand `LocationServiceConnector` its own `token` and still expect
+ * `LOCATION_API_URL` to say where to send it.
+ */
+export function resolveApiUrl(explicit) {
+    return (explicit ||
+        process.env.LOCATION_API_URL ||
+        process.env.LOCATION_SERVICE_API_URL);
+}
+export function serverTokenSource(config = {}) {
+    log('[serverTokenSource] Starting with config:', {
+        hasApiUrl: !!config.apiUrl,
+        hasClientId: !!config.clientId,
+    });
+    // Auto-detect from environment with fallbacks
+    const apiUrl = resolveApiUrl(config.apiUrl);
+    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('[serverTokenSource] Resolved config:', {
+        apiUrl,
+        clientId: clientId?.substring(0, 10) + '...',
+    });
+    // Validate required values. A LocationServiceException like everything else
+    // this package throws — it used to be a bare `Error`, which was survivable
+    // while only `getClientConfig` could raise it and is not now that the
+    // connector reaches this path too.
+    if (!apiUrl || !clientId || !clientSecret) {
+        console.error('[location-client] Missing required configuration');
+        throw new LocationServiceException({
+            code: 'ValidationException',
+            message: 'Missing required configuration. Set environment variables: ' +
+                'LOCATION_API_URL, LOCATION_CLIENT_ID, LOCATION_CLIENT_SECRET',
+            details: { source: 'client' },
+        });
+    }
+    log('[serverTokenSource] Getting TokenProvider instance');
+    const provider = getTokenProvider(apiUrl, clientId, clientSecret);
+    return {
+        apiUrl,
+        async getToken(forceRefresh = false) {
+            log('[serverTokenSource] Fetching token (forceRefresh=%s)', forceRefresh);
+            let result;
+            try {
+                result = await provider.getToken(forceRefresh);
+            }
+            catch (error) {
+                // The provider now rejects rather than resolving with success:false, and
+                // the rejection is typed — so a store outage (503) can be reported as a
+                // store outage instead of as bad credentials.
+                if (error instanceof LocationServiceException) {
+                    if (error.isAuth) {
+                        throw new LocationServiceException({
+                            code: 'InvalidCredentialsException',
+                            message: `Authentication failed for client ID "${clientId}". ` +
+                                `Verify LOCATION_CLIENT_ID and LOCATION_CLIENT_SECRET match your application in the developer portal.`,
+                            statusCode: error.statusCode,
+                            requestId: error.requestId,
+                            cause: error,
+                        });
+                    }
+                    throw error;
+                }
+                throw error;
+            }
+            // TokenProvider rejects rather than returning a tokenless success, so this
+            // is unreachable in practice — it is here to keep the contract explicit at
+            // the type level rather than asserting non-null.
+            const token = result.token;
+            if (!token) {
+                throw new LocationServiceException({
+                    code: 'InvalidCredentialsException',
+                    message: 'Token provider returned no token',
+                    details: { source: 'client' },
+                });
+            }
+            return { ...result, token };
+        },
+    };
+}
 /**
  * Get client configuration with OAuth2 authentication.
  *
@@ -43,6 +129,21 @@ function getTokenProvider(apiUrl, clientId, clientSecret) {
  * NEVER call from browser/client code as it exposes credentials.
  * For SPA projects, create your own backend endpoint that calls this.
  *
+ * ## The return value is PLAIN DATA, and has to stay that way
+ *
+ * `{ apiUrl, token, expiresAt }` — no methods, no closures. The reason is not
+ * style: the shape every sample uses is a Next.js Server Action that returns
+ * this straight to a Client Component (every `src/lib/actions/location.ts`
+ * under `location-service-samples/web`), and the RSC boundary
+ * serialises it. A function on this object is not serialisable and throws at
+ * the boundary, so "make getClientConfig return getToken" — which #36 proposed
+ * and this JSDoc used to promise two lines below — would break every Next.js
+ * consumer of the library.
+ *
+ * A caller that needs a token which REFRESHES wants one of:
+ * - `LocationServiceConnector`, which holds a live source internally (#36), or
+ * - `TokenProvider` directly, if it is managing its own lifecycle.
+ *
  * @example
  * // Auto-detect from environment
  * const config = await getClientConfig()
@@ -50,74 +151,15 @@ function getTokenProvider(apiUrl, clientId, clientSecret) {
  * // 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 })
+ * // The API rejected the token before its exp — revoked, or secret rotated
+ * const fresh = await getClientConfig({ forceRefresh: true })
  */
 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] Getting TokenProvider instance');
-    const provider = getTokenProvider(apiUrl, clientId, clientSecret);
-    log('[getClientConfig] Fetching token');
-    let result;
-    try {
-        result = await provider.getToken();
-    }
-    catch (error) {
-        // The provider now rejects rather than resolving with success:false, and the
-        // rejection is typed — so a store outage (503) can be reported as a store
-        // outage instead of as bad credentials.
-        if (error instanceof LocationServiceException) {
-            if (error.isAuth) {
-                throw new LocationServiceException({
-                    code: 'InvalidCredentialsException',
-                    message: `Authentication failed for client ID "${clientId}". ` +
-                        `Verify LOCATION_CLIENT_ID and LOCATION_CLIENT_SECRET match your application in the developer portal.`,
-                    statusCode: error.statusCode,
-                    requestId: error.requestId,
-                    cause: error,
-                });
-            }
-            throw error;
-        }
-        throw error;
-    }
-    // TokenProvider rejects rather than returning a tokenless success, so this is
-    // unreachable in practice — it is here to keep the contract explicit at the
-    // type level rather than asserting non-null.
-    if (!result.token) {
-        throw new LocationServiceException({
-            code: 'InvalidCredentialsException',
-            message: 'Token provider returned no token',
-            details: { source: 'client' },
-        });
-    }
+    const source = serverTokenSource(config);
+    const result = await source.getToken(config.forceRefresh);
     log('[getClientConfig] Token fetched successfully, length:', result.token.length);
     return {
-        apiUrl,
+        apiUrl: source.apiUrl,
         token: result.token,
         expiresAt: result.expiresAt,
     };

package/dist/server/index.d.ts

@@ -1,6 +1,6 @@
-export { TokenProvider } from '../auth/TokenProvider';
-export type { TokenProviderConfig, TokenResponse } from '../auth/TokenProvider';
-export { getClientConfig } from './getClientConfig';
-export type { ServerAuthConfig, ServerClientConfig } from './getClientConfig';
-export { LocationServiceConnector } from './LocationServiceConnector';
-export type { ConnectorConfig, SendOptions } from './LocationServiceConnector';
+export { TokenProvider } from '../auth/TokenProvider.js';
+export type { TokenProviderConfig, TokenResponse, } from '../auth/TokenProvider.js';
+export { getClientConfig } from './getClientConfig.js';
+export type { ServerAuthConfig, ServerClientConfig } from './getClientConfig.js';
+export { LocationServiceConnector } from './LocationServiceConnector.js';
+export type { ConnectorConfig, SendOptions, } from './LocationServiceConnector.js';

package/dist/server/index.js

@@ -1,3 +1,3 @@
-export { TokenProvider } from '../auth/TokenProvider';
-export { getClientConfig } from './getClientConfig';
-export { LocationServiceConnector } from './LocationServiceConnector';
+export { TokenProvider } from '../auth/TokenProvider.js';
+export { getClientConfig } from './getClientConfig.js';
+export { LocationServiceConnector } from './LocationServiceConnector.js';

package/dist/transport/endpoints.d.ts

@@ -1,2 +1,2 @@
-import type { GeoPlacesCommand } from '../types';
+import type { GeoPlacesCommand } from '../types/index.js';
 export declare function resolveEndpoint(command: GeoPlacesCommand): string;

package/dist/transport/endpoints.js

@@ -1,5 +1,5 @@
 import { AutocompleteCommand, GeocodeCommand, GetPlaceCommand, ReverseGeocodeCommand, SearchNearbyCommand, SearchTextCommand, SuggestCommand, } from '@aws-sdk/client-geo-places';
-import { LocationServiceException } from '../errors/LocationServiceException';
+import { LocationServiceException } from '../errors/LocationServiceException.js';
 /**
  * Command class -> API path.
  *

package/dist/transport/errors.d.ts

@@ -1,4 +1,4 @@
-import { LocationServiceException } from '../errors/LocationServiceException';
+import { LocationServiceException } from '../errors/LocationServiceException.js';
 /**
  * Turn a non-2xx response into a LocationServiceException.
  *
@@ -12,6 +12,19 @@ import { LocationServiceException } from '../errors/LocationServiceException';
  *   { message: "Unauthorized" }          API Gateway's own responses
  */
 export declare function parseErrorResponse(status: number, statusText: string, body: string, headers?: Headers): LocationServiceException;
+/**
+ * The API has rejected this token: a 401, and only a 401.
+ *
+ * The authorizer throws `Unauthorized` for a token it cannot verify or that has
+ * expired, and API Gateway turns that into a 401. Its other refusals — no
+ * domain configured for the application, an Origin the application does not
+ * allow — are a Deny policy or a service 403, and a fresh token changes
+ * neither. Retrying those would send, and bill, the same doomed request twice.
+ *
+ * Shared by both send paths so the browser client and the server connector
+ * cannot come to different conclusions about the same response.
+ */
+export declare function isTokenRejected(err: unknown): boolean;
 /**
  * `Retry-After` is either delta-seconds or an HTTP date. Both are legal and the
  * API sends the first; a date is handled so a proxy or gateway cannot surprise us.

package/dist/transport/errors.js

@@ -1,4 +1,4 @@
-import { LocationServiceException } from '../errors/LocationServiceException';
+import { LocationServiceException } from '../errors/LocationServiceException.js';
 /**
  * Turn a non-2xx response into a LocationServiceException.
  *
@@ -83,6 +83,21 @@ function statusCode(status) {
             return status >= 500 ? 'InternalException' : 'ServiceException';
     }
 }
+/**
+ * The API has rejected this token: a 401, and only a 401.
+ *
+ * The authorizer throws `Unauthorized` for a token it cannot verify or that has
+ * expired, and API Gateway turns that into a 401. Its other refusals — no
+ * domain configured for the application, an Origin the application does not
+ * allow — are a Deny policy or a service 403, and a fresh token changes
+ * neither. Retrying those would send, and bill, the same doomed request twice.
+ *
+ * Shared by both send paths so the browser client and the server connector
+ * cannot come to different conclusions about the same response.
+ */
+export function isTokenRejected(err) {
+    return err instanceof LocationServiceException && err.statusCode === 401;
+}
 /**
  * `Retry-After` is either delta-seconds or an HTTP date. Both are legal and the
  * API sends the first; a date is handled so a proxy or gateway cannot surprise us.

package/dist/transport/http.js

@@ -1,6 +1,6 @@
 import debug from 'debug';
-import { LocationServiceException } from '../errors/LocationServiceException';
-import { parseErrorResponse, parseRetryAfter } from './errors';
+import { LocationServiceException } from '../errors/LocationServiceException.js';
+import { parseErrorResponse, parseRetryAfter } from './errors.js';
 const log = debug('location-client:transport');
 /** Per-attempt timeout. Sits well under the API's own 25 s Lambda ceiling. */
 export const DEFAULT_TIMEOUT_MS = 10000;

package/dist/types/index.d.ts

@@ -4,6 +4,25 @@ export interface ClientConfig {
     /** Optional callback to get the current token dynamically. When provided,
      *  called on every request so token updates are reflected without recreating the client. */
     getToken?: () => string | undefined;
+    /**
+     * Asked for a replacement AFTER the API has rejected the current token with a
+     * 401, so the request can be retried once instead of failing.
+     *
+     * Separate from `getToken` because that one is synchronous by contract — it
+     * is read while a request is being built and cannot await anything, so it can
+     * only ever return the token already in hand. Nothing in this library could
+     * therefore recover from a token revoked, or a secret rotated, before its
+     * `exp`: every request failed until the refresh buffer elapsed on its own
+     * (#36).
+     *
+     * Returning `undefined` is not "no replacement": the client then re-reads
+     * `getToken`, because a provider refreshing in the background may have landed
+     * a new token while the failed request was in flight. What actually decides
+     * is the token that comes out of those two — if it is the one just rejected,
+     * or there is none, the retry is skipped rather than repeating a request that
+     * is going to fail again.
+     */
+    refreshToken?: () => Promise<string | undefined>;
 }
 /**
  * Minimal interface for AWS SDK command objects.

package/package.json

@@ -1,30 +1,43 @@
 {
   "name": "@chaosity/location-client",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "description": "Client library for Chaosity Location Service with AWS Location Service compatibility",
   "type": "module",
-  "main": "dist/index.js",
+  "main": "dist/cjs/index.js",
   "types": "dist/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
     },
     "./server": {
-      "types": "./dist/server/index.d.ts",
-      "default": "./dist/server/index.js"
+      "import": {
+        "types": "./dist/server/index.d.ts",
+        "default": "./dist/server/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/server/index.d.ts",
+        "default": "./dist/cjs/server/index.js"
+      }
     }
   },
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && tsc -p tsconfig.cjs.json && node scripts/finish-cjs.mjs",
     "dev": "tsc --watch",
     "lint": "eslint . && prettier --check .",
     "lint:fix": "eslint --fix . && prettier --write .",
     "format": "prettier --write .",
     "test": "vitest run",
     "test:watch": "vitest",
-    "prepublishOnly": "npm run build",
-    "prepare": "husky"
+    "prepublishOnly": "npm run build && npm run smoke",
+    "prepare": "husky",
+    "smoke": "node scripts/smoke.mjs"
   },
   "keywords": [
     "aws",
@@ -47,19 +60,23 @@
   "dependencies": {
     "@aws-sdk/client-geo-places": "^3.0.0",
     "@aws/amazon-location-utilities-datatypes": "^1.0.0",
-    "@maplibre/maplibre-gl-geocoder": "^1.9.4",
     "debug": "^4.4.3"
   },
   "peerDependencies": {
+    "@maplibre/maplibre-gl-geocoder": "^1.9.4",
     "maplibre-gl": "^5.0.0"
   },
   "peerDependenciesMeta": {
+    "@maplibre/maplibre-gl-geocoder": {
+      "optional": true
+    },
     "maplibre-gl": {
       "optional": true
     }
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
+    "@maplibre/maplibre-gl-geocoder": "^1.9.4",
     "@types/debug": "^4.1.12",
     "@types/node": "^25.0.3",
     "@vitest/coverage-v8": "^3.0.0",
@@ -79,5 +96,10 @@
     "dist",
     "README.md",
     "LICENSE"
-  ]
+  ],
+  "module": "dist/index.js",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  }
 }