@chaosity/location-client 0.5.0 → 0.6.0

package/dist/cjs/maps/mapLanguage.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.languageExpression = languageExpression;
+exports.labelsByName = labelsByName;
+exports.applyMapLanguage = applyMapLanguage;
+/**
+ * The `text-field` expression that prefers `language`, then English, then the
+ * feature's default name.
+ *
+ * Based on the approach documented at:
+ * https://docs.aws.amazon.com/location/latest/developerguide/how-to-set-preferred-language-map.html
+ */
+function languageExpression(language) {
+    return language === 'en'
+        ? ['coalesce', ['get', 'name:en'], ['get', 'name']]
+        : [
+            'coalesce',
+            ['get', `name:${language}`],
+            ['get', 'name:en'],
+            ['get', 'name'],
+        ];
+}
+/**
+ * Whether a `text-field` reads a name property — the only kind of label a
+ * language rewrite makes sense for (#28).
+ *
+ * The AWS Standard style has 62 symbol layers with a text-field and 30 of
+ * them do NOT label by name: `building_label_number` reads
+ * `addr_housenumber`, and the 29 `shield_*` layers read `shield_text` or
+ * `ref`. Replacing those with a `name:<lang>` coalesce points them at a
+ * property their features do not carry, and the house numbers and road
+ * shields disappear — for `en` too. Measured against the live sandbox on
+ * 2026-08-29; the testbed showed it as "one map has house numbers, the
+ * others don't".
+ *
+ * Serialising the expression is the simplest exact test: `name`, `name:en`,
+ * `name_en` and a literal `{name}` template all contain it, and none of the
+ * non-name properties do.
+ */
+function labelsByName(textField) {
+    return JSON.stringify(textField)?.includes('name') ?? false;
+}
+/**
+ * Apply a preferred display language to the name labels on a MapLibre map.
+ *
+ * AWS GeoMaps vector tiles carry `name:${lang}` properties (`name:en`,
+ * `name:fr`, `name:ja`, …). Every symbol layer whose `text-field` reads a
+ * name is rewritten to prefer the requested language, falling back to
+ * English then the default name. Layers that label by something else — house
+ * numbers, road shields — are left exactly as the style declared them.
+ *
+ * @param map - MapLibre Map instance (or any object matching the MapLike interface)
+ * @param language - ISO 639-1 language code (e.g. 'en', 'fr', 'de', 'ja', 'zh', 'ar')
+ *
+ * @example
+ * map.once('style.load', () => applyMapLanguage(map, 'fr'))
+ */
+function applyMapLanguage(map, language) {
+    try {
+        const expression = languageExpression(language);
+        map.getStyle().layers.forEach((layer) => {
+            if (layer.type !== 'symbol')
+                return;
+            const textField = map.getLayoutProperty(layer.id, 'text-field');
+            if (textField === undefined || textField === null)
+                return;
+            if (!labelsByName(textField))
+                return;
+            map.setLayoutProperty(layer.id, 'text-field', expression);
+        });
+    }
+    catch {
+        // Style may not be fully loaded — call after 'style.load' event
+    }
+}

package/dist/cjs/maps/mapPoi.d.ts

@@ -0,0 +1,44 @@
+import type { Map } from 'maplibre-gl';
+/**
+ * Mapping of POI category names to their MapLibre layer IDs in AWS GeoMaps tiles.
+ * Layer IDs are stable across Standard, Monochrome, and Hybrid map styles.
+ */
+export declare const POI_CATEGORIES: {
+    readonly food_drink: readonly ["poi_100_food_drink"];
+    readonly entertainment: readonly ["poi_200_going_out_entertainment"];
+    readonly sights: readonly ["poi_300_sights_museums"];
+    readonly transit: readonly ["poi_400_transit"];
+    readonly accommodations: readonly ["poi_500_accommodations"];
+    readonly leisure: readonly ["poi_550_leisure_outdoor"];
+    readonly shopping: readonly ["poi_600_shopping"];
+    readonly business: readonly ["poi_700_business_services"];
+    readonly facilities: readonly ["poi_800_facilities"];
+    readonly areas: readonly ["poi_900_areas_buildings"];
+    readonly parks: readonly ["poi_landuse_park", "poi_landuse_public_complex"];
+};
+export type PoiCategory = keyof typeof POI_CATEGORIES;
+/**
+ * Set the visibility of one or more POI categories on the map.
+ *
+ * @param map - MapLibre Map instance
+ * @param category - POI category key or array of keys
+ * @param visible - Whether to show (true) or hide (false) the category
+ *
+ * @example
+ * // Hide transit and shopping POIs
+ * setPoiVisibility(map, ['transit', 'shopping'], false)
+ *
+ * // Show all food & drink POIs
+ * setPoiVisibility(map, 'food_drink', true)
+ */
+export declare function setPoiVisibility(map: Map, category: PoiCategory | PoiCategory[], visible: boolean): void;
+/**
+ * Show or hide all POI layers at once.
+ *
+ * @param map - MapLibre Map instance
+ * @param visible - Whether to show or hide all POIs
+ *
+ * @example
+ * setAllPoiVisibility(map, false) // hide everything
+ */
+export declare function setAllPoiVisibility(map: Map, visible: boolean): void;

