@alteriom/mqtt-schema 0.2.1 → 0.3.0

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,71 @@
 # @alteriom/mqtt-schema
 
+![Metadata Compliance](https://github.com/Alteriom/alteriom-mqtt-schema/actions/workflows/metadata-compliance.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.
 
+> NOTE: OTA manifest CI validation workflow file could not be added via automated API due to path constraints; it can be added manually post-merge if still absent.
+
+See also: `docs/SCHEMA_MAP.md` for complete schema listing.
+
+## OTA Firmware Manifest Schema (NEW in 0.3.0)
+
+The package now includes the OTA firmware manifest schema used by build + deployment tooling.
+
+Import the schema JSON directly:
+```ts
+import otaManifestSchema from '@alteriom/mqtt-schema/schemas/ota/ota-manifest.schema.json';
+```
+
+Types:
+```ts
+import { OtaManifest, isRichManifest } from '@alteriom/mqtt-schema/types/ota-manifest';
+```
+
+Shapes supported (oneOf):
+- Rich manifest:
+```json
+{
+  "environment": "universal-sensor",
+  "branch": "main",
+  "manifests": { "dev": { /* richEntry */ }, "prod": { /* richEntry */ } }
+}
+```
+- Minimal environment map:
+```json
+{
+  "universal-sensor": { "dev": { /* minimalChannel */ } }
+}
+```
+
+Chunk hashing variants (mutually exclusive):
+1. Structured objects (offset + size + sha256)
+2. Array of lowercase sha256 strings
+
+Validation example:
+```ts
+import Ajv from 'ajv';
+import schema from '@alteriom/mqtt-schema/schemas/ota/ota-manifest.schema.json';
+import { OtaManifest } from '@alteriom/mqtt-schema/types/ota-manifest';
+
+const ajv = new Ajv({ allErrors: true });
+const validate = ajv.compile<OtaManifest>(schema as any);
+const manifest: OtaManifest = JSON.parse(raw);
+if (!validate(manifest)) {
+  console.error(validate.errors);
+}
+```
+
+---
+
 ## 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:
 
@@ -101,9 +165,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)
@@ -129,8 +195,11 @@ All Ajv validator functions are compiled once at module load. For typical web us
 | `SensorDataMessage` etc. | TS interfaces | Strongly typed shapes |
 | `isSensorDataMessage` etc. | type guards | Runtime narrowing helpers |
 | `schemas/*.json` | JSON | Original schema assets (optional) |
+| `schemas/ota/ota-manifest.schema.json` | JSON | OTA firmware manifest schema (rich + minimal) |
+| `types/ota-manifest` | TS types | OtaManifest union + helpers |
 
 ### Validator Keys
+
 `sensorData`, `sensorHeartbeat`, `sensorStatus`, `gatewayInfo`, `gatewayMetrics`, `firmwareStatus`, `controlResponse`
 
 ### Classification Heuristics (Simplified)
@@ -154,6 +223,8 @@ Schema stability is paramount. We track two related versions:
 
 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).
 
+Backward-compatible schema additions to OTA manifest WILL use minor bumps.
+
 ## TypeScript / Bundler Notes
 
 - Works in TS >= 5, Node >= 16, Vite / Webpack / ESBuild.
@@ -165,6 +236,8 @@ Backward‑compatible additions: new optional properties or enums, documented in
 - Optional custom Ajv injection hook
 - JSON Schema → Zod conversion example
 - Runtime metrics helper (count validation categories)
+- Signed OTA manifest extension
+- Delta / compressed OTA metadata fields
 
 ## Contributing
 
@@ -177,52 +250,3 @@ Schemas are static. No network access. Supply-chain risk minimized by keeping de
 ## License
 
 MIT
-
-## Registry Mirrors
-
-This package is published to BOTH:
-
-- Public npm registry: `https://registry.npmjs.org` (primary)
-- GitHub Packages registry: `https://npm.pkg.github.com` (mirror for visibility in repo Packages tab)
-
-### Installing from GitHub Packages (optional)
-
-Create or update an `.npmrc` with a scoped registry override (auth token with `read:packages` required):
-
-```
-@alteriom:registry=https://npm.pkg.github.com
-//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
-```
-
-Then install normally:
-
-```
-npm install @alteriom/mqtt-schema ajv ajv-formats
-```
-
-If you omit the override, npmjs.org is used (recommended for most consumers).
-
-### Why dual publish?
-
-- GitHub Packages listing provides provenance + quick visibility in the repo UI.
-- npm remains the canonical public distribution source (faster, anonymous installs allowed).
-
-### Operational Notes
-
-| Aspect | Behavior |
-|--------|----------|
-| Build artifact | Built once, same tarball published to both registries. |
-| Version uniqueness | Same version must not be republished; bump if any change needed. |
-| Auth (GitHub) | Always required for install from GitHub Packages, even for public repos. |
-| Tarball parity | Do not rebuild between publishes; workflows ensure single build. |
-| Fallback strategy | If mirror publish fails (e.g., transient), primary npm publish still stands. |
-| Provenance flag | Applied for npm (GitHub ignores currently). |
-
-### Verifying a Release
-
-```bash
-npm view @alteriom/mqtt-schema version
-npm view @alteriom/mqtt-schema version --registry=https://npm.pkg.github.com
-```
-
-Both should return the same version.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alteriom/mqtt-schema",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Alteriom MQTT v1 schemas, TypeScript types, and validation helpers for web integration",
   "license": "MIT",
   "author": "Alteriom Development Team",
