@khalido/home 0.0.0-stage → 0.1.1

package/src/connectors/weather/index.ts

@@ -0,0 +1,396 @@
+import { type Clock, localTime, realClock } from "../../clock.ts";
+import type { Integration, Status } from "../../home.ts";
+import { field, type Manifest } from "../../manifest.ts";
+import { poller } from "../../poll.ts";
+import {
+  type BlockDef,
+  blockText,
+  checkBlocks,
+  type DayBlocks,
+  dayBlocks,
+} from "./blocks.ts";
+import { openMeteo } from "./open-meteo.ts";
+import { type RainSoon, rainSoon } from "./rain.ts";
+import {
+  DEFAULT_POLL_MINUTES,
+  type ForecastDay,
+  RAIN_HORIZON_MINUTES,
+  type SliceName,
+  type Slices,
+  sourcePollMinutes,
+  type SourceReading,
+  mergeWeather,
+  type WeatherSource,
+} from "./source.ts";
+import { type SunNow, sunNow } from "./sun.ts";
+
+export {
+  type Condition,
+  type ForecastDay,
+  type ForecastHour,
+  mergeWeather,
+  nextPoll,
+  type Place,
+  type RainSegment,
+  type ReadRequest,
+  type SkyHour,
+  type SliceMeta,
+  type Slices,
+  type SourceReading,
+  type WeatherForecast,
+  type WeatherHourly,
+  type WeatherNow,
+  type WeatherRain,
+  type WeatherSky,
+  type WeatherSource,
+} from "./source.ts";
+export { type SunNext, type SunNow, sunNow } from "./sun.ts";
+export { type RainSoon, rainSoon } from "./rain.ts";
+export {
+  type BlockDef,
+  BLOCKS,
+  blockText,
+  type DayBlock,
+  type DayBlocks,
+  dayBlocks,
+} from "./blocks.ts";
+export { bom, type BomOptions } from "./bom.ts";
+export { openMeteo, type OpenMeteoOptions } from "./open-meteo.ts";
+export { google, type GoogleOptions } from "./google.ts";
+
+/** The sun moves about a degree every four minutes; recompute it this often between source reads. */
+const SUN_MS = 5 * 60_000;
+/** However soon a source asks to be called again, never sooner than this. */
+const MIN_POLL_MS = 60_000;
+
+/**
+ * Where the home is, and the sources in preference order: each slice comes from the first source with a fresh one.
+ * The default is `[openMeteo()]`, which works anywhere with no key. In Australia put `bom({ fetch: ftpFetch(), forecastLocation })`
+ * first: it needs the FTP transport, so it is opt-in. `pollMinutes` (default 15) is how often observations and sky are read;
+ * forecasts follow their issue times. `timeZone` (IANA, the runtime's when left out) is where the home's day and its times are.
+ * `blocks` are the parts of the day `state.blocks` is cut into (`BLOCKS` by default).
+ */
+export type WeatherConfig = {
+  latitude: number;
+  longitude: number;
+  sources?: WeatherSource[];
+  pollMinutes?: number;
+  timeZone?: string;
+  blocks?: readonly BlockDef[];
+  clock?: Clock;
+};
+
+/** The weather in the snapshot: one slice each from the preferred fresh source, the sun, and how each source is doing. */
+export type WeatherState = Slices & {
+  sun: SunNow;
+  rainSoon?: RainSoon; // recomputed at every report and every 5 minutes; a consumer with its own clock calls `rainSoon(state.rain, now)`
+  blocks?: DayBlocks; // the same: `dayBlocks(state.hourly, now, state.timeZone, blocks)`
+  timeZone?: string; // the config's, which the blocks and the text use
+  sources: Record<
+    string,
+    { read: boolean; problem?: string; stopped?: string; anomaly?: string }
+  >;
+};
+
+const SLICE_NAMES = [
+  "now",
+  "forecast",
+  "hourly",
+  "sky",
+  "rain",
+] as const satisfies readonly SliceName[];
+
+/** Outside weather as a home integration. Each source polls on its own cadence; the sun is computed, never fetched. */
+export function weather(
+  config: WeatherConfig,
+): Integration<WeatherState, "weather"> {
+  const sources = config.sources ?? [openMeteo()];
+  const clock = config.clock ?? realClock;
+  const pollMinutes = config.pollMinutes ?? DEFAULT_POLL_MINUTES;
+  if (!(pollMinutes >= 1))
+    throw new Error(
+      `weather: pollMinutes must be at least 1, got ${config.pollMinutes}`,
+    );
+  if (config.blocks) checkBlocks(config.blocks); // a bad block fails here, not at every report
+  const place = { latitude: config.latitude, longitude: config.longitude };
+  const readings = new Map<string, SourceReading>();
+  const fresh = new Map<string, boolean>(); // whether a source's latest read brought anything new, rather than its last good slices again
+  let readAt: number | undefined; // the last read that brought something new: the part's `lastGoodAt`, so a re-report is not a read
+  const polls = new Map(sources.map((s) => [s.name, poller(clock)]));
+  let answer: (() => void) | undefined; // reports now: for a refresh no source will answer
+
+  return {
+    name: "weather",
+    /**
+     * Read every source now, whatever its schedule, forecasts included (`force`). A source with a floor (a billed one,
+     * Google) is not forced, and is skipped when its last read is younger than its floor.
+     */
+    refresh() {
+      for (const poll of polls.values()) poll.nudge();
+      if (sources.every((s) => readings.get(s.name)?.stop)) answer?.(); // every source has stopped: none will read, so say so now
+    },
+    async run(signal, update) {
+      const emit = () => {
+        const at = clock.now();
+        const slices = mergeWeather(
+          sources.map((source) => ({
+            source,
+            reading: readings.get(source.name),
+          })),
+          at,
+          pollMinutes,
+        );
+        const report = Object.fromEntries(
+          sources.map((s) => {
+            const r = readings.get(s.name);
+            return [
+              s.name,
+              {
+                read: r !== undefined,
+                problem: r?.problem,
+                stopped: r?.stop,
+                anomaly: r?.anomaly,
+              },
+            ];
+          }),
+        );
+        // Connected while some source's latest read brought something new; its older slices alone are a failed read, kept as state.
+        const status: Status = sources.some((s) => fresh.get(s.name))
+          ? "connected"
+          : sources.every((s) => readings.get(s.name)?.stop)
+            ? "unavailable"
+            : "disconnected";
+        const notes = (k: "problem" | "stopped" | "anomaly") =>
+          Object.values(report)
+            .map((r) => r[k])
+            .filter(Boolean)
+            .join("; ") || undefined;
+        const detail =
+          [notes("stopped"), notes("problem")].filter(Boolean).join("; ") ||
+          undefined;
+        const lastGoodAt =
+          status === "connected" && readAt !== undefined
+            ? new Date(readAt).toISOString()
+            : undefined;
+        update({
+          status,
+          detail,
+          anomaly: notes("anomaly"),
+          lastGoodAt,
+          state: {
+            ...slices,
+            sun: sunNow(place.latitude, place.longitude, at),
+            rainSoon: rainSoon(slices.rain, at),
+            blocks: dayBlocks(
+              slices.hourly,
+              at,
+              config.timeZone,
+              config.blocks,
+            ),
+            timeZone: config.timeZone,
+            sources: report,
+          },
+        });
+      };
+      const poll = async (source: WeatherSource) => {
+        const floorMs = (source.minPollMinutes ?? 0) * 60_000;
+        let force = false;
+        while (!signal.aborted) {
+          const at = clock.now();
+          const reading = await source.read({
+            place,
+            at,
+            pollMinutes: sourcePollMinutes(source, pollMinutes),
+            force,
+            signal,
+          });
+          if (signal.aborted) return; // an aborted read is not a problem to report
+          readings.set(source.name, reading);
+          const isFresh = SLICE_NAMES.some((k) =>
+            reading[k]?.fetchedAt
+              ? Date.parse(reading[k]!.fetchedAt) >= at
+              : false,
+          );
+          fresh.set(source.name, isFresh);
+          if (isFresh) readAt = Math.max(readAt ?? at, at);
+          emit();
+          if (reading.stop) return;
+          for (;;) {
+            const woken = await polls
+              .get(source.name)!
+              .wait(
+                Math.max(reading.nextAt - clock.now(), MIN_POLL_MS),
+                signal,
+              );
+            if (woken && clock.now() - at < floorMs) {
+              emit(); // a refresh never beats a billed source's floor, but it gets an answer: what there is now
+              continue;
+            }
+            force = woken && !floorMs;
+            break;
+          }
+        }
+      };
+      answer = emit;
+      const sun = async () => {
+        while (!signal.aborted) {
+          await clock.sleep(SUN_MS, signal);
+          if (!signal.aborted) emit();
+        }
+      };
+      await Promise.all([...sources.map(poll), sun()]);
+    },
+  };
+}
+
+/** "20:20" in the home's time zone (the runtime's when unset), or "?". */
+const hhmmIn = (iso: string | undefined, timeZone?: string) =>
+  iso ? localTime(Date.parse(iso), timeZone) : "?";
+const day = (d?: ForecastDay, rainLeft?: number) =>
+  d
+    ? [
+        d.minC === undefined && d.maxC === undefined
+          ? ""
+          : `${d.minC ?? "?"}–${d.maxC ?? "?"} °C`,
+        d.text?.replace(/\.$/, "").toLowerCase() ?? "",
+        d.rainChance === undefined
+          ? ""
+          : rainLeft !== undefined && rainLeft < d.rainChance
+            ? `${rainLeft}% chance of rain the rest of the day`
+            : `${d.rainChance}% chance of rain`,
+      ]
+        .filter(Boolean)
+        .join(" ")
+    : "?";
+
+/** The highest hourly chance left today, all 24 hours of it, when the hourly forecast is the same source and day as the forecast: sources are never mixed. */
+const rainLeftToday = (
+  w: Pick<Slices, "forecast" | "hourly"> & { timeZone?: string },
+  at: number,
+) => {
+  if (!w.hourly || w.hourly.source !== w.forecast?.source) return undefined;
+  const rest = dayBlocks(w.hourly, at, w.timeZone, [
+    { name: "rest", from: 0, to: 24 },
+  ])?.today[0];
+  return rest?.date === w.forecast.today?.date ? rest?.rainChance : undefined;
+};
+
+/** "rain in 30 min, ends in 55 min, 70%, 0.8 mm, moderate (google)", "raining, ends in 25 min", or "no rain for 2 h"; nothing when the forecast covers none of the window. */
+export function rainText(
+  rain: Slices["rain"],
+  r: RainSoon | undefined,
+): string {
+  if (!r || !rain) return "";
+  const covered =
+    r.coveredMin >= RAIN_HORIZON_MINUTES
+      ? `${RAIN_HORIZON_MINUTES / 60} h`
+      : `${r.coveredMin} min`;
+  if (!r.wet) return `no rain for ${covered} (${rain.source})`;
+  const end =
+    r.endsInMin !== undefined
+      ? `ends in ${r.endsInMin} min`
+      : r.startsInMin === 0
+        ? `still at ${covered}`
+        : "";
+  const parts = [
+    r.startsInMin === 0 ? "raining" : `rain in ${r.startsInMin} min`,
+    end,
+    field(r.chance, (v) => `${v}%`),
+    field(r.mm, (v) => `${v} mm`),
+    r.intensity && r.intensity !== "NO_INTENSITY"
+      ? r.intensity.toLowerCase()
+      : "",
+  ];
+  return `${parts.filter(Boolean).join(", ")} (${rain.source})`;
+}
+
+/** The weather in one line, every part named by its source and time, never mixed. */
+export function weatherText(
+  w: Slices & { rainSoon?: RainSoon; timeZone?: string },
+  sun: SunNow,
+): string {
+  const n = w.now;
+  const hhmm = (iso?: string) => hhmmIn(iso, w.timeZone);
+  const readings = n
+    ? [
+        field(n.tempC, (v) => `${v} °C`),
+        field(n.apparentC, (v) => `feels ${v}`),
+        field(n.humidity, (v) => `${v}%`),
+        field(n.rainMm, (v) => `${v} mm since 9am to ${hhmm(n.rainTo)}`),
+      ]
+        .filter(Boolean)
+        .join(", ")
+    : "";
+  const now = n
+    ? `${n.station ? `${n.station.name} (${n.station.distanceKm.toFixed(1)} km)` : n.source} ${hhmm(n.at)}${n.modelled ? " modelled" : ""}: ${readings}`
+    : "";
+  const f = w.forecast;
+  const forecast = f
+    ? `today ${day(f.today, rainLeftToday(w, Date.parse(sun.at)))}, tomorrow ${day(f.tomorrow)} (${f.source}${f.modelled ? " modelled" : ""})`
+    : "";
+  const k = w.sky;
+  const skyParts = k
+    ? [
+        field(k.cloudPct, (v) => `cloud ${v}%`),
+        field(k.uvIndex, (v) => `UV ${v}`),
+        field(k.radiationWm2, (v) => `${v} W/m²`),
+      ]
+        .filter(Boolean)
+        .join(", ")
+    : "";
+  const sky = k ? `${skyParts} (${k.source})` : "";
+  const sunText = `sun ${Math.round(sun.altitudeDeg)}°, ${sun.rising ? "rising" : "setting"}, ${sun.daylight ? `sets ${hhmm(sun.next.sunset)}` : `rises ${hhmm(sun.next.sunrise)}`}`;
+  return [now, forecast, sky, rainText(w.rain, w.rainSoon), sunText]
+    .filter(Boolean)
+    .join(" · ");
+}
+
+/** "today: afternoon …; evening …" and the same for tomorrow, when there is an hourly forecast. */
+const blockLines = (state: Pick<WeatherState, "blocks" | "timeZone">) =>
+  state.blocks
+    ? (["today", "tomorrow"] as const)
+        .filter((d) => state.blocks![d].length)
+        .map(
+          (d) =>
+            `${d}: ${state.blocks![d].map((b) => blockText(b, state.timeZone)).join("; ")} (${state.blocks!.source})`,
+        )
+    : [];
+
+export const manifest: Manifest<WeatherState> = {
+  name: "weather",
+  title: "Weather",
+  iotClass: "cloud_polling",
+  pollSeconds: DEFAULT_POLL_MINUTES * 60,
+  access:
+    "BOM anonymous FTP, Open-Meteo, Google with GOOGLE_WEATHER_KEY; sun computed",
+  env: [
+    {
+      name: "HOME_LATITUDE",
+      example: "-33.8688",
+      what: "the home's position for weather and the sun (this one is Sydney CBD)",
+    },
+    { name: "HOME_LONGITUDE", example: "151.2093", what: "" },
+    {
+      name: "HOME_TIMEZONE",
+      example: "Australia/Sydney",
+      optional: true,
+      what: "the home's IANA time zone for weather times and day blocks; this machine's when unset",
+    },
+    {
+      name: "HOME_BOM_FORECAST",
+      example: "Sydney",
+      optional: true,
+      what: "BOM précis location by name or aac; unset, the forecast comes from Open-Meteo",
+    },
+    {
+      name: "GOOGLE_WEATHER_KEY",
+      example: "",
+      optional: true,
+      what: "Maps Platform key with the Weather API enabled",
+    },
+  ],
+  lines: ({ state }) =>
+    state ? [weatherText(state, state.sun), ...blockLines(state)] : [],
+  record: ({ state }) =>
+    state ? { ...state, line: weatherText(state, state.sun) } : {},
+};

