@khalido/home 0.0.0-stage → 0.1.1

package/src/connectors/weather/README.md

@@ -0,0 +1,84 @@
+# Weather
+
+Outside weather for the home: what it is now, today and tomorrow by the hour and by morning, afternoon and evening, how much sun is reaching the roof, and where the sun is. `iot_class`: **cloud_polling**. The probe that chose these sources is [`docs/weather-probe.md`](../../../docs/weather-probe.md).
+
+```ts
+import { weather, bom, openMeteo } from "@khalido/home/weather";
+import { ftpFetch } from "@khalido/home/weather/ftp";
+
+weather({
+  latitude,
+  longitude,
+  sources: [
+    bom({ fetch: ftpFetch(), forecastLocation: "Sydney" }),
+    openMeteo(),
+  ],
+});
+```
+
+## Slices
+
+Each slice carries `source`, `modelled` (a model, not an instrument), `at` (the time it is for) and `fetchedAt`. Observed and modelled data are never shown as each other.
+
+| Slice      | What                                                                                                                                                                                                                                                         | Owner with BOM first                                                 | Fallback                                     |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | -------------------------------------------- |
+| `now`      | temperature, feels-like, humidity, wind and gust, rain since 9am with its own window, station and distance                                                                                                                                                   | BOM (observed)                                                       | Open-Meteo `current` (modelled, 15-minutely) |
+| `forecast` | today and tomorrow: min, max, rain chance, rain range (BOM) or amount (models), text, the source's icon code                                                                                                                                                 | BOM précis                                                           | Open-Meteo daily (modelled)                  |
+| `hourly`   | today and tomorrow hour by hour from the home's midnight: temperature, feels-like, rain chance and amount, wind and gust, cloud, UV, the source's code and a `condition` word. `dayBlocks(hourly, at, timeZone)` cuts it into morning, afternoon and evening | Open-Meteo (the only source read hourly)                             | none                                         |
+| `sky`      | cloud %, UV index, shortwave radiation W/m², now and the next 6 hours                                                                                                                                                                                        | Open-Meteo (the only source with radiation)                          | Google (no radiation)                        |
+| `rain`     | minute by minute for the next 2 hours, in 15-minute segments: type, chance, amount, weight. `rainSoon(rain, at)` turns it into when rain starts and ends                                                                                                     | Google's minute forecast (the only source)                           | none                                         |
+| `sun`      | dawn, sunrise, golden hour, solar noon, sunset, dusk, astronomical night, azimuth, altitude, rising, daylight, and the next dawn, sunrise, sunset and dusk                                                                                                   | computed: `sunNow(latitude, longitude, at)` with suncalc, no network | none needed                                  |
+
+**Day blocks.** `dayBlocks(state.hourly, now, timeZone, blocks?)` is the owner: by default morning 6–12, afternoon 12–18, evening 18–22 (`BLOCKS`, KO's call) by the local hour each hour starts in, for the rest of today and all of tomorrow. A consumer passes its own parts of the day (`[{ name: "Noon", from: 11, to: 15 }, …]`, each within 0–24), to `dayBlocks` or as `weather({ blocks })`. An hour counts while it has not ended, so at 16:50 today has "afternoon from 16:00" (2 hours) and the evening. Each block holds `hours` (how many it summarises), min and max temperature, the highest rain chance, the rain summed (missing if any hour lacks it, never zero), the highest wind, gust and UV index, `late` when it starts after its part of the day does, and the worst hour's `condition`. `condition` is one word from `CONDITIONS`, mildest first: clear, partly cloudy, cloudy, fog, drizzle, showers, rain, snow, storm; Open-Meteo maps WMO codes to it by family (`wmoCondition`). The snapshot's `blocks` is recomputed at every report and every 5 minutes; `blockText` gives the words `home weather` prints; it names UV from 3 (`UV_SHOWN`, where WHO starts advising sun protection).
+
+**The home's time zone.** `weather({ timeZone })`, from the config's `location.timezone` or `HOME_TIMEZONE`, sets where today and tomorrow start for the blocks and the zone every time in the text is shown in. Unset, it is the machine's: on a Pi left on UTC that cuts Sydney's afternoon at UTC's midday, and `home weather` reads "05:50" for 16:50. Checked live on 2026-10-16 (Bun 1.4.3) with `TZ=UTC`.
+
+`sources` is the preference order. The default is `[openMeteo()]`, which works anywhere with no key. **In Australia put BOM first; it needs the FTP transport, so it is opt-in**, as in the example above and in `home status`. Put Google last when it is used at all: it needs a key, its calls count against a monthly quota and it has no radiation, so it is the last resort for every slice, not a preference. `mergeWeather` (one owner, used by the integration and `home status`) gives each slice to the first source holding one whose `at` is younger than one polling interval plus what that source allows (`owns`): `now` and `sky` 30 min for every source, BOM `forecast` 24 h, the models' `forecast` 6 h. An older one falls through to the next source. A fourth provider is a `WeatherSource` (`source.ts`): a `name`, `owns`, and `read({ place, at, pollMinutes, force, signal })` returning its slices and `nextAt`. `force` (from `refresh()`) means read everything now, forecasts included, whatever the schedule. The integration is `connected` while some source's latest read brought a slice fetched in that read; a read that returns only its last good slices is a failed read, so the part is `disconnected` and keeps the data.
+
+**One cadence.** `weather({ pollMinutes })`, default **15**, is how often every source reads observations and sky, at :05, :20, :35 and :50 (`nextPoll`), so BOM's 10-minutely file, sent about 3 minutes past, has landed. Forecasts follow their own issue times (BOM) or are read hourly (the models). A source billed per call sets a floor, `minPollMinutes`, and reads at whichever is longer: Google's is 15, the length of a rain segment, and inside that read it takes current conditions only every 30 minutes. Nothing reads faster than this, `refresh()` included: it forces only sources without a floor, and skips a billed source whose last read is younger than its floor.
+
+**Two outside temperatures.** The Daikin outdoor unit's sensor (`outsideC`) and the BOM station are different instruments in different places. `home status` shows both, the first as "outdoor unit", the second under the station's name; nothing here prefers one.
+
+## Sources
+
+**BOM, anonymous FTP** (`bom.ts`, `ftp.ts`). The channel BOM's own block page names for automated access. Two state products, read with `fast-xml-parser`, every element by its `type`, numbers parsed here so "-" or "80%" shows up in `anomaly` instead of becoming NaN:
+
+- **Observations `IDx60920`** (NSW 560 KB): every station in the state. `now` is the nearest station reporting air temperature whose last observation is within an hour of the file's newest (some stations are daily manual reports, days old), unless `station` pins a WMO id. Distance is great-circle from the station's 4-decimal coordinates. Most stations report every 10 minutes and the file lands about 3 minutes later; at the 15-minute default this is 96 reads, about **54 MB of FTP a day** for the NSW file.
+- **Précis forecast `IDx11060` and siblings** (NSW 736 KB): needs `forecastLocation` (a name like "Sydney" or an aac like `NSW_PT131`), because the locations carry no coordinates and a guessed town would be worse than asking. Without one, `forecast` falls through. Today is the period containing now; after the afternoon issue it has no min, max or rain range, and they stay missing. Read again at the file's own `next-routine-issue-time-utc` plus 5 minutes (hourly if it names none), so an amendment between routine issues waits for the next one.
+
+| State                 | `observations` | `forecasts` |
+| --------------------- | -------------- | ----------- |
+| NSW and ACT (default) | IDN60920       | IDN11060    |
+| Victoria              | IDV60920       | IDV10753    |
+| Queensland            | IDQ60920       | IDQ11295    |
+| South Australia       | IDS60920       | IDS10044    |
+| Western Australia     | IDW60920       | IDW14199    |
+| Tasmania              | IDT60920       | IDT16710    |
+| Northern Territory    | IDD60920       | IDD10207    |
+
+Each id was checked on the server on 2026-10-13 (the file exists; for the forecasts, its `amoc` names the state and service `WSP`/`FPR`). `IDN10064` is a 19 KB Sydney-metro-only forecast in the same shape, if that covers the home.
+
+Plain `fetch` cannot read `ftp://` (Bun 1.4.2: "protocol must be http:, https: or s3:"), so `bom()` takes a `fetch` that can: `ftpFetch()` from `@khalido/home/weather/ftp`, `basic-ftp` over Node's `net`, which runs in Bun and Node. It is the one library file using Node APIs, so it is outside the runtime-neutral build (`tsconfig.build.json`) and type-checked by `tsconfig.node.json`. `bom()` without an FTP `fetch` stops at once, like a rejected key: "pass fetch: ftpFetch()" goes in `detail`, nothing is fetched or retried, and its slices fall through. Measured, Bun 1.4.2: `IDN60920` 0.8 s, `IDN10064` 0.3 s, both products together 1.8–2.0 s.
+
+**Open-Meteo** (`open-meteo.ts`, [docs](https://open-meteo.com/en/docs)). One keyless JSON call per poll: `current` is 15-minutely model data (`interval: 900`), so it is read every poll, and the daily and hourly parts, from models that update hourly at best (6-hourly for IFS), are added to one call an hour. That call reads 48 hours from today's local midnight (`forecast_days=2`) for `hourly`; `sky.hours` is the 6 from the hour it was read. Open-Meteo gives local times and one `utc_offset_seconds`, and applies that offset to every time, across a daylight-saving change too (it returned 02:00 on the night Sydney skipped it; live, 2026-10-16), so `wall − offset` is right for all of them. `dayBlocks` labels each UTC hour in the real zone. 96 calls a day at the default, against 10,000 free. No `models` parameter: [Open-Meteo's BOM page](https://open-meteo.com/en/docs/bom-api) says BOM's open-data delivery is still suspended, and its `bom_access_global` answers only nulls. Radiation is the mean over the preceding interval. `precipitation` is the last 15 minutes, so `now.rainMm` stays empty rather than pretending to be since 9am. 1.3 s a call from Sydney, nearly all of it the TLS handshake with a server in Germany. Plain `fetch` of the JSON API, not the `openmeteo` SDK: the SDK forces FlatBuffers, reads variables by position, calls the global `fetch` (no injection for tests) and adds about 700 KB.
+
+**Google Weather** (`google.ts`, [docs](https://developers.google.com/maps/documentation/weather)). Built from the docs' example responses (`test/fixtures/weather/google-*.json`, the complete objects only; the docs elide the rest) and checked live against Sydney on 2026-10-13: `now`, `forecast` and `sky` in 1.19 s. `google({ key })` reads `forecast/minutes:lookup` every 15 minutes (its floor), `currentConditions:lookup` every 30 and `forecast/days:lookup?days=2` and `forecast/hours:lookup?hours=6` hourly, since Google documents nothing that changes faster. That is 192 calls a day, about 5,800–5,950 a month. Google bills each call as one Weather Usage event: 10,000 free a month, then $0.15 per 1,000 ([pricing](https://developers.google.com/maps/billing-and-pricing/pricing)). Any other use of the same key shares that quota. Whether the minute forecast bills as the same event is unverified: its docs page shows no price. Every slice is `modelled: true`: the docs never say it is observed. A day's rain chance is the higher of its day and night halves, its amount their sum; `currentConditionsHistory.qpf` is a rolling 24 hours, so it is not used as rain since 9am. A 400, 401 or 403 stops the source (`stop`), with no retry loop. The key goes in the query string and never into a message.
+
+**Google minute forecast** (`toRain` in `google.ts`, [docs](https://developers.google.com/maps/documentation/weather/minute-forecast)). `GET /v1/forecast/minutes:lookup` for a point returns `overallPredictionTimeframe` and 24 `segments` (6 hours) of 15 minutes, each with `type` (`NONE`, `RAIN`, `SNOW`, `HAIL`), `probability` 0–100, `qpf` in mm and `intensity`. Probed for Sydney CBD on 2026-10-15 (curl): HTTP 200 in 1.0 s, every segment dry; the first segment began 12 minutes before the forecast's start. Google calls it Experimental, so its failure is a `problem` on `rain` and never stops the other slices. The docs do not list its coverage by country, say nothing of how it is made, and allow keeping minute values for one hour at most: `rain` owns 15 minutes of age on top of one poll, so a stale slice is dropped, not served (with a `pollMinutes` above 45 the slice outlives that hour: keep it at 15), and the test fixture is invented values in the real shape. We keep the segments that start within 2 hours (`RAIN_HORIZON_MINUTES`). **`rainSoon(rain, at, windowMin = 120)` is the owner**: when the first wet stretch starts and ends, its chance, amount and weight, and `coveredMin`, how much of the window the forecast covers. A segment with no `type` is unknown, not dry. Next: if the minute forecast fails, fall back to the hourly rain chance (`forecast/hours:lookup` already carries `precipitation`; not read yet).
+
+**Sun** (`sun.ts`). `sunNow` with [suncalc](https://github.com/mourner/suncalc) 2.1.1, which bundles its own types (degrees, azimuth clockwise from north; `@types/suncalc` describes v1 and is wrong for it). Times are for the local solar day containing `at`. On 2026-10-13 it matched BOM's own Sydney sunrise and sunset to the second. Dawn and dusk are civil (6° below the horizon), `nightEnd` and `night` astronomical (18°), `goldenHour` starts the evening's and `goldenHourEnd` ends the morning's (6° above). `rising` is before solar noon, which in suncalc's solar day means from solar midnight; `daylight` is altitude above 0°. **`sunNow(latitude, longitude, now)` is the owner**: the snapshot's `sun` is recomputed every 5 minutes, so a consumer showing `rising`, `daylight`, `next` or the position calls `sunNow` with its own clock, as `home status` does. `next` holds each of dawn, sunrise, sunset and dusk at its next occurrence after `at` (today's while still ahead, else tomorrow's), missing on a day that has none. The computed sun is the owner: Google's daily `sunEvents` are parsed only to check it, and a sunrise or sunset more than 2 minutes from the computed one (`sunDisagrees`, comparing within the solar day containing Google's time) goes into Google's `anomaly`, never into the sun.
+
+Every request has a 10 s timeout and the user agent `home (+https://github.com/khalido/home.ts)`: BOM's app API gives Bun's default `Bun/1.4.2` no answer at all, so nothing here relies on the default.
+
+## Not built, on purpose
+
+- **BOM's app API** (`api.weather.bom.gov.au/v1/locations/<geohash>/…`, used by [bremor/bureau_of_meteorology](https://github.com/bremor/bureau_of_meteorology)). Fast and convenient, but every response says: "This application programming interface (API) is owned by the Bureau of Meteorology. You must not use, copy or share it."
+- **`reg.bom.gov.au/fwo/…`** over HTTPS. It answers anyone today, but it is BOM's Registered User host, a paid service ([charges](https://reg.bom.gov.au/other/charges.shtml)).
+- **`www.bom.gov.au/fwo/…`** with a browser user agent. The 403 it gives other clients says automated access "should stop".
+
+## Licences
+
+- **BOM products**: not CC BY. The [data feeds catalogue](https://www.bom.gov.au/catalogue/data-feeds.shtml) says they "are free to access and are not for commercial use"; the [copyright notice](https://www.bom.gov.au/other/copyright.shtml)'s default terms allow personal use and say "You must not supply it to any other person". A home reading them is fine; the BOM fixtures here are invented values in the real shape for that reason.
+- **Open-Meteo**: data [CC BY 4.0](https://open-meteo.com/en/licence) (link to Open-Meteo wherever its data is shown); the free API is non-commercial, under 10,000 calls a day, 5,000 an hour, 600 a minute ([terms](https://open-meteo.com/en/terms)).
+- **Google Weather**: Maps Platform terms, billed per call (see Google Weather above).
+- **Libraries**: suncalc (BSD-2-Clause), basic-ftp (MIT), fast-xml-parser (MIT).

package/src/connectors/weather/blocks.ts

@@ -0,0 +1,173 @@
+import { localDay, localHour, localTime } from "../../clock.ts";
+import { field } from "../../manifest.ts";
+import {
+  CONDITIONS,
+  type Condition,
+  type ForecastHour,
+  type WeatherHourly,
+} from "./source.ts";
+
+/** One part of a day: its name and the local hours it covers, `from` up to `to` (0–24, within one day). */
+export type BlockDef = { name: string; from: number; to: number };
+
+/** 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: readonly BlockDef[] = [
+  { name: "morning", from: 6, to: 12 },
+  { name: "afternoon", from: 12, to: 18 },
+  { name: "evening", from: 18, to: 22 },
+];
+
+/**
+ * One part of a day from the hourly forecast: `hours` is how many hours it summarises, fewer than its length when it is under way or
+ * the source left hours out. `rainChance` is the highest hour's, `rainMm` the sum (missing if any hour lacks one), `condition` the worst hour's.
+ * `late`: it starts after its part of the day does (under way, or the source began later).
+ */
+export type DayBlock = {
+  name: string;
+  date: string; // local YYYY-MM-DD
+  from: string; // UTC ISO, the first hour counted
+  to: string; // UTC ISO, the end of the last
+  hours: number;
+  late?: boolean;
+  minC?: number;
+  maxC?: number;
+  rainChance?: number;
+  rainMm?: number;
+  windKmh?: number; // the highest hour's
+  gustKmh?: number;
+  uvIndex?: number; // the highest hour's
+  condition?: Condition;
+};
+export type DayBlocks = {
+  source: string;
+  today: DayBlock[];
+  tomorrow: DayBlock[];
+};
+
+const HOUR_MS = 3_600_000;
+
+function summarise(
+  block: BlockDef,
+  date: string,
+  hours: (ForecastHour & { t: number; hour: number })[],
+): DayBlock {
+  const values = (
+    k: "tempC" | "rainChance" | "windKmh" | "gustKmh" | "rainMm" | "uvIndex",
+  ) => hours.map((h) => h[k]).filter((v) => v !== undefined);
+  const max = (k: Parameters<typeof values>[0]) =>
+    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: WeatherHourly | undefined,
+  at: number,
+  timeZone?: string,
+  blocks: readonly BlockDef[] = BLOCKS,
+): DayBlocks | undefined {
+  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: string) =>
+    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: readonly BlockDef[]): void {
+  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: DayBlock, timeZone?: string): string {
+  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/src/connectors/weather/bom.ts

@@ -0,0 +1,344 @@
+import { XMLParser } from "fast-xml-parser";
+import {
+  type ForecastDay,
+  getText,
+  iso,
+  nextPoll,
+  num,
+  type Place,
+  type WeatherForecast,
+  type WeatherNow,
+  type WeatherSource,
+} from "./source.ts";
+
+// 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),
+});
+
+type El = { "#text"?: string; [attr: `@${string}`]: string | undefined };
+type Period = { "@time-utc"?: string; level?: { element?: El[] }[] };
+type Station = {
+  "@wmo-id"?: string;
+  "@description"?: string;
+  "@lat"?: string;
+  "@lon"?: string;
+  period?: Period[];
+};
+type FPeriod = {
+  "@start-time-local"?: string;
+  "@start-time-utc"?: string;
+  "@end-time-utc"?: string;
+  element?: El[];
+  text?: El[];
+};
+type Area = {
+  "@aac"?: string;
+  "@description"?: string;
+  "@type"?: string;
+  "forecast-period"?: FPeriod[];
+};
+type Product = {
+  product?: {
+    amoc?: {
+      "issue-time-utc"?: string;
+      "next-routine-issue-time-utc"?: string;
+    };
+    observations?: { station?: Station[] };
+    forecast?: { area?: Area[] };
+  };
+};
+
+const byType = (els: El[] | undefined, type: string) =>
+  els?.find((e) => e["@type"] === type);
+
+/** Great-circle distance in km. */
+export function distanceKm(a: Place, b: Place): number {
+  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: string,
+  place: Place,
+  fetchedAt: number,
+  wmoId?: string,
+): { now?: WeatherNow; anomaly?: string; problem?: string } {
+  const stations =
+    (parser.parse(xml) as Product).product?.observations?.station ?? [];
+  const odd: string[] = [];
+  const surface = (s: Station) => s.period?.[0]?.level?.[0]?.element;
+  const time = (s: Station) => 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: string) => num(byType(els, type)?.["#text"], type, odd);
+  const rain = byType(els, "rainfall");
+  const now: WeatherNow = {
+    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: string | undefined,
+  odd: string[],
+): [number, number] | undefined {
+  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: string,
+  location: string,
+  fetchedAt: number,
+): {
+  forecast?: WeatherForecast;
+  nextIssue?: number;
+  anomaly?: string;
+  problem?: string;
+} {
+  const p = (parser.parse(xml) as Product).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: string[] = [];
+  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: FPeriod | undefined): ForecastDay | undefined => {
+    if (!f) return undefined;
+    const el = (type: string) => 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: WeatherForecast = {
+    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,
+  };
+}
+
+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 function bom(options: BomOptions = {}): WeatherSource {
+  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: WeatherNow | undefined;
+  let forecast: WeatherForecast | undefined;
+  let obsDue = 0;
+  let fcDue = 0;
+  const notes = {
+    obs: {} as { problem?: string; anomaly?: string },
+    fc: {} as { problem?: string; anomaly?: string },
+  };
+  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 as 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 as Error).message}` };
+          fcDue = nextPoll(at, pollMinutes);
+        }
+      }
+      const join = (a?: string, b?: string) =>
+        [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/src/connectors/weather/ftp.ts

@@ -0,0 +1,48 @@
+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): typeof fetch {
+  const f = async (
+    input: RequestInfo | URL,
+    init?: RequestInit,
+  ): Promise<Response> => {
+    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: Buffer[] = [];
+    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: Buffer, _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 as typeof fetch;
+}