@enyo-energy/energy-app-sdk 1.31.0 → 1.33.0

package/README.md

@@ -33,6 +33,7 @@ The official TypeScript SDK for building Energy Apps on the enyo platform. Creat
   - [NetworkDeviceManager](#networkdevicemanager)
   - [Startup pattern](#startup-pattern)
 - [Package Files](#package-files)
+- [Printable Manual Setup Guide](#printable-manual-setup-guide)
 - [Firmware Update Registry](#firmware-update-registry)
   - [Declaring firmware](#declaring-firmware)
   - [Firmware modes](#firmware-modes)
@@ -828,6 +829,9 @@ vehicle?.priceLimitMode;             // how the ceiling is expressed, or none
 vehicle?.priceLimitCtPerKwh;         // ct/kWh ceiling, under 'ct-per-kwh'
 vehicle?.priceLimitSharePercent;     // cheapest n % of the day, under 'cheapest-share'
 vehicle?.immediateReserveKwh;        // full-power reserve before any mode
+vehicle?.minChargingCurrentAmpere;   // lowest current per phase the car accepts
+vehicle?.cannotBePaused;             // true: never pause a started session
+vehicle?.phaseSwitchDisabled;        // true: never switch phases while charging
 vehicle?.departureTimeHHmm;          // daily deadline, wall-clock "07:30"
 vehicle?.departureTimezone;          // IANA zone the time is read in
 
@@ -2851,6 +2855,43 @@ It checks that names are unique slugs, that paths stay inside the package and ca
 extension, and that any declared MIME type is well formed; two names pointing at one
 path is a warning.
 
+## Printable Manual Setup Guide
+
+A package can declare **one optional** onboarding guide (v2) as static data in its package
+definition. The enyo CLI reads it during `enyo release`, and enyo renders it as a printable
+PDF installation manual. It is separate from the interactive guides an app returns from
+`useOnboardingV2().registerOnboardingGuidesHandler()`: it never takes part in an onboarding
+run, so it needs no `name` and doesn't conflict with those guides in any way.
+
+Paper cannot scan the network or ask the app anything, so the guide must describe a
+**manual setup**:
+
+- `startVariant: EnyoOnboardingV2StartVariant.ManualSetup` and `requiresNetworkScan: false`
+- no `network-scan` / `device-test` actions, no `device-select` / `eebus-device-select`
+  blocks, no `dynamic` blocks, no `start-variant` targets
+- no `applianceId`, `vendorId` or `modelIds`
+- plain JSON only, and every image block `file` declared in `files`
+
+```typescript
+import {
+    defineEnergyAppPackage,
+    definePublicFile,
+    validatePackageOnboardingGuide
+} from '@enyo-energy/energy-app-sdk';
+import {manualSetupGuide} from './src/onboarding/manual-setup.guide.js';
+
+const packageDef = defineEnergyAppPackage({
+    // ...
+    files: [definePublicFile({name: 'modbus-menu', path: './assets/modbus-menu.png'})],
+    onboardingGuide: manualSetupGuide
+});
+
+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`.
+
 ## 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.
@@ -4279,7 +4320,7 @@ Each event carries the **complete** picture of the slot — render it as it arri
 
 New reason types came with this surface, so a skipped row can say *why* instead of falling back to a generic "scheduled optimization": `SessionComplete`, `AppliancePaused`, `NothingConnected`, `DeadlinePassed`, `WaitingForCheaperSlot`, `AboveOwnPriceLimit`, `BelowMinPower`, `OtherApplianceTurn`, `SupplyExhausted`, `OutsideSchedule` — grouped by the new `SessionState` and `Contention` reason categories. `ApplianceInitiatedDraw` and `PowerOffered` came with the waterfall states above.
 
-**Battery vs. charging car.** While a car charges, the house battery is either held out of it or allowed to help, according to the owner's `batteryEvDischargeMode`. Two reason types (category `BatteryState`) say which: `BatteryReservedFromEv` for the hold (`Discharge 0`) and `BatterySupportsEvCharging` for the release (`mode=Auto`). Both carry `context.batteryToEv` (`EnyoDataBusCommandReasonBatteryToEvContext`) with the owner's `mode`, the hold `trigger` (`EnyoBatteryToEvHoldTriggerEnum`: `OwnerBlocked`, `SocLimitReached`, `AllowanceSpent`, `NoMeasurement`), `socLimitPercent`, `allowanceWh` and `remainingWh`. The energy manager re-checks a hold periodically by briefly releasing the battery; that re-check sets `batteryToEv.probe: true` and should not be listed as its own entry in a command history.
+**Battery vs. charging car.** While a car charges, the house battery is either held out of it or allowed to help, according to the owner's `batteryEvDischargeMode`. Two reason types (category `BatteryState`) say which: `BatteryReservedFromEv` for the hold (`Discharge 0`) and `BatterySupportsEvCharging` for the release (`mode=Auto`). Both carry `context.batteryToEv` (`EnyoDataBusCommandReasonBatteryToEvContext`) with the owner's `mode`, the hold `trigger` (`EnyoBatteryToEvHoldTriggerEnum`: `OwnerBlocked`, `SocLimitReached`, `AllowanceSpent`, `NoMeasurement`), `socLimitPercent`, `allowanceWh` and `remainingWh`. The energy manager re-checks a hold periodically by briefly releasing the battery; that re-check sets `batteryToEv.probe: true` and should not be listed as its own entry in a command history. The car's side of the same decision is stated on the charger's command with `EvChargingFromHomeBattery` (also category `BatteryState`): `powerW` is the battery's share of the charging setpoint (never the whole setpoint), `socPercent` the battery fleet's SoC, `context.batteryToEv` the owner's mode and the session's `socLimitPercent` / `allowanceWh` / `remainingWh` (never `trigger` or `probe`), and, under `Intelligent` only, `electricityPricePerKwh` is what the stored energy costs.
 
 **Battery first on PV surplus.** When a surplus consumer (EV on PV, heating rod, heat pump boost, surplus automation) is held back or reduced because the battery is charged first up to the owner's `batteryPvPriorityTargetSocPercent`, the energy manager states `BatteryPvPriority` (category `PvSurplus`) on that consumer: `context.batteryPvPriority.targetSocPercent` for the target, `socPercent` for the pack's current SoC and `powerW` for the surplus the battery is taking — e.g. "The battery charges to 40 % first (now 28 %)."
 
@@ -4289,6 +4330,10 @@ New reason types came with this surface, so a skipped row can say *why* instead
 - `ElectricityPriceBelowThreshold` on a grid charge — the buy and the peak it is for: "Charging at 33.6 ct for the 17:00 peak at 43.7 ct."
 - `ScheduledOptimization` on a price hold (`Discharge 0`) — `sellStartIso` / `sellPricePerKwh`: "Stored energy kept for 17:00 (43.7 ct)." Not `ElectricityPriceBelowThreshold`, which would say power is cheap for a command that stops the battery.
 
+**Not enough power to start.** `BelowMinPower` (category `Contention`) carries `powerW` for the power that was available and `minPowerW` for the minimum the appliance needs to start — e.g. "Only 4.1 kW left — needs at least 4.2 kW to start."
+
+**Left to its own control.** When the energy manager deliberately does not steer an appliance — e.g. a heat pump left alone at night on a static tariff — it states `SelfManaged` (category `Other`). This is the manager's choice not to steer, not the appliance overriding a plan (`ApplianceInitiatedDraw`) or declining power (`AppliancePaused`).
+
 **Installation limits.** Power capped by a limit the owner or installer set — not the grid operator — carries `InstallationLimit` (category `Contention`) with `powerW` set to the ceiling and `context.installationLimit` = `{source, limitW}`, where `source` is `EnyoInstallationLimitSourceEnum.DesiredGridLimit` (`desiredKwLimit`) or `ChargerLimit` (`chargerLimitW`). `limitW` is in **W** even for the desired limit, which is configured in kW. `GridOperatorPowerLimitationActive` stays reserved for limits the grid operator imposed.
 
 **Grid-optimised charging.** A cost-optimised session placed in, or waiting for, a low-load hour because of `gridOptimizedEvCharging` carries `GridLoadOptimized` (category `Schedule`) with `context.placement` (chosen window and deadline) and `context.gridLoad` (`epexPricePerKwh`, `currency`). The EPEX price is a grid-load proxy, not what the customer pays, so the text must not promise a saving — e.g. "Charging from 02:00, when the grid is less busy — ready by 07:00."

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

@@ -1,6 +1,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";
 export type EnergyAppPackageLanguage = 'de' | 'en';
 export declare enum EnergyAppPackageCategory {
     Inverter = "inverter",
@@ -658,6 +659,147 @@ export interface EnergyAppPackageDefinition {
      * Only relevant when {@link firmware} is declared.
      */
     firmwareMode?: EnergyAppPackageFirmwareMode;
+    /**
+     * The package's static **manual setup** onboarding guide (v2). It is
+     * optional and there is at most one. The enyo CLI reads it at release time
+     * and ships it with the package version, where enyo renders it as a
+     * printable PDF installation manual.
+     *
+     * ## What it is for
+     *
+     * The guides an app returns from
+     * {@link EnergyAppOnboardingV2.registerOnboardingGuidesHandler} are
+     * interactive and only exist on a device where the app is running. This
+     * guide is the opposite: a fixed document that exists as soon as the
+     * package is released. An installer can read it on paper before the
+     * device is even powered. It is written with the same v2 guide model, so
+     * an app that already has an interactive manual setup flow can usually
+     * declare the same steps here.
+     *
+     * It does not take part in onboarding runs. It is never offered by the
+     * host, never addressed by name and never compared against the guides from
+     * the runtime handler, so there are no naming or precedence rules between
+     * the two.
+     *
+     * ## What it may contain
+     *
+     * Paper cannot scan the network or ask the app anything, so the guide is
+     * limited to a manual setup the installer can follow by reading. The
+     * following rules are enforced by `validatePackageOnboardingGuide()`, and
+     * the CLI refuses the release if any of them is broken:
+     *
+     * | Rule | Why |
+     * |---|---|
+     * | `startVariant` is {@link EnyoOnboardingV2StartVariant.ManualSetup} | The document describes a manual setup, nothing else. |
+     * | `requiresNetworkScan: false` is set explicitly | The default is `true`, and a printed manual has no scan to rely on. |
+     * | No `network-scan` or `device-test` action blocks | Both act on devices found by a scan. |
+     * | No `device-select` or `eebus-device-select` blocks | Both pick from devices the host discovered. |
+     * | No `dynamic` blocks | Their value is resolved by the app at runtime and does not exist when the PDF is rendered. |
+     * | No `start-variant` targets | They lead into another, scan-based guide that is not part of the document. |
+     * | No `applianceId`, `vendorId` or `modelIds` | A document is not bound to an appliance, and enyo derives vendor and models from the package. |
+     * | Plain JSON only (no functions, `Date`s, `undefined` in arrays, class instances) | The CLI serializes the guide into the release. |
+     * | Every image block `file` is declared in {@link files} | Otherwise the PDF has a hole where the image belongs. |
+     *
+     * Everything else is allowed. Content blocks (text, headline, bullets,
+     * image, hint, link) render as they are. Interactive blocks (choice,
+     * select, input, credentials, auth, additional-setup and the
+     * `connection-check` / `ocpp-connect` actions) render as instructions,
+     * and their outcomes and transitions become the branches of the document
+     * ("if the device is not reachable, continue with …"). Give every
+     * outcome a label that reads well on paper.
+     *
+     * `name` is optional and has no meaning here.
+     *
+     * ## How to write one
+     *
+     * 1. Put the guide in its own file (for example
+     *    `src/onboarding/manual-setup.guide.ts`) and build it with
+     *    `defineOnboardingGuideV2()`, the `onboardingV2Block.*` and
+     *    `onboardingV2Target.*` factories, and the `onContinueV2()` /
+     *    `onOutcomeV2()` transition helpers.
+     * 2. Keep the file free of runtime dependencies. The CLI loads it while
+     *    loading this definition, outside the app sandbox, so it must not
+     *    touch the SDK instance, storage, the network or environment state.
+     * 3. Import it here and assign it to `onboardingGuide`.
+     * 4. Check it locally with `validatePackageOnboardingGuide(definition)`.
+     * 5. Release. The CLI validates the guide again and aborts on errors.
+     *
+     * ```typescript
+     * // src/onboarding/manual-setup.guide.ts
+     * import {
+     *     defineOnboardingGuideV2,
+     *     EnyoDeviceTestOutcomeEnum,
+     *     EnyoOnboardingV2InputValueType,
+     *     EnyoOnboardingV2StartVariant,
+     *     onboardingV2Block,
+     *     onboardingV2Target,
+     *     onContinueV2,
+     *     onOutcomeV2,
+     * } from '@enyo-energy/energy-app-sdk';
+     *
+     * const t = (de: string, en: string) => [
+     *     {language: 'de' as const, value: de},
+     *     {language: 'en' as const, value: en},
+     * ];
+     *
+     * export const manualSetupGuide = defineOnboardingGuideV2({
+     *     title: t('Wechselrichter manuell einrichten', 'Set up the inverter manually'),
+     *     startVariant: EnyoOnboardingV2StartVariant.ManualSetup,
+     *     requiresNetworkScan: false,
+     *     startStepId: 'prepare',
+     *     steps: [
+     *         {
+     *             id: 'prepare',
+     *             name: 'modbus-aktivieren',
+     *             title: t('Modbus TCP aktivieren', 'Enable Modbus TCP'),
+     *             blocks: [
+     *                 onboardingV2Block.text('intro', t(
+     *                     'Aktiviere Modbus TCP im Webinterface des Wechselrichters.',
+     *                     'Enable Modbus TCP in the inverter web interface.',
+     *                 )),
+     *                 onboardingV2Block.imageFile('menu', 'modbus-menu', t('Menü', 'Menu')),
+     *             ],
+     *             transitions: [onContinueV2(onboardingV2Target.step('ip'))],
+     *         },
+     *         {
+     *             id: 'ip',
+     *             name: 'ip-eingeben',
+     *             title: t('IP-Adresse eingeben', 'Enter the IP address'),
+     *             blocks: [
+     *                 onboardingV2Block.input(
+     *                     'device-ip',
+     *                     EnyoOnboardingV2InputValueType.IpAddress,
+     *                     t('IP-Adresse des Wechselrichters', 'Inverter IP address'),
+     *                     t('Verbindung prüfen', 'Check connection'),
+     *                     [
+     *                         {id: 'ok', value: EnyoDeviceTestOutcomeEnum.AppliancesCreated, label: t('Verbunden', 'Connected')},
+     *                         {id: 'unreachable', value: EnyoDeviceTestOutcomeEnum.Unreachable, label: t('Nicht erreichbar', 'Unreachable')},
+     *                     ],
+     *                     {placeholder: t('z. B. 192.168.1.42', 'e.g. 192.168.1.42')},
+     *                 ),
+     *             ],
+     *             transitions: [
+     *                 onOutcomeV2('device-ip', 'ok', onboardingV2Target.success()),
+     *                 onOutcomeV2('device-ip', 'unreachable', onboardingV2Target.step('prepare')),
+     *             ],
+     *         },
+     *     ],
+     * });
+     *
+     * // energy-app.package.ts
+     * import {defineEnergyAppPackage, definePublicFile} from '@enyo-energy/energy-app-sdk';
+     * import {manualSetupGuide} from './src/onboarding/manual-setup.guide.js';
+     *
+     * export default defineEnergyAppPackage({
+     *     // ...
+     *     files: [definePublicFile({name: 'modbus-menu', path: './assets/modbus-menu.png'})],
+     *     onboardingGuide: manualSetupGuide,
+     * });
+     * ```
+     *
+     * Omit the field for packages that have no manual setup to document.
+     */
+    onboardingGuide?: EnyoOnboardingV2Guide;
 }
 /**
  * Defines an Energy App package with automatic SDK version injection.

package/dist/cjs/implementations/onboarding-v2/package-onboarding-guide-validators.cjs

@@ -0,0 +1,213 @@
+"use strict";
+/**
+ * Client-side validator for the static manual setup guide declared in a
+ * package definition ({@link EnergyAppPackageDefinition.onboardingGuide}).
+ *
+ * The guide leaves the app repository as data: the enyo CLI reads it at release
+ * time and enyo renders it as a printable PDF. Nothing on paper can scan the
+ * network or ask the app for a value, so on top of the regular graph checks of
+ * {@link validateOnboardingGuideV2} this rejects everything that only works in
+ * an interactive run — scans, device pickers, device tests, dynamic values —
+ * and everything the CLI cannot serialize.
+ *
+ * Use {@link validatePackageOnboardingGuide} for the non-throwing result, or
+ * {@link assertValidPackageOnboardingGuide} to throw on failure.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PackageOnboardingGuideValidationError = exports.PACKAGE_ONBOARDING_GUIDE_START_VARIANT = void 0;
+exports.validatePackageOnboardingGuide = validatePackageOnboardingGuide;
+exports.assertValidPackageOnboardingGuide = assertValidPackageOnboardingGuide;
+const enyo_onboarding_v2_js_1 = require("../../types/enyo-onboarding-v2.cjs");
+const onboarding_v2_validators_js_1 = require("./onboarding-v2-validators.cjs");
+/**
+ * The only start variant a package's static guide may use. The guide documents
+ * a setup the installer performs by hand.
+ */
+exports.PACKAGE_ONBOARDING_GUIDE_START_VARIANT = enyo_onboarding_v2_js_1.EnyoOnboardingV2StartVariant.ManualSetup;
+/**
+ * Thrown by {@link assertValidPackageOnboardingGuide} when a package's static
+ * onboarding guide fails validation. The message lists every blocking error so
+ * callers can surface them directly.
+ */
+class PackageOnboardingGuideValidationError extends Error {
+    /** The individual blocking errors that caused the failure. */
+    errors;
+    /**
+     * @param errors - The blocking validation errors.
+     */
+    constructor(errors) {
+        super(`Invalid package onboarding guide:\n- ${errors.join('\n- ')}`);
+        this.name = 'PackageOnboardingGuideValidationError';
+        this.errors = errors;
+    }
+}
+exports.PackageOnboardingGuideValidationError = PackageOnboardingGuideValidationError;
+/** Action kinds that act on scanned devices and therefore cannot be printed. */
+const FORBIDDEN_ACTIONS = new Set([
+    enyo_onboarding_v2_js_1.EnyoOnboardingV2ActionKind.NetworkScan,
+    enyo_onboarding_v2_js_1.EnyoOnboardingV2ActionKind.DeviceTest,
+]);
+/**
+ * Block types that only exist in an interactive run, with the reason shown to
+ * the author.
+ */
+const FORBIDDEN_BLOCKS = new Map([
+    [enyo_onboarding_v2_js_1.EnyoOnboardingV2BlockType.DeviceSelect, 'it picks from devices the host discovered'],
+    [enyo_onboarding_v2_js_1.EnyoOnboardingV2BlockType.EebusDeviceSelect, 'it picks from devices the host discovered'],
+    [enyo_onboarding_v2_js_1.EnyoOnboardingV2BlockType.Dynamic, 'its value is resolved by the app at runtime and does not exist when the PDF is rendered'],
+]);
+/**
+ * Validates the static manual setup guide of a package: the regular v2 graph
+ * checks (with image references resolved against the package's `files`), the
+ * manual-setup-only rules, and that the guide is plain JSON the CLI can ship.
+ *
+ * A package without an `onboardingGuide` is trivially valid.
+ *
+ * @param definition - The package definition, or just its `onboardingGuide`
+ *   and `files`.
+ * @returns The {@link PackageOnboardingGuideValidationResult}.
+ *
+ * @example
+ * ```typescript
+ * const {ok, errors} = validatePackageOnboardingGuide(packageDef);
+ * if (!ok) throw new Error(errors.join('\n'));
+ * ```
+ */
+function validatePackageOnboardingGuide(definition) {
+    const errors = [];
+    const warnings = [];
+    const guide = definition.onboardingGuide;
+    if (guide === undefined)
+        return { ok: true, errors, warnings };
+    if (guide === null || typeof guide !== 'object' || Array.isArray(guide)) {
+        errors.push('`onboardingGuide` must be a single guide object — a package declares at most one.');
+        return { ok: false, errors, warnings };
+    }
+    // Not plain data means not a guide shape the graph checks can walk safely.
+    collectNonJsonValues(guide, 'onboardingGuide', errors);
+    if (errors.length > 0)
+        return { ok: false, errors, warnings };
+    const base = (0, onboarding_v2_validators_js_1.validateOnboardingGuideV2)(guide, { files: definition.files });
+    errors.push(...base.errors);
+    warnings.push(...base.warnings);
+    validateManualSetupOnly(guide, errors);
+    return { ok: errors.length === 0, errors, warnings };
+}
+/**
+ * Like {@link validatePackageOnboardingGuide}, but throws
+ * {@link PackageOnboardingGuideValidationError} when there are blocking errors.
+ * Warnings never throw.
+ *
+ * @param definition - The package definition, or just its `onboardingGuide`
+ *   and `files`.
+ * @returns The declared guide, or `undefined` when the package declares none.
+ * @throws {PackageOnboardingGuideValidationError} When validation produces any error.
+ */
+function assertValidPackageOnboardingGuide(definition) {
+    const { ok, errors } = validatePackageOnboardingGuide(definition);
+    if (!ok)
+        throw new PackageOnboardingGuideValidationError(errors);
+    return definition.onboardingGuide;
+}
+/**
+ * Applies the rules that make a guide printable: manual setup variant, no
+ * scan, nothing that depends on discovered devices or runtime values, no link
+ * into another guide, and no appliance or catalog binding.
+ *
+ * @param guide - The guide being validated.
+ * @param errors - Collector for blocking problems.
+ */
+function validateManualSetupOnly(guide, errors) {
+    if (guide.startVariant !== exports.PACKAGE_ONBOARDING_GUIDE_START_VARIANT) {
+        errors.push(`\`startVariant\` must be "${exports.PACKAGE_ONBOARDING_GUIDE_START_VARIANT}" — the package guide ` +
+            `documents a manual setup, got "${guide.startVariant}".`);
+    }
+    if (guide.requiresNetworkScan !== false) {
+        errors.push('`requiresNetworkScan` must be set to `false` — it defaults to `true`, and a printed ' +
+            'manual has no scan to rely on.');
+    }
+    if (guide.applianceId !== undefined) {
+        errors.push('`applianceId` must not be set — a printed manual is not bound to an appliance.');
+    }
+    if (guide.vendorId !== undefined || guide.modelIds !== undefined) {
+        errors.push('`vendorId` / `modelIds` must not be set — enyo derives them from the package and its ' +
+            '`compatibility` list.');
+    }
+    for (const [i, step] of (guide.steps ?? []).entries()) {
+        const at = `steps[${i}] (${step.name || '?'})`;
+        for (const block of step.blocks ?? []) {
+            const reason = FORBIDDEN_BLOCKS.get(block.type);
+            if (reason) {
+                errors.push(`${at}: ${block.type} block "${block.id}" is not allowed in the package guide — ${reason}.`);
+            }
+            else if (block.type === enyo_onboarding_v2_js_1.EnyoOnboardingV2BlockType.Action && FORBIDDEN_ACTIONS.has(block.action)) {
+                errors.push(`${at}: ${block.action} action "${block.id}" is not allowed in the package guide — ` +
+                    'it acts on devices found by a scan.');
+            }
+        }
+        for (const transition of step.transitions ?? []) {
+            if (transition.target?.type === enyo_onboarding_v2_js_1.EnyoOnboardingV2TargetType.StartVariant) {
+                errors.push(`${at}: transition "${transition.id}" leads to start variant "${transition.target.variant}" — ` +
+                    'the package guide cannot hand over to another guide.');
+            }
+        }
+    }
+}
+/**
+ * Walks a value and reports everything that does not survive a JSON round trip
+ * unchanged: functions, symbols, bigints, non-finite numbers, `undefined` array
+ * entries, and objects that are not plain objects (class instances, `Date`,
+ * `Map`, …). `undefined` object properties are fine — they are simply dropped.
+ *
+ * @param value - The value to inspect.
+ * @param path - Human-readable location of `value`, used in messages.
+ * @param errors - Collector for blocking problems.
+ * @param seen - Objects already on the current path, to report cycles.
+ */
+function collectNonJsonValues(value, path, errors, seen = new Set()) {
+    switch (typeof value) {
+        case 'string':
+        case 'boolean':
+            return;
+        case 'number':
+            if (!Number.isFinite(value))
+                errors.push(`${path}: ${value} is not representable in JSON.`);
+            return;
+        case 'undefined':
+            return;
+        case 'function':
+        case 'symbol':
+        case 'bigint':
+            errors.push(`${path}: a ${typeof value} cannot be serialized into the release — use plain data only.`);
+            return;
+    }
+    if (value === null)
+        return;
+    const obj = value;
+    if (seen.has(obj)) {
+        errors.push(`${path}: circular reference — the guide must be a tree of plain data.`);
+        return;
+    }
+    if (Array.isArray(obj)) {
+        seen.add(obj);
+        obj.forEach((entry, i) => {
+            if (entry === undefined)
+                errors.push(`${path}[${i}]: undefined array entries become null in JSON.`);
+            else
+                collectNonJsonValues(entry, `${path}[${i}]`, errors, seen);
+        });
+        seen.delete(obj);
+        return;
+    }
+    const proto = Object.getPrototypeOf(obj);
+    if (proto !== Object.prototype && proto !== null) {
+        const kind = obj.constructor?.name ?? 'non-plain object';
+        errors.push(`${path}: ${kind} is not plain data — use object literals, strings, numbers and booleans.`);
+        return;
+    }
+    seen.add(obj);
+    for (const [key, entry] of Object.entries(obj)) {
+        collectNonJsonValues(entry, `${path}.${key}`, errors, seen);
+    }
+    seen.delete(obj);
+}

package/dist/cjs/implementations/onboarding-v2/package-onboarding-guide-validators.d.cts

@@ -0,0 +1,75 @@
+/**
+ * Client-side validator for the static manual setup guide declared in a
+ * package definition ({@link EnergyAppPackageDefinition.onboardingGuide}).
+ *
+ * The guide leaves the app repository as data: the enyo CLI reads it at release
+ * time and enyo renders it as a printable PDF. Nothing on paper can scan the
+ * network or ask the app for a value, so on top of the regular graph checks of
+ * {@link validateOnboardingGuideV2} this rejects everything that only works in
+ * an interactive run — scans, device pickers, device tests, dynamic values —
+ * and everything the CLI cannot serialize.
+ *
+ * Use {@link validatePackageOnboardingGuide} for the non-throwing result, or
+ * {@link assertValidPackageOnboardingGuide} to throw on failure.
+ */
+import type { EnergyAppPackageDefinition } from '../../energy-app-package-definition.cjs';
+import { EnyoOnboardingV2StartVariant } from '../../types/enyo-onboarding-v2.cjs';
+import type { EnyoOnboardingV2Guide } from '../../types/enyo-onboarding-v2.cjs';
+/**
+ * The only start variant a package's static guide may use. The guide documents
+ * a setup the installer performs by hand.
+ */
+export declare const PACKAGE_ONBOARDING_GUIDE_START_VARIANT = EnyoOnboardingV2StartVariant.ManualSetup;
+/**
+ * Thrown by {@link assertValidPackageOnboardingGuide} when a package's static
+ * onboarding guide fails validation. The message lists every blocking error so
+ * callers can surface them directly.
+ */
+export declare class PackageOnboardingGuideValidationError extends Error {
+    /** The individual blocking errors that caused the failure. */
+    readonly errors: string[];
+    /**
+     * @param errors - The blocking validation errors.
+     */
+    constructor(errors: string[]);
+}
+/** The outcome of validating a package's static onboarding guide. */
+export interface PackageOnboardingGuideValidationResult {
+    /** True when there are no blocking `errors` (warnings are still allowed). */
+    ok: boolean;
+    /** Blocking problems — these must be fixed before releasing. */
+    errors: string[];
+    /** Advisory problems — allowed, but usually worth reviewing. */
+    warnings: string[];
+}
+/** The parts of a package definition the static guide is validated against. */
+export type PackageOnboardingGuideSource = Pick<EnergyAppPackageDefinition, 'onboardingGuide' | 'files'>;
+/**
+ * Validates the static manual setup guide of a package: the regular v2 graph
+ * checks (with image references resolved against the package's `files`), the
+ * manual-setup-only rules, and that the guide is plain JSON the CLI can ship.
+ *
+ * A package without an `onboardingGuide` is trivially valid.
+ *
+ * @param definition - The package definition, or just its `onboardingGuide`
+ *   and `files`.
+ * @returns The {@link PackageOnboardingGuideValidationResult}.
+ *
+ * @example
+ * ```typescript
+ * const {ok, errors} = validatePackageOnboardingGuide(packageDef);
+ * if (!ok) throw new Error(errors.join('\n'));
+ * ```
+ */
+export declare function validatePackageOnboardingGuide(definition: PackageOnboardingGuideSource): PackageOnboardingGuideValidationResult;
+/**
+ * Like {@link validatePackageOnboardingGuide}, but throws
+ * {@link PackageOnboardingGuideValidationError} when there are blocking errors.
+ * Warnings never throw.
+ *
+ * @param definition - The package definition, or just its `onboardingGuide`
+ *   and `files`.
+ * @returns The declared guide, or `undefined` when the package declares none.
+ * @throws {PackageOnboardingGuideValidationError} When validation produces any error.
+ */
+export declare function assertValidPackageOnboardingGuide(definition: PackageOnboardingGuideSource): EnyoOnboardingV2Guide | undefined;

package/dist/cjs/index.cjs

@@ -115,6 +115,7 @@ __exportStar(require("./packages/energy-app-onboarding.cjs"), exports);
 __exportStar(require("./types/enyo-onboarding-v2.cjs"), exports);
 __exportStar(require("./implementations/onboarding-v2/define-onboarding-guide-v2.cjs"), exports);
 __exportStar(require("./implementations/onboarding-v2/onboarding-v2-validators.cjs"), exports);
+__exportStar(require("./implementations/onboarding-v2/package-onboarding-guide-validators.cjs"), exports);
 __exportStar(require("./types/enyo-onboarding-v2-provider.cjs"), exports);
 __exportStar(require("./packages/energy-app-onboarding-v2.cjs"), exports);
 __exportStar(require("./implementations/onboarding-v2/onboarding-v2-provider-validators.cjs"), exports);

package/dist/cjs/index.d.cts

@@ -99,6 +99,7 @@ export * from './packages/energy-app-onboarding.cjs';
 export * from './types/enyo-onboarding-v2.cjs';
 export * from './implementations/onboarding-v2/define-onboarding-guide-v2.cjs';
 export * from './implementations/onboarding-v2/onboarding-v2-validators.cjs';
+export * from './implementations/onboarding-v2/package-onboarding-guide-validators.cjs';
 export * from './types/enyo-onboarding-v2-provider.cjs';
 export * from './packages/energy-app-onboarding-v2.cjs';
 export * from './implementations/onboarding-v2/onboarding-v2-provider-validators.cjs';

package/dist/cjs/types/enyo-charger-appliance.d.cts

@@ -143,6 +143,43 @@ export interface EnyoChargerApplianceMetadata {
      * cannot switch phases.
      */
     phaseSwitchThresholdKw?: number;
+    /**
+     * Lowest charging current, in Amperes per phase, the charger can hold a
+     * session at — typically `6` (the IEC 61851 minimum), higher on chargers
+     * that cannot regulate down that far.
+     *
+     * The EMS must not issue a non-zero current limit below it; a session is
+     * held at the higher of this value and the vehicle's
+     * {@link EnyoVehicle.minChargingCurrentAmpere}. Omit when unknown.
+     */
+    minChargingCurrentAmpere?: number;
+    /**
+     * Whether a charging session on this charger must not be paused once it
+     * has started — e.g. chargers that end the session or need a re-plug
+     * when the current is set to `0`.
+     *
+     * When `true`, the EMS must not pause the session (setpoint `0`) but hold
+     * it at least at its minimum current until it is complete. Applies if
+     * either this or the vehicle's {@link EnyoVehicle.cannotBePaused} is
+     * `true`. Omitted means `false`.
+     *
+     * @default false
+     */
+    cannotBePaused?: boolean;
+    /**
+     * Whether the EMS must not switch phases (1 ↔ 3) on this charger, even
+     * though the hardware supports it (see {@link availablePhases}) — e.g.
+     * because the installer disabled it or switching proved unreliable.
+     *
+     * When `true`, sessions stay in the phase configuration they started in,
+     * and {@link phaseSwitchThresholdKw}, {@link phaseSwitchDelaySeconds} and
+     * {@link phaseSwitchIntervalSeconds} are not used. Applies if either this
+     * or the vehicle's {@link EnyoVehicle.phaseSwitchDisabled} is `true`.
+     * Omitted means `false`.
+     *
+     * @default false
+     */
+    phaseSwitchDisabled?: boolean;
     /**
      * Granularity, in Amperes, at which the charging current limit can be set
      * on this charger. Any current limit the EMS issues should be a multiple of
@@ -166,6 +203,26 @@ export interface EnyoChargerApplianceMetadata {
      *   `ThreeToOnePhaseSwitch` feature)
      */
     availablePhases?: EnyoChargerAppliancePhase[];
+    /**
+     * Time, in seconds, the charger needs to carry out a phase switch after it
+     * has been triggered (e.g. 1 → 3 phases or 3 → 1 phase).
+     *
+     * During this delay the charger is still operating in the previous phase
+     * configuration; the EMS should not expect the new phase count to be in
+     * effect until it has elapsed. Only meaningful on chargers that can switch
+     * phases (see {@link availablePhases}). Omit when unknown.
+     */
+    phaseSwitchDelaySeconds?: number;
+    /**
+     * Minimum time, in seconds, the charger has to stay in a phase
+     * configuration after a phase switch before another phase switch is
+     * possible.
+     *
+     * The EMS must not trigger a new phase switch until this interval has
+     * passed since the last switch. Only meaningful on chargers that can switch
+     * phases (see {@link availablePhases}). Omit when unknown.
+     */
+    phaseSwitchIntervalSeconds?: number;
     /**
      * Whether the energy manager is allowed to actively control (steer) this
      * charger. When `false`, the charger is treated as read-only/monitor-only