@khalido/home 0.0.0-stage → 0.1.0

package/src/home.ts

@@ -0,0 +1,205 @@
+import { z } from "zod";
+import { asOf, type Clock, realClock } from "./clock.ts";
+import { errorText } from "./connector.ts";
+
+/** A secret in a home config is the name of an environment variable, never the secret: a pasted key fails here. */
+export const envName = z
+  .string()
+  .regex(
+    /^[A-Z_][A-Z0-9_]*$/,
+    "an environment variable name (e.g. AMBER_KEY), not the secret itself",
+  );
+/** A file a connector needs (a CA, a token), relative to the config file. The caller reads it; the library reads no files. */
+export const filePath = z.string().min(1);
+
+/** How an integration is doing. "unavailable" means it stopped and will not retry by itself. */
+export type Status =
+  "connecting" | "connected" | "disconnected" | "unavailable";
+
+/**
+ * One integration's slice of the home: its status, a human detail, anything odd the device reported, and its state.
+ * `createHome` stamps the times (UTC ISO). `lastGoodAt`: its last report while connected, or the read time a connected report
+ * gives when it repeats an older read (weather's 5-minute sun tick). `downSince`: when it stopped being connected (or started,
+ * if it never has); none while connected. Any other time an integration sets is ignored.
+ */
+export type Part<S = unknown> = {
+  status: Status;
+  detail?: string;
+  anomaly?: string;
+  state?: S;
+  lastGoodAt?: string;
+  downSince?: string;
+};
+
+/**
+ * An integration is a folder in `src/` that exports a factory returning this.
+ * `run` keeps its state current until `signal` aborts, reporting each change through `update`.
+ * `refresh` asks for a fresh read now, ahead of the integration's schedule; it returns at once and the read reports through `update`.
+ */
+export type Integration<S = unknown, N extends string = string> = {
+  name: N;
+  run(signal: AbortSignal, update: (part: Part<S>) => void): Promise<void>;
+  refresh(): void;
+};
+
+/** The state an integration reports. */
+export type StateOf<I> = I extends Integration<infer S, string> ? S : never;
+
+/**
+ * The whole home: one `Part` per integration, by name, each typed by its integration (`snapshot.weather?.state` is a
+ * `WeatherState`). A name can be missing: a config need not have every connector. This is the cache every read comes from.
+ */
+export type HomeSnapshot<
+  I extends Integration<any, string> = Integration<unknown, string>,
+> = { [X in I as X["name"]]?: Part<StateOf<X>> };
+
+/** One report: which integration, its part before and after. Typed by name, so `change.after.state` is that integration's state. */
+export type Change<
+  I extends Integration<any, string> = Integration<unknown, string>,
+> = {
+  [X in I as X["name"]]: {
+    name: X["name"];
+    before: Part<StateOf<X>>;
+    after: Part<StateOf<X>>;
+  };
+}[I["name"]];
+
+/** The times `createHome` keeps on a part, from the one before it: when it was last good, and when it stopped being. */
+function stamped(part: Part, before: Part | undefined, now: string): Part {
+  if (part.status === "connected")
+    return {
+      ...part,
+      lastGoodAt: part.lastGoodAt ?? now,
+      downSince: undefined,
+    };
+  return {
+    ...part,
+    lastGoodAt: before?.lastGoodAt,
+    downSince: before?.downSince ?? now,
+  };
+}
+
+/**
+ * Load a home: run each integration, keep one snapshot, call `onChange` with it and what changed after every report.
+ * `clock` stamps each part's `lastGoodAt` and `downSince`.
+ */
+export function createHome<I extends Integration<any, string>>(
+  integrations: readonly I[],
+  onChange?: (home: HomeSnapshot<I>, change: Change<I>) => void,
+  options: { clock?: Clock } = {},
+) {
+  type Name = I["name"];
+  const clock = options.clock ?? realClock;
+  let snapshot = Object.fromEntries(
+    integrations.map((i) => [i.name, { status: "connecting" }]),
+  ) as HomeSnapshot<I>;
+  const waiting = new Map<string, (() => void)[]>(); // refresh() callers, resolved by the integration's next report
+  const finished = new Set<string>(); // integrations whose run has ended: a refresh of one resolves at once, nothing will report
+  const set = (name: Name, reported: Part) => {
+    const before = (snapshot as Record<string, Part>)[name]!;
+    const part = stamped(reported, before, asOf(clock));
+    snapshot = { ...snapshot, [name]: part };
+    onChange?.(snapshot, { name, before, after: part } as Change<I>);
+    const w = waiting.get(name);
+    if (w) {
+      waiting.delete(name);
+      for (const resolve of w) resolve();
+    }
+  };
+  return {
+    /** The latest snapshot. Never touches a device. */
+    snapshot: () => snapshot,
+    /** One integration's part, typed by its name: `home.part("weather")?.state?.blocks`. */
+    part: <N extends Name>(name: N): HomeSnapshot<I>[N] => snapshot[name],
+    /** One integration by name, for its writes: `home.integration("daikin")?.client.write(setPower(true))`. */
+    integration: <N extends Name>(
+      name: N,
+    ): Extract<I, { name: N }> | undefined =>
+      integrations.find((i) => i.name === name) as
+        Extract<I, { name: N }> | undefined,
+    /**
+     * Read now: one integration by name, or every one. Results arrive through the snapshot and `onChange` as usual; the
+     * promise resolves once each target has reported (its next update, good or bad), or at once for one whose run has ended.
+     */
+    refresh(name?: Name): Promise<void> {
+      const targets =
+        name === undefined
+          ? integrations
+          : integrations.filter((i) => i.name === name);
+      if (!targets.length)
+        throw new Error(
+          `no integration "${name}"; have ${integrations.map((i) => i.name).join(", ")}`,
+        );
+      const reported = targets.map(
+        (i) =>
+          new Promise<void>((resolve) => {
+            if (finished.has(i.name)) return resolve();
+            waiting.set(i.name, [...(waiting.get(i.name) ?? []), resolve]);
+          }),
+      );
+      for (const i of targets) i.refresh();
+      return Promise.all(reported).then(() => undefined);
+    },
+    /** Run every integration until `signal` aborts. One failing marks itself unavailable; the rest carry on. */
+    async start(signal: AbortSignal): Promise<void> {
+      finished.clear(); // a second start, after the first has stopped, runs them all again
+      const now = asOf(clock); // the wait for a first report counts from here, not from createHome
+      snapshot = Object.fromEntries(
+        Object.entries(snapshot as Record<string, Part>).map(([name, p]) => [
+          name,
+          p.status === "connecting"
+            ? { ...p, downSince: p.downSince ?? now }
+            : p,
+        ]),
+      ) as HomeSnapshot<I>;
+      await Promise.all(
+        integrations.map((i) =>
+          i
+            .run(signal, (part) => set(i.name, part))
+            .catch((error) =>
+              set(i.name, { status: "unavailable", detail: errorText(error) }),
+            )
+            .finally(() => {
+              finished.add(i.name);
+              for (const resolve of waiting.get(i.name) ?? []) resolve(); // nothing more will report
+              waiting.delete(i.name);
+            }),
+        ),
+      );
+    },
+  };
+}
+
+/** Answered: past connecting, and when the state lists sources (the weather), every source has read. */
+const answered = (p: Part | undefined) =>
+  !!p &&
+  p.status !== "connecting" &&
+  Object.values(
+    (p.state as { sources?: Record<string, { read: boolean }> })?.sources ?? {},
+  ).every((s) => s.read);
+
+/**
+ * One read of everything, for a script, a test or a one-shot command: run the integrations until each has answered
+ * (connected or not), at most `ms` (15 s by default) or until `signal` aborts, then stop them and return the snapshot.
+ */
+export async function settle<I extends Integration<any, string>>(
+  integrations: readonly I[],
+  options: { ms?: number; clock?: Clock; signal?: AbortSignal } = {},
+): Promise<HomeSnapshot<I>> {
+  const { ms = 15_000, clock = realClock, signal } = options;
+  const stop = new AbortController();
+  const run = signal ? AbortSignal.any([signal, stop.signal]) : stop.signal; // the caller's signal stops it too, with nothing left on it after
+  const home = createHome(
+    integrations,
+    (snapshot) => {
+      if (Object.values(snapshot as Record<string, Part>).every(answered))
+        stop.abort();
+    },
+    { clock },
+  );
+  const running = home.start(run);
+  await Promise.race([clock.sleep(ms, run), running]);
+  stop.abort();
+  await running;
+  return home.snapshot();
+}

