@enyo-energy/energy-app-sdk 1.5.0 → 1.6.0

package/README.md

@@ -367,6 +367,7 @@ Energy Apps use a granular permissions system to control access to system resour
 - **`Savings`**: Publish and read back day-scoped savings reports
 - **`EpexSpotPrices`**: Read EPEX SPOT day-ahead wholesale market prices
 - **`GridFeeRegister`** / **`GridFeeUse`**: Publish / resolve dynamic grid fees (time-variable network charges)
+- **`CommandLog`**: Record and read back the commands apps issued to appliances
 
 #### Site & Identity Permissions
 
@@ -1500,6 +1501,50 @@ Notes worth respecting when producing a report:
 
 Requires the `Savings` permission.
 
+#### `useCommandLog(): EnergyAppCommandLog`
+
+Record which register, configuration key or message your app wrote to an appliance — and read those
+writes back. This is the answer to *"why did the device do that?"*: an appliance's state shows what it
+is doing now, not that you wrote holding register 40023 four seconds ago because the energy manager cut
+available power, nor that the write was rejected.
+
+```typescript
+const commandLog = energyApp.useCommandLog();
+
+await commandLog.logCommand({
+    applianceId,
+    protocol: EnyoCommandProtocolEnum.Modbus,
+    operation: 'write-single-register',
+    target: '40023',
+    previousValue: String(before),
+    newValue: String(limitW),
+    outcome: EnyoCommandOutcomeEnum.Success,
+    reason: 'energy manager reduced available power',
+});
+
+// Everything we failed to write to this appliance today.
+const failures = await commandLog.getCommands({
+    applianceId,
+    outcome: EnyoCommandOutcomeEnum.Failed,
+    fromIso: startOfDay,
+});
+```
+
+- **Writes, not reads.** Polling a register every two seconds does not belong here; recording reads
+  would bury the writes the log exists for.
+- **Log the attempt, not only the success.** `Failed`, `TimedOut` and `Rejected` entries are the ones
+  someone goes looking for. `Rejected` is separate from `Failed` on purpose — a device that answered and
+  refused is a different diagnosis from one that could not be reached.
+- **Fill `reason`.** *What* was written can be reconstructed from the device; *why* cannot.
+- **Never gate the command on the log.** Log after the write is attempted; a failure to log must not
+  surface as a failure to control the appliance.
+- **Append-only.** No update, no delete — a log the app can rewrite cannot explain an incident.
+  Retention is the host's.
+- **Reads span every app** unless you filter by `packageName`: two packages fighting over the same
+  register are invisible from one app's own entries.
+
+Requires the `CommandLog` permission.
+
 ### Operational Utilities
 
 #### `useOnboardingV2(): EnergyAppOnboardingV2`

package/dist/cjs/energy-app-permission.type.cjs

@@ -62,4 +62,5 @@ var EnergyAppPermissionTypeEnum;
     EnergyAppPermissionTypeEnum["FirmwareRegistry"] = "FirmwareRegistry";
     EnergyAppPermissionTypeEnum["GridFeeRegister"] = "GridFeeRegister";
     EnergyAppPermissionTypeEnum["GridFeeUse"] = "GridFeeUse";
+    EnergyAppPermissionTypeEnum["CommandLog"] = "CommandLog";
 })(EnergyAppPermissionTypeEnum || (exports.EnergyAppPermissionTypeEnum = EnergyAppPermissionTypeEnum = {}));

package/dist/cjs/energy-app-permission.type.d.cts

@@ -57,7 +57,8 @@ export declare enum EnergyAppPermissionTypeEnum {
     EpexSpotPrices = "EpexSpotPrices",
     FirmwareRegistry = "FirmwareRegistry",
     GridFeeRegister = "GridFeeRegister",
-    GridFeeUse = "GridFeeUse"
+    GridFeeUse = "GridFeeUse",
+    CommandLog = "CommandLog"
 }
 /**
  * String union of every permission name, derived from

package/dist/cjs/energy-app.cjs

@@ -465,6 +465,22 @@ class EnergyApp {
     useGridFee() {
         return this.energyAppSdk.useGridFee();
     }
+    /**
+     * Gets the Command Log API for recording the writes this app issued to an
+     * appliance — which Modbus register, which OCPP configuration key or
+     * message, with what it was before and whether the device took it.
+     *
+     * An appliance's state shows what it is doing; the command log shows what
+     * was done to it and why, which is what an incident investigation actually
+     * needs. Entries are append-only, and reads span every app so that two
+     * packages fighting over the same register are visible.
+     * @returns The Command Log API instance
+     * @throws {EnergyAppPermissionNotGrantedError} If the `CommandLog`
+     *         permission is not granted.
+     */
+    useCommandLog() {
+        return this.energyAppSdk.useCommandLog();
+    }
     /**
      * Gets the current SDK version.
      * @returns The semantic version string of the SDK

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

@@ -46,6 +46,7 @@ import { EnergyAppSavings } from "./packages/energy-app-savings.cjs";
 import { EnergyAppDeviceTest } from "./packages/energy-app-device-test.cjs";
 import { EnergyAppEpexSpotPrice } from "./packages/energy-app-epex-spot-price.cjs";
 import { EnergyAppGridFee } from "./packages/energy-app-grid-fee.cjs";
+import { EnergyAppCommandLog } from "./packages/energy-app-command-log.cjs";
 import { UseFetchOptions } from "./types/enyo-fetch.cjs";
 /**
  * Concrete implementation of {@link EnyoEnergyAppSdk} that delegates every call
@@ -387,6 +388,20 @@ export declare class EnergyApp implements EnyoEnergyAppSdk {
      *         `GridFeeUse` permission required by the called method is not granted.
      */
     useGridFee(): EnergyAppGridFee;
