@enyo-energy/energy-app-sdk 1.35.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
 
@@ -2249,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`
@@ -2857,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

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/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;

package/dist/cjs/implementations/subscriptions/in-memory-subscriptions.cjs

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InMemorySubscriptions = void 0;
+/**
+ * In-memory implementation of {@link EnergyAppSubscriptions} for tests and
+ * local development.
+ *
+ * It holds the subscriptions in memory and lets a test play the part of enyo:
+ * {@link upsertSubscription} simulates a purchase, renewal, cancellation,
+ * failed payment or expiry and notifies the registered listeners exactly like
+ * the host would.
+ *
+ * @example
+ * ```typescript
+ * const subscriptions = new InMemorySubscriptions();
+ * const app = new MyApp(subscriptions);
+ *
+ * await subscriptions.upsertSubscription({
+ *     subscriptionId: 'sub-1',
+ *     planKey: 'premium',
+ *     status: EnyoSubscriptionStatusEnum.Active,
+ *     paymentInterval: EnyoSubscriptionPaymentIntervalEnum.Yearly,
+ *     price: {amountWithoutTax: 41.18, currency: EnyoCurrencyEnum.EUR},
+ *     startedAtIso: '2026-01-01T00:00:00Z',
+ *     currentPeriodStartIso: '2026-01-01T00:00:00Z',
+ *     currentPeriodEndIso: '2027-01-01T00:00:00Z'
+ * });
+ * expect(app.isOptimising()).toBe(true);
+ * ```
+ */
+class InMemorySubscriptions {
+    subscriptions = new Map();
+    listeners = new Map();
+    nextListenerId = 1;
+    /**
+     * @param initialSubscriptions - Subscriptions that exist before the app
+     *   starts. They do not trigger listeners.
+     */
+    constructor(initialSubscriptions = []) {
+        for (const subscription of initialSubscriptions) {
+            this.subscriptions.set(subscription.subscriptionId, { ...subscription });
+        }
+    }
+    /**
+     * Returns copies of all stored subscriptions.
+     *
+     * @returns Promise that resolves to the subscriptions in insertion order
+     */
+    async getSubscriptions() {
+        return [...this.subscriptions.values()].map(subscription => ({ ...subscription }));
+    }
+    /**
+     * Registers a listener for new or changed subscriptions.
+     *
+     * @param listener - Callback invoked by {@link upsertSubscription}.
+     * @returns The listener ID, to be passed to {@link removeListener}
+     */
+    listenForSubscriptionChanges(listener) {
+        const listenerId = `subscription-listener-${this.nextListenerId++}`;
+        this.listeners.set(listenerId, listener);
+        return listenerId;
+    }
+    /**
+     * Removes a listener previously registered with
+     * {@link listenForSubscriptionChanges}.
+     *
+     * @param listenerId - The ID returned by {@link listenForSubscriptionChanges}
+     */
+    removeListener(listenerId) {
+        this.listeners.delete(listenerId);
+    }
+    /**
+     * Removes every registered listener.
+     */
+    removeAllListeners() {
+        this.listeners.clear();
+    }
+    /**
+     * Test helper: creates or replaces a subscription, keyed by
+     * {@link EnyoSubscription.subscriptionId}, and notifies every listener —
+     * with `previousStatus` unset for a new subscription.
+     *
+     * @param subscription - The subscription as it is after the change.
+     * @returns Promise that resolves once every listener has completed
+     */
+    async upsertSubscription(subscription) {
+        const previousStatus = this.subscriptions.get(subscription.subscriptionId)?.status;
+        this.subscriptions.set(subscription.subscriptionId, { ...subscription });
+        for (const listener of [...this.listeners.values()]) {
+            await listener({ subscription: { ...subscription }, previousStatus });
+        }
+    }
+}
+exports.InMemorySubscriptions = InMemorySubscriptions;