package/src/index.ts

@@ -0,0 +1,62 @@
+// The root entry: the home, its config, discovery types, the clock, energy, and the sun, rain and day-block helpers. The weather types are in `./weather`.
+// Each connector has its own entry point (`@khalido/home/hue` and so on). Every export is named; test/exports.test.ts lists them.
+export {
+  type Change,
+  createHome,
+  envName,
+  filePath,
+  settle,
+  type HomeSnapshot,
+  type Integration,
+  type Part,
+  type StateOf,
+  type Status,
+} from "./home.ts";
+export {
+  DOWN_POLLS,
+  type Health,
+  health,
+  PUSH_DOWN_MS,
+  STALE_POLLS,
+} from "./health.ts";
+export { asOf, type Clock, realClock } from "./clock.ts";
+export { ConnectorError } from "./connector.ts";
+export {
+  bestWindow,
+  type EnergyNow,
+  energyNow,
+  gridText,
+  type PriceWindow,
+  solarLevel,
+} from "./energy.ts";
+export {
+  checkHome,
+  checkPlan,
+  Device,
+  HomeConfig,
+  HomeConfigError,
+  type HomeIntegration,
+  type LoadOptions,
+  loadHome,
+  parseJsonc,
+  Room,
+  type Setup,
+} from "./config.ts";
+export type {
+  AddressCache,
+  CachedAddress,
+  Connector,
+  Finder,
+  Found,
+} from "./discover.ts";
+export { type SunNow, sunNow } from "./connectors/weather/sun.ts";
+export { type RainSoon, rainSoon } from "./connectors/weather/rain.ts";
+export {
+  type BlockDef,
+  BLOCKS,
+  blockText,
+  type DayBlock,
+  type DayBlocks,
+  dayBlocks,
+} from "./connectors/weather/blocks.ts";
+export type { EnvVar, IotClass, Manifest } from "./manifest.ts";

