@enyo-energy/energy-app-sdk 1.17.0 → 1.18.0

package/README.md

@@ -928,6 +928,24 @@ 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.
 
+**A session records the answers it ran under**, so a listener sees what the
+customer actually chose rather than only what the charger measured:
+
+| Field | Meaning |
+|---|---|
+| `startSocPercent` / `targetSocPercent` | The SoC the session started from and was to reach. Fixed for the session. |
+| `priceLimitMode` | Which ceiling applied — `ct-per-kwh`, `cheapest-share`, or absent for none. |
+| `priceLimitCtPerKwh` / `priceLimitSharePercent` | The ceiling itself, read according to the mode. |
+| `maxChargingPowerW` | The power the user dialled, in **Watts**. `Immediate` only. |
+| `vehicleAssignment` | `detected` \| `manual` \| `unknown` — how the session found its car. |
+
+These mirror the fields on `StartChargeV1`: the command says what a session was
+asked for, the charge says what it ran with. `maxChargingPowerW` is the opening
+figure only — the energy manager's `SetChargerAvailablePowerV2` envelope still
+bounds the session and overrides it. Watch the units: this one is watts, while
+`EnyoChargeScheduleEntry.limitAmpere` is amperes and the superseded
+`ChangeChargingPowerV1` is kW.
+
 React to charging sessions as they happen:
 
 ```typescript

package/dist/cjs/types/enyo-charge.cjs

@@ -1,6 +1,27 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EnyoChargeStatus = void 0;
+exports.EnyoChargeStatus = exports.EnyoChargeVehicleAssignmentEnum = void 0;
+/**
+ * Where the vehicle on a charging session came from.
+ *
+ * Kept apart from "is {@link EnyoCharge.vehicleId} set" because the two answer
+ * different questions: a manually assigned session and a recognised one both
+ * carry an id, but only the recognised one says anything about the wallbox's
+ * ability to identify cars.
+ */
+var EnyoChargeVehicleAssignmentEnum;
+(function (EnyoChargeVehicleAssignmentEnum) {
+    /** The charger or an integration recognised the car on its own. */
+    EnyoChargeVehicleAssignmentEnum["Detected"] = "detected";
+    /** A user picked the car, either at plug-in or afterwards in the history. */
+    EnyoChargeVehicleAssignmentEnum["Manual"] = "manual";
+    /**
+     * No car is assigned. A normal outcome rather than a fault — plenty of
+     * wallboxes cannot identify a vehicle, and the history offers this as
+     * something to fix rather than reporting it as an error.
+     */
+    EnyoChargeVehicleAssignmentEnum["Unknown"] = "unknown";
+})(EnyoChargeVehicleAssignmentEnum || (exports.EnyoChargeVehicleAssignmentEnum = EnyoChargeVehicleAssignmentEnum = {}));
 /**
  * Status of a charging session
  */

package/dist/cjs/types/enyo-charge.d.cts

@@ -1,4 +1,24 @@
-import { EnyoChargeModeEnum } from "./enyo-data-bus-value.cjs";
+import { EnyoChargeModeEnum, EnyoPriceLimitModeEnum } from "./enyo-data-bus-value.cjs";
+/**
+ * Where the vehicle on a charging session came from.
+ *
+ * Kept apart from "is {@link EnyoCharge.vehicleId} set" because the two answer
+ * different questions: a manually assigned session and a recognised one both
+ * carry an id, but only the recognised one says anything about the wallbox's
+ * ability to identify cars.
+ */
+export declare enum EnyoChargeVehicleAssignmentEnum {
+    /** The charger or an integration recognised the car on its own. */
+    Detected = "detected",
+    /** A user picked the car, either at plug-in or afterwards in the history. */
+    Manual = "manual",
+    /**
+     * No car is assigned. A normal outcome rather than a fault — plenty of
+     * wallboxes cannot identify a vehicle, and the history offers this as
+     * something to fix rather than reporting it as an error.
+     */
+    Unknown = "unknown"
+}
 /**
  * Status of a charging session
  */
@@ -117,6 +137,77 @@ export interface EnyoCharge {
     chargeMode?: EnyoChargeModeEnum;
     /** Target completion time for the charging session as an ISO 8601 timestamp */
     completeAtIsoTimestamp?: string;
+    /**
+     * State of charge at plug-in, in percent (0-100) — the host's estimate as
+     * the user corrected it.
+     *
+     * Fixed for the session, because it describes a moment and not a
+     * preference. The charging screen draws its progress bar from here to
+     * {@link targetSocPercent}.
+     *
+     * This is the recorded counterpart of
+     * {@link EnyoDataBusStartChargeV1.data.startSocPercent}: the command says
+     * what the session was asked for, the charge says what it ran with.
+     */
+    startSocPercent?: number;
+    /**
+     * State of charge this session was to reach, in percent (0-100). The
+     * vehicle's standing charge limit unless the user overrode it for this one
+     * session.
+     */
+    targetSocPercent?: number;
+    /**
+     * How the grid price ceiling that governed this session was expressed, or
+     * omitted when there was **no ceiling** — recorded so the history can say
+     * why a session waited instead of charging.
+     *
+     * Decides which of {@link priceLimitCtPerKwh} and
+     * {@link priceLimitSharePercent} applied; the other was ignored.
+     */
+    priceLimitMode?: EnyoPriceLimitModeEnum;
+    /**
+     * The absolute ceiling that applied, in **cents per kWh** (`25` is
+     * 25 ct/kWh). Only meaningful while {@link priceLimitMode} is
+     * {@link EnyoPriceLimitModeEnum.CtPerKwh}.
+     */
+    priceLimitCtPerKwh?: number;
+    /**
+     * The relative ceiling that applied — the cheapest share of the day the
+     * session was allowed to import in, in percent. Only meaningful while
+     * {@link priceLimitMode} is {@link EnyoPriceLimitModeEnum.CheapestShare}.
+     *
+     * Note this records the *setting*, not the price threshold it resolved to:
+     * that threshold moved as prices published, so it is not a property of the
+     * session.
+     */
+    priceLimitSharePercent?: number;
+    /**
+     * How this session found its vehicle — see
+     * {@link EnyoChargeVehicleAssignmentEnum}. Absent on sessions recorded
+     * before the distinction existed; treat that as
+     * {@link EnyoChargeVehicleAssignmentEnum.Unknown} only when
+     * {@link vehicleId} is unset too.
+     */
+    vehicleAssignment?: EnyoChargeVehicleAssignmentEnum;
+    /**
+     * Charging power the user dialled for this session, in **Watts**.
+     *
+     * Only meaningful under {@link EnyoChargeModeEnum.Immediate}, where how
+     * fast to charge is the customer's call rather than the energy manager's.
+     * Recorded on the session so reopening it shows the figure actually in
+     * force.
+     *
+     * Watts, matching
+     * {@link EnyoAvailablePowerCommandData.powerW} — note the SDK's other
+     * charging ceilings do not agree on a unit:
+     * {@link EnyoChargeScheduleEntry.limitAmpere} is in Amperes and the
+     * superseded {@link EnyoDataBusChangeChargingPowerV1} is in kW.
+     *
+     * **Not a second limit.** The energy manager's power envelope
+     * ({@link EnyoDataBusSetChargerAvailablePowerV2}) still bounds the session;
+     * this is what the user asked for within it.
+     */
+    maxChargingPowerW?: number;
 }
 /**
  * Represents a single entry in a charging schedule.
@@ -166,4 +257,10 @@ export interface EnyoChargeFilter {
     chargingCardId?: string;
     /** Filter by vehicle */
     vehicleId?: string;
+    /**
+     * Filter by how the session found its vehicle. Mainly useful for
+     * {@link EnyoChargeVehicleAssignmentEnum.Unknown} — the sessions a user
+     * can still be asked to assign a car to.
+     */
+    vehicleAssignment?: EnyoChargeVehicleAssignmentEnum;
 }

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

@@ -1420,6 +1420,26 @@ export interface EnyoDataBusStartChargeV1 extends EnyoDataBusMessage {
          * start.
          */
         priceLimitSharePercent?: number;
+        /**
+         * Charging power the user asked for, in **Watts**.
+         *
+         * Only meaningful under {@link EnyoChargeModeEnum.Immediate}, where how
+         * fast to charge is the customer's call rather than the energy
+         * manager's; the optimised modes derive their own power from the plan.
+         *
+         * Watts, matching {@link EnyoAvailablePowerCommandData.powerW} — the
+         * SDK's other charging ceilings disagree on units
+         * ({@link EnyoChargeScheduleEntry.limitAmpere} is Amperes, the
+         * superseded {@link EnyoDataBusChangeChargingPowerV1} is kW), so do not
+         * assume.
+         *
+         * **The opening figure, not a standing one.** The energy manager's
+         * envelope ({@link EnyoDataBusSetChargerAvailablePowerV2}) still bounds
+         * the session and overrides this as soon as it arrives; this is what
+         * the user asked for within it. Omitted means "as fast as the car and
+         * the wallbox jointly allow".
+         */
+        maxChargingPowerW?: number;
         /** Optional reason why this command was issued */
         reason?: EnyoDataBusCommandReason;
     };

package/dist/cjs/version.cjs

@@ -9,7 +9,7 @@ exports.getSdkVersion = getSdkVersion;
 /**
  * Current version of the enyo Energy App SDK.
  */
-exports.SDK_VERSION = '1.17.0';
+exports.SDK_VERSION = '1.18.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.17.0";
+export declare const SDK_VERSION = "1.18.0";
 /**
  * Gets the current SDK version.
  * @returns The semantic version string of the SDK

package/dist/types/enyo-charge.d.ts

@@ -1,4 +1,24 @@
-import { EnyoChargeModeEnum } from "./enyo-data-bus-value.js";
+import { EnyoChargeModeEnum, EnyoPriceLimitModeEnum } from "./enyo-data-bus-value.js";
+/**
+ * Where the vehicle on a charging session came from.
+ *
+ * Kept apart from "is {@link EnyoCharge.vehicleId} set" because the two answer
+ * different questions: a manually assigned session and a recognised one both
+ * carry an id, but only the recognised one says anything about the wallbox's
+ * ability to identify cars.
+ */
+export declare enum EnyoChargeVehicleAssignmentEnum {
+    /** The charger or an integration recognised the car on its own. */
+    Detected = "detected",
+    /** A user picked the car, either at plug-in or afterwards in the history. */
+    Manual = "manual",
+    /**
+     * No car is assigned. A normal outcome rather than a fault — plenty of
+     * wallboxes cannot identify a vehicle, and the history offers this as
+     * something to fix rather than reporting it as an error.
+     */
+    Unknown = "unknown"
+}
 /**
  * Status of a charging session
  */
@@ -117,6 +137,77 @@ export interface EnyoCharge {
     chargeMode?: EnyoChargeModeEnum;
     /** Target completion time for the charging session as an ISO 8601 timestamp */
     completeAtIsoTimestamp?: string;
+    /**
+     * State of charge at plug-in, in percent (0-100) — the host's estimate as
+     * the user corrected it.
+     *
+     * Fixed for the session, because it describes a moment and not a
+     * preference. The charging screen draws its progress bar from here to
+     * {@link targetSocPercent}.
+     *
+     * This is the recorded counterpart of
+     * {@link EnyoDataBusStartChargeV1.data.startSocPercent}: the command says
+     * what the session was asked for, the charge says what it ran with.
+     */
+    startSocPercent?: number;
+    /**
+     * State of charge this session was to reach, in percent (0-100). The
+     * vehicle's standing charge limit unless the user overrode it for this one
+     * session.
+     */
+    targetSocPercent?: number;
+    /**
+     * How the grid price ceiling that governed this session was expressed, or
+     * omitted when there was **no ceiling** — recorded so the history can say
+     * why a session waited instead of charging.
+     *
+     * Decides which of {@link priceLimitCtPerKwh} and
+     * {@link priceLimitSharePercent} applied; the other was ignored.
+     */
+    priceLimitMode?: EnyoPriceLimitModeEnum;
+    /**
+     * The absolute ceiling that applied, in **cents per kWh** (`25` is
+     * 25 ct/kWh). Only meaningful while {@link priceLimitMode} is
+     * {@link EnyoPriceLimitModeEnum.CtPerKwh}.
+     */
+    priceLimitCtPerKwh?: number;
+    /**
+     * The relative ceiling that applied — the cheapest share of the day the
+     * session was allowed to import in, in percent. Only meaningful while
+     * {@link priceLimitMode} is {@link EnyoPriceLimitModeEnum.CheapestShare}.
+     *
+     * Note this records the *setting*, not the price threshold it resolved to:
+     * that threshold moved as prices published, so it is not a property of the
+     * session.
+     */
+    priceLimitSharePercent?: number;
+    /**
+     * How this session found its vehicle — see
+     * {@link EnyoChargeVehicleAssignmentEnum}. Absent on sessions recorded
+     * before the distinction existed; treat that as
+     * {@link EnyoChargeVehicleAssignmentEnum.Unknown} only when
+     * {@link vehicleId} is unset too.
+     */
+    vehicleAssignment?: EnyoChargeVehicleAssignmentEnum;
+    /**
+     * Charging power the user dialled for this session, in **Watts**.
+     *
+     * Only meaningful under {@link EnyoChargeModeEnum.Immediate}, where how
+     * fast to charge is the customer's call rather than the energy manager's.
+     * Recorded on the session so reopening it shows the figure actually in
+     * force.
+     *
+     * Watts, matching
+     * {@link EnyoAvailablePowerCommandData.powerW} — note the SDK's other
+     * charging ceilings do not agree on a unit:
+     * {@link EnyoChargeScheduleEntry.limitAmpere} is in Amperes and the
+     * superseded {@link EnyoDataBusChangeChargingPowerV1} is in kW.
+     *
+     * **Not a second limit.** The energy manager's power envelope
+     * ({@link EnyoDataBusSetChargerAvailablePowerV2}) still bounds the session;
+     * this is what the user asked for within it.
+     */
+    maxChargingPowerW?: number;
 }
 /**
  * Represents a single entry in a charging schedule.
@@ -166,4 +257,10 @@ export interface EnyoChargeFilter {
     chargingCardId?: string;
     /** Filter by vehicle */
     vehicleId?: string;
+    /**
+     * Filter by how the session found its vehicle. Mainly useful for
+     * {@link EnyoChargeVehicleAssignmentEnum.Unknown} — the sessions a user
+     * can still be asked to assign a car to.
+     */
+    vehicleAssignment?: EnyoChargeVehicleAssignmentEnum;
 }

package/dist/types/enyo-charge.js

@@ -1,3 +1,24 @@
+/**
+ * Where the vehicle on a charging session came from.
+ *
+ * Kept apart from "is {@link EnyoCharge.vehicleId} set" because the two answer
+ * different questions: a manually assigned session and a recognised one both
+ * carry an id, but only the recognised one says anything about the wallbox's
+ * ability to identify cars.
+ */
+export var EnyoChargeVehicleAssignmentEnum;
+(function (EnyoChargeVehicleAssignmentEnum) {
+    /** The charger or an integration recognised the car on its own. */
+    EnyoChargeVehicleAssignmentEnum["Detected"] = "detected";
+    /** A user picked the car, either at plug-in or afterwards in the history. */
+    EnyoChargeVehicleAssignmentEnum["Manual"] = "manual";
+    /**
+     * No car is assigned. A normal outcome rather than a fault — plenty of
+     * wallboxes cannot identify a vehicle, and the history offers this as
+     * something to fix rather than reporting it as an error.
+     */
+    EnyoChargeVehicleAssignmentEnum["Unknown"] = "unknown";
+})(EnyoChargeVehicleAssignmentEnum || (EnyoChargeVehicleAssignmentEnum = {}));
 /**
  * Status of a charging session
  */

package/dist/types/enyo-data-bus-value.d.ts

@@ -1420,6 +1420,26 @@ export interface EnyoDataBusStartChargeV1 extends EnyoDataBusMessage {
          * start.
          */
         priceLimitSharePercent?: number;
+        /**
+         * Charging power the user asked for, in **Watts**.
+         *
+         * Only meaningful under {@link EnyoChargeModeEnum.Immediate}, where how
+         * fast to charge is the customer's call rather than the energy
+         * manager's; the optimised modes derive their own power from the plan.
+         *
+         * Watts, matching {@link EnyoAvailablePowerCommandData.powerW} — the
+         * SDK's other charging ceilings disagree on units
+         * ({@link EnyoChargeScheduleEntry.limitAmpere} is Amperes, the
+         * superseded {@link EnyoDataBusChangeChargingPowerV1} is kW), so do not
+         * assume.
+         *
+         * **The opening figure, not a standing one.** The energy manager's
+         * envelope ({@link EnyoDataBusSetChargerAvailablePowerV2}) still bounds
+         * the session and overrides this as soon as it arrives; this is what
+         * the user asked for within it. Omitted means "as fast as the car and
+         * the wallbox jointly allow".
+         */
+        maxChargingPowerW?: number;
         /** Optional reason why this command was issued */
         reason?: EnyoDataBusCommandReason;
     };

package/dist/version.d.ts

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