@rcpch/imd-map 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -8,6 +8,20 @@ This project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.3.1] — 2026-04-28
+
+### Added
+
+- Optional tile API key support via `tilesApiKey` and `tilesApiKeyParam` options in `CreateImdMapOptions`.
+- Tile API key query parameters are appended to all choropleth and boundary overlay tile requests.
+- Customizable query parameter name for tile auth (defaults to `api_key`).
+- Unit test coverage for tile URL builder with optional auth and auth propagation across overlays.
+
+### Documentation
+
+- Updated README runtime tile configuration section with tile auth options and example usage.
+- Added note that browser-delivered keys are non-secret and primarily useful for operational traffic control (rate limiting, revocation, origin restrictions).
+
 ## [0.3.0] — 2026-04-27
 
 ### Changed

package/README.md

@@ -201,6 +201,24 @@ Tile URL resolution precedence:
 
 The library source contains **no hardcoded tile URLs**.
 
+Optional tile auth query options:
+
+- `tilesApiKey`: appends a query value to all choropleth and overlay tile requests
+- `tilesApiKeyParam`: query parameter name for `tilesApiKey` (default: `api_key`)
+
+Example:
+
+```js
+createImdMap({
+  container: 'map',
+  tilesBaseUrl: 'https://your-tile-server.example.com',
+  tilesApiKey: 'switchable-browser-token',
+  tilesApiKeyParam: 'key',
+});
+```
+
+This is useful for revoking abusive traffic quickly, but browser-delivered keys must still be treated as non-secret.
+
 ### Overlay boundary tile contract
 
 Boundary overlays (local authority, NHSER, ICB, LHB) are requested from schema-qualified table ids and rendered with the same schema-qualified `source-layer` name. Example:
@@ -407,6 +425,8 @@ map.setStyle({ tooltip: { areaLabel: 'Local area' } });
 |---|---|---|---|
 | `container` | `string \| HTMLElement` | — | DOM element ID or element reference |
 | `tilesBaseUrl` | `string` | — | Base URL of the tile server |
+| `tilesApiKey` | `string` | — | Optional API key appended to tile URLs as a query parameter |
+| `tilesApiKeyParam` | `string` | `'api_key'` | Query parameter name used for `tilesApiKey` |
 | `initialNation` | `Nation` | `'all'` | Starting nation filter |
 | `initialEra` | `Era` | `'2021'` | Requested era (may be overridden) |
 | `enableLocalAuthorityOverlay` | `boolean` | `false` | Show local authority boundary overlay at startup |

package/dist/index.d.ts

