@enyo-energy/energy-app-sdk 0.0.196 → 0.0.198

package/README.md

@@ -1127,6 +1127,65 @@ if (info) console.log(`Active manager: ${info.name} v${info.version}`);
 
 Requires the `EnergyManagerInfo` permission.
 
+##### General settings
+
+A closed, SDK-defined set of user-facing controls the active energy manager honours — the contract between the enyo cockpit and whichever manager is installed. Not to be confused with `useSettings()`, which is per-package, string-valued, and rendered on your own config screen.
+
+| Setting | Type |
+|---|---|
+| `BatteryControl` | boolean |
+| `BatteryChargingMode` | `paced` \| `immediate` |
+| `BatteryChargeFromGrid` | boolean |
+| `BatteryDischargeWhileChargingWh` | number \| `null` (Wh allowance; `null`/unset = disabled) |
+| `BlockBatteryDischargeWhileEvCharging` | boolean |
+| `HeatpumpControl` | boolean |
+| `HeatingRodControl` | boolean |
+| `HeatingRodMode` | `pv-surplus-only` \| `boost` |
+| `ChargerControl` | boolean |
+| `DefaultChargeMode` | `EnyoChargeModeEnum` |
+| `PriceLimitCtPerKwh` | number, **ct/kWh** (`7` = 7 ct/kWh) |
+| `CostOptimizedTarget` | wall-clock `"07:30"` + IANA timezone |
+
+An energy manager declares what it honours, next to `registerFeatures()`:
+
+```typescript
+em.registerSupportedSettings([
+    EnergyManagerSettingEnum.BatteryControl,
+    EnergyManagerSettingEnum.BatteryChargingMode,
+    EnergyManagerSettingEnum.ChargerControl,
+    EnergyManagerSettingEnum.DefaultChargeMode,
+]);
+
+// seed defaults without ever overriding the user
+await em.setEnergyManagerSettings(
+    { batteryControl: true, batteryChargingMode: EnergyManagerBatteryChargingModeEnum.Paced },
+    { onlyIfUnset: true },
+);
+```
+
+Anyone can read and react:
+
+```typescript
+const state = await em.getEnergyManagerSettings();   // null when no EM is configured
+if (state?.supported.includes(EnergyManagerSettingEnum.ChargerControl)
+    && state.values.chargerControl === false) {
+    skipChargerOptimization();
+}
+
+const id = em.listenForEnergyManagerSettingsChange(async ({ changed, state }) => {
+    if (changed.includes(EnergyManagerSettingEnum.DefaultChargeMode)) {
+        await applyChargeMode(state.values.defaultChargeMode);
+    }
+});
+em.unsubscribeEnergyManagerSettings(id);
+```
+
+Three things to get right:
+
+- **Absent is not `false`.** `undefined` means unsupported or never chosen; `false` means the user switched it off. Check `supported` first, then the value — collapsing the two steers hardware someone deliberately disabled.
+- **Six settings are gated by another** (`heatingRodMode` needs `heatingRodControl`, `priceLimitCtPerKwh` only applies under `price-limit`, …). The tree is exported as `ENERGY_MANAGER_SETTING_DEPENDENCIES` so the UI and the validator share one source of truth.
+- **`priceLimitCtPerKwh` is in cents**, unlike the SDK's machine-readable price fields (`electricityPricePerKwh`, EUR/kWh). Divide by 100 when comparing. `validateEnergyManagerSettingsState()` warns on values outside a plausible ct band, which catches the mix-up.
+
 #### `useElectricityTariff(): EnergyAppElectricityTariff`
 
 Register, retrieve, and manage electricity tariffs. One tariff can be marked as the system default.
