@enyo-energy/energy-app-sdk 1.20.0 → 1.22.0

package/README.md

@@ -375,6 +375,7 @@ Energy Apps use a granular permissions system to control access to system resour
 - **`EnergyManager`**: Run as the active energy manager
 - **`EnergyManagerInfo`**: Read information about the active energy manager
 - **`WeatherForecastRegister`** / **`WeatherForecastUse`**: Publish / consume weather forecasts
+- **`WeatherHistoryRegister`** / **`WeatherHistoryUse`**: Publish / consume observed (past) weather data
 - **`PvForecastRegister`** / **`PvForecastUse`**: Publish / consume PV forecasts
 - **`DynamicPriceForecastRegister`** / **`DynamicPriceForecastUse`**: Publish / consume dynamic-price forecasts
 - **`PvSystemRegister`** / **`PvSystemUse`**: Register / read PV system configuration
@@ -1769,6 +1770,86 @@ const byCoords = await weather.getWeatherForecastByCoordinates('wx-prod', 48.13,
 
 Publishers need `WeatherForecastRegister`; consumers need `WeatherForecastUse`.
 
+#### `useWeatherHistory(): EnergyAppWeatherHistory`
+
+The backward-looking counterpart. Where forecasting says what the weather *will* do, this says what it
+*did* between two timestamps — temperature, wind, cloud cover and solar irradiance. That is what you
+need to correlate measured consumption with the weather that drove it, build heating-degree-day
+statistics, check measured PV production against the irradiance that was actually available, or train
+a consumption model on outdoor conditions.
+
+```typescript
+const weatherHistory = energyApp.useWeatherHistory();
+
+await weatherHistory.registerHistory({
+    historyId: 'dwd-archive',
+    name: 'DWD Climate Archive',
+    vendor: 'Deutscher Wetterdienst',
+    availableHistoryDays: 730,
+    availableMeasures: [
+        WeatherHistoryMeasureEnum.OutdoorTemperature,
+        WeatherHistoryMeasureEnum.WindSpeed,
+        WeatherHistoryMeasureEnum.GlobalHorizontalIrradiance,
+    ],
+});
+
+const temperatures = await weatherHistory.getOutdoorTemperature('dwd-archive', {
+    fromIso: '2026-01-15T00:00:00Z',
+    untilIso: '2026-01-16T00:00:00Z',
+    resolution: WeatherHistoryResolutionEnum.OneHour,  // optional, defaults to the provider's
+});
+
+temperatures.averageCelsius;   // time-weighted mean over the interval
+temperatures.minCelsius;
+temperatures.maxCelsius;
+temperatures.readings;         // [{ timestampIso, outdoorTemperatureCelsius }, …]
+```
+
+The interval is half-open — `fromIso` included, `untilIso` excluded — so consecutive intervals line
+up without double-counting the boundary. A `resolution` finer than the provider's is filled by
+linear interpolation, a coarser one aggregated as a time-weighted average.
+
+Reaching further back than the archive goes is **not** an error: you get the covered part plus
+`coveredFromIso` / `coveredUntilIso` telling you where the data actually began and ended, and an
+interval the provider holds nothing for returns empty `readings` with no aggregates.
+
+No location is passed: the registered provider resolves the device's own location through
+`useLocation()`, so a consumer only states the interval it wants.
+
+For anything beyond temperature — irradiance, wind, cloud cover — use `getWeatherHistory`, which
+returns every requested measure per bucket:
+
+```typescript
+const history = await weatherHistory.getWeatherHistory('open-meteo-archive', {
+    fromIso: '2026-01-15T00:00:00Z',
+    untilIso: '2026-01-16T00:00:00Z',
+    resolution: WeatherHistoryResolutionEnum.OneHour,
+    measures: [                                    // optional, defaults to everything held
+        WeatherHistoryMeasureEnum.GlobalHorizontalIrradiance,
+        WeatherHistoryMeasureEnum.WindSpeed,
+        WeatherHistoryMeasureEnum.CloudArea,
+    ],
+});
+
+history.measures;      // what actually came back
+history.readings;      // [{ timestampIso, globalHorizontalIrradiance, windSpeedMs, … }, …]
+history.statistics?.[WeatherHistoryMeasureEnum.WindSpeed]?.averageValue;
+```
+
+Field names and units mirror `WeatherForecastEntry` one to one — `outdoorTemperatureCelsius`,
+`windSpeedMs`, `cloudAreaPercent` (0–100), `symbol`, and `globalHorizontalIrradiance` /
+`directNormalIrradiance` / `diffuseHorizontalIrradiance` in W/m² — so an observed series and a
+forecast series concatenate into one timeline without translation. Every measure on a reading is
+optional: you get what the provider holds and you asked for, and a measure it does not hold is simply
+absent rather than an error.
+
+Aggregates per measure live in `statistics`, keyed by `WeatherHistoryMeasureEnum`. `averageValue` is
+time-weighted; for the irradiance measures it is a mean power density in W/m², so multiply by the
+covered duration in hours to get received energy in Wh/m². `symbol` is categorical and therefore
+never appears in `statistics`.
+
+Publishers need `WeatherHistoryRegister`; consumers need `WeatherHistoryUse`.
+
 #### `usePvForecasting(): EnergyAppPvForecasting`
 
 Same shape as weather forecasting, but for PV production.

package/dist/cjs/energy-app-package-definition.cjs

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EnergyAppPackageFirmwareModeEnum = exports.EnergyAppPackageCategory = void 0;
+exports.EnergyAppPackageFirmwareModeEnum = exports.EnergyAppPackageCompatibilityStatus = exports.EnergyAppPackageCategory = void 0;
 exports.defineEnergyAppPackage = defineEnergyAppPackage;
 const version_js_1 = require("./version.cjs");
 var EnergyAppPackageCategory;
@@ -27,6 +27,24 @@ var EnergyAppPackageCategory;
     EnergyAppPackageCategory["Vehicle"] = "vehicle";
     EnergyAppPackageCategory["Other"] = "other";
 })(EnergyAppPackageCategory || (exports.EnergyAppPackageCategory = EnergyAppPackageCategory = {}));
