@khalido/home 0.0.0-stage → 0.1.0

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,
+    };
+}

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

@@ -0,0 +1,149 @@
+/** Sent on every request, so each service can see who is calling rather than a runtime's default string. */
+export declare const USER_AGENT = "home (+https://github.com/khalido/home.ts)";
+export type Place = {
+    latitude: number;
+    longitude: number;
+};
+/** The one polling number for observations and sky: every 15 minutes, KO's call. Forecasts follow their issue times. */
+export declare const DEFAULT_POLL_MINUTES = 15;
+/** The next read slot after `at`: every `pollMinutes` from 5 minutes past the hour when `pollMinutes` divides 60 (else from the epoch, plus 5 minutes). */
+export declare function nextPoll(at: number, pollMinutes?: number): number;
+/** What a source is asked to read: where, at what instant (epoch ms), the polling interval to schedule by, and `force` to read everything now. */
+export type ReadRequest = {
+    place: Place;
+    at: number;
+    pollMinutes: number;
+    force?: boolean;
+    signal?: AbortSignal;
+};
+/** Every slice says who made it, whether it is a model rather than an instrument, the time it is for, and when it was fetched. */
+export type SliceMeta = {
+    source: string;
+    modelled: boolean;
+    at: string;
+    fetchedAt: string;
+};
+/** Outside now. Speeds in km/h, direction where the wind comes from. */
+export type WeatherNow = SliceMeta & {
+    tempC?: number;
+    apparentC?: number;
+    humidity?: number;
+    windKmh?: number;
+    windDir?: string;
+    windDeg?: number;
+    gustKmh?: number;
+    rainMm?: number;
+    rainFrom?: string;
+    rainTo?: string;
+    station?: {
+        name: string;
+        distanceKm: number;
+    };
+};
+/** One forecast day. Any field can be missing: after BOM's afternoon issue, today has no min, max or rain range. */
+export type ForecastDay = {
+    date: string;
+    minC?: number;
+    maxC?: number;
+    rainChance?: number;
+    rainMm?: number;
+    rainRangeMm?: [number, number];
+    text?: string;
+    code?: string;
+};
+export type WeatherForecast = SliceMeta & {
+    issuedAt?: string;
+    today?: ForecastDay;
+    tomorrow?: ForecastDay;
+};
+/** Cloud, UV and sunlight on the ground. `radiationWm2` is shortwave (global horizontal) irradiance. */
+export type SkyHour = {
+    at: string;
+    cloudPct?: number;
+    uvIndex?: number;
+    radiationWm2?: number;
+};
+export type WeatherSky = SliceMeta & Omit<SkyHour, "at"> & {
+    hours: SkyHour[];
+};
+/** One stretch of the minute-by-minute rain forecast. `from` and `to` are UTC ISO; `type` is the source's own (`NONE`, `RAIN`, ...). */
+export type RainSegment = {
+    from: string;
+    to: string;
+    type?: string;
+    chance?: number;
+    mm?: number;
+    intensity?: string;
+};
+/** Rain minute by minute, up to `RAIN_HORIZON_MINUTES` ahead. `at` is when the forecast starts. Ask `rainSoon` what it means. */
+export type WeatherRain = SliceMeta & {
+    segments: RainSegment[];
+};
+/** How far ahead the rain forecast is kept and read: two hours, KO's call. */
+export declare const RAIN_HORIZON_MINUTES = 120;
+/** Weather in words, mildest first, so an hour from any source reads the same and a stretch of hours takes its worst. */
+export declare const CONDITIONS: readonly ["clear", "partly cloudy", "cloudy", "fog", "drizzle", "showers", "rain", "snow", "storm"];
+export type Condition = (typeof CONDITIONS)[number];
+/** One forecast hour, starting at `at`. `rainChance` in percent, `rainMm` over the hour, `code` the source's own, `condition` it in a word. */
+export type ForecastHour = {
+    at: string;
+    tempC?: number;
+    apparentC?: number;
+    rainChance?: number;
+    rainMm?: number;
+    windKmh?: number;
+    gustKmh?: number;
+    cloudPct?: number;
+    uvIndex?: number;
+    code?: string;
+    condition?: Condition;
+};
+/** The hourly forecast for today and tomorrow, from the home's midnight. `at` is when it was read. Ask `dayBlocks` for mornings and evenings. */
+export type WeatherHourly = SliceMeta & {
+    hours: ForecastHour[];
+};
+export type SliceName = "now" | "forecast" | "hourly" | "sky" | "rain";
+export type Slices = {
+    now?: WeatherNow;
+    forecast?: WeatherForecast;
+    hourly?: WeatherHourly;
+    sky?: WeatherSky;
+    rain?: WeatherRain;
+};
+/** One read of a source: the slices it has (last good ones included), when to call again, and anything to report. */
+export type SourceReading = Slices & {
+    nextAt: number;
+    problem?: string;
+    anomaly?: string;
+    stop?: string;
+};
+/**
+ * A weather provider. `owns` names the slices it can fill and how old each may get (by its `at`, beyond one polling
+ * interval) before the next source's is used. `read` fetches what is due and returns every slice it holds; it throws only on a bug.
+ */
+export type WeatherSource = {
+    name: string;
+    owns: Partial<Record<SliceName, number>>;
+    minPollMinutes?: number;
+    read(request: ReadRequest): Promise<SourceReading>;
+};
+/** The interval a source actually reads at: the shared `pollMinutes`, or its own floor if that is longer. */
+export declare const sourcePollMinutes: (source: WeatherSource, pollMinutes: number) => number;
+/** Hourly: how often forecast and hourly-sky reads happen where nothing documented changes faster. */
+export declare const HOURLY_MINUTES = 60;
+/**
+ * One owner for which source fills each slice, so the integration and `home status` show the same thing.
+ * `readings` are in preference order; a slice older than its source's `owns` age plus one polling interval falls through.
+ */
+export declare function mergeWeather(readings: {
+    source: WeatherSource;
+    reading?: SourceReading;
+}[], at: number, pollMinutes?: number): Slices;
+/** GET a URL as text (BOM's XML), with the timeout and user agent every source sends. A non-ok status throws `ConnectorError` with it. */
+export declare function getText(fetcher: typeof fetch, url: string, signal?: AbortSignal): Promise<string>;
+/** A number from a string the source sent, or undefined plus a note in `odd`. Never rounds or clamps. */
+export declare function num(value: unknown, what: string, odd: string[]): number | undefined;
+/** A source's timestamp as UTC ISO, or undefined when it does not parse: one odd time never sinks a whole read. */
+export declare const iso: (s: string | undefined) => string | undefined;
+/** The local calendar date (YYYY-MM-DD) of an instant at a UTC offset in seconds. */
+export declare const localDate: (at: number, offsetSeconds: number) => string;

