@chaosity/location-client 0.6.0 → 0.7.0

package/README.md

@@ -69,6 +69,10 @@ Set these environment variables:
 LOCATION_API_URL=https://api.chaosity.cloud
 LOCATION_CLIENT_ID=your-client-id
 LOCATION_CLIENT_SECRET=your-client-secret
+
+# Only for LocationServiceConnector: the Origin sent on every data request.
+# The API answers 403 without one it recognises — see below.
+LOCATION_ORIGIN=https://your-allowed-domain.example
 ```
 
 Or pass credentials explicitly:
@@ -207,6 +211,7 @@ const client = new GeoPlacesClient({
   apiUrl: string,
   token: string,
   getToken?: () => string | undefined, // Optional: dynamic token getter
+  refreshToken?: () => Promise<string | undefined>, // Optional: 401 self-heal
 })
 
 await client.send(command)
@@ -214,6 +219,16 @@ await client.send(command)
 
 When `getToken` is provided, it is called on every request so token updates are reflected without recreating the client.
 
+`refreshToken` covers the case `getToken` cannot. `getToken` is synchronous —
+MapLibre's `transformRequest` requires that — so it can only ever return the
+token already in hand, and a token the API stops accepting **before** its `exp`
+(revoked, or issued against a since-rotated secret) fails every request until
+the refresh buffer elapses. `refreshToken` is awaited after a 401, and the
+request is retried **once** with what it returns. Return the same token, or
+nothing, and no retry is sent — a request that is going to fail again is not
+worth being billed for twice. A 403 is never retried: a new token cannot fix an
+`Origin` the application does not allow.
+
 #### GeoPlaces Adapter
 
 Implements the `MaplibreGeocoderApi` interface for use with `@maplibre/maplibre-gl-geocoder`. Methods are called automatically by the geocoder control.
@@ -351,8 +366,19 @@ import { getClientConfig } from '@chaosity/location-client/server'
 
 const config = await getClientConfig()
 // { apiUrl: string, token: string, expiresAt?: number }
+
+// The API has rejected a token that has not reached its exp — revoked in the
+// portal, or issued against a client secret that has since been rotated.
+const replacement = await getClientConfig({ forceRefresh: true })
 ```
 
+The return value is **plain data** — no methods, no closures — so it can be
+returned straight out of a Next.js Server Action to a Client Component. It is
+therefore a snapshot: the token in it stops working at its `expiresAt`, and the
+caller asks for another. For a long-lived server process that should just keep
+working, use `LocationServiceConnector`, which holds a live token source and
+refreshes for you.
+
 #### TokenProvider
 
 Lower-level token management with caching and deduplication.
@@ -371,14 +397,18 @@ const { success, token, expiresAt } = await provider.getToken()
 
 #### LocationServiceConnector
 
-Server-side connector for backend-to-backend API calls. Can auto-configure from environment variables when no config is passed.
+Server-side connector for backend-to-backend API calls. It **completes** its
+configuration from the environment rather than replacing it, so you supply only
+the parts the environment does not have:
 
 ```typescript
 import { LocationServiceConnector } from '@chaosity/location-client/server'
 
+// apiUrl + credentials from LOCATION_API_URL / LOCATION_CLIENT_ID /
+// LOCATION_CLIENT_SECRET; Origin from here. Set LOCATION_ORIGIN as well and
+// `new LocationServiceConnector()` needs no arguments at all.
 const connector = new LocationServiceConnector({
-  apiUrl: config.apiUrl,
-  token: config.token,
+  origin: 'https://your-allowed-domain.example',
 })
 
 const result = await connector.send(
@@ -386,9 +416,34 @@ const result = await connector.send(
 )
 ```
 
