@enyo-energy/energy-app-sdk 1.31.0 → 1.32.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)
@@ -2851,6 +2852,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 +4317,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 %)."
 

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-data-bus-value.cjs

@@ -263,6 +263,37 @@ var EnyoDataBusCommandReasonTypeEnum;
      * {@link EnyoDataBusCommandReasonCategoryEnum.BatteryState}.
      */
     EnyoDataBusCommandReasonTypeEnum["BatterySupportsEvCharging"] = "battery-supports-ev-charging";
+    /**
+     * The car charges on energy from the house battery, within the owner's
+     * battery-to-EV setting (`batteryEvDischargeMode`).
+     *
+     * Stated on the CHARGER's command by the decision maker that routed the
+     * battery's energy into the car — never inferred from the battery's
+     * measured discharge. The battery states its own side of the same decision
+     * with {@link BatterySupportsEvCharging} (released) or
+     * {@link BatteryReservedFromEv} (held); this reason is the car's side, and
+     * the two are sent together.
+     *
+     * Fields:
+     * - {@link EnyoDataBusCommandReason.powerW}: the battery's share of the
+     *   charging setpoint, in W. The rest of the setpoint is solar. Never the
+     *   whole setpoint.
+     * - {@link EnyoDataBusCommandReason.socPercent}: the battery fleet's current
+     *   SoC.
+     * - {@link EnyoDataBusCommandReasonContext.batteryToEv}: the owner's mode and
+     *   where the session stands against it — `socLimitPercent` under
+     *   `SocLimit`, `allowanceWh` under `FixedWh`, `remainingWh` under both.
+     *   `trigger` and `probe` are never set here: they describe a battery hold.
+     * - {@link EnyoDataBusCommandReason.electricityPricePerKwh}: under
+     *   `Intelligent` only, what the stored energy costs, which the car's own
+     *   price limit was compared against. Absent under `SocLimit` / `FixedWh`,
+     *   which feed the car at any stored price.
+     *
+     * Told apart from {@link BatteryCapacityAvailable}, which says only that a
+     * battery can supply power and names no owner setting. Category
+     * {@link EnyoDataBusCommandReasonCategoryEnum.BatteryState}.
+     */
+    EnyoDataBusCommandReasonTypeEnum["EvChargingFromHomeBattery"] = "ev-charging-from-home-battery";
     /**
      * The appliance was switched off a moment ago and is held off for its
      * declared minimum off-time, so it is not cycled on and off. Stated by the

package/dist/cjs/types/enyo-data-bus-value.d.cts

@@ -279,6 +279,37 @@ export declare enum EnyoDataBusCommandReasonTypeEnum {
      * {@link EnyoDataBusCommandReasonCategoryEnum.BatteryState}.
      */
     BatterySupportsEvCharging = "battery-supports-ev-charging",
