@chaosity/location-client 0.5.0 → 0.6.0

package/dist/cjs/server/LocationServiceConnector.js

@@ -0,0 +1,91 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocationServiceConnector = void 0;
+const debug_1 = __importDefault(require("debug"));
+const LocationServiceException_js_1 = require("../errors/LocationServiceException.js");
+const endpoints_js_1 = require("../transport/endpoints.js");
+const http_js_1 = require("../transport/http.js");
+const roundPosition_js_1 = require("../utils/roundPosition.js");
+const tokenClaims_js_1 = require("../utils/tokenClaims.js");
+const getClientConfig_js_1 = require("./getClientConfig.js");
+const log = (0, debug_1.default)('location-client:connector');
+/**
+ * LocationServiceConnector — server-side connector for the Location Service API.
+ *
+ * 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
+ * const connector = new LocationServiceConnector({ origin: 'https://app.example.com' })
+ * const result = await connector.send(new SearchTextCommand({ QueryText: 'Space Needle' }))
+ * ```
+ */
+class LocationServiceConnector {
+    constructor(config) {
+        this.serviceId = 'Geo Places';
+        this.configPromise = config ? Promise.resolve(config) : (0, getClientConfig_js_1.getClientConfig)();
+        this.origin = config?.origin;
+    }
+    /** One place that knows how a token is obtained, so nothing can drift. */
+    async resolveToken() {
+        const config = await this.configPromise;
+        if ('getToken' in config && typeof config.getToken === 'function') {
+            const result = await config.getToken();
+            if (!result)
+                return undefined;
+            return typeof result === 'string' ? result : result.token;
+        }
+        return config.token;
+    }
+    /**
+     * This application's own configuration, as carried on the access token
+     * (api#65) — bias precision, and the countries it is scoped to.
+     *
+     * Provided so an application can SHOW its own settings: populate a country
+     * selector with the markets it actually serves, label a settings screen, and
+     * so on. Being a few minutes stale is cosmetic for that.
+     *
+     * It is not an entitlement check. See AppConfigClaims for why acting on
+     * `countries` client-side makes requests fail that would otherwise succeed.
+     *
+     * Returns `{}` when the token carries no application config, which is the
+     * case until one is configured in the portal.
+     */
+    async getAppConfig() {
+        return (0, tokenClaims_js_1.readAppConfigClaims)(await this.resolveToken());
+    }
+    async send(command, options) {
+        const token = await this.resolveToken();
+        if (!token) {
+            throw new LocationServiceException_js_1.LocationServiceException({
+                code: 'InvalidCredentialsException',
+                message: 'No token available — check clientId/clientSecret configuration',
+                details: { source: 'client' },
+            });
+        }
+        const cmd = command;
+        const endpoint = (0, endpoints_js_1.resolveEndpoint)(cmd);
+        // The token is already resolved above, so the precision this application
+        // is entitled to is available before the request is shaped (api#65).
+        // Absent claim -> the 3 dp floor, which is what every application gets
+        // until one is configured otherwise.
+        const { biasDecimals } = (0, tokenClaims_js_1.readAppConfigClaims)(token);
+        const input = (0, roundPosition_js_1.roundPositionFields)(cmd.input, biasDecimals);
+        // 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 = {
+            ...(this.origin ? { Origin: this.origin } : {}),
+            ...(options?.headers ?? {}),
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${token}`,
+        };
+        log('Sending %s request to %s', cmd.constructor?.name, endpoint);
+        return (0, http_js_1.requestJson)(`${(await this.configPromise).apiUrl}${endpoint}`, { method: 'POST', headers, body: JSON.stringify(input) }, options);
+    }
+}
+exports.LocationServiceConnector = LocationServiceConnector;

package/dist/cjs/server/getClientConfig.d.ts

@@ -0,0 +1,40 @@
+import type { ClientConfig } from '../types/index.js';
+export interface ServerAuthConfig {
+    apiUrl?: string;
+    clientId?: string;
+    clientSecret?: string;
+}
+export interface ServerClientConfig extends ClientConfig {
+    expiresAt?: number;
+}
+/**
+ * Get client configuration with OAuth2 authentication.
+ *
+ * Automatically reads from environment variables:
+ * - LOCATION_API_URL or LOCATION_SERVICE_API_URL
+ * - LOCATION_CLIENT_ID or LOCATION_SERVICE_CLIENT_ID
+ * - LOCATION_CLIENT_SECRET or LOCATION_SERVICE_CLIENT_SECRET
+ *
+ * You can override any value by passing it explicitly.
+ *
+ * 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.
+ *
+ * @example
+ * // Auto-detect from environment
+ * const config = await getClientConfig()
+ *
+ * // 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 })
+ */
+export declare function getClientConfig(config?: ServerAuthConfig): Promise<ServerClientConfig>;

package/dist/cjs/server/getClientConfig.js

@@ -0,0 +1,130 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getClientConfig = getClientConfig;
+const debug_1 = __importDefault(require("debug"));
+const node_crypto_1 = require("node:crypto");
+const TokenProvider_js_1 = require("../auth/TokenProvider.js");
+const LocationServiceException_js_1 = require("../errors/LocationServiceException.js");
+const log = (0, debug_1.default)('location-client:clientConfig');
+// Singleton instance to prevent race conditions
+let tokenProviderInstance = null;
+let currentConfig = null;
+function getTokenProvider(apiUrl, clientId, clientSecret) {
+    // 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}:${(0, node_crypto_1.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');
+        return tokenProviderInstance;
+    }
+    // Create new instance if config changed
+    log('[getTokenProvider] Creating new TokenProvider instance');
+    tokenProviderInstance = new TokenProvider_js_1.TokenProvider({ apiUrl, clientId, clientSecret });
+    currentConfig = configKey;
+    return tokenProviderInstance;
+}
+/**
+ * Get client configuration with OAuth2 authentication.
+ *
+ * Automatically reads from environment variables:
+ * - LOCATION_API_URL or LOCATION_SERVICE_API_URL
+ * - LOCATION_CLIENT_ID or LOCATION_SERVICE_CLIENT_ID
+ * - LOCATION_CLIENT_SECRET or LOCATION_SERVICE_CLIENT_SECRET
+ *
+ * You can override any value by passing it explicitly.
+ *
+ * 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.
+ *
+ * @example
+ * // Auto-detect from environment
+ * const config = await getClientConfig()
+ *
+ * // 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 })
+ */
+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_js_1.LocationServiceException) {
+            if (error.isAuth) {
+                throw new LocationServiceException_js_1.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_js_1.LocationServiceException({
+            code: 'InvalidCredentialsException',
+            message: 'Token provider returned no token',
+            details: { source: 'client' },
+        });
+    }
+    log('[getClientConfig] Token fetched successfully, length:', result.token.length);
+    return {
+        apiUrl,
+        token: result.token,
+        expiresAt: result.expiresAt,
+    };
+}

package/dist/cjs/server/index.d.ts

@@ -0,0 +1,6 @@
+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/cjs/server/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocationServiceConnector = exports.getClientConfig = exports.TokenProvider = void 0;
+var TokenProvider_js_1 = require("../auth/TokenProvider.js");
+Object.defineProperty(exports, "TokenProvider", { enumerable: true, get: function () { return TokenProvider_js_1.TokenProvider; } });
+var getClientConfig_js_1 = require("./getClientConfig.js");
+Object.defineProperty(exports, "getClientConfig", { enumerable: true, get: function () { return getClientConfig_js_1.getClientConfig; } });
+var LocationServiceConnector_js_1 = require("./LocationServiceConnector.js");
+Object.defineProperty(exports, "LocationServiceConnector", { enumerable: true, get: function () { return LocationServiceConnector_js_1.LocationServiceConnector; } });

package/dist/cjs/transport/endpoints.d.ts

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

package/dist/cjs/transport/endpoints.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveEndpoint = resolveEndpoint;
+const client_geo_places_1 = require("@aws-sdk/client-geo-places");
+const LocationServiceException_js_1 = require("../errors/LocationServiceException.js");
+/**
+ * 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([
+    [client_geo_places_1.AutocompleteCommand, '/address/autocomplete'],
+    [client_geo_places_1.GeocodeCommand, '/address/geocode'],
+    [client_geo_places_1.GetPlaceCommand, '/address/place'],
+    [client_geo_places_1.ReverseGeocodeCommand, '/address/search/reverse-geocode'],
+    [client_geo_places_1.SearchNearbyCommand, '/address/search/nearby'],
+    [client_geo_places_1.SearchTextCommand, '/address/search/text'],
+    [client_geo_places_1.SuggestCommand, '/address/suggestion'],
+]);
+function resolveEndpoint(command) {
+    for (const [CommandClass, endpoint] of ENDPOINTS) {
+        if (command instanceof CommandClass)
+            return endpoint;
+    }
+    throw new LocationServiceException_js_1.LocationServiceException({
+        code: 'UnknownCommandException',
+        message: `Unknown command type: ${command?.constructor?.name ?? typeof command}`,
+        details: { source: 'client' },
+    });
+}

package/dist/cjs/transport/errors.d.ts

@@ -0,0 +1,19 @@
+import { LocationServiceException } from '../errors/LocationServiceException.js';
+/**
+ * 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/cjs/transport/errors.js

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseErrorResponse = parseErrorResponse;
+exports.parseRetryAfter = parseRetryAfter;
+const LocationServiceException_js_1 = require("../errors/LocationServiceException.js");
+/**
+ * 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
+ */
+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_js_1.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.
+ */
+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/cjs/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/cjs/transport/http.js

@@ -0,0 +1,142 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_MAX_ATTEMPTS = exports.DEFAULT_TIMEOUT_MS = void 0;
+exports.backoffMs = backoffMs;
+exports.requestJson = requestJson;
+const debug_1 = __importDefault(require("debug"));
+const LocationServiceException_js_1 = require("../errors/LocationServiceException.js");
+const errors_js_1 = require("./errors.js");
+const log = (0, debug_1.default)('location-client:transport');
+/** Per-attempt timeout. Sits well under the API's own 25 s Lambda ceiling. */
+exports.DEFAULT_TIMEOUT_MS = 10000;
+exports.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. */
+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.
+ */
+async function requestJson(url, init, options = {}) {
+    const timeoutMs = options.timeoutMs ?? exports.DEFAULT_TIMEOUT_MS;
+    const maxAttempts = options.retry === false
+        ? 1
+        : (options.retry?.maxAttempts ?? exports.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 = (0, errors_js_1.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 ??
+                (0, errors_js_1.parseRetryAfter)(response.headers.get('retry-after')) ??
+                backoffMs(attempt));
+        }
+        catch (err) {
+            if (err instanceof LocationServiceException_js_1.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_js_1.LocationServiceException({
+            code: 'InternalException',
+            message: 'Request failed',
+        }));
+}
+function abortedException(signal) {
+    return new LocationServiceException_js_1.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_js_1.LocationServiceException({
+            code: 'TimeoutException',
+            message: 'Request timed out',
+            details: { source: 'client' },
+            cause: err,
+        });
+    }
+    return new LocationServiceException_js_1.LocationServiceException({
+        code: 'NetworkException',
+        message: err instanceof Error ? err.message : 'Network request failed',
+        details: { source: 'client' },
+        cause: err,
+    });
+}

package/dist/cjs/types/index.d.ts

@@ -0,0 +1,34 @@
+export interface ClientConfig {
+    apiUrl: string;
+    token: string;
+    /** 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;
+}
+/**
+ * Minimal interface for AWS SDK command objects.
+ * All AWS SDK commands (AutocompleteCommand, SearchTextCommand, etc.) extend
+ * Smithy's Command base class which has an `input` property containing the
+ * request parameters. This interface captures what we actually need from
+ * commands without coupling to Smithy internals.
+ */
+export interface GeoPlacesCommand {
+    readonly input: object;
+}
+/**
+ * Minimal interface for a MapLibre Map instance.
+ * Using a structural type avoids hard coupling to a specific maplibre-gl version.
+ */
+export interface MapLike {
+    isStyleLoaded(): boolean | void;
+    on(event: string, listener: (...args: unknown[]) => void): void;
+    off(event: string, listener: (...args: unknown[]) => void): void;
+    getStyle(): {
+        layers: Array<{
+            id: string;
+            type: string;
+        }>;
+    };
+    getLayoutProperty(layerId: string, name: string): unknown;
+    setLayoutProperty(layerId: string, name: string, value: unknown): void;
+}

package/dist/cjs/types/index.js

@@ -0,0 +1,3 @@
+"use strict";
+// Custom types not provided by AWS SDK
+Object.defineProperty(exports, "__esModule", { value: true });