@enyo-energy/energy-app-sdk 1.47.0 → 1.49.0

package/README.md

@@ -411,6 +411,7 @@ Energy Apps use a granular permissions system to control access to system resour
 - **`Subscriptions`**: Read the subscriptions bought for the app on this device
 - **`Room`**: Read the rooms of the home the customer set up in the enyo app
 - **`RoomTemperatures`**: Read the current and past temperatures measured in those rooms
+- **`TimeseriesStore`**: Store the app's own number and text timeseries and query them raw or aggregated
 
 #### Site & Identity Permissions
 
@@ -2461,6 +2462,42 @@ Notes worth respecting when producing a report:
 
 Requires the `Savings` permission.
 
+#### `useTimeseriesStore(): EnergyAppTimeseriesStore`
+
+Store your app's own timeseries — numbers (temperatures, internal registers, learned parameters) and text (states, modes, error codes) — and query them back. Use it for anything that is not already on the data bus (`useTimeseries()` covers that) and that changes over time (`useStorage()` rewrites a whole object per key and is the wrong fit).
+
+- **Define once.** `defineSeries({name, valueType, unit?, retentionDays?})` is idempotent, so call it on every start. The `valueType` (`Number` or `Text`) is fixed so the host can store numbers compressed and text deduplicated. Series belong to your package only.
+- **Write in batches.** `write(points)` takes up to 1000 points across several series. A point is identified by series, tags and timestamp, so writing it again overwrites it and retries are safe. Invalid points come back in `rejected`, and the rest of the batch is stored. For values that arrive one at a time, use `TimeseriesStoreWriteBuffer`: it stamps each point when added, writes in batches on size or on an interval, keeps points across failed writes, and flushes on `dispose()`.
+- **Tags are for a few fixed dimensions** (`{phase: 'L1'}`, `{circuit: '2'}`), at most 8 per point. Every combination is its own stream, so never put changing values into tags.
+- **Query.**
+  - `queryPoints({series, fromIso, untilIso, tags?, order?, limit?, cursor?})` returns raw points page by page.
+  - `queryAggregated({series, fromIso, untilIso, resolution, aggregations, tags?, groupByTags?})` returns host-side buckets (`'1m'` to `'1d'`, UTC-aligned) with `avg`/`min`/`max`/`sum` (number series only) and `count`/`first`/`last`. Only non-empty buckets are returned.
+  - `getLatest(series, tags?)` returns the newest point per stream, e.g. to restore state after a restart.
+- **Clean up.** The host drops points after the retention. `deletePoints({series, fromIso, untilIso, tags?})` removes a range, and `deleteSeries(name)` removes everything.
+
+```typescript
+const store = energyApp.useTimeseriesStore();
+await store.defineSeries({name: 'compressor.temperature', valueType: EnyoTimeseriesStoreValueTypeEnum.Number, unit: '°C', retentionDays: 90});
+await store.defineSeries({name: 'compressor.state', valueType: EnyoTimeseriesStoreValueTypeEnum.Text});
+
+const buffer = new TimeseriesStoreWriteBuffer({store, interval: energyApp.useInterval(), flushInterval: '30s'});
+energyApp.onShutdown(() => buffer.dispose());
+
+buffer.add({series: 'compressor.temperature', value: 61.5, tags: {circuit: '1'}});
+buffer.add({series: 'compressor.state', value: 'defrost'});
+
+const hourly = await store.queryAggregated({
+    series: 'compressor.temperature',
+    fromIso: '2026-11-01T00:00:00Z',
+    untilIso: '2026-11-02T00:00:00Z',
+    resolution: '1h',
+    aggregations: [EnyoTimeseriesStoreAggregationEnum.Avg, EnyoTimeseriesStoreAggregationEnum.Max],
+    groupByTags: ['circuit'],
+});
+```
+
+Validate during development with `validateTimeseriesStoreSeriesDefinition`, `validateTimeseriesStorePoints` and `validateTimeseriesStoreAggregatedQuery`. Requires the `TimeseriesStore` permission.
+
 #### `useCommandLog(): EnergyAppCommandLog`
 
 Record which register, configuration key or message your app wrote to an appliance — and read those

