@enyo-energy/energy-app-sdk 1.5.0 → 1.7.0

package/README.md

@@ -367,6 +367,7 @@ Energy Apps use a granular permissions system to control access to system resour
 - **`Savings`**: Publish and read back day-scoped savings reports
 - **`EpexSpotPrices`**: Read EPEX SPOT day-ahead wholesale market prices
 - **`GridFeeRegister`** / **`GridFeeUse`**: Publish / resolve dynamic grid fees (time-variable network charges)
+- **`CommandLog`**: Record and read back the commands apps issued to appliances
 
 #### Site & Identity Permissions
 
@@ -1500,6 +1501,50 @@ Notes worth respecting when producing a report:
 
 Requires the `Savings` permission.
 
+#### `useCommandLog(): EnergyAppCommandLog`
+
+Record which register, configuration key or message your app wrote to an appliance — and read those
+writes back. This is the answer to *"why did the device do that?"*: an appliance's state shows what it
+is doing now, not that you wrote holding register 40023 four seconds ago because the energy manager cut
+available power, nor that the write was rejected.
+
+```typescript
+const commandLog = energyApp.useCommandLog();
+
+await commandLog.logCommand({
+    applianceId,
+    protocol: EnyoCommandProtocolEnum.Modbus,
+    operation: 'write-single-register',
+    target: '40023',
+    previousValue: String(before),
+    newValue: String(limitW),
+    outcome: EnyoCommandOutcomeEnum.Success,
+    reason: 'energy manager reduced available power',
+});
+
+// Everything we failed to write to this appliance today.
+const failures = await commandLog.getCommands({
+    applianceId,
+    outcome: EnyoCommandOutcomeEnum.Failed,
+    fromIso: startOfDay,
+});
+```
+
+- **Writes, not reads.** Polling a register every two seconds does not belong here; recording reads
+  would bury the writes the log exists for.
+- **Log the attempt, not only the success.** `Failed`, `TimedOut` and `Rejected` entries are the ones
+  someone goes looking for. `Rejected` is separate from `Failed` on purpose — a device that answered and
+  refused is a different diagnosis from one that could not be reached.
+- **Fill `reason`.** *What* was written can be reconstructed from the device; *why* cannot.
+- **Never gate the command on the log.** Log after the write is attempted; a failure to log must not
+  surface as a failure to control the appliance.
+- **Append-only.** No update, no delete — a log the app can rewrite cannot explain an incident.
+  Retention is the host's.
+- **Reads span every app** unless you filter by `packageName`: two packages fighting over the same
+  register are invisible from one app's own entries.
+
+Requires the `CommandLog` permission.
+
 ### Operational Utilities
 
 #### `useOnboardingV2(): EnergyAppOnboardingV2`

package/dist/cjs/energy-app-permission.type.cjs

@@ -62,4 +62,5 @@ var EnergyAppPermissionTypeEnum;
     EnergyAppPermissionTypeEnum["FirmwareRegistry"] = "FirmwareRegistry";
     EnergyAppPermissionTypeEnum["GridFeeRegister"] = "GridFeeRegister";
     EnergyAppPermissionTypeEnum["GridFeeUse"] = "GridFeeUse";
+    EnergyAppPermissionTypeEnum["CommandLog"] = "CommandLog";
 })(EnergyAppPermissionTypeEnum || (exports.EnergyAppPermissionTypeEnum = EnergyAppPermissionTypeEnum = {}));

package/dist/cjs/energy-app-permission.type.d.cts

