@alteriom/mqtt-schema 0.3.1 → 0.4.0

package/README.md

@@ -173,6 +173,9 @@ All Ajv validator functions are compiled once at module load. For typical web us
 | gateway_metrics.schema.json | Gateway performance metrics |
 | firmware_status.schema.json | Firmware update lifecycle events |
 | control_response.schema.json | Command/control response messages |
+| mesh_node_list.schema.json | Mesh network node list with status |
+| mesh_topology.schema.json | Mesh network topology and connections |
+| mesh_alert.schema.json | Mesh network alerts and warnings |
 
 ## Exports
 
@@ -187,12 +190,15 @@ All Ajv validator functions are compiled once at module load. For typical web us
 
 ### Validator Keys
 
-`sensorData`, `sensorHeartbeat`, `sensorStatus`, `gatewayInfo`, `gatewayMetrics`, `firmwareStatus`, `controlResponse`
+`sensorData`, `sensorHeartbeat`, `sensorStatus`, `gatewayInfo`, `gatewayMetrics`, `firmwareStatus`, `controlResponse`, `meshNodeList`, `meshTopology`, `meshAlert`
 
 ### Classification Heuristics (Simplified)
 
 - `metrics` → `gatewayMetrics`
 - `sensors` → `sensorData`
+- `nodes` array → `meshNodeList`
+- `connections` array → `meshTopology`
+- `alerts` array → `meshAlert`
 - `progress_pct` or OTA status keywords → `firmwareStatus`
 - `status` + `device_type: sensor` → `sensorStatus`
 - `status: ok|error` (no other match) → `controlResponse`
@@ -226,7 +232,38 @@ Backward‑compatible additions: new optional properties or enums, documented in
 
 Issues & PRs welcome. Ensure firmware repo schemas remain the authoritative source—do not manually edit generated `schema_data.ts`.
 
-**Before opening a PR:** Run `npm run verify` to validate schemas, changelog, and tests.
+### Development Workflow
+
+**Before opening a PR:** Run the comprehensive validation suite:
+
+```bash
+npm run verify        # Schema sync + changelog + fixtures
+npm run verify:all    # Additional schema compilation + OTA manifest validation  
+npm test              # Enhanced fixture validation with detailed reporting
+```
+
+**Available validation scripts:**
+- `npm run test` - Cross-platform fixture validation (CJS/ESM) with enhanced error reporting
+- `npm run test:ota` - OTA manifest fixture validation
+- `npm run verify:schemas` - Ensure schemas are synced from source directory
+- `npm run verify:release` - Check changelog contains current version
+- `npm run verify:all` - Comprehensive schema compilation and fixture validation
+
+### Script Organization
+
+Scripts are organized by category in `package.json`:
+- **Build Scripts**: `build`, `build:cjs`, `build:esm`, `clean`, etc.
+- **Testing & Validation**: `test`, `verify:*`, etc.  
+- **Release Management**: `release:prepare`, `wiki:generate`
+- **Repository Metadata**: `metadata:*` (organization compliance)
+
+### Release Process
+
+See `PUBLISH_CHECKLIST.md` for detailed release procedures. Quick summary:
+1. Update schemas in `docs/mqtt_schema/`
+2. Run `npm run verify` to ensure everything is valid
+3. Use `npm run release:prepare -- patch|minor|major` for version bumping
+4. Follow checklist for tagging and publishing
 
 ## Security
 

package/dist/cjs/generated/types.d.ts

@@ -84,7 +84,49 @@ export interface ControlResponseMessage extends BaseEnvelope {
     message?: string;
     result?: unknown;
 }
