@khalido/home 0.0.0-stage → 0.1.1

package/dist/config.js

@@ -0,0 +1,392 @@
+import { parse, printParseErrorCode } from "jsonc-parser";
+import { z } from "zod";
+import { isTimeZone, realClock } from "./clock.js";
+import { errorText } from "./connector.js";
+import { amber, configSchema as amberDevice, } from "./connectors/amber/index.js";
+import { daikin, configSchema as daikinDevice, } from "./connectors/daikin/index.js";
+import { cast, configSchema as castDevice, resolvedFrom, } from "./connectors/cast/index.js";
+import { bunGatewayFetch, enphase, configSchema as enphaseDevice, } from "./connectors/enphase/index.js";
+import { addressBook, discover, MANY, sameId, } from "./discover.js";
+import { envName, filePath } from "./home.js";
+import { bunPinnedFetch, hue, configSchema as hueDevice, } from "./connectors/hue/index.js";
+import { printers, configSchema as printersDevice, } from "./connectors/printers/index.js";
+import { spotify, configSchema as spotifyDevice, } from "./connectors/spotify/index.js";
+import { up, configSchema as upDevice } from "./connectors/up/index.js";
+import { manifestOf } from "./manifests.js";
+import { bom, google, openMeteo, weather, } from "./connectors/weather/index.js";
+// One home config (JSONC) that the CLI, jaldi and the bot all read. Devices hold only what it takes to reach them and
+// where they live; what a device reports about itself comes live. Secrets are env names; files are paths the caller reads.
+/** Where a device or marker sits: `id` matches `<g class="room" id="…">` in the plan's SVG. */
+export const Room = z.looseObject({
+    id: z.string().startsWith("room-"),
+    name: z.string(),
+    floor: z.string().optional(),
+    hueRoom: z
+        .string()
+        .optional()
+        .describe("the Hue room, zone or grouped_light id whose lights this room's marker shows"),
+});
+/** JSONC (comments and trailing commas) through jsonc-parser, which runs on Node too; a syntax error throws rather than parsing to part of the file. */
+export function parseJsonc(text) {
+    const errors = [];
+    const value = parse(text, errors, { allowTrailingComma: true });
+    if (errors.length)
+        throw new SyntaxError(`JSONC: ${printParseErrorCode(errors[0].error)} at offset ${errors[0].offset}`);
+    return value;
+}
+/** Every device: an id, the room it is in (absent: the whole house), a name if the id is not enough. */
+const placed = {
+    id: z.string(),
+    room: z.string().startsWith("room-").optional(),
+    name: z.string().optional(),
+};
+/** A device is one connector's settings; a new connector adds its `configSchema` here, in one line. */
+export const Device = z.discriminatedUnion("connector", [
+    hueDevice.extend(placed),
+    daikinDevice.extend(placed),
+    enphaseDevice.extend(placed),
+    amberDevice.extend(placed),
+    upDevice.extend(placed),
+    castDevice.extend({ id: placed.id, room: placed.room }), // its name is required: the Google Home name
+    printersDevice.extend({ id: placed.id, room: placed.room }), // likewise: the printer's own name
+    spotifyDevice.extend(placed),
+]);
+export const WEATHER_SOURCES = ["bom", "open-meteo", "google"];
+export const HomeConfig = z.looseObject({
+    $schema: z.string().optional(),
+    name: z.string().optional(),
+    location: z
+        .looseObject({
+        latitude: z.number().min(-90).max(90),
+        longitude: z.number().min(-180).max(180),
+        bomForecast: z
+            .string()
+            .optional()
+            .describe("BOM précis location by name or aac, e.g. Sydney"),
+        timezone: z
+            .string()
+            .refine(isTimeZone, "an IANA time zone, e.g. Australia/Sydney")
+            .optional()
+            .describe("the home's IANA time zone, where its day starts (Enphase's and Up's today, the weather's day blocks) and the zone weather times show in; the runtime's when left out"),
+    })
+        .optional(),
+    weather: z
+        .looseObject({
+        sources: z
+            .array(z.enum(WEATHER_SOURCES))
+            .optional()
+            .describe("preference order; default open-meteo"),
+        pollMinutes: z.number().min(1).optional(),
+        googleKey: envName
+            .optional()
+            .describe("env name holding a Maps Platform key, when sources has google"),
+    })
+        .optional(),
+    rooms: z.array(Room).optional(),
+    devices: z.array(Device).optional(),
+    plan: z
+        .looseObject({ svg: filePath.optional(), json: filePath.optional() })
+        .optional()
+        .describe("the drawing, by path relative to this file"),
+});
+/** A config that cannot run. `problems` names each field. */
+export class HomeConfigError extends Error {
+    problems;
+    constructor(problems) {
+        super(problems.join("; "));
+        this.problems = problems;
+        this.name = "HomeConfigError";
+    }
+}
+/** A field's path in one format for every problem: `devices[3] (prices).key`. */
+function fieldPath(path, input) {
+    const devices = input
+        ?.devices;
+    return path
+        .map((p, i) => {
+        if (typeof p !== "number")
+            return `${i ? "." : ""}${String(p)}`;
+        const id = path[i - 1] === "devices" && i === 1 ? devices?.[p]?.id : undefined;
+        return `[${p}]${typeof id === "string" ? ` (${id})` : ""}`;
+    })
+        .join("");
+}
+/** The drawing side of a config: the schema, unique room and device ids, and every device's room present. Problems, not a throw. */
+export function checkPlan(input) {
+    const parsed = HomeConfig.safeParse(input);
+    if (!parsed.success)
+        return {
+            problems: parsed.error.issues.map((i) => `${fieldPath(i.path, input) || "(root)"}: ${i.message}`),
+        };
+    const config = parsed.data;
+    const ids = (config.rooms ?? []).map((r) => r.id);
+    const rooms = new Set(ids);
+    const problems = ids
+        .filter((id, i) => ids.indexOf(id) !== i)
+        .map((id) => `rooms: ${id} twice`);
+    const deviceIds = (config.devices ?? []).map((d) => d.id);
+    deviceIds.forEach((id, i) => deviceIds.indexOf(id) !== i &&
+        problems.push(`devices[${i}] (${id}).id: a second device with this id`));
+    (config.devices ?? []).forEach((d, i) => d.room &&
+        !rooms.has(d.room) &&
+        problems.push(`devices[${i}] (${d.id}).room: no room ${d.room}`));
+    (config.rooms ?? []).forEach((r, i) => "marker" in r &&
+        problems.push(`rooms[${i}] (${r.id}).marker: renamed hueRoom; marker now means only an SVG marker id`));
+    return { config, problems };
+}
+/**
+ * Validate a parsed config against `env`: `checkPlan`, one device per connector (Cast and printers: any number), and every env name set.
+ * Returns the problems rather than throwing, and what would be set up, secrets shown only as set or unset.
+ */
+export function checkHome(input, env) {
+    const { config, problems } = checkPlan(input);
+    if (!config)
+        return { setup: [], problems };
+    const secret = (field, name) => {
+        if (!env[name])
+            problems.push(`${field}: env ${name} is not set`);
+        return { [name]: env[name] ? "set" : "unset" };
+    };
+    const seen = new Map();
+    const setup = [];
+    (config.devices ?? []).forEach((d, i) => {
+        const at = `devices[${i}] (${d.id})`;
+        const twin = seen.get(d.connector);
+        if (twin && !MANY.has(d.connector))
+            problems.push(`${at}: a second ${d.connector} device (first: ${twin}); one per connector for now`);
+        seen.set(d.connector, d.id);
+        if (d.connector === "cast") {
+            const twinCast = (config.devices ?? []).findIndex((x) => x.connector === "cast" && sameId(x.castId, d.castId));
+            if (twinCast < i)
+                problems.push(`${at}.castId: the same Cast device as devices[${twinCast}] (${config.devices[twinCast].id})`);
+        }
+        if (d.connector === "printers") {
+            const twin = (config.devices ?? []).findIndex((x) => x.connector === "printers" && sameId(x.uuid, d.uuid));
+            if (twin < i)
+                problems.push(`${at}.uuid: the same printer as devices[${twin}] (${config.devices[twin].id})`);
+        }
+        const { connector, id, room, name, ...rest } = d;
+        // Only the schema's own fields: a loose entry may carry anything, a pasted secret included.
+        const known = Device.options.find((o) => o.shape.connector.value === connector).shape;
+        const settings = Object.fromEntries(Object.entries(rest).filter(([k, v]) => k in known &&
+            k !== "key" &&
+            (typeof v === "string" || typeof v === "number")));
+        const key = d.key; // any connector's `key` is an env name (the schema's envName)
+        setup.push({
+            name: connector,
+            from: id,
+            settings,
+            secrets: typeof key === "string" ? secret(`${at}.key`, key) : {},
+        });
+    });
+    if (config.location) {
+        const sources = config.weather?.sources ?? ["open-meteo"];
+        const key = config.weather?.googleKey;
+        if (sources.includes("google") && !key)
+            problems.push("weather.googleKey: needed when weather.sources has google");
+        setup.push({
+            name: "weather",
+            from: "location",
+            settings: {
+                latitude: config.location.latitude,
+                longitude: config.location.longitude,
+                sources: sources.join(", "),
+                ...(config.location.bomForecast
+                    ? { bomForecast: config.location.bomForecast }
+                    : {}),
+            },
+            secrets: sources.includes("google") && key
+                ? secret("weather.googleKey", key)
+                : {},
+        });
+    }
+    else if (config.weather)
+        problems.push("weather: needs location");
+    return { config, setup, problems };
+}
+/** The token in a JSON token file (`home enphase login` writes `{ token, expiresAt }`); a file that is not JSON says so by name. */
+function tokenFromJson(text, at) {
+    try {
+        return JSON.parse(text).token;
+    }
+    catch (error) {
+        throw new HomeConfigError([`${at}: not JSON (${errorText(error)})`]);
+    }
+}
+/** Build the integrations a config describes, in its device order, weather last. Throws `HomeConfigError` naming every problem. */
+export function loadHome(input, options) {
+    const { config, problems } = checkHome(input, options.env);
+    if (config && !options.readFile)
+        (config.devices ?? []).forEach((d, i) => {
+            for (const f of manifestOf(d.connector)?.files ?? []) {
+                const path = d[f];
+                if (typeof path === "string")
+                    problems.push(`devices[${i}] (${d.id}).${f}: needs readFile to read ${path}`);
+            }
+        });
+    const castAt = (config?.devices ?? []).findIndex((d) => d.connector === "cast");
+    const notBun = typeof globalThis.Bun === "undefined"; // Bun's fetch takes a `tls` option; elsewhere it is ignored and the read fails
+    for (const [i, d] of (config?.devices ?? []).entries())
+        if ((d.connector === "hue" || d.connector === "enphase") &&
+            !options.tls &&
+            notBun)
+            problems.push(`devices[${i}] (${d.id}): ${d.connector} needs tls (NODE_TLS from @khalido/home/node) outside Bun`);
+    if (castAt >= 0 && !options.castConnect)
+        problems.push(`devices[${castAt}] (${config.devices[castAt].id}): Cast needs castConnect (tlsConnect from @khalido/home/cast/tls)`);
+    if (castAt >= 0 && !options.finders?.cast)
+        problems.push(`devices[${castAt}] (${config.devices[castAt].id}): Cast needs finders.cast (its mDNS discovery)`);
+    if (!config || problems.length)
+        throw new HomeConfigError(problems);
+    const file = (path) => options.readFile(path);
+    const env = (name) => options.env[name];
+    const net = options.fetch ?? fetch;
+    const clock = options.clock ?? realClock;
+    const tls = options.tls ?? { hue: bunPinnedFetch, enphase: bunGatewayFetch };
+    const book = addressBook(options.cache, { configAt: options.configAt });
+    /** Where a polling connector starts: a fresh cached address, else the config's, and its write-back for each good read. */
+    const start = (connector, id, configured) => {
+        const cached = book.fresh(connector, id);
+        return {
+            host: cached?.host ?? configured,
+            hostCached: cached !== undefined,
+            seen: (at) => book.seen(connector, id, { host: at }),
+        };
+    };
+    // Every Cast entry is one integration, at the first Cast entry's place; so is every printer.
+    const printersAt = (config.devices ?? []).findIndex((d) => d.connector === "printers");
+    const integrations = (config.devices ?? []).flatMap((d, i) => d.connector === "cast"
+        ? i === castAt
+            ? [castAll()]
+            : []
+        : d.connector === "printers"
+            ? i === printersAt
+                ? [printersAll()]
+                : []
+            : [one(d, `devices[${i}] (${d.id})`)]);
+    function one(d, at) {
+        switch (d.connector) {
+            case "hue": {
+                const ca = file(d.ca);
+                return hue({
+                    ...start("hue", d.bridgeId, d.host),
+                    bridgeId: d.bridgeId,
+                    key: env(d.key),
+                    ca,
+                    fetch: tls.hue(d.bridgeId, ca),
+                    find: options.finders?.hue,
+                    clock,
+                });
+            }
+            case "daikin":
+                return daikin({
+                    ...start("daikin", d.mac, d.host),
+                    mac: d.mac,
+                    find: options.finders?.daikin,
+                    fetch: net,
+                    clock,
+                });
+            case "enphase": {
+                const text = file(d.token).trim();
+                const token = text.startsWith("{")
+                    ? tokenFromJson(text, `${at}.token`)
+                    : text;
+                if (!token)
+                    throw new HomeConfigError([`${at}.token: no token in ${d.token}`]);
+                return enphase({
+                    ...start("enphase", d.serial, d.host),
+                    token,
+                    serial: d.serial,
+                    find: options.finders?.enphase,
+                    fetch: tls.enphase(),
+                    timeZone: config.location?.timezone,
+                    clock,
+                });
+            }
+            case "amber":
+                return amber({ key: env(d.key), siteId: d.siteId, fetch: net, clock });
+            case "up":
+                return up({
+                    token: env(d.key),
+                    account: d.account,
+                    household: d.household,
+                    fetch: net,
+                    timeZone: config.location?.timezone,
+                    clock,
+                });
+            case "spotify":
+                return spotify({
+                    url: d.url,
+                    maxVolume: d.maxVolume,
+                    repairStalls: d.repairStalls,
+                    clock,
+                });
+        }
+    }
+    function castAll() {
+        const expect = config.devices.flatMap((x) => {
+            if (x.connector !== "cast")
+                return [];
+            const c = book.fresh("cast", x.castId);
+            return [
+                {
+                    castId: x.castId,
+                    name: x.name,
+                    ...(c?.port === undefined ? {} : { host: c.host, port: c.port }),
+                },
+            ];
+        });
+        // Two passes, as every discovery runs, but done once every entry in the config has answered.
+        const all = (found) => expect.every((e) => found.some((f) => sameId(f.id, e.castId)));
+        const resolve = async () => resolvedFrom(await discover(options.finders.cast, { clock, done: all }));
+        return cast({
+            resolve,
+            connect: options.castConnect,
+            expect,
+            serve: options.castServe,
+            clock,
+            seen: (id, a) => book.seen("cast", id, a),
+        });
+    }
+    function printersAll() {
+        const entries = config.devices.flatMap((x) => {
+            if (x.connector !== "printers")
+                return [];
+            const c = book.fresh("printers", x.uuid);
+            return [
+                {
+                    uuid: x.uuid,
+                    name: x.name,
+                    host: c?.host ?? x.host,
+                    port: c?.port ?? x.port,
+                    room: x.room,
+                    offlineDays: x.offlineDays,
+                },
+            ];
+        });
+        return printers({
+            printers: entries,
+            fetch: net,
+            find: options.finders?.printers,
+            clock,
+            seen: (uuid, a) => book.seen("printers", uuid, a),
+        });
+    }
+    if (config.location) {
+        const { latitude, longitude, bomForecast } = config.location;
+        const make = {
+            bom: () => bom({ fetch: options.ftpFetch, forecastLocation: bomForecast }),
+            "open-meteo": () => openMeteo({ fetch: net }),
+            google: () => google({ key: env(config.weather.googleKey), fetch: net }),
+        };
+        const sources = config.weather?.sources?.map((s) => make[s]());
+        integrations.push(weather({
+            latitude,
+            longitude,
+            sources,
+            pollMinutes: config.weather?.pollMinutes,
+            timeZone: config.location.timezone,
+            clock,
+        }));
+    }
+    return integrations;
+}

package/dist/connector.d.ts

@@ -0,0 +1,34 @@
+import type { z } from "zod";
+/** No device or service call waits longer than this. */
+export declare const TIMEOUT_MS = 10000;
+/**
+ * An error as a detail line: its message ("fetch failed", not "TypeError: fetch failed"), and its cause's when it has one.
+ * Node's fetch puts the reason there: "fetch failed: connect ECONNREFUSED 192.0.2.10:443".
+ */
+export declare function errorText(error: unknown): string;
+/** A failed device or service call. `status` is the HTTP status (or a device's own code); `code` a connector's own reason. */
+export declare class ConnectorError extends Error {
+    readonly status?: number;
+    readonly code?: string;
+    constructor(message: string, options?: {
+        status?: number;
+        code?: string;
+        cause?: unknown;
+    });
+}
+/** `fetch` that gives up after `timeoutMs`, or as soon as `signal` (a run's) aborts. Returns the response whatever its status. */
+export declare function fetchTimeout(fetcher: typeof fetch, url: string | URL, init?: Omit<RequestInit, "signal">, options?: {
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}): Promise<Response>;
+/**
+ * GET (or `init.method`) JSON through `fetchTimeout`. A non-ok status throws `error` (ConnectorError by default) with the
+ * status, as "HTTP 500 on GET /path" (no query: it can carry a key). With a `schema` the body is parsed by it.
+ */
+export declare function getJson<T = unknown>(fetcher: typeof fetch, url: string | URL, options?: {
+    init?: Omit<RequestInit, "signal">;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    schema?: z.ZodType<T>;
+    error?: typeof ConnectorError;
+}): Promise<T>;

package/dist/connector.js

@@ -0,0 +1,47 @@
+// What every connector's client shares: one timeout, one error, one fetch that a run's abort can cancel.
+/** No device or service call waits longer than this. */
+export const TIMEOUT_MS = 10_000;
+/**
+ * An error as a detail line: its message ("fetch failed", not "TypeError: fetch failed"), and its cause's when it has one.
+ * Node's fetch puts the reason there: "fetch failed: connect ECONNREFUSED 192.0.2.10:443".
+ */
+export function errorText(error) {
+    if (!(error instanceof Error))
+        return String(error);
+    const cause = error.cause instanceof Error ? error.cause.message : undefined;
+    return cause && cause !== error.message
+        ? `${error.message}: ${cause}`
+        : error.message;
+}
+/** A failed device or service call. `status` is the HTTP status (or a device's own code); `code` a connector's own reason. */
+export class ConnectorError extends Error {
+    status;
+    code;
+    constructor(message, options = {}) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = new.target.name; // a subclass (HueError, AmberError) names itself in logs; a detail shows only the message
+        this.status = options.status;
+        this.code = options.code;
+    }
+}
+/** `fetch` that gives up after `timeoutMs`, or as soon as `signal` (a run's) aborts. Returns the response whatever its status. */
+export function fetchTimeout(fetcher, url, init = {}, options = {}) {
+    const timeout = AbortSignal.timeout(options.timeoutMs ?? TIMEOUT_MS);
+    return fetcher(url, {
+        ...init,
+        signal: options.signal
+            ? AbortSignal.any([timeout, options.signal])
+            : timeout,
+    });
+}
+/**
+ * GET (or `init.method`) JSON through `fetchTimeout`. A non-ok status throws `error` (ConnectorError by default) with the
+ * status, as "HTTP 500 on GET /path" (no query: it can carry a key). With a `schema` the body is parsed by it.
+ */
+export async function getJson(fetcher, url, options = {}) {
+    const res = await fetchTimeout(fetcher, url, options.init, options);
+    if (!res.ok)
+        throw new (options.error ?? ConnectorError)(`HTTP ${res.status} on ${options.init?.method ?? "GET"} ${new URL(url).pathname}`, { status: res.status });
+    const body = await res.json();
+    return options.schema ? options.schema.parse(body) : body;
+}

package/dist/connectors/amber/client.d.ts

@@ -0,0 +1,61 @@
+import { z } from "zod";
+import { ConnectorError } from "../../connector.ts";
+/** A failed Amber call. `status` 401 means the key is wrong or revoked; 429 means the rate limit (50 per 5 min). */
+export declare class AmberError extends ConnectorError {
+}
+/** One 5-minute price interval on one channel. Prices are c/kWh including GST, as a cost: negative feed-in means you are paid. */
+export declare const Interval: z.ZodObject<{
+    type: z.ZodString;
+    channelType: z.ZodString;
+    perKwh: z.ZodNumber;
+    spotPerKwh: z.ZodOptional<z.ZodNumber>;
+    renewables: z.ZodOptional<z.ZodNumber>;
+    descriptor: z.ZodOptional<z.ZodString>;
+    spikeStatus: z.ZodOptional<z.ZodString>;
+    startTime: z.ZodOptional<z.ZodString>;
+    endTime: z.ZodOptional<z.ZodString>;
+    estimate: z.ZodOptional<z.ZodBoolean>;
+    duration: z.ZodOptional<z.ZodNumber>;
+}, z.core.$loose>;
+export type Interval = z.infer<typeof Interval>;
+/** Prices now, as a home view wants them: what a kWh costs to import and earns to export. */
+export type AmberState = {
+    importCents?: number;
+    exportCents?: number;
+    priceDescriptor?: string;
+    exportDescriptor?: string;
+    spike?: string;
+    renewables?: number;
+    estimate?: boolean;
+    nextImportCents?: number;
+    intervalEnds?: string;
+    anomaly?: string;
+    forecast?: PriceInterval[];
+};
+/**
+ * One interval of the forecast, both channels. `start` is the interval's own start: Amber's `startTime` is a second past
+ * it (07:15:01 for 07:15–07:20), so it is taken to the minute. `exportCents` is what you are paid, as in `AmberState`.
+ */
+export type PriceInterval = {
+    start: string;
+    end: string;
+    importCents?: number;
+    exportCents?: number;
+    renewables?: number;
+    descriptor?: string;
+};
+/** How many intervals to ask for: more than Amber forecasts (48 half-hours), so the reply is as far as Amber has one. */
+export declare const NEXT = 96;
+/** Map `prices/current?next=…` to the state: the CurrentInterval of each channel, the next import forecast, and the forecast. */
+export declare function toPrices(intervals: unknown): AmberState;
+/** A read-only client for Amber's API. The key comes in; nothing is stored. */
+export declare function amberClient(options: {
+    key: string;
+    fetch: typeof fetch;
+}): {
+    get: (path: string, signal?: AbortSignal) => Promise<unknown>;
+    /** The account's active site id (the first active one). */
+    siteId(signal?: AbortSignal): Promise<string>;
+    /** Prices now and the forecast for a site: one call, ~270 ms (measured with `next=1`, Bun 1.4.2). */
+    prices(siteId: string, signal?: AbortSignal): Promise<AmberState>;
+};

package/dist/connectors/amber/client.js

@@ -0,0 +1,106 @@
+import { z } from "zod";
+import { ConnectorError, getJson } from "../../connector.js";
+// Amber Electric's public API v1 (https://app.amber.com.au/developers; the published spec is 1.0, there is no v2). Shapes checked against live replies,
+// 2026-10-13; every field optional so a change degrades a reading rather than throwing.
+/** A failed Amber call. `status` 401 means the key is wrong or revoked; 429 means the rate limit (50 per 5 min). */
+export class AmberError extends ConnectorError {
+}
+/** One 5-minute price interval on one channel. Prices are c/kWh including GST, as a cost: negative feed-in means you are paid. */
+export const Interval = z.looseObject({
+    type: z.string(), // "ActualInterval" | "CurrentInterval" | "ForecastInterval"
+    channelType: z.string(), // "general" (import) | "feedIn" (export) | "controlledLoad"
+    perKwh: z.number(),
+    spotPerKwh: z.number().optional(),
+    renewables: z.number().optional(), // percent of the grid
+    descriptor: z.string().optional(), // "extremelyLow" … "spike"
+    spikeStatus: z.string().optional(), // "none" | "potential" | "spike"
+    startTime: z.string().optional(),
+    endTime: z.string().optional(),
+    estimate: z.boolean().optional(), // CurrentInterval: true until the interval's price is final
+    duration: z.number().optional(), // minutes: 5 for the current hour, 30 further out
+});
+const Site = z.looseObject({
+    id: z.string(),
+    status: z.string().optional(),
+    intervalLength: z.number().optional(),
+});
+/** How many intervals to ask for: more than Amber forecasts (48 half-hours), so the reply is as far as Amber has one. */
+export const NEXT = 96;
+/** Map `prices/current?next=…` to the state: the CurrentInterval of each channel, the next import forecast, and the forecast. */
+export function toPrices(intervals) {
+    const list = z.array(Interval).parse(intervals);
+    const pick = (type, channel) => list.find((i) => i.type === type && i.channelType === channel);
+    const buy = pick("CurrentInterval", "general");
+    const sell = pick("CurrentInterval", "feedIn");
+    return {
+        importCents: buy?.perKwh,
+        exportCents: sell === undefined ? undefined : -sell.perKwh,
+        priceDescriptor: buy?.descriptor,
+        exportDescriptor: sell?.descriptor,
+        spike: buy?.spikeStatus,
+        renewables: buy?.renewables,
+        estimate: buy?.estimate,
+        nextImportCents: pick("ForecastInterval", "general")?.perKwh,
+        intervalEnds: buy?.endTime,
+        ...forecastOf(list),
+    };
+}
+const MINUTE = 60_000;
+/**
+ * The current and forecast intervals, in time order, each channel's price on one row; none when Amber sent none. An interval
+ * whose times do not parse is left out and counted in `anomaly`, so one odd row never fails the prices.
+ */
+function forecastOf(list) {
+    const timed = list.filter((i) => i.type === "CurrentInterval" || i.type === "ForecastInterval");
+    const ahead = timed.filter((i) => Number.isFinite(Date.parse(i.startTime ?? "")) &&
+        Number.isFinite(Date.parse(i.endTime ?? "")));
+    const odd = timed.length - ahead.length;
+    const feedIn = new Map(ahead.filter((i) => i.channelType === "feedIn").map((i) => [i.endTime, i]));
+    const rows = ahead
+        .filter((i) => i.channelType === "general")
+        .map((i) => {
+        const sell = feedIn.get(i.endTime);
+        return {
+            start: new Date(Math.floor(Date.parse(i.startTime) / MINUTE) * MINUTE).toISOString(),
+            end: new Date(Date.parse(i.endTime)).toISOString(),
+            importCents: i.perKwh,
+            exportCents: sell === undefined ? undefined : -sell.perKwh,
+            renewables: i.renewables,
+            descriptor: i.descriptor,
+        };
+    })
+        .sort((a, b) => a.start.localeCompare(b.start));
+    return {
+        forecast: rows.length ? rows : undefined,
+        anomaly: odd
+            ? `${odd} price row(s) left out: their start or end time could not be read`
+            : undefined,
+    };
+}
+/** A read-only client for Amber's API. The key comes in; nothing is stored. */
+export function amberClient(options) {
+    const headers = {
+        authorization: `Bearer ${options.key}`,
+        accept: "application/json",
+    };
+    const get = (path, signal) => getJson(options.fetch, `https://api.amber.com.au/v1${path}`, {
+        init: { headers },
+        signal,
+        error: AmberError,
+    });
+    return {
+        get,
+        /** The account's active site id (the first active one). */
+        async siteId(signal) {
+            const sites = z.array(Site).parse(await get("/sites", signal));
+            const site = sites.find((s) => s.status === "active") ?? sites[0];
+            if (!site)
+                throw new AmberError("no Amber site on this account");
+            return site.id;
+        },
+        /** Prices now and the forecast for a site: one call, ~270 ms (measured with `next=1`, Bun 1.4.2). */
+        async prices(siteId, signal) {
+            return toPrices(await get(`/sites/${siteId}/prices/current?next=${NEXT}`, signal));
+        },
+    };
+}

