@alteriom/mqtt-schema 0.2.0

package/dist/cjs/validators.d.ts

@@ -0,0 +1,23 @@
+export interface CompileOptions {
+    allErrors?: boolean;
+    strict?: boolean;
+}
+export interface ValidationResult {
+    valid: boolean;
+    errors?: string[];
+}
+export declare const validators: {
+    sensorData: (d: unknown) => ValidationResult;
+    sensorHeartbeat: (d: unknown) => ValidationResult;
+    sensorStatus: (d: unknown) => ValidationResult;
+    gatewayInfo: (d: unknown) => ValidationResult;
+    gatewayMetrics: (d: unknown) => ValidationResult;
+    firmwareStatus: (d: unknown) => ValidationResult;
+    controlResponse: (d: unknown) => ValidationResult;
+};
+export type ValidatorName = keyof typeof validators;
+export declare function validateMessage(kind: ValidatorName, data: unknown): ValidationResult;
+export declare function classifyAndValidate(data: any): {
+    kind?: ValidatorName;
+    result: ValidationResult;
+};

package/dist/cjs/validators.js

@@ -0,0 +1,84 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validators = void 0;
+exports.validateMessage = validateMessage;
+exports.classifyAndValidate = classifyAndValidate;
+const _2020_js_1 = __importDefault(require("ajv/dist/2020.js"));
+const ajv_formats_1 = __importDefault(require("ajv-formats"));
+// Schemas embedded via generated schema_data.ts (copy-schemas.cjs) to avoid filesystem dependency
+const schema_data_js_1 = require("./schema_data.js");
+// Load JSON schemas via createRequire so it works in both CJS and ESM builds without import assertions.
+// Bind embedded schema objects for Ajv consumption
+const envelope = schema_data_js_1.envelope_schema;
+const sensorData = schema_data_js_1.sensor_data_schema;
+const sensorHeartbeat = schema_data_js_1.sensor_heartbeat_schema;
+const sensorStatus = schema_data_js_1.sensor_status_schema;
+const gatewayInfo = schema_data_js_1.gateway_info_schema;
+const gatewayMetrics = schema_data_js_1.gateway_metrics_schema;
+const firmwareStatus = schema_data_js_1.firmware_status_schema;
+const controlResponse = schema_data_js_1.control_response_schema;
+// Lazy singleton Ajv instance so consumers can optionally supply their own if needed.
+let _ajv = null;
+function getAjv(opts) {
+    if (_ajv)
+        return _ajv;
+    _ajv = new _2020_js_1.default({
+        strict: false,
+        allErrors: true,
+        allowUnionTypes: true,
+        ...opts
+    });
+    (0, ajv_formats_1.default)(_ajv);
+    // Add base schema so $ref works for those referencing envelope
+    _ajv.addSchema(envelope, 'envelope.schema.json');
+    return _ajv;
+}
+function toResult(v, data) {
+    const valid = v(data);
+    if (valid)
+        return { valid: true };
+    return { valid: false, errors: (v.errors || []).map((e) => `${e.instancePath || '/'} ${e.message || ''}`.trim()) };
+}
+// Pre-compile validators (they are small; compilation cost negligible for typical web usage)
+const ajv = getAjv();
+const sensorDataValidate = ajv.compile(sensorData);
+const sensorHeartbeatValidate = ajv.compile(sensorHeartbeat);
+const sensorStatusValidate = ajv.compile(sensorStatus);
+const gatewayInfoValidate = ajv.compile(gatewayInfo);
+const gatewayMetricsValidate = ajv.compile(gatewayMetrics);
+const firmwareStatusValidate = ajv.compile(firmwareStatus);
+const controlResponseValidate = ajv.compile(controlResponse);
+exports.validators = {
+    sensorData: (d) => toResult(sensorDataValidate, d),
+    sensorHeartbeat: (d) => toResult(sensorHeartbeatValidate, d),
+    sensorStatus: (d) => toResult(sensorStatusValidate, d),
+    gatewayInfo: (d) => toResult(gatewayInfoValidate, d),
+    gatewayMetrics: (d) => toResult(gatewayMetricsValidate, d),
+    firmwareStatus: (d) => toResult(firmwareStatusValidate, d),
+    controlResponse: (d) => toResult(controlResponseValidate, d)
+};
+function validateMessage(kind, data) {
+    return exports.validators[kind](data);
+}
+// Classifier using lightweight heuristics to pick a schema validator.
+function classifyAndValidate(data) {
+    if (!data || typeof data !== 'object')
+        return { result: { valid: false, errors: ['Not an object'] } };
+    if (data.metrics)
+        return { kind: 'gatewayMetrics', result: exports.validators.gatewayMetrics(data) };
+    if (data.sensors)
+        return { kind: 'sensorData', result: exports.validators.sensorData(data) };
+    if (data.progress_pct !== undefined || (data.status && ['pending', 'downloading', 'flashing', 'verifying', 'rebooting', 'completed', 'failed'].includes(data.status)))
+        return { kind: 'firmwareStatus', result: exports.validators.firmwareStatus(data) };
+    if (data.status && ['online', 'offline', 'updating', 'error'].includes(data.status) && data.device_type === 'sensor')
+        return { kind: 'sensorStatus', result: exports.validators.sensorStatus(data) };
+    if (data.status && ['ok', 'error'].includes(data.status))
+        return { kind: 'controlResponse', result: exports.validators.controlResponse(data) };
+    if (data.device_type === 'gateway')
+        return { kind: 'gatewayInfo', result: exports.validators.gatewayInfo(data) };
+    // Fallback treat as heartbeat attempt
+    return { kind: 'sensorHeartbeat', result: exports.validators.sensorHeartbeat(data) };
+}