@@ -57,7 +57,8 @@ export declare enum EnergyAppPermissionTypeEnum {
     EpexSpotPrices = "EpexSpotPrices",
     FirmwareRegistry = "FirmwareRegistry",
     GridFeeRegister = "GridFeeRegister",
-    GridFeeUse = "GridFeeUse"
+    GridFeeUse = "GridFeeUse",
+    CommandLog = "CommandLog"
 }
 /**
  * String union of every permission name, derived from

package/dist/cjs/energy-app.cjs

@@ -465,6 +465,22 @@ class EnergyApp {
     useGridFee() {
         return this.energyAppSdk.useGridFee();
     }
+    /**
+     * Gets the Command Log API for recording the writes this app issued to an
+     * appliance — which Modbus register, which OCPP configuration key or
+     * message, with what it was before and whether the device took it.
+     *
+     * An appliance's state shows what it is doing; the command log shows what
+     * was done to it and why, which is what an incident investigation actually
+     * needs. Entries are append-only, and reads span every app so that two
+     * packages fighting over the same register are visible.
+     * @returns The Command Log API instance
+     * @throws {EnergyAppPermissionNotGrantedError} If the `CommandLog`
+     *         permission is not granted.
+     */
+    useCommandLog() {
+        return this.energyAppSdk.useCommandLog();
+    }
     /**
      * Gets the current SDK version.
      * @returns The semantic version string of the SDK

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

@@ -46,6 +46,7 @@ import { EnergyAppSavings } from "./packages/energy-app-savings.cjs";
 import { EnergyAppDeviceTest } from "./packages/energy-app-device-test.cjs";
 import { EnergyAppEpexSpotPrice } from "./packages/energy-app-epex-spot-price.cjs";
 import { EnergyAppGridFee } from "./packages/energy-app-grid-fee.cjs";
+import { EnergyAppCommandLog } from "./packages/energy-app-command-log.cjs";
 import { UseFetchOptions } from "./types/enyo-fetch.cjs";
 /**
  * Concrete implementation of {@link EnyoEnergyAppSdk} that delegates every call
@@ -387,6 +388,20 @@ export declare class EnergyApp implements EnyoEnergyAppSdk {
      *         `GridFeeUse` permission required by the called method is not granted.
      */
     useGridFee(): EnergyAppGridFee;
+    /**
+     * Gets the Command Log API for recording the writes this app issued to an
+     * appliance — which Modbus register, which OCPP configuration key or
+     * message, with what it was before and whether the device took it.
+     *
+     * An appliance's state shows what it is doing; the command log shows what
+     * was done to it and why, which is what an incident investigation actually
+     * needs. Entries are append-only, and reads span every app so that two
+     * packages fighting over the same register are visible.
+     * @returns The Command Log API instance
+     * @throws {EnergyAppPermissionNotGrantedError} If the `CommandLog`
+     *         permission is not granted.
+     */
+    useCommandLog(): EnergyAppCommandLog;
     /**
      * Gets the current SDK version.
      * @returns The semantic version string of the SDK

package/dist/cjs/enyo-energy-app-sdk.d.cts

@@ -45,6 +45,7 @@ import { EnergyAppSavings } from "./packages/energy-app-savings.cjs";
 import { EnergyAppDeviceTest } from "./packages/energy-app-device-test.cjs";
 import { EnergyAppEpexSpotPrice } from "./packages/energy-app-epex-spot-price.cjs";
 import { EnergyAppGridFee } from "./packages/energy-app-grid-fee.cjs";
+import { EnergyAppCommandLog } from "./packages/energy-app-command-log.cjs";
 import { UseFetchOptions } from "./types/enyo-fetch.cjs";
 export declare enum EnergyAppStateEnum {
     Launching = "launching",
@@ -166,4 +167,6 @@ export interface EnyoEnergyAppSdk {
     useEpexSpotPrices: () => EnergyAppEpexSpotPrice;
     /** Get the Grid Fee API for publishing time-dependent network charges and resolving them to a 15-minute series */
     useGridFee: () => EnergyAppGridFee;
+    /** Get the Command Log API for recording which register, configuration key or message this app wrote to an appliance, and reading those commands back */
+    useCommandLog: () => EnergyAppCommandLog;
 }

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

