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

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);

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';

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.

package/dist/cjs/packages/energy-app-onboarding-v2.d.cts

@@ -1,6 +1,8 @@
 import type { EnyoOnboardingV2GuidesRequest, EnyoOnboardingV2GuidesResult } from '../types/enyo-onboarding-v2-provider.cjs';
 import type { EnyoOnboardingV2DynamicRequest, EnyoOnboardingV2DynamicResult } from '../types/enyo-onboarding-v2-dynamic.cjs';
 import type { EnyoOnboardingV2AdditionalSetupRequest, EnyoOnboardingV2AdditionalSetupResult } from '../types/enyo-onboarding-v2-additional-setup.cjs';
+import type { EnyoOnboardingV2ValidationHandler } from '../types/enyo-onboarding-v2-validation.cjs';
+import type { EnyoOnboardingV2DeviceSelectHandler } from '../types/enyo-onboarding-v2-device-select.cjs';
 /**
  * Which run of a named guide an app means.
  *
@@ -428,4 +430,56 @@ export interface EnergyAppOnboardingV2 {
      * @returns Promise that resolves once the handler has been removed.
      */
     deregisterAdditionalSetupHandler(): Promise<void>;
+    /**
+     * Registers the handler the host calls to check a value typed into an
+     * {@link EnyoOnboardingV2InputBlock} that set
+     * {@link EnyoOnboardingV2InputBlock.validated}.
+     *
+     * One handler serves every validated input across all of this app's guides.
+     * Registering again replaces the previous one.
+     *
+     * A guide that declares `validated` blocks while no handler is registered is
+     * not broken — unanswered validation is treated as acceptance, exactly like
+     * a timeout — but nothing is checked, so register the handler before
+     * publishing guides that rely on it.
+     *
+     * @param handler - Called with the submitted value; answers valid or invalid
+     * @returns Promise that resolves once the handler is registered
+     */
+    registerInputValidationHandler(handler: EnyoOnboardingV2ValidationHandler): Promise<void>;
+    /**
+     * Removes the registered input validation handler. Validated inputs then
+     * accept every value, as if no handler had ever been registered.
+     *
+     * @returns Promise that resolves once the handler is removed
+     */
+    deregisterInputValidationHandler(): Promise<void>;
+    /**
+     * Registers the handler the host calls when an installer picks devices in an
+     * {@link EnyoOnboardingV2ActionKind.DeviceSelect} block, so the app can turn
+     * them into appliances and hand back the ids.
+     *
+     * The host awaits the answer and binds the run to the returned appliances,
+     * which is what fills `applianceId` for later dynamic and additional-setup
+     * requests on the same run.
+     *
+     * Optional. Without a handler the block still works — the run takes its
+     * `selected` branch and stays bound to the picked device — but no appliance
+     * is created, so a guide that ends there produces an address and nothing the
+     * energy manager can read or control.
+     *
+     * One handler serves every device-select block across all of this app's
+     * guides. Registering again replaces the previous one.
+     *
+     * @param handler - Called with the picked devices; answers with appliance ids
+     * @returns Promise that resolves once the handler is registered
+     */
+    registerDeviceSelectHandler(handler: EnyoOnboardingV2DeviceSelectHandler): Promise<void>;
+    /**
+     * Removes the registered device-select handler. Picks then create no
+     * appliances, as if no handler had ever been registered.
+     *
+     * @returns Promise that resolves once the handler is removed
+     */
+    deregisterDeviceSelectHandler(): Promise<void>;
 }

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

