@m1kad0/hannah-proto 5.0.0 → 5.2.0

package/dist/v2/agent.d.ts

@@ -100,13 +100,15 @@ export interface CaptureControl {
 }
 /**
  * A state change event for a state Hannah asked to watch (AgentWatchMore), e.g. the
- * trigger engine's conditions. Devices are not reported this way, they use SlotUpdate.
+ * trigger engine's conditions. `state_id` is the identifier the adapter uses for the value
+ * (for ioBroker the state ID, the same as `Slot.identifier` for a slot of a device). Devices
+ * report their changes as SlotUpdate; a value that is both a slot and watched gets both.
  * ack=true means the device confirmed the value (as opposed to ack=false which is the
  * "desired" value). Hannah uses this to verify that a SetState command was executed
- * successfully.
+ * successfully. The value is the raw one of that state, not normalized to a slot scale.
  */
 export interface AgentStateUpdate {
-    /** full ioBroker state ID, e.g. "0_userdata.0.feeded" */
+    /** identifier of the value, for ioBroker the full state ID, e.g. "0_userdata.0.feeded" */
     stateId: string;
     /** JSON-encoded value: "true", "42", "\"text\"" */
     value: string;
@@ -114,6 +116,13 @@ export interface AgentStateUpdate {
     ack: boolean;
     /** Unix timestamp in milliseconds */
     ts: bigint;
+    /**
+     * Field 5 is deliberately unused: in hannah.v1 it was `canonical_key`, a different type.
+     * true = the current value the adapter sends when it starts watching a state (its answer to
+     * AgentWatchMore), not a change. Hannah Core uses it to prefill the trigger engine's cache
+     * silently, without firing triggers: an update from "unknown" to a value is not a transition.
+     */
+    initial: boolean;
 }
 /** The text-command state in ioBroker changed — treat as a SubmitText call. */
 export interface AgentTextCommand {
@@ -183,15 +192,16 @@ export interface AgentFirmwareEvent {
  * confirms execution back to Hannah.
  */
 export interface AgentSetState {
-    /** ioBroker state ID to write */
+    /** identifier of the value to write, for ioBroker the state ID */
     stateId: string;
     /** JSON-encoded value */
     value: string;
 }
 /**
- * Hannah requests additional state IDs to be included in the AgentStateUpdate stream.
- * Used by the trigger engine at runtime when triggers reference arbitrary state IDs
- * (e.g. unless.state: "0_userdata.0.feeded") that aren't covered by enum discovery.
+ * Hannah requests additional identifiers (for ioBroker state IDs) to be included in the
+ * AgentStateUpdate stream. Used by the trigger engine at runtime when triggers reference
+ * arbitrary values (e.g. unless.state: "0_userdata.0.feeded") that aren't covered by enum
+ * discovery. The adapter answers every new one with its current raw value, `initial` = true.
  */
 export interface AgentWatchMore {
     stateIds: string[];

package/dist/v2/agent.js

@@ -476,7 +476,7 @@ exports.CaptureControl = {
     },
 };
 function createBaseAgentStateUpdate() {
-    return { stateId: "", value: "", ack: false, ts: 0n };
+    return { stateId: "", value: "", ack: false, ts: 0n, initial: false };
 }
 exports.AgentStateUpdate = {
     encode(message, writer = new wire_1.BinaryWriter()) {
@@ -495,6 +495,9 @@ exports.AgentStateUpdate = {
             }
             writer.uint32(32).int64(message.ts);
         }
+        if (message.initial !== false) {
+            writer.uint32(48).bool(message.initial);
+        }
         return writer;
     },
     decode(input, length) {
@@ -538,6 +541,13 @@ exports.AgentStateUpdate = {
                         message.ts = reader.int64();
                         continue;
                     }
+                    case 6: {
+                        if (tag !== 48) {
+                            break;
+                        }
+                        message.initial = reader.bool();
+                        continue;
+                    }
                 }
                 if ((tag & 7) === 4 || tag === 0) {
                     break;
@@ -559,6 +569,7 @@ exports.AgentStateUpdate = {
         message.value = object.value ?? "";
         message.ack = object.ack ?? false;
         message.ts = (object.ts !== undefined && object.ts !== null) ? BigInt(object.ts) : 0n;
+        message.initial = object.initial ?? false;
         return message;
     },
 };

package/dist/v2/device_control_menu.d.ts

@@ -1,5 +1,5 @@
 import { BinaryReader, BinaryWriter } from "@bufbuild/protobuf/wire";
-import { DeviceClass, Slot, SlotValue } from "./device_model";
+import { DeviceClass, DeviceSubtype, Slot, SlotValue } from "./device_model";
 export declare const protobufPackage = "hannah.v2";
 /**
  * A device for control menus (WebUI, Telegram), in the typed device model: the class
@@ -16,6 +16,8 @@ export interface DeviceInfo {
     /** with current values; Slot.writable says what a menu may offer */
     slots: Slot[];
     available: boolean;
+    /** TypedDevice.subtype, e.g. window or door for a contact */
+    subtype: DeviceSubtype;
 }
 export interface RoomInfo {
     /** room_id (lowercase), e.g. "wohnzimmer" */

package/dist/v2/device_control_menu.js

@@ -11,7 +11,7 @@ const wire_1 = require("@bufbuild/protobuf/wire");
 const device_model_1 = require("./device_model");
 exports.protobufPackage = "hannah.v2";
 function createBaseDeviceInfo() {
-    return { id: "", name: "", deviceClass: 0, slots: [], available: false };
+    return { id: "", name: "", deviceClass: 0, slots: [], available: false, subtype: 0 };
 }
 exports.DeviceInfo = {
     encode(message, writer = new wire_1.BinaryWriter()) {
@@ -30,6 +30,9 @@ exports.DeviceInfo = {
         if (message.available !== false) {
             writer.uint32(96).bool(message.available);
         }
+        if (message.subtype !== 0) {
+            writer.uint32(104).int32(message.subtype);
+        }
         return writer;
     },
     decode(input, length) {
@@ -80,6 +83,13 @@ exports.DeviceInfo = {
                         message.available = reader.bool();
                         continue;
                     }
+                    case 13: {
+                        if (tag !== 104) {
+                            break;
+                        }
+                        message.subtype = reader.int32();
+                        continue;
+                    }
                 }
                 if ((tag & 7) === 4 || tag === 0) {
                     break;
@@ -102,6 +112,7 @@ exports.DeviceInfo = {
         message.deviceClass = object.deviceClass ?? 0;
         message.slots = object.slots?.map((e) => device_model_1.Slot.fromPartial(e)) || [];
         message.available = object.available ?? false;
+        message.subtype = object.subtype ?? 0;
         return message;
     },
 };

package/dist/v2/device_model.d.ts

@@ -16,8 +16,9 @@ export declare enum DeviceClass {
      */
     DEVICE_CLASS_GENERIC_BINARY_SWITCH = 3,
     /**
-     * DEVICE_CLASS_THERMOSTAT - Thermostat/room climate. Slots: TARGET_TEMPERATURE (required), TEMPERATURE,
-     * HUMIDITY, VALVE. Comfort/eco setpoints and similar are not slots.
+     * DEVICE_CLASS_THERMOSTAT - Radiator or room thermostat. Slots: TARGET_TEMPERATURE (required), TEMPERATURE,
+     * HUMIDITY, VALVE. Comfort/eco setpoints and similar are not slots. Units with an
+     * operating mode and a fan are DEVICE_CLASS_CLIMATE.
      */
     DEVICE_CLASS_THERMOSTAT = 4,
     /** DEVICE_CLASS_COVER - Blind, shutter, awning. Slots: POSITION (required), TILT, STOP. */
@@ -34,6 +35,26 @@ export declare enum DeviceClass {
      * (GENERIC_NUMBER / GENERIC_BOOL / GENERIC_TEXT), each with label and unit.
      */
     DEVICE_CLASS_GENERIC = 8,
+    /**
+     * DEVICE_CLASS_CLIMATE - Air conditioner / room climate unit with operating mode and fan. Slots: ON (required),
+     * MODE, TARGET_TEMPERATURE, TEMPERATURE, HUMIDITY, FAN_SPEED. A radiator thermostat
+     * without mode and fan is a THERMOSTAT, not a CLIMATE.
+     */
+    DEVICE_CLASS_CLIMATE = 9,
+    UNRECOGNIZED = -1
+}
+/**
+ * A finer kind within a device class, for the cases where the class alone does not say
+ * what a user means ("the windows" versus "the doors"). Optional: the adapter sets it
+ * where it knows (function, role, type detector), otherwise UNSPECIFIED.
+ */
+export declare enum DeviceSubtype {
+    /** DEVICE_SUBTYPE_UNSPECIFIED - No statement. Hannah Core may fall back to the device name. */
+    DEVICE_SUBTYPE_UNSPECIFIED = 0,
+    /** DEVICE_SUBTYPE_WINDOW - DEVICE_CLASS_CONTACT: window contact. */
+    DEVICE_SUBTYPE_WINDOW = 1,
+    /** DEVICE_SUBTYPE_DOOR - DEVICE_CLASS_CONTACT: door contact. */
+    DEVICE_SUBTYPE_DOOR = 2,
     UNRECOGNIZED = -1
 }
 /**
@@ -66,6 +87,17 @@ export declare enum SlotKind {
     SLOT_KIND_HUMIDITY = 22,
     /** SLOT_KIND_VALVE - number, 0-100 (% open) */
     SLOT_KIND_VALVE = 23,
+    /**
+     * SLOT_KIND_MODE - Operating mode of a CLIMATE device, text, one of: "cool", "heat", "dry", "fan_only",
+     * "auto". The adapter normalizes the device's own values to this vocabulary. The modes the
+     * device really supports are listed in Slot.options.
+     */
+    SLOT_KIND_MODE = 24,
+    /**
+     * SLOT_KIND_FAN_SPEED - Fan level of a CLIMATE device, text, one of: "low", "medium", "high", "auto". Supported
+     * levels are listed in Slot.options.
+     */
+    SLOT_KIND_FAN_SPEED = 25,
     /** SLOT_KIND_POSITION - --- cover --- */
     SLOT_KIND_POSITION = 30,
     /** SLOT_KIND_TILT - number, 0-100 (%) */
@@ -124,6 +156,21 @@ export interface Slot {
      * Unset = not configured, no restriction — distinct from an explicit 0.
      */
     requiredTrustLevel?: number | undefined;
+    /**
+     * The values this slot accepts, for SLOT_KIND_MODE and SLOT_KIND_FAN_SPEED, taken from the
+     * vocabulary of the kind (e.g. a cooling-only unit lists just "cool", "dry", "fan_only").
+     * Empty = no statement, every value of the vocabulary may work. Hannah uses it to answer
+     * honestly when a device cannot do what was asked.
+     */
+    options: string[];
+    /**
+     * How a trigger (and any client building triggers) refers to the value behind this slot: the
+     * identifier the adapter uses for it, for ioBroker the state ID. Opaque to Hannah Core, which
+     * only passes it through (AgentWatchMore, AgentSetState, AgentStateUpdate, trigger conditions
+     * and actions). Empty = not addressable by triggers. Triggers compare against the raw value
+     * of the identified state (and its own scale), not against the normalized `value` above.
+     */
+    identifier: string;
 }
 /** A device, as the adapter derived it from the ioBroker objects (grouping, class, slots). */
 export interface TypedDevice {
@@ -139,6 +186,8 @@ export interface TypedDevice {
     slots: Slot[];
     /** false = device currently unreachable */
     available: boolean;
+    /** finer kind within the class, UNSPECIFIED = no statement */
+    subtype: DeviceSubtype;
 }
 /**
  * All devices the adapter knows. Sent on AgentConnect and whenever the set of devices

package/dist/v2/device_model.js

@@ -5,7 +5,7 @@
 //   protoc               unknown
 // source: hannah/v2/device_model.proto
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SetSlot = exports.DeviceAvailability = exports.SlotUpdate = exports.TypedDeviceSnapshot = exports.TypedDevice = exports.Slot = exports.SlotValue = exports.SlotKind = exports.DeviceClass = exports.protobufPackage = void 0;
+exports.SetSlot = exports.DeviceAvailability = exports.SlotUpdate = exports.TypedDeviceSnapshot = exports.TypedDevice = exports.Slot = exports.SlotValue = exports.SlotKind = exports.DeviceSubtype = exports.DeviceClass = exports.protobufPackage = void 0;
 /* eslint-disable */
 const wire_1 = require("@bufbuild/protobuf/wire");
 exports.protobufPackage = "hannah.v2";
@@ -26,8 +26,9 @@ var DeviceClass;
      */
     DeviceClass[DeviceClass["DEVICE_CLASS_GENERIC_BINARY_SWITCH"] = 3] = "DEVICE_CLASS_GENERIC_BINARY_SWITCH";
     /**
-     * DEVICE_CLASS_THERMOSTAT - Thermostat/room climate. Slots: TARGET_TEMPERATURE (required), TEMPERATURE,
-     * HUMIDITY, VALVE. Comfort/eco setpoints and similar are not slots.
+     * DEVICE_CLASS_THERMOSTAT - Radiator or room thermostat. Slots: TARGET_TEMPERATURE (required), TEMPERATURE,
+     * HUMIDITY, VALVE. Comfort/eco setpoints and similar are not slots. Units with an
+     * operating mode and a fan are DEVICE_CLASS_CLIMATE.
      */
     DeviceClass[DeviceClass["DEVICE_CLASS_THERMOSTAT"] = 4] = "DEVICE_CLASS_THERMOSTAT";
     /** DEVICE_CLASS_COVER - Blind, shutter, awning. Slots: POSITION (required), TILT, STOP. */
@@ -44,8 +45,29 @@ var DeviceClass;
      * (GENERIC_NUMBER / GENERIC_BOOL / GENERIC_TEXT), each with label and unit.
      */
     DeviceClass[DeviceClass["DEVICE_CLASS_GENERIC"] = 8] = "DEVICE_CLASS_GENERIC";
+    /**
+     * DEVICE_CLASS_CLIMATE - Air conditioner / room climate unit with operating mode and fan. Slots: ON (required),
+     * MODE, TARGET_TEMPERATURE, TEMPERATURE, HUMIDITY, FAN_SPEED. A radiator thermostat
+     * without mode and fan is a THERMOSTAT, not a CLIMATE.
+     */
+    DeviceClass[DeviceClass["DEVICE_CLASS_CLIMATE"] = 9] = "DEVICE_CLASS_CLIMATE";
     DeviceClass[DeviceClass["UNRECOGNIZED"] = -1] = "UNRECOGNIZED";
 })(DeviceClass || (exports.DeviceClass = DeviceClass = {}));
+/**
+ * A finer kind within a device class, for the cases where the class alone does not say
+ * what a user means ("the windows" versus "the doors"). Optional: the adapter sets it
+ * where it knows (function, role, type detector), otherwise UNSPECIFIED.
+ */
+var DeviceSubtype;
+(function (DeviceSubtype) {
+    /** DEVICE_SUBTYPE_UNSPECIFIED - No statement. Hannah Core may fall back to the device name. */
+    DeviceSubtype[DeviceSubtype["DEVICE_SUBTYPE_UNSPECIFIED"] = 0] = "DEVICE_SUBTYPE_UNSPECIFIED";
+    /** DEVICE_SUBTYPE_WINDOW - DEVICE_CLASS_CONTACT: window contact. */
+    DeviceSubtype[DeviceSubtype["DEVICE_SUBTYPE_WINDOW"] = 1] = "DEVICE_SUBTYPE_WINDOW";
+    /** DEVICE_SUBTYPE_DOOR - DEVICE_CLASS_CONTACT: door contact. */
+    DeviceSubtype[DeviceSubtype["DEVICE_SUBTYPE_DOOR"] = 2] = "DEVICE_SUBTYPE_DOOR";
+    DeviceSubtype[DeviceSubtype["UNRECOGNIZED"] = -1] = "UNRECOGNIZED";
+})(DeviceSubtype || (exports.DeviceSubtype = DeviceSubtype = {}));
 /**
  * What a slot means, and therefore which scale and unit its value has. The adapter
  * normalizes every value to exactly this scale; Core relies on it.
@@ -77,6 +99,17 @@ var SlotKind;
     SlotKind[SlotKind["SLOT_KIND_HUMIDITY"] = 22] = "SLOT_KIND_HUMIDITY";
     /** SLOT_KIND_VALVE - number, 0-100 (% open) */
     SlotKind[SlotKind["SLOT_KIND_VALVE"] = 23] = "SLOT_KIND_VALVE";
+    /**
+     * SLOT_KIND_MODE - Operating mode of a CLIMATE device, text, one of: "cool", "heat", "dry", "fan_only",
+     * "auto". The adapter normalizes the device's own values to this vocabulary. The modes the
+     * device really supports are listed in Slot.options.
+     */
+    SlotKind[SlotKind["SLOT_KIND_MODE"] = 24] = "SLOT_KIND_MODE";
+    /**
+     * SLOT_KIND_FAN_SPEED - Fan level of a CLIMATE device, text, one of: "low", "medium", "high", "auto". Supported
+     * levels are listed in Slot.options.
+     */
+    SlotKind[SlotKind["SLOT_KIND_FAN_SPEED"] = 25] = "SLOT_KIND_FAN_SPEED";
     /** SLOT_KIND_POSITION - --- cover --- */
     SlotKind[SlotKind["SLOT_KIND_POSITION"] = 30] = "SLOT_KIND_POSITION";
     /** SLOT_KIND_TILT - number, 0-100 (%) */
@@ -188,7 +221,17 @@ exports.SlotValue = {
     },
 };
 function createBaseSlot() {
-    return { slotId: "", kind: 0, value: undefined, writable: false, unit: "", label: "", requiredTrustLevel: undefined };
+    return {
+        slotId: "",
+        kind: 0,
+        value: undefined,
+        writable: false,
+        unit: "",
+        label: "",
+        requiredTrustLevel: undefined,
+        options: [],
+        identifier: "",
+    };
 }
 exports.Slot = {
     encode(message, writer = new wire_1.BinaryWriter()) {
@@ -213,6 +256,12 @@ exports.Slot = {
         if (message.requiredTrustLevel !== undefined) {
             writer.uint32(56).int32(message.requiredTrustLevel);
         }
+        for (const v of message.options) {
+            writer.uint32(66).string(v);
+        }
+        if (message.identifier !== "") {
+            writer.uint32(74).string(message.identifier);
+        }
         return writer;
     },
     decode(input, length) {
@@ -277,6 +326,20 @@ exports.Slot = {
                         message.requiredTrustLevel = reader.int32();
                         continue;
                     }
+                    case 8: {
+                        if (tag !== 66) {
+                            break;
+                        }
+                        message.options.push(reader.string());
+                        continue;
+                    }
+                    case 9: {
+                        if (tag !== 74) {
+                            break;
+                        }
+                        message.identifier = reader.string();
+                        continue;
+                    }
                 }
                 if ((tag & 7) === 4 || tag === 0) {
                     break;
@@ -303,11 +366,13 @@ exports.Slot = {
         message.unit = object.unit ?? "";
         message.label = object.label ?? "";
         message.requiredTrustLevel = object.requiredTrustLevel ?? undefined;
+        message.options = object.options?.map((e) => e) || [];
+        message.identifier = object.identifier ?? "";
         return message;
     },
 };
 function createBaseTypedDevice() {
-    return { deviceId: "", name: "", room: "", floor: "", deviceClass: 0, slots: [], available: false };
+    return { deviceId: "", name: "", room: "", floor: "", deviceClass: 0, slots: [], available: false, subtype: 0 };
 }
 exports.TypedDevice = {
     encode(message, writer = new wire_1.BinaryWriter()) {
@@ -332,6 +397,9 @@ exports.TypedDevice = {
         if (message.available !== false) {
             writer.uint32(56).bool(message.available);
         }
+        if (message.subtype !== 0) {
+            writer.uint32(64).int32(message.subtype);
+        }
         return writer;
     },
     decode(input, length) {
@@ -396,6 +464,13 @@ exports.TypedDevice = {
                         message.available = reader.bool();
                         continue;
                     }
+                    case 8: {
+                        if (tag !== 64) {
+                            break;
+                        }
+                        message.subtype = reader.int32();
+                        continue;
+                    }
                 }
                 if ((tag & 7) === 4 || tag === 0) {
                     break;
@@ -420,6 +495,7 @@ exports.TypedDevice = {
         message.deviceClass = object.deviceClass ?? 0;
         message.slots = object.slots?.map((e) => exports.Slot.fromPartial(e)) || [];
         message.available = object.available ?? false;
+        message.subtype = object.subtype ?? 0;
         return message;
     },
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m1kad0/hannah-proto",
-  "version": "5.0.0",
+  "version": "5.2.0",
   "description": "Generated TypeScript gRPC-js client stubs for the Hannah voice assistant proto schema",
   "license": "UNLICENSED",
   "main": "dist/index.js",
@@ -22,7 +22,7 @@
     "@grpc/grpc-js": "^1.14.4"
   },
   "devDependencies": {
-    "@grpc/grpc-js": "1.14.4",
+    "@grpc/grpc-js": "1.14.5",
     "ts-proto": "2.12.1",
     "typescript": "7.0.2"
   },