@glasshome/sync-layer 0.1.12 → 0.1.14

package/dist/energy/prefs.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Energy Preferences Fetching
+ *
+ * Reads HA's energy dashboard config via `energy/get_prefs`.
+ *
+ * @packageDocumentation
+ */
+import type { SyncLayerConnection } from "../connection/types";
+/**
+ * An energy source entry. Only the fields the widgets read are typed; the
+ * rest is passthrough. HA emits one of several shapes keyed by `type`:
+ * - grid: `flow_from[].stat_energy_from`, `flow_to[].stat_energy_to`
+ * - solar: `stat_energy_from`
+ * - battery: `stat_energy_from`, `stat_energy_to`
+ */
+export interface EnergySource {
+    type: "grid" | "solar" | "battery" | "gas" | "water" | string;
+    stat_energy_from?: string;
+    stat_energy_to?: string;
+    flow_from?: Array<{
+        stat_energy_from: string;
+        [key: string]: unknown;
+    }>;
+    flow_to?: Array<{
+        stat_energy_to: string;
+        [key: string]: unknown;
+    }>;
+    [key: string]: unknown;
+}
+/** A device tracked on the energy dashboard. */
+export interface EnergyDeviceConsumption {
+    stat_consumption: string;
+    name?: string;
+    [key: string]: unknown;
+}
+/**
+ * HA energy dashboard preferences.
+ *
+ * Based on HA frontend: EnergyPreferences.
+ */
+export interface EnergyPreferences {
+    energy_sources: EnergySource[];
+    device_consumption: EnergyDeviceConsumption[];
+    [key: string]: unknown;
+}
+/** Connection surface used by energy prefs fetching. */
+type EnergyConnection = Pick<SyncLayerConnection, "sendMessagePromise">;
+/**
+ * Fetch the HA energy dashboard preferences.
+ *
+ * Returns `null` when no energy dashboard is configured (HA raises an error
+ * for `energy/get_prefs` in that case); callers treat `null` as "not
+ * configured".
+ */
+export declare function fetchEnergyPreferences(connection: EnergyConnection): Promise<EnergyPreferences | null>;
+export {};

package/dist/history/query.d.ts

@@ -7,6 +7,8 @@ export interface HistoryPoint {
     lastUpdated: number;
     lastChanged?: number;
 }
+/** Hard cap on retained points per entity timeline. */
+export declare const MAX_HISTORY_POINTS = 5760;
 /** Check if an entity has active history tracking. */
 export declare function isHistoryTracked(entityId: EntityId): boolean;
 /** Start tracking history for an entity. Fetches initial backfill. */

package/dist/history/statistics.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Long-term Statistics Fetching
+ *
+ * Reads HA's recorder long-term statistics via `recorder/statistics_during_period`.
+ *
+ * @packageDocumentation
+ */
+import type { SyncLayerConnection } from "../connection/types";
+/**
+ * A single statistics bucket for one statistic id.
+ *
+ * HA 2023.6+ omits columns that were not requested and may omit null
+ * columns, so every value field is optional. `start`/`end` are normalized
+ * to ms epoch numbers regardless of the version's wire format.
+ */
+export interface StatisticValue {
+    /** Bucket start (ms epoch) */
+    start: number;
+    /** Bucket end (ms epoch) */
+    end: number;
+    mean?: number;
+    sum?: number;
+    min?: number;
+    max?: number;
+    state?: number;
+    change?: number;
+}
+/** Aggregation period for statistics buckets. */
+export type StatisticsPeriod = "5minute" | "hour" | "day" | "week" | "month";
+/**
+ * Options for {@link fetchStatisticsDuringPeriod}.
+ */
+export interface StatisticsQueryOptions {
+    /** Start time (required) */
+    startTime: Date;
+    /** End time (optional, defaults to now on the HA side) */
+    endTime?: Date;
+    /** Aggregation period */
+    period: StatisticsPeriod;
+}
+/** Connection surface used by statistics fetching. */
+type StatisticsConnection = Pick<SyncLayerConnection, "sendMessagePromise">;
+/**
+ * HA returns start/end as ISO strings or ms numbers depending on version.
+ * Normalize both shapes to ms epoch numbers; unparseable values become NaN.
+ */
+export declare function normalizeStatisticTime(value: unknown): number;
+/**
+ * Fetch long-term statistics for one or more statistic ids during a period.
+ *
+ * Statistic ids with no data are returned as empty arrays so callers never
+ * hit `undefined`.
+ */
+export declare function fetchStatisticsDuringPeriod(connection: StatisticsConnection, statisticIds: string[], options: StatisticsQueryOptions): Promise<Record<string, StatisticValue[]>>;
+export {};

