@alteriom/mqtt-schema 0.2.0

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

@@ -0,0 +1,21 @@
+{
+  "$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
+}

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

@@ -0,0 +1,26 @@
+{
+  "$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
+}

package/dist/esm/schemas/mqtt_v1_bundle.json

@@ -0,0 +1,14 @@
+{
+  "$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/sensor_data.schema.json

@@ -0,0 +1,33 @@
+{
+  "$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
+}

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

@@ -0,0 +1,14 @@
+{
+  "$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
+}

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

@@ -0,0 +1,14 @@
+{
+  "$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
+}

package/dist/esm/schemas/validation_rules.md

@@ -0,0 +1,44 @@
+# Validation Rules (Operational Layer)
+
+This file captures dynamic / contextual validation that is OUTSIDE pure structural JSON Schema constraints.
+
+## Timing & Rate
+- Future timestamp drift: reject if > 5s ahead of server reference.
+- Heartbeat interval recommended 30s; backend may rate-limit <10s.
+- Sensor data soft min 30s unless negotiated high-frequency mode.
+
+## Heartbeat Firmware Version Exception
+- Only heartbeat topic may omit `firmware_version` when unchanged.
+- All other topics require the field.
+
+## Forbidden / Drop Conditions
+| Reason | Condition |
+|--------|----------|
+| missing_fields | Required base fields absent (heartbeat firmware exception applied). |
+| invalid_timestamp | Non-ISO 8601 / unparseable timestamp. |
+| deprecated_keys | Usage of forbidden alias keys (f, fw, ver, version, u, up, rssi). |
+| invalid_sensor_entry | Sensor object missing `value` key. |
+| future_drift | Timestamp too far in future (>5s). |
+| out_of_range | battery_level not 0-100 OR quality_score not 0-1. |
+| invalid_numeric | Non-numeric where numeric expected. |
+| spec_violation | Generic fallback after failed internal validation. |
+
+## Sensor Object Semantics
+- `value` REQUIRED.
+- `unit`, `raw_value`, `calibrated_value`, `quality_score`, `name`, `location`, `additional_data` OPTIONAL.
+- If `quality_score` present must be 0.0–1.0 inclusive.
+
+## Metrics Constraints
+- Gateway metrics MUST appear under `metrics` (never at top-level).
+- Required minimal metric: `uptime_s`.
+
+## Firmware Update Status
+- `status` must be one of: pending, downloading, flashing, verifying, rebooting, completed, failed.
+- `progress_pct` (if present) must be 0–100.
+
+## Extensibility
+- Unknown top-level keys tolerated (future evolution) except if they collide with any deprecated alias or reserved future keys announced in CHANGELOG.
+
+## Versioning
+- Current `schema_version`: 1
+- Additions remain optional; breaking changes introduce new schema set.

package/dist/esm/types.js

@@ -0,0 +1,7 @@
+// Re-export the generated firmware repo types by importing relative path.
+// This keeps single source of truth while enabling package consumers to import from package root.
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// Re-export generated types copied during prebuild from firmware docs into src/generated/types.ts
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore
+export * from './generated/types.js';

package/dist/esm/validators.js

@@ -0,0 +1,76 @@
+import Ajv from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+// Schemas embedded via generated schema_data.ts (copy-schemas.cjs) to avoid filesystem dependency
+import { envelope_schema, sensor_data_schema, sensor_heartbeat_schema, sensor_status_schema, gateway_info_schema, gateway_metrics_schema, firmware_status_schema, control_response_schema } from './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 = envelope_schema;
+const sensorData = sensor_data_schema;
+const sensorHeartbeat = sensor_heartbeat_schema;
+const sensorStatus = sensor_status_schema;
+const gatewayInfo = gateway_info_schema;
+const gatewayMetrics = gateway_metrics_schema;
+const firmwareStatus = firmware_status_schema;
+const controlResponse = 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 Ajv({
+        strict: false,
+        allErrors: true,
+        allowUnionTypes: true,
+        ...opts
+    });
+    addFormats(_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);
+export const 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)
+};
+export function validateMessage(kind, data) {
+    return validators[kind](data);
+}
+// Classifier using lightweight heuristics to pick a schema validator.
+export function classifyAndValidate(data) {
+    if (!data || typeof data !== 'object')
+        return { result: { valid: false, errors: ['Not an object'] } };
+    if (data.metrics)
+        return { kind: 'gatewayMetrics', result: validators.gatewayMetrics(data) };
+    if (data.sensors)
+        return { kind: 'sensorData', result: validators.sensorData(data) };
+    if (data.progress_pct !== undefined || (data.status && ['pending', 'downloading', 'flashing', 'verifying', 'rebooting', 'completed', 'failed'].includes(data.status)))
+        return { kind: 'firmwareStatus', result: validators.firmwareStatus(data) };
+    if (data.status && ['online', 'offline', 'updating', 'error'].includes(data.status) && data.device_type === 'sensor')
+        return { kind: 'sensorStatus', result: validators.sensorStatus(data) };
+    if (data.status && ['ok', 'error'].includes(data.status))
+        return { kind: 'controlResponse', result: validators.controlResponse(data) };
+    if (data.device_type === 'gateway')
+        return { kind: 'gatewayInfo', result: validators.gatewayInfo(data) };
+    // Fallback treat as heartbeat attempt
+    return { kind: 'sensorHeartbeat', result: validators.sensorHeartbeat(data) };
+}

