@chaosity/location-client 0.5.1 → 0.7.0

package/dist/cjs/server/getClientConfig.js

@@ -0,0 +1,174 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveApiUrl = resolveApiUrl;
+exports.serverTokenSource = serverTokenSource;
+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;
+}
+/**
+ * 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.
+ */
+function resolveApiUrl(explicit) {
+    return (explicit ||
+        process.env.LOCATION_API_URL ||
+        process.env.LOCATION_SERVICE_API_URL);
+}
+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_js_1.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_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.
+            const token = result.token;
+            if (!token) {
+                throw new LocationServiceException_js_1.LocationServiceException({
+                    code: 'InvalidCredentialsException',
+                    message: 'Token provider returned no token',
+                    details: { source: 'client' },
+                });
+            }
+            return { ...result, token };
+        },
+    };
+}
+/**
+ * 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.
+ *
+ * ## 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()
+ *
+ * // Or override specific values
+ * const config = await getClientConfig({ apiUrl: 'https://custom.api.com' })
+ *
+ * // The API rejected the token before its exp — revoked, or secret rotated
+ * const fresh = await getClientConfig({ forceRefresh: true })
+ */
+async function getClientConfig(config = {}) {
+    const source = serverTokenSource(config);
+    const result = await source.getToken(config.forceRefresh);
+    log('[getClientConfig] Token fetched successfully, length:', result.token.length);
+    return {
+        apiUrl: source.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,32 @@
+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;
+/**
+ * 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.
+ */
+export declare function parseRetryAfter(value: string | null | undefined): number | undefined;

package/dist/cjs/transport/errors.js

@@ -0,0 +1,120 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseErrorResponse = parseErrorResponse;
+exports.isTokenRejected = isTokenRejected;
+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';
+    }
+}
+/**
+ * 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.
+ */
+function isTokenRejected(err) {
+    return err instanceof LocationServiceException_js_1.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.
+ */
+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,53 @@
+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;
+    /**
+     * 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.
+ * 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 });