@aguacerowx/javascript-sdk 0.0.16 → 0.0.20

package/src/getBundleId.js

@@ -1,22 +1,8 @@
-// This module acts as a platform-agnostic proxy.
-
-let getBundleIdImpl;
-
-try {
-  // This line will ONLY succeed in a React Native environment where the
-  // 'react-native-device-info' module is installed.
-  const DeviceInfo = require('react-native-device-info');
-  
-  // If the above line doesn't throw an error, we set the implementation
-  // to the native version.
-  getBundleIdImpl = () => DeviceInfo.getBundleId();
-
-} catch (e) {
-  // If require() fails, we know we are in a non-React Native environment
-  // (like the web). We set the implementation to a "dummy" function
-  // that does nothing and returns null.
-  getBundleIdImpl = () => null;
-}
-
-// Export the chosen implementation.
-export const getBundleId = getBundleIdImpl;
+/**
+ * Default implementation for web and Node bundlers (Vite, webpack).
+ * Do not import react-native-device-info here: static analysis would pull in
+ * `react-native` (Flow sources) and break esbuild.
+ *
+ * Metro resolves `getBundleId.native.js` on iOS/Android instead of this file.
+ */
+export const getBundleId = () => null;

package/src/getBundleId.native.js

@@ -0,0 +1,14 @@
+/**
+ * React Native (Metro picks this file over getBundleId.js on native platforms).
+ */
+
+let getBundleIdImpl;
+
+try {
+    const DeviceInfo = require('react-native-device-info');
+    getBundleIdImpl = () => DeviceInfo.getBundleId();
+} catch {
+    getBundleIdImpl = () => null;
+}
+
+export const getBundleId = getBundleIdImpl;

package/src/gridDecodePipeline.js

@@ -0,0 +1,32 @@
+import { decompress } from 'fzstd';
+
+function reconstructData(decompressedDeltas, encoding) {
+    const expectedLength = encoding.length;
+    const reconstructedData = new Int8Array(expectedLength);
+
+    if (decompressedDeltas.length > 0 && expectedLength > 0) {
+        reconstructedData[0] = decompressedDeltas[0] > 127 ? decompressedDeltas[0] - 256 : decompressedDeltas[0];
+        for (let i = 1; i < expectedLength; i++) {
+            const delta = decompressedDeltas[i] > 127 ? decompressedDeltas[i] - 256 : decompressedDeltas[i];
+            reconstructedData[i] = reconstructedData[i - 1] + delta;
+        }
+    }
+    return new Uint8Array(reconstructedData.buffer);
+}
+
+/**
+ * zstd decompress → delta reconstruction → unsigned byte offset for GPU lookup.
+ * Used on the main thread as a fallback and inside {@link ./gridDecodeWorker.js}.
+ */
+export function processCompressedGrid(compressedData, encoding) {
+    const decompressedDeltas = decompress(compressedData);
+    const finalData = reconstructData(decompressedDeltas, encoding);
+
+    const transformedData = new Uint8Array(finalData.length);
+    for (let i = 0; i < finalData.length; i++) {
+        const signedValue = finalData[i] > 127 ? finalData[i] - 256 : finalData[i];
+        transformedData[i] = signedValue + 128;
+    }
+
+    return { data: transformedData, encoding };
+}

package/src/gridDecodeWorker.js

@@ -0,0 +1,24 @@
+import { processCompressedGrid } from './gridDecodePipeline.js';
+
+self.onmessage = (e) => {
+    const { id, encoding, compressedBuffer, compressedByteOffset, compressedByteLength } = e.data;
+    try {
+        const compressedData = new Uint8Array(compressedBuffer, compressedByteOffset, compressedByteLength);
+        const { data, encoding: enc } = processCompressedGrid(compressedData, encoding);
+        self.postMessage(
+            {
+                id,
+                encoding: enc,
+                dataBuffer: data.buffer,
+                dataByteOffset: data.byteOffset,
+                dataByteLength: data.byteLength,
+            },
+            [data.buffer]
+        );
+    } catch (err) {
+        self.postMessage({
+            id,
+            error: err?.message || String(err),
+        });
+    }
+};

package/src/index.js

@@ -5,7 +5,23 @@ import { AguaceroCore } from './AguaceroCore.js';
 import { EventEmitter } from './events.js';
 import { THEME_CONFIGS } from './map-styles.js';
 import { DICTIONARIES } from './dictionaries.js';
+import { DEFAULT_COLORMAPS } from './default-colormaps.js';
 import { getUnitConversionFunction } from './unitConversions.js';
+export {
+    SATELLITE_FRAMES_URL,
+    GOES_EAST_SATELLITE_SECTORS,
+    GOES_SATELLITE_CHANNELS,
+    GOES_SATELLITE_CHANNEL_LABELS,
+    SATELLITE_DURATION_CONFIG,
+    TIMELINE_DURATION_HOUR_VALUES,
+    normalizeTimelineDurationValue,
+    parseTimelineDurationHours,
+    getDefaultSatelliteDurationOption,
+    buildSatelliteTimelineForKey,
+    getAllGoesEastSatelliteKeys,
+    calculateUnixTimeFromSatelliteKey,
+    resolveSatelliteS3FileName,
+} from './satellite_support.js';
 
 // Now, export them all so other packages can import them.
 export {
@@ -13,5 +29,10 @@ export {
     EventEmitter,
     THEME_CONFIGS,
     DICTIONARIES,
+    DEFAULT_COLORMAPS,
     getUnitConversionFunction
-};
+};
+
+/** NEXRAD tilt + listing helpers (also importable via subpaths; root re-export fixes Vite/esbuild subpath resolution). */
+export * from './nexradTilts.js';
+export * from './nexrad_support.js';

package/src/nexradTilts.js

@@ -0,0 +1,128 @@
+/**
+ * NEXRAD tilt helpers (mirrors aguacero-frontend dictionaries + radar tilts manifest behavior).
+ * When {@link setRadarTiltsManifest} has been called with a non-empty map, per-site tilts follow it.
+ */
+
+const WSR88D_TILTS = [0.5, 0.9, 1.3, 1.8, 2.4, 3.1, 4.0, 5.1, 6.4];
+const TDWR_TILTS = [0.3, 1.0, 2, 6.5, 8.8, 16.0, 21.3];
+
+const WSR88D_SITE_IDS_WITH_T_PREFIX = new Set(['TJUA']);
+
+/** @type {Record<string, { g1_tilts: number[]; g2_tilts: number[]; last_seen?: number }>} */
+let manifestBySite = {};
+
+export function setRadarTiltsManifest(map) {
+    manifestBySite = map && typeof map === 'object' ? map : {};
+}
+
+export function getRadarTiltsManifest() {
+    return manifestBySite;
+}
+
+export function isNexradTdwrSiteId(siteId) {
+    const id = String(siteId ?? '').trim().toUpperCase();
+    if (!id) return false;
+    if (WSR88D_SITE_IDS_WITH_T_PREFIX.has(id)) return false;
+    return id.startsWith('T');
+}
+
+export function isTerminalRadar(siteId) {
+    return isNexradTdwrSiteId(siteId);
+}
+
+const NEXRAD_G2_VARIABLES = new Set(['VEL', 'SW']);
+const TDWR_DUAL_POL_CAPPED = new Set(['ZDR', 'PHI', 'RHO', 'KDP']);
+const TDWR_DUAL_POL_MAX_TILT = 0.3;
+
+function uniqSorted(nums) {
+    const arr = nums.filter((n) => typeof n === 'number' && Number.isFinite(n));
+    const rounded = arr.map((n) => Math.round(n * 1000) / 1000);
+    return [...new Set(rounded)].sort((a, b) => a - b);
+}
+
+function computeRadarTiltsFromManifestEntry(entry, siteId, radarVariable) {
+    const v = (radarVariable || 'REF').toUpperCase();
+    let base;
+    if (NEXRAD_G2_VARIABLES.has(v)) {
+        base = uniqSorted(entry.g2_tilts || []);
+    } else {
+        base = uniqSorted([...(entry.g1_tilts || []), ...(entry.g2_tilts || [])]);
+    }
+    if (isNexradTdwrSiteId(siteId) && TDWR_DUAL_POL_CAPPED.has(v)) {
+        return base.filter((t) => t <= TDWR_DUAL_POL_MAX_TILT);
+    }
+    return base;
+}
+
+function getDefaultTiltFromManifestEntry(entry) {
+    const g1 = entry.g1_tilts;
+    if (!Array.isArray(g1) || g1.length === 0) return null;
+    const sorted = uniqSorted(g1);
+    return sorted[0] ?? null;
+}
+
+export function getDefaultRadarTilt(siteId) {
+    const id = siteId?.toUpperCase();
+    const entry = id ? manifestBySite[id] : undefined;
+    if (entry) {
+        const t = getDefaultTiltFromManifestEntry(entry);
+        if (t != null) return t;
+    }
+    return isTerminalRadar(siteId) ? 0.3 : 0.5;
+}
+
+export function getRadarTilts(siteId, radarVariable) {
+    const id = siteId?.toUpperCase();
+    const entry = id ? manifestBySite[id] : undefined;
+    if (entry) {
+        const fromManifest = computeRadarTiltsFromManifestEntry(entry, siteId, radarVariable);
+        if (fromManifest.length) return fromManifest;
+    }
+    const base = isTerminalRadar(siteId) ? TDWR_TILTS : WSR88D_TILTS;
+    if (!radarVariable || !isTerminalRadar(siteId)) return [...base];
+    const v = radarVariable.toUpperCase();
+    if (['ZDR', 'PHI', 'RHO'].includes(v)) {
+        return base.filter((t) => t <= TDWR_DUAL_POL_MAX_TILT);
+    }
+    return [...base];
+}
+
+export function clampNexradTiltForVariable(siteId, variable, tilt) {
+    if (!isTerminalRadar(siteId)) return tilt;
+    const v = (variable || 'REF').toUpperCase();
+    if (['ZDR', 'PHI', 'RHO'].includes(v)) {
+        return Math.min(tilt, TDWR_DUAL_POL_MAX_TILT);
+    }
+    return tilt;
+}
+
+export function formatTiltForApi(tilt) {
+    return tilt.toFixed(2);
+}
+
+export const RADAR_TILTS_MANIFEST_URL =
+    'https://radar-tilts.s3.us-east-2.amazonaws.com/manifest.json';
+
+export async function fetchRadarTiltsManifestFromNetwork() {
+    try {
+        const res = await fetch(RADAR_TILTS_MANIFEST_URL, { cache: 'no-store' });
+        if (!res.ok) return null;
+        const raw = await res.json();
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
+        const out = {};
+        for (const [key, val] of Object.entries(raw)) {
+            if (!val || typeof val !== 'object' || Array.isArray(val)) continue;
+            const g1 = val.g1_tilts;
+            const g2 = val.g2_tilts;
+            if (!Array.isArray(g1) || !Array.isArray(g2)) continue;
+            out[key.toUpperCase()] = {
+                g1_tilts: g1.filter((n) => typeof n === 'number' && Number.isFinite(n)),
+                g2_tilts: g2.filter((n) => typeof n === 'number' && Number.isFinite(n)),
+                last_seen: typeof val.last_seen === 'number' ? val.last_seen : undefined,
+            };
+        }
+        return Object.keys(out).length ? out : null;
+    } catch {
+        return null;
+    }
+}

package/src/nexrad_level3_catalog.js

@@ -0,0 +1,26 @@
+/** Subset of aguacero-frontend NEXRAD_LEVEL3_MENU for API product resolution. */
+
+export const NEXRAD_LEVEL3_ELEV = '0.50';
+export const 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'));
+
+export function getNexradLevel3EntryByRadarKey(radarKey) {
+    return byRadarKey.get(radarKey);
+}

package/src/nexrad_support.js

@@ -0,0 +1,276 @@
+/**
+ * NEXRAD Level-II / Level-III time listings (aligned with aguacero-frontend nexradTimes.ts).
+ */
+
+import {
+    formatTiltForApi,
+    clampNexradTiltForVariable,
+    getDefaultRadarTilt,
+    getRadarTilts,
+} from './nexradTilts.js';
+import {
+    NEXRAD_LEVEL3_ELEV,
+    NEXRAD_LEVEL3_MOTION_PRODUCT,
+    getNexradLevel3EntryByRadarKey,
+} from './nexrad_level3_catalog.js';
+
+/** Colormap / DICTIONARIES.fld key for customColormaps (matches frontend userDefaultColormap). */
+export function nexradColormapFldKey(nexradDataSource, nexradProduct) {
+    const p = (nexradProduct || 'REF').toUpperCase();
+    if (nexradDataSource === 'level3') {
+        const entry = getNexradLevel3EntryByRadarKey(p);
+        return 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()}`;
+}
+
+export const NEXRAD_SWEEP_LAMBDA_URL = 'https://ddknicwcw2wyov7v5bzxmbqu440tzntf.lambda-url.us-east-2.on.aws/';
+export const 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'];
+
+export function variableToNexradGroup(variable) {
+    const v = (variable || 'REF').toUpperCase();
+    if (NEXRAD_GROUP_G2.includes(v)) return 'g2';
+    return 'g1';
+}
+
+export 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;
+}
+
+export 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?.[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
+ */
+export async function fetchNexradTimesListing(opts) {
+    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 = getDefaultRadarTilt(stationId);
+    const elevNormUse =
+        dataSource === 'level3'
+            ? NEXRAD_LEVEL3_ELEV
+            : formatTiltForApi(clampNexradTiltForVariable(stationId, variable, tiltNum));
+    const group = dataSource === 'level3' ? 'l3' : variableToNexradGroup(variable);
+    const l3Product =
+        dataSource === 'level3'
+            ? opts.level3Product ??
+              getNexradLevel3EntryByRadarKey(variable)?.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_MOTION_PRODUCT}_${elevNormUse}`
+            : '';
+    const l2StormMotionListKey =
+        dataSource === 'level2' && fetchL2VelMotion
+            ? `${stationId}_l3_${NEXRAD_LEVEL3_MOTION_PRODUCT}_${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_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?.times)) {
+            times = data.times;
+        } else if (data?.body) {
+            const body = typeof data.body === 'string' ? JSON.parse(data.body) : data.body;
+            times = Array.isArray(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_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;
+
+/**
+ * Tilt angles for the UI (manifest-driven L2 list; Level III KDP/N0H use the first slots like aguacero-frontend).
+ * @param {string} siteId
+ * @param {'level2'|'level3'} nexradDataSource
+ * @param {string} [nexradProduct]
+ * @returns {number[]}
+ */
+export function getAvailableNexradTilts(siteId, nexradDataSource, nexradProduct) {
+    if (!siteId) return [];
+    const v = (nexradProduct || 'REF').toUpperCase();
+    const ds = nexradDataSource === 'level3' ? 'level3' : 'level2';
+    const tilts = getRadarTilts(siteId, v);
+    if (ds === 'level2') {
+        return [...tilts];
+    }
+    if (v === 'KDP' || v === 'N0H') {
+        return tilts.slice(0, L3_TILT_INDEX_MANIFEST_SLOTS);
+    }
+    if (v === 'VEL') {
+        return [...tilts];
+    }
+    return [];
+}