+/**
+ * Whether a declared compatibility entry means "this works" or "this is known
+ * not to work".
+ *
+ * Used by {@link EnergyAppPackageCompatibilityVendor.status} and
+ * {@link EnergyAppPackageCompatibilityModel.status} so a package can
+ * list a vendor or model it has explicitly tested and found unsupported,
+ * instead of silently leaving it out. The enyo Store and onboarding flows can
+ * then tell the user "this device is not supported by this app" rather than
+ * showing nothing at all.
+ */
+var EnergyAppPackageCompatibilityStatus;
+(function (EnergyAppPackageCompatibilityStatus) {
+    /** The package supports this vendor or model. */
+    EnergyAppPackageCompatibilityStatus["Compatible"] = "compatible";
+    /** The package has been verified **not** to work with this vendor or model. */
+    EnergyAppPackageCompatibilityStatus["NotCompatible"] = "not-compatible";
+})(EnergyAppPackageCompatibilityStatus || (exports.EnergyAppPackageCompatibilityStatus = EnergyAppPackageCompatibilityStatus = {}));
 /**
  * Enum form of {@link EnergyAppPackageFirmwareMode} for use in package
  * definitions.

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

@@ -213,6 +213,23 @@ export interface EnergyAppPackagePermission {
     /** Internal documentation describing what this permission is used for */
     internalComment: string;
 }
