@enyo-energy/energy-app-sdk 1.40.0 → 1.42.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)
@@ -860,6 +862,8 @@ energyApp.useDataBus().sendMessage([{
     data: {
         vehicleId,
         socPercent: 62,
+        // optional: remaining range in km, when the source reports it (e.g. Smartcar)
+        rangeKm: 280,
         // omit only when the reading came straight off the wire
         measuredAtIso: new Date().toISOString(),
     },
@@ -870,6 +874,19 @@ That message is the only write path for a state of charge; it needs the
 `SendDataBusValues` permission. `getSoc()` resolves to `undefined` when nothing
 is known — an ordinary answer for a car with no SoC source, not an error.
 
+The vehicle's battery size is written the same way: publish
+`VehicleBatterySizeUpdateV1` with the usable capacity in watt-hours, and the
+host stores it on the vehicle (replacing the previous value, including one the
+user entered). It is read back as `batterySizeKwh`.
+
+```typescript
+energyApp.useDataBus().sendMessage([{
+    type: 'message',
+    message: 'VehicleBatterySizeUpdateV1',
+    data: {vehicleId, batterySizeWh: 75_000},
+}]);
+```
+
 ##### Car integrations: pairing a vehicle
 
 A package in the `vehicle` category talks to a manufacturer's cloud and links
@@ -979,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
 
@@ -3282,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.

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