@@ -67,6 +67,62 @@ exports.onboardingV2Block = {
      * @param items - One translated entry per bullet (de/en).
      */
     bullets: (id, items) => ({ id, type: enyo_onboarding_v2_js_1.EnyoOnboardingV2BlockType.Bullets, items }),
+    /**
+     * A select block — a dropdown whose answer is recorded, not branched on.
+     *
+     * Use this, not {@link block.choice}, when the answer is data rather than a
+     * route: a choice needs one outgoing transition per option, so forty models
+     * would mean forty transitions to the same step.
+     *
+     * @param id - Stable block id, unique within the guide.
+     * @param label - Translated field label (de/en).
+     * @param options - The selectable options; unique values, at least one.
+     * @param opts - Optional `defaultValue`, `help` and `required`.
+     *
+     * @example
+     * ```typescript
+     * block.select('model', t('Modell', 'Model'), [
+     *     {value: 'sb-3-0', label: t('Sunny Boy 3.0', 'Sunny Boy 3.0')},
+     *     {value: 'sb-5-0', label: t('Sunny Boy 5.0', 'Sunny Boy 5.0')},
+     * ], {required: true})
+     * ```
+     */
+    select: (id, label, options, opts) => ({
+        id,
+        type: enyo_onboarding_v2_js_1.EnyoOnboardingV2BlockType.Select,
+        label,
+        options,
+        ...(opts?.defaultValue !== undefined ? { defaultValue: opts.defaultValue } : {}),
+        ...(opts?.help ? { help: opts.help } : {}),
+        ...(opts?.required !== undefined ? { required: opts.required } : {}),
+    }),
+    /**
+     * A credentials block — label/value pairs the installer transcribes into the
+     * device or a vendor portal.
+     *
+     * Passive content: it routes nothing, so a step whose only non-content block
+     * is this one still leaves through its single `continue` handle.
+     *
+     * @param id - Stable block id, unique within the guide.
+     * @param credentials - The label/value pairs. At least one.
+     * @param options - Optional heading, note, and copy-button toggle.
+     *
+     * @example
+     * ```typescript
+     * block.credentials('creds', [
+     *     {label: t('Benutzername', 'Username'), value: 'enyo'},
+     *     {label: t('Passwort', 'Password'), value: generated, secret: true},
+     * ], {title: t('Zugangsdaten', 'Credentials')})
+     * ```
+     */
+    credentials: (id, credentials, options) => ({
+        id,
+        type: enyo_onboarding_v2_js_1.EnyoOnboardingV2BlockType.Credentials,
+        credentials,
+        copyable: options?.copyable ?? true,
+        ...(options?.title ? { title: options.title } : {}),
+        ...(options?.description ? { description: options.description } : {}),
+    }),
     /**
      * An image block addressing an externally hosted image by URL.
      *
@@ -217,6 +273,40 @@ exports.onboardingV2Block = {
         label,
         outcomes,
     }),
+    /**
+     * A device-select block: the installer picks the device being onboarded from
+     * everything the run has found.
+     *
+     * Use it whenever a scan can turn up more than one candidate. A
+     * {@link block.networkScan} branches on found/not-found but binds nothing,
+     * so without this the run does not know *which* device it is working on —
+     * and {@link EnyoOnboardingV2DeviceSelection.Current} and
+     * {@link EnyoOnboardingV2DynamicKind.DeviceIp} have nothing to resolve
+     * against.
+     *
+     * The picker renders what discovery found, so the guide must have scanned:
+     * keep {@link EnyoOnboardingV2Guide.requiresNetworkScan} at its default, or
+     * place a {@link block.networkScan} ahead of this one.
+     *
+     * Outcome `value`s must be {@link EnyoOnboardingV2DeviceSelectOutcome}
+     * members; route `not-found` to troubleshooting rather than to a step that
+     * assumes a device exists.
+     *
+     * Register an {@link EnyoOnboardingV2DeviceSelectHandler} to turn the pick
+     * into appliances — the host awaits it and binds the run to the ids it
+     * returns. Without one the pick binds an address and nothing more.
+     *
+     * @param id - Stable block id, unique within the guide.
+     * @param label - Translated trigger button text (de/en).
+     * @param outcomes - The `selected` / `not-found` results; each is a routing handle.
+     */
+    deviceSelect: (id, label, outcomes) => ({
+        id,
+        type: enyo_onboarding_v2_js_1.EnyoOnboardingV2BlockType.Action,
+        action: enyo_onboarding_v2_js_1.EnyoOnboardingV2ActionKind.DeviceSelect,
+        label,
+        outcomes,
+    }),
     /**
      * An auth block: the installer signs into the energy app's own account
      * system (OAuth / vendor portal).

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

@@ -10,7 +10,7 @@
  * before publishing.
  */
 import type { EnyoOnboardingTranslatedContent } from '../../types/enyo-onboarding.cjs';
-import { EnyoOnboardingV2ActionKind, EnyoOnboardingV2ChoiceLayout, EnyoOnboardingV2DeviceSelection, EnyoOnboardingV2PauseReason } from '../../types/enyo-onboarding-v2.cjs';
+import { EnyoOnboardingV2ActionKind, EnyoOnboardingV2Credential, EnyoOnboardingV2SelectOption, EnyoOnboardingV2ChoiceLayout, EnyoOnboardingV2DeviceSelection, EnyoOnboardingV2PauseReason } from '../../types/enyo-onboarding-v2.cjs';
 import type { EnyoOnboardingV2ActionOutcome, EnyoOnboardingV2AuthOutcome, EnyoOnboardingV2SetupField, EnyoOnboardingV2SetupOutcome, EnyoOnboardingV2SetupSkipHandle, 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
@@ -45,6 +45,55 @@ export declare const onboardingV2Block: {
      * @param items - One translated entry per bullet (de/en).
      */
     bullets: (id: string, items: EnyoOnboardingTranslatedContent[][]) => EnyoOnboardingV2Block;
+    /**
+     * A select block — a dropdown whose answer is recorded, not branched on.
+     *
+     * Use this, not {@link block.choice}, when the answer is data rather than a
+     * route: a choice needs one outgoing transition per option, so forty models
+     * would mean forty transitions to the same step.
+     *
+     * @param id - Stable block id, unique within the guide.
+     * @param label - Translated field label (de/en).
+     * @param options - The selectable options; unique values, at least one.
+     * @param opts - Optional `defaultValue`, `help` and `required`.
+     *
+     * @example
+     * ```typescript
+     * block.select('model', t('Modell', 'Model'), [
+     *     {value: 'sb-3-0', label: t('Sunny Boy 3.0', 'Sunny Boy 3.0')},
+     *     {value: 'sb-5-0', label: t('Sunny Boy 5.0', 'Sunny Boy 5.0')},
+     * ], {required: true})
+     * ```
+     */
+    select: (id: string, label: EnyoOnboardingTranslatedContent[], options: EnyoOnboardingV2SelectOption[], opts?: {
+        defaultValue?: string;
+        help?: EnyoOnboardingTranslatedContent[];
+        required?: boolean;
+    }) => EnyoOnboardingV2Block;
+    /**
+     * A credentials block — label/value pairs the installer transcribes into the
+     * device or a vendor portal.
+     *
+     * Passive content: it routes nothing, so a step whose only non-content block
+     * is this one still leaves through its single `continue` handle.
+     *
+     * @param id - Stable block id, unique within the guide.
+     * @param credentials - The label/value pairs. At least one.
+     * @param options - Optional heading, note, and copy-button toggle.
+     *
+     * @example
+     * ```typescript
+     * block.credentials('creds', [
+     *     {label: t('Benutzername', 'Username'), value: 'enyo'},
+     *     {label: t('Passwort', 'Password'), value: generated, secret: true},
+     * ], {title: t('Zugangsdaten', 'Credentials')})
+     * ```
+     */
+    credentials: (id: string, credentials: EnyoOnboardingV2Credential[], options?: {
+        title?: EnyoOnboardingTranslatedContent[];
+        description?: EnyoOnboardingTranslatedContent[];
+        copyable?: boolean;
+    }) => EnyoOnboardingV2Block;
     /**
      * An image block addressing an externally hosted image by URL.
      *
@@ -169,6 +218,34 @@ export declare const onboardingV2Block: {
      * @param outcomes - The `paired` / `not-found` / `failure` results; each is a routing handle.
      */
     eebusPair: (id: string, label: EnyoOnboardingTranslatedContent[], outcomes: EnyoOnboardingV2ActionOutcome[]) => EnyoOnboardingV2Block;
+    /**
+     * A device-select block: the installer picks the device being onboarded from
+     * everything the run has found.
+     *
+     * Use it whenever a scan can turn up more than one candidate. A
+     * {@link block.networkScan} branches on found/not-found but binds nothing,
+     * so without this the run does not know *which* device it is working on —
+     * and {@link EnyoOnboardingV2DeviceSelection.Current} and
+     * {@link EnyoOnboardingV2DynamicKind.DeviceIp} have nothing to resolve
+     * against.
+     *
+     * The picker renders what discovery found, so the guide must have scanned:
+     * keep {@link EnyoOnboardingV2Guide.requiresNetworkScan} at its default, or
+     * place a {@link block.networkScan} ahead of this one.
+     *
+     * Outcome `value`s must be {@link EnyoOnboardingV2DeviceSelectOutcome}
+     * members; route `not-found` to troubleshooting rather than to a step that
+     * assumes a device exists.
+     *
+     * Register an {@link EnyoOnboardingV2DeviceSelectHandler} to turn the pick
+     * into appliances — the host awaits it and binds the run to the ids it
+     * returns. Without one the pick binds an address and nothing more.
+     *
+     * @param id - Stable block id, unique within the guide.
+     * @param label - Translated trigger button text (de/en).
+     * @param outcomes - The `selected` / `not-found` results; each is a routing handle.
+     */
+    deviceSelect: (id: string, label: EnyoOnboardingTranslatedContent[], outcomes: EnyoOnboardingV2ActionOutcome[]) => EnyoOnboardingV2Block;
     /**
      * An auth block: the installer signs into the energy app's own account
      * system (OAuth / vendor portal).

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

@@ -83,6 +83,8 @@ function validateOnboardingGuideV2(guide, context) {
             warnings.push(`${at}: no content blocks.`);
         validateActionBlocks(step, at, errors, warnings);
         validateLinkBlocks(step, at, errors, warnings);
+        validateCredentialsBlocks(step, at, errors, warnings);
+        validateSelectBlocks(step, at, errors, warnings);
         validateImageBlocks(step, at, errors, warnings, context);
         validateInputBlocks(step, at, errors, warnings);
         validateAuthBlocks(step, at, errors, warnings);
@@ -191,6 +193,9 @@ function validateActionBlocks(step, at, errors, warnings) {
             if (block.action === enyo_onboarding_v2_js_1.EnyoOnboardingV2ActionKind.OcppConnect) {
                 validateOcppConnectOutcomes(block, at, errors);
             }
+            if (block.action === enyo_onboarding_v2_js_1.EnyoOnboardingV2ActionKind.DeviceSelect) {
+                validateDeviceSelectOutcomes(block, at, errors, warnings);
+            }
             if (block.action === enyo_onboarding_v2_js_1.EnyoOnboardingV2ActionKind.EebusPair) {
                 validateEebusPairOutcomes(block, at, errors, warnings);
             }
@@ -247,6 +252,76 @@ function validateLinkBlocks(step, at, errors, warnings) {
         }
     }
 }
+/**
+ * Validates the select blocks of a step.
+ *
+ * A select records an answer rather than routing on one, so the failures that
+ * matter are the ones that make the recorded value ambiguous or unreachable:
+ * duplicate option values (the app cannot tell which was picked) and a
+ * `defaultValue` naming no option (nothing is pre-selected, silently).
+ */
+function validateSelectBlocks(step, at, errors, warnings) {
+    for (const block of step.blocks ?? []) {
+        if (block.type !== enyo_onboarding_v2_js_1.EnyoOnboardingV2BlockType.Select)
+            continue;
+        if (!block.label?.length) {
+            warnings.push(`${at}: select block "${block.id}" has no label.`);
+        }
+        if (!block.options?.length) {
+            errors.push(`${at}: select block "${block.id}" has no options.`);
+            continue;
+        }
+        if (block.options.length === 1) {
+            warnings.push(`${at}: select block "${block.id}" offers a single option — ` +
+                `there is nothing for the installer to choose.`);
+        }
+        const seen = new Set();
+        block.options.forEach((option, index) => {
+            if (!option.value?.trim()) {
+                errors.push(`${at}: select block "${block.id}" option ${index} has no value.`);
+                return;
+            }
+            if (seen.has(option.value)) {
+                errors.push(`${at}: select block "${block.id}" uses the option value ` +
+                    `"${option.value}" more than once.`);
+            }
+            seen.add(option.value);
+            if (!option.label?.length) {
+                warnings.push(`${at}: select block "${block.id}" option "${option.value}" has no label.`);
+            }
+        });
+        if (block.defaultValue !== undefined && !seen.has(block.defaultValue)) {
+            errors.push(`${at}: select block "${block.id}" defaultValue "${block.defaultValue}" ` +
+                `matches no option.`);
+        }
+    }
+}
+/**
+ * Validates the credentials blocks of a step.
+ *
+ * A pair with no value is the failure that matters: it renders as an empty row,
+ * and the installer has nothing to type into the device. An untranslated label
+ * only degrades the display, so it is a warning.
+ */
+function validateCredentialsBlocks(step, at, errors, warnings) {
+    for (const block of step.blocks ?? []) {
+        if (block.type !== enyo_onboarding_v2_js_1.EnyoOnboardingV2BlockType.Credentials)
+            continue;
+        if (!block.credentials?.length) {
+            errors.push(`${at}: credentials block "${block.id}" has no credentials.`);
+            continue;
+        }
+        block.credentials.forEach((credential, index) => {
+            if (!credential.value?.trim()) {
+                errors.push(`${at}: credentials block "${block.id}" entry ${index} has no value — ` +
+                    `it would render as an empty row.`);
+            }
+            if (!credential.label?.length) {
+                warnings.push(`${at}: credentials block "${block.id}" entry ${index} has no label.`);
+            }
+        });
+    }
+}
 /** An image-block `file` reference — the slug shape a package file is named with. */
 const FILE_NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 /**
@@ -366,6 +441,10 @@ function validateInputBlocks(step, at, errors, warnings) {
         if (!block.submitLabel?.length) {
             errors.push(`${at}: input block "${block.id}" has no submitLabel.`);
         }
+        if (block.validated && block.valueType === enyo_onboarding_v2_js_1.EnyoOnboardingV2InputValueType.IpAddress) {
+            errors.push(`${at}: input block "${block.id}" sets validated on an ip-address input — ` +
+                `the device test already produces the app's own verdict.`);
+        }
         const outcomes = block.outcomes ?? [];
         if (outcomes.length < 2) {
             errors.push(`${at}: input block "${block.id}" needs at least 2 outcomes.`);
@@ -432,6 +511,46 @@ function validateOcppConnectOutcomes(block, at, errors) {
         }
     }
 }
+/** Every {@link EnyoOnboardingV2DeviceSelectOutcome} value. */
+const DEVICE_SELECT_OUTCOMES = new Set(Object.values(enyo_onboarding_v2_js_1.EnyoOnboardingV2DeviceSelectOutcome));
+/**
+ * Validates the outcomes of an {@link EnyoOnboardingV2ActionKind.DeviceSelect}
+ * block.
+ *
+ * The block reports one of two things — the installer picked a device, or the
+ * run came away without one — so its outcome `value`s are closed over
+ * {@link EnyoOnboardingV2DeviceSelectOutcome}. Anything else is an outcome that
+ * can never fire.
+ *
+ * A missing `selected` branch strands every successful pick, and a missing
+ * `not-found` branch strands the installer whose device is not in the list —
+ * both warnings rather than errors, so a guide can be staged step by step.
+ *
+ * @param block - The device-select 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 validateDeviceSelectOutcomes(block, at, errors, warnings) {
+    const values = new Set();
+    for (const outcome of block.outcomes ?? []) {
+        if (!DEVICE_SELECT_OUTCOMES.has(outcome.value)) {
+            errors.push(`${at}: device-select block "${block.id}" has outcome value "${outcome.value}", which is not an EnyoOnboardingV2DeviceSelectOutcome member.`);
+        }
+        else if (values.has(outcome.value)) {
+            errors.push(`${at}: device-select block "${block.id}" wires outcome value "${outcome.value}" more than once.`);
+        }
+        values.add(outcome.value);
+    }
+    if (!values.has(enyo_onboarding_v2_js_1.EnyoOnboardingV2DeviceSelectOutcome.Selected)) {
+        warnings.push(`${at}: device-select block "${block.id}" has no "${enyo_onboarding_v2_js_1.EnyoOnboardingV2DeviceSelectOutcome.Selected}" outcome — ` +
+            'a picked device would have nowhere to go.');
+    }
+    if (!values.has(enyo_onboarding_v2_js_1.EnyoOnboardingV2DeviceSelectOutcome.NotFound)) {
+        warnings.push(`${at}: device-select block "${block.id}" has no "${enyo_onboarding_v2_js_1.EnyoOnboardingV2DeviceSelectOutcome.NotFound}" outcome — ` +
+            'an installer whose device is not in the list would be stranded.');
+    }
+}
 /** Every {@link EnyoOnboardingV2EebusPairOutcome} value. */
 const EEBUS_PAIR_OUTCOMES = new Set(Object.values(enyo_onboarding_v2_js_1.EnyoOnboardingV2EebusPairOutcome));
 /**

package/dist/cjs/index.cjs

@@ -103,6 +103,8 @@ __exportStar(require("./packages/energy-app-onboarding-v2.cjs"), exports);
 __exportStar(require("./implementations/onboarding-v2/onboarding-v2-provider-validators.cjs"), exports);
 __exportStar(require("./types/enyo-onboarding-v2-dynamic.cjs"), exports);
 __exportStar(require("./types/enyo-onboarding-v2-additional-setup.cjs"), exports);
+__exportStar(require("./types/enyo-onboarding-v2-validation.cjs"), exports);
+__exportStar(require("./types/enyo-onboarding-v2-device-select.cjs"), exports);
 __exportStar(require("./implementations/onboarding-v2/onboarding-v2-dynamic-validators.cjs"), exports);
 __exportStar(require("./implementations/files/define-public-file.cjs"), exports);
 __exportStar(require("./implementations/files/public-file-validators.cjs"), exports);
@@ -147,6 +149,8 @@ __exportStar(require("./packages/energy-app-device-test.cjs"), exports);
 __exportStar(require("./implementations/device-test/device-test-validators.cjs"), exports);
 __exportStar(require("./types/enyo-savings.cjs"), exports);
 __exportStar(require("./packages/energy-app-savings.cjs"), exports);
+__exportStar(require("./types/enyo-command-log.cjs"), exports);
+__exportStar(require("./packages/energy-app-command-log.cjs"), exports);
 __exportStar(require("./types/enyo-epex-spot-price.cjs"), exports);
 __exportStar(require("./packages/energy-app-epex-spot-price.cjs"), exports);
 __exportStar(require("./types/enyo-automation.cjs"), exports);

package/dist/cjs/index.d.cts

@@ -87,6 +87,8 @@ export * from './packages/energy-app-onboarding-v2.cjs';
 export * from './implementations/onboarding-v2/onboarding-v2-provider-validators.cjs';
 export * from './types/enyo-onboarding-v2-dynamic.cjs';
 export * from './types/enyo-onboarding-v2-additional-setup.cjs';
+export * from './types/enyo-onboarding-v2-validation.cjs';
+export * from './types/enyo-onboarding-v2-device-select.cjs';
 export * from './implementations/onboarding-v2/onboarding-v2-dynamic-validators.cjs';
 export * from './implementations/files/define-public-file.cjs';
 export * from './implementations/files/public-file-validators.cjs';
@@ -131,6 +133,8 @@ export * from './packages/energy-app-device-test.cjs';
 export * from './implementations/device-test/device-test-validators.cjs';
 export * from './types/enyo-savings.cjs';
 export * from './packages/energy-app-savings.cjs';
+export * from './types/enyo-command-log.cjs';
+export * from './packages/energy-app-command-log.cjs';
 export * from './types/enyo-epex-spot-price.cjs';
 export * from './packages/energy-app-epex-spot-price.cjs';
 export * from './types/enyo-automation.cjs';

package/dist/cjs/packages/energy-app-command-log.cjs

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/packages/energy-app-command-log.d.cts

@@ -0,0 +1,108 @@
+import { EnyoCommandLogEntry, EnyoCommandLogEntryInput, EnyoCommandLogFilter } from "../types/enyo-command-log.cjs";
+/**
+ * Interface for recording and reading back the commands an energy app issued to
+ * an appliance.
+ *
+ * This is the answer to "why did the device do that?". An appliance's own state
+ * shows what it is doing now; it does not show that this app wrote holding
+ * register 40023 four seconds ago because the energy manager cut the available
+ * power, nor that the write was rejected. Without a record of the writes, that
+ * has to be reconstructed from log files that may already have rotated away.
+ *
+ * The unit is a **write, not a read**. Polling a register every two seconds does
+ * not belong here — an entry is a command that changed, or tried to change,
+ * something on the device. Recording reads would bury the writes.
+ *
+ * Entries are append-only: there is no update and no delete. A log an app can
+ * rewrite cannot be trusted to explain an incident, and retention is the host's
+ * to enforce.
+ *
+ * Access to this API requires the `CommandLog` permission
+ * ({@link EnergyAppPermissionType}); {@link EnergyApp.useCommandLog} throws when
+ * it has not been granted.
+ *
+ * @example
+ * ```typescript
+ * const commandLog = energyApp.useCommandLog();
+ *
+ * const before = await modbus.readHoldingRegisters(40023, 1);
+ * try {
+ *     await modbus.writeSingleRegister(40023, limitW);
+ *     await commandLog.logCommand({
+ *         applianceId,
+ *         protocol: EnyoCommandProtocolEnum.Modbus,
+ *         operation: 'write-single-register',
+ *         target: '40023',
+ *         previousValue: String(before.readUInt16BE(0)),
+ *         newValue: String(limitW),
+ *         outcome: EnyoCommandOutcomeEnum.Success,
+ *         reason: 'energy manager reduced available power',
+ *     });
+ * } catch (error) {
+ *     await commandLog.logCommand({
+ *         applianceId,
+ *         protocol: EnyoCommandProtocolEnum.Modbus,
+ *         operation: 'write-single-register',
+ *         target: '40023',
+ *         newValue: String(limitW),
+ *         outcome: EnyoCommandOutcomeEnum.Failed,
+ *         errorMessage: String(error),
+ *         reason: 'energy manager reduced available power',
+ *     });
+ * }
+ * ```
+ */
+export interface EnergyAppCommandLog {
+    /**
+     * Appends one command to the log.
+     *
+     * Log the attempt, not only the success: a command that timed out or was
+     * rejected is the entry someone will actually go looking for, and an app
+     * that only records its successes produces a log where nothing ever went
+     * wrong. Set {@link EnyoCommandLogEntry.outcome} accordingly and put the
+     * detail in `errorMessage`.
+     *
+     * Fill {@link EnyoCommandLogEntry.reason} whenever the app knows it. What was
+     * written can be reconstructed from the device; why it was written cannot.
+     *
+     * This call is for auditing and must never gate the command itself — log
+     * after the write has been attempted, and do not let a failure to log
+     * surface as a failure to control the appliance.
+     *
+     * Requires the `CommandLog` permission.
+     *
+     * @param entry - The command to record. `id`, `packageName` and (unless
+     *   supplied) `timestampIso` are assigned by the host.
+     * @returns Promise resolving to the stored entry, including its assigned id
+     * @throws {EnergyAppPermissionNotGrantedError} If the `CommandLog` permission
+     *         is not granted.
+     */
+    logCommand(entry: EnyoCommandLogEntryInput): Promise<EnyoCommandLogEntry>;
+    /**
+     * Reads recorded commands back, newest first.
+     *
+     * Returns entries from **every** app, not just this one, unless
+     * {@link EnyoCommandLogFilter.packageName} narrows it. That is deliberate:
+     * the failure this log exists to explain is often two apps writing the same
+     * register, which is invisible from either app's own entries.
+     *
+     * Requires the `CommandLog` permission.
+     *
+     * @param filter - Optional narrowing by appliance, protocol, outcome, time
+     *   range or package. Fields combine with AND.
+     * @returns Promise resolving to the matching entries, newest first
+     * @throws {EnergyAppPermissionNotGrantedError} If the `CommandLog` permission
+     *         is not granted.
+     *
+     * @example
+     * ```typescript
+     * // Everything we failed to write to this appliance today.
+     * const failures = await commandLog.getCommands({
+     *     applianceId,
+     *     outcome: EnyoCommandOutcomeEnum.Failed,
+     *     fromIso: startOfDay,
+     * });
+     * ```
+     */
+    getCommands(filter?: EnyoCommandLogFilter): Promise<EnyoCommandLogEntry[]>;
+}

package/dist/cjs/packages/energy-app-interval.d.cts

@@ -2,7 +2,7 @@
  * Supported interval durations for scheduled tasks.
  * Provides predefined time intervals from 1 second to 1 hour.
  */
-export type IntervalDuration = '1s' | '5s' | '10s' | '30s' | '1m' | '5m' | '1hr';
+export type IntervalDuration = '1s' | '2s' | '3s' | '5s' | '10s' | '30s' | '1m' | '5m' | '1hr';
 /**
  * Interface for managing scheduled intervals in enyo packages.
  * Provides functionality to create and manage recurring tasks.