@khalido/home 0.0.0-stage → 0.1.1

package/dist/connectors/weather/google.js

@@ -0,0 +1,364 @@
+import { z } from "zod";
+import { getJson } from "../../connector.js";
+import { RAIN_INTENSITIES } from "./rain.js";
+import { sunDisagrees } from "./sun.js";
+import { HOURLY_MINUTES, iso, nextPoll, num, RAIN_HORIZON_MINUTES, USER_AGENT, } from "./source.js";
+// Google's Weather API (Maps Platform, https://developers.google.com/maps/documentation/weather): needs a key with
+// billing. Built from the docs' example responses, checked live against Sydney on 2026-10-13. Every slice is a model.
+export const BASE = "https://weather.googleapis.com/v1";
+const Temp = z
+    .looseObject({ degrees: z.number().optional(), unit: z.string().optional() })
+    .optional();
+const Speed = z
+    .looseObject({ value: z.number().optional(), unit: z.string().optional() })
+    .optional();
+const Condition = z
+    .looseObject({
+    description: z.looseObject({ text: z.string().optional() }).optional(),
+    type: z.string().optional(),
+})
+    .optional();
+const Precipitation = z
+    .looseObject({
+    probability: z.looseObject({ percent: z.number().optional() }).optional(),
+    qpf: z
+        .looseObject({
+        quantity: z.number().optional(),
+        unit: z.string().optional(),
+    })
+        .optional(),
+})
+    .optional();
+const Interval = z
+    .looseObject({
+    startTime: z.string().optional(),
+    endTime: z.string().optional(),
+})
+    .optional();
+const Current = z.looseObject({
+    currentTime: z.string().optional(),
+    weatherCondition: Condition,
+    temperature: Temp,
+    feelsLikeTemperature: Temp,
+    relativeHumidity: z.number().optional(),
+    uvIndex: z.number().optional(),
+    cloudCover: z.number().optional(),
+    wind: z
+        .looseObject({
+        direction: z
+            .looseObject({
+            degrees: z.number().optional(),
+            cardinal: z.string().optional(),
+        })
+            .optional(),
+        speed: Speed,
+        gust: Speed,
+    })
+        .optional(),
+});
+const Half = z
+    .looseObject({ weatherCondition: Condition, precipitation: Precipitation })
+    .optional();
+const Days = z.looseObject({
+    forecastDays: z
+        .array(z.looseObject({
+        interval: Interval,
+        displayDate: z
+            .looseObject({ year: z.number(), month: z.number(), day: z.number() })
+            .optional(),
+        daytimeForecast: Half,
+        nighttimeForecast: Half,
+        maxTemperature: Temp,
+        minTemperature: Temp,
+        sunEvents: z
+            .looseObject({
+            sunriseTime: z.string().optional(),
+            sunsetTime: z.string().optional(),
+        })
+            .optional(),
+    }))
+        .optional(),
+});
+const Hours = z.looseObject({
+    forecastHours: z
+        .array(z.looseObject({
+        interval: Interval,
+        uvIndex: z.number().optional(),
+        cloudCover: z.number().optional(),
+    }))
+        .optional(),
+});
+const Minutes = z.looseObject({
+    overallPredictionTimeframe: Interval,
+    segments: z
+        .array(z.looseObject({
+        timeFrame: Interval,
+        type: z.string().optional(),
+        probability: z.number().optional(),
+        qpf: z
+            .looseObject({
+            quantity: z.number().optional(),
+            unit: z.string().optional(),
+        })
+            .optional(),
+        intensity: z.string().optional(),
+    }))
+        .optional(),
+});
+/** Celsius, or undefined plus a note: the requests ask for METRIC, so another unit is a surprise worth seeing. */
+const celsius = (t, what, odd) => {
+    if (t?.unit && t.unit !== "CELSIUS")
+        odd.push(`${what} in ${t.unit}`);
+    return t?.unit === "CELSIUS" || t?.unit === undefined
+        ? num(t?.degrees, what, odd)
+        : undefined;
+};
+const kmh = (s, what, odd) => {
+    if (s?.unit && s.unit !== "KILOMETERS_PER_HOUR")
+        odd.push(`${what} in ${s.unit}`);
+    return s?.unit === "KILOMETERS_PER_HOUR" || s?.unit === undefined
+        ? num(s?.value, what, odd)
+        : undefined;
+};
+const contains = (i, at) => Date.parse(i?.startTime ?? "") <= at && at < Date.parse(i?.endTime ?? "");
+/**
+ * Map the three responses to slices. A day's rain chance is the higher of its day and night halves; its amount is their sum.
+ * With `place`, each day's `sunEvents` are checked against the computed sun (the owner); one more than 2 minutes out is an anomaly.
+ */
+export function toSlices(current, days, hours, fetchedAt, forecastAt = fetchedAt, place) {
+    const odd = [];
+    const c = Current.parse(current);
+    const meta = (at) => ({
+        source: "google",
+        modelled: true,
+        at,
+        fetchedAt: new Date(fetchedAt).toISOString(),
+    });
+    const at = iso(c.currentTime);
+    if (c.currentTime !== undefined && !at)
+        odd.push(`currentTime not understood: ${c.currentTime}`);
+    const now = at
+        ? {
+            ...meta(at),
+            tempC: celsius(c.temperature, "temperature", odd),
+            apparentC: celsius(c.feelsLikeTemperature, "feels like", odd),
+            humidity: c.relativeHumidity,
+            windKmh: kmh(c.wind?.speed, "wind", odd),
+            windDir: c.wind?.direction?.cardinal,
+            windDeg: c.wind?.direction?.degrees,
+            gustKmh: kmh(c.wind?.gust, "gust", odd),
+        }
+        : undefined;
+    const hourly = (Hours.parse(hours).forecastHours ?? []).flatMap((h) => {
+        const at = iso(h.interval?.startTime);
+        if (!at)
+            odd.push(`forecast hour time not understood: ${h.interval?.startTime}`);
+        return at ? [{ at, cloudPct: h.cloudCover, uvIndex: h.uvIndex }] : [];
+    });
+    const sky = at
+        ? { ...meta(at), cloudPct: c.cloudCover, uvIndex: c.uvIndex, hours: hourly }
+        : undefined;
+    const list = Days.parse(days).forecastDays ?? [];
+    if (place)
+        for (const d of list) {
+            const off = sunDisagrees("google", place.latitude, place.longitude, {
+                sunrise: d.sunEvents?.sunriseTime,
+                sunset: d.sunEvents?.sunsetTime,
+            });
+            if (off)
+                odd.push(off);
+        }
+    const i = list.findIndex((d) => contains(d.interval, fetchedAt));
+    const day = (d) => {
+        if (!d?.displayDate)
+            return undefined;
+        const { year, month, day: dd } = d.displayDate;
+        const chances = [d.daytimeForecast, d.nighttimeForecast]
+            .map((h) => h?.precipitation?.probability?.percent)
+            .filter((p) => p !== undefined);
+        const amounts = [d.daytimeForecast, d.nighttimeForecast].map((h) => h?.precipitation?.qpf);
+        for (const q of amounts)
+            if (q?.unit && q.unit !== "MILLIMETERS")
+                odd.push(`rain in ${q.unit}`);
+        const mm = amounts.every((q) => q?.quantity !== undefined &&
+            (q.unit ?? "MILLIMETERS") === "MILLIMETERS")
+            ? amounts.reduce((s, q) => s + q.quantity, 0)
+            : undefined;
+        return {
+            date: `${year}-${String(month).padStart(2, "0")}-${String(dd).padStart(2, "0")}`,
+            minC: celsius(d.minTemperature, "minimum", odd),
+            maxC: celsius(d.maxTemperature, "maximum", odd),
+            rainChance: chances.length ? Math.max(...chances) : undefined,
+            rainMm: mm,
+            text: d.daytimeForecast?.weatherCondition?.description?.text,
+            code: d.daytimeForecast?.weatherCondition?.type,
+        };
+    };
+    const forecastIso = new Date(forecastAt).toISOString();
+    const forecast = list.length
+        ? {
+            ...meta(forecastIso),
+            fetchedAt: forecastIso,
+            today: i < 0 ? undefined : day(list[i]),
+            tomorrow: i < 0 ? undefined : day(list[i + 1]),
+        }
+        : undefined;
+    return {
+        now,
+        forecast,
+        sky,
+        anomaly: odd.length ? odd.join("; ") : undefined,
+    };
+}
+/**
+ * The minute forecast as a `rain` slice: the segments that start within `RAIN_HORIZON_MINUTES` of `fetchedAt`. A segment with an odd time is
+ * skipped and noted; a rain amount in a unit other than millimetres is left out and noted, never converted.
+ */
+export function toRain(minutes, fetchedAt) {
+    const odd = [];
+    const parsed = Minutes.safeParse(minutes);
+    if (!parsed.success)
+        return {
+            anomaly: "minute forecast not understood: the response is not the documented shape",
+        };
+    const m = parsed.data;
+    const at = iso(m.overallPredictionTimeframe?.startTime);
+    if (!at)
+        odd.push(`minute forecast has no start time: ${m.overallPredictionTimeframe?.startTime}`);
+    const limit = fetchedAt + RAIN_HORIZON_MINUTES * 60_000;
+    const segments = (m.segments ?? []).flatMap((s) => {
+        const from = iso(s.timeFrame?.startTime);
+        const to = iso(s.timeFrame?.endTime);
+        if (!from || !to) {
+            odd.push(`minute forecast segment time not understood: ${s.timeFrame?.startTime}`);
+            return [];
+        }
+        if (Date.parse(from) >= limit)
+            return [];
+        if (s.qpf?.unit && s.qpf.unit !== "MILLIMETERS")
+            odd.push(`rain in ${s.qpf.unit}`);
+        if (s.intensity && !RAIN_INTENSITIES.includes(s.intensity))
+            odd.push(`rain intensity not understood: ${s.intensity}`);
+        const mm = s.qpf?.unit === undefined || s.qpf.unit === "MILLIMETERS"
+            ? num(s.qpf?.quantity, "rain amount", odd)
+            : undefined;
+        return [
+            {
+                from,
+                to,
+                type: s.type,
+                chance: s.probability,
+                mm,
+                intensity: s.intensity,
+            },
+        ];
+    });
+    const anomaly = odd.length ? odd.join("; ") : undefined;
+    if (!at || !segments.length)
+        return { anomaly };
+    return {
+        rain: {
+            source: "google",
+            modelled: true,
+            at,
+            fetchedAt: new Date(fetchedAt).toISOString(),
+            segments,
+        },
+        anomaly,
+    };
+}
+/**
+ * The shortest interval Google is read at: the minute forecast moves in 15-minute segments. Billed per call, 10,000 free a month across the key:
+ * rain every 15 minutes, current conditions every 30 (`CURRENT_MINUTES`), the day and hour forecasts hourly: 192 calls a day, about 5,900 a month.
+ */
+export const MIN_POLL_MINUTES = 15;
+export const CURRENT_MINUTES = 30;
+/**
+ * Google Weather as a source: modelled `now`, `forecast` (10 days available, 2 read), `sky` without radiation, and `rain` from the
+ * minute forecast (Experimental at Google, so its failure is a `problem` on `rain` and never stops the other slices).
+ */
+export function google(options) {
+    const fetcher = options.fetch ?? fetch;
+    const base = options.base ?? BASE;
+    let slices = {};
+    let rain;
+    let forecasts;
+    let forecastsDue = 0;
+    let slowDue = 0;
+    return {
+        name: "google",
+        owns: {
+            now: 30 * 60_000,
+            forecast: 6 * 3_600_000,
+            sky: 30 * 60_000,
+            rain: 15 * 60_000,
+        },
+        minPollMinutes: MIN_POLL_MINUTES,
+        async read({ place, at, pollMinutes, force, signal, }) {
+            const q = (extra) => `key=${encodeURIComponent(options.key)}&location.latitude=${place.latitude}&location.longitude=${place.longitude}${extra}`;
+            const json = (path) => getJson(fetcher, `${base}/${path}`, {
+                init: { headers: { "user-agent": USER_AGENT } },
+                signal,
+            });
+            // Started first and never throws: a failed minute forecast must not sink the rest.
+            const minutes = json(`forecast/minutes:lookup?${q("")}`).then((value) => ({ value }), (error) => ({ error: error }));
+            let problem;
+            let failed = false;
+            try {
+                if (force || at >= slowDue) {
+                    const both = force || !forecasts || at >= forecastsDue;
+                    const [current, days, hours] = await Promise.all([
+                        json(`currentConditions:lookup?${q("")}`),
+                        both
+                            ? json(`forecast/days:lookup?${q("&days=2")}`)
+                            : forecasts.days,
+                        both
+                            ? json(`forecast/hours:lookup?${q("&hours=6")}`)
+                            : forecasts.hours,
+                    ]);
+                    if (both)
+                        ((forecasts = { days, hours, at }),
+                            (forecastsDue = nextPoll(at, HOURLY_MINUTES)));
+                    slices = toSlices(current, days, hours, at, forecasts.at, place);
+                    slowDue = nextPoll(at, Math.max(pollMinutes, CURRENT_MINUTES));
+                }
+            }
+            catch (error) {
+                const status = error.status;
+                if (status === 400 || status === 401 || status === 403)
+                    return {
+                        stop: `google: key rejected or request refused (HTTP ${status})`,
+                        nextAt: Infinity,
+                    };
+                problem = `google: ${error.message}`; // the old slices stay; the minute forecast below is still used
+                failed = true;
+            }
+            const m = await minutes;
+            let rainOdd;
+            if ("error" in m)
+                problem = [problem, `google minute forecast: ${m.error.message}`]
+                    .filter(Boolean)
+                    .join("; ");
+            else {
+                const r = toRain(m.value, at);
+                rainOdd = r.anomaly;
+                if (r.rain)
+                    rain = r.rain;
+                else
+                    problem = [problem, "google minute forecast: no segments"]
+                        .filter(Boolean)
+                        .join("; ");
+            }
+            const anomaly = [failed ? undefined : slices.anomaly, rainOdd]
+                .filter(Boolean)
+                .join("; ") || undefined;
+            return {
+                ...slices,
+                rain,
+                anomaly,
+                problem,
+                nextAt: nextPoll(at, pollMinutes),
+            };
+        },
+    };
+}

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

@@ -0,0 +1,53 @@
+import { type Clock } from "../../clock.ts";
+import type { Integration } from "../../home.ts";
+import { type Manifest } from "../../manifest.ts";
+import { type BlockDef, type DayBlocks } from "./blocks.ts";
+import { type RainSoon } from "./rain.ts";
+import { type Slices, type WeatherSource } from "./source.ts";
+import { type SunNow } from "./sun.ts";
+export { type Condition, type ForecastDay, type ForecastHour, mergeWeather, nextPoll, type Place, type RainSegment, type ReadRequest, type SkyHour, type SliceMeta, type Slices, type SourceReading, type WeatherForecast, type WeatherHourly, type WeatherNow, type WeatherRain, type WeatherSky, type WeatherSource, } from "./source.ts";
+export { type SunNext, type SunNow, sunNow } from "./sun.ts";
+export { type RainSoon, rainSoon } from "./rain.ts";
+export { type BlockDef, BLOCKS, blockText, type DayBlock, type DayBlocks, dayBlocks, } from "./blocks.ts";
+export { bom, type BomOptions } from "./bom.ts";
+export { openMeteo, type OpenMeteoOptions } from "./open-meteo.ts";
+export { google, type GoogleOptions } from "./google.ts";
+/**
+ * Where the home is, and the sources in preference order: each slice comes from the first source with a fresh one.
+ * The default is `[openMeteo()]`, which works anywhere with no key. In Australia put `bom({ fetch: ftpFetch(), forecastLocation })`
+ * first: it needs the FTP transport, so it is opt-in. `pollMinutes` (default 15) is how often observations and sky are read;
+ * forecasts follow their issue times. `timeZone` (IANA, the runtime's when left out) is where the home's day and its times are.
+ * `blocks` are the parts of the day `state.blocks` is cut into (`BLOCKS` by default).
+ */
+export type WeatherConfig = {
+    latitude: number;
+    longitude: number;
+    sources?: WeatherSource[];
+    pollMinutes?: number;
+    timeZone?: string;
+    blocks?: readonly BlockDef[];
+    clock?: Clock;
+};
+/** The weather in the snapshot: one slice each from the preferred fresh source, the sun, and how each source is doing. */
+export type WeatherState = Slices & {
+    sun: SunNow;
+    rainSoon?: RainSoon;
+    blocks?: DayBlocks;
+    timeZone?: string;
+    sources: Record<string, {
+        read: boolean;
+        problem?: string;
+        stopped?: string;
+        anomaly?: string;
+    }>;
+};
+/** Outside weather as a home integration. Each source polls on its own cadence; the sun is computed, never fetched. */
+export declare function weather(config: WeatherConfig): Integration<WeatherState, "weather">;
+/** "rain in 30 min, ends in 55 min, 70%, 0.8 mm, moderate (google)", "raining, ends in 25 min", or "no rain for 2 h"; nothing when the forecast covers none of the window. */
+export declare function rainText(rain: Slices["rain"], r: RainSoon | undefined): string;
+/** The weather in one line, every part named by its source and time, never mixed. */
+export declare function weatherText(w: Slices & {
+    rainSoon?: RainSoon;
+    timeZone?: string;
+}, sun: SunNow): string;
+export declare const manifest: Manifest<WeatherState>;