@enyo-energy/energy-app-sdk 0.0.199 → 1.0.0

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

@@ -147,6 +147,7 @@ function validateOnboardingGuideV2(guide, context) {
             `"${enyo_onboarding_v2_js_1.EnyoOnboardingV2PauseReason.EnyoTodo}" when enyo takes the setup over.`);
     }
     validateNetworkScanFlag(guide, warnings);
+    validateApplianceBinding(guide, errors, warnings);
     return { ok: errors.length === 0, errors, warnings };
 }
 /**
@@ -645,6 +646,41 @@ function validateAdditionalSetupBlocks(step, at, errors, warnings) {
         }
     }
 }
+/**
+ * Checks {@link EnyoOnboardingV2Guide.applianceId} against the guide's
+ * {@link EnyoOnboardingV2Guide.startVariant}.
+ *
+ * The binding is required on {@link EnyoOnboardingV2StartVariant.Maintenance}
+ * and meaningless everywhere else. A maintenance run services an appliance that
+ * already exists, so a guide that does not name one cannot be bound to anything
+ * — that is a blocking error, not advice. The reverse is only a warning: an
+ * installation guide carrying an appliance id is harmless, the host ignores it,
+ * but it is a sign the wrong variant was chosen.
+ *
+ * @param guide - The guide being validated.
+ * @param errors - Collector for blocking problems.
+ * @param warnings - Collector for advisory problems.
+ */
+function validateApplianceBinding(guide, errors, warnings) {
+    const isMaintenance = guide.startVariant === enyo_onboarding_v2_js_1.EnyoOnboardingV2StartVariant.Maintenance;
+    const applianceId = typeof guide.applianceId === 'string' ? guide.applianceId.trim() : undefined;
+    if (isMaintenance) {
+        if (!applianceId) {
+            errors.push('`applianceId` is required on a `' +
+                `${enyo_onboarding_v2_js_1.EnyoOnboardingV2StartVariant.Maintenance}` +
+                '` guide — a maintenance run services an appliance that already exists, so the ' +
+                'guide must name it.');
+        }
+        return;
+    }
+    if (applianceId) {
+        warnings.push('`applianceId` is set on a `' +
+            `${guide.startVariant}` +
+            '` guide and is ignored — only a `' +
+            `${enyo_onboarding_v2_js_1.EnyoOnboardingV2StartVariant.Maintenance}` +
+            '` guide binds an existing appliance.');
+    }
+}
 /**
  * Checks {@link EnyoOnboardingV2Guide.requiresNetworkScan} against what the guide
  * actually does.

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

@@ -39,6 +39,27 @@ var EnyoOnboardingV2StartVariant;
     EnyoOnboardingV2StartVariant["DeviceFoundConfig"] = "device-found-config";
     /** Manual setup is required by the user (e.g. enter OCPP URL). */
     EnyoOnboardingV2StartVariant["ManualSetup"] = "manual-setup";
+    /**
+     * Maintenance on an appliance that already exists — the only variant that
+     * does not start from an installation.
+     *
+     * The other three all describe a device on its way *into* the system: not
+     * found yet, found but unconfigured, or set up by hand. This one starts from
+     * the opposite situation — the appliance is installed, known and running,
+     * and the installer is coming back to it to service, reconfigure or
+     * reconnect it.
+     *
+     * Because the appliance is the subject of the run rather than its result, a
+     * maintenance guide MUST name it: see
+     * {@link EnyoOnboardingV2Guide.applianceId}, which
+     * {@link validateOnboardingGuideV2} requires on this variant and on no
+     * other. That binding is what fills the `applianceId` the host passes to
+     * {@link EnyoOnboardingV2DynamicRequest} and
+     * {@link EnyoOnboardingV2AdditionalSetupRequest} — on an installation
+     * variant those are populated only once an appliance happens to exist,
+     * whereas here they are known from the first step.
+     */
+    EnyoOnboardingV2StartVariant["Maintenance"] = "maintenance";
 })(EnyoOnboardingV2StartVariant || (exports.EnyoOnboardingV2StartVariant = EnyoOnboardingV2StartVariant = {}));
 /**
  * Why an onboarding run left the flow through a {@link EnyoOnboardingV2TargetType.Pause}

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

@@ -32,7 +32,28 @@ export declare enum EnyoOnboardingV2StartVariant {
     /** The device is on the network but still needs configuration. */
     DeviceFoundConfig = "device-found-config",
     /** Manual setup is required by the user (e.g. enter OCPP URL). */
