@alteriom/mqtt-schema 0.2.0

package/README.md

@@ -0,0 +1,174 @@
+# @alteriom/mqtt-schema
+
+Alteriom MQTT v1 JSON Schemas, TypeScript types, and production‑ready validation helpers for integrating firmware MQTT payloads into web or backend services.
+
+## Why this exists
+Firmware emits structured MQTT payloads that must remain tightly aligned with web, analytics, and gateway logic. This package is the single source of truth for:
+
+- Canonical, versioned JSON Schemas (`schema_version: 1` series)
+- Embedded (tree‑shakeable) schema objects — no runtime file I/O
+- Precompiled Ajv validators (fast + consistent across CJS / ESM)
+- TypeScript interfaces & type guards generated from the same source schema set
+- Message classification helper that infers the schema kind heuristically
+- Forward‑compatible design: unknown extra properties are ignored unless explicitly constrained
+
+## Features
+
+- Dual build: CommonJS + ESM (Node 16+ / bundlers)
+- Zero configuration: just import and validate
+- Helpful error paths (JSON Pointer style)
+- Lightweight (Ajv peer dependency, schemas embedded)
+- Ships original schema JSON files (optional consumption)
+
+## Installation
+
+```bash
+npm install @alteriom/mqtt-schema ajv ajv-formats
+```
+
+## Quick Start
+
+Validate a JSON payload (object already parsed):
+
+```ts
+import { validators } from '@alteriom/mqtt-schema';
+
+const payload = JSON.parse(rawMqttString);
+const result = validators.sensorData(payload);
+if (!result.valid) {
+  console.error('Invalid sensor data', result.errors);
+}
+```
+
+Classify and validate automatically:
+
+```ts
+import { classifyAndValidate } from '@alteriom/mqtt-schema';
+
+const { kind, result } = classifyAndValidate(payload);
+if (result.valid) {
+  console.log('Message kind:', kind);
+} else {
+  console.warn('Validation errors', result.errors);
+}
+```
+
+Use strong TypeScript types after classification:
+
+```ts
+import { classifyAndValidate, isSensorDataMessage, SensorDataMessage } from '@alteriom/mqtt-schema';
+
+const { result } = classifyAndValidate(payload);
+if (result.valid && isSensorDataMessage(payload)) {
+  const data: SensorDataMessage = payload;
+  Object.entries(data.sensors).forEach(([name, s]) => {
+    console.log(name, s.value, s.unit);
+  });
+}
+```
+
+Access raw schema JSON (if you need to introspect or power form generation):
+
+```ts
+import envelopeSchema from '@alteriom/mqtt-schema/schemas/envelope.schema.json';
+```
+
+## API Surface
+
+```ts
+import { validators, validateMessage, classifyAndValidate } from '@alteriom/mqtt-schema';
+
+// 1. Direct validator by message kind
+validators.sensorData(payload); // => { valid: boolean; errors?: string[] }
+
+// 2. Generic function
+validateMessage('sensorData', payload);
+
+// 3. Classify unknown payload then validate
+const { kind, result } = classifyAndValidate(payload);
+
+// 4. Type guards (when available)
+// if (isSensorDataMessage(payload)) { ... }
+```
+
+Validation result format:
+
+```ts
+interface ValidationResult {
+  valid: boolean;
+  errors?: string[]; // Each item contains instancePath + message
+}
+```
+
+### Performance Notes
+All Ajv validator functions are compiled once at module load. For typical web usage (tens to hundreds of validations per page/session) this is faster and simpler than on‑demand compilation. If you need custom Ajv options (e.g., different formats), open an issue—an override hook can be added without breaking changes.
+
+### Embedded Schemas
+`schema_data.ts` is auto‑generated during build. This avoids dynamic `require()` / `import` of JSON and works cleanly in both Node ESM and bundlers without JSON import assertions. The original JSON files are still published under `schemas/` for tooling or documentation pipelines.
+
+## Provided Schemas (v1)
+
+| File | Purpose |
+|------|---------|
+| envelope.schema.json | Base required envelope fields |
+| sensor_data.schema.json | Telemetry payload with sensors map |
+| sensor_heartbeat.schema.json | Lightweight heartbeat (firmware_version may be omitted) |
+| sensor_status.schema.json | Sensor status / presence updates |
+| gateway_info.schema.json | Gateway identity & capabilities |
+| gateway_metrics.schema.json | Gateway performance metrics |
+| firmware_status.schema.json | Firmware update lifecycle events |
+| control_response.schema.json | Command/control response messages |
+
+## Exports
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `validators` | object | Precompiled validators per message type |
+| `validateMessage(kind,data)` | fn | Run a specific validator by key |
+| `classifyAndValidate(data)` | fn | Heuristic classification + validation |
+| `SensorDataMessage` etc. | TS interfaces | Strongly typed shapes |
+| `isSensorDataMessage` etc. | type guards | Runtime narrowing helpers |
+| `schemas/*.json` | JSON | Original schema assets (optional) |
+
+### Validator Keys
+`sensorData`, `sensorHeartbeat`, `sensorStatus`, `gatewayInfo`, `gatewayMetrics`, `firmwareStatus`, `controlResponse`
+
+### Classification Heuristics (Simplified)
+- `metrics` → `gatewayMetrics`
+- `sensors` → `sensorData`
+- `progress_pct` or OTA status keywords → `firmwareStatus`
+- `status` + `device_type: sensor` → `sensorStatus`
+- `status: ok|error` (no other match) → `controlResponse`
+- `device_type: gateway` → `gatewayInfo`
+- fallback → `sensorHeartbeat`
+
+## Versioning Policy
+
+Schema stability is paramount. We track two related versions:
+
+| Concept | Meaning |
+|---------|---------|
+| `schema_version` (in payload) | Wire format major. Only increments for breaking changes. |
+| npm package version | Follows semver; patch/minor may add optional properties or tooling, major aligns with `schema_version` bump. |
+
+Backward‑compatible additions: new optional properties or enums, documented in CHANGELOG. Breaking: new required fields, structural changes, or removed properties (triggers parallel `v2` schema path & coordinated firmware rollout).
+
+## TypeScript / Bundler Notes
+- Works in TS >= 5, Node >= 16, Vite / Webpack / ESBuild.
+- Tree shaking: unused validators pruned when using ESM builds.
+- No side effects besides Ajv instance creation.
+
+## Roadmap
+- Optional custom Ajv injection hook
+- JSON Schema → Zod conversion example
+- Runtime metrics helper (count validation categories)
+
+## Contributing
+Issues & PRs welcome. Ensure firmware repo schemas remain the authoritative source—do not manually edit generated `schema_data.ts`.
+
+## Security
+Schemas are static. No network access. Supply-chain risk minimized by keeping dependencies minimal (Ajv + formats only).
+
+## License
+
+MIT

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

