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

package/README.md

@@ -2276,6 +2276,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,6 +2319,8 @@ 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.
 
@@ -2972,7 +2985,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 the app reports — see [Per-unit plans](#per-unit-plans). |
+| `prices` | One net price per currency. `amountWithoutTax` is always the **total for one interval** — per month, per year, or the single one-time amount; per unit for `per-unit` plans — in the currency (not cent), at most two decimals; enyo adds VAT. |
 | `trialDays` | Optional free trial in days. Not allowed for `one-time` plans. |
 | `storeEntry` | Title, short description and optional benefits; `de` and `en` are required. |
 | `internalComment` | Optional note, never shown to users. |
@@ -2980,6 +2994,51 @@ const packageDef = defineEnergyAppPackage({
 What a plan unlocks is decided by the app: check `isPlanActive(subscriptions, planKey)` at runtime (see
 [`useSubscriptions()`](#usesubscriptions-energyappsubscriptions)).
 
+### Per-unit plans
+
+For a `per-unit` plan the price is charged once per unit, and the **quantity comes from the energy app**. The app
+reports every unit it currently manages with `setUnits()` — on boot and whenever a unit is added or removed. Each
+unit has a `type` and a `referenceId` it is paid under:
+
+| `type` | `referenceId` | Name shown to the customer |
+|---|---|---|
+| `appliance` | the appliance id | taken from the appliance |
+| `vehicle` | the vehicle id | taken from the vehicle |
+| `custom` | an id chosen by the app | `name`, translated; `de` and `en` are required |
+
+```typescript
+import { EnyoSubscriptionUnitTypeEnum, isUnitActive } from '@enyo-energy/energy-app-sdk';
+
+const subscriptions = energyApp.useSubscriptions();
+const wallboxes = await energyApp.useAppliances().list();
+
+// 3 wallboxes on a yearly plan for 10 € → 30 € per year (net).
+await subscriptions.setUnits('smart-charging', wallboxes.map(wallbox => ({
+    type: EnyoSubscriptionUnitTypeEnum.Appliance,
+    referenceId: wallbox.id
+})));
+
+// A custom unit carries its own translated name.
+await subscriptions.setUnits('room-climate', [{
+    type: EnyoSubscriptionUnitTypeEnum.Custom,
+    referenceId: 'living-room',
+    name: [{ language: 'en', value: 'Living room' }, { language: 'de', value: 'Wohnzimmer' }]
+}]);
+
+// Only the units the customer paid for are active.
+const all = await subscriptions.getSubscriptions();
+for (const wallbox of wallboxes) {
+    setSmartCharging(wallbox, isUnitActive(all, 'smart-charging', { type: 'appliance', referenceId: wallbox.id }));
+}
+```
+
+- **Reporting a unit does not pay for it.** Paid units are listed in `subscription.units`; when the customer pays
+  for more units, the change listeners are called.
+- **Keep `referenceId` stable.** `type` plus `referenceId` identify the unit; a new reference is a new, unpaid unit.
+- **enyo decides how a changed quantity is charged**, e.g. pro rata for the rest of the period.
+- `validateSubscriptionUnits(units)` applies the host's rules up front: known type, non-empty reference, no unit
+  twice, `de` and `en` names on custom units.
+
 **A price change needs a new release** and only applies to new purchases — running subscriptions keep the price
 they were bought at.
 
@@ -2990,7 +3049,7 @@ 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
+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.

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 { EnyoSubscriptionPaymentInterval, EnyoSubscriptionPrice, EnyoSubscriptionPricingModel } from "./types/enyo-subscription.cjs";
 export type EnergyAppPackageLanguage = 'de' | 'en';
 export declare enum EnergyAppPackageCategory {
     Inverter = "inverter",
@@ -333,10 +333,18 @@ 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 app reports the units — appliances, vehicles or custom
+     * units — at runtime with {@link EnergyAppSubscriptions.setUnits}.
+     */
+    pricingModel?: EnyoSubscriptionPricingModel;
     /**
      * Net price, one entry per currency. At least one entry is required. The
      * amount is always the total for one interval: per month for `monthly`,
-     * per year for `yearly`, and the single amount for `one-time`.
+     * per year for `yearly`, and the single amount for `one-time`. For a
+     * `per-unit` plan it is the amount per unit.
      */
     prices: EnyoSubscriptionPrice[];
     /**

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,8 @@ 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}.
  *
  * @example
  * ```typescript
@@ -20,6 +23,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 +33,61 @@ exports.InMemorySubscriptions = void 0;
  * ```
  */
 class InMemorySubscriptions {
+    plans;
     subscriptions = new Map();
     listeners = new Map();
+    unitsByPlan = 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.
      */
-    constructor(initialSubscriptions = []) {
+    constructor(initialSubscriptions = [], plans) {
+        this.plans = plans;
         for (const subscription of initialSubscriptions) {
-            this.subscriptions.set(subscription.subscriptionId, { ...subscription });
+            this.subscriptions.set(subscription.subscriptionId, structuredClone(subscription));
         }
     }
+    /**
+     * Stores the 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.
+     * @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.
+     */
+    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.`);
+            }
+        }
+        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)));
+    }
+    /**
+     * Returns copies of the units last reported for a plan.
+     *
+     * @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));
+    }
     /**
      * 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,9 +125,9 @@ 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 });
         }
     }
 }

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

@@ -1,5 +1,6 @@
+import type { EnergyAppPackageSubscriptionPlan } from '../../energy-app-package-definition.cjs';
 import type { EnergyAppSubscriptions } from '../../packages/energy-app-subscriptions.cjs';
-import type { EnyoSubscription, EnyoSubscriptionChangeListener } from '../../types/enyo-subscription.cjs';
+import { EnyoSubscription, EnyoSubscriptionChangeListener, EnyoSubscriptionUnit } from '../../types/enyo-subscription.cjs';
 /**
  * In-memory implementation of {@link EnergyAppSubscriptions} for tests and
  * local development.
@@ -7,7 +8,8 @@ import type { EnyoSubscription, EnyoSubscriptionChangeListener } from '../../typ
  * 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}.
  *
  * @example
  * ```typescript
@@ -19,6 +21,7 @@ import type { EnyoSubscription, EnyoSubscriptionChangeListener } from '../../typ
  *     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',
@@ -28,14 +31,36 @@ import type { EnyoSubscription, EnyoSubscriptionChangeListener } from '../../typ
  * ```
  */
 export declare class InMemorySubscriptions implements EnergyAppSubscriptions {
+    private readonly plans?;
     private readonly subscriptions;
     private readonly listeners;
+    private readonly unitsByPlan;
     private nextListenerId;
     /**
      * @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.
      */
-    constructor(initialSubscriptions?: EnyoSubscription[]);
+    constructor(initialSubscriptions?: EnyoSubscription[], plans?: EnergyAppPackageSubscriptionPlan[] | undefined);
+    /**
+     * Stores the 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.
+     * @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.
+     */
+    setUnits(planKey: string, units: EnyoSubscriptionUnit[]): Promise<void>;
+    /**
+     * Returns copies of the units last reported for a plan.
+     *
+     * @param planKey - The key of the plan.
+     * @returns Promise that resolves to the units; an empty list when none were reported
+     */
+    getUnits(planKey: string): Promise<EnyoSubscriptionUnit[]>;
     /**
      * Returns copies of all stored subscriptions.
      *

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

@@ -15,6 +15,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.PackageSubscriptionPlansValidationError = void 0;
 exports.validatePackageSubscriptionPlans = validatePackageSubscriptionPlans;
 exports.assertValidPackageSubscriptionPlans = assertValidPackageSubscriptionPlans;
+exports.validateSubscriptionUnits = validateSubscriptionUnits;
 const energy_app_permission_type_js_1 = require("../../energy-app-permission.type.cjs");
 const enyo_currency_js_1 = require("../../types/enyo-currency.cjs");
 const enyo_subscription_js_1 = require("../../types/enyo-subscription.cjs");
@@ -159,6 +160,10 @@ function validatePackageSubscriptionPlans(definition) {
         if (!Object.values(enyo_subscription_js_1.EnyoSubscriptionPaymentIntervalEnum).includes(plan.paymentInterval)) {
             errors.push(`${at}: paymentInterval "${plan.paymentInterval}" is not supported.`);
         }
+        if (plan.pricingModel !== undefined
+            && !Object.values(enyo_subscription_js_1.EnyoSubscriptionPricingModelEnum).includes(plan.pricingModel)) {
+            errors.push(`${at}: pricingModel "${plan.pricingModel}" is not supported.`);
+        }
         validatePrices(plan, at, errors);
         if (plan.trialDays !== undefined) {
             if (plan.paymentInterval === enyo_subscription_js_1.EnyoSubscriptionPaymentIntervalEnum.OneTime) {
@@ -189,3 +194,48 @@ function assertValidPackageSubscriptionPlans(definition) {
         throw new PackageSubscriptionPlansValidationError(errors);
     return definition.subscriptionPlans;
 }
+/**
+ * Validates the units an app reports for a `per-unit` plan with
+ * {@link EnergyAppSubscriptions.setUnits}: every unit has a known type and a
+ * non-empty reference, no unit is reported twice (same `type` and
+ * `referenceId`), and every custom unit has a non-empty name in German and
+ * English. The host applies the same rules and rejects invalid units.
+ *
+ * @param units - The units to report.
+ * @returns The {@link SubscriptionUnitsValidationResult}.
+ *
+ * @example
+ * ```typescript
+ * const {ok, errors} = validateSubscriptionUnits(units);
+ * if (!ok) logger.warn(errors.join('\n'));
+ * ```
+ */
+function validateSubscriptionUnits(units) {
+    const errors = [];
+    const seen = new Set();
+    for (const [index, unit] of units.entries()) {
+        const at = `units[${index}] (${unit.type || '?'} ${unit.referenceId || '?'})`;
+        if (!Object.values(enyo_subscription_js_1.EnyoSubscriptionUnitTypeEnum).includes(unit.type)) {
+            errors.push(`${at}: type "${unit.type}" is not supported.`);
+        }
+        if (!unit.referenceId?.trim()) {
+            errors.push(`${at}: referenceId is required.`);
+        }
+        else {
+            const key = `${unit.type}\u0000${unit.referenceId}`;
+            if (seen.has(key)) {
+                errors.push(`${at}: duplicate unit — type and referenceId must be unique.`);
+            }
+            seen.add(key);
+        }
+        if (unit.type === enyo_subscription_js_1.EnyoSubscriptionUnitTypeEnum.Custom) {
+            const names = unit.name ?? [];
+            for (const language of REQUIRED_LANGUAGES) {
+                if (!names.some(name => name.language === language && name.value?.trim())) {
+                    errors.push(`${at}: a custom unit needs a name in language "${language}".`);
+                }
+            }
+        }
+    }
+    return { ok: errors.length === 0, errors };
+}

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

@@ -11,6 +11,7 @@
  * {@link assertValidPackageSubscriptionPlans} to throw on failure.
  */
 import type { EnergyAppPackageDefinition, EnergyAppPackageSubscriptionPlan } from '../../energy-app-package-definition.cjs';
+import { EnyoSubscriptionUnit } from '../../types/enyo-subscription.cjs';
 /**
  * Thrown by {@link assertValidPackageSubscriptionPlans} when a package's
  * subscription plans fail validation. The message lists every blocking error
@@ -69,3 +70,27 @@ export declare function validatePackageSubscriptionPlans(definition: PackageSubs
  * @throws {PackageSubscriptionPlansValidationError} When validation produces any error.
  */
 export declare function assertValidPackageSubscriptionPlans(definition: PackageSubscriptionPlansSource): EnergyAppPackageSubscriptionPlan[] | undefined;
+/** The outcome of validating the units reported for a `per-unit` plan. */
+export interface SubscriptionUnitsValidationResult {
+    /** True when there are no `errors`. */
+    ok: boolean;
+    /** Problems that make the host reject the units. */
+    errors: string[];
+}
+/**
+ * Validates the units an app reports for a `per-unit` plan with
+ * {@link EnergyAppSubscriptions.setUnits}: every unit has a known type and a
+ * non-empty reference, no unit is reported twice (same `type` and
+ * `referenceId`), and every custom unit has a non-empty name in German and
+ * English. The host applies the same rules and rejects invalid units.
+ *
+ * @param units - The units to report.
+ * @returns The {@link SubscriptionUnitsValidationResult}.
+ *
+ * @example
+ * ```typescript
+ * const {ok, errors} = validateSubscriptionUnits(units);
+ * if (!ok) logger.warn(errors.join('\n'));
+ * ```
+ */
+export declare function validateSubscriptionUnits(units: EnyoSubscriptionUnit[]): SubscriptionUnitsValidationResult;

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

@@ -1,4 +1,4 @@
-import { EnyoSubscription, EnyoSubscriptionChangeListener } from "../types/enyo-subscription.cjs";
+import { EnyoSubscription, EnyoSubscriptionChangeListener, EnyoSubscriptionUnit } from "../types/enyo-subscription.cjs";
 /**
  * Interface for reading the subscriptions a customer bought for this energy
  * app on this device.
@@ -16,6 +16,12 @@ import { EnyoSubscription, EnyoSubscriptionChangeListener } from "../types/enyo-
  * or grace period ending, a cancelled subscription expiring — are reported even
  * without a connection.
  *
+ * A `per-unit` plan is charged once per unit — appliance, vehicle or custom
+ * unit — and the quantity comes from the app: it reports the units it
+ * currently manages with {@link setUnits}, and enyo offers and charges the
+ * plan for them. {@link EnyoSubscription.units} lists the units that are paid
+ * for; check a single unit with `isUnitActive()`.
+ *
  * When a plan stops being active, the app must fall back to a safe behaviour.
  * For example, release any control it holds over a heat pump, wallbox or
  * battery instead of leaving the appliance in the last commanded state.
@@ -48,11 +54,57 @@ export interface EnergyAppSubscriptions {
      *   permission is not granted.
      */
     getSubscriptions(): Promise<EnyoSubscription[]>;
+    /**
+     * Reports the units the app currently manages for a `per-unit` plan,
+     * replacing the previously reported list. The number of units is the
+     * quantity enyo offers and charges the plan for.
+     *
+     * Call it on boot and whenever a unit is added or removed, with the full
+     * list each time. A unit is identified by its `type` plus `referenceId`,
+     * so keep the reference stable: a changed reference reads as a removed and
+     * a new, unpaid unit. How a changed quantity is charged — for example
+     * pro rata for the rest of the period — is decided by enyo.
+     *
+     * Reporting a unit does not pay for it. Once the customer has paid, the
+     * unit appears in {@link EnyoSubscription.units} and the change listeners
+     * are called.
+     *
+     * @param planKey - The key of a `per-unit` plan declared in the package definition.
+     * @param units - Every unit the app currently manages for the plan; an
+     *   empty list when there is none.
+     * @returns Promise that resolves once the host has stored the units
+     * @throws {Error} If `planKey` is not a `per-unit` plan of this package, or
+     *   a unit is invalid (empty reference, duplicate `type` + `referenceId`,
+     *   custom unit without `de` and `en` name).
+     * @throws {EnergyAppPermissionNotGrantedError} If the `Subscriptions`
+     *   permission is not granted.
+     *
+     * @example
+     * ```typescript
+     * const wallboxes = await energyApp.useAppliances().list();
+     * await subscriptions.setUnits('smart-charging', wallboxes.map(wallbox => ({
+     *     type: EnyoSubscriptionUnitTypeEnum.Appliance,
+     *     referenceId: wallbox.id
+     * })));
+     * ```
+     */
+    setUnits(planKey: string, units: EnyoSubscriptionUnit[]): Promise<void>;
+    /**
+     * Returns the units last reported with {@link setUnits} for a `per-unit`
+     * plan. These are the units the app manages, whether paid for or not.
+     *
+     * @param planKey - The key of a `per-unit` plan declared in the package definition.
+     * @returns Promise that resolves to the reported units; an empty list when
+     *   none were reported yet
+     * @throws {EnergyAppPermissionNotGrantedError} If the `Subscriptions`
+     *   permission is not granted.
+     */
+    getUnits(planKey: string): Promise<EnyoSubscriptionUnit[]>;
     /**
      * Registers a listener that is called whenever a subscription of this app
      * on this device is created or changes — a purchase, a renewal, a
-     * cancellation, a failed payment, or the end of a trial, grace or paid
-     * period.
+     * cancellation, a failed payment, units paid for or removed, or the end of
+     * a trial, grace or paid period.
      *
      * The listener is not called for the state that exists when it is
      * registered. Read that with {@link getSubscriptions} on boot.

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

@@ -1,4 +1,4 @@
-import { EnyoWebhookEvent } from "../types/enyo-webhook.cjs";
+import { EnyoWebhookEvent, EnyoWebhookListenOptions } from "../types/enyo-webhook.cjs";
 /**
  * Interface for receiving webhooks from third-party services.
  *
@@ -54,11 +54,30 @@ export interface EnergyAppWebhook {
      * is at least once and the order of calls is not guaranteed; deduplicate
      * with {@link EnyoWebhookEvent.webhookRequestId}.
      *
+     * By default the listener receives calls from the public sources only.
+     * To also receive a hidden source, pass its access token in
+     * `options.secretKeys`. The tokens apply to this listener only; other
+     * listeners of the app do not receive the hidden source unless they pass
+     * the token themselves.
+     *
      * @typeParam T - Shape of the JSON body the app expects.
      * @param listener - Callback invoked for every forwarded webhook call. May be async.
+     * @param options - Optional settings, such as access tokens for hidden sources.
      * @returns The listener ID, to be passed to {@link removeListener}
+     *
+     * @example
+     * ```typescript
+     * const token = await energyApp.useSecretManager().getSecret<string>('vendor-webhook-token', encryptionKey);
+     * webhook.listenForWebhook<VendorEvent>(async (event) => {
+     *     if (event.source === 'vendor-cloud') {
+     *         await handleVendorEvent(event.body);
+     *     }
+     * }, {
+     *     secretKeys: [{source: 'vendor-cloud', token}]
+     * });
+     * ```
      */
-    listenForWebhook<T = unknown>(listener: (event: EnyoWebhookEvent<T>) => void | Promise<void>): string;
+    listenForWebhook<T = unknown>(listener: (event: EnyoWebhookEvent<T>) => void | Promise<void>, options?: EnyoWebhookListenOptions): string;
     /**
      * Removes a listener previously registered with {@link listenForWebhook}.
      *