@chaosity/location-client 0.5.1 → 0.7.0

package/dist/cjs/maps/mapEnums.js

@@ -0,0 +1,103 @@
+"use strict";
+/**
+ * The values Amazon Location accepts for each map parameter.
+ *
+ * WHY THESE ARE EXPORTED AS VALUES, NOT JUST TYPES
+ *
+ * A type union gives you compile-time safety and nothing to iterate. Every
+ * consumer that renders a style picker then re-types the same list by hand into
+ * a `<select>`, and those copies drift the moment AWS adds a style. Exporting
+ * the arrays means a dropdown is `MAP_STYLES.map(...)` and cannot disagree with
+ * the type beside it.
+ *
+ * THESE ARE CASE SENSITIVE
+ *
+ * AWS documents them so, and since location-service-api#89 the API enforces it
+ * rather than forwarding a wrong-cased value for Amazon to reject with an
+ * unhelpful 404. `'light'` is not `'Light'`:
+ *
+ *   GET /maps/Standard/descriptor?colorScheme=light
+ *   400  "'colorScheme' is case sensitive — use 'Light', not 'light'"
+ *
+ * So take the values from here rather than typing them, and the case is right
+ * by construction.
+ *
+ * MEMBERSHIP IS NOT THE WHOLE STORY
+ *
+ * A value being in one of these lists does not mean it is legal in every
+ * COMBINATION. `Traffic: 'All'` is valid, and `Style: 'Satellite'` is valid,
+ * but together they are not:
+ *
+ *   400  "Traffic is not supported for style."
+ *
+ * Amazon owns those rules and answers them per request; the API forwards that
+ * message verbatim. Do not try to encode combination rules here — they change
+ * without an SDK release.
+ *
+ * KEEPING THESE HONEST
+ *
+ * The API derives its copy from the AWS SDK's own `enums.d.ts` via
+ * `npm run generate:maps-enums`, so that side cannot drift. This file is the
+ * client-side mirror and every value below was additionally confirmed against
+ * the live geo-maps API on 2026-08-26. If the API starts rejecting something
+ * listed here, its generated list is the authority.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAP_FEATURE_MODES = exports.SCALE_BAR_UNITS = exports.LABEL_SIZES = exports.SPRITE_VARIANTS = exports.TRAVEL_MODES = exports.TRAFFIC_MODES = exports.CONTOUR_DENSITIES = exports.BUILDINGS = exports.TERRAINS = exports.COLOR_SCHEMES = exports.STATIC_MAP_STYLES = exports.MAP_STYLES = void 0;
+/** Map styles for the style descriptor. */
+exports.MAP_STYLES = [
+    'Hybrid',
+    'Monochrome',
+    'Satellite',
+    'Standard',
+];
+/**
+ * Styles the STATIC map accepts — deliberately narrower than `MAP_STYLES`.
+ *
+ * `/maps/static/*` takes only Satellite and Standard. Passing Hybrid or
+ * Monochrome there is a 400, so the two lists are not interchangeable.
+ */
+exports.STATIC_MAP_STYLES = ['Satellite', 'Standard'];
+/** Light or dark cartography. Not applicable to the raster styles. */
+exports.COLOR_SCHEMES = ['Dark', 'Light'];
+/** Terrain overlay. `Hillshade` is shaded relief; `Terrain3D` is elevation. */
+exports.TERRAINS = ['Hillshade', 'Terrain3D'];
+/** 3D building extrusions. One value today, kept a list for when that changes. */
+exports.BUILDINGS = ['Buildings3D'];
+/**
+ * Elevation contour line density.
+ *
+ * All three work. An earlier version of this library documented `Medium` as
+ * "the only value currently supported by the AWS SDK", which was wrong — `High`
+ * and `Low` were both confirmed against the live API on 2026-08-26.
+ */
+exports.CONTOUR_DENSITIES = ['High', 'Low', 'Medium'];
+/**
+ * Traffic overlay.
+ *
+ * `Congestion` was previously missing from this library's types, so it could
+ * not be requested from TypeScript even though the API accepts it.
+ */
+exports.TRAFFIC_MODES = ['All', 'Congestion'];
+/** Routing overlays. Sent as a comma-separated list; each entry is checked. */
+exports.TRAVEL_MODES = ['Transit', 'Truck'];
+/** Sprite sheet variant. One value today. */
+exports.SPRITE_VARIANTS = ['Default'];
+/** Static map label size. */
+exports.LABEL_SIZES = ['Large', 'Small'];
+/** Static map scale bar units. */
+exports.SCALE_BAR_UNITS = [
+    'Kilometers',
+    'KilometersMiles',
+    'Miles',
+    'MilesKilometers',
+];
+/**
+ * Static map points-of-interest rendering.
+ *
+ * A MODE, not a list of categories — an easy one to get wrong, and the reason
+ * the static map route returned a confusing error before
+ * location-service-api#35. To filter POIs on an interactive map, use
+ * `setPoiVisibility` instead.
+ */
+exports.MAP_FEATURE_MODES = ['Disabled', 'Enabled'];

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

@@ -0,0 +1,43 @@
+import type { MapLike } from '../types/index.js';
+/**
+ * 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
+ */
+export declare function languageExpression(language: string): unknown[];
+/**
+ * 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.
+ */
+export declare function labelsByName(textField: unknown): boolean;
+/**
+ * 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'))
+ */
+export declare function applyMapLanguage(map: MapLike, language: string): void;

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>;