-    ManualSetup = "manual-setup"
+    ManualSetup = "manual-setup",
+    /**
+     * Maintenance on an appliance that already exists — the only variant that
+     * does not start from an installation.
+     *
+     * The other three all describe a device on its way *into* the system: not
+     * found yet, found but unconfigured, or set up by hand. This one starts from
+     * the opposite situation — the appliance is installed, known and running,
+     * and the installer is coming back to it to service, reconfigure or
+     * reconnect it.
+     *
+     * Because the appliance is the subject of the run rather than its result, a
+     * maintenance guide MUST name it: see
+     * {@link EnyoOnboardingV2Guide.applianceId}, which
+     * {@link validateOnboardingGuideV2} requires on this variant and on no
+     * other. That binding is what fills the `applianceId` the host passes to
+     * {@link EnyoOnboardingV2DynamicRequest} and
+     * {@link EnyoOnboardingV2AdditionalSetupRequest} — on an installation
+     * variant those are populated only once an appliance happens to exist,
+     * whereas here they are known from the first step.
+     */
+    Maintenance = "maintenance"
 }
 /**
  * Why an onboarding run left the flow through a {@link EnyoOnboardingV2TargetType.Pause}
@@ -863,6 +884,25 @@ export interface EnyoOnboardingV2Guide {
     startStepId: string;
     /** The graph nodes (a set, not an ordered list). */
     steps: EnyoOnboardingV2Step[];
+    /**
+     * The appliance this guide is bound to — **required on**
+     * {@link EnyoOnboardingV2StartVariant.Maintenance}, and meaningless on every
+     * other variant.
+     *
+     * A maintenance run services an appliance that already exists, so the
+     * appliance is an input to the run rather than something it produces: the
+     * host binds the run to this id and passes it on as
+     * {@link EnyoOnboardingV2DynamicRequest.applianceId} and
+     * {@link EnyoOnboardingV2AdditionalSetupRequest.applianceId} from the first
+     * step onwards. The installation variants have nothing to bind — their
+     * appliance is created by the run, if it is created at all — and a guide
+     * that sets this anyway is warned about and the value ignored.
+     *
+     * Optional in the type because one interface serves all four variants; the
+     * variant-dependent requirement is enforced by
+     * {@link validateOnboardingGuideV2} instead of by the compiler.
+     */
+    applianceId?: string;
     /** Optional vendor binding (catalog id). Usually set at publish time. */
     vendorId?: string;
     /** Optional model bindings (catalog ids). Usually set at publish time. */

package/dist/cjs/version.cjs

@@ -9,7 +9,7 @@ exports.getSdkVersion = getSdkVersion;
 /**
  * Current version of the enyo Energy App SDK.
  */
-exports.SDK_VERSION = '0.0.199';
+exports.SDK_VERSION = '1.0.0';
 /**
  * Gets the current SDK version.
  * @returns The semantic version string of the SDK

package/dist/cjs/version.d.cts

@@ -5,7 +5,7 @@
 /**
  * Current version of the enyo Energy App SDK.
  */
-export declare const SDK_VERSION = "0.0.199";
+export declare const SDK_VERSION = "1.0.0";
 /**
  * Gets the current SDK version.
  * @returns The semantic version string of the SDK

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

@@ -13,7 +13,7 @@
  * {@link EnyoOnboardingV2PauseReason.EnyoTodo}) — both count, so a guide that
  * legitimately ends in a hand-off is not nagged about a missing success path.
  */
