@chaosity/location-client 0.6.0 → 0.7.0

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

@@ -1,12 +1,52 @@
+import type { TokenResponse } from '../auth/TokenProvider.js';
 import type { ClientConfig } from '../types/index.js';
 export interface ServerAuthConfig {
     apiUrl?: string;
     clientId?: string;
     clientSecret?: string;
+    /**
+     * Mint a new token instead of returning the cached one.
+     *
+     * For the case the cache cannot see: a token the API has stopped accepting
+     * before its `exp` — revoked in the portal, or issued against a secret that
+     * has since been rotated. `TokenProvider` judges freshness from `exp` alone,
+     * so without this a caller holding a dead token waits out its whole lifetime.
+     */
+    forceRefresh?: boolean;
 }
 export interface ServerClientConfig extends ClientConfig {
     expiresAt?: number;
 }
+/**
+ * Where the API lives, from the argument or the environment.
+ *
+ * Separate from the credentials because the two are independently overridable:
+ * a caller can hand `LocationServiceConnector` its own `token` and still expect
+ * `LOCATION_API_URL` to say where to send it.
+ */
+export declare function resolveApiUrl(explicit?: string): string | undefined;
+/**
+ * A LIVE token source: resolved credentials plus a `getToken` that re-mints
+ * when the cached token is spent.
+ *
+ * This is the seam `getClientConfig` and `LocationServiceConnector` share, and
+ * it exists because the two need different SHAPES of the same thing.
+ * `getClientConfig` has to return plain data — see the warning on its return
+ * value — so it can only ever hand back a snapshot. The connector is long-lived
+ * and needs the source itself, or it dies at the first `exp` (#36).
+ *
+ * Deliberately not exported from `./server`: it hands out a callable bound to
+ * the process-wide provider, and the public surface stays the two functions
+ * that were already there.
+ */
+export interface ServerTokenSource {
+    apiUrl: string;
+    /** Resolves with a token or rejects; it never resolves tokenless. */
+    getToken(forceRefresh?: boolean): Promise<TokenResponse & {
+        token: string;
+    }>;
+}
+export declare function serverTokenSource(config?: ServerAuthConfig): ServerTokenSource;
 /**
  * Get client configuration with OAuth2 authentication.
  *
@@ -26,6 +66,21 @@ export interface ServerClientConfig extends ClientConfig {
  * 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()
@@ -33,8 +88,7 @@ export interface ServerClientConfig extends ClientConfig {
  * // Or override specific values
  * const config = await getClientConfig({ apiUrl: 'https://custom.api.com' })
  *
- * // Use getToken() for automatic caching and refresh
- * const { token } = await config.getToken()
- * const connector = new LocationServiceConnector({ apiUrl: config.apiUrl, token })
+ * // The API rejected the token before its exp — revoked, or secret rotated
+ * const fresh = await getClientConfig({ forceRefresh: true })
  */
 export declare function getClientConfig(config?: ServerAuthConfig): Promise<ServerClientConfig>;

package/dist/cjs/server/getClientConfig.js

@@ -3,6 +3,8 @@ 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");
@@ -30,6 +32,92 @@ function getTokenProvider(apiUrl, clientId, clientSecret) {
     currentConfig = configKey;
     return tokenProviderInstance;
 }
+/**
+ * Where the API lives, from the argument or the environment.
+ *
+ * Separate from the credentials because the two are independently overridable:
+ * a caller can hand `LocationServiceConnector` its own `token` and still expect
+ * `LOCATION_API_URL` to say where to send it.
+ */
+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.
  *