package/dist/cjs/maps/mapPoi.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.POI_CATEGORIES = void 0;
+exports.setPoiVisibility = setPoiVisibility;
+exports.setAllPoiVisibility = setAllPoiVisibility;
+/**
+ * Mapping of POI category names to their MapLibre layer IDs in AWS GeoMaps tiles.
+ * Layer IDs are stable across Standard, Monochrome, and Hybrid map styles.
+ */
+exports.POI_CATEGORIES = {
+    food_drink: ['poi_100_food_drink'],
+    entertainment: ['poi_200_going_out_entertainment'],
+    sights: ['poi_300_sights_museums'],
+    transit: ['poi_400_transit'],
+    accommodations: ['poi_500_accommodations'],
+    leisure: ['poi_550_leisure_outdoor'],
+    shopping: ['poi_600_shopping'],
+    business: ['poi_700_business_services'],
+    facilities: ['poi_800_facilities'],
+    areas: ['poi_900_areas_buildings'],
+    parks: ['poi_landuse_park', 'poi_landuse_public_complex'],
+};
+/**
+ * Set the visibility of one or more POI categories on the map.
+ *
+ * @param map - MapLibre Map instance
+ * @param category - POI category key or array of keys
+ * @param visible - Whether to show (true) or hide (false) the category
+ *
+ * @example
+ * // Hide transit and shopping POIs
+ * setPoiVisibility(map, ['transit', 'shopping'], false)
+ *
+ * // Show all food & drink POIs
+ * setPoiVisibility(map, 'food_drink', true)
+ */
+function setPoiVisibility(map, category, visible) {
+    const categories = Array.isArray(category) ? category : [category];
+    const visibility = visible ? 'visible' : 'none';
+    for (const cat of categories) {
+        for (const layerId of exports.POI_CATEGORIES[cat]) {
+            try {
+                if (map.getLayer(layerId)) {
+                    map.setLayoutProperty(layerId, 'visibility', visibility);
+                }
+            }
+            catch {
+                // Layer may not exist in the current map style
+            }
+        }
+    }
+}
+/**
+ * Show or hide all POI layers at once.
+ *
+ * @param map - MapLibre Map instance
+ * @param visible - Whether to show or hide all POIs
+ *
+ * @example
+ * setAllPoiVisibility(map, false) // hide everything
+ */
+function setAllPoiVisibility(map, visible) {
+    setPoiVisibility(map, Object.keys(exports.POI_CATEGORIES), visible);
+}

package/dist/cjs/maps/mapStyle.d.ts