+    /**
+     * The car charges on energy from the house battery, within the owner's
+     * battery-to-EV setting (`batteryEvDischargeMode`).
+     *
+     * Stated on the CHARGER's command by the decision maker that routed the
+     * battery's energy into the car — never inferred from the battery's
+     * measured discharge. The battery states its own side of the same decision
+     * with {@link BatterySupportsEvCharging} (released) or
+     * {@link BatteryReservedFromEv} (held); this reason is the car's side, and
+     * the two are sent together.
+     *
+     * Fields:
+     * - {@link EnyoDataBusCommandReason.powerW}: the battery's share of the
+     *   charging setpoint, in W. The rest of the setpoint is solar. Never the
+     *   whole setpoint.
+     * - {@link EnyoDataBusCommandReason.socPercent}: the battery fleet's current
+     *   SoC.
+     * - {@link EnyoDataBusCommandReasonContext.batteryToEv}: the owner's mode and
+     *   where the session stands against it — `socLimitPercent` under
+     *   `SocLimit`, `allowanceWh` under `FixedWh`, `remainingWh` under both.
+     *   `trigger` and `probe` are never set here: they describe a battery hold.
+     * - {@link EnyoDataBusCommandReason.electricityPricePerKwh}: under
+     *   `Intelligent` only, what the stored energy costs, which the car's own
+     *   price limit was compared against. Absent under `SocLimit` / `FixedWh`,
+     *   which feed the car at any stored price.
+     *
+     * Told apart from {@link BatteryCapacityAvailable}, which says only that a
+     * battery can supply power and names no owner setting. Category
+     * {@link EnyoDataBusCommandReasonCategoryEnum.BatteryState}.
+     */
+    EvChargingFromHomeBattery = "ev-charging-from-home-battery",
     /**
      * The appliance was switched off a moment ago and is held off for its
      * declared minimum off-time, so it is not cycled on and off. Stated by the
@@ -675,7 +706,10 @@ export interface EnyoDataBusCommandReasonContext {
      * The owner's battery-to-EV setting (`batteryEvDischargeMode`) and where
      * the charging session stands against it. Set on
      * {@link EnyoDataBusCommandReasonTypeEnum.BatteryReservedFromEv} and
-     * {@link EnyoDataBusCommandReasonTypeEnum.BatterySupportsEvCharging}.
+     * {@link EnyoDataBusCommandReasonTypeEnum.BatterySupportsEvCharging} (the
+     * battery's command), and on
+     * {@link EnyoDataBusCommandReasonTypeEnum.EvChargingFromHomeBattery} (the
+     * charger's command).
      */
     batteryToEv?: EnyoDataBusCommandReasonBatteryToEvContext;
     /**
@@ -962,8 +996,9 @@ export declare enum EnyoBatteryToEvHoldTriggerEnum {
 /**
  * The owner's battery-to-EV setting (`batteryEvDischargeMode`) and where
  * the current charging session stands against it — the structured backing of
- * {@link EnyoDataBusCommandReasonTypeEnum.BatteryReservedFromEv} and
- * {@link EnyoDataBusCommandReasonTypeEnum.BatterySupportsEvCharging}.
+ * {@link EnyoDataBusCommandReasonTypeEnum.BatteryReservedFromEv},
+ * {@link EnyoDataBusCommandReasonTypeEnum.BatterySupportsEvCharging} and
+ * {@link EnyoDataBusCommandReasonTypeEnum.EvChargingFromHomeBattery}.
  *
  * All energy values are in watt-hours (Wh).
  *
@@ -994,6 +1029,20 @@ export declare enum EnyoBatteryToEvHoldTriggerEnum {
  *     }},
  * };
  *
+ * // The charger's side of the same decision: 2.4 kW of the car's setpoint is
+ * // the battery's, which may go on down to 50 %:
+ * const charging: EnyoDataBusCommandReason = {
+ *     type: EnyoDataBusCommandReasonTypeEnum.EvChargingFromHomeBattery,
+ *     category: EnyoDataBusCommandReasonCategoryEnum.BatteryState,
+ *     powerW: 2400,
+ *     socPercent: 79,
+ *     context: {batteryToEv: {
+ *         mode: EnergyManagerBatteryEvDischargeModeEnum.SocLimit,
+ *         socLimitPercent: 50,
+ *         remainingWh: 3895,
+ *     }},
+ * };
+ *
  * // The periodic re-check of an existing hold — not a new decision:
  * const probe: EnyoDataBusCommandReason = {
  *     type: EnyoDataBusCommandReasonTypeEnum.BatterySupportsEvCharging,
@@ -1014,6 +1063,7 @@ export interface EnyoDataBusCommandReasonBatteryToEvContext {
     /**
      * Why the battery is held. Set on
      * {@link EnyoDataBusCommandReasonTypeEnum.BatteryReservedFromEv} only.
+     * Never set on {@link EnyoDataBusCommandReasonTypeEnum.EvChargingFromHomeBattery}.
      */
     trigger?: EnyoBatteryToEvHoldTriggerEnum;
     /**
@@ -1036,6 +1086,7 @@ export interface EnyoDataBusCommandReasonBatteryToEvContext {
      * `true` for a short re-check of an existing hold: the battery is offered
      * `Auto` to see whether it still drains into the car. Not a change of
      * decision — consumers SHOULD NOT list it as a separate history entry.
+     * Never set on {@link EnyoDataBusCommandReasonTypeEnum.EvChargingFromHomeBattery}.
      */
     probe?: boolean;
 }