package/src/lane.ts

@@ -0,0 +1,110 @@
+import { type Clock, realClock } from "./clock.ts";
+
+// Writes to a device go through a lane: one at a time, spaced by the device's gap, and coalesced per slot. A slot is
+// what one write changes (a light, the AC, a speaker's volume). While a slot's write waits, a newer write to the same
+// slot merges into it: the middle drops, the last value lands. A slot sending faster than `perMinute` is held to that
+// rate rather than refused, so a runaway loop slows down and a person's last change still arrives.
+
+export type LaneOptions = {
+  /** Minimum time between two sends on the lane, across slots. */
+  gapMs: number;
+  /** At most this many sends per slot in any minute; more wait their turn, still coalescing. None: no cap. */
+  perMinute?: number;
+  clock?: Clock;
+};
+
+type Waiter = { resolve(value: unknown): void; reject(error: unknown): void };
+type Pending = {
+  slot: string;
+  body: unknown;
+  write: (body: unknown) => Promise<unknown>;
+  waiters: Waiter[];
+};
+
+const MINUTE = 60_000;
+
+/**
+ * A write lane for one device or bridge. `send(slot, body, write, merge)` resolves with the result of the send that
+ * carried its body: a write merged into a later one resolves (or rejects) with that later one. `merge(older, newer)`
+ * defaults to the newer body alone.
+ */
+export function writeLane(options: LaneOptions) {
+  if (options.perMinute !== undefined && !(options.perMinute >= 1))
+    throw new RangeError(
+      `writeLane: perMinute must be at least 1, got ${options.perMinute}`,
+    );
+  const clock = options.clock ?? realClock;
+  const queue: Pending[] = []; // in order of each slot's first waiting write
+  const sent = new Map<string, number[]>(); // send times per slot, the last minute's
+  let lastAt = -Infinity;
+  let running = false;
+  let wake = new AbortController();
+
+  const recent = (slot: string) =>
+    (sent.get(slot) ?? []).filter((t) => t > clock.now() - MINUTE);
+
+  function readyAt(slot: string): number {
+    const times = recent(slot);
+    const capped =
+      options.perMinute !== undefined && times.length >= options.perMinute
+        ? times[times.length - options.perMinute]! + MINUTE
+        : -Infinity;
+    return Math.max(lastAt + options.gapMs, capped);
+  }
+
+  async function run() {
+    running = true;
+    while (queue.length) {
+      const now = clock.now();
+      const next = queue.find((p) => readyAt(p.slot) <= now);
+      if (!next) {
+        wake = new AbortController();
+        await clock.sleep(
+          Math.min(...queue.map((p) => readyAt(p.slot))) - now,
+          wake.signal,
+        );
+        continue;
+      }
+      queue.splice(queue.indexOf(next), 1);
+      lastAt = now;
+      sent.set(next.slot, [...recent(next.slot), now]);
+      try {
+        const result = await next.write(next.body);
+        for (const w of next.waiters) w.resolve(result);
+      } catch (error) {
+        for (const w of next.waiters) w.reject(error);
+      }
+    }
+    running = false;
+  }
+
+  return {
+    send<B, T>(
+      slot: string,
+      body: B,
+      write: (body: B) => Promise<T>,
+      merge: (older: B, newer: B) => B = (_, newer) => newer,
+    ): Promise<T> {
+      return new Promise<T>((resolve, reject) => {
+        const waiter = { resolve, reject } as Waiter;
+        const waiting = queue.find((p) => p.slot === slot);
+        if (waiting) {
+          waiting.body = merge(waiting.body as B, body);
+          waiting.write = write as Pending["write"];
+          waiting.waiters.push(waiter);
+          return;
+        }
+        queue.push({
+          slot,
+          body,
+          write: write as Pending["write"],
+          waiters: [waiter],
+        });
+        if (running)
+          wake.abort(); // a sleeping lane looks again: this slot may be ready sooner
+        else void run();
+      });
+    },
+  };
+}
+export type WriteLane = ReturnType<typeof writeLane>;