@@ -0,0 +1,77 @@
+import type { StyleSpecification } from 'maplibre-gl';
+import type { Buildings, ColorScheme, ContourDensity, MapStyle, Terrain, TrafficMode, TravelMode } from './mapEnums.js';
+/**
+ * Options for building an AWS Location Service map style URL.
+ * All parameters map directly to query parameters supported by the style descriptor endpoint.
+ *
+ * Values are CASE SENSITIVE — the API rejects a wrong-cased one with a 400 that
+ * names the right spelling. Import the arrays from `mapEnums` to build pickers
+ * rather than typing the values, and the case is right by construction.
+ */
+export interface MapStyleOptions {
+    /** Color scheme for the map (default: Light). Not applicable to Satellite/Hybrid styles. */
+    colorScheme?: ColorScheme;
+    /** ISO 3166-1 alpha-3 country code for political boundary perspective (e.g. 'IND', 'TUR'). */
+    politicalView?: string;
+    /** Terrain overlay type. */
+    terrain?: Terrain;
+    /** Enable 3D building extrusions. */
+    buildings?: Buildings;
+    /**
+     * Elevation contour line density.
+     *
+     * All of High, Low and Medium work. This was previously typed as `'Medium'`
+     * alone, documented as "the only value currently supported by the AWS SDK",
+     * which was wrong — the other two were confirmed against the live API.
+     */
+    contourDensity?: ContourDensity;
+    /**
+     * Traffic overlay.
+     *
+     * `Congestion` was previously missing here, so it could not be requested from
+     * TypeScript even though the API accepts it.
+     *
+     * Valid on its own, but NOT with every style: `Satellite` + `All` answers
+     * 400 "Traffic is not supported for style." Amazon owns that rule.
+     */
+    traffic?: TrafficMode;
+    /** Travel mode overlays for routing-specific features. */
+    travelModes?: TravelMode[];
+}
+/**
+ * Build a map style descriptor URL for the Location Service API.
+ *
+ * @param apiUrl - Base URL of the Location Service API
+ * @param mapStyle - Map style name (e.g. 'Standard', 'Monochrome', 'Satellite', 'Hybrid')
+ * @param options - Optional style parameters
+ * @returns Full style descriptor URL
+ *
+ * @example
+ * const url = buildMapStyleUrl(API_URL, 'Standard', { colorScheme: 'Dark', terrain: 'Hillshade' })
+ * map.setStyle(url)
+ */
+export declare function buildMapStyleUrl(apiUrl: string, mapStyle: MapStyle, options?: MapStyleOptions): string;
+/**
+ * Fetch the map style descriptor with authentication and apply descriptor-level modifications.
+ *
+ * Language is applied directly to the descriptor's layer definitions before MapLibre ever
+ * processes them, eliminating the visual flash that occurs when modifying layers post-load.
+ * All other style parameters (terrain, traffic, etc.) are passed as query parameters.
+ *
+ * The returned style object can be passed directly to `new maplibregl.Map({ style })` or
+ * `map.setStyle()`. Tile, glyph, and sprite requests still go through `transformRequest`
+ * for authentication — this only pre-processes the descriptor itself.
+ *
+ * @param apiUrl - Base URL of the Location Service API
+ * @param mapStyle - Map style name (e.g. 'Standard', 'Monochrome', 'Satellite', 'Hybrid')
+ * @param getToken - Callback returning the current auth token
+ * @param options - Style options; `language` is applied to the descriptor, all others become URL params
+ * @returns Modified MapLibre StyleSpecification object
+ *
+ * @example
+ * const style = await fetchMapStyle(API_URL, 'Standard', getToken, { colorScheme: 'Dark', language: 'fr' })
+ * const map = new maplibregl.Map({ style, transformRequest: createTransformRequest(API_URL, getToken) })
+ */
+export declare function fetchMapStyle(apiUrl: string, mapStyle: MapStyle, getToken: () => string | undefined, options?: MapStyleOptions & {
+    language?: string;
+}): Promise<StyleSpecification>;

package/dist/cjs/maps/mapStyle.js