@@ -49,6 +137,21 @@ function getTokenProvider(apiUrl, clientId, clientSecret) {
  * NEVER call from browser/client code as it exposes credentials.
  * For SPA projects, create your own backend endpoint that calls this.
  *
+ * ## The return value is PLAIN DATA, and has to stay that way
+ *
+ * `{ apiUrl, token, expiresAt }` — no methods, no closures. The reason is not
+ * style: the shape every sample uses is a Next.js Server Action that returns
+ * this straight to a Client Component (every `src/lib/actions/location.ts`
+ * under `location-service-samples/web`), and the RSC boundary
+ * serialises it. A function on this object is not serialisable and throws at
+ * the boundary, so "make getClientConfig return getToken" — which #36 proposed
+ * and this JSDoc used to promise two lines below — would break every Next.js
+ * consumer of the library.
+ *
+ * A caller that needs a token which REFRESHES wants one of:
+ * - `LocationServiceConnector`, which holds a live source internally (#36), or
+ * - `TokenProvider` directly, if it is managing its own lifecycle.
+ *
  * @example
  * // Auto-detect from environment
  * const config = await getClientConfig()
@@ -56,74 +159,15 @@ function getTokenProvider(apiUrl, clientId, clientSecret) {
  * // Or override specific values
  * const config = await getClientConfig({ apiUrl: 'https://custom.api.com' })
  *
- * // Use getToken() for automatic caching and refresh
- * const { token } = await config.getToken()
- * const connector = new LocationServiceConnector({ apiUrl: config.apiUrl, token })
+ * // The API rejected the token before its exp — revoked, or secret rotated
+ * const fresh = await getClientConfig({ forceRefresh: true })
  */
 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' },
-        });
-    }
+    const source = serverTokenSource(config);
+    const result = await source.getToken(config.forceRefresh);
     log('[getClientConfig] Token fetched successfully, length:', result.token.length);
     return {
-        apiUrl,
+        apiUrl: source.apiUrl,
         token: result.token,
         expiresAt: result.expiresAt,
     };

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

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

package/dist/cjs/transport/errors.js

@@ -1,6 +1,7 @@
 "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");
 /**
@@ -87,6 +88,21 @@ function statusCode(status) {
             return status >= 500 ? 'InternalException' : 'ServiceException';
     }
 }
+/**
+ * The API has rejected this token: a 401, and only a 401.
+ *
+ * The authorizer throws `Unauthorized` for a token it cannot verify or that has
+ * expired, and API Gateway turns that into a 401. Its other refusals — no
+ * domain configured for the application, an Origin the application does not
+ * allow — are a Deny policy or a service 403, and a fresh token changes
+ * neither. Retrying those would send, and bill, the same doomed request twice.
+ *
+ * Shared by both send paths so the browser client and the server connector
+ * cannot come to different conclusions about the same response.
+ */
+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.

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

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

package/dist/client/GeoPlacesClient.d.ts