package/dist/cjs/energy-app-permission.type.cjs

@@ -71,4 +71,5 @@ var EnergyAppPermissionTypeEnum;
     EnergyAppPermissionTypeEnum["Subscriptions"] = "Subscriptions";
     EnergyAppPermissionTypeEnum["Room"] = "Room";
     EnergyAppPermissionTypeEnum["RoomTemperatures"] = "RoomTemperatures";
+    EnergyAppPermissionTypeEnum["TimeseriesStore"] = "TimeseriesStore";
 })(EnergyAppPermissionTypeEnum || (exports.EnergyAppPermissionTypeEnum = EnergyAppPermissionTypeEnum = {}));

package/dist/cjs/energy-app-permission.type.d.cts

@@ -66,7 +66,8 @@ export declare enum EnergyAppPermissionTypeEnum {
     Webhook = "Webhook",
     Subscriptions = "Subscriptions",
     Room = "Room",
-    RoomTemperatures = "RoomTemperatures"
+    RoomTemperatures = "RoomTemperatures",
+    TimeseriesStore = "TimeseriesStore"
 }
 /**
  * String union of every permission name, derived from

package/dist/cjs/energy-app.cjs

@@ -578,6 +578,21 @@ class EnergyApp {
     useRoomTemperatures() {
         return this.energyAppSdk.useRoomTemperatures();
     }
+    /**
+     * Gets the Timeseries Store API for storing the app's own timeseries —
+     * numbers and text — and querying them back raw or aggregated by the host.
+     *
+     * Define each series once with `defineSeries()`, write points in batches
+     * with `write()` (or through a `TimeseriesStoreWriteBuffer`), and read them
+     * with `queryPoints()`, `queryAggregated()` or `getLatest()`. Every series
+     * belongs to this package; the host drops points after the series' retention.
+     * @returns The Timeseries Store API instance
+     * @throws {EnergyAppPermissionNotGrantedError} If the `TimeseriesStore`
+     *         permission is not granted.
+     */
+    useTimeseriesStore() {
+        return this.energyAppSdk.useTimeseriesStore();
+    }
     /**
      * Gets the current SDK version.
      * @returns The semantic version string of the SDK

package/dist/cjs/energy-app.d.cts

@@ -55,6 +55,7 @@ import { EnergyAppWebhook } from "./packages/energy-app-webhook.cjs";
 import { EnergyAppSubscriptions } from "./packages/energy-app-subscriptions.cjs";
 import { EnergyAppRoom } from "./packages/energy-app-room.cjs";
 import { EnergyAppRoomTemperatures } from "./packages/energy-app-room-temperatures.cjs";
+import { EnergyAppTimeseriesStore } from "./packages/energy-app-timeseries-store.cjs";
 import { UseFetchOptions } from "./types/enyo-fetch.cjs";
 /**
  * Concrete implementation of {@link EnyoEnergyAppSdk} that delegates every call
@@ -493,6 +494,19 @@ export declare class EnergyApp implements EnyoEnergyAppSdk {
      *         permission is not granted.
      */
     useRoomTemperatures(): EnergyAppRoomTemperatures;