@@ -0,0 +1,101 @@
+/**
+ * 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.
+ */
+export interface BaseEnvelope {
+    schema_version: 1;
+    device_id: string;
+    device_type: 'sensor' | 'gateway';
+    timestamp: string;
+    firmware_version?: string;
+    hardware_version?: string;
+    [k: string]: unknown;
+}
+export interface SensorEntry {
+    value: number;
+    unit?: string;
+    raw_value?: number;
+    calibrated_value?: number;
+    quality_score?: number;
+    name?: string;
+    location?: string;
+    additional_data?: Record<string, unknown>;
+    [k: string]: unknown;
+}
+export interface SensorDataMessage extends BaseEnvelope {
+    device_type: 'sensor';
+    firmware_version: string;
+    sensors: Record<string, SensorEntry>;
+    battery_level?: number;
+    signal_strength?: number;
+    additional?: Record<string, unknown>;
+}
+export interface SensorHeartbeatMessage extends Omit<BaseEnvelope, 'firmware_version'> {
+    device_type: 'sensor' | 'gateway';
+    firmware_version?: string;
+}
+export interface SensorStatusMessage extends BaseEnvelope {
+    device_type: 'sensor';
+    firmware_version: string;
+    status: 'online' | 'offline' | 'updating' | 'error';
+    battery_level?: number;
+    signal_strength?: number;
+}
+export interface GatewayInfoMessage extends BaseEnvelope {
+    device_type: 'gateway';
+    firmware_version: string;
+    mac_address?: string;
+    ip_address?: string;
+    capabilities?: {
+        max_nodes?: number;
+        supports_mesh?: boolean;
+        firmware_update?: boolean;
+        [k: string]: unknown;
+    };
+}
+export interface GatewayMetricsMessage extends BaseEnvelope {
+    device_type: 'gateway';
+    firmware_version: string;
+    metrics: {
+        uptime_s: number;
+        cpu_usage_pct?: number;
+        memory_usage_pct?: number;
+        temperature_c?: number;
+        connected_devices?: number;
+        mesh_nodes?: number;
+        packet_loss_pct?: number;
+        data_throughput_kbps?: number;
+        [k: string]: unknown;
+    };
+}
+export interface FirmwareStatusMessage extends BaseEnvelope {
+    status: 'pending' | 'downloading' | 'flashing' | 'verifying' | 'rebooting' | 'completed' | 'failed';
+    event?: string;
+    from_version?: string;
+    to_version?: string;
+    progress_pct?: number;
+    error?: string | null;
+}
+export interface ControlResponseMessage extends BaseEnvelope {
+    status: 'ok' | 'error';
+    command?: string;
+    message?: string;
+    result?: unknown;
+}
+export type AnyMqttV1Message = SensorDataMessage | SensorHeartbeatMessage | SensorStatusMessage | GatewayInfoMessage | GatewayMetricsMessage | FirmwareStatusMessage | ControlResponseMessage;
+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;
+export declare function isGatewayInfoMessage(msg: any): msg is GatewayInfoMessage;
+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 classifyMessage(msg: any): AnyMqttV1Message | null;
+export interface BasicValidationIssue {
+    field?: string;
+    reason: string;
+}
+export declare function basicValidate(msg: AnyMqttV1Message): BasicValidationIssue[];
+export declare function parseMessage(json: string): AnyMqttV1Message | null;