+/**
+ * Whether a declared compatibility entry means "this works" or "this is known
+ * not to work".
+ *
+ * Used by {@link EnergyAppPackageCompatibilityVendor.status} and
+ * {@link EnergyAppPackageCompatibilityModel.status} so a package can
+ * list a vendor or model it has explicitly tested and found unsupported,
+ * instead of silently leaving it out. The enyo Store and onboarding flows can
+ * then tell the user "this device is not supported by this app" rather than
+ * showing nothing at all.
+ */
+export declare enum EnergyAppPackageCompatibilityStatus {
+    /** The package supports this vendor or model. */
+    Compatible = "compatible",
+    /** The package has been verified **not** to work with this vendor or model. */
+    NotCompatible = "not-compatible"
+}
 /**
  * A specific device model supported by an Energy App package.
  * the concrete models the package has been verified to work with.
@@ -249,6 +266,16 @@ export interface EnergyAppPackageCompatibilityModel {
     category?: EnergyAppPackageCategory;
     /** Optional internal note explaining model-specific caveats or limitations */
     internalComment?: string;
+    /**
+     * Whether this model is supported or explicitly unsupported.
+     *
+     * Defaults to {@link EnergyAppPackageCompatibilityStatus.Compatible} when
+     * omitted, so existing definitions keep their meaning. Set it to
+     * {@link EnergyAppPackageCompatibilityStatus.NotCompatible} to document a
+     * model you have tested and found not to work — use
+     * {@link internalComment} to say why.
+     */
+    status?: EnergyAppPackageCompatibilityStatus;
     /**
      * Important capabilities this specific model supports (e.g. charging the
      * battery from grid, limiting the charge, or forcing a heat pump DHW boost).
@@ -277,6 +304,16 @@ export interface EnergyAppPackageCompatibilityVendor {
      * worse than listing none.
      */
     models: EnergyAppPackageCompatibilityModel[];
+    /**
+     * Whether this vendor is supported or explicitly unsupported.
+     *
+     * Defaults to {@link EnergyAppPackageCompatibilityStatus.Compatible} when
+     * omitted. Set it to
+     * {@link EnergyAppPackageCompatibilityStatus.NotCompatible} to declare a
+     * brand the package is known not to work with; individual models may still
+     * override it with their own {@link EnergyAppPackageCompatibilityModel.status}.
+     */
+    status?: EnergyAppPackageCompatibilityStatus;
     /**
      * Marks this package as the default Energy App for the vendor when no
      * concrete model has been selected.

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

@@ -37,6 +37,8 @@ var EnergyAppPermissionTypeEnum;
     EnergyAppPermissionTypeEnum["EnergyPrices"] = "EnergyPrices";
     EnergyAppPermissionTypeEnum["WeatherForecastRegister"] = "WeatherForecastRegister";
     EnergyAppPermissionTypeEnum["WeatherForecastUse"] = "WeatherForecastUse";
+    EnergyAppPermissionTypeEnum["WeatherHistoryRegister"] = "WeatherHistoryRegister";
+    EnergyAppPermissionTypeEnum["WeatherHistoryUse"] = "WeatherHistoryUse";
     EnergyAppPermissionTypeEnum["PvForecastRegister"] = "PvForecastRegister";
     EnergyAppPermissionTypeEnum["PvForecastUse"] = "PvForecastUse";
     EnergyAppPermissionTypeEnum["DynamicPriceForecastRegister"] = "DynamicPriceForecastRegister";

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

@@ -33,6 +33,8 @@ export declare enum EnergyAppPermissionTypeEnum {
     EnergyPrices = "EnergyPrices",
     WeatherForecastRegister = "WeatherForecastRegister",
     WeatherForecastUse = "WeatherForecastUse",
+    WeatherHistoryRegister = "WeatherHistoryRegister",
+    WeatherHistoryUse = "WeatherHistoryUse",
     PvForecastRegister = "PvForecastRegister",
     PvForecastUse = "PvForecastUse",
     DynamicPriceForecastRegister = "DynamicPriceForecastRegister",

package/dist/cjs/energy-app.cjs

@@ -188,6 +188,15 @@ class EnergyApp {
     useWeatherForecasting() {
         return this.energyAppSdk.useWeatherForecasting();
     }
+    /**
+     * Gets the Weather History API for managing weather history providers and retrieving observed weather data.
+     * Provides methods to register/deregister weather history providers, list available providers,
+     * and fetch the outdoor temperature for a past time interval by zip code or coordinates.
+     * @returns The Weather History API instance
+     */
+    useWeatherHistory() {
+        return this.energyAppSdk.useWeatherHistory();
+    }
     /**
      * Gets the PV Forecasting API for managing PV forecast providers and retrieving PV forecasts.
      * Provides methods to register/deregister PV forecast providers and fetch power production forecasts.

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

@@ -23,6 +23,7 @@ import { EnyoEnergyAppEnvironment } from "./enyo-energy-app-environment.cjs";
 import { EnergyAppEnergyManager } from "./packages/energy-app-energy-manager.cjs";
 import { EnergyAppElectricityTariff } from "./packages/energy-app-electricity-tariff.cjs";
 import { EnergyAppWeatherForecasting } from "./packages/energy-app-weather-forecasting.cjs";
+import { EnergyAppWeatherHistory } from "./packages/energy-app-weather-history.cjs";
 import { EnergyAppPvForecasting } from "./packages/energy-app-pv-forecasting.cjs";
 import { EnergyAppDynamicPriceForecast } from "./packages/energy-app-dynamic-price-forecast.cjs";
 import { EnergyAppPvSystem } from "./packages/energy-app-pv-system.cjs";
@@ -161,6 +162,13 @@ export declare class EnergyApp implements EnyoEnergyAppSdk {
      * @returns The Weather Forecasting API instance
      */
     useWeatherForecasting(): EnergyAppWeatherForecasting;