package/package.json

@@ -0,0 +1,91 @@
+{
+  "name": "@alteriom/mqtt-schema",
+  "version": "0.2.0",
+  "description": "Alteriom MQTT v1 schemas, TypeScript types, and validation helpers for web integration",
+  "license": "MIT",
+  "author": "Alteriom Development Team",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Alteriom/alteriom-firmware.git"
+  },
+  "homepage": "https://github.com/Alteriom/alteriom-firmware/tree/main/docs/mqtt_schema",
+  "bugs": {
+    "url": "https://github.com/Alteriom/alteriom-firmware/issues"
+  },
+  "type": "commonjs",
+  "main": "dist/cjs/index.js",
+  "module": "dist/esm/index.js",
+  "types": "dist/cjs/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "require": "./dist/cjs/index.js",
+      "import": "./dist/esm/index.js",
+      "types": "./dist/cjs/index.d.ts",
+      "default": "./dist/cjs/index.js"
+    },
+    "./validators": {
+      "require": "./dist/cjs/validators.js",
+      "import": "./dist/esm/validators.js",
+      "types": "./dist/cjs/validators.d.ts",
+      "default": "./dist/cjs/validators.js"
+    },
+    "./types": {
+      "require": "./dist/cjs/types.js",
+      "import": "./dist/esm/types.js",
+      "types": "./dist/cjs/types.d.ts",
+      "default": "./dist/cjs/types.js"
+    },
+    "./schemas/*": {
+      "default": "./schemas/*"
+    },
+    "./package.json": "./package.json"
+  },
+  "typesVersions": {
+    "*": {
+      "validators": [
+        "dist/cjs/validators.d.ts"
+      ],
+      "types": [
+        "dist/cjs/types.d.ts"
+      ],
+      "schemas/*": [
+        "schemas/*"
+      ]
+    }
+  },
+  "files": [
+    "dist/",
+    "schemas/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "prebuild": "npm run clean && node scripts/copy-schemas.cjs",
+    "build:cjs": "tsc -p tsconfig.json",
+    "build:esm": "tsc -p tsconfig.esm.json && node scripts/post-esm.cjs",
+    "build": "npm run build:cjs && npm run build:esm && node scripts/copy-schemas.cjs",
+    "clean": "rimraf dist schemas",
+    "prepare": "npm run build",
+    "lint": "echo 'No linter configured'",
+    "test": "node test/validate-fixtures.cjs",
+    "release:prepare": "node scripts/release-prepare.cjs"
+  },
+  "keywords": [
+    "alteriom",
+    "mqtt",
+    "iot",
+    "schema",
+    "validation",
+    "typescript"
+  ],
+  "peerDependencies": {
+    "ajv": ">=8.0.0"
+  },
+  "devDependencies": {
+    "ajv": "^8.17.0",
+    "ajv-formats": "^2.1.1",
+    "rimraf": "^5.0.5",
+    "typescript": "^5.4.0"
+  }
+}