@chaosity/location-client 0.4.1 → 0.5.0

package/dist/adapters/GeoPlaces.js

@@ -2,6 +2,47 @@ import { GeocodeCommand, GetPlaceAdditionalFeature, GetPlaceCommand, ReverseGeoc
 import { geocodeResponseToFeatureCollection, getPlaceResponseToFeatureCollection, reverseGeocodeResponseToFeatureCollection, } from '@aws/amazon-location-utilities-datatypes';
 import debug from 'debug';
 const log = debug('location-client:geocoder');
+/**
+ * Give the control the fields it renders, not just the ones GeoJSON needs.
+ *
+ * `@maplibre/maplibre-gl-geocoder` is a Carmen-shaped consumer: its result list
+ * calls `item.place_name.split(',')`, the input takes `result.place_name` on
+ * select, and fly-to reads `center` / `bbox`. The AWS converters produce plain
+ * GeoJSON — `properties` and `geometry` only — so a forward geocode used to
+ * hand the control features with no `place_name`. The list renderer threw, the
+ * control caught it and emitted `error`, and with no listener that surfaced as
+ * `Unhandled error. (undefined)` in the console: the Enter key silently did
+ * nothing. Suggestions were unaffected because that path renders `text`.
+ *
+ * The `as MaplibreGeocoderFeatureResults` cast this replaces is what hid it —
+ * `place_name` and `text` are required on the type.
+ */
+function toCarmenFeatures(features) {
+    return features.map((feature) => {
+        const p = (feature.properties ?? {});
+        const title = typeof p.Title === 'string' ? p.Title : '';
+        const label = typeof p['Address.Label'] === 'string' ? p['Address.Label'] : '';
+        // `flattenProperties` flattens nested OBJECTS (Address.Label) but leaves an
+        // array of numbers intact, so MapView is still [minx, miny, maxx, maxy].
+        const view = p.MapView;
+        const bbox = Array.isArray(view) &&
+            view.length === 4 &&
+            view.every((v) => typeof v === 'number')
+            ? view
+            : undefined;
+        const center = feature.geometry?.type === 'Point'
+            ? feature.geometry.coordinates
+            : undefined;
+        return {
+            ...feature,
+            text: title || label,
+            place_name: label || title,
+            place_type: typeof p.PlaceType === 'string' ? [p.PlaceType] : [],
+            ...(bbox ? { bbox } : {}),
+            ...(center ? { center } : {}),
+        };
+    });
+}
 export class GeoPlaces {
     constructor(client, map, options = {}) {
         this.client = client;
@@ -53,10 +94,14 @@ export class GeoPlaces {
             };
         }
         const response = (await this.client.send(new GeocodeCommand(commandInput)));
-        const result = geocodeResponseToFeatureCollection(response, {
+        const converted = geocodeResponseToFeatureCollection(response, {
             flattenProperties: true,
         });
-        log('forwardGeocode returned %d results', result.features?.length ?? 0);
+        const result = {
+            type: 'FeatureCollection',
+            features: toCarmenFeatures(converted.features),
+        };
+        log('forwardGeocode returned %d results', result.features.length);
         return result;
     }
     async reverseGeocode(config) {
@@ -70,10 +115,14 @@ export class GeoPlaces {
             Language: this.normalizeLanguage(config.language),
         };
         const response = (await this.client.send(new ReverseGeocodeCommand(commandInput)));
-        const result = reverseGeocodeResponseToFeatureCollection(response, {
+        const converted = reverseGeocodeResponseToFeatureCollection(response, {
             flattenProperties: true,
         });
-        log('reverseGeocode returned %d results', result.features?.length ?? 0);
+        const result = {
+            type: 'FeatureCollection',
+            features: toCarmenFeatures(converted.features),
+        };
+        log('reverseGeocode returned %d results', result.features.length);
         return result;
     }
     async getSuggestions(config) {

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/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,68 @@
+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';
+}
+/** 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.
+    if (center)
+        params.set('center', center.join(','));
+    if (boundingBox)
+        params.set('bounding-box', boundingBox.join(','));
+    if (boundedPositions) {
+        params.set('bounded-positions', boundedPositions.flat().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.1",
+  "version": "0.5.0",
   "description": "Client library for Chaosity Location Service with AWS Location Service compatibility",
   "type": "module",
   "main": "dist/index.js",