@enyo-energy/energy-app-sdk 1.41.0 → 1.43.0

package/README.md

@@ -34,6 +34,8 @@ The official TypeScript SDK for building Energy Apps on the enyo platform. Creat
   - [Startup pattern](#startup-pattern)
 - [Package Files](#package-files)
 - [Printable Manual Setup Guide](#printable-manual-setup-guide)
+- [Installer Mail](#installer-mail)
+- [Compatibility Declaration](#compatibility-declaration)
 - [Firmware Update Registry](#firmware-update-registry)
   - [Declaring firmware](#declaring-firmware)
   - [Firmware modes](#firmware-modes)
@@ -994,23 +996,36 @@ Pairing needs the `VehicleIntegration` permission; reading vehicles needs only
 
 ##### Declaring supported brands
 
-Car integrations declare brands, not model lines — the vendor's cloud serves
-every car in the account and the line-up changes yearly. An empty `models`
-array with `default: true` reads as "every car of this brand":
+Declare every brand the package serves. Where you know the model line-up, list the models
+with their **model years** — a model name alone is ambiguous, because the same name is sold
+across generations that talk to different APIs. Give each generation its own entry; the same
+`modelName` may appear more than once as long as the `modelYears` ranges do not overlap.
+Leave out `to` while a model is still built.
 
 ```typescript
 categories: [EnergyAppPackageCategory.Vehicle],
 compatibility: [{
+    vendorName: 'Volkswagen',
+    defaultEnergyApp: true,
+    models: [
+        {modelName: 'ID.3', modelYears: {from: 2020, to: 2023}, features: [EnergyAppModelFeatureEnum.VehicleSocReadout]},
+        {modelName: 'ID.3', modelYears: {from: 2024}, features: [EnergyAppModelFeatureEnum.VehicleSocReadout]},
+    ],
+}, {
+    // Brand-wide support: an empty `models` array reads as "every car of this brand".
     vendorName: 'Tesla',
-    default: true,
+    defaultEnergyApp: true,
     models: [],
 }],
 ```
 
-Declare per-model entries only where support genuinely differs, and set
-`features` honestly — a brand whose API only reports SoC
+When the user picked a model and year in the enyo app, the pair handler receives them as
+`context.modelName` and `context.modelYear` next to `context.vendorName`.
+
+Set `features` honestly — a brand whose API only reports SoC
 (`VehicleSocReadout`) should not look like one that can also start a charge
-(`VehicleChargeStartStop`). See `EnergyAppModelFeatureEnum`'s vehicle group.
+(`VehicleChargeStartStop`). See `EnergyAppModelFeatureEnum`'s vehicle group, and validate
+the list with `validatePackageCompatibility()` (see [Compatibility Declaration](#compatibility-declaration)).
 
 ##### Charge modes
 
@@ -3297,6 +3312,99 @@ const {ok, errors, warnings} = validatePackageOnboardingGuide(packageDef);
 The complete authoring guide, with the reason behind each rule and a full example, is the
 JSDoc of `EnergyAppPackageDefinition.onboardingGuide`.
 
+## Installer Mail
+
+A package can declare the mail a customer sends to their installer from the enyo customer
+portal, telling the installer what to do. The enyo CLI reads it during `enyo release`. In the
+portal the customer enters the installer's address and details only they know, such as the
+device's serial number; enyo fills in the placeholders, renders the Markdown body as an HTML
+mail and sends it — with the PDF of the [Printable Manual Setup Guide](#printable-manual-setup-guide)
+attached when the package declares one (`attachOnboardingGuide: false` turns that off).
+
+- `subject` is plain text on one line, `body` is Markdown (raw HTML is not rendered); both
+  need `de` and `en`.
+- Placeholders are written as `{{name}}`; `installerMailPlaceholder()` writes them for you.
+  The list is closed (`EnyoInstallerMailPlaceholder`): `customerName`, `customerNumber`,
+  `customerEmail`, `customerPhone`, `installationStreet`, `installationZip`,
+  `installationCity`, `serialNumber` (entered by the customer), `vendorName`, `modelName`,
+  `energyAppName`, `onboardingGuideUrl`.
+- Any value can be missing when the mail is sent and is then left empty — put placeholders in
+  lists of details rather than in the middle of a sentence.
+- `attachments` names further files declared in `files`.
+
+```typescript
+import {
+    defineEnergyAppPackage,
+    defineInstallerMail,
+    EnyoInstallerMailPlaceholder as P,
+    installerMailPlaceholder as p,
+    renderInstallerMail,
+    validatePackageInstallerMail
+} from '@enyo-energy/energy-app-sdk';
+
+const packageDef = defineEnergyAppPackage({
+    // ...
+    onboardingGuide: manualSetupGuide,
+    onboardingFlowInstallerMail: defineInstallerMail({
+        subject: [
+            {language: 'de', value: `Einrichtung ${p(P.EnergyAppName)} bei ${p(P.CustomerName)}`},
+            {language: 'en', value: `${p(P.EnergyAppName)} setup for ${p(P.CustomerName)}`}
+        ],
+        body: [
+            {language: 'de', value: [
+                'Bitte aktiviere Modbus TCP am Wechselrichter, damit enyo ihn steuern kann.',
+                '',
+                `- **Kunde:** ${p(P.CustomerName)} (${p(P.CustomerNumber)})`,
+                `- **Adresse:** ${p(P.InstallationStreet)}, ${p(P.InstallationZip)} ${p(P.InstallationCity)}`,
+                `- **Gerät:** ${p(P.VendorName)} ${p(P.ModelName)}, Seriennummer ${p(P.SerialNumber)}`,
+                '',
+                `Die Schritt-für-Schritt-Anleitung findest du [hier](${p(P.OnboardingGuideUrl)}).`
+            ].join('\n')},
+            {language: 'en', value: '...'}
+        ]
+    })
+});
+
+const {ok, errors, warnings} = validatePackageInstallerMail(packageDef);
+
+// Preview what the installer receives:
+const preview = renderInstallerMail(packageDef.onboardingFlowInstallerMail!, 'de', {
+    [P.CustomerName]: 'Erika Mustermann',
+    [P.SerialNumber]: 'SN-123'
+});
+```
+
+Unknown placeholders, unpaired `{{` / `}}`, a missing language, a multi-line subject,
+`{{onboardingGuideUrl}}` or `attachOnboardingGuide: true` without an `onboardingGuide`, and
+attachments not declared in `files` are errors; raw HTML in the body and different
+placeholders per language are warnings.
+
+## Compatibility Declaration
+
+`compatibility` is the list of vendors and models enyo shows customers in the enyo Store,
+the onboarding flows and the customer portal. Each model may carry `modelYears`
+(`{from?, to?}`, both inclusive) — use it whenever a model name spans several generations,
+for vehicles as well as for inverters, wallboxes or heat pumps.
+
+```typescript
+import {isYearInCompatibilityRange, validatePackageCompatibility} from '@enyo-energy/energy-app-sdk';
+
+compatibility: [{
+    vendorName: 'SolarEdge',
+    models: [
+        {modelName: 'SE10K', modelYears: {from: 2016, to: 2020}, features: []},
+        {modelName: 'SE10K-RW0TEBNN4', modelYears: {from: 2021}, features: []}
+    ]
+}]
+
+const {ok, errors, warnings} = validatePackageCompatibility(packageDef);
+isYearInCompatibilityRange({from: 2021}, 2023); // true
+```
+
+Duplicate vendors, the same model name for overlapping years, `from` after `to` and years
+outside 1990 to two years ahead are errors. An empty range, and a vehicle model without
+`modelYears`, are warnings.
+
 ## Firmware Update Registry
 
 Ship firmware images with your package and hand them to devices at runtime. You declare the files by local path in the package definition, the enyo CLI uploads them during `enyo release`, and the app reaches them through `energyApp.useFirmwareRegistry()`. The release tarball never carries the bytes.
@@ -3558,12 +3666,13 @@ Drives a heatpump. Manages building / DHW overheating commands and grid-power-av
 
 > **Preferred: control heatpumps with the V3 messages.** `HeatpumpControlV3` (power, power sources, which zones to heat now, until when), `HeatpumpControlCancelV3` (cancel a session) and `HeatpumpControlStatusV3` (progress) are the preferred way to control a heatpump — for energy managers sending commands and for integrations receiving them. Use them for all new work. `HeatpumpOverheatingV1`, `SetHeatpumpAvailablePowerV2` and `HeatpumpAvailablePowerAnnouncementV1` are deprecated and only remain for heatpumps that do not declare `ControlV3`. See [HeatpumpControlV3](#heatpumpcontrolv3). Likewise, a heatpump offers its flexibility with `HeatpumpFlexibilityAnnouncementV3` rather than the generic `ApplianceFlexibilityAnnouncementV1` / `V2` — see [HeatpumpFlexibilityAnnouncementV3](#heatpumpflexibilityannouncementv3).
 
-- **Subscribed commands:** `HeatpumpControlV3`, `HeatpumpControlCancelV3`, `HeatpumpProgramSwitchV3`, `HeatpumpOverheatingV1` (deprecated), `HeatpumpAvailablePowerAnnouncementV1` (deprecated), `SetHeatpumpAvailablePowerV2` (deprecated), `SetHeatpumpRoomTemperatureV1`, `GridOperatorPowerLimitationV1` (broadcast)
+- **Subscribed commands:** `HeatpumpControlV3`, `HeatpumpControlCancelV3`, `HeatpumpProgramSwitchV3`, `SetHeatpumpHeatingCurveOffsetV1`, `HeatpumpOverheatingV1` (deprecated), `HeatpumpAvailablePowerAnnouncementV1` (deprecated), `SetHeatpumpAvailablePowerV2` (deprecated), `SetHeatpumpRoomTemperatureV1`, `GridOperatorPowerLimitationV1` (broadcast)
 - **Implement:** `handleHeatpumpOverheating`, `handleHeatpumpAvailablePowerAnnouncement`, `handleSetHeatpumpAvailablePower`, `handleGridOperatorPowerLimitation`
 - **Optional overrides:**
   - `handleSetHeatpumpRoomTemperature` — write a measured room temperature into a heating circuit. Answers `NotSupported` by default; override it when the heatpump declares `RoomTemperatureInput`.
   - `handleHeatpumpControl` — support `HeatpumpControlV3` (see below). Answers `NotSupported` by default; override it and declare `ControlV3`.
   - `handleHeatpumpProgramSwitch(request)` — switch a zone to comfort or eco, or back to its time program (see [HeatpumpProgramSwitchV3](#heatpumpprogramswitchv3)). Answers `NotSupported` by default; override it and declare `ProgramSwitch`.
+  - `handleHeatpumpHeatingCurveOffset(message)` — shift a heating circuit's curve permanently, relative to its initial curve (see [SetHeatpumpHeatingCurveOffsetV1](#setheatpumpheatingcurveoffsetv1)). Answers `NotSupported` by default; override it and declare `HeatingCurveOffset`.
   - `handleHeatpumpControlCancel` — withdraw a cancelled session on the device. By default `Accepted` for heatpumps declaring `ControlV3`, `NotSupported` otherwise.
   - `onHeatpumpControlEnded(applianceId, cause)` — return the heatpump to its own behaviour when a session ends; `cause` is `HeatpumpControlEndCauseEnum.Expired`, `Ended` or `Cancelled`. Does nothing by default.
   - `resolveHeatpumpMetadata(applianceId)` — the metadata actions are validated against. Defaults to the stored appliance's `heatpump` metadata.
@@ -3624,6 +3733,44 @@ Switches one heating circuit or DHW zone to its **comfort** or **eco** setpoint
 - **Owner's consent for price-driven eco.** An energy manager switches zones to eco for price reasons only while the general setting `heatpumpEcoModeInExpensiveTimes` (and `heatpumpControl`) is `true` — see [General settings](#general-settings).
 - **Validation** (run by the base class before the handler, or `validateHeatpumpProgramSwitch(data, metadata)` directly): target `Room` / `Dhw`, a known mode, a valid `untilIso` for comfort / eco (`Rejected`); `ProgramSwitch` declared and the mode listed for the zone (`NotSupported`); a known zone index (`Rejected`).
 
+#### SetHeatpumpHeatingCurveOffsetV1
+
+Shifts the heating curve of one heating circuit in parallel — **permanently**, until the next message. The energy manager uses it to lower the curve as far as the measured room temperature allows (less flow temperature, roughly 2.5 % less heating electricity per K).
+
+```typescript
+{
+    heatingCircuitIndex: 0,
+    offsetK: -1.5,   // K of flow temperature, relative to the initial curve; 0 restores it
+}
+```
+
+- **Relative to the initial curve, never to the current one.** Before the first offset other than `0`, the integration stores the curve set on the device as `heatingCircuits[].initialHeatingCurve` (`ApplianceManager.rememberHeatpumpInitialHeatingCurve` keeps an already stored one). The same message may therefore arrive twice.
+- **`offsetK: 0` restores** the initial curve exactly, including vendor parameters, then clears it (`ApplianceManager.clearHeatpumpInitialHeatingCurve`, which also sets `activeHeatingCurveOffsetK` to `0`).
+- **No expiry.** If the hub is offline nobody could reset it anyway; the stored initial curve is the safety net.
+- **Vendor units.** Convert to whatever the device shifts in (K of room temperature, steps, …) and report the effective shift in K of flow temperature as `heatingCircuits[].activeHeatingCurveOffsetK`, read back from the device. The energy manager waits for it before the next change.
+- **Changed by hand.** If the curve read from the device differs from `initialHeatingCurve` shifted by `activeHeatingCurveOffsetK` by more than 0.5 K at any point (`isHeatingCurveManuallyChanged(initial, offsetK, read)`), store the read curve as the new `initialHeatingCurve`, set `activeHeatingCurveOffsetK` to `0` and log it in a plain sentence.
+- **Alongside `HeatpumpControlV3` and `HeatpumpProgramSwitchV3`.** Boost and eco act on top; the offset is the new base.
+- **Validation** (run by the base class before the handler via `checkHeatingCurveOffset`, or `validateHeatpumpHeatingCurveOffset(data, metadata)` directly): a valid index and finite `offsetK` (`Rejected`); `HeatingCurveOffset` declared (`NotSupported`); a known circuit and — unless `offsetK` is `0` — within `heatingCurveOffsetRangeK` (`Rejected`).
+- **Customer settings.** Whether to optimise at all, and which rooms of the home the circuit heats (`roomIds`, whether or not a room has a sensor), live in `heatingCircuits[].curveOptimization`. The host resolves them into `rooms`: per room its target temperature (set in the enyo app, `HEATPUMP_CURVE_OPTIMIZATION_DEFAULT_TARGET_C` = 21 °C until then) and the temperature sensors assigned to it. Rooms without a sensor are left out; the room furthest below its target counts, and the curve is lowered by at most `HEATPUMP_CURVE_OPTIMIZATION_MAX_LOWERING_K` (3 K). Integrations only read them.
+
+```typescript
+protected async handleHeatpumpHeatingCurveOffset(message: EnyoDataBusSetHeatpumpHeatingCurveOffsetV1) {
+    const {heatingCircuitIndex: index, offsetK} = message.data;
+    if (offsetK !== 0) {
+        await this.appliances.rememberHeatpumpInitialHeatingCurve(message.applianceId, index, await this.readCurve(index));
+    }
+    await this.device.writeCurveShift(index, offsetK);
+    if (offsetK === 0) {
+        await this.appliances.clearHeatpumpInitialHeatingCurve(message.applianceId, index);
+    } else {
+        await this.appliances.updateHeatpumpHeatingCircuit(message.applianceId, index, {
+            activeHeatingCurveOffsetK: await this.readEffectiveShiftK(index),
+        });
+    }
+    return {answer: EnyoCommandAcknowledgeAnswerEnum.Accepted};
+}
+```
+
 #### HeatpumpFlexibilityAnnouncementV3
 
 The heatpump's offer, in the vocabulary of `HeatpumpControlV3`: per zone (`target` + `index`), how far it can be raised right now (`maxDeltaK` above `setpointC`, room in Kelvin of room temperature) and the smallest raise that actually starts it (`minDeltaK`, e.g. the remaining hysteresis), with which heat source at what power (`heatSources`: compressor and heating rod as separate entries, each with a `power` band and an optional `estimatedElectricalKwh` for the full raise), and when (`earliestStartIso` / `latestStartIso`, `minDurationMinutes`). An optional `required: {deltaK, byIso}` turns a "may" into a "must, by then" — e.g. hot water dropping below comfort at 18:00. Declare `FlexibilityAnnouncementV3` on the heatpump; for such heatpumps it supersedes the generic `ApplianceFlexibilityAnnouncementV1` / `V2`.
@@ -3659,6 +3806,9 @@ Beyond tanks and circuits, the heatpump metadata (`EnyoHeatpumpApplianceMetadata
 | `ProgramSwitch` | `heatingCircuits[].supportedProgramModes` / `programModeTemperaturesC` / `activeProgramMode` and the same on `domesticHotWater[]` — which zones can be switched to comfort / eco with `HeatpumpProgramSwitchV3`, at which setpoints, and the mode they run in now |
 | `RoomTemperature` | `heatingCircuits[].roomTemperatureC` in `HeatpumpTemperaturesUpdateV1`; where it is measured goes in `heatingCircuits[].roomTemperatureSource` (`None` / `Internal` / `External`) and, for an enyo sensor, `roomTemperatureSensor` |
 | `RoomTemperatureInput` | The heatpump accepts measured room temperatures via `SetHeatpumpRoomTemperatureV1` |
+| `HeatingCurveOffset` | The heatpump's app shifts a circuit's curve via `SetHeatpumpHeatingCurveOffsetV1`. `heatingCircuits[].heatingCurveOffsetRangeK` (allowed range, must contain 0), `activeHeatingCurveOffsetK` (effective shift read back) and `initialHeatingCurve` (the curve before the first shift) |
+| — | `heatingCircuits[].curveOptimization` — the customer's choice for the room-temperature based curve optimisation: `enabled` (off by default), `roomIds` (the rooms the circuit heats) and, resolved by the host, `rooms` — per room `roomId`, `name`, its `targetRoomTemperatureC` (16–26 °C) and the `sensors` assigned to it. Customer-owned; integrations only read it |
+| — | `building.recommendedHeatingCurve` — the curve the building actually needs, learned from the days the room held its target |
 | `PvSurplusSignal` | The heatpump takes `availablePowerW` of `HeatpumpControlV3` as a PV surplus signal (e.g. Lambda register 102). Supersedes the deprecated `AvailablePowerAnnouncement` |
 | `ControlV3` | The heatpump's app handles `HeatpumpControlV3` / `HeatpumpControlCancelV3` and reports `HeatpumpControlStatusV3`. The energy manager sends V3 only to heatpumps declaring it. Needs at least one overheating feature to be actionable |
 | `FlexibilityAnnouncementV3` | The heatpump publishes `HeatpumpFlexibilityAnnouncementV3` offers; the energy manager plans from them instead of deriving the headroom from metadata. Needs at least one overheating feature to be actionable |

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EnergyAppPackageFirmwareModeEnum = exports.EnergyAppPackageCompatibilityStatus = exports.EnergyAppPackageOptionsDeviceDetectionModbusModeEnum = exports.EnergyAppPackageCategory = void 0;
+exports.EnyoInstallerMailPlaceholder = exports.EnergyAppPackageFirmwareModeEnum = exports.EnergyAppPackageCompatibilityStatus = exports.EnergyAppPackageOptionsDeviceDetectionModbusModeEnum = exports.EnergyAppPackageCategory = void 0;
 exports.defineEnergyAppPackage = defineEnergyAppPackage;
 const version_js_1 = require("./version.cjs");
 var EnergyAppPackageCategory;
@@ -84,6 +84,56 @@ var EnergyAppPackageFirmwareModeEnum;
     /** Follow the explicit `installForFirmwareVersion` upgrade graph. */
     EnergyAppPackageFirmwareModeEnum["Dependent"] = "dependent";
 })(EnergyAppPackageFirmwareModeEnum || (exports.EnergyAppPackageFirmwareModeEnum = EnergyAppPackageFirmwareModeEnum = {}));
+/**
+ * The values enyo can insert into an
+ * {@link EnergyAppPackageInstallerMail installer mail}.
+ *
+ * Write a placeholder into the subject or body as `{{name}}` — for example
+ * `{{customerName}}` — or build it with `installerMailPlaceholder()`. The list
+ * is closed: the mail is sent by enyo while the app is not involved, so every
+ * value has to come from enyo, and `validatePackageInstallerMail()` rejects
+ * any name not listed here.
+ *
+ * Any value can be missing when the mail is sent (a customer without a phone
+ * number, a serial number the customer skipped). enyo then inserts an empty
+ * string, so write sentences that still read well without the value — put
+ * placeholders in lists of details rather than in the middle of a sentence.
+ */
+var EnyoInstallerMailPlaceholder;
+(function (EnyoInstallerMailPlaceholder) {
+    /** Full name of the customer. */
+    EnyoInstallerMailPlaceholder["CustomerName"] = "customerName";
+    /** The customer's enyo customer number. */
+    EnyoInstallerMailPlaceholder["CustomerNumber"] = "customerNumber";
+    /** The customer's e-mail address — where the installer can reply. */
+    EnyoInstallerMailPlaceholder["CustomerEmail"] = "customerEmail";
+    /** The customer's phone number. */
+    EnyoInstallerMailPlaceholder["CustomerPhone"] = "customerPhone";
+    /** Street and house number of the installation site. */
+    EnyoInstallerMailPlaceholder["InstallationStreet"] = "installationStreet";
+    /** Postal code of the installation site. */
+    EnyoInstallerMailPlaceholder["InstallationZip"] = "installationZip";
+    /** City of the installation site. */
+    EnyoInstallerMailPlaceholder["InstallationCity"] = "installationCity";
+    /**
+     * Serial number of the device to set up (e.g. the inverter), as the
+     * customer entered it in the portal. enyo does not know it from anywhere
+     * else, so it is the value most likely to be missing.
+     */
+    EnyoInstallerMailPlaceholder["SerialNumber"] = "serialNumber";
+    /** Vendor the customer selected, one of the package's `compatibility` vendors. */
+    EnyoInstallerMailPlaceholder["VendorName"] = "vendorName";
+    /** Model the customer selected, one of that vendor's `compatibility` models. */
+    EnyoInstallerMailPlaceholder["ModelName"] = "modelName";
+    /** Display title of the Energy App from its store entry, in the mail's language. */
+    EnyoInstallerMailPlaceholder["EnergyAppName"] = "energyAppName";
+    /**
+     * Public link to the PDF rendered from
+     * {@link EnergyAppPackageDefinition.onboardingGuide}. Only allowed when the
+     * package declares that guide.
+     */
+    EnyoInstallerMailPlaceholder["OnboardingGuideUrl"] = "onboardingGuideUrl";
+})(EnyoInstallerMailPlaceholder || (exports.EnyoInstallerMailPlaceholder = EnyoInstallerMailPlaceholder = {}));
 /**
  * Defines an Energy App package with automatic SDK version injection.
  * This function automatically adds the current SDK version to the package definition

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

@@ -2,6 +2,7 @@ import { EnergyAppPermissionType } from "./energy-app-permission.type.cjs";
 import { EnergyAppModelFeatureEnum } from "./energy-app-model-feature.enum.cjs";
 import type { EnyoFileTranslation } from "./types/enyo-file.cjs";
 import type { EnyoOnboardingV2Guide } from "./types/enyo-onboarding-v2.cjs";
+import type { EnyoOnboardingTranslatedContent } from "./types/enyo-onboarding.cjs";
 import type { EnyoSubscriptionMode, EnyoSubscriptionPaymentInterval, EnyoSubscriptionPrice, EnyoSubscriptionPricingModel } from "./types/enyo-subscription.cjs";
 export type EnergyAppPackageLanguage = 'de' | 'en';
 export declare enum EnergyAppPackageCategory {
@@ -387,6 +388,38 @@ export declare enum EnergyAppPackageCompatibilityStatus {
     /** The package has been verified **not** to work with this vendor or model. */
     NotCompatible = "not-compatible"
 }
+/**
+ * The model years a {@link EnergyAppPackageCompatibilityModel} entry covers,
+ * both ends inclusive.
+ *
+ * Model names alone are ambiguous for products that are sold under one name
+ * for many years: a 2020 "ID.3" and a 2024 "ID.3" can talk to completely
+ * different vendor APIs, and the same holds for inverter generations. The range
+ * lets the enyo Store, onboarding flows and the customer portal tell a user
+ * whether *their* device is covered.
+ *
+ * Years are whole calendar years (model years for vehicles, years of
+ * manufacture for other devices). Leave out {@link to} for a model that is
+ * still being built; leave out {@link from} only when the start is genuinely
+ * unknown. A product with several generations is declared as several model
+ * entries, one range each.
+ *
+ * Validated by `validatePackageCompatibility()`.
+ *
+ * @example
+ * ```typescript
+ * models: [
+ *     {modelName: 'ID.3', modelYears: {from: 2020, to: 2023}, features: [...]},
+ *     {modelName: 'ID.3', modelYears: {from: 2024}, features: [...]},
+ * ]
+ * ```
+ */
+export interface EnergyAppPackageCompatibilityYearRange {
+    /** First supported year, inclusive. Omit when the start is unknown. */
+    from?: number;
+    /** Last supported year, inclusive. Omit while the model is still built. */
+    to?: number;
+}
 /**
  * A specific device model supported by an Energy App package.
  * the concrete models the package has been verified to work with.
@@ -394,6 +427,16 @@ export declare enum EnergyAppPackageCompatibilityStatus {
 export interface EnergyAppPackageCompatibilityModel {
     /** Human-readable model name as marketed by the vendor (e.g. "SE10K-RW0TEBNN4") */
     modelName: string;
+    /**
+     * Optional range of model years this entry covers.
+     *
+     * Recommended for every model whose name is reused across generations —
+     * always for vehicles, and for inverters, wallboxes or heat pumps where a
+     * name spans hardware revisions. The same `modelName` may appear more than
+     * once per vendor as long as the ranges do not overlap. Omit when the entry
+     * applies to every year the model was built.
+     */
+    modelYears?: EnergyAppPackageCompatibilityYearRange;
     /**
      * Optional internal display name shown in the enyo Store / Admin UI when
      * different from the official `modelName` (e.g. a friendlier label).
@@ -669,6 +712,117 @@ export interface EnergyAppPackageFirmwareFile {
     /** Optional internal note explaining this image; never shown to users. */
     internalComment?: string;
 }
+/**
+ * The values enyo can insert into an
+ * {@link EnergyAppPackageInstallerMail installer mail}.
+ *
+ * Write a placeholder into the subject or body as `{{name}}` — for example
+ * `{{customerName}}` — or build it with `installerMailPlaceholder()`. The list
+ * is closed: the mail is sent by enyo while the app is not involved, so every
+ * value has to come from enyo, and `validatePackageInstallerMail()` rejects
+ * any name not listed here.
+ *
+ * Any value can be missing when the mail is sent (a customer without a phone
+ * number, a serial number the customer skipped). enyo then inserts an empty
+ * string, so write sentences that still read well without the value — put
+ * placeholders in lists of details rather than in the middle of a sentence.
+ */
+export declare enum EnyoInstallerMailPlaceholder {
+    /** Full name of the customer. */
+    CustomerName = "customerName",
+    /** The customer's enyo customer number. */
+    CustomerNumber = "customerNumber",
+    /** The customer's e-mail address — where the installer can reply. */
+    CustomerEmail = "customerEmail",
+    /** The customer's phone number. */
+    CustomerPhone = "customerPhone",
+    /** Street and house number of the installation site. */
+    InstallationStreet = "installationStreet",
+    /** Postal code of the installation site. */
+    InstallationZip = "installationZip",
+    /** City of the installation site. */
+    InstallationCity = "installationCity",
+    /**
+     * Serial number of the device to set up (e.g. the inverter), as the
+     * customer entered it in the portal. enyo does not know it from anywhere
+     * else, so it is the value most likely to be missing.
+     */
+    SerialNumber = "serialNumber",
+    /** Vendor the customer selected, one of the package's `compatibility` vendors. */
+    VendorName = "vendorName",
+    /** Model the customer selected, one of that vendor's `compatibility` models. */
+    ModelName = "modelName",
+    /** Display title of the Energy App from its store entry, in the mail's language. */
+    EnergyAppName = "energyAppName",
+    /**
+     * Public link to the PDF rendered from
+     * {@link EnergyAppPackageDefinition.onboardingGuide}. Only allowed when the
+     * package declares that guide.
+     */
+    OnboardingGuideUrl = "onboardingGuideUrl"
+}
+/**
+ * A mail the customer sends to their installer from the enyo customer portal,
+ * declared in {@link EnergyAppPackageDefinition.onboardingFlowInstallerMail}.
+ *
+ * ## Format
+ *
+ * - {@link subject} is plain text on one line.
+ * - {@link body} is Markdown (CommonMark: paragraphs, headings, emphasis,
+ *   lists, links). enyo renders it into its HTML mail template, so do not add a
+ *   greeting header, footer or styling of your own. Raw HTML is not rendered.
+ * - Both may contain {@link EnyoInstallerMailPlaceholder placeholders} written
+ *   as `{{name}}`. enyo inserts the values as text, escaped for Markdown, so a
+ *   customer name cannot break the layout.
+ * - Both need a `de` and an `en` entry; enyo picks the one matching the
+ *   customer's language.
+ *
+ * @example
+ * ```typescript
+ * const p = installerMailPlaceholder;
+ * const P = EnyoInstallerMailPlaceholder;
+ *
+ * onboardingFlowInstallerMail: defineInstallerMail({
+ *     subject: [
+ *         {language: 'de', value: `Einrichtung ${p(P.EnergyAppName)} für ${p(P.CustomerName)}`},
+ *         {language: 'en', value: `${p(P.EnergyAppName)} setup for ${p(P.CustomerName)}`},
+ *     ],
+ *     body: [
+ *         {language: 'de', value: [
+ *             'Bitte aktiviere Modbus TCP am Wechselrichter, damit enyo ihn steuern kann.',
+ *             '',
+ *             `- Kunde: ${p(P.CustomerName)} (${p(P.CustomerNumber)})`,
+ *             `- Seriennummer: ${p(P.SerialNumber)}`,
+ *             '',
+ *             `[Anleitung (PDF)](${p(P.OnboardingGuideUrl)})`,
+ *         ].join('\n')},
+ *         {language: 'en', value: '...'},
+ *     ],
+ * })
+ * ```
+ */
+export interface EnergyAppPackageInstallerMail {
+    /** Translated subject line: plain text, one line, may contain placeholders. */
+    subject: EnyoOnboardingTranslatedContent[];
+    /** Translated Markdown body, may contain placeholders. */
+    body: EnyoOnboardingTranslatedContent[];
+    /**
+     * Whether enyo attaches the PDF rendered from
+     * {@link EnergyAppPackageDefinition.onboardingGuide}. Defaults to `true`
+     * when the package declares that guide. Setting it to `true` without a
+     * guide is a validation error.
+     */
+    attachOnboardingGuide?: boolean;
+    /**
+     * Further attachments, by the `name` of a file declared in
+     * {@link EnergyAppPackageDefinition.files} (a datasheet, a wiring diagram).
+     * Those files are public anyway; attaching them only saves the installer
+     * a download.
+     */
+    attachments?: string[];
+    /** Optional internal note explaining this mail; never shown to anyone. */
+    internalComment?: string;
+}
 /**
  * Complete definition for a enyo Energy App package.
  * This interface defines all the metadata, permissions, and configuration
@@ -879,6 +1033,24 @@ export interface EnergyAppPackageDefinition {
      * Omit the field for packages that have no manual setup to document.
      */
     onboardingGuide?: EnyoOnboardingV2Guide;
+    /**
+     * The mail a customer sends to their installer from the enyo customer
+     * portal, telling the installer what to do to set the device up.
+     *
+     * The enyo CLI reads it at release time. In the portal the customer enters
+     * the installer's address and the details only they know (such as the
+     * device's serial number); enyo fills in the
+     * {@link EnyoInstallerMailPlaceholder placeholders}, renders the Markdown
+     * body as an HTML mail and sends it — attaching the PDF of
+     * {@link onboardingGuide} unless told otherwise.
+     *
+     * Validate it with `validatePackageInstallerMail()` before publishing; the
+     * CLI refuses the release on errors. See
+     * {@link EnergyAppPackageInstallerMail} for the format.
+     *
+     * Omit for packages that need no installer.
+     */
+    onboardingFlowInstallerMail?: EnergyAppPackageInstallerMail;
     /**
      * Subscription plans this package sells, including their prices. The enyo
      * CLI reads them at release time; enyo offers them to the customer and

package/dist/cjs/implementations/appliances/appliance-manager.cjs

@@ -618,6 +618,62 @@ class ApplianceManager {
         await this.energyApp.useAppliances().save(this.mergeApplianceData(appliance, { heatpump: { domesticHotWater: zones } }), applianceId);
         await this.primeCacheFromSdk(applianceId);
     }
+    /**
+     * Remembers the heating curve a circuit had before the first
+     * `SetHeatpumpHeatingCurveOffsetV1` changed it, as the circuit's
+     * `initialHeatingCurve` — the curve `offsetK: 0` restores. Call it before
+     * writing the first offset other than `0`.
+     *
+     * Keeps an already stored initial curve: every later offset is relative to
+     * the curve before the *first* change, so it must not be overwritten with
+     * an already shifted one. Works like {@link updateHeatpumpHeatingCircuit}
+     * otherwise.
+     *
+     * Does nothing when the appliance does not exist.
+     *
+     * @param applianceId The ID of the heatpump appliance
+     * @param index The `index` of the heating circuit
+     * @param curve The curve currently set on the device
+     * @returns `true` when the curve was stored, `false` when an initial curve
+     *   was already stored or the appliance does not exist
+     * @throws {ApplianceManagerDisposedError} when called after {@link dispose}
+     */
+    async rememberHeatpumpInitialHeatingCurve(applianceId, index, curve) {
+        this.throwIfDisposed();
+        const appliance = await this.energyApp.useAppliances().getById(applianceId);
+        if (!appliance)
+            return false;
+        const circuit = appliance.heatpump?.heatingCircuits?.find(c => c.index === index);
+        if (circuit?.initialHeatingCurve)
+            return false;
+        await this.updateHeatpumpHeatingCircuit(applianceId, index, { initialHeatingCurve: curve });
+        return true;
+    }
+    /**
+     * Forgets a circuit's `initialHeatingCurve` after the integration restored
+     * it on the device (`offsetK: 0`), and sets `activeHeatingCurveOffsetK` to
+     * `0`. Other circuits and fields are left untouched.
+     *
+     * Does nothing when the appliance or the circuit does not exist.
+     *
+     * @param applianceId The ID of the heatpump appliance
+     * @param index The `index` of the heating circuit
+     * @throws {ApplianceManagerDisposedError} when called after {@link dispose}
+     */
+    async clearHeatpumpInitialHeatingCurve(applianceId, index) {
+        this.throwIfDisposed();
+        const appliance = await this.energyApp.useAppliances().getById(applianceId);
+        if (!appliance)
+            return;
+        const circuits = [...(appliance.heatpump?.heatingCircuits ?? [])];
+        const position = circuits.findIndex(c => c.index === index);
+        if (position < 0)
+            return;
+        const { initialHeatingCurve: _removed, ...rest } = circuits[position];
+        circuits[position] = { ...rest, activeHeatingCurveOffsetK: 0 };
+        await this.energyApp.useAppliances().save(this.mergeApplianceData(appliance, { heatpump: { heatingCircuits: circuits } }), applianceId);
+        await this.primeCacheFromSdk(applianceId);
+    }
     /**
      * Refetches an appliance from the SDK and reflects the result in the
      * cache. Used by mutating methods to keep cache reads consistent with

package/dist/cjs/implementations/appliances/appliance-manager.d.cts

@@ -3,7 +3,7 @@ import type { EnyoNetworkDevice } from "../../types/enyo-network-device.cjs";
 import { EnyoAppliance, EnyoApplianceAvailableFeaturesEnum, EnyoApplianceConnectionType, EnyoApplianceGroup, EnyoApplianceMetadata, EnyoApplianceName, EnyoApplianceStateEnum, EnyoApplianceTopology, EnyoApplianceTypeEnum } from "../../types/enyo-appliance.cjs";
 import type { EnyoApplianceCreatedFilter } from "../../packages/energy-app-appliance.cjs";
 import type { EnyoChargerApplianceMetadata } from "../../types/enyo-charger-appliance.cjs";
-import type { EnyoHeatpumpApplianceDomesticHotWater, EnyoHeatpumpApplianceHeatingCircuit, EnyoHeatpumpApplianceMetadata } from "../../types/enyo-heatpump-appliance.cjs";
+import type { EnyoHeatpumpApplianceDomesticHotWater, EnyoHeatpumpApplianceHeatingCircuit, EnyoHeatpumpApplianceHeatingCurve, EnyoHeatpumpApplianceMetadata } from "../../types/enyo-heatpump-appliance.cjs";
 import type { EnyoBatteryApplianceMetadata } from "../../types/enyo-battery-appliance.cjs";
 import type { EnyoInverterApplianceMetadata } from "../../types/enyo-inverter-appliance.cjs";
 import type { EnyoMeterAppliance } from "../../types/enyo-meter-appliance.cjs";
@@ -401,6 +401,39 @@ export declare class ApplianceManager {
      * @throws {Error} when the zone does not exist and `patch` lacks `targetTemperatureC`
      */
     updateHeatpumpDomesticHotWater(applianceId: string, index: number, patch: Partial<Omit<EnyoHeatpumpApplianceDomesticHotWater, 'index'>>): Promise<void>;
+    /**
+     * Remembers the heating curve a circuit had before the first
+     * `SetHeatpumpHeatingCurveOffsetV1` changed it, as the circuit's
+     * `initialHeatingCurve` — the curve `offsetK: 0` restores. Call it before
+     * writing the first offset other than `0`.
+     *
+     * Keeps an already stored initial curve: every later offset is relative to
+     * the curve before the *first* change, so it must not be overwritten with
+     * an already shifted one. Works like {@link updateHeatpumpHeatingCircuit}
+     * otherwise.
+     *
+     * Does nothing when the appliance does not exist.
+     *
+     * @param applianceId The ID of the heatpump appliance
+     * @param index The `index` of the heating circuit
+     * @param curve The curve currently set on the device
+     * @returns `true` when the curve was stored, `false` when an initial curve
+     *   was already stored or the appliance does not exist
+     * @throws {ApplianceManagerDisposedError} when called after {@link dispose}
+     */
+    rememberHeatpumpInitialHeatingCurve(applianceId: string, index: number, curve: EnyoHeatpumpApplianceHeatingCurve): Promise<boolean>;
+    /**
+     * Forgets a circuit's `initialHeatingCurve` after the integration restored
+     * it on the device (`offsetK: 0`), and sets `activeHeatingCurveOffsetK` to
+     * `0`. Other circuits and fields are left untouched.
+     *
+     * Does nothing when the appliance or the circuit does not exist.
+     *
+     * @param applianceId The ID of the heatpump appliance
+     * @param index The `index` of the heating circuit
+     * @throws {ApplianceManagerDisposedError} when called after {@link dispose}
+     */
+    clearHeatpumpInitialHeatingCurve(applianceId: string, index: number): Promise<void>;
     /**
      * Refetches an appliance from the SDK and reflects the result in the
      * cache. Used by mutating methods to keep cache reads consistent with