@kody/environment

@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 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 (CC BY 4.0). Place search via Nominatim / OpenStreetMap. Sun times from sunrise-sunset.org with Open-Meteo timezone fallback.

License

MIT