@enyo-energy/energy-app-sdk 0.0.191 → 0.0.193

package/README.md

@@ -757,18 +757,33 @@ the update callback cheap.
 
 #### `useChargingCard(): EnergyAppChargingCard`
 
-Handle charging authentication:
+Read registered charging cards and pair new RFID cards:
 
 ```typescript
 const chargingCards = energyApp.useChargingCard();
 
-// Validate charging card
-const isValid = await chargingCards.validateCard('RFID-12345');
+// List all registered charging cards
+const cards = await chargingCards.list();
 
-// Get card information
-const cardInfo = await chargingCards.getCardInfo('RFID-12345');
+// Get a single card
+const card = await chargingCards.getById('card-id');
+
+// Handle pairing requests coming from the app
+const listenerId = chargingCards.listenForPairingStarted(async (request) => {
+    // Put the reader into pairing mode and wait for a card to be presented.
+    // Resolve with the RFID read from the card - the host assigns it to
+    // request.chargingCardId and clears its pendingRegistration flag.
+    return await charger.enterPairingMode(request.applianceId, request.timeoutMs);
+});
+
+chargingCards.removeListener(listenerId);
 ```
 
+Reject the promise returned by the pairing listener when no card was presented or
+the charger refused to enter pairing mode - the host then reports the attempt as
+failed and leaves the card pending. A package managing several chargers should
+check `request.applianceId` and reject requests for appliances it does not own.
+
 ### User Features
 
 #### `useAuthentication(): EnergyAppAuthentication`

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

@@ -133,6 +133,52 @@ exports.onboardingV2Block = {
         outcomes,
         deviceSelection,
     }),
+    /**
+     * An OCPP-connect action block: wait for the charger to dial into enyo's
+     * CSMS after the installer has entered the dynamic OCPP URL in it.
+     *
+     * A convenience wrapper over {@link onboardingV2Block.action} that pins the
+     * action kind. Nothing is searched — an OCPP wallbox is never on the LAN, so
+     * {@link EnyoOnboardingV2ActionKind.NetworkScan} is not a substitute. Pair it
+     * with an {@link onboardingV2Block.dynamic} `ocpp-url` block on the same or a
+     * preceding step.
+     *
+     * Outcome `value`s must be {@link EnyoOnboardingV2OcppConnectOutcome} members
+     * and both must be wired — the validator enforces that, since a charger that
+     * never calls home is the common case.
+     *
+     * @param id - Stable block id, unique within the guide.
+     * @param label - Translated trigger button text (de/en).
+     * @param outcomes - The `connected` / `timeout` results; each is a routing handle.
+     */
+    ocppConnect: (id, label, outcomes) => ({
+        id,
+        type: enyo_onboarding_v2_js_1.EnyoOnboardingV2BlockType.Action,
+        action: enyo_onboarding_v2_js_1.EnyoOnboardingV2ActionKind.OcppConnect,
+        label,
+        outcomes,
+    }),
+    /**
+     * An auth block: the installer signs into the energy app's own account
+     * system (OAuth / vendor portal).
+     *
+     * Exactly one routing handle, and it means "the login succeeded". The server
+     * decides when it fires, so the installer cannot skip it; there is no failure
+     * branch to author — a failed attempt simply keeps them on the step. Route
+     * the handle with {@link onOutcomeV2}, passing `outcome.id`.
+     *
+     * @param id - Stable block id, unique within the guide.
+     * @param label - Translated sign-in button text (de/en).
+     * @param outcome - The single success handle (`{id, label}`).
+     * @param opts - Optional translated `help` naming the account that is needed.
+     */
+    auth: (id, label, outcome, opts) => ({
+        id,
+        type: enyo_onboarding_v2_js_1.EnyoOnboardingV2BlockType.Auth,
+        label,
+        outcome,
+        help: opts?.help,
+    }),
     /**
      * A link block: a fixed URL the installer opens or copies.
      *
@@ -191,14 +237,40 @@ exports.onboardingV2Target = {
     step: (stepId) => ({ type: enyo_onboarding_v2_js_1.EnyoOnboardingV2TargetType.Step, stepId }),
     /** Exit: onboarding succeeded (hand back to the app). */
     success: () => ({ type: enyo_onboarding_v2_js_1.EnyoOnboardingV2TargetType.Success }),
