@chaosity/location-client 0.1.14 → 0.2.1

package/README.md

@@ -73,14 +73,18 @@ const config = await getClientConfig({
 ### Client-Side: Using the GeoPlacesClient
 
 ```typescript
-import { GeoPlacesClient, SuggestCommand } from '@chaosity/location-client'
+import {
+  GeoPlacesClient,
+  SuggestCommand,
+  type SuggestCommandOutput,
+} from '@chaosity/location-client'
 
 const client = new GeoPlacesClient({
   apiUrl: 'https://api.chaosity.cloud',
   token: 'your-bearer-token',
 })
 
-const response = await client.send(
+const response: SuggestCommandOutput = await client.send(
   new SuggestCommand({ QueryText: 'Vancouver', MaxResults: 5 }),
 )
 ```
@@ -396,7 +400,7 @@ DEBUG=location-client:api npm run dev
 Full TypeScript support with types from AWS SDK:
 
 ```typescript
-import type { SuggestCommandOutput } from '@aws-sdk/client-geo-places'
+import type { SuggestCommandOutput } from '@chaosity/location-client'
 
 const response: SuggestCommandOutput = await client.send(
   new SuggestCommand({ QueryText: 'Vancouver' }),

package/dist/auth/TokenProvider.d.ts

@@ -44,6 +44,20 @@ export declare class TokenProvider {
     private tokenPromise?;
     constructor(config: TokenProviderConfig);
     getToken(forceRefresh?: boolean): Promise<TokenResponse>;
+    /**
+     * Fetch a token, distinguishing transient failure from terminal (#9).
+     *
+     * This used to collapse every non-200 into `new Error(message)`: no status,
+     * no OAuth `error`, no `Retry-After`. So `503 temporarily_unavailable` — which
+     * the API returns when its config store is unreachable — was indistinguishable
+     * from `401 unauthorized`, and a customer whose credentials were perfectly
+     * good was told to go and check them.
+     *
+     * The shared transport now does the classifying: it retries 503/429/network
+     * honouring `Retry-After`, never retries 401/400, and throws a typed
+     * LocationServiceException either way. A failure REJECTS rather than resolving
+     * with `success: false`, so a stale token can never be used by accident.
+     */
     private fetchToken;
     private isExpired;
     clearCache(): void;

package/dist/auth/TokenProvider.js

@@ -1,4 +1,7 @@
 import debug from 'debug';
+import { LocationServiceException } from '../errors/LocationServiceException';
+import { requestJson } from '../transport/http';
+import { TOKEN_REFRESH_BUFFER_SECONDS, readTokenExpiry } from './tokenRefresh';
 const log = debug('location-client:auth');
 /**
  * TokenProvider - SERVER-SIDE ONLY
@@ -73,57 +76,56 @@ export class TokenProvider {
             this.tokenPromise = undefined;
         }
     }
+    /**
+     * Fetch a token, distinguishing transient failure from terminal (#9).
+     *
+     * This used to collapse every non-200 into `new Error(message)`: no status,
+     * no OAuth `error`, no `Retry-After`. So `503 temporarily_unavailable` — which
+     * the API returns when its config store is unreachable — was indistinguishable
+     * from `401 unauthorized`, and a customer whose credentials were perfectly
+     * good was told to go and check them.
+     *
+     * The shared transport now does the classifying: it retries 503/429/network
+     * honouring `Retry-After`, never retries 401/400, and throws a typed
+     * LocationServiceException either way. A failure REJECTS rather than resolving
+     * with `success: false`, so a stale token can never be used by accident.
+     */
     async fetchToken() {
-        try {
-            const { clientId, clientSecret, apiUrl } = this.config;
-            const credentials = btoa(`${clientId}:${clientSecret}`);
-            const response = await fetch(`${apiUrl}/auth/token`, {
-                method: 'POST',
-                headers: {
-                    Authorization: `Basic ${credentials}`,
-                    'Content-Type': 'application/x-www-form-urlencoded',
-                },
-                body: new URLSearchParams({
-                    grant_type: 'client_credentials',
-                }).toString(),
+        const { clientId, clientSecret, apiUrl } = this.config;
+        const credentials = btoa(`${clientId}:${clientSecret}`);
+        const data = await requestJson(`${apiUrl}/auth/token`, {
+            method: 'POST',
+            headers: {
+                Authorization: `Basic ${credentials}`,
+                'Content-Type': 'application/x-www-form-urlencoded',
+            },
+            body: new URLSearchParams({
+                grant_type: 'client_credentials',
+            }).toString(),
+        }, { retry: { maxAttempts: 3 } });
+        if (!data.access_token) {
+            throw new LocationServiceException({
+                code: 'InvalidCredentialsException',
+                message: 'Token endpoint returned no access_token',
+                details: { source: 'client' },
             });
-            if (!response.ok) {
-                const errorText = await response.text();
-                let errorMessage = `Token request failed: ${response.statusText}`;
-                try {
-                    const errorData = JSON.parse(errorText);
-                    if (errorData.error_description)
-                        errorMessage = errorData.error_description;
-                    else if (errorData.error)
-                        errorMessage = errorData.error;
-                }
-                catch {
-                    /* use statusText */
-                }
-                throw new Error(errorMessage);
-            }
-            const data = await response.json();
-            this.cachedToken = data.access_token;
-            // Prefer absolute expires_at (ms) from response, fall back to expires_in (seconds)
-            this.cachedExpiresAt =
-                data.expires_at ?? Date.now() + (data.expires_in ?? 900) * 1000;
-            const expiresInSec = Math.floor((this.cachedExpiresAt - Date.now()) / 1000);
-            log('Token acquired successfully (expires in %ds)', expiresInSec);
-            return {
-                success: true,
-                token: this.cachedToken,
-                expiresAt: this.cachedExpiresAt,
-            };
-        }
-        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',
-            };
         }
+        this.cachedToken = data.access_token;
+        // The token's own `exp` claim first — it is the only value that cannot
+        // disagree with what the API will actually accept. `expires_at` and
+        // `expires_in` are what the response CLAIMS, and are kept as fallbacks.
+        this.cachedExpiresAt =
+            readTokenExpiry(data.access_token) ??
+                data.expires_at ??
+                Date.now() + (data.expires_in ?? 900) * 1000;
+        log('Token acquired successfully (expires in %ds)', Math.floor((this.cachedExpiresAt - Date.now()) / 1000));
+        return {
+            success: true,
+            token: this.cachedToken,
+            expiresAt: this.cachedExpiresAt,
+        };
     }
-    isExpired(bufferSeconds = 60) {
+    isExpired(bufferSeconds = TOKEN_REFRESH_BUFFER_SECONDS) {
         if (!this.cachedExpiresAt)
             return true;
         return Date.now() >= this.cachedExpiresAt - bufferSeconds * 1000;

package/dist/auth/tokenRefresh.d.ts

@@ -0,0 +1,37 @@
+/**
+ * How long before expiry a token is treated as needing replacement.
+ *
+ * ONE number, used by both sides: the server-side `TokenProvider` deciding
+ * whether its cached token is still good, and the React provider deciding
+ * whether to ask for a new one. Both apply it to the same `exp` claim, so they
+ * cannot reach different answers about the same token.
+ *
+ * It used to be two separate `60`s — a private literal in `isExpired()` and a
+ * public `refreshBuffer` prop default — with nothing tying them together. On
+ * 2026-08-23 a consumer passed `refreshBuffer={800}` against a 900 s token: the
+ * client judged it stale after 100 s, the server still considered it fresh for
+ * another 840 s and returned the same one, and the client asked again
+ * immediately — roughly 110 requests per second from an idle page.
+ *
+ * Not configurable per consumer, deliberately. A settable client-side buffer is
+ * precisely what allowed that disagreement, and no amount of capping or backing
+ * off fixes it as cleanly as the two sides simply sharing the number.
+ */
+export declare const TOKEN_REFRESH_BUFFER_SECONDS = 60;
+/**
+ * Read the `exp` claim out of a JWT, in milliseconds.
+ *
+ * The expiry is IN THE TOKEN, so neither side needs to be told it. Both used to
+ * take it on trust from elsewhere — the server from the response body's
+ * `expires_at`, the React provider from whatever `getConfig` returned, falling
+ * back to inventing `Date.now() + 900_000` when that was absent. An invented
+ * expiry is how the two ended up disagreeing about the same token.
+ *
+ * Deliberately NOT verified. This is only used to decide *when to refresh*;
+ * nothing is authorised on the strength of it, and the API verifies the
+ * signature on every request regardless. Trusting `exp` for scheduling is safe
+ * in a way that trusting it for access would not be.
+ *
+ * Returns undefined for anything unparseable, so callers keep their fallback.
+ */
+export declare function readTokenExpiry(token: string | undefined): number | undefined;

package/dist/auth/tokenRefresh.js

@@ -0,0 +1,54 @@
+/**
+ * How long before expiry a token is treated as needing replacement.
+ *
+ * ONE number, used by both sides: the server-side `TokenProvider` deciding
+ * whether its cached token is still good, and the React provider deciding
+ * whether to ask for a new one. Both apply it to the same `exp` claim, so they
+ * cannot reach different answers about the same token.
+ *
+ * It used to be two separate `60`s — a private literal in `isExpired()` and a
+ * public `refreshBuffer` prop default — with nothing tying them together. On
+ * 2026-08-23 a consumer passed `refreshBuffer={800}` against a 900 s token: the
+ * client judged it stale after 100 s, the server still considered it fresh for
+ * another 840 s and returned the same one, and the client asked again
+ * immediately — roughly 110 requests per second from an idle page.
+ *
+ * Not configurable per consumer, deliberately. A settable client-side buffer is
+ * precisely what allowed that disagreement, and no amount of capping or backing
+ * off fixes it as cleanly as the two sides simply sharing the number.
+ */
+export const TOKEN_REFRESH_BUFFER_SECONDS = 60;
+/**
+ * Read the `exp` claim out of a JWT, in milliseconds.
+ *
+ * The expiry is IN THE TOKEN, so neither side needs to be told it. Both used to
+ * take it on trust from elsewhere — the server from the response body's
+ * `expires_at`, the React provider from whatever `getConfig` returned, falling
+ * back to inventing `Date.now() + 900_000` when that was absent. An invented
+ * expiry is how the two ended up disagreeing about the same token.
+ *
+ * Deliberately NOT verified. This is only used to decide *when to refresh*;
+ * nothing is authorised on the strength of it, and the API verifies the
+ * signature on every request regardless. Trusting `exp` for scheduling is safe
+ * in a way that trusting it for access would not be.
+ *
+ * Returns undefined for anything unparseable, so callers keep their fallback.
+ */
+export function readTokenExpiry(token) {
+    if (!token)
+        return undefined;
+    const payload = token.split('.')[1];
+    if (!payload)
+        return undefined;
+    try {
+        const base64 = payload.replace(/-/g, '+').replace(/_/g, '/');
+        const json = typeof atob === 'function'
+            ? atob(base64)
+            : Buffer.from(base64, 'base64').toString('utf8');
+        const exp = JSON.parse(json)?.exp;
+        return typeof exp === 'number' ? exp * 1000 : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/client/GeoPlacesClient.d.ts

@@ -1,11 +1,13 @@
+import type { RequestOptions } from '../transport/http';
 import type { ClientConfig } from '../types';
+export type SendOptions = RequestOptions;
 /**
- * GeoPlacesClient - AWS Location Service compatible client with custom auth
+ * GeoPlacesClient — AWS Location Service compatible client with custom auth.
  *
- * Uses AWS SDK command classes but replaces SigV4 auth with Bearer token.
- * All request/response types are identical to AWS Location Service.
+ * Uses AWS SDK command classes but replaces SigV4 with a Bearer token. All
+ * request and response types are identical to AWS Location Service.
  *
- * Pass `getToken` in config to support live token refresh without recreating the client.
+ * Pass `getToken` in config for live refresh without recreating the client.
  */
 export declare class GeoPlacesClient {
     private clientConfig;
@@ -13,6 +15,9 @@ export declare class GeoPlacesClient {
         serviceId: string;
     };
     constructor(config: ClientConfig);
-    send<TInput, TOutput>(command: TInput): Promise<TOutput>;
-    private getEndpoint;
+    /**
+     * @param options `signal` to cancel, `timeoutMs` per attempt, `retry: false`
+     *   to disable the retry loop. Every failure throws LocationServiceException.
+     */
+    send<TInput, TOutput>(command: TInput, options?: SendOptions): Promise<TOutput>;
 }

package/dist/client/GeoPlacesClient.js

@@ -1,86 +1,39 @@
-import { AutocompleteCommand, GeocodeCommand, GetPlaceCommand, ReverseGeocodeCommand, SearchNearbyCommand, SearchTextCommand, SuggestCommand, } from '@aws-sdk/client-geo-places';
 import debug from 'debug';
-import { LocationServiceException } from '../errors/LocationServiceException';
+import { resolveEndpoint } from '../transport/endpoints';
+import { requestJson } from '../transport/http';
 import { roundPositionFields } from '../utils/roundPosition';
 const log = debug('location-client:api');
-const logError = debug('location-client:api:error');
-// Minification-safe endpoint map — uses constructor identity, not class name strings
-const ENDPOINT_MAP = new Map([
-    [AutocompleteCommand, '/address/autocomplete'],
-    [GeocodeCommand, '/address/geocode'],
-    [GetPlaceCommand, '/address/place'],
-    [ReverseGeocodeCommand, '/address/search/reverse-geocode'],
-    [SearchNearbyCommand, '/address/search/nearby'],
-    [SearchTextCommand, '/address/search/text'],
-    [SuggestCommand, '/address/suggestion'],
-]);
 /**
- * GeoPlacesClient - AWS Location Service compatible client with custom auth
+ * GeoPlacesClient — AWS Location Service compatible client with custom auth.
  *
- * Uses AWS SDK command classes but replaces SigV4 auth with Bearer token.
- * All request/response types are identical to AWS Location Service.
+ * Uses AWS SDK command classes but replaces SigV4 with a Bearer token. All
+ * request and response types are identical to AWS Location Service.
  *
- * Pass `getToken` in config to support live token refresh without recreating the client.
+ * Pass `getToken` in config for live refresh without recreating the client.
  */
 export class GeoPlacesClient {
     constructor(config) {
         this.clientConfig = config;
         this.config = { serviceId: 'Geo Places' };
     }
-    async send(command) {
+    /**
+     * @param options `signal` to cancel, `timeoutMs` per attempt, `retry: false`
+     *   to disable the retry loop. Every failure throws LocationServiceException.
+     */
+    async send(command, options) {
         const cmd = command;
-        const endpoint = this.getEndpoint(cmd);
-        const url = `${this.clientConfig.apiUrl}${endpoint}`;
-        const commandName = cmd.constructor.name;
+        const endpoint = resolveEndpoint(cmd);
         const input = roundPositionFields(cmd.input);
-        // Prefer getToken callback (live ref) over static token string
+        // Prefer the getToken callback (live ref) over a static token string.
         const token = this.clientConfig.getToken?.() ?? this.clientConfig.token;
-        log('Sending %s to %s', commandName, endpoint);
-        const startTime = Date.now();
-        const response = await fetch(url, {
+        log('Sending %s to %s', cmd.constructor?.name, endpoint);
+        return requestJson(`${this.clientConfig.apiUrl}${endpoint}`, {
             method: 'POST',
             headers: {
                 'Content-Type': 'application/json',
                 Authorization: `Bearer ${token}`,
             },
             body: JSON.stringify(input),
-        });
-        const duration = Date.now() - startTime;
-        if (!response.ok) {
-            const errorText = await response.text();
-            logError('Request failed: %s %s (%dms)', response.status, response.statusText, duration);
-            let errorMessage = `API request failed: ${response.statusText}`;
-            let errorCode = 'ServiceException';
-            let requestId;
-            try {
-                const errorData = JSON.parse(errorText);
-                if (errorData.message)
-                    errorMessage = errorData.message;
-                if (errorData.code)
-                    errorCode = errorData.code;
-                if (errorData.requestId)
-                    requestId = errorData.requestId;
-            }
-            catch {
-                if (errorText)
-                    errorMessage = errorText;
-            }
-            throw new LocationServiceException({
-                message: errorMessage,
-                code: errorCode,
-                statusCode: response.status,
-                requestId,
-            });
-        }
-        const result = await response.json();
-        log('Request successful: %s (%dms)', response.status, duration);
-        return result;
-    }
-    getEndpoint(command) {
-        for (const [CommandClass, endpoint] of ENDPOINT_MAP) {
-            if (command instanceof CommandClass)
-                return endpoint;
-        }
-        throw new Error(`Unknown command type: ${command.constructor?.name ?? typeof command}`);
+        }, options);
     }
 }

package/dist/errors/LocationServiceException.d.ts

@@ -1,16 +1,44 @@
 export interface LocationServiceExceptionOptions {
     message: string;
     code: string;
-    statusCode: number;
+    /** Absent for failures that never reached the server: network, timeout, abort. */
+    statusCode?: number;
     requestId?: string;
+    /** Structured extras — `source: 'client'` marks a locally-raised failure. */
+    details?: Record<string, unknown>;
+    cause?: unknown;
+    /** Parsed from the `Retry-After` header, in milliseconds. */
+    retryAfterMs?: number;
 }
+/**
+ * The single error type this package throws.
+ *
+ * Every failure — an API error envelope, a network fault, a timeout, an abort —
+ * arrives as one of these, so a caller writes one `catch` and asks the getters
+ * rather than sniffing at `TypeError` vs `DOMException` vs a bare `Error`.
+ */
 export declare class LocationServiceException extends Error {
     readonly code: string;
-    readonly statusCode: number;
+    readonly statusCode?: number;
     readonly requestId?: string;
+    readonly details?: Record<string, unknown>;
+    readonly retryAfterMs?: number;
     constructor(options: LocationServiceExceptionOptions);
+    /**
+     * Worth another attempt.
+     *
+     * Deliberately a explicit list rather than `statusCode >= 500`: a 500 or 501
+     * means the server broke on this request and will break again, while 502/503/
+     * 504 mean it never got there or gave up waiting. Retrying the first kind just
+     * multiplies the damage. Network failures and timeouts are retryable because
+     * nothing was necessarily processed.
+     */
     get isRetryable(): boolean;
     get isThrottling(): boolean;
     get isValidation(): boolean;
+    /** Credentials or entitlements — the caller must act, retrying will not help. */
+    get isAuth(): boolean;
+    get isAborted(): boolean;
+    get isTimeout(): boolean;
     toString(): string;
 }

package/dist/errors/LocationServiceException.js

@@ -1,13 +1,35 @@
+/**
+ * The single error type this package throws.
+ *
+ * Every failure — an API error envelope, a network fault, a timeout, an abort —
+ * arrives as one of these, so a caller writes one `catch` and asks the getters
+ * rather than sniffing at `TypeError` vs `DOMException` vs a bare `Error`.
+ */
 export class LocationServiceException extends Error {
     constructor(options) {
-        super(options.message);
+        super(options.message, { cause: options.cause });
         this.name = 'LocationServiceException';
         this.code = options.code;
         this.statusCode = options.statusCode;
         this.requestId = options.requestId;
+        this.details = options.details;
+        this.retryAfterMs = options.retryAfterMs;
     }
+    /**
+     * Worth another attempt.
+     *
+     * Deliberately a explicit list rather than `statusCode >= 500`: a 500 or 501
+     * means the server broke on this request and will break again, while 502/503/
+     * 504 mean it never got there or gave up waiting. Retrying the first kind just
+     * multiplies the damage. Network failures and timeouts are retryable because
+     * nothing was necessarily processed.
+     */
     get isRetryable() {
-        return this.statusCode === 429 || this.statusCode >= 500;
+        if (this.code === 'AbortedException')
+            return false;
+        if (this.code === 'NetworkException' || this.code === 'TimeoutException')
+            return true;
+        return (this.statusCode === 429 || [502, 503, 504].includes(this.statusCode ?? 0));
     }
     get isThrottling() {
         return this.code === 'ThrottlingException' || this.statusCode === 429;
@@ -15,6 +37,16 @@ export class LocationServiceException extends Error {
     get isValidation() {
         return this.code === 'ValidationException' || this.statusCode === 400;
     }
+    /** Credentials or entitlements — the caller must act, retrying will not help. */
+    get isAuth() {
+        return this.statusCode === 401 || this.statusCode === 403;
+    }
+    get isAborted() {
+        return this.code === 'AbortedException';
+    }
+    get isTimeout() {
+        return this.code === 'TimeoutException';
+    }
     toString() {
         const parts = [`LocationServiceException: [${this.code}] ${this.message}`];
         if (this.requestId)

package/dist/index.d.ts

@@ -1,4 +1,8 @@
 export { GeoPlacesClient } from './client/GeoPlacesClient';
+export type { SendOptions } from './client/GeoPlacesClient';
+export { DEFAULT_MAX_ATTEMPTS, DEFAULT_TIMEOUT_MS } from './transport/http';
+export type { RequestOptions } from './transport/http';
+export { TOKEN_REFRESH_BUFFER_SECONDS, readTokenExpiry, } from './auth/tokenRefresh';
 export { LocationServiceException } from './errors/LocationServiceException';
 export type { LocationServiceExceptionOptions } from './errors/LocationServiceException';
 export * from '@aws-sdk/client-geo-places';

package/dist/index.js

@@ -1,5 +1,9 @@
 // Client (Custom - uses our auth instead of AWS SigV4)
 export { GeoPlacesClient } from './client/GeoPlacesClient';
+// Transport options — cancellation, per-attempt timeout, retry policy
+export { DEFAULT_MAX_ATTEMPTS, DEFAULT_TIMEOUT_MS } from './transport/http';
+// Token refresh policy — shared by the server provider and the React provider
+export { TOKEN_REFRESH_BUFFER_SECONDS, readTokenExpiry, } from './auth/tokenRefresh';
 // Errors
 export { LocationServiceException } from './errors/LocationServiceException';
 // Re-export AWS SDK commands and types

package/dist/server/LocationServiceConnector.d.ts

@@ -1,46 +1,37 @@
+import type { RequestOptions } from '../transport/http';
 export interface ConnectorConfig {
     apiUrl?: string;
     token?: string;
     getToken?: () => Promise<{
         token: string;
     }>;
+    /**
+     * Sent as the `Origin` header on every request. The API requires an Origin it
+     * recognises on every data request and answers 403 without one, so every
+     * caller was setting it by hand on each `send`; this does it once.
+     */
+    origin?: string;
 }
-export interface SendOptions {
+export interface SendOptions extends RequestOptions {
     headers?: Record<string, string>;
 }
 /**
- * LocationServiceConnector - Server-side connector for Location Service API
+ * LocationServiceConnector — server-side connector for the Location Service API.
  *
- * Optimized for backend-to-backend communication with:
- * - Automatic configuration from environment variables
- * - Automatic Origin header handling
- * - Server-side token management
- * - Enhanced error handling
- *
- * Uses AWS SDK command classes with Bearer token authentication.
+ * Backend-to-backend: automatic configuration from the environment, server-side
+ * token management, and the same transport (timeout, cancellation, retry) as the
+ * browser client.
  *
  * @example
  * ```typescript
- * // Auto-detect from environment
- * const connector = new LocationServiceConnector()
- *
- * // Or provide explicit config
- * const connector = new LocationServiceConnector({
- *   apiUrl: 'https://api.example.com',
- *   token: 'your-token'
- * })
- *
- * // Send with custom headers (including Origin)
- * const result = await connector.send(
- *   new SearchTextCommand({ QueryText: 'Space Needle' }),
- *   { headers: { 'Origin': req.headers.origin } }
- * )
+ * const connector = new LocationServiceConnector({ origin: 'https://app.example.com' })
+ * const result = await connector.send(new SearchTextCommand({ QueryText: 'Space Needle' }))
  * ```
  */
 export declare class LocationServiceConnector {
     private configPromise;
+    private origin?;
     readonly serviceId: string;
     constructor(config?: ConnectorConfig);
     send<TInput, TOutput>(command: TInput, options?: SendOptions): Promise<TOutput>;
-    private getEndpoint;
 }

package/dist/server/LocationServiceConnector.js

@@ -1,46 +1,31 @@
-import { AutocompleteCommand, GeocodeCommand, GetPlaceCommand, ReverseGeocodeCommand, SearchNearbyCommand, SearchTextCommand, SuggestCommand, } from '@aws-sdk/client-geo-places';
 import debug from 'debug';
 import { LocationServiceException } from '../errors/LocationServiceException';
+import { resolveEndpoint } from '../transport/endpoints';
+import { requestJson } from '../transport/http';
 import { roundPositionFields } from '../utils/roundPosition';
 import { getClientConfig } from './getClientConfig';
 const log = debug('location-client:connector');
 /**
- * LocationServiceConnector - Server-side connector for Location Service API
+ * LocationServiceConnector — server-side connector for the Location Service API.
  *
- * Optimized for backend-to-backend communication with:
- * - Automatic configuration from environment variables
- * - Automatic Origin header handling
- * - Server-side token management
- * - Enhanced error handling
- *
- * Uses AWS SDK command classes with Bearer token authentication.
+ * Backend-to-backend: automatic configuration from the environment, server-side
+ * token management, and the same transport (timeout, cancellation, retry) as the
+ * browser client.
  *
  * @example
  * ```typescript
- * // Auto-detect from environment
- * const connector = new LocationServiceConnector()
- *
- * // Or provide explicit config
- * const connector = new LocationServiceConnector({
- *   apiUrl: 'https://api.example.com',
- *   token: 'your-token'
- * })
- *
- * // Send with custom headers (including Origin)
- * const result = await connector.send(
- *   new SearchTextCommand({ QueryText: 'Space Needle' }),
- *   { headers: { 'Origin': req.headers.origin } }
- * )
+ * const connector = new LocationServiceConnector({ origin: 'https://app.example.com' })
+ * const result = await connector.send(new SearchTextCommand({ QueryText: 'Space Needle' }))
  * ```
  */
 export class LocationServiceConnector {
     constructor(config) {
         this.serviceId = 'Geo Places';
         this.configPromise = config ? Promise.resolve(config) : getClientConfig();
+        this.origin = config?.origin;
     }
     async send(command, options) {
         const config = await this.configPromise;
-        // Get token - ConnectorConfig may have getToken, ServerClientConfig has static token
         let token;
         if ('getToken' in config && typeof config.getToken === 'function') {
             const result = await config.getToken();
@@ -54,72 +39,24 @@ export class LocationServiceConnector {
             token = config.token;
         }
         if (!token) {
-            throw new Error('No token available');
+            throw new LocationServiceException({
+                code: 'InvalidCredentialsException',
+                message: 'No token available — check clientId/clientSecret configuration',
+                details: { source: 'client' },
+            });
         }
         const cmd = command;
-        const endpoint = this.getEndpoint(cmd);
-        const url = `${config.apiUrl}${endpoint}`;
-        const commandName = cmd.constructor.name;
+        const endpoint = resolveEndpoint(cmd);
         const input = roundPositionFields(cmd.input);
-        log('Sending %s request to %s', commandName, endpoint);
-        const startTime = Date.now();
-        // Merge headers: user headers, then system headers override
+        // Caller headers first so the system ones below cannot be overridden, but an
+        // explicit per-call Origin still beats the connector-wide default.
         const headers = {
-            ...(options?.headers || {}),
+            ...(this.origin ? { Origin: this.origin } : {}),
+            ...(options?.headers ?? {}),
             'Content-Type': 'application/json',
             Authorization: `Bearer ${token}`,
         };
-        const response = await fetch(url, {
-            method: 'POST',
-            headers,
-            body: JSON.stringify(input),
-        });
-        const duration = Date.now() - startTime;
-        if (!response.ok) {
-            const errorText = await response.text();
-            log('Request failed: %s %s (%dms)', response.status, response.statusText, duration);
-            let errorMessage = `API request failed: ${response.statusText}`;
-            let errorCode = 'ServiceException';
-            let requestId;
-            try {
-                const errorData = JSON.parse(errorText);
-                if (errorData.message)
-                    errorMessage = errorData.message;
-                if (errorData.code)
-                    errorCode = errorData.code;
-                if (errorData.requestId)
-                    requestId = errorData.requestId;
-            }
-            catch {
-                if (errorText)
-                    errorMessage = errorText;
-            }
-            throw new LocationServiceException({
-                message: errorMessage,
-                code: errorCode,
-                statusCode: response.status,
-                requestId,
-            });
-        }
-        const result = await response.json();
-        log('Request successful: %s (%dms)', response.status, duration);
-        return result;
-    }
-    getEndpoint(command) {
-        if (command instanceof AutocompleteCommand)
-            return '/address/autocomplete';
-        if (command instanceof GeocodeCommand)
-            return '/address/geocode';
-        if (command instanceof GetPlaceCommand)
-            return '/address/place';
-        if (command instanceof ReverseGeocodeCommand)
-            return '/address/search/reverse-geocode';
-        if (command instanceof SearchNearbyCommand)
-            return '/address/search/nearby';
-        if (command instanceof SearchTextCommand)
-            return '/address/search/text';
-        if (command instanceof SuggestCommand)
-            return '/address/suggestion';
-        throw new Error(`Unknown command type: ${command.constructor?.name ?? typeof command}`);
+        log('Sending %s request to %s', cmd.constructor?.name, endpoint);
+        return requestJson(`${config.apiUrl}${endpoint}`, { method: 'POST', headers, body: JSON.stringify(input) }, options);
     }
 }

package/dist/server/getClientConfig.js

@@ -1,11 +1,18 @@
 import debug from 'debug';
+import { createHash } from 'node:crypto';
 import { TokenProvider } from '../auth/TokenProvider';
+import { LocationServiceException } from '../errors/LocationServiceException';
 const log = debug('location-client:clientConfig');
 // Singleton instance to prevent race conditions
 let tokenProviderInstance = null;
 let currentConfig = null;
 function getTokenProvider(apiUrl, clientId, clientSecret) {
-    const configKey = `${apiUrl}:${clientId}`;
+    // The SECRET is part of the key. Without it, rotating a client secret while
+    // keeping the same clientId left this process reusing a provider built on the
+    // old secret — so the rotation appeared to do nothing until a restart. Hashed
+    // rather than concatenated so the key is never a secret in its own right, and
+    // never ends up in a log line (#5).
+    const configKey = `${apiUrl}:${clientId}:${createHash('sha256').update(clientSecret).digest('hex').slice(0, 16)}`;
     // Reuse existing instance if config matches
     if (tokenProviderInstance && currentConfig === configKey) {
         log('[getTokenProvider] Reusing existing TokenProvider instance');
@@ -75,15 +82,38 @@ export async function getClientConfig(config = {}) {
     log('[getClientConfig] Getting TokenProvider instance');
     const provider = getTokenProvider(apiUrl, clientId, clientSecret);
     log('[getClientConfig] Fetching token');
-    const result = await provider.getToken();
-    if (!result.success || !result.token) {
-        console.error('[getClientConfig] Token fetch failed:', result.error);
-        const isAuthError = result.error === 'Invalid credentials' ||
-            result.error?.toLowerCase().includes('unauthorized');
-        throw new Error(isAuthError
-            ? `Authentication failed for client ID "${clientId}". ` +
-                `Verify LOCATION_CLIENT_ID and LOCATION_CLIENT_SECRET match your application in the developer portal.`
-            : result.error || 'Failed to get 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' },
+        });
     }
     log('[getClientConfig] Token fetched successfully, length:', result.token.length);
     return {

package/dist/transport/endpoints.d.ts

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

package/dist/transport/endpoints.js

@@ -0,0 +1,31 @@
+import { AutocompleteCommand, GeocodeCommand, GetPlaceCommand, ReverseGeocodeCommand, SearchNearbyCommand, SearchTextCommand, SuggestCommand, } from '@aws-sdk/client-geo-places';
+import { LocationServiceException } from '../errors/LocationServiceException';
+/**
+ * Command class -> API path.
+ *
+ * Keyed on constructor IDENTITY, never on `constructor.name`: a minifier
+ * rewrites class names and a string-keyed map silently stops matching in a
+ * production bundle while working perfectly in dev. The server connector used
+ * to carry its own `if (cmd instanceof X)` chain saying the same thing in a
+ * different order — one of them was always going to drift.
+ */
+const ENDPOINTS = new Map([
+    [AutocompleteCommand, '/address/autocomplete'],
+    [GeocodeCommand, '/address/geocode'],
+    [GetPlaceCommand, '/address/place'],
+    [ReverseGeocodeCommand, '/address/search/reverse-geocode'],
+    [SearchNearbyCommand, '/address/search/nearby'],
+    [SearchTextCommand, '/address/search/text'],
+    [SuggestCommand, '/address/suggestion'],
+]);
+export function resolveEndpoint(command) {
+    for (const [CommandClass, endpoint] of ENDPOINTS) {
+        if (command instanceof CommandClass)
+            return endpoint;
+    }
+    throw new LocationServiceException({
+        code: 'UnknownCommandException',
+        message: `Unknown command type: ${command?.constructor?.name ?? typeof command}`,
+        details: { source: 'client' },
+    });
+}

package/dist/transport/errors.d.ts

@@ -0,0 +1,19 @@
+import { LocationServiceException } from '../errors/LocationServiceException';
+/**
+ * Turn a non-2xx response into a LocationServiceException.
+ *
+ * The API does not yet speak one error shape — that is api#29 (T23) — so this
+ * tolerates the three it currently emits and synthesises a `code` for each.
+ * RFC-0002 calls this legacy tolerance, and it is what lets the client ship
+ * before the API contract lands. Delete the fallbacks once T23 is deployed.
+ *
+ *   { message, code, requestId }         service Lambdas — already correct
+ *   { error, error_description }         /auth/token, OAuth shape
+ *   { message: "Unauthorized" }          API Gateway's own responses
+ */
+export declare function parseErrorResponse(status: number, statusText: string, body: string, headers?: Headers): LocationServiceException;
+/**
+ * `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.
+ */
+export declare function parseRetryAfter(value: string | null | undefined): number | undefined;

package/dist/transport/errors.js

@@ -0,0 +1,100 @@
+import { LocationServiceException } from '../errors/LocationServiceException';
+/**
+ * Turn a non-2xx response into a LocationServiceException.
+ *
+ * The API does not yet speak one error shape — that is api#29 (T23) — so this
+ * tolerates the three it currently emits and synthesises a `code` for each.
+ * RFC-0002 calls this legacy tolerance, and it is what lets the client ship
+ * before the API contract lands. Delete the fallbacks once T23 is deployed.
+ *
+ *   { message, code, requestId }         service Lambdas — already correct
+ *   { error, error_description }         /auth/token, OAuth shape
+ *   { message: "Unauthorized" }          API Gateway's own responses
+ */
+export function parseErrorResponse(status, statusText, body, headers) {
+    let message = `Request failed: ${statusText || status}`;
+    let code;
+    let requestId;
+    let details;
+    try {
+        const data = JSON.parse(body);
+        if (typeof data.message === 'string')
+            message = data.message;
+        if (typeof data.code === 'string')
+            code = data.code;
+        if (typeof data.requestId === 'string')
+            requestId = data.requestId;
+        // OAuth envelope from /auth/token
+        if (!code && typeof data.error === 'string') {
+            message = data.error_description ?? data.error;
+            code = oauthCode(data.error, status);
+            details = { oauthError: data.error };
+        }
+    }
+    catch {
+        if (body)
+            message = body;
+    }
+    return new LocationServiceException({
+        message,
+        code: code ?? statusCode(status),
+        statusCode: status,
+        requestId,
+        details,
+        retryAfterMs: parseRetryAfter(headers?.get('retry-after')),
+    });
+}
+/** OAuth `error` values the token endpoint emits, mapped to our codes. */
+function oauthCode(error, status) {
+    switch (error) {
+        case 'temporarily_unavailable':
+            return 'ServiceUnavailableException';
+        case 'invalid_client':
+        case 'unauthorized':
+            return 'InvalidCredentialsException';
+        case 'invalid_request':
+            return 'ValidationException';
+        case 'unsupported_grant_type':
+            return 'ValidationException';
+        default:
+            return statusCode(status);
+    }
+}
+/** Last resort when the body carried no code at all (bare gateway responses). */
+function statusCode(status) {
+    switch (status) {
+        case 400:
+            return 'ValidationException';
+        case 401:
+            return 'UnauthorizedException';
+        case 403:
+            return 'ForbiddenException';
+        case 404:
+            return 'NotFoundException';
+        case 429:
+            return 'ThrottlingException';
+        case 502:
+            return 'UpstreamException';
+        case 503:
+            return 'ServiceUnavailableException';
+        case 504:
+            return 'TimeoutException';
+        default:
+            return status >= 500 ? 'InternalException' : 'ServiceException';
+    }
+}
+/**
+ * `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.
+ */
+export function parseRetryAfter(value) {
+    if (!value)
+        return undefined;
+    const seconds = Number(value);
+    if (Number.isFinite(seconds) && seconds >= 0)
+        return seconds * 1000;
+    const date = Date.parse(value);
+    if (!Number.isNaN(date))
+        return Math.max(0, date - Date.now());
+    return undefined;
+}

package/dist/transport/http.d.ts

@@ -0,0 +1,24 @@
+/** Per-attempt timeout. Sits well under the API's own 25 s Lambda ceiling. */
+export declare const DEFAULT_TIMEOUT_MS = 10000;
+export declare const DEFAULT_MAX_ATTEMPTS = 3;
+export interface RequestOptions {
+    /** Caller cancellation. Aborting rejects with code `AbortedException`. */
+    signal?: AbortSignal;
+    /** Per ATTEMPT, not for the whole call. Default 10 s. */
+    timeoutMs?: number;
+    /** `false` disables retries entirely. Default 3 attempts = 2 retries. */
+    retry?: false | {
+        maxAttempts?: number;
+    };
+}
+/** Exponential backoff with FULL jitter, so retries never march in lockstep. */
+export declare function backoffMs(attempt: number, random?: () => number): number;
+/**
+ * One JSON request, with timeout, cancellation and retry.
+ *
+ * Every failure leaves as a LocationServiceException — a fetch rejection
+ * becomes `NetworkException` with the original as `cause`, an abort becomes
+ * `AbortedException`, a timeout becomes `TimeoutException` with
+ * `details.source = 'client'` so it is distinguishable from the API's own 504.
+ */
+export declare function requestJson<T>(url: string, init: RequestInit, options?: RequestOptions): Promise<T>;

package/dist/transport/http.js

@@ -0,0 +1,134 @@
+import debug from 'debug';
+import { LocationServiceException } from '../errors/LocationServiceException';
+import { parseErrorResponse, parseRetryAfter } from './errors';
+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;
+export const DEFAULT_MAX_ATTEMPTS = 3;
+const BACKOFF_BASE_MS = 250;
+const BACKOFF_CAP_MS = 4000;
+/**
+ * Combine the caller's signal with a per-attempt timeout.
+ *
+ * `AbortSignal.any` is the clean way and exists in Node 20+ and current
+ * browsers; the manual fan-in keeps older runtimes working rather than
+ * throwing at import time.
+ */
+function attemptSignal(caller, timeoutMs) {
+    const timeout = AbortSignal.timeout(timeoutMs);
+    if (!caller)
+        return { signal: timeout, cleanup: () => { } };
+    if (typeof AbortSignal.any === 'function') {
+        return { signal: AbortSignal.any([caller, timeout]), cleanup: () => { } };
+    }
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    if (caller.aborted || timeout.aborted)
+        controller.abort();
+    caller.addEventListener('abort', abort);
+    timeout.addEventListener('abort', abort);
+    return {
+        signal: controller.signal,
+        cleanup: () => {
+            caller.removeEventListener('abort', abort);
+            timeout.removeEventListener('abort', abort);
+        },
+    };
+}
+/** Exponential backoff with FULL jitter, so retries never march in lockstep. */
+export function backoffMs(attempt, random = Math.random) {
+    const ceiling = Math.min(BACKOFF_CAP_MS, BACKOFF_BASE_MS * 2 ** attempt);
+    return Math.floor(random() * ceiling);
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * One JSON request, with timeout, cancellation and retry.
+ *
+ * Every failure leaves as a LocationServiceException — a fetch rejection
+ * becomes `NetworkException` with the original as `cause`, an abort becomes
+ * `AbortedException`, a timeout becomes `TimeoutException` with
+ * `details.source = 'client'` so it is distinguishable from the API's own 504.
+ */
+export async function requestJson(url, init, options = {}) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const maxAttempts = options.retry === false
+        ? 1
+        : (options.retry?.maxAttempts ?? DEFAULT_MAX_ATTEMPTS);
+    let lastError;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        // Checked before every attempt: a signal aborted during backoff must not fire one more.
+        if (options.signal?.aborted)
+            throw abortedException(options.signal);
+        const { signal, cleanup } = attemptSignal(options.signal, timeoutMs);
+        try {
+            const response = await fetch(url, { ...init, signal });
+            if (response.ok)
+                return (await response.json());
+            const error = parseErrorResponse(response.status, response.statusText, await response.text(), response.headers);
+            lastError = error;
+            if (!error.isRetryable || attempt === maxAttempts - 1)
+                throw error;
+            log('attempt %d failed (%s), retrying', attempt + 1, error.code);
+            await sleep(error.retryAfterMs ??
+                parseRetryAfter(response.headers.get('retry-after')) ??
+                backoffMs(attempt));
+        }
+        catch (err) {
+            if (err instanceof LocationServiceException) {
+                // Already classified above, or thrown on the final attempt.
+                if (!err.isRetryable || attempt === maxAttempts - 1)
+                    throw err;
+                lastError = err;
+                continue;
+            }
+            const wrapped = wrapFetchError(err, options.signal);
+            lastError = wrapped;
+            if (!wrapped.isRetryable || attempt === maxAttempts - 1)
+                throw wrapped;
+            log('attempt %d failed (%s), retrying', attempt + 1, wrapped.code);
+            await sleep(backoffMs(attempt));
+        }
+        finally {
+            cleanup();
+        }
+    }
+    /* c8 ignore next */
+    throw (lastError ??
+        new LocationServiceException({
+            code: 'InternalException',
+            message: 'Request failed',
+        }));
+}
+function abortedException(signal) {
+    return new LocationServiceException({
+        code: 'AbortedException',
+        message: 'Request was aborted by the caller',
+        details: { source: 'client' },
+        cause: signal?.reason,
+    });
+}
+/**
+ * fetch rejects with a raw `TypeError` for a network fault and a `DOMException`
+ * named AbortError for both cancellation and timeout — indistinguishable from
+ * each other unless the caller's own signal is checked, which is why that is
+ * checked first.
+ */
+function wrapFetchError(err, callerSignal) {
+    const name = err?.name;
+    if (callerSignal?.aborted)
+        return abortedException(callerSignal);
+    if (name === 'TimeoutError' || name === 'AbortError') {
+        return new LocationServiceException({
+            code: 'TimeoutException',
+            message: 'Request timed out',
+            details: { source: 'client' },
+            cause: err,
+        });
+    }
+    return new LocationServiceException({
+        code: 'NetworkException',
+        message: err instanceof Error ? err.message : 'Network request failed',
+        details: { source: 'client' },
+        cause: err,
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chaosity/location-client",
-  "version": "0.1.14",
+  "version": "0.2.1",
   "description": "Client library for Chaosity Location Service with AWS Location Service compatibility",
   "type": "module",
   "main": "dist/index.js",
@@ -21,11 +21,10 @@
     "lint": "eslint . && prettier --check .",
     "lint:fix": "eslint --fix . && prettier --write .",
     "format": "prettier --write .",
-    "test": "vitest run --passWithNoTests",
+    "test": "vitest run",
     "test:watch": "vitest",
     "prepublishOnly": "npm run build",
-    "prepare": "husky",
-    "postversion": "git push --follow-tags"
+    "prepare": "husky"
   },
   "keywords": [
     "aws",