@aguacerowx/javascript-sdk

Core SDK for fetching and decoding Aguacero weather grids, radar, satellite, and overlay feeds. @aguacerowx/mapsgl and @aguacerowx/react-native both consume this package.

Weather models

The model catalog matches aguacero-frontend live products: 127 forecast, analysis, ensemble, marine, air-quality, and observational sources.

Pass a model key on AguaceroCore state (for example gfs, icon, hrrr, ecmwfaifs, cdas). Hurricane nests use a prefix plus storm id (hwrf-al09, atcf-gefs-al09).

import {
    AguaceroCore,
    MODEL_CONFIGS,
    MODEL_INFO,
    getModelDisplayName,
    COORDINATE_CONFIGS,
} from '@aguacerowx/javascript-sdk';

const core = new AguaceroCore({ apiKey: '…' });
await core.setState({ model: 'icon', variable: '2t_2' });

MODEL_CONFIGS.icon.vars;          // available fields
MODEL_INFO.icon.operator;         // 'DWD (Deutscher Wetterdienst)'
getModelDisplayName('hwrf-al09'); // 'HWRF (AL09)'

See MODELS.md for every key, category, field count, and forecast length.

Aliases kept for older clients:

• graphcastgfs → weatherNext2
• sst → crw

SPC Mesoscale Analysis (SFCOA)

Hourly SPC SFCOA-HRRR surface objective analysis — convective diagnostics plus a 5-level (925/850/700/500/250 hPa) sounding on the HRRR 3 km CONUS grid (~126 fields). This is an observational analysis, not a forecast model. Prefer the first-class data type:

await core.setState({
    // mapsgl / react-native: weatherManager.switchMode({ ... })
    mode: 'sfcoa',
    variable: 'cape_0',
});
// State: isSFCOA / dataType: 'sfcoa'
// Playhead: unix seconds in forecastHour / availableHours (default 12h lookback; max 72h)

mode: 'model', model: 'sfcoa' still remaps to this data type. Ready statuses: P, D, PA. Final analysis posts ~50 minutes past the hour.

Via the Weather API: /v1/model/status?model=sfcoa, NetCDF grids, and 5-level soundings (run = analysis hour, fh=0). No meteograms.

This is not SPC mesoscale discussions (MCD / winter MD / WPC MPD) — those arrive on NWS alerts with discussions=1 (see below).

NWS alerts (NWWS)

NwsWatchesWarningsOverlay matches aguacero-frontend: HTTP snapshot + SSE, GET /alerts?hours=N&discussions=1.

• Discussions (SPC MCD, winter MD, WPC MPD, flash flood guidance) arrive on this overlay, not the legacy spc-MD.geojson feed. Event names: Mesoscale Discussion, Winter Mesoscale Discussion, Mesoscale Precipitation Discussion, Flash Flood Guidance.
• SPS / MWS / SMW split into base vs (Convective) keys (Severe vs Other/Marine). Convective subtypes do not inherit allowlist/disable from the parent.
• SpcMesoscaleDiscussionsOverlay remains for apps that still enable the old GeoJSON path (Severe / Winter only; no MPD).

When frontend tag parsing changes, regenerate:

npm run gen:nws-key

(from packages/javascript-sdk; requires a sibling aguacero-frontend checkout).

Syncing from the frontend

When aguacero-frontend adds models, regenerate the SDK catalogs:

node packages/javascript-sdk/scripts/sync-models-from-frontend.mjs

That copies MODEL_CONFIGS, COORDINATE_CONFIGS, MODEL_INFO, smoothing/model_type, and missing field metadata from the frontend dictionaries.

Satellite

Tiled satellite (the same processing catalog as aguacero.com) is selected with switchMode or setSatelliteSelection:

await core.setSatelliteSelection({
  satelliteId: 'METEOSAT11',
  sector: 'rapid_scan',
  satelliteProduct: 'C13',
});

await core.setSatelliteSelection({
  satelliteId: 'GOES19-EAST',
  sector: 'GOES-EAST CONUS',
  satelliteProduct: 'TPW',
});

SATELLITE_INSTRUMENTS lists every spacecraft and sector label: GOES-19 East, GOES-18 West, Himawari-9, Meteosat-12, Meteosat-11 (EUMETSAT Rapid Scan), and Meteosat-9 (EUMETSAT Indian Ocean).

SATELLITE_IMAGERY_CHANNELS is C01–C16 plus the RGB recipes. SATELLITE_L2_CHANNELS is the GOES Level-2 menu (cloud-top height, fire mask, CAPE, total precipitable water, rainfall rate, land surface temperature, and the rest). GOES_SATELLITE_CHANNEL_LABELS has the display name for each id. Level-2 products are GOES only.

@aguacerowx/mapsgl draws this with the website WebGL tile layer, including RGB recipes. @aguacerowx/react-native draws single-band and Level-2 tiles in the native map. See those packages' READMEs.

Shader smoothing

shaderSmoothingEnabled (constructor option and setShaderSmoothing(boolean)) is a global flag. It applies to model/MRMS grid spatial sampling, satellite fill smoothing, and NEXRAD polar gate smoothing. It does not control colormap interpolation (hard stops vs blended colors); that is a separate colormap setting (interpolateNexradColormap / customColormaps[].interpolateColormap). There is no per-data-type smoothing toggle.

onStateChange includes shaderSmoothingEnabled as currently stored. Product, site, tilt, and mode switches keep that value; they do not rebuild NEXRAD from the default true. Each NEXRAD frame/style rebuild derives polar gate smoothing from the current flag; colormap interpolation is left unchanged.