# @kody/environment

## Intent

Reusable outdoor environment lookups for any city or coordinates: weather,
air quality, sun times, moon phase, elevation, forecast-history fallbacks,
and one-call snapshots. Built for agents that need public, zero-auth
environment data instead of a home-specific default location.

## What it does

- Daily/hourly **weather** with durable cache fallback when live Open-Meteo is degraded
- **Weather geocode** — free-form place names or direct coordinates
- **Sun** — sunrise, sunset, twilight, solar noon, day length
- **Moon** — phase, illumination, next full/new moon (computed locally; no API)
- **Air quality** — hourly series plus US EPA AQI helpers (`getAirQuality`,
  `summarizeAirQuality` on the root export)
- **Elevation** — ground elevation via Open-Meteo Elevation API
- **Forecast history** — persist / read resilient forecast highs
- **Snapshot** — one-call weather + air quality + sun + moon; sections degrade
  independently (`{ error }` per section instead of throwing)

## Prerequisites / setup

Usually none. This package calls public APIs (Open-Meteo, Nominatim,
sunrise-sunset.org). No secrets, OAuth, or API keys.

1. Pass `location` (free-form city or place) or `latitude` + `longitude`.
2. Optional `label` names a coordinate pair in summaries.
3. Weather and forecast caches live in this package's `packageStorage()`
   (`weatherCache`, `forecastHistory`) and are best-effort.
4. Agents: see [`AGENTS.md`](./AGENTS.md) for import paths and smoke checks.

## Done when

- Root overview or `summarizeAirQuality()` / `./snapshot` returns without error
  for a city or coordinate pair you choose
- You can resolve a place with `./weather-geocode` and fetch weather/sun/moon/AQI
- Snapshot sections that fail upstream return `{ error }` for that section only

## Attribution

Weather, air-quality, and elevation data from
[Open-Meteo](https://open-meteo.com/) (CC BY 4.0). Place search via
[Nominatim / OpenStreetMap](https://nominatim.org/). Sun times from
[sunrise-sunset.org](https://sunrise-sunset.org/api) with Open-Meteo
timezone fallback.

## License

MIT