@enyo-energy/energy-app-sdk 1.40.0 → 1.41.0

package/README.md

@@ -860,6 +860,8 @@ energyApp.useDataBus().sendMessage([{
     data: {
         vehicleId,
         socPercent: 62,
+        // optional: remaining range in km, when the source reports it (e.g. Smartcar)
+        rangeKm: 280,
         // omit only when the reading came straight off the wire
         measuredAtIso: new Date().toISOString(),
     },
@@ -870,6 +872,19 @@ That message is the only write path for a state of charge; it needs the
 `SendDataBusValues` permission. `getSoc()` resolves to `undefined` when nothing
 is known — an ordinary answer for a car with no SoC source, not an error.
 
+The vehicle's battery size is written the same way: publish
+`VehicleBatterySizeUpdateV1` with the usable capacity in watt-hours, and the
+host stores it on the vehicle (replacing the previous value, including one the
+user entered). It is read back as `batterySizeKwh`.
+
+```typescript
+energyApp.useDataBus().sendMessage([{
+    type: 'message',
+    message: 'VehicleBatterySizeUpdateV1',
+    data: {vehicleId, batterySizeWh: 75_000},
+}]);
+```
+
 ##### Car integrations: pairing a vehicle
 
 A package in the `vehicle` category talks to a manufacturer's cloud and links

package/dist/cjs/packages/energy-app-vehicle.d.cts

@@ -29,6 +29,13 @@ import { EnyoLinkedVehicle, EnyoVehicle, EnyoVehiclePackageUnpairReasonEnum, Eny
  * That message is the only write path for a state of charge; publishing it
  * requires the `SendDataBusValues` permission.
  *
+ * ## Writing a battery size
+ *
+ * The same holds for the vehicle's battery size: an app that knows it publishes
+ * `EnyoDataBusVehicleBatterySizeUpdateV1` with `batterySizeWh`, and the host
+ * stores it on the vehicle, replacing the previous value. It is read back as
+ * {@link EnyoVehicle.batterySizeKwh}.
+ *
  * ## Pairing a car integration
  *
  * A package in the `vehicle` category — a manufacturer cloud integration —

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

@@ -847,6 +847,8 @@ var EnyoDataBusMessageEnum;
     EnyoDataBusMessageEnum["StopAirConditioningV1"] = "StopAirConditioningV1";
     EnyoDataBusMessageEnum["ChangeAirConditioningOptimizationModeV1"] = "ChangeAirConditioningOptimizationModeV1";
     EnyoDataBusMessageEnum["VehicleSocUpdateV1"] = "VehicleSocUpdateV1";
+    /** Provide or update the usable traction battery capacity of a vehicle, in Wh. */
+    EnyoDataBusMessageEnum["VehicleBatterySizeUpdateV1"] = "VehicleBatterySizeUpdateV1";
     /** Request the current or estimated state of charge of a vehicle, by vehicle id. */
     EnyoDataBusMessageEnum["RequestVehicleSocEstimateV1"] = "RequestVehicleSocEstimateV1";
     /** Answer to {@link RequestVehicleSocEstimateV1} — the estimate with its age and source, or why none could be given. */

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

@@ -1542,6 +1542,8 @@ export declare enum EnyoDataBusMessageEnum {
     StopAirConditioningV1 = "StopAirConditioningV1",
     ChangeAirConditioningOptimizationModeV1 = "ChangeAirConditioningOptimizationModeV1",
     VehicleSocUpdateV1 = "VehicleSocUpdateV1",
+    /** Provide or update the usable traction battery capacity of a vehicle, in Wh. */
+    VehicleBatterySizeUpdateV1 = "VehicleBatterySizeUpdateV1",
     /** Request the current or estimated state of charge of a vehicle, by vehicle id. */
     RequestVehicleSocEstimateV1 = "RequestVehicleSocEstimateV1",
     /** Answer to {@link RequestVehicleSocEstimateV1} — the estimate with its age and source, or why none could be given. */
@@ -4922,7 +4924,8 @@ export interface EnyoDataBusChangeAirConditioningOptimizationModeV1 extends Enyo
     };
 }
 /**
- * Informational message reporting the state of charge of an electric vehicle.
+ * Informational message reporting the state of charge of an electric vehicle,
+ * optionally with its remaining driving range.
  *
  * **This message is the write path for a state of charge.** `EnergyAppVehicle`
  * is read-only by design — there is no `vehicles.update()` — so an app that can
@@ -4942,6 +4945,7 @@ export interface EnyoDataBusChangeAirConditioningOptimizationModeV1 extends Enyo
  *     data: {
  *         vehicleId,
  *         socPercent: 62,
+ *         rangeKm: 280, // optional, when the source reports it
  *         measuredAtIso: new Date().toISOString(),
  *     },
  * }]);
@@ -4957,6 +4961,15 @@ export interface EnyoDataBusVehicleSocUpdateV1 extends EnyoDataBusMessage {
         vehicleId: string;
         /** Current state of charge of the vehicle's traction battery in percent (0-100) */
         socPercent: number;
+        /**
+         * Remaining driving range in kilometres at this state of charge, as the
+         * vehicle or its cloud API estimates it — e.g. the `range` Smartcar's
+         * battery endpoint returns alongside the percentage. Convert from miles
+         * before sending, and omit it rather than deriving one from
+         * {@link socPercent}: a range depends on the car's consumption, which
+         * only the car knows.
+         */
+        rangeKm?: number;
         /** Total usable capacity of the vehicle's traction battery in kWh, if known */
         batterySizeKwh?: number;
         /**
@@ -4978,6 +4991,57 @@ export interface EnyoDataBusVehicleSocUpdateV1 extends EnyoDataBusMessage {
         source?: EnyoVehicleSocSourceEnum;
     };
 }
+/**
+ * Provides or updates the usable capacity of a vehicle's traction battery.
+ *
+ * **This message is the write path for a vehicle's battery size.**
+ * `EnergyAppVehicle` is read-only, so an app that knows the capacity — a
+ * manufacturer or Smartcar cloud integration, a wallbox reading it over
+ * ISO 15118 — publishes it here and the host stores it on the vehicle. It is
+ * read back as `EnyoVehicle.batterySizeKwh` (the value divided by 1000).
+ *
+ * Unlike {@link EnyoDataBusVehicleSocUpdateV1.data.batterySizeKwh}, which only
+ * travels with one reading, this updates the vehicle itself and replaces the
+ * value stored on it — including one the user entered — because it is what
+ * every charging plan for the car is sized against. Send it when the app first
+ * learns the capacity and whenever it changes (e.g. the vendor reports a
+ * degraded usable capacity); there is no need to repeat an unchanged value.
+ *
+ * Only send a value you actually read. An invented or rounded-up capacity is
+ * planned against as if it were measured, and the car is charged short.
+ *
+ * ```typescript
+ * energyApp.useDataBus().sendMessage([{
+ *     type: 'message',
+ *     message: 'VehicleBatterySizeUpdateV1',
+ *     data: {
+ *         vehicleId,
+ *         batterySizeWh: 75_000,
+ *     },
+ * }]);
+ * ```
+ *
+ * Requires the `SendDataBusValues` permission.
+ */
+export interface EnyoDataBusVehicleBatterySizeUpdateV1 extends EnyoDataBusMessage {
+    type: 'message';
+    message: EnyoDataBusMessageEnum.VehicleBatterySizeUpdateV1;
+    data: {
+        /** ID of the vehicle the battery size belongs to */
+        vehicleId: string;
+        /**
+         * Usable (net) capacity of the traction battery in watt-hours — what
+         * can actually be charged, not the gross capacity on the spec sheet.
+         * Must be greater than 0.
+         */
+        batterySizeWh: number;
+        /**
+         * Where the value came from. A manufacturer or Smartcar cloud reading
+         * is {@link EnyoVehicleSocSourceEnum.Vehicle}.
+         */
+        source?: EnyoVehicleSocSourceEnum;
+    };
+}
 /**
  * Request the current or estimated state of charge of a vehicle, by id.
  *

package/dist/cjs/version.cjs

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

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

@@ -29,6 +29,13 @@ import { EnyoLinkedVehicle, EnyoVehicle, EnyoVehiclePackageUnpairReasonEnum, Eny
  * That message is the only write path for a state of charge; publishing it
  * requires the `SendDataBusValues` permission.
  *
+ * ## Writing a battery size
+ *
+ * The same holds for the vehicle's battery size: an app that knows it publishes
+ * `EnyoDataBusVehicleBatterySizeUpdateV1` with `batterySizeWh`, and the host
+ * stores it on the vehicle, replacing the previous value. It is read back as
+ * {@link EnyoVehicle.batterySizeKwh}.
+ *
  * ## Pairing a car integration
  *
  * A package in the `vehicle` category — a manufacturer cloud integration —

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

@@ -1542,6 +1542,8 @@ export declare enum EnyoDataBusMessageEnum {
     StopAirConditioningV1 = "StopAirConditioningV1",
     ChangeAirConditioningOptimizationModeV1 = "ChangeAirConditioningOptimizationModeV1",
     VehicleSocUpdateV1 = "VehicleSocUpdateV1",
+    /** Provide or update the usable traction battery capacity of a vehicle, in Wh. */
+    VehicleBatterySizeUpdateV1 = "VehicleBatterySizeUpdateV1",
     /** Request the current or estimated state of charge of a vehicle, by vehicle id. */
     RequestVehicleSocEstimateV1 = "RequestVehicleSocEstimateV1",
     /** Answer to {@link RequestVehicleSocEstimateV1} — the estimate with its age and source, or why none could be given. */
@@ -4922,7 +4924,8 @@ export interface EnyoDataBusChangeAirConditioningOptimizationModeV1 extends Enyo
     };
 }
 /**
- * Informational message reporting the state of charge of an electric vehicle.
+ * Informational message reporting the state of charge of an electric vehicle,
+ * optionally with its remaining driving range.
  *
  * **This message is the write path for a state of charge.** `EnergyAppVehicle`
  * is read-only by design — there is no `vehicles.update()` — so an app that can
@@ -4942,6 +4945,7 @@ export interface EnyoDataBusChangeAirConditioningOptimizationModeV1 extends Enyo
  *     data: {
  *         vehicleId,
  *         socPercent: 62,
+ *         rangeKm: 280, // optional, when the source reports it
  *         measuredAtIso: new Date().toISOString(),
  *     },
  * }]);
@@ -4957,6 +4961,15 @@ export interface EnyoDataBusVehicleSocUpdateV1 extends EnyoDataBusMessage {
         vehicleId: string;
         /** Current state of charge of the vehicle's traction battery in percent (0-100) */
         socPercent: number;
+        /**
+         * Remaining driving range in kilometres at this state of charge, as the
+         * vehicle or its cloud API estimates it — e.g. the `range` Smartcar's
+         * battery endpoint returns alongside the percentage. Convert from miles
+         * before sending, and omit it rather than deriving one from
+         * {@link socPercent}: a range depends on the car's consumption, which
+         * only the car knows.
+         */
+        rangeKm?: number;
         /** Total usable capacity of the vehicle's traction battery in kWh, if known */
         batterySizeKwh?: number;
         /**
@@ -4978,6 +4991,57 @@ export interface EnyoDataBusVehicleSocUpdateV1 extends EnyoDataBusMessage {
         source?: EnyoVehicleSocSourceEnum;
     };
 }
+/**
+ * Provides or updates the usable capacity of a vehicle's traction battery.
+ *
+ * **This message is the write path for a vehicle's battery size.**
+ * `EnergyAppVehicle` is read-only, so an app that knows the capacity — a
+ * manufacturer or Smartcar cloud integration, a wallbox reading it over
+ * ISO 15118 — publishes it here and the host stores it on the vehicle. It is
+ * read back as `EnyoVehicle.batterySizeKwh` (the value divided by 1000).
+ *
+ * Unlike {@link EnyoDataBusVehicleSocUpdateV1.data.batterySizeKwh}, which only
+ * travels with one reading, this updates the vehicle itself and replaces the
+ * value stored on it — including one the user entered — because it is what
+ * every charging plan for the car is sized against. Send it when the app first
+ * learns the capacity and whenever it changes (e.g. the vendor reports a
+ * degraded usable capacity); there is no need to repeat an unchanged value.
+ *
+ * Only send a value you actually read. An invented or rounded-up capacity is
+ * planned against as if it were measured, and the car is charged short.
+ *
+ * ```typescript
+ * energyApp.useDataBus().sendMessage([{
+ *     type: 'message',
+ *     message: 'VehicleBatterySizeUpdateV1',
+ *     data: {
+ *         vehicleId,
+ *         batterySizeWh: 75_000,
+ *     },
+ * }]);
+ * ```
+ *
+ * Requires the `SendDataBusValues` permission.
+ */
+export interface EnyoDataBusVehicleBatterySizeUpdateV1 extends EnyoDataBusMessage {
+    type: 'message';
+    message: EnyoDataBusMessageEnum.VehicleBatterySizeUpdateV1;
+    data: {
+        /** ID of the vehicle the battery size belongs to */
+        vehicleId: string;
+        /**
+         * Usable (net) capacity of the traction battery in watt-hours — what
+         * can actually be charged, not the gross capacity on the spec sheet.
+         * Must be greater than 0.
+         */
+        batterySizeWh: number;
+        /**
+         * Where the value came from. A manufacturer or Smartcar cloud reading
+         * is {@link EnyoVehicleSocSourceEnum.Vehicle}.
+         */
+        source?: EnyoVehicleSocSourceEnum;
+    };
+}
 /**
  * Request the current or estimated state of charge of a vehicle, by id.
  *

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

@@ -844,6 +844,8 @@ export var EnyoDataBusMessageEnum;
     EnyoDataBusMessageEnum["StopAirConditioningV1"] = "StopAirConditioningV1";
     EnyoDataBusMessageEnum["ChangeAirConditioningOptimizationModeV1"] = "ChangeAirConditioningOptimizationModeV1";
     EnyoDataBusMessageEnum["VehicleSocUpdateV1"] = "VehicleSocUpdateV1";
+    /** Provide or update the usable traction battery capacity of a vehicle, in Wh. */
+    EnyoDataBusMessageEnum["VehicleBatterySizeUpdateV1"] = "VehicleBatterySizeUpdateV1";
     /** Request the current or estimated state of charge of a vehicle, by vehicle id. */
     EnyoDataBusMessageEnum["RequestVehicleSocEstimateV1"] = "RequestVehicleSocEstimateV1";
     /** Answer to {@link RequestVehicleSocEstimateV1} — the estimate with its age and source, or why none could be given. */

package/dist/version.d.ts

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