+    /**
+     * Gets the Timeseries Store API for storing the app's own timeseries —
+     * numbers and text — and querying them back raw or aggregated by the host.
+     *
+     * Define each series once with `defineSeries()`, write points in batches
+     * with `write()` (or through a `TimeseriesStoreWriteBuffer`), and read them
+     * with `queryPoints()`, `queryAggregated()` or `getLatest()`. Every series
+     * belongs to this package; the host drops points after the series' retention.
+     * @returns The Timeseries Store API instance
+     * @throws {EnergyAppPermissionNotGrantedError} If the `TimeseriesStore`
+     *         permission is not granted.
+     */
+    useTimeseriesStore(): EnergyAppTimeseriesStore;
     /**
      * Gets the current SDK version.
      * @returns The semantic version string of the SDK

package/dist/cjs/enyo-energy-app-sdk.d.cts

@@ -54,6 +54,7 @@ import { EnergyAppWebhook } from "./packages/energy-app-webhook.cjs";
 import { EnergyAppSubscriptions } from "./packages/energy-app-subscriptions.cjs";
 import { EnergyAppRoom } from "./packages/energy-app-room.cjs";
 import { EnergyAppRoomTemperatures } from "./packages/energy-app-room-temperatures.cjs";
+import { EnergyAppTimeseriesStore } from "./packages/energy-app-timeseries-store.cjs";
 import { UseFetchOptions } from "./types/enyo-fetch.cjs";
 export declare enum EnergyAppStateEnum {
     Launching = "launching",
@@ -204,4 +205,6 @@ export interface EnyoEnergyAppSdk {
     useRoom: () => EnergyAppRoom;
     /** Get the Room Temperatures API for reading the current and past temperatures measured in the rooms of the home */
     useRoomTemperatures: () => EnergyAppRoomTemperatures;
+    /** Get the Timeseries Store API for storing the app's own number and text timeseries and querying them raw or aggregated */
+    useTimeseriesStore: () => EnergyAppTimeseriesStore;
 }

package/dist/cjs/implementations/timeseries-store/timeseries-store-validators.cjs