@@ -31,9 +31,12 @@ export declare class GeoPlacesClient {
      * case until one is configured in the portal.
      */
     getAppConfig(): AppConfigClaims;
+    /** Prefer the getToken callback (live ref) over a static token string. */
+    private currentToken;
     /**
      * @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>;
+    private dispatch;
 }

package/dist/client/GeoPlacesClient.js

@@ -1,5 +1,6 @@
 import debug from 'debug';
 import { resolveEndpoint } from '../transport/endpoints.js';
+import { isTokenRejected } from '../transport/errors.js';
 import { requestJson } from '../transport/http.js';
 import { roundPositionFields } from '../utils/roundPosition.js';
 import { readAppConfigClaims } from '../utils/tokenClaims.js';
@@ -32,8 +33,11 @@ export class GeoPlacesClient {
      * case until one is configured in the portal.
      */
     getAppConfig() {
-        const token = this.clientConfig.getToken?.() ?? this.clientConfig.token;
-        return readAppConfigClaims(token);
+        return readAppConfigClaims(this.currentToken());
+    }
+    /** Prefer the getToken callback (live ref) over a static token string. */
+    currentToken() {
+        return this.clientConfig.getToken?.() ?? this.clientConfig.token;
     }
     /**
      * @param options `signal` to cancel, `timeoutMs` per attempt, `retry: false`
@@ -41,15 +45,35 @@ export class GeoPlacesClient {
      */
     async send(command, options) {
         const cmd = command;
-        const endpoint = resolveEndpoint(cmd);
-        // Prefer the getToken callback (live ref) over a static token string.
-        const token = this.clientConfig.getToken?.() ?? this.clientConfig.token;
+        const url = `${this.clientConfig.apiUrl}${resolveEndpoint(cmd)}`;
+        const token = this.currentToken();
+        try {
+            return await this.dispatch(url, token, cmd, options);
+        }
+        catch (err) {
+            if (!isTokenRejected(err))
+                throw err;
+            // One shot. `refreshToken` is the only way to actually obtain a new
+            // token here — `getToken` is synchronous and returns the one already in
+            // hand — but it is re-read as a fallback because a provider that
+            // refreshes in the background may have landed a new one while this
+            // request was in flight.
+            const fresh = (await this.clientConfig.refreshToken?.()) ?? this.currentToken();
+            // Nothing new to send. Repeating the request would fail identically, and
+            // be billed identically.
+            if (!fresh || fresh === token)
+                throw err;
+            log('401 — retrying %s once with a refreshed token', cmd.constructor?.name);
+            return await this.dispatch(url, fresh, cmd, options);
+        }
+    }
+    dispatch(url, token, cmd, options) {
         // Resolve the token BEFORE rounding: the precision this application is
         // entitled to is a claim on it (api#65). Absent claim -> the 3 dp floor.
         const { biasDecimals } = readAppConfigClaims(token);
         const input = roundPositionFields(cmd.input, biasDecimals);
-        log('Sending %s to %s', cmd.constructor?.name, endpoint);
-        return requestJson(`${this.clientConfig.apiUrl}${endpoint}`, {
+        log('Sending %s to %s', cmd.constructor?.name, url);
+        return requestJson(url, {
             method: 'POST',
             headers: {
                 'Content-Type': 'application/json',

package/dist/maps/createTransformRequest.d.ts

@@ -3,6 +3,8 @@ import type { RequestTransformFunction } from 'maplibre-gl';
  * Creates a transformRequest function for MapLibre that adds authentication
  * and proper Accept headers for AWS Location Service API requests.
  *
+ * The token is attached to our own API and nowhere else — see isOurApi.
+ *
  * @param apiUrl - Base URL of the Location Service API
  * @param getToken - Callback function that returns the current auth token
  * @returns MapLibre transformRequest function

package/dist/maps/createTransformRequest.js

@@ -1,14 +1,58 @@
+/**
+ * Does this URL belong to our API?
+ *
+ * This decides who receives the customer's bearer token, and it used to be
+ * `url.startsWith(apiUrl)` — a string test standing in for a URL test. For
+ * `apiUrl = "https://api.example.com"`, the host `api.example.com.evil.test`
+ * is a prefix match, so a style referencing
+ * `https://api.example.com.evil.test/tiles/1/2/3` was handed
+ * `Authorization: Bearer <token>` and the token left the building (#34).
+ *
+ * That is reachable because a style descriptor is DATA: its `sprite`, `glyphs`
+ * and `sources` entries are URLs the style author chose, and MapLibre asks
+ * transformRequest about every one of them. Any style not wholly ours — a
+ * customer's own, or one edited through a tool — can name a host it likes.
+ *
+ * Compared as URLs instead, which also gets host case-folding, default ports
+ * (`https://api.test:443` === `https://api.test`) and userinfo right for free,
+ * and adds a path check so a shared host serving another tenant under a
+ * different base path is not "ours" either.
+ *
+ * Fails CLOSED: anything that will not parse gets no token. The only way to
+ * reach that is a relative `apiUrl` in a runtime with no `location` to resolve
+ * it against — i.e. not a browser, which is the only place MapLibre runs.
+ */
+function isOurApi(url, apiUrl) {
+    const base = typeof location === 'undefined' ? undefined : location.href;
+    let ours;
+    let theirs;
+    try {
+        ours = new URL(apiUrl, base);
+        theirs = new URL(url, base);
+    }
+    catch {
+        return false;
+    }
+    if (theirs.origin !== ours.origin)
+        return false;
+    // Trailing slashes normalised so `/v1` and `/v1/` behave the same; the `/`
+    // boundary is what stops `/v1` from matching `/v1-internal`.
+    const basePath = ours.pathname.replace(/\/+$/, '');
+    return (theirs.pathname === basePath || theirs.pathname.startsWith(`${basePath}/`));
+}
 /**
  * Creates a transformRequest function for MapLibre that adds authentication
  * and proper Accept headers for AWS Location Service API requests.
  *
+ * The token is attached to our own API and nowhere else — see isOurApi.
+ *
  * @param apiUrl - Base URL of the Location Service API
  * @param getToken - Callback function that returns the current auth token
  * @returns MapLibre transformRequest function
  */
 export function createTransformRequest(apiUrl, getToken) {
     return (url, _resourceType) => {
-        if (url.startsWith(apiUrl)) {
+        if (isOurApi(url, apiUrl)) {
             const token = getToken();
             if (!token) {
                 console.warn('[createTransformRequest] No token available');

package/dist/server/LocationServiceConnector.d.ts

@@ -1,15 +1,35 @@
 import type { RequestOptions } from '../transport/http.js';
 import type { AppConfigClaims } from '../utils/tokenClaims.js';
 export interface ConnectorConfig {
+    /** Falls back to `LOCATION_API_URL` / `LOCATION_SERVICE_API_URL`. */
     apiUrl?: string;
+    /**
+     * A fixed token. Nothing can refresh it, so it dies at its own `exp` — pass
+     * `getToken` instead, or nothing at all, for a connector that keeps working.
+     */
     token?: string;
-    getToken?: () => Promise<{
-        token: string;
-    }>;
+    /**
+     * Where a token comes from. Called for every request, so this is what makes
+     * a long-lived connector survive expiry.
+     *
+     * `forceRefresh` is passed as `true` when the API has just rejected the token
+     * this returned — the signature is `TokenProvider.getToken`'s exactly, so
+     * `getToken: (f) => provider.getToken(f)` is a complete implementation.
+     */
+    getToken?: (forceRefresh?: boolean) => Promise<string | {
+        token?: string;
+    } | undefined>;
+    /** Falls back to `LOCATION_CLIENT_ID` / `LOCATION_SERVICE_CLIENT_ID`. */
+    clientId?: string;
+    /** Falls back to `LOCATION_CLIENT_SECRET` / `LOCATION_SERVICE_CLIENT_SECRET`. */
+    clientSecret?: 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.
+     *
+     * Falls back to `LOCATION_ORIGIN` / `LOCATION_SERVICE_ORIGIN`, so the
+     * zero-argument connector can be made to work from the environment alone.
      */
     origin?: string;
 }
@@ -23,19 +43,38 @@ export interface SendOptions extends RequestOptions {
  * token management, and the same transport (timeout, cancellation, retry) as the
  * browser client.
  *
+ * Configuration is COMPLETED from the environment rather than replaced by it.
+ * The constructor used to be all-or-nothing — any argument at all took the
+ * "caller supplies everything" branch — so `new LocationServiceConnector()` had
+ * credentials but could never send an Origin (403 on every data request) and
+ * `new LocationServiceConnector({ origin })` had an Origin but no credentials
+ * (#45). Now an explicit `token`/`getToken` still wins outright, and anything
+ * short of that is filled in from `LOCATION_API_URL` / `LOCATION_CLIENT_ID` /
+ * `LOCATION_CLIENT_SECRET` / `LOCATION_ORIGIN`.
+ *
  * @example
  * ```typescript
+ * // Credentials and apiUrl from the environment, Origin supplied here
  * 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?;
+    private readonly config;
+    private tokenSource?;
+    private readonly origin?;
     readonly serviceId: string;
     constructor(config?: ConnectorConfig);
-    /** One place that knows how a token is obtained, so nothing can drift. */
-    private resolveToken;
+    /**
+     * One place that knows how a token is obtained, so nothing can drift.
+     *
+     * Built on first use rather than in the constructor: resolving the
+     * environment path used to start a `/auth/token` round trip from `new`, whose
+     * rejection nothing was awaiting yet — an unhandled rejection for a
+     * misconfigured process, before it had made a single request.
+     */
+    private source;
+    private buildSource;
     /**
      * This application's own configuration, as carried on the access token
      * (api#65) — bias precision, and the countries it is scoped to.
@@ -51,5 +90,15 @@ export declare class LocationServiceConnector {
      * case until one is configured in the portal.
      */
     getAppConfig(): Promise<AppConfigClaims>;
+    /**
+     * The Origin this request will actually carry.
+     *
+     * ONE definition, for the two readers that must never disagree about it: the
+     * header merge in `dispatch`, and the 403 explanation in `send`. A per-call
+     * header beats the connector default, whatever the caller capitalised.
+     */
+    private effectiveOrigin;
     send<TInput, TOutput>(command: TInput, options?: SendOptions): Promise<TOutput>;
+    private dispatchWithRetry;
+    private dispatch;
 }