@aguacerowx/javascript-sdk 0.0.24 → 0.0.26

package/dist/nexrad_level3_catalog.js

@@ -0,0 +1,56 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.NEXRAD_LEVEL3_MOTION_PRODUCT = exports.NEXRAD_LEVEL3_ELEV = void 0;
+exports.getNexradLevel3EntryByRadarKey = getNexradLevel3EntryByRadarKey;
+/** Subset of aguacero-frontend NEXRAD_LEVEL3_MENU for API product resolution. */
+
+const NEXRAD_LEVEL3_ELEV = exports.NEXRAD_LEVEL3_ELEV = '0.50';
+const NEXRAD_LEVEL3_MOTION_PRODUCT = exports.NEXRAD_LEVEL3_MOTION_PRODUCT = 'N0S';
+const MENU = [{
+  radarKey: 'VEL',
+  product: 'N0G',
+  fldKey: 'nexrad_vel'
+}, {
+  radarKey: 'KDP',
+  product: 'N0K',
+  fldKey: 'nexrad_l3_n0k'
+}, {
+  radarKey: 'N0H',
+  product: 'N0H',
+  fldKey: 'nexrad_l3_n0h'
+}, {
+  radarKey: 'HHC',
+  product: 'HHC',
+  fldKey: 'nexrad_l3_hhc'
+}, {
+  radarKey: 'EET',
+  product: 'EET',
+  fldKey: 'nexrad_l3_eet'
+}, {
+  radarKey: 'DVL',
+  product: 'DVL',
+  fldKey: 'nexrad_l3_dvl'
+}, {
+  radarKey: 'DAA',
+  product: 'DAA',
+  fldKey: 'nexrad_l3_daa'
+}, {
+  radarKey: 'DU3',
+  product: 'DU3',
+  fldKey: 'nexrad_l3_du3'
+}, {
+  radarKey: 'DTA',
+  product: 'DTA',
+  fldKey: 'nexrad_l3_dta'
+}];
+const byRadarKey = new Map();
+for (const e of MENU) {
+  byRadarKey.set(e.radarKey, e);
+}
+byRadarKey.set('NVL', byRadarKey.get('DVL'));
+function getNexradLevel3EntryByRadarKey(radarKey) {
+  return byRadarKey.get(radarKey);
+}

package/dist/nexrad_support.js