package/dist/connectors/amber/index.d.ts

@@ -0,0 +1,30 @@
+import { type Clock } from "../../clock.ts";
+import { z } from "zod";
+import { type Integration } from "../../home.ts";
+import { type Manifest } from "../../manifest.ts";
+import { type AmberState } from "./client.ts";
+export { AmberError, type AmberState, amberClient, type Interval, type PriceInterval, } from "./client.ts";
+/** Poll every 60 s: prices move in 5-minute intervals and the current one is revised inside it; 5 calls in 5 min, limit 50. */
+export declare const POLL_MS = 60000;
+/** Amber in a home config: the key's env name, and the site when the account has more than one. */
+export declare const configSchema: z.ZodObject<{
+    connector: z.ZodLiteral<"amber">;
+    key: z.ZodString;
+    siteId: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+/** Amber settings for a home. `siteId` is looked up once when left out. */
+export type AmberConfig = {
+    key: string;
+    siteId?: string;
+    fetch: typeof fetch;
+    clock?: Clock;
+};
+/** What the snapshot holds: prices now and when they were read. */
+export type AmberSnapshot = AmberState & {
+    asOf: string;
+};
+/** Amber prices as a home integration: one read now, then every 60 s. */
+export declare function amber(config: AmberConfig): Integration<AmberSnapshot, "amber">;
+/** Amber's prices in a few words: "buy 40.9c low (estimate) · sell 35.3c · 7% renewables", with a spike and a negative price when there is one. */
+export declare function amberText(a: AmberState): string;
+export declare const manifest: Manifest<AmberSnapshot>;