@khalido/home 0.0.0-stage → 0.1.0

package/dist/connectors/weather/blocks.js

@@ -0,0 +1,106 @@
+import { localDay, localHour, localTime } from "../../clock.js";
+import { field } from "../../manifest.js";
+import { CONDITIONS, } from "./source.js";
+/** The parts of a day by default, by the local hour each starts in: KO's call. A consumer passes its own to `dayBlocks`. */
+export const BLOCKS = [
+    { name: "morning", from: 6, to: 12 },
+    { name: "afternoon", from: 12, to: 18 },
+    { name: "evening", from: 18, to: 22 },
+];
+const HOUR_MS = 3_600_000;
+function summarise(block, date, hours) {
+    const values = (k) => hours.map((h) => h[k]).filter((v) => v !== undefined);
+    const max = (k) => values(k).length ? Math.max(...values(k)) : undefined;
+    const temps = values("tempC");
+    const mm = values("rainMm");
+    const worst = hours
+        .map((h) => h.condition)
+        .filter((c) => c !== undefined)
+        .sort((a, b) => CONDITIONS.indexOf(b) - CONDITIONS.indexOf(a))[0];
+    return {
+        name: block.name,
+        date,
+        from: new Date(hours[0].t).toISOString(),
+        to: new Date(hours[hours.length - 1].t + HOUR_MS).toISOString(),
+        hours: hours.length,
+        late: hours[0].hour > block.from || undefined,
+        minC: temps.length ? Math.min(...temps) : undefined,
+        maxC: temps.length ? Math.max(...temps) : undefined,
+        rainChance: max("rainChance"),
+        rainMm: mm.length === hours.length
+            ? Number(mm.reduce((s, v) => s + v, 0).toFixed(2))
+            : undefined, // toFixed drops float noise only
+        windKmh: max("windKmh"),
+        gustKmh: max("gustKmh"),
+        uvIndex: max("uvIndex"),
+        condition: worst,
+    };
+}
+/**
+ * The rest of today and tomorrow in `blocks` (`BLOCKS` by default), from the hourly forecast, in the home's time zone (the
+ * runtime's when left out). The one owner: the integration, `home weather` and a consumer with its own clock all call
+ * `dayBlocks(state.hourly, now, timeZone)`. An hour counts while it has not ended; a part with no hours left is left out.
+ * Throws on a block outside 0–24 or ending before it starts.
+ */
+export function dayBlocks(hourly, at, timeZone, blocks = BLOCKS) {
+    checkBlocks(blocks);
+    if (!hourly)
+        return undefined;
+    const hours = hourly.hours
+        .map((h) => ({ ...h, t: Date.parse(h.at) }))
+        .filter((h) => h.t + HOUR_MS > at)
+        .map((h) => ({
+        ...h,
+        date: localDay(h.t, timeZone),
+        hour: localHour(h.t, timeZone),
+    }));
+    const cut = (date) => blocks.flatMap((b) => {
+        const inside = hours.filter((h) => h.date === date && h.hour >= b.from && h.hour < b.to);
+        return inside.length ? [summarise(b, date, inside)] : [];
+    });
+    const today = localDay(at, timeZone);
+    const [y, m, d] = today.split("-").map(Number);
+    const tomorrow = new Date(Date.UTC(y, m - 1, d + 1))
+        .toISOString()
+        .slice(0, 10); // by the calendar: a day is 23 or 25 hours twice a year
+    return { source: hourly.source, today: cut(today), tomorrow: cut(tomorrow) };
+}
+/** Throw on blocks a day cannot hold: whole hours within 0–24, each ending after it starts. */
+export function checkBlocks(blocks) {
+    for (const b of blocks)
+        if (!(Number.isInteger(b.from) &&
+            Number.isInteger(b.to) &&
+            b.from >= 0 &&
+            b.to <= 24 &&
+            b.from < b.to))
+            throw new RangeError(`day block ${b.name}: hours ${b.from}–${b.to}, want whole hours, 0 ≤ from < to ≤ 24`);
+}
+/** The UV index from which a block's text names it: 3, where sun protection starts to be advised (WHO's "moderate"). A display rule. */
+export const UV_SHOWN = 3;
+/**
+ * "afternoon from 16:00 17–19 °C, showers, rain 40% 1.2 mm, wind 25 km/h gusting 40, UV 8". `from` shows when the part is
+ * under way or short; UV shows from `UV_SHOWN`.
+ */
+export function blockText(b, timeZone) {
+    const name = b.late
+        ? `${b.name} from ${localTime(Date.parse(b.from), timeZone)}`
+        : b.name;
+    const temp = b.minC === undefined || b.maxC === undefined
+        ? ""
+        : b.minC === b.maxC
+            ? `${b.minC} °C`
+            : `${b.minC}–${b.maxC} °C`;
+    const rain = [
+        field(b.rainChance, (v) => `rain ${v}%`),
+        b.rainMm
+            ? `${b.rainChance === undefined ? "rain " : ""}${b.rainMm} mm`
+            : "",
+    ]
+        .filter(Boolean)
+        .join(" ");
+    const wind = field(b.windKmh, (v) => `wind ${v} km/h${b.gustKmh === undefined ? "" : ` gusting ${b.gustKmh}`}`);
+    const uv = b.uvIndex !== undefined && b.uvIndex >= UV_SHOWN ? `UV ${b.uvIndex}` : "";
+    return [`${name} ${temp}`.trim(), b.condition ?? "", rain, wind, uv]
+        .filter(Boolean)
+        .join(", ");
+}

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