package/dist/cjs/generated/types.js

@@ -0,0 +1,104 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSensorDataMessage = isSensorDataMessage;
+exports.isSensorHeartbeatMessage = isSensorHeartbeatMessage;
+exports.isSensorStatusMessage = isSensorStatusMessage;
+exports.isGatewayInfoMessage = isGatewayInfoMessage;
+exports.isGatewayMetricsMessage = isGatewayMetricsMessage;
+exports.isFirmwareStatusMessage = isFirmwareStatusMessage;
+exports.isControlResponseMessage = isControlResponseMessage;
+exports.classifyMessage = classifyMessage;
+exports.basicValidate = basicValidate;
+exports.parseMessage = parseMessage;
+// Type Guards ------------------------------------------------
+function isSensorDataMessage(msg) {
+    return msg && msg.schema_version === 1 && msg.device_type === 'sensor' && typeof msg.sensors === 'object';
+}
+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)));
+}
+function isSensorStatusMessage(msg) {
+    return msg && msg.schema_version === 1 && msg.device_type === 'sensor' && typeof msg.status === 'string' && ['online', 'offline', 'updating', 'error'].includes(msg.status);
+}
+function isGatewayInfoMessage(msg) {
+    return msg && msg.schema_version === 1 && msg.device_type === 'gateway' && (!msg.metrics) && (!msg.status) && (!msg.progress_pct);
+}
+function isGatewayMetricsMessage(msg) {
+    return msg && msg.schema_version === 1 && msg.device_type === 'gateway' && typeof msg.metrics === 'object';
+}
+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));
+}
+function isControlResponseMessage(msg) {
+    return msg && msg.schema_version === 1 && (msg.status === 'ok' || msg.status === 'error') && 'timestamp' in msg;
+}
+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;
+}
+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
+function parseMessage(json) {
+    try {
+        const obj = JSON.parse(json);
+        return classifyMessage(obj);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/cjs/index.d.ts

@@ -0,0 +1,2 @@
+export * from './validators.js';
+export * from './types.js';

package/dist/cjs/index.js

@@ -0,0 +1,23 @@
+"use strict";
+// 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.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// Use explicit .js extensions so ESM build (with dist/esm/package.json type=module) treats them as ESM.
+__exportStar(require("./validators.js"), exports);
+__exportStar(require("./types.js"), exports);