@molecule/api-weather-open-meteo

Auto-generated, AI-first package reference for the molecule.dev ecosystem. It is written to be read by coding agents as much as by people, and is generated from this package's source — edit src/index.ts JSDoc, not this file.

Open-Meteo weather provider for molecule.dev.

Implements the WeatherProvider interface against the public Open-Meteo forecast endpoint (https://api.open-meteo.com/v1/forecast), which is keyless, free for non-commercial use, and emits WMO 4677 weather codes directly. Open-Meteo's native units (Celsius, mm, km/h, percent) already match the core interface, so the provider performs a structural reshape rather than a unit conversion.

Quick Start

import { setProvider } from '@molecule/api-weather'
import { provider } from '@molecule/api-weather-open-meteo'

setProvider(provider)

Type

provider

Installation

npm install @molecule/api-weather-open-meteo @molecule/api-weather

API

Interfaces

OpenMeteoWeatherConfig

Configuration options for the Open-Meteo weather provider.

Open-Meteo's public forecast endpoint (https://api.open-meteo.com/v1/forecast) is keyless and free for non-commercial use, so all fields are optional.

interface OpenMeteoWeatherConfig {
  /**
   * Base URL override. Defaults to `'https://api.open-meteo.com/v1'`.
   * Useful for self-hosted Open-Meteo instances or for the commercial
   * `customer-api.open-meteo.com` endpoint.
   */
  baseUrl?: string

  /**
   * API key, sent as the `apikey` query parameter. Only required for the
   * commercial customer endpoint; ignored by the public service.
   */
  apiKey?: string

  /**
   * Request timeout in milliseconds. Defaults to `10000`.
   */
  timeout?: number

  /**
   * Default IANA timezone used when {@link WeatherLocation.timezone} is
   * omitted. Defaults to `'auto'`, which lets Open-Meteo derive the
   * location's local timezone server-side.
   */
  defaultTimezone?: string
}

Functions

createProvider(config)

Creates an Open-Meteo weather provider.

function createProvider(config?: OpenMeteoWeatherConfig): WeatherProvider

• config — Provider configuration. All fields are optional.

Returns: A WeatherProvider backed by the Open-Meteo forecast API.

summarizeWmoCode(code)

Maps a WMO 4677 numeric weather code to a short English summary.

The mapping covers the codes Open-Meteo emits. Unknown codes fall back to a generic 'Unknown' label so summary always returns a non-empty string.

function summarizeWmoCode(code: number): string

• code — WMO 4677 weather code.

Returns: Short English summary suitable for developer-facing logs.

Constants

provider

The provider implementation, lazily initialized on first use.

Reads OPEN_METEO_BASE_URL and OPEN_METEO_API_KEY from environment variables for optional self-hosted or commercial endpoints. The public Open-Meteo service requires neither.

const provider: WeatherProvider

Core Interface

Implements @molecule/api-weather interface.

Bond Wiring

Setup function to register this provider with the core interface:

import { setProvider } from '@molecule/api-weather'
import { provider } from '@molecule/api-weather-open-meteo'

export function setupWeatherOpenMeteo(): void {
  setProvider(provider)
}

Injection Notes

Requirements

Peer dependencies:

• @molecule/api-weather ^1.0.1

Runtime Dependencies

• @molecule/api-weather

E2E Tests

Integration checklist — drive the real UI (live preview, no mocks), adapt each item to this app's actual screens/flows, and check every box off one by one. A box you can't check is an integration bug to fix — not a skip:

• Requesting weather for a real location (getCurrent) renders PLAUSIBLE current conditions in the UI — a temperature in a sane range (roughly -60 to 60 °C), a non-empty summary/condition, plus the humidity (0–100) and wind the widget shows — never null, NaN, "--"/placeholder, or a hardcoded constant that never moves. Reload and confirm values track the provider.
• If a forecast is shown, getForecast returns MULTIPLE future days with DISTINCT values (min/max temps and codes vary day to day), and getHourly likewise — not one row repeated N times or every day identical.
• Changing the location changes the data: fetch two clearly different coordinates (e.g. a tropical vs. a polar city) and confirm the rendered current + forecast actually differ. Identical output for different lat/lon means the location never reached the provider.
• Units: the core normalizes everything to metric (Celsius, km/h, mm). If the UI offers a °F / imperial toggle it is an app-side conversion — flipping it must consistently convert EVERY displayed value (current, feels-like, forecast min/max, wind) while the fetched data stays metric; no half- converted mix (a °C label over an °F number, or wind left in km/h).
• An unknown place name (if the app geocodes) or out-of-range coordinates surfaces a clear "not found" — not a blank widget — and a provider outage or rate-limit (429) surfaces a graceful message that leaves the last-known reading or an empty state. The app never crashes, spins forever, or shows NaN/undefined.
• The provider API key (if the bonded provider needs one) stays server- side — never shipped to the browser or a client bundle — and the weather endpoint is not an open unbounded proxy: it accepts only the app's own locations, not arbitrary caller-supplied upstream URLs or keys.