@enyo-energy/energy-app-sdk 1.34.0 → 1.36.0

package/README.md

@@ -186,6 +186,8 @@ The SDK exposes several layered building blocks. Pick the one that matches the k
 | Query historical timeseries (PV, battery, meter, …) | [`useTimeseries()`](#usetimeseries-energyapptimeseries) |
 | Read site location (zip or coordinates) | [`useLocation()`](#uselocation-energyapplocation) |
 | Read grid connection point (fuse, phases, max power, charger limit) | [`useGridConnectionPoint()`](#usegridconnectionpoint-energyappgridconnectionpoint) |
+| Receive webhooks from third-party services (one URL per app, parsed JSON body) | [`useWebhook()`](#usewebhook-energyappwebhook) |
+| Sell one-time, monthly or yearly plans and check which ones the device has | [`useSubscriptions()`](#usesubscriptions-energyappsubscriptions) / [Subscription Plans](#subscription-plans) |
 | Retrieve secrets from the developer org secret store | [`useSecretManager()`](#usesecretmanager-energyappsecretmanager) |
 | Submit energy-manager diagnostics | [`useDiagnostics()`](#usediagnostics-energyappdiagnostics) |
 | Register a weather / PV / dynamic-price forecast provider | [`useWeatherForecasting()`](#useweatherforecasting-energyappweatherforecasting) / [`usePvForecasting()`](#usepvforecasting-energyapppvforecasting) / [`useDynamicPriceForecast()`](#usedynamicpriceforecast-energyappdynamicpriceforecast) |
@@ -242,6 +244,7 @@ energyApp.onShutdown(async () => {
 - `running`: App is functioning normally
 - `configuration-required`: App needs user configuration
 - `internet-connection-required`: App needs internet connectivity
+- `subscription-required`: App needs a subscription plan; the host shows the plans declared in the package definition
 
 ### Package Definition
 
@@ -384,6 +387,7 @@ Energy Apps use a granular permissions system to control access to system resour
 - **`Wifi`**: List known WiFi SSIDs
 - **`Udp`**: Bind UDP sockets and exchange datagrams
 - **`ChildProcess`**: Spawn child processes from the runtime
+- **`Webhook`**: Receive webhooks posted to the app's endpoint on the enyo API
 
 #### Data & Domain Permissions
 
@@ -401,6 +405,7 @@ Energy Apps use a granular permissions system to control access to system resour
 - **`EpexSpotPrices`**: Read EPEX SPOT day-ahead wholesale market prices
 - **`GridFeeRegister`** / **`GridFeeUse`**: Publish / resolve dynamic grid fees (time-variable network charges)
 - **`CommandLog`**: Record and read back the commands apps issued to appliances
+- **`Subscriptions`**: Read the subscriptions bought for the app on this device
 
 #### Site & Identity Permissions
 
@@ -1653,6 +1658,7 @@ A closed, SDK-defined set of user-facing controls the active energy manager hono
 | `BatteryPvPriorityTargetSocPercent` | number \| `null`, **%** target the battery is charged to from PV before other surplus consumers (absent / `null` = disabled) |
 | `BatteryDischargeBlockAboveHomeConsumptionW` | number \| `null`, **W** home consumption above which the battery may not discharge (absent / `null` = disabled) |
 | `HeatpumpControl` | boolean |
+| `HeatpumpEcoModeInExpensiveTimes` | boolean, off by default — switch the heat pump to its eco setpoint while electricity is expensive |
 | `HeatingRodControl` | boolean |
 | `HeatingRodMode` | `pv-surplus-only` \| `boost` |
 | `HeatingRodBatteryDischargeSocLimitPercent` | number \| `null`, **%** floor the battery may feed the heating rod down to (absent / `null` = disabled) |
@@ -1706,7 +1712,8 @@ Three things to get right:
 - **The heating rod may draw from the battery only down to a floor, and only when asked.** `HeatingRodBatteryDischargeSocLimitPercent` (`80` = the rod may use the battery while it holds more than 80 %) is disabled while absent or `null`. It applies under both heating rod modes — under `pv-surplus-only` the battery above the floor counts as supply alongside PV, still never a grid import. It needs `batteryControl` to be enforced, and should not lie below `BatteryPvPriorityTargetSocPercent`; the validator warns on both. A consumer held back by it carries the command reason `BatteryPvPriority` (category `PvSurplus`) with `context.batteryPvPriority.targetSocPercent` and `socPercent`.
 - **The battery can be blocked from discharging under a heavy load.** `BatteryDischargeBlockAboveHomeConsumptionW` (`11000` = no discharge while the house draws more than 11 kW) keeps a sauna or an oven from emptying the battery in minutes. It is in **watts** — the validator warns below 100 W, which catches a kW value. Home consumption means the household plus every appliance the energy manager does **not** track — the same quantity as `homeConsumptionW` in the home consumption timeseries. Tracked appliances (wallbox, heat pump, heating rod, …) and the battery's own charging are excluded, so a charging car alone never trips the block. The block wins over the EV and heating rod discharge permissions; charging is unaffected. Disabled while absent or `null`. A battery held by it carries `HomeConsumptionHigh` with `context.batteryDischargeBlock.thresholdW` and `powerW` set to the current consumption.
 - **Grid-optimised EV charging is about the grid, not the bill.** `GridOptimizedEvCharging` adds no charge mode. It only affects `cost-optimized` sessions while the tariff is static or time-of-use (no effect under a dynamic one): the grid energy PV does not cover is placed in the hours with the lowest EPEX spot price before the deadline — the spot price as a proxy for grid load — instead of as late as possible or in the tariff's cheap windows. PV still comes first, the deadline still holds, and a session's price ceiling still applies against the customer's own tariff. On a time-of-use tariff a low-load hour can be a more expensive one; that is the trade the owner opts into.
-- **Fifteen settings are gated by another** (`heatingRodMode` needs `heatingRodControl`, `priceLimitCtPerKwh` only applies under `priceLimitMode: 'ct-per-kwh'`, …). The tree is exported as `ENERGY_MANAGER_SETTING_DEPENDENCIES`, with two helpers over it: `getEnergyManagerSettingDependency(setting)` returns the direct gate and the value it must hold (or `null` for an ungated root), and `isEnergyManagerSettingActive(setting, values)` walks the whole chain — the gates are now two deep, so a Wh budget is live only when the mode is `fixed-wh` *and* battery control is on.
+- **Eco mode in expensive times switches setpoints, not temperatures.** `HeatpumpEcoModeInExpensiveTimes` (needs `heatpumpControl`) lets the energy manager send `HeatpumpProgramSwitchV3` with `mode: Eco` to every zone listing `eco` in `supportedProgramModes` while the tariff is expensive, and `mode: Program` once it is not. The user's own eco temperature applies (`programModeTemperaturesC`); the energy manager only chooses *when*. "Expensive" comes from the consumption tariff — the dearest slots under a dynamic tariff, the high-price windows under a time-of-use one; under a static tariff the setting has no effect, as it has on heat pumps without `ProgramSwitch`. Each such switch carries `ElectricityPriceAboveThreshold` (category `EnergyPrice`) with `electricityPricePerKwh`.
+- **Sixteen settings are gated by another** (`heatingRodMode` needs `heatingRodControl`, `priceLimitCtPerKwh` only applies under `priceLimitMode: 'ct-per-kwh'`, …). The tree is exported as `ENERGY_MANAGER_SETTING_DEPENDENCIES`, with two helpers over it: `getEnergyManagerSettingDependency(setting)` returns the direct gate and the value it must hold (or `null` for an ungated root), and `isEnergyManagerSettingActive(setting, values)` walks the whole chain — the gates are now two deep, so a Wh budget is live only when the mode is `fixed-wh` *and* battery control is on.
 - **`priceLimitCtPerKwh` is in cents**, unlike the SDK's machine-readable price fields (`electricityPricePerKwh`, EUR/kWh). Divide by 100 when comparing. `validateEnergyManagerSettingsState()` warns on values outside a plausible ct band, which catches the mix-up.
 - **A price ceiling is one mode plus its parameter**, the same shape as the battery-to-EV one. `PriceLimitMode` picks how the ceiling is expressed — an absolute `ct-per-kwh` or a relative `cheapest-share` — and each value is read only under its own mode; the mode being absent means no ceiling at all. A relative ceiling ranks the price intervals *known* for the day and treats the cheapest `n` % as importable (the same rule as the `cheapest-share-of-day` automation trigger), so its effective threshold moves when tomorrow's prices publish — re-evaluate it rather than resolving it once.
 
@@ -2247,6 +2254,68 @@ const failures = await commandLog.getCommands({
 
 Requires the `CommandLog` permission.
 
+#### `useWebhook(): EnergyAppWebhook`
+
+Receive webhooks from a vendor cloud. Apps run behind NAT on the hub, so every app gets **one** public
+endpoint on the enyo API instead; whatever JSON body is POSTed to it is forwarded to the app as a parsed object.
+
+```typescript
+const webhook = energyApp.useWebhook();
+
+const url = await webhook.getWebhookUrl();     // stable per app installation
+await vendorApi.subscribe({ callbackUrl: url });
+
+const listenerId = webhook.listenForWebhook<VendorEvent>(async (event) => {
+    // event: { webhookRequestId, source, receivedAtIso, body } — source defaults to 'custom-webhook'
+    await handleVendorEvent(event.body);   // already parsed JSON
+});
+```
+
+- **One endpoint per app.** Several event types share the same URL; tell them apart by the body.
+- **The body is already parsed.** `body` is the JSON object the caller sent. The type parameter is an
+  assertion, not validation — check the fields you rely on.
+- **At-least-once delivery.** A call may be forwarded more than once and order is not guaranteed —
+  deduplicate on `webhookRequestId`.
+
+Requires the `Webhook` permission.
+
+#### `useSubscriptions(): EnergyAppSubscriptions`
+
+Read the subscriptions a customer bought for this app **on this device**. The plans and their prices are
+declared in the package definition (see [Subscription Plans](#subscription-plans)); enyo handles checkout,
+billing, renewal and cancellation. The app never starts a purchase — it reads the result and reacts to it.
+
+```typescript
+import { isPlanActive } from '@enyo-energy/energy-app-sdk';
+
+const subscriptions = energyApp.useSubscriptions();
+
+// On boot: read the current state.
+applyPlan(isPlanActive(await subscriptions.getSubscriptions(), 'premium'));
+
+// Afterwards: purchases, renewals, cancellations, failed payments and expiry.
+subscriptions.listenForSubscriptionChanges(async ({ subscription, previousStatus }) => {
+    // previousStatus is undefined for a new subscription
+    applyPlan(isPlanActive(await subscriptions.getSubscriptions(), 'premium'));
+});
+```
+
+- **Use `isPlanActive()` / `isSubscriptionActive()`** instead of comparing statuses yourself. `trialing`, `active`,
+  `cancelled-until-period-end` and `grace` count as active; `expired` does not.
+- **`getSubscriptions()` returns expired subscriptions too**, so the app can tell "never bought" from "expired".
+- **The listener does not replay the current state.** Call `getSubscriptions()` on boot.
+- **Works offline.** The host keeps the last known state on the device and reports time-based changes (end of
+  trial, grace or paid period) without a connection.
+- **Fall back safely.** When a plan stops being active, release any control over appliances instead of leaving
+  them in the last commanded state.
+- **Point the user to an offer** with a notification target `{ type: 'subscription-offer', planKey: 'premium' }`,
+  or set `EnergyAppStateEnum.SubscriptionRequired` when the whole app needs a plan.
+
+For tests, `InMemorySubscriptions` implements the same interface; `upsertSubscription()` plays the part of enyo
+and notifies the listeners.
+
+Requires the `Subscriptions` permission.
+
 ### Operational Utilities
 
 #### `useOnboardingV2(): EnergyAppOnboardingV2`
@@ -2855,6 +2924,77 @@ It checks that names are unique slugs, that paths stay inside the package and ca
 extension, and that any declared MIME type is well formed; two names pointing at one
 path is a warning.
 
+## Subscription Plans
+
+Sell a one-time purchase or a monthly or yearly subscription for the whole app or for parts of it. Declare the plans, **including their prices**,
+in the package definition. The enyo CLI reads them during `enyo release`; enyo offers them to the customer and
+handles checkout, VAT, invoices, renewal and cancellation. Subscriptions belong to the **device** the app runs on.
+
+```typescript
+import {
+    defineEnergyAppPackage,
+    defineSubscriptionPlan,
+    EnergyAppPermissionTypeEnum,
+    EnyoCurrencyEnum,
+    EnyoSubscriptionPaymentIntervalEnum,
+    validatePackageSubscriptionPlans
+} from '@enyo-energy/energy-app-sdk';
+
+const packageDef = defineEnergyAppPackage({
+    // ...
+    permissions: [EnergyAppPermissionTypeEnum.Subscriptions /* , ... */],
+    subscriptionPlans: [
+        defineSubscriptionPlan({
+            planKey: 'premium',
+            paymentInterval: EnyoSubscriptionPaymentIntervalEnum.Yearly,
+            prices: [{ amountWithoutTax: 41.18, currency: EnyoCurrencyEnum.EUR }],
+            trialDays: 30,
+            storeEntry: [
+                {
+                    language: 'en',
+                    title: 'Premium',
+                    shortDescription: 'Optimises your heat pump with dynamic prices.',
+                    benefits: ['Dynamic price optimisation', 'Heat pump boost']
+                },
+                {
+                    language: 'de',
+                    title: 'Premium',
+                    shortDescription: 'Optimiert deine Wärmepumpe mit dynamischen Preisen.',
+                    benefits: ['Optimierung nach dynamischen Preisen', 'Wärmepumpen-Boost']
+                }
+            ]
+        })
+    ]
+});
+```
+
+| Field | Meaning |
+|---|---|
+| `planKey` | Kebab-case slug, unique in the package. Subscriptions refer to the plan by it — treat it as an API. |
+| `paymentInterval` | `one-time`, `monthly` or `yearly`. One-time purchases never renew and stay `active` until refunded. |
+| `prices` | One net price per currency. `amountWithoutTax` is always the **total for one interval** — per month, per year, or the single one-time amount — in the currency (not cent), at most two decimals; enyo adds VAT. |
+| `trialDays` | Optional free trial in days. Not allowed for `one-time` plans. |
+| `storeEntry` | Title, short description and optional benefits; `de` and `en` are required. |
+| `internalComment` | Optional note, never shown to users. |
+
+What a plan unlocks is decided by the app: check `isPlanActive(subscriptions, planKey)` at runtime (see
+[`useSubscriptions()`](#usesubscriptions-energyappsubscriptions)).
+
+**A price change needs a new release** and only applies to new purchases — running subscriptions keep the price
+they were bought at.
+
+Validate the plans before releasing:
+
+```typescript
+const { ok, errors } = validatePackageSubscriptionPlans(packageDef);
+// or: assertValidPackageSubscriptionPlans(packageDef) — throws PackageSubscriptionPlansValidationError
+```
+
+It checks that plan keys are unique slugs, that the payment interval is known, that every plan has at least one
+positive price per currency with at most two decimals, that `trialDays` is a positive whole number and not set on a
+`one-time` plan, that `de` and
+`en` store entries exist, and that the package requests the `Subscriptions` permission.
+
 ## Printable Manual Setup Guide
 
 A package can declare **one optional** onboarding guide (v2) as static data in its package
@@ -3216,6 +3356,7 @@ Switches one heating circuit or DHW zone to its **comfort** or **eco** setpoint
 - **One zone per message**, answered with a plain `CommandAcknowledgeV1`.
 - **Ending and safety net.** `mode: Program` ends a switch (idempotent). A switch to comfort or eco holds until `untilIso` (at most `HEATPUMP_PROGRAM_SWITCH_MAX_MINUTES` = 30 min ahead); the energy manager re-sends about every 15 min while it should hold. When `untilIso` passes without a newer message, the base class calls `handleHeatpumpProgramSwitch` with `mode: Program` and `cause: HeatpumpProgramSwitchCauseEnum.Expired` — so after a restart of either side a zone is back on its program within 30 min, and the app stores nothing.
 - **Alongside `HeatpumpControlV3`.** The two run side by side: the mode sets the base, an action raises above it (eco 20 °C + room action +1 K = 21 °C).
+- **Owner's consent for price-driven eco.** An energy manager switches zones to eco for price reasons only while the general setting `heatpumpEcoModeInExpensiveTimes` (and `heatpumpControl`) is `true` — see [General settings](#general-settings).
 - **Validation** (run by the base class before the handler, or `validateHeatpumpProgramSwitch(data, metadata)` directly): target `Room` / `Dhw`, a known mode, a valid `untilIso` for comfort / eco (`Rejected`); `ProgramSwitch` declared and the mode listed for the zone (`NotSupported`); a known zone index (`Rejected`).
 
 #### HeatpumpFlexibilityAnnouncementV3

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

@@ -2,6 +2,7 @@ import { EnergyAppPermissionType } from "./energy-app-permission.type.cjs";
 import { EnergyAppModelFeatureEnum } from "./energy-app-model-feature.enum.cjs";
 import type { EnyoFileTranslation } from "./types/enyo-file.cjs";
 import type { EnyoOnboardingV2Guide } from "./types/enyo-onboarding-v2.cjs";
+import type { EnyoSubscriptionPaymentInterval, EnyoSubscriptionPrice } from "./types/enyo-subscription.cjs";
 export type EnergyAppPackageLanguage = 'de' | 'en';
 export declare enum EnergyAppPackageCategory {
     Inverter = "inverter",
@@ -281,6 +282,74 @@ export interface EnergyAppPackageStoreEntry {
     /** Detailed description of the package functionality */
     description: string;
 }
+/**
+ * Localized store information for one subscription plan. Shown by enyo on the
+ * offer and checkout screens and in the customer's subscription overview.
+ */
+export interface EnergyAppPackageSubscriptionPlanStoreEntry {
+    /** Language code for this store entry */
+    language: EnergyAppPackageLanguage;
+    /** Display name of the plan, e.g. `'Premium'` */
+    title: string;
+    /** One sentence describing what the plan unlocks */
+    shortDescription: string;
+    /** Optional list of benefits, shown as bullet points on the offer screen */
+    benefits?: string[];
+}
+/**
+ * A subscription plan an Energy App package sells, declared in
+ * {@link EnergyAppPackageDefinition.subscriptionPlans}.
+ *
+ * A plan can unlock the whole app or only parts of it — the app decides that
+ * in its own code by checking whether the plan is active (see
+ * {@link EnergyAppSubscriptions}). enyo handles checkout, billing, renewal and
+ * cancellation; the plan only describes what is sold and at which price.
+ *
+ * The enyo CLI reads the plans at release time. A price change therefore
+ * requires a new release, and only applies to new purchases: running
+ * subscriptions keep the price they were bought at.
+ *
+ * @example
+ * ```typescript
+ * defineSubscriptionPlan({
+ *     planKey: 'premium',
+ *     paymentInterval: EnyoSubscriptionPaymentIntervalEnum.Yearly,
+ *     prices: [{amountWithoutTax: 41.18, currency: EnyoCurrencyEnum.EUR}],
+ *     trialDays: 30,
+ *     storeEntry: [
+ *         {language: 'en', title: 'Premium', shortDescription: 'Optimises your heat pump with dynamic prices.'},
+ *         {language: 'de', title: 'Premium', shortDescription: 'Optimiert deine Wärmepumpe mit dynamischen Preisen.'}
+ *     ]
+ * })
+ * ```
+ */
+export interface EnergyAppPackageSubscriptionPlan {
+    /**
+     * Stable, app-chosen key for this plan: a kebab-case slug, unique within
+     * the package. Subscriptions refer to the plan by this key, so treat it as
+     * an API — renaming it disconnects every existing subscription from the
+     * app's checks.
+     */
+    planKey: string;
+    /** How often the plan is paid for: `one-time`, `monthly` or `yearly`. */
+    paymentInterval: EnyoSubscriptionPaymentInterval;
+    /**
+     * Net price, one entry per currency. At least one entry is required. The
+     * amount is always the total for one interval: per month for `monthly`,
+     * per year for `yearly`, and the single amount for `one-time`.
+     */
+    prices: EnyoSubscriptionPrice[];
+    /**
+     * Optional length of a free trial in days. The customer is charged for the
+     * first time when the trial ends, unless they cancelled before. Not
+     * allowed for `one-time` plans.
+     */
+    trialDays?: number;
+    /** Localized store information. Entries for `de` and `en` are required. */
+    storeEntry: EnergyAppPackageSubscriptionPlanStoreEntry[];
+    /** Optional internal note explaining this plan; never shown to users. */
+    internalComment?: string;
+}
 /**
  * Defines a permission entry for an Energy App package.
  * Contains the permission type and an internal comment explaining its usage.
@@ -800,6 +869,19 @@ export interface EnergyAppPackageDefinition {
      * Omit the field for packages that have no manual setup to document.
      */
     onboardingGuide?: EnyoOnboardingV2Guide;
+    /**
+     * Subscription plans this package sells, including their prices. The enyo
+     * CLI reads them at release time; enyo offers them to the customer and
+     * handles checkout, billing, renewal and cancellation.
+     *
+     * Subscriptions belong to the device the app runs on. The app reads them
+     * at runtime through {@link EnergyAppSubscriptions}, which requires the
+     * `Subscriptions` permission. Validate the declarations with
+     * `validatePackageSubscriptionPlans()` before publishing.
+     *
+     * Omit for packages that are free.
+     */
+    subscriptionPlans?: EnergyAppPackageSubscriptionPlan[];
 }
 /**
  * Defines an Energy App package with automatic SDK version injection.

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

@@ -67,4 +67,6 @@ var EnergyAppPermissionTypeEnum;
     EnergyAppPermissionTypeEnum["CommandLog"] = "CommandLog";
     EnergyAppPermissionTypeEnum["Calibration"] = "Calibration";
     EnergyAppPermissionTypeEnum["VehicleIntegration"] = "VehicleIntegration";
+    EnergyAppPermissionTypeEnum["Webhook"] = "Webhook";
+    EnergyAppPermissionTypeEnum["Subscriptions"] = "Subscriptions";
 })(EnergyAppPermissionTypeEnum || (exports.EnergyAppPermissionTypeEnum = EnergyAppPermissionTypeEnum = {}));

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

@@ -62,7 +62,9 @@ export declare enum EnergyAppPermissionTypeEnum {
     GridFeeUse = "GridFeeUse",
     CommandLog = "CommandLog",
     Calibration = "Calibration",
-    VehicleIntegration = "VehicleIntegration"
+    VehicleIntegration = "VehicleIntegration",
+    Webhook = "Webhook",
+    Subscriptions = "Subscriptions"
 }
 /**
  * String union of every permission name, derived from

package/dist/cjs/energy-app.cjs

@@ -523,6 +523,35 @@ class EnergyApp {
     useCascade() {
         return this.energyAppSdk.useCascade();
     }
+    /**
+     * Gets the Webhook API for receiving webhooks from third-party services.
+     *
+     * Every app has exactly one webhook endpoint on the enyo API. Read its URL
+     * with `getWebhookUrl()`, hand it to the vendor, and every JSON body posted
+     * to it is forwarded as a parsed object to the listeners registered with
+     * `listenForWebhook()`.
+     * @returns The Webhook API instance
+     * @throws {EnergyAppPermissionNotGrantedError} If the `Webhook`
+     *         permission is not granted.
+     */
+    useWebhook() {
+        return this.energyAppSdk.useWebhook();
+    }
+    /**
+     * Gets the Subscriptions API for reading the subscriptions a customer
+     * bought for this app on this device.
+     *
+     * The plans and their prices are declared in the package definition;
+     * enyo handles checkout, billing, renewal and cancellation. The app reads
+     * the result with `getSubscriptions()` and reacts to purchases, renewals,
+     * cancellations and expiry with `listenForSubscriptionChanges()`.
+     * @returns The Subscriptions API instance
+     * @throws {EnergyAppPermissionNotGrantedError} If the `Subscriptions`
+     *         permission is not granted.
+     */
+    useSubscriptions() {
+        return this.energyAppSdk.useSubscriptions();
+    }
     /**
      * Gets the current SDK version.
      * @returns The semantic version string of the SDK

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

@@ -51,6 +51,8 @@ import { EnergyAppEpexSpotPrice } from "./packages/energy-app-epex-spot-price.cj
 import { EnergyAppGridFee } from "./packages/energy-app-grid-fee.cjs";
 import { EnergyAppCommandLog } from "./packages/energy-app-command-log.cjs";
 import { EnergyAppCascade } from "./packages/energy-app-cascade.cjs";
+import { EnergyAppWebhook } from "./packages/energy-app-webhook.cjs";
+import { EnergyAppSubscriptions } from "./packages/energy-app-subscriptions.cjs";
 import { UseFetchOptions } from "./types/enyo-fetch.cjs";
 /**
  * Concrete implementation of {@link EnyoEnergyAppSdk} that delegates every call
@@ -442,6 +444,31 @@ export declare class EnergyApp implements EnyoEnergyAppSdk {
      *         called method is not granted.
      */
     useCascade(): EnergyAppCascade;
+    /**
+     * Gets the Webhook API for receiving webhooks from third-party services.
+     *
+     * Every app has exactly one webhook endpoint on the enyo API. Read its URL
+     * with `getWebhookUrl()`, hand it to the vendor, and every JSON body posted
+     * to it is forwarded as a parsed object to the listeners registered with
+     * `listenForWebhook()`.
+     * @returns The Webhook API instance
+     * @throws {EnergyAppPermissionNotGrantedError} If the `Webhook`
+     *         permission is not granted.
+     */
+    useWebhook(): EnergyAppWebhook;
+    /**
+     * Gets the Subscriptions API for reading the subscriptions a customer
+     * bought for this app on this device.
+     *
+     * The plans and their prices are declared in the package definition;
+     * enyo handles checkout, billing, renewal and cancellation. The app reads
+     * the result with `getSubscriptions()` and reacts to purchases, renewals,
+     * cancellations and expiry with `listenForSubscriptionChanges()`.
+     * @returns The Subscriptions API instance
+     * @throws {EnergyAppPermissionNotGrantedError} If the `Subscriptions`
+     *         permission is not granted.
+     */
+    useSubscriptions(): EnergyAppSubscriptions;
     /**
      * Gets the current SDK version.
      * @returns The semantic version string of the SDK

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

@@ -9,4 +9,6 @@ var EnergyAppStateEnum;
     EnergyAppStateEnum["ConfigurationRequired"] = "configuration-required";
     /** This state tells the user that an internet connection of the system is required which blocks the energy app from running*/
     EnergyAppStateEnum["InternetConnectionRequired"] = "internet-connection-required";
+    /** This state tells the user that a subscription plan is required which blocks the energy app from running. The host shows the plans declared in the package definition. */
+    EnergyAppStateEnum["SubscriptionRequired"] = "subscription-required";
 })(EnergyAppStateEnum || (exports.EnergyAppStateEnum = EnergyAppStateEnum = {}));

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

@@ -50,6 +50,8 @@ import { EnergyAppEpexSpotPrice } from "./packages/energy-app-epex-spot-price.cj
 import { EnergyAppGridFee } from "./packages/energy-app-grid-fee.cjs";
 import { EnergyAppCommandLog } from "./packages/energy-app-command-log.cjs";
 import { EnergyAppCascade } from "./packages/energy-app-cascade.cjs";
+import { EnergyAppWebhook } from "./packages/energy-app-webhook.cjs";
+import { EnergyAppSubscriptions } from "./packages/energy-app-subscriptions.cjs";
 import { UseFetchOptions } from "./types/enyo-fetch.cjs";
 export declare enum EnergyAppStateEnum {
     Launching = "launching",
@@ -57,7 +59,9 @@ export declare enum EnergyAppStateEnum {
     /** This state tells the user that a configuration is required which blocks the energy app from running*/
     ConfigurationRequired = "configuration-required",
     /** This state tells the user that an internet connection of the system is required which blocks the energy app from running*/
-    InternetConnectionRequired = "internet-connection-required"
+    InternetConnectionRequired = "internet-connection-required",
+    /** This state tells the user that a subscription plan is required which blocks the energy app from running. The host shows the plans declared in the package definition. */
+    SubscriptionRequired = "subscription-required"
 }
 /**
  * Main API interface for enyo Energy App packages.
@@ -184,4 +188,8 @@ export interface EnyoEnergyAppSdk {
     useCommandLog: () => EnergyAppCommandLog;
     /** Get the Cascade API for the meter behind the primary meter: whether it is active, which appliances are behind it, and its own electricity tariff, prices and grid fee */
     useCascade: () => EnergyAppCascade;
+    /** Get the Webhook API for reading this app's single webhook URL on the enyo API and receiving the raw JSON bodies posted to it */
+    useWebhook: () => EnergyAppWebhook;
+    /** Get the Subscriptions API for reading the subscriptions bought for this app on this device and listening for new or changed subscriptions */
+    useSubscriptions: () => EnergyAppSubscriptions;
 }

package/dist/cjs/implementations/energy-manager-settings/energy-manager-settings-validators.cjs

@@ -208,7 +208,8 @@ function validateEnergyManagerSettingsState(state) {
     const values = state.values ?? {};
     // ── value formats ──────────────────────────────────────────────────────
     for (const key of ['batteryControl', 'batteryChargeFromGrid', 'heatpumpControl',
-        'heatingRodControl', 'chargerControl', 'gridOptimizedEvCharging']) {
+        'heatpumpEcoModeInExpensiveTimes', 'heatingRodControl', 'chargerControl',
+        'gridOptimizedEvCharging']) {
         if (values[key] !== undefined && typeof values[key] !== 'boolean') {
             errors.push(`\`${key}\` must be a boolean when set.`);
         }

package/dist/cjs/implementations/subscriptions/define-subscription-plan.cjs

@@ -0,0 +1,86 @@
+"use strict";
+/**
+ * Authoring and runtime helpers for subscription plans
+ * ({@link EnergyAppPackageDefinition.subscriptionPlans}).
+ *
+ * `defineSubscriptionPlan()` is an identity helper that type-checks a plan
+ * where it is written — mirroring `definePublicFile()` and
+ * `defineFirmwareFile()`. `isSubscriptionActive()` and `isPlanActive()` hold
+ * the single rule for which subscription statuses grant access, so every app
+ * applies it the same way.
+ *
+ * Pair with `validatePackageSubscriptionPlans()`
+ * (`./subscription-plan-validators.ts`) to fail fast before publishing.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ACTIVE_SUBSCRIPTION_STATUSES = void 0;
+exports.defineSubscriptionPlan = defineSubscriptionPlan;
+exports.isSubscriptionActive = isSubscriptionActive;
+exports.isPlanActive = isPlanActive;
+const enyo_subscription_js_1 = require("../../types/enyo-subscription.cjs");
+/**
+ * Subscription statuses in which the customer may use what a plan unlocks.
+ *
+ * A cancelled subscription stays usable until its paid period ends, and a
+ * subscription whose renewal payment failed stays usable during the grace
+ * period.
+ */
+exports.ACTIVE_SUBSCRIPTION_STATUSES = [
+    enyo_subscription_js_1.EnyoSubscriptionStatusEnum.Trialing,
+    enyo_subscription_js_1.EnyoSubscriptionStatusEnum.Active,
+    enyo_subscription_js_1.EnyoSubscriptionStatusEnum.CancelledUntilPeriodEnd,
+    enyo_subscription_js_1.EnyoSubscriptionStatusEnum.Grace,
+];
+/**
+ * Identity helper that type-checks a subscription plan at definition time
+ * (mirrors `defineEnergyAppPackage`). Prefer this over a bare object literal so
+ * mistakes surface where the plan is written.
+ *
+ * @param plan - The subscription plan to declare.
+ * @returns The same plan, typed as {@link EnergyAppPackageSubscriptionPlan}.
+ *
+ * @example
+ * ```typescript
+ * defineSubscriptionPlan({
+ *     planKey: 'premium',
+ *     paymentInterval: EnyoSubscriptionPaymentIntervalEnum.Yearly,
+ *     prices: [{amountWithoutTax: 41.18, currency: EnyoCurrencyEnum.EUR}],
+ *     storeEntry: [
+ *         {language: 'en', title: 'Premium', shortDescription: 'Optimises your heat pump with dynamic prices.'},
+ *         {language: 'de', title: 'Premium', shortDescription: 'Optimiert deine Wärmepumpe mit dynamischen Preisen.'}
+ *     ]
+ * })
+ * ```
+ */
+function defineSubscriptionPlan(plan) {
+    return plan;
+}
+/**
+ * Tests whether a subscription currently grants access, i.e. whether its
+ * status is one of {@link ACTIVE_SUBSCRIPTION_STATUSES}.
+ *
+ * @param subscription - The subscription to check.
+ * @returns True when the customer may use what the subscription's plan unlocks.
+ */
+function isSubscriptionActive(subscription) {
+    return exports.ACTIVE_SUBSCRIPTION_STATUSES.includes(subscription.status);
+}
+/**
+ * Tests whether the customer has an active subscription for a plan.
+ *
+ * @param subscriptions - The subscriptions, as returned by
+ *   {@link EnergyAppSubscriptions.getSubscriptions}.
+ * @param planKey - The {@link EnergyAppPackageSubscriptionPlan.planKey} to check.
+ * @returns True when at least one subscription for the plan is active.
+ *
+ * @example
+ * ```typescript
+ * const subscriptions = await energyApp.useSubscriptions().getSubscriptions();
+ * if (isPlanActive(subscriptions, 'premium')) {
+ *     enableOptimisation();
+ * }
+ * ```
+ */
+function isPlanActive(subscriptions, planKey) {
+    return subscriptions.some(subscription => subscription.planKey === planKey && isSubscriptionActive(subscription));
+}

package/dist/cjs/implementations/subscriptions/define-subscription-plan.d.cts

@@ -0,0 +1,70 @@
+/**
+ * Authoring and runtime helpers for subscription plans
+ * ({@link EnergyAppPackageDefinition.subscriptionPlans}).
+ *
+ * `defineSubscriptionPlan()` is an identity helper that type-checks a plan
+ * where it is written — mirroring `definePublicFile()` and
+ * `defineFirmwareFile()`. `isSubscriptionActive()` and `isPlanActive()` hold
+ * the single rule for which subscription statuses grant access, so every app
+ * applies it the same way.
+ *
+ * Pair with `validatePackageSubscriptionPlans()`
+ * (`./subscription-plan-validators.ts`) to fail fast before publishing.
+ */
+import type { EnergyAppPackageSubscriptionPlan } from '../../energy-app-package-definition.cjs';
+import { EnyoSubscription, EnyoSubscriptionStatus } from '../../types/enyo-subscription.cjs';
+/**
+ * Subscription statuses in which the customer may use what a plan unlocks.
+ *
+ * A cancelled subscription stays usable until its paid period ends, and a
+ * subscription whose renewal payment failed stays usable during the grace
+ * period.
+ */
+export declare const ACTIVE_SUBSCRIPTION_STATUSES: readonly EnyoSubscriptionStatus[];
+/**
+ * Identity helper that type-checks a subscription plan at definition time
+ * (mirrors `defineEnergyAppPackage`). Prefer this over a bare object literal so
+ * mistakes surface where the plan is written.
+ *
+ * @param plan - The subscription plan to declare.
+ * @returns The same plan, typed as {@link EnergyAppPackageSubscriptionPlan}.
+ *
+ * @example
+ * ```typescript
+ * defineSubscriptionPlan({
+ *     planKey: 'premium',
+ *     paymentInterval: EnyoSubscriptionPaymentIntervalEnum.Yearly,
+ *     prices: [{amountWithoutTax: 41.18, currency: EnyoCurrencyEnum.EUR}],
+ *     storeEntry: [
+ *         {language: 'en', title: 'Premium', shortDescription: 'Optimises your heat pump with dynamic prices.'},
+ *         {language: 'de', title: 'Premium', shortDescription: 'Optimiert deine Wärmepumpe mit dynamischen Preisen.'}
+ *     ]
+ * })
+ * ```
+ */
+export declare function defineSubscriptionPlan(plan: EnergyAppPackageSubscriptionPlan): EnergyAppPackageSubscriptionPlan;
+/**
+ * Tests whether a subscription currently grants access, i.e. whether its
+ * status is one of {@link ACTIVE_SUBSCRIPTION_STATUSES}.
+ *
+ * @param subscription - The subscription to check.
+ * @returns True when the customer may use what the subscription's plan unlocks.
+ */
+export declare function isSubscriptionActive(subscription: EnyoSubscription): boolean;
+/**
+ * Tests whether the customer has an active subscription for a plan.
+ *
+ * @param subscriptions - The subscriptions, as returned by
+ *   {@link EnergyAppSubscriptions.getSubscriptions}.
+ * @param planKey - The {@link EnergyAppPackageSubscriptionPlan.planKey} to check.
+ * @returns True when at least one subscription for the plan is active.
+ *
+ * @example
+ * ```typescript
+ * const subscriptions = await energyApp.useSubscriptions().getSubscriptions();
+ * if (isPlanActive(subscriptions, 'premium')) {
+ *     enableOptimisation();
+ * }
+ * ```
+ */
+export declare function isPlanActive(subscriptions: EnyoSubscription[], planKey: string): boolean;