@@ -0,0 +1,111 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildMapStyleUrl = buildMapStyleUrl;
+exports.fetchMapStyle = fetchMapStyle;
+const errors_js_1 = require("../transport/errors.js");
+const mapLanguage_js_1 = require("./mapLanguage.js");
+/**
+ * Build a map style descriptor URL for the Location Service API.
+ *
+ * @param apiUrl - Base URL of the Location Service API
+ * @param mapStyle - Map style name (e.g. 'Standard', 'Monochrome', 'Satellite', 'Hybrid')
+ * @param options - Optional style parameters
+ * @returns Full style descriptor URL
+ *
+ * @example
+ * const url = buildMapStyleUrl(API_URL, 'Standard', { colorScheme: 'Dark', terrain: 'Hillshade' })
+ * map.setStyle(url)
+ */
+function buildMapStyleUrl(apiUrl, mapStyle, options = {}) {
+    const params = new URLSearchParams();
+    if (options.colorScheme)
+        params.set('color-scheme', options.colorScheme);
+    if (options.politicalView)
+        params.set('political-view', options.politicalView);
+    if (options.terrain)
+        params.set('terrain', options.terrain);
+    if (options.buildings)
+        params.set('buildings', options.buildings);
+    if (options.contourDensity)
+        params.set('contour-density', options.contourDensity);
+    if (options.traffic)
+        params.set('traffic', options.traffic);
+    if (options.travelModes?.length)
+        params.set('travel-modes', options.travelModes.join(','));
+    const qs = params.toString();
+    return `${apiUrl}/maps/${mapStyle}/descriptor${qs ? `?${qs}` : ''}`;
+}
+/**
+ * Fetch the map style descriptor with authentication and apply descriptor-level modifications.
+ *
+ * Language is applied directly to the descriptor's layer definitions before MapLibre ever
+ * processes them, eliminating the visual flash that occurs when modifying layers post-load.
+ * All other style parameters (terrain, traffic, etc.) are passed as query parameters.
+ *
+ * The returned style object can be passed directly to `new maplibregl.Map({ style })` or
+ * `map.setStyle()`. Tile, glyph, and sprite requests still go through `transformRequest`
+ * for authentication — this only pre-processes the descriptor itself.
+ *
+ * @param apiUrl - Base URL of the Location Service API
+ * @param mapStyle - Map style name (e.g. 'Standard', 'Monochrome', 'Satellite', 'Hybrid')
+ * @param getToken - Callback returning the current auth token
+ * @param options - Style options; `language` is applied to the descriptor, all others become URL params
+ * @returns Modified MapLibre StyleSpecification object
+ *
+ * @example
+ * const style = await fetchMapStyle(API_URL, 'Standard', getToken, { colorScheme: 'Dark', language: 'fr' })
+ * const map = new maplibregl.Map({ style, transformRequest: createTransformRequest(API_URL, getToken) })
+ */
+async function fetchMapStyle(apiUrl, mapStyle, getToken, options = {}) {
+    const { language, ...styleOptions } = options;
+    const url = buildMapStyleUrl(apiUrl, mapStyle, styleOptions);
+    const token = getToken();
+    const response = await fetch(url, {
+        headers: {
+            Authorization: `Bearer ${token}`,
+            Accept: 'application/json',
+        },
+    });
+    if (!response.ok) {
+        // Read the body. The API sends `{message, code, requestId}` and the message
+        // is the whole point of it — for a style request it is Amazon's own
+        // sentence, forwarded verbatim by location-service-api#89:
+        //
+        //   400 "Traffic is not supported for style."
+        //   400 "light is not a supported color scheme for style Standard."
+        //
+        // This used to throw `Failed to fetch map style: 400`, discarding all of it
+        // two lines before anyone could read it — the same defect #89 fixed in the
+        // API, one layer up. Reuses parseErrorResponse so a style failure arrives as
+        // the same LocationServiceException as every other call in this package,
+        // with `code`, `statusCode` and `requestId` intact.
+        throw (0, errors_js_1.parseErrorResponse)(response.status, response.statusText, await response.text(), response.headers);
+    }
+    const style = (await response.json());
+    if (language) {
+        applyLanguageToDescriptor(style, language);
+    }
+    return style;
+}
+/**
+ * Apply a preferred language to the name labels within a style descriptor.
+ * Mutates the style in place — call before passing to MapLibre.
+ *
+ * Only a `text-field` that reads a name property is rewritten. House numbers
+ * (`addr_housenumber`) and road shields (`shield_text`) used to be rewritten
+ * too, and vanished from every map that asked for a language (#28); the rule
+ * lives in `labelsByName` so this and `applyMapLanguage` cannot disagree.
+ */
+function applyLanguageToDescriptor(style, language) {
+    const expression = (0, mapLanguage_js_1.languageExpression)(language);
+    for (const layer of style.layers) {
+        if (layer.type !== 'symbol')
+            continue;
+        const layout = layer.layout;
+        if (layout?.['text-field'] === undefined)
+            continue;
+        if (!(0, mapLanguage_js_1.labelsByName)(layout['text-field']))
+            continue;
+        layout['text-field'] = expression;
+    }
+}

package/dist/cjs/maps/staticMap.d.ts

