@kusinta/iot-schema 0.1.0-beta.9 → 0.2.0-beta.2

package/src/kusinta/iot/device/v1/descriptor_pb.js

@@ -6,12 +6,13 @@ import { fileDesc, messageDesc } from "@bufbuild/protobuf/codegenv2";
 import { file_google_protobuf_timestamp } from "@bufbuild/protobuf/wkt";
 import { file_kusinta_iot_common_v1_types } from "../../common/v1/types_pb.js";
 import { file_kusinta_iot_identity_v1_identity } from "../../identity/v1/identity_pb.js";
+import { file_kusinta_iot_vendor_homematic_v1_homematic } from "../../vendor/homematic/v1/homematic_pb.js";
 
 /**
  * Describes the file kusinta/iot/device/v1/descriptor.proto.
  */
 export const file_kusinta_iot_device_v1_descriptor = /*@__PURE__*/
-  fileDesc("CiZrdXNpbnRhL2lvdC9kZXZpY2UvdjEvZGVzY3JpcHRvci5wcm90bxIVa3VzaW50YS5pb3QuZGV2aWNlLnYxIv0EChBEZXZpY2VEZXNjcmlwdG9yEjQKCWRldmljZV9pZBgBIAEoCzIhLmt1c2ludGEuaW90LmlkZW50aXR5LnYxLkRldmljZUlkEh0KFW1hdHRlcl9kZXZpY2VfdHlwZV9pZBgCIAEoDRITCgt2ZW5kb3JfbmFtZRgDIAEoCRIUCgxwcm9kdWN0X25hbWUYBCABKAkSFQoNc2VyaWFsX251bWJlchgFIAEoCRISCgpub2RlX2xhYmVsGAYgASgJEhEKCXZlbmRvcl9pZBgHIAEoDRISCgpwcm9kdWN0X2lkGAggASgNEh8KF2hhcmR3YXJlX3ZlcnNpb25fc3RyaW5nGAkgASgJEh8KF3NvZnR3YXJlX3ZlcnNpb25fc3RyaW5nGAogASgJEjoKDGNvbm5lY3Rvcl9pZBgLIAEoCzIkLmt1c2ludGEuaW90LmlkZW50aXR5LnYxLkNvbm5lY3RvcklkEjIKCHNwYWNlX2lkGAwgASgLMiAua3VzaW50YS5pb3QuaWRlbnRpdHkudjEuU3BhY2VJZBI9Cglvd25lcnNoaXAYDSABKA4yKi5rdXNpbnRhLmlvdC5jb21tb24udjEuRGV2aWNlT3duZXJzaGlwVHlwZRI+CglsaWZlY3ljbGUYDiABKA4yKy5rdXNpbnRhLmlvdC5jb21tb24udjEuRGV2aWNlTGlmZWN5Y2xlU3RhdGUSNgoNb3duZXJfdXNlcl9pZBgPIAEoCzIfLmt1c2ludGEuaW90LmlkZW50aXR5LnYxLlVzZXJJZBIuCgpjbGFpbWVkX2F0GBAgASgLMhouZ29vZ2xlLnByb3RvYnVmLlRpbWVzdGFtcEICSAFiBnByb3RvMw", [file_google_protobuf_timestamp, file_kusinta_iot_common_v1_types, file_kusinta_iot_identity_v1_identity]);
+  fileDesc("CiZrdXNpbnRhL2lvdC9kZXZpY2UvdjEvZGVzY3JpcHRvci5wcm90bxIVa3VzaW50YS5pb3QuZGV2aWNlLnYxIrkGChBEZXZpY2VEZXNjcmlwdG9yEjQKCWRldmljZV9pZBgBIAEoCzIhLmt1c2ludGEuaW90LmlkZW50aXR5LnYxLkRldmljZUlkEhMKC3ZlbmRvcl9uYW1lGAMgASgJEhQKDHByb2R1Y3RfbmFtZRgEIAEoCRIVCg1zZXJpYWxfbnVtYmVyGAUgASgJEhIKCm5vZGVfbGFiZWwYBiABKAkSEQoJdmVuZG9yX2lkGAcgASgNEhIKCnByb2R1Y3RfaWQYCCABKA0SHwoXaGFyZHdhcmVfdmVyc2lvbl9zdHJpbmcYCSABKAkSHwoXc29mdHdhcmVfdmVyc2lvbl9zdHJpbmcYCiABKAkSOgoMY29ubmVjdG9yX2lkGAsgASgLMiQua3VzaW50YS5pb3QuaWRlbnRpdHkudjEuQ29ubmVjdG9ySWQSMgoIc3BhY2VfaWQYDCABKAsyIC5rdXNpbnRhLmlvdC5pZGVudGl0eS52MS5TcGFjZUlkEj0KCW93bmVyc2hpcBgNIAEoDjIqLmt1c2ludGEuaW90LmNvbW1vbi52MS5EZXZpY2VPd25lcnNoaXBUeXBlEj4KCWxpZmVjeWNsZRgOIAEoDjIrLmt1c2ludGEuaW90LmNvbW1vbi52MS5EZXZpY2VMaWZlY3ljbGVTdGF0ZRI2Cg1vd25lcl91c2VyX2lkGA8gASgLMh8ua3VzaW50YS5pb3QuaWRlbnRpdHkudjEuVXNlcklkEi4KCmNsYWltZWRfYXQYECABKAsyGi5nb29nbGUucHJvdG9idWYuVGltZXN0YW1wEjoKCmJyaWRnZWRfYnkYEyABKAsyIS5rdXNpbnRhLmlvdC5pZGVudGl0eS52MS5EZXZpY2VJZEgBiAEBEk0KCWhvbWVtYXRpYxgSIAEoCzI4Lmt1c2ludGEuaW90LnZlbmRvci5ob21lbWF0aWMudjEuSG9tZW1hdGljRGV2aWNlSWRlbnRpdHlIAEIRCg92ZW5kb3JfaWRlbnRpdHlCDQoLX2JyaWRnZWRfYnlKBAgCEANKBAgREBJSFW1hdHRlcl9kZXZpY2VfdHlwZV9pZFIJZW5kcG9pbnRzQgJIAWIGcHJvdG8z", [file_google_protobuf_timestamp, file_kusinta_iot_common_v1_types, file_kusinta_iot_identity_v1_identity, file_kusinta_iot_vendor_homematic_v1_homematic]);
 
 /**
  * Describes the message kusinta.iot.device.v1.DeviceDescriptor.

package/src/kusinta/iot/device/v1/device_event_pb.d.ts

@@ -0,0 +1,162 @@
+// @generated by protoc-gen-es v2.12.0 with parameter "target=js+dts,import_extension=js"
+// @generated from file kusinta/iot/device/v1/device_event.proto (package kusinta.iot.device.v1, syntax proto3)
+/* eslint-disable */
+
+import type { GenEnum, GenFile, GenMessage } from "@bufbuild/protobuf/codegenv2";
+import type { Message } from "@bufbuild/protobuf";
+import type { DeviceId } from "../../identity/v1/identity_pb.js";
+import type { Timestamp } from "@bufbuild/protobuf/wkt";
+import type { AttributeValue } from "./cluster_state_pb.js";
+
+/**
+ * Describes the file kusinta/iot/device/v1/device_event.proto.
+ */
+export declare const file_kusinta_iot_device_v1_device_event: GenFile;
+
+/**
+ * Something that HAPPENED on a device, as opposed to what a device currently IS.
+ *
+ * PropertyUpdate answers "what is the lock's state now" — latest wins, order does not
+ * matter, a missed one is corrected by the next. DeviceEvent answers "what happened to the
+ * lock" — each is a distinct occurrence, order matters, and a missed one is gone unless it
+ * is fetched by its number. Matter models both for the same reason, and neither substitutes
+ * for the other: a lock's LockState attribute cannot say who unlocked it, with what
+ * credential, at what time, and an event log cannot cheaply answer what the state is now.
+ *
+ * This is the audit surface. In a building with several residents sharing a device, "the
+ * door is unlocked" and "this credential unlocked the door at 14:02" are different
+ * questions with different consumers.
+ *
+ * Events do NOT feed Device.endpoints. A consumer must not merge an event into a properties
+ * field or a ClusterState — an event's data is its own payload, not an attribute value, and
+ * the attribute it relates to reports separately. The resolution rule in
+ * property_update.proto has nothing to do with events.
+ *
+ * @generated from message kusinta.iot.device.v1.DeviceEvent
+ */
+export declare type DeviceEvent = Message<"kusinta.iot.device.v1.DeviceEvent"> & {
+  /**
+   * @generated from field: kusinta.iot.identity.v1.DeviceId device_id = 1;
+   */
+  deviceId?: DeviceId | undefined;
+
+  /**
+   * Which endpoint emitted it, and which cluster defines it. Required, as for an update.
+   *
+   * @generated from field: optional uint32 endpoint_id = 2;
+   */
+  endpointId?: number | undefined;
+
+  /**
+   * @generated from field: uint32 cluster_id = 3;
+   */
+  clusterId: number;
+
+  /**
+   * The Matter event ID within that cluster.
+   *
+   * @generated from field: uint32 event_id = 4;
+   */
+  eventId: number;
+
+  /**
+   * Matter's EventNumber: monotonically increasing per node, and the reason an event log
+   * can be resumed rather than merely replayed. A consumer that sees a gap knows it missed
+   * something and can say so — the one guarantee a PropertyUpdate stream cannot give.
+   *
+   * Monotonic within one device. Do NOT compare across devices; they are unrelated
+   * sequences.
+   *
+   * @generated from field: uint64 event_number = 5;
+   */
+  eventNumber: bigint;
+
+  /**
+   * When the device says it happened, which is not when the gateway saw it. On a
+   * battery-powered device that wakes on a cycle, the two can differ by minutes.
+   *
+   * @generated from field: google.protobuf.Timestamp timestamp = 6;
+   */
+  timestamp?: Timestamp | undefined;
+
+  /**
+   * @generated from field: kusinta.iot.device.v1.EventPriority priority = 7;
+   */
+  priority: EventPriority;
+
+  /**
+   * The event's own payload. Matter events carry a struct, so this is normally
+   * AttributeValue.struct_value keyed by context tag; a scalar-payload event uses a scalar
+   * case directly.
+   *
+   * @generated from field: kusinta.iot.device.v1.AttributeValue data = 8;
+   */
+  data?: AttributeValue | undefined;
+};
+
+/**
+ * Describes the message kusinta.iot.device.v1.DeviceEvent.
+ * Use `create(DeviceEventSchema)` to create a new message.
+ */
+export declare const DeviceEventSchema: GenMessage<DeviceEvent>;
+
+/**
+ * @generated from message kusinta.iot.device.v1.DeviceEventBatch
+ */
+export declare type DeviceEventBatch = Message<"kusinta.iot.device.v1.DeviceEventBatch"> & {
+  /**
+   * @generated from field: repeated kusinta.iot.device.v1.DeviceEvent events = 1;
+   */
+  events: DeviceEvent[];
+
+  /**
+   * When the gateway received these, as distinct from each event's own timestamp, which is
+   * when the device says it happened. The two differ by however long a sleeping device took
+   * to wake, and for an audit trail both matter: one is what occurred, the other is when
+   * anyone could have known.
+   *
+   * @generated from field: google.protobuf.Timestamp received_at = 2;
+   */
+  receivedAt?: Timestamp | undefined;
+};
+
+/**
+ * Describes the message kusinta.iot.device.v1.DeviceEventBatch.
+ * Use `create(DeviceEventBatchSchema)` to create a new message.
+ */
+export declare const DeviceEventBatchSchema: GenMessage<DeviceEventBatch>;
+
+/**
+ * Matter's event priority. Governs retention and delivery urgency, not severity in a
+ * logging sense: CRITICAL events are retained and delivered with the most effort, DEBUG
+ * with the least.
+ *
+ * @generated from enum kusinta.iot.device.v1.EventPriority
+ */
+export enum EventPriority {
+  /**
+   * @generated from enum value: EVENT_PRIORITY_UNSPECIFIED = 0;
+   */
+  UNSPECIFIED = 0,
+
+  /**
+   * @generated from enum value: EVENT_PRIORITY_DEBUG = 1;
+   */
+  DEBUG = 1,
+
+  /**
+   * @generated from enum value: EVENT_PRIORITY_INFO = 2;
+   */
+  INFO = 2,
+
+  /**
+   * @generated from enum value: EVENT_PRIORITY_CRITICAL = 3;
+   */
+  CRITICAL = 3,
+}
+
+/**
+ * Describes the enum kusinta.iot.device.v1.EventPriority.
+ */
+export declare const EventPrioritySchema: GenEnum<EventPriority>;
+

