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

package/README.md

@@ -712,20 +712,52 @@ Manage charging sessions:
 ```typescript
 const charging = energyApp.useCharge();
 
-// Start charging session
-const sessionId = await charging.startCharge({
-    vehicleId: 'vehicle-123',
+// Open a session when the charger reports a StartTransaction
+const charge = await charging.startCharge({
+    applianceId: 'appliance-42',
+    transactionId: 'tx-1',
+    meterStartValueWh: 1_204_000,
     connectorId: 1,
-    maxPowerKw: 22
 });
 
-// Get active sessions
-const sessions = await charging.getActiveSessions();
+// Close it when the charger reports a StopTransaction
+const finished = await charging.stopCharge(charge.id, {
+    meterEndValueWh: 1_215_500,
+    energyDeliveredWh: 11_500,
+});
+console.log(`${finished.totalEnergyKwh} kWh for ${finished.paidPriceEuroCent} ct`);
+
+// The session a charger is running right now, if any
+const active = await charging.findActiveCharge('appliance-42');
 
-// Stop charging
-await charging.stopCharge(sessionId);
+// A session that spans several OCPP transactions (reconnect, re-authorization)
+await charging.addTransactionIdToActiveCharge('appliance-42', 'tx-2');
+
+// Read the history
+const completed = await charging.list({
+    applianceId: 'appliance-42',
+    status: EnyoChargeStatus.Completed,
+});
 ```
 
+**Energy and cost totals are the host's to compute, never the app's.**
+`stopCharge()` derives `totalEnergyKwh` and `paidPriceEuroCent` from the
+session's meter readings and the electricity tariff in force while the energy
+flowed. Pass readings — `meterEndValueWh`, and `energyDeliveredWh` when the
+charger reports it — and let the host price them. An app that computes its own
+totals makes the customer's bill depend on which app closed the session.
+
+The same division applies to the samples in `meterValues`: leave `pricePerKwh`
+and `chargingCostEuro` unset and the host resolves the tariff for each sample's
+15-minute slot itself. `powerW` and `voltageL1..L3` are optional — write them
+when the charger reports them; when omitted the host keeps whatever it already
+recorded for that timestamp.
+
+`startCharge()` is idempotent on `applianceId` + `transactionId`, so a repeated
+StartTransaction returns the running session instead of opening a second one.
+`save()` remains a whole-object update for a session that already exists; it
+offers no uniqueness guarantee, so do not open sessions with it.
+
 React to charging sessions as they happen:
 
 ```typescript

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

@@ -148,6 +148,8 @@ 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 };
 }
 /**
@@ -681,6 +683,63 @@ 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}.
+ *
+ * The flag asks the host to tell the end customer that a maintenance run is
+ * happening on their appliance, so it only means anything on
+ * {@link EnyoOnboardingV2StartVariant.Maintenance}. An installation guide has
+ * nobody to notify — the appliance does not exist yet and the installer is
+ * standing in front of the device — so setting it there is a warning, not an
+ * error: the host ignores the value, but it is a sign the wrong variant was
+ * chosen. Leaving it unset is always fine; it defaults to `false`.
+ *
+ * @param guide - The guide being validated.
+ * @param warnings - Collector for advisory problems.
+ */
+function validateUserNotification(guide, warnings) {
+    if (guide.notifyUser === undefined)
+        return;
+    if (guide.startVariant === enyo_onboarding_v2_js_1.EnyoOnboardingV2StartVariant.Maintenance)
+        return;
+    warnings.push('`notifyUser` is set on a `' +
+        `${guide.startVariant}` +
+        '` guide and is ignored — only a `' +
+        `${enyo_onboarding_v2_js_1.EnyoOnboardingV2StartVariant.Maintenance}` +
+        '` guide notifies the end customer about the run.');
+}
 /**
  * Checks {@link EnyoOnboardingV2Guide.requiresNetworkScan} against what the guide
  * actually does.

package/dist/cjs/index.cjs

@@ -88,6 +88,8 @@ __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-charge.cjs"), exports);
+__exportStar(require("./packages/energy-app-charge.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

@@ -72,6 +72,8 @@ 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-charge.cjs';
+export * from './packages/energy-app-charge.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-charge.d.cts

@@ -1,10 +1,94 @@
-import { EnyoCharge, EnyoChargeFilter, EnyoDefaultChargeMode } from "../types/enyo-charge.cjs";
+import { EnyoCharge, EnyoChargeFilter, EnyoDefaultChargeMode, EnyoStartChargeRequest, EnyoStopChargeRequest } from "../types/enyo-charge.cjs";
 /**
  * Interface for managing charging sessions in enyo packages.
  * Provides operations for charge session tracking and management.
  */
 export interface EnergyAppCharge {
-    /** Save or update a charging session in the system */
+    /**
+     * Opens a charging session for an appliance and returns it.
+     *
+     * Use this to start a session — not {@link save}. `save` writes whatever
+     * object it is given and offers no uniqueness guarantee, so two
+     * StartTransactions arriving a few milliseconds apart both pass an app-side
+     * "is one already active?" check and create two sessions for one plug-in.
+     * This call is handled by the host, which holds the invariant that an
+     * appliance has at most one active charge.
+     *
+     * **Idempotent.** When a session is already active for the same
+     * `applianceId` + `transactionId`, that session is returned unchanged
+     * rather than a second one being created — a repeated StartTransaction is
+     * safe. A session that is active on the appliance under a *different*
+     * transaction ID is treated as over: the host finalises it with best-effort
+     * end values before opening this one. If it is really the same physical
+     * session continuing under a new transaction ID (a reconnect, a
+     * re-authorization), use {@link addTransactionIdToActiveCharge} instead.
+     *
+     * The returned charge carries its `id`, so the session can be updated and
+     * later stopped without a {@link findActiveCharge} round-trip first.
+     *
+     * **Required permission:** `Charge`.
+     *
+     * @param request - What is known at plug-in time.
+     * @returns Promise resolving to the started session — or the session that
+     *          was already running for this appliance and transaction.
+     *
+     * @example
+     * ```typescript
+     * const charge = await energyApp.useCharge().startCharge({
+     *     applianceId,
+     *     transactionId: ocppTransactionId,
+     *     meterStartValueWh: meterValue,
+     *     connectorId: 1,
+     * });
+     * ```
+     */
+    startCharge: (request: EnyoStartChargeRequest) => Promise<EnyoCharge>;
+    /**
+     * Closes a charging session and returns the final record.
+     *
+     * The host does the arithmetic, and that is the point of this call: it
+     * derives {@link EnyoCharge.totalEnergyKwh} and
+     * {@link EnyoCharge.paidPriceEuroCent} from the session's meter readings
+     * and the electricity tariff in force while the energy flowed, then moves
+     * the session to a terminal status and notifies
+     * {@link listenForChargeStopped}. An app must not price a session itself —
+     * totals computed app-side would differ between apps, and a customer's bill
+     * would depend on which app happened to close the charge.
+     *
+     * Supply readings, not totals: `meterEndValueWh` and, when the charger
+     * reports it, `energyDeliveredWh`. Anything an app writes into
+     * `paidPriceEuroCent` via {@link save} is overwritten here.
+     *
+     * Stopping a session that is already in a terminal status is a no-op and
+     * returns the stored record — a duplicate StopTransaction will not re-price
+     * a finished charge.
+     *
+     * **Required permission:** `Charge`.
+     *
+     * @param chargeId - The session to close, as returned by
+     *   {@link startCharge} or {@link findActiveCharge}.
+     * @param request - How the session ended.
+     * @returns Promise resolving to the final charge record, totals included.
+     *
+     * @example
+     * ```typescript
+     * const finished = await energyApp.useCharge().stopCharge(charge.id, {
+     *     meterEndValueWh: meterValue,
+     *     energyDeliveredWh: stopTransaction.energyWh,
+     * });
+     * console.log(`${finished.totalEnergyKwh} kWh for ${finished.paidPriceEuroCent} ct`);
+     * ```
+     */
+    stopCharge: (chargeId: string, request: EnyoStopChargeRequest) => Promise<EnyoCharge>;
+    /**
+     * Save or update a charging session in the system.
+     *
+     * This is a whole-object write for a session that already exists — a
+     * changed vehicle, a corrected reading. Use {@link startCharge} to open a
+     * session and {@link stopCharge} to close one: calling this without a
+     * `chargeId` creates a row with no uniqueness guarantee, and writing
+     * terminal values by hand skips the host's energy and cost calculation.
+     */
     save: (charge: Omit<EnyoCharge, 'id'>, chargeId?: string) => Promise<void>;
     /** Get a list of charging sessions with optional filtering */
     list: (filter?: EnyoChargeFilter) => Promise<EnyoCharge[]>;

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-charge.d.cts

@@ -11,16 +11,37 @@ export declare enum EnyoChargeStatus {
     Failed = "Failed"
 }
 /**
- * Meter values recorded during a charging session
+ * A single sample recorded during a charging session — the charger's meter
+ * reading at one instant, plus whatever electrical detail it reported with it.
+ *
+ * `timestamp` and `valueWh` are the load-bearing pair: every energy total and
+ * every cost in a charge is a delta between two samples' `valueWh`, walked in
+ * timestamp order (see `calculateChargeCost()`). The rest is detail the charger
+ * may or may not report.
+ *
+ * **Pricing fields are normally filled in by the host, not the app.** Leave
+ * {@link pricePerKwh} and {@link chargingCostEuro} unset and the host resolves
+ * the tariff for the sample's 15-minute slot and derives the incremental cost
+ * itself; set them and your values are kept. Deriving them app-side means
+ * reimplementing the tariff lookup, and getting the cent-native unit of
+ * `pricePerKwh` wrong there is a silent factor-100 error in the customer's bill.
  */
 export interface ChargeMeterValue {
     /** Timestamp when the value was recorded */
     timestamp: Date;
     /** Energy value in Watt hours */
     valueWh: number;
-    /** Price per kWh at the time of measurement */
+    /**
+     * Price per kWh at the time of measurement, in **Euro cents** (ct/kWh) —
+     * not Euro. Usually left unset for the host to resolve from the appliance's
+     * electricity tariff; see the note on {@link ChargeMeterValue}.
+     */
     pricePerKwh?: number;
-    /** Charging cost in Euro for this measurement */
+    /**
+     * Incremental charging cost in **Euro** for this sample — the energy
+     * delivered since the previous sample priced at {@link pricePerKwh}, not a
+     * running total. Usually left unset for the host to derive.
+     */
     chargingCostEuro?: number;
     /** Current on phase 1 in Amperes */
     currentPhase1: number;
@@ -28,6 +49,23 @@ export interface ChargeMeterValue {
     currentPhase2?: number;
     /** Current on phase 3 in Amperes */
     currentPhase3?: number;
+    /**
+     * Active charging power in Watt at the moment of the sample.
+     *
+     * Optional because not every charger reports it and it is derivable from
+     * the `valueWh` deltas — but only coarsely, at the sampling interval, which
+     * is why a charger that does report it should write it here. When omitted,
+     * the host keeps whatever power it already recorded for a sample with this
+     * timestamp (its own meter-value stream may have seen one) rather than
+     * overwriting it with a zero.
+     */
+    powerW?: number;
+    /** Voltage on phase 1 in Volt, when the charger reports it. */
+    voltageL1?: number;
+    /** Voltage on phase 2 in Volt, when the charger reports it. */
+    voltageL2?: number;
+    /** Voltage on phase 3 in Volt, when the charger reports it. */
+    voltageL3?: number;
 }
 /**
  * Represents a charging session in the enyo system.
@@ -80,6 +118,77 @@ export interface EnyoCharge {
     /** Target completion time for the charging session as an ISO 8601 timestamp */
     completeAtIsoTimestamp?: string;
 }
+/**
+ * What is known when a charging session opens — the input to
+ * {@link EnergyAppCharge.startCharge}.
+ *
+ * Everything here is fact at plug-in time. The totals a session is judged by
+ * ({@link EnyoCharge.totalEnergyKwh}, {@link EnyoCharge.paidPriceEuroCent}) are
+ * absent on purpose: they are the host's to compute when the session ends, from
+ * the meter readings and the tariff in force while the energy flowed.
+ */
+export interface EnyoStartChargeRequest {
+    /** The appliance (charger) running the session. */
+    applianceId: string;
+    /**
+     * The charger's transaction ID for this session (OCPP `transactionId` or
+     * the protocol's equivalent).
+     *
+     * Together with `applianceId` this identifies the session: two chargers may
+     * independently issue the same transaction ID, so it is unique per
+     * appliance, not globally. It is also the idempotency key —
+     * {@link EnergyAppCharge.startCharge} returns the existing session rather
+     * than opening a second one when this pair is already active.
+     */
+    transactionId: string;
+    /** When charging started. Defaults to the moment the host handles the call. */
+    startTime?: Date;
+    /** The charger's meter reading at session start, in Watt hours. */
+    meterStartValueWh?: number;
+    /** Connector on the charge point the vehicle is plugged into. */
+    connectorId?: number;
+    /** The charging card that authorized the session, if any. */
+    chargingCardId?: string;
+    /** The vehicle being charged, if known. */
+    vehicleId?: string;
+    /** Number of phases charging over. Defaults to 3. */
+    numberOfPhases?: number;
+    /** Charging mode to apply. Defaults to the appliance's configured default. */
+    chargeMode?: EnyoChargeModeEnum;
+    /** Target completion time as an ISO 8601 timestamp, for optimized modes. */
+    completeAtIsoTimestamp?: string;
+}
+/**
+ * How a charging session ended — the input to
+ * {@link EnergyAppCharge.stopCharge}.
+ *
+ * Meter readings, not totals: give the host what the charger reported and it
+ * derives the delivered energy and the price. See
+ * {@link EnergyAppCharge.stopCharge}.
+ */
+export interface EnyoStopChargeRequest {
+    /** When charging ended. Defaults to the moment the host handles the call. */
+    endTime?: Date;
+    /** The charger's meter reading at session end, in Watt hours. */
+    meterEndValueWh?: number;
+    /**
+     * Energy delivered over the session in Watt hours, when the charger reports
+     * it directly (OCPP `StopTransaction`).
+     *
+     * Preferred over the meter delta when present — a charger that meters its
+     * own session knows better than a subtraction across two readings that may
+     * span a meter reset.
+     */
+    energyDeliveredWh?: number;
+    /**
+     * How the session ended. Defaults to {@link EnyoChargeStatus.Completed};
+     * pass {@link EnyoChargeStatus.Failed} for a session cut short by a fault.
+     *
+     * Both are terminal and both fire the stopped listener — a handler that
+     * assumes success will mis-report faulted sessions.
+     */
+    status?: EnyoChargeStatus;
+}
 /**
  * Represents a single entry in a charging schedule.
  * Defines a time-bound current limit for smart charging.

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. */
@@ -903,6 +932,28 @@ export interface EnyoOnboardingV2Guide {
      * {@link validateOnboardingGuideV2} instead of by the compiler.
      */
     applianceId?: string;
+    /**
+     * Whether the end customer is told about this maintenance run — **only
+     * meaningful on** {@link EnyoOnboardingV2StartVariant.Maintenance}, and
+     * ignored on every other variant.
+     *
+     * A maintenance run touches an appliance the customer already lives with:
+     * it may take the wallbox offline for a few minutes, change how the
+     * inverter behaves, or simply happen while nobody is watching. Set this to
+     * `true` when the customer should hear about it — the host sends them a
+     * notification for the run — and leave it unset when the work is invisible
+     * to them and a message would only be noise.
+     *
+     * Defaults to `false`: a guide says nothing unless it asks to. The
+     * installation variants have no customer to notify — there is no appliance
+     * yet, and the installer is standing in front of the device — so a guide
+     * that sets this anyway is warned about and the value ignored.
+     *
+     * Optional in the type because one interface serves all four variants; the
+     * variant-dependent meaning is enforced by
+     * {@link validateOnboardingGuideV2} instead of by the compiler.
+     */
+    notifyUser?: boolean;
     /** Optional vendor binding (catalog id). Usually set at publish time. */
     vendorId?: string;
     /** Optional model bindings (catalog ids). Usually set at publish time. */

package/dist/cjs/version.cjs

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