@@ -0,0 +1,160 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isValidTimeseriesStoreName = isValidTimeseriesStoreName;
+exports.validateTimeseriesStoreSeriesDefinition = validateTimeseriesStoreSeriesDefinition;
+exports.validateTimeseriesStorePoint = validateTimeseriesStorePoint;
+exports.validateTimeseriesStorePoints = validateTimeseriesStorePoints;
+exports.validateTimeseriesStoreAggregatedQuery = validateTimeseriesStoreAggregatedQuery;
+const enyo_timeseries_store_js_1 = require("../../types/enyo-timeseries-store.cjs");
+/** Allowed series names and tag keys: letters, digits, `.`, `_`, `-`, starting with a letter or digit. */
+const NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+/** Aggregations that need numbers and are therefore invalid on a text series. */
+const NUMERIC_AGGREGATIONS = new Set([
+    enyo_timeseries_store_js_1.EnyoTimeseriesStoreAggregationEnum.Avg,
+    enyo_timeseries_store_js_1.EnyoTimeseriesStoreAggregationEnum.Min,
+    enyo_timeseries_store_js_1.EnyoTimeseriesStoreAggregationEnum.Max,
+    enyo_timeseries_store_js_1.EnyoTimeseriesStoreAggregationEnum.Sum,
+]);
+/**
+ * Whether a string is a valid series name or tag key.
+ *
+ * @param name - The name to check.
+ * @returns `true` for 1 to {@link TIMESERIES_STORE_MAX_NAME_LENGTH} letters, digits, `.`, `_` or `-`, starting with a letter or digit.
+ */
+function isValidTimeseriesStoreName(name) {
+    return typeof name === 'string'
+        && name.length <= enyo_timeseries_store_js_1.TIMESERIES_STORE_MAX_NAME_LENGTH
+        && NAME_PATTERN.test(name);
+}
+/**
+ * Validates a series definition before it is passed to `defineSeries`.
+ *
+ * @param definition - The definition to check.
+ * @returns The {@link TimeseriesStoreValidationResult}.
+ */
+function validateTimeseriesStoreSeriesDefinition(definition) {
+    const errors = [];
+    if (!isValidTimeseriesStoreName(definition.name)) {
+        errors.push(`invalid series name '${definition.name}'`);
+    }
+    if (!Object.values(enyo_timeseries_store_js_1.EnyoTimeseriesStoreValueTypeEnum).includes(definition.valueType)) {
+        errors.push(`invalid valueType '${String(definition.valueType)}'`);
+    }
+    if (definition.retentionDays !== undefined
+        && !(Number.isInteger(definition.retentionDays) && definition.retentionDays > 0)) {
+        errors.push('retentionDays must be a positive integer');
+    }
+    return { ok: errors.length === 0, errors };
+}
+/**
+ * Checks one point to be written and returns why it is invalid.
+ *
+ * @param point - The point to check.
+ * @param valueType - Value type of the point's series, when known; without it the value is only checked to be a finite number or a string.
+ * @returns The reason the point is invalid, or `undefined` when it is valid.
+ */
+function validateTimeseriesStorePoint(point, valueType) {
+    if (!isValidTimeseriesStoreName(point.series)) {
+        return `invalid series name '${point.series}'`;
+    }
+    if (point.timestampIso !== undefined && Number.isNaN(Date.parse(point.timestampIso))) {
+        return `invalid timestampIso '${point.timestampIso}'`;
+    }
+    const isNumber = typeof point.value === 'number';
+    if (isNumber && !Number.isFinite(point.value)) {
+        return 'value must be a finite number';
+    }
+    if (!isNumber && typeof point.value !== 'string') {
+        return 'value must be a number or a string';
+    }
+    if (typeof point.value === 'string' && point.value.length > enyo_timeseries_store_js_1.TIMESERIES_STORE_MAX_TEXT_LENGTH) {
+        return `text value longer than ${enyo_timeseries_store_js_1.TIMESERIES_STORE_MAX_TEXT_LENGTH} characters`;
+    }
+    if (valueType === enyo_timeseries_store_js_1.EnyoTimeseriesStoreValueTypeEnum.Number && !isNumber) {
+        return `series '${point.series}' holds numbers, got a string`;
+    }
+    if (valueType === enyo_timeseries_store_js_1.EnyoTimeseriesStoreValueTypeEnum.Text && isNumber) {
+        return `series '${point.series}' holds text, got a number`;
+    }
+    return validateTimeseriesStoreTags(point.tags);
+}
+/**
+ * Checks a batch of points to be written, the way the host does.
+ *
+ * @param points - The batch to check.
+ * @param valueTypes - Value type per series name, when known (e.g. from the app's own series definitions).
+ * @returns The invalid points with their index and reason — the same shape as
+ *   {@link EnyoTimeseriesStoreWriteResult.rejected}. A batch larger than
+ *   {@link TIMESERIES_STORE_MAX_POINTS_PER_WRITE} rejects every point beyond the limit.
+ */
+function validateTimeseriesStorePoints(points, valueTypes) {
+    const rejected = [];
+    points.forEach((point, index) => {
+        const reason = index >= enyo_timeseries_store_js_1.TIMESERIES_STORE_MAX_POINTS_PER_WRITE
+            ? `batch exceeds ${enyo_timeseries_store_js_1.TIMESERIES_STORE_MAX_POINTS_PER_WRITE} points`
+            : validateTimeseriesStorePoint(point, valueTypes?.[point.series]);
+        if (reason) {
+            rejected.push({ index, reason });
+        }
+    });
+    return rejected;
+}
+/**
+ * Validates an aggregated query before it is passed to `queryAggregated`.
+ *
+ * @param query - The query to check.
+ * @param valueType - Value type of the queried series, when known; needed to reject numeric aggregations on a text series.
+ * @returns The {@link TimeseriesStoreValidationResult}.
+ */
+function validateTimeseriesStoreAggregatedQuery(query, valueType) {
+    const errors = [];
+    if (!isValidTimeseriesStoreName(query.series)) {
+        errors.push(`invalid series name '${query.series}'`);
+    }
+    const from = Date.parse(query.fromIso);
+    const until = Date.parse(query.untilIso);
+    if (Number.isNaN(from) || Number.isNaN(until)) {
+        errors.push('fromIso and untilIso must be valid ISO 8601 timestamps');
+    }
+    else if (from >= until) {
+        errors.push('fromIso must be before untilIso');
+    }
+    if (query.aggregations.length === 0) {
+        errors.push('at least one aggregation is required');
+    }
+    if (valueType === enyo_timeseries_store_js_1.EnyoTimeseriesStoreValueTypeEnum.Text) {
+        const numeric = query.aggregations.filter((aggregation) => NUMERIC_AGGREGATIONS.has(aggregation));
+        if (numeric.length > 0) {
+            errors.push(`aggregations ${numeric.join(', ')} need a number series`);
+        }
+    }
+    const tagError = validateTimeseriesStoreTags(query.tags);
+    if (tagError) {
+        errors.push(tagError);
+    }
+    return { ok: errors.length === 0, errors };
+}
+/**
+ * Checks the tags of a point or a query filter.
+ *
+ * @param tags - The tags, if any.
+ * @returns The reason the tags are invalid, or `undefined` when they are valid.
+ */
+function validateTimeseriesStoreTags(tags) {
+    if (!tags) {
+        return undefined;
+    }
+    const entries = Object.entries(tags);
+    if (entries.length > enyo_timeseries_store_js_1.TIMESERIES_STORE_MAX_TAGS) {
+        return `more than ${enyo_timeseries_store_js_1.TIMESERIES_STORE_MAX_TAGS} tags`;
+    }
+    for (const [key, value] of entries) {
+        if (!isValidTimeseriesStoreName(key)) {
+            return `invalid tag key '${key}'`;
+        }
+        if (typeof value !== 'string' || value.length === 0 || value.length > enyo_timeseries_store_js_1.TIMESERIES_STORE_MAX_NAME_LENGTH) {
+            return `tag '${key}' needs a string value of 1 to ${enyo_timeseries_store_js_1.TIMESERIES_STORE_MAX_NAME_LENGTH} characters`;
+        }
+    }
+    return undefined;
+}

package/dist/cjs/implementations/timeseries-store/timeseries-store-validators.d.cts

@@ -0,0 +1,50 @@
+import { EnyoTimeseriesStoreAggregatedQuery, EnyoTimeseriesStorePointInput, EnyoTimeseriesStoreSeriesDefinition, EnyoTimeseriesStoreValueTypeEnum, EnyoTimeseriesStoreWriteResult } from '../../types/enyo-timeseries-store.cjs';
+/**
+ * Result of the timeseries store validators that check a whole object.
+ */
+export interface TimeseriesStoreValidationResult {
+    /** `true` when {@link errors} is empty. */
+    ok: boolean;
+    /** One human-readable message per problem found. */
+    errors: string[];
+}
+/**
+ * Whether a string is a valid series name or tag key.
+ *
+ * @param name - The name to check.
+ * @returns `true` for 1 to {@link TIMESERIES_STORE_MAX_NAME_LENGTH} letters, digits, `.`, `_` or `-`, starting with a letter or digit.
+ */
+export declare function isValidTimeseriesStoreName(name: string): boolean;
+/**
+ * Validates a series definition before it is passed to `defineSeries`.
+ *
+ * @param definition - The definition to check.
+ * @returns The {@link TimeseriesStoreValidationResult}.
+ */
+export declare function validateTimeseriesStoreSeriesDefinition(definition: EnyoTimeseriesStoreSeriesDefinition): TimeseriesStoreValidationResult;
+/**
+ * Checks one point to be written and returns why it is invalid.
+ *
+ * @param point - The point to check.
+ * @param valueType - Value type of the point's series, when known; without it the value is only checked to be a finite number or a string.
+ * @returns The reason the point is invalid, or `undefined` when it is valid.
+ */
+export declare function validateTimeseriesStorePoint(point: EnyoTimeseriesStorePointInput, valueType?: EnyoTimeseriesStoreValueTypeEnum): string | undefined;
+/**
+ * Checks a batch of points to be written, the way the host does.
+ *
+ * @param points - The batch to check.
+ * @param valueTypes - Value type per series name, when known (e.g. from the app's own series definitions).
+ * @returns The invalid points with their index and reason — the same shape as
+ *   {@link EnyoTimeseriesStoreWriteResult.rejected}. A batch larger than
+ *   {@link TIMESERIES_STORE_MAX_POINTS_PER_WRITE} rejects every point beyond the limit.
+ */
+export declare function validateTimeseriesStorePoints(points: EnyoTimeseriesStorePointInput[], valueTypes?: Record<string, EnyoTimeseriesStoreValueTypeEnum>): EnyoTimeseriesStoreWriteResult['rejected'];
+/**
+ * Validates an aggregated query before it is passed to `queryAggregated`.
+ *
+ * @param query - The query to check.
+ * @param valueType - Value type of the queried series, when known; needed to reject numeric aggregations on a text series.
+ * @returns The {@link TimeseriesStoreValidationResult}.
+ */
+export declare function validateTimeseriesStoreAggregatedQuery(query: EnyoTimeseriesStoreAggregatedQuery, valueType?: EnyoTimeseriesStoreValueTypeEnum): TimeseriesStoreValidationResult;