package/src/connectors/weather/open-meteo.ts

@@ -0,0 +1,309 @@
+import { z } from "zod";
+import { getJson } from "../../connector.ts";
+import {
+  type Condition,
+  type ForecastDay,
+  type ForecastHour,
+  HOURLY_MINUTES,
+  iso,
+  localDate,
+  nextPoll,
+  num,
+  type SourceReading,
+  USER_AGENT,
+  type WeatherSource,
+} from "./source.ts";
+
+// Open-Meteo's forecast API (https://open-meteo.com/en/docs): keyless, JSON, data CC BY 4.0. No `models`, so the default
+// best_match answers; its BOM model (bom_access_global) has returned only nulls since BOM paused open data in mid 2025.
+
+const CURRENT =
+  "temperature_2m,apparent_temperature,relative_humidity_2m,wind_speed_10m,wind_direction_10m,wind_gusts_10m,cloud_cover,uv_index,shortwave_radiation,weather_code";
+const HOURLY =
+  "temperature_2m,apparent_temperature,precipitation_probability,precipitation,weather_code,wind_speed_10m,wind_gusts_10m,cloud_cover,uv_index,shortwave_radiation";
+/** How many hours ahead `sky.hours` holds. */
+const SKY_HOURS = 6;
+const DAILY =
+  "temperature_2m_max,temperature_2m_min,precipitation_probability_max,precipitation_sum,weather_code";
+
+const series = z.array(z.number().nullable()).optional();
+const OpenMeteoResponse = z.looseObject({
+  utc_offset_seconds: z.number().optional(),
+  current: z.record(z.string(), z.unknown()).optional(),
+  hourly: z
+    .looseObject({
+      time: z.array(z.string()),
+      temperature_2m: series,
+      apparent_temperature: series,
+      precipitation_probability: series,
+      precipitation: series,
+      weather_code: series,
+      wind_speed_10m: series,
+      wind_gusts_10m: series,
+      cloud_cover: series,
+      uv_index: series,
+      shortwave_radiation: series,
+    })
+    .optional(),
+  daily: z
+    .looseObject({
+      time: z.array(z.string()),
+      temperature_2m_max: series,
+      temperature_2m_min: series,
+      precipitation_probability_max: series,
+      precipitation_sum: series,
+      weather_code: series,
+    })
+    .optional(),
+});
+
+/** WMO weather codes as Open-Meteo documents them (the table at the end of its docs page). */
+const WMO: Record<number, string> = {
+  0: "Clear sky",
+  1: "Mainly clear",
+  2: "Partly cloudy",
+  3: "Overcast",
+  45: "Fog",
+  48: "Depositing rime fog",
+  51: "Light drizzle",
+  53: "Moderate drizzle",
+  55: "Dense drizzle",
+  56: "Light freezing drizzle",
+  57: "Dense freezing drizzle",
+  61: "Slight rain",
+  63: "Moderate rain",
+  65: "Heavy rain",
+  66: "Light freezing rain",
+  67: "Heavy freezing rain",
+  71: "Slight snow",
+  73: "Moderate snow",
+  75: "Heavy snow",
+  77: "Snow grains",
+  80: "Slight rain showers",
+  81: "Moderate rain showers",
+  82: "Violent rain showers",
+  85: "Slight snow showers",
+  86: "Heavy snow showers",
+  95: "Thunderstorm",
+  96: "Thunderstorm with slight hail",
+  99: "Thunderstorm with heavy hail",
+};
+
+/** WMO codes in a word: 0–1 clear, 2 partly cloudy, 3 cloudy, then by family. */
+export function wmoCondition(code: number): Condition | undefined {
+  if (!(code in WMO)) return undefined;
+  if (code <= 1) return "clear";
+  if (code === 2) return "partly cloudy";
+  if (code === 3) return "cloudy";
+  if (code < 50) return "fog";
+  if (code < 60) return "drizzle";
+  if (code < 70) return "rain";
+  if (code < 80) return "snow";
+  if (code < 85) return "showers";
+  if (code < 95) return "snow"; // snow showers
+  return "storm";
+}
+
+/** Open-Meteo's local times ("2026-10-13T20:15") to UTC ISO, using the response's offset; undefined when it does not parse. Open-Meteo applies that one offset to every time it returns, across a daylight-saving change too (checked live, 2026-10-16), so it is right for all of them. */
+const utc = (local: string, offset: number) => {
+  const t = Date.parse(`${local}Z`);
+  return Number.isNaN(t)
+    ? undefined
+    : iso(new Date(t - offset * 1000).toISOString());
+};
+const value = (s: (number | null)[] | undefined, i: number) =>
+  s?.[i] ?? undefined;
+
+/** Map one forecast response to slices. Everything here is a model, so every slice says `modelled: true`. `forecastAt` is when the daily part was read. */
+export function toSlices(
+  body: unknown,
+  fetchedAt: number,
+  forecastAt = fetchedAt,
+): Omit<SourceReading, "nextAt"> {
+  const r = OpenMeteoResponse.parse(body);
+  const offset = r.utc_offset_seconds ?? 0;
+  const odd: string[] = [];
+  const meta = (at: string) => ({
+    source: "open-meteo",
+    modelled: true,
+    at,
+    fetchedAt: new Date(fetchedAt).toISOString(),
+  });
+  const c = r.current;
+  const cur = (k: string) => num(c?.[k], `current.${k}`, odd);
+  const code = cur("weather_code");
+  const nowAt = typeof c?.time === "string" ? utc(c.time, offset) : undefined;
+  if (c && !nowAt) odd.push(`current.time not understood: ${String(c.time)}`);
+  const now = nowAt
+    ? {
+        ...meta(nowAt),
+        tempC: cur("temperature_2m"),
+        apparentC: cur("apparent_temperature"),
+        humidity: cur("relative_humidity_2m"),
+        windKmh: cur("wind_speed_10m"),
+        windDeg: cur("wind_direction_10m"),
+        gustKmh: cur("wind_gusts_10m"),
+      }
+    : undefined;
+  const h = r.hourly;
+  const unknownCodes = new Set<number>();
+  const hours = (h?.time ?? []).flatMap((t, i) => {
+    const at = utc(t, offset);
+    if (!at) odd.push(`hourly time not understood: ${t}`);
+    if (!at) return [];
+    const wmo = value(h?.weather_code, i);
+    if (wmo !== undefined && !(wmo in WMO)) unknownCodes.add(wmo);
+    const hour: ForecastHour & { radiationWm2?: number } = {
+      at,
+      tempC: value(h?.temperature_2m, i),
+      apparentC: value(h?.apparent_temperature, i),
+      rainChance: value(h?.precipitation_probability, i),
+      rainMm: value(h?.precipitation, i),
+      windKmh: value(h?.wind_speed_10m, i),
+      gustKmh: value(h?.wind_gusts_10m, i),
+      cloudPct: value(h?.cloud_cover, i),
+      uvIndex: value(h?.uv_index, i),
+      radiationWm2: value(h?.shortwave_radiation, i),
+      code: wmo === undefined ? undefined : String(wmo),
+      condition: wmo === undefined ? undefined : wmoCondition(wmo),
+    };
+    return [hour];
+  });
+  for (const code of unknownCodes)
+    odd.push(`unknown WMO code ${code} in the hourly forecast`);
+  // The hourly part is read once an hour; the sky's hours run from the hour it was read in.
+  const skyHours = hours
+    .filter((x) => Date.parse(x.at) + 3_600_000 > forecastAt)
+    .slice(0, SKY_HOURS)
+    .map((x) => ({
+      at: x.at,
+      cloudPct: x.cloudPct,
+      uvIndex: x.uvIndex,
+      radiationWm2: x.radiationWm2,
+    }));
+  const sky = now
+    ? {
+        ...meta(now.at),
+        cloudPct: cur("cloud_cover"),
+        uvIndex: cur("uv_index"),
+        radiationWm2: cur("shortwave_radiation"),
+        hours: skyHours,
+      }
+    : undefined;
+  const d = r.daily;
+  const day = (date: string): ForecastDay | undefined => {
+    const i = d?.time.indexOf(date) ?? -1;
+    if (!d || i < 0) return undefined;
+    const wmo = value(d.weather_code, i);
+    return {
+      date,
+      minC: value(d.temperature_2m_min, i),
+      maxC: value(d.temperature_2m_max, i),
+      rainChance: value(d.precipitation_probability_max, i),
+      rainMm: value(d.precipitation_sum, i),
+      text: wmo === undefined ? undefined : WMO[wmo],
+      code: wmo === undefined ? undefined : String(wmo),
+    };
+  };
+  const today = localDate(fetchedAt, offset);
+  const tomorrow = localDate(fetchedAt + 86_400_000, offset);
+  const forecastIso = new Date(forecastAt).toISOString();
+  const forecast = d
+    ? {
+        ...meta(forecastIso),
+        fetchedAt: forecastIso,
+        today: day(today),
+        tomorrow: day(tomorrow),
+      }
+    : undefined;
+  const hourly = hours.length
+    ? {
+        ...meta(forecastIso),
+        fetchedAt: forecastIso,
+        hours: hours.map(({ radiationWm2: _, ...x }) => x),
+      }
+    : undefined;
+  for (const [i, wmo] of (d?.weather_code ?? []).entries())
+    if (wmo !== null && !(wmo in WMO))
+      odd.push(`unknown WMO code ${wmo} on ${d?.time[i]}`);
+  if (code !== undefined && !(code in WMO))
+    odd.push(`unknown WMO code ${code} now`);
+  return {
+    now,
+    forecast,
+    hourly,
+    sky,
+    anomaly: odd.length ? odd.join("; ") : undefined,
+  };
+}
+
+export type OpenMeteoOptions = { fetch?: typeof fetch; base?: string };
+
+/**
+ * Open-Meteo as a weather source: modelled `now`, `forecast`, `hourly` (today and tomorrow) and `sky` (the only source with radiation). `current` is
+ * 15-minutely, so it is read every poll; the daily and hourly parts come from models that update hourly at best, so
+ * they are read hourly (one call with everything), and the polls between ask for `current` alone.
+ */
+export function openMeteo(options: OpenMeteoOptions = {}): WeatherSource {
+  const fetcher = options.fetch ?? fetch;
+  const base = options.base ?? "https://api.open-meteo.com/v1/forecast";
+  let last: Omit<SourceReading, "nextAt"> = {};
+  let full: { body: Record<string, unknown>; at: number } | undefined;
+  let fullDue = 0;
+  return {
+    name: "open-meteo",
+    owns: {
+      now: 30 * 60_000,
+      forecast: 6 * 3_600_000,
+      hourly: 6 * 3_600_000,
+      sky: 30 * 60_000,
+    }, // `current.time` starts its 15-minute interval
+    async read({
+      place,
+      at,
+      pollMinutes,
+      force,
+      signal,
+    }): Promise<SourceReading> {
+      const everything = force || !full || at >= fullDue;
+      const q = new URLSearchParams({
+        latitude: String(place.latitude),
+        longitude: String(place.longitude),
+        timezone: "auto",
+        current: CURRENT,
+      });
+      if (everything)
+        for (const [k, v] of Object.entries({
+          hourly: HOURLY,
+          daily: DAILY,
+          forecast_days: "2",
+        }))
+          q.set(k, v);
+      try {
+        const body = (await getJson(fetcher, `${base}?${q}`, {
+          init: { headers: { "user-agent": USER_AGENT } },
+          signal,
+        })) as Record<string, unknown>;
+        if (everything)
+          ((full = { body, at }), (fullDue = nextPoll(at, HOURLY_MINUTES)));
+        last = toSlices(
+          {
+            ...full!.body,
+            current: body.current,
+            utc_offset_seconds: body.utc_offset_seconds,
+          },
+          at,
+          full!.at,
+        );
+        return { ...last, nextAt: nextPoll(at, pollMinutes) };
+      } catch (error) {
+        return {
+          ...last,
+          anomaly: undefined,
+          problem: `open-meteo: ${(error as Error).message}`,
+          nextAt: nextPoll(at, pollMinutes),
+        };
+      }
+    },
+  };
+}