package/src/kusinta/iot/device/v1/device_event_pb.js

@@ -0,0 +1,45 @@
+// @generated by protoc-gen-es v2.12.0 with parameter "target=js+dts,import_extension=js"
+// @generated from file kusinta/iot/device/v1/device_event.proto (package kusinta.iot.device.v1, syntax proto3)
+/* eslint-disable */
+
+import { enumDesc, fileDesc, messageDesc, tsEnum } from "@bufbuild/protobuf/codegenv2";
+import { file_google_protobuf_timestamp } from "@bufbuild/protobuf/wkt";
+import { file_kusinta_iot_device_v1_cluster_state } from "./cluster_state_pb.js";
+import { file_kusinta_iot_identity_v1_identity } from "../../identity/v1/identity_pb.js";
+
+/**
+ * Describes the file kusinta/iot/device/v1/device_event.proto.
+ */
+export const file_kusinta_iot_device_v1_device_event = /*@__PURE__*/
+  fileDesc("CihrdXNpbnRhL2lvdC9kZXZpY2UvdjEvZGV2aWNlX2V2ZW50LnByb3RvEhVrdXNpbnRhLmlvdC5kZXZpY2UudjEixQIKC0RldmljZUV2ZW50EjQKCWRldmljZV9pZBgBIAEoCzIhLmt1c2ludGEuaW90LmlkZW50aXR5LnYxLkRldmljZUlkEhgKC2VuZHBvaW50X2lkGAIgASgNSACIAQESEgoKY2x1c3Rlcl9pZBgDIAEoDRIQCghldmVudF9pZBgEIAEoDRIUCgxldmVudF9udW1iZXIYBSABKAQSLQoJdGltZXN0YW1wGAYgASgLMhouZ29vZ2xlLnByb3RvYnVmLlRpbWVzdGFtcBI2Cghwcmlvcml0eRgHIAEoDjIkLmt1c2ludGEuaW90LmRldmljZS52MS5FdmVudFByaW9yaXR5EjMKBGRhdGEYCCABKAsyJS5rdXNpbnRhLmlvdC5kZXZpY2UudjEuQXR0cmlidXRlVmFsdWVCDgoMX2VuZHBvaW50X2lkIncKEERldmljZUV2ZW50QmF0Y2gSMgoGZXZlbnRzGAEgAygLMiIua3VzaW50YS5pb3QuZGV2aWNlLnYxLkRldmljZUV2ZW50Ei8KC3JlY2VpdmVkX2F0GAIgASgLMhouZ29vZ2xlLnByb3RvYnVmLlRpbWVzdGFtcCp/Cg1FdmVudFByaW9yaXR5Eh4KGkVWRU5UX1BSSU9SSVRZX1VOU1BFQ0lGSUVEEAASGAoURVZFTlRfUFJJT1JJVFlfREVCVUcQARIXChNFVkVOVF9QUklPUklUWV9JTkZPEAISGwoXRVZFTlRfUFJJT1JJVFlfQ1JJVElDQUwQA0ICSAFiBnByb3RvMw", [file_google_protobuf_timestamp, file_kusinta_iot_device_v1_cluster_state, file_kusinta_iot_identity_v1_identity]);
+
+/**
+ * Describes the message kusinta.iot.device.v1.DeviceEvent.
+ * Use `create(DeviceEventSchema)` to create a new message.
+ */
+export const DeviceEventSchema = /*@__PURE__*/
+  messageDesc(file_kusinta_iot_device_v1_device_event, 0);
+
+/**
+ * Describes the message kusinta.iot.device.v1.DeviceEventBatch.
+ * Use `create(DeviceEventBatchSchema)` to create a new message.
+ */
+export const DeviceEventBatchSchema = /*@__PURE__*/
+  messageDesc(file_kusinta_iot_device_v1_device_event, 1);
+
+/**
+ * Describes the enum kusinta.iot.device.v1.EventPriority.
+ */
+export const EventPrioritySchema = /*@__PURE__*/
+  enumDesc(file_kusinta_iot_device_v1_device_event, 0);
+
+/**
+ * Matter's event priority. Governs retention and delivery urgency, not severity in a
+ * logging sense: CRITICAL events are retained and delivered with the most effort, DEBUG
+ * with the least.
+ *
+ * @generated from enum kusinta.iot.device.v1.EventPriority
+ */
+export const EventPriority = /*@__PURE__*/
+  tsEnum(EventPrioritySchema);
+