package/dist/cjs/implementations/timeseries-store/timeseries-store-write-buffer.cjs

@@ -0,0 +1,132 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TimeseriesStoreWriteBuffer = void 0;
+const enyo_timeseries_store_js_1 = require("../../types/enyo-timeseries-store.cjs");
+/**
+ * Collects timeseries points in memory and writes them to the
+ * {@link EnergyAppTimeseriesStore} in batches — the efficient way to record
+ * values that arrive one at a time (every poll, every data bus message).
+ *
+ * Points get their timestamp when they are added, not when they are written,
+ * so batching never shifts them in time. A failed write keeps the points and
+ * retries them on the next flush; since writes overwrite points with the same
+ * series, tags and timestamp, a retry never duplicates data.
+ *
+ * Call {@link dispose} on shutdown: it stops the interval and writes what is
+ * still buffered.
+ *
+ * @example
+ * ```typescript
+ * const buffer = new TimeseriesStoreWriteBuffer({
+ *     store: energyApp.useTimeseriesStore(),
+ *     interval: energyApp.useInterval(),
+ * });
+ * buffer.add({series: 'compressor.temperature', value: 61.5});
+ * energyApp.onShutdown(() => buffer.dispose());
+ * ```
+ */
+class TimeseriesStoreWriteBuffer {
+    store;
+    interval;
+    maxPoints;
+    maxBufferedPoints;
+    onRejected;
+    onError;
+    intervalId;
+    buffer = [];
+    flushing;
+    /**
+     * Creates the buffer and, when an interval API is given, starts flushing periodically.
+     *
+     * @param options - See {@link TimeseriesStoreWriteBufferOptions}.
+     */
+    constructor(options) {
+        this.store = options.store;
+        this.interval = options.interval;
+        this.maxPoints = Math.max(1, Math.min(options.maxPoints ?? enyo_timeseries_store_js_1.TIMESERIES_STORE_MAX_POINTS_PER_WRITE, enyo_timeseries_store_js_1.TIMESERIES_STORE_MAX_POINTS_PER_WRITE));
+        this.maxBufferedPoints = Math.max(this.maxPoints, options.maxBufferedPoints ?? this.maxPoints * 10);
+        this.onRejected = options.onRejected;
+        this.onError = options.onError;
+        if (this.interval) {
+            this.intervalId = this.interval.createInterval(options.flushInterval ?? '30s', () => this.flush());
+        }
+    }
+    /** Number of points waiting to be written. */
+    get size() {
+        return this.buffer.length;
+    }
+    /**
+     * Adds points to the buffer, stamping those without `timestampIso` with the
+     * current time. Starts a flush when {@link TimeseriesStoreWriteBufferOptions.maxPoints} is reached.
+     *
+     * @param points - One point or several.
+     */
+    add(points) {
+        const nowIso = new Date().toISOString();
+        for (const point of Array.isArray(points) ? points : [points]) {
+            this.buffer.push(point.timestampIso ? point : { ...point, timestampIso: nowIso });
+        }
+        this.trimToCapacity();
+        if (this.buffer.length >= this.maxPoints) {
+            void this.flush();
+        }
+    }
+    /**
+     * Writes everything buffered so far, in batches of at most
+     * {@link TimeseriesStoreWriteBufferOptions.maxPoints}. Concurrent calls share
+     * one flush. Never throws: failures go to `onError` and the points stay buffered.
+     *
+     * @returns Promise resolving once the flush has ended.
+     */
+    flush() {
+        if (!this.flushing) {
+            this.flushing = this.writeAll().finally(() => {
+                this.flushing = undefined;
+            });
+        }
+        return this.flushing;
+    }
+    /**
+     * Stops the periodic flush and writes the remaining points.
+     *
+     * @returns Promise resolving once the final flush has ended.
+     */
+    async dispose() {
+        if (this.interval && this.intervalId) {
+            this.interval.stopInterval(this.intervalId);
+        }
+        await this.flushing;
+        await this.flush();
+    }
+    /**
+     * Writes the buffer batch by batch until it is empty or a write fails.
+     */
+    async writeAll() {
+        while (this.buffer.length > 0) {
+            // Taken out before the write, so points added meanwhile are never mixed up with it.
+            const batch = this.buffer.splice(0, this.maxPoints);
+            try {
+                const result = await this.store.write(batch);
+                if (result.rejected.length > 0) {
+                    this.onRejected?.(result.rejected, batch);
+                }
+            }
+            catch (error) {
+                this.buffer.unshift(...batch);
+                this.trimToCapacity();
+                this.onError?.(error);
+                return;
+            }
+        }
+    }
+    /**
+     * Drops the oldest points beyond {@link TimeseriesStoreWriteBufferOptions.maxBufferedPoints}.
+     */
+    trimToCapacity() {
+        const excess = this.buffer.length - this.maxBufferedPoints;
+        if (excess > 0) {
+            this.buffer.splice(0, excess);
+        }
+    }
+}
+exports.TimeseriesStoreWriteBuffer = TimeseriesStoreWriteBuffer;