@@ -0,0 +1,85 @@
+import type { ColorScheme, LabelSize, MapFeatureMode, ScaleBarUnit, StaticMapStyle } from './mapEnums.js';
+/**
+ * Static maps: build the URL, send the right headers, get a Blob.
+ *
+ * This exists because `/maps/static/{fileName}` is the one map route MapLibre
+ * never requests, so `createTransformRequest` never sees it and every caller was
+ * left to hand-roll the fetch. Ours did — `nextjs-address-finder-full`'s
+ * NearbySearch.tsx carried a comment explaining the rule — which is the clearest
+ * sign it belonged in the library (client#25, api#35).
+ *
+ * Two things make a plain fetch fail, and neither is discoverable:
+ *
+ * 1. `Accept` MUST name the exact type. Measured against the sandbox on
+ *    2026-08-26: `image/png` -> 200, while `image/*`, `*\/*`, and the header a
+ *    browser sends for `<img>` all -> 406. Not even `image/*` is enough.
+ *
+ * 2. The type follows the STYLE, not the file name, and the default is
+ *    Satellite:
+ *
+ *      Standard   -> image/png
+ *      Satellite  -> image/jpeg   <- the default when `style` is omitted
+ *
+ *    So the naive `Accept: image/png` is wrong for the DEFAULT request. The API
+ *    hit the mirror image of this bug itself: it hard-coded image/png on the
+ *    response and labelled every default render — a JPEG — as a PNG.
+ *
+ * `<img src="...">` cannot be made to work: it sends neither `Authorization` nor
+ * an acceptable `Accept`. Fetching to a Blob is the only viable shape, which is
+ * why this returns one rather than a URL.
+ */
+/** `map`, or `map@2x` for a retina render. There is no file extension. */
+export type StaticMapFileName = 'map' | 'map@2x';
+export interface StaticMapOptions {
+    /** Pixels, 64-1500. */
+    width: number;
+    /** Pixels, 64-1500. */
+    height: number;
+    /** `[longitude, latitude]`. */
+    center?: [number, number];
+    /** `[west, south, east, north]`. */
+    boundingBox?: [number, number, number, number];
+    /** Positions the render must contain, as `[lng, lat]` pairs. */
+    boundedPositions?: Array<[number, number]>;
+    zoom?: number;
+    radius?: number;
+    padding?: number;
+    cropLabels?: boolean;
+    style?: StaticMapStyle;
+    colorScheme?: ColorScheme;
+    labelSize?: LabelSize;
+    /**
+     * `Enabled` | `Disabled` -- NOT a list of categories. api#35 records this
+     * being passed as a string array against the SDK's Enabled|Disabled type,
+     * working only by stringification. Typed here so that cannot recur.
+     */
+    pointsOfInterests?: MapFeatureMode;
+    scaleBarUnit?: ScaleBarUnit;
+    /** Defaults to `map`. */
+    fileName?: StaticMapFileName;
+}
+/**
+ * The Accept header this request must send.
+ *
+ * Exported because it is the one rule a caller cannot guess, and anyone doing
+ * their own fetch — a server-side render, a proxy — needs it too. Satellite is
+ * the default, so an absent style means JPEG.
+ */
+export declare function staticMapAccept(style?: StaticMapStyle): string;
+/** Build the request URL without fetching it. */
+export declare function buildStaticMapUrl(apiUrl: string, options: StaticMapOptions): string;
+/**
+ * Fetch a static map as a Blob.
+ *
+ * @param apiUrl   Base URL of the Location Service API
+ * @param options  Render options; exactly one of center / boundingBox / boundedPositions
+ * @param getToken Callback returning the current auth token
+ *
+ * @example
+ * const blob = await fetchStaticMap(API_URL, {
+ *   width: 640, height: 400, center: [151.2093, -33.8688], zoom: 14,
+ *   style: 'Standard',
+ * }, getToken)
+ * const url = URL.createObjectURL(blob)   // remember to revokeObjectURL
+ */
+export declare function fetchStaticMap(apiUrl: string, options: StaticMapOptions, getToken: () => string | undefined): Promise<Blob>;