+    /**
+     * Gets the Command Log API for recording the writes this app issued to an
+     * appliance — which Modbus register, which OCPP configuration key or
+     * message, with what it was before and whether the device took it.
+     *
+     * An appliance's state shows what it is doing; the command log shows what
+     * was done to it and why, which is what an incident investigation actually
+     * needs. Entries are append-only, and reads span every app so that two
+     * packages fighting over the same register are visible.
+     * @returns The Command Log API instance
+     * @throws {EnergyAppPermissionNotGrantedError} If the `CommandLog`
+     *         permission is not granted.
+     */
+    useCommandLog(): EnergyAppCommandLog;
     /**
      * Gets the current SDK version.
      * @returns The semantic version string of the SDK

package/dist/cjs/enyo-energy-app-sdk.d.cts

@@ -45,6 +45,7 @@ import { EnergyAppSavings } from "./packages/energy-app-savings.cjs";
 import { EnergyAppDeviceTest } from "./packages/energy-app-device-test.cjs";
 import { EnergyAppEpexSpotPrice } from "./packages/energy-app-epex-spot-price.cjs";
 import { EnergyAppGridFee } from "./packages/energy-app-grid-fee.cjs";
+import { EnergyAppCommandLog } from "./packages/energy-app-command-log.cjs";
 import { UseFetchOptions } from "./types/enyo-fetch.cjs";
 export declare enum EnergyAppStateEnum {
     Launching = "launching",
@@ -166,4 +167,6 @@ export interface EnyoEnergyAppSdk {
     useEpexSpotPrices: () => EnergyAppEpexSpotPrice;
     /** Get the Grid Fee API for publishing time-dependent network charges and resolving them to a 15-minute series */
     useGridFee: () => EnergyAppGridFee;
+    /** Get the Command Log API for recording which register, configuration key or message this app wrote to an appliance, and reading those commands back */
+    useCommandLog: () => EnergyAppCommandLog;
 }

package/dist/cjs/index.cjs

@@ -147,6 +147,8 @@ __exportStar(require("./packages/energy-app-device-test.cjs"), exports);
 __exportStar(require("./implementations/device-test/device-test-validators.cjs"), exports);
 __exportStar(require("./types/enyo-savings.cjs"), exports);
 __exportStar(require("./packages/energy-app-savings.cjs"), exports);
+__exportStar(require("./types/enyo-command-log.cjs"), exports);
+__exportStar(require("./packages/energy-app-command-log.cjs"), exports);
 __exportStar(require("./types/enyo-epex-spot-price.cjs"), exports);
 __exportStar(require("./packages/energy-app-epex-spot-price.cjs"), exports);
 __exportStar(require("./types/enyo-automation.cjs"), exports);

package/dist/cjs/index.d.cts

@@ -131,6 +131,8 @@ export * from './packages/energy-app-device-test.cjs';
 export * from './implementations/device-test/device-test-validators.cjs';
 export * from './types/enyo-savings.cjs';
 export * from './packages/energy-app-savings.cjs';
+export * from './types/enyo-command-log.cjs';
+export * from './packages/energy-app-command-log.cjs';
 export * from './types/enyo-epex-spot-price.cjs';
 export * from './packages/energy-app-epex-spot-price.cjs';
 export * from './types/enyo-automation.cjs';

package/dist/cjs/packages/energy-app-command-log.cjs

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/packages/energy-app-command-log.d.cts