package/dist/cjs/implementations/timeseries-store/timeseries-store-write-buffer.d.cts

@@ -0,0 +1,104 @@
+import { EnergyAppInterval, IntervalDuration } from '../../packages/energy-app-interval.cjs';
+import { EnergyAppTimeseriesStore } from '../../packages/energy-app-timeseries-store.cjs';
+import { EnyoTimeseriesStorePointInput, EnyoTimeseriesStoreWriteResult } from '../../types/enyo-timeseries-store.cjs';
+/**
+ * Options of a {@link TimeseriesStoreWriteBuffer}.
+ */
+export interface TimeseriesStoreWriteBufferOptions {
+    /** The store to write to, from `energyApp.useTimeseriesStore()`. */
+    store: EnergyAppTimeseriesStore;
+    /**
+     * Interval API, from `energyApp.useInterval()`. When given, the buffer is
+     * flushed every {@link flushInterval}; without it, only on size and on
+     * explicit {@link TimeseriesStoreWriteBuffer.flush} calls.
+     */
+    interval?: EnergyAppInterval;
+    /** How often to flush when {@link interval} is given. Defaults to `'30s'`. */
+    flushInterval?: IntervalDuration;
+    /**
+     * Number of buffered points that triggers a flush right away. Defaults to
+     * and is capped at {@link TIMESERIES_STORE_MAX_POINTS_PER_WRITE}.
+     */
+    maxPoints?: number;
+    /**
+     * Most points kept while writes fail (e.g. the host is busy). The oldest are
+     * dropped beyond it, so a long outage cannot exhaust memory. Defaults to
+     * 10 × {@link maxPoints}.
+     */
+    maxBufferedPoints?: number;
+    /** Called with the result of every write that rejected points. */
+    onRejected?: (rejected: EnyoTimeseriesStoreWriteResult['rejected'], points: EnyoTimeseriesStorePointInput[]) => void;
+    /** Called when a write fails as a whole; the points stay buffered and are retried on the next flush. */
+    onError?: (error: unknown) => void;
+}
+/**
+ * Collects timeseries points in memory and writes them to the
+ * {@link EnergyAppTimeseriesStore} in batches — the efficient way to record
+ * values that arrive one at a time (every poll, every data bus message).
+ *
+ * Points get their timestamp when they are added, not when they are written,
+ * so batching never shifts them in time. A failed write keeps the points and
+ * retries them on the next flush; since writes overwrite points with the same
+ * series, tags and timestamp, a retry never duplicates data.
+ *
+ * Call {@link dispose} on shutdown: it stops the interval and writes what is
+ * still buffered.
+ *
+ * @example
+ * ```typescript
+ * const buffer = new TimeseriesStoreWriteBuffer({
+ *     store: energyApp.useTimeseriesStore(),
+ *     interval: energyApp.useInterval(),
+ * });
+ * buffer.add({series: 'compressor.temperature', value: 61.5});
+ * energyApp.onShutdown(() => buffer.dispose());
+ * ```
+ */
+export declare class TimeseriesStoreWriteBuffer {
+    private readonly store;
+    private readonly interval?;
+    private readonly maxPoints;
+    private readonly maxBufferedPoints;
+    private readonly onRejected?;
+    private readonly onError?;
+    private readonly intervalId?;
+    private buffer;
+    private flushing?;
+    /**
+     * Creates the buffer and, when an interval API is given, starts flushing periodically.
+     *
+     * @param options - See {@link TimeseriesStoreWriteBufferOptions}.
+     */
+    constructor(options: TimeseriesStoreWriteBufferOptions);
+    /** Number of points waiting to be written. */
+    get size(): number;
+    /**
+     * Adds points to the buffer, stamping those without `timestampIso` with the
+     * current time. Starts a flush when {@link TimeseriesStoreWriteBufferOptions.maxPoints} is reached.
+     *
+     * @param points - One point or several.
+     */
+    add(points: EnyoTimeseriesStorePointInput | EnyoTimeseriesStorePointInput[]): void;
+    /**
+     * Writes everything buffered so far, in batches of at most
+     * {@link TimeseriesStoreWriteBufferOptions.maxPoints}. Concurrent calls share
+     * one flush. Never throws: failures go to `onError` and the points stay buffered.
+     *
+     * @returns Promise resolving once the flush has ended.
+     */
+    flush(): Promise<void>;
+    /**
+     * Stops the periodic flush and writes the remaining points.
+     *
+     * @returns Promise resolving once the final flush has ended.
+     */
+    dispose(): Promise<void>;
+    /**
+     * Writes the buffer batch by batch until it is empty or a write fails.
+     */
+    private writeAll;
+    /**
+     * Drops the oldest points beyond {@link TimeseriesStoreWriteBufferOptions.maxBufferedPoints}.
+     */
+    private trimToCapacity;
+}

