@enyo-energy/energy-app-sdk 1.16.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.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}. */
@@ -1415,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;
     };
@@ -1661,6 +1686,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 +1718,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 +3030,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.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.16.0";
+export declare const SDK_VERSION = "1.18.0";
 /**
  * Gets the current SDK version.
  * @returns The semantic version string of the SDK