@@ -183,6 +183,10 @@ interface CreateImdMapOptions {
     container: string | HTMLElement;
     /** Base URL of the tile server. Required for choropleth rendering. */
     tilesBaseUrl?: string;
+    /** Optional API key appended to tile URLs as a query string parameter. */
+    tilesApiKey?: string;
+    /** Query parameter name used for tilesApiKey. Default: api_key. */
+    tilesApiKeyParam?: string;
     initialNation?: Nation;
     initialEra?: Era;
     showDefaultControls?: boolean;

package/dist/index.esm.js

@@ -29,9 +29,13 @@ var ZOOM_TIERS = [
 function resolveFullTableName(effectiveEra, tier) {
   return `public.uk_master_${effectiveEra}_${tier}`;
 }
-function buildTileUrl(tilesBaseUrl, fullTableName) {
+function buildTileUrl(tilesBaseUrl, fullTableName, auth) {
   const base = tilesBaseUrl.replace(/\/$/, "");
-  return `${base}/${fullTableName}/{z}/{x}/{y}.pbf`;
+  const tileUrl = `${base}/${fullTableName}/{z}/{x}/{y}.pbf`;
+  if (!auth?.apiKey) return tileUrl;
+  const paramName = auth.apiKeyParam?.trim() || "api_key";
+  const separator = tileUrl.includes("?") ? "&" : "?";
+  return `${tileUrl}${separator}${encodeURIComponent(paramName)}=${encodeURIComponent(auth.apiKey)}`;
 }
 function resolveNationFilter(nation) {
   if (nation === "all") return null;
@@ -60,11 +64,11 @@ function choroplethSourceId(tier) {
 ZOOM_TIERS.map((t) => choroplethSourceId(t.tier));
 var PATIENTS_SOURCE_ID = "rcpch-imd-patients";
 var LEAD_CENTRE_SOURCE_ID = "rcpch-imd-lead-centre";
-function addOrUpdateChoroplethSources(map, tilesBaseUrl, effectiveEra) {
+function addOrUpdateChoroplethSources(map, tilesBaseUrl, effectiveEra, tileAuth) {
   for (const { tier } of ZOOM_TIERS) {
     const sourceId = choroplethSourceId(tier);
     const fullTableName = resolveFullTableName(effectiveEra, tier);
-    const tileUrl = buildTileUrl(tilesBaseUrl, fullTableName);
+    const tileUrl = buildTileUrl(tilesBaseUrl, fullTableName, tileAuth);
     const existing = map.getSource(sourceId);
     if (existing instanceof VectorTileSource) {
       existing.setTiles([tileUrl]);
@@ -899,13 +903,13 @@ function localAuthoritySourceId(tier) {
 function localAuthorityLayerId(tier) {
   return `${LOCAL_AUTHORITY_LAYER_ID}-${tier}`;
 }
-function addOrUpdateLocalAuthorityOverlay(map, tilesBaseUrl, style) {
+function addOrUpdateLocalAuthorityOverlay(map, tilesBaseUrl, style, tileAuth) {
   for (const { tier, minzoom, maxzoom } of ZOOM_TIERS) {
     const sourceId = localAuthoritySourceId(tier);
     const layerId = localAuthorityLayerId(tier);
     const fullTableName = buildMvtLayerName(LOCAL_AUTHORITY_TABLE_PREFIX, tier);
     const sourceLayer = fullTableName;
-    const tileUrl = buildTileUrl(tilesBaseUrl, fullTableName);
+    const tileUrl = buildTileUrl(tilesBaseUrl, fullTableName, tileAuth);
     const existing = map.getSource(sourceId);
     if (existing instanceof VectorTileSource) {
       existing.setTiles([tileUrl]);
@@ -972,13 +976,13 @@ function overlaySourceId(baseSourceId, tier) {
 function overlayLayerId(baseLayerId, tier) {
   return `${baseLayerId}-${tier}`;
 }
-function addOrUpdateBoundaryOverlay(map, tilesBaseUrl, input) {
+function addOrUpdateBoundaryOverlay(map, tilesBaseUrl, tileAuth, input) {
   for (const { tier, minzoom, maxzoom } of ZOOM_TIERS) {
     const sourceId = overlaySourceId(input.sourceId, tier);
     const layerId = overlayLayerId(input.layerId, tier);
     const fullTableName = buildMvtLayerName(input.tablePrefix, tier);
     const sourceLayer = fullTableName;
-    const tileUrl = buildTileUrl(tilesBaseUrl, fullTableName);
+    const tileUrl = buildTileUrl(tilesBaseUrl, fullTableName, tileAuth);
     const existing = map.getSource(sourceId);
     if (existing instanceof VectorTileSource) {
       existing.setTiles([tileUrl]);
@@ -1014,8 +1018,8 @@ function addOrUpdateBoundaryOverlay(map, tilesBaseUrl, input) {
     });
   }
 }
-function addOrUpdateNhserOverlay(map, tilesBaseUrl, style) {
-  addOrUpdateBoundaryOverlay(map, tilesBaseUrl, {
+function addOrUpdateNhserOverlay(map, tilesBaseUrl, style, tileAuth) {
+  addOrUpdateBoundaryOverlay(map, tilesBaseUrl, tileAuth, {
     sourceId: NHSER_SOURCE_ID,
     layerId: NHSER_LAYER_ID,
     tablePrefix: NHSER_TABLE_PREFIX,
@@ -1023,8 +1027,8 @@ function addOrUpdateNhserOverlay(map, tilesBaseUrl, style) {
     lineWidth: style.boundaries.nhserWidth ?? 1.5
   });
 }
-function addOrUpdateIcbOverlay(map, tilesBaseUrl, style) {
-  addOrUpdateBoundaryOverlay(map, tilesBaseUrl, {
+function addOrUpdateIcbOverlay(map, tilesBaseUrl, style, tileAuth) {
+  addOrUpdateBoundaryOverlay(map, tilesBaseUrl, tileAuth, {
     sourceId: ICB_SOURCE_ID,
     layerId: ICB_LAYER_ID,
     tablePrefix: ICB_TABLE_PREFIX,
@@ -1032,8 +1036,8 @@ function addOrUpdateIcbOverlay(map, tilesBaseUrl, style) {
     lineWidth: style.boundaries.icbWidth ?? 1
   });
 }
-function addOrUpdateLhbOverlay(map, tilesBaseUrl, style) {
-  addOrUpdateBoundaryOverlay(map, tilesBaseUrl, {
+function addOrUpdateLhbOverlay(map, tilesBaseUrl, style, tileAuth) {
+  addOrUpdateBoundaryOverlay(map, tilesBaseUrl, tileAuth, {
     sourceId: LHB_SOURCE_ID,
     layerId: LHB_LAYER_ID,
     tablePrefix: LHB_TABLE_PREFIX,
@@ -1377,6 +1381,10 @@ function createImdMap(options) {
   if (!tilesBaseUrl) {
     logger.warn("No tilesBaseUrl provided. Choropleth tiles will not load.");
   }
+  const tileAuth = {
+    apiKey: options.tilesApiKey,
+    apiKeyParam: options.tilesApiKeyParam
+  };
   let resolvedStyle = mergeStyle(DEFAULT_STYLE, options.style);
   let state = createInitialState(options.initialNation ?? "all", options.initialEra ?? "2021");
   if (options.enableLocalAuthorityOverlay) {
@@ -1473,22 +1481,22 @@ function createImdMap(options) {
     const canShowIcb = nation === "all" || nation === "england";
     const canShowLhb = nation === "all" || nation === "wales";
     if (state.overlays.localAuthority) {
-      addOrUpdateLocalAuthorityOverlay(map, tilesBaseUrl, resolvedStyle);
+      addOrUpdateLocalAuthorityOverlay(map, tilesBaseUrl, resolvedStyle, tileAuth);
     } else {
       hideLocalAuthorityOverlay(map);
     }
     if (state.overlays.nhser && canShowNhser) {
-      addOrUpdateNhserOverlay(map, tilesBaseUrl, resolvedStyle);
+      addOrUpdateNhserOverlay(map, tilesBaseUrl, resolvedStyle, tileAuth);
     } else {
       hideNhserOverlay(map);
     }
     if (state.overlays.icb && canShowIcb) {
-      addOrUpdateIcbOverlay(map, tilesBaseUrl, resolvedStyle);
+      addOrUpdateIcbOverlay(map, tilesBaseUrl, resolvedStyle, tileAuth);
     } else {
       hideIcbOverlay(map);
     }
     if (state.overlays.lhb && canShowLhb) {
-      addOrUpdateLhbOverlay(map, tilesBaseUrl, resolvedStyle);
+      addOrUpdateLhbOverlay(map, tilesBaseUrl, resolvedStyle, tileAuth);
     } else {
       hideLhbOverlay(map);
     }
@@ -1522,10 +1530,13 @@ function createImdMap(options) {
     });
   }
   logger.debug(`tilesBaseUrl resolved to: "${tilesBaseUrl}"`);
+  if (tileAuth.apiKey) {
+    logger.debug("Tile API key is configured for tile URL requests.");
+  }
   map.on("load", () => {
     mapLoaded = true;
     if (tilesBaseUrl) {
-      addOrUpdateChoroplethSources(map, tilesBaseUrl, state.effectiveEra);
+      addOrUpdateChoroplethSources(map, tilesBaseUrl, state.effectiveEra, tileAuth);
       addChoroplethLayers(map, state.nation, state.effectiveEra, resolvedStyle);
     }
     applyOverlayVisibility();
@@ -1576,7 +1587,7 @@ function createImdMap(options) {
     if (mapLoaded && tilesBaseUrl) {
       if (eraChanged) {
         removeChoroplethLayers(map);
-        addOrUpdateChoroplethSources(map, tilesBaseUrl, newEffectiveEra);
+        addOrUpdateChoroplethSources(map, tilesBaseUrl, newEffectiveEra, tileAuth);
         addChoroplethLayers(map, newNation, newEffectiveEra, resolvedStyle);
       } else if (nationChanged) {
         updateChoroplethNationFilter(map, newNation);