package/dist/connectors/weather/source.js

@@ -0,0 +1,77 @@
+import { ConnectorError, fetchTimeout } from "../../connector.js";
+// The one place a weather provider plugs in: a `WeatherSource` returns slices, and `mergeWeather` picks one per slice.
+/** Sent on every request, so each service can see who is calling rather than a runtime's default string. */
+export const USER_AGENT = "home (+https://github.com/khalido/home.ts)";
+/** The one polling number for observations and sky: every 15 minutes, KO's call. Forecasts follow their issue times. */
+export const DEFAULT_POLL_MINUTES = 15;
+/** Reads land this far past each slot, so BOM's 10-minutely file (sent about 3 minutes past) is there: :05, :20, :35, :50. */
+const SLOT_OFFSET_MS = 5 * 60_000;
+/** The next read slot after `at`: every `pollMinutes` from 5 minutes past the hour when `pollMinutes` divides 60 (else from the epoch, plus 5 minutes). */
+export function nextPoll(at, pollMinutes = DEFAULT_POLL_MINUTES) {
+    const step = pollMinutes * 60_000;
+    return (Math.floor((at - SLOT_OFFSET_MS) / step) * step + step + SLOT_OFFSET_MS);
+}
+/** How far ahead the rain forecast is kept and read: two hours, KO's call. */
+export const RAIN_HORIZON_MINUTES = 120;
+/** Weather in words, mildest first, so an hour from any source reads the same and a stretch of hours takes its worst. */
+export const CONDITIONS = [
+    "clear",
+    "partly cloudy",
+    "cloudy",
+    "fog",
+    "drizzle",
+    "showers",
+    "rain",
+    "snow",
+    "storm",
+];
+/** The interval a source actually reads at: the shared `pollMinutes`, or its own floor if that is longer. */
+export const sourcePollMinutes = (source, pollMinutes) => Math.max(pollMinutes, source.minPollMinutes ?? 0);
+/** Hourly: how often forecast and hourly-sky reads happen where nothing documented changes faster. */
+export const HOURLY_MINUTES = 60;
+/**
+ * One owner for which source fills each slice, so the integration and `home status` show the same thing.
+ * `readings` are in preference order; a slice older than its source's `owns` age plus one polling interval falls through.
+ */
+export function mergeWeather(readings, at, pollMinutes = DEFAULT_POLL_MINUTES) {
+    const pick = (name) => {
+        for (const { source, reading } of readings) {
+            const slice = reading?.[name];
+            const maxAge = source.owns[name];
+            if (slice &&
+                maxAge !== undefined &&
+                at - Date.parse(slice.at) <=
+                    maxAge + sourcePollMinutes(source, pollMinutes) * 60_000)
+                return slice;
+        }
+        return undefined;
+    };
+    return {
+        now: pick("now"),
+        forecast: pick("forecast"),
+        hourly: pick("hourly"),
+        sky: pick("sky"),
+        rain: pick("rain"),
+    };
+}
+/** GET a URL as text (BOM's XML), with the timeout and user agent every source sends. A non-ok status throws `ConnectorError` with it. */
+export async function getText(fetcher, url, signal) {
+    const res = await fetchTimeout(fetcher, url, { headers: { "user-agent": USER_AGENT } }, { signal });
+    if (!res.ok)
+        throw new ConnectorError(`HTTP ${res.status} on GET ${new URL(url).pathname}`, { status: res.status });
+    return res.text();
+}
+/** A number from a string the source sent, or undefined plus a note in `odd`. Never rounds or clamps. */
+export function num(value, what, odd) {
+    if (value === undefined || value === null || value === "")
+        return undefined;
+    const n = typeof value === "number" ? value : Number(value);
+    if (Number.isFinite(n))
+        return n;
+    odd.push(`${what} is not a number: ${String(value)}`);
+    return undefined;
+}
+/** A source's timestamp as UTC ISO, or undefined when it does not parse: one odd time never sinks a whole read. */
+export const iso = (s) => s && !Number.isNaN(Date.parse(s)) ? new Date(s).toISOString() : undefined;
+/** The local calendar date (YYYY-MM-DD) of an instant at a UTC offset in seconds. */
+export const localDate = (at, offsetSeconds) => new Date(at + offsetSeconds * 1000).toISOString().slice(0, 10);

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

@@ -0,0 +1,48 @@
+/** The next of each event after `at`: today's while it is still ahead, else tomorrow's; missing when that day has none (polar). */
+export type SunNext = {
+    dawn?: string;
+    sunrise?: string;
+    sunset?: string;
+    dusk?: string;
+};
+/**
+ * The sun at a place and instant, computed locally (suncalc 2: degrees, azimuth clockwise from north). No network.
+ * Times are ISO instants for the local solar day containing `at` (the one whose solar noon is nearest); any can be
+ * missing at high latitudes when the sun never reaches that altitude.
+ *
+ * `sunNow(latitude, longitude, now)` is the owner. The weather snapshot holds one recomputed every 5 minutes, so its
+ * position, `rising`, `daylight` and `next` can be that old; a consumer that shows them calls `sunNow` with its own clock,
+ * as `home status` does.
+ */
+export type SunNow = {
+    at: string;
+    nightEnd?: string;
+    dawn?: string;
+    sunrise?: string;
+    goldenHourEnd?: string;
+    solarNoon: string;
+    goldenHour?: string;
+    sunset?: string;
+    dusk?: string;
+    night?: string;
+    azimuthDeg: number;
+    altitudeDeg: number;
+    rising: boolean;
+    daylight: boolean;
+    next: SunNext;
+    alwaysUp?: boolean;
+    alwaysDown?: boolean;
+};
+/** One owner for the sun's numbers. `at` is epoch ms. */
+export declare function sunNow(latitude: number, longitude: number, at: number): SunNow;
+/** How far a source's sunrise or sunset may be from the computed one before it is worth saying. */
+export declare const SUN_TOLERANCE_MS: number;
+/**
+ * A source's sunrise and sunset checked against the computed sun, which stays the owner: a note per event more than
+ * two minutes out, else undefined. Each is compared with the nearest computed event of the solar days either side of it,
+ * so near solar midnight at high latitude, where the solar day containing it can be the neighbouring one, it still pairs.
+ */
+export declare function sunDisagrees(source: string, latitude: number, longitude: number, reported: {
+    sunrise?: string;
+    sunset?: string;
+}): string | undefined;