@enyo-energy/energy-app-sdk 1.19.0 → 1.21.0

package/README.md

@@ -212,8 +212,14 @@ Energy Apps follow a specific lifecycle managed by the enyo system:
 const energyApp = new EnergyApp();
 
 // Register startup callback
-energyApp.register((packageName, version) => {
-    console.log(`${packageName} v${version} started`);
+energyApp.register((packageName, version, channel, deviceId, environment) => {
+    console.log(`${packageName} v${version} started on ${deviceId} (${channel}, ${environment})`);
+
+    // e.g. skip hardware access when running in the developer portal simulation
+    if (environment === EnyoEnergyAppEnvironment.DeveloperPortalSimulation) {
+        console.log('Running in simulation - using mocked devices');
+    }
+
     energyApp.updateEnergyAppState(EnergyAppStateEnum.Running);
 });
 
@@ -369,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
@@ -1763,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-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

@@ -14,7 +14,7 @@ const version_js_1 = require("./version.cjs");
  * @example
  * ```ts
  * const app = new EnergyApp();
- * app.register((packageName, version, channel, deviceId) => {
+ * app.register((packageName, version, channel, deviceId, environment) => {
  *   // perform initialization
  * });
  * ```
@@ -51,6 +51,12 @@ class EnergyApp {
     updateEnergyAppState(state) {
         this.energyAppSdk.updateEnergyAppState(state);
     }
+    /**
+     * Registers the package with the enyo system.
+     * @param callback - Invoked once the package is initialized with the package name,
+     *   the installed package version, the {@link EnyoPackageChannel} it was installed from,
+     *   the id of the device it runs on and the {@link EnyoEnergyAppEnvironment} it is executed in
+     */
     register(callback) {
         // This registers the package with the enyo system
         this.energyAppSdk.register(callback);
@@ -182,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

@@ -19,9 +19,11 @@ import { EnergyAppOnboarding } from "./packages/energy-app-onboarding.cjs";
 import { EnergyAppOnboardingV2 } from "./packages/energy-app-onboarding-v2.cjs";
 import { EnergyAppTimeseries } from "./packages/energy-app-timeseries.cjs";
 import { EnyoPackageChannel } from "./enyo-package-channel.cjs";
+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";
@@ -61,7 +63,7 @@ import { UseFetchOptions } from "./types/enyo-fetch.cjs";
  * @example
  * ```ts
  * const app = new EnergyApp();
- * app.register((packageName, version, channel, deviceId) => {
+ * app.register((packageName, version, channel, deviceId, environment) => {
  *   // perform initialization
  * });
  * ```
@@ -79,7 +81,13 @@ export declare class EnergyApp implements EnyoEnergyAppSdk {
      */
     onNetworkStatusChanged(listener: (online: boolean) => void | Promise<void>): string;
     updateEnergyAppState(state: EnergyAppStateEnum): void;
-    register(callback: (packageName: string, version: number, channel: EnyoPackageChannel, deviceId: string) => void | Promise<void>): void;
+    /**
+     * Registers the package with the enyo system.
+     * @param callback - Invoked once the package is initialized with the package name,
+     *   the installed package version, the {@link EnyoPackageChannel} it was installed from,
+     *   the id of the device it runs on and the {@link EnyoEnergyAppEnvironment} it is executed in
+     */
+    register(callback: (packageName: string, version: number, channel: EnyoPackageChannel, deviceId: string, environment: EnyoEnergyAppEnvironment) => void | Promise<void>): void;
     onShutdown(callback: () => void | Promise<void>): void;
     /**
      * Returns a `fetch` implementation provided by the runtime.
@@ -154,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-environment.cjs

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EnyoEnergyAppEnvironment = void 0;
+/**
+ * Runtime environment an energy app is executed in.
+ *
+ * The environment is handed to the callback passed to `register()` so an app can
+ * adapt its behaviour, e.g. use verbose logging or mocked hardware access while
+ * developing, and skip anything that requires real hardware when it runs inside
+ * the developer portal simulation.
+ */
+var EnyoEnergyAppEnvironment;
+(function (EnyoEnergyAppEnvironment) {
+    /** Running on a real enyo device in development mode (e.g. a developer's test device). */
+    EnyoEnergyAppEnvironment["OnDeviceDevelopment"] = "on-device-development";
+    /** Running on a real enyo device in production, i.e. at a customer's site. */
+    EnyoEnergyAppEnvironment["OnDeviceProduction"] = "on-device-production";
+    /** Running inside the developer portal simulation, without real hardware attached. */
+    EnyoEnergyAppEnvironment["DeveloperPortalSimulation"] = "developer-portal-simulation";
+})(EnyoEnergyAppEnvironment || (exports.EnyoEnergyAppEnvironment = EnyoEnergyAppEnvironment = {}));

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

@@ -0,0 +1,16 @@
+/**
+ * Runtime environment an energy app is executed in.
+ *
+ * The environment is handed to the callback passed to `register()` so an app can
+ * adapt its behaviour, e.g. use verbose logging or mocked hardware access while
+ * developing, and skip anything that requires real hardware when it runs inside
+ * the developer portal simulation.
+ */
+export declare enum EnyoEnergyAppEnvironment {
+    /** Running on a real enyo device in development mode (e.g. a developer's test device). */
+    OnDeviceDevelopment = "on-device-development",
+    /** Running on a real enyo device in production, i.e. at a customer's site. */
+    OnDeviceProduction = "on-device-production",
+    /** Running inside the developer portal simulation, without real hardware attached. */
+    DeveloperPortalSimulation = "developer-portal-simulation"
+}

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

@@ -18,9 +18,11 @@ import { EnergyAppOnboarding } from "./packages/energy-app-onboarding.cjs";
 import { EnergyAppOnboardingV2 } from "./packages/energy-app-onboarding-v2.cjs";
 import { EnergyAppTimeseries } from "./packages/energy-app-timeseries.cjs";
 import { EnyoPackageChannel } from "./enyo-package-channel.cjs";
+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";
@@ -62,8 +64,13 @@ export declare enum EnergyAppStateEnum {
  * network operations, storage, and device communication.
  */
 export interface EnyoEnergyAppSdk {
-    /** Register a callback that gets called when the package is initialized */
-    register: (callback: (packageName: string, version: number, channel: EnyoPackageChannel, deviceId: string) => void | Promise<void>) => void;
+    /**
+     * Register a callback that gets called when the package is initialized.
+     * The callback receives the package name, its version, the release channel it
+     * was installed from, the id of the device it runs on and the
+     * {@link EnyoEnergyAppEnvironment} the app is executed in.
+     */
+    register: (callback: (packageName: string, version: number, channel: EnyoPackageChannel, deviceId: string, environment: EnyoEnergyAppEnvironment) => void | Promise<void>) => void;
     /** health check - returns the current date to check if alive */
     healthcheck: () => Date;
     /** Register a callback that gets called when the system is shutting down */
@@ -120,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/index.cjs

@@ -37,6 +37,7 @@ __exportStar(require("./implementations/network-devices/network-access-guard.cjs
 __exportStar(require("./implementations/network-devices/network-device-manager.cjs"), exports);
 __exportStar(require("./implementations/storage/storage-schedule-handler.cjs"), exports);
 __exportStar(require("./enyo-package-channel.cjs"), exports);
+__exportStar(require("./enyo-energy-app-environment.cjs"), exports);
 __exportStar(require("./types/enyo-timeseries.cjs"), exports);
 __exportStar(require("./types/enyo-energy-manager.cjs"), exports);
 __exportStar(require("./packages/energy-app-energy-manager.cjs"), exports);
@@ -48,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

@@ -21,6 +21,7 @@ export * from './implementations/network-devices/network-access-guard.cjs';
 export * from './implementations/network-devices/network-device-manager.cjs';
 export * from './implementations/storage/storage-schedule-handler.cjs';
 export * from './enyo-package-channel.cjs';
+export * from './enyo-energy-app-environment.cjs';
 export * from './types/enyo-timeseries.cjs';
 export * from './types/enyo-energy-manager.cjs';
 export * from './packages/energy-app-energy-manager.cjs';
@@ -32,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-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 = {}));