@alteriom/mqtt-schema 0.2.0 → 0.3.0

package/dist/esm/schemas/validation_rules.md

@@ -1,44 +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.
+# 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/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@alteriom/mqtt-schema",
-  "version": "0.2.0",
+  "version": "0.3.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"
+    "url": "https://github.com/Alteriom/alteriom-mqtt-schema.git"
   },
-  "homepage": "https://github.com/Alteriom/alteriom-firmware/tree/main/docs/mqtt_schema",
+  "homepage": "https://github.com/Alteriom/alteriom-mqtt-schema#readme",
   "bugs": {
-    "url": "https://github.com/Alteriom/alteriom-firmware/issues"
+    "url": "https://github.com/Alteriom/alteriom-mqtt-schema/issues"
   },
   "type": "commonjs",
   "main": "dist/cjs/index.js",
@@ -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,15 +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",
@@ -69,7 +87,16 @@
     "prepare": "npm run build",
     "lint": "echo 'No linter configured'",
     "test": "node test/validate-fixtures.cjs",
-    "release:prepare": "node scripts/release-prepare.cjs"
+    "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",
+    "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",
@@ -77,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);
+}