-import { EnyoOnboardingV2ActionKind, EnyoOnboardingV2EebusPairOutcome, EnyoOnboardingV2BlockType, EnyoOnboardingV2DeviceSelection, EnyoOnboardingV2SetupFieldType, EnyoOnboardingV2InputValueType, EnyoOnboardingV2OcppConnectOutcome, EnyoOnboardingV2PauseReason, EnyoOnboardingV2TargetType, EnyoOnboardingV2TransitionSourceKind, } from '../../types/enyo-onboarding-v2.js';
+import { EnyoOnboardingV2ActionKind, EnyoOnboardingV2EebusPairOutcome, EnyoOnboardingV2BlockType, EnyoOnboardingV2DeviceSelection, EnyoOnboardingV2SetupFieldType, EnyoOnboardingV2InputValueType, EnyoOnboardingV2OcppConnectOutcome, EnyoOnboardingV2PauseReason, EnyoOnboardingV2StartVariant, EnyoOnboardingV2TargetType, EnyoOnboardingV2TransitionSourceKind, } from '../../types/enyo-onboarding-v2.js';
 import { EnyoDeviceTestOutcomeEnum } from '../../types/enyo-device-test.js';
 import { ENYO_ONBOARDING_V2_SETUP_FAILED_OUTCOME } from '../../types/enyo-onboarding-v2-additional-setup.js';
 import { isImagePublicFile } from '../files/public-file-validators.js';
@@ -141,6 +141,7 @@ export function validateOnboardingGuideV2(guide, context) {
             `"${EnyoOnboardingV2PauseReason.EnyoTodo}" when enyo takes the setup over.`);
     }
     validateNetworkScanFlag(guide, warnings);
+    validateApplianceBinding(guide, errors, warnings);
     return { ok: errors.length === 0, errors, warnings };
 }
 /**
@@ -639,6 +640,41 @@ function validateAdditionalSetupBlocks(step, at, errors, warnings) {
         }
     }
 }
+/**
+ * Checks {@link EnyoOnboardingV2Guide.applianceId} against the guide's
+ * {@link EnyoOnboardingV2Guide.startVariant}.
+ *
+ * The binding is required on {@link EnyoOnboardingV2StartVariant.Maintenance}
+ * and meaningless everywhere else. A maintenance run services an appliance that
+ * already exists, so a guide that does not name one cannot be bound to anything
+ * — that is a blocking error, not advice. The reverse is only a warning: an
+ * installation guide carrying an appliance id is harmless, the host ignores it,
+ * but it is a sign the wrong variant was chosen.
+ *
+ * @param guide - The guide being validated.
+ * @param errors - Collector for blocking problems.
+ * @param warnings - Collector for advisory problems.
+ */
+function validateApplianceBinding(guide, errors, warnings) {
+    const isMaintenance = guide.startVariant === EnyoOnboardingV2StartVariant.Maintenance;
+    const applianceId = typeof guide.applianceId === 'string' ? guide.applianceId.trim() : undefined;
+    if (isMaintenance) {
+        if (!applianceId) {
+            errors.push('`applianceId` is required on a `' +
+                `${EnyoOnboardingV2StartVariant.Maintenance}` +
+                '` guide — a maintenance run services an appliance that already exists, so the ' +
+                'guide must name it.');
+        }
+        return;
+    }
+    if (applianceId) {
+        warnings.push('`applianceId` is set on a `' +
+            `${guide.startVariant}` +
+            '` guide and is ignored — only a `' +
+            `${EnyoOnboardingV2StartVariant.Maintenance}` +
+            '` guide binds an existing appliance.');
+    }
+}
 /**
  * Checks {@link EnyoOnboardingV2Guide.requiresNetworkScan} against what the guide
  * actually does.

package/dist/types/enyo-onboarding-v2.d.ts

@@ -32,7 +32,28 @@ export declare enum EnyoOnboardingV2StartVariant {
     /** The device is on the network but still needs configuration. */
     DeviceFoundConfig = "device-found-config",
     /** Manual setup is required by the user (e.g. enter OCPP URL). */
-    ManualSetup = "manual-setup"
+    ManualSetup = "manual-setup",
+    /**
+     * Maintenance on an appliance that already exists — the only variant that
+     * does not start from an installation.
+     *
+     * The other three all describe a device on its way *into* the system: not
+     * found yet, found but unconfigured, or set up by hand. This one starts from
+     * the opposite situation — the appliance is installed, known and running,
+     * and the installer is coming back to it to service, reconfigure or
+     * reconnect it.
+     *
+     * Because the appliance is the subject of the run rather than its result, a
+     * maintenance guide MUST name it: see
+     * {@link EnyoOnboardingV2Guide.applianceId}, which
+     * {@link validateOnboardingGuideV2} requires on this variant and on no
+     * other. That binding is what fills the `applianceId` the host passes to
+     * {@link EnyoOnboardingV2DynamicRequest} and
+     * {@link EnyoOnboardingV2AdditionalSetupRequest} — on an installation
+     * variant those are populated only once an appliance happens to exist,
+     * whereas here they are known from the first step.
+     */
+    Maintenance = "maintenance"
 }
 /**
  * Why an onboarding run left the flow through a {@link EnyoOnboardingV2TargetType.Pause}
@@ -863,6 +884,25 @@ export interface EnyoOnboardingV2Guide {
     startStepId: string;
     /** The graph nodes (a set, not an ordered list). */
     steps: EnyoOnboardingV2Step[];
