@enyo-energy/sunspec-sdk 0.0.71 → 0.0.73

package/dist/sunspec-interfaces.d.ts

@@ -1,6 +1,7 @@
 /**
  * SunSpec block interfaces with block numbers
  */
+import { EnyoBatteryFeature } from "@enyo-energy/energy-app-sdk/dist/types/enyo-battery-appliance.js";
 /**
  * A single phase in the tiered retry schedule
  */
@@ -616,6 +617,39 @@ export declare enum SunspecBatteryCapability {
     DischargeLimit = "discharge-limit",
     ChargeLimit = "charge-limit"
 }
+/**
+ * Selects how `SunspecBattery` populates `appliance.battery.features`.
+ *
+ * - `Disabled`: ignore the SunSpec registers and ignore calibration. The SDK
+ *   publishes whatever the consumer puts in `allowedFeatures` (omit or pass
+ *   `[]` to advertise nothing). Useful when the host already knows what the
+ *   battery can do and doesn't want the SDK to make any inference.
+ * - `RegisterBased`: publish whatever the device's registers expose. If
+ *   `allowedFeatures` is set, the published list is the intersection — the
+ *   register-detected set filtered to the allow-list. Lets the consumer hide
+ *   features that the hardware exposes but they don't want to use.
+ * - `CalibrationBased`: same as `RegisterBased`, but controllable features
+ *   (grid charging, grid discharging, charge limitation, discharge
+ *   limitation) stay hidden until `CalibrationResultStore.isCalibrated(...)`
+ *   returns true for this appliance. Requires `configureCalibration(...)` to
+ *   actually run a calibration; without it the controllable features remain
+ *   hidden forever (safe-fallback behaviour).
+ */
+export declare enum SunspecBatteryFeatureModeKind {
+    Disabled = "disabled",
+    RegisterBased = "register-based",
+    CalibrationBased = "calibration-based"
+}
+export type SunspecBatteryFeatureMode = {
+    kind: SunspecBatteryFeatureModeKind.Disabled;
+    allowedFeatures?: EnyoBatteryFeature[];
+} | {
+    kind: SunspecBatteryFeatureModeKind.RegisterBased;
+    allowedFeatures?: EnyoBatteryFeature[];
+} | {
+    kind: SunspecBatteryFeatureModeKind.CalibrationBased;
+    allowedFeatures?: EnyoBatteryFeature[];
+};
 export declare enum SunspecMeterCapability {
 }
 export interface SunspecBatteryControls {
@@ -626,3 +660,35 @@ export interface SunspecBatteryControls {
     outWRte?: number;
     minRsvPct?: number;
 }
+/**
+ * The four `EnyoBatteryFeature` values that imply outbound control writes from
+ * the host action-taker. `SunspecBattery` calibration probes each one
+ * individually so `appliance.battery.features` reflects only what the device
+ * actually honours.
+ *
+ * Exposed as `as const` (not a plain `EnyoBatteryFeature[]`) so consumers can
+ * iterate the tuple with full type narrowing — see the `WRITABLE_BATTERY_FIELDS`
+ * pattern in `sunspec-battery-calibration-driver.ts`.
+ */
+export declare const SUNSPEC_CONTROLLABLE_FEATURES: readonly [EnyoBatteryFeature.GridCharging, EnyoBatteryFeature.GridDischarging, EnyoBatteryFeature.ChargeLimitation, EnyoBatteryFeature.DischargeLimitation];
+export type SunspecControllableFeature = typeof SUNSPEC_CONTROLLABLE_FEATURES[number];
+/**
+ * Outcome of a single per-feature calibration probe.
+ *
+ * - `passed`: the SDK observed the expected register/meter response.
+ * - `failed`: the SDK wrote the registers but the response was absent or wrong.
+ * - `not-supported`: a precondition stopped the probe (battery SoC out of
+ *   range, missing telemetry, register not exposed). Distinct from `failed`
+ *   so the host can distinguish "device won't" from "we couldn't even try".
+ */
+export type SunspecFeatureVerdict = 'passed' | 'failed' | 'not-supported';
+/**
+ * Per-feature outcomes captured during one calibration session. Serialised
+ * into `CalibrationResult.notes` as JSON; decoded with runtime guards by
+ * `decodeFeatureResults` (no `as` casts at the use site).
+ */
+export interface SunspecCalibrationFeatureResults {
+    featureResults: Partial<Record<SunspecControllableFeature, SunspecFeatureVerdict>>;
+    /** Free-form per-probe diagnostics (SoC at start, observed deltas, timeouts). */
+    diagnostics?: Partial<Record<SunspecControllableFeature, string>>;
+}

package/dist/sunspec-interfaces.js

@@ -1,6 +1,7 @@
 /**
  * SunSpec block interfaces with block numbers
  */
+import { EnyoBatteryFeature } from "@enyo-energy/energy-app-sdk/dist/types/enyo-battery-appliance.js";
 export const DEFAULT_RETRY_CONFIG = {
     phases: [
         { intervalMs: 10_000, durationMs: 60_000 }, // Phase 1: every 10s for 1 minute
@@ -254,6 +255,46 @@ export var SunspecBatteryCapability;
     SunspecBatteryCapability["DischargeLimit"] = "discharge-limit";
     SunspecBatteryCapability["ChargeLimit"] = "charge-limit";
 })(SunspecBatteryCapability || (SunspecBatteryCapability = {}));
+/**
+ * Selects how `SunspecBattery` populates `appliance.battery.features`.
+ *
+ * - `Disabled`: ignore the SunSpec registers and ignore calibration. The SDK
+ *   publishes whatever the consumer puts in `allowedFeatures` (omit or pass
+ *   `[]` to advertise nothing). Useful when the host already knows what the
+ *   battery can do and doesn't want the SDK to make any inference.
+ * - `RegisterBased`: publish whatever the device's registers expose. If
+ *   `allowedFeatures` is set, the published list is the intersection — the
+ *   register-detected set filtered to the allow-list. Lets the consumer hide
+ *   features that the hardware exposes but they don't want to use.
+ * - `CalibrationBased`: same as `RegisterBased`, but controllable features
+ *   (grid charging, grid discharging, charge limitation, discharge
+ *   limitation) stay hidden until `CalibrationResultStore.isCalibrated(...)`
+ *   returns true for this appliance. Requires `configureCalibration(...)` to
+ *   actually run a calibration; without it the controllable features remain
+ *   hidden forever (safe-fallback behaviour).
+ */
+export var SunspecBatteryFeatureModeKind;
+(function (SunspecBatteryFeatureModeKind) {
+    SunspecBatteryFeatureModeKind["Disabled"] = "disabled";
+    SunspecBatteryFeatureModeKind["RegisterBased"] = "register-based";
+    SunspecBatteryFeatureModeKind["CalibrationBased"] = "calibration-based";
+})(SunspecBatteryFeatureModeKind || (SunspecBatteryFeatureModeKind = {}));
 export var SunspecMeterCapability;
 (function (SunspecMeterCapability) {
 })(SunspecMeterCapability || (SunspecMeterCapability = {}));
+/**
+ * The four `EnyoBatteryFeature` values that imply outbound control writes from
+ * the host action-taker. `SunspecBattery` calibration probes each one
+ * individually so `appliance.battery.features` reflects only what the device
+ * actually honours.
+ *
+ * Exposed as `as const` (not a plain `EnyoBatteryFeature[]`) so consumers can
+ * iterate the tuple with full type narrowing — see the `WRITABLE_BATTERY_FIELDS`
+ * pattern in `sunspec-battery-calibration-driver.ts`.
+ */
+export const SUNSPEC_CONTROLLABLE_FEATURES = [
+    EnyoBatteryFeature.GridCharging,
+    EnyoBatteryFeature.GridDischarging,
+    EnyoBatteryFeature.ChargeLimitation,
+    EnyoBatteryFeature.DischargeLimitation,
+];

package/dist/version.d.ts

@@ -5,7 +5,7 @@
 /**
  * Current version of the enyo Energy App SDK.
  */
-export declare const SDK_VERSION = "0.0.71";
+export declare const SDK_VERSION = "0.0.73";
 /**
  * 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 = '0.0.71';
+export const SDK_VERSION = '0.0.73';
 /**
  * Gets the current SDK version.
  * @returns The semantic version string of the SDK

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enyo-energy/sunspec-sdk",
-  "version": "0.0.71",
+  "version": "0.0.73",
   "description": "enyo Energy Sunspec SDK",
   "type": "module",
   "main": "dist/index.js",
@@ -8,6 +8,8 @@
   "scripts": {
     "extract-version": "node scripts/extract-version.js",
     "build": "npm run extract-version && duel",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "prepublishOnly": "npm run extract-version && npm run build"
   },
   "files": [
@@ -34,10 +36,12 @@
     "@knighted/duel": "2.1.4",
     "@types/express": "^5.0.3",
     "@types/node": "^24.0.13",
-    "typescript": "^5.8.3"
+    "typescript": "^5.8.3",
+    "vitest": "^2.1.9"
   },
   "dependencies": {
-    "@enyo-energy/energy-app-sdk": "^0.0.137"
+    "@enyo-energy/appliance-calibration": "0.0.2",
+    "@enyo-energy/energy-app-sdk": "0.0.143"
   },
   "volta": {
     "node": "22.17.0"