@khalido/home 0.0.0-stage → 0.1.1

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;

package/dist/connectors/weather/sun.js

@@ -0,0 +1,65 @@
+import { getPosition, getTimes } from "suncalc";
+const DAY_MS = 86_400_000;
+const isoOf = (d) => d?.toISOString();
+/** One owner for the sun's numbers. `at` is epoch ms. */
+export function sunNow(latitude, longitude, at) {
+    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) => {
+        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, latitude, longitude, reported) {
+    const notes = ["sunrise", "sunset"].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;
+}

package/dist/discover.d.ts

@@ -0,0 +1,197 @@
+import type { Clock } from "./clock.ts";
+import type { HomeConfig } from "./config.ts";
+/** mDNS service types worth looking for at home, and what this package does with each. Extend the list as needed. */
+export declare const KNOWN_SERVICES: Record<string, {
+    what: string;
+    connector?: string;
+}>;
+/** A device a discovery answer named: its connector, the identity it reported, and where it answered; Cast adds its name, model, port and whether it is a group; a printer adds its port, whether it answered on `_ipps._tcp`, and its TXT record. */
+export type Found = {
+    connector: Connector;
+    id: string;
+    host: string;
+    name?: string;
+    model?: string;
+    port?: number;
+    group?: boolean;
+    secure?: boolean;
+    txt?: Record<string, string>;
+};
+/** One connector's discovery, as the caller can run it (mDNS, UDP): every device of that kind that answered. */
+export type Finder = () => Promise<Found[]>;
+/** Which config field holds each connector's identity, as its discovery reports it. */
+export declare const IDENTITY: {
+    readonly hue: "bridgeId";
+    readonly daikin: "mac";
+    readonly enphase: "serial";
+    readonly cast: "castId";
+    readonly printers: "uuid";
+};
+export type Connector = keyof typeof IDENTITY;
+/** Connectors with many devices in one integration (every Cast device and group, every printer); the rest allow one device for now. */
+export declare const MANY: ReadonlySet<string>;
+/** An identity without case, separators or a `urn:uuid:` prefix: "00:17:88:B0" is "001788b0", "urn:uuid:AB-CD" is "abcd". */
+export declare const idKey: (id: string) => string;
+/** Identities compared by `idKey`. */
+export declare const sameId: (a: string, b: string) => boolean;
+export type Match = {
+    moved: {
+        index: number;
+        id: string;
+        connector: Connector;
+        from: string;
+        to: string;
+    }[];
+    renamed: {
+        index: number;
+        id: string;
+        connector: Connector;
+        from: string;
+        to: string;
+    }[];
+    added: {
+        found: Found;
+        entry: Record<string, string | number>;
+    }[];
+    skipped: {
+        found: Found;
+        why: string;
+    }[];
+    known: {
+        id: string;
+        connector: Connector;
+        hint?: string;
+    }[];
+};
+/**
+ * Match what discovery found against the config by identity. An entry with no identity yet is matched by host, and a
+ * device at an entry's host with a different identity is a conflict, not a match. New entries get ids no entry has.
+ */
+export declare function matchFound(config: HomeConfig, found: Found[]): Match;
+/**
+ * The config's text with moved hosts and renamed Cast entries updated and new devices appended, through jsonc-parser's edits: comments, unknown
+ * keys and every other line stay as they were. A new device goes on its own line at its neighbour's indent.
+ */
+export declare function applyFound(text: string, match: Match, hasDevices: boolean): string;
+/** mDNS and Daikin's broadcast drop answers now and then, so discovery runs this many passes by default… */
+export declare const DISCOVERY_PASSES = 2;
+/** …this far apart. */
+export declare const DISCOVERY_GAP_MS = 5000;
+/** A device's key, across discovery passes and in the address cache: its connector and identity, without case or separators. */
+export declare const addressKey: (connector: Connector, id: string) => string;
+export declare const foundKey: (f: Found) => string;
+/** Where a device last answered, and when that was last confirmed. `name` is kept for Cast, whose config entry may be absent. */
+export type CachedAddress = {
+    host: string;
+    port?: number;
+    name?: string;
+    seenAt: string;
+};
+/**
+ * Addresses kept between runs, so discovery stays rare. The caller persists them (the CLI: a file); the library writes
+ * no files. `write` gets the whole map each time an address is new or has changed.
+ */
+export type AddressCache = {
+    read(): Record<string, CachedAddress>;
+    write(entries: Record<string, CachedAddress>): void;
+};
+/**
+ * One run's view of an address cache. `fresh` is a cached address confirmed since the config was edited (`configAt`,
+ * the config file's time; a config edited since wins); `seen` records an address that answered, writing through when it
+ * changed or was not fresh, so an address confirmed after a config edit is trusted again. A Cast name, when given, is the
+ * device's own (discovery's fn, or its own multizone status, never a config's), so a new one is written too; a call
+ * without a name keeps the one cached.
+ */
+export declare function addressBook(cache: AddressCache | undefined, options?: {
+    configAt?: number;
+    now?: () => number;
+}): {
+    fresh(connector: Connector, id?: string): CachedAddress | undefined;
+    seen(connector: Connector, id: string | undefined, address: {
+        host: string;
+        port?: number;
+        name?: string;
+    }): void;
+    entries: () => {
+        [x: string]: CachedAddress;
+    };
+};
+/**
+ * Run one discovery `passes` times, `gapMs` apart, and return the union (first answer wins). `onPass` sees each pass's
+ * additions as they come; `done` ends it early once what was looked for has answered. A pass that throws adds nothing;
+ * when every pass threw, discovery never ran, so it throws the last error rather than reporting nothing found. An error
+ * `stopOn` accepts is thrown at once: no later pass could do better.
+ */
+export declare function discover<T = Found>(pass: () => Promise<T[]>, options: {
+    clock: Clock;
+    passes?: number;
+    gapMs?: number;
+    key?: (t: T) => string;
+    done?: (all: T[]) => boolean;
+    stopOn?: (error: unknown) => boolean;
+    onPass?: (n: number, added: T[]) => void;
+    signal?: AbortSignal;
+}): Promise<T[]>;
+/** Discovery runs after this many failed reads in a row. */
+export declare const RESCAN_AFTER_FAILURES = 3;
+/** Then again after these delays, then hourly for as long as reads fail. */
+export declare const RESCAN_DELAYS_MS: number[];
+export declare const HOUR = 3600000;
+/** The wait before the next scan after `attempt` scans have missed: 1, 5 and 15 minutes, then hourly. The relocator and Cast's re-discovery share it. */
+export declare const rescanDelay: (attempt: number) => number;
+/** After this long without a read, the detail says a day has passed; the scans carry on hourly. */
+export declare const DAY_MS: number;
+/** What `failed()` learned: a move, that a day has passed since the scans began, whether the last scan found it at its address, or why the last scan could not run. */
+export type Lost = {
+    moved?: string;
+    overADay?: boolean;
+    seenHere?: boolean;
+    discoveryFailed?: string;
+};
+/**
+ * A polling connector's address, rescanned only on failure. `failed()` after each failed read runs `find` once reads
+ * have failed `RESCAN_AFTER_FAILURES` times in a row, then on the backoff, then hourly with no end, so a device that comes
+ * back is found without a restart. `ok()` after a good read, `reset()` on a refresh (the next failure scans at once).
+ * Without `find` or an identity it never scans. `cached`: the starting host came from an address cache, so the first
+ * failure scans at once. `failed(signal)` takes the run's signal, so a shutdown does not wait out a scan.
+ */
+export declare function relocator(options: {
+    host: string;
+    id?: string;
+    find?: Finder;
+    clock: Clock;
+    cached?: boolean;
+}): {
+    host: () => string;
+    ok: () => undefined;
+    reset: () => undefined;
+    failed(signal?: AbortSignal): Promise<Lost>;
+};
+/** A failed read's detail, saying what discovery found: never "not found" unless a scan looked and missed it. */
+export declare function lostDetail(lost: Lost, error: unknown): string;
+/** Instance names from `dns-sd -B`, each once. */
+export declare const parseBrowse: (text: string) => string[];
+/**
+ * `avahi-browse --parsable --resolve` (Linux): each resolved instance once, IPv4 only (the config keeps IPv4 addresses).
+ * A resolved line is `=;interface;IPv4;name;type;domain;hostname;address;port;"txt" "txt"`; names and TXT strings use
+ * the same escapes as `dns-sd` (`\059` for a `;` in a name, `\"` inside TXT). An instance seen on two interfaces is kept
+ * once, the first; loopback is skipped. Checked against avahi-utils on Debian trixie, 2026-10-16.
+ */
+export declare function parseAvahi(text: string): {
+    instance: string;
+    hostname: string;
+    host: string;
+    port: number;
+    txt: Record<string, string>;
+}[];
+/** Instance names from `avahi-browse --parsable` (a `+` line per instance and interface), each once. */
+export declare const parseAvahiBrowse: (text: string) => string[];
+/**
+ * One `dns-sd -L` answer: the host and port it can be reached at, and its TXT record. TXT values come escaped (`\ ` for
+ * a space, `\226\128\153` for each byte of a UTF-8 character); these are undone, so `fn` reads as the Google Home app shows it.
+ */
+export declare function parseResolve(text: string): {
+    hostname: string;
+    port: number;
+    txt: Record<string, string>;
+} | undefined;