@enyo-energy/energy-app-sdk 1.36.0 → 1.38.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()) {
@@ -2276,6 +2284,17 @@ const listenerId = webhook.listenForWebhook<VendorEvent>(async (event) => {
   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.
 
@@ -2308,8 +2327,11 @@ subscriptions.listenForSubscriptionChanges(async ({ subscription, previousStatus
   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.
+  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.
@@ -2936,6 +2958,7 @@ import {
     defineSubscriptionPlan,
     EnergyAppPermissionTypeEnum,
     EnyoCurrencyEnum,
+    EnyoSubscriptionModeEnum,
     EnyoSubscriptionPaymentIntervalEnum,
     validatePackageSubscriptionPlans
 } from '@enyo-energy/energy-app-sdk';
@@ -2943,6 +2966,7 @@ import {
 const packageDef = defineEnergyAppPackage({
     // ...
     permissions: [EnergyAppPermissionTypeEnum.Subscriptions /* , ... */],
+    subscriptionMode: EnyoSubscriptionModeEnum.Required,   // see "Subscription mode" below
     subscriptionPlans: [
         defineSubscriptionPlan({
             planKey: 'premium',
@@ -2972,7 +2996,8 @@ 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. |
-| `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. |
+| `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. |
 | `internalComment` | Optional note, never shown to users. |
@@ -2980,6 +3005,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 — 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 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();
+
+await subscriptions.setUnits('room-climate', [{
+    type: EnyoSubscriptionUnitTypeEnum.Custom,
+    referenceId: 'living-room',
+    name: [{ language: 'en', value: 'Living room' }, { language: 'de', value: 'Wohnzimmer' }]
+}]);
+
+// Whatever the type: only the units the customer paid for are active.
+const all = await subscriptions.getSubscriptions();
+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, 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.
+- `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.
 
@@ -2990,10 +3122,10 @@ 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.
+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 } 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",
@@ -333,10 +333,20 @@ export interface EnergyAppPackageSubscriptionPlan {
     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 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;
     /**
      * 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`.
+     * per year for `yearly`, and the single amount for `one-time`. For a
+     * `per-unit` plan it is the amount per unit.
      */
     prices: EnyoSubscriptionPrice[];
     /**
@@ -882,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/define-subscription-plan.cjs

@@ -7,7 +7,8 @@
  * 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.
+ * 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.
@@ -17,6 +18,8 @@ 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.
@@ -84,3 +87,38 @@ function isSubscriptionActive(subscription) {
 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)));
+}

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

@@ -6,13 +6,14 @@
  * 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.
+ * 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.
  */
 import type { EnergyAppPackageSubscriptionPlan } from '../../energy-app-package-definition.cjs';
-import { EnyoSubscription, EnyoSubscriptionStatus } from '../../types/enyo-subscription.cjs';
+import { EnyoSubscription, EnyoSubscriptionStatus, EnyoSubscriptionUnit } from '../../types/enyo-subscription.cjs';
 /**
  * Subscription statuses in which the customer may use what a plan unlocks.
  *
@@ -68,3 +69,32 @@ export declare function isSubscriptionActive(subscription: EnyoSubscription): bo
  * ```
  */
 export declare function isPlanActive(subscriptions: EnyoSubscription[], planKey: string): boolean;
+/**
+ * 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.
+ */
+export declare function isSameSubscriptionUnit(a: Pick<EnyoSubscriptionUnit, 'type' | 'referenceId'>, b: Pick<EnyoSubscriptionUnit, 'type' | 'referenceId'>): boolean;
+/**
+ * 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);
+ * }
+ * ```
+ */
+export declare function isUnitActive(subscriptions: EnyoSubscription[], planKey: string, unit: Pick<EnyoSubscriptionUnit, 'type' | 'referenceId'>): boolean;

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

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.InMemorySubscriptions = void 0;
+const enyo_subscription_js_1 = require("../../types/enyo-subscription.cjs");
+const subscription_plan_validators_js_1 = require("./subscription-plan-validators.cjs");
 /**
  * In-memory implementation of {@link EnergyAppSubscriptions} for tests and
  * local development.
@@ -8,7 +10,10 @@ exports.InMemorySubscriptions = void 0;
  * 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.
+ * the host would. Units reported with {@link setUnits} are kept per plan and
+ * 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
@@ -20,6 +25,7 @@ exports.InMemorySubscriptions = void 0;
  *     planKey: 'premium',
  *     status: EnyoSubscriptionStatusEnum.Active,
  *     paymentInterval: EnyoSubscriptionPaymentIntervalEnum.Yearly,
+ *     pricingModel: EnyoSubscriptionPricingModelEnum.PerPackage,
  *     price: {amountWithoutTax: 41.18, currency: EnyoCurrencyEnum.EUR},
  *     startedAtIso: '2026-01-01T00:00:00Z',
  *     currentPeriodStartIso: '2026-01-01T00:00:00Z',
@@ -29,25 +35,101 @@ exports.InMemorySubscriptions = void 0;
  * ```
  */
 class InMemorySubscriptions {
+    plans;
+    subscriptionMode;
     subscriptions = new Map();
     listeners = 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} 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 = []) {
+    constructor(initialSubscriptions = [], plans, subscriptionMode) {
+        this.plans = plans;
+        this.subscriptionMode = subscriptionMode;
         for (const subscription of initialSubscriptions) {
-            this.subscriptions.set(subscription.subscriptionId, { ...subscription });
+            this.subscriptions.set(subscription.subscriptionId, structuredClone(subscription));
         }
     }
+    /**
+     * Stores the custom units reported for a `per-unit` plan, replacing
+     * earlier ones.
+     *
+     * @param planKey - The key of 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 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) {
+        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(', ')}).`);
+        }
+        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 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.billedUnitsByPlan.get(planKey) ?? []),
+            ...(this.customUnitsByPlan.get(planKey) ?? []),
+        ].map(unit => structuredClone(unit));
+    }
     /**
      * 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 }));
+        return [...this.subscriptions.values()].map(subscription => structuredClone(subscription));
     }
     /**
      * Registers a listener for new or changed subscriptions.
@@ -85,10 +167,34 @@ class InMemorySubscriptions {
      */
     async upsertSubscription(subscription) {
         const previousStatus = this.subscriptions.get(subscription.subscriptionId)?.status;
-        this.subscriptions.set(subscription.subscriptionId, { ...subscription });
+        this.subscriptions.set(subscription.subscriptionId, structuredClone(subscription));
         for (const listener of [...this.listeners.values()]) {
-            await listener({ subscription: { ...subscription }, previousStatus });
+            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;