@@ -0,0 +1,37 @@
+import { type Place, type WeatherForecast, type WeatherNow, type WeatherSource } from "./source.ts";
+export declare const FTP_BASE = "ftp://ftp.bom.gov.au/anon/gen/fwo";
+/** Great-circle distance in km. */
+export declare function distanceKm(a: Place, b: Place): number;
+/**
+ * The `now` slice from an observations product: the station given by WMO id, else the nearest one that reports air
+ * temperature. Rain since 9am keeps its own window, which ends a few minutes after the observation time.
+ */
+export declare function toNow(xml: string, place: Place, fetchedAt: number, wmoId?: string): {
+    now?: WeatherNow;
+    anomaly?: string;
+    problem?: string;
+};
+/**
+ * The `forecast` slice for one précis location (its name, e.g. "Sydney", or its `aac`, e.g. "NSW_PT131"). Today is the
+ * period containing `fetchedAt`; after the afternoon issue it has no min, max or rain range, and they stay missing.
+ */
+export declare function toForecast(xml: string, location: string, fetchedAt: number): {
+    forecast?: WeatherForecast;
+    nextIssue?: number;
+    anomaly?: string;
+    problem?: string;
+};
+export type BomOptions = {
+    /** A `fetch` that speaks ftp://, e.g. `ftpFetch()` from `@khalido/home/weather/ftp`. Without one the source stops at once. */
+    fetch?: typeof fetch;
+    /** The précis location by name or aac. Without one there is no BOM forecast and that slice falls to the next source. */
+    forecastLocation?: string;
+    /** A station's WMO id, to pin it instead of the nearest. */
+    station?: string;
+    /** Another state's product ids (README has the table checked on the server). Default NSW: IDN60920 and IDN11060. */
+    observations?: string;
+    forecasts?: string;
+    base?: string;
+};
+/** BOM as a weather source: observed `now` every polling interval, the forecaster's `forecast` at its issue times. */
+export declare function bom(options?: BomOptions): WeatherSource;

package/dist/connectors/weather/bom.js