package/src/kusinta/iot/device/v1/device_pb.d.ts

@@ -4,9 +4,10 @@
 
 import type { GenFile, GenMessage } from "@bufbuild/protobuf/codegenv2";
 import type { Message } from "@bufbuild/protobuf";
+import type { ColorTemperatureLightProperties, ContactSensorProperties, DimmableLightProperties, DoorLockProperties, EnergySensorProperties, HumiditySensorProperties, OccupancySensorProperties, OnOffLightProperties, PowerSourceProperties, PressureSensorProperties, TemperatureSensorProperties, ThermostatProperties, WindowCoveringProperties } from "./properties_pb.js";
+import type { HmThermostatProps } from "../../vendor/homematic/v1/homematic_pb.js";
+import type { ClusterState } from "./cluster_state_pb.js";
 import type { DeviceDescriptor } from "./descriptor_pb.js";
-import type { ColorTemperatureLightProperties, ContactSensorProperties, DimmableLightProperties, DoorLockProperties, EnergySensorProperties, HumiditySensorProperties, OccupancySensorProperties, OnOffLightProperties, PressureSensorProperties, TemperatureSensorProperties, ThermostatProperties, WindowCoveringProperties } from "./properties_pb.js";
-import type { HomematicVendorExtension } from "../../vendor/homematic/v1/homematic_pb.js";
 import type { Timestamp } from "@bufbuild/protobuf/wkt";
 
 /**
@@ -15,109 +16,234 @@ import type { Timestamp } from "@bufbuild/protobuf/wkt";
 export declare const file_kusinta_iot_device_v1_device: GenFile;
 
 /**
- * Device combines a DeviceDescriptor with a strongly-typed oneof for its current state.
- * Field number convention: 1 = descriptor, 2-49 = standard Matter device types,
- * 50-99 = vendor extensions, 20+ = timestamps.
+ * The state one Matter endpoint reports.
  *
- * @generated from message kusinta.iot.device.v1.Device
+ * Matter nodes present several endpoints, each with its own device type, and real
+ * devices need it — a wall thermostat is a Thermostat AND a Humidity Sensor, a
+ * 4-channel actuator is four On/Off Lights, almost any battery device is also a Power
+ * Source. Endpoints are the only thing that buys; filing, ownership and DeviceId stay
+ * per physical device, so a device is still one row, one claim, one placement.
+ *
+ * Field numbers: 1-2 identity, 3-49 standard Matter device types, 50-99 vendor
+ * extensions.
+ *
+ * endpoint_id is Matter's own endpoint number, and it is scoped to ONE DEVICE — not
+ * global, and nothing coordinates numbering between devices. Endpoint 1 on one valve and
+ * endpoint 1 on another are unrelated; what identifies an endpoint is the pair
+ * (DeviceId, endpoint_id). PropertyUpdate carries device_id for exactly that reason.
+ *
+ * Endpoint 0 is the Matter root node and carries BasicInformation, which DeviceDescriptor
+ * already holds — so 0 never appears here and a producer emitting it is wrong. Device
+ * endpoints are 1..n.
+ *
+ * Two producer obligations, neither enforceable by the schema:
+ *
+ *  1. UNIQUE within the device. Two entries sharing an endpoint_id make step 1 of the
+ *     resolution rule ambiguous, and nothing rejects it.
+ *  2. STABLE for the life of the device. This is the one that bites. Access grants and
+ *     property constraints reference (DeviceId, endpoint_id) — see access/v1/acl.proto —
+ *     so a connector that renumbers across a restart does not fail loudly, it silently
+ *     retargets permissions: a grant on channel 1 starts applying to channel 3. A
+ *     duplicate id produces visible nonsense quickly; renumbering produces a working
+ *     system with the wrong permissions.
+ *
+ * Where the number comes from depends on what is behind the connector. A Matter device
+ * declares its own: endpoint 0's Descriptor cluster carries a PartsList, and each
+ * endpoint's Descriptor a DeviceTypeList. A bridged non-Matter device has no Matter
+ * endpoints at all, so the connector must synthesise them — derive from something the
+ * upstream system holds stable, typically its own channel number, never from enumeration
+ * order.
+ *
+ * A typed case and the generic clusters list are not alternatives. An endpoint uses its
+ * typed case for the attributes this schema models and clusters for everything else,
+ * including cluster metadata for the modelled ones. See cluster_state.proto.
+ *
+ * matter_properties and vendor_properties are separate oneofs on purpose. An endpoint
+ * carries its typed Matter properties AND its vendor extension — one oneof spanning both
+ * would make them mutually exclusive, which left every vendor field unreachable in
+ * practice. Named in parallel because they are the same kind of thing addressed through
+ * two annotation namespaces: (matter_attribute) resolves one, (vendor_attribute) the
+ * other. See property_update.proto for the two branches.
+ *
+ * @generated from message kusinta.iot.device.v1.Endpoint
  */
