@khalido/home 0.0.0-stage → 0.1.0

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,195 @@
+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.
+ */
+export declare function discover<T = Found>(pass: () => Promise<T[]>, options: {
+    clock: Clock;
+    passes?: number;
+    gapMs?: number;
+    key?: (t: T) => string;
+    done?: (all: T[]) => 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;