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

package/README.md

@@ -172,7 +172,8 @@ The SDK exposes several layered building blocks. Pick the one that matches the k
 | Manage electricity tariffs (default tariff, price per kWh) | [`useElectricityTariff()`](#useelectricitytariff-energyappelectricitytariff) |
 | Register a PV system (kWp, DC strings, orientation) | [`usePvSystem()`](#usepvsystem-energyapppvsystem) |
 | Discover capabilities of the active energy manager | [`useEnergyManager()`](#useenergymanager-energyappenergymanager) |
-| Drive a multi-step onboarding flow | [`useOnboarding()`](#useonboarding-energyapponboarding) |
+| Serve your v2 onboarding guides when the host asks for them | [`useOnboardingV2()`](#useonboardingv2-energyapponboardingv2) |
+| Drive a multi-step onboarding flow (v1, deprecated) | [`useOnboarding()`](#useonboarding-energyapponboarding) |
 | Allocate process-local sequential IDs | [`useSequenceGenerator()`](#usesequencegenerator-energyappsequencegenerator) |
 | Manage retries with circuit-breaker semantics | [`RetryManager`](#retry-framework) |
 | Keep an `applianceId` cache in sync with the SDK | [`ApplianceManager`](#appliance-management) |
@@ -1334,8 +1335,36 @@ Requires the `Savings` permission.
 
 ### Operational Utilities
 
+#### `useOnboardingV2(): EnergyAppOnboardingV2`
+
+Serve the onboarding guides your app ships. Guides are **pulled, not published**: you register one handler, and the host calls it with "give me your v2 onboarding guides". You answer with the **complete set** or with **nothing** — there is no save, update or delete, and every answer replaces the host's picture of what your app offers.
+
+```typescript
+await energyApp.useOnboardingV2().registerOnboardingGuidesHandler(async (request) => {
+    const result = { requestId: request.requestId, guides: buildGuides() };
+
+    const { ok, errors } = validateOnboardingV2GuidesResult(result, {
+        files: packageDefinition.files,
+    });
+    if (!ok) {
+        console.error('onboarding guides invalid', errors);
+        return null;   // keep whatever the host already has
+    }
+
+    return result;
+});
+```
+
+`null` and `[]` are **not** the same answer: `[]` says "I genuinely have no guides" and drops the host's cached ones, `null` says "I cannot answer right now" and leaves them alone. Use `null` for transient failures. The host stops waiting after `request.timeoutMs`, so build the guides in memory rather than fetching them.
+
+Each guide must carry the `vendorId`, `modelIds` and `startVariant` it applies to — that is how the host selects one for a run, and there is no publish step left to bind them. See [ONBOARDING.md](./ONBOARDING.md#serving-guides-the-host-pulls-the-app-never-publishes) for the full v2 model.
+
+Not permission-gated.
+
 #### `useOnboarding(): EnergyAppOnboarding`
 
+> **Deprecated** — the v1 model. New guides use the v2 graph model and are served through [`useOnboardingV2()`](#useonboardingv2-energyapponboardingv2).
+
 Drive a multi-step onboarding guide — start / advance / back / skip / cancel, persist responses, and observe step transitions.
 
 ```typescript

package/dist/cjs/energy-app.cjs

@@ -117,6 +117,20 @@ class EnergyApp {
     useOnboarding() {
         return this.energyAppSdk.useOnboarding();
     }
+    /**
+     * Gets the Onboarding v2 API for serving this app's onboarding guides.
+     *
+     * Guides are pulled rather than published: the app registers one handler and
+     * the host calls it with "give me your v2 onboarding guides", receiving the
+     * complete current set or nothing. There is no save, update or delete —
+     * every answer replaces the host's picture of what this app offers.
+     *
+     * Available to every app — this API is not permission-gated.
+     * @returns The Onboarding v2 API instance
+     */
+    useOnboardingV2() {
+        return this.energyAppSdk.useOnboardingV2();
+    }
     /**
      * Gets the Secret Manager API for retrieving secrets from the developer organization.
      * Provides methods to fetch secrets that have been configured in the developer org's secret store.

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

@@ -16,6 +16,7 @@ import { EnergyAppNotification } from "./packages/energy-app-notification.cjs";
 import { EnergyAppSecretManager } from "./packages/energy-app-secret-manager.cjs";
 import { EnergyAppLocation } from "./packages/energy-app-location.cjs";
 import { EnergyAppOnboarding } from "./packages/energy-app-onboarding.cjs";
+import { EnergyAppOnboardingV2 } from "./packages/energy-app-onboarding-v2.cjs";
 import { EnergyAppTimeseries } from "./packages/energy-app-timeseries.cjs";
 import { EnyoPackageChannel } from "./enyo-package-channel.cjs";
 import { EnergyAppEnergyManager } from "./packages/energy-app-energy-manager.cjs";
@@ -99,6 +100,18 @@ export declare class EnergyApp implements EnyoEnergyAppSdk {
     useElectricityPrices(): EnergyAppEnergyPrices;
     useNotification(): EnergyAppNotification;
     useOnboarding(): EnergyAppOnboarding;
+    /**
+     * Gets the Onboarding v2 API for serving this app's onboarding guides.
+     *
+     * Guides are pulled rather than published: the app registers one handler and
+     * the host calls it with "give me your v2 onboarding guides", receiving the
+     * complete current set or nothing. There is no save, update or delete —
+     * every answer replaces the host's picture of what this app offers.
+     *
+     * Available to every app — this API is not permission-gated.
+     * @returns The Onboarding v2 API instance
+     */
+    useOnboardingV2(): EnergyAppOnboardingV2;
     /**
      * Gets the Secret Manager API for retrieving secrets from the developer organization.
      * Provides methods to fetch secrets that have been configured in the developer org's secret store.

package/dist/cjs/enyo-energy-app-sdk.d.cts

@@ -15,6 +15,7 @@ import { EnergyAppNotification } from "./packages/energy-app-notification.cjs";
 import { EnergyAppSecretManager } from "./packages/energy-app-secret-manager.cjs";
 import { EnergyAppLocation } from "./packages/energy-app-location.cjs";
 import { EnergyAppOnboarding } from "./packages/energy-app-onboarding.cjs";
+import { EnergyAppOnboardingV2 } from "./packages/energy-app-onboarding-v2.cjs";
 import { EnergyAppTimeseries } from "./packages/energy-app-timeseries.cjs";
 import { EnyoPackageChannel } from "./enyo-package-channel.cjs";
 import { EnergyAppEnergyManager } from "./packages/energy-app-energy-manager.cjs";
@@ -106,6 +107,8 @@ export interface EnyoEnergyAppSdk {
     useLocation: () => EnergyAppLocation;
     /** Get the Onboarding API */
     useOnboarding: () => EnergyAppOnboarding;
+    /** Get the Onboarding v2 API for registering the handler the host calls to collect this app's onboarding guides */
+    useOnboardingV2: () => EnergyAppOnboardingV2;
     /** Get the Timeseries API for querying historical energy data */
     useTimeseries: () => EnergyAppTimeseries;
     /** Get the Energy Manager API for retrieving energy manager info and capabilities */

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

@@ -0,0 +1,167 @@
+"use strict";
+/**
+ * Client-side validation for an {@link EnyoOnboardingV2GuidesResult} — the whole
+ * answer an app hands back when the host asks for its v2 onboarding guides.
+ *
+ * {@link validateOnboardingGuideV2} checks one guide's graph. This checks the
+ * *set*: that every guide in it is publishable, that each one says which
+ * vendor/model/start-variant it applies to, and that no two of them claim the
+ * same one. Those last two only become checkable here, because a guide is now
+ * selected out of an app's own answer rather than bound to a catalog entry at
+ * publish time — a guide with no binding can never be chosen for a device, and
+ * two guides with the same binding leave the host with no way to pick.
+ *
+ * `errors` mean the answer is not fit to return; `warnings` are advisory. Use
+ * {@link validateOnboardingV2GuidesResult} for the non-throwing result, or
+ * {@link assertValidOnboardingV2GuidesResult} to throw.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OnboardingV2GuidesValidationError = void 0;
+exports.validateOnboardingV2GuidesResult = validateOnboardingV2GuidesResult;
+exports.assertValidOnboardingV2GuidesResult = assertValidOnboardingV2GuidesResult;
+const onboarding_v2_validators_js_1 = require("./onboarding-v2-validators.cjs");
+/**
+ * Thrown by {@link assertValidOnboardingV2GuidesResult} when an answer fails
+ * validation. The message lists every blocking error so callers can surface
+ * them directly.
+ */
+class OnboardingV2GuidesValidationError extends Error {
+    /** The individual blocking errors that caused the failure. */
+    errors;
+    /**
+     * @param errors - The blocking validation errors.
+     */
+    constructor(errors) {
+        super(`Invalid onboarding guides result (v2):\n- ${errors.join('\n- ')}`);
+        this.name = 'OnboardingV2GuidesValidationError';
+        this.errors = errors;
+    }
+}
+exports.OnboardingV2GuidesValidationError = OnboardingV2GuidesValidationError;
+/**
+ * Placeholder used in a binding key for a guide that names no model — it applies
+ * to every model of its vendor, and therefore collides with any other such guide
+ * for the same vendor and start variant.
+ */
+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.
+ *
+ * @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 title = guide.title?.[0]?.value;
+    return `guides[${index}] (${title ? `"${title}"` : (guide.startVariant ?? '?')})`;
+}
+/**
+ * Every (vendor, model, start variant) binding a guide claims.
+ *
+ * A guide with several `modelIds` claims one binding per model, so two guides
+ * that overlap on a single model collide even when the rest of their model lists
+ * differ.
+ *
+ * @param guide - The guide to derive bindings for.
+ * @returns The binding keys, or an empty array when the guide names no vendor.
+ */
+function bindingKeys(guide) {
+    if (!guide.vendorId)
+        return [];
+    const models = guide.modelIds?.length ? guide.modelIds : [ANY_MODEL];
+    return models.map((modelId) => `${guide.vendorId}|${modelId}|${guide.startVariant}`);
+}
+/**
+ * Validates a complete guides answer: the envelope, every guide in it, and the
+ * bindings across them.
+ *
+ * Each guide is run through {@link validateOnboardingGuideV2}, and its errors
+ * and warnings are surfaced here prefixed with the guide's position — pass the
+ * declaring package's `files` in `context` to have image references resolved
+ * rather than merely reported.
+ *
+ * An empty `guides` array is valid but warned about: it is the deliberate
+ * statement "I have no guides, drop the ones you cached". An app that meant
+ * "I cannot answer right now" must resolve its handler with `null` instead.
+ *
+ * @param result - The answer the handler is about to return.
+ * @param context - Optional {@link OnboardingV2ValidationContext} every guide is
+ *   checked against.
+ * @returns The {@link OnboardingV2GuidesValidationResult}.
+ *
+ * @example
+ * ```typescript
+ * const result = {requestId: request.requestId, guides: buildGuides()};
+ * const {ok, errors, warnings} = validateOnboardingV2GuidesResult(result, {
+ *     files: packageDefinition.files,
+ * });
+ * if (!ok) {
+ *     console.error('onboarding guides invalid', errors);
+ *     return null;
+ * }
+ * warnings.forEach((w) => console.warn('onboarding guides:', w));
+ * return result;
+ * ```
+ */
+function validateOnboardingV2GuidesResult(result, context) {
+    const errors = [];
+    const warnings = [];
+    if (!result?.requestId) {
+        errors.push('`requestId` is required and must echo the request.');
+    }
+    if (!Array.isArray(result?.guides)) {
+        errors.push('`guides` must be an array — resolve the handler with `null` to answer "nothing".');
+        return { ok: false, errors, warnings };
+    }
+    if (result.guides.length === 0) {
+        warnings.push('Empty `guides` retires every guide the host cached for this app. ' +
+            'Resolve the handler with `null` instead if the intent was "no answer right now".');
+    }
+    // Which guide(s) claimed each binding, so a collision can name both sides.
+    const claimedBy = 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);
+        errors.push(...guideResult.errors.map((e) => `${at}: ${e}`));
+        warnings.push(...guideResult.warnings.map((w) => `${at}: ${w}`));
+        if (!guide.vendorId) {
+            warnings.push(`${at}: no vendorId — the host matches a run by vendor, model and start variant, ` +
+                'so an unbound guide can never be selected.');
+        }
+        else if (!guide.modelIds?.length) {
+            warnings.push(`${at}: no modelIds — this guide applies to every model of "${guide.vendorId}".`);
+        }
+        for (const key of bindingKeys(guide)) {
+            const previous = claimedBy.get(key);
+            if (previous) {
+                errors.push(`${at}: binding "${key}" is already claimed by ${previous} — ` +
+                    'the host cannot choose between two guides for the same vendor, model and start variant.');
+            }
+            else {
+                claimedBy.set(key, at);
+            }
+        }
+    }
+    return { ok: errors.length === 0, errors, warnings };
+}
+/**
+ * Like {@link validateOnboardingV2GuidesResult}, but throws
+ * {@link OnboardingV2GuidesValidationError} when there are blocking errors.
+ * Warnings never throw; the validated answer is returned on success for
+ * chaining.
+ *
+ * @param result - The answer the handler is about to return.
+ * @param context - Optional {@link OnboardingV2ValidationContext}, as for
+ *   {@link validateOnboardingV2GuidesResult}.
+ * @returns The same answer when it has no blocking errors.
+ * @throws {OnboardingV2GuidesValidationError} When validation produces any error.
+ */
+function assertValidOnboardingV2GuidesResult(result, context) {
+    const { ok, errors } = validateOnboardingV2GuidesResult(result, context);
+    if (!ok)
+        throw new OnboardingV2GuidesValidationError(errors);
+    return result;
+}

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

@@ -0,0 +1,86 @@
+/**
+ * Client-side validation for an {@link EnyoOnboardingV2GuidesResult} — the whole
+ * answer an app hands back when the host asks for its v2 onboarding guides.
+ *
+ * {@link validateOnboardingGuideV2} checks one guide's graph. This checks the
+ * *set*: that every guide in it is publishable, that each one says which
+ * vendor/model/start-variant it applies to, and that no two of them claim the
+ * same one. Those last two only become checkable here, because a guide is now
+ * selected out of an app's own answer rather than bound to a catalog entry at
+ * publish time — a guide with no binding can never be chosen for a device, and
+ * two guides with the same binding leave the host with no way to pick.
+ *
+ * `errors` mean the answer is not fit to return; `warnings` are advisory. Use
+ * {@link validateOnboardingV2GuidesResult} for the non-throwing result, or
+ * {@link assertValidOnboardingV2GuidesResult} to throw.
+ */
+import type { OnboardingV2ValidationContext } from './onboarding-v2-validators.cjs';
+import type { EnyoOnboardingV2GuidesResult } from '../../types/enyo-onboarding-v2-provider.cjs';
+/**
+ * Thrown by {@link assertValidOnboardingV2GuidesResult} when an answer fails
+ * validation. The message lists every blocking error so callers can surface
+ * them directly.
+ */
+export declare class OnboardingV2GuidesValidationError extends Error {
+    /** The individual blocking errors that caused the failure. */
+    readonly errors: string[];
+    /**
+     * @param errors - The blocking validation errors.
+     */
+    constructor(errors: string[]);
+}
+/** The outcome of validating an {@link EnyoOnboardingV2GuidesResult}. */
+export interface OnboardingV2GuidesValidationResult {
+    /** True when there are no blocking `errors` (warnings are still allowed). */
+    ok: boolean;
+    /** Blocking problems — the answer should not be returned to the host. */
+    errors: string[];
+    /** Advisory problems — allowed, but usually worth fixing. */
+    warnings: string[];
+}
+/**
+ * Validates a complete guides answer: the envelope, every guide in it, and the
+ * bindings across them.
+ *
+ * Each guide is run through {@link validateOnboardingGuideV2}, and its errors
+ * and warnings are surfaced here prefixed with the guide's position — pass the
+ * declaring package's `files` in `context` to have image references resolved
+ * rather than merely reported.
+ *
+ * An empty `guides` array is valid but warned about: it is the deliberate
+ * statement "I have no guides, drop the ones you cached". An app that meant
+ * "I cannot answer right now" must resolve its handler with `null` instead.
+ *
+ * @param result - The answer the handler is about to return.
+ * @param context - Optional {@link OnboardingV2ValidationContext} every guide is
+ *   checked against.
+ * @returns The {@link OnboardingV2GuidesValidationResult}.
+ *
+ * @example
+ * ```typescript
+ * const result = {requestId: request.requestId, guides: buildGuides()};
+ * const {ok, errors, warnings} = validateOnboardingV2GuidesResult(result, {
+ *     files: packageDefinition.files,
+ * });
+ * if (!ok) {
+ *     console.error('onboarding guides invalid', errors);
+ *     return null;
+ * }
+ * warnings.forEach((w) => console.warn('onboarding guides:', w));
+ * return result;
+ * ```
+ */
+export declare function validateOnboardingV2GuidesResult(result: EnyoOnboardingV2GuidesResult, context?: OnboardingV2ValidationContext): OnboardingV2GuidesValidationResult;
+/**
+ * Like {@link validateOnboardingV2GuidesResult}, but throws
+ * {@link OnboardingV2GuidesValidationError} when there are blocking errors.
+ * Warnings never throw; the validated answer is returned on success for
+ * chaining.
+ *
+ * @param result - The answer the handler is about to return.
+ * @param context - Optional {@link OnboardingV2ValidationContext}, as for
+ *   {@link validateOnboardingV2GuidesResult}.
+ * @returns The same answer when it has no blocking errors.
+ * @throws {OnboardingV2GuidesValidationError} When validation produces any error.
+ */
+export declare function assertValidOnboardingV2GuidesResult(result: EnyoOnboardingV2GuidesResult, context?: OnboardingV2ValidationContext): EnyoOnboardingV2GuidesResult;

package/dist/cjs/index.cjs

@@ -93,6 +93,9 @@ __exportStar(require("./packages/energy-app-onboarding.cjs"), exports);
 __exportStar(require("./types/enyo-onboarding-v2.cjs"), exports);
 __exportStar(require("./implementations/onboarding-v2/define-onboarding-guide-v2.cjs"), exports);
 __exportStar(require("./implementations/onboarding-v2/onboarding-v2-validators.cjs"), exports);
+__exportStar(require("./types/enyo-onboarding-v2-provider.cjs"), exports);
+__exportStar(require("./packages/energy-app-onboarding-v2.cjs"), exports);
+__exportStar(require("./implementations/onboarding-v2/onboarding-v2-provider-validators.cjs"), exports);
 __exportStar(require("./implementations/files/define-public-file.cjs"), exports);
 __exportStar(require("./implementations/files/public-file-validators.cjs"), exports);
 __exportStar(require("./types/enyo-retry-manager.cjs"), exports);

package/dist/cjs/index.d.cts

@@ -77,6 +77,9 @@ export * from './packages/energy-app-onboarding.cjs';
 export * from './types/enyo-onboarding-v2.cjs';
 export * from './implementations/onboarding-v2/define-onboarding-guide-v2.cjs';
 export * from './implementations/onboarding-v2/onboarding-v2-validators.cjs';
+export * from './types/enyo-onboarding-v2-provider.cjs';
+export * from './packages/energy-app-onboarding-v2.cjs';
+export * from './implementations/onboarding-v2/onboarding-v2-provider-validators.cjs';
 export * from './implementations/files/define-public-file.cjs';
 export * from './implementations/files/public-file-validators.cjs';
 export * from './types/enyo-retry-manager.cjs';

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

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1,128 @@
+import type { EnyoOnboardingV2GuidesRequest, EnyoOnboardingV2GuidesResult } from '../types/enyo-onboarding-v2-provider.cjs';
+/**
+ * Handler the host calls to collect every onboarding guide (v2) an app ships.
+ *
+ * The handler builds the guides and resolves — that promise is the whole
+ * protocol. There is no per-guide save, update or delete call: each invocation
+ * returns the app's *complete* current set, and the host replaces what it knew
+ * with the answer. A guide is retired by leaving it out of the array.
+ *
+ * Answer from memory. The host owns the clock and stops waiting after
+ * {@link EnyoOnboardingV2GuidesRequest.timeoutMs}, and an abandoned handler is
+ * never told, so a handler that fetches guides over the network on every call
+ * will eventually be the reason an installer sees no guide.
+ *
+ * **`null` is not the same as an empty array.** Resolve with `null` (or reject)
+ * to say "I am not answering right now" — the host keeps whatever it cached.
+ * Resolve with an empty `guides` array to say "I genuinely have no guides" —
+ * the host drops the ones it cached. Use `null` for the transient case, never
+ * an empty array.
+ *
+ * Registering a handler requires no permission.
+ *
+ * @param request - Who is asking, the correlation id, and the time budget.
+ * @returns A promise resolving to the app's complete guide set, or `null` to
+ *   leave the host's cached guides untouched.
+ */
+export type EnyoOnboardingV2GuidesHandler = (request: EnyoOnboardingV2GuidesRequest) => Promise<EnyoOnboardingV2GuidesResult | null>;
+/**
+ * Interface for answering the host's "give me your v2 onboarding guides"
+ * question.
+ *
+ * Guides are **pulled, not pushed**. The app registers one handler here and the
+ * host calls it — when the package is installed or updated, when it syncs its
+ * catalog, and when an installer starts a run. The app never publishes a guide
+ * and never deletes one: it simply answers with whatever set it currently
+ * offers, and the host's picture is replaced by that answer.
+ *
+ * That inversion is the point. A guide lives in the app's source next to the
+ * code it describes, so shipping a new package version ships the corrected
+ * guide with it — there is no separate publish step to forget and no stored
+ * copy to drift out of date. It also lets the guide set be *computed*: an app
+ * can return a different variant depending on which firmware it supports, or
+ * omit a guide for hardware it no longer handles, without any host-side
+ * bookkeeping.
+ *
+ * Author the guides with `defineOnboardingGuideV2()` and check them with
+ * `validateOnboardingV2GuidesResult()` before returning — a guide with blocking
+ * errors is dropped by the host, and dropped silently is the worst way to find
+ * out.
+ *
+ * This API is available to every app — it is not permission-gated.
+ *
+ * @example
+ * ```typescript
+ * const guides = [
+ *     defineOnboardingGuideV2({
+ *         title: t('Wallbox über OCPP', 'Wallbox via OCPP'),
+ *         startVariant: EnyoOnboardingV2StartVariant.ManualSetup,
+ *         requiresNetworkScan: false,
+ *         startStepId: 'enter-url',
+ *         steps: [ ... ],
+ *         vendorId: 'acme',
+ *         modelIds: ['ac22'],
+ *     }),
+ * ];
+ *
+ * energyApp.useOnboardingV2().registerOnboardingGuidesHandler(async (request) => {
+ *     const result = {requestId: request.requestId, guides};
+ *     const {ok, errors} = validateOnboardingV2GuidesResult(result, {
+ *         files: packageDefinition.files,
+ *     });
+ *     if (!ok) {
+ *         console.error('onboarding guides invalid', errors);
+ *         return null;   // keep whatever the host already has
+ *     }
+ *     return result;
+ * });
+ * ```
+ */
+export interface EnergyAppOnboardingV2 {
+    /**
+     * Registers the handler the host calls to collect this app's v2 onboarding
+     * guides.
+     *
+     * One handler per package: registering again replaces the previous one, so a
+     * hot-reloading app does not accumulate stale handlers. Register during
+     * startup — a request that arrives before registration is answered as
+     * *nothing*, which leaves the host's cached guides in place but means a
+     * freshly installed app offers no guide until it registers.
+     *
+     * @param handler - Callback invoked once per guide request.
+     * @returns Promise that resolves once the handler is registered with the host.
+     *
+     * @example
+     * ```typescript
+     * const onboarding = energyApp.useOnboardingV2();
+     * await onboarding.registerOnboardingGuidesHandler(async (request) => ({
+     *     requestId: request.requestId,
+     *     guides: buildGuides(),
+     * }));
+     * ```
+     */
+    registerOnboardingGuidesHandler(handler: EnyoOnboardingV2GuidesHandler): Promise<void>;
+    /**
+     * Removes the registered handler.
+     *
+     * After deregistration the host no longer asks this package for guides. Its
+     * cached guides are left as they were — deregistering is not a way to retire
+     * them; return an empty `guides` array for that. If no handler is registered
+     * this operation is a no-op.
+     *
+     * @returns Promise that resolves once the handler has been removed.
+     */
+    deregisterOnboardingGuidesHandler(): Promise<void>;
+    /**
+     * Asks the host to call the registered handler again now, instead of waiting
+     * for its next sync.
+     *
+     * For the case where the app's guide set changed after startup — a firmware
+     * capability was discovered, a vendor account was linked — and the app wants
+     * the host's picture updated without a restart. It is a request to re-pull,
+     * not a push: the host still calls the handler, and the handler still
+     * returns the complete set.
+     *
+     * @returns Promise that resolves once the host has taken the new answer.
+     */
+    refreshOnboardingGuides(): Promise<void>;
+}

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

@@ -6,10 +6,15 @@ import { EnyoOnboardingGuide, EnyoOnboardingGuideCategory, EnyoOnboardingStep, E
  * Supports multiple parallel guides identified by their unique guideName.
  *
  * @deprecated This runtime surface operates on the v1 {@link EnyoOnboardingGuide}
- * model. New guides should be authored with the v2 graph model
- * ({@link EnyoOnboardingV2Guide} / `defineOnboardingGuideV2()`); a v2 runtime
- * method (`saveOnboardingGuideV2`) will be added in a follow-up task. v1 remains
- * supported for backward compatibility.
+ * model, and on the push lifecycle that goes with it — the app saves, updates and
+ * removes guides, and the host stores a copy that can drift.
+ *
+ * New guides are authored with the v2 graph model
+ * ({@link EnyoOnboardingV2Guide} / `defineOnboardingGuideV2()`) and served
+ * through {@link EnergyAppOnboardingV2}, which inverts the direction: the app
+ * registers one handler and the host calls it for the complete set. There is
+ * deliberately no `saveOnboardingGuideV2` — nothing to publish, nothing to keep
+ * in sync. v1 remains supported for backward compatibility.
  */
 export interface EnergyAppOnboarding {
     /**
@@ -30,8 +35,10 @@ export interface EnergyAppOnboarding {
      * });
      * ```
      *
-     * @deprecated Saves a v1 {@link EnyoOnboardingGuide}. A v2 equivalent
-     * (`saveOnboardingGuideV2`) accepting {@link EnyoOnboardingV2Guide} is planned.
+     * @deprecated Saves a v1 {@link EnyoOnboardingGuide}. v2 guides are not saved
+     * at all — register a handler with
+     * {@link EnergyAppOnboardingV2.registerOnboardingGuidesHandler} and return
+     * them when the host asks.
      */
     saveOnboardingGuide(guide: EnyoOnboardingGuide): Promise<void>;
     /**

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

@@ -0,0 +1,51 @@
+"use strict";
+/**
+ * Onboarding guide **v2 provisioning** — the host asking an energy app to hand
+ * over the guides it ships.
+ *
+ * This inverts how guides used to reach enyo. Previously an app *pushed* its
+ * guides out (the v1 {@link EnergyAppOnboarding.saveOnboardingGuide} surface,
+ * and the guide editor's create/update calls): the app decided when to publish,
+ * the host stored a copy, and the two could drift — a guide fixed in the app's
+ * source stayed stale on the host until someone remembered to re-publish it.
+ *
+ * The v2 model *pulls* instead. The app registers one handler
+ * ({@link EnyoOnboardingV2GuidesHandler}) and the host calls it with
+ * "give me your v2 onboarding guides". The app answers with **all** of them or
+ * with **nothing** — there is no partial answer and no per-guide lifecycle to
+ * keep in sync, because every call replaces the host's whole picture of what
+ * this app offers. Deleting a guide is deleting it from the returned array.
+ *
+ * The app is the single source of truth; the host caches at most a snapshot of
+ * the last answer.
+ *
+ * Pure type declarations (no runtime logic). Register the handler through
+ * {@link EnergyAppOnboardingV2} (`../packages/energy-app-onboarding-v2.ts`) and
+ * check an answer before returning it with `validateOnboardingV2GuidesResult()`
+ * (`../implementations/onboarding-v2/onboarding-v2-provider-validators.ts`).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EnyoOnboardingV2GuidesOriginEnum = void 0;
+/**
+ * Who asked for the guides. One handler serves every caller, so an app builds
+ * its guides once; this field exists so an app can tell a routine catalog
+ * refresh apart from a request made while an installer is standing in front of
+ * a device.
+ */
+var EnyoOnboardingV2GuidesOriginEnum;
+(function (EnyoOnboardingV2GuidesOriginEnum) {
+    /**
+     * The host is refreshing its catalog of what this app offers — on install,
+     * on update, or on a periodic sync. Not time-critical, and nobody is
+     * waiting on a screen.
+     */
+    EnyoOnboardingV2GuidesOriginEnum["CatalogSync"] = "catalog-sync";
+    /**
+     * An installer is starting an onboarding run and the host needs the current
+     * guide for the device in front of them. Answer fast: this call is on the
+     * critical path of a screen.
+     */
+    EnyoOnboardingV2GuidesOriginEnum["OnboardingStart"] = "onboarding-start";
+    /** A user or support agent explicitly asked the host to re-read the guides. */
+    EnyoOnboardingV2GuidesOriginEnum["UserRequest"] = "user-request";
+})(EnyoOnboardingV2GuidesOriginEnum || (exports.EnyoOnboardingV2GuidesOriginEnum = EnyoOnboardingV2GuidesOriginEnum = {}));