package/src/locate.ts

@@ -0,0 +1,85 @@
+import { applyEdits, modify, parse } from "jsonc-parser";
+import { z } from "zod";
+
+// A street address to the home's latitude and longitude, once, through OpenStreetMap's Nominatim, and that position
+// written into a home config's text. Pure: the caller passes `fetch` and its User-Agent, and writes the file.
+
+/** One Nominatim match. It sends the coordinates as strings; they are read as numbers, never rounded. */
+const Place = z.looseObject({
+  display_name: z.string(),
+  lat: z.coerce.number(),
+  lon: z.coerce.number(),
+});
+
+export type Located = { name: string; latitude: number; longitude: number };
+
+/**
+ * The best match for `address`, or undefined when Nominatim finds none. Its usage policy requires a User-Agent that
+ * names the application, and allows one request a second: this is for a one-off lookup, not a loop.
+ */
+export async function geocode(
+  address: string,
+  options: { fetch?: typeof fetch; userAgent: string; signal?: AbortSignal },
+): Promise<Located | undefined> {
+  const url = `https://nominatim.openstreetmap.org/search?${new URLSearchParams({ q: address, format: "jsonv2", limit: "1" })}`;
+  const res = await (options.fetch ?? fetch)(url, {
+    headers: { "User-Agent": options.userAgent },
+    signal: options.signal ?? AbortSignal.timeout(10_000),
+  });
+  if (!res.ok) throw new Error(`Nominatim answered ${res.status}`);
+  const places = z.array(Place).safeParse(await res.json());
+  if (!places.success)
+    throw new Error(
+      "Nominatim's answer was not a list of places with coordinates",
+    );
+  const p = places.data[0];
+  return p && { name: p.display_name, latitude: p.lat, longitude: p.lon };
+}
+
+/**
+ * A config's text with `location.latitude` and `.longitude` set and, when it has none, `.timezone`, through
+ * jsonc-parser's edits: comments and every other key stay. With no `location` (absent or commented out) a fresh one is
+ * added, and `fresh` says so; a commented-out one is left as it was.
+ */
+export function applyLocation(
+  text: string,
+  at: { latitude: number; longitude: number },
+  timeZone: string,
+): { text: string; fresh: boolean; timezoneSet: boolean } {
+  const location = (parse(text) as { location?: unknown } | undefined)
+    ?.location;
+  const format = { formattingOptions: { insertSpaces: true, tabSize: 2 } };
+  if (typeof location !== "object" || location === null) {
+    return {
+      text: applyEdits(
+        text,
+        modify(
+          text,
+          ["location"],
+          {
+            latitude: at.latitude,
+            longitude: at.longitude,
+            timezone: timeZone,
+          },
+          format,
+        ),
+      ),
+      fresh: true,
+      timezoneSet: true,
+    };
+  }
+  let out = text;
+  for (const [key, value] of [
+    ["latitude", at.latitude],
+    ["longitude", at.longitude],
+  ] as const)
+    out = applyEdits(out, modify(out, ["location", key], value, format));
+  const timezoneSet =
+    (location as { timezone?: unknown }).timezone === undefined;
+  if (timezoneSet)
+    out = applyEdits(
+      out,
+      modify(out, ["location", "timezone"], timeZone, format),
+    );
+  return { text: out, fresh: false, timezoneSet };
+}