@@ -0,0 +1,269 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.NEXRAD_SWEEP_LAMBDA_URL = exports.NEXRAD_LEVEL3_BASE_URL = void 0;
+exports.fetchLevel3ProductTimesForStation = fetchLevel3ProductTimesForStation;
+exports.fetchNexradTimesListing = fetchNexradTimesListing;
+exports.getAvailableNexradTilts = getAvailableNexradTilts;
+exports.getRawNexradTiltsForCoalesce = getRawNexradTiltsForCoalesce;
+exports.inferNexradDataSourceForProduct = inferNexradDataSourceForProduct;
+exports.nexradBinGroupIdForKey = nexradBinGroupIdForKey;
+exports.nexradColormapFldKey = nexradColormapFldKey;
+exports.variableToNexradGroup = variableToNexradGroup;
+var _nexradTilts = require("./nexradTilts.js");
+var _nexradTiltCoalesce = require("./nexradTiltCoalesce.js");
+var _nexrad_level3_catalog = require("./nexrad_level3_catalog.js");
+/**
+ * NEXRAD Level-II / Level-III time listings (aligned with aguacero-frontend nexradTimes.ts).
+ */
+
+/**
+ * Whether listings and archive fetches for this product use Level-II sweep lambda vs Level-III S3 products.
+ * AguaceroCore derives this from the product key only (not user-configurable).
+ * @param {string} [nexradProduct] - Radar variable key (e.g. REF, KDP, VEL).
+ * @returns {'level2'|'level3'}
+ */
+function inferNexradDataSourceForProduct(nexradProduct) {
+  const p = (nexradProduct || 'REF').toUpperCase();
+  return (0, _nexrad_level3_catalog.getNexradLevel3EntryByRadarKey)(p) ? 'level3' : 'level2';
+}
+
+/** Colormap / DICTIONARIES.fld key for customColormaps (matches frontend userDefaultColormap). */
+function nexradColormapFldKey(nexradDataSource, nexradProduct) {
+  const p = (nexradProduct || 'REF').toUpperCase();
+  if (nexradDataSource === 'level3') {
+    const entry = (0, _nexrad_level3_catalog.getNexradLevel3EntryByRadarKey)(p);
+    return (entry === null || entry === void 0 ? void 0 : entry.fldKey) ?? `nexrad_l3_${p.toLowerCase()}`;
+  }
+  const map = {
+    REF: 'nexrad_ref',
+    PHI: 'nexrad_phi',
+    ZDR: 'nexrad_zdr',
+    RHO: 'nexrad_rho',
+    KDP: 'nexrad_kdp',
+    VEL: 'nexrad_vel',
+    SW: 'nexrad_sw'
+  };
+  return map[p] ?? `nexrad_${p.toLowerCase()}`;
+}
+const NEXRAD_SWEEP_LAMBDA_URL = exports.NEXRAD_SWEEP_LAMBDA_URL = 'https://ddknicwcw2wyov7v5bzxmbqu440tzntf.lambda-url.us-east-2.on.aws/';
+const NEXRAD_LEVEL3_BASE_URL = exports.NEXRAD_LEVEL3_BASE_URL = 'https://unidata-nexrad-level3.s3.amazonaws.com';
+const NEXRAD_GROUP_G1 = ['REF', 'PHI', 'ZDR', 'RHO'];
+const NEXRAD_GROUP_G2 = ['VEL', 'SW'];
+function variableToNexradGroup(variable) {
+  const v = (variable || 'REF').toUpperCase();
+  if (NEXRAD_GROUP_G2.includes(v)) return 'g2';
+  return 'g1';
+}
+function nexradBinGroupIdForKey(cacheGroup) {
+  return cacheGroup === 'g1' ? 1 : 2;
+}
+function getLevel3StationPrefix(stationId) {
+  const upper = (stationId || '').toUpperCase();
+  if (upper.startsWith('K') && upper.length === 4) return upper.slice(1);
+  return upper.slice(-3);
+}
+function parseS3KeyTimeToUnix(key) {
+  const m = key.match(/_(\d{4})_(\d{2})_(\d{2})_(\d{2})_(\d{2})_(\d{2})$/);
+  if (!m) return null;
+  const [, y, mo, d, h, mi, s] = m;
+  const unix = Date.UTC(Number(y), Number(mo) - 1, Number(d), Number(h), Number(mi), Number(s)) / 1000;
+  return Number.isFinite(unix) ? unix : null;
+}
+async function fetchLevel3ProductTimesForStation(stationId, productCode, listWindowHours) {
+  const stationPrefix = getLevel3StationPrefix(stationId);
+  const nowMs = Date.now();
+  const nowSec = Math.floor(nowMs / 1000);
+  const hourSec = 3600;
+  const windowSec = Math.max(hourSec, Math.ceil(listWindowHours) * hourSec);
+  const dayPrefixForOffset = dayOff => {
+    const dt = new Date(nowMs - dayOff * 86400000);
+    const y = dt.getUTCFullYear();
+    const mo = String(dt.getUTCMonth() + 1).padStart(2, '0');
+    const day = String(dt.getUTCDate()).padStart(2, '0');
+    return `${stationPrefix}_${productCode}_${y}_${mo}_${day}_`;
+  };
+  const dayPrefixes = [dayPrefixForOffset(0), dayPrefixForOffset(1)];
+  const byUnix = new Map();
+  const listKeysForPrefix = async prefix => {
+    let continuationToken = null;
+    for (let page = 0; page < 8; page++) {
+      const params = new URLSearchParams({
+        'list-type': '2',
+        prefix,
+        'max-keys': '1000'
+      });
+      if (continuationToken) params.set('continuation-token', continuationToken);
+      const res = await fetch(`${NEXRAD_LEVEL3_BASE_URL}/?${params.toString()}`);
+      if (!res.ok) throw new Error(`Level3 list HTTP ${res.status}`);
+      const xml = await res.text();
+      const keyMatches = [...xml.matchAll(/<Key>([^<]+)<\/Key>/g)];
+      keyMatches.forEach(match => {
+        const objectKey = match[1];
+        const unix = parseS3KeyTimeToUnix(objectKey);
+        if (unix == null) return;
+        byUnix.set(unix, objectKey);
+      });
+      const tokenMatch = xml.match(/<NextContinuationToken>([^<]+)<\/NextContinuationToken>/);
+      continuationToken = (tokenMatch === null || tokenMatch === void 0 ? void 0 : tokenMatch[1]) || null;
+      if (!continuationToken) break;
+    }
+  };
+  for (const prefix of dayPrefixes) {
+    await listKeysForPrefix(prefix);
+  }
+  const sorted = [...byUnix.keys()].sort((a, b) => a - b);
+  const windowStart = nowSec - windowSec;
+  let inWindow = sorted.filter(t => t >= windowStart);
+  if (inWindow.length === 0 && sorted.length > 0) {
+    inWindow = sorted.filter(t => t >= nowSec - Math.max(6 * hourSec, windowSec));
+  }
+  if (inWindow.length === 0 && sorted.length > 0) {
+    inWindow = sorted.slice(-48);
+  }
+  const timeToKeyMap = {};
+  inWindow.forEach(t => {
+    const k = byUnix.get(t);
+    if (k) timeToKeyMap[String(t)] = k;
+  });
+  return {
+    unixTimes: inWindow,
+    timeToKeyMap
+  };
+}
+
+/**
+ * @param {object} opts
+ * @param {string} opts.stationId
+ * @param {string} [opts.variable]
+ * @param {string} [opts.elev]
+ * @param {'level2'|'level3'} [opts.source]
+ * @param {boolean} [opts.level3StormRelative]
+ * @param {number} opts.listingWindowHours
+ */
+async function fetchNexradTimesListing(opts) {
+  var _getNexradLevel3Entry;
+  const {
+    stationId,
+    variable = 'REF',
+    elev,
+    source = 'level2',
+    level3StormRelative,
+    listingWindowHours
+  } = opts;
+  if (!stationId) {
+    return {
+      unixTimes: [],
+      timeToKeyMap: {},
+      level3MotionUnixTimes: [],
+      level3MotionTimeToKeyMap: {}
+    };
+  }
+  const dataSource = source === 'level3' ? 'level3' : 'level2';
+  let tiltNum = Number(elev);
+  if (!Number.isFinite(tiltNum)) tiltNum = (0, _nexradTilts.getDefaultRadarTilt)(stationId);
+  const elevNormUse = dataSource === 'level3' ? _nexrad_level3_catalog.NEXRAD_LEVEL3_ELEV : (0, _nexradTilts.formatTiltForApi)((0, _nexradTilts.clampNexradTiltForVariable)(stationId, variable, tiltNum));
+  const group = dataSource === 'level3' ? 'l3' : variableToNexradGroup(variable);
+  const l3Product = dataSource === 'level3' ? opts.level3Product ?? ((_getNexradLevel3Entry = (0, _nexrad_level3_catalog.getNexradLevel3EntryByRadarKey)(variable)) === null || _getNexradLevel3Entry === void 0 ? void 0 : _getNexradLevel3Entry.product) ?? (variable === 'VEL' ? 'N0G' : variable) : '';
+  const fetchL3Motion = dataSource === 'level3' && l3Product === 'N0G' && variable === 'VEL' && level3StormRelative === true;
+  const fetchL2VelMotion = dataSource === 'level2' && variable === 'VEL' && level3StormRelative === true;
+  const key = dataSource === 'level3' ? `${stationId}_l3_${l3Product}_${elevNormUse}` : `${stationId}_${group}_${elevNormUse}`;
+  const level3MotionKey = dataSource === 'level3' && fetchL3Motion ? `${stationId}_l3_${_nexrad_level3_catalog.NEXRAD_LEVEL3_MOTION_PRODUCT}_${elevNormUse}` : '';
+  const l2StormMotionListKey = dataSource === 'level2' && fetchL2VelMotion ? `${stationId}_l3_${_nexrad_level3_catalog.NEXRAD_LEVEL3_MOTION_PRODUCT}_${_nexrad_level3_catalog.NEXRAD_LEVEL3_ELEV}` : '';
+  let times = [];
+  let timeToKeyMap = {};
+  let l3MotionUnixTimes = [];
+  let l3MotionTimeToKeyMap = {};
+  if (dataSource === 'level3') {
+    const l3Primary = await fetchLevel3ProductTimesForStation(stationId, l3Product, listingWindowHours);
+    times = l3Primary.unixTimes;
+    timeToKeyMap = l3Primary.timeToKeyMap;
+    if (fetchL3Motion) {
+      const l3Motion = await fetchLevel3ProductTimesForStation(stationId, _nexrad_level3_catalog.NEXRAD_LEVEL3_MOTION_PRODUCT, listingWindowHours);
+      l3MotionUnixTimes = l3Motion.unixTimes;
+      l3MotionTimeToKeyMap = l3Motion.timeToKeyMap;
+    }
+  } else {
+    const params = new URLSearchParams({
+      station: stationId,
+      field: group,
+      elev: elevNormUse,
+      hours: String(listingWindowHours)
+    });
+    const url = `${NEXRAD_SWEEP_LAMBDA_URL}?${params.toString()}`;
+    const res = await fetch(url);
+    if (!res.ok) throw new Error(`NEXRAD lambda HTTP ${res.status}`);
+    const data = await res.json();
+    if (Array.isArray(data === null || data === void 0 ? void 0 : data.times)) {
+      times = data.times;
+    } else if (data !== null && data !== void 0 && data.body) {
+      const body = typeof data.body === 'string' ? JSON.parse(data.body) : data.body;
+      times = Array.isArray(body === null || body === void 0 ? void 0 : body.times) ? body.times : [];
+    }
+    const groupId = nexradBinGroupIdForKey(group);
+    const elevNorm = elevNormUse;
+    times.forEach(t => {
+      timeToKeyMap[String(t)] = `${stationId}_${elevNorm}_${t}_g${groupId}.bin`;
+    });
+    if (fetchL2VelMotion) {
+      const l3Motion = await fetchLevel3ProductTimesForStation(stationId, _nexrad_level3_catalog.NEXRAD_LEVEL3_MOTION_PRODUCT, listingWindowHours);
+      l3MotionUnixTimes = l3Motion.unixTimes;
+      l3MotionTimeToKeyMap = l3Motion.timeToKeyMap;
+    }
+  }
+  const out = {
+    cacheKey: key,
+    unixTimes: times,
+    timeToKeyMap,
+    level3MotionKey: level3MotionKey || null,
+    level3MotionUnixTimes: l3MotionUnixTimes,
+    level3MotionTimeToKeyMap: l3MotionTimeToKeyMap,
+    l2StormMotionListKey: l2StormMotionListKey || null
+  };
+  return out;
+}
+const L3_TILT_INDEX_MANIFEST_SLOTS = 6;
+
+/**
+ * Raw manifest tilt list before coalescing (same rules as aguacero-frontend `radarTiltOptionsRaw`).
+ * Use {@link coalesceNexradTiltOptionsForDisplay} or {@link getAvailableNexradTilts} for UI controls.
+ *
+ * @param {string} siteId
+ * @param {'level2'|'level3'} nexradDataSource
+ * @param {string} [nexradProduct]
+ * @returns {number[]}
+ */
+function getRawNexradTiltsForCoalesce(siteId, nexradDataSource, nexradProduct) {
+  if (!siteId) return [];
+  const v = (nexradProduct || 'REF').toUpperCase();
+  const ds = nexradDataSource === 'level3' ? 'level3' : 'level2';
+  const tilts = (0, _nexradTilts.getRadarTilts)(siteId, v);
+  /** L3 super-res VEL (N*G) uses the same first-N manifest slots as KDP/N0H — not the full L2 g2-only list. */
+  if (v === 'VEL') {
+    return tilts.slice(0, L3_TILT_INDEX_MANIFEST_SLOTS);
+  }
+  if (ds === 'level2') {
+    return [...tilts];
+  }
+  if (v === 'KDP' || v === 'N0H') {
+    return tilts.slice(0, L3_TILT_INDEX_MANIFEST_SLOTS);
+  }
+  return [];
+}
+
+/**
+ * Tilt angles for the UI: manifest tilts with adjacent 0.1° steps merged like aguacero-frontend
+ * ({@link coalesceNexradTiltOptionsForDisplay}).
+ *
+ * @param {string} siteId
+ * @param {'level2'|'level3'} nexradDataSource
+ * @param {string} [nexradProduct]
+ * @returns {number[]}
+ */
+function getAvailableNexradTilts(siteId, nexradDataSource, nexradProduct) {
+  const raw = getRawNexradTiltsForCoalesce(siteId, nexradDataSource, nexradProduct);
+  if (!raw.length) return [];
+  return (0, _nexradTiltCoalesce.coalesceNexradTiltOptionsForDisplay)(raw);
+}