+    /**
+     * Gets the Weather History API for managing weather history providers and retrieving observed weather data.
+     * Provides methods to register/deregister weather history providers, list available providers,
+     * and fetch the outdoor temperature for a past time interval by zip code or coordinates.
+     * @returns The Weather History API instance
+     */
+    useWeatherHistory(): EnergyAppWeatherHistory;
     /**
      * Gets the PV Forecasting API for managing PV forecast providers and retrieving PV forecasts.
      * Provides methods to register/deregister PV forecast providers and fetch power production forecasts.

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

@@ -22,6 +22,7 @@ import { EnyoEnergyAppEnvironment } from "./enyo-energy-app-environment.cjs";
 import { EnergyAppEnergyManager } from "./packages/energy-app-energy-manager.cjs";
 import { EnergyAppElectricityTariff } from "./packages/energy-app-electricity-tariff.cjs";
 import { EnergyAppWeatherForecasting } from "./packages/energy-app-weather-forecasting.cjs";
+import { EnergyAppWeatherHistory } from "./packages/energy-app-weather-history.cjs";
 import { EnergyAppPvForecasting } from "./packages/energy-app-pv-forecasting.cjs";
 import { EnergyAppDynamicPriceForecast } from "./packages/energy-app-dynamic-price-forecast.cjs";
 import { EnergyAppPvSystem } from "./packages/energy-app-pv-system.cjs";
@@ -126,6 +127,8 @@ export interface EnyoEnergyAppSdk {
     useElectricityTariff: () => EnergyAppElectricityTariff;
     /** Get the Weather Forecasting API for managing weather forecast providers and retrieving weather forecasts */
     useWeatherForecasting: () => EnergyAppWeatherForecasting;
+    /** Get the Weather History API for managing weather history providers and retrieving observed weather for a past interval */
+    useWeatherHistory: () => EnergyAppWeatherHistory;
     /** Get the PV Forecasting API for managing PV forecast providers and retrieving PV forecasts */
     usePvForecasting: () => EnergyAppPvForecasting;
     /** Get the Dynamic Price Forecast API for publishing and consuming forward-looking electricity price forecasts */

package/dist/cjs/implementations/firmware/firmware-validators.cjs

@@ -24,6 +24,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.FirmwareRegistryValidationError = void 0;
 exports.validateFirmwareRegistry = validateFirmwareRegistry;
 exports.assertValidFirmwareRegistry = assertValidFirmwareRegistry;
