@kusinta/iot-schema 0.1.0-beta.17 → 0.1.0-beta.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kusinta/iot-schema",
-  "version": "0.1.0-beta.17",
+  "version": "0.1.0-beta.19",
   "type": "module",
   "license": "MIT",
   "files": ["src"],
@@ -14,6 +14,7 @@
     "./device":                 "./src/kusinta/iot/device/v1/device_pb.js",
     "./device/descriptor":      "./src/kusinta/iot/device/v1/descriptor_pb.js",
     "./device/properties":      "./src/kusinta/iot/device/v1/properties_pb.js",
+    "./device/matter-options":   "./src/kusinta/iot/device/v1/matter_options_pb.js",
     "./device/property-update": "./src/kusinta/iot/device/v1/property_update_pb.js",
     "./space":                  "./src/kusinta/iot/space/v1/space_pb.js",
     "./access":                 "./src/kusinta/iot/access/v1/acl_pb.js",

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

@@ -19,6 +19,24 @@ export declare const file_kusinta_iot_device_v1_device: GenFile;
  * Field number convention: 1 = descriptor, 2-49 = standard Matter device types,
  * 50-99 = vendor extensions, 20+ = timestamps.
  *
+ * Selecting the properties case
+ *
+ * Each non-vendor case's message type declares the Matter device type it models in
+ * (matter_device_type), so the mapping from DeviceDescriptor.matter_device_type_id to a
+ * case is read from the descriptor rather than hard-coded. See matter_options.proto, and
+ * property_update.proto for the full resolution rule.
+ *
+ * matter_device_type_id stays a bare uint32: a connector must be able to report a device
+ * type this schema does not model. Such a device is legitimate — it exists, it belongs in
+ * a device list, it simply carries no typed properties. A consumer that cannot match the
+ * device type leaves the properties oneof unset and keeps the Device; it MUST NOT drop the
+ * device or substitute a nearby case. An unset oneof therefore means either "not modelled"
+ * or "modelled but nothing reported yet", which are indistinguishable here on purpose;
+ * distinguish them by re-resolving matter_device_type_id if you need to.
+ *
+ * Adding a case: annotate the new *Properties message with its (matter_device_type). A case
+ * without one resolves for nobody.
+ *
  * @generated from message kusinta.iot.device.v1.Device
  */
 export declare type Device = Message<"kusinta.iot.device.v1.Device"> & {
@@ -113,11 +131,25 @@ export declare type Device = Message<"kusinta.iot.device.v1.Device"> & {
   } | { case: undefined; value?: undefined };
 
   /**
+   * 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/matter_options_pb.d.ts

@@ -0,0 +1,46 @@
+// @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_hex
+ * parsed as a hex integer.
+ *
+ * @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 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
+ * DeviceDescriptor.matter_device_type_id to a Device.properties case is a function.
+ *
+ * @generated from extension: repeated uint32 matter_device_type = 50003;
+ */
+export declare const matter_device_type: GenExtension<MessageOptions, number[]>;
+

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

@@ -0,0 +1,50 @@
+// @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 { extDesc, fileDesc } from "@bufbuild/protobuf/codegenv2";
+import { file_google_protobuf_descriptor } from "@bufbuild/protobuf/wkt";
+
+/**
+ * Describes the file kusinta/iot/device/v1/matter_options.proto.
+ */
+export const file_kusinta_iot_device_v1_matter_options = /*@__PURE__*/
+  fileDesc("CiprdXNpbnRhL2lvdC9kZXZpY2UvdjEvbWF0dGVyX29wdGlvbnMucHJvdG8SFWt1c2ludGEuaW90LmRldmljZS52MTpLChFtYXR0ZXJfY2x1c3Rlcl9pZBIdLmdvb2dsZS5wcm90b2J1Zi5GaWVsZE9wdGlvbnMY0YYDIAEoDVIPbWF0dGVyQ2x1c3RlcklkOkoKEG1hdHRlcl9hdHRyaWJ1dGUSHS5nb29nbGUucHJvdG9idWYuRmllbGRPcHRpb25zGNKGAyABKAlSD21hdHRlckF0dHJpYnV0ZTpPChJtYXR0ZXJfZGV2aWNlX3R5cGUSHy5nb29nbGUucHJvdG9idWYuTWVzc2FnZU9wdGlvbnMY04YDIAMoDVIQbWF0dGVyRGV2aWNlVHlwZUICSAFiBnByb3RvMw", [file_google_protobuf_descriptor]);
+
+/**
+ * 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_hex
+ * parsed as a hex integer.
+ *
+ * @generated from extension: uint32 matter_cluster_id = 50001;
+ */
+export const matter_cluster_id = /*@__PURE__*/
+  extDesc(file_kusinta_iot_device_v1_matter_options, 0);
+
+/**
+ * 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 const matter_attribute = /*@__PURE__*/
+  extDesc(file_kusinta_iot_device_v1_matter_options, 1);
+
+/**
+ * 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
+ * DeviceDescriptor.matter_device_type_id to a Device.properties case is a function.
+ *
+ * @generated from extension: repeated uint32 matter_device_type = 50003;
+ */
+export const matter_device_type = /*@__PURE__*/
+  extDesc(file_kusinta_iot_device_v1_matter_options, 2);
+