-export type AnyMqttV1Message = SensorDataMessage | SensorHeartbeatMessage | SensorStatusMessage | GatewayInfoMessage | GatewayMetricsMessage | FirmwareStatusMessage | ControlResponseMessage;
+export interface MeshNodeListMessage extends BaseEnvelope {
+    device_type: 'gateway';
+    firmware_version: string;
+    nodes: Array<{
+        node_id: string;
+        status?: 'online' | 'offline' | 'unreachable';
+        last_seen?: string;
+        signal_strength?: number;
+        [k: string]: unknown;
+    }>;
+    node_count?: number;
+    mesh_id?: string;
+}
+export interface MeshTopologyMessage extends BaseEnvelope {
+    device_type: 'gateway';
+    firmware_version: string;
+    connections: Array<{
+        from_node: string;
+        to_node: string;
+        link_quality?: number;
+        latency_ms?: number;
+        hop_count?: number;
+        [k: string]: unknown;
+    }>;
+    root_node?: string;
+    total_connections?: number;
+}
+export interface MeshAlertMessage extends BaseEnvelope {
+    device_type: 'gateway';
+    firmware_version: string;
+    alerts: Array<{
+        alert_type: 'low_memory' | 'node_offline' | 'connection_lost' | 'high_latency' | 'packet_loss' | 'firmware_mismatch' | 'configuration_error' | 'security_warning' | 'other';
+        severity: 'critical' | 'warning' | 'info';
+        message: string;
+        node_id?: string;
+        metric_value?: number;
+        threshold?: number;
+        alert_id?: string;
+        [k: string]: unknown;
+    }>;
+    alert_count?: number;
+}
+export type AnyMqttV1Message = SensorDataMessage | SensorHeartbeatMessage | SensorStatusMessage | GatewayInfoMessage | GatewayMetricsMessage | FirmwareStatusMessage | ControlResponseMessage | MeshNodeListMessage | MeshTopologyMessage | MeshAlertMessage;
 export declare function isSensorDataMessage(msg: any): msg is SensorDataMessage;
 export declare function isSensorHeartbeatMessage(msg: any): msg is SensorHeartbeatMessage;
 export declare function isSensorStatusMessage(msg: any): msg is SensorStatusMessage;
@@ -92,6 +134,9 @@ export declare function isGatewayInfoMessage(msg: any): msg is GatewayInfoMessag
 export declare function isGatewayMetricsMessage(msg: any): msg is GatewayMetricsMessage;
 export declare function isFirmwareStatusMessage(msg: any): msg is FirmwareStatusMessage;
 export declare function isControlResponseMessage(msg: any): msg is ControlResponseMessage;