@@ -0,0 +1,108 @@
+import { EnyoCommandLogEntry, EnyoCommandLogEntryInput, EnyoCommandLogFilter } from "../types/enyo-command-log.cjs";
+/**
+ * Interface for recording and reading back the commands an energy app issued to
+ * an appliance.
+ *
+ * This is the answer to "why did the device do that?". An appliance's own state
+ * shows what it is doing now; it does not show that this app wrote holding
+ * register 40023 four seconds ago because the energy manager cut the available
+ * power, nor that the write was rejected. Without a record of the writes, that
+ * has to be reconstructed from log files that may already have rotated away.
+ *
+ * The unit is a **write, not a read**. Polling a register every two seconds does
+ * not belong here — an entry is a command that changed, or tried to change,
+ * something on the device. Recording reads would bury the writes.
+ *
+ * Entries are append-only: there is no update and no delete. A log an app can
+ * rewrite cannot be trusted to explain an incident, and retention is the host's
+ * to enforce.
+ *
+ * Access to this API requires the `CommandLog` permission
+ * ({@link EnergyAppPermissionType}); {@link EnergyApp.useCommandLog} throws when
+ * it has not been granted.
+ *
+ * @example
+ * ```typescript
+ * const commandLog = energyApp.useCommandLog();
+ *
+ * const before = await modbus.readHoldingRegisters(40023, 1);
+ * try {
+ *     await modbus.writeSingleRegister(40023, limitW);
+ *     await commandLog.logCommand({
+ *         applianceId,
+ *         protocol: EnyoCommandProtocolEnum.Modbus,
+ *         operation: 'write-single-register',
+ *         target: '40023',
+ *         previousValue: String(before.readUInt16BE(0)),
+ *         newValue: String(limitW),
+ *         outcome: EnyoCommandOutcomeEnum.Success,
+ *         reason: 'energy manager reduced available power',
+ *     });
+ * } catch (error) {
+ *     await commandLog.logCommand({
+ *         applianceId,
+ *         protocol: EnyoCommandProtocolEnum.Modbus,
+ *         operation: 'write-single-register',
+ *         target: '40023',
+ *         newValue: String(limitW),
+ *         outcome: EnyoCommandOutcomeEnum.Failed,
+ *         errorMessage: String(error),
+ *         reason: 'energy manager reduced available power',
+ *     });
+ * }
+ * ```
+ */
+export interface EnergyAppCommandLog {
+    /**
+     * Appends one command to the log.
+     *
+     * Log the attempt, not only the success: a command that timed out or was
+     * rejected is the entry someone will actually go looking for, and an app
+     * that only records its successes produces a log where nothing ever went
+     * wrong. Set {@link EnyoCommandLogEntry.outcome} accordingly and put the
+     * detail in `errorMessage`.
+     *
+     * Fill {@link EnyoCommandLogEntry.reason} whenever the app knows it. What was
+     * written can be reconstructed from the device; why it was written cannot.
+     *
+     * This call is for auditing and must never gate the command itself — log
+     * after the write has been attempted, and do not let a failure to log
+     * surface as a failure to control the appliance.
+     *
+     * Requires the `CommandLog` permission.
+     *
+     * @param entry - The command to record. `id`, `packageName` and (unless
+     *   supplied) `timestampIso` are assigned by the host.
+     * @returns Promise resolving to the stored entry, including its assigned id
+     * @throws {EnergyAppPermissionNotGrantedError} If the `CommandLog` permission
+     *         is not granted.
+     */
+    logCommand(entry: EnyoCommandLogEntryInput): Promise<EnyoCommandLogEntry>;
+    /**
+     * Reads recorded commands back, newest first.
+     *
+     * Returns entries from **every** app, not just this one, unless
+     * {@link EnyoCommandLogFilter.packageName} narrows it. That is deliberate:
+     * the failure this log exists to explain is often two apps writing the same
+     * register, which is invisible from either app's own entries.
+     *
+     * Requires the `CommandLog` permission.
+     *
+     * @param filter - Optional narrowing by appliance, protocol, outcome, time
+     *   range or package. Fields combine with AND.
+     * @returns Promise resolving to the matching entries, newest first
+     * @throws {EnergyAppPermissionNotGrantedError} If the `CommandLog` permission
+     *         is not granted.
+     *
+     * @example
+     * ```typescript
+     * // Everything we failed to write to this appliance today.
+     * const failures = await commandLog.getCommands({
+     *     applianceId,
+     *     outcome: EnyoCommandOutcomeEnum.Failed,
+     *     fromIso: startOfDay,
+     * });
+     * ```
+     */
+    getCommands(filter?: EnyoCommandLogFilter): Promise<EnyoCommandLogEntry[]>;
+}

package/dist/cjs/types/enyo-battery-appliance.d.cts

@@ -65,4 +65,27 @@ export interface EnyoBatteryApplianceMetadata {
      * (0–100). The EMS should not charge the battery above this value.
      */
     maxSoC?: number;
+    /**
+     * Observed round-trip efficiency as a percentage (0–100): of the energy put
+     * into the battery, how much comes back out again.
+     *
+     * A **calculated** value, not a nameplate figure — derived from measured
+     * charge and discharge energy over completed cycles. It therefore drifts
+     * with cell age, temperature and depth of discharge, and is absent until
+     * enough cycles have been observed to compute it. Consumers should treat a
+     * missing value as "not yet known" rather than substituting a datasheet
+     * number.
+     *
+     * This is what decides whether a charge/discharge cycle is worth running at
+     * all: arbitrage pays only when the price spread exceeds the energy lost to
+     * the round trip, so an optimizer that assumes 100% will schedule cycles
+     * that lose money.
+     *
+     * Measure it at the same boundary the battery reports its power and meter
+     * values at. An AC-to-AC round trip includes the inverter's conversion
+     * losses in both directions and typically lands several points below the
+     * DC-to-DC figure for the same pack — quoting one where the other is
+     * expected silently misprices every cycle.
+     */
+    roundTripEfficiencyPercent?: number;
 }

package/dist/cjs/types/enyo-command-log.cjs

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EnyoCommandOutcomeEnum = exports.EnyoCommandProtocolEnum = void 0;
+/**
+ * The protocol a logged command was issued over.
+ *
+ * Names the transport, not the appliance: the same wallbox may be written to
+ * over Modbus TCP for power limits and over OCPP for configuration keys, and an
+ * entry is only interpretable once you know which.
+ */
+var EnyoCommandProtocolEnum;
+(function (EnyoCommandProtocolEnum) {
+    /** Modbus TCP */
+    EnyoCommandProtocolEnum["Modbus"] = "modbus";
+    /** Modbus RTU (serial) */
+    EnyoCommandProtocolEnum["ModbusRtu"] = "modbus-rtu";
+    /** OCPP — a configuration change or a call sent to a charge point */
+    EnyoCommandProtocolEnum["Ocpp"] = "ocpp";
+    /** EEBUS SHIP/SPINE */
+    EnyoCommandProtocolEnum["Eebus"] = "eebus";
+    /** MQTT publish */
+    EnyoCommandProtocolEnum["Mqtt"] = "mqtt";
+    /** HTTP request against a vendor API or local endpoint */
+    EnyoCommandProtocolEnum["Http"] = "http";
+    /** Bluetooth Low Energy GATT write */
+    EnyoCommandProtocolEnum["Bluetooth"] = "bluetooth";
+    /** UDP datagram */
+    EnyoCommandProtocolEnum["Udp"] = "udp";
+    /** Anything else — describe it in {@link EnyoCommandLogEntry.operation} */
+    EnyoCommandProtocolEnum["Other"] = "other";
+})(EnyoCommandProtocolEnum || (exports.EnyoCommandProtocolEnum = EnyoCommandProtocolEnum = {}));
+/**
+ * How a logged command ended.
+ *
+ * {@link Rejected} is deliberately separate from {@link Failed}: a device that
+ * answered and refused is a very different diagnosis from one that could not be
+ * reached, and collapsing the two is what makes a log unable to answer "did it
+ * hear us?".
+ */
+var EnyoCommandOutcomeEnum;
+(function (EnyoCommandOutcomeEnum) {
+    /** The device accepted the command. */
+    EnyoCommandOutcomeEnum["Success"] = "success";
+    /** The command could not be delivered or the device errored. */
+    EnyoCommandOutcomeEnum["Failed"] = "failed";
+    /** No answer arrived within the app's deadline. */
+    EnyoCommandOutcomeEnum["TimedOut"] = "timed-out";
+    /** The device answered and refused the command. */
+    EnyoCommandOutcomeEnum["Rejected"] = "rejected";
+})(EnyoCommandOutcomeEnum || (exports.EnyoCommandOutcomeEnum = EnyoCommandOutcomeEnum = {}));