+**Every data request needs an `Origin` the service recognises, and the API
+answers 403 without one** — server-to-server calls included, not just browsers.
+In a browser the browser sets it; here you do, with `origin` above,
+`LOCATION_ORIGIN`, or a per-call header (`send(cmd, { headers: { Origin } })`,
+which wins over both). `/auth/token` is the one endpoint exempt.
+
+A connector configured this way keeps working indefinitely: it holds a live
+token source, refreshes before expiry, and retries once with a new token if the
+API rejects the one it sent. Pass an explicit `token` instead and you opt out of
+all of that — it is a fixed string, and it dies at its own `exp`:
+
+```typescript
+// Managing credentials yourself: an explicit token source wins outright, and
+// the environment is not consulted.
+const connector = new LocationServiceConnector({
+  apiUrl,
+  origin: 'https://your-allowed-domain.example',
+  getToken: (forceRefresh) => provider.getToken(forceRefresh),
+})
+```
+
 ## Cache-Friendly Position Rounding
 
-`BiasPosition` coordinates are automatically rounded to 2 decimal places (~1.1 km grid) before each API request. This maximizes cache hits across nearby users without affecting result quality — bias is approximate by nature.
+`BiasPosition` coordinates are automatically rounded before each API request, to
+whatever precision your application is entitled to — a `biasDecimals` claim on
+the access token, defaulting to **3 decimal places** (~110 m) when the token
+carries none. This maximizes cache hits across nearby users without affecting
+result quality — bias is approximate by nature.
 
 `QueryPosition` (reverse geocode) retains full precision since it represents an exact point the user selected.
 

package/dist/cjs/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/cjs/client/GeoPlacesClient.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.GeoPlacesClient = void 0;
 const debug_1 = __importDefault(require("debug"));
 const endpoints_js_1 = require("../transport/endpoints.js");