-    /** Exit: escalate to enyo support. */
-    support: () => ({ type: enyo_onboarding_v2_js_1.EnyoOnboardingV2TargetType.Support }),
+    /**
+     * Exit: escalate to enyo support.
+     * @param reason - Optional short internal key describing what failed, e.g.
+     * `firmware-too-old`. Never shown to the installer; it travels with the
+     * hand-off so support knows why it arrived.
+     */
+    support: (reason) => ({
+        type: enyo_onboarding_v2_js_1.EnyoOnboardingV2TargetType.Support,
+        reason,
+    }),
     /**
      * Exit: pause the run (resumable) with a reason.
+     *
+     * For {@link EnyoOnboardingV2PauseReason.EnyoTodo} prefer
+     * {@link onboardingV2Target.enyoTakeover} — that reason is a terminal
+     * hand-off, not a park, and `resumeStepName` does not apply to it.
+     *
      * @param reason - Why the run is parked.
      * @param resumeStepName - Optional step `name` to resume at.
      */
     pause: (reason, resumeStepName) => ({ type: enyo_onboarding_v2_js_1.EnyoOnboardingV2TargetType.Pause, reason, resumeStepName }),
+    /**
+     * Exit: **enyo übernimmt** — the installer is done and enyo finishes the
+     * setup. A terminal exit alongside `success` and `support`: the app shows the
+     * takeover screen rather than returning to the cockpit.
+     *
+     * Emits the unchanged wire shape (`pause` with reason `enyo-todo`), and
+     * counts as a completing exit for {@link validateOnboardingGuideV2} — a guide
+     * that only ends here needs no `success` branch.
+     */
+    enyoTakeover: () => ({
+        type: enyo_onboarding_v2_js_1.EnyoOnboardingV2TargetType.Pause,
+        reason: enyo_onboarding_v2_js_1.EnyoOnboardingV2PauseReason.EnyoTodo,
+    }),
     /**
      * Jump into another start variant's flow for the same vendor/model.
      * @param variant - The start variant to hand off to.

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

@@ -10,8 +10,8 @@
  * before publishing.
  */
 import type { EnyoOnboardingTranslatedContent } from '../../types/enyo-onboarding.cjs';