package/src/manifest.ts

@@ -0,0 +1,43 @@
+import type { Part } from "./home.ts";
+
+// What each connector declares about itself, so the CLI, `.env.example` and the docs derive from one place. Modelled on
+// Home Assistant's manifest (domain, name, iot_class). Each connector's index.ts exports one as `manifest`.
+
+/** Home Assistant's `iot_class`: where the device is and how its state arrives. */
+export type IotClass = "local_push" | "local_polling" | "cloud_polling";
+
+/** One environment name the CLI reads for a connector; `.env.example` is written from these. `optional`: `home status` runs without it. */
+export type EnvVar = {
+  name: string;
+  what: string;
+  optional?: boolean;
+  example?: string;
+};
+
+export type Manifest<S = unknown> = {
+  /** The folder, the config's connector literal, the integration's name and the CLI verb: "hue". */
+  name: string;
+  title: string;
+  iotClass: IotClass;
+  pollSeconds?: number;
+  /** What it reaches and with what key, for `home status`. */
+  access: string;
+  /** Every env name the CLI reads for this connector, in `.env.example`'s order. */
+  env: EnvVar[];
+  /** Config fields that are file paths, read relative to the config file. */
+  files?: string[];
+  /** The status text: the first line is the connector's own summary, any further lines its children (rooms, devices). Empty without state. */
+  lines(part: Part<S>): string[];
+  /** The state as `home status --json` shows it, when it is not the state itself. */
+  record?(part: Part<S>): Record<string, unknown>;
+};
+
+/** Watts as "1.2 kW", or "" without a number. Rounded for reading only. */
+export const kw = (w: unknown) =>
+  typeof w === "number" ? `${(w / 1000).toFixed(1)} kW` : "";
+
+/** A value's text when it exists, else "": a missing field is left out, never printed as "undefined". */
+export const field = (
+  value: number | undefined,
+  text: (v: number) => string,
+) => (value === undefined ? "" : text(value));

package/src/manifests.ts