+export declare function isMeshNodeListMessage(msg: any): msg is MeshNodeListMessage;
+export declare function isMeshTopologyMessage(msg: any): msg is MeshTopologyMessage;
+export declare function isMeshAlertMessage(msg: any): msg is MeshAlertMessage;
 export declare function classifyMessage(msg: any): AnyMqttV1Message | null;
 export interface BasicValidationIssue {
     field?: string;

package/dist/cjs/generated/types.js

@@ -13,6 +13,9 @@ exports.isGatewayInfoMessage = isGatewayInfoMessage;
 exports.isGatewayMetricsMessage = isGatewayMetricsMessage;
 exports.isFirmwareStatusMessage = isFirmwareStatusMessage;
 exports.isControlResponseMessage = isControlResponseMessage;
+exports.isMeshNodeListMessage = isMeshNodeListMessage;
+exports.isMeshTopologyMessage = isMeshTopologyMessage;
+exports.isMeshAlertMessage = isMeshAlertMessage;
 exports.classifyMessage = classifyMessage;
 exports.basicValidate = basicValidate;
 exports.parseMessage = parseMessage;
@@ -38,11 +41,26 @@ function isFirmwareStatusMessage(msg) {
 function isControlResponseMessage(msg) {
     return msg && msg.schema_version === 1 && (msg.status === 'ok' || msg.status === 'error') && 'timestamp' in msg;
 }
+function isMeshNodeListMessage(msg) {
+    return msg && msg.schema_version === 1 && msg.device_type === 'gateway' && Array.isArray(msg.nodes);
+}
+function isMeshTopologyMessage(msg) {
+    return msg && msg.schema_version === 1 && msg.device_type === 'gateway' && Array.isArray(msg.connections);
+}
+function isMeshAlertMessage(msg) {
+    return msg && msg.schema_version === 1 && msg.device_type === 'gateway' && Array.isArray(msg.alerts);
+}
 function classifyMessage(msg) {
     if (isSensorDataMessage(msg))
         return msg;
     if (isGatewayMetricsMessage(msg))
         return msg;
+    if (isMeshNodeListMessage(msg))
+        return msg;
+    if (isMeshTopologyMessage(msg))
+        return msg;
+    if (isMeshAlertMessage(msg))
+        return msg;
     if (isSensorStatusMessage(msg))
         return msg;
     if (isGatewayInfoMessage(msg))

package/dist/cjs/schema_data.d.ts

@@ -303,6 +303,172 @@ export declare const control_response_schema: {
     };
     readonly additionalProperties: true;
 };
+export declare const mesh_node_list_schema: {
+    readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+    readonly $id: "https://schemas.alteriom.io/mqtt/v1/mesh_node_list.schema.json";
+    readonly title: "Mesh Node List v1";
+    readonly allOf: readonly [{
+        readonly $ref: "envelope.schema.json";
+    }];
+    readonly type: "object";
+    readonly required: readonly ["nodes"];
+    readonly properties: {
+        readonly nodes: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly required: readonly ["node_id"];
+                readonly properties: {
+                    readonly node_id: {
+                        readonly type: "string";
+                        readonly description: "Unique node identifier";
+                    };
+                    readonly status: {
+                        readonly type: "string";
+                        readonly enum: readonly ["online", "offline", "unreachable"];
+                        readonly description: "Current node status";
+                    };
+                    readonly last_seen: {
+                        readonly type: "string";
+                        readonly format: "date-time";
+                        readonly description: "Last communication timestamp";
+                    };
+                    readonly signal_strength: {
+                        readonly type: "integer";
+                        readonly minimum: -200;
+                        readonly maximum: 0;
+                        readonly description: "Signal strength in dBm";
+                    };
+                };
+                readonly additionalProperties: true;
+            };
+        };
+        readonly node_count: {
+            readonly type: "integer";
+            readonly minimum: 0;
+            readonly description: "Total number of nodes";
+        };
+        readonly mesh_id: {
+            readonly type: "string";
+            readonly description: "Mesh network identifier";
+        };
+    };
+    readonly additionalProperties: true;
+};
+export declare const mesh_topology_schema: {
+    readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+    readonly $id: "https://schemas.alteriom.io/mqtt/v1/mesh_topology.schema.json";
+    readonly title: "Mesh Network Topology v1";
+    readonly allOf: readonly [{
+        readonly $ref: "envelope.schema.json";
+    }];
+    readonly type: "object";
+    readonly required: readonly ["connections"];
+    readonly properties: {
+        readonly connections: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly required: readonly ["from_node", "to_node"];
+                readonly properties: {
+                    readonly from_node: {
+                        readonly type: "string";
+                        readonly description: "Source node ID";
+                    };
+                    readonly to_node: {
+                        readonly type: "string";
+                        readonly description: "Destination node ID";
+                    };
+                    readonly link_quality: {
+                        readonly type: "number";
+                        readonly minimum: 0;
+                        readonly maximum: 1;
+                        readonly description: "Link quality score (0-1)";
+                    };
+                    readonly latency_ms: {
+                        readonly type: "integer";
+                        readonly minimum: 0;
+                        readonly description: "Link latency in milliseconds";
+                    };
+                    readonly hop_count: {
+                        readonly type: "integer";
+                        readonly minimum: 1;
+                        readonly description: "Number of hops in path";
+                    };
+                };
+                readonly additionalProperties: true;
+            };
+        };
+        readonly root_node: {
+            readonly type: "string";
+            readonly description: "Root node ID (gateway/bridge)";
+        };
+        readonly total_connections: {
+            readonly type: "integer";
+            readonly minimum: 0;
+            readonly description: "Total number of connections";
+        };
+    };
+    readonly additionalProperties: true;
+};
+export declare const mesh_alert_schema: {
+    readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+    readonly $id: "https://schemas.alteriom.io/mqtt/v1/mesh_alert.schema.json";
+    readonly title: "Mesh Network Alert v1";
+    readonly allOf: readonly [{
+        readonly $ref: "envelope.schema.json";
+    }];
+    readonly type: "object";
+    readonly required: readonly ["alerts"];
+    readonly properties: {
+        readonly alerts: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly required: readonly ["alert_type", "severity", "message"];
+                readonly properties: {
+                    readonly alert_type: {
+                        readonly type: "string";
+                        readonly enum: readonly ["low_memory", "node_offline", "connection_lost", "high_latency", "packet_loss", "firmware_mismatch", "configuration_error", "security_warning", "other"];
+                        readonly description: "Type of alert";
+                    };
+                    readonly severity: {
+                        readonly type: "string";
+                        readonly enum: readonly ["critical", "warning", "info"];
+                        readonly description: "Alert severity level";
+                    };
+                    readonly message: {
+                        readonly type: "string";
+                        readonly description: "Human-readable alert message";
+                    };
+                    readonly node_id: {
+                        readonly type: "string";
+                        readonly description: "Related node ID (if applicable)";
+                    };
+                    readonly metric_value: {
+                        readonly type: "number";
+                        readonly description: "Related metric value (if applicable)";
+                    };
+                    readonly threshold: {
+                        readonly type: "number";
+                        readonly description: "Threshold that triggered alert";
+                    };
+                    readonly alert_id: {
+                        readonly type: "string";
+                        readonly description: "Unique alert identifier";
+                    };
+                };
+                readonly additionalProperties: true;
+            };
+        };
+        readonly alert_count: {
+            readonly type: "integer";
+            readonly minimum: 0;
+            readonly description: "Total number of active alerts";
+        };
+    };
+    readonly additionalProperties: true;
+};
 export declare const mqtt_v1_bundle_json: {
     readonly $comment: "Convenience bundle referencing all v1 schema artifact filenames for tooling discovery.";
     readonly version: 1;
@@ -315,6 +481,9 @@ export declare const mqtt_v1_bundle_json: {
         readonly gateway_metrics: "gateway_metrics.schema.json";
         readonly firmware_status: "firmware_status.schema.json";
         readonly control_response: "control_response.schema.json";
+        readonly mesh_node_list: "mesh_node_list.schema.json";
+        readonly mesh_topology: "mesh_topology.schema.json";
+        readonly mesh_alert: "mesh_alert.schema.json";
     };
 };
 export declare const ota_ota_manifest_schema: {

package/dist/cjs/schema_data.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ota_ota_manifest_schema = exports.mqtt_v1_bundle_json = exports.control_response_schema = exports.firmware_status_schema = exports.gateway_metrics_schema = exports.gateway_info_schema = exports.sensor_status_schema = exports.sensor_heartbeat_schema = exports.sensor_data_schema = exports.envelope_schema = void 0;
+exports.ota_ota_manifest_schema = exports.mqtt_v1_bundle_json = exports.mesh_alert_schema = exports.mesh_topology_schema = exports.mesh_node_list_schema = exports.control_response_schema = exports.firmware_status_schema = exports.gateway_metrics_schema = exports.gateway_info_schema = exports.sensor_status_schema = exports.sensor_heartbeat_schema = exports.sensor_data_schema = exports.envelope_schema = void 0;
 // AUTO-GENERATED by copy-schemas.cjs. Do not edit manually.
 /* eslint-disable */
 exports.envelope_schema = {
@@ -386,6 +386,211 @@ exports.control_response_schema = {
     },
     "additionalProperties": true
 };
+exports.mesh_node_list_schema = {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.alteriom.io/mqtt/v1/mesh_node_list.schema.json",
+    "title": "Mesh Node List v1",
+    "allOf": [
+        {
+            "$ref": "envelope.schema.json"
+        }
+    ],
+    "type": "object",
+    "required": [
+        "nodes"
+    ],
+    "properties": {
+        "nodes": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "required": [
+                    "node_id"
+                ],
+                "properties": {
+                    "node_id": {
+                        "type": "string",
+                        "description": "Unique node identifier"
+                    },
+                    "status": {
+                        "type": "string",
+                        "enum": [
+                            "online",
+                            "offline",
+                            "unreachable"
+                        ],
+                        "description": "Current node status"
+                    },
+                    "last_seen": {
+                        "type": "string",
+                        "format": "date-time",
+                        "description": "Last communication timestamp"
+                    },
+                    "signal_strength": {
+                        "type": "integer",
+                        "minimum": -200,
+                        "maximum": 0,
+                        "description": "Signal strength in dBm"
+                    }
+                },
+                "additionalProperties": true
+            }
+        },
+        "node_count": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "Total number of nodes"
+        },
+        "mesh_id": {
+            "type": "string",
+            "description": "Mesh network identifier"
+        }
+    },
+    "additionalProperties": true
+};
+exports.mesh_topology_schema = {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.alteriom.io/mqtt/v1/mesh_topology.schema.json",
+    "title": "Mesh Network Topology v1",
+    "allOf": [
+        {
+            "$ref": "envelope.schema.json"
+        }
+    ],
+    "type": "object",
+    "required": [
+        "connections"
+    ],
+    "properties": {
+        "connections": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "required": [
+                    "from_node",
+                    "to_node"
+                ],
+                "properties": {
+                    "from_node": {
+                        "type": "string",
+                        "description": "Source node ID"
+                    },
+                    "to_node": {
+                        "type": "string",
+                        "description": "Destination node ID"
+                    },
+                    "link_quality": {
+                        "type": "number",
+                        "minimum": 0,
+                        "maximum": 1,
+                        "description": "Link quality score (0-1)"
+                    },
+                    "latency_ms": {
+                        "type": "integer",
+                        "minimum": 0,
+                        "description": "Link latency in milliseconds"
+                    },
+                    "hop_count": {
+                        "type": "integer",
+                        "minimum": 1,
+                        "description": "Number of hops in path"
+                    }
+                },
+                "additionalProperties": true
+            }
+        },
+        "root_node": {
+            "type": "string",
+            "description": "Root node ID (gateway/bridge)"
+        },
+        "total_connections": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "Total number of connections"
+        }
+    },
+    "additionalProperties": true
+};
+exports.mesh_alert_schema = {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.alteriom.io/mqtt/v1/mesh_alert.schema.json",
+    "title": "Mesh Network Alert v1",
+    "allOf": [
+        {
+            "$ref": "envelope.schema.json"
+        }
+    ],
+    "type": "object",
+    "required": [
+        "alerts"
+    ],
+    "properties": {
+        "alerts": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "required": [
+                    "alert_type",
+                    "severity",
+                    "message"
+                ],
+                "properties": {
+                    "alert_type": {
+                        "type": "string",
+                        "enum": [
+                            "low_memory",
+                            "node_offline",
+                            "connection_lost",
+                            "high_latency",
+                            "packet_loss",
+                            "firmware_mismatch",
+                            "configuration_error",
+                            "security_warning",
+                            "other"
+                        ],
+                        "description": "Type of alert"
+                    },
+                    "severity": {
+                        "type": "string",
+                        "enum": [
+                            "critical",
+                            "warning",
+                            "info"
+                        ],
+                        "description": "Alert severity level"
+                    },
+                    "message": {
+                        "type": "string",
+                        "description": "Human-readable alert message"
+                    },
+                    "node_id": {
+                        "type": "string",
+                        "description": "Related node ID (if applicable)"
+                    },
+                    "metric_value": {
+                        "type": "number",
+                        "description": "Related metric value (if applicable)"
+                    },
+                    "threshold": {
+                        "type": "number",
+                        "description": "Threshold that triggered alert"
+                    },
+                    "alert_id": {
+                        "type": "string",
+                        "description": "Unique alert identifier"
+                    }
+                },
+                "additionalProperties": true
+            }
+        },
+        "alert_count": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "Total number of active alerts"
+        }
+    },
+    "additionalProperties": true
+};
 exports.mqtt_v1_bundle_json = {
     "$comment": "Convenience bundle referencing all v1 schema artifact filenames for tooling discovery.",
     "version": 1,
@@ -397,7 +602,10 @@ exports.mqtt_v1_bundle_json = {
         "gateway_info": "gateway_info.schema.json",
         "gateway_metrics": "gateway_metrics.schema.json",
         "firmware_status": "firmware_status.schema.json",
-        "control_response": "control_response.schema.json"
+        "control_response": "control_response.schema.json",
+        "mesh_node_list": "mesh_node_list.schema.json",
+        "mesh_topology": "mesh_topology.schema.json",
+        "mesh_alert": "mesh_alert.schema.json"
     }
 };
 exports.ota_ota_manifest_schema = {

package/dist/cjs/schemas/mesh_alert.schema.json

@@ -0,0 +1,66 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.alteriom.io/mqtt/v1/mesh_alert.schema.json",
+  "title": "Mesh Network Alert v1",
+  "allOf": [{"$ref": "envelope.schema.json"}],
+  "type": "object",
+  "required": ["alerts"],
+  "properties": {
+    "alerts": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["alert_type", "severity", "message"],
+        "properties": {
+          "alert_type": {
+            "type": "string",
+            "enum": [
+              "low_memory",
+              "node_offline",
+              "connection_lost",
+              "high_latency",
+              "packet_loss",
+              "firmware_mismatch",
+              "configuration_error",
+              "security_warning",
+              "other"
+            ],
+            "description": "Type of alert"
+          },
+          "severity": {
+            "type": "string",
+            "enum": ["critical", "warning", "info"],
+            "description": "Alert severity level"
+          },
+          "message": {
+            "type": "string",
+            "description": "Human-readable alert message"
+          },
+          "node_id": {
+            "type": "string",
+            "description": "Related node ID (if applicable)"
+          },
+          "metric_value": {
+            "type": "number",
+            "description": "Related metric value (if applicable)"
+          },
+          "threshold": {
+            "type": "number",
+            "description": "Threshold that triggered alert"
+          },
+          "alert_id": {
+            "type": "string",
+            "description": "Unique alert identifier"
+          }
+        },
+        "additionalProperties": true
+      }
+    },
+    "alert_count": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Total number of active alerts"
+    }
+  },
+  "additionalProperties": true
+}