@khalido/home 0.0.0-stage → 0.1.1

package/dist/connectors/weather/index.js

@@ -0,0 +1,280 @@
+import { localTime, realClock } from "../../clock.js";
+import { field } from "../../manifest.js";
+import { poller } from "../../poll.js";
+import { blockText, checkBlocks, dayBlocks, } from "./blocks.js";
+import { openMeteo } from "./open-meteo.js";
+import { rainSoon } from "./rain.js";
+import { DEFAULT_POLL_MINUTES, RAIN_HORIZON_MINUTES, sourcePollMinutes, mergeWeather, } from "./source.js";
+import { sunNow } from "./sun.js";
+export { mergeWeather, nextPoll, } from "./source.js";
+export { sunNow } from "./sun.js";
+export { rainSoon } from "./rain.js";
+export { BLOCKS, blockText, dayBlocks, } from "./blocks.js";
+export { bom } from "./bom.js";
+export { openMeteo } from "./open-meteo.js";
+export { google } from "./google.js";
+/** 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;
+const SLICE_NAMES = [
+    "now",
+    "forecast",
+    "hourly",
+    "sky",
+    "rain",
+];
+/** Outside weather as a home integration. Each source polls on its own cadence; the sun is computed, never fetched. */
+export function weather(config) {
+    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();
+    const fresh = new Map(); // whether a source's latest read brought anything new, rather than its last good slices again
+    let readAt; // 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; // 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 = sources.some((s) => fresh.get(s.name))
+                    ? "connected"
+                    : sources.every((s) => readings.get(s.name)?.stop)
+                        ? "unavailable"
+                        : "disconnected";
+                const notes = (k) => 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) => {
+                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, timeZone) => iso ? localTime(Date.parse(iso), timeZone) : "?";
+const day = (d, rainLeft) => 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, at) => {
+    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, r) {
+    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, sun) {
+    const n = w.now;
+    const hhmm = (iso) => 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) => state.blocks
+    ? ["today", "tomorrow"]
+        .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 = {
+    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/dist/connectors/weather/open-meteo.d.ts

@@ -0,0 +1,15 @@
+import { type Condition, type SourceReading, type WeatherSource } from "./source.ts";
+/** WMO codes in a word: 0–1 clear, 2 partly cloudy, 3 cloudy, then by family. */
+export declare function wmoCondition(code: number): Condition | 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 declare function toSlices(body: unknown, fetchedAt: number, forecastAt?: number): Omit<SourceReading, "nextAt">;
+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 declare function openMeteo(options?: OpenMeteoOptions): WeatherSource;

package/dist/connectors/weather/open-meteo.js

@@ -0,0 +1,285 @@
+import { z } from "zod";
+import { getJson } from "../../connector.js";
+import { HOURLY_MINUTES, iso, localDate, nextPoll, num, USER_AGENT, } from "./source.js";
+// 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 = {
+    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) {
+    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, offset) => {
+    const t = Date.parse(`${local}Z`);
+    return Number.isNaN(t)
+        ? undefined
+        : iso(new Date(t - offset * 1000).toISOString());
+};
+const value = (s, i) => 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, fetchedAt, forecastAt = fetchedAt) {
+    const r = OpenMeteoResponse.parse(body);
+    const offset = r.utc_offset_seconds ?? 0;
+    const odd = [];
+    const meta = (at) => ({
+        source: "open-meteo",
+        modelled: true,
+        at,
+        fetchedAt: new Date(fetchedAt).toISOString(),
+    });
+    const c = r.current;
+    const cur = (k) => 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();
+    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 = {
+            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) => {
+        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,
+    };
+}
+/**
+ * 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 = {}) {
+    const fetcher = options.fetch ?? fetch;
+    const base = options.base ?? "https://api.open-meteo.com/v1/forecast";
+    let last = {};
+    let full;
+    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, }) {
+            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,
+                }));
+                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.message}`,
+                    nextAt: nextPoll(at, pollMinutes),
+                };
+            }
+        },
+    };
+}

package/dist/connectors/weather/rain.d.ts

@@ -0,0 +1,19 @@
+import { type WeatherRain } from "./source.ts";
+/** What the rain forecast says about the next stretch. The one owner: every consumer calls `rainSoon`. */
+export type RainSoon = {
+    wet: boolean;
+    startsInMin?: number;
+    endsInMin?: number;
+    chance?: number;
+    mm?: number;
+    intensity?: string;
+    type?: string;
+    coveredMin: number;
+};
+/** Google's intensities, lightest first. An unknown one is noted by the source, never ranked. */
+export declare const RAIN_INTENSITIES: string[];
+/**
+ * Rain in the next `windowMin` minutes from `at` (epoch ms). A segment counts while its end is still ahead, so one that began a few minutes ago is used.
+ * A segment with no `type` is unknown, not dry: it adds nothing to `coveredMin`. Returns nothing when the forecast covers none of the window.
+ */
+export declare function rainSoon(rain: WeatherRain | undefined, at: number, windowMin?: number): RainSoon | undefined;