package/dist/esm/generated/types.js

@@ -0,0 +1,92 @@
+/**
+ * Auto-generated TypeScript types for Alteriom MQTT Schema v1
+ * Source: docs/mqtt_schema/*.schema.json
+ * Generation Date: 2025-09-20
+ * NOTE: This file is maintained in firmware repo for UI alignment. Changes require coordinated review.
+ */
+// Type Guards ------------------------------------------------
+export function isSensorDataMessage(msg) {
+    return msg && msg.schema_version === 1 && msg.device_type === 'sensor' && typeof msg.sensors === 'object';
+}
+export function isSensorHeartbeatMessage(msg) {
+    return msg && msg.schema_version === 1 && !!msg.device_type && !!msg.timestamp && !('sensors' in msg) && !('metrics' in msg) && !('status' in msg || (msg.status && ['online', 'offline', 'updating', 'error'].includes(msg.status)));
+}
+export function isSensorStatusMessage(msg) {
+    return msg && msg.schema_version === 1 && msg.device_type === 'sensor' && typeof msg.status === 'string' && ['online', 'offline', 'updating', 'error'].includes(msg.status);
+}
+export function isGatewayInfoMessage(msg) {
+    return msg && msg.schema_version === 1 && msg.device_type === 'gateway' && (!msg.metrics) && (!msg.status) && (!msg.progress_pct);
+}
+export function isGatewayMetricsMessage(msg) {
+    return msg && msg.schema_version === 1 && msg.device_type === 'gateway' && typeof msg.metrics === 'object';
+}
+export function isFirmwareStatusMessage(msg) {
+    return msg && msg.schema_version === 1 && typeof msg.status === 'string' && ['pending', 'downloading', 'flashing', 'verifying', 'rebooting', 'completed', 'failed'].includes(msg.status) && (msg.progress_pct === undefined || (typeof msg.progress_pct === 'number' && msg.progress_pct >= 0 && msg.progress_pct <= 100));
+}
+export function isControlResponseMessage(msg) {
+    return msg && msg.schema_version === 1 && (msg.status === 'ok' || msg.status === 'error') && 'timestamp' in msg;
+}
+export function classifyMessage(msg) {
+    if (isSensorDataMessage(msg))
+        return msg;
+    if (isGatewayMetricsMessage(msg))
+        return msg;
+    if (isSensorStatusMessage(msg))
+        return msg;
+    if (isGatewayInfoMessage(msg))
+        return msg;
+    if (isFirmwareStatusMessage(msg))
+        return msg;
+    if (isControlResponseMessage(msg))
+        return msg;
+    if (isSensorHeartbeatMessage(msg))
+        return msg;
+    return null;
+}
+export function basicValidate(msg) {
+    const issues = [];
+    if (msg.schema_version !== 1)
+        issues.push({ reason: 'unsupported_schema' });
+    if (!msg.device_id)
+        issues.push({ field: 'device_id', reason: 'missing' });
+    if (!msg.device_type)
+        issues.push({ field: 'device_type', reason: 'missing' });
+    if (!msg.timestamp)
+        issues.push({ field: 'timestamp', reason: 'missing' });
+    if ('firmware_version' in msg) {
+        if (msg.firmware_version === '')
+            issues.push({ field: 'firmware_version', reason: 'empty' });
+    }
+    else if (!isSensorHeartbeatMessage(msg)) {
+        issues.push({ field: 'firmware_version', reason: 'missing' });
+    }
+    if (isSensorDataMessage(msg)) {
+        if (!Object.keys(msg.sensors).length)
+            issues.push({ field: 'sensors', reason: 'empty' });
+        for (const [k, v] of Object.entries(msg.sensors)) {
+            if (typeof v.value !== 'number')
+                issues.push({ field: `sensors.${k}.value`, reason: 'invalid' });
+            if (v.quality_score !== undefined && (v.quality_score < 0 || v.quality_score > 1))
+                issues.push({ field: `sensors.${k}.quality_score`, reason: 'out_of_range' });
+        }
+    }
+    if (isGatewayMetricsMessage(msg)) {
+        if (typeof msg.metrics.uptime_s !== 'number')
+            issues.push({ field: 'metrics.uptime_s', reason: 'missing' });
+    }
+    if (isFirmwareStatusMessage(msg)) {
+        if (msg.progress_pct !== undefined && (msg.progress_pct < 0 || msg.progress_pct > 100))
+            issues.push({ field: 'progress_pct', reason: 'out_of_range' });
+    }
+    return issues;
+}
+// Example parse wrapper
+export function parseMessage(json) {
+    try {
+        const obj = JSON.parse(json);
+        return classifyMessage(obj);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/esm/index.js

@@ -0,0 +1,7 @@
+// Public export surface for @alteriom/mqtt-schema
+// NOTE: This initial iteration re-exports pre-generated types produced in the firmware repo.
+// In future, generation could move into this package build, but we intentionally depend on
+// the firmware repo as the single source of truth to avoid divergence.
+// Use explicit .js extensions so ESM build (with dist/esm/package.json type=module) treats them as ESM.
+export * from './validators.js';
+export * from './types.js';

package/dist/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/dist/esm/schema_data.js

@@ -0,0 +1,399 @@
+// AUTO-GENERATED by copy-schemas.cjs. Do not edit manually.
+/* eslint-disable */
+export const envelope_schema = {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.alteriom.io/mqtt/v1/envelope.schema.json",
+    "title": "Alteriom MQTT Base Envelope v1",
+    "type": "object",
+    "required": [
+        "schema_version",
+        "device_id",
+        "device_type",
+        "timestamp",
+        "firmware_version"
+    ],
+    "properties": {
+        "schema_version": {
+            "type": "integer",
+            "const": 1
+        },
+        "device_id": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 64,
+            "pattern": "^[A-Za-z0-9_-]+$"
+        },
+        "device_type": {
+            "type": "string",
+            "enum": [
+                "sensor",
+                "gateway"
+            ]
+        },
+        "timestamp": {
+            "type": "string",
+            "format": "date-time"
+        },
+        "firmware_version": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 40
+        },
+        "hardware_version": {
+            "type": "string",
+            "maxLength": 80
+        }
+    },
+    "additionalProperties": true
+};
+export const sensor_data_schema = {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.alteriom.io/mqtt/v1/sensor_data.schema.json",
+    "title": "Sensor Data Message v1",
+    "allOf": [
+        {
+            "$ref": "envelope.schema.json"
+        }
+    ],
+    "type": "object",
+    "required": [
+        "sensors"
+    ],
+    "properties": {
+        "sensors": {
+            "type": "object",
+            "minProperties": 1,
+            "additionalProperties": {
+                "type": "object",
+                "required": [
+                    "value"
+                ],
+                "properties": {
+                    "value": {
+                        "type": [
+                            "number",
+                            "integer"
+                        ]
+                    },
+                    "unit": {
+                        "type": "string"
+                    },
+                    "raw_value": {
+                        "type": [
+                            "number",
+                            "integer"
+                        ]
+                    },
+                    "calibrated_value": {
+                        "type": [
+                            "number",
+                            "integer"
+                        ]
+                    },
+                    "quality_score": {
+                        "type": "number",
+                        "minimum": 0,
+                        "maximum": 1
+                    },
+                    "name": {
+                        "type": "string"
+                    },
+                    "location": {
+                        "type": "string"
+                    },
+                    "additional_data": {
+                        "type": "object"
+                    }
+                },
+                "additionalProperties": false
+            }
+        },
+        "battery_level": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 100
+        },
+        "signal_strength": {
+            "type": "integer",
+            "minimum": -200,
+            "maximum": 0
+        },
+        "additional": {
+            "type": "object"
+        }
+    },
+    "additionalProperties": true
+};
+export const sensor_heartbeat_schema = {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.alteriom.io/mqtt/v1/sensor_heartbeat.schema.json",
+    "title": "Sensor Heartbeat v1",
+    "type": "object",
+    "required": [
+        "schema_version",
+        "device_id",
+        "device_type",
+        "timestamp"
+    ],
+    "properties": {
+        "schema_version": {
+            "type": "integer",
+            "const": 1
+        },
+        "device_id": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 64,
+            "pattern": "^[A-Za-z0-9_-]+$"
+        },
+        "device_type": {
+            "type": "string",
+            "enum": [
+                "sensor",
+                "gateway"
+            ]
+        },
+        "timestamp": {
+            "type": "string",
+            "format": "date-time"
+        }
+    },
+    "additionalProperties": true
+};
+export const sensor_status_schema = {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.alteriom.io/mqtt/v1/sensor_status.schema.json",
+    "title": "Sensor Status v1",
+    "allOf": [
+        {
+            "$ref": "envelope.schema.json"
+        }
+    ],
+    "type": "object",
+    "required": [
+        "status"
+    ],
+    "properties": {
+        "status": {
+            "type": "string",
+            "enum": [
+                "online",
+                "offline",
+                "updating",
+                "error"
+            ]
+        },
+        "battery_level": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 100
+        },
+        "signal_strength": {
+            "type": "integer",
+            "minimum": -200,
+            "maximum": 0
+        }
+    },
+    "additionalProperties": true
+};
+export const gateway_info_schema = {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.alteriom.io/mqtt/v1/gateway_info.schema.json",
+    "title": "Gateway Info v1",
+    "allOf": [
+        {
+            "$ref": "envelope.schema.json"
+        }
+    ],
+    "type": "object",
+    "properties": {
+        "mac_address": {
+            "type": "string",
+            "pattern": "^[0-9A-Fa-f:]{17}$"
+        },
+        "ip_address": {
+            "type": "string",
+            "format": "ipv4"
+        },
+        "capabilities": {
+            "type": "object",
+            "properties": {
+                "max_nodes": {
+                    "type": "integer",
+                    "minimum": 0
+                },
+                "supports_mesh": {
+                    "type": "boolean"
+                },
+                "firmware_update": {
+                    "type": "boolean"
+                }
+            },
+            "additionalProperties": true
+        }
+    },
+    "additionalProperties": true
+};
+export const gateway_metrics_schema = {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.alteriom.io/mqtt/v1/gateway_metrics.schema.json",
+    "title": "Gateway Metrics v1",
+    "allOf": [
+        {
+            "$ref": "envelope.schema.json"
+        }
+    ],
+    "type": "object",
+    "required": [
+        "metrics"
+    ],
+    "properties": {
+        "metrics": {
+            "type": "object",
+            "required": [
+                "uptime_s"
+            ],
+            "properties": {
+                "uptime_s": {
+                    "type": "integer",
+                    "minimum": 0
+                },
+                "cpu_usage_pct": {
+                    "type": "number",
+                    "minimum": 0,
+                    "maximum": 100
+                },
+                "memory_usage_pct": {
+                    "type": "number",
+                    "minimum": 0,
+                    "maximum": 100
+                },
+                "temperature_c": {
+                    "type": "number"
+                },
+                "connected_devices": {
+                    "type": "integer",
+                    "minimum": 0
+                },
+                "mesh_nodes": {
+                    "type": "integer",
+                    "minimum": 0
+                },
+                "packet_loss_pct": {
+                    "type": "number",
+                    "minimum": 0,
+                    "maximum": 100
+                },
+                "data_throughput_kbps": {
+                    "type": "number",
+                    "minimum": 0
+                }
+            },
+            "additionalProperties": true
+        }
+    },
+    "additionalProperties": true
+};
+export const firmware_status_schema = {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.alteriom.io/mqtt/v1/firmware_status.schema.json",
+    "title": "Firmware Update Status v1",
+    "allOf": [
+        {
+            "$ref": "envelope.schema.json"
+        }
+    ],
+    "type": "object",
+    "required": [
+        "status"
+    ],
+    "properties": {
+        "event": {
+            "type": "string"
+        },
+        "from_version": {
+            "type": "string"
+        },
+        "to_version": {
+            "type": "string"
+        },
+        "status": {
+            "type": "string",
+            "enum": [
+                "pending",
+                "downloading",
+                "flashing",
+                "verifying",
+                "rebooting",
+                "completed",
+                "failed"
+            ]
+        },
+        "progress_pct": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 100
+        },
+        "error": {
+            "type": [
+                "string",
+                "null"
+            ]
+        }
+    },
+    "additionalProperties": true
+};
+export const control_response_schema = {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.alteriom.io/mqtt/v1/control_response.schema.json",
+    "title": "Control / Command Response v1",
+    "allOf": [
+        {
+            "$ref": "envelope.schema.json"
+        }
+    ],
+    "type": "object",
+    "required": [
+        "status"
+    ],
+    "properties": {
+        "command": {
+            "type": "string"
+        },
+        "status": {
+            "type": "string",
+            "enum": [
+                "ok",
+                "error"
+            ]
+        },
+        "message": {
+            "type": "string"
+        },
+        "result": {
+            "type": [
+                "object",
+                "array",
+                "string",
+                "number",
+                "boolean",
+                "null"
+            ]
+        }
+    },
+    "additionalProperties": true
+};
+export const mqtt_v1_bundle_json = {
+    "$comment": "Convenience bundle referencing all v1 schema artifact filenames for tooling discovery.",
+    "version": 1,
+    "schemas": {
+        "envelope": "envelope.schema.json",
+        "sensor_data": "sensor_data.schema.json",
+        "sensor_heartbeat": "sensor_heartbeat.schema.json",
+        "sensor_status": "sensor_status.schema.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"
+    }
+};