package/dist/cjs/types/enyo-command-log.d.cts

@@ -0,0 +1,151 @@
+/**
+ * The protocol a logged command was issued over.
+ *
+ * Names the transport, not the appliance: the same wallbox may be written to
+ * over Modbus TCP for power limits and over OCPP for configuration keys, and an
+ * entry is only interpretable once you know which.
+ */
+export declare enum EnyoCommandProtocolEnum {
+    /** Modbus TCP */
+    Modbus = "modbus",
+    /** Modbus RTU (serial) */
+    ModbusRtu = "modbus-rtu",
+    /** OCPP — a configuration change or a call sent to a charge point */
+    Ocpp = "ocpp",
+    /** EEBUS SHIP/SPINE */
+    Eebus = "eebus",
+    /** MQTT publish */
+    Mqtt = "mqtt",
+    /** HTTP request against a vendor API or local endpoint */
+    Http = "http",
+    /** Bluetooth Low Energy GATT write */
+    Bluetooth = "bluetooth",
+    /** UDP datagram */
+    Udp = "udp",
+    /** Anything else — describe it in {@link EnyoCommandLogEntry.operation} */
+    Other = "other"
+}
+/**
+ * How a logged command ended.
+ *
+ * {@link Rejected} is deliberately separate from {@link Failed}: a device that
+ * answered and refused is a very different diagnosis from one that could not be
+ * reached, and collapsing the two is what makes a log unable to answer "did it
+ * hear us?".
+ */
+export declare enum EnyoCommandOutcomeEnum {
+    /** The device accepted the command. */
+    Success = "success",
+    /** The command could not be delivered or the device errored. */
+    Failed = "failed",
+    /** No answer arrived within the app's deadline. */
+    TimedOut = "timed-out",
+    /** The device answered and refused the command. */
+    Rejected = "rejected"
+}
+/**
+ * One recorded command an energy app issued to an appliance.
+ *
+ * The unit of the log is a **write**, not a read: which register was set, which
+ * OCPP configuration key was changed, which message was executed — with what it
+ * was before, what it became, and whether the device took it.
+ */
+export interface EnyoCommandLogEntry {
+    /** Unique identifier of this entry. Assigned by the host. */
+    id: string;
+    /** The appliance the command was issued to. */
+    applianceId: string;
+    /** When the command was issued, in ISO format. */
+    timestampIso: string;
+    /** The package that issued it. Set by the host, not by the caller. */
+    packageName: string;
+    /** Which protocol carried the command. */
+    protocol: EnyoCommandProtocolEnum;
+    /**
+     * What was done, in the protocol's own vocabulary — `'write-holding-registers'`,
+     * `'ChangeConfiguration'`, `'SetChargingProfile'`, `'gatt-write'`.
+     *
+     * Use the name the protocol uses rather than a prose description, so entries
+     * from one protocol group and compare.
+     */
+    operation: string;
+    /**
+     * What was addressed: a register address (`'40023'`), an OCPP configuration
+     * key (`'MeterValueSampleInterval'`), an MQTT topic, a GATT characteristic
+     * UUID. Omit for commands that address nothing in particular.
+     */
+    target?: string;
+    /**
+     * The value before the write, rendered as a string. Omit when it was not
+     * read back first — do not substitute a value the app merely believed was
+     * there, or the log will explain changes that never happened.
+     */
+    previousValue?: string;
+    /** The value written, rendered as a string. */
+    newValue?: string;
+    /** How the command ended. */
+    outcome: EnyoCommandOutcomeEnum;
+    /**
+     * Why the app issued the command — `'energy manager reduced available power'`,
+     * `'user changed charge mode'`.
+     *
+     * The single most useful field when reading the log back: the *what* can be
+     * reconstructed from the device, the *why* cannot.
+     */
+    reason?: string;
+    /**
+     * The error or rejection detail, for any outcome other than
+     * {@link EnyoCommandOutcomeEnum.Success}.
+     */
+    errorMessage?: string;
+    /** How long the command took, in milliseconds. */
+    durationMs?: number;
+    /**
+     * Anything the flat fields cannot carry — a decoded payload, the full
+     * register block written, the OCPP response object.
+     *
+     * Values above carry strings so entries from different protocols share one
+     * shape and can be rendered in one table; structured data belongs here.
+     */
+    details?: Record<string, unknown>;
+}
+/**
+ * What an app passes to {@link EnergyAppCommandLog.logCommand}.
+ *
+ * `id` and `packageName` are assigned by the host. `timestampIso` may be
+ * supplied when the command was issued earlier than it is being logged —
+ * a batch flushed after a reconnect — and otherwise defaults to the moment the
+ * host handles the call.
+ */
+export type EnyoCommandLogEntryInput = Omit<EnyoCommandLogEntry, 'id' | 'packageName' | 'timestampIso'> & {
+    timestampIso?: string;
+};
+/**
+ * Narrows which entries {@link EnergyAppCommandLog.getCommands} returns.
+ *
+ * Every field is optional and they combine with AND. With no filter at all, the
+ * most recent entries across every appliance are returned.
+ */
+export interface EnyoCommandLogFilter {
+    /** Only commands issued to this appliance. */
+    applianceId?: string;
+    /** Only commands carried over this protocol. */
+    protocol?: EnyoCommandProtocolEnum;
+    /** Only commands that ended this way — e.g. every failure in the last day. */
+    outcome?: EnyoCommandOutcomeEnum;
+    /** Only commands issued at or after this ISO timestamp (inclusive). */
+    fromIso?: string;
+    /** Only commands issued before this ISO timestamp (exclusive). */
+    untilIso?: string;
+    /**
+     * Only commands issued by this package. Omit to see every app's commands —
+     * a device misbehaving because two apps are writing the same register is
+     * invisible from one app's own entries.
+     */
+    packageName?: string;
+    /**
+     * Maximum number of entries to return, newest first. The host applies its
+     * own upper bound when this is omitted or larger than that bound.
+     */
+    limit?: number;
+}

package/dist/cjs/version.cjs

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

package/dist/energy-app-permission.type.d.ts

@@ -57,7 +57,8 @@ export declare enum EnergyAppPermissionTypeEnum {
     EpexSpotPrices = "EpexSpotPrices",
     FirmwareRegistry = "FirmwareRegistry",
     GridFeeRegister = "GridFeeRegister",
-    GridFeeUse = "GridFeeUse"
+    GridFeeUse = "GridFeeUse",
+    CommandLog = "CommandLog"
 }
 /**
  * String union of every permission name, derived from

package/dist/energy-app-permission.type.js

@@ -59,4 +59,5 @@ export var EnergyAppPermissionTypeEnum;
     EnergyAppPermissionTypeEnum["FirmwareRegistry"] = "FirmwareRegistry";
     EnergyAppPermissionTypeEnum["GridFeeRegister"] = "GridFeeRegister";
     EnergyAppPermissionTypeEnum["GridFeeUse"] = "GridFeeUse";
+    EnergyAppPermissionTypeEnum["CommandLog"] = "CommandLog";
 })(EnergyAppPermissionTypeEnum || (EnergyAppPermissionTypeEnum = {}));

package/dist/energy-app.d.ts

@@ -46,6 +46,7 @@ import { EnergyAppSavings } from "./packages/energy-app-savings.js";
 import { EnergyAppDeviceTest } from "./packages/energy-app-device-test.js";
 import { EnergyAppEpexSpotPrice } from "./packages/energy-app-epex-spot-price.js";
 import { EnergyAppGridFee } from "./packages/energy-app-grid-fee.js";
+import { EnergyAppCommandLog } from "./packages/energy-app-command-log.js";
 import { UseFetchOptions } from "./types/enyo-fetch.js";
 /**
  * Concrete implementation of {@link EnyoEnergyAppSdk} that delegates every call
@@ -387,6 +388,20 @@ export declare class EnergyApp implements EnyoEnergyAppSdk {
      *         `GridFeeUse` permission required by the called method is not granted.
      */
     useGridFee(): EnergyAppGridFee;
+    /**
+     * Gets the Command Log API for recording the writes this app issued to an
+     * appliance — which Modbus register, which OCPP configuration key or
+     * message, with what it was before and whether the device took it.
+     *
+     * An appliance's state shows what it is doing; the command log shows what
+     * was done to it and why, which is what an incident investigation actually
+     * needs. Entries are append-only, and reads span every app so that two
+     * packages fighting over the same register are visible.
+     * @returns The Command Log API instance
+     * @throws {EnergyAppPermissionNotGrantedError} If the `CommandLog`
+     *         permission is not granted.
+     */
+    useCommandLog(): EnergyAppCommandLog;
     /**
      * Gets the current SDK version.
      * @returns The semantic version string of the SDK

package/dist/energy-app.js

@@ -462,6 +462,22 @@ export class EnergyApp {
     useGridFee() {
         return this.energyAppSdk.useGridFee();
     }
+    /**
+     * Gets the Command Log API for recording the writes this app issued to an
+     * appliance — which Modbus register, which OCPP configuration key or
+     * message, with what it was before and whether the device took it.
+     *
+     * An appliance's state shows what it is doing; the command log shows what
+     * was done to it and why, which is what an incident investigation actually
+     * needs. Entries are append-only, and reads span every app so that two
+     * packages fighting over the same register are visible.
+     * @returns The Command Log API instance
+     * @throws {EnergyAppPermissionNotGrantedError} If the `CommandLog`
+     *         permission is not granted.
+     */
+    useCommandLog() {
+        return this.energyAppSdk.useCommandLog();
+    }
     /**
      * Gets the current SDK version.
      * @returns The semantic version string of the SDK

package/dist/enyo-energy-app-sdk.d.ts

@@ -45,6 +45,7 @@ import { EnergyAppSavings } from "./packages/energy-app-savings.js";
 import { EnergyAppDeviceTest } from "./packages/energy-app-device-test.js";
 import { EnergyAppEpexSpotPrice } from "./packages/energy-app-epex-spot-price.js";
 import { EnergyAppGridFee } from "./packages/energy-app-grid-fee.js";
+import { EnergyAppCommandLog } from "./packages/energy-app-command-log.js";
 import { UseFetchOptions } from "./types/enyo-fetch.js";
 export declare enum EnergyAppStateEnum {
     Launching = "launching",
@@ -166,4 +167,6 @@ export interface EnyoEnergyAppSdk {
     useEpexSpotPrices: () => EnergyAppEpexSpotPrice;
     /** Get the Grid Fee API for publishing time-dependent network charges and resolving them to a 15-minute series */
     useGridFee: () => EnergyAppGridFee;
