@enyo-energy/energy-app-sdk 0.0.199 → 1.1.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-validators.cjs

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

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

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

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

package/dist/cjs/version.d.cts

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

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

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

package/dist/index.d.ts

@@ -72,6 +72,8 @@ export * from './types/enyo-heating-rod-appliance.js';
 export * from './types/enyo-charger-appliance.js';
 export * from './types/enyo-charging-card.js';
 export * from './packages/energy-app-charging-card.js';
+export * from './types/enyo-charge.js';
+export * from './packages/energy-app-charge.js';
 export * from './types/enyo-battery-appliance.js';
 export * from './types/enyo-heatpump-appliance.js';
 export * from './types/enyo-inverter-appliance.js';

package/dist/index.js

@@ -72,6 +72,8 @@ export * from './types/enyo-heating-rod-appliance.js';
 export * from './types/enyo-charger-appliance.js';
 export * from './types/enyo-charging-card.js';
 export * from './packages/energy-app-charging-card.js';
+export * from './types/enyo-charge.js';
+export * from './packages/energy-app-charge.js';
 export * from './types/enyo-battery-appliance.js';
 export * from './types/enyo-heatpump-appliance.js';
 export * from './types/enyo-inverter-appliance.js';

package/dist/packages/energy-app-charge.d.ts

@@ -1,10 +1,94 @@
-import { EnyoCharge, EnyoChargeFilter, EnyoDefaultChargeMode } from "../types/enyo-charge.js";
+import { EnyoCharge, EnyoChargeFilter, EnyoDefaultChargeMode, EnyoStartChargeRequest, EnyoStopChargeRequest } from "../types/enyo-charge.js";
 /**
  * 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/types/enyo-charge.d.ts

@@ -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/types/enyo-onboarding-v2.d.ts

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

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

package/dist/version.d.ts

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

package/dist/version.js

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

package/package.json

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