package/dist/esm/schemas/control_response.schema.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.alteriom.io/mqtt/v1/control_response.schema.json",
+  "title": "Control / Command Response v1",
+  "allOf": [{"$ref": "envelope.schema.json"}],
+  "type": "object",
+  "required": ["status"],
+  "properties": {
+    "command": {"type": "string"},
+    "status": {"type": "string", "enum": ["ok", "error"]},
+    "message": {"type": "string"},
+    "result": {"type": ["object", "array", "string", "number", "boolean", "null"]}
+  },
+  "additionalProperties": true
+}

package/dist/esm/schemas/envelope.schema.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.alteriom.io/mqtt/v1/envelope.schema.json",
+  "title": "Alteriom MQTT Base Envelope v1",
+  "type": "object",
+  "required": ["schema_version", "device_id", "device_type", "timestamp", "firmware_version"],
+  "properties": {
+    "schema_version": {"type": "integer", "const": 1},
+    "device_id": {"type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]+$"},
+    "device_type": {"type": "string", "enum": ["sensor", "gateway"]},
+    "timestamp": {"type": "string", "format": "date-time"},
+    "firmware_version": {"type": "string", "minLength": 1, "maxLength": 40},
+    "hardware_version": {"type": "string", "maxLength": 80}
+  },
+  "additionalProperties": true
+}

package/dist/esm/schemas/firmware_status.schema.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.alteriom.io/mqtt/v1/firmware_status.schema.json",
+  "title": "Firmware Update Status v1",
+  "allOf": [{"$ref": "envelope.schema.json"}],
+  "type": "object",
+  "required": ["status"],
+  "properties": {
+    "event": {"type": "string"},
+    "from_version": {"type": "string"},
+    "to_version": {"type": "string"},
+    "status": {"type": "string", "enum": ["pending", "downloading", "flashing", "verifying", "rebooting", "completed", "failed"]},
+    "progress_pct": {"type": "number", "minimum": 0, "maximum": 100},
+    "error": {"type": ["string", "null"]}
+  },
+  "additionalProperties": true
+}