+    /** Get the Command Log API for recording which register, configuration key or message this app wrote to an appliance, and reading those commands back */
+    useCommandLog: () => EnergyAppCommandLog;
 }

package/dist/index.d.ts

@@ -131,6 +131,8 @@ export * from './packages/energy-app-device-test.js';
 export * from './implementations/device-test/device-test-validators.js';
 export * from './types/enyo-savings.js';
 export * from './packages/energy-app-savings.js';
+export * from './types/enyo-command-log.js';
+export * from './packages/energy-app-command-log.js';
 export * from './types/enyo-epex-spot-price.js';
 export * from './packages/energy-app-epex-spot-price.js';
 export * from './types/enyo-automation.js';

package/dist/index.js

@@ -131,6 +131,8 @@ export * from './packages/energy-app-device-test.js';
 export * from './implementations/device-test/device-test-validators.js';
 export * from './types/enyo-savings.js';
 export * from './packages/energy-app-savings.js';
+export * from './types/enyo-command-log.js';
+export * from './packages/energy-app-command-log.js';
 export * from './types/enyo-epex-spot-price.js';
 export * from './packages/energy-app-epex-spot-price.js';
 export * from './types/enyo-automation.js';

package/dist/packages/energy-app-command-log.d.ts

@@ -0,0 +1,108 @@
+import { EnyoCommandLogEntry, EnyoCommandLogEntryInput, EnyoCommandLogFilter } from "../types/enyo-command-log.js";
+/**
+ * Interface for recording and reading back the commands an energy app issued to
+ * an appliance.
+ *
+ * This is the answer to "why did the device do that?". An appliance's own state
+ * shows what it is doing now; it does not show that this app wrote holding
+ * register 40023 four seconds ago because the energy manager cut the available
+ * power, nor that the write was rejected. Without a record of the writes, that
+ * has to be reconstructed from log files that may already have rotated away.
+ *
+ * The unit is a **write, not a read**. Polling a register every two seconds does
+ * not belong here — an entry is a command that changed, or tried to change,
+ * something on the device. Recording reads would bury the writes.
+ *
+ * Entries are append-only: there is no update and no delete. A log an app can
+ * rewrite cannot be trusted to explain an incident, and retention is the host's
+ * to enforce.
+ *
+ * Access to this API requires the `CommandLog` permission
+ * ({@link EnergyAppPermissionType}); {@link EnergyApp.useCommandLog} throws when
+ * it has not been granted.
+ *
+ * @example
+ * ```typescript
+ * const commandLog = energyApp.useCommandLog();
+ *
+ * const before = await modbus.readHoldingRegisters(40023, 1);
+ * try {
+ *     await modbus.writeSingleRegister(40023, limitW);
+ *     await commandLog.logCommand({
+ *         applianceId,
+ *         protocol: EnyoCommandProtocolEnum.Modbus,
+ *         operation: 'write-single-register',
+ *         target: '40023',
+ *         previousValue: String(before.readUInt16BE(0)),
+ *         newValue: String(limitW),
+ *         outcome: EnyoCommandOutcomeEnum.Success,
+ *         reason: 'energy manager reduced available power',
+ *     });
+ * } catch (error) {
+ *     await commandLog.logCommand({
+ *         applianceId,
+ *         protocol: EnyoCommandProtocolEnum.Modbus,
+ *         operation: 'write-single-register',
+ *         target: '40023',
+ *         newValue: String(limitW),
+ *         outcome: EnyoCommandOutcomeEnum.Failed,
+ *         errorMessage: String(error),
+ *         reason: 'energy manager reduced available power',
+ *     });
+ * }
+ * ```
+ */
+export interface EnergyAppCommandLog {
+    /**
+     * Appends one command to the log.
+     *
+     * Log the attempt, not only the success: a command that timed out or was
+     * rejected is the entry someone will actually go looking for, and an app
+     * that only records its successes produces a log where nothing ever went
+     * wrong. Set {@link EnyoCommandLogEntry.outcome} accordingly and put the
+     * detail in `errorMessage`.
+     *
+     * Fill {@link EnyoCommandLogEntry.reason} whenever the app knows it. What was
+     * written can be reconstructed from the device; why it was written cannot.
+     *
+     * This call is for auditing and must never gate the command itself — log
+     * after the write has been attempted, and do not let a failure to log
+     * surface as a failure to control the appliance.
+     *
+     * Requires the `CommandLog` permission.
+     *
+     * @param entry - The command to record. `id`, `packageName` and (unless
+     *   supplied) `timestampIso` are assigned by the host.
+     * @returns Promise resolving to the stored entry, including its assigned id
+     * @throws {EnergyAppPermissionNotGrantedError} If the `CommandLog` permission
+     *         is not granted.
+     */
+    logCommand(entry: EnyoCommandLogEntryInput): Promise<EnyoCommandLogEntry>;
+    /**
+     * Reads recorded commands back, newest first.
+     *
+     * Returns entries from **every** app, not just this one, unless
+     * {@link EnyoCommandLogFilter.packageName} narrows it. That is deliberate:
+     * the failure this log exists to explain is often two apps writing the same
+     * register, which is invisible from either app's own entries.
+     *
+     * Requires the `CommandLog` permission.
+     *
+     * @param filter - Optional narrowing by appliance, protocol, outcome, time
+     *   range or package. Fields combine with AND.
+     * @returns Promise resolving to the matching entries, newest first
+     * @throws {EnergyAppPermissionNotGrantedError} If the `CommandLog` permission
+     *         is not granted.
+     *
+     * @example
+     * ```typescript
+     * // Everything we failed to write to this appliance today.
+     * const failures = await commandLog.getCommands({
+     *     applianceId,
+     *     outcome: EnyoCommandOutcomeEnum.Failed,
+     *     fromIso: startOfDay,
+     * });
+     * ```
+     */
+    getCommands(filter?: EnyoCommandLogFilter): Promise<EnyoCommandLogEntry[]>;
+}

package/dist/packages/energy-app-command-log.js

@@ -0,0 +1 @@
+export {};

package/dist/types/enyo-battery-appliance.d.ts

@@ -65,4 +65,27 @@ export interface EnyoBatteryApplianceMetadata {
      * (0–100). The EMS should not charge the battery above this value.
      */
     maxSoC?: number;
+    /**
+     * Observed round-trip efficiency as a percentage (0–100): of the energy put
+     * into the battery, how much comes back out again.
+     *
+     * A **calculated** value, not a nameplate figure — derived from measured
+     * charge and discharge energy over completed cycles. It therefore drifts
+     * with cell age, temperature and depth of discharge, and is absent until
+     * enough cycles have been observed to compute it. Consumers should treat a
+     * missing value as "not yet known" rather than substituting a datasheet
+     * number.
+     *
+     * This is what decides whether a charge/discharge cycle is worth running at
+     * all: arbitrage pays only when the price spread exceeds the energy lost to
+     * the round trip, so an optimizer that assumes 100% will schedule cycles
+     * that lose money.
+     *
+     * Measure it at the same boundary the battery reports its power and meter
+     * values at. An AC-to-AC round trip includes the inverter's conversion
+     * losses in both directions and typically lands several points below the
+     * DC-to-DC figure for the same pack — quoting one where the other is
+     * expected silently misprices every cycle.
+     */
+    roundTripEfficiencyPercent?: number;
 }

package/dist/types/enyo-command-log.d.ts

@@ -0,0 +1,151 @@
+/**
+ * The protocol a logged command was issued over.
+ *
+ * Names the transport, not the appliance: the same wallbox may be written to
+ * over Modbus TCP for power limits and over OCPP for configuration keys, and an
+ * entry is only interpretable once you know which.
+ */
+export declare enum EnyoCommandProtocolEnum {
+    /** Modbus TCP */
+    Modbus = "modbus",
+    /** Modbus RTU (serial) */
+    ModbusRtu = "modbus-rtu",
+    /** OCPP — a configuration change or a call sent to a charge point */
+    Ocpp = "ocpp",
+    /** EEBUS SHIP/SPINE */
+    Eebus = "eebus",
+    /** MQTT publish */
+    Mqtt = "mqtt",
+    /** HTTP request against a vendor API or local endpoint */
+    Http = "http",
+    /** Bluetooth Low Energy GATT write */
+    Bluetooth = "bluetooth",
+    /** UDP datagram */
+    Udp = "udp",
+    /** Anything else — describe it in {@link EnyoCommandLogEntry.operation} */
+    Other = "other"
+}
+/**
+ * How a logged command ended.
+ *
+ * {@link Rejected} is deliberately separate from {@link Failed}: a device that
+ * answered and refused is a very different diagnosis from one that could not be
+ * reached, and collapsing the two is what makes a log unable to answer "did it
+ * hear us?".
+ */
+export declare enum EnyoCommandOutcomeEnum {
+    /** The device accepted the command. */
+    Success = "success",
+    /** The command could not be delivered or the device errored. */
+    Failed = "failed",
+    /** No answer arrived within the app's deadline. */
+    TimedOut = "timed-out",
+    /** The device answered and refused the command. */
+    Rejected = "rejected"
+}
+/**
+ * One recorded command an energy app issued to an appliance.
+ *
+ * The unit of the log is a **write**, not a read: which register was set, which
+ * OCPP configuration key was changed, which message was executed — with what it
+ * was before, what it became, and whether the device took it.
+ */
+export interface EnyoCommandLogEntry {
+    /** Unique identifier of this entry. Assigned by the host. */
+    id: string;
+    /** The appliance the command was issued to. */
+    applianceId: string;
+    /** When the command was issued, in ISO format. */
+    timestampIso: string;
+    /** The package that issued it. Set by the host, not by the caller. */
+    packageName: string;
+    /** Which protocol carried the command. */
+    protocol: EnyoCommandProtocolEnum;
+    /**
+     * What was done, in the protocol's own vocabulary — `'write-holding-registers'`,
+     * `'ChangeConfiguration'`, `'SetChargingProfile'`, `'gatt-write'`.
+     *
+     * Use the name the protocol uses rather than a prose description, so entries
+     * from one protocol group and compare.
+     */
+    operation: string;
+    /**
+     * What was addressed: a register address (`'40023'`), an OCPP configuration
+     * key (`'MeterValueSampleInterval'`), an MQTT topic, a GATT characteristic
+     * UUID. Omit for commands that address nothing in particular.
+     */
+    target?: string;
+    /**
+     * The value before the write, rendered as a string. Omit when it was not
+     * read back first — do not substitute a value the app merely believed was
+     * there, or the log will explain changes that never happened.
+     */
+    previousValue?: string;
+    /** The value written, rendered as a string. */
+    newValue?: string;
+    /** How the command ended. */
+    outcome: EnyoCommandOutcomeEnum;
+    /**
+     * Why the app issued the command — `'energy manager reduced available power'`,
+     * `'user changed charge mode'`.
+     *
+     * The single most useful field when reading the log back: the *what* can be
+     * reconstructed from the device, the *why* cannot.
+     */
+    reason?: string;
+    /**
+     * The error or rejection detail, for any outcome other than
+     * {@link EnyoCommandOutcomeEnum.Success}.
+     */
+    errorMessage?: string;
+    /** How long the command took, in milliseconds. */
+    durationMs?: number;
+    /**
+     * Anything the flat fields cannot carry — a decoded payload, the full
+     * register block written, the OCPP response object.
+     *
+     * Values above carry strings so entries from different protocols share one
+     * shape and can be rendered in one table; structured data belongs here.
+     */
+    details?: Record<string, unknown>;
+}
+/**
+ * What an app passes to {@link EnergyAppCommandLog.logCommand}.
+ *
+ * `id` and `packageName` are assigned by the host. `timestampIso` may be
+ * supplied when the command was issued earlier than it is being logged —
+ * a batch flushed after a reconnect — and otherwise defaults to the moment the
+ * host handles the call.
+ */
+export type EnyoCommandLogEntryInput = Omit<EnyoCommandLogEntry, 'id' | 'packageName' | 'timestampIso'> & {
+    timestampIso?: string;
+};
+/**
+ * Narrows which entries {@link EnergyAppCommandLog.getCommands} returns.
+ *
+ * Every field is optional and they combine with AND. With no filter at all, the
+ * most recent entries across every appliance are returned.
+ */
+export interface EnyoCommandLogFilter {
+    /** Only commands issued to this appliance. */
+    applianceId?: string;
+    /** Only commands carried over this protocol. */
+    protocol?: EnyoCommandProtocolEnum;
+    /** Only commands that ended this way — e.g. every failure in the last day. */
+    outcome?: EnyoCommandOutcomeEnum;
+    /** Only commands issued at or after this ISO timestamp (inclusive). */
+    fromIso?: string;
+    /** Only commands issued before this ISO timestamp (exclusive). */
+    untilIso?: string;
+    /**
+     * Only commands issued by this package. Omit to see every app's commands —
+     * a device misbehaving because two apps are writing the same register is
+     * invisible from one app's own entries.
+     */
+    packageName?: string;
+    /**
+     * Maximum number of entries to return, newest first. The host applies its
+     * own upper bound when this is omitted or larger than that bound.
+     */
+    limit?: number;
+}

