@chaosity/location-client 0.4.2 → 0.5.1

package/dist/index.d.ts

@@ -15,6 +15,8 @@ export { POI_CATEGORIES, setAllPoiVisibility, setPoiVisibility, } from './maps/m
 export type { PoiCategory } from './maps/mapPoi';
 export { buildMapStyleUrl, fetchMapStyle } from './maps/mapStyle';
 export type { MapStyleOptions } from './maps/mapStyle';
+export { buildStaticMapUrl, fetchStaticMap, staticMapAccept, } from './maps/staticMap';
+export type { StaticMapFileName, StaticMapOptions } from './maps/staticMap';
 export { BUILDINGS, COLOR_SCHEMES, CONTOUR_DENSITIES, LABEL_SIZES, MAP_FEATURE_MODES, MAP_STYLES, SCALE_BAR_UNITS, SPRITE_VARIANTS, STATIC_MAP_STYLES, TERRAINS, TRAFFIC_MODES, TRAVEL_MODES, } from './maps/mapEnums';
 export type { Buildings, ColorScheme, ContourDensity, LabelSize, MapFeatureMode, MapStyle, ScaleBarUnit, SpriteVariant, StaticMapStyle, Terrain, TrafficMode, TravelMode, } from './maps/mapEnums';
 export { transformRequest } from './maps/Utils';

package/dist/index.js

@@ -17,6 +17,7 @@ export { createTransformRequest } from './maps/createTransformRequest';
 export { applyMapLanguage } from './maps/mapLanguage';
 export { POI_CATEGORIES, setAllPoiVisibility, setPoiVisibility, } from './maps/mapPoi';
 export { buildMapStyleUrl, fetchMapStyle } from './maps/mapStyle';
+export { buildStaticMapUrl, fetchStaticMap, staticMapAccept, } from './maps/staticMap';
 // Accepted values for every map parameter, as VALUES so a picker can be built
 // from them, plus the matching types. Case sensitive — see mapEnums.ts.
 export { BUILDINGS, COLOR_SCHEMES, CONTOUR_DENSITIES, LABEL_SIZES, MAP_FEATURE_MODES, MAP_STYLES, SCALE_BAR_UNITS, SPRITE_VARIANTS, STATIC_MAP_STYLES, TERRAINS, TRAFFIC_MODES, TRAVEL_MODES, } from './maps/mapEnums';

package/dist/maps/createTransformRequest.js

@@ -7,7 +7,7 @@
  * @returns MapLibre transformRequest function
  */
 export function createTransformRequest(apiUrl, getToken) {
-    return (url, resourceType) => {
+    return (url, _resourceType) => {
         if (url.startsWith(apiUrl)) {
             const token = getToken();
             if (!token) {

package/dist/maps/mapLanguage.d.ts

@@ -1,14 +1,38 @@
 import type { MapLike } from '../types';
 /**
- * Apply a preferred display language to all symbol layers on a MapLibre map.
- *
- * AWS GeoMaps vector tiles include language-specific name properties in `name:${lang}` format
- * (e.g. `name:en`, `name:fr`, `name:ja`). This function updates the `text-field` expression
- * on every symbol layer to prefer the requested language, falling back to English then the
- * default name if the preferred language is unavailable for a feature.
+ * 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')

package/dist/maps/mapLanguage.js

@@ -1,13 +1,48 @@
 /**
- * Apply a preferred display language to all symbol layers on a MapLibre map.
- *
- * AWS GeoMaps vector tiles include language-specific name properties in `name:${lang}` format
- * (e.g. `name:en`, `name:fr`, `name:ja`). This function updates the `text-field` expression
- * on every symbol layer to prefer the requested language, falling back to English then the
- * default name if the preferred language is unavailable for a feature.
+ * 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 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.
+ */
+export 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')
@@ -17,21 +52,16 @@
  */
 export function applyMapLanguage(map, language) {
     try {
-        const expression = language === 'en'
-            ? ['coalesce', ['get', 'name:en'], ['get', 'name']]
-            : [
-                'coalesce',
-                ['get', `name:${language}`],
-                ['get', 'name:en'],
-                ['get', 'name'],
-            ];
+        const expression = languageExpression(language);
         map.getStyle().layers.forEach((layer) => {
-            if (layer.type === 'symbol') {
-                const textField = map.getLayoutProperty(layer.id, 'text-field');
-                if (textField !== undefined && textField !== null) {
-                    map.setLayoutProperty(layer.id, 'text-field', expression);
-                }
-            }
+            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 {

package/dist/maps/mapStyle.js

@@ -1,4 +1,5 @@
 import { parseErrorResponse } from '../transport/errors';
+import { labelsByName, languageExpression } from './mapLanguage';
 /**
  * Build a map style descriptor URL for the Location Service API.
  *
@@ -83,24 +84,24 @@ export async function fetchMapStyle(apiUrl, mapStyle, getToken, options = {}) {
     return style;
 }
 /**
- * Apply a preferred language to all symbol layers within a style descriptor object.
+ * 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 = language === 'en'
-        ? ['coalesce', ['get', 'name:en'], ['get', 'name']]
-        : [
-            'coalesce',
-            ['get', `name:${language}`],
-            ['get', 'name:en'],
-            ['get', 'name'],
-        ];
+    const expression = languageExpression(language);
     for (const layer of style.layers) {
-        if (layer.type === 'symbol') {
-            const layout = layer.layout;
-            if (layout?.['text-field'] !== undefined) {
-                layout['text-field'] = expression;
-            }
-        }
+        if (layer.type !== 'symbol')
+            continue;
+        const layout = layer.layout;
+        if (layout?.['text-field'] === undefined)
+            continue;
+        if (!labelsByName(layout['text-field']))
+            continue;
+        layout['text-field'] = expression;
     }
 }

package/dist/maps/staticMap.d.ts

@@ -0,0 +1,85 @@
+import type { ColorScheme, LabelSize, MapFeatureMode, ScaleBarUnit, StaticMapStyle } from './mapEnums';
+/**
+ * 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/maps/staticMap.js

@@ -0,0 +1,76 @@
+import { parseErrorResponse } from '../transport/errors';
+/**
+ * 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 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. */
+export 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
+ */
+export 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 parseErrorResponse(response.status, response.statusText, await response.text());
+    }
+    return response.blob();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chaosity/location-client",
-  "version": "0.4.2",
+  "version": "0.5.1",
   "description": "Client library for Chaosity Location Service with AWS Location Service compatibility",
   "type": "module",
   "main": "dist/index.js",