+    /**
+     * The appliance this guide is bound to — **required on**
+     * {@link EnyoOnboardingV2StartVariant.Maintenance}, and meaningless on every
+     * other variant.
+     *
+     * A maintenance run services an appliance that already exists, so the
+     * appliance is an input to the run rather than something it produces: the
+     * host binds the run to this id and passes it on as
+     * {@link EnyoOnboardingV2DynamicRequest.applianceId} and
+     * {@link EnyoOnboardingV2AdditionalSetupRequest.applianceId} from the first
+     * step onwards. The installation variants have nothing to bind — their
+     * appliance is created by the run, if it is created at all — and a guide
+     * that sets this anyway is warned about and the value ignored.
+     *
+     * Optional in the type because one interface serves all four variants; the
+     * variant-dependent requirement is enforced by
+     * {@link validateOnboardingGuideV2} instead of by the compiler.
+     */
+    applianceId?: string;
     /** Optional vendor binding (catalog id). Usually set at publish time. */
     vendorId?: string;
     /** Optional model bindings (catalog ids). Usually set at publish time. */

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

@@ -36,6 +36,27 @@ export var EnyoOnboardingV2StartVariant;
     EnyoOnboardingV2StartVariant["DeviceFoundConfig"] = "device-found-config";
     /** Manual setup is required by the user (e.g. enter OCPP URL). */
     EnyoOnboardingV2StartVariant["ManualSetup"] = "manual-setup";
+    /**
+     * Maintenance on an appliance that already exists — the only variant that
+     * does not start from an installation.
+     *
+     * The other three all describe a device on its way *into* the system: not
+     * found yet, found but unconfigured, or set up by hand. This one starts from
+     * the opposite situation — the appliance is installed, known and running,
+     * and the installer is coming back to it to service, reconfigure or
+     * reconnect it.
+     *
+     * Because the appliance is the subject of the run rather than its result, a
+     * maintenance guide MUST name it: see
+     * {@link EnyoOnboardingV2Guide.applianceId}, which
+     * {@link validateOnboardingGuideV2} requires on this variant and on no
+     * other. That binding is what fills the `applianceId` the host passes to
+     * {@link EnyoOnboardingV2DynamicRequest} and
+     * {@link EnyoOnboardingV2AdditionalSetupRequest} — on an installation
+     * variant those are populated only once an appliance happens to exist,
+     * whereas here they are known from the first step.
+     */
+    EnyoOnboardingV2StartVariant["Maintenance"] = "maintenance";
 })(EnyoOnboardingV2StartVariant || (EnyoOnboardingV2StartVariant = {}));
 /**
  * Why an onboarding run left the flow through a {@link EnyoOnboardingV2TargetType.Pause}

package/dist/version.d.ts

@@ -5,7 +5,7 @@
 /**
  * Current version of the enyo Energy App SDK.
  */
-export declare const SDK_VERSION = "0.0.199";
+export declare const SDK_VERSION = "1.0.0";
 /**
  * Gets the current SDK version.
  * @returns The semantic version string of the SDK

package/dist/version.js

@@ -5,7 +5,7 @@
 /**
  * Current version of the enyo Energy App SDK.
  */
-export const SDK_VERSION = '0.0.199';
+export const SDK_VERSION = '1.0.0';
 /**
  * Gets the current SDK version.
  * @returns The semantic version string of the SDK

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enyo-energy/energy-app-sdk",
-  "version": "0.0.199",
+  "version": "1.0.0",
   "description": "enyo Energy App SDK",
   "type": "module",
   "main": "dist/index.js",