@@ -0,0 +1,237 @@
+import { XMLParser } from "fast-xml-parser";
+import { getText, iso, nextPoll, num, } from "./source.js";
+// The Bureau of Meteorology's anonymous FTP products (https://www.bom.gov.au/catalogue/anon-ftp.shtml): a state's
+// observations (IDx60920, every station, 10-minutely) and its précis forecast (IDx11060). Free, not for commercial use,
+// BOM's default copyright terms. FTP is the channel BOM names for automated access; `fetch` must speak ftp:// (ftp.ts).
+export const FTP_BASE = "ftp://ftp.bom.gov.au/anon/gen/fwo";
+/** Stations whose latest observation is this much older than the file's newest are skipped (daily manual stations). */
+const STALE_STATION_MS = 60 * 60_000;
+/** After the forecast's own next routine issue time, wait this long for the file to land. */
+const ISSUE_GRACE_MS = 5 * 60_000;
+const HOUR = 3_600_000;
+const parser = new XMLParser({
+    ignoreAttributes: false,
+    attributeNamePrefix: "@",
+    parseTagValue: false, // numbers are read here, so "-" or "80%" is seen as written
+    parseAttributeValue: false,
+    isArray: (name) => [
+        "station",
+        "period",
+        "level",
+        "element",
+        "area",
+        "forecast-period",
+        "text",
+    ].includes(name),
+});
+const byType = (els, type) => els?.find((e) => e["@type"] === type);
+/** Great-circle distance in km. */
+export function distanceKm(a, b) {
+    const rad = Math.PI / 180;
+    const dLat = (b.latitude - a.latitude) * rad;
+    const dLon = (b.longitude - a.longitude) * rad;
+    const h = Math.sin(dLat / 2) ** 2 +
+        Math.cos(a.latitude * rad) *
+            Math.cos(b.latitude * rad) *
+            Math.sin(dLon / 2) ** 2;
+    return 2 * 6371 * Math.asin(Math.sqrt(h));
+}
+/**
+ * The `now` slice from an observations product: the station given by WMO id, else the nearest one that reports air
+ * temperature. Rain since 9am keeps its own window, which ends a few minutes after the observation time.
+ */
+export function toNow(xml, place, fetchedAt, wmoId) {
+    const stations = parser.parse(xml).product?.observations?.station ?? [];
+    const odd = [];
+    const surface = (s) => s.period?.[0]?.level?.[0]?.element;
+    const time = (s) => Date.parse(s.period?.[0]?.["@time-utc"] ?? "");
+    const newest = Math.max(...stations.map(time).filter((t) => !Number.isNaN(t)));
+    const located = stations.flatMap((s) => {
+        const latitude = Number(s["@lat"]);
+        const longitude = Number(s["@lon"]);
+        return Number.isFinite(latitude) && Number.isFinite(longitude)
+            ? [{ s, km: distanceKm(place, { latitude, longitude }) }]
+            : [];
+    });
+    const pick = wmoId
+        ? located.find(({ s }) => s["@wmo-id"] === wmoId) // a pinned station is shown however old; its `at` says so
+        : located
+            .filter(({ s }) => byType(surface(s), "air_temperature") &&
+            newest - time(s) <= STALE_STATION_MS)
+            .sort((a, b) => a.km - b.km)[0];
+    if (!pick)
+        return {
+            problem: wmoId
+                ? `no station ${wmoId} in this product`
+                : "no station with an air temperature in this product",
+        };
+    const { s, km } = pick;
+    const els = surface(s);
+    const at = iso(s.period?.[0]?.["@time-utc"]);
+    if (!at)
+        return { problem: `station ${s["@wmo-id"]} has no observation time` };
+    const n = (type) => num(byType(els, type)?.["#text"], type, odd);
+    const rain = byType(els, "rainfall");
+    const now = {
+        source: "bom",
+        modelled: false,
+        at,
+        fetchedAt: new Date(fetchedAt).toISOString(),
+        tempC: n("air_temperature"),
+        apparentC: n("apparent_temp"),
+        humidity: n("rel-humidity"),
+        windKmh: n("wind_spd_kmh"),
+        windDir: byType(els, "wind_dir")?.["#text"],
+        windDeg: n("wind_dir_deg"),
+        gustKmh: n("gust_kmh"),
+        rainMm: n("rainfall"),
+        rainFrom: iso(rain?.["@start-time-utc"]),
+        rainTo: iso(rain?.["@end-time-utc"]),
+        station: {
+            name: s["@description"] ?? s["@wmo-id"] ?? "unnamed",
+            distanceKm: km,
+        },
+    };
+    return { now, anomaly: odd.length ? odd.join("; ") : undefined };
+}
+/** "0 to 1 mm" → [0, 1]; anything else is reported, not guessed. */
+function range(text, odd) {
+    if (text === undefined)
+        return undefined;
+    const m = text.match(/^(\d+(?:\.\d+)?) to (\d+(?:\.\d+)?) mm$/);
+    if (!m)
+        odd.push(`rain range not understood: ${text}`);
+    return m ? [Number(m[1]), Number(m[2])] : undefined;
+}
+/**
+ * The `forecast` slice for one précis location (its name, e.g. "Sydney", or its `aac`, e.g. "NSW_PT131"). Today is the
+ * period containing `fetchedAt`; after the afternoon issue it has no min, max or rain range, and they stay missing.
+ */
+export function toForecast(xml, location, fetchedAt) {
+    const p = parser.parse(xml).product;
+    const nextIssue = Date.parse(p?.amoc?.["next-routine-issue-time-utc"] ?? "");
+    const want = location.toLowerCase();
+    const areas = (p?.forecast?.area ?? []).filter((a) => a["@type"] === "location");
+    const area = areas.find((a) => a["@aac"]?.toLowerCase() === want ||
+        a["@description"]?.toLowerCase() === want);
+    const result = { nextIssue: Number.isNaN(nextIssue) ? undefined : nextIssue };
+    if (!area)
+        return {
+            ...result,
+            problem: `no forecast location "${location}"; have ${areas
+                .slice(0, 8)
+                .map((a) => a["@description"])
+                .join(", ")}…`,
+        };
+    const odd = [];
+    const periods = area["forecast-period"] ?? [];
+    const i = periods.findIndex((f) => Date.parse(f["@start-time-utc"] ?? "") <= fetchedAt &&
+        fetchedAt < Date.parse(f["@end-time-utc"] ?? ""));
+    const day = (f) => {
+        if (!f)
+            return undefined;
+        const el = (type) => byType(f.element, type)?.["#text"];
+        const chance = byType(f.text, "probability_of_precipitation")?.["#text"];
+        const percent = chance?.match(/^(\d+)%$/)?.[1];
+        if (chance !== undefined && percent === undefined)
+            odd.push(`rain chance not understood: ${chance}`);
+        return {
+            date: (f["@start-time-local"] ?? "").slice(0, 10),
+            minC: num(el("air_temperature_minimum"), "minimum", odd),
+            maxC: num(el("air_temperature_maximum"), "maximum", odd),
+            rainChance: percent === undefined ? undefined : Number(percent),
+            rainRangeMm: range(el("precipitation_range"), odd),
+            text: byType(f.text, "precis")?.["#text"],
+            code: el("forecast_icon_code"),
+        };
+    };
+    const issuedAt = iso(p?.amoc?.["issue-time-utc"]);
+    const forecast = {
+        source: "bom",
+        modelled: false,
+        at: issuedAt ?? new Date(fetchedAt).toISOString(),
+        fetchedAt: new Date(fetchedAt).toISOString(),
+        issuedAt,
+        today: i < 0 ? undefined : day(periods[i]),
+        tomorrow: i < 0 ? undefined : day(periods[i + 1]),
+    };
+    if (i < 0)
+        odd.push(`no forecast period contains ${new Date(fetchedAt).toISOString()}`);
+    return {
+        ...result,
+        forecast,
+        anomaly: odd.length ? odd.join("; ") : undefined,
+    };
+}
+/** BOM as a weather source: observed `now` every polling interval, the forecaster's `forecast` at its issue times. */
+export function bom(options = {}) {
+    const fetcher = options.fetch ?? fetch;
+    const base = options.base ?? FTP_BASE;
+    const obsUrl = `${base}/${options.observations ?? "IDN60920"}.xml`;
+    const fcUrl = `${base}/${options.forecasts ?? "IDN11060"}.xml`;
+    let now;
+    let forecast;
+    let obsDue = 0;
+    let fcDue = 0;
+    const notes = {
+        obs: {},
+        fc: {},
+    };
+    return {
+        name: "bom",
+        owns: { now: 30 * 60_000, forecast: 24 * HOUR },
+        async read({ place, at, pollMinutes, force, signal }) {
+            // Plain fetch never reads ftp:// (Bun and Node fail differently), so this is terminal, like a rejected key.
+            if (!options.fetch && base.startsWith("ftp:"))
+                return {
+                    stop: "bom: plain fetch cannot read ftp://; pass fetch: ftpFetch() from @khalido/home/weather/ftp",
+                    nextAt: Infinity,
+                };
+            if (force || at >= obsDue) {
+                try {
+                    const r = toNow(await getText(fetcher, obsUrl, signal), place, at, options.station);
+                    now = r.now ?? now;
+                    notes.obs = {
+                        problem: r.problem && `bom observations: ${r.problem}`,
+                        anomaly: r.anomaly,
+                    };
+                }
+                catch (error) {
+                    notes.obs = {
+                        problem: `bom observations: ${error.message}`,
+                    };
+                }
+                obsDue = nextPoll(at, pollMinutes);
+            }
+            if (!options.forecastLocation)
+                notes.fc = { problem: "bom forecast: no forecastLocation set" };
+            else if (force || at >= fcDue) {
+                try {
+                    const r = toForecast(await getText(fetcher, fcUrl, signal), options.forecastLocation, at);
+                    forecast = r.forecast ?? forecast;
+                    notes.fc = {
+                        problem: r.problem && `bom forecast: ${r.problem}`,
+                        anomaly: r.anomaly,
+                    };
+                    // At the file's own next routine issue; hourly only when it names none. An amendment between issues waits (README).
+                    fcDue =
+                        r.nextIssue && r.nextIssue > at
+                            ? r.nextIssue + ISSUE_GRACE_MS
+                            : at + HOUR;
+                }
+                catch (error) {
+                    notes.fc = { problem: `bom forecast: ${error.message}` };
+                    fcDue = nextPoll(at, pollMinutes);
+                }
+            }
+            const join = (a, b) => [a, b].filter(Boolean).join("; ") || undefined;
+            return {
+                now,
+                forecast,
+                problem: join(notes.obs.problem, notes.fc.problem),
+                anomaly: join(notes.obs.anomaly, notes.fc.anomaly),
+                nextAt: options.forecastLocation ? Math.min(obsDue, fcDue) : obsDue,
+            };
+        },
+    };
+}

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

@@ -0,0 +1,5 @@
+/**
+ * A `fetch` that also reads anonymous `ftp://` URLs (BOM's products), passing every other URL to the global `fetch`.
+ * One connection per request; a missing file answers 404. Honours `init.signal`, so a caller's timeout applies.
+ */
+export declare function ftpFetch(timeoutMs?: number): typeof fetch;

package/dist/connectors/weather/ftp.js

@@ -0,0 +1,46 @@
+import { Client, FTPError } from "basic-ftp";
+import { Writable } from "node:stream";
+// The one file in the library that uses Node APIs (net and stream, through basic-ftp), so it sits outside the
+// runtime-neutral build (tsconfig.build.json) and has its own (tsconfig.node.json). Runs in Bun and Node.
+/**
+ * A `fetch` that also reads anonymous `ftp://` URLs (BOM's products), passing every other URL to the global `fetch`.
+ * One connection per request; a missing file answers 404. Honours `init.signal`, so a caller's timeout applies.
+ */
+export function ftpFetch(timeoutMs = 10_000) {
+    const f = async (input, init) => {
+        const url = new URL(input instanceof Request ? input.url : String(input));
+        if (url.protocol !== "ftp:")
+            return fetch(input, init);
+        const client = new Client(timeoutMs);
+        const abort = () => client.close();
+        init?.signal?.throwIfAborted();
+        init?.signal?.addEventListener("abort", abort, { once: true });
+        const chunks = [];
+        try {
+            await client.access({
+                host: url.hostname,
+                port: url.port ? Number(url.port) : 21,
+                user: url.username || "anonymous",
+                password: url.password || "anonymous@",
+            });
+            const sink = new Writable({
+                write: (chunk, _encoding, done) => (chunks.push(chunk), done()),
+            });
+            await client.downloadTo(sink, decodeURIComponent(url.pathname));
+            return new Response(new Uint8Array(Buffer.concat(chunks)), {
+                status: 200,
+            });
+        }
+        catch (error) {
+            init?.signal?.throwIfAborted();
+            if (error instanceof FTPError && error.code === 550)
+                return new Response(error.message, { status: 404 });
+            throw error;
+        }
+        finally {
+            init?.signal?.removeEventListener("abort", abort);
+            client.close();
+        }
+    };
+    return f;
+}

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