package/dist/cjs/maps/staticMap.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.staticMapAccept = staticMapAccept;
+exports.buildStaticMapUrl = buildStaticMapUrl;
+exports.fetchStaticMap = fetchStaticMap;
+const errors_js_1 = require("../transport/errors.js");
+/**
+ * The Accept header this request must send.
+ *
+ * Exported because it is the one rule a caller cannot guess, and anyone doing
+ * their own fetch — a server-side render, a proxy — needs it too. Satellite is
+ * the default, so an absent style means JPEG.
+ */
+function staticMapAccept(style) {
+    return style === 'Standard' ? 'image/png' : 'image/jpeg';
+}
+/** A coordinate as the API accepts it: at most six decimals, no float noise. */
+const coord = (n) => String(Number(n.toFixed(6)));
+/** Build the request URL without fetching it. */
+function buildStaticMapUrl(apiUrl, options) {
+    const { width, height, center, boundingBox, boundedPositions, fileName = 'map', ...rest } = options;
+    const params = new URLSearchParams({
+        width: String(width),
+        height: String(height),
+    });
+    // Positions go over the wire as comma-separated numbers. api#35 records that
+    // passing arrays straight through worked only by accidental stringification;
+    // doing it explicitly here means the shape is ours, not JavaScript's default.
+    //
+    // Each number is rounded to six decimals (#29). The API caps a coordinate at
+    // fourteen decimals, and a value straight from `map.getCenter()` routinely
+    // has fifteen or sixteen — so the obvious "render what the user is looking
+    // at" was a 400 blaming the FORMAT. Six decimals is ~10 cm, more than a
+    // raster render can show.
+    if (center)
+        params.set('center', center.map(coord).join(','));
+    if (boundingBox)
+        params.set('bounding-box', boundingBox.map(coord).join(','));
+    if (boundedPositions) {
+        params.set('bounded-positions', boundedPositions.flat().map(coord).join(','));
+    }
+    // The API accepts kebab-case on the wire and camelCase for older callers;
+    // kebab is the documented form, so emit that.
+    const KEBAB = { cropLabels: 'crop-labels' };
+    for (const [key, value] of Object.entries(rest)) {
+        if (value === undefined)
+            continue;
+        params.set(KEBAB[key] ?? key, String(value));
+    }
+    return `${apiUrl}/maps/static/${fileName}?${params}`;
+}
+/**
+ * Fetch a static map as a Blob.
+ *
+ * @param apiUrl   Base URL of the Location Service API
+ * @param options  Render options; exactly one of center / boundingBox / boundedPositions
+ * @param getToken Callback returning the current auth token
+ *
+ * @example
+ * const blob = await fetchStaticMap(API_URL, {
+ *   width: 640, height: 400, center: [151.2093, -33.8688], zoom: 14,
+ *   style: 'Standard',
+ * }, getToken)
+ * const url = URL.createObjectURL(blob)   // remember to revokeObjectURL
+ */
+async function fetchStaticMap(apiUrl, options, getToken) {
+    const response = await fetch(buildStaticMapUrl(apiUrl, options), {
+        headers: {
+            Authorization: `Bearer ${getToken()}`,
+            Accept: staticMapAccept(options.style),
+        },
+    });
+    if (!response.ok) {
+        // Same treatment as fetchMapStyle: the API's {message, code, requestId} is
+        // the useful part, and a bare "failed: 400" throws it away. The messages
+        // here are specific and actionable -- "'width' and 'height' are required",
+        // "Only one of center, bounding-box or bounded-positions may be set".
+        throw (0, errors_js_1.parseErrorResponse)(response.status, response.statusText, await response.text());
+    }
+    return response.blob();
+}

package/dist/cjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

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

@@ -0,0 +1,55 @@
+import type { RequestOptions } from '../transport/http.js';
+import type { AppConfigClaims } from '../utils/tokenClaims.js';
+export interface ConnectorConfig {
+    apiUrl?: string;
+    token?: string;
+    getToken?: () => Promise<{
+        token: string;
+    }>;
+    /**
+     * Sent as the `Origin` header on every request. The API requires an Origin it
+     * recognises on every data request and answers 403 without one, so every
+     * caller was setting it by hand on each `send`; this does it once.
+     */
+    origin?: string;
+}
+export interface SendOptions extends RequestOptions {
+    headers?: Record<string, string>;
+}
+/**
+ * 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' }))
+ * ```
+ */
+export declare class LocationServiceConnector {
+    private configPromise;
+    private origin?;
+    readonly serviceId: string;
+    constructor(config?: ConnectorConfig);
+    /** One place that knows how a token is obtained, so nothing can drift. */
+    private resolveToken;
+    /**
+     * 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.
+     */
+    getAppConfig(): Promise<AppConfigClaims>;
+    send<TInput, TOutput>(command: TInput, options?: SendOptions): Promise<TOutput>;
+}