@enyo-energy/energy-app-sdk 0.0.192 → 0.0.194

package/README.md

@@ -2054,6 +2054,16 @@ Drives an EV wallbox / charger. Has the richest command surface of all integrati
   - `publishChargingMeterValues(applianceId, data)` — periodic meter values during a session.
   - `publishMaxChargingPowerChanged(applianceId, maxChargingPowerKw)` — e.g. on thermal derating.
   - `publishChargerStatusChanged(applianceId, data)` — OCPP-style status changes.
+  - `publishEnergyManagementChargingState(applianceId, data)` — the app's own continuously
+    updated state for the energy manager. Facts only: `activePhases` (the phase count in
+    force), `phaseSwitching` (`supported` / `available` right now, `availableFromIso` when
+    it is barred until a known time, `inProgress`), `appliedCurrentLimitA` and the
+    `appliedPowerW` it implies, `lastLimitRequest` (`accepted` \| `clamped` \| `rejected`,
+    with what was requested), and `measuredAtIso` — when the reading was taken, as opposed
+    to when the message was sent. No recommended minimum power, no suggested setpoint,
+    nothing derived from the manager's own plan; static nameplate data stays in the
+    appliance metadata. Republish the **complete** payload on every change and periodically
+    as a heartbeat — an omitted field means "unknown", never "unchanged".
 
 ```typescript
 class MyWallbox extends WallboxIntegrationEnergyApp {

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

@@ -228,6 +228,18 @@ export interface EnergyAppPackageCompatibilityModel {
      * upgrade graph in {@link EnergyAppPackageDefinition.firmware} instead.
      */
     minimumFirmwareVersion?: string;
+    /**
+     * Optional device category of this concrete model (e.g. `Inverter`,
+     * `BatteryStorage`).
+     *
+     * Packages can support models of different kinds — a hybrid inverter plus a
+     * matching battery, for example — while
+     * {@link EnergyAppPackageDefinition.categories} only describes the package
+     * as a whole. Declaring the category per model lets the enyo Store and
+     * onboarding flows group and filter individual models correctly. Omit when
+     * the package-level categories are precise enough.
+     */
+    category?: EnergyAppPackageCategory;
     /** Optional internal note explaining model-specific caveats or limitations */
     internalComment?: string;
     /**

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

@@ -133,6 +133,83 @@ exports.onboardingV2Block = {
         outcomes,
         deviceSelection,
     }),
+    /**
+     * An OCPP-connect action block: wait for the charger to dial into enyo's
+     * CSMS after the installer has entered the dynamic OCPP URL in it.
+     *
+     * A convenience wrapper over {@link onboardingV2Block.action} that pins the
+     * action kind. Nothing is searched — an OCPP wallbox is never on the LAN, so
+     * {@link EnyoOnboardingV2ActionKind.NetworkScan} is not a substitute. Pair it
+     * with an {@link onboardingV2Block.dynamic} `ocpp-url` block on the same or a
+     * preceding step.
+     *
+     * Outcome `value`s must be {@link EnyoOnboardingV2OcppConnectOutcome} members
+     * and both must be wired — the validator enforces that, since a charger that
+     * never calls home is the common case.
+     *
+     * @param id - Stable block id, unique within the guide.
+     * @param label - Translated trigger button text (de/en).
+     * @param outcomes - The `connected` / `timeout` results; each is a routing handle.
+     */
+    ocppConnect: (id, label, outcomes) => ({
+        id,
+        type: enyo_onboarding_v2_js_1.EnyoOnboardingV2BlockType.Action,
+        action: enyo_onboarding_v2_js_1.EnyoOnboardingV2ActionKind.OcppConnect,
+        label,
+        outcomes,
+    }),
+    /**
+     * An EEBUS-pair action block: the installer picks one of the discovered
+     * EEBUS peers and the host trusts its SKI.
+     *
+     * A convenience wrapper over {@link onboardingV2Block.action} that pins the
+     * action kind. The picker is drawn from what mDNS discovery found, so the
+     * guide must have scanned — keep
+     * {@link EnyoOnboardingV2Guide.requiresNetworkScan} at its default or place
+     * a {@link EnyoOnboardingV2ActionKind.NetworkScan} block ahead of this one.
+     *
+     * Most EEBUS devices only announce themselves once pairing is enabled in
+     * their own menu or portal, and many ask for a confirmation there while the
+     * handshake runs, so put that instruction in a text/hint block on the
+     * preceding step — the app cannot do it for the installer.
+     *
+     * Outcome `value`s must be {@link EnyoOnboardingV2EebusPairOutcome} members;
+     * route `not-found` to troubleshooting and `failure` to a step describing
+     * the confirmation on the device. A retry must lead into a *second* pairing
+     * step: a back-edge onto the same step reads as a loop and ends the run.
+     *
+     * @param id - Stable block id, unique within the guide.
+     * @param label - Translated trigger button text (de/en).
+     * @param outcomes - The `paired` / `not-found` / `failure` results; each is a routing handle.
+     */
+    eebusPair: (id, label, outcomes) => ({
+        id,
+        type: enyo_onboarding_v2_js_1.EnyoOnboardingV2BlockType.Action,
+        action: enyo_onboarding_v2_js_1.EnyoOnboardingV2ActionKind.EebusPair,
+        label,
+        outcomes,
+    }),
+    /**
+     * An auth block: the installer signs into the energy app's own account
+     * system (OAuth / vendor portal).
+     *
+     * Exactly one routing handle, and it means "the login succeeded". The server
+     * decides when it fires, so the installer cannot skip it; there is no failure
+     * branch to author — a failed attempt simply keeps them on the step. Route
+     * the handle with {@link onOutcomeV2}, passing `outcome.id`.
+     *
+     * @param id - Stable block id, unique within the guide.
+     * @param label - Translated sign-in button text (de/en).
+     * @param outcome - The single success handle (`{id, label}`).
+     * @param opts - Optional translated `help` naming the account that is needed.
+     */
+    auth: (id, label, outcome, opts) => ({
+        id,
+        type: enyo_onboarding_v2_js_1.EnyoOnboardingV2BlockType.Auth,
+        label,
+        outcome,
+        help: opts?.help,
+    }),
     /**
      * A link block: a fixed URL the installer opens or copies.
      *
@@ -191,14 +268,40 @@ exports.onboardingV2Target = {
     step: (stepId) => ({ type: enyo_onboarding_v2_js_1.EnyoOnboardingV2TargetType.Step, stepId }),
     /** Exit: onboarding succeeded (hand back to the app). */
     success: () => ({ type: enyo_onboarding_v2_js_1.EnyoOnboardingV2TargetType.Success }),
-    /** Exit: escalate to enyo support. */
-    support: () => ({ type: enyo_onboarding_v2_js_1.EnyoOnboardingV2TargetType.Support }),
+    /**
+     * Exit: escalate to enyo support.
+     * @param reason - Optional short internal key describing what failed, e.g.
+     * `firmware-too-old`. Never shown to the installer; it travels with the
+     * hand-off so support knows why it arrived.
+     */
+    support: (reason) => ({
+        type: enyo_onboarding_v2_js_1.EnyoOnboardingV2TargetType.Support,
+        reason,
+    }),
     /**
      * Exit: pause the run (resumable) with a reason.
+     *
+     * For {@link EnyoOnboardingV2PauseReason.EnyoTodo} prefer
+     * {@link onboardingV2Target.enyoTakeover} — that reason is a terminal
+     * hand-off, not a park, and `resumeStepName` does not apply to it.
+     *
      * @param reason - Why the run is parked.
      * @param resumeStepName - Optional step `name` to resume at.
      */
     pause: (reason, resumeStepName) => ({ type: enyo_onboarding_v2_js_1.EnyoOnboardingV2TargetType.Pause, reason, resumeStepName }),
+    /**
+     * Exit: **enyo übernimmt** — the installer is done and enyo finishes the
+     * setup. A terminal exit alongside `success` and `support`: the app shows the
+     * takeover screen rather than returning to the cockpit.
+     *
+     * Emits the unchanged wire shape (`pause` with reason `enyo-todo`), and
+     * counts as a completing exit for {@link validateOnboardingGuideV2} — a guide
+     * that only ends here needs no `success` branch.
+     */
+    enyoTakeover: () => ({
+        type: enyo_onboarding_v2_js_1.EnyoOnboardingV2TargetType.Pause,
+        reason: enyo_onboarding_v2_js_1.EnyoOnboardingV2PauseReason.EnyoTodo,
+    }),
     /**
      * Jump into another start variant's flow for the same vendor/model.
      * @param variant - The start variant to hand off to.

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

@@ -10,8 +10,8 @@
  * before publishing.
  */
 import type { EnyoOnboardingTranslatedContent } from '../../types/enyo-onboarding.cjs';
-import { EnyoOnboardingV2ActionKind, EnyoOnboardingV2ChoiceLayout, EnyoOnboardingV2DeviceSelection } from '../../types/enyo-onboarding-v2.cjs';
-import type { EnyoOnboardingV2ActionOutcome, EnyoOnboardingV2Block, EnyoOnboardingV2ChoiceOption, EnyoOnboardingV2DynamicKind, EnyoOnboardingV2Guide, EnyoOnboardingV2HintVariant, EnyoOnboardingV2InputOutcome, EnyoOnboardingV2InputValueType, EnyoOnboardingV2PauseReason, EnyoOnboardingV2StartVariant, EnyoOnboardingV2Target, EnyoOnboardingV2Transition } from '../../types/enyo-onboarding-v2.cjs';
+import { EnyoOnboardingV2ActionKind, EnyoOnboardingV2ChoiceLayout, EnyoOnboardingV2DeviceSelection, EnyoOnboardingV2PauseReason } from '../../types/enyo-onboarding-v2.cjs';
+import type { EnyoOnboardingV2ActionOutcome, EnyoOnboardingV2AuthOutcome, EnyoOnboardingV2Block, EnyoOnboardingV2ChoiceOption, EnyoOnboardingV2DynamicKind, EnyoOnboardingV2Guide, EnyoOnboardingV2HintVariant, EnyoOnboardingV2InputOutcome, EnyoOnboardingV2InputValueType, EnyoOnboardingV2StartVariant, EnyoOnboardingV2Target, EnyoOnboardingV2Transition } from '../../types/enyo-onboarding-v2.cjs';
 /**
  * Identity helper that type-checks a v2 guide literal at definition time
  * (mirrors `defineEnergyAppPackage`). Prefer this over a bare object literal so
@@ -98,6 +98,67 @@ export declare const onboardingV2Block: {
      * @param deviceSelection - Which devices to test (defaults to `Detected`).
      */
     deviceTest: (id: string, label: EnyoOnboardingTranslatedContent[], outcomes: EnyoOnboardingV2ActionOutcome[], deviceSelection?: EnyoOnboardingV2DeviceSelection) => EnyoOnboardingV2Block;
+    /**
+     * An OCPP-connect action block: wait for the charger to dial into enyo's
+     * CSMS after the installer has entered the dynamic OCPP URL in it.
+     *
+     * A convenience wrapper over {@link onboardingV2Block.action} that pins the
+     * action kind. Nothing is searched — an OCPP wallbox is never on the LAN, so
+     * {@link EnyoOnboardingV2ActionKind.NetworkScan} is not a substitute. Pair it
+     * with an {@link onboardingV2Block.dynamic} `ocpp-url` block on the same or a
+     * preceding step.
+     *
+     * Outcome `value`s must be {@link EnyoOnboardingV2OcppConnectOutcome} members
+     * and both must be wired — the validator enforces that, since a charger that
+     * never calls home is the common case.
+     *
+     * @param id - Stable block id, unique within the guide.
+     * @param label - Translated trigger button text (de/en).
+     * @param outcomes - The `connected` / `timeout` results; each is a routing handle.
+     */
+    ocppConnect: (id: string, label: EnyoOnboardingTranslatedContent[], outcomes: EnyoOnboardingV2ActionOutcome[]) => EnyoOnboardingV2Block;
+    /**
+     * An EEBUS-pair action block: the installer picks one of the discovered
+     * EEBUS peers and the host trusts its SKI.
+     *
+     * A convenience wrapper over {@link onboardingV2Block.action} that pins the
+     * action kind. The picker is drawn from what mDNS discovery found, so the
+     * guide must have scanned — keep
+     * {@link EnyoOnboardingV2Guide.requiresNetworkScan} at its default or place
+     * a {@link EnyoOnboardingV2ActionKind.NetworkScan} block ahead of this one.
+     *
+     * Most EEBUS devices only announce themselves once pairing is enabled in
+     * their own menu or portal, and many ask for a confirmation there while the
+     * handshake runs, so put that instruction in a text/hint block on the
+     * preceding step — the app cannot do it for the installer.
+     *
+     * Outcome `value`s must be {@link EnyoOnboardingV2EebusPairOutcome} members;
+     * route `not-found` to troubleshooting and `failure` to a step describing
+     * the confirmation on the device. A retry must lead into a *second* pairing
+     * step: a back-edge onto the same step reads as a loop and ends the run.
+     *
+     * @param id - Stable block id, unique within the guide.
+     * @param label - Translated trigger button text (de/en).
+     * @param outcomes - The `paired` / `not-found` / `failure` results; each is a routing handle.
+     */
+    eebusPair: (id: string, label: EnyoOnboardingTranslatedContent[], outcomes: EnyoOnboardingV2ActionOutcome[]) => EnyoOnboardingV2Block;
+    /**
+     * An auth block: the installer signs into the energy app's own account
+     * system (OAuth / vendor portal).
+     *
+     * Exactly one routing handle, and it means "the login succeeded". The server
+     * decides when it fires, so the installer cannot skip it; there is no failure
+     * branch to author — a failed attempt simply keeps them on the step. Route
+     * the handle with {@link onOutcomeV2}, passing `outcome.id`.
+     *
+     * @param id - Stable block id, unique within the guide.
+     * @param label - Translated sign-in button text (de/en).
+     * @param outcome - The single success handle (`{id, label}`).
+     * @param opts - Optional translated `help` naming the account that is needed.
+     */
+    auth: (id: string, label: EnyoOnboardingTranslatedContent[], outcome: EnyoOnboardingV2AuthOutcome, opts?: {
+        help?: EnyoOnboardingTranslatedContent[];
+    }) => EnyoOnboardingV2Block;
     /**
      * A link block: a fixed URL the installer opens or copies.
      *
@@ -143,14 +204,34 @@ export declare const onboardingV2Target: {
     step: (stepId: string) => EnyoOnboardingV2Target;
     /** Exit: onboarding succeeded (hand back to the app). */
     success: () => EnyoOnboardingV2Target;
-    /** Exit: escalate to enyo support. */
-    support: () => EnyoOnboardingV2Target;
+    /**
+     * Exit: escalate to enyo support.
+     * @param reason - Optional short internal key describing what failed, e.g.
+     * `firmware-too-old`. Never shown to the installer; it travels with the
+     * hand-off so support knows why it arrived.
+     */
+    support: (reason?: string) => EnyoOnboardingV2Target;
     /**
      * Exit: pause the run (resumable) with a reason.
+     *
+     * For {@link EnyoOnboardingV2PauseReason.EnyoTodo} prefer
+     * {@link onboardingV2Target.enyoTakeover} — that reason is a terminal
+     * hand-off, not a park, and `resumeStepName` does not apply to it.
+     *
      * @param reason - Why the run is parked.
      * @param resumeStepName - Optional step `name` to resume at.
      */
     pause: (reason: EnyoOnboardingV2PauseReason, resumeStepName?: string) => EnyoOnboardingV2Target;
+    /**
+     * Exit: **enyo übernimmt** — the installer is done and enyo finishes the
+     * setup. A terminal exit alongside `success` and `support`: the app shows the
+     * takeover screen rather than returning to the cockpit.
+     *
+     * Emits the unchanged wire shape (`pause` with reason `enyo-todo`), and
+     * counts as a completing exit for {@link validateOnboardingGuideV2} — a guide
+     * that only ends here needs no `success` branch.
+     */
+    enyoTakeover: () => EnyoOnboardingV2Target;
     /**
      * Jump into another start variant's flow for the same vendor/model.
      * @param variant - The start variant to hand off to.

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

@@ -5,8 +5,14 @@
  * energy app can fail fast locally before publishing.
  *
  * `errors` block publishing; `warnings` are advisory (e.g. unreachable step, no
- * path to success). Use {@link validateOnboardingGuideV2} for the non-throwing
- * result, or {@link assertValidOnboardingGuideV2} to throw on the first failure.
+ * path to a completing exit). Use {@link validateOnboardingGuideV2} for the
+ * non-throwing result, or {@link assertValidOnboardingGuideV2} to throw on the
+ * first failure.
+ *
+ * A run completes either through a `success` target **or** through the
+ * "enyo übernimmt" hand-off (`pause` with reason
+ * {@link EnyoOnboardingV2PauseReason.EnyoTodo}) — both count, so a guide that
+ * legitimately ends in a hand-off is not nagged about a missing success path.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OnboardingV2ValidationError = void 0;
@@ -34,8 +40,8 @@ exports.OnboardingV2ValidationError = OnboardingV2ValidationError;
 const SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 /**
  * Structural + plausibility validation of a v2 guide graph. `errors` block
- * publishing; `warnings` are advisory (e.g. unreachable step, no path to
- * success).
+ * publishing; `warnings` are advisory (e.g. unreachable step, no path to a
+ * completing exit — `success` or the `enyo-todo` hand-off).
  *
  * @param guide - The v2 guide to validate.
  * @returns The {@link OnboardingV2ValidationResult}.
@@ -72,11 +78,12 @@ function validateOnboardingGuideV2(guide) {
         validateActionBlocks(step, at, errors, warnings);
         validateLinkBlocks(step, at, errors, warnings);
         validateInputBlocks(step, at, errors, warnings);
+        validateAuthBlocks(step, at, errors, warnings);
     }
     if (!guide.startStepId || !stepIds.has(guide.startStepId)) {
         errors.push('`startStepId` must reference an existing step.');
     }
-    let hasSuccess = false;
+    let hasCompletingExit = false;
     for (const [i, step] of guide.steps.entries()) {
         const at = `steps[${i}] (${step.name})`;
         const required = requiredHandleKeys(step);
@@ -90,14 +97,24 @@ function validateOnboardingGuideV2(guide) {
             wired.add(key);
             const tg = t.target;
             if (tg.type === enyo_onboarding_v2_js_1.EnyoOnboardingV2TargetType.Success)
-                hasSuccess = true;
+                hasCompletingExit = true;
             else if (tg.type === enyo_onboarding_v2_js_1.EnyoOnboardingV2TargetType.Step && !stepIds.has(tg.stepId)) {
                 errors.push(`${at}: transition targets missing step "${tg.stepId}".`);
             }
-            else if (tg.type === enyo_onboarding_v2_js_1.EnyoOnboardingV2TargetType.Pause &&
-                tg.resumeStepName &&
-                !stepNames.has(tg.resumeStepName)) {
-                errors.push(`${at}: pause resumeStepName "${tg.resumeStepName}" is unknown.`);
+            else if (tg.type === enyo_onboarding_v2_js_1.EnyoOnboardingV2TargetType.Pause) {
+                // "enyo übernimmt" is a terminal hand-off, not a park: it completes
+                // the run for the installer, so it satisfies the completion check
+                // and has nothing to resume at.
+                if (tg.reason === enyo_onboarding_v2_js_1.EnyoOnboardingV2PauseReason.EnyoTodo) {
+                    hasCompletingExit = true;
+                    if (tg.resumeStepName) {
+                        warnings.push(`${at}: pause reason "${enyo_onboarding_v2_js_1.EnyoOnboardingV2PauseReason.EnyoTodo}" is a hand-off to enyo, ` +
+                            `not a resumable park — resumeStepName "${tg.resumeStepName}" is ignored.`);
+                    }
+                }
+                else if (tg.resumeStepName && !stepNames.has(tg.resumeStepName)) {
+                    errors.push(`${at}: pause resumeStepName "${tg.resumeStepName}" is unknown.`);
+                }
             }
             else if (tg.type === enyo_onboarding_v2_js_1.EnyoOnboardingV2TargetType.StartVariant &&
                 tg.variant === guide.startVariant) {
@@ -117,8 +134,11 @@ function validateOnboardingGuideV2(guide) {
                 warnings.push(`step "${step.name}" is unreachable from the start.`);
         }
     }
-    if (!hasSuccess)
-        warnings.push('No branch reaches a `success` exit.');
+    if (!hasCompletingExit) {
+        warnings.push('No branch reaches a completing exit — wire a `success` target, or a `pause` with reason ' +
+            `"${enyo_onboarding_v2_js_1.EnyoOnboardingV2PauseReason.EnyoTodo}" when enyo takes the setup over.`);
+    }
+    validateNetworkScanFlag(guide, warnings);
     return { ok: errors.length === 0, errors, warnings };
 }
 /**
@@ -155,6 +175,12 @@ function validateActionBlocks(step, at, errors, warnings) {
             if (block.deviceSelection) {
                 warnings.push(`${at}: block "${block.id}" sets deviceSelection but is not a device-test action; it is ignored.`);
             }
+            if (block.action === enyo_onboarding_v2_js_1.EnyoOnboardingV2ActionKind.OcppConnect) {
+                validateOcppConnectOutcomes(block, at, errors);
+            }
+            if (block.action === enyo_onboarding_v2_js_1.EnyoOnboardingV2ActionKind.EebusPair) {
+                validateEebusPairOutcomes(block, at, errors, warnings);
+            }
             continue;
         }
         const values = new Set();
@@ -210,8 +236,17 @@ function validateLinkBlocks(step, at, errors, warnings) {
 }
 /** Every valid {@link EnyoOnboardingV2InputValueType} value. */
 const INPUT_VALUE_TYPES = new Set(Object.values(enyo_onboarding_v2_js_1.EnyoOnboardingV2InputValueType));
-/** Outcome values the host treats as "the check succeeded". */
-const POSITIVE_INPUT_OUTCOMES = new Set(['reachable', 'success', 'found']);
+/**
+ * Outcome values the host treats as "the check succeeded" — mirrors the
+ * runtime's own positive-outcome set, `paired` included, so an eebus-pair
+ * result is not read as a failure.
+ */
+const POSITIVE_INPUT_OUTCOMES = new Set([
+    'reachable',
+    'success',
+    'found',
+    enyo_onboarding_v2_js_1.EnyoOnboardingV2EebusPairOutcome.Paired,
+]);
 /**
  * The {@link EnyoDeviceTestOutcomeEnum} verdicts that collapse onto a positive
  * input outcome; every other verdict collapses onto a negative one.
@@ -284,6 +319,153 @@ function validateInputBlocks(step, at, errors, warnings) {
         }
     }
 }
+/** Every {@link EnyoOnboardingV2OcppConnectOutcome} value. */
+const OCPP_CONNECT_OUTCOMES = new Set(Object.values(enyo_onboarding_v2_js_1.EnyoOnboardingV2OcppConnectOutcome));
+/**
+ * Validates the outcomes of an {@link EnyoOnboardingV2ActionKind.OcppConnect}
+ * block.
+ *
+ * The block waits for the charger to dial into our CSMS; it can only ever report
+ * that the connection arrived or that it did not, so its outcome `value`s are
+ * closed over {@link EnyoOnboardingV2OcppConnectOutcome}. Both must be wired: a
+ * charger that never calls home — wrong URL typed, no mobile coverage in the
+ * garage — is the *common* case, and a guide without a `timeout` branch strands
+ * the installer on a spinner.
+ *
+ * @param block - The ocpp-connect action block being checked.
+ * @param at - Human-readable location prefix for messages.
+ * @param errors - Collector for blocking problems.
+ */
+function validateOcppConnectOutcomes(block, at, errors) {
+    const values = new Set();
+    for (const outcome of block.outcomes ?? []) {
+        if (!OCPP_CONNECT_OUTCOMES.has(outcome.value)) {
+            errors.push(`${at}: ocpp-connect block "${block.id}" has outcome value "${outcome.value}", which is not an EnyoOnboardingV2OcppConnectOutcome member.`);
+        }
+        else if (values.has(outcome.value)) {
+            errors.push(`${at}: ocpp-connect block "${block.id}" wires outcome value "${outcome.value}" more than once.`);
+        }
+        values.add(outcome.value);
+    }
+    for (const required of OCPP_CONNECT_OUTCOMES) {
+        if (!values.has(required)) {
+            errors.push(`${at}: ocpp-connect block "${block.id}" has no "${required}" outcome; both results must be routed.`);
+        }
+    }
+}
+/** Every {@link EnyoOnboardingV2EebusPairOutcome} value. */
+const EEBUS_PAIR_OUTCOMES = new Set(Object.values(enyo_onboarding_v2_js_1.EnyoOnboardingV2EebusPairOutcome));
+/**
+ * Validates the outcomes of an {@link EnyoOnboardingV2ActionKind.EebusPair}
+ * block.
+ *
+ * The block reports one of three things — a peer was picked and the SHIP
+ * handshake came up, discovery found nothing, or the handshake failed — so its
+ * outcome `value`s are closed over {@link EnyoOnboardingV2EebusPairOutcome}.
+ * Anything else is an outcome that can never fire.
+ *
+ * The missing `paired` branch is a warning rather than an error: it strands
+ * every successful pairing, but an author staging a guide step by step may
+ * legitimately not have wired it yet.
+ *
+ * @param block - The eebus-pair action block being checked.
+ * @param at - Human-readable location prefix for messages.
+ * @param errors - Collector for blocking problems.
+ * @param warnings - Collector for advisory problems.
+ */
+function validateEebusPairOutcomes(block, at, errors, warnings) {
+    const values = new Set();
+    for (const outcome of block.outcomes ?? []) {
+        if (!EEBUS_PAIR_OUTCOMES.has(outcome.value)) {
+            errors.push(`${at}: eebus-pair block "${block.id}" has outcome value "${outcome.value}", which is not an EnyoOnboardingV2EebusPairOutcome member.`);
+        }
+        else if (values.has(outcome.value)) {
+            errors.push(`${at}: eebus-pair block "${block.id}" wires outcome value "${outcome.value}" more than once.`);
+        }
+        values.add(outcome.value);
+    }
+    if (!values.has(enyo_onboarding_v2_js_1.EnyoOnboardingV2EebusPairOutcome.Paired)) {
+        warnings.push(`${at}: eebus-pair block "${block.id}" has no "${enyo_onboarding_v2_js_1.EnyoOnboardingV2EebusPairOutcome.Paired}" outcome — ` +
+            'a successful pairing would have nowhere to go.');
+    }
+}
+/**
+ * Validates the auth blocks of a step.
+ *
+ * An auth block has exactly one handle, and the **server** decides when it
+ * fires — there is no failure branch to author, because a failed login keeps the
+ * installer on the step to retry. So the checks are about the handle existing and
+ * being routable at all, and about the step not pretending the login is optional:
+ * a second decision block next to it would offer a way past a gate the client is
+ * not allowed to skip.
+ *
+ * @param step - The step whose blocks are checked.
+ * @param at - Human-readable location prefix for messages.
+ * @param errors - Collector for blocking problems.
+ * @param warnings - Collector for advisory problems.
+ */
+function validateAuthBlocks(step, at, errors, warnings) {
+    const authBlocks = (step.blocks ?? []).filter((b) => b.type === enyo_onboarding_v2_js_1.EnyoOnboardingV2BlockType.Auth);
+    for (const block of authBlocks) {
+        if (!block.label?.length)
+            errors.push(`${at}: auth block "${block.id}" has no label.`);
+        if (!block.outcome?.id) {
+            errors.push(`${at}: auth block "${block.id}" has no outcome id — its success handle cannot be routed.`);
+        }
+        if (!block.outcome?.label?.length) {
+            warnings.push(`${at}: auth block "${block.id}" outcome has no label.`);
+        }
+    }
+    if (authBlocks.length > 1) {
+        errors.push(`${at}: more than one auth block; a step can hold at most one login.`);
+    }
+    if (authBlocks.length === 1) {
+        const others = (step.blocks ?? []).filter((b) => b.type === enyo_onboarding_v2_js_1.EnyoOnboardingV2BlockType.Choice ||
+            b.type === enyo_onboarding_v2_js_1.EnyoOnboardingV2BlockType.Action ||
+            b.type === enyo_onboarding_v2_js_1.EnyoOnboardingV2BlockType.Input);
+        if (others.length) {
+            warnings.push(`${at}: auth block "${authBlocks[0].id}" shares the step with ${others.length} other decision block(s) — ` +
+                'those give the installer a way past a login the server gates.');
+        }
+    }
+}
+/**
+ * Checks {@link EnyoOnboardingV2Guide.requiresNetworkScan} against what the guide
+ * actually does.
+ *
+ * Opting out means "don't search, start here" — right for a device that is never
+ * on the LAN (an OCPP wallbox), wrong if the guide then relies on scan results.
+ * Both mismatches are warnings, not errors: the flag describes the host's
+ * behaviour before the guide runs, and an author may have a reason.
+ *
+ * @param guide - The guide being validated.
+ * @param warnings - Collector for advisory problems.
+ */
+function validateNetworkScanFlag(guide, warnings) {
+    if (guide.requiresNetworkScan !== false)
+        return;
+    const blocks = guide.steps.flatMap((s) => s.blocks ?? []);
+    const scansItself = blocks.some((b) => b.type === enyo_onboarding_v2_js_1.EnyoOnboardingV2BlockType.Action &&
+        b.action === enyo_onboarding_v2_js_1.EnyoOnboardingV2ActionKind.NetworkScan);
+    if (scansItself)
+        return;
+    const dependsOnDetected = blocks.some((b) => b.type === enyo_onboarding_v2_js_1.EnyoOnboardingV2BlockType.Action &&
+        b.action === enyo_onboarding_v2_js_1.EnyoOnboardingV2ActionKind.DeviceTest &&
+        (b.deviceSelection ?? enyo_onboarding_v2_js_1.EnyoOnboardingV2DeviceSelection.Detected) !==
+            enyo_onboarding_v2_js_1.EnyoOnboardingV2DeviceSelection.Current);
+    if (dependsOnDetected) {
+        warnings.push('requiresNetworkScan is false, but a device-test block selects from detected devices — ' +
+            'nothing was scanned, so it has nothing to test. Use deviceSelection "current", or run a ' +
+            'network-scan action inside the guide.');
+    }
+    const pairsEebus = blocks.some((b) => b.type === enyo_onboarding_v2_js_1.EnyoOnboardingV2BlockType.Action &&
+        b.action === enyo_onboarding_v2_js_1.EnyoOnboardingV2ActionKind.EebusPair);
+    if (pairsEebus) {
+        warnings.push('requiresNetworkScan is false, but an eebus-pair block asks the installer to pick a ' +
+            'discovered EEBUS peer — nothing was scanned, so the picker would open on an empty ' +
+            'list. Run a network-scan action inside the guide ahead of it.');
+    }
+}
 /**
  * The set of routing-handle keys a step must wire exactly once: one per
  * choice option / action outcome / input outcome, or the single `continue`
@@ -303,6 +485,9 @@ function requiredHandleKeys(step) {
             for (const o of b.outcomes)
                 keys.add(`outcome:${b.id}:${o.id}`);
         }
+        else if (b.type === enyo_onboarding_v2_js_1.EnyoOnboardingV2BlockType.Auth && b.outcome?.id) {
+            keys.add(`outcome:${b.id}:${b.outcome.id}`);
+        }
     }
     if (keys.size === 0)
         keys.add('continue');

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

@@ -4,8 +4,14 @@
  * energy app can fail fast locally before publishing.
  *
  * `errors` block publishing; `warnings` are advisory (e.g. unreachable step, no
- * path to success). Use {@link validateOnboardingGuideV2} for the non-throwing
- * result, or {@link assertValidOnboardingGuideV2} to throw on the first failure.
+ * path to a completing exit). Use {@link validateOnboardingGuideV2} for the
+ * non-throwing result, or {@link assertValidOnboardingGuideV2} to throw on the
+ * first failure.
+ *
+ * A run completes either through a `success` target **or** through the
+ * "enyo übernimmt" hand-off (`pause` with reason
+ * {@link EnyoOnboardingV2PauseReason.EnyoTodo}) — both count, so a guide that
+ * legitimately ends in a hand-off is not nagged about a missing success path.
  */
 import type { EnyoOnboardingV2Guide } from '../../types/enyo-onboarding-v2.cjs';
 /**
@@ -31,8 +37,8 @@ export interface OnboardingV2ValidationResult {
 }
 /**
  * Structural + plausibility validation of a v2 guide graph. `errors` block
- * publishing; `warnings` are advisory (e.g. unreachable step, no path to
- * success).
+ * publishing; `warnings` are advisory (e.g. unreachable step, no path to a
+ * completing exit — `success` or the `enyo-todo` hand-off).
  *
  * @param guide - The v2 guide to validate.
  * @returns The {@link OnboardingV2ValidationResult}.

package/dist/cjs/integrations/wallbox-integration-energy-app.cjs

@@ -117,6 +117,40 @@ class WallboxIntegrationEnergyApp extends integration_energy_app_js_1.Integratio
         };
         this.useDataBus().sendMessage([msg]);
     }
+    /**
+     * Publishes an `EnergyManagementChargingStateV1` message: the app's own
+     * state — the phase count in force, whether a phase switch is possible
+     * right now, the limit actually applied and the verdict on the last
+     * request — reported to the energy manager.
+     *
+     * This is a continuously updated state, not an event. Call it whenever
+     * anything in the payload changes (a phase switch starts or finishes, a
+     * cool-down expires, a new limit is applied) and periodically as a
+     * heartbeat, always passing the **complete** picture: an omitted field
+     * means "unknown", never "unchanged".
+     *
+     * Report facts, never advice: the phase count, the applied limit and the
+     * power it implies, the request verdict, the measurement timestamp — no
+     * recommended minimum power, no suggested setpoint, nothing derived from
+     * the energy manager's own plan.
+     *
+     * @param applianceId - The charger appliance the state describes.
+     * @param data - The full charging state; see
+     *   {@link EnyoDataBusEnergyManagementChargingStateV1}.
+     */
+    publishEnergyManagementChargingState(applianceId, data) {
+        const msg = {
+            id: this.generateMessageId(),
+            type: 'message',
+            message: enyo_data_bus_value_js_1.EnyoDataBusMessageEnum.EnergyManagementChargingStateV1,
+            source: this.source,
+            applianceId,
+            timestampIso: new Date().toISOString(),
+            resolution: 'dynamic',
+            data
+        };
+        this.useDataBus().sendMessage([msg]);
+    }
     /**
      * Publishes a `ChargerStatusChangedV1` message reporting the current OCPP
      * status (Available, Preparing, Charging, …).