@enyo-energy/energy-app-sdk 1.41.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)
@@ -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.

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/compatibility/compatibility-validators.cjs

@@ -0,0 +1,253 @@
+"use strict";
+/**
+ * Client-side validator for the vendors and models a package declares in
+ * {@link EnergyAppPackageDefinition.compatibility}.
+ *
+ * enyo publishes this list to customers — in the enyo Store, the onboarding
+ * flows and the customer portal — as the answer to "does this app work with my
+ * device?". A duplicate vendor, an inverted year range or a model that appears
+ * twice for the same years makes that answer ambiguous, so those are blocking
+ * `errors`. `warnings` point at entries that are valid but probably less
+ * precise than intended, such as a car model declared without its model years.
+ *
+ * Use {@link validatePackageCompatibility} for the non-throwing result, or
+ * {@link assertValidPackageCompatibility} to throw on failure.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PackageCompatibilityValidationError = exports.COMPATIBILITY_MAX_YEARS_AHEAD = exports.COMPATIBILITY_MIN_YEAR = void 0;
+exports.validatePackageCompatibility = validatePackageCompatibility;
+exports.assertValidPackageCompatibility = assertValidPackageCompatibility;
+exports.isYearInCompatibilityRange = isYearInCompatibilityRange;
+const energy_app_package_definition_js_1 = require("../../energy-app-package-definition.cjs");
+/**
+ * Earliest year accepted in a {@link EnergyAppPackageCompatibilityYearRange}.
+ * Nothing older can be integrated, so an earlier year is almost certainly a
+ * typo.
+ */
+exports.COMPATIBILITY_MIN_YEAR = 1990;
+/**
+ * How many years past the current one a range may reach. Vehicle model years
+ * run ahead of the calendar, and announced models are declared before release.
+ */
+exports.COMPATIBILITY_MAX_YEARS_AHEAD = 2;
+/**
+ * Thrown by {@link assertValidPackageCompatibility} when a package's
+ * compatibility declaration fails validation. The message lists every blocking
+ * error so callers can surface them directly.
+ */
+class PackageCompatibilityValidationError extends Error {
+    /** The individual blocking errors that caused the failure. */
+    errors;
+    /**
+     * @param errors - The blocking validation errors.
+     */
+    constructor(errors) {
+        super(`Invalid package compatibility:\n- ${errors.join('\n- ')}`);
+        this.name = 'PackageCompatibilityValidationError';
+        this.errors = errors;
+    }
+}
+exports.PackageCompatibilityValidationError = PackageCompatibilityValidationError;
+/**
+ * Validates a package's declared vendors and models: names present and unique,
+ * year ranges well-formed and plausible, and no model declared twice for
+ * overlapping years.
+ *
+ * Model names are compared case-insensitively, since a customer cannot tell
+ * "ID.3" from "id.3" apart. The same model name may appear more than once for
+ * a vendor — one entry per generation — as long as the
+ * {@link EnergyAppPackageCompatibilityModel.modelYears} ranges do not overlap.
+ *
+ * @param definition - The package definition, or just its `compatibility` and
+ *   (optionally) `categories`.
+ * @param options - See {@link PackageCompatibilityValidationOptions}.
+ * @returns The {@link PackageCompatibilityValidationResult}.
+ *
+ * @example
+ * ```typescript
+ * const {ok, errors, warnings} = validatePackageCompatibility(packageDef);
+ * if (!ok) throw new Error(errors.join('\n'));
+ * ```
+ */
+function validatePackageCompatibility(definition, options = {}) {
+    const errors = [];
+    const warnings = [];
+    const compatibility = definition.compatibility;
+    if (!Array.isArray(compatibility)) {
+        errors.push('`compatibility` must be an array of vendors.');
+        return { ok: false, errors, warnings };
+    }
+    const maxYear = (options.now ?? new Date()).getFullYear() + exports.COMPATIBILITY_MAX_YEARS_AHEAD;
+    const isVehiclePackage = definition.categories?.includes(energy_app_package_definition_js_1.EnergyAppPackageCategory.Vehicle) ?? false;
+    const vendorNames = new Map();
+    compatibility.forEach((vendor, vendorIndex) => {
+        const at = `compatibility[${vendorIndex}] (${vendor?.vendorName || '?'})`;
+        if (typeof vendor?.vendorName !== 'string' || vendor.vendorName.trim() === '') {
+            errors.push(`${at}: vendorName must be a non-empty string.`);
+        }
+        else {
+            const key = normalizeName(vendor.vendorName);
+            const first = vendorNames.get(key);
+            if (first !== undefined) {
+                errors.push(`${at}: duplicate vendor — already declared at compatibility[${first}]. Merge the model lists.`);
+            }
+            else {
+                vendorNames.set(key, vendorIndex);
+            }
+        }
+        if (!Array.isArray(vendor?.models)) {
+            errors.push(`${at}: models must be an array (empty for brand-wide support).`);
+            return;
+        }
+        validateModels(vendor, at, isVehiclePackage, maxYear, errors, warnings);
+    });
+    return { ok: errors.length === 0, errors, warnings };
+}
+/**
+ * Like {@link validatePackageCompatibility}, but throws
+ * {@link PackageCompatibilityValidationError} when there are blocking errors.
+ * Warnings never throw.
+ *
+ * @param definition - The package definition, or just its `compatibility` and
+ *   (optionally) `categories`.
+ * @param options - See {@link PackageCompatibilityValidationOptions}.
+ * @returns The declared compatibility list.
+ * @throws {PackageCompatibilityValidationError} When validation produces any error.
+ */
+function assertValidPackageCompatibility(definition, options = {}) {
+    const { ok, errors } = validatePackageCompatibility(definition, options);
+    if (!ok)
+        throw new PackageCompatibilityValidationError(errors);
+    return definition.compatibility;
+}
+/**
+ * Checks whether a year falls within a declared range. An open end matches
+ * every year on that side, and a missing range matches every year.
+ *
+ * This is the matching rule enyo applies when a customer picks a model year,
+ * exposed so an app can test its own declarations against real devices.
+ *
+ * @param range - The model's declared range, or `undefined` for "all years".
+ * @param year - The year to check.
+ * @returns `true` when `year` lies within `range`.
+ *
+ * @example
+ * ```typescript
+ * isYearInCompatibilityRange({from: 2020, to: 2023}, 2022); // true
+ * isYearInCompatibilityRange({from: 2024}, 2022);           // false
+ * ```
+ */
+function isYearInCompatibilityRange(range, year) {
+    if (!range)
+        return true;
+    if (range.from !== undefined && year < range.from)
+        return false;
+    if (range.to !== undefined && year > range.to)
+        return false;
+    return true;
+}
+/**
+ * Validates the models of one vendor: names, year ranges, and overlapping
+ * duplicates.
+ *
+ * @param vendor - The vendor whose models are checked.
+ * @param vendorAt - Human-readable location of the vendor, used in messages.
+ * @param isVehiclePackage - Whether the package is a vehicle integration.
+ * @param maxYear - The latest year a range may reach.
+ * @param errors - Collector for blocking problems.
+ * @param warnings - Collector for advisory problems.
+ */
+function validateModels(vendor, vendorAt, isVehiclePackage, maxYear, errors, warnings) {
+    const seen = new Map();
+    vendor.models.forEach((model, modelIndex) => {
+        const at = `${vendorAt}.models[${modelIndex}] (${model?.modelName || '?'})`;
+        if (typeof model?.modelName !== 'string' || model.modelName.trim() === '') {
+            errors.push(`${at}: modelName must be a non-empty string.`);
+            return;
+        }
+        const rangeOk = validateYearRange(model.modelYears, at, maxYear, errors, warnings);
+        const isVehicleModel = model.category === energy_app_package_definition_js_1.EnergyAppPackageCategory.Vehicle ||
+            (model.category === undefined && isVehiclePackage);
+        if (isVehicleModel && model.modelYears === undefined) {
+            warnings.push(`${at}: no modelYears — a car model name usually spans several generations; declare which years are supported.`);
+        }
+        const key = normalizeName(model.modelName);
+        const earlier = seen.get(key) ?? [];
+        if (rangeOk) {
+            for (const other of earlier) {
+                if (rangesOverlap(other.range, model.modelYears)) {
+                    errors.push(`${at}: duplicate model — ${vendorAt}.models[${other.index}] has the same name for ` +
+                        'overlapping years. Give each generation its own, non-overlapping modelYears.');
+                    break;
+                }
+            }
+            earlier.push({ index: modelIndex, range: model.modelYears });
+            seen.set(key, earlier);
+        }
+    });
+}
+/**
+ * Validates one {@link EnergyAppPackageCompatibilityYearRange}.
+ *
+ * @param range - The declared range, possibly `undefined`.
+ * @param at - Human-readable location of the model, used in messages.
+ * @param maxYear - The latest year a range may reach.
+ * @param errors - Collector for blocking problems.
+ * @param warnings - Collector for advisory problems.
+ * @returns `true` when the range is absent or well-formed, so it can be
+ *   compared against other ranges.
+ */
+function validateYearRange(range, at, maxYear, errors, warnings) {
+    if (range === undefined)
+        return true;
+    if (range === null || typeof range !== 'object' || Array.isArray(range)) {
+        errors.push(`${at}: modelYears must be an object like {from: 2020, to: 2023}.`);
+        return false;
+    }
+    let ok = true;
+    for (const end of ['from', 'to']) {
+        const year = range[end];
+        if (year === undefined)
+            continue;
+        if (!Number.isInteger(year)) {
+            errors.push(`${at}: modelYears.${end} must be a whole year, got ${String(year)}.`);
+            ok = false;
+        }
+        else if (year < exports.COMPATIBILITY_MIN_YEAR || year > maxYear) {
+            errors.push(`${at}: modelYears.${end} ${year} is outside ${exports.COMPATIBILITY_MIN_YEAR}–${maxYear}.`);
+            ok = false;
+        }
+    }
+    if (ok && range.from !== undefined && range.to !== undefined && range.from > range.to) {
+        errors.push(`${at}: modelYears.from (${range.from}) is after modelYears.to (${range.to}).`);
+        ok = false;
+    }
+    if (ok && range.from === undefined && range.to === undefined) {
+        warnings.push(`${at}: modelYears is empty — omit it when the entry covers every year.`);
+    }
+    return ok;
+}
+/**
+ * Whether two year ranges share at least one year. A missing range or a
+ * missing end is unbounded on that side.
+ *
+ * @param a - The first range.
+ * @param b - The second range.
+ * @returns `true` when the ranges overlap.
+ */
+function rangesOverlap(a, b) {
+    const aFrom = a?.from ?? -Infinity;
+    const aTo = a?.to ?? Infinity;
+    const bFrom = b?.from ?? -Infinity;
+    const bTo = b?.to ?? Infinity;
+    return aFrom <= bTo && bFrom <= aTo;
+}
+/**
+ * Normalizes a vendor or model name for duplicate detection.
+ *
+ * @param name - The declared name.
+ * @returns The trimmed, lower-cased name with inner whitespace collapsed.
+ */
+function normalizeName(name) {
+    return name.trim().replace(/\s+/g, ' ').toLowerCase();
+}