@enyo-energy/energy-app-sdk 1.35.0 → 1.37.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
 
@@ -2249,6 +2254,81 @@ 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`.
+- **Hidden sources need a token.** Some webhook sources are only delivered to listeners that present their static
+  access token. Pass it per listener; the listener then receives these sources in addition to the public ones:
+
+  ```typescript
+  webhook.listenForWebhook<VendorEvent>(handleEvent, {
+      secretKeys: [{ source: 'vendor-cloud', token: vendorWebhookToken }]
+  });
+  ```
+
+  The token only applies to that listener, and a source with a wrong token is not delivered. Keep the token in the
+  secret manager, not in the source code.
+
+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.
+- **Per-unit plans:** report the units with `setUnits(planKey, units)` and check each one with
+  `isUnitActive(subscriptions, planKey, unit)` — see [Per-unit plans](#per-unit-plans).
+- **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`
@@ -2857,6 +2937,123 @@ 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. |
+| `pricingModel` | `per-package` (default): one price for the package on the device. `per-unit`: the price is charged per unit the app reports — see [Per-unit plans](#per-unit-plans). |
+| `prices` | One net price per currency. `amountWithoutTax` is always the **total for one interval** — per month, per year, or the single one-time amount; per unit for `per-unit` plans — 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)).
+
+### Per-unit plans
+
+For a `per-unit` plan the price is charged once per unit, and the **quantity comes from the energy app**. The app
+reports every unit it currently manages with `setUnits()` — on boot and whenever a unit is added or removed. Each
+unit has a `type` and a `referenceId` it is paid under:
+
+| `type` | `referenceId` | Name shown to the customer |
+|---|---|---|
+| `appliance` | the appliance id | taken from the appliance |
+| `vehicle` | the vehicle id | taken from the vehicle |
+| `custom` | an id chosen by the app | `name`, translated; `de` and `en` are required |
+
+```typescript
+import { EnyoSubscriptionUnitTypeEnum, isUnitActive } from '@enyo-energy/energy-app-sdk';
+
+const subscriptions = energyApp.useSubscriptions();
+const wallboxes = await energyApp.useAppliances().list();
+
+// 3 wallboxes on a yearly plan for 10 € → 30 € per year (net).
+await subscriptions.setUnits('smart-charging', wallboxes.map(wallbox => ({
+    type: EnyoSubscriptionUnitTypeEnum.Appliance,
+    referenceId: wallbox.id
+})));
+
+// A custom unit carries its own translated name.
+await subscriptions.setUnits('room-climate', [{
+    type: EnyoSubscriptionUnitTypeEnum.Custom,
+    referenceId: 'living-room',
+    name: [{ language: 'en', value: 'Living room' }, { language: 'de', value: 'Wohnzimmer' }]
+}]);
+
+// Only the units the customer paid for are active.
+const all = await subscriptions.getSubscriptions();
+for (const wallbox of wallboxes) {
+    setSmartCharging(wallbox, isUnitActive(all, 'smart-charging', { type: 'appliance', referenceId: wallbox.id }));
+}
+```
+
+- **Reporting a unit does not pay for it.** Paid units are listed in `subscription.units`; when the customer pays
+  for more units, the change listeners are called.
+- **Keep `referenceId` stable.** `type` plus `referenceId` identify the unit; a new reference is a new, unpaid unit.
+- **enyo decides how a changed quantity is charged**, e.g. pro rata for the rest of the period.
+- `validateSubscriptionUnits(units)` applies the host's rules up front: known type, non-empty reference, no unit
+  twice, `de` and `en` names on custom units.
+
+**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 and pricing model are 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

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, EnyoSubscriptionPricingModel } from "./types/enyo-subscription.cjs";
 export type EnergyAppPackageLanguage = 'de' | 'en';
 export declare enum EnergyAppPackageCategory {
     Inverter = "inverter",
@@ -281,6 +282,82 @@ 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;
+    /**
+     * Whether the price is charged once for the package on the device
+     * (`per-package`, the default) or once per unit (`per-unit`). For
+     * `per-unit` the app reports the units — appliances, vehicles or custom
+     * units — at runtime with {@link EnergyAppSubscriptions.setUnits}.
+     */
+    pricingModel?: EnyoSubscriptionPricingModel;
+    /**
+     * 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`. For a
+     * `per-unit` plan it is the amount per unit.
+     */
+    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 +877,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/subscriptions/define-subscription-plan.cjs

@@ -0,0 +1,124 @@
+"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; `isUnitActive()` applies it to one unit of a
+ * `per-unit` plan.
+ *
+ * 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;
+exports.isSameSubscriptionUnit = isSameSubscriptionUnit;
+exports.isUnitActive = isUnitActive;
+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));
+}
+/**
+ * Tests whether two units are the same unit, i.e. have the same `type` and
+ * `referenceId`. The name of a custom unit is not compared.
+ *
+ * @param a - The first unit.
+ * @param b - The second unit.
+ * @returns True when both identify the same unit.
+ */
+function isSameSubscriptionUnit(a, b) {
+    return a.type === b.type && a.referenceId === b.referenceId;
+}
+/**
+ * Tests whether one unit of a `per-unit` plan is paid for, i.e. whether an
+ * active subscription for the plan lists the unit in
+ * {@link EnyoSubscription.units}.
+ *
+ * @param subscriptions - The subscriptions, as returned by
+ *   {@link EnergyAppSubscriptions.getSubscriptions}.
+ * @param planKey - The {@link EnergyAppPackageSubscriptionPlan.planKey} to check.
+ * @param unit - The unit to check, identified by `type` and `referenceId`.
+ * @returns True when the unit is covered by an active subscription for the plan.
+ *
+ * @example
+ * ```typescript
+ * const subscriptions = await energyApp.useSubscriptions().getSubscriptions();
+ * if (isUnitActive(subscriptions, 'smart-charging', {type: 'appliance', referenceId: wallbox.id})) {
+ *     enableSmartCharging(wallbox);
+ * }
+ * ```
+ */
+function isUnitActive(subscriptions, planKey, unit) {
+    return subscriptions.some(subscription => subscription.planKey === planKey
+        && isSubscriptionActive(subscription)
+        && (subscription.units ?? []).some(paid => isSameSubscriptionUnit(paid, unit)));
+}