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

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

@@ -385,6 +385,10 @@ var EnyoDataBusMessageEnum;
     EnyoDataBusMessageEnum["StopAirConditioningV1"] = "StopAirConditioningV1";
     EnyoDataBusMessageEnum["ChangeAirConditioningOptimizationModeV1"] = "ChangeAirConditioningOptimizationModeV1";
     EnyoDataBusMessageEnum["VehicleSocUpdateV1"] = "VehicleSocUpdateV1";
+    /** 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. */
+    EnyoDataBusMessageEnum["VehicleSocEstimateResponseV1"] = "VehicleSocEstimateResponseV1";
     /** V2 control command: announce the available/max power (W) envelope to a charger. Supersedes {@link EnyoDataBusMessageEnum.ChangeChargingPowerV1}. */
     EnyoDataBusMessageEnum["SetChargerAvailablePowerV2"] = "SetChargerAvailablePowerV2";
     /** V2 control command: announce the available/max power (W) envelope to a heatpump, with purpose and power-source context. Supersedes {@link EnyoDataBusMessageEnum.HeatpumpAvailablePowerAnnouncementV1}. */

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

@@ -4,6 +4,7 @@ import { EnyoSourceEnum } from "./enyo-source.enum.cjs";
 import { EnyoOcppRelativeSchedule } from "./enyo-ocpp.cjs";
 import { EnyoChargerAppliancePhase, EnyoChargerApplianceStatusEnum, EnyoChargerApplianceSuspendedReasonEnum } from "./enyo-charger-appliance.cjs";
 import { PreviewChargingSchedule, PreviewChargingScheduleCostComparison, PreviewChargingScheduleUnavailableReasonEnum } from "./enyo-energy-manager.cjs";
+import { EnyoVehicleSocSourceEnum, EnyoVehicleSocUnavailableReasonEnum } from "./enyo-vehicle.cjs";
 import { EnyoEnergyPrices } from "./enyo-energy-prices.cjs";
 import { EnyoCurrencyEnum } from "./enyo-currency.cjs";
 import { EnyoHeatpumpApplianceModeEnum } from "./enyo-heatpump-appliance.cjs";