package/dist/index.d.ts

@@ -26,14 +26,18 @@ export { resetStore, setState, state } from "./core/store";
 export type { CallServiceRequest, CoreEventType, Domain, EntityCategory, EntityRegistryEntry, EventStateChangedData, HAEvent, RegistryEntryDisabler, RegistryEntryHider, ServiceCall, ServiceName, WsCommandType, WsResult, } from "@glasshome/ha-types";
 export { fetchStream, fetchStreamData } from "./camera/fetch";
 export { getStream, refreshStream } from "./camera/query";
+export { fetchEnergyPreferences } from "./energy/prefs";
+export type { EnergyDeviceConsumption, EnergyPreferences, EnergySource, } from "./energy/prefs";
 export type { CameraStream, CameraStreamData, CameraStreams, EntityStreamQueryOptions, StreamFormat, StreamQueryOptions, StreamResult, } from "./camera/types";
 export { getWebRtcClientConfig, sendWebRtcCandidate, startWebRtcSession, } from "./camera/webrtc";
 export { buildAreaView, buildDeviceView, getAreaView, getAreaViews, } from "./entities/area-views";
 export { buildEntityView, entityViewEquals, getAllEntityViews, getEntityView, getEntityViews, } from "./entities/views";
 export { DOMAINS_USE_LAST_UPDATED, entityIdHistoryNeedsAttributes, LINE_ATTRIBUTES_TO_KEEP, NEED_ATTRIBUTE_DOMAINS, } from "./history/constants";
 export { fetchEntityHistory, fetchHistory, historyStateToTimeline } from "./history/fetch";
-export { appendHistoryPoint, bulkAppendHistoryPoints, isHistoryTracked, trackEntityHistory, untrackEntityHistory, } from "./history/query";
+export { appendHistoryPoint, bulkAppendHistoryPoints, isHistoryTracked, MAX_HISTORY_POINTS, trackEntityHistory, untrackEntityHistory, } from "./history/query";
 export type { HistoryPoint } from "./history/query";
+export { fetchStatisticsDuringPeriod, normalizeStatisticTime, } from "./history/statistics";
+export type { StatisticsPeriod, StatisticsQueryOptions, StatisticValue, } from "./history/statistics";
 export type { EntityHistoryData, EntityHistoryQueryOptions, EntityHistoryResult, EntityHistoryState, HistoryData, HistoryQueryOptions, HistoryResult, HistoryStates, TimelineState, } from "./history/types";
 export { fetchForecast, fetchForecastData, fetchForecasts } from "./weather/fetch";
 export { getForecast, getForecasts, refreshForecast, refreshForecasts } from "./weather/query";

package/dist/index.js