-import { EnyoOnboardingV2ActionKind, EnyoOnboardingV2ChoiceLayout, EnyoOnboardingV2DeviceSelection } from '../../types/enyo-onboarding-v2.cjs';
-import type { EnyoOnboardingV2ActionOutcome, EnyoOnboardingV2Block, EnyoOnboardingV2ChoiceOption, EnyoOnboardingV2DynamicKind, EnyoOnboardingV2Guide, EnyoOnboardingV2HintVariant, EnyoOnboardingV2InputOutcome, EnyoOnboardingV2InputValueType, EnyoOnboardingV2PauseReason, EnyoOnboardingV2StartVariant, EnyoOnboardingV2Target, EnyoOnboardingV2Transition } from '../../types/enyo-onboarding-v2.cjs';
+import { EnyoOnboardingV2ActionKind, EnyoOnboardingV2ChoiceLayout, EnyoOnboardingV2DeviceSelection, EnyoOnboardingV2PauseReason } from '../../types/enyo-onboarding-v2.cjs';
+import type { EnyoOnboardingV2ActionOutcome, EnyoOnboardingV2AuthOutcome, 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
  * (mirrors `defineEnergyAppPackage`). Prefer this over a bare object literal so
@@ -98,6 +98,42 @@ export declare const onboardingV2Block: {
      * @param deviceSelection - Which devices to test (defaults to `Detected`).
      */
     deviceTest: (id: string, label: EnyoOnboardingTranslatedContent[], outcomes: EnyoOnboardingV2ActionOutcome[], deviceSelection?: EnyoOnboardingV2DeviceSelection) => EnyoOnboardingV2Block;
+    /**
+     * An OCPP-connect action block: wait for the charger to dial into enyo's
+     * CSMS after the installer has entered the dynamic OCPP URL in it.
+     *
+     * A convenience wrapper over {@link onboardingV2Block.action} that pins the
+     * action kind. Nothing is searched — an OCPP wallbox is never on the LAN, so
+     * {@link EnyoOnboardingV2ActionKind.NetworkScan} is not a substitute. Pair it
+     * with an {@link onboardingV2Block.dynamic} `ocpp-url` block on the same or a
+     * preceding step.
+     *
+     * Outcome `value`s must be {@link EnyoOnboardingV2OcppConnectOutcome} members
+     * and both must be wired — the validator enforces that, since a charger that
+     * never calls home is the common case.
+     *
+     * @param id - Stable block id, unique within the guide.
+     * @param label - Translated trigger button text (de/en).
+     * @param outcomes - The `connected` / `timeout` results; each is a routing handle.
+     */
+    ocppConnect: (id: string, label: EnyoOnboardingTranslatedContent[], outcomes: EnyoOnboardingV2ActionOutcome[]) => EnyoOnboardingV2Block;
+    /**
+     * An auth block: the installer signs into the energy app's own account
+     * system (OAuth / vendor portal).
+     *
+     * Exactly one routing handle, and it means "the login succeeded". The server
+     * decides when it fires, so the installer cannot skip it; there is no failure
+     * branch to author — a failed attempt simply keeps them on the step. Route
+     * the handle with {@link onOutcomeV2}, passing `outcome.id`.
+     *
+     * @param id - Stable block id, unique within the guide.
+     * @param label - Translated sign-in button text (de/en).
+     * @param outcome - The single success handle (`{id, label}`).
+     * @param opts - Optional translated `help` naming the account that is needed.
+     */
+    auth: (id: string, label: EnyoOnboardingTranslatedContent[], outcome: EnyoOnboardingV2AuthOutcome, opts?: {
+        help?: EnyoOnboardingTranslatedContent[];
+    }) => EnyoOnboardingV2Block;
     /**
      * A link block: a fixed URL the installer opens or copies.
      *
@@ -143,14 +179,34 @@ export declare const onboardingV2Target: {
     step: (stepId: string) => EnyoOnboardingV2Target;
     /** Exit: onboarding succeeded (hand back to the app). */
     success: () => EnyoOnboardingV2Target;
-    /** Exit: escalate to enyo support. */
-    support: () => EnyoOnboardingV2Target;
+    /**
+     * Exit: escalate to enyo support.
+     * @param reason - Optional short internal key describing what failed, e.g.
+     * `firmware-too-old`. Never shown to the installer; it travels with the
+     * hand-off so support knows why it arrived.
+     */
+    support: (reason?: string) => EnyoOnboardingV2Target;
     /**
      * Exit: pause the run (resumable) with a reason.
+     *
+     * For {@link EnyoOnboardingV2PauseReason.EnyoTodo} prefer
+     * {@link onboardingV2Target.enyoTakeover} — that reason is a terminal
+     * hand-off, not a park, and `resumeStepName` does not apply to it.
+     *
      * @param reason - Why the run is parked.
      * @param resumeStepName - Optional step `name` to resume at.
      */
     pause: (reason: EnyoOnboardingV2PauseReason, resumeStepName?: string) => EnyoOnboardingV2Target;
+    /**
+     * Exit: **enyo übernimmt** — the installer is done and enyo finishes the
+     * setup. A terminal exit alongside `success` and `support`: the app shows the
+     * takeover screen rather than returning to the cockpit.
+     *
+     * Emits the unchanged wire shape (`pause` with reason `enyo-todo`), and
+     * counts as a completing exit for {@link validateOnboardingGuideV2} — a guide
+     * that only ends here needs no `success` branch.
+     */
+    enyoTakeover: () => EnyoOnboardingV2Target;
     /**
      * Jump into another start variant's flow for the same vendor/model.
      * @param variant - The start variant to hand off to.

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

@@ -5,8 +5,14 @@
  * energy app can fail fast locally before publishing.
  *
  * `errors` block publishing; `warnings` are advisory (e.g. unreachable step, no
- * path to success). Use {@link validateOnboardingGuideV2} for the non-throwing
- * result, or {@link assertValidOnboardingGuideV2} to throw on the first failure.
+ * path to a completing exit). Use {@link validateOnboardingGuideV2} for the
+ * non-throwing result, or {@link assertValidOnboardingGuideV2} to throw on the
+ * first failure.
+ *
+ * A run completes either through a `success` target **or** through the
+ * "enyo übernimmt" hand-off (`pause` with reason
+ * {@link EnyoOnboardingV2PauseReason.EnyoTodo}) — both count, so a guide that
+ * legitimately ends in a hand-off is not nagged about a missing success path.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OnboardingV2ValidationError = void 0;
@@ -34,8 +40,8 @@ exports.OnboardingV2ValidationError = OnboardingV2ValidationError;
 const SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 /**
  * Structural + plausibility validation of a v2 guide graph. `errors` block
- * publishing; `warnings` are advisory (e.g. unreachable step, no path to
- * success).
+ * publishing; `warnings` are advisory (e.g. unreachable step, no path to a
+ * completing exit — `success` or the `enyo-todo` hand-off).
  *
  * @param guide - The v2 guide to validate.
  * @returns The {@link OnboardingV2ValidationResult}.
@@ -72,11 +78,12 @@ function validateOnboardingGuideV2(guide) {
         validateActionBlocks(step, at, errors, warnings);
         validateLinkBlocks(step, at, errors, warnings);
         validateInputBlocks(step, at, errors, warnings);
+        validateAuthBlocks(step, at, errors, warnings);
     }
     if (!guide.startStepId || !stepIds.has(guide.startStepId)) {
         errors.push('`startStepId` must reference an existing step.');
     }
-    let hasSuccess = false;
+    let hasCompletingExit = false;
     for (const [i, step] of guide.steps.entries()) {
         const at = `steps[${i}] (${step.name})`;
         const required = requiredHandleKeys(step);
@@ -90,14 +97,24 @@ function validateOnboardingGuideV2(guide) {
             wired.add(key);
             const tg = t.target;
             if (tg.type === enyo_onboarding_v2_js_1.EnyoOnboardingV2TargetType.Success)
-                hasSuccess = true;
+                hasCompletingExit = true;
             else if (tg.type === enyo_onboarding_v2_js_1.EnyoOnboardingV2TargetType.Step && !stepIds.has(tg.stepId)) {
                 errors.push(`${at}: transition targets missing step "${tg.stepId}".`);
             }
-            else if (tg.type === enyo_onboarding_v2_js_1.EnyoOnboardingV2TargetType.Pause &&
-                tg.resumeStepName &&
-                !stepNames.has(tg.resumeStepName)) {
-                errors.push(`${at}: pause resumeStepName "${tg.resumeStepName}" is unknown.`);
+            else if (tg.type === enyo_onboarding_v2_js_1.EnyoOnboardingV2TargetType.Pause) {
+                // "enyo übernimmt" is a terminal hand-off, not a park: it completes
+                // the run for the installer, so it satisfies the completion check
+                // and has nothing to resume at.
+                if (tg.reason === enyo_onboarding_v2_js_1.EnyoOnboardingV2PauseReason.EnyoTodo) {
+                    hasCompletingExit = true;
+                    if (tg.resumeStepName) {
+                        warnings.push(`${at}: pause reason "${enyo_onboarding_v2_js_1.EnyoOnboardingV2PauseReason.EnyoTodo}" is a hand-off to enyo, ` +
+                            `not a resumable park — resumeStepName "${tg.resumeStepName}" is ignored.`);
+                    }
+                }
+                else if (tg.resumeStepName && !stepNames.has(tg.resumeStepName)) {
+                    errors.push(`${at}: pause resumeStepName "${tg.resumeStepName}" is unknown.`);
+                }
             }
             else if (tg.type === enyo_onboarding_v2_js_1.EnyoOnboardingV2TargetType.StartVariant &&
                 tg.variant === guide.startVariant) {
@@ -117,8 +134,11 @@ function validateOnboardingGuideV2(guide) {
                 warnings.push(`step "${step.name}" is unreachable from the start.`);
         }
     }
-    if (!hasSuccess)
-        warnings.push('No branch reaches a `success` exit.');
+    if (!hasCompletingExit) {
+        warnings.push('No branch reaches a completing exit — wire a `success` target, or a `pause` with reason ' +
+            `"${enyo_onboarding_v2_js_1.EnyoOnboardingV2PauseReason.EnyoTodo}" when enyo takes the setup over.`);
+    }
+    validateNetworkScanFlag(guide, warnings);
     return { ok: errors.length === 0, errors, warnings };
 }
 /**
@@ -155,6 +175,9 @@ function validateActionBlocks(step, at, errors, warnings) {
             if (block.deviceSelection) {
                 warnings.push(`${at}: block "${block.id}" sets deviceSelection but is not a device-test action; it is ignored.`);
             }
+            if (block.action === enyo_onboarding_v2_js_1.EnyoOnboardingV2ActionKind.OcppConnect) {
+                validateOcppConnectOutcomes(block, at, errors);
+            }
             continue;
         }
         const values = new Set();
@@ -284,6 +307,110 @@ function validateInputBlocks(step, at, errors, warnings) {
         }
     }
 }
+/** Every {@link EnyoOnboardingV2OcppConnectOutcome} value. */
+const OCPP_CONNECT_OUTCOMES = new Set(Object.values(enyo_onboarding_v2_js_1.EnyoOnboardingV2OcppConnectOutcome));
+/**
+ * Validates the outcomes of an {@link EnyoOnboardingV2ActionKind.OcppConnect}
+ * block.
+ *
+ * The block waits for the charger to dial into our CSMS; it can only ever report
+ * that the connection arrived or that it did not, so its outcome `value`s are
+ * closed over {@link EnyoOnboardingV2OcppConnectOutcome}. Both must be wired: a
+ * charger that never calls home — wrong URL typed, no mobile coverage in the
+ * garage — is the *common* case, and a guide without a `timeout` branch strands
+ * the installer on a spinner.
+ *
+ * @param block - The ocpp-connect action block being checked.
+ * @param at - Human-readable location prefix for messages.
+ * @param errors - Collector for blocking problems.
+ */
+function validateOcppConnectOutcomes(block, at, errors) {
+    const values = new Set();
+    for (const outcome of block.outcomes ?? []) {
+        if (!OCPP_CONNECT_OUTCOMES.has(outcome.value)) {
+            errors.push(`${at}: ocpp-connect block "${block.id}" has outcome value "${outcome.value}", which is not an EnyoOnboardingV2OcppConnectOutcome member.`);
+        }
+        else if (values.has(outcome.value)) {
+            errors.push(`${at}: ocpp-connect block "${block.id}" wires outcome value "${outcome.value}" more than once.`);
+        }
+        values.add(outcome.value);
+    }
+    for (const required of OCPP_CONNECT_OUTCOMES) {
+        if (!values.has(required)) {
+            errors.push(`${at}: ocpp-connect block "${block.id}" has no "${required}" outcome; both results must be routed.`);
+        }
+    }
+}
+/**
+ * Validates the auth blocks of a step.
+ *
+ * An auth block has exactly one handle, and the **server** decides when it
+ * fires — there is no failure branch to author, because a failed login keeps the
+ * installer on the step to retry. So the checks are about the handle existing and
+ * being routable at all, and about the step not pretending the login is optional:
+ * a second decision block next to it would offer a way past a gate the client is
+ * not allowed to skip.
+ *
+ * @param step - The step whose blocks are checked.
+ * @param at - Human-readable location prefix for messages.
+ * @param errors - Collector for blocking problems.
+ * @param warnings - Collector for advisory problems.
+ */
+function validateAuthBlocks(step, at, errors, warnings) {
+    const authBlocks = (step.blocks ?? []).filter((b) => b.type === enyo_onboarding_v2_js_1.EnyoOnboardingV2BlockType.Auth);
+    for (const block of authBlocks) {
+        if (!block.label?.length)
+            errors.push(`${at}: auth block "${block.id}" has no label.`);
+        if (!block.outcome?.id) {
+            errors.push(`${at}: auth block "${block.id}" has no outcome id — its success handle cannot be routed.`);
+        }
+        if (!block.outcome?.label?.length) {
+            warnings.push(`${at}: auth block "${block.id}" outcome has no label.`);
+        }
+    }
+    if (authBlocks.length > 1) {
+        errors.push(`${at}: more than one auth block; a step can hold at most one login.`);
+    }
+    if (authBlocks.length === 1) {
+        const others = (step.blocks ?? []).filter((b) => b.type === enyo_onboarding_v2_js_1.EnyoOnboardingV2BlockType.Choice ||
+            b.type === enyo_onboarding_v2_js_1.EnyoOnboardingV2BlockType.Action ||
+            b.type === enyo_onboarding_v2_js_1.EnyoOnboardingV2BlockType.Input);
+        if (others.length) {
+            warnings.push(`${at}: auth block "${authBlocks[0].id}" shares the step with ${others.length} other decision block(s) — ` +
+                'those give the installer a way past a login the server gates.');
+        }
+    }
+}
+/**
+ * Checks {@link EnyoOnboardingV2Guide.requiresNetworkScan} against what the guide
+ * actually does.
+ *
+ * Opting out means "don't search, start here" — right for a device that is never
+ * on the LAN (an OCPP wallbox), wrong if the guide then relies on scan results.
+ * Both mismatches are warnings, not errors: the flag describes the host's
+ * behaviour before the guide runs, and an author may have a reason.
+ *
+ * @param guide - The guide being validated.
+ * @param warnings - Collector for advisory problems.
+ */
+function validateNetworkScanFlag(guide, warnings) {
+    if (guide.requiresNetworkScan !== false)
+        return;
+    const blocks = guide.steps.flatMap((s) => s.blocks ?? []);
+    const scansItself = blocks.some((b) => b.type === enyo_onboarding_v2_js_1.EnyoOnboardingV2BlockType.Action &&
+        b.action === enyo_onboarding_v2_js_1.EnyoOnboardingV2ActionKind.NetworkScan);
+    if (scansItself)
+        return;
+    const dependsOnDetected = blocks.some((b) => b.type === enyo_onboarding_v2_js_1.EnyoOnboardingV2BlockType.Action &&
+        b.action === enyo_onboarding_v2_js_1.EnyoOnboardingV2ActionKind.DeviceTest &&
+        (b.deviceSelection ?? enyo_onboarding_v2_js_1.EnyoOnboardingV2DeviceSelection.Detected) !==
+            enyo_onboarding_v2_js_1.EnyoOnboardingV2DeviceSelection.Current);
+    if (dependsOnDetected) {
+        warnings.push('requiresNetworkScan is false, but a device-test block selects from detected devices — ' +
+            'nothing was scanned, so it has nothing to test. Use deviceSelection "current", or run a ' +
+            'network-scan action inside the guide.');
+    }
+}
 /**
  * The set of routing-handle keys a step must wire exactly once: one per
  * choice option / action outcome / input outcome, or the single `continue`
@@ -303,6 +430,9 @@ function requiredHandleKeys(step) {
             for (const o of b.outcomes)
                 keys.add(`outcome:${b.id}:${o.id}`);
         }
+        else if (b.type === enyo_onboarding_v2_js_1.EnyoOnboardingV2BlockType.Auth && b.outcome?.id) {
+            keys.add(`outcome:${b.id}:${b.outcome.id}`);
+        }
     }
     if (keys.size === 0)
         keys.add('continue');

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

@@ -4,8 +4,14 @@
  * energy app can fail fast locally before publishing.
  *
  * `errors` block publishing; `warnings` are advisory (e.g. unreachable step, no
- * path to success). Use {@link validateOnboardingGuideV2} for the non-throwing
- * result, or {@link assertValidOnboardingGuideV2} to throw on the first failure.
+ * path to a completing exit). Use {@link validateOnboardingGuideV2} for the
+ * non-throwing result, or {@link assertValidOnboardingGuideV2} to throw on the
+ * first failure.
+ *
+ * A run completes either through a `success` target **or** through the
+ * "enyo übernimmt" hand-off (`pause` with reason
+ * {@link EnyoOnboardingV2PauseReason.EnyoTodo}) — both count, so a guide that
+ * legitimately ends in a hand-off is not nagged about a missing success path.
  */
 import type { EnyoOnboardingV2Guide } from '../../types/enyo-onboarding-v2.cjs';
 /**
@@ -31,8 +37,8 @@ export interface OnboardingV2ValidationResult {
 }
 /**
  * Structural + plausibility validation of a v2 guide graph. `errors` block
- * publishing; `warnings` are advisory (e.g. unreachable step, no path to
- * success).
+ * publishing; `warnings` are advisory (e.g. unreachable step, no path to a
+ * completing exit — `success` or the `enyo-todo` hand-off).
  *
  * @param guide - The v2 guide to validate.
  * @returns The {@link OnboardingV2ValidationResult}.

package/dist/cjs/index.cjs

@@ -83,6 +83,8 @@ __exportStar(require("./packages/energy-app-configuration-manager.cjs"), exports
 __exportStar(require("./types/enyo-air-conditioning-appliance.cjs"), exports);
 __exportStar(require("./types/enyo-heating-rod-appliance.cjs"), exports);
 __exportStar(require("./types/enyo-charger-appliance.cjs"), exports);
+__exportStar(require("./types/enyo-charging-card.cjs"), exports);
+__exportStar(require("./packages/energy-app-charging-card.cjs"), exports);
 __exportStar(require("./types/enyo-battery-appliance.cjs"), exports);
 __exportStar(require("./types/enyo-heatpump-appliance.cjs"), exports);
 __exportStar(require("./types/enyo-inverter-appliance.cjs"), exports);

package/dist/cjs/index.d.cts

@@ -67,6 +67,8 @@ export * from './packages/energy-app-configuration-manager.cjs';
 export * from './types/enyo-air-conditioning-appliance.cjs';
 export * from './types/enyo-heating-rod-appliance.cjs';
 export * from './types/enyo-charger-appliance.cjs';
+export * from './types/enyo-charging-card.cjs';
+export * from './packages/energy-app-charging-card.cjs';
 export * from './types/enyo-battery-appliance.cjs';
 export * from './types/enyo-heatpump-appliance.cjs';
 export * from './types/enyo-inverter-appliance.cjs';

package/dist/cjs/packages/energy-app-charging-card.d.cts

@@ -1,11 +1,56 @@
-import { EnyoChargingCard } from "../types/enyo-charging-card.cjs";
+import { EnyoChargingCard, EnyoChargingCardPairingRequest } from "../types/enyo-charging-card.cjs";
 /**
  * Interface for managing charging cards in enyo packages.
- * Provides read-only operations for charging card information.
+ * Provides read-only operations for charging card information as well as
+ * RFID pairing support.
  */
 export interface EnergyAppChargingCard {
     /** Get a list of all registered charging cards */
     list: () => Promise<EnyoChargingCard[]>;
     /** Get a specific charging card by its ID */
     getById: (id: string) => Promise<EnyoChargingCard | null>;
+    /**
+     * Listen for pairing requests, i.e. the host asking this package to put its
+     * RFID reader into pairing mode — typically because a user started adding a
+     * new charging card in the app.
+     *
+     * The listener owns the whole pairing attempt: it enables pairing mode on
+     * the charger, waits for a card to be held against the reader and resolves
+     * with the RFID identifier that was read (the value stored in
+     * {@link EnyoChargingCard.rfid}). The host assigns it to the charging card
+     * named by {@link EnyoChargingCardPairingRequest.chargingCardId} and clears
+     * that card's {@link EnyoChargingCard.pendingRegistration} flag.
+     *
+     * Reject the returned promise when no card was presented or the charger
+     * refused to enter pairing mode; the host then reports the attempt as
+     * failed and leaves the card pending. Honour
+     * {@link EnyoChargingCardPairingRequest.timeoutMs} when it is set — the host
+     * ignores a result that arrives after the deadline.
+     *
+     * Only register a listener when the package actually drives an RFID reader.
+     * Requests carry an optional
+     * {@link EnyoChargingCardPairingRequest.applianceId}; a package managing
+     * several chargers should check it and reject requests for appliances it
+     * does not own.
+     *
+     * @param listener - Callback invoked for every pairing request, resolving
+     *   with the RFID identifier read from the presented card
+     * @returns A unique listener ID that can be used to remove the listener
+     *
+     * @example
+     * ```typescript
+     * const chargingCard = energyApp.useChargingCard();
+     * const listenerId = chargingCard.listenForPairingStarted(async (request) => {
+     *     const rfid = await charger.enterPairingMode(request.applianceId, request.timeoutMs);
+     *     return rfid;
+     * });
+     * ```
+     */
+    listenForPairingStarted: (listener: (request: EnyoChargingCardPairingRequest) => Promise<string>) => string;
+    /**
+     * Removes a previously registered listener.
+     *
+     * @param listenerId - The ID returned by {@link listenForPairingStarted}
+     */
+    removeListener: (listenerId: string) => void;
 }

package/dist/cjs/types/enyo-charging-card.d.cts

@@ -9,3 +9,24 @@ export interface EnyoChargingCard {
     rfid?: string;
     pendingRegistration?: boolean;
 }
+/**
+ * Details of a pairing request handed to a
+ * {@link EnergyAppChargingCard.listenForPairingStarted} listener when the
+ * host asks a package to put its RFID reader into pairing mode.
+ */
+export interface EnyoChargingCardPairingRequest {
+    /** ID of the charging card record the scanned RFID should be assigned to */
+    chargingCardId: string;
+    /**
+     * Appliance (charger) whose RFID reader should enter pairing mode. Omitted
+     * when the host does not target a specific charger — in that case the
+     * package decides which of its readers to use.
+     */
+    applianceId?: string;
+    /**
+     * Time budget, in milliseconds, the package has to deliver a scanned card.
+     * The host stops waiting once it elapses, so a listener that resolves later
+     * has no effect. Omitted when the host does not impose a deadline.
+     */
+    timeoutMs?: number;
+}

package/dist/cjs/types/enyo-data-bus-value.cjs

@@ -15,6 +15,15 @@ var EnyoDataBusCommandReasonTypeEnum;
     EnyoDataBusCommandReasonTypeEnum["PvSurplusAvailable"] = "pv-surplus-available";
     /** Command issued because PV surplus is unavailable */
     EnyoDataBusCommandReasonTypeEnum["PvSurplusUnavailable"] = "pv-surplus-unavailable";
+    /**
+     * Command issued because PV surplus exists but is allocated to another
+     * appliance. Belongs to the
+     * {@link EnyoDataBusCommandReasonCategoryEnum.PvSurplus} category. Set
+     * {@link EnyoDataBusCommandReason.inFavourOfApplianceType} so the
+     * end-user text can name the appliance that got the surplus instead of
+     * saying "elsewhere".
+     */
+    EnyoDataBusCommandReasonTypeEnum["PvSurplusAllocatedElsewhere"] = "pv-surplus-allocated-elsewhere";
     /** Command issued because battery capacity is available */
     EnyoDataBusCommandReasonTypeEnum["BatteryCapacityAvailable"] = "battery-capacity-available";
     /** Command issued because battery capacity is unavailable */

package/dist/cjs/types/enyo-data-bus-value.d.cts

@@ -23,6 +23,15 @@ export declare enum EnyoDataBusCommandReasonTypeEnum {
     PvSurplusAvailable = "pv-surplus-available",
     /** Command issued because PV surplus is unavailable */
     PvSurplusUnavailable = "pv-surplus-unavailable",
+    /**
+     * Command issued because PV surplus exists but is allocated to another
+     * appliance. Belongs to the
+     * {@link EnyoDataBusCommandReasonCategoryEnum.PvSurplus} category. Set
+     * {@link EnyoDataBusCommandReason.inFavourOfApplianceType} so the
+     * end-user text can name the appliance that got the surplus instead of
+     * saying "elsewhere".
+     */
+    PvSurplusAllocatedElsewhere = "pv-surplus-allocated-elsewhere",
     /** Command issued because battery capacity is available */
     BatteryCapacityAvailable = "battery-capacity-available",
     /** Command issued because battery capacity is unavailable */
@@ -100,6 +109,16 @@ export interface EnyoDataBusCommandReason {
     temperatureC?: number;
     /** Relevant state of charge as a percentage (battery-driven reasons) */
     socPercent?: number;
+    /**
+     * The appliance category the decision was made in favour of.
+     *
+     * Set on reasons that describe a trade-off between appliances — most
+     * notably
+     * {@link EnyoDataBusCommandReasonTypeEnum.PvSurplusAllocatedElsewhere} —
+     * so the end-user text can name the winning appliance (e.g. "the battery")
+     * rather than saying "elsewhere".
+     */
+    inFavourOfApplianceType?: EnyoApplianceTypeEnum;
 }
 /**
  * Whether a grid operator power limitation caps power drawn from the grid