@chaosity/location-client 0.4.2 → 0.5.0

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.2",
+  "version": "0.5.0",
   "description": "Client library for Chaosity Location Service with AWS Location Service compatibility",
   "type": "module",
   "main": "dist/index.js",