@alteriom/mqtt-schema 0.2.1 → 0.3.1

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog (Moved)
+
+The canonical changelog is maintained at:
+
+`docs/mqtt_schema/CHANGELOG.md`
+
+This root file is intentionally minimal to avoid duplication and ensure release integrity scripts target a single source of truth.

package/README.md

@@ -1,7 +1,21 @@
 # @alteriom/mqtt-schema
 
+![Metadata Compliance](https://github.com/Alteriom/alteriom-mqtt-schema/actions/workflows/metadata-compliance.yml/badge.svg)
+![OTA Manifest Validation](https://github.com/Alteriom/alteriom-mqtt-schema/actions/workflows/validate-ota-manifest.yml/badge.svg)
+![Schema Verify](https://github.com/Alteriom/alteriom-mqtt-schema/actions/workflows/schema-verify.yml/badge.svg)
+![npm version](https://img.shields.io/npm/v/@alteriom/mqtt-schema.svg)
+![npm downloads](https://img.shields.io/npm/dm/@alteriom/mqtt-schema.svg)
+![license](https://img.shields.io/npm/l/@alteriom/mqtt-schema.svg)
+![npm total downloads](https://img.shields.io/npm/dt/@alteriom/mqtt-schema.svg)
+![node version](https://img.shields.io/node/v/@alteriom/mqtt-schema.svg)
+![peer ajv](https://img.shields.io/badge/peer%20ajv-%3E%3D8.0.0-blue.svg)
+![latest tag](https://img.shields.io/github/v/tag/Alteriom/alteriom-mqtt-schema?label=tag)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/@alteriom/mqtt-schema)](https://bundlephobia.com/package/@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:
 
@@ -26,6 +40,8 @@ Firmware emits structured MQTT payloads that must remain tightly aligned with we
 npm install @alteriom/mqtt-schema ajv ajv-formats
 ```
 
+**Support & Compatibility**: Node 18+ tested; Node 20 primary. Dual CJS/ESM builds.
+
 ## Quick Start
 
 Validate a JSON payload (object already parsed):
@@ -73,6 +89,43 @@ Access raw schema JSON (if you need to introspect or power form generation):
 import envelopeSchema from '@alteriom/mqtt-schema/schemas/envelope.schema.json';
 ```
 
+## OTA Firmware Manifest Schema (v0.3.1+)
+
+The package includes OTA firmware manifest schema with both rich and minimal formats.
+
+**Preferred: Stable alias import** (v0.3.1+):
+```ts
+import otaManifestSchema from '@alteriom/mqtt-schema/ota-manifest';
+import { OtaManifest, isRichManifest } from '@alteriom/mqtt-schema/types/ota-manifest';
+```
+
+**Legacy: Deep path import** (still supported):
+```ts
+import otaManifestSchema from '@alteriom/mqtt-schema/schemas/ota/ota-manifest.schema.json';
+```
+
+**Usage example:**
+```ts
+import Ajv from 'ajv';
+import addFormats from 'ajv-formats';
+import otaManifestSchema from '@alteriom/mqtt-schema/ota-manifest';
+import { OtaManifest } from '@alteriom/mqtt-schema/types/ota-manifest';
+
+const ajv = new Ajv({ allErrors: true, strict: false });
+addFormats(ajv);
+const validate = ajv.compile<OtaManifest>(otaManifestSchema as any);
+
+const manifest: OtaManifest = JSON.parse(manifestJson);
+if (!validate(manifest)) {
+  console.error('Invalid OTA manifest:', validate.errors);
+}
+```
+
+Supported formats:
+- **Rich manifest**: environment + branch + manifests object
+- **Minimal environment map**: environment → channels mapping  
+- **Chunk variants**: structured objects or SHA256 array
+
 ## API Surface
 
 ```ts
@@ -101,9 +154,11 @@ interface ValidationResult {
 ```
 
 ### 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)
@@ -131,6 +186,7 @@ All Ajv validator functions are compiled once at module load. For typical web us
 | `schemas/*.json` | JSON | Original schema assets (optional) |
 
 ### Validator Keys
+
 `sensorData`, `sensorHeartbeat`, `sensorStatus`, `gatewayInfo`, `gatewayMetrics`, `firmwareStatus`, `controlResponse`
 
 ### Classification Heuristics (Simplified)
@@ -170,6 +226,8 @@ 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.
+
 ## Security
 
 Schemas are static. No network access. Supply-chain risk minimized by keeping dependencies minimal (Ajv + formats only).
@@ -189,14 +247,14 @@ This package is published to BOTH:
 
 Create or update an `.npmrc` with a scoped registry override (auth token with `read:packages` required):
 
-```
+```bash
 @alteriom:registry=https://npm.pkg.github.com
 //npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
 ```
 
 Then install normally:
 
-```
+```bash
 npm install @alteriom/mqtt-schema ajv ajv-formats
 ```
 
@@ -226,3 +284,58 @@ npm view @alteriom/mqtt-schema version --registry=https://npm.pkg.github.com
 ```
 
 Both should return the same version.
+
+## Repository Metadata Compliance
+
+This repository integrates the `@alteriom/repository-metadata-manager` tooling to continuously validate and report on repository metadata health (description, topics, documentation signals, etc.) within the Alteriom organization standards.
+
+### Local Usage
+
+Run a validation (non‑destructive):
+
+```bash
+npm run metadata:validate
+```
+
+Generate a detailed report:
+
+```bash
+npm run metadata:report
+```
+
+Configuration lives in `metadata-config.json` (organizationTag `alteriom`). Default detection is auto; adjust if repository classification needs overriding.
+
+### CI Workflow
+
+Workflow file: `.github/workflows/metadata-compliance.yml`
+
+On each push / PR against `main` it will:
+
+1. Install dependencies
+2. Run `metadata:validate` (fails job on hard non‑compliance)
+3. Always attempt a best‑effort report (`metadata:report`) for visibility
+
+### Tokens / Permissions
+
+The workflow relies only on the default `GITHUB_TOKEN` for read operations. If future auto‑apply operations are desired, a token with elevated repo scope would be needed and the `metadata:apply` script could be wired (currently omitted to keep CI read‑only).
+
+### Extending
+
+If you add new categories of tooling or documentation, re‑run the report to see updated recommendations. For cross‑repo analytics or policy generation, use the original project directly.
+
+### Applying Metadata (Manual Workflow)
+
+For authorized maintainers you can run adjustments via GitHub Actions:
+
+1. Open the "Repository Metadata Apply" workflow under the Actions tab.
+2. Choose whether to keep `dryRun` (default) or set to `false` to apply.
+3. Run the workflow; the log will show proposed or applied changes.
+
+Local dry‑run vs apply:
+
+```bash
+npm run metadata:apply:dry  # show what would change
+npm run metadata:apply      # apply changes (requires proper permissions via GITHUB_TOKEN)
+```
+
+Note: Applying metadata modifies repository settings (description, topics) through the GitHub API; ensure the default token has the necessary repo scopes (in public repositories the workflow GITHUB_TOKEN normally suffices for these fields).

package/dist/cjs/schema_data.d.ts

@@ -317,3 +317,184 @@ export declare const mqtt_v1_bundle_json: {
         readonly control_response: "control_response.schema.json";
     };
 };
+export declare const ota_ota_manifest_schema: {
+    readonly $id: "https://schemas.alteriom.com/ota/ota-manifest.schema.json";
+    readonly title: "Alteriom OTA Firmware Manifest";
+    readonly description: "Schema for Alteriom OTA firmware manifests supporting both rich and minimal variants";
+    readonly type: "object";
+    readonly oneOf: readonly [{
+        readonly title: "Rich Manifest";
+        readonly description: "Rich manifest format with environment, branch, and manifests object";
+        readonly type: "object";
+        readonly properties: {
+            readonly environment: {
+                readonly type: "string";
+                readonly description: "Target environment (e.g., universal-sensor)";
+            };
+            readonly branch: {
+                readonly type: "string";
+                readonly description: "Source control branch the build originated from";
+            };
+            readonly manifests: {
+                readonly type: "object";
+                readonly description: "Build variants keyed by type (dev, prod, etc.)";
+                readonly patternProperties: {
+                    readonly "^[a-z][a-z0-9-]*$": {
+                        readonly $ref: "#/$defs/richEntry";
+                    };
+                };
+                readonly additionalProperties: false;
+                readonly minProperties: 1;
+            };
+        };
+        readonly required: readonly ["environment", "branch", "manifests"];
+        readonly additionalProperties: true;
+    }, {
+        readonly title: "Minimal Environment Map";
+        readonly description: "Minimal manifest format as environment -> channels mapping";
+        readonly type: "object";
+        readonly patternProperties: {
+            readonly "^[a-z][a-z0-9-]*$": {
+                readonly type: "object";
+                readonly description: "Environment entry with channel mappings";
+                readonly patternProperties: {
+                    readonly "^[a-z][a-z0-9-]*$": {
+                        readonly $ref: "#/$defs/minimalChannel";
+                    };
+                };
+                readonly additionalProperties: false;
+                readonly minProperties: 1;
+            };
+        };
+        readonly additionalProperties: false;
+        readonly minProperties: 1;
+    }];
+    readonly $defs: {
+        readonly richEntry: {
+            readonly title: "Rich Build Entry";
+            readonly description: "Rich manifest build entry (dev or prod)";
+            readonly type: "object";
+            readonly properties: {
+                readonly build_type: {
+                    readonly type: "string";
+                    readonly enum: readonly ["dev", "prod"];
+                    readonly description: "Build type identifier";
+                };
+                readonly file: {
+                    readonly type: "string";
+                    readonly description: "Firmware binary filename";
+                };
+                readonly size: {
+                    readonly type: "integer";
+                    readonly minimum: 1;
+                    readonly description: "Total firmware size in bytes";
+                };
+                readonly sha256: {
+                    readonly type: "string";
+                    readonly pattern: "^[a-f0-9]{64}$";
+                    readonly description: "SHA256 hash of the full firmware binary (lowercase hex)";
+                };
+                readonly firmware_version: {
+                    readonly type: "string";
+                    readonly description: "Semantic or build version string";
+                };
+                readonly built: {
+                    readonly type: "string";
+                    readonly format: "date-time";
+                    readonly description: "ISO8601 timestamp when built";
+                };
+                readonly ota_url: {
+                    readonly type: "string";
+                    readonly format: "uri";
+                    readonly description: "Absolute or relative URL to fetch the firmware";
+                };
+                readonly chunk_size: {
+                    readonly type: "integer";
+                    readonly minimum: 1;
+                    readonly description: "Size of each chunk except possibly the last";
+                };
+                readonly chunks: {
+                    readonly description: "Either structured chunk objects or array of SHA256 strings";
+                    readonly oneOf: readonly [{
+                        readonly type: "array";
+                        readonly items: {
+                            readonly $ref: "#/$defs/chunkObject";
+                        };
+                        readonly description: "Array of structured chunk objects with metadata";
+                    }, {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                            readonly pattern: "^[a-f0-9]{64}$";
+                            readonly description: "SHA256 hash of chunk (lowercase hex)";
+                        };
+                        readonly description: "Array of SHA256 strings for chunks";
+                    }];
+                };
+            };
+            readonly required: readonly ["build_type", "file", "size", "sha256", "firmware_version", "built", "ota_url"];
+            readonly additionalProperties: true;
+        };
+        readonly chunkObject: {
+            readonly title: "OTA Chunk Object";
+            readonly description: "Structured chunk metadata with offset and size";
+            readonly type: "object";
+            readonly properties: {
+                readonly index: {
+                    readonly type: "integer";
+                    readonly minimum: 0;
+                    readonly description: "0-based sequential chunk index";
+                };
+                readonly offset: {
+                    readonly type: "integer";
+                    readonly minimum: 0;
+                    readonly description: "Byte offset within firmware binary";
+                };
+                readonly size: {
+                    readonly type: "integer";
+                    readonly minimum: 1;
+                    readonly description: "Chunk size in bytes";
+                };
+                readonly sha256: {
+                    readonly type: "string";
+                    readonly pattern: "^[a-f0-9]{64}$";
+                    readonly description: "SHA256 hash of the chunk (lowercase hex)";
+                };
+            };
+            readonly required: readonly ["index", "offset", "size", "sha256"];
+            readonly additionalProperties: true;
+        };
+        readonly minimalChannel: {
+            readonly title: "Minimal Channel Entry";
+            readonly description: "Minimal manifest channel entry";
+            readonly type: "object";
+            readonly properties: {
+                readonly file: {
+                    readonly type: "string";
+                    readonly description: "Firmware binary filename";
+                };
+                readonly size: {
+                    readonly type: "integer";
+                    readonly minimum: 1;
+                    readonly description: "Total firmware size in bytes";
+                };
+                readonly sha256: {
+                    readonly type: "string";
+                    readonly pattern: "^[a-f0-9]{64}$";
+                    readonly description: "SHA256 hash of the firmware binary (lowercase hex)";
+                };
+                readonly version: {
+                    readonly type: "string";
+                    readonly description: "Firmware version string";
+                };
+                readonly timestamp: {
+                    readonly type: "string";
+                    readonly format: "date-time";
+                    readonly description: "ISO8601 timestamp";
+                };
+            };
+            readonly required: readonly ["file", "size", "sha256", "version", "timestamp"];
+            readonly additionalProperties: true;
+        };
+    };
+};

package/dist/cjs/schema_data.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-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.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 = {
@@ -400,3 +400,216 @@ exports.mqtt_v1_bundle_json = {
         "control_response": "control_response.schema.json"
     }
 };
+exports.ota_ota_manifest_schema = {
+    "$id": "https://schemas.alteriom.com/ota/ota-manifest.schema.json",
+    "title": "Alteriom OTA Firmware Manifest",
+    "description": "Schema for Alteriom OTA firmware manifests supporting both rich and minimal variants",
+    "type": "object",
+    "oneOf": [
+        {
+            "title": "Rich Manifest",
+            "description": "Rich manifest format with environment, branch, and manifests object",
+            "type": "object",
+            "properties": {
+                "environment": {
+                    "type": "string",
+                    "description": "Target environment (e.g., universal-sensor)"
+                },
+                "branch": {
+                    "type": "string",
+                    "description": "Source control branch the build originated from"
+                },
+                "manifests": {
+                    "type": "object",
+                    "description": "Build variants keyed by type (dev, prod, etc.)",
+                    "patternProperties": {
+                        "^[a-z][a-z0-9-]*$": {
+                            "$ref": "#/$defs/richEntry"
+                        }
+                    },
+                    "additionalProperties": false,
+                    "minProperties": 1
+                }
+            },
+            "required": [
+                "environment",
+                "branch",
+                "manifests"
+            ],
+            "additionalProperties": true
+        },
+        {
+            "title": "Minimal Environment Map",
+            "description": "Minimal manifest format as environment -> channels mapping",
+            "type": "object",
+            "patternProperties": {
+                "^[a-z][a-z0-9-]*$": {
+                    "type": "object",
+                    "description": "Environment entry with channel mappings",
+                    "patternProperties": {
+                        "^[a-z][a-z0-9-]*$": {
+                            "$ref": "#/$defs/minimalChannel"
+                        }
+                    },
+                    "additionalProperties": false,
+                    "minProperties": 1
+                }
+            },
+            "additionalProperties": false,
+            "minProperties": 1
+        }
+    ],
+    "$defs": {
+        "richEntry": {
+            "title": "Rich Build Entry",
+            "description": "Rich manifest build entry (dev or prod)",
+            "type": "object",
+            "properties": {
+                "build_type": {
+                    "type": "string",
+                    "enum": [
+                        "dev",
+                        "prod"
+                    ],
+                    "description": "Build type identifier"
+                },
+                "file": {
+                    "type": "string",
+                    "description": "Firmware binary filename"
+                },
+                "size": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "description": "Total firmware size in bytes"
+                },
+                "sha256": {
+                    "type": "string",
+                    "pattern": "^[a-f0-9]{64}$",
+                    "description": "SHA256 hash of the full firmware binary (lowercase hex)"
+                },
+                "firmware_version": {
+                    "type": "string",
+                    "description": "Semantic or build version string"
+                },
+                "built": {
+                    "type": "string",
+                    "format": "date-time",
+                    "description": "ISO8601 timestamp when built"
+                },
+                "ota_url": {
+                    "type": "string",
+                    "format": "uri",
+                    "description": "Absolute or relative URL to fetch the firmware"
+                },
+                "chunk_size": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "description": "Size of each chunk except possibly the last"
+                },
+                "chunks": {
+                    "description": "Either structured chunk objects or array of SHA256 strings",
+                    "oneOf": [
+                        {
+                            "type": "array",
+                            "items": {
+                                "$ref": "#/$defs/chunkObject"
+                            },
+                            "description": "Array of structured chunk objects with metadata"
+                        },
+                        {
+                            "type": "array",
+                            "items": {
+                                "type": "string",
+                                "pattern": "^[a-f0-9]{64}$",
+                                "description": "SHA256 hash of chunk (lowercase hex)"
+                            },
+                            "description": "Array of SHA256 strings for chunks"
+                        }
+                    ]
+                }
+            },
+            "required": [
+                "build_type",
+                "file",
+                "size",
+                "sha256",
+                "firmware_version",
+                "built",
+                "ota_url"
+            ],
+            "additionalProperties": true
+        },
+        "chunkObject": {
+            "title": "OTA Chunk Object",
+            "description": "Structured chunk metadata with offset and size",
+            "type": "object",
+            "properties": {
+                "index": {
+                    "type": "integer",
+                    "minimum": 0,
+                    "description": "0-based sequential chunk index"
+                },
+                "offset": {
+                    "type": "integer",
+                    "minimum": 0,
+                    "description": "Byte offset within firmware binary"
+                },
+                "size": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "description": "Chunk size in bytes"
+                },
+                "sha256": {
+                    "type": "string",
+                    "pattern": "^[a-f0-9]{64}$",
+                    "description": "SHA256 hash of the chunk (lowercase hex)"
+                }
+            },
+            "required": [
+                "index",
+                "offset",
+                "size",
+                "sha256"
+            ],
+            "additionalProperties": true
+        },
+        "minimalChannel": {
+            "title": "Minimal Channel Entry",
+            "description": "Minimal manifest channel entry",
+            "type": "object",
+            "properties": {
+                "file": {
+                    "type": "string",
+                    "description": "Firmware binary filename"
+                },
+                "size": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "description": "Total firmware size in bytes"
+                },
+                "sha256": {
+                    "type": "string",
+                    "pattern": "^[a-f0-9]{64}$",
+                    "description": "SHA256 hash of the firmware binary (lowercase hex)"
+                },
+                "version": {
+                    "type": "string",
+                    "description": "Firmware version string"
+                },
+                "timestamp": {
+                    "type": "string",
+                    "format": "date-time",
+                    "description": "ISO8601 timestamp"
+                }
+            },
+            "required": [
+                "file",
+                "size",
+                "sha256",
+                "version",
+                "timestamp"
+            ],
+            "additionalProperties": true
+        }
+    }
+};