@enyo-energy/energy-app-sdk 1.20.0 → 1.21.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-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/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-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 = {}));

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

@@ -0,0 +1,284 @@
+import { EnyoWeatherSymbolEnum } from './enyo-forecasting.cjs';
+/**
+ * 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.
+ */
+export declare enum WeatherHistoryResolutionEnum {
+    /** 1-minute intervals */
+    OneMinute = "1min",
+    /** 15-minute intervals */
+    FifteenMinutes = "15min",
+    /** 1-hour intervals */
+    OneHour = "1hr"
+}
+/**
+ * Registration data for a weather history provider.
+ *
+ * A provider is not told which place to serve: it resolves the device's own
+ * location itself via `energyApp.useLocation()`, so nothing location-shaped
+ * travels through this API.
+ */
+export interface WeatherHistoryRegistration {
+    /** Unique identifier for the weather history provider */
+    historyId: string;
+    /** Human-readable name of the history provider */
+    name: string;
+    /** Vendor or company providing the historical data */
+    vendor: string;
+    /**
+     * How far back the provider can serve data, in days. Informational — it
+     * lets a consumer size its request before issuing one that would only be
+     * partially covered.
+     */
+    availableHistoryDays?: number;
+    /**
+     * The measures this provider can serve. Informational — it lets a consumer
+     * pick a provider that holds the quantity it needs instead of discovering
+     * the gap from an empty result. When omitted, assume outdoor temperature
+     * only.
+     */
+    availableMeasures?: WeatherHistoryMeasureEnum[];
+}
+/**
+ * A registered weather history provider with metadata.
+ */
+export interface WeatherHistoryInfo extends WeatherHistoryRegistration {
+    /** Timestamp when this history provider was registered in ISO format */
+    registeredAtIso: string;
+}
+/**
+ * Time interval and resolution shared by every weather history request.
+ *
+ * The interval is half-open — `fromIso` is included, `untilIso` is not — so
+ * consecutive intervals can be requested back to back without the boundary
+ * timestamp being counted twice.
+ */
+export interface WeatherHistoryIntervalRequest {
+    /** Start of the requested interval in ISO format (inclusive) */
+    fromIso: string;
+    /** End of the requested interval in ISO format (exclusive) */
+    untilIso: string;
+    /**
+     * Desired resolution of the returned readings. When omitted, the
+     * provider's own resolution is used. A resolution finer than the
+     * provider's is filled by linear interpolation; a coarser one is
+     * aggregated as a time-weighted average.
+     */
+    resolution?: WeatherHistoryResolutionEnum;
+}
+/**
+ * Request parameters for fetching historical outdoor temperatures for a time
+ * interval — the interval and resolution, nothing else.
+ */
+export type OutdoorTemperatureHistoryRequest = WeatherHistoryIntervalRequest;
+/**
+ * A single observed outdoor temperature at a point in time.
+ */
+export interface OutdoorTemperatureReading {
+    /** Start of the bucket this reading applies to, in ISO format */
+    timestampIso: string;
+    /** Observed outdoor temperature in degrees Celsius */
+    outdoorTemperatureCelsius: number;
+}
+/**
+ * Observed outdoor temperatures covering a requested time interval.
+ *
+ * `fromIso`, `untilIso` and `resolution` echo what was asked for, while
+ * {@link OutdoorTemperatureHistory.coveredFromIso} and
+ * {@link OutdoorTemperatureHistory.coveredUntilIso} state what the provider
+ * could actually deliver — these differ whenever the requested interval
+ * reaches further back than the provider's archive, or into the future.
+ */
+export interface OutdoorTemperatureHistory {
+    /** Start of the requested interval in ISO format (inclusive) */
+    fromIso: string;
+    /** End of the requested interval in ISO format (exclusive) */
+    untilIso: string;
+    /** The resolution of the returned readings */
+    resolution: WeatherHistoryResolutionEnum;
+    /**
+     * Readings ordered by timestamp, one per bucket of
+     * {@link OutdoorTemperatureHistory.resolution}. Empty when the provider
+     * holds no data for the requested interval — this is a normal result, not
+     * an error.
+     */
+    readings: OutdoorTemperatureReading[];
+    /**
+     * Time-weighted mean temperature over the covered part of the interval, in
+     * degrees Celsius. Absent when {@link OutdoorTemperatureHistory.readings}
+     * is empty.
+     */
+    averageCelsius?: number;
+    /**
+     * Lowest temperature in degrees Celsius over the covered part of the
+     * interval. Absent when {@link OutdoorTemperatureHistory.readings} is
+     * empty.
+     */
+    minCelsius?: number;
+    /**
+     * Highest temperature in degrees Celsius over the covered part of the
+     * interval. Absent when {@link OutdoorTemperatureHistory.readings} is
+     * empty.
+     */
+    maxCelsius?: number;
+    /**
+     * Start of the part of the interval the provider could cover, in ISO
+     * format. Later than {@link OutdoorTemperatureHistory.fromIso} when the
+     * request reached further back than the archive goes. Absent when
+     * {@link OutdoorTemperatureHistory.readings} is empty.
+     */
+    coveredFromIso?: string;
+    /**
+     * End of the part of the interval the provider could cover, in ISO format.
+     * Earlier than {@link OutdoorTemperatureHistory.untilIso} when the request
+     * reached into the future or past the most recent observation. Absent when
+     * {@link OutdoorTemperatureHistory.readings} is empty.
+     */
+    coveredUntilIso?: string;
+}
+/**
+ * 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.
+ */
+export declare enum WeatherHistoryMeasureEnum {
+    /** Outdoor air temperature in degrees Celsius */
+    OutdoorTemperature = "outdoor-temperature",
+    /** Wind speed in meters per second */
+    WindSpeed = "wind-speed",
+    /** Cloud coverage area in percent */
+    CloudArea = "cloud-area",
+    /** Global horizontal irradiance in W/m² */
+    GlobalHorizontalIrradiance = "global-horizontal-irradiance",
+    /** Direct normal irradiance in W/m² */
+    DirectNormalIrradiance = "direct-normal-irradiance",
+    /** Diffuse horizontal irradiance in W/m² */
+    DiffuseHorizontalIrradiance = "diffuse-horizontal-irradiance",
+    /** Categorical weather symbol */
+    Symbol = "symbol"
+}
+/**
+ * A single observed weather data point.
+ *
+ * Every measure is optional: a reading only carries the quantities the
+ * provider holds and the request asked for. The field names and units mirror
+ * `WeatherForecastEntry` exactly, so an observed series and a forecast series
+ * can be concatenated into one timeline without translating between them.
+ */
+export interface WeatherHistoryReading {
+    /** Start of the bucket this reading applies to, in ISO format */
+    timestampIso: string;
+    /** Observed outdoor temperature in degrees Celsius */
+    outdoorTemperatureCelsius?: number;
+    /** Observed wind speed in meters per second */
+    windSpeedMs?: number;
+    /** Observed cloud coverage area as a percentage (0-100) */
+    cloudAreaPercent?: number;
+    /** Weather symbol describing the observed condition */
+    symbol?: EnyoWeatherSymbolEnum;
+    /**
+     * Global horizontal irradiance in W/m².
+     *
+     * Total shortwave radiation received by a horizontal surface — the sum of
+     * the diffuse part and the horizontal projection of the direct part
+     * (`GHI = DHI + DNI * cos(zenith)`). This is the quantity to correlate
+     * with measured PV production.
+     */
+    globalHorizontalIrradiance?: number;
+    /**
+     * Direct normal irradiance (DNI) in W/m².
+     *
+     * Beam radiation arriving from the direction of the sun, measured on a
+     * surface held perpendicular to the sun's rays. Together with
+     * {@link WeatherHistoryReading.diffuseHorizontalIrradiance} it allows
+     * transposing the observation onto an arbitrarily tilted plane (plane of
+     * array), which a single GHI value cannot do.
+     */
+    directNormalIrradiance?: number;
+    /**
+     * Diffuse horizontal irradiance (DHI) in W/m².
+     *
+     * The part of the radiation on a horizontal surface that has been
+     * scattered by the atmosphere and clouds, i.e. everything that did not
+     * arrive directly from the sun's disc. See
+     * {@link WeatherHistoryReading.directNormalIrradiance}.
+     */
+    diffuseHorizontalIrradiance?: number;
+}
+/**
+ * Aggregates of one numeric measure over the covered part of an interval.
+ */
+export interface WeatherHistoryStatistics {
+    /**
+     * Time-weighted mean of the measure over the covered interval, in the
+     * measure's own unit.
+     *
+     * For the irradiance measures this is a mean power density in W/m²;
+     * multiply by the covered duration in hours to get the received energy in
+     * Wh/m².
+     */
+    averageValue: number;
+    /** Lowest observed value of the measure, in the measure's own unit */
+    minValue: number;
+    /** Highest observed value of the measure, in the measure's own unit */
+    maxValue: number;
+}
+/**
+ * Request parameters for fetching observed weather for a time interval.
+ */
+export interface WeatherHistoryRequest extends WeatherHistoryIntervalRequest {
+    /**
+     * The measures to return. When omitted, the provider returns everything it
+     * holds for the interval.
+     */
+    measures?: WeatherHistoryMeasureEnum[];
+}
+/**
+ * Observed weather covering a requested time interval, across every requested
+ * measure.
+ *
+ * This is the general-purpose counterpart to {@link OutdoorTemperatureHistory}:
+ * same interval and coverage semantics, but each reading carries the full set
+ * of requested quantities instead of temperature alone.
+ */
+export interface WeatherHistory {
+    /** Start of the requested interval in ISO format (inclusive) */
+    fromIso: string;
+    /** End of the requested interval in ISO format (exclusive) */
+    untilIso: string;
+    /** The resolution of the returned readings */
+    resolution: WeatherHistoryResolutionEnum;
+    /** The measures actually contained in the readings */
+    measures: WeatherHistoryMeasureEnum[];
+    /**
+     * Readings ordered by timestamp, one per bucket of
+     * {@link WeatherHistory.resolution}. Empty when the provider holds no data
+     * for the requested interval — this is a normal result, not an error.
+     */
+    readings: WeatherHistoryReading[];
+    /**
+     * Aggregates per numeric measure over the covered part of the interval.
+     * {@link WeatherHistoryMeasureEnum.Symbol} is categorical and therefore
+     * never present here. Absent when {@link WeatherHistory.readings} is empty.
+     */
+    statistics?: Partial<Record<WeatherHistoryMeasureEnum, WeatherHistoryStatistics>>;
+    /**
+     * Start of the part of the interval the provider could cover, in ISO
+     * format. Later than {@link WeatherHistory.fromIso} when the request
+     * reached further back than the archive goes. Absent when
+     * {@link WeatherHistory.readings} is empty.
+     */
+    coveredFromIso?: string;
+    /**
+     * End of the part of the interval the provider could cover, in ISO format.
+     * Earlier than {@link WeatherHistory.untilIso} when the request reached
+     * into the future or past the most recent observation. Absent when
+     * {@link WeatherHistory.readings} is empty.
+     */
+    coveredUntilIso?: string;
+}

package/dist/cjs/version.cjs

@@ -9,7 +9,7 @@ exports.getSdkVersion = getSdkVersion;
 /**
  * Current version of the enyo Energy App SDK.
  */
-exports.SDK_VERSION = '1.20.0';
+exports.SDK_VERSION = '1.21.0';
 /**
  * Gets the current SDK version.
  * @returns The semantic version string of the SDK

package/dist/cjs/version.d.cts

@@ -5,7 +5,7 @@
 /**
  * Current version of the enyo Energy App SDK.
  */
-export declare const SDK_VERSION = "1.20.0";
+export declare const SDK_VERSION = "1.21.0";
 /**
  * Gets the current SDK version.
  * @returns The semantic version string of the SDK

package/dist/energy-app-permission.type.d.ts

@@ -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/energy-app-permission.type.js

@@ -34,6 +34,8 @@ export 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/energy-app.d.ts

@@ -23,6 +23,7 @@ import { EnyoEnergyAppEnvironment } from "./enyo-energy-app-environment.js";
 import { EnergyAppEnergyManager } from "./packages/energy-app-energy-manager.js";
 import { EnergyAppElectricityTariff } from "./packages/energy-app-electricity-tariff.js";
 import { EnergyAppWeatherForecasting } from "./packages/energy-app-weather-forecasting.js";
+import { EnergyAppWeatherHistory } from "./packages/energy-app-weather-history.js";
 import { EnergyAppPvForecasting } from "./packages/energy-app-pv-forecasting.js";
 import { EnergyAppDynamicPriceForecast } from "./packages/energy-app-dynamic-price-forecast.js";
 import { EnergyAppPvSystem } from "./packages/energy-app-pv-system.js";
@@ -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/energy-app.js

@@ -185,6 +185,15 @@ export 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/enyo-energy-app-sdk.d.ts

@@ -22,6 +22,7 @@ import { EnyoEnergyAppEnvironment } from "./enyo-energy-app-environment.js";
 import { EnergyAppEnergyManager } from "./packages/energy-app-energy-manager.js";
 import { EnergyAppElectricityTariff } from "./packages/energy-app-electricity-tariff.js";
 import { EnergyAppWeatherForecasting } from "./packages/energy-app-weather-forecasting.js";
+import { EnergyAppWeatherHistory } from "./packages/energy-app-weather-history.js";
 import { EnergyAppPvForecasting } from "./packages/energy-app-pv-forecasting.js";
 import { EnergyAppDynamicPriceForecast } from "./packages/energy-app-dynamic-price-forecast.js";
 import { EnergyAppPvSystem } from "./packages/energy-app-pv-system.js";
@@ -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/index.d.ts

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

package/dist/index.js

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

package/dist/packages/energy-app-weather-history.d.ts

@@ -0,0 +1,138 @@
+import { WeatherHistoryRegistration, WeatherHistoryInfo, OutdoorTemperatureHistoryRequest, OutdoorTemperatureHistory, WeatherHistoryRequest, WeatherHistory } from "../types/enyo-weather-history.js";
+/**
+ * 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/packages/energy-app-weather-history.js

@@ -0,0 +1 @@
+export {};

package/dist/types/enyo-weather-history.d.ts

@@ -0,0 +1,284 @@
+import { EnyoWeatherSymbolEnum } from './enyo-forecasting.js';
+/**
+ * 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.
+ */
+export declare enum WeatherHistoryResolutionEnum {
+    /** 1-minute intervals */
+    OneMinute = "1min",
+    /** 15-minute intervals */
+    FifteenMinutes = "15min",
+    /** 1-hour intervals */
+    OneHour = "1hr"
+}
+/**
+ * Registration data for a weather history provider.
+ *
+ * A provider is not told which place to serve: it resolves the device's own
+ * location itself via `energyApp.useLocation()`, so nothing location-shaped
+ * travels through this API.
+ */
+export interface WeatherHistoryRegistration {
+    /** Unique identifier for the weather history provider */
+    historyId: string;
+    /** Human-readable name of the history provider */
+    name: string;
+    /** Vendor or company providing the historical data */
+    vendor: string;
+    /**
+     * How far back the provider can serve data, in days. Informational — it
+     * lets a consumer size its request before issuing one that would only be
+     * partially covered.
+     */
+    availableHistoryDays?: number;
+    /**
+     * The measures this provider can serve. Informational — it lets a consumer
+     * pick a provider that holds the quantity it needs instead of discovering
+     * the gap from an empty result. When omitted, assume outdoor temperature
+     * only.
+     */
+    availableMeasures?: WeatherHistoryMeasureEnum[];
+}
+/**
+ * A registered weather history provider with metadata.
+ */
+export interface WeatherHistoryInfo extends WeatherHistoryRegistration {
+    /** Timestamp when this history provider was registered in ISO format */
+    registeredAtIso: string;
+}
+/**
+ * Time interval and resolution shared by every weather history request.
+ *
+ * The interval is half-open — `fromIso` is included, `untilIso` is not — so
+ * consecutive intervals can be requested back to back without the boundary
+ * timestamp being counted twice.
+ */
+export interface WeatherHistoryIntervalRequest {
+    /** Start of the requested interval in ISO format (inclusive) */
+    fromIso: string;
+    /** End of the requested interval in ISO format (exclusive) */
+    untilIso: string;
+    /**
+     * Desired resolution of the returned readings. When omitted, the
+     * provider's own resolution is used. A resolution finer than the
+     * provider's is filled by linear interpolation; a coarser one is
+     * aggregated as a time-weighted average.
+     */
+    resolution?: WeatherHistoryResolutionEnum;
+}
+/**
+ * Request parameters for fetching historical outdoor temperatures for a time
+ * interval — the interval and resolution, nothing else.
+ */
+export type OutdoorTemperatureHistoryRequest = WeatherHistoryIntervalRequest;
+/**
+ * A single observed outdoor temperature at a point in time.
+ */
+export interface OutdoorTemperatureReading {
+    /** Start of the bucket this reading applies to, in ISO format */
+    timestampIso: string;
+    /** Observed outdoor temperature in degrees Celsius */
+    outdoorTemperatureCelsius: number;
+}
+/**
+ * Observed outdoor temperatures covering a requested time interval.
+ *
+ * `fromIso`, `untilIso` and `resolution` echo what was asked for, while
+ * {@link OutdoorTemperatureHistory.coveredFromIso} and
+ * {@link OutdoorTemperatureHistory.coveredUntilIso} state what the provider
+ * could actually deliver — these differ whenever the requested interval
+ * reaches further back than the provider's archive, or into the future.
+ */
+export interface OutdoorTemperatureHistory {
+    /** Start of the requested interval in ISO format (inclusive) */
+    fromIso: string;
+    /** End of the requested interval in ISO format (exclusive) */
+    untilIso: string;
+    /** The resolution of the returned readings */
+    resolution: WeatherHistoryResolutionEnum;
+    /**
+     * Readings ordered by timestamp, one per bucket of
+     * {@link OutdoorTemperatureHistory.resolution}. Empty when the provider
+     * holds no data for the requested interval — this is a normal result, not
+     * an error.
+     */
+    readings: OutdoorTemperatureReading[];
+    /**
+     * Time-weighted mean temperature over the covered part of the interval, in
+     * degrees Celsius. Absent when {@link OutdoorTemperatureHistory.readings}
+     * is empty.
+     */
+    averageCelsius?: number;
+    /**
+     * Lowest temperature in degrees Celsius over the covered part of the
+     * interval. Absent when {@link OutdoorTemperatureHistory.readings} is
+     * empty.
+     */
+    minCelsius?: number;
+    /**
+     * Highest temperature in degrees Celsius over the covered part of the
+     * interval. Absent when {@link OutdoorTemperatureHistory.readings} is
+     * empty.
+     */
+    maxCelsius?: number;
+    /**
+     * Start of the part of the interval the provider could cover, in ISO
+     * format. Later than {@link OutdoorTemperatureHistory.fromIso} when the
+     * request reached further back than the archive goes. Absent when
+     * {@link OutdoorTemperatureHistory.readings} is empty.
+     */
+    coveredFromIso?: string;
+    /**
+     * End of the part of the interval the provider could cover, in ISO format.
+     * Earlier than {@link OutdoorTemperatureHistory.untilIso} when the request
+     * reached into the future or past the most recent observation. Absent when
+     * {@link OutdoorTemperatureHistory.readings} is empty.
+     */
+    coveredUntilIso?: string;
+}
+/**
+ * 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.
+ */
+export declare enum WeatherHistoryMeasureEnum {
+    /** Outdoor air temperature in degrees Celsius */
+    OutdoorTemperature = "outdoor-temperature",
+    /** Wind speed in meters per second */
+    WindSpeed = "wind-speed",
+    /** Cloud coverage area in percent */
+    CloudArea = "cloud-area",
+    /** Global horizontal irradiance in W/m² */
+    GlobalHorizontalIrradiance = "global-horizontal-irradiance",
+    /** Direct normal irradiance in W/m² */
+    DirectNormalIrradiance = "direct-normal-irradiance",
+    /** Diffuse horizontal irradiance in W/m² */
+    DiffuseHorizontalIrradiance = "diffuse-horizontal-irradiance",
+    /** Categorical weather symbol */
+    Symbol = "symbol"
+}
+/**
+ * A single observed weather data point.
+ *
+ * Every measure is optional: a reading only carries the quantities the
+ * provider holds and the request asked for. The field names and units mirror
+ * `WeatherForecastEntry` exactly, so an observed series and a forecast series
+ * can be concatenated into one timeline without translating between them.
+ */
+export interface WeatherHistoryReading {
+    /** Start of the bucket this reading applies to, in ISO format */
+    timestampIso: string;
+    /** Observed outdoor temperature in degrees Celsius */
+    outdoorTemperatureCelsius?: number;
+    /** Observed wind speed in meters per second */
+    windSpeedMs?: number;
+    /** Observed cloud coverage area as a percentage (0-100) */
+    cloudAreaPercent?: number;
+    /** Weather symbol describing the observed condition */
+    symbol?: EnyoWeatherSymbolEnum;
+    /**
+     * Global horizontal irradiance in W/m².
+     *
+     * Total shortwave radiation received by a horizontal surface — the sum of
+     * the diffuse part and the horizontal projection of the direct part
+     * (`GHI = DHI + DNI * cos(zenith)`). This is the quantity to correlate
+     * with measured PV production.
+     */
+    globalHorizontalIrradiance?: number;
+    /**
+     * Direct normal irradiance (DNI) in W/m².
+     *
+     * Beam radiation arriving from the direction of the sun, measured on a
+     * surface held perpendicular to the sun's rays. Together with
+     * {@link WeatherHistoryReading.diffuseHorizontalIrradiance} it allows
+     * transposing the observation onto an arbitrarily tilted plane (plane of
+     * array), which a single GHI value cannot do.
+     */
+    directNormalIrradiance?: number;
+    /**
+     * Diffuse horizontal irradiance (DHI) in W/m².
+     *
+     * The part of the radiation on a horizontal surface that has been
+     * scattered by the atmosphere and clouds, i.e. everything that did not
+     * arrive directly from the sun's disc. See
+     * {@link WeatherHistoryReading.directNormalIrradiance}.
+     */
+    diffuseHorizontalIrradiance?: number;
+}
+/**
+ * Aggregates of one numeric measure over the covered part of an interval.
+ */
+export interface WeatherHistoryStatistics {
+    /**
+     * Time-weighted mean of the measure over the covered interval, in the
+     * measure's own unit.
+     *
+     * For the irradiance measures this is a mean power density in W/m²;
+     * multiply by the covered duration in hours to get the received energy in
+     * Wh/m².
+     */
+    averageValue: number;
+    /** Lowest observed value of the measure, in the measure's own unit */
+    minValue: number;
+    /** Highest observed value of the measure, in the measure's own unit */
+    maxValue: number;
+}
+/**
+ * Request parameters for fetching observed weather for a time interval.
+ */
+export interface WeatherHistoryRequest extends WeatherHistoryIntervalRequest {
+    /**
+     * The measures to return. When omitted, the provider returns everything it
+     * holds for the interval.
+     */
+    measures?: WeatherHistoryMeasureEnum[];
+}
+/**
+ * Observed weather covering a requested time interval, across every requested
+ * measure.
+ *
+ * This is the general-purpose counterpart to {@link OutdoorTemperatureHistory}:
+ * same interval and coverage semantics, but each reading carries the full set
+ * of requested quantities instead of temperature alone.
+ */
+export interface WeatherHistory {
+    /** Start of the requested interval in ISO format (inclusive) */
+    fromIso: string;
+    /** End of the requested interval in ISO format (exclusive) */
+    untilIso: string;
+    /** The resolution of the returned readings */
+    resolution: WeatherHistoryResolutionEnum;
+    /** The measures actually contained in the readings */
+    measures: WeatherHistoryMeasureEnum[];
+    /**
+     * Readings ordered by timestamp, one per bucket of
+     * {@link WeatherHistory.resolution}. Empty when the provider holds no data
+     * for the requested interval — this is a normal result, not an error.
+     */
+    readings: WeatherHistoryReading[];
+    /**
+     * Aggregates per numeric measure over the covered part of the interval.
+     * {@link WeatherHistoryMeasureEnum.Symbol} is categorical and therefore
+     * never present here. Absent when {@link WeatherHistory.readings} is empty.
+     */
+    statistics?: Partial<Record<WeatherHistoryMeasureEnum, WeatherHistoryStatistics>>;
+    /**
+     * Start of the part of the interval the provider could cover, in ISO
+     * format. Later than {@link WeatherHistory.fromIso} when the request
+     * reached further back than the archive goes. Absent when
+     * {@link WeatherHistory.readings} is empty.
+     */
+    coveredFromIso?: string;
+    /**
+     * End of the part of the interval the provider could cover, in ISO format.
+     * Earlier than {@link WeatherHistory.untilIso} when the request reached
+     * into the future or past the most recent observation. Absent when
+     * {@link WeatherHistory.readings} is empty.
+     */
+    coveredUntilIso?: string;
+}

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

@@ -0,0 +1,40 @@
+/**
+ * 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.
+ */
+export var WeatherHistoryResolutionEnum;
+(function (WeatherHistoryResolutionEnum) {
+    /** 1-minute intervals */
+    WeatherHistoryResolutionEnum["OneMinute"] = "1min";
+    /** 15-minute intervals */
+    WeatherHistoryResolutionEnum["FifteenMinutes"] = "15min";
+    /** 1-hour intervals */
+    WeatherHistoryResolutionEnum["OneHour"] = "1hr";
+})(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.
+ */
+export 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 || (WeatherHistoryMeasureEnum = {}));

package/dist/version.d.ts

@@ -5,7 +5,7 @@
 /**
  * Current version of the enyo Energy App SDK.
  */
-export declare const SDK_VERSION = "1.20.0";
+export declare const SDK_VERSION = "1.21.0";
 /**
  * Gets the current SDK version.
  * @returns The semantic version string of the SDK

package/dist/version.js

@@ -5,7 +5,7 @@
 /**
  * Current version of the enyo Energy App SDK.
  */
-export const SDK_VERSION = '1.20.0';
+export const SDK_VERSION = '1.21.0';
 /**
  * Gets the current SDK version.
  * @returns The semantic version string of the SDK

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enyo-energy/energy-app-sdk",
-  "version": "1.20.0",
+  "version": "1.21.0",
   "description": "enyo Energy App SDK",
   "type": "module",
   "main": "dist/index.js",