@@ -0,0 +1,31 @@
+import { type Place, type SourceReading, type WeatherRain, type WeatherSource } from "./source.ts";
+export declare const BASE = "https://weather.googleapis.com/v1";
+/**
+ * Map the three responses to slices. A day's rain chance is the higher of its day and night halves; its amount is their sum.
+ * With `place`, each day's `sunEvents` are checked against the computed sun (the owner); one more than 2 minutes out is an anomaly.
+ */
+export declare function toSlices(current: unknown, days: unknown, hours: unknown, fetchedAt: number, forecastAt?: number, place?: Place): Omit<SourceReading, "nextAt">;
+/**
+ * The minute forecast as a `rain` slice: the segments that start within `RAIN_HORIZON_MINUTES` of `fetchedAt`. A segment with an odd time is
+ * skipped and noted; a rain amount in a unit other than millimetres is left out and noted, never converted.
+ */
+export declare function toRain(minutes: unknown, fetchedAt: number): {
+    rain?: WeatherRain;
+    anomaly?: string;
+};
+export type GoogleOptions = {
+    key: string;
+    fetch?: typeof fetch;
+    base?: string;
+};
+/**
+ * The shortest interval Google is read at: the minute forecast moves in 15-minute segments. Billed per call, 10,000 free a month across the key:
+ * rain every 15 minutes, current conditions every 30 (`CURRENT_MINUTES`), the day and hour forecasts hourly: 192 calls a day, about 5,900 a month.
+ */
+export declare const MIN_POLL_MINUTES = 15;
+export declare const CURRENT_MINUTES = 30;
+/**
+ * Google Weather as a source: modelled `now`, `forecast` (10 days available, 2 read), `sky` without radiation, and `rain` from the
+ * minute forecast (Experimental at Google, so its failure is a `problem` on `rain` and never stops the other slices).
+ */
+export declare function google(options: GoogleOptions): WeatherSource;