@@ -39,6 +39,13 @@
     "./schemas/*": {
       "default": "./schemas/*"
     },
+    "./schemas/ota/ota-manifest.schema.json": {
+      "default": "./schemas/ota/ota-manifest.schema.json"
+    },
+    "./types/ota-manifest": {
+      "types": "./types/ota-manifest.d.ts",
+      "default": "./types/ota-manifest.d.ts"
+    },
     "./package.json": "./package.json"
   },
   "typesVersions": {
@@ -51,18 +58,26 @@
       ],
       "schemas/*": [
         "schemas/*"
+      ],
+      "types/ota-manifest": [
+        "types/ota-manifest.d.ts"
       ]
     }
   },
   "files": [
     "dist/",
     "schemas/",
+    "types/",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "CHANGELOG.md"
   ],
   "publishConfig": {
     "access": "public"
   },
+  "engines": {
+    "node": ">=16.0.0"
+  },
   "scripts": {
     "prebuild": "npm run clean && node scripts/copy-schemas.cjs",
     "build:cjs": "tsc -p tsconfig.json",
@@ -75,7 +90,13 @@
     "verify:schemas": "node scripts/check-schema-sync.cjs",
     "verify:release": "node scripts/check-release-integrity.cjs",
     "verify": "npm run verify:schemas && npm run verify:release && npm test",
-    "release:prepare": "node scripts/release-prepare.cjs"
+    "release:prepare": "node scripts/release-prepare.cjs",
+    "wiki:generate": "node scripts/generate-wiki.cjs",
+    "metadata:report": "alteriom-metadata report --org-tag alteriom || echo 'metadata report failed'",
+    "metadata:validate": "alteriom-metadata validate --org-tag alteriom || echo 'metadata validate failed'",
+    "metadata:apply": "alteriom-metadata apply --org-tag alteriom",
+    "metadata:apply:dry": "alteriom-metadata dry-run --org-tag alteriom",
+    "validate:ota": "node scripts/validate-ota-manifest.js"
   },
   "keywords": [
     "alteriom",
@@ -83,15 +104,20 @@
     "iot",
     "schema",
     "validation",
-    "typescript"
+    "typescript",
+    "ota"
   ],
   "peerDependencies": {
     "ajv": ">=8.0.0"
   },
   "devDependencies": {
+    "@alteriom/repository-metadata-manager": "^1.2.4",
     "ajv": "^8.17.0",
     "ajv-formats": "^2.1.1",
     "rimraf": "^5.0.5",
     "typescript": "^5.4.0"
+  },
+  "dependencies": {
+    "dotenv": "^17.2.2"
   }
 }

package/types/ota-manifest.d.ts

@@ -0,0 +1,63 @@
+// Type definitions for Alteriom OTA Manifest (rich + minimal variants)
+// Generated manually alongside schema at schemas/ota/ota-manifest.schema.json
+
+export interface OtaChunkObject {
+  index: number;        // 0-based sequential index
+  offset: number;       // byte offset within firmware binary
+  size: number;         // chunk size in bytes
+  sha256: string;       // lowercase hex sha256 of the chunk
+}
+
+// Rich manifest build entry (dev or prod)
+export interface OtaRichEntryBase {
+  build_type: 'dev' | 'prod';
+  file: string;              // firmware-dev.bin or firmware-prod.bin
+  size: number;              // total firmware size (bytes)
+  sha256: string;            // full firmware binary sha256
+  firmware_version: string;  // semantic or build version string
+  built: string;             // ISO8601 timestamp
+  ota_url: string;           // absolute or relative fetch URL
+  chunk_size?: number;       // size each chunk except possibly last
+  // Either structured objects OR array of sha256 strings
+  chunks?: OtaChunkObject[] | string[];
+}
+
+export type OtaRichEntry = OtaRichEntryBase;
+
+export interface OtaRichManifest {
+  environment: string;   // e.g. universal-sensor
+  branch: string;        // source control branch build originated from
+  manifests: {
+    dev?: OtaRichEntry;
+    prod?: OtaRichEntry;
+  };
+}
+
+// Minimal variant channel entry
+export interface OtaMinimalChannel {
+  file: string;      // firmware-dev.bin / firmware-prod.bin
+  size: number;      // bytes
+  sha256: string;    // full firmware sha256
+  version: string;   // version string
+  timestamp: string; // ISO8601 build time
+  chunk_size?: number;
+  chunks?: string[]; // hash-only list (no structured offsets)
+}
+
+export interface OtaMinimalEnv {
+  dev?: OtaMinimalChannel;
+  prod?: OtaMinimalChannel;
+}
+
+// Root minimal map: environment -> channels
+export type OtaMinimalManifest = Record<string, OtaMinimalEnv>;
+
+export type OtaManifest = OtaRichManifest | OtaMinimalManifest;
+
+export function isRichManifest(m: OtaManifest): m is OtaRichManifest {
+  return (m as OtaRichManifest).manifests !== undefined && typeof (m as any).environment === 'string';
+}
+
+export function isMinimalManifest(m: OtaManifest): m is OtaMinimalManifest {
+  return !isRichManifest(m);
+}