package/dist/types/enyo-command-log.js

@@ -0,0 +1,47 @@
+/**
+ * The protocol a logged command was issued over.
+ *
+ * Names the transport, not the appliance: the same wallbox may be written to
+ * over Modbus TCP for power limits and over OCPP for configuration keys, and an
+ * entry is only interpretable once you know which.
+ */
+export var EnyoCommandProtocolEnum;
+(function (EnyoCommandProtocolEnum) {
+    /** Modbus TCP */
+    EnyoCommandProtocolEnum["Modbus"] = "modbus";
+    /** Modbus RTU (serial) */
+    EnyoCommandProtocolEnum["ModbusRtu"] = "modbus-rtu";
+    /** OCPP — a configuration change or a call sent to a charge point */
+    EnyoCommandProtocolEnum["Ocpp"] = "ocpp";
+    /** EEBUS SHIP/SPINE */
+    EnyoCommandProtocolEnum["Eebus"] = "eebus";
+    /** MQTT publish */
+    EnyoCommandProtocolEnum["Mqtt"] = "mqtt";
+    /** HTTP request against a vendor API or local endpoint */
+    EnyoCommandProtocolEnum["Http"] = "http";
+    /** Bluetooth Low Energy GATT write */
+    EnyoCommandProtocolEnum["Bluetooth"] = "bluetooth";
+    /** UDP datagram */
+    EnyoCommandProtocolEnum["Udp"] = "udp";
+    /** Anything else — describe it in {@link EnyoCommandLogEntry.operation} */
+    EnyoCommandProtocolEnum["Other"] = "other";
+})(EnyoCommandProtocolEnum || (EnyoCommandProtocolEnum = {}));
+/**
+ * How a logged command ended.
+ *
+ * {@link Rejected} is deliberately separate from {@link Failed}: a device that
+ * answered and refused is a very different diagnosis from one that could not be
+ * reached, and collapsing the two is what makes a log unable to answer "did it
+ * hear us?".
+ */
+export var EnyoCommandOutcomeEnum;
+(function (EnyoCommandOutcomeEnum) {
+    /** The device accepted the command. */
+    EnyoCommandOutcomeEnum["Success"] = "success";
+    /** The command could not be delivered or the device errored. */
+    EnyoCommandOutcomeEnum["Failed"] = "failed";
+    /** No answer arrived within the app's deadline. */
+    EnyoCommandOutcomeEnum["TimedOut"] = "timed-out";
+    /** The device answered and refused the command. */
+    EnyoCommandOutcomeEnum["Rejected"] = "rejected";
+})(EnyoCommandOutcomeEnum || (EnyoCommandOutcomeEnum = {}));

package/dist/version.d.ts

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