@khalido/home 0.0.0-stage → 0.1.0

package/src/connectors/weather/rain.ts

@@ -0,0 +1,73 @@
+import { RAIN_HORIZON_MINUTES, 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; // rain somewhere in the covered part of the window
+  startsInMin?: number; // 0 when it is raining now
+  endsInMin?: number; // when the first wet stretch ends; missing when it runs past the window or the forecast stops while it is still wet
+  chance?: number; // percent, the highest in that stretch
+  mm?: number; // total over that stretch; missing if any segment lacks an amount
+  intensity?: string; // the heaviest in that stretch
+  type?: string; // the source's own, of the first wet segment
+  coveredMin: number; // how much of the window the forecast actually covers
+};
+
+const WET = (type?: string) => 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: number) => 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: WeatherRain | undefined,
+  at: number,
+  windowMin = RAIN_HORIZON_MINUTES,
+): RainSoon | undefined {
+  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/src/connectors/weather/source.ts

@@ -0,0 +1,236 @@
+import { ConnectorError, fetchTimeout } from "../../connector.ts";
+
+// 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)";
+
+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 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: number,
+  pollMinutes = DEFAULT_POLL_MINUTES,
+): number {
+  const step = pollMinutes * 60_000;
+  return (
+    Math.floor((at - SLOT_OFFSET_MS) / step) * step + step + SLOT_OFFSET_MS
+  );
+}
+
+/** 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; // percent
+  windKmh?: number;
+  windDir?: string; // compass point as the source gives it, e.g. "ESE"
+  windDeg?: number;
+  gustKmh?: number;
+  rainMm?: number; // rain since 9am, over rainFrom..rainTo, which can differ from `at`
+  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; // local YYYY-MM-DD
+  minC?: number;
+  maxC?: number;
+  rainChance?: number; // percent
+  rainMm?: number; // a model's single amount
+  rainRangeMm?: [number, number]; // a forecaster's range, e.g. "0 to 1 mm"
+  text?: string;
+  code?: string; // the source's own icon or condition code (BOM 1–19, WMO for Open-Meteo, a type name for Google)
+};
+
+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 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",
+] as const;
+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; // epoch ms; the integration never calls sooner
+  problem?: string; // a failed product, a missing option; the source keeps going
+  anomaly?: string; // a value the source sent that could not be read as given
+  stop?: string; // a terminal problem (a rejected key): the integration stops calling this source
+};
+
+/**
+ * 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>>; // slice → ms of age allowed on top of one polling interval
+  minPollMinutes?: number; // a floor under the shared interval, for a source billed per call
+  read(request: ReadRequest): Promise<SourceReading>;
+};
+
+/** The interval a source actually reads at: the shared `pollMinutes`, or its own floor if that is longer. */
+export const sourcePollMinutes = (source: WeatherSource, pollMinutes: number) =>
+  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: { source: WeatherSource; reading?: SourceReading }[],
+  at: number,
+  pollMinutes = DEFAULT_POLL_MINUTES,
+): Slices {
+  const pick = <K extends SliceName>(name: K): Slices[K] => {
+    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: typeof fetch,
+  url: string,
+  signal?: AbortSignal,
+): Promise<string> {
+  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: unknown,
+  what: string,
+  odd: string[],
+): number | undefined {
+  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: string | undefined) =>
+  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: number, offsetSeconds: number) =>
+  new Date(at + offsetSeconds * 1000).toISOString().slice(0, 10);

package/src/connectors/weather/sun.ts

@@ -0,0 +1,114 @@
+import { getPosition, getTimes } from "suncalc";
+
+const DAY_MS = 86_400_000;
+
+/** 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; // astronomical dawn, sun 18° below the horizon
+  dawn?: string; // civil dawn, 6° below
+  sunrise?: string; // missing on a polar day or night
+  goldenHourEnd?: string; // morning golden hour ends, 6° above
+  solarNoon: string;
+  goldenHour?: string; // evening golden hour starts, 6° above
+  sunset?: string;
+  dusk?: string; // civil dusk, 6° below
+  night?: string; // astronomical dusk, 18° below
+  azimuthDeg: number; // 0 north, 90 east
+  altitudeDeg: number; // refraction-corrected; negative below the horizon
+  rising: boolean; // before solar noon: the sun is climbing (from solar midnight)
+  daylight: boolean; // altitude above 0°
+  next: SunNext;
+  alwaysUp?: boolean;
+  alwaysDown?: boolean;
+};
+
+const isoOf = (d: Date | null) => d?.toISOString();
+
+/** One owner for the sun's numbers. `at` is epoch ms. */
+export function sunNow(
+  latitude: number,
+  longitude: number,
+  at: number,
+): SunNow {
+  const date = new Date(at);
+  const times = getTimes(date, latitude, longitude);
+  const tomorrow = getTimes(new Date(at + DAY_MS), latitude, longitude);
+  const { azimuth, altitude } = getPosition(date, latitude, longitude);
+  const next = (name: "dawn" | "sunrise" | "sunset" | "dusk") => {
+    const today = times[name];
+    return today && today.getTime() > at
+      ? today.toISOString()
+      : isoOf(tomorrow[name]);
+  };
+  return {
+    at: date.toISOString(),
+    nightEnd: isoOf(times.nightEnd),
+    dawn: isoOf(times.dawn),
+    sunrise: isoOf(times.sunrise),
+    goldenHourEnd: isoOf(times.goldenHourEnd),
+    solarNoon: times.solarNoon.toISOString(),
+    goldenHour: isoOf(times.goldenHour),
+    sunset: isoOf(times.sunset),
+    dusk: isoOf(times.dusk),
+    night: isoOf(times.night),
+    azimuthDeg: azimuth,
+    altitudeDeg: altitude,
+    rising: at < times.solarNoon.getTime(),
+    daylight: altitude > 0,
+    next: {
+      dawn: next("dawn"),
+      sunrise: next("sunrise"),
+      sunset: next("sunset"),
+      dusk: next("dusk"),
+    },
+    alwaysUp: times.alwaysUp,
+    alwaysDown: times.alwaysDown,
+  };
+}
+
+/** How far a source's sunrise or sunset may be from the computed one before it is worth saying. */
+export const SUN_TOLERANCE_MS = 2 * 60_000;
+
+/**
+ * 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 function sunDisagrees(
+  source: string,
+  latitude: number,
+  longitude: number,
+  reported: { sunrise?: string; sunset?: string },
+): string | undefined {
+  const notes = (["sunrise", "sunset"] as const).flatMap((name) => {
+    const t = Date.parse(reported[name] ?? "");
+    if (Number.isNaN(t)) return [];
+    const nearest = [t - DAY_MS, t, t + DAY_MS]
+      .map((day) => sunNow(latitude, longitude, day)[name])
+      .filter((c) => c !== undefined)
+      .map((c) => ({ computed: c, offMs: Math.abs(t - Date.parse(c)) }))
+      .sort((a, b) => a.offMs - b.offMs)[0];
+    if (nearest && nearest.offMs <= SUN_TOLERANCE_MS) return [];
+    return [
+      `${source} ${name} ${reported[name]} ${nearest ? `is ${(nearest.offMs / 60_000).toFixed(1)} min from the computed ${nearest.computed}` : "on a day the computed sun has none"}`,
+    ];
+  });
+  return notes.length ? notes.join("; ") : undefined;
+}