@@ -0,0 +1,29 @@
+"use strict";
+/**
+ * Onboarding guide **v2 device selection** — the host handing an energy app the
+ * network devices an installer picked, and taking back the appliances the app
+ * made of them.
+ *
+ * An {@link EnyoOnboardingV2ActionKind.DeviceSelect} block answers "which of
+ * these is it?" and binds the run to the installer's pick. That binding is an
+ * address, not an appliance: nothing in the system yet represents the device as
+ * something the energy manager can read or control. This model closes that gap —
+ * the app is asked to turn the picked device(s) into appliances and answer with
+ * their ids, and the host binds the run to them so later steps have an
+ * `applianceId` to work with.
+ *
+ * **Distinct from {@link EnyoDeviceTestHandler}, which stays the right tool when
+ * the guide must branch.** A device test produces a verdict per device and an
+ * aggregate outcome the graph routes on — the app decides whether the device is
+ * usable. Here the installer already decided; there is no verdict, no branching,
+ * and the handler's only job is to produce appliances. Reach for the device test
+ * when "we could not use it" must lead somewhere different in the flow.
+ *
+ * Registering is optional. Without a handler the block still works: the run
+ * takes its `selected` branch and stays bound to the device, and no appliance is
+ * created.
+ *
+ * Pure type declarations (no runtime logic). Register the handler through
+ * {@link EnergyAppOnboardingV2} (`../packages/energy-app-onboarding-v2.ts`).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1,105 @@
+/**
+ * Onboarding guide **v2 device selection** — the host handing an energy app the
+ * network devices an installer picked, and taking back the appliances the app
+ * made of them.
+ *
+ * An {@link EnyoOnboardingV2ActionKind.DeviceSelect} block answers "which of
+ * these is it?" and binds the run to the installer's pick. That binding is an
+ * address, not an appliance: nothing in the system yet represents the device as
+ * something the energy manager can read or control. This model closes that gap —
+ * the app is asked to turn the picked device(s) into appliances and answer with
+ * their ids, and the host binds the run to them so later steps have an
+ * `applianceId` to work with.
+ *
+ * **Distinct from {@link EnyoDeviceTestHandler}, which stays the right tool when
+ * the guide must branch.** A device test produces a verdict per device and an
+ * aggregate outcome the graph routes on — the app decides whether the device is
+ * usable. Here the installer already decided; there is no verdict, no branching,
+ * and the handler's only job is to produce appliances. Reach for the device test
+ * when "we could not use it" must lead somewhere different in the flow.
+ *
+ * Registering is optional. Without a handler the block still works: the run
+ * takes its `selected` branch and stays bound to the device, and no appliance is
+ * created.
+ *
+ * Pure type declarations (no runtime logic). Register the handler through
+ * {@link EnergyAppOnboardingV2} (`../packages/energy-app-onboarding-v2.ts`).
+ */
+import type { EnyoNetworkDevice } from './enyo-network-device.cjs';
+/**
+ * One "the installer picked these — make appliances of them" request.
+ *
+ * Raised when a {@link EnyoOnboardingV2ActionKind.DeviceSelect} block completes,
+ * so it is on the critical path of a screen someone is waiting on.
+ */
+export interface EnyoOnboardingV2DeviceSelectRequest {
+    /** Correlates this request with its result. Unique per request. */
+    requestId: string;
+    /** The {@link EnyoOnboardingV2ActionBlock.id} the pick was made on. */
+    blockId: string;
+    /**
+     * The {@link EnyoOnboardingV2Step.name} the block sits on, so an app can tell
+     * two picks apart in a guide that selects more than once, and so a log line
+     * says where an empty answer came from.
+     */
+    stepName: string;
+    /**
+     * What the installer picked, as detected by the host. Never empty.
+     *
+     * An array because one pick can legitimately become several appliances — a
+     * hybrid inverter is an inverter and a battery — and because a block that
+     * later offers a multiple selection delivers here without a breaking change.
+     * A single-pick block sends exactly one entry.
+     */
+    devices: EnyoNetworkDevice[];
+    /** The appliance the run is already bound to, when one exists. */
+    applianceId?: string;
+    /**
+     * The budget for this request, in milliseconds.
+     *
+     * The host owns the clock: once it is spent the host stops waiting and
+     * continues as if no appliance had been produced. The handler is not
+     * notified, so it must bound its own work — cap socket timeouts and retries
+     * so they fit inside the budget.
+     */
+    timeoutMs: number;
+}
+/**
+ * An app's answer to one {@link EnyoOnboardingV2DeviceSelectRequest}.
+ */
+export interface EnyoOnboardingV2DeviceSelectResult {
+    /** The {@link EnyoOnboardingV2DeviceSelectRequest.requestId} this answers. */
+    requestId: string;
+    /**
+     * The appliances the picked device(s) are now represented by — created just
+     * now, or already existing and re-confirmed. The host binds the run to them,
+     * which is what fills `applianceId` for later dynamic and additional-setup
+     * requests.
+     *
+     * Return the ids of appliances that already existed too. Omitting them
+     * because the app did not create them in this call leaves the run unbound to
+     * a device it can plainly see.
+     *
+     * An empty array is a valid answer and means no appliance could be made. It
+     * does **not** re-route the flow — the run still takes the block's
+     * `selected` branch. A guide that must go somewhere else in that case needs
+     * an {@link EnyoOnboardingV2ActionKind.DeviceTest} block, whose verdict is a
+     * routing handle.
+     */
+    applianceIds: string[];
+    /** Untranslated technical detail for support, e.g. why nothing was created. Not shown to users. */
+    detail?: string;
+}
+/**
+ * Handles the host's "make appliances of these devices" requests.
+ *
+ * One handler serves every device-select block the app's guides declare —
+ * switch on {@link EnyoOnboardingV2DeviceSelectRequest.blockId} (and `stepName`
+ * where a block id repeats across guides) when the treatment differs.
+ *
+ * Throwing is treated the same as answering with no appliance ids: the run
+ * continues on the block's `selected` branch, unbound. Creating an appliance is
+ * a convenience the flow does not depend on, so a handler must never strand an
+ * installer by failing loudly.
+ */
+export type EnyoOnboardingV2DeviceSelectHandler = (request: EnyoOnboardingV2DeviceSelectRequest) => Promise<EnyoOnboardingV2DeviceSelectResult>;

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

@@ -0,0 +1,29 @@
+"use strict";
+/**
+ * Onboarding guide **v2 input validation** — the host asking an energy app
+ * whether a typed value is acceptable, before the run moves on.
+ *
+ * An {@link EnyoOnboardingV2InputBlock} of type
+ * {@link EnyoOnboardingV2InputValueType.IpAddress} already gets the app's own
+ * verdict: the host runs the registered {@link EnyoDeviceTestHandler} and routes
+ * on the outcome. `Text`, `Number` and `Password` have no such check — the value
+ * is recorded and the flow takes the positive outcome, whatever was typed. A
+ * mistyped serial number or a wrong API token is therefore accepted at the step
+ * that asked for it and only fails later, somewhere with no installer standing
+ * in front of it.
+ *
+ * This model closes that gap. An input block that opts in
+ * ({@link EnyoOnboardingV2InputBlock.validated}) has its value handed to the
+ * app, which answers valid or invalid — with a translated message the installer
+ * reads on the spot.
+ *
+ * **Validation is not a branch.** A rejected value keeps the installer on the
+ * step with the message shown; it produces no outcome and needs no transition,
+ * so adding `validated` to a block never changes a guide's graph. Use an
+ * outcome when the flow should go somewhere different, and validation when the
+ * answer is simply wrong.
+ *
+ * Pure type declarations (no runtime logic). Register the handler through
+ * {@link EnergyAppOnboardingV2} (`../packages/energy-app-onboarding-v2.ts`).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });