homebridge-weather-noaa/CHANGELOG.md

Homebridge plugin providing temperature and humidity sensors using the NOAA / NWS API.

# Changelog

## [1.6.0] - 2026-04-28

A security- and minimalism-focused refresh aligned with the current
[homebridge-plugin-template](https://github.com/homebridge/homebridge-plugin-template)
and the [NOAA / NWS API documentation](https://www.weather.gov/documentation/services-web-api).
**No breaking config changes** — existing v1.5 installs upgrade in place.

### Security & hardening

- **Input validation on `stationId`** — both manually configured and
  cache-loaded values are regex-validated (`^[A-Z0-9]{3,8}$`) before any
  URL interpolation. Defense-in-depth `encodeURIComponent` applied to all
  path components.
- **Grid response validation** — `gridId`/`gridX`/`gridY` are
  shape-validated before being interpolated into the gridpoint stations
  URL.
- **Atomic cache writes** — cache files written via temp-then-rename with
  `0o600` permissions; eliminates corruption from interrupted writes.
- **Bounded response size** — NOAA responses capped at 2 MB to defend
  against pathological payloads.
- **Bounded `Retry-After`** — server-supplied retry delays capped at
  5 minutes to prevent indefinite stalls.
- **Header-injection safe `User-Agent`** — optional `userAgentContact`
  config field is sanitized to strip CR/LF and length-capped before
  being placed in the HTTP header.
- **Coordinate range validation** at both schema and runtime
  (`-90..90` / `-180..180`).

### Minimization

- **Dropped `axios` dependency entirely** — replaced with native Node 18+
  `fetch` and `AbortController`. Zero runtime dependencies.
- **Removed self-heal recovery code** in the accessory — the previous
  `addService()` retry path could not succeed (Homebridge rejects
  duplicate subtypes). We now trust HAP-NodeJS and log-and-continue on
  rare characteristic update failures.
- **Removed `require_qc=true` query parameter** — verified against the
  NOAA OpenAPI spec. Replaced with **client-side QC filtering** that
  accepts MADIS flags `V`, `C`, `S`, `Z` (per
  [MADIS QC notes](https://madis.ncep.noaa.gov/madis_sfc_qc_notes.shtml)).
- **Deleted dead state** (`lastTemperature`/`lastHumidity` fields that
  were written but never read).
- **Dropped per-instance/static metric duplication** — now a single
  per-platform metrics object, no leak across child-bridge restarts.
- **Removed undocumented `Referer` header** — NWS docs do not require it.

### NOAA / NWS correctness

- **NWS-recommended `User-Agent` format** — uses
  `(github.com/Phirtue/homebridge-weather-noaa, contact)` per the
  [API docs](https://www.weather.gov/documentation/services-web-api).
- **Rate-limit floor at 5s** — anchored to NWS docs guidance:
  *"may be retried after the limit clears (typically within 5 seconds)."*
- **`unitCode`-aware temperature conversion** — observations reported in
  `wmoUnit:degF` or `wmoUnit:K` are now correctly converted to °C
  instead of being trusted blindly as Celsius.
- **Humidity clamped to `[0, 100]`** before being pushed to HomeKit.
- **`config.schema.json` `refreshInterval` default** changed to `15` to
  match the runtime default.

### Reliability

- **No overlapping requests** — polling tick is mutex-guarded so a slow
  NOAA response cannot cause request pile-up.
- **Proper teardown** — `setTimeout`/`setInterval` handles tracked and
  cleared on Homebridge `shutdown` event; timers `unref`'d so they don't
  hold the event loop open.
- **`process.on('exit', ...)` listeners removed** — replaced with the
  Homebridge `shutdown` event so child-bridge restarts don't leak
  listeners.

### Template alignment

- **Source split into `settings.ts` / `index.ts` / `platform.ts` /
  `platformAccessory.ts`** matching the current Homebridge plugin
  template.
- **Accessories tracked in a `Map<string, PlatformAccessory>`** with O(1)
  UUID lookup, including stale-accessory cleanup.
- **`Logging` type used** instead of the deprecated `Logger` alias.
- **`AccessoryInformation` service populated** with manufacturer, model,
  serial, and firmware revision.
- **ESLint flat config** with `--max-warnings=0` enforced via
  `prepublishOnly`.
- **Two-arg `registerPlatform`** form per the current Homebridge API.

### Features

- **Adaptive polling** — when readings remain stable across consecutive
  polls, the interval automatically backs off up to 4× the base.
  Resets immediately on any change or error. Toggle via `adaptivePolling`
  config (default: on).

### Notes

- **Stable accessory UUID preserved** (`noaa-weather-unique`) so existing
  HomeKit room assignments and automations survive the upgrade.
- Existing station caches are honored if they validate against the new
  stricter schema; otherwise rebuilt automatically.
- Optional new config: `userAgentContact` (string) — adds your contact
  to the NOAA User-Agent header. Recommended by NWS.

---

## [1.5.0] - 2026-01-31

### Enhancements
- **Node.js 24 LTS support** — Officially tested and compatible with Node.js 24 (Krypton).
- **NOAA API alignment** — Uses the modern Points → Gridpoints → Stations flow (replaces deprecated `/points/{lat,lon}/stations`) and requests observations with `require_qc=true` for quality-controlled data.
- **429 Rate Limiting** — Added proper handling for NOAA API rate limiting with `Retry-After` header support.
- **Improved service management** — Use stable subtypes (`noaa-temperature`, `noaa-humidity`) with `getServiceById()` to prevent service collisions.
- **Safer config parsing** — Config values now properly coerced with `Number()` and validated with `Number.isFinite()` to handle string inputs from Homebridge UI.
- Updated dependencies:
  - `axios` to ^1.7.9
  - `typescript` to ^5.7.3
  - `@types/node` to ^22.10.7
- Ensures seamless operation on Homebridge installations running Node.js 18, 20, 22, or 24.

### Bug Fixes
- Fixed potential issue where latitude/longitude of `0` would be incorrectly treated as invalid.
- Improved TypeScript compatibility by using HAP characteristics via `this.platform.api.hap.Characteristic.*`.

### Notes
- No breaking changes from 1.4.0.
- Users on Node.js 24 will no longer see engine compatibility warnings during installation.
- Existing station caches will be rebuilt on first run to include new grid metadata.

---

## [1.4.0] - 2025-08-04

### Enhancements
- Added detailed metrics tracking:
  - API request failures
  - Retry attempts
  - Station cache resets
  - Cache write errors
  - Characteristic update errors
  - HomeKit service recovery attempts
- Implemented hourly and shutdown metrics logging for easier troubleshooting.
- All logs now display timestamps in the local timezone of the Homebridge device.
- Improved logging consistency across both platform and accessory code.
- Explicitly marked as **Homebridge v2 compatible**
- Added marketing tagline to highlight NOAA accuracy and v2 readiness.

### Bug Fixes
- Fixed potential stale data issues by ensuring forced updates to HomeKit.
- Improved automatic recovery from:
  - Corrupted cache files
  - Missing HomeKit services
- Prevents plugin from throwing unhandled exceptions that could crash Homebridge.

---

## [1.3.0] - 2025-08-03

### Enhancements
- Reuses cached accessories to avoid “Cached accessory found (not used)” messages.
- Ensures only one NOAA Weather accessory is created and reused after Homebridge restarts.
- Maintains persistent caching of station lookup and last NOAA readings.
- Forces HomeKit updates every fetch to keep displayed temperature and humidity synchronized.

### Bug Fixes
- Fixed duplicate accessory registration issues.
- Improved startup logs and accessory reuse behavior.

---

## [1.2.0] - 2025-08-03

### Enhancements
- HomeKit always shows a valid temperature and humidity reading, even right after restart.
- Persistent caching of last NOAA readings (`noaa-weather-last.json`).
- Real-time characteristic updates for temperature and humidity on each NOAA fetch.
- NOAA unchanged readings logged without skipping HomeKit updates.
- Graceful handling of NOAA null values.

### Bug Fixes
- Fixed brief zero or missing readings when NOAA API response delayed.
- Improved robustness of cache writes.

---

## [1.1.0] - 2025-08-03

### Enhancements
- Cached NOAA station lookups for 30 days.
- Added retry logic with exponential backoff for transient NOAA API errors.
- Updated headers to NOAA compliance (`Referer` and improved `User-Agent`).
- Manual station override supported.
- Metadata improvements for Homebridge verified plugin.
- Added CI tests for Node.js 18, 20, 22 with Homebridge v1 and v2 compatibility.

### Bug Fixes
- Fixed missing Node typings.
- Improved station selection and caching.
- Reused cached stations for efficiency.

---

## [1.0.0] - 2025-08-02

### Initial Release
- Basic Homebridge platform plugin providing temperature and humidity sensors via NOAA API.
- Supports automatic station detection and manual configuration.
- Fetches real-time NOAA observations and displays in HomeKit.