@enyo-energy/energy-app-sdk 0.0.186 → 0.0.188

package/README.md

@@ -724,6 +724,37 @@ const sessions = await charging.getActiveSessions();
 await charging.stopCharge(sessionId);
 ```
 
+React to charging sessions as they happen:
+
+```typescript
+const charge = energyApp.useCharge();
+
+const startedId = charge.listenForChargeStarted((session) => {
+    console.log(`charging started on ${session.applianceId}`);
+});
+
+const updatedId = charge.listenForChargeUpdated((session) => {
+    const latest = session.meterValues?.at(-1);
+    console.log(`now at ${latest?.valueWh} Wh`);
+});
+
+const stoppedId = charge.listenForChargeStopped((session) => {
+    if (session.status === EnyoChargeStatus.Completed) {
+        console.log(`delivered ${session.totalEnergyKwh} kWh`);
+    }
+});
+
+// later
+charge.removeListener(startedId);
+```
+
+The three events are disjoint: `listenForChargeUpdated` fires only for changes to a
+*running* session (meter values, charge mode, smart-charging schedule, additional
+transaction IDs), never for the start or the end, so a handler never sees the same
+event twice. Check `session.status` in the stopped listener — `Completed` and
+`Failed` both end a charge. Meter updates can arrive every few seconds, so keep
+the update callback cheap.
+
 #### `useChargingCard(): EnergyAppChargingCard`
 
 Handle charging authentication:

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

@@ -133,6 +133,51 @@ exports.onboardingV2Block = {
         outcomes,
         deviceSelection,
     }),
+    /**
+     * A link block: a fixed URL the installer opens or copies.
+     *
+     * Passive content — it produces no routing handle, so a step whose only
+     * non-content block is a link still routes through `continue`.
+     *
+     * @param id - Stable block id, unique within the guide.
+     * @param url - Absolute `http(s)` URL. Other schemes are rejected by the validator.
+     * @param label - Translated link text (de/en).
+     * @param opts - Optional translated `description` and `copyable` (defaults to `true`).
+     */
+    link: (id, url, label, opts) => ({
+        id,
+        type: enyo_onboarding_v2_js_1.EnyoOnboardingV2BlockType.Link,
+        url,
+        label,
+        description: opts?.description,
+        copyable: opts?.copyable ?? true,
+    }),
+    /**
+     * An input block: the installer types a value and the host checks it,
+     * producing the branch.
+     *
+     * For {@link EnyoOnboardingV2InputValueType.IpAddress} the host runs this
+     * app's registered device-test handler against the typed address; see
+     * {@link EnyoOnboardingV2InputBlock} for how a verdict picks an outcome.
+     * Route the outcomes with {@link onOutcomeV2} — there is no separate helper.
+     *
+     * @param id - Stable block id, unique within the guide.
+     * @param valueType - What is asked for (`Text` | `IpAddress` | `Number`).
+     * @param label - Translated field label (de/en).
+     * @param submitLabel - Translated submit button text (de/en).
+     * @param outcomes - The possible verdicts; each is a routing handle.
+     * @param opts - Optional translated `placeholder` and `help`.
+     */
+    input: (id, valueType, label, submitLabel, outcomes, opts) => ({
+        id,
+        type: enyo_onboarding_v2_js_1.EnyoOnboardingV2BlockType.Input,
+        valueType,
+        label,
+        submitLabel,
+        outcomes,
+        placeholder: opts?.placeholder,
+        help: opts?.help,
+    }),
 };
 // ---------------------------------------------------------------------------
 // Target factories

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

@@ -11,7 +11,7 @@
  */
 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, EnyoOnboardingV2PauseReason, EnyoOnboardingV2StartVariant, EnyoOnboardingV2Target, EnyoOnboardingV2Transition } 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';
 /**
  * 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,41 @@ export declare const onboardingV2Block: {
      * @param deviceSelection - Which devices to test (defaults to `Detected`).
      */
     deviceTest: (id: string, label: EnyoOnboardingTranslatedContent[], outcomes: EnyoOnboardingV2ActionOutcome[], deviceSelection?: EnyoOnboardingV2DeviceSelection) => EnyoOnboardingV2Block;
+    /**
+     * A link block: a fixed URL the installer opens or copies.
+     *
+     * Passive content — it produces no routing handle, so a step whose only
+     * non-content block is a link still routes through `continue`.
+     *
+     * @param id - Stable block id, unique within the guide.
+     * @param url - Absolute `http(s)` URL. Other schemes are rejected by the validator.
+     * @param label - Translated link text (de/en).
+     * @param opts - Optional translated `description` and `copyable` (defaults to `true`).
+     */
+    link: (id: string, url: string, label: EnyoOnboardingTranslatedContent[], opts?: {
+        description?: EnyoOnboardingTranslatedContent[];
+        copyable?: boolean;
+    }) => EnyoOnboardingV2Block;
+    /**
+     * An input block: the installer types a value and the host checks it,
+     * producing the branch.
+     *
+     * For {@link EnyoOnboardingV2InputValueType.IpAddress} the host runs this
+     * app's registered device-test handler against the typed address; see
+     * {@link EnyoOnboardingV2InputBlock} for how a verdict picks an outcome.
+     * Route the outcomes with {@link onOutcomeV2} — there is no separate helper.
+     *
+     * @param id - Stable block id, unique within the guide.
+     * @param valueType - What is asked for (`Text` | `IpAddress` | `Number`).
+     * @param label - Translated field label (de/en).
+     * @param submitLabel - Translated submit button text (de/en).
+     * @param outcomes - The possible verdicts; each is a routing handle.
+     * @param opts - Optional translated `placeholder` and `help`.
+     */
+    input: (id: string, valueType: EnyoOnboardingV2InputValueType, label: EnyoOnboardingTranslatedContent[], submitLabel: EnyoOnboardingTranslatedContent[], outcomes: EnyoOnboardingV2InputOutcome[], opts?: {
+        placeholder?: EnyoOnboardingTranslatedContent[];
+        help?: EnyoOnboardingTranslatedContent[];
+    }) => EnyoOnboardingV2Block;
 };
 /** Typed factories for each transition {@link EnyoOnboardingV2Target}. */
 export declare const onboardingV2Target: {

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

@@ -70,6 +70,8 @@ function validateOnboardingGuideV2(guide) {
         if (!step.blocks?.length)
             warnings.push(`${at}: no content blocks.`);
         validateActionBlocks(step, at, errors, warnings);
+        validateLinkBlocks(step, at, errors, warnings);
+        validateInputBlocks(step, at, errors, warnings);
     }
     if (!guide.startStepId || !stepIds.has(guide.startStepId)) {
         errors.push('`startStepId` must reference an existing step.');
@@ -175,10 +177,119 @@ function validateActionBlocks(step, at, errors, warnings) {
         }
     }
 }
+/** An absolute `http(s)` URL — the only scheme a link block may carry. */
+const HTTP_URL_RE = /^https?:\/\/\S+$/i;
+/**
+ * Validates the link blocks of a step.
+ *
+ * The scheme check is **security-relevant, not cosmetic**: the installer app
+ * renders a link block as a tap target, so this keeps `javascript:`, `data:` and
+ * `file:` payloads out of it. connect-core enforces the identical rule
+ * server-side and the app re-checks before opening — three gates, deliberately.
+ * Do not relax it to a generic "looks like a URL" test.
+ *
+ * @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 validateLinkBlocks(step, at, errors, warnings) {
+    for (const block of step.blocks ?? []) {
+        if (block.type !== enyo_onboarding_v2_js_1.EnyoOnboardingV2BlockType.Link)
+            continue;
+        if (!block.url?.trim()) {
+            errors.push(`${at}: link block "${block.id}" has no url.`);
+        }
+        else if (!HTTP_URL_RE.test(block.url.trim())) {
+            errors.push(`${at}: link block "${block.id}" url must be an absolute http(s) URL.`);
+        }
+        if (!block.label?.length) {
+            warnings.push(`${at}: link block "${block.id}" has no label — the raw URL is shown instead.`);
+        }
+    }
+}
+/** 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']);
+/**
+ * The {@link EnyoDeviceTestOutcomeEnum} verdicts that collapse onto a positive
+ * input outcome; every other verdict collapses onto a negative one.
+ */
+const POSITIVE_DEVICE_TEST_OUTCOMES = new Set([
+    enyo_device_test_js_1.EnyoDeviceTestOutcomeEnum.AppliancesCreated,
+    enyo_device_test_js_1.EnyoDeviceTestOutcomeEnum.AppliancesAlreadyExisted,
+    enyo_device_test_js_1.EnyoDeviceTestOutcomeEnum.DeviceConfirmedNoAppliance,
+]);
+/** True when `value` routes a successful check (exact verdict or binary key). */
+function isPositiveInputOutcomeValue(value) {
+    return POSITIVE_INPUT_OUTCOMES.has(value) || POSITIVE_DEVICE_TEST_OUTCOMES.has(value);
+}
+/**
+ * Validates the input blocks of a step.
+ *
+ * An {@link EnyoOnboardingV2InputValueType.IpAddress} block is checked more
+ * strictly than the other value types because it is the only one the host
+ * actually runs a check for: a one-sided outcome set there is a step the
+ * installer can enter and never leave, so both "no positive" and "no negative"
+ * are errors rather than warnings. Unlike a device test there is no `failed`
+ * verdict the host can fall back to.
+ *
+ * @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 validateInputBlocks(step, at, errors, warnings) {
+    for (const block of step.blocks ?? []) {
+        if (block.type !== enyo_onboarding_v2_js_1.EnyoOnboardingV2BlockType.Input)
+            continue;
+        if (!INPUT_VALUE_TYPES.has(block.valueType)) {
+            errors.push(`${at}: input block "${block.id}" has an unknown valueType "${block.valueType}".`);
+        }
+        if (!block.label?.length)
+            errors.push(`${at}: input block "${block.id}" has no label.`);
+        if (!block.submitLabel?.length) {
+            errors.push(`${at}: input block "${block.id}" has no submitLabel.`);
+        }
+        const outcomes = block.outcomes ?? [];
+        if (outcomes.length < 2) {
+            errors.push(`${at}: input block "${block.id}" needs at least 2 outcomes.`);
+        }
+        const ids = new Set();
+        const values = new Set();
+        for (const outcome of outcomes) {
+            if (ids.has(outcome.id)) {
+                errors.push(`${at}: input block "${block.id}" has a duplicate outcome id "${outcome.id}".`);
+            }
+            ids.add(outcome.id);
+            if (values.has(outcome.value)) {
+                errors.push(`${at}: input block "${block.id}" wires outcome value "${outcome.value}" more than once.`);
+            }
+            values.add(outcome.value);
+        }
+        if (block.valueType === enyo_onboarding_v2_js_1.EnyoOnboardingV2InputValueType.IpAddress) {
+            if (![...values].some(isPositiveInputOutcomeValue)) {
+                errors.push(`${at}: input block "${block.id}" has no outcome for a successful check — ` +
+                    `wire "reachable" (or an EnyoDeviceTestOutcomeEnum success member).`);
+            }
+            if (![...values].some((v) => !isPositiveInputOutcomeValue(v))) {
+                errors.push(`${at}: input block "${block.id}" has no outcome for a failed check — ` +
+                    `the installer would be stranded when the device does not answer.`);
+            }
+        }
+        else if (outcomes.length > 1) {
+            warnings.push(`${at}: input block "${block.id}" has valueType "${block.valueType}", which runs no check — ` +
+                `only the positive outcome can ever fire, so its other ${outcomes.length - 1} outcome(s) are dead branches.`);
+        }
+    }
+}
 /**
  * The set of routing-handle keys a step must wire exactly once: one per
- * choice option / action outcome, or the single `continue` handle when the step
- * has no interactive block.
+ * choice option / action outcome / input outcome, or the single `continue`
+ * handle when the step has no interactive block.
+ *
+ * A `Link` block contributes nothing — it is passive content.
  */
 function requiredHandleKeys(step) {
     const keys = new Set();
@@ -187,7 +298,8 @@ function requiredHandleKeys(step) {
             for (const o of b.options)
                 keys.add(`choice:${b.id}:${o.id}`);
         }
-        else if (b.type === enyo_onboarding_v2_js_1.EnyoOnboardingV2BlockType.Action) {
+        else if (b.type === enyo_onboarding_v2_js_1.EnyoOnboardingV2BlockType.Action ||
+            b.type === enyo_onboarding_v2_js_1.EnyoOnboardingV2BlockType.Input) {
             for (const o of b.outcomes)
                 keys.add(`outcome:${b.id}:${o.id}`);
         }

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

@@ -52,4 +52,84 @@ export interface EnergyAppCharge {
      * @returns Promise resolving to the configured default charge mode
      */
     getDefaultChargeMode: (applianceId: string) => Promise<EnyoDefaultChargeMode>;
+    /**
+     * Listen for charging sessions that have just started.
+     *
+     * Fires once per session, when the charge is first created and enters
+     * {@link EnyoChargeStatus.Charging} — not on subsequent meter updates (use
+     * {@link listenForChargeUpdated} for those). The delivered charge carries the
+     * data known at start: `applianceId`, `transactionId`, `startTime` and
+     * `meterStartValueWh`; the totals are only meaningful once the session ends.
+     *
+     * Listeners receive sessions of every appliance the package can see — filter
+     * on {@link EnyoCharge.applianceId} when only one charger is of interest.
+     *
+     * @param listener - Callback invoked with the started charging session
+     * @returns A unique listener ID that can be used to remove the listener
+     *
+     * @example
+     * ```typescript
+     * const charge = energyApp.useCharge();
+     * const listenerId = charge.listenForChargeStarted(async (session) => {
+     *     console.log(`charging started on ${session.applianceId}`);
+     * });
+     * ```
+     */
+    listenForChargeStarted: (listener: (charge: EnyoCharge) => void | Promise<void>) => string;
+    /**
+     * Listen for charging sessions that have ended.
+     *
+     * Fires once per session, when it leaves {@link EnyoChargeStatus.Charging}
+     * for a terminal status. Check {@link EnyoCharge.status} to tell a session
+     * that {@link EnyoChargeStatus.Completed completed} from one that
+     * {@link EnyoChargeStatus.Failed failed} — both end a charge, and a listener
+     * that assumes success will mis-report faulted sessions.
+     *
+     * The delivered charge is the final record, including `endTime`,
+     * `meterEndValueWh` and `totalEnergyKwh`.
+     *
+     * @param listener - Callback invoked with the ended charging session
+     * @returns A unique listener ID that can be used to remove the listener
+     *
+     * @example
+     * ```typescript
+     * charge.listenForChargeStopped(async (session) => {
+     *     if (session.status === EnyoChargeStatus.Completed) {
+     *         console.log(`delivered ${session.totalEnergyKwh} kWh`);
+     *     }
+     * });
+     * ```
+     */
+    listenForChargeStopped: (listener: (charge: EnyoCharge) => void | Promise<void>) => string;
+    /**
+     * Listen for changes to a running charging session.
+     *
+     * Fires whenever an active charge is modified — new meter values, a changed
+     * {@link EnyoCharge.chargeMode}, an updated smart-charging
+     * {@link EnyoCharge.schedule}, or an additional transaction ID. It does NOT
+     * fire for the start and the end of a session; those have their own
+     * listeners, so a handler registered here never sees the same event twice.
+     *
+     * Meter updates can arrive at the charger's reporting interval (often every
+     * few seconds), so keep the callback cheap and do not persist on every call.
+     *
+     * @param listener - Callback invoked with the updated charging session
+     * @returns A unique listener ID that can be used to remove the listener
+     *
+     * @example
+     * ```typescript
+     * charge.listenForChargeUpdated(async (session) => {
+     *     const latest = session.meterValues?.at(-1);
+     *     console.log(`now at ${latest?.valueWh} Wh`);
+     * });
+     * ```
+     */
+    listenForChargeUpdated: (listener: (charge: EnyoCharge) => void | Promise<void>) => string;
+    /**
+     * Removes a previously registered listener.
+     *
+     * @param listenerId - The ID returned by {@link listenForChargeStarted},
+     *   {@link listenForChargeStopped} or {@link listenForChargeUpdated}
+     */
+    removeListener: (listenerId: string) => void;
 }

package/dist/cjs/types/enyo-air-conditioning-appliance.cjs

@@ -10,6 +10,12 @@ var EnyoAirConditioningApplianceAvailableFeaturesEnum;
     EnyoAirConditioningApplianceAvailableFeaturesEnum["Cooling"] = "Cooling";
     /** If the air conditioning unit supports heating */
     EnyoAirConditioningApplianceAvailableFeaturesEnum["Heating"] = "Heating";
+    /** If the air conditioning unit reports electrical power values (e.g. consumption in watts) */
+    EnyoAirConditioningApplianceAvailableFeaturesEnum["Power"] = "Power";
+    /** If the air conditioning unit's electrical power draw can be steered (e.g. limited to a target in watts) */
+    EnyoAirConditioningApplianceAvailableFeaturesEnum["PowerControllable"] = "PowerControllable";
+    /** If the air conditioning unit's target room temperature can be set */
+    EnyoAirConditioningApplianceAvailableFeaturesEnum["TemperatureControllable"] = "TemperatureControllable";
 })(EnyoAirConditioningApplianceAvailableFeaturesEnum || (exports.EnyoAirConditioningApplianceAvailableFeaturesEnum = EnyoAirConditioningApplianceAvailableFeaturesEnum = {}));
 /**
  * Energy-optimization modes for an air conditioning appliance. These control how

package/dist/cjs/types/enyo-air-conditioning-appliance.d.cts

@@ -5,7 +5,13 @@ export declare enum EnyoAirConditioningApplianceAvailableFeaturesEnum {
     /** If the air conditioning unit supports cooling */
     Cooling = "Cooling",
     /** If the air conditioning unit supports heating */
-    Heating = "Heating"
+    Heating = "Heating",
+    /** If the air conditioning unit reports electrical power values (e.g. consumption in watts) */
+    Power = "Power",
+    /** If the air conditioning unit's electrical power draw can be steered (e.g. limited to a target in watts) */
+    PowerControllable = "PowerControllable",
+    /** If the air conditioning unit's target room temperature can be set */
+    TemperatureControllable = "TemperatureControllable"
 }
 /**
  * Energy-optimization modes for an air conditioning appliance. These control how

package/dist/cjs/types/enyo-heating-rod-appliance.cjs

@@ -11,6 +11,16 @@ var EnyoHeatingRodApplianceAvailableFeaturesEnum;
     EnyoHeatingRodApplianceAvailableFeaturesEnum["Power"] = "Power";
     /** If the heating rod supports available power announcements */
     EnyoHeatingRodApplianceAvailableFeaturesEnum["AvailablePowerAnnouncement"] = "AvailablePowerAnnouncement";
+    /**
+     * If the heating rod has a domestic hot water temperature sensor, i.e. it
+     * reports the measured DHW tank temperature rather than only its own
+     * operating state.
+     *
+     * Without this feature {@link EnyoHeatingRodApplianceMetadata.targetTemperatureC}
+     * is a setpoint the appliance cannot verify — consumers should not expect a
+     * measured temperature to compare it against.
+     */
+    EnyoHeatingRodApplianceAvailableFeaturesEnum["DomesticHotWaterSensor"] = "DomesticHotWaterSensor";
 })(EnyoHeatingRodApplianceAvailableFeaturesEnum || (exports.EnyoHeatingRodApplianceAvailableFeaturesEnum = EnyoHeatingRodApplianceAvailableFeaturesEnum = {}));
 /**
  * Operating modes for a heating rod appliance.

package/dist/cjs/types/enyo-heating-rod-appliance.d.cts

@@ -6,7 +6,17 @@ export declare enum EnyoHeatingRodApplianceAvailableFeaturesEnum {
     /** If the heating rod reports electrical power values (e.g. consumption in watts) */
     Power = "Power",
     /** If the heating rod supports available power announcements */
-    AvailablePowerAnnouncement = "AvailablePowerAnnouncement"
+    AvailablePowerAnnouncement = "AvailablePowerAnnouncement",
+    /**
+     * If the heating rod has a domestic hot water temperature sensor, i.e. it
+     * reports the measured DHW tank temperature rather than only its own
+     * operating state.
+     *
+     * Without this feature {@link EnyoHeatingRodApplianceMetadata.targetTemperatureC}
+     * is a setpoint the appliance cannot verify — consumers should not expect a
+     * measured temperature to compare it against.
+     */
+    DomesticHotWaterSensor = "DomesticHotWaterSensor"
 }
 /**
  * Operating modes for a heating rod appliance.

package/dist/cjs/types/enyo-onboarding-v2.cjs

@@ -22,7 +22,7 @@
  * before publishing.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EnyoOnboardingV2TargetType = exports.EnyoOnboardingV2TransitionSourceKind = exports.EnyoOnboardingV2BlockType = exports.EnyoOnboardingV2ChoiceLayout = exports.EnyoOnboardingV2IconKey = exports.EnyoOnboardingV2DeviceSelection = exports.EnyoOnboardingV2ActionKind = exports.EnyoOnboardingV2DynamicKind = exports.EnyoOnboardingV2HintVariant = exports.EnyoOnboardingV2PauseReason = exports.EnyoOnboardingV2StartVariant = void 0;
+exports.EnyoOnboardingV2TargetType = exports.EnyoOnboardingV2TransitionSourceKind = exports.EnyoOnboardingV2BlockType = exports.EnyoOnboardingV2ChoiceLayout = exports.EnyoOnboardingV2IconKey = exports.EnyoOnboardingV2DeviceSelection = exports.EnyoOnboardingV2InputValueType = exports.EnyoOnboardingV2ActionKind = exports.EnyoOnboardingV2DynamicKind = exports.EnyoOnboardingV2HintVariant = exports.EnyoOnboardingV2PauseReason = exports.EnyoOnboardingV2StartVariant = void 0;
 // ---------------------------------------------------------------------------
 // Enumerable string enums
 // ---------------------------------------------------------------------------
@@ -88,6 +88,19 @@ var EnyoOnboardingV2ActionKind;
      */
     EnyoOnboardingV2ActionKind["DeviceTest"] = "device-test";
 })(EnyoOnboardingV2ActionKind || (exports.EnyoOnboardingV2ActionKind = EnyoOnboardingV2ActionKind = {}));
+/**
+ * What an {@link EnyoOnboardingV2InputBlock} asks the installer for. Drives the
+ * keyboard the app shows, the format check it applies and the seeded texts.
+ */
+var EnyoOnboardingV2InputValueType;
+(function (EnyoOnboardingV2InputValueType) {
+    /** Free text; any non-empty value is accepted. */
+    EnyoOnboardingV2InputValueType["Text"] = "text";
+    /** An IPv4 address. This is the only type the host actually checks. */
+    EnyoOnboardingV2InputValueType["IpAddress"] = "ip-address";
+    /** A number; `,` and `.` are both accepted as the decimal separator. */
+    EnyoOnboardingV2InputValueType["Number"] = "number";
+})(EnyoOnboardingV2InputValueType || (exports.EnyoOnboardingV2InputValueType = EnyoOnboardingV2InputValueType = {}));
 /**
  * Which devices a {@link EnyoOnboardingV2ActionKind.DeviceTest} block hands to
  * the app.
@@ -129,6 +142,8 @@ var EnyoOnboardingV2BlockType;
     EnyoOnboardingV2BlockType["Dynamic"] = "dynamic";
     EnyoOnboardingV2BlockType["Choice"] = "choice";
     EnyoOnboardingV2BlockType["Action"] = "action";
+    EnyoOnboardingV2BlockType["Link"] = "link";
+    EnyoOnboardingV2BlockType["Input"] = "input";
 })(EnyoOnboardingV2BlockType || (exports.EnyoOnboardingV2BlockType = EnyoOnboardingV2BlockType = {}));
 // ---------------------------------------------------------------------------
 // Routing: transitions & targets
@@ -140,7 +155,7 @@ var EnyoOnboardingV2TransitionSourceKind;
     EnyoOnboardingV2TransitionSourceKind["Continue"] = "continue";
     /** A specific option of a `Choice` block was picked. */
     EnyoOnboardingV2TransitionSourceKind["Choice"] = "choice";
-    /** A specific outcome of an `Action` block fired. */
+    /** A specific outcome of an `Action` or `Input` block fired. */
     EnyoOnboardingV2TransitionSourceKind["Outcome"] = "outcome";
 })(EnyoOnboardingV2TransitionSourceKind || (exports.EnyoOnboardingV2TransitionSourceKind = EnyoOnboardingV2TransitionSourceKind = {}));
 /** Discriminator for the {@link EnyoOnboardingV2Target} union. */

package/dist/cjs/types/enyo-onboarding-v2.d.cts

@@ -78,6 +78,18 @@ export declare enum EnyoOnboardingV2ActionKind {
      */
     DeviceTest = "device-test"
 }
+/**
+ * What an {@link EnyoOnboardingV2InputBlock} asks the installer for. Drives the
+ * keyboard the app shows, the format check it applies and the seeded texts.
+ */
+export declare enum EnyoOnboardingV2InputValueType {
+    /** Free text; any non-empty value is accepted. */
+    Text = "text",
+    /** An IPv4 address. This is the only type the host actually checks. */
+    IpAddress = "ip-address",
+    /** A number; `,` and `.` are both accepted as the decimal separator. */
+    Number = "number"
+}
 /**
  * Which devices a {@link EnyoOnboardingV2ActionKind.DeviceTest} block hands to
  * the app.
@@ -111,7 +123,9 @@ export declare enum EnyoOnboardingV2BlockType {
     Hint = "hint",
     Dynamic = "dynamic",
     Choice = "choice",
-    Action = "action"
+    Action = "action",
+    Link = "link",
+    Input = "input"
 }
 /** Fields shared by every content/interactive block. */
 export interface EnyoOnboardingV2BlockBase {
@@ -209,17 +223,139 @@ export interface EnyoOnboardingV2ActionBlock extends EnyoOnboardingV2BlockBase {
      */
     deviceSelection?: EnyoOnboardingV2DeviceSelection;
 }
+/**
+ * A fixed URL the installer opens or copies — a vendor portal, a manual, a
+ * firmware download.
+ *
+ * Passive content: it produces no routing handle, so a step whose only
+ * non-content block is a link still routes through its single `continue`
+ * handle. Unlike {@link EnyoOnboardingV2DynamicBlock}, the URL is the same for
+ * every installer — nothing is resolved per device.
+ */
+export interface EnyoOnboardingV2LinkBlock extends EnyoOnboardingV2BlockBase {
+    type: EnyoOnboardingV2BlockType.Link;
+    /**
+     * Absolute `http(s)` URL, not translated. Any other scheme is rejected by
+     * the validator and by the host: the installer app renders this as a tap
+     * target.
+     */
+    url: string;
+    /** Translated link text (de/en). Falls back to the raw URL when empty. */
+    label: EnyoOnboardingTranslatedContent[];
+    /** Optional translated context line below the link (de/en). */
+    description?: EnyoOnboardingTranslatedContent[];
+    /**
+     * Show a copy-to-clipboard button. Defaults to `true` — on a phone it is the
+     * more useful affordance of the two.
+     */
+    copyable?: boolean;
+}
+/**
+ * A possible verdict of an {@link EnyoOnboardingV2InputBlock}'s check; each
+ * outcome is a routing handle.
+ */
+export interface EnyoOnboardingV2InputOutcome {
+    /** Stable id, unique within the block; referenced by a transition. */
+    id: string;
+    /**
+     * Semantic key, not translated. Either an {@link EnyoDeviceTestOutcomeEnum}
+     * member (routed exactly) or one of the binary keys the host collapses
+     * onto — `reachable` / `unreachable`. See {@link EnyoOnboardingV2InputBlock}
+     * for the full mapping.
+     */
+    value: string;
+    /** Translated display label for the verdict (de/en). */
+    label: EnyoOnboardingTranslatedContent[];
+}
+/**
+ * The installer types a value and the **host** checks it, producing the branch —
+ * unlike {@link EnyoOnboardingV2ChoiceBlock}, where the installer picks the
+ * branch directly.
+ *
+ * For {@link EnyoOnboardingV2InputValueType.IpAddress} the host pairs the typed
+ * address with this energy app (creating the network device when the scan never
+ * discovered it) and runs the app's registered {@link EnyoDeviceTestHandler}
+ * against it, so the verdict is the app's own — it confirms *your* device, not
+ * merely a live host. `Text` and `Number` are recorded and take the positive
+ * branch; there is nothing the host could check about them.
+ *
+ * Each outcome MUST have exactly one outgoing transition.
+ *
+ * **How a verdict picks an outcome**
+ *
+ * 1. *Exact match wins.* An outcome whose `value` is an
+ *    {@link EnyoDeviceTestOutcomeEnum} member receives that verdict verbatim —
+ *    so a guide can route `authentication-required` to a credentials step and
+ *    `user-action-required` to a "press the pairing button" step.
+ * 2. *Otherwise it collapses to a binary pair.* `appliances-created`,
+ *    `appliances-already-existed` and `device-confirmed-no-appliance` go to the
+ *    first outcome valued `reachable` / `success` / `found`; everything else
+ *    (`unreachable`, `not-supported`, `authentication-required`,
+ *    `access-not-granted`, `user-action-required`, `failed`) goes to the first
+ *    outcome valued `unreachable` / `failure` / `failed` / `not-found`.
+ * 3. `Text` and `Number` run no check: the value is recorded and the flow takes
+ *    the positive outcome (first `reachable`/`success`/`found`, else the first
+ *    outcome). Any further outcome on such a block can never fire.
+ * 4. An offline hub, a package that is not installed, or no energy app linked to
+ *    the vendor/model all resolve to the **negative** branch — never an error.
+ *    The guide always gets an outcome to route on.
+ *
+ * The typed value is persisted per block in the run state and handed back on
+ * resume/back, so a typo is corrected rather than retyped. Values may be secrets
+ * (a device password typed into a `Text` input): the host logs outcome keys
+ * only, never the value itself.
+ *
+ * @example
+ * ```ts
+ * onboardingV2Block.input(
+ *     'b3',
+ *     EnyoOnboardingV2InputValueType.IpAddress,
+ *     t('IP-Adresse des Geräts', 'Device IP address'),
+ *     t('Gerät prüfen', 'Check device'),
+ *     [
+ *         {id: 'ok', value: 'reachable', label: t('Gerät erreichbar', 'Device reachable')},
+ *         {
+ *             id: 'auth',
+ *             value: EnyoDeviceTestOutcomeEnum.AuthenticationRequired,
+ *             label: t('Passwort nötig', 'Password required'),
+ *         },
+ *         {id: 'no', value: 'unreachable', label: t('Nicht erreichbar', 'Not reachable')},
+ *     ],
+ *     {placeholder: t('z. B. 192.168.1.42', 'e.g. 192.168.1.42')},
+ * );
+ * ```
+ */
+export interface EnyoOnboardingV2InputBlock extends EnyoOnboardingV2BlockBase {
+    type: EnyoOnboardingV2BlockType.Input;
+    /** What is asked for; drives keyboard, format check and seeded texts. */
+    valueType: EnyoOnboardingV2InputValueType;
+    /** Translated field label, e.g. "IP-Adresse des Geräts" (de/en). */
+    label: EnyoOnboardingTranslatedContent[];
+    /** Optional translated placeholder, e.g. "z. B. 192.168.1.42" (de/en). */
+    placeholder?: EnyoOnboardingTranslatedContent[];
+    /** Optional translated help text — where the installer finds the value (de/en). */
+    help?: EnyoOnboardingTranslatedContent[];
+    /** Translated submit button text, e.g. "Gerät prüfen" (de/en). */
+    submitLabel: EnyoOnboardingTranslatedContent[];
+    /** The possible verdicts; each is a routing handle. At least 2. */
+    outcomes: EnyoOnboardingV2InputOutcome[];
+}
 /** Any block that can appear in a step's `blocks`. */
-export type EnyoOnboardingV2Block = EnyoOnboardingV2TextBlock | EnyoOnboardingV2HeadlineBlock | EnyoOnboardingV2BulletsBlock | EnyoOnboardingV2ImageBlock | EnyoOnboardingV2HintBlock | EnyoOnboardingV2DynamicBlock | EnyoOnboardingV2ChoiceBlock | EnyoOnboardingV2ActionBlock;
-/** Blocks that produce routing handles (a step's decision points). */
-export type EnyoOnboardingV2InteractiveBlock = EnyoOnboardingV2ChoiceBlock | EnyoOnboardingV2ActionBlock;
+export type EnyoOnboardingV2Block = EnyoOnboardingV2TextBlock | EnyoOnboardingV2HeadlineBlock | EnyoOnboardingV2BulletsBlock | EnyoOnboardingV2ImageBlock | EnyoOnboardingV2HintBlock | EnyoOnboardingV2DynamicBlock | EnyoOnboardingV2ChoiceBlock | EnyoOnboardingV2ActionBlock | EnyoOnboardingV2LinkBlock | EnyoOnboardingV2InputBlock;
+/**
+ * Blocks that produce routing handles (a step's decision points).
+ *
+ * A {@link EnyoOnboardingV2LinkBlock} is deliberately absent: it is passive
+ * content and routes nothing.
+ */
+export type EnyoOnboardingV2InteractiveBlock = EnyoOnboardingV2ChoiceBlock | EnyoOnboardingV2ActionBlock | EnyoOnboardingV2InputBlock;
 /** Discriminator for the {@link EnyoOnboardingV2TransitionSource} union. */
 export declare enum EnyoOnboardingV2TransitionSourceKind {
     /** The step's plain "continue" button (steps with no interactive block). */
     Continue = "continue",
     /** A specific option of a `Choice` block was picked. */
     Choice = "choice",
-    /** A specific outcome of an `Action` block fired. */
+    /** A specific outcome of an `Action` or `Input` block fired. */
     Outcome = "outcome"
 }
 /** Where a transition leaves from within a step. */
@@ -234,7 +370,7 @@ export type EnyoOnboardingV2TransitionSource =
     blockId: string;
     optionId: string;
 }
-/** A specific outcome of an `Action` block fired. */
+/** A specific outcome of an `Action` or `Input` block fired. */
  | {
     kind: EnyoOnboardingV2TransitionSourceKind.Outcome;
     blockId: string;