+const energy_app_package_definition_js_1 = require("../../energy-app-package-definition.cjs");
 const energy_app_permission_type_js_1 = require("../../energy-app-permission.type.cjs");
 const define_firmware_file_js_1 = require("./define-firmware-file.cjs");
 /**
@@ -269,11 +270,12 @@ function findDanglingSources(files) {
 }
 /**
  * Reports vendors and models referenced by firmware entries that the package
- * does not declare in its `compatibility` list.
+ * does not declare in its `compatibility` list, or that it declares as
+ * {@link EnergyAppPackageCompatibilityStatus.NotCompatible}.
  *
  * @param files - All declared firmware entries.
  * @param compatibility - The package's declared vendors and models.
- * @returns One warning per unknown vendor or model.
+ * @returns One warning per unknown or explicitly incompatible vendor or model.
  */
 function findUnknownCompatibility(files, compatibility) {
     const warnings = [];
@@ -281,15 +283,27 @@ function findUnknownCompatibility(files, compatibility) {
         return warnings;
     const vendors = new Set(compatibility.map(vendor => vendor.vendorName));
     const models = new Set(compatibility.flatMap(vendor => vendor.models.map(model => model.modelName)));
+    const incompatibleVendors = new Set(compatibility
+        .filter(vendor => vendor.status === energy_app_package_definition_js_1.EnergyAppPackageCompatibilityStatus.NotCompatible)
+        .map(vendor => vendor.vendorName));
+    const incompatibleModels = new Set(compatibility.flatMap(vendor => vendor.models
+        .filter(model => model.status === energy_app_package_definition_js_1.EnergyAppPackageCompatibilityStatus.NotCompatible)
+        .map(model => model.modelName)));
     for (const [index, file] of files.entries()) {
         const at = describe(file, index);
         if (file.vendorName && !vendors.has(file.vendorName)) {
             warnings.push(`${at}: vendorName "${file.vendorName}" is not listed in compatibility.`);
         }
+        else if (file.vendorName && incompatibleVendors.has(file.vendorName)) {
+            warnings.push(`${at}: vendorName "${file.vendorName}" is declared as not-compatible.`);
+        }
         for (const model of file.modelNames ?? []) {
             if (!models.has(model)) {
                 warnings.push(`${at}: modelName "${model}" is not listed in compatibility.`);
             }
+            else if (incompatibleModels.has(model)) {
+                warnings.push(`${at}: modelName "${model}" is declared as not-compatible.`);
+            }
         }
     }
     return warnings;

package/dist/cjs/index.cjs

@@ -49,6 +49,8 @@ __exportStar(require("./packages/energy-app-electricity-tariff.cjs"), exports);
 __exportStar(require("./types/enyo-pv-forecast.cjs"), exports);
 __exportStar(require("./types/enyo-forecasting.cjs"), exports);
 __exportStar(require("./packages/energy-app-weather-forecasting.cjs"), exports);
+__exportStar(require("./types/enyo-weather-history.cjs"), exports);
+__exportStar(require("./packages/energy-app-weather-history.cjs"), exports);
 __exportStar(require("./packages/energy-app-pv-forecasting.cjs"), exports);
 __exportStar(require("./packages/energy-app-dynamic-price-forecast.cjs"), exports);
 __exportStar(require("./types/enyo-pv-system.cjs"), exports);

package/dist/cjs/index.d.cts

@@ -33,6 +33,8 @@ export * from './packages/energy-app-electricity-tariff.cjs';
 export * from './types/enyo-pv-forecast.cjs';
 export * from './types/enyo-forecasting.cjs';
 export * from './packages/energy-app-weather-forecasting.cjs';
+export * from './types/enyo-weather-history.cjs';
+export * from './packages/energy-app-weather-history.cjs';
 export * from './packages/energy-app-pv-forecasting.cjs';
 export * from './packages/energy-app-dynamic-price-forecast.cjs';
 export * from './types/enyo-pv-system.cjs';

package/dist/cjs/packages/energy-app-modbus-rtu.d.cts

@@ -28,6 +28,21 @@ export interface ModbusRtuOptions {
      */
     waitBetweenMessagesMs?: number;
 }
+/**
+ * Which register bank an RTU read addresses, and therefore which Modbus
+ * function code goes on the wire.
+ *
+ * Holding and input registers are two separate address spaces: a device may
+ * answer register 30001 as an input register and hold something entirely
+ * different — or nothing at all — at the same address in the holding bank.
+ * Reading the wrong bank yields an illegal-data-address exception, not a
+ * timeout, so this is a correctness knob rather than a recovery one.
+ */
+export type ModbusRtuRegisterType = 
+/** Holding registers, read with function code 3 (`mbpoll -t 4`). */
+'holding'
+/** Input registers, read with function code 4 (`mbpoll -t 3`). */
+ | 'input';
 /**
  * Request parameters for reading Modbus RTU registers.
  */
@@ -38,6 +53,14 @@ export interface ModbusRtuReadRegistersRequest {
     startRegister: number;
     /** Number of consecutive registers to read */
     count: number;
+    /**
+     * Which register bank to read from.
+     *
+     * `'holding'` issues function code 3 and `'input'` issues function code 4.
+     * Defaults to `'holding'` when omitted, which is what every existing caller
+     * gets today.
+     */
+    registerType?: ModbusRtuRegisterType;
 }
 /**
  * Response containing register values read from a Modbus RTU device.
@@ -63,9 +86,15 @@ export interface ModbusRtuWriteRegistersRequest {
  * Provides methods for reading and writing registers over a serial connection.
  */
 export interface EnergyAppModbusRtuInstance {
-    /** Read register values from the connected Modbus RTU device */
+    /**
+     * Read register values from the connected Modbus RTU device.
+     *
+     * Reads holding registers (function code 3) unless the request sets
+     * {@link ModbusRtuReadRegistersRequest.registerType} to `'input'`, which
+     * reads input registers with function code 4 instead.
+     */
     readRegisters: (request: ModbusRtuReadRegistersRequest) => Promise<ModbusRtuReadRegistersResponse>;
-    /** Write register values to the connected Modbus RTU device */
+    /** Write register values to the connected Modbus RTU device (holding registers only) */
     writeRegisters: (request: ModbusRtuWriteRegistersRequest) => Promise<void>;
 }
 /**

package/dist/cjs/packages/energy-app-weather-history.cjs

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

package/dist/cjs/packages/energy-app-weather-history.d.cts

@@ -0,0 +1,138 @@
+import { WeatherHistoryRegistration, WeatherHistoryInfo, OutdoorTemperatureHistoryRequest, OutdoorTemperatureHistory, WeatherHistoryRequest, WeatherHistory } from "../types/enyo-weather-history.cjs";
+/**
+ * Interface for managing weather history providers and retrieving observed
+ * weather data for a past time interval.
+ *
+ * This is the backward-looking counterpart to `EnergyAppWeatherForecasting`:
+ * where the forecasting API answers "what will the weather do", this one
+ * answers "what was the weather between these two timestamps" — temperature,
+ * wind, cloud cover and solar irradiance. That is the input an app needs to
+ * correlate measured consumption with the weather that drove it, to build
+ * heating-degree-day statistics, to check measured PV production against the
+ * irradiance that was actually available, or to train a consumption model on
+ * outdoor conditions.
+ *
+ * Two queries are offered: {@link EnergyAppWeatherHistory.getWeatherHistory}
+ * returns every requested measure per bucket, while
+ * {@link EnergyAppWeatherHistory.getOutdoorTemperature} is the shorthand for
+ * the common temperature-only case. Neither takes a location — the registered
+ * provider resolves the device's own location via `energyApp.useLocation()`,
+ * so a consumer only ever states the interval it cares about.
+ *
+ * Like the forecasting API, data comes from registered providers; an app
+ * either registers one (wrapping an external archive) or consumes one that is
+ * already registered, or both.
+ */
+export interface EnergyAppWeatherHistory {
+    /**
+     * Registers a new weather history provider or updates an existing one.
+     * Uses upsert logic based on historyId - if a provider with the same ID
+     * exists, it will be updated; otherwise, a new provider will be created.
+     *
+     * @param registration - The history provider registration data
+     * @returns Promise that resolves when the provider has been registered
+     *
+     * @example
+     * ```typescript
+     * await weatherHistory.registerHistory({
+     *     historyId: 'dwd-archive',
+     *     name: 'DWD Climate Archive',
+     *     vendor: 'Deutscher Wetterdienst',
+     *     availableHistoryDays: 730,
+     *     availableMeasures: [WeatherHistoryMeasureEnum.OutdoorTemperature]
+     * });
+     * ```
+     */
+    registerHistory(registration: WeatherHistoryRegistration): Promise<void>;
+    /**
+     * Removes a registered weather history provider by its ID.
+     * If the provider does not exist, this operation is a no-op.
+     *
+     * @param historyId - The unique identifier of the history provider to remove
+     * @returns Promise that resolves when the provider has been removed
+     */
+    deregisterHistory(historyId: string): Promise<void>;
+    /**
+     * Retrieves all registered weather history providers.
+     *
+     * @returns Promise that resolves to an array of all registered weather history providers
+     *
+     * @example
+     * ```typescript
+     * const providers = await weatherHistory.listHistories();
+     * providers.forEach(p => console.log(`${p.name} (${p.vendor})`));
+     * ```
+     */
+    listHistories(): Promise<WeatherHistoryInfo[]>;
+    /**
+     * Fetches the observed outdoor temperature for a time interval.
+     *
+     * The interval is half-open: `fromIso` is included and `untilIso` is not,
+     * so consecutive intervals can be requested back to back without the
+     * boundary timestamp being counted twice. Pass `resolution` to get a bucket
+     * size other than the provider's own — a finer resolution is filled by
+     * linear interpolation, a coarser one aggregated as a time-weighted
+     * average.
+     *
+     * An interval that reaches further back than the provider's archive, or
+     * forward past its most recent observation, is not an error: the covered
+     * part is returned and `coveredFromIso` / `coveredUntilIso` state where the
+     * data actually began and ended. An interval the provider holds no data for
+     * at all yields an empty `readings` array.
+     *
+     * @param historyId - The unique identifier of the history provider to use
+     * @param request - The requested interval and resolution
+     * @returns Promise that resolves to the observed temperatures for the interval
+     *
+     * @example
+     * ```typescript
+     * const temperatures = await weatherHistory.getOutdoorTemperature('dwd-archive', {
+     *     fromIso: '2026-01-15T00:00:00Z',
+     *     untilIso: '2026-01-16T00:00:00Z',
+     *     resolution: WeatherHistoryResolutionEnum.OneHour
+     * });
+     * console.log(`Average: ${temperatures.averageCelsius}°C`);
+     * temperatures.readings.forEach(r =>
+     *     console.log(`${r.timestampIso}: ${r.outdoorTemperatureCelsius}°C`)
+     * );
+     * ```
+     */
+    getOutdoorTemperature(historyId: string, request: OutdoorTemperatureHistoryRequest): Promise<OutdoorTemperatureHistory>;
+    /**
+     * Fetches the observed weather for a time interval across every requested
+     * measure — temperature, wind speed, cloud cover and the three irradiance
+     * components.
+     *
+     * Interval, resolution and coverage behave exactly as described on
+     * {@link EnergyAppWeatherHistory.getOutdoorTemperature}. Narrow the result
+     * with `measures` when only some quantities are needed — archives are
+     * typically billed or rate-limited per quantity. Measures the provider does
+     * not hold are simply absent from the readings rather than reported as an
+     * error; `measures` on the result states what actually came back.
+     *
+     * @param historyId - The unique identifier of the history provider to use
+     * @param request - The requested interval, resolution and measures
+     * @returns Promise that resolves to the observed weather for the interval
+     *
+     * @example
+     * ```typescript
+     * const history = await weatherHistory.getWeatherHistory('open-meteo-archive', {
+     *     fromIso: '2026-01-15T00:00:00Z',
+     *     untilIso: '2026-01-16T00:00:00Z',
+     *     resolution: WeatherHistoryResolutionEnum.OneHour,
+     *     measures: [
+     *         WeatherHistoryMeasureEnum.GlobalHorizontalIrradiance,
+     *         WeatherHistoryMeasureEnum.WindSpeed,
+     *         WeatherHistoryMeasureEnum.CloudArea
+     *     ]
+     * });
+     *
+     * const ghi = history.statistics?.[WeatherHistoryMeasureEnum.GlobalHorizontalIrradiance];
+     * console.log(`Mean irradiance: ${ghi?.averageValue} W/m²`);
+     * history.readings.forEach(r =>
+     *     console.log(`${r.timestampIso}: ${r.globalHorizontalIrradiance} W/m², ${r.windSpeedMs} m/s`)
+     * );
+     * ```
+     */
+    getWeatherHistory(historyId: string, request: WeatherHistoryRequest): Promise<WeatherHistory>;
+}

package/dist/cjs/types/enyo-weather-history.cjs

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WeatherHistoryMeasureEnum = exports.WeatherHistoryResolutionEnum = void 0;
+/**
+ * Resolution of historical weather data entries.
+ *
+ * The values mirror {@link ForecastResolutionEnum} so a history series and a
+ * forecast series of the same resolution can be concatenated without
+ * translating between the two vocabularies.
+ */
+var WeatherHistoryResolutionEnum;
+(function (WeatherHistoryResolutionEnum) {
+    /** 1-minute intervals */
+    WeatherHistoryResolutionEnum["OneMinute"] = "1min";
+    /** 15-minute intervals */
+    WeatherHistoryResolutionEnum["FifteenMinutes"] = "15min";
+    /** 1-hour intervals */
+    WeatherHistoryResolutionEnum["OneHour"] = "1hr";
+})(WeatherHistoryResolutionEnum || (exports.WeatherHistoryResolutionEnum = WeatherHistoryResolutionEnum = {}));
+/**
+ * A weather quantity a history provider can serve.
+ *
+ * Used to narrow a request to the measures an app actually needs — archives
+ * are usually billed or rate-limited per quantity, so asking for irradiance
+ * when only wind is wanted is pure cost.
+ */
+var WeatherHistoryMeasureEnum;
+(function (WeatherHistoryMeasureEnum) {
+    /** Outdoor air temperature in degrees Celsius */
+    WeatherHistoryMeasureEnum["OutdoorTemperature"] = "outdoor-temperature";
+    /** Wind speed in meters per second */
+    WeatherHistoryMeasureEnum["WindSpeed"] = "wind-speed";
+    /** Cloud coverage area in percent */
+    WeatherHistoryMeasureEnum["CloudArea"] = "cloud-area";
+    /** Global horizontal irradiance in W/m² */
+    WeatherHistoryMeasureEnum["GlobalHorizontalIrradiance"] = "global-horizontal-irradiance";
+    /** Direct normal irradiance in W/m² */
+    WeatherHistoryMeasureEnum["DirectNormalIrradiance"] = "direct-normal-irradiance";
+    /** Diffuse horizontal irradiance in W/m² */
+    WeatherHistoryMeasureEnum["DiffuseHorizontalIrradiance"] = "diffuse-horizontal-irradiance";
+    /** Categorical weather symbol */
+    WeatherHistoryMeasureEnum["Symbol"] = "symbol";
+})(WeatherHistoryMeasureEnum || (exports.WeatherHistoryMeasureEnum = WeatherHistoryMeasureEnum = {}));