@@ -807,6 +807,8 @@ function historyStateToTimeline(s) {
 
 //#endregion
 //#region src/history/query.ts
+/** Hard cap on retained points per entity timeline. */
+const MAX_HISTORY_POINTS = 5760;
 /** Set of entity IDs with active history tracking. */
 const trackedEntities = /* @__PURE__ */ new Set();
 /** Check if an entity has active history tracking. */
@@ -860,6 +862,7 @@ function appendHistoryPoint(entityId, stateValue, attributes, lastUpdated, lastC
 function bulkAppendHistoryPoints(points) {
 	if (points.length === 0) return;
 	setState(produce((s) => {
+		const touched = /* @__PURE__ */ new Set();
 		for (const { entityId, stateValue, attributes, lastUpdated, lastChanged } of points) {
 			const history = s.history[entityId];
 			if (!history) continue;
@@ -876,6 +879,13 @@ function bulkAppendHistoryPoints(points) {
 				lastChanged,
 				lastUpdated
 			});
+			touched.add(entityId);
+		}
+		for (const entityId of touched) {
+			const history = s.history[entityId];
+			if (!history) continue;
+			if (history.entityHistory.length > MAX_HISTORY_POINTS) history.entityHistory.splice(0, history.entityHistory.length - MAX_HISTORY_POINTS);
+			if (history.timeline.length > MAX_HISTORY_POINTS) history.timeline.splice(0, history.timeline.length - MAX_HISTORY_POINTS);
 		}
 	}));
 }
@@ -2164,6 +2174,35 @@ async function refreshStream(entityId, format = "hls") {
 	return getStream(entityId, { format });
 }
 
+//#endregion
+//#region src/energy/prefs.ts
+function isRecord(value) {
+	return typeof value === "object" && value !== null;
+}
+/**
+* Fetch the HA energy dashboard preferences.
+*
+* Returns `null` when no energy dashboard is configured (HA raises an error
+* for `energy/get_prefs` in that case); callers treat `null` as "not
+* configured".
+*/
+async function fetchEnergyPreferences(connection) {
+	let response;
+	try {
+		response = await connection.sendMessagePromise({ type: "energy/get_prefs" });
+	} catch {
+		return null;
+	}
+	if (!isRecord(response)) return null;
+	const sources = Array.isArray(response.energy_sources) ? response.energy_sources.filter(isRecord) : [];
+	const devices = Array.isArray(response.device_consumption) ? response.device_consumption.filter(isRecord) : [];
+	return {
+		...response,
+		energy_sources: sources,
+		device_consumption: devices
+	};
+}
+
 //#endregion
 //#region src/camera/webrtc.ts
 /**
@@ -2248,6 +2287,70 @@ async function sendWebRtcCandidate(entityId, sessionId, candidate) {
 	});
 }
 
+//#endregion
+//#region src/history/statistics.ts
+const STATISTIC_TYPES = [
+	"mean",
+	"sum",
+	"min",
+	"max",
+	"state",
+	"change"
+];
+/**
+* HA returns start/end as ISO strings or ms numbers depending on version.
+* Normalize both shapes to ms epoch numbers; unparseable values become NaN.
+*/
+function normalizeStatisticTime(value) {
+	if (typeof value === "number") return value;
+	if (typeof value === "string") return new Date(value).getTime();
+	return NaN;
+}
+function normalizeNumber(value) {
+	return typeof value === "number" ? value : void 0;
+}
+function normalizeStatisticValue(raw) {
+	const value = {
+		start: normalizeStatisticTime(raw.start),
+		end: normalizeStatisticTime(raw.end)
+	};
+	const mean = normalizeNumber(raw.mean);
+	if (mean !== void 0) value.mean = mean;
+	const sum = normalizeNumber(raw.sum);
+	if (sum !== void 0) value.sum = sum;
+	const min = normalizeNumber(raw.min);
+	if (min !== void 0) value.min = min;
+	const max = normalizeNumber(raw.max);
+	if (max !== void 0) value.max = max;
+	const stateVal = normalizeNumber(raw.state);
+	if (stateVal !== void 0) value.state = stateVal;
+	const change = normalizeNumber(raw.change);
+	if (change !== void 0) value.change = change;
+	return value;
+}
+/**
+* Fetch long-term statistics for one or more statistic ids during a period.
+*
+* Statistic ids with no data are returned as empty arrays so callers never
+* hit `undefined`.
+*/
+async function fetchStatisticsDuringPeriod(connection, statisticIds, options) {
+	const { startTime, endTime, period } = options;
+	const params = {
+		type: "recorder/statistics_during_period",
+		start_time: startTime.toISOString(),
+		statistic_ids: statisticIds,
+		period,
+		types: STATISTIC_TYPES
+	};
+	if (endTime) params.end_time = endTime.toISOString();
+	const response = await connection.sendMessagePromise(params);
+	const result = {};
+	for (const id of statisticIds) result[id] = [];
+	if (response && typeof response === "object") for (const [id, buckets] of Object.entries(response)) result[id] = Array.isArray(buckets) ? buckets.map(normalizeStatisticValue) : [];
+	return result;
+}
+
 //#endregion
 //#region src/weather/fetch.ts
 /**
@@ -2510,4 +2613,4 @@ async function refreshForecasts(entityId, types) {
 const VERSION = "0.1.0";
 
 //#endregion
-export { DOMAINS_USE_LAST_UPDATED, LINE_ATTRIBUTES_TO_KEEP, NEED_ATTRIBUTE_DOMAINS, VERSION, addDebugIncomingMessageListener, addDebugOutgoingMessageListener, appendHistoryPoint, applyDemoServiceCall, area, areas, authenticateWithOAuth, authenticateWithToken, batchEntityUpdates, batchServiceCalls, buildAreaView, buildDeviceView, buildEntityView, bulkAppendHistoryPoints, callService, createDemoFixtures, disconnect, entities, entitiesByAreaAndDomain, entitiesWhere, entity, entityIdHistoryNeedsAttributes, entityViewEquals, extractDomain, fetchEntityHistory, fetchForecast, fetchForecastData, fetchForecasts, fetchHistory, fetchStream, fetchStreamData, getAllEntityViews, getAreaView, getAreaViews, getConnection, getConnectionState, getEntityView, getEntityViews, getForecast, getForecasts, getStream, getWebRtcClientConfig, historyStateToTimeline, initConnection, isAuthValid, isConnected, isDemoMode, isHistoryTracked, loadDemoData, refreshAuth, refreshForecast, refreshForecasts, refreshStream, registerEntity, resetStore, searchEntities, sendCommand, sendWebRtcCandidate, setState, startWebRtcSession, state, toggle, trackEntityHistory, turnOff, turnOn, unloadDemoData, untrackEntityHistory, updateEntity };
+export { DOMAINS_USE_LAST_UPDATED, LINE_ATTRIBUTES_TO_KEEP, MAX_HISTORY_POINTS, NEED_ATTRIBUTE_DOMAINS, VERSION, addDebugIncomingMessageListener, addDebugOutgoingMessageListener, appendHistoryPoint, applyDemoServiceCall, area, areas, authenticateWithOAuth, authenticateWithToken, batchEntityUpdates, batchServiceCalls, buildAreaView, buildDeviceView, buildEntityView, bulkAppendHistoryPoints, callService, createDemoFixtures, disconnect, entities, entitiesByAreaAndDomain, entitiesWhere, entity, entityIdHistoryNeedsAttributes, entityViewEquals, extractDomain, fetchEnergyPreferences, fetchEntityHistory, fetchForecast, fetchForecastData, fetchForecasts, fetchHistory, fetchStatisticsDuringPeriod, fetchStream, fetchStreamData, getAllEntityViews, getAreaView, getAreaViews, getConnection, getConnectionState, getEntityView, getEntityViews, getForecast, getForecasts, getStream, getWebRtcClientConfig, historyStateToTimeline, initConnection, isAuthValid, isConnected, isDemoMode, isHistoryTracked, loadDemoData, normalizeStatisticTime, refreshAuth, refreshForecast, refreshForecasts, refreshStream, registerEntity, resetStore, searchEntities, sendCommand, sendWebRtcCandidate, setState, startWebRtcSession, state, toggle, trackEntityHistory, turnOff, turnOn, unloadDemoData, untrackEntityHistory, updateEntity };

package/dist/solid/hooks.d.ts

@@ -10,8 +10,8 @@
  *
  * @packageDocumentation
  */
-import type { Accessor } from "solid-js";
-import type { AreaView, CameraStreamData, ConnectionState, EntityHistoryData, EntityView, GlassHomeState, HassEntity, WeatherForecastsData } from "@glasshome/sync-layer";
+import type { Accessor, Resource } from "solid-js";
+import type { AreaView, CameraStreamData, ConnectionState, EntityHistoryData, EntityView, GlassHomeState, HassEntity, StatisticsQueryOptions, StatisticValue, WeatherForecastsData } from "@glasshome/sync-layer";
 import { callService, toggle, turnOff, turnOn } from "@glasshome/sync-layer";
 /**
  * Get a reactive EntityView for an entity ID.
@@ -71,6 +71,14 @@ export declare function useArea(areaId: Accessor<string> | string): Accessor<Are
  * this hook simply reads it reactively.
  */
 export declare function useEntityHistory(entityId: Accessor<string> | string): Accessor<EntityHistoryData | undefined>;
+/**
+ * Get reactive long-term statistics for a statistic id.
+ *
+ * Fetches via `recorder/statistics_during_period` and re-fetches whenever the
+ * statistic id or options change. The returned Resource exposes `.loading`
+ * and `.error` alongside the value accessor.
+ */
+export declare function useEntityStatistics(statisticId: Accessor<string> | string, options: Accessor<StatisticsQueryOptions> | StatisticsQueryOptions): Resource<StatisticValue[]>;
 /**
  * Get reactive camera stream data.
  */

package/dist/solid/index.d.ts

@@ -6,5 +6,5 @@
  *
  * @packageDocumentation
  */
-export { useArea, useAreas, useCamera, useConnection, useEntities, useEntity, useEntityHistory, useEntityState, useForecast, useService, useStore, useToggle, useTurnOff, useTurnOn, } from "./hooks";
+export { useArea, useAreas, useCamera, useConnection, useEntities, useEntity, useEntityHistory, useEntityState, useEntityStatistics, useForecast, useService, useStore, useToggle, useTurnOff, useTurnOn, } from "./hooks";
 export { allEntityIds, byArea, byDevice, byDomain, byFloor, byLabel, } from "./indices";

package/dist/solid/index.js

@@ -1,5 +1,5 @@
-import { createEffect, createMemo, onCleanup } from "solid-js";
-import { buildAreaView, callService, entityViewEquals, extractDomain, getEntityView, registerEntity, state, toggle, turnOff, turnOn } from "@glasshome/sync-layer";
+import { createEffect, createMemo, createResource, onCleanup } from "solid-js";
+import { buildAreaView, callService, entityViewEquals, extractDomain, fetchStatisticsDuringPeriod, getEntityView, registerEntity, state, toggle, turnOff, turnOn } from "@glasshome/sync-layer";
 
 //#region src/solid/hooks.ts
 /**
@@ -152,6 +152,28 @@ function useEntityHistory(entityId) {
 	return createMemo(() => state.history[getId()]);
 }
 /**
+* Get reactive long-term statistics for a statistic id.
+*
+* Fetches via `recorder/statistics_during_period` and re-fetches whenever the
+* statistic id or options change. The returned Resource exposes `.loading`
+* and `.error` alongside the value accessor.
+*/
+function useEntityStatistics(statisticId, options) {
+	const getId = typeof statisticId === "function" ? statisticId : () => statisticId;
+	const getOptions = typeof options === "function" ? options : () => options;
+	const [data] = createResource(() => ({
+		id: getId(),
+		options: getOptions()
+	}), async ({ id, options: opts }) => {
+		if (!id) return [];
+		const conn = state.conn;
+		if (!conn) return [];
+		const result = await fetchStatisticsDuringPeriod(conn, [id], opts);
+		return result[id] ?? [];
+	});
+	return data;
+}
+/**
 * Get reactive camera stream data.
 */
 function useCamera(entityId) {
@@ -179,9 +201,6 @@ function useStore(selector) {
 
 //#endregion
 //#region src/solid/indices.ts
-/**
-* Group items by a key function
-*/
 function groupBy(items, keyFn) {
 	const result = {};
 	for (const item of items) {
@@ -190,26 +209,14 @@ function groupBy(items, keyFn) {
 	}
 	return result;
 }
-/**
-* Create a lazily-initialized memo. The actual createMemo runs on first
-* access, inside whichever Solid root is current at that point.
-* This avoids top-level createMemo calls that execute outside any root.
-*/
-function lazyMemo(fn) {
-	let memo;
-	return () => {
-		if (!memo) memo = createMemo(fn);
-		return memo();
-	};
-}
 /** Entity IDs grouped by domain (e.g., "light" -> ["light.living_room", ...]) */
-const byDomain = lazyMemo(() => groupBy(Object.keys(state.entities), (id) => extractDomain(id)));
+const byDomain = () => groupBy(Object.keys(state.entities), (id) => extractDomain(id));
 /** Entity IDs grouped by area (via entity registry area_id) */
-const byArea = lazyMemo(() => groupBy(Object.keys(state.entityRegistry), (id) => state.entityRegistry[id]?.area_id ?? null));
+const byArea = () => groupBy(Object.keys(state.entityRegistry), (id) => state.entityRegistry[id]?.area_id ?? null);
 /** Entity IDs grouped by device (via entity registry device_id) */
-const byDevice = lazyMemo(() => groupBy(Object.keys(state.entityRegistry), (id) => state.entityRegistry[id]?.device_id ?? null));
+const byDevice = () => groupBy(Object.keys(state.entityRegistry), (id) => state.entityRegistry[id]?.device_id ?? null);
 /** Entity IDs grouped by floor (device -> area -> floor chain) */
-const byFloor = lazyMemo(() => {
+const byFloor = () => {
 	const result = {};
 	for (const [entityId, reg] of Object.entries(state.entityRegistry)) if (reg.device_id) {
 		const device = state.devices[reg.device_id];
@@ -219,15 +226,15 @@ const byFloor = lazyMemo(() => {
 		}
 	}
 	return result;
-});
+};
 /** Entity IDs grouped by label */
-const byLabel = lazyMemo(() => {
+const byLabel = () => {
 	const result = {};
 	for (const [entityId, reg] of Object.entries(state.entityRegistry)) for (const label of reg.labels ?? []) (result[label] ??= []).push(entityId);
 	return result;
-});
+};
 /** All entity IDs currently in the store */
-const allEntityIds = lazyMemo(() => Object.keys(state.entities));
+const allEntityIds = () => Object.keys(state.entities);
 
 //#endregion
-export { allEntityIds, byArea, byDevice, byDomain, byFloor, byLabel, useArea, useAreas, useCamera, useConnection, useEntities, useEntity, useEntityHistory, useEntityState, useForecast, useService, useStore, useToggle, useTurnOff, useTurnOn };
+export { allEntityIds, byArea, byDevice, byDomain, byFloor, byLabel, useArea, useAreas, useCamera, useConnection, useEntities, useEntity, useEntityHistory, useEntityState, useEntityStatistics, useForecast, useService, useStore, useToggle, useTurnOff, useTurnOn };

package/dist/solid/indices.d.ts

@@ -1,4 +1,5 @@
-/** Reactive derived entity indices — lazily created inside the caller's root. */
+/** Reactive derived entity indices. Each call reads from the SolidJS store directly,
+ * so consumers wrap in createMemo within their own reactive root for memoization. */
 import type { Accessor } from "solid-js";
 /** Entity IDs grouped by domain (e.g., "light" -> ["light.living_room", ...]) */
 export declare const byDomain: Accessor<Record<string, string[]>>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glasshome/sync-layer",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "description": "Type-safe, reactive state synchronization layer for Home Assistant",
   "repository": {
     "type": "git",