@enyo-energy/energy-app-sdk 1.1.0 → 1.2.0

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

@@ -47,14 +47,18 @@ const ANY_MODEL = '*';
 /**
  * A short human-readable label for a guide, for use in messages.
  *
- * Prefers the first translated title, since ids are not required at guide level;
- * falls back to the start variant so a titleless guide is still identifiable.
+ * Prefers {@link EnyoOnboardingV2Guide.name} — it is the handle the author will
+ * search for — then the first translated title, then the start variant, so a
+ * guide with neither a name nor a title is still identifiable.
  *
  * @param guide - The guide to label.
  * @param index - Its position in the answer's `guides` array.
  * @returns A message prefix such as ``guides[2] ("Wallbox über OCPP")``.
  */
 function guideLabel(guide, index) {
+    const name = guide.name?.trim();
+    if (name)
+        return `guides[${index}] ("${name}")`;
     const title = guide.title?.[0]?.value;
     return `guides[${index}] (${title ? `"${title}"` : (guide.startVariant ?? '?')})`;
 }
@@ -122,6 +126,9 @@ function validateOnboardingV2GuidesResult(result, context) {
     }
     // Which guide(s) claimed each binding, so a collision can name both sides.
     const claimedBy = new Map();
+    // Same, for the explicit `name` handles — a duplicate makes an app unable to
+    // say which of the two it means.
+    const namedBy = new Map();
     for (const [i, guide] of result.guides.entries()) {
         const at = guideLabel(guide, i);
         const guideResult = (0, onboarding_v2_validators_js_1.validateOnboardingGuideV2)(guide, context);
@@ -134,6 +141,17 @@ function validateOnboardingV2GuidesResult(result, context) {
         else if (!guide.modelIds?.length) {
             warnings.push(`${at}: no modelIds — this guide applies to every model of "${guide.vendorId}".`);
         }
+        const name = guide.name?.trim();
+        if (name) {
+            const previouslyNamed = namedBy.get(name);
+            if (previouslyNamed) {
+                errors.push(`${at}: name "${name}" is already used by ${previouslyNamed} — ` +
+                    'a name is how an app addresses one specific guide, so two guides cannot share one.');
+            }
+            else {
+                namedBy.set(name, at);
+            }
+        }
         for (const key of bindingKeys(guide)) {
             const previous = claimedBy.get(key);
             if (previous) {

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

@@ -149,6 +149,7 @@ function validateOnboardingGuideV2(guide, context) {
     validateNetworkScanFlag(guide, warnings);
     validateApplianceBinding(guide, errors, warnings);
     validateUserNotification(guide, warnings);
+    validateGuideName(guide, errors, warnings);
     return { ok: errors.length === 0, errors, warnings };
 }
 /**
@@ -682,6 +683,37 @@ function validateApplianceBinding(guide, errors, warnings) {
             '` guide binds an existing appliance.');
     }
 }
+/**
+ * Checks {@link EnyoOnboardingV2Guide.name} is usable as a handle.
+ *
+ * The property is optional — a guide that never needs to be addressed does not
+ * need one, and the host falls back to a name derived from the guide's
+ * bindings. But a name that is *present* and blank is worse than absent: it
+ * looks like a handle at the call site and matches nothing, so
+ * `removeOnboardingGuide('')` would silently do nothing. That is an error.
+ *
+ * Whitespace around a name is trimmed by the host before it is compared, so
+ * `" setup "` and `"setup"` are the same handle; a name carrying padding is
+ * only warned about, since it works but will not look like what the author
+ * typed in a log line.
+ *
+ * @param guide - The guide being validated.
+ * @param errors - Collector for blocking problems.
+ * @param warnings - Collector for advisory problems.
+ */
+function validateGuideName(guide, errors, warnings) {
+    if (guide.name === undefined)
+        return;
+    if (typeof guide.name !== 'string' || guide.name.trim() === '') {
+        errors.push('`name` is present but blank — a guide either carries a handle an app can address ' +
+            'it by or omits the property entirely; an empty name matches nothing.');
+        return;
+    }
+    if (guide.name !== guide.name.trim()) {
+        warnings.push(`\`name\` "${guide.name}" has leading or trailing whitespace, which the host trims — ` +
+            'the guide is addressed as `' + guide.name.trim() + '`.');
+    }
+}
 /**
  * Checks {@link EnyoOnboardingV2Guide.notifyUser} against the guide's
  * {@link EnyoOnboardingV2Guide.startVariant}.

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

@@ -1,6 +1,28 @@
 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';
+/**
+ * Which run of a named guide an app means.
+ *
+ * A guide name identifies the *flow*; this narrows it to one walk of that flow
+ * when more than one can be open at a time. A maintenance guide is bound to an
+ * appliance and its runs live in a lane of their own — one per appliance — so
+ * that is the only distinction the host needs.
+ *
+ * Omit it entirely for a guide that has one open run, which is every
+ * installation variant.
+ */
+export interface EnyoOnboardingV2RunSelector {
+    /**
+     * The appliance whose run is meant, for a guide bound to one
+     * ({@link EnyoOnboardingV2StartVariant.Maintenance}).
+     *
+     * Omitted on a maintenance guide, the call addresses that guide's single
+     * open run when there is exactly one and is rejected when there are
+     * several — an ambiguous "complete the run" must not close an arbitrary one.
+     */
+    applianceId?: string;
+}
 /**
  * Handler the host calls to collect every onboarding guide (v2) an app ships.
  *
@@ -196,6 +218,124 @@ export interface EnergyAppOnboardingV2 {
      * @returns Promise that resolves once the host has taken the new answer.
      */
     refreshOnboardingGuides(): Promise<void>;
+    /**
+     * Retires one guide by name, without the app restating its whole set.
+     *
+     * The ordinary way to retire a guide is to leave it out of the next
+     * {@link EnyoOnboardingV2GuidesHandler} answer, and that remains the right
+     * choice when the app's guide set is a static list in its source. This is
+     * for the case that answer cannot express: a guide the app decided to
+     * withdraw *now* — a vendor account was unlinked, an appliance it was bound
+     * to is gone — where waiting for the host's next pull means an installer
+     * can still start a flow the app can no longer serve.
+     *
+     * Names the guide by its {@link EnyoOnboardingV2Guide.name}, so only a
+     * guide that carries one can be retired this way. A guide without a name is
+     * addressable only as part of the complete answer.
+     *
+     * **The handler is still the source of truth.** This drops the guide from
+     * the host's cache; it does not stop the app from offering it again. If the
+     * handler keeps returning the guide, the next pull brings it back — so
+     * remove it from what the handler builds as well, or the retirement lasts
+     * only until the next sync.
+     *
+     * Runs already walking the guide are not touched: a guide is retired for the
+     * *next* installer, and pulling a flow out from under one already inside it
+     * would strand them mid-installation. Use {@link removeOnboardingRun} to end
+     * a run.
+     *
+     * Removing a guide the host does not know — wrong name, already retired — is
+     * a no-op rather than an error.
+     *
+     * This API is available to every app — it is not permission-gated.
+     *
+     * @param name - The {@link EnyoOnboardingV2Guide.name} of the guide to retire.
+     * @returns Promise that resolves once the host has dropped the guide.
+     *
+     * @example
+     * ```typescript
+     * await energyApp.useOnboardingV2().removeOnboardingGuide('vendor-cloud-setup');
+     * ```
+     */
+    removeOnboardingGuide(name: string): Promise<void>;
+    /**
+     * Marks the run walking a named guide as **completed**.
+     *
+     * For the flow that finished somewhere other than on the installer's
+     * screen. A guide normally completes when the walk reaches a success
+     * target — the installer taps through to the end. But an app sometimes
+     * learns the goal was met by another route: the wallbox connected over OCPP
+     * by itself, the vendor cloud confirmed the pairing, the appliance the
+     * maintenance run was servicing reported healthy. Leaving that run open
+     * shows the customer an installation still in progress that nobody intends
+     * to continue.
+     *
+     * The run is closed as a **success**: it leaves the "open" set, stops being
+     * offered for resumption, and counts as a finished installation. Use
+     * {@link removeOnboardingRun} for a flow that ended without achieving
+     * anything — the two are not interchangeable, and reporting an abandoned
+     * setup as completed is how a broken installation looks fine on a dashboard.
+     *
+     * Completing a run that is already finished — completed or removed — is a
+     * no-op: the first outcome stands, and a late confirmation does not reopen
+     * or re-close a run. So is naming a guide with no open run at all.
+     *
+     * Not permission-gated, like the rest of this API: a guide name is resolved
+     * within the calling package, so an app can only reach runs of guides it
+     * ships itself.
+     *
+     * @param name - The {@link EnyoOnboardingV2Guide.name} of the guide whose run
+     *   should be completed.
+     * @param selector - Which run, when the guide can have more than one open.
+     * @returns Promise that resolves once the host has closed the run.
+     *
+     * @example
+     * ```typescript
+     * // The wallbox connected on its own — the installer never reached the last step.
+     * ocpp.onChargePointConnect(async () => {
+     *     await energyApp.useOnboardingV2().completeOnboardingRun('wallbox-ocpp-setup');
+     * });
+     * ```
+     */
+    completeOnboardingRun(name: string, selector?: EnyoOnboardingV2RunSelector): Promise<void>;
+    /**
+     * Ends the run walking a named guide **without** completing it.
+     *
+     * The counterpart to {@link completeOnboardingRun}, for a flow that is over
+     * but achieved nothing: the device it was setting up was removed, the
+     * appliance a maintenance run was servicing no longer exists, the app can no
+     * longer serve the guide the run is walking. The run leaves the open set as
+     * abandoned rather than successful, so it stops being offered for resumption
+     * and is not counted as a finished installation.
+     *
+     * This ends a *run*, not a guide. The guide stays available and a new run
+     * can start on it immediately — that is the point when a stuck run is
+     * blocking a fresh attempt, since a device can have only one open run per
+     * flow. Use {@link removeOnboardingGuide} to withdraw the flow itself.
+     *
+     * An installer may be looking at the run when it is removed. Do this because
+     * the run genuinely cannot continue, not to tidy up: the screen ends the
+     * setup under them, and nothing explains why.
+     *
+     * Removing a run that is already finished, or naming a guide with no open
+     * run, is a no-op.
+     *
+     * Not permission-gated, like the rest of this API: a guide name is resolved
+     * within the calling package, so an app can only reach runs of guides it
+     * ships itself.
+     *
+     * @param name - The {@link EnyoOnboardingV2Guide.name} of the guide whose run
+     *   should be removed.
+     * @param selector - Which run, when the guide can have more than one open.
+     * @returns Promise that resolves once the host has ended the run.
+     *
+     * @example
+     * ```typescript
+     * // The appliance this maintenance flow services was deleted.
+     * await energyApp.useOnboardingV2().removeOnboardingRun('wallbox-service', {applianceId});
+     * ```
+     */
+    removeOnboardingRun(name: string, selector?: EnyoOnboardingV2RunSelector): Promise<void>;
     /**
      * Registers the handler the host calls to resolve dynamic block values
      * (`ocpp-url`, `device-ip`) while a step is rendered.

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

@@ -851,6 +851,35 @@ export interface EnyoOnboardingV2Step {
  * usually bound at registration/publish time and may be omitted here.
  */
 export interface EnyoOnboardingV2Guide {
+    /**
+     * Stable handle for this guide — the name the app calls it by when it wants
+     * to act on it later.
+     *
+     * A guide is normally never addressed: guides are pulled, the app's answer
+     * is the complete set, and a guide is retired by leaving it out. This exists
+     * for the cases where an app has to say something *about one specific
+     * guide* instead of restating the whole set — retiring it with
+     * {@link EnergyAppOnboardingV2.removeOnboardingGuide}, or completing or
+     * removing the run walking it
+     * ({@link EnergyAppOnboardingV2.completeOnboardingRun},
+     * {@link EnergyAppOnboardingV2.removeOnboardingRun}).
+     *
+     * **Stable once shipped, like a step's `name`.** A run in progress is
+     * anchored to it, so renaming a guide between two package versions strands
+     * whatever was paused inside it. Choose a kebab-case slug that describes the
+     * flow rather than the hardware it currently applies to
+     * (`wallbox-ocpp-setup`, not `acme-ac22`), and keep it when the bindings
+     * change.
+     *
+     * Unique within the app's answer — two guides sharing a name cannot be told
+     * apart, and {@link validateOnboardingV2GuidesResult} rejects the answer.
+     *
+     * Optional. Omit it and the host files the guide under a name derived from
+     * what it binds to (vendor, models, start variant, and the appliance on a
+     * maintenance guide) exactly as before — that keeps working, it just cannot
+     * be named by an app that never chose a name.
+     */
+    name?: string;
     /** Translated display title (de/en). */
     title: EnyoOnboardingTranslatedContent[];
     /** Which start situation this guide covers. */

package/dist/cjs/version.cjs

@@ -9,7 +9,7 @@ exports.getSdkVersion = getSdkVersion;
 /**
  * Current version of the enyo Energy App SDK.
  */
-exports.SDK_VERSION = '1.1.0';
+exports.SDK_VERSION = '1.2.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 = "1.1.0";
+export declare const SDK_VERSION = "1.2.0";
 /**
  * Gets the current SDK version.
  * @returns The semantic version string of the SDK

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

@@ -41,14 +41,18 @@ const ANY_MODEL = '*';
 /**
  * A short human-readable label for a guide, for use in messages.
  *
- * Prefers the first translated title, since ids are not required at guide level;
- * falls back to the start variant so a titleless guide is still identifiable.
+ * Prefers {@link EnyoOnboardingV2Guide.name} — it is the handle the author will
+ * search for — then the first translated title, then the start variant, so a
+ * guide with neither a name nor a title is still identifiable.
  *
  * @param guide - The guide to label.
  * @param index - Its position in the answer's `guides` array.
  * @returns A message prefix such as ``guides[2] ("Wallbox über OCPP")``.
  */
 function guideLabel(guide, index) {
+    const name = guide.name?.trim();
+    if (name)
+        return `guides[${index}] ("${name}")`;
     const title = guide.title?.[0]?.value;
     return `guides[${index}] (${title ? `"${title}"` : (guide.startVariant ?? '?')})`;
 }
@@ -116,6 +120,9 @@ export function validateOnboardingV2GuidesResult(result, context) {
     }
     // Which guide(s) claimed each binding, so a collision can name both sides.
     const claimedBy = new Map();
+    // Same, for the explicit `name` handles — a duplicate makes an app unable to
+    // say which of the two it means.
+    const namedBy = new Map();
     for (const [i, guide] of result.guides.entries()) {
         const at = guideLabel(guide, i);
         const guideResult = validateOnboardingGuideV2(guide, context);
@@ -128,6 +135,17 @@ export function validateOnboardingV2GuidesResult(result, context) {
         else if (!guide.modelIds?.length) {
             warnings.push(`${at}: no modelIds — this guide applies to every model of "${guide.vendorId}".`);
         }
+        const name = guide.name?.trim();
+        if (name) {
+            const previouslyNamed = namedBy.get(name);
+            if (previouslyNamed) {
+                errors.push(`${at}: name "${name}" is already used by ${previouslyNamed} — ` +
+                    'a name is how an app addresses one specific guide, so two guides cannot share one.');
+            }
+            else {
+                namedBy.set(name, at);
+            }
+        }
         for (const key of bindingKeys(guide)) {
             const previous = claimedBy.get(key);
             if (previous) {

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

@@ -143,6 +143,7 @@ export function validateOnboardingGuideV2(guide, context) {
     validateNetworkScanFlag(guide, warnings);
     validateApplianceBinding(guide, errors, warnings);
     validateUserNotification(guide, warnings);
+    validateGuideName(guide, errors, warnings);
     return { ok: errors.length === 0, errors, warnings };
 }
 /**
@@ -676,6 +677,37 @@ function validateApplianceBinding(guide, errors, warnings) {
             '` guide binds an existing appliance.');
     }
 }
+/**
+ * Checks {@link EnyoOnboardingV2Guide.name} is usable as a handle.
+ *
+ * The property is optional — a guide that never needs to be addressed does not
+ * need one, and the host falls back to a name derived from the guide's
+ * bindings. But a name that is *present* and blank is worse than absent: it
+ * looks like a handle at the call site and matches nothing, so
+ * `removeOnboardingGuide('')` would silently do nothing. That is an error.
+ *
+ * Whitespace around a name is trimmed by the host before it is compared, so
+ * `" setup "` and `"setup"` are the same handle; a name carrying padding is
+ * only warned about, since it works but will not look like what the author
+ * typed in a log line.
+ *
+ * @param guide - The guide being validated.
+ * @param errors - Collector for blocking problems.
+ * @param warnings - Collector for advisory problems.
+ */
+function validateGuideName(guide, errors, warnings) {
+    if (guide.name === undefined)
+        return;
+    if (typeof guide.name !== 'string' || guide.name.trim() === '') {
+        errors.push('`name` is present but blank — a guide either carries a handle an app can address ' +
+            'it by or omits the property entirely; an empty name matches nothing.');
+        return;
+    }
+    if (guide.name !== guide.name.trim()) {
+        warnings.push(`\`name\` "${guide.name}" has leading or trailing whitespace, which the host trims — ` +
+            'the guide is addressed as `' + guide.name.trim() + '`.');
+    }
+}
 /**
  * Checks {@link EnyoOnboardingV2Guide.notifyUser} against the guide's
  * {@link EnyoOnboardingV2Guide.startVariant}.

package/dist/packages/energy-app-onboarding-v2.d.ts

@@ -1,6 +1,28 @@
 import type { EnyoOnboardingV2GuidesRequest, EnyoOnboardingV2GuidesResult } from '../types/enyo-onboarding-v2-provider.js';
 import type { EnyoOnboardingV2DynamicRequest, EnyoOnboardingV2DynamicResult } from '../types/enyo-onboarding-v2-dynamic.js';
 import type { EnyoOnboardingV2AdditionalSetupRequest, EnyoOnboardingV2AdditionalSetupResult } from '../types/enyo-onboarding-v2-additional-setup.js';
+/**
+ * Which run of a named guide an app means.
+ *
+ * A guide name identifies the *flow*; this narrows it to one walk of that flow
+ * when more than one can be open at a time. A maintenance guide is bound to an
+ * appliance and its runs live in a lane of their own — one per appliance — so
+ * that is the only distinction the host needs.
+ *
+ * Omit it entirely for a guide that has one open run, which is every
+ * installation variant.
+ */
+export interface EnyoOnboardingV2RunSelector {
+    /**
+     * The appliance whose run is meant, for a guide bound to one
+     * ({@link EnyoOnboardingV2StartVariant.Maintenance}).
+     *
+     * Omitted on a maintenance guide, the call addresses that guide's single
+     * open run when there is exactly one and is rejected when there are
+     * several — an ambiguous "complete the run" must not close an arbitrary one.
+     */
+    applianceId?: string;
+}
 /**
  * Handler the host calls to collect every onboarding guide (v2) an app ships.
  *
@@ -196,6 +218,124 @@ export interface EnergyAppOnboardingV2 {
      * @returns Promise that resolves once the host has taken the new answer.
      */
     refreshOnboardingGuides(): Promise<void>;
+    /**
+     * Retires one guide by name, without the app restating its whole set.
+     *
+     * The ordinary way to retire a guide is to leave it out of the next
+     * {@link EnyoOnboardingV2GuidesHandler} answer, and that remains the right
+     * choice when the app's guide set is a static list in its source. This is
+     * for the case that answer cannot express: a guide the app decided to
+     * withdraw *now* — a vendor account was unlinked, an appliance it was bound
+     * to is gone — where waiting for the host's next pull means an installer
+     * can still start a flow the app can no longer serve.
+     *
+     * Names the guide by its {@link EnyoOnboardingV2Guide.name}, so only a
+     * guide that carries one can be retired this way. A guide without a name is
+     * addressable only as part of the complete answer.
+     *
+     * **The handler is still the source of truth.** This drops the guide from
+     * the host's cache; it does not stop the app from offering it again. If the
+     * handler keeps returning the guide, the next pull brings it back — so
+     * remove it from what the handler builds as well, or the retirement lasts
+     * only until the next sync.
+     *
+     * Runs already walking the guide are not touched: a guide is retired for the
+     * *next* installer, and pulling a flow out from under one already inside it
+     * would strand them mid-installation. Use {@link removeOnboardingRun} to end
+     * a run.
+     *
+     * Removing a guide the host does not know — wrong name, already retired — is
+     * a no-op rather than an error.
+     *
+     * This API is available to every app — it is not permission-gated.
+     *
+     * @param name - The {@link EnyoOnboardingV2Guide.name} of the guide to retire.
+     * @returns Promise that resolves once the host has dropped the guide.
+     *
+     * @example
+     * ```typescript
+     * await energyApp.useOnboardingV2().removeOnboardingGuide('vendor-cloud-setup');
+     * ```
+     */
+    removeOnboardingGuide(name: string): Promise<void>;
+    /**
+     * Marks the run walking a named guide as **completed**.
+     *
+     * For the flow that finished somewhere other than on the installer's
+     * screen. A guide normally completes when the walk reaches a success
+     * target — the installer taps through to the end. But an app sometimes
+     * learns the goal was met by another route: the wallbox connected over OCPP
+     * by itself, the vendor cloud confirmed the pairing, the appliance the
+     * maintenance run was servicing reported healthy. Leaving that run open
+     * shows the customer an installation still in progress that nobody intends
+     * to continue.
+     *
+     * The run is closed as a **success**: it leaves the "open" set, stops being
+     * offered for resumption, and counts as a finished installation. Use
+     * {@link removeOnboardingRun} for a flow that ended without achieving
+     * anything — the two are not interchangeable, and reporting an abandoned
+     * setup as completed is how a broken installation looks fine on a dashboard.
+     *
+     * Completing a run that is already finished — completed or removed — is a
+     * no-op: the first outcome stands, and a late confirmation does not reopen
+     * or re-close a run. So is naming a guide with no open run at all.
+     *
+     * Not permission-gated, like the rest of this API: a guide name is resolved
+     * within the calling package, so an app can only reach runs of guides it
+     * ships itself.
+     *
+     * @param name - The {@link EnyoOnboardingV2Guide.name} of the guide whose run
+     *   should be completed.
+     * @param selector - Which run, when the guide can have more than one open.
+     * @returns Promise that resolves once the host has closed the run.
+     *
+     * @example
+     * ```typescript
+     * // The wallbox connected on its own — the installer never reached the last step.
+     * ocpp.onChargePointConnect(async () => {
+     *     await energyApp.useOnboardingV2().completeOnboardingRun('wallbox-ocpp-setup');
+     * });
+     * ```
+     */
+    completeOnboardingRun(name: string, selector?: EnyoOnboardingV2RunSelector): Promise<void>;
+    /**
+     * Ends the run walking a named guide **without** completing it.
+     *
+     * The counterpart to {@link completeOnboardingRun}, for a flow that is over
+     * but achieved nothing: the device it was setting up was removed, the
+     * appliance a maintenance run was servicing no longer exists, the app can no
+     * longer serve the guide the run is walking. The run leaves the open set as
+     * abandoned rather than successful, so it stops being offered for resumption
+     * and is not counted as a finished installation.
+     *
+     * This ends a *run*, not a guide. The guide stays available and a new run
+     * can start on it immediately — that is the point when a stuck run is
+     * blocking a fresh attempt, since a device can have only one open run per
+     * flow. Use {@link removeOnboardingGuide} to withdraw the flow itself.
+     *
+     * An installer may be looking at the run when it is removed. Do this because
+     * the run genuinely cannot continue, not to tidy up: the screen ends the
+     * setup under them, and nothing explains why.
+     *
+     * Removing a run that is already finished, or naming a guide with no open
+     * run, is a no-op.
+     *
+     * Not permission-gated, like the rest of this API: a guide name is resolved
+     * within the calling package, so an app can only reach runs of guides it
+     * ships itself.
+     *
+     * @param name - The {@link EnyoOnboardingV2Guide.name} of the guide whose run
+     *   should be removed.
+     * @param selector - Which run, when the guide can have more than one open.
+     * @returns Promise that resolves once the host has ended the run.
+     *
+     * @example
+     * ```typescript
+     * // The appliance this maintenance flow services was deleted.
+     * await energyApp.useOnboardingV2().removeOnboardingRun('wallbox-service', {applianceId});
+     * ```
+     */
+    removeOnboardingRun(name: string, selector?: EnyoOnboardingV2RunSelector): Promise<void>;
     /**
      * Registers the handler the host calls to resolve dynamic block values
      * (`ocpp-url`, `device-ip`) while a step is rendered.

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

@@ -851,6 +851,35 @@ export interface EnyoOnboardingV2Step {
  * usually bound at registration/publish time and may be omitted here.
  */
 export interface EnyoOnboardingV2Guide {
+    /**
+     * Stable handle for this guide — the name the app calls it by when it wants
+     * to act on it later.
+     *
+     * A guide is normally never addressed: guides are pulled, the app's answer
+     * is the complete set, and a guide is retired by leaving it out. This exists
+     * for the cases where an app has to say something *about one specific
+     * guide* instead of restating the whole set — retiring it with
+     * {@link EnergyAppOnboardingV2.removeOnboardingGuide}, or completing or
+     * removing the run walking it
+     * ({@link EnergyAppOnboardingV2.completeOnboardingRun},
+     * {@link EnergyAppOnboardingV2.removeOnboardingRun}).
+     *
+     * **Stable once shipped, like a step's `name`.** A run in progress is
+     * anchored to it, so renaming a guide between two package versions strands
+     * whatever was paused inside it. Choose a kebab-case slug that describes the
+     * flow rather than the hardware it currently applies to
+     * (`wallbox-ocpp-setup`, not `acme-ac22`), and keep it when the bindings
+     * change.
+     *
+     * Unique within the app's answer — two guides sharing a name cannot be told
+     * apart, and {@link validateOnboardingV2GuidesResult} rejects the answer.
+     *
+     * Optional. Omit it and the host files the guide under a name derived from
+     * what it binds to (vendor, models, start variant, and the appliance on a
+     * maintenance guide) exactly as before — that keeps working, it just cannot
+     * be named by an app that never chose a name.
+     */
+    name?: string;
     /** Translated display title (de/en). */
     title: EnyoOnboardingTranslatedContent[];
     /** Which start situation this guide covers. */

package/dist/version.d.ts

@@ -5,7 +5,7 @@
 /**
  * Current version of the enyo Energy App SDK.
  */
-export declare const SDK_VERSION = "1.1.0";
+export declare const SDK_VERSION = "1.2.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 = '1.1.0';
+export const SDK_VERSION = '1.2.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": "1.1.0",
+  "version": "1.2.0",
   "description": "enyo Energy App SDK",
   "type": "module",
   "main": "dist/index.js",