@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.

Setup

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

• Pass location (free-form city or place) or latitude + longitude.
• Optional label names a coordinate pair in summaries.
• Weather and forecast caches live in this package's packageStorage() (weatherCache, forecastHistory) and are best-effort.

When to use

• Current, forecast, or historical weather (weather, plus weather-geocode when you only have a place name).
• Sunrise, sunset, twilight, and day length (sun).
• Moon phase, illumination, and next full/new moon (moon, computed locally with no API).
• Outdoor air quality (summarizeAirQuality, or ./air-quality for the hourly series).
• Ground elevation in meters and feet (elevation).
• Resilient forecast highs when live Open-Meteo is degraded (forecast-history).
• One combined briefing (snapshot: weather + air quality + sun + moon, with independent per-section errors).

Exports

• kody:@kody/environment — overview plus getAirQuality and summarizeAirQuality.
• kody:@kody/environment/weather — daily/hourly weather with cache fallback.
• kody:@kody/environment/weather-geocode — resolve a place name or coordinates.
• kody:@kody/environment/sun — sunrise, sunset, twilight, day length.
• kody:@kody/environment/moon — moon phase, illumination, next full/new moon (no API).
• kody:@kody/environment/air-quality — full hourly AQI payload.
• kody:@kody/environment/elevation — ground elevation.
• kody:@kody/environment/forecast-history — forecast daily high with history/seasonal fallback.
• kody:@kody/environment/snapshot — combined outdoor report.

Named ESM exports work via static import { ... }. For keyless packages.invoke, use a subpath whose default export is the function (for example exportName: "weather"), or call the root overview.

Example

import { summarizeAirQuality } from 'kody:@kody/environment'
import environmentSnapshot from 'kody:@kody/environment/snapshot'
import weatherLookup from 'kody:@kody/environment/weather'

export default async function main() {
	const byCity = await weatherLookup({ location: 'Reykjavík' })
	const byCoords = await summarizeAirQuality({
		latitude: 40.7128,
		longitude: -74.006,
		label: 'New York City',
	})
	const snapshot = await environmentSnapshot({ location: 'Tokyo' })
	return { byCity, byCoords, snapshot }
}

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