@@ -653,6 +654,10 @@ export declare enum EnyoDataBusMessageEnum {
     StopAirConditioningV1 = "StopAirConditioningV1",
     ChangeAirConditioningOptimizationModeV1 = "ChangeAirConditioningOptimizationModeV1",
     VehicleSocUpdateV1 = "VehicleSocUpdateV1",
+    /** 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. */
+    VehicleSocEstimateResponseV1 = "VehicleSocEstimateResponseV1",
     /** V2 control command: announce the available/max power (W) envelope to a charger. Supersedes {@link EnyoDataBusMessageEnum.ChangeChargingPowerV1}. */
     SetChargerAvailablePowerV2 = "SetChargerAvailablePowerV2",
     /** V2 control command: announce the available/max power (W) envelope to a heatpump, with purpose and power-source context. Supersedes {@link EnyoDataBusMessageEnum.HeatpumpAvailablePowerAnnouncementV1}. */
@@ -1661,6 +1666,25 @@ export interface EnyoDataBusEnergyManagementChargingStateV1 extends EnyoDataBusM
 /**
  * Request message to get a preview of the optimized charging schedule.
  * Sent when user wants to see the charging plan before starting.
+ *
+ * **How much energy to plan for** can be said three ways, and the energy
+ * manager resolves them in this order:
+ *
+ * 1. {@link data.targetEnergyWh} — an explicit figure, used as given.
+ * 2. {@link data.startSocPercent} and {@link data.targetSocPercent} together
+ *    with the vehicle's `batterySizeKwh`, which is what the charging screen
+ *    draws its progress bar from.
+ * 3. {@link data.vehicleId} alone — the host falls back to the vehicle's own
+ *    state of charge and standing charge limit.
+ *
+ * When none of them yields a figure the response carries
+ * {@link PreviewChargingScheduleUnavailableReasonEnum.NoTargetEnergy}.
+ *
+ * **The price ceiling should match the one the session will actually run
+ * under**, otherwise the preview shows a plan the real session will not follow.
+ * It is spelled exactly as on {@link EnyoDataBusStartChargeV1}: a
+ * {@link data.priceLimitMode} naming which of the two ceiling values is read,
+ * or no mode at all for no ceiling.
  */
 export interface EnyoDataBusRequestPreviewChargingScheduleV1 extends EnyoDataBusMessage {
     type: 'message';
@@ -1674,6 +1698,53 @@ export interface EnyoDataBusRequestPreviewChargingScheduleV1 extends EnyoDataBus
         targetEnergyWh?: number;
         /** Alternative vehicle id instead of targetEnergyWh*/
         vehicleId?: string;
+        /**
+         * State of charge to plan from, in percent (0-100) — the host's
+         * estimate as the user corrected it on the charging screen.
+         *
+         * Only useful together with {@link targetSocPercent} and a
+         * {@link vehicleId} whose `batterySizeKwh` is known: percent is not
+         * energy until there is a battery size to multiply it by. A preview
+         * asked with a start but no target cannot size the session and falls
+         * back to the next resolution step.
+         */
+        startSocPercent?: number;
+        /**
+         * State of charge the previewed session should reach, in percent
+         * (0-100). Defaults to the vehicle's standing charge limit when
+         * omitted.
+         */
+        targetSocPercent?: number;
+        /**
+         * Which price ceiling to plan against, or omitted for **no ceiling**.
+         * Same vocabulary as
+         * {@link EnyoDataBusStartChargeV1.data.priceLimitMode}.
+         *
+         * Only affects the {@link EnyoChargeModeEnum.CostOptimized} result — it
+         * is the only mode that imports, so it is the only one a ceiling can
+         * change. The other modes' entries in
+         * {@link PreviewChargingScheduleModeResult} are unaffected, which is
+         * what makes the side-by-side comparison meaningful.
+         */
+        priceLimitMode?: EnyoPriceLimitModeEnum;
+        /**
+         * Absolute ceiling in **cents per kWh** to plan against. Only read
+         * while {@link priceLimitMode} is
+         * {@link EnyoPriceLimitModeEnum.CtPerKwh}.
+         */
+        priceLimitCtPerKwh?: number;
+        /**
+         * Relative ceiling — plan to import only during the cheapest share of
+         * the day, in percent, integer 1 to 100. Only read while
+         * {@link priceLimitMode} is
+         * {@link EnyoPriceLimitModeEnum.CheapestShare}.
+         *
+         * A preview under a relative ceiling is a snapshot: the share is taken
+         * over the prices known when the request is answered, so the plan
+         * changes once the next day's prices publish. Do not cache it past the
+         * price horizon.
+         */
+        priceLimitSharePercent?: number;
         /** Target completion time as ISO timestamp (optional) */
         completeByIso?: string;
         /** Charger max power setting in Watts for cost comparison (optional) */
@@ -2939,6 +3010,110 @@ export interface EnyoDataBusVehicleSocUpdateV1 extends EnyoDataBusMessage {
          * the session against it.
          */
         measuredAtIso?: string;
+        /**
+         * Where this reading came from. Set it when you know — a value the car
+         * reported and one derived from energy delivered since plug-in are not
+         * interchangeable, and the app tells the user which it is showing.
+         */
+        source?: EnyoVehicleSocSourceEnum;
+    };
+}
+/**
+ * Request the current or estimated state of charge of a vehicle, by id.
+ *
+ * The pull counterpart to {@link EnyoDataBusVehicleSocUpdateV1}: that message
+ * is published when a source happens to have a new reading, which is the wrong
+ * shape for "the user just opened the charging screen and needs a number now".
+ * Whoever can answer replies with a
+ * {@link EnyoDataBusVehicleSocEstimateResponseV1} carrying the same
+ * {@link data.requestId}.
+ *
+ * A responder may answer from a stored reading or go and fetch a fresh one —
+ * the request says how old a value the caller will accept, not how to obtain
+ * it.
+ *
+ * ```typescript
+ * energyApp.useDataBus().sendMessage([{
+ *     type: 'message',
+ *     message: 'RequestVehicleSocEstimateV1',
+ *     data: {requestId, vehicleId, maxAgeMs: 15 * 60 * 1000},
+ * }]);
+ * ```
+ */
+export interface EnyoDataBusRequestVehicleSocEstimateV1 extends EnyoDataBusMessage {
+    type: 'message';
+    message: EnyoDataBusMessageEnum.RequestVehicleSocEstimateV1;
+    data: {
+        /** Unique request identifier the response must echo back. */
+        requestId: string;
+        /** ID of the vehicle whose state of charge is wanted. */
+        vehicleId: string;
+        /**
+         * Oldest reading the caller will accept, in milliseconds. A stored
+         * value older than this is not returned — the responder answers
+         * {@link EnyoVehicleSocUnavailableReasonEnum.ReadingTooOld} instead, or
+         * fetches a fresh one if it can.
+         *
+         * Omitted means any age is acceptable; the caller judges for itself
+         * from {@link EnyoDataBusVehicleSocEstimateResponseV1.data.measuredAtIso}.
+         * A planner sizing a session wants minutes; a screen showing a
+         * last-known figure is happy with hours.
+         */
+        maxAgeMs?: number;
+        /**
+         * ID of the charger the vehicle is plugged into, when known. Lets a
+         * responder that can only read the car over the cable — a wallbox
+         * speaking ISO 15118, a charge point reporting SoC in its meter
+         * values — find the right one without guessing.
+         */
+        applianceId?: string;
+    };
+}
+/**
+ * Answer to a {@link EnyoDataBusRequestVehicleSocEstimateV1}.
+ *
+ * Shaped like the preview response: {@link data.available} says whether there
+ * is an answer at all, and the reading or the reason follows. **No answer is an
+ * ordinary outcome**, not an error — plenty of vehicles have no source that can
+ * report their charge, and a caller has to cope without one rather than assume
+ * a number.
+ */
+export interface EnyoDataBusVehicleSocEstimateResponseV1 extends EnyoDataBusMessage {
+    type: 'message';
+    message: EnyoDataBusMessageEnum.VehicleSocEstimateResponseV1;
+    data: {
+        /** The {@link EnyoDataBusRequestVehicleSocEstimateV1.data.requestId} this answers. */
+        requestId: string;
+        /** ID of the vehicle the answer is about. */
+        vehicleId: string;
+        /** Whether a state of charge could be given. */
+        available: boolean;
+        /**
+         * State of charge of the traction battery in percent (0-100). Only
+         * present while {@link available} is `true`.
+         */
+        socPercent?: number;
+        /**
+         * When {@link socPercent} was taken, ISO 8601 — not when this response
+         * was sent. Always set alongside a value: a percentage without an age
+         * cannot be aged out, and is shown to the user as current however old
+         * it is.
+         */
+        measuredAtIso?: string;
+        /** Where the reading came from, when the responder can attribute it. */
+        source?: EnyoVehicleSocSourceEnum;
+        /**
+         * Total usable capacity of the traction battery in kWh, if known.
+         * Included because a percentage is not energy without it, and the
+         * caller would otherwise need a second round trip to size a session.
+         */
+        batterySizeKwh?: number;
+        /**
+         * Why no value could be given. Only present while {@link available} is
+         * `false`; see {@link EnyoVehicleSocUnavailableReasonEnum} for which of
+         * them are worth retrying.
+         */
+        unavailableReason?: EnyoVehicleSocUnavailableReasonEnum;
     };
 }
 /**

package/dist/cjs/types/enyo-energy-manager.cjs

@@ -90,8 +90,9 @@ var PreviewChargingScheduleUnavailableReasonEnum;
     PreviewChargingScheduleUnavailableReasonEnum["VehicleNotFound"] = "vehicle-not-found";
     /**
      * The amount of energy to plan for could not be determined — the request
-     * carried neither `targetEnergyWh` nor a `vehicleId` whose battery state
-     * yields one.
+     * carried no `targetEnergyWh`, no usable `startSocPercent` /
+     * `targetSocPercent` pair (which needs the vehicle's `batterySizeKwh` to
+     * become energy), and no `vehicleId` whose battery state yields one.
      */
     PreviewChargingScheduleUnavailableReasonEnum["NoTargetEnergy"] = "no-target-energy";
     /**
@@ -113,6 +114,19 @@ var PreviewChargingScheduleUnavailableReasonEnum;
      * preview for.
      */
     PreviewChargingScheduleUnavailableReasonEnum["ChargeModeNotSupported"] = "charge-mode-not-supported";
+    /**
+     * A price ceiling was requested that no slot in the planning window meets,
+     * so a cost-optimized plan would import nothing at all.
+     *
+     * Actionable, which is why it is distinct from
+     * {@link DeadlineNotReachable}: the deadline is fine and the charger is
+     * fine — the user's limit is simply below every price on offer, and a
+     * consumer can say so and offer to raise it. Applies to both spellings of
+     * a ceiling: a `priceLimitCtPerKwh` under the cheapest slot, or a
+     * `priceLimitSharePercent` whose share contains no usable slot before the
+     * deadline.
+     */
+    PreviewChargingScheduleUnavailableReasonEnum["PriceLimitNotReachable"] = "price-limit-not-reachable";
     // ── Everything else ────────────────────────────────────────────────────
     /**
      * The energy manager could not produce a preview right now — it is still

package/dist/cjs/types/enyo-energy-manager.d.cts

@@ -78,8 +78,9 @@ export declare enum PreviewChargingScheduleUnavailableReasonEnum {
     VehicleNotFound = "vehicle-not-found",
     /**
      * The amount of energy to plan for could not be determined — the request
-     * carried neither `targetEnergyWh` nor a `vehicleId` whose battery state
-     * yields one.
+     * carried no `targetEnergyWh`, no usable `startSocPercent` /
+     * `targetSocPercent` pair (which needs the vehicle's `batterySizeKwh` to
+     * become energy), and no `vehicleId` whose battery state yields one.
      */
     NoTargetEnergy = "no-target-energy",
     /**
@@ -100,6 +101,19 @@ export declare enum PreviewChargingScheduleUnavailableReasonEnum {
      * preview for.
      */
     ChargeModeNotSupported = "charge-mode-not-supported",
+    /**
+     * A price ceiling was requested that no slot in the planning window meets,
+     * so a cost-optimized plan would import nothing at all.
+     *
+     * Actionable, which is why it is distinct from
+     * {@link DeadlineNotReachable}: the deadline is fine and the charger is
+     * fine — the user's limit is simply below every price on offer, and a
+     * consumer can say so and offer to raise it. Applies to both spellings of
+     * a ceiling: a `priceLimitCtPerKwh` under the cheapest slot, or a
+     * `priceLimitSharePercent` whose share contains no usable slot before the
+     * deadline.
+     */
+    PriceLimitNotReachable = "price-limit-not-reachable",
     /**
      * The energy manager could not produce a preview right now — it is still
      * starting up, busy, or in a temporary error state. Transient: a later

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

@@ -1,2 +1,77 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.EnyoVehicleSocUnavailableReasonEnum = exports.EnyoVehicleSocSourceEnum = void 0;
+/**
+ * Where a state-of-charge reading came from, and therefore how much it can be
+ * trusted.
+ *
+ * The app tells the user which it is — "Jetzt 60 % · von enyo geschätzt" reads
+ * very differently from a figure the car itself reported — and a planner may
+ * want to widen its margins on a derived value.
+ */
+var EnyoVehicleSocSourceEnum;
+(function (EnyoVehicleSocSourceEnum) {
+    /**
+     * The vehicle reported it: ISO 15118, a manufacturer cloud integration, or
+     * any other channel that asks the car directly. The most trustworthy
+     * source.
+     */
+    EnyoVehicleSocSourceEnum["Vehicle"] = "vehicle";
+    /**
+     * The charge point reported it, typically in OCPP meter values. Comes from
+     * the car over the cable, so it is as current as the session.
+     */
+    EnyoVehicleSocSourceEnum["Charger"] = "charger";
+    /**
+     * Derived rather than read — energy delivered since plug-in added to an
+     * earlier figure, or a model of the vehicle's usage. Drifts with every
+     * assumption it rests on, and is the reason a reading must carry
+     * {@link EnyoVehicleSoc.measuredAtIso}.
+     */
+    EnyoVehicleSocSourceEnum["Estimated"] = "estimated";
+    /** The user typed or corrected it on the charging screen. */
+    EnyoVehicleSocSourceEnum["UserProvided"] = "user-provided";
+})(EnyoVehicleSocSourceEnum || (exports.EnyoVehicleSocSourceEnum = EnyoVehicleSocSourceEnum = {}));
+/**
+ * Why no state of charge could be given for a vehicle.
+ *
+ * Carried by the response to a request for an estimate. The members are
+ * deliberately separate so a consumer can say something useful instead of "not
+ * available": {@link NoSocSource} is permanent for this car,
+ * {@link VehicleNotConnected} resolves when it is plugged in, and
+ * {@link ReadingTooOld} means a value exists but the caller asked for a fresher
+ * one.
+ */
+var EnyoVehicleSocUnavailableReasonEnum;
+(function (EnyoVehicleSocUnavailableReasonEnum) {
+    /** No vehicle with the requested id exists. */
+    EnyoVehicleSocUnavailableReasonEnum["VehicleNotFound"] = "vehicle-not-found";
+    /**
+     * Nothing in the system can report this vehicle's charge — no integration
+     * reads the car and no charge point on site reports one. Permanent until
+     * the setup changes, so a consumer should stop asking rather than retry.
+     */
+    EnyoVehicleSocUnavailableReasonEnum["NoSocSource"] = "no-soc-source";
+    /**
+     * A source exists but needs the car connected to read it, and it is not
+     * plugged in. Resolves on the next session.
+     */
+    EnyoVehicleSocUnavailableReasonEnum["VehicleNotConnected"] = "vehicle-not-connected";
+    /**
+     * A reading exists but is older than the `maxAgeMs` the request asked for.
+     * Ask again without the constraint to take the stale value anyway — the
+     * responder does not decide for the caller what is too old.
+     */
+    EnyoVehicleSocUnavailableReasonEnum["ReadingTooOld"] = "reading-too-old";
+    /**
+     * The source could not be reached right now — the vehicle's cloud API is
+     * down, the charge point is offline, the integration is still starting.
+     * Transient: a later request may succeed.
+     */
+    EnyoVehicleSocUnavailableReasonEnum["TemporarilyUnavailable"] = "temporarily-unavailable";
+    /**
+     * No more specific reason applies. Prefer any of the members above; this
+     * exists so a sender never has to omit the field.
+     */
+    EnyoVehicleSocUnavailableReasonEnum["Unknown"] = "unknown";
+})(EnyoVehicleSocUnavailableReasonEnum || (exports.EnyoVehicleSocUnavailableReasonEnum = EnyoVehicleSocUnavailableReasonEnum = {}));

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

@@ -117,6 +117,78 @@ export interface EnyoVehicle {
      */
     departureTimezone?: string;
 }
+/**
+ * Where a state-of-charge reading came from, and therefore how much it can be
+ * trusted.
+ *
+ * The app tells the user which it is — "Jetzt 60 % · von enyo geschätzt" reads
+ * very differently from a figure the car itself reported — and a planner may
+ * want to widen its margins on a derived value.
+ */
+export declare enum EnyoVehicleSocSourceEnum {
+    /**
+     * The vehicle reported it: ISO 15118, a manufacturer cloud integration, or
+     * any other channel that asks the car directly. The most trustworthy
+     * source.
+     */
+    Vehicle = "vehicle",
+    /**
+     * The charge point reported it, typically in OCPP meter values. Comes from
+     * the car over the cable, so it is as current as the session.
+     */
+    Charger = "charger",
+    /**
+     * Derived rather than read — energy delivered since plug-in added to an
+     * earlier figure, or a model of the vehicle's usage. Drifts with every
+     * assumption it rests on, and is the reason a reading must carry
+     * {@link EnyoVehicleSoc.measuredAtIso}.
+     */
+    Estimated = "estimated",
+    /** The user typed or corrected it on the charging screen. */
+    UserProvided = "user-provided"
+}
+/**
+ * Why no state of charge could be given for a vehicle.
+ *
+ * Carried by the response to a request for an estimate. The members are
+ * deliberately separate so a consumer can say something useful instead of "not
+ * available": {@link NoSocSource} is permanent for this car,
+ * {@link VehicleNotConnected} resolves when it is plugged in, and
+ * {@link ReadingTooOld} means a value exists but the caller asked for a fresher
+ * one.
+ */
+export declare enum EnyoVehicleSocUnavailableReasonEnum {
+    /** No vehicle with the requested id exists. */
+    VehicleNotFound = "vehicle-not-found",
+    /**
+     * Nothing in the system can report this vehicle's charge — no integration
+     * reads the car and no charge point on site reports one. Permanent until
+     * the setup changes, so a consumer should stop asking rather than retry.
+     */
+    NoSocSource = "no-soc-source",
+    /**
+     * A source exists but needs the car connected to read it, and it is not
+     * plugged in. Resolves on the next session.
+     */
+    VehicleNotConnected = "vehicle-not-connected",
+    /**
+     * A reading exists but is older than the `maxAgeMs` the request asked for.
+     * Ask again without the constraint to take the stale value anyway — the
+     * responder does not decide for the caller what is too old.
+     */
+    ReadingTooOld = "reading-too-old",
+    /**
+     * The source could not be reached right now — the vehicle's cloud API is
+     * down, the charge point is offline, the integration is still starting.
+     * Transient: a later request may succeed.
+     */
+    TemporarilyUnavailable = "temporarily-unavailable",
+    /**
+     * No more specific reason applies. Prefer any of the members above; this
+     * exists so a sender never has to omit the field.
+     */
+    Unknown = "unknown"
+}
 /**
  * A state-of-charge reading for a vehicle, together with the age that makes it
  * usable.
@@ -136,4 +208,11 @@ export interface EnyoVehicleSoc {
     measuredAtIso: string;
     /** Total usable capacity of the traction battery in kWh, if the reporting source knew it. */
     batterySizeKwh?: number;
+    /**
+     * Where the reading came from. Omitted when the host cannot attribute it.
+     *
+     * Worth surfacing: a user shown a percentage wants to know whether the car
+     * said so or enyo worked it out.
+     */
+    source?: EnyoVehicleSocSourceEnum;
 }

package/dist/cjs/version.cjs

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

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

@@ -4,6 +4,7 @@ import { EnyoSourceEnum } from "./enyo-source.enum.js";
 import { EnyoOcppRelativeSchedule } from "./enyo-ocpp.js";
 import { EnyoChargerAppliancePhase, EnyoChargerApplianceStatusEnum, EnyoChargerApplianceSuspendedReasonEnum } from "./enyo-charger-appliance.js";
 import { PreviewChargingSchedule, PreviewChargingScheduleCostComparison, PreviewChargingScheduleUnavailableReasonEnum } from "./enyo-energy-manager.js";
+import { EnyoVehicleSocSourceEnum, EnyoVehicleSocUnavailableReasonEnum } from "./enyo-vehicle.js";
 import { EnyoEnergyPrices } from "./enyo-energy-prices.js";
 import { EnyoCurrencyEnum } from "./enyo-currency.js";
 import { EnyoHeatpumpApplianceModeEnum } from "./enyo-heatpump-appliance.js";
@@ -653,6 +654,10 @@ export declare enum EnyoDataBusMessageEnum {
     StopAirConditioningV1 = "StopAirConditioningV1",
     ChangeAirConditioningOptimizationModeV1 = "ChangeAirConditioningOptimizationModeV1",
     VehicleSocUpdateV1 = "VehicleSocUpdateV1",
+    /** 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. */
+    VehicleSocEstimateResponseV1 = "VehicleSocEstimateResponseV1",
     /** V2 control command: announce the available/max power (W) envelope to a charger. Supersedes {@link EnyoDataBusMessageEnum.ChangeChargingPowerV1}. */
     SetChargerAvailablePowerV2 = "SetChargerAvailablePowerV2",
     /** V2 control command: announce the available/max power (W) envelope to a heatpump, with purpose and power-source context. Supersedes {@link EnyoDataBusMessageEnum.HeatpumpAvailablePowerAnnouncementV1}. */
@@ -1661,6 +1666,25 @@ export interface EnyoDataBusEnergyManagementChargingStateV1 extends EnyoDataBusM
 /**
  * Request message to get a preview of the optimized charging schedule.
  * Sent when user wants to see the charging plan before starting.
+ *
+ * **How much energy to plan for** can be said three ways, and the energy
+ * manager resolves them in this order:
+ *
+ * 1. {@link data.targetEnergyWh} — an explicit figure, used as given.
+ * 2. {@link data.startSocPercent} and {@link data.targetSocPercent} together
+ *    with the vehicle's `batterySizeKwh`, which is what the charging screen
+ *    draws its progress bar from.
+ * 3. {@link data.vehicleId} alone — the host falls back to the vehicle's own
+ *    state of charge and standing charge limit.
+ *
+ * When none of them yields a figure the response carries
+ * {@link PreviewChargingScheduleUnavailableReasonEnum.NoTargetEnergy}.
+ *
+ * **The price ceiling should match the one the session will actually run
+ * under**, otherwise the preview shows a plan the real session will not follow.
+ * It is spelled exactly as on {@link EnyoDataBusStartChargeV1}: a
+ * {@link data.priceLimitMode} naming which of the two ceiling values is read,
+ * or no mode at all for no ceiling.
  */
 export interface EnyoDataBusRequestPreviewChargingScheduleV1 extends EnyoDataBusMessage {
     type: 'message';
@@ -1674,6 +1698,53 @@ export interface EnyoDataBusRequestPreviewChargingScheduleV1 extends EnyoDataBus
         targetEnergyWh?: number;
         /** Alternative vehicle id instead of targetEnergyWh*/
         vehicleId?: string;
+        /**
+         * State of charge to plan from, in percent (0-100) — the host's
+         * estimate as the user corrected it on the charging screen.
+         *
+         * Only useful together with {@link targetSocPercent} and a
+         * {@link vehicleId} whose `batterySizeKwh` is known: percent is not
+         * energy until there is a battery size to multiply it by. A preview
+         * asked with a start but no target cannot size the session and falls
+         * back to the next resolution step.
+         */
+        startSocPercent?: number;
+        /**
+         * State of charge the previewed session should reach, in percent
+         * (0-100). Defaults to the vehicle's standing charge limit when
+         * omitted.
+         */
+        targetSocPercent?: number;
+        /**
+         * Which price ceiling to plan against, or omitted for **no ceiling**.
+         * Same vocabulary as
+         * {@link EnyoDataBusStartChargeV1.data.priceLimitMode}.
+         *
+         * Only affects the {@link EnyoChargeModeEnum.CostOptimized} result — it
+         * is the only mode that imports, so it is the only one a ceiling can
+         * change. The other modes' entries in
+         * {@link PreviewChargingScheduleModeResult} are unaffected, which is
+         * what makes the side-by-side comparison meaningful.
+         */
+        priceLimitMode?: EnyoPriceLimitModeEnum;
+        /**
+         * Absolute ceiling in **cents per kWh** to plan against. Only read
+         * while {@link priceLimitMode} is
+         * {@link EnyoPriceLimitModeEnum.CtPerKwh}.
+         */
+        priceLimitCtPerKwh?: number;
+        /**
+         * Relative ceiling — plan to import only during the cheapest share of
+         * the day, in percent, integer 1 to 100. Only read while
+         * {@link priceLimitMode} is
+         * {@link EnyoPriceLimitModeEnum.CheapestShare}.
+         *
+         * A preview under a relative ceiling is a snapshot: the share is taken
+         * over the prices known when the request is answered, so the plan
+         * changes once the next day's prices publish. Do not cache it past the
+         * price horizon.
+         */
+        priceLimitSharePercent?: number;
         /** Target completion time as ISO timestamp (optional) */
         completeByIso?: string;
         /** Charger max power setting in Watts for cost comparison (optional) */
@@ -2939,6 +3010,110 @@ export interface EnyoDataBusVehicleSocUpdateV1 extends EnyoDataBusMessage {
          * the session against it.
          */
         measuredAtIso?: string;
+        /**
+         * Where this reading came from. Set it when you know — a value the car
+         * reported and one derived from energy delivered since plug-in are not
+         * interchangeable, and the app tells the user which it is showing.
+         */
+        source?: EnyoVehicleSocSourceEnum;
+    };
+}
+/**
+ * Request the current or estimated state of charge of a vehicle, by id.
+ *
+ * The pull counterpart to {@link EnyoDataBusVehicleSocUpdateV1}: that message
+ * is published when a source happens to have a new reading, which is the wrong
+ * shape for "the user just opened the charging screen and needs a number now".
+ * Whoever can answer replies with a
+ * {@link EnyoDataBusVehicleSocEstimateResponseV1} carrying the same
+ * {@link data.requestId}.
+ *
+ * A responder may answer from a stored reading or go and fetch a fresh one —
+ * the request says how old a value the caller will accept, not how to obtain
+ * it.
+ *
+ * ```typescript
+ * energyApp.useDataBus().sendMessage([{
+ *     type: 'message',
+ *     message: 'RequestVehicleSocEstimateV1',
+ *     data: {requestId, vehicleId, maxAgeMs: 15 * 60 * 1000},
+ * }]);
+ * ```
+ */
+export interface EnyoDataBusRequestVehicleSocEstimateV1 extends EnyoDataBusMessage {
+    type: 'message';
+    message: EnyoDataBusMessageEnum.RequestVehicleSocEstimateV1;
+    data: {
+        /** Unique request identifier the response must echo back. */
+        requestId: string;
+        /** ID of the vehicle whose state of charge is wanted. */
+        vehicleId: string;
+        /**
+         * Oldest reading the caller will accept, in milliseconds. A stored
+         * value older than this is not returned — the responder answers
+         * {@link EnyoVehicleSocUnavailableReasonEnum.ReadingTooOld} instead, or
+         * fetches a fresh one if it can.
+         *
+         * Omitted means any age is acceptable; the caller judges for itself
+         * from {@link EnyoDataBusVehicleSocEstimateResponseV1.data.measuredAtIso}.
+         * A planner sizing a session wants minutes; a screen showing a
+         * last-known figure is happy with hours.
+         */
+        maxAgeMs?: number;
+        /**
+         * ID of the charger the vehicle is plugged into, when known. Lets a
+         * responder that can only read the car over the cable — a wallbox
+         * speaking ISO 15118, a charge point reporting SoC in its meter
+         * values — find the right one without guessing.
+         */
+        applianceId?: string;
+    };
+}
+/**
+ * Answer to a {@link EnyoDataBusRequestVehicleSocEstimateV1}.
+ *
+ * Shaped like the preview response: {@link data.available} says whether there
+ * is an answer at all, and the reading or the reason follows. **No answer is an
+ * ordinary outcome**, not an error — plenty of vehicles have no source that can
+ * report their charge, and a caller has to cope without one rather than assume
+ * a number.
+ */
+export interface EnyoDataBusVehicleSocEstimateResponseV1 extends EnyoDataBusMessage {
+    type: 'message';
+    message: EnyoDataBusMessageEnum.VehicleSocEstimateResponseV1;
+    data: {
+        /** The {@link EnyoDataBusRequestVehicleSocEstimateV1.data.requestId} this answers. */
+        requestId: string;
+        /** ID of the vehicle the answer is about. */
+        vehicleId: string;
+        /** Whether a state of charge could be given. */
+        available: boolean;
+        /**
+         * State of charge of the traction battery in percent (0-100). Only
+         * present while {@link available} is `true`.
+         */
+        socPercent?: number;
+        /**
+         * When {@link socPercent} was taken, ISO 8601 — not when this response
+         * was sent. Always set alongside a value: a percentage without an age
+         * cannot be aged out, and is shown to the user as current however old
+         * it is.
+         */
+        measuredAtIso?: string;
+        /** Where the reading came from, when the responder can attribute it. */
+        source?: EnyoVehicleSocSourceEnum;
+        /**
+         * Total usable capacity of the traction battery in kWh, if known.
+         * Included because a percentage is not energy without it, and the
+         * caller would otherwise need a second round trip to size a session.
+         */
+        batterySizeKwh?: number;
+        /**
+         * Why no value could be given. Only present while {@link available} is
+         * `false`; see {@link EnyoVehicleSocUnavailableReasonEnum} for which of
+         * them are worth retrying.
+         */
+        unavailableReason?: EnyoVehicleSocUnavailableReasonEnum;
     };
 }
 /**

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

@@ -382,6 +382,10 @@ export var EnyoDataBusMessageEnum;
     EnyoDataBusMessageEnum["StopAirConditioningV1"] = "StopAirConditioningV1";
     EnyoDataBusMessageEnum["ChangeAirConditioningOptimizationModeV1"] = "ChangeAirConditioningOptimizationModeV1";
     EnyoDataBusMessageEnum["VehicleSocUpdateV1"] = "VehicleSocUpdateV1";
+    /** 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. */
+    EnyoDataBusMessageEnum["VehicleSocEstimateResponseV1"] = "VehicleSocEstimateResponseV1";
     /** V2 control command: announce the available/max power (W) envelope to a charger. Supersedes {@link EnyoDataBusMessageEnum.ChangeChargingPowerV1}. */
     EnyoDataBusMessageEnum["SetChargerAvailablePowerV2"] = "SetChargerAvailablePowerV2";
     /** V2 control command: announce the available/max power (W) envelope to a heatpump, with purpose and power-source context. Supersedes {@link EnyoDataBusMessageEnum.HeatpumpAvailablePowerAnnouncementV1}. */

package/dist/types/enyo-energy-manager.d.ts

@@ -78,8 +78,9 @@ export declare enum PreviewChargingScheduleUnavailableReasonEnum {
     VehicleNotFound = "vehicle-not-found",
     /**
      * The amount of energy to plan for could not be determined — the request
-     * carried neither `targetEnergyWh` nor a `vehicleId` whose battery state
-     * yields one.
+     * carried no `targetEnergyWh`, no usable `startSocPercent` /
+     * `targetSocPercent` pair (which needs the vehicle's `batterySizeKwh` to
+     * become energy), and no `vehicleId` whose battery state yields one.
      */
     NoTargetEnergy = "no-target-energy",
     /**
@@ -100,6 +101,19 @@ export declare enum PreviewChargingScheduleUnavailableReasonEnum {
      * preview for.
      */
     ChargeModeNotSupported = "charge-mode-not-supported",
+    /**
+     * A price ceiling was requested that no slot in the planning window meets,
+     * so a cost-optimized plan would import nothing at all.
+     *
+     * Actionable, which is why it is distinct from
+     * {@link DeadlineNotReachable}: the deadline is fine and the charger is
+     * fine — the user's limit is simply below every price on offer, and a
+     * consumer can say so and offer to raise it. Applies to both spellings of
+     * a ceiling: a `priceLimitCtPerKwh` under the cheapest slot, or a
+     * `priceLimitSharePercent` whose share contains no usable slot before the
+     * deadline.
+     */
+    PriceLimitNotReachable = "price-limit-not-reachable",
     /**
      * The energy manager could not produce a preview right now — it is still
      * starting up, busy, or in a temporary error state. Transient: a later

package/dist/types/enyo-energy-manager.js

@@ -87,8 +87,9 @@ export var PreviewChargingScheduleUnavailableReasonEnum;
     PreviewChargingScheduleUnavailableReasonEnum["VehicleNotFound"] = "vehicle-not-found";
     /**
      * The amount of energy to plan for could not be determined — the request
-     * carried neither `targetEnergyWh` nor a `vehicleId` whose battery state
-     * yields one.
+     * carried no `targetEnergyWh`, no usable `startSocPercent` /
+     * `targetSocPercent` pair (which needs the vehicle's `batterySizeKwh` to
+     * become energy), and no `vehicleId` whose battery state yields one.
      */
     PreviewChargingScheduleUnavailableReasonEnum["NoTargetEnergy"] = "no-target-energy";
     /**
@@ -110,6 +111,19 @@ export var PreviewChargingScheduleUnavailableReasonEnum;
      * preview for.
      */
     PreviewChargingScheduleUnavailableReasonEnum["ChargeModeNotSupported"] = "charge-mode-not-supported";
+    /**
+     * A price ceiling was requested that no slot in the planning window meets,
+     * so a cost-optimized plan would import nothing at all.
+     *
+     * Actionable, which is why it is distinct from
+     * {@link DeadlineNotReachable}: the deadline is fine and the charger is
+     * fine — the user's limit is simply below every price on offer, and a
+     * consumer can say so and offer to raise it. Applies to both spellings of
+     * a ceiling: a `priceLimitCtPerKwh` under the cheapest slot, or a
+     * `priceLimitSharePercent` whose share contains no usable slot before the
+     * deadline.
+     */
+    PreviewChargingScheduleUnavailableReasonEnum["PriceLimitNotReachable"] = "price-limit-not-reachable";
     // ── Everything else ────────────────────────────────────────────────────
     /**
      * The energy manager could not produce a preview right now — it is still

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

@@ -117,6 +117,78 @@ export interface EnyoVehicle {
      */
     departureTimezone?: string;
 }
+/**
+ * Where a state-of-charge reading came from, and therefore how much it can be
+ * trusted.
+ *
+ * The app tells the user which it is — "Jetzt 60 % · von enyo geschätzt" reads
+ * very differently from a figure the car itself reported — and a planner may
+ * want to widen its margins on a derived value.
+ */
+export declare enum EnyoVehicleSocSourceEnum {
+    /**
+     * The vehicle reported it: ISO 15118, a manufacturer cloud integration, or
+     * any other channel that asks the car directly. The most trustworthy
+     * source.
+     */
+    Vehicle = "vehicle",
+    /**
+     * The charge point reported it, typically in OCPP meter values. Comes from
+     * the car over the cable, so it is as current as the session.
+     */
+    Charger = "charger",
+    /**
+     * Derived rather than read — energy delivered since plug-in added to an
+     * earlier figure, or a model of the vehicle's usage. Drifts with every
+     * assumption it rests on, and is the reason a reading must carry
+     * {@link EnyoVehicleSoc.measuredAtIso}.
+     */
+    Estimated = "estimated",
+    /** The user typed or corrected it on the charging screen. */
+    UserProvided = "user-provided"
+}
+/**
+ * Why no state of charge could be given for a vehicle.
+ *
+ * Carried by the response to a request for an estimate. The members are
+ * deliberately separate so a consumer can say something useful instead of "not
+ * available": {@link NoSocSource} is permanent for this car,
+ * {@link VehicleNotConnected} resolves when it is plugged in, and
+ * {@link ReadingTooOld} means a value exists but the caller asked for a fresher
+ * one.
+ */
+export declare enum EnyoVehicleSocUnavailableReasonEnum {
+    /** No vehicle with the requested id exists. */
+    VehicleNotFound = "vehicle-not-found",
+    /**
+     * Nothing in the system can report this vehicle's charge — no integration
+     * reads the car and no charge point on site reports one. Permanent until
+     * the setup changes, so a consumer should stop asking rather than retry.
+     */
+    NoSocSource = "no-soc-source",
+    /**
+     * A source exists but needs the car connected to read it, and it is not
+     * plugged in. Resolves on the next session.
+     */
+    VehicleNotConnected = "vehicle-not-connected",
+    /**
+     * A reading exists but is older than the `maxAgeMs` the request asked for.
+     * Ask again without the constraint to take the stale value anyway — the
+     * responder does not decide for the caller what is too old.
+     */
+    ReadingTooOld = "reading-too-old",
+    /**
+     * The source could not be reached right now — the vehicle's cloud API is
+     * down, the charge point is offline, the integration is still starting.
+     * Transient: a later request may succeed.
+     */
+    TemporarilyUnavailable = "temporarily-unavailable",
+    /**
+     * No more specific reason applies. Prefer any of the members above; this
+     * exists so a sender never has to omit the field.
+     */
+    Unknown = "unknown"
+}
 /**
  * A state-of-charge reading for a vehicle, together with the age that makes it
  * usable.
@@ -136,4 +208,11 @@ export interface EnyoVehicleSoc {
     measuredAtIso: string;
     /** Total usable capacity of the traction battery in kWh, if the reporting source knew it. */
     batterySizeKwh?: number;
+    /**
+     * Where the reading came from. Omitted when the host cannot attribute it.
+     *
+     * Worth surfacing: a user shown a percentage wants to know whether the car
+     * said so or enyo worked it out.
+     */
+    source?: EnyoVehicleSocSourceEnum;
 }

package/dist/types/enyo-vehicle.js

@@ -1 +1,74 @@
-export {};
+/**
+ * Where a state-of-charge reading came from, and therefore how much it can be
+ * trusted.
+ *
+ * The app tells the user which it is — "Jetzt 60 % · von enyo geschätzt" reads
+ * very differently from a figure the car itself reported — and a planner may
+ * want to widen its margins on a derived value.
+ */
+export var EnyoVehicleSocSourceEnum;
+(function (EnyoVehicleSocSourceEnum) {
+    /**
+     * The vehicle reported it: ISO 15118, a manufacturer cloud integration, or
+     * any other channel that asks the car directly. The most trustworthy
+     * source.
+     */
+    EnyoVehicleSocSourceEnum["Vehicle"] = "vehicle";
+    /**
+     * The charge point reported it, typically in OCPP meter values. Comes from
+     * the car over the cable, so it is as current as the session.
+     */
+    EnyoVehicleSocSourceEnum["Charger"] = "charger";
+    /**
+     * Derived rather than read — energy delivered since plug-in added to an
+     * earlier figure, or a model of the vehicle's usage. Drifts with every
+     * assumption it rests on, and is the reason a reading must carry
+     * {@link EnyoVehicleSoc.measuredAtIso}.
+     */
+    EnyoVehicleSocSourceEnum["Estimated"] = "estimated";
+    /** The user typed or corrected it on the charging screen. */
+    EnyoVehicleSocSourceEnum["UserProvided"] = "user-provided";
+})(EnyoVehicleSocSourceEnum || (EnyoVehicleSocSourceEnum = {}));
+/**
+ * Why no state of charge could be given for a vehicle.
+ *
+ * Carried by the response to a request for an estimate. The members are
+ * deliberately separate so a consumer can say something useful instead of "not
+ * available": {@link NoSocSource} is permanent for this car,
+ * {@link VehicleNotConnected} resolves when it is plugged in, and
+ * {@link ReadingTooOld} means a value exists but the caller asked for a fresher
+ * one.
+ */
+export var EnyoVehicleSocUnavailableReasonEnum;
+(function (EnyoVehicleSocUnavailableReasonEnum) {
+    /** No vehicle with the requested id exists. */
+    EnyoVehicleSocUnavailableReasonEnum["VehicleNotFound"] = "vehicle-not-found";
+    /**
+     * Nothing in the system can report this vehicle's charge — no integration
+     * reads the car and no charge point on site reports one. Permanent until
+     * the setup changes, so a consumer should stop asking rather than retry.
+     */
+    EnyoVehicleSocUnavailableReasonEnum["NoSocSource"] = "no-soc-source";
+    /**
+     * A source exists but needs the car connected to read it, and it is not
+     * plugged in. Resolves on the next session.
+     */
+    EnyoVehicleSocUnavailableReasonEnum["VehicleNotConnected"] = "vehicle-not-connected";
+    /**
+     * A reading exists but is older than the `maxAgeMs` the request asked for.
+     * Ask again without the constraint to take the stale value anyway — the
+     * responder does not decide for the caller what is too old.
+     */
+    EnyoVehicleSocUnavailableReasonEnum["ReadingTooOld"] = "reading-too-old";
+    /**
+     * The source could not be reached right now — the vehicle's cloud API is
+     * down, the charge point is offline, the integration is still starting.
+     * Transient: a later request may succeed.
+     */
+    EnyoVehicleSocUnavailableReasonEnum["TemporarilyUnavailable"] = "temporarily-unavailable";
+    /**
+     * No more specific reason applies. Prefer any of the members above; this
+     * exists so a sender never has to omit the field.
+     */
+    EnyoVehicleSocUnavailableReasonEnum["Unknown"] = "unknown";
+})(EnyoVehicleSocUnavailableReasonEnum || (EnyoVehicleSocUnavailableReasonEnum = {}));

package/dist/version.d.ts

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