+const errors_js_1 = require("../transport/errors.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");
@@ -38,8 +39,11 @@ class GeoPlacesClient {
      * case until one is configured in the portal.
      */
     getAppConfig() {
-        const token = this.clientConfig.getToken?.() ?? this.clientConfig.token;
-        return (0, tokenClaims_js_1.readAppConfigClaims)(token);
+        return (0, tokenClaims_js_1.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`
@@ -47,15 +51,35 @@ class GeoPlacesClient {
      */
     async send(command, options) {
         const cmd = command;
-        const endpoint = (0, endpoints_js_1.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}${(0, endpoints_js_1.resolveEndpoint)(cmd)}`;
+        const token = this.currentToken();
+        try {
+            return await this.dispatch(url, token, cmd, options);
+        }
+        catch (err) {
+            if (!(0, errors_js_1.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 } = (0, tokenClaims_js_1.readAppConfigClaims)(token);
         const input = (0, roundPosition_js_1.roundPositionFields)(cmd.input, biasDecimals);
-        log('Sending %s to %s', cmd.constructor?.name, endpoint);
-        return (0, http_js_1.requestJson)(`${this.clientConfig.apiUrl}${endpoint}`, {
+        log('Sending %s to %s', cmd.constructor?.name, url);
+        return (0, http_js_1.requestJson)(url, {
             method: 'POST',
             headers: {
                 'Content-Type': 'application/json',

package/dist/cjs/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/cjs/maps/createTransformRequest.js

@@ -1,17 +1,61 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createTransformRequest = createTransformRequest;
+/**
+ * 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
  */
 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/cjs/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;
 }

package/dist/cjs/server/LocationServiceConnector.js

@@ -7,11 +7,68 @@ 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 errors_js_1 = require("../transport/errors.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');
+/** Header lookup that does not care how the caller capitalised the name. */
+function headerValue(headers, name) {
+    if (!headers)
+        return undefined;
+    const wanted = name.toLowerCase();
+    for (const [key, value] of Object.entries(headers)) {
+        if (key.toLowerCase() === wanted)
+            return value;
+    }
+    return undefined;
+}
+/**
+ * The headers `dispatch` sets itself, and which a caller therefore cannot
+ * supply. Lower-case, because that is how they are compared.
+ *
+ * Kept beside `withoutHeaders` so the list and the record in `dispatch` cannot
+ * drift apart: a header added there must be added here too, or the caller's own
+ * spelling of it survives the merge.
+ */
+const SYSTEM_HEADERS = ['origin', 'content-type', 'authorization'];
+/** The caller's headers minus `names`, however they capitalised them. */
+function withoutHeaders(headers, names) {
+    if (!headers)
+        return {};
+    const wanted = new Set(names);
+    return Object.fromEntries(Object.entries(headers).filter(([key]) => !wanted.has(key.toLowerCase())));
+}
+/**
+ * Say why the 403 happened, when we know.
+ *
+ * `Origin not allowed` with no Origin sent is not an ambiguous failure — it is
+ * the documented backend path missing one piece of configuration (#45), and the
+ * API's own message cannot say so because from its side the header is simply
+ * absent. A new integrator following the README hit a bare "Origin not allowed"
+ * that named neither the cause nor the fix.
+ */
+function explainMissingOrigin(err, sentOrigin) {
+    if (sentOrigin)
+        return err;
+    if (!(err instanceof LocationServiceException_js_1.LocationServiceException))
+        return err;
+    if (err.code !== 'OriginNotAllowedException')
+        return err;
+    return new LocationServiceException_js_1.LocationServiceException({
+        code: err.code,
+        message: `${err.message} — this request carried no Origin header, and the API requires ` +
+            `one it recognises on every data request. Set \`origin\` on the ` +
+            `LocationServiceConnector, set LOCATION_ORIGIN, or pass an Origin in the ` +
+            `per-call headers; if the application has no allowed domain configured in ` +
+            `the developer portal yet, set that first.`,
+        statusCode: err.statusCode,
+        requestId: err.requestId,
+        details: err.details,
+        cause: err,
+    });
+}
 /**
  * LocationServiceConnector — server-side connector for the Location Service API.
  *
@@ -19,28 +76,79 @@ const log = (0, debug_1.default)('location-client:connector');
  * 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' }))
  * ```
  */
 class LocationServiceConnector {
-    constructor(config) {
+    constructor(config = {}) {
         this.serviceId = 'Geo Places';
-        this.configPromise = config ? Promise.resolve(config) : (0, getClientConfig_js_1.getClientConfig)();
-        this.origin = config?.origin;
+        this.config = config;
+        // `||`, not `??`, to match the other four env-completed fields: an empty
+        // string is not a choice to send no Origin, it is a missing value, and the
+        // asymmetry meant `origin: ''` suppressed the environment and then produced
+        // an error telling the caller to set a variable they may already have set.
+        this.origin =
+            config.origin ||
+                process.env.LOCATION_ORIGIN ||
+                process.env.LOCATION_SERVICE_ORIGIN;
+    }
+    /**
+     * 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.
+     */
+    source() {
+        return (this.tokenSource ?? (this.tokenSource = this.buildSource()));
     }
-    /** 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;
+    buildSource() {
+        const { apiUrl, token, getToken, clientId, clientSecret } = this.config;
+        // An explicit token source wins outright. A caller that supplied one is
+        // managing credentials itself, and quietly reading the environment
+        // underneath it could send another application's token.
+        if (getToken) {
+            return {
+                apiUrl: () => requireApiUrl(apiUrl),
+                get: async (forceRefresh) => {
+                    const result = await getToken(forceRefresh);
+                    if (!result)
+                        return undefined;
+                    return typeof result === 'string' ? result : result.token;
+                },
+            };
+        }
+        if (token) {
+            return {
+                apiUrl: () => requireApiUrl(apiUrl),
+                // A fixed string. Asking again returns the same one, which is how the
+                // retry guard knows there is nothing to retry with.
+                get: async () => token,
+            };
         }
-        return config.token;
+        // Nothing but (at most) an apiUrl and an origin — complete it from the
+        // environment. This is the branch every sample and doc actually takes.
+        const env = (0, getClientConfig_js_1.serverTokenSource)({ apiUrl, clientId, clientSecret });
+        return {
+            // Already validated by serverTokenSource, which cannot resolve
+            // credentials without it.
+            apiUrl: () => env.apiUrl,
+            get: async (forceRefresh) => (await env.getToken(forceRefresh)).token,
+        };
     }
     /**
      * This application's own configuration, as carried on the access token
@@ -57,35 +165,106 @@ class LocationServiceConnector {
      * case until one is configured in the portal.
      */
     async getAppConfig() {
-        return (0, tokenClaims_js_1.readAppConfigClaims)(await this.resolveToken());
+        return (0, tokenClaims_js_1.readAppConfigClaims)(await this.source().get());
+    }
+    /**
+     * 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.
+     */
+    effectiveOrigin(options) {
+        // `||` for the same reason as the constructor: an empty per-call header is
+        // a missing value, not a decision to send no Origin.
+        return headerValue(options?.headers, 'origin') || this.origin;
     }
     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 source = this.source();
         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 url = `${source.apiUrl()}${(0, endpoints_js_1.resolveEndpoint)(cmd)}`;
+        try {
+            return await this.dispatchWithRetry(source, url, cmd, options);
+        }
+        catch (err) {
+            throw explainMissingOrigin(err, this.effectiveOrigin(options));
+        }
+    }
+    async dispatchWithRetry(source, url, cmd, options) {
+        const token = await source.get();
+        if (!token)
+            throw noTokenAvailable();
+        try {
+            return await this.dispatch(url, token, cmd, options);
+        }
+        catch (err) {
+            if (!(0, errors_js_1.isTokenRejected)(err))
+                throw err;
+            // One retry, and only when the replacement is genuinely a different
+            // token. That single comparison covers every source: a fixed `token`
+            // string, a caller `getToken` that ignores `forceRefresh`, and a cached
+            // token the API has revoked before its `exp` all hand back what we
+            // already sent — and re-sending it would be a second doomed request, and
+            // a second billed one.
+            const fresh = await source.get(true);
+            if (!fresh || fresh === token)
+                throw err;
+            log('401 on a token the API no longer accepts — retrying once, refreshed');
+            return await this.dispatch(url, fresh, cmd, options);
+        }
+    }
+    dispatch(url, token, cmd, options) {
+        // The token is resolved before the request is shaped, so the precision this
+        // application is entitled to is available (api#65). Absent claim -> the
+        // 3 dp floor, which is what every application gets until one is configured
+        // otherwise. Recomputed per attempt because a refreshed token may carry
+        // different claims.
         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.
+        // Every system header is set exactly ONCE, and the caller's own spelling of
+        // each is dropped first.
+        //
+        // Spreading them over the caller's record is not enough, because fetch's
+        // Headers fill APPENDS rather than replaces: a caller's lowercase key
+        // survives beside the canonical one and both go on the wire. For Origin
+        // that produced `Origin: default, per-call`, which the API's exact-match
+        // domain check rejects (observed: 403 OriginNotAllowedException) — and two
+        // keys with the SAME value fared no better, `Origin: x, x`. For
+        // Authorization it is worse than a failed override: `{ authorization:
+        // 'Bearer not-yours' }` went out as `Bearer not-yours, Bearer <real>`,
+        // corrupting the token rather than being ignored by it.
+        //
+        // Origin's value comes from `effectiveOrigin`, so a per-call header still
+        // beats the connector default — it is the DUPLICATE that is removed, not
+        // the caller's intent.
+        const origin = this.effectiveOrigin(options);
         const headers = {
-            ...(this.origin ? { Origin: this.origin } : {}),
-            ...(options?.headers ?? {}),
+            ...withoutHeaders(options?.headers, SYSTEM_HEADERS),
+            ...(origin ? { Origin: origin } : {}),
             '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);
+        log('Sending %s request to %s', cmd.constructor?.name, url);
+        return (0, http_js_1.requestJson)(url, { method: 'POST', headers, body: JSON.stringify(input) }, options);
     }
 }
 exports.LocationServiceConnector = LocationServiceConnector;
+function requireApiUrl(explicit) {
+    const apiUrl = (0, getClientConfig_js_1.resolveApiUrl)(explicit);
+    if (!apiUrl) {
+        throw new LocationServiceException_js_1.LocationServiceException({
+            code: 'ValidationException',
+            message: 'No API URL. Pass `apiUrl` to the LocationServiceConnector constructor ' +
+                'or set LOCATION_API_URL.',
+            details: { source: 'client' },
+        });
+    }
+    return apiUrl;
+}
+function noTokenAvailable() {
+    return new LocationServiceException_js_1.LocationServiceException({
+        code: 'InvalidCredentialsException',
+        message: 'No token available — check clientId/clientSecret configuration',
+        details: { source: 'client' },
+    });
+}