@enyo-energy/energy-app-sdk 1.37.0 → 1.39.0

package/README.md

@@ -244,7 +244,8 @@ 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
+- `subscription-required`: App needs a subscription plan; the host shows the plans declared in the package definition.
+  Only for packages with `subscriptionMode: 'required'` — see [Subscription mode](#subscription-mode)
 
 ### Package Definition
 
@@ -886,8 +887,10 @@ vehicles and it does not go looking for them — the flow starts with the user:
 ```typescript
 const vehicles = energyApp.useVehicle();
 
-vehicles.onPairVehicle(async (vehicle, selection) => {
-    const cars = await vendorApi.listVehicles();
+vehicles.onPairVehicle(async (vehicle, selection, context) => {
+    // The brand the user selected in the enyo app, from the package's `compatibility`
+    // vendors — lets an aggregator package pick the right vendor API.
+    const cars = await vendorApi.listVehicles(context?.vendorName);
 
     // Several cars in the account and nothing to tell them apart —
     // hand the choice back to the user instead of guessing
@@ -929,6 +932,9 @@ vehicles.onPairVehicle(async (vehicle, selection) => {
 
 The handler is called a second time with `selection` after the user picks from
 `candidates`. A package serving single-car accounts can ignore the parameter.
+`context.vendorName` is the vendor the user selected and is passed on both calls; it is
+also kept on the link (`EnyoLinkedVehicle.vendorName`) so the package can read it back
+after a restart.
 
 Once paired, the package has the `vehicleId` it was always missing and publishes
 readings the normal way — `VehicleSocUpdateV1`, keyed by that id. Nothing about
@@ -947,9 +953,11 @@ vehicles.onUnpairVehicle(async (link, reason) => {
     }
 });
 
-// The car vanished from the vendor account, or the subscription lapsed.
+// The car vanished from the vendor account, or the vendor revoked access.
 // Does NOT call onUnpairVehicle — the package already knows.
-await vehicles.unpairVehicle(vehicleId);
+// The reason decides how a billed car is billed — see "What a removal means for billing".
+await vehicles.unpairVehicle(vehicleId, EnyoVehiclePackageUnpairReasonEnum.VehicleNotFound);
+await vehicles.unpairVehicle(otherVehicleId, EnyoVehiclePackageUnpairReasonEnum.AccessRevoked);
 
 // Handlers only fire on change, so pick the links back up after a restart
 for (const link of await vehicles.listLinkedVehicles()) {
@@ -1282,32 +1290,150 @@ prices.onPriceChange((newPrice) => {
 
 #### `useNotification(): EnergyAppNotification`
 
-Send notifications to users:
+Send notifications to users. Every category must be registered before it is used; the host uses the category for the
+user's on/off switch and for rate limits.
 
 ```typescript
 const notifications = energyApp.useNotification();
 
-// Send info notification
-await notifications.sendNotification({
-    type: 'info',
-    title: 'Energy Optimization',
-    message: 'Your system is running optimally',
-    timestamp: Date.now()
+notifications.registerNotificationCategory({
+    category: 'connection-issue',
+    name: [
+        { language: 'en', name: 'Connection issue' },
+        { language: 'de', name: 'Verbindungsproblem' }
+    ]
 });
 
-// Send warning
-await notifications.sendNotification({
-    type: 'warning',
-    title: 'High Energy Consumption',
-    message: 'Consider reducing energy usage during peak hours'
-});
+const notificationId = notifications.sendNotification(
+    'connection-issue',
+    { applianceId, target: { type: 'appliance-settings', applianceId } },
+    [
+        { language: 'en', title: 'Inverter offline', body: 'Inverter communication lost - please check the connection.' },
+        { language: 'de', title: 'Wechselrichter offline', body: 'Keine Verbindung zum Wechselrichter - bitte Verbindung prüfen.' }
+    ]
+);
+```
+
+Categories:
+
+| Category | Use when |
+|---|---|
+| `connection-issue` | An appliance, gateway or upstream service is unreachable. |
+| `onboarding-required` | The user has to complete (or revisit) an onboarding flow. |
+| `charging-issue` | The app asked a charger to charge, but it is not charging. See [Charging issues](#charging-issues). |
+| `battery-issue` | The app commanded a battery, but it does not follow the command. See [Battery issues](#battery-issues). |
+| `authentication-required` | A sign-in that used to work was lost. See [Lost sign-in](#lost-sign-in). |
+
+Targets (`options.target`) decide where tapping the notification leads:
+
+| Target | Opens |
+|---|---|
+| `{ type: 'onboarding', onboardingName }` | A registered onboarding guide. |
+| `{ type: 'energy-app-settings' }` | The package's own settings. |
+| `{ type: 'appliance-settings', applianceId }` | The settings screen of an appliance. |
+| `{ type: 'appliance', applianceId }` | The live view of an appliance (current state, power and session). |
+| `{ type: 'authentication', applianceId? }` | The package's pending sign-in, created with `requestAuthentication()`. |
+| `{ type: 'subscription-offer', planKey }` | The offer screen for a subscription plan. |
+
+`sendNotification` throws an `EnyoNotificationSendError` with `type: 'not-registered'` if the category was not
+registered, or `type: 'rate-limit'` if the host's rate limit for the category is exceeded.
+
+##### Charging issues
+
+Only the app that decided a charger should charge knows that it should be charging, so the app sends
+`charging-issue` notifications. The host relies on these rules and does not re-check them. Send one only when
+**all** of the following hold:
+
+- The app itself asked the charger to charge: it sent a start or resume, or it is giving the charger more than 0 W.
+- The charger has stayed non-charging for at least 5 minutes after that request (status is not `Charging`, or it is
+  `Charging` but draws almost no power).
+- The charger is not `Suspended` with reason `EnyoChargerApplianceSuspendedReasonEnum.Ev`: the car is full or paused
+  charging itself, which is not a fault.
+- No grid-operator limit (§14a / `GridOperatorPowerLimitationV1`) is currently pushing the charger to 0.
+
+Send it **at most once per plug-in**: wait until the charger is `Available` again (car unplugged) before sending
+another one for that appliance. Always pass `applianceId` and the `appliance` target. The host drops more than one
+`charging-issue` per appliance per 30 minutes with a `rate-limit` error.
+
+```typescript
+const notification = energyApp.useNotification();
 
-// Send critical alert
-await notifications.sendNotification({
-    type: 'error',
-    title: 'System Fault',
-    message: 'Inverter communication lost - please check connection'
+notification.registerNotificationCategory({
+    category: 'charging-issue',
+    name: [
+        {language: 'de', name: 'Ladeprobleme'},
+        {language: 'en', name: 'Charging issues'},
+    ],
+    description: [
+        {language: 'de', name: 'Ladeprobleme', description: 'Wenn dein Auto nicht lädt, obwohl es laden sollte.'},
+        {language: 'en', name: 'Charging issues', description: 'When your car is not charging although it should.'},
+    ],
 });
+
+notification.sendNotification(
+    'charging-issue',
+    {applianceId, target: {type: 'appliance', applianceId}},
+    [
+        {language: 'de', title: 'Dein Auto lädt nicht', body: 'Die Wallbox sollte gerade laden, tut es aber nicht. Prüfe bitte Auto und Ladekabel.'},
+        {language: 'en', title: 'Your car is not charging', body: 'The wallbox should be charging right now but isn\'t. Please check the car and the charging cable.'},
+    ],
+);
+```
+
+##### Battery issues
+
+`battery-issue` follows the same idea for home batteries. Send one only when **all** of the following hold:
+
+- The app itself commanded the battery (`SetStorageControlV2` with mode `Controlled`, or one of the other storage
+  commands) and that command is still in effect. Never while the battery runs on `Auto`.
+- For at least 5 minutes the battery has not followed it, judged by `batteryPowerW` in `BatteryValuesUpdateV1`:
+  not charging on `Charge`, not discharging on `Discharge`, or moving power noticeably on `Hold`.
+- The battery is not simply at its limit: no charge command at or above `maxSoC` (or 100 %), no discharge command
+  at or below `minSoC`.
+- A discharge to the house is not just capped by low household consumption.
+- No grid-operator limit (§14a) is pushing the battery to 0, and `controlAllowed` is not `false`.
+
+Send it **at most once per issue**: wait until the battery follows a command again, or the app releases it to
+`Auto`, before sending another one. Always pass `applianceId` and the `appliance` target. The host drops more than
+one `battery-issue` per appliance per 30 minutes with a `rate-limit` error.
+
+```typescript
+notification.sendNotification(
+    'battery-issue',
+    {applianceId, target: {type: 'appliance', applianceId}},
+    [
+        {language: 'de', title: 'Dein Speicher reagiert nicht', body: 'Der Batteriespeicher folgt der Steuerung gerade nicht. Prüfe bitte, ob die externe Steuerung am Speicher aktiviert ist.'},
+        {language: 'en', title: 'Your battery is not responding', body: 'The home battery is not following the control right now. Please check that external control is enabled on the battery.'},
+    ],
+);
+```
+
+##### Lost sign-in
+
+`requestAuthentication()` already prompts the user, including for the first sign-in during onboarding.
+`authentication-required` is only for a sign-in that **used to work** and was lost. Send one only when:
+
+- The package was `Authenticated` before, the vendor now rejects the credentials or token, and a refresh failed.
+- The failure is not transient. Timeouts or a vendor outage are a `connection-issue`.
+- The user did not sign out themselves.
+
+Before sending, set the state with `setAuthenticationState()` and create a new request with
+`requestAuthentication()`, so the `authentication` target has a sign-in to open. Send it **at most once per lost
+session**, and not again until the package is `Authenticated` again. The host allows one per package (or per
+appliance, for an appliance sign-in) per 24 hours.
+
+```typescript
+await auth.setAuthenticationState({state: EnyoAuthenticationStateEnum.AuthenticationFailed});
+await auth.requestAuthentication({authenticationType: 'oauth', oauth: {}, oneTimeAuthentication: false});
+
+notification.sendNotification(
+    'authentication-required',
+    {target: {type: 'authentication'}},
+    [
+        {language: 'de', title: 'Bitte erneut anmelden', body: 'Deine Anmeldung ist abgelaufen. Melde dich erneut an, damit wir deine Geräte weiter steuern können.'},
+        {language: 'en', title: 'Please sign in again', body: 'Your sign-in has expired. Sign in again so we can keep controlling your devices.'},
+    ],
+);
 ```
 
 ### App Intelligence
@@ -2322,7 +2448,8 @@ subscriptions.listenForSubscriptionChanges(async ({ subscription, previousStatus
 - **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.
+  or set `EnergyAppStateEnum.SubscriptionRequired` when the whole app needs a plan (`subscriptionMode: 'required'`
+  only).
 
 For tests, `InMemorySubscriptions` implements the same interface; `upsertSubscription()` plays the part of enyo
 and notifies the listeners.
@@ -2949,6 +3076,7 @@ import {
     defineSubscriptionPlan,
     EnergyAppPermissionTypeEnum,
     EnyoCurrencyEnum,
+    EnyoSubscriptionModeEnum,
     EnyoSubscriptionPaymentIntervalEnum,
     validatePackageSubscriptionPlans
 } from '@enyo-energy/energy-app-sdk';
@@ -2956,6 +3084,7 @@ import {
 const packageDef = defineEnergyAppPackage({
     // ...
     permissions: [EnergyAppPermissionTypeEnum.Subscriptions /* , ... */],
+    subscriptionMode: EnyoSubscriptionModeEnum.Required,   // see "Subscription mode" below
     subscriptionPlans: [
         defineSubscriptionPlan({
             planKey: 'premium',
@@ -2985,7 +3114,7 @@ const packageDef = defineEnergyAppPackage({
 |---|---|
 | `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). |
+| `pricingModel` | `per-package` (default): one price for the package on the device. `per-unit`: the price is charged per unit — 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. |
@@ -2994,51 +3123,113 @@ const packageDef = defineEnergyAppPackage({
 What a plan unlocks is decided by the app: check `isPlanActive(subscriptions, planKey)` at runtime (see
 [`useSubscriptions()`](#usesubscriptions-energyappsubscriptions)).
 
+### Subscription mode
+
+As soon as a package declares `subscriptionPlans`, it must also declare `subscriptionMode`: does the app work
+without a plan at all? enyo uses it to decide what to offer — a free base option next to the plans, a downgrade to
+that base in the subscription management, and the wording of the cancellation and uninstall texts.
+
+| `subscriptionMode` | Meaning | App state without an active plan |
+|---|---|---|
+| `required` | The app sells its whole function; without a plan it does nothing useful. enyo offers no free option, and cancelling warns that the app stops working. | Reports `SubscriptionRequired`, and `Running` again once a plan is active. |
+| `optional` | The app has a free base; its plans add features. enyo offers the free base and lets the customer downgrade to it. | Keeps running. **Never** reports `SubscriptionRequired` — gate only the paid features with `isPlanActive()` / `isUnitActive()`. |
+
+```typescript
+defineEnergyAppPackage({
+    // ...
+    subscriptionMode: EnyoSubscriptionModeEnum.Optional,
+    subscriptionPlans: [/* price optimisation on top of free basic control */]
+});
+```
+
+In tests, `InMemorySubscriptions` takes the mode as its third constructor argument; `assertEnergyAppState(state)`
+throws when an `optional` package reports `SubscriptionRequired`. The same check is available as
+`assertEnergyAppStateMatchesSubscriptionMode(mode, state)`.
+
 ### 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:
+For a `per-unit` plan the price is charged once per unit — 3 units on a yearly plan for 10 € cost 30 € per year
+(net). 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 |
+| `appliance` | the enyo appliance id (`EnyoAppliance.id`) | taken from the appliance |
+| `vehicle` | the enyo vehicle id (`EnyoVehicle.id` = `EnyoLinkedVehicle.vehicleId`), **never** the vendor's `externalId` | taken from the vehicle |
 | `custom` | an id chosen by the app | `name`, translated; `de` and `en` are required |
 
+Where a unit comes from depends on its type:
+
+| Unit | How the app declares it | Who keeps the list |
+|---|---|---|
+| Appliance | `billing: { billed: true, planKey }` on the appliance it saves | The host — added on save, removed when the appliance is removed or the mark is cleared |
+| Vehicle | `billing: { billed: true, planKey }` in the pair result | The host — added on pairing, removed on unpairing |
+| Custom | `setUnits(planKey, units)` — on boot and whenever one is added or removed | The app |
+
+Marking appliances and vehicles where they are created keeps the billed units in step with what is actually
+connected, gives every unit the right enyo id, and lets the host bill a removal by its reason (see below). An app
+that also creates appliances it doesn't bill, such as a meter next to the heat pump, simply leaves `billing` off
+them. `onUnpairVehicle` and `listenForApplianceRemoved` then only need to stop serving the unit. `billing.planKey`
+must name a `per-unit` plan of the package; check it with `validateSubscriptionBilling(billing, plans)`.
+
+```typescript
+// A heat pump billed per unit; the meter the app also creates is not billed.
+await energyApp.useAppliances().save({
+    ...heatpump,
+    billing: { billed: true, planKey: 'heatpump-optimisation' }
+});
+await energyApp.useAppliances().save(meter);
+
+// A car billed per unit, marked in the pair result.
+vehicles.onPairVehicle(async (vehicle, selection) => ({
+    paired: true,
+    externalId: car.id,
+    billing: { billed: true, planKey: 'smartcar-vehicle' }
+}));
+```
+
+For anything else, report custom units yourself. `setUnits()` only takes custom units:
+
 ```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.
+// Whatever the type: 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 }));
-}
+setClimateControl('living-room', isUnitActive(all, 'room-climate', { type: 'custom', referenceId: 'living-room' }));
+setOptimisation(heatpump, isUnitActive(all, 'heatpump-optimisation', { type: 'appliance', referenceId: heatpump.id }));
 ```
 
+`getUnits(planKey)` returns all units of a plan — the billed appliances and vehicles plus the custom units.
+
 - **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.
+  for more units, or a unit is removed, 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.
 
+#### What a removal means for billing
+
+The host decides, never the app's unit list:
+
+| Unit leaves because… | Billing |
+|---|---|
+| The customer confirmed „Trennen" / „Entfernen" in the enyo app (vehicle unpaired by the user, appliance removed by the user) | The quantity drops at the next renewal; removing the last unit cancels the subscription at the end of the period. Nothing is refunded. |
+| The vehicle was deleted in the enyo app | Same as above. |
+| The app unlinked the car because it is gone from the vendor account — `unpairVehicle(id, EnyoVehiclePackageUnpairReasonEnum.VehicleNotFound)` | Same as above. |
+| Vendor sign-out | **Unchanged.** Usually followed by signing in again; a paid unit stays paid. |
+| The app unlinked the car because the vendor revoked access — `unpairVehicle(id, EnyoVehiclePackageUnpairReasonEnum.AccessRevoked)` | Unchanged — access is usually granted again. |
+| Unknown reason, `unpairVehicle()` without a reason, or the app's own report shrinks | Unchanged. |
+
+A shorter unit list alone — an expired token, an app bug — never cancels anything a customer paid for. Every
+change takes effect at the next renewal or at the end of the paid period; there are no pro-rata refunds.
+
 **A price change needs a new release** and only applies to new purchases — running subscriptions keep the price
 they were bought at.
 
@@ -3049,10 +3240,10 @@ 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.
+It checks that `subscriptionMode` is declared, 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. A `subscriptionMode` without plans is a warning.
 
 ## Printable Manual Setup Guide
 

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

@@ -2,7 +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";
+import type { EnyoSubscriptionMode, EnyoSubscriptionPaymentInterval, EnyoSubscriptionPrice, EnyoSubscriptionPricingModel } from "./types/enyo-subscription.cjs";
 export type EnergyAppPackageLanguage = 'de' | 'en';
 export declare enum EnergyAppPackageCategory {
     Inverter = "inverter",
@@ -336,8 +336,10 @@ export interface EnergyAppPackageSubscriptionPlan {
     /**
      * 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}.
+     * `per-unit` the units are the appliances and vehicles the app marks as
+     * billed under this plan ({@link EnyoAppliance.billing},
+     * {@link EnyoVehiclePairResult.billing}), plus the custom units it reports
+     * with {@link EnergyAppSubscriptions.setUnits}.
      */
     pricingModel?: EnyoSubscriptionPricingModel;
     /**
@@ -890,6 +892,20 @@ export interface EnergyAppPackageDefinition {
      * Omit for packages that are free.
      */
     subscriptionPlans?: EnergyAppPackageSubscriptionPlan[];
+    /**
+     * Whether the app needs one of its plans to work at all.
+     *
+     * - `'required'`: without an active plan the app does nothing useful and
+     *   reports {@link EnergyAppStateEnum.SubscriptionRequired}. enyo offers no
+     *   free option, and cancelling warns that the app stops working.
+     * - `'optional'`: the app has a free base; its plans add features. The app
+     *   never reports `SubscriptionRequired`. enyo offers a free base option
+     *   and lets the customer downgrade to it.
+     *
+     * Required as soon as {@link subscriptionPlans} is set; omit it for free
+     * packages.
+     */
+    subscriptionMode?: EnyoSubscriptionMode;
 }
 /**
  * Defines an Energy App package with automatic SDK version injection.

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

@@ -9,6 +9,12 @@ 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. */
+    /**
+     * 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.
+     *
+     * Only for packages with `subscriptionMode: 'required'`: such an app reports this state while it has no active
+     * plan, and returns to `Running` once one is active. An app with `subscriptionMode: 'optional'` must never report
+     * it — it keeps its free base running and gates only the paid features with `isPlanActive()` / `isUnitActive()`.
+     */
     EnergyAppStateEnum["SubscriptionRequired"] = "subscription-required";
 })(EnergyAppStateEnum || (exports.EnergyAppStateEnum = EnergyAppStateEnum = {}));

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

@@ -60,7 +60,13 @@ export declare enum 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*/
     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. */
+    /**
+     * 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.
+     *
+     * Only for packages with `subscriptionMode: 'required'`: such an app reports this state while it has no active
+     * plan, and returns to `Running` once one is active. An app with `subscriptionMode: 'optional'` must never report
+     * it — it keeps its free base running and gates only the paid features with `isPlanActive()` / `isUnitActive()`.
+     */
     SubscriptionRequired = "subscription-required"
 }
 /**

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

@@ -11,7 +11,9 @@ const subscription_plan_validators_js_1 = require("./subscription-plan-validator
  * {@link upsertSubscription} simulates a purchase, renewal, cancellation,
  * failed payment or expiry and notifies the registered listeners exactly like
  * the host would. Units reported with {@link setUnits} are kept per plan and
- * can be read back with {@link getUnits}.
+ * can be read back with {@link getUnits}, together with the billed appliance
+ * and vehicle units a test sets with {@link setBilledUnits}. {@link assertEnergyAppState}
+ * checks a reported app state against the package's subscription mode.
  *
  * @example
  * ```typescript
@@ -34,52 +36,92 @@ const subscription_plan_validators_js_1 = require("./subscription-plan-validator
  */
 class InMemorySubscriptions {
     plans;
+    subscriptionMode;
     subscriptions = new Map();
     listeners = new Map();
-    unitsByPlan = new Map();
+    customUnitsByPlan = new Map();
+    billedUnitsByPlan = new Map();
     nextListenerId = 1;
     /**
      * @param initialSubscriptions - Subscriptions that exist before the app
      *   starts. They do not trigger listeners.
-     * @param plans - Optional plans of the package. When given, {@link setUnits}
-     *   rejects plan keys that are not declared as `per-unit`, like the host
-     *   does. When omitted, every plan key is accepted.
+     * @param plans - Optional plans of the package. When given,
+     *   {@link setUnits} and {@link setBilledUnits} reject plan keys that are
+     *   not declared as `per-unit`, like the host does. When omitted, every
+     *   plan key is accepted.
+     * @param subscriptionMode - Optional subscription mode of the package,
+     *   checked by {@link assertEnergyAppState}.
      */
-    constructor(initialSubscriptions = [], plans) {
+    constructor(initialSubscriptions = [], plans, subscriptionMode) {
         this.plans = plans;
+        this.subscriptionMode = subscriptionMode;
         for (const subscription of initialSubscriptions) {
             this.subscriptions.set(subscription.subscriptionId, structuredClone(subscription));
         }
     }
     /**
-     * Stores the units reported for a `per-unit` plan, replacing earlier ones.
+     * Stores the custom units reported for a `per-unit` plan, replacing
+     * earlier ones.
      *
      * @param planKey - The key of the plan.
-     * @param units - Every unit the app currently manages for the plan.
+     * @param units - Every custom unit the app currently manages for the plan.
      * @returns Promise that resolves once the units are stored
-     * @throws {Error} If the units are invalid, or `plans` were given and
-     *   `planKey` is not a `per-unit` plan among them.
+     * @throws {Error} If a unit is not a custom unit or invalid, or `plans`
+     *   were given and `planKey` is not a `per-unit` plan among them.
      */
     async setUnits(planKey, units) {
-        if (this.plans) {
-            const plan = this.plans.find(candidate => candidate.planKey === planKey);
-            if (plan?.pricingModel !== enyo_subscription_js_1.EnyoSubscriptionPricingModelEnum.PerUnit) {
-                throw new Error(`Plan "${planKey}" is not a per-unit plan of this package.`);
-            }
+        this.assertPerUnitPlan(planKey);
+        const notCustom = units.filter(unit => unit.type !== enyo_subscription_js_1.EnyoSubscriptionUnitTypeEnum.Custom);
+        if (notCustom.length > 0) {
+            throw new Error(`setUnits() only takes custom units — mark appliances and vehicles with \`billing\` instead (got ${notCustom.map(unit => unit.type).join(', ')}).`);
         }
-        const { ok, errors } = (0, subscription_plan_validators_js_1.validateSubscriptionUnits)(units);
-        if (!ok)
-            throw new Error(`Invalid subscription units:\n- ${errors.join('\n- ')}`);
-        this.unitsByPlan.set(planKey, units.map(unit => structuredClone(unit)));
+        this.assertValidUnits(units);
+        this.customUnitsByPlan.set(planKey, units.map(unit => structuredClone(unit)));
+    }
+    /**
+     * Test helper: sets the appliance and vehicle units the host keeps for a
+     * plan from their billing marks, replacing earlier ones — as if the app
+     * had saved those appliances or paired those vehicles with
+     * `billing: {billed: true, planKey}`.
+     *
+     * @param planKey - The key of the plan.
+     * @param units - The billed appliance and vehicle units.
+     * @returns Promise that resolves once the units are stored
+     * @throws {Error} If a unit is a custom unit or invalid, or `plans` were
+     *   given and `planKey` is not a `per-unit` plan among them.
+     */
+    async setBilledUnits(planKey, units) {
+        this.assertPerUnitPlan(planKey);
+        if (units.some(unit => unit.type === enyo_subscription_js_1.EnyoSubscriptionUnitTypeEnum.Custom)) {
+            throw new Error('setBilledUnits() only takes appliance and vehicle units — report custom units with setUnits().');
+        }
+        this.assertValidUnits(units);
+        this.billedUnitsByPlan.set(planKey, units.map(unit => structuredClone(unit)));
+    }
+    /**
+     * Test helper: checks an app state against the subscription mode given to
+     * the constructor. Call it wherever the app under test reports its state.
+     *
+     * @param state - The state the app reports.
+     * @throws {Error} When the package's subscription mode is `optional` and
+     *   the state is `subscription-required`.
+     */
+    assertEnergyAppState(state) {
+        (0, subscription_plan_validators_js_1.assertEnergyAppStateMatchesSubscriptionMode)(this.subscriptionMode, state);
     }
     /**
-     * Returns copies of the units last reported for a plan.
+     * Returns copies of the current units of a plan: the billed appliances and
+     * vehicles set with {@link setBilledUnits}, followed by the custom units
+     * reported with {@link setUnits}.
      *
      * @param planKey - The key of the plan.
      * @returns Promise that resolves to the units; an empty list when none were reported
      */
     async getUnits(planKey) {
-        return (this.unitsByPlan.get(planKey) ?? []).map(unit => structuredClone(unit));
+        return [
+            ...(this.billedUnitsByPlan.get(planKey) ?? []),
+            ...(this.customUnitsByPlan.get(planKey) ?? []),
+        ].map(unit => structuredClone(unit));
     }
     /**
      * Returns copies of all stored subscriptions.
@@ -130,5 +172,29 @@ class InMemorySubscriptions {
             await listener({ subscription: structuredClone(subscription), previousStatus });
         }
     }
+    /**
+     * Throws when `plans` were given and `planKey` is not a `per-unit` plan
+     * among them.
+     *
+     * @param planKey - The key of the plan.
+     */
+    assertPerUnitPlan(planKey) {
+        if (!this.plans)
+            return;
+        const plan = this.plans.find(candidate => candidate.planKey === planKey);
+        if (plan?.pricingModel !== enyo_subscription_js_1.EnyoSubscriptionPricingModelEnum.PerUnit) {
+            throw new Error(`Plan "${planKey}" is not a per-unit plan of this package.`);
+        }
+    }
+    /**
+     * Throws when the units break the host's rules.
+     *
+     * @param units - The units to check.
+     */
+    assertValidUnits(units) {
+        const { ok, errors } = (0, subscription_plan_validators_js_1.validateSubscriptionUnits)(units);
+        if (!ok)
+            throw new Error(`Invalid subscription units:\n- ${errors.join('\n- ')}`);
+    }
 }
 exports.InMemorySubscriptions = InMemorySubscriptions;