package/dist/cjs/index.cjs

@@ -180,6 +180,10 @@ __exportStar(require("./types/enyo-savings.cjs"), exports);
 __exportStar(require("./packages/energy-app-savings.cjs"), exports);
 __exportStar(require("./types/enyo-command-log.cjs"), exports);
 __exportStar(require("./packages/energy-app-command-log.cjs"), exports);
+__exportStar(require("./types/enyo-timeseries-store.cjs"), exports);
+__exportStar(require("./packages/energy-app-timeseries-store.cjs"), exports);
+__exportStar(require("./implementations/timeseries-store/timeseries-store-validators.cjs"), exports);
+__exportStar(require("./implementations/timeseries-store/timeseries-store-write-buffer.cjs"), exports);
 __exportStar(require("./types/enyo-epex-spot-price.cjs"), exports);
 __exportStar(require("./packages/energy-app-epex-spot-price.cjs"), exports);
 __exportStar(require("./types/enyo-automation.cjs"), exports);

package/dist/cjs/index.d.cts

@@ -164,6 +164,10 @@ export * from './types/enyo-savings.cjs';
 export * from './packages/energy-app-savings.cjs';
 export * from './types/enyo-command-log.cjs';
 export * from './packages/energy-app-command-log.cjs';
+export * from './types/enyo-timeseries-store.cjs';
+export * from './packages/energy-app-timeseries-store.cjs';
+export * from './implementations/timeseries-store/timeseries-store-validators.cjs';
+export * from './implementations/timeseries-store/timeseries-store-write-buffer.cjs';
 export * from './types/enyo-epex-spot-price.cjs';
 export * from './packages/energy-app-epex-spot-price.cjs';
 export * from './types/enyo-automation.cjs';

package/dist/cjs/packages/energy-app-timeseries-store.cjs

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });