@aguacerowx/javascript-sdk 0.0.25 → 0.0.27

package/src/nws/nwsAlertsFetchSpec.js

@@ -0,0 +1,93 @@
+/**
+ * NWWS `/alerts?hours=` sizing (aguacero-frontend baseline + overlap window parity).
+ *
+ * Hours follow the **active** observational mode only: NEXRAD → `nexradDurationValue`,
+ * MRMS → `mrmsDurationValue`, satellite → `satelliteDurationValue`, otherwise `1` (e.g. model-only).
+ * Tier cap uses {@link AguaceroCore} `satelliteTier` — the only subscription-style field on core today
+ * (same values as the frontend board tier: basic / enthusiast / professional).
+ */
+
+import { parseTimelineDurationHours } from '../satellite_support.js';
+
+const MAX_ALERT_HISTORY_HOURS = 8760;
+
+/** Max option span (hours) per tier from frontend `RADAR_DURATION_CONFIG`. */
+const TIER_MAX_HOURS = {
+    professional: 12,
+    enthusiast: 4,
+    basic: 1,
+};
+
+/**
+ * @param {string | undefined} tier
+ * @returns {'professional'|'enthusiast'|'basic'}
+ */
+export function normalizeNwsSubscriptionTier(tier) {
+    const t = String(tier || 'basic').toLowerCase();
+    if (t === 'commercial' || t === 'lifetime' || t === 'partner') return 'professional';
+    if (t === 'professional' || t === 'enthusiast' || t === 'basic') return t;
+    return 'basic';
+}
+
+/**
+ * @param {string | undefined} tier
+ * @returns {number}
+ */
+export function getMaxRadarHistoryHoursForTier(tier) {
+    const k = normalizeNwsSubscriptionTier(tier);
+    return TIER_MAX_HOURS[k] ?? TIER_MAX_HOURS.basic;
+}
+
+/**
+ * @param {object | null | undefined} state - {@link AguaceroCore} `state`
+ * @returns {number} integer hours in [1, MAX_ALERT_HISTORY_HOURS]
+ */
+export function computeNwsAlertsFetchHoursFromAguaceroState(state) {
+    const tierMax = getMaxRadarHistoryHoursForTier(state?.satelliteTier);
+    let desired = 1;
+    if (state?.isNexrad) {
+        desired = parseTimelineDurationHours(state.nexradDurationValue);
+    } else if (state?.isMRMS) {
+        desired = parseTimelineDurationHours(state.mrmsDurationValue);
+    } else if (state?.isSatellite) {
+        desired = parseTimelineDurationHours(state.satelliteDurationValue);
+    }
+    const clamped = Math.min(tierMax, Math.max(1, desired));
+    return Math.min(MAX_ALERT_HISTORY_HOURS, Math.floor(clamped));
+}
+
+/**
+ * @param {number} hours
+ * @returns {string}
+ */
+export function nwsAlertsFetchSpecCacheKey(hours) {
+    return `h${hours}`;
+}
+
+/**
+ * Unix window [start, end] for client-side validity overlap (wall-clock end at “now”).
+ *
+ * @param {number} hours
+ * @param {number | null} [anchorSec] - reserved; default now (matches frontend `anchorSec: null`)
+ * @returns {{ winStartSec: number; winEndSec: number }}
+ */
+export function nwwsAlertsFetchUnixWindow(hours, anchorSec = null) {
+    const nowSec = Math.floor(Date.now() / 1000);
+    const winEndSec = anchorSec ?? nowSec;
+    const winStartSec = winEndSec - hours * 3600;
+    return { winStartSec, winEndSec };
+}
+
+/**
+ * @param {string} baseUrl - `/alerts` root (no query)
+ * @param {number} hours
+ * @returns {string}
+ */
+export function buildNwwsActiveAlertsUrl(baseUrl, hours) {
+    const h = Math.max(1, Math.floor(Number(hours) || 1));
+    const params = new URLSearchParams();
+    params.set('hours', String(h));
+    const q = params.toString();
+    const base = String(baseUrl || '').replace(/\/$/, '');
+    return q ? `${base}?${q}` : base;
+}