-export declare type Device = Message<"kusinta.iot.device.v1.Device"> & {
+export declare type Endpoint = Message<"kusinta.iot.device.v1.Endpoint"> & {
   /**
-   * @generated from field: kusinta.iot.device.v1.DeviceDescriptor descriptor = 1;
+   * @generated from field: uint32 endpoint_id = 1;
    */
-  descriptor?: DeviceDescriptor | undefined;
+  endpointId: number;
+
+  /**
+   * @generated from field: uint32 matter_device_type_id = 2;
+   */
+  matterDeviceTypeId: number;
 
   /**
-   * @generated from oneof kusinta.iot.device.v1.Device.properties
+   * @generated from oneof kusinta.iot.device.v1.Endpoint.matter_properties
    */
-  properties: {
+  matterProperties: {
     /**
-     * @generated from field: kusinta.iot.device.v1.ThermostatProperties thermostat = 2;
+     * @generated from field: kusinta.iot.device.v1.ThermostatProperties thermostat = 3;
      */
     value: ThermostatProperties;
     case: "thermostat";
   } | {
     /**
-     * @generated from field: kusinta.iot.device.v1.TemperatureSensorProperties temperature_sensor = 3;
+     * @generated from field: kusinta.iot.device.v1.TemperatureSensorProperties temperature_sensor = 4;
      */
     value: TemperatureSensorProperties;
     case: "temperatureSensor";
   } | {
     /**
-     * @generated from field: kusinta.iot.device.v1.HumiditySensorProperties humidity_sensor = 4;
+     * @generated from field: kusinta.iot.device.v1.HumiditySensorProperties humidity_sensor = 5;
      */
     value: HumiditySensorProperties;
     case: "humiditySensor";
   } | {
     /**
-     * @generated from field: kusinta.iot.device.v1.OccupancySensorProperties occupancy_sensor = 5;
+     * @generated from field: kusinta.iot.device.v1.OccupancySensorProperties occupancy_sensor = 6;
      */
     value: OccupancySensorProperties;
     case: "occupancySensor";
   } | {
     /**
-     * @generated from field: kusinta.iot.device.v1.ContactSensorProperties contact_sensor = 6;
+     * @generated from field: kusinta.iot.device.v1.ContactSensorProperties contact_sensor = 7;
      */
     value: ContactSensorProperties;
     case: "contactSensor";
   } | {
     /**
-     * @generated from field: kusinta.iot.device.v1.WindowCoveringProperties window_covering = 7;
+     * @generated from field: kusinta.iot.device.v1.WindowCoveringProperties window_covering = 8;
      */
     value: WindowCoveringProperties;
     case: "windowCovering";
   } | {
     /**
-     * @generated from field: kusinta.iot.device.v1.DoorLockProperties door_lock = 8;
+     * @generated from field: kusinta.iot.device.v1.DoorLockProperties door_lock = 9;
      */
     value: DoorLockProperties;
     case: "doorLock";
   } | {
     /**
-     * @generated from field: kusinta.iot.device.v1.OnOffLightProperties on_off_light = 9;
+     * @generated from field: kusinta.iot.device.v1.OnOffLightProperties on_off_light = 10;
      */
     value: OnOffLightProperties;
     case: "onOffLight";
   } | {
     /**
-     * @generated from field: kusinta.iot.device.v1.DimmableLightProperties dimmable_light = 10;
+     * @generated from field: kusinta.iot.device.v1.DimmableLightProperties dimmable_light = 11;
      */
     value: DimmableLightProperties;
     case: "dimmableLight";
   } | {
     /**
-     * @generated from field: kusinta.iot.device.v1.ColorTemperatureLightProperties color_temp_light = 11;
+     * @generated from field: kusinta.iot.device.v1.ColorTemperatureLightProperties color_temp_light = 12;
      */
     value: ColorTemperatureLightProperties;
     case: "colorTempLight";
   } | {
     /**
-     * @generated from field: kusinta.iot.device.v1.EnergySensorProperties energy_sensor = 12;
+     * @generated from field: kusinta.iot.device.v1.EnergySensorProperties energy_sensor = 13;
      */
     value: EnergySensorProperties;
     case: "energySensor";
   } | {
     /**
-     * @generated from field: kusinta.iot.device.v1.PressureSensorProperties pressure_sensor = 13;
+     * @generated from field: kusinta.iot.device.v1.PressureSensorProperties pressure_sensor = 14;
      */
     value: PressureSensorProperties;
     case: "pressureSensor";
   } | {
     /**
-     * Vendor extensions (fields 50-99)
-     *
-     * @generated from field: kusinta.iot.vendor.homematic.v1.HomematicVendorExtension homematic = 50;
+     * @generated from field: kusinta.iot.device.v1.PowerSourceProperties power_source = 15;
      */
-    value: HomematicVendorExtension;
-    case: "homematic";
+    value: PowerSourceProperties;
+    case: "powerSource";
   } | { case: undefined; value?: undefined };
 
   /**
+   * Vendor readings for this endpoint, beside its Matter properties rather than instead
+   * of them. Vendor IDENTITY — who the physical device is — is on DeviceDescriptor.
+   *
+   * @generated from oneof kusinta.iot.device.v1.Endpoint.vendor_properties
+   */
+  vendorProperties: {
+    /**
+     * @generated from field: kusinta.iot.vendor.homematic.v1.HmThermostatProps hm_thermostat = 50;
+     */
+    value: HmThermostatProps;
+    case: "hmThermostat";
+  } | { case: undefined; value?: undefined };
+
+  /**
+   * Every cluster this endpoint hosts: what it supports, and any attribute value that has
+   * no typed field above. This is what makes a device the schema does not model usable
+   * rather than silent — and what carries the optional clusters the Matter specification
+   * lets an endpoint add beyond its device type's set.
+   *
+   * Field 16 rather than a one-byte number: 1-15 are spent on identity and the typed
+   * cases, and a ClusterState's tag is amortised over the attributes it carries.
+   *
+   * @generated from field: repeated kusinta.iot.device.v1.ClusterState clusters = 16;
+   */
+  clusters: ClusterState[];
+};
+
+/**
+ * Describes the message kusinta.iot.device.v1.Endpoint.
+ * Use `create(EndpointSchema)` to create a new message.
+ */
+export declare const EndpointSchema: GenMessage<Endpoint>;
+
+/**
+ * Device is a DeviceDescriptor plus the endpoints it presents.
+ *
+ * It travels on BOTH legs — a connector announces one with connector.v1.DeviceAnnouncement,
+ * and the gateway sends one to the app. One shape everywhere, so the endpoint list has a
+ * single home and nothing has to be kept in step with a parallel copy.
+ *
+ * Resolving an endpoint's device type to a properties case is read from the descriptor via
+ * (matter_device_type), never hard-coded. property_update.proto states the rule normatively;
+ * matter_options.proto defines the annotations.
+ *
+ * An empty endpoints list means the device presents nothing this schema models, or has
+ * reported nothing yet. Keep the Device either way — it exists and belongs in a list.
+ *
+ * @generated from message kusinta.iot.device.v1.Device
+ */
+export declare type Device = Message<"kusinta.iot.device.v1.Device"> & {
+  /**
+   * @generated from field: kusinta.iot.device.v1.DeviceDescriptor descriptor = 1;
+   */
+  descriptor?: DeviceDescriptor | undefined;
+
+  /**
+   * 15-19 are free; 20+ is the timestamp band.
+   *
+   * @generated from field: repeated kusinta.iot.device.v1.Endpoint endpoints = 14;
+   */
+  endpoints: Endpoint[];
+
+  /**
+   * When the gateway last had evidence this device exists and is reachable — the
+   * most recent PropertyUpdate, announcement, or command result concerning it.
+   * Gateway-observed, not connector-reported: no message on either leg carries a
+   * per-device liveness timestamp, so this is as precise as the device's own report
+   * interval. A device that reports every 15 minutes looks stale for 15 minutes.
+   *
+   * Survives a connector reconnect. Losing the route to a device is not evidence the
+   * device is gone, so last_seen keeps its value; only fresh evidence advances it.
+   *
+   * Advisory, for showing staleness in a UI. It is not a removal signal — that is
+   * webrtc.v1.DeviceRemoved, sent only when a connector reports the device gone.
+   *
    * @generated from field: google.protobuf.Timestamp last_seen = 20;
    */
   lastSeen?: Timestamp | undefined;
 
   /**
+   * When any field of this Device last changed value.
+   *
    * @generated from field: google.protobuf.Timestamp last_updated = 21;
    */
   lastUpdated?: Timestamp | undefined;

package/src/kusinta/iot/device/v1/device_pb.js

@@ -4,6 +4,7 @@
 
 import { fileDesc, messageDesc } from "@bufbuild/protobuf/codegenv2";
 import { file_google_protobuf_timestamp } from "@bufbuild/protobuf/wkt";
+import { file_kusinta_iot_device_v1_cluster_state } from "./cluster_state_pb.js";
 import { file_kusinta_iot_device_v1_descriptor } from "./descriptor_pb.js";
 import { file_kusinta_iot_device_v1_properties } from "./properties_pb.js";
 import { file_kusinta_iot_vendor_homematic_v1_homematic } from "../../vendor/homematic/v1/homematic_pb.js";
@@ -12,12 +13,19 @@ import { file_kusinta_iot_vendor_homematic_v1_homematic } from "../../vendor/hom
  * Describes the file kusinta/iot/device/v1/device.proto.
  */
 export const file_kusinta_iot_device_v1_device = /*@__PURE__*/
-  fileDesc("CiJrdXNpbnRhL2lvdC9kZXZpY2UvdjEvZGV2aWNlLnByb3RvEhVrdXNpbnRhLmlvdC5kZXZpY2UudjEigAkKBkRldmljZRI7CgpkZXNjcmlwdG9yGAEgASgLMicua3VzaW50YS5pb3QuZGV2aWNlLnYxLkRldmljZURlc2NyaXB0b3ISQQoKdGhlcm1vc3RhdBgCIAEoCzIrLmt1c2ludGEuaW90LmRldmljZS52MS5UaGVybW9zdGF0UHJvcGVydGllc0gAElAKEnRlbXBlcmF0dXJlX3NlbnNvchgDIAEoCzIyLmt1c2ludGEuaW90LmRldmljZS52MS5UZW1wZXJhdHVyZVNlbnNvclByb3BlcnRpZXNIABJKCg9odW1pZGl0eV9zZW5zb3IYBCABKAsyLy5rdXNpbnRhLmlvdC5kZXZpY2UudjEuSHVtaWRpdHlTZW5zb3JQcm9wZXJ0aWVzSAASTAoQb2NjdXBhbmN5X3NlbnNvchgFIAEoCzIwLmt1c2ludGEuaW90LmRldmljZS52MS5PY2N1cGFuY3lTZW5zb3JQcm9wZXJ0aWVzSAASSAoOY29udGFjdF9zZW5zb3IYBiABKAsyLi5rdXNpbnRhLmlvdC5kZXZpY2UudjEuQ29udGFjdFNlbnNvclByb3BlcnRpZXNIABJKCg93aW5kb3dfY292ZXJpbmcYByABKAsyLy5rdXNpbnRhLmlvdC5kZXZpY2UudjEuV2luZG93Q292ZXJpbmdQcm9wZXJ0aWVzSAASPgoJZG9vcl9sb2NrGAggASgLMikua3VzaW50YS5pb3QuZGV2aWNlLnYxLkRvb3JMb2NrUHJvcGVydGllc0gAEkMKDG9uX29mZl9saWdodBgJIAEoCzIrLmt1c2ludGEuaW90LmRldmljZS52MS5Pbk9mZkxpZ2h0UHJvcGVydGllc0gAEkgKDmRpbW1hYmxlX2xpZ2h0GAogASgLMi4ua3VzaW50YS5pb3QuZGV2aWNlLnYxLkRpbW1hYmxlTGlnaHRQcm9wZXJ0aWVzSAASUgoQY29sb3JfdGVtcF9saWdodBgLIAEoCzI2Lmt1c2ludGEuaW90LmRldmljZS52MS5Db2xvclRlbXBlcmF0dXJlTGlnaHRQcm9wZXJ0aWVzSAASRgoNZW5lcmd5X3NlbnNvchgMIAEoCzItLmt1c2ludGEuaW90LmRldmljZS52MS5FbmVyZ3lTZW5zb3JQcm9wZXJ0aWVzSAASSgoPcHJlc3N1cmVfc2Vuc29yGA0gASgLMi8ua3VzaW50YS5pb3QuZGV2aWNlLnYxLlByZXNzdXJlU2Vuc29yUHJvcGVydGllc0gAEk4KCWhvbWVtYXRpYxgyIAEoCzI5Lmt1c2ludGEuaW90LnZlbmRvci5ob21lbWF0aWMudjEuSG9tZW1hdGljVmVuZG9yRXh0ZW5zaW9uSAASLQoJbGFzdF9zZWVuGBQgASgLMhouZ29vZ2xlLnByb3RvYnVmLlRpbWVzdGFtcBIwCgxsYXN0X3VwZGF0ZWQYFSABKAsyGi5nb29nbGUucHJvdG9idWYuVGltZXN0YW1wQgwKCnByb3BlcnRpZXNCAkgBYgZwcm90bzM", [file_google_protobuf_timestamp, file_kusinta_iot_device_v1_descriptor, file_kusinta_iot_device_v1_properties, file_kusinta_iot_vendor_homematic_v1_homematic]);
+  fileDesc("CiJrdXNpbnRhL2lvdC9kZXZpY2UvdjEvZGV2aWNlLnByb3RvEhVrdXNpbnRhLmlvdC5kZXZpY2UudjEirgkKCEVuZHBvaW50EhMKC2VuZHBvaW50X2lkGAEgASgNEh0KFW1hdHRlcl9kZXZpY2VfdHlwZV9pZBgCIAEoDRJBCgp0aGVybW9zdGF0GAMgASgLMisua3VzaW50YS5pb3QuZGV2aWNlLnYxLlRoZXJtb3N0YXRQcm9wZXJ0aWVzSAASUAoSdGVtcGVyYXR1cmVfc2Vuc29yGAQgASgLMjIua3VzaW50YS5pb3QuZGV2aWNlLnYxLlRlbXBlcmF0dXJlU2Vuc29yUHJvcGVydGllc0gAEkoKD2h1bWlkaXR5X3NlbnNvchgFIAEoCzIvLmt1c2ludGEuaW90LmRldmljZS52MS5IdW1pZGl0eVNlbnNvclByb3BlcnRpZXNIABJMChBvY2N1cGFuY3lfc2Vuc29yGAYgASgLMjAua3VzaW50YS5pb3QuZGV2aWNlLnYxLk9jY3VwYW5jeVNlbnNvclByb3BlcnRpZXNIABJICg5jb250YWN0X3NlbnNvchgHIAEoCzIuLmt1c2ludGEuaW90LmRldmljZS52MS5Db250YWN0U2Vuc29yUHJvcGVydGllc0gAEkoKD3dpbmRvd19jb3ZlcmluZxgIIAEoCzIvLmt1c2ludGEuaW90LmRldmljZS52MS5XaW5kb3dDb3ZlcmluZ1Byb3BlcnRpZXNIABI+Cglkb29yX2xvY2sYCSABKAsyKS5rdXNpbnRhLmlvdC5kZXZpY2UudjEuRG9vckxvY2tQcm9wZXJ0aWVzSAASQwoMb25fb2ZmX2xpZ2h0GAogASgLMisua3VzaW50YS5pb3QuZGV2aWNlLnYxLk9uT2ZmTGlnaHRQcm9wZXJ0aWVzSAASSAoOZGltbWFibGVfbGlnaHQYCyABKAsyLi5rdXNpbnRhLmlvdC5kZXZpY2UudjEuRGltbWFibGVMaWdodFByb3BlcnRpZXNIABJSChBjb2xvcl90ZW1wX2xpZ2h0GAwgASgLMjYua3VzaW50YS5pb3QuZGV2aWNlLnYxLkNvbG9yVGVtcGVyYXR1cmVMaWdodFByb3BlcnRpZXNIABJGCg1lbmVyZ3lfc2Vuc29yGA0gASgLMi0ua3VzaW50YS5pb3QuZGV2aWNlLnYxLkVuZXJneVNlbnNvclByb3BlcnRpZXNIABJKCg9wcmVzc3VyZV9zZW5zb3IYDiABKAsyLy5rdXNpbnRhLmlvdC5kZXZpY2UudjEuUHJlc3N1cmVTZW5zb3JQcm9wZXJ0aWVzSAASRAoMcG93ZXJfc291cmNlGA8gASgLMiwua3VzaW50YS5pb3QuZGV2aWNlLnYxLlBvd2VyU291cmNlUHJvcGVydGllc0gAEksKDWhtX3RoZXJtb3N0YXQYMiABKAsyMi5rdXNpbnRhLmlvdC52ZW5kb3IuaG9tZW1hdGljLnYxLkhtVGhlcm1vc3RhdFByb3BzSAESNQoIY2x1c3RlcnMYECADKAsyIy5rdXNpbnRhLmlvdC5kZXZpY2UudjEuQ2x1c3RlclN0YXRlQhMKEW1hdHRlcl9wcm9wZXJ0aWVzQhMKEXZlbmRvcl9wcm9wZXJ0aWVzIrADCgZEZXZpY2USOwoKZGVzY3JpcHRvchgBIAEoCzInLmt1c2ludGEuaW90LmRldmljZS52MS5EZXZpY2VEZXNjcmlwdG9yEjIKCWVuZHBvaW50cxgOIAMoCzIfLmt1c2ludGEuaW90LmRldmljZS52MS5FbmRwb2ludBItCglsYXN0X3NlZW4YFCABKAsyGi5nb29nbGUucHJvdG9idWYuVGltZXN0YW1wEjAKDGxhc3RfdXBkYXRlZBgVIAEoCzIaLmdvb2dsZS5wcm90b2J1Zi5UaW1lc3RhbXBKBAgCEA5KBAgyEDNSCnRoZXJtb3N0YXRSEnRlbXBlcmF0dXJlX3NlbnNvclIPaHVtaWRpdHlfc2Vuc29yUhBvY2N1cGFuY3lfc2Vuc29yUg5jb250YWN0X3NlbnNvclIPd2luZG93X2NvdmVyaW5nUglkb29yX2xvY2tSDG9uX29mZl9saWdodFIOZGltbWFibGVfbGlnaHRSEGNvbG9yX3RlbXBfbGlnaHRSDWVuZXJneV9zZW5zb3JSD3ByZXNzdXJlX3NlbnNvclIJaG9tZW1hdGljQgJIAWIGcHJvdG8z", [file_google_protobuf_timestamp, file_kusinta_iot_device_v1_cluster_state, file_kusinta_iot_device_v1_descriptor, file_kusinta_iot_device_v1_properties, file_kusinta_iot_vendor_homematic_v1_homematic]);
+
+/**
+ * Describes the message kusinta.iot.device.v1.Endpoint.
+ * Use `create(EndpointSchema)` to create a new message.
+ */
+export const EndpointSchema = /*@__PURE__*/
+  messageDesc(file_kusinta_iot_device_v1_device, 0);
 
 /**
  * Describes the message kusinta.iot.device.v1.Device.
  * Use `create(DeviceSchema)` to create a new message.
  */
 export const DeviceSchema = /*@__PURE__*/
-  messageDesc(file_kusinta_iot_device_v1_device, 0);
+  messageDesc(file_kusinta_iot_device_v1_device, 1);
 

package/src/kusinta/iot/device/v1/matter_options_pb.d.ts

@@ -0,0 +1,84 @@
+// @generated by protoc-gen-es v2.12.0 with parameter "target=js+dts,import_extension=js"
+// @generated from file kusinta/iot/device/v1/matter_options.proto (package kusinta.iot.device.v1, syntax proto3)
+/* eslint-disable */
+
+import type { GenExtension, GenFile } from "@bufbuild/protobuf/codegenv2";
+import type { FieldOptions, MessageOptions } from "@bufbuild/protobuf/wkt";
+
+/**
+ * Describes the file kusinta/iot/device/v1/matter_options.proto.
+ */
+export declare const file_kusinta_iot_device_v1_matter_options: GenFile;
+
+/**
+ * The Matter cluster this attribute belongs to, e.g. 0x0201 for Thermostat.
+ *
+ * Required alongside matter_attribute because a properties message may span
+ * clusters: DimmableLightProperties.on_off is On/Off (0x0006) while its
+ * current_level is Level Control (0x0008). Matches PropertyUpdate.cluster_id, which
+ * is a uint32 too, so the comparison needs no parsing.
+ *
+ * @generated from extension: uint32 matter_cluster_id = 50001;
+ */
+export declare const matter_cluster_id: GenExtension<FieldOptions, number>;
+
+/**
+ * The Matter attribute name in the spec's own PascalCase, e.g.
+ * "PIROccupiedToUnoccupiedDelay". This is the authoritative spelling; the proto
+ * field name is not derived from it and must not be assumed to be. Matches
+ * PropertyUpdate.attribute_name byte for byte.
+ *
+ * @generated from extension: string matter_attribute = 50002;
+ */
+export declare const matter_attribute: GenExtension<FieldOptions, string>;
+
+/**
+ * The Matter attribute ID within that cluster, e.g. 0x0012 for OccupiedHeatingSetpoint.
+ * This is what a PropertyUpdate resolves on — Matter addresses attributes numerically and
+ * so does this schema, because the generic cluster carrier must address attributes of
+ * clusters this schema does not model, and a vendor-defined cluster has no spec name to
+ * address it by. One scheme rather than two.
+ *
+ * matter_attribute above stays as the authoritative spelling for logs and for anything
+ * rendering an attribute to a human; it is not what resolution matches on.
+ *
+ * @generated from extension: uint32 matter_attribute_id = 50006;
+ */
+export declare const matter_attribute_id: GenExtension<FieldOptions, number>;
+
+/**
+ * The Matter device type IDs this properties message models, e.g. 0x0301 for
+ * Thermostat. Repeated because one shape of properties can serve several device
+ * types; empty on vendor extension messages, which have no Matter device type.
+ *
+ * A device type appears on at most one properties message, so the mapping from
+ * Endpoint.matter_device_type_id to an Endpoint.matter_properties case is a
+ * function.
+ *
+ * @generated from extension: repeated uint32 matter_device_type = 50003;
+ */
+export declare const matter_device_type: GenExtension<MessageOptions, number[]>;
+
+/**
+ * The Matter cluster a command-parameters message belongs to, e.g. 0x0006 for On/Off.
+ * Always exactly one — a parameters message never spans clusters.
+ *
+ * @generated from extension: uint32 matter_command_cluster = 50007;
+ */
+export declare const matter_command_cluster: GenExtension<MessageOptions, number>;
+
+/**
+ * The Matter command ID this parameters message carries arguments for, e.g. 0x00 for
+ * Thermostat's SetpointRaiseLower.
+ *
+ * Singular on purpose. An earlier form was repeated, so that one message could cover
+ * several commands and choose between them by its own fields — but a message that
+ * encodes WHICH command it is duplicates DeviceCommand.matter_command_id, in a second
+ * numbering, with nothing reconciling the two. The parameters carry arguments; the
+ * command ID says which command. A message shared by several commands that take the
+ * same arguments simply omits this and lets matter_command_id stand alone.
+ *
+ * @generated from extension: optional uint32 matter_command_id = 50008;
+ */
+export declare const matter_command_id: GenExtension<MessageOptions, number>;
+