package/dist/connectors/weather/rain.js

@@ -0,0 +1,51 @@
+import { RAIN_HORIZON_MINUTES } from "./source.js";
+const WET = (type) => type !== undefined && type !== "NONE";
+/** Google's intensities, lightest first. An unknown one is noted by the source, never ranked. */
+export const RAIN_INTENSITIES = ["NO_INTENSITY", "LIGHT", "MODERATE", "HEAVY"];
+const minutes = (ms) => Math.round(ms / 60_000);
+/**
+ * Rain in the next `windowMin` minutes from `at` (epoch ms). A segment counts while its end is still ahead, so one that began a few minutes ago is used.
+ * A segment with no `type` is unknown, not dry: it adds nothing to `coveredMin`. Returns nothing when the forecast covers none of the window.
+ */
+export function rainSoon(rain, at, windowMin = RAIN_HORIZON_MINUTES) {
+    if (!rain)
+        return undefined;
+    const end = at + windowMin * 60_000;
+    const segs = rain.segments
+        .map((s) => ({ ...s, f: Date.parse(s.from), t: Date.parse(s.to) }))
+        .filter((s) => s.t > at && s.f < end && s.type !== undefined)
+        .sort((a, b) => a.f - b.f);
+    const covered = segs.reduce((sum, s) => sum + Math.min(s.t, end) - Math.max(s.f, at), 0);
+    if (covered <= 0)
+        return undefined;
+    const coveredMin = minutes(covered);
+    const first = segs.findIndex((s) => WET(s.type));
+    if (first < 0)
+        return { wet: false, coveredMin };
+    let last = first;
+    while (last + 1 < segs.length &&
+        WET(segs[last + 1].type) &&
+        segs[last + 1].f <= segs[last].t)
+        last++;
+    const run = segs.slice(first, last + 1);
+    const chances = run.map((s) => s.chance).filter((c) => c !== undefined);
+    const mms = run.map((s) => s.mm);
+    const heaviest = run
+        .map((s) => s.intensity)
+        .filter((i) => i !== undefined)
+        .sort((a, b) => RAIN_INTENSITIES.indexOf(b) - RAIN_INTENSITIES.indexOf(a))[0];
+    const runEnd = run[run.length - 1].t;
+    const after = segs[last + 1]; // a known dry segment right after the run proves it ended
+    return {
+        wet: true,
+        startsInMin: Math.max(0, minutes(run[0].f - at)),
+        endsInMin: after && after.f <= runEnd ? minutes(runEnd - at) : undefined,
+        chance: chances.length ? Math.max(...chances) : undefined,
+        mm: mms.every((m) => m !== undefined)
+            ? mms.reduce((sum, m) => sum + m, 0)
+            : undefined,
+        intensity: heaviest,
+        type: run[0].type,
+        coveredMin,
+    };
+}