@@ -1357,6 +1416,38 @@ await energyApp.useOnboardingV2().registerOnboardingGuidesHandler(async (request
 
 `null` and `[]` are **not** the same answer: `[]` says "I genuinely have no guides" and drops the host's cached ones, `null` says "I cannot answer right now" and leaves them alone. Use `null` for transient failures. The host stops waiting after `request.timeoutMs`, so build the guides in memory rather than fetching them.
 
+Guides declare **slots**, not values: `onboardingV2Block.dynamic(id, kind)` for an OCPP URL or a device IP. Register a second handler to fill them, and return `null` for anything you cannot resolve — a dynamic block is passive content, so an unresolved value never strands a run.
+
+```typescript
+await energyApp.useOnboardingV2().registerDynamicValueHandler(async (request) => {
+    if (request.kind !== EnyoOnboardingV2DynamicKind.OcppUrl) return null;
+
+    const { cloud, local } = await energyApp.useOcpp().getAvailableConnectionDetails();
+    const endpoint = cloud ?? local;
+    if (!endpoint) return null;   // unavailable beats wrong
+
+    return { requestId: request.requestId, kind: request.kind, value: endpoint.url };
+});
+```
+
+Guides can also carry `additional-setup` blocks — the one interactive block **your app** judges. It collects fields (including masked `Password`/`Token` fields, which v2 previously had no way to gather at all), calls a third handler, and branches on the outcome you return:
+
+```typescript
+await energyApp.useOnboardingV2().registerAdditionalSetupHandler(async (request) => {
+    if (request.setupKey !== 'vendor-cloud-token') return { requestId: request.requestId, outcome: 'failed' };
+    const token = request.values.find((v) => v.name === 'api-token')?.value;
+    if (!token || !(await vendorCloud.verify(token))) {
+        return { requestId: request.requestId, outcome: 'invalid' };
+    }
+    await energyApp.useSecretManager().saveSecret('vendor-cloud', { token });
+    return { requestId: request.requestId, outcome: 'connected' };
+});
+```
+
+Every such block must declare a `failed` outcome — it absorbs a rejection, a timeout, a missing handler, and an outcome value matching no branch (guide and handler are linked only by strings). Secrets are never logged, never prefilled, and not kept in run state. See [ONBOARDING.md](./ONBOARDING.md#app-defined-setups-additional-setup).
+
+Your answer wins over the host's own resolution, so a wrong value is worse than none — the installer pastes it into a charger and it fails minutes later as an `ocpp-connect` timeout. `validateOnboardingV2DynamicResult()` catches the copy-target mistakes (whitespace, a non-absolute URL, a plaintext scheme).
+
 Each guide must carry the `vendorId`, `modelIds` and `startVariant` it applies to — that is how the host selects one for a run, and there is no publish step left to bind them. See [ONBOARDING.md](./ONBOARDING.md#serving-guides-the-host-pulls-the-app-never-publishes) for the full v2 model.
 
 Not permission-gated.

package/dist/cjs/implementations/energy-manager-settings/energy-manager-settings-validators.cjs

@@ -0,0 +1,273 @@
+"use strict";
+/**
+ * Client-side validation for {@link EnergyManagerSettingsState} — the general
+ * settings an energy manager declares and the values stored against them.
+ *
+ * Two classes of problem live here, and only the second is obvious:
+ *
+ * 1. **Malformed values.** A `HH:mm` that is not a time, a timezone that is not
+ *    an IANA zone, a price that is not a finite number. These fail at planning
+ *    time, in the dark, on the night the charge was supposed to happen.
+ * 2. **Values that can never take effect.** A heating-rod mode stored while rod
+ *    control is off, a price limit while the default charge mode is
+ *    cost-optimized. Nothing rejects these — they simply do nothing, which reads
+ *    to a user as "the app ignored me".
+ *
+ * The second class is why {@link ENERGY_MANAGER_SETTING_DEPENDENCIES} exists as
+ * data: the gate tree is checked here rather than restated by every surface.
+ *
+ * `errors` mean the state is malformed; `warnings` are advisory. Use
+ * {@link validateEnergyManagerSettingsState} for the non-throwing result, or
+ * {@link assertValidEnergyManagerSettingsState} to throw.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EnergyManagerSettingsValidationError = void 0;
+exports.validateEnergyManagerSettingsState = validateEnergyManagerSettingsState;
+exports.assertValidEnergyManagerSettingsState = assertValidEnergyManagerSettingsState;
+const enyo_energy_manager_settings_js_1 = require("../../types/enyo-energy-manager-settings.cjs");
+const enyo_data_bus_value_js_1 = require("../../types/enyo-data-bus-value.cjs");
+/**
+ * Thrown by {@link assertValidEnergyManagerSettingsState} when a state fails
+ * validation. The message lists every blocking error so callers can surface them
+ * directly.
+ */
+class EnergyManagerSettingsValidationError extends Error {
+    /** The individual blocking errors that caused the failure. */
+    errors;
+    /**
+     * @param errors - The blocking validation errors.
+     */
+    constructor(errors) {
+        super(`Invalid energy manager settings:\n- ${errors.join('\n- ')}`);
+        this.name = 'EnergyManagerSettingsValidationError';
+        this.errors = errors;
+    }
+}
+exports.EnergyManagerSettingsValidationError = EnergyManagerSettingsValidationError;
+/** Every {@link EnergyManagerSettingEnum} value. */
+const SETTINGS = new Set(Object.values(enyo_energy_manager_settings_js_1.EnergyManagerSettingEnum));
+/** 24-hour `HH:mm`, the format {@link EnergyManagerSettingValues.costOptimizedTargetTime} uses. */
+const TIME_RE = /^([01]\d|2[0-3]):[0-5]\d$/;
+/**
+ * Plausible band for a price limit in ct/kWh.
+ *
+ * Wide on purpose, and negative at the bottom: wholesale prices go negative, and
+ * "charge only when I am paid to" is a real preference. The band exists to catch
+ * a EUR/kWh value entered into a ct/kWh field (`0.07` where `7` was meant) and
+ * the reverse (`700`), not to express an opinion about tariffs.
+ */
+const PRICE_LIMIT_MIN_CT = -100;
+const PRICE_LIMIT_MAX_CT = 200;
+/**
+ * Below this, a {@link EnergyManagerSettingValues.batteryDischargeWhileChargingWh}
+ * budget is almost certainly kWh entered into a Wh field.
+ *
+ * `10` would be ten watt-hours — a rounding error against any house battery, and
+ * indistinguishable from "no discharge at all" in practice, where `10` kWh was
+ * plainly meant. `0` is exempt: it is a legitimate, if roundabout, way to say
+ * disabled.
+ */
+const DISCHARGE_BUDGET_MIN_PLAUSIBLE_WH = 100;
+/** Value enums checked per field, for the enum-valued settings. */
+const BATTERY_CHARGING_MODES = new Set(Object.values(enyo_energy_manager_settings_js_1.EnergyManagerBatteryChargingModeEnum));
+const HEATING_ROD_MODES = new Set(Object.values(enyo_energy_manager_settings_js_1.EnergyManagerHeatingRodModeEnum));
+const CHARGE_MODES = new Set(Object.values(enyo_data_bus_value_js_1.EnyoChargeModeEnum));
+/**
+ * True when `timezone` is an IANA zone this runtime recognises.
+ *
+ * Uses `Intl` rather than a pattern: `"Europe/Berlin"` and `"Europe/Berln"` are
+ * indistinguishable by shape, and only the first one resolves a wall-clock time.
+ *
+ * @param timezone - The candidate IANA timezone identifier.
+ * @returns True when the runtime accepts it.
+ */
+function isValidTimezone(timezone) {
+    try {
+        new Intl.DateTimeFormat('en-US', { timeZone: timezone });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Reads the effective value a dependency is gated on.
+ *
+ * @param values - The stored values.
+ * @param setting - The gating setting.
+ * @returns The gate's current value, or `undefined` when it is unset.
+ */
+function gateValue(values, setting) {
+    const [key] = enyo_energy_manager_settings_js_1.ENERGY_MANAGER_SETTING_VALUE_KEYS[setting];
+    return key ? values[key] : undefined;
+}
+/**
+ * Validates an energy manager settings state: the declared support list, the
+ * value formats, and the gate tree between them.
+ *
+ * Checks applied:
+ *
+ * - `supported` holds only {@link EnergyManagerSettingEnum} members, without
+ *   duplicates (**error**).
+ * - Each stored value has the right type, and each enum-valued setting holds an
+ *   enum member (**error**).
+ * - `costOptimizedTargetTime` is `HH:mm`, and `costOptimizedTimezone` is an IANA
+ *   zone the runtime resolves (**error**).
+ * - `priceLimitCtPerKwh` is a finite number (**error**), and lies in a plausible
+ *   ct/kWh band (**warning** — catches a EUR/kWh value in a ct/kWh field).
+ * - `batteryDischargeWhileChargingWh` is a finite non-negative number or `null`
+ *   (**error**), and is not a negligible positive figure (**warning** — catches
+ *   a kWh value in a Wh field).
+ * - `blockBatteryDischargeWhileEvCharging` does not sit alongside a positive
+ *   `batteryDischargeWhileChargingWh` budget (**warning** — the block overrides
+ *   the budget, so it could never be spent).
+ * - A value stored for an unsupported setting (**warning** — the energy manager
+ *   will ignore it).
+ * - A value stored while its gate does not hold (**warning** — it can never take
+ *   effect; see {@link ENERGY_MANAGER_SETTING_DEPENDENCIES}).
+ * - A supported gate whose dependants are unsupported (**warning** — a
+ *   half-built control surface).
+ * - `costOptimizedTargetTime` set without a timezone (**warning** — the
+ *   wall-clock value is ambiguous across a DST boundary).
+ *
+ * @param state - The settings state to validate.
+ * @returns The {@link EnergyManagerSettingsValidationResult}.
+ *
+ * @example
+ * ```typescript
+ * const {ok, errors, warnings} = validateEnergyManagerSettingsState(state);
+ * warnings.forEach((w) => console.warn('energy manager settings:', w));
+ * if (!ok) console.error('energy manager settings are malformed', errors);
+ * ```
+ */
+function validateEnergyManagerSettingsState(state) {
+    const errors = [];
+    const warnings = [];
+    if (!state)
+        return { ok: false, errors: ['state is required.'], warnings };
+    if (!Array.isArray(state.supported)) {
+        return { ok: false, errors: ['`supported` must be an array.'], warnings };
+    }
+    const supported = new Set();
+    for (const setting of state.supported) {
+        if (!SETTINGS.has(setting)) {
+            errors.push(`\`supported\` contains "${setting}", which is not an EnergyManagerSettingEnum member.`);
+        }
+        else if (supported.has(setting)) {
+            errors.push(`\`supported\` lists "${setting}" more than once.`);
+        }
+        else {
+            supported.add(setting);
+        }
+    }
+    const values = state.values ?? {};
+    // ── value formats ──────────────────────────────────────────────────────
+    for (const key of ['batteryControl', 'batteryChargeFromGrid',
+        'blockBatteryDischargeWhileEvCharging', 'heatpumpControl',
+        'heatingRodControl', 'chargerControl']) {
+        if (values[key] !== undefined && typeof values[key] !== 'boolean') {
+            errors.push(`\`${key}\` must be a boolean when set.`);
+        }
+    }
+    if (values.batteryChargingMode !== undefined
+        && !BATTERY_CHARGING_MODES.has(values.batteryChargingMode)) {
+        errors.push(`\`batteryChargingMode\` "${values.batteryChargingMode}" is not an EnergyManagerBatteryChargingModeEnum member.`);
+    }
+    if (values.heatingRodMode !== undefined && !HEATING_ROD_MODES.has(values.heatingRodMode)) {
+        errors.push(`\`heatingRodMode\` "${values.heatingRodMode}" is not an EnergyManagerHeatingRodModeEnum member.`);
+    }
+    if (values.defaultChargeMode !== undefined && !CHARGE_MODES.has(values.defaultChargeMode)) {
+        errors.push(`\`defaultChargeMode\` "${values.defaultChargeMode}" is not an EnyoChargeModeEnum member.`);
+    }
+    if (values.priceLimitCtPerKwh !== undefined) {
+        if (typeof values.priceLimitCtPerKwh !== 'number'
+            || !Number.isFinite(values.priceLimitCtPerKwh)) {
+            errors.push('`priceLimitCtPerKwh` must be a finite number when set.');
+        }
+        else if (values.priceLimitCtPerKwh < PRICE_LIMIT_MIN_CT
+            || values.priceLimitCtPerKwh > PRICE_LIMIT_MAX_CT) {
+            warnings.push(`\`priceLimitCtPerKwh\` is ${values.priceLimitCtPerKwh}, outside the plausible ` +
+                `${PRICE_LIMIT_MIN_CT}…${PRICE_LIMIT_MAX_CT} ct/kWh band — this field is in ` +
+                'cents per kWh, not EUR per kWh.');
+        }
+    }
+    if (values.batteryDischargeWhileChargingWh !== undefined
+        && values.batteryDischargeWhileChargingWh !== null) {
+        const budget = values.batteryDischargeWhileChargingWh;
+        if (typeof budget !== 'number' || !Number.isFinite(budget)) {
+            errors.push('`batteryDischargeWhileChargingWh` must be a finite number or `null` when set.');
+        }
+        else if (budget < 0) {
+            errors.push(`\`batteryDischargeWhileChargingWh\` is ${budget}; a discharge budget cannot be ` +
+                'negative. Use `null` to disable the transfer entirely.');
+        }
+        else if (budget > 0 && budget < DISCHARGE_BUDGET_MIN_PLAUSIBLE_WH) {
+            warnings.push(`\`batteryDischargeWhileChargingWh\` is ${budget} Wh, which is negligible against ` +
+                'any house battery — this field is in watt-hours, not kilowatt-hours.');
+        }
+    }
+    if (values.blockBatteryDischargeWhileEvCharging === true
+        && typeof values.batteryDischargeWhileChargingWh === 'number'
+        && values.batteryDischargeWhileChargingWh > 0) {
+        warnings.push('`blockBatteryDischargeWhileEvCharging` is true, which closes the tap entirely, so the ' +
+            `\`batteryDischargeWhileChargingWh\` budget of ${values.batteryDischargeWhileChargingWh} Wh ` +
+            'can never be spent. Clear one of the two.');
+    }
+    if (values.costOptimizedTargetTime !== undefined) {
+        if (typeof values.costOptimizedTargetTime !== 'string'
+            || !TIME_RE.test(values.costOptimizedTargetTime)) {
+            errors.push(`\`costOptimizedTargetTime\` "${values.costOptimizedTargetTime}" is not a 24-hour HH:mm time.`);
+        }
+        if (values.costOptimizedTimezone === undefined) {
+            warnings.push('`costOptimizedTargetTime` is set without `costOptimizedTimezone` — the wall-clock ' +
+                'value cannot be resolved unambiguously across a DST boundary.');
+        }
+    }
+    if (values.costOptimizedTimezone !== undefined) {
+        if (typeof values.costOptimizedTimezone !== 'string'
+            || !isValidTimezone(values.costOptimizedTimezone)) {
+            errors.push(`\`costOptimizedTimezone\` "${values.costOptimizedTimezone}" is not an IANA timezone.`);
+        }
+    }
+    // ── stored but unsupported ─────────────────────────────────────────────
+    for (const setting of Object.values(enyo_energy_manager_settings_js_1.EnergyManagerSettingEnum)) {
+        const keys = enyo_energy_manager_settings_js_1.ENERGY_MANAGER_SETTING_VALUE_KEYS[setting];
+        const held = keys.filter((key) => values[key] !== undefined);
+        if (held.length && !supported.has(setting)) {
+            warnings.push(`"${setting}" holds a value (${held.join(', ')}) but is not in \`supported\` — ` +
+                'the energy manager will ignore it.');
+        }
+    }
+    // ── gate tree ──────────────────────────────────────────────────────────
+    for (const [setting, dependency] of Object.entries(enyo_energy_manager_settings_js_1.ENERGY_MANAGER_SETTING_DEPENDENCIES)) {
+        if (!dependency)
+            continue;
+        const key = setting;
+        const held = enyo_energy_manager_settings_js_1.ENERGY_MANAGER_SETTING_VALUE_KEYS[key].some((k) => values[k] !== undefined);
+        if (held && gateValue(values, dependency.requires) !== dependency.equals) {
+            warnings.push(`"${key}" holds a value, but it only takes effect while "${dependency.requires}" ` +
+                `is ${JSON.stringify(dependency.equals)} — it currently cannot.`);
+        }
+        if (supported.has(dependency.requires) && !supported.has(key)
+            && gateValue(values, dependency.requires) === dependency.equals) {
+            warnings.push(`"${dependency.requires}" is supported and active, but its dependent setting ` +
+                `"${key}" is not — the user is offered a gate with nothing behind it.`);
+        }
+    }
+    return { ok: errors.length === 0, errors, warnings };
+}
+/**
+ * Like {@link validateEnergyManagerSettingsState}, but throws
+ * {@link EnergyManagerSettingsValidationError} when there are blocking errors.
+ * Warnings never throw; the validated state is returned on success for chaining.
+ *
+ * @param state - The settings state to validate.
+ * @returns The same state when it has no blocking errors.
+ * @throws {EnergyManagerSettingsValidationError} When validation produces any error.
+ */
+function assertValidEnergyManagerSettingsState(state) {
+    const { ok, errors } = validateEnergyManagerSettingsState(state);
+    if (!ok)
+        throw new EnergyManagerSettingsValidationError(errors);
+    return state;
+}

package/dist/cjs/implementations/energy-manager-settings/energy-manager-settings-validators.d.cts

@@ -0,0 +1,94 @@
+/**
+ * Client-side validation for {@link EnergyManagerSettingsState} — the general
+ * settings an energy manager declares and the values stored against them.
+ *
+ * Two classes of problem live here, and only the second is obvious:
+ *
+ * 1. **Malformed values.** A `HH:mm` that is not a time, a timezone that is not
+ *    an IANA zone, a price that is not a finite number. These fail at planning
+ *    time, in the dark, on the night the charge was supposed to happen.
+ * 2. **Values that can never take effect.** A heating-rod mode stored while rod
+ *    control is off, a price limit while the default charge mode is
+ *    cost-optimized. Nothing rejects these — they simply do nothing, which reads
+ *    to a user as "the app ignored me".
+ *
+ * The second class is why {@link ENERGY_MANAGER_SETTING_DEPENDENCIES} exists as
+ * data: the gate tree is checked here rather than restated by every surface.
+ *
+ * `errors` mean the state is malformed; `warnings` are advisory. Use
+ * {@link validateEnergyManagerSettingsState} for the non-throwing result, or
+ * {@link assertValidEnergyManagerSettingsState} to throw.
+ */
+import type { EnergyManagerSettingsState } from '../../types/enyo-energy-manager-settings.cjs';
+/**
+ * Thrown by {@link assertValidEnergyManagerSettingsState} when a state fails
+ * validation. The message lists every blocking error so callers can surface them
+ * directly.
+ */
+export declare class EnergyManagerSettingsValidationError 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 an {@link EnergyManagerSettingsState}. */
+export interface EnergyManagerSettingsValidationResult {
+    /** True when there are no blocking `errors` (warnings are still allowed). */
+    ok: boolean;
+    /** Blocking problems — the state is malformed. */
+    errors: string[];
+    /** Advisory problems — allowed, but usually worth fixing. */
+    warnings: string[];
+}
+/**
+ * Validates an energy manager settings state: the declared support list, the
+ * value formats, and the gate tree between them.
+ *
+ * Checks applied:
+ *
+ * - `supported` holds only {@link EnergyManagerSettingEnum} members, without
+ *   duplicates (**error**).
+ * - Each stored value has the right type, and each enum-valued setting holds an
+ *   enum member (**error**).
+ * - `costOptimizedTargetTime` is `HH:mm`, and `costOptimizedTimezone` is an IANA
+ *   zone the runtime resolves (**error**).
+ * - `priceLimitCtPerKwh` is a finite number (**error**), and lies in a plausible
+ *   ct/kWh band (**warning** — catches a EUR/kWh value in a ct/kWh field).
+ * - `batteryDischargeWhileChargingWh` is a finite non-negative number or `null`
+ *   (**error**), and is not a negligible positive figure (**warning** — catches
+ *   a kWh value in a Wh field).
+ * - `blockBatteryDischargeWhileEvCharging` does not sit alongside a positive
+ *   `batteryDischargeWhileChargingWh` budget (**warning** — the block overrides
+ *   the budget, so it could never be spent).
+ * - A value stored for an unsupported setting (**warning** — the energy manager
+ *   will ignore it).
+ * - A value stored while its gate does not hold (**warning** — it can never take
+ *   effect; see {@link ENERGY_MANAGER_SETTING_DEPENDENCIES}).
+ * - A supported gate whose dependants are unsupported (**warning** — a
+ *   half-built control surface).
+ * - `costOptimizedTargetTime` set without a timezone (**warning** — the
+ *   wall-clock value is ambiguous across a DST boundary).
+ *
+ * @param state - The settings state to validate.
+ * @returns The {@link EnergyManagerSettingsValidationResult}.
+ *
+ * @example
+ * ```typescript
+ * const {ok, errors, warnings} = validateEnergyManagerSettingsState(state);
+ * warnings.forEach((w) => console.warn('energy manager settings:', w));
+ * if (!ok) console.error('energy manager settings are malformed', errors);
+ * ```
+ */
+export declare function validateEnergyManagerSettingsState(state: EnergyManagerSettingsState): EnergyManagerSettingsValidationResult;
+/**
+ * Like {@link validateEnergyManagerSettingsState}, but throws
+ * {@link EnergyManagerSettingsValidationError} when there are blocking errors.
+ * Warnings never throw; the validated state is returned on success for chaining.
+ *
+ * @param state - The settings state to validate.
+ * @returns The same state when it has no blocking errors.
+ * @throws {EnergyManagerSettingsValidationError} When validation produces any error.
+ */
+export declare function assertValidEnergyManagerSettingsState(state: EnergyManagerSettingsState): EnergyManagerSettingsState;

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

@@ -15,6 +15,7 @@ exports.onboardingV2Target = exports.onboardingV2Block = void 0;
 exports.defineOnboardingGuideV2 = defineOnboardingGuideV2;
 exports.onContinueV2 = onContinueV2;
 exports.onOptionV2 = onOptionV2;
+exports.onSkipV2 = onSkipV2;
 exports.onOutcomeV2 = onOutcomeV2;
 const enyo_onboarding_v2_js_1 = require("../../types/enyo-onboarding-v2.cjs");
 // ---------------------------------------------------------------------------
@@ -228,7 +229,9 @@ exports.onboardingV2Block = {
      * @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.
+     * @param opts - Optional translated `help` naming the account that is needed,
+     *   and `requiresWebAuthentication` to force the login into a web browser
+     *   when the provider rejects a custom-scheme redirect such as `enyoapp://`.
      */
     auth: (id, label, outcome, opts) => ({
         id,
@@ -236,6 +239,7 @@ exports.onboardingV2Block = {
         label,
         outcome,
         help: opts?.help,
+        requiresWebAuthentication: opts?.requiresWebAuthentication,
     }),
     /**
      * A link block: a fixed URL the installer opens or copies.
@@ -282,6 +286,57 @@ exports.onboardingV2Block = {
         placeholder: opts?.placeholder,
         help: opts?.help,
     }),
+    /**
+     * An additional-setup block: collect zero or more values, hand them to this
+     * energy app, and branch on the verdict the app returns.
+     *
+     * The only interactive block the app itself judges — use it for a vendor API
+     * key, a service token, an installer code. Keep
+     * {@link onboardingV2Block.auth} for the app's own OAuth session, whose
+     * server gating this cannot replace.
+     *
+     * `outcomes` must contain at least two entries, one of them valued `failed`
+     * ({@link ENYO_ONBOARDING_V2_SETUP_FAILED_OUTCOME}) — every breakdown lands
+     * there, including an outcome the handler returns that no branch declares.
+     * Route each outcome with {@link onOutcomeV2} and the optional skip with
+     * {@link onSkipV2}.
+     *
+     * `Password` and `Token` fields are treated as secrets: masked, never logged,
+     * never prefilled, and not persisted in run state.
+     *
+     * @param id - Stable block id, unique within the guide.
+     * @param setupKey - App-facing key the handler switches on; may repeat across guides.
+     * @param opts - `cta` and `description` (both translated, both required),
+     *   optional `fields`, the `outcomes`, and an optional `skip` handle.
+     *
+     * @example
+     * ```typescript
+     * onboardingV2Block.additionalSetup('cloud', 'vendor-cloud-token', {
+     *     cta: t('Cloud verbinden', 'Connect the cloud'),
+     *     description: t('Optional: bessere Prognosen.', 'Optional: better forecasts.'),
+     *     fields: [{
+     *         name: 'api-token',
+     *         type: EnyoOnboardingV2SetupFieldType.Token,
+     *         label: t('API-Token', 'API token'),
+     *     }],
+     *     outcomes: [
+     *         {id: 'ok',     value: 'connected', label: t('Verbunden', 'Connected')},
+     *         {id: 'failed', value: 'failed',    label: t('Fehlgeschlagen', 'Failed')},
+     *     ],
+     *     skip: {id: 'later', label: t('Später', 'Later')},
+     * })
+     * ```
+     */
+    additionalSetup: (id, setupKey, opts) => ({
+        id,
+        type: enyo_onboarding_v2_js_1.EnyoOnboardingV2BlockType.AdditionalSetup,
+        setupKey,
+        cta: opts.cta,
+        description: opts.description,
+        fields: opts.fields,
+        outcomes: opts.outcomes,
+        skip: opts.skip,
+    }),
 };
 // ---------------------------------------------------------------------------
 // Target factories
@@ -364,6 +419,26 @@ function onOptionV2(blockId, optionId, to, note) {
         note,
     };
 }
+/**
+ * Route the skip handle of an `AdditionalSetup` block.
+ *
+ * Only an optional setup has one. It leaves the block without a verdict, so
+ * nothing is collected and the handler is never called — which is what keeps a
+ * failing bonus feature from blocking an otherwise finished onboarding.
+ *
+ * @param blockId - The additional-setup block's id.
+ * @param skipId - The skip handle's id.
+ * @param to - Where skipping leads.
+ * @param note - Optional author note.
+ */
+function onSkipV2(blockId, skipId, to, note) {
+    return {
+        id: `skip:${blockId}:${skipId}`,
+        source: { kind: enyo_onboarding_v2_js_1.EnyoOnboardingV2TransitionSourceKind.Skip, blockId, skipId },
+        target: to,
+        note,
+    };
+}
 /**
  * Route an `Action` outcome.
  * @param blockId - The action block's id.