@@ -0,0 +1,27 @@
+import { manifest as amber } from "./connectors/amber/index.ts";
+import { manifest as cast } from "./connectors/cast/index.ts";
+import { manifest as daikin } from "./connectors/daikin/index.ts";
+import { manifest as enphase } from "./connectors/enphase/index.ts";
+import { manifest as hue } from "./connectors/hue/index.ts";
+import { manifest as printers } from "./connectors/printers/index.ts";
+import { manifest as spotify } from "./connectors/spotify/index.ts";
+import { manifest as up } from "./connectors/up/index.ts";
+import { manifest as weather } from "./connectors/weather/index.ts";
+import type { Manifest } from "./manifest.ts";
+
+/** Every connector's manifest, in the order `home status` and `.env.example` list them. */
+export const MANIFESTS: Manifest<any>[] = [
+  hue,
+  daikin,
+  enphase,
+  amber,
+  up,
+  weather,
+  cast,
+  printers,
+  spotify,
+];
+
+/** One connector's manifest by name, or undefined. */
+export const manifestOf = (name: string): Manifest<any> | undefined =>
+  MANIFESTS.find((m) => m.name === name);

package/src/node-fetch.ts

@@ -0,0 +1,41 @@
+import { Agent, fetch as undiciFetch } from "undici";
+import type { LoadOptions } from "./config.ts";
+
+// `@khalido/home/node`: the fetches Hue and Enphase need under Node, where Bun's `tls` fetch option does not exist. Node's
+// global `fetch` takes no CA, so these use undici's own `fetch` and `Agent` (one undici on both sides). Outside the
+// runtime-neutral build, like cast/tls.ts; a Node consumer passes `NODE_TLS` to `loadHome`, or one fetch to `hue()` or `enphase()`.
+
+/** undici's `fetch` through `dispatcher`. Takes a URL, not a `Request`, and returns undici's own `Response`. */
+const through = (dispatcher: Agent) =>
+  ((input: RequestInfo | URL, init?: RequestInit) =>
+    undiciFetch(
+      input as never,
+      { ...init, dispatcher } as never,
+    )) as unknown as typeof fetch;
+
+/** A `fetch` that trusts only `ca` and accepts only a certificate whose CN is `bridgeId`: Node's `bunPinnedFetch`. */
+export function nodePinnedFetch(bridgeId: string, ca: string): typeof fetch {
+  const checkServerIdentity = (
+    _host: string,
+    cert: { subject?: { CN?: string | string[] } },
+  ) => {
+    const cn = [cert.subject?.CN].flat()[0];
+    return cn?.toLowerCase() === bridgeId.toLowerCase()
+      ? undefined
+      : new Error(
+          `Hue bridge certificate is for ${cn ?? "nobody"}, expected ${bridgeId}`,
+        );
+  };
+  return through(new Agent({ connect: { ca, checkServerIdentity } }));
+}
+
+/** A `fetch` for the Enphase gateway that skips certificate verification, for its requests only: Node's `bunGatewayFetch`. */
+export function nodeGatewayFetch(): typeof fetch {
+  return through(new Agent({ connect: { rejectUnauthorized: false } }));
+}
+
+/** What `loadHome` takes as `tls` under Node. */
+export const NODE_TLS = {
+  hue: nodePinnedFetch,
+  enphase: nodeGatewayFetch,
+} satisfies LoadOptions["tls"];

package/src/poll.ts

@@ -0,0 +1,33 @@
+import type { Clock } from "./clock.ts";
+
+/**
+ * The wait between polls, shared by every polling integration, so each can be told to read now.
+ * `wait` resolves after `ms`, on abort, or on `nudge()`, and says whether a nudge woke it. A nudge while no one is waiting (mid-read) makes the next wait
+ * return at once, so a refresh asked for during a read still gets a read that starts after it.
+ */
+export function poller(clock: Clock) {
+  let wake: (() => void) | undefined;
+  let pending = false;
+  return {
+    async wait(ms: number, signal?: AbortSignal): Promise<boolean> {
+      if (signal?.aborted) return false;
+      if (pending) return !(pending = false);
+      const nudged = new AbortController();
+      wake = () => nudged.abort();
+      try {
+        await clock.sleep(
+          ms,
+          signal ? AbortSignal.any([signal, nudged.signal]) : nudged.signal,
+        );
+        return nudged.signal.aborted;
+      } finally {
+        wake = undefined;
+        pending = false;
+      }
+    },
+    nudge(): void {
+      if (wake) wake();
+      else pending = true;
+    },
+  };
+}