@enyo-energy/energy-app-sdk 1.0.0 → 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

@@ -148,6 +148,7 @@ function validateOnboardingGuideV2(guide, context) {
     }
     validateNetworkScanFlag(guide, warnings);
     validateApplianceBinding(guide, errors, warnings);
+    validateUserNotification(guide, warnings);
     return { ok: errors.length === 0, errors, warnings };
 }
 /**
@@ -681,6 +682,32 @@ function validateApplianceBinding(guide, errors, warnings) {
             '` 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.d.cts

@@ -903,6 +903,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.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 = "1.0.0";
+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

@@ -142,6 +142,7 @@ export function validateOnboardingGuideV2(guide, context) {
     }
     validateNetworkScanFlag(guide, warnings);
     validateApplianceBinding(guide, errors, warnings);
+    validateUserNotification(guide, warnings);
     return { ok: errors.length === 0, errors, warnings };
 }
 /**
@@ -675,6 +676,32 @@ function validateApplianceBinding(guide, errors, warnings) {
             '` 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

@@ -903,6 +903,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/version.d.ts

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