ne-room-digital-signage-contracts 0.1.1

package/dist/src/index.d.ts

@@ -0,0 +1,298 @@
+export * from "./types";
+export declare const schemas: {
+    device: {
+        command: {
+            $schema: string;
+            title: string;
+            type: string;
+            additionalProperties: boolean;
+            required: string[];
+            properties: {
+                tenantId: {
+                    type: string;
+                    minLength: number;
+                };
+                deviceId: {
+                    type: string;
+                    minLength: number;
+                };
+                commandId: {
+                    type: string;
+                    minLength: number;
+                };
+                type: {
+                    type: string;
+                    enum: string[];
+                };
+                issuedAt: {
+                    type: string;
+                    format: string;
+                };
+                expiresAt: {
+                    type: string;
+                    format: string;
+                };
+                desiredVersion: {
+                    type: string;
+                };
+                payload: {
+                    type: string;
+                };
+            };
+        };
+        ack: {
+            $schema: string;
+            title: string;
+            type: string;
+            additionalProperties: boolean;
+            required: string[];
+            properties: {
+                tenantId: {
+                    type: string;
+                    minLength: number;
+                };
+                deviceId: {
+                    type: string;
+                    minLength: number;
+                };
+                commandId: {
+                    type: string;
+                    minLength: number;
+                };
+                status: {
+                    type: string;
+                    enum: string[];
+                };
+                timestamp: {
+                    type: string;
+                    format: string;
+                };
+                message: {
+                    type: string;
+                };
+                details: {
+                    type: string;
+                };
+                deviceAppVersion: {
+                    type: string;
+                };
+                deviceOsVersion: {
+                    type: string;
+                };
+            };
+        };
+        telemetry: {
+            $schema: string;
+            title: string;
+            type: string;
+            additionalProperties: boolean;
+            required: string[];
+            properties: {
+                tenantId: {
+                    type: string;
+                    minLength: number;
+                };
+                deviceId: {
+                    type: string;
+                    minLength: number;
+                };
+                timestamp: {
+                    type: string;
+                    format: string;
+                };
+                online: {
+                    type: string;
+                };
+                health: {
+                    type: string;
+                    additionalProperties: boolean;
+                    properties: {
+                        cpuPct: {
+                            type: string;
+                            minimum: number;
+                            maximum: number;
+                        };
+                        memPct: {
+                            type: string;
+                            minimum: number;
+                            maximum: number;
+                        };
+                        diskFreeBytes: {
+                            type: string;
+                            minimum: number;
+                        };
+                        diskTotalBytes: {
+                            type: string;
+                            minimum: number;
+                        };
+                        tempC: {
+                            type: string;
+                        };
+                    };
+                };
+                playback: {
+                    type: string;
+                    additionalProperties: boolean;
+                    properties: {
+                        state: {
+                            type: string;
+                            enum: string[];
+                        };
+                        currentAssetId: {
+                            type: string;
+                        };
+                        currentPlaylistId: {
+                            type: string;
+                        };
+                        currentScheduleId: {
+                            type: string;
+                        };
+                    };
+                };
+                network: {
+                    type: string;
+                    additionalProperties: boolean;
+                    properties: {
+                        type: {
+                            type: string;
+                            enum: string[];
+                        };
+                        rssi: {
+                            type: string;
+                        };
+                    };
+                };
+                app: {
+                    type: string;
+                    additionalProperties: boolean;
+                    properties: {
+                        version: {
+                            type: string;
+                        };
+                        build: {
+                            type: string;
+                        };
+                    };
+                };
+                errors: {
+                    type: string;
+                    items: {
+                        type: string;
+                        additionalProperties: boolean;
+                        required: string[];
+                        properties: {
+                            code: {
+                                type: string;
+                            };
+                            message: {
+                                type: string;
+                            };
+                            severity: {
+                                type: string;
+                                enum: string[];
+                            };
+                        };
+                    };
+                };
+            };
+        };
+        manifest: {
+            $schema: string;
+            title: string;
+            type: string;
+            additionalProperties: boolean;
+            required: string[];
+            properties: {
+                tenantId: {
+                    type: string;
+                };
+                deviceId: {
+                    type: string;
+                };
+                manifestVersion: {
+                    type: string;
+                };
+                manifestUrl: {
+                    type: string;
+                    format: string;
+                };
+                generatedAt: {
+                    type: string;
+                    format: string;
+                };
+            };
+        };
+        proofOfPlay: {
+            $schema: string;
+            title: string;
+            type: string;
+            additionalProperties: boolean;
+            required: string[];
+            properties: {
+                tenantId: {
+                    type: string;
+                };
+                deviceId: {
+                    type: string;
+                };
+                eventId: {
+                    type: string;
+                    minLength: number;
+                };
+                assetId: {
+                    type: string;
+                };
+                playlistId: {
+                    type: string;
+                };
+                scheduleId: {
+                    type: string;
+                };
+                startedAt: {
+                    type: string;
+                    format: string;
+                };
+                endedAt: {
+                    type: string;
+                    format: string;
+                };
+                durationMs: {
+                    type: string;
+                    minimum: number;
+                };
+                outcome: {
+                    type: string;
+                    enum: string[];
+                };
+                failureReason: {
+                    type: string;
+                };
+            };
+        };
+    };
+    admin: {
+        wsEvents: {
+            $schema: string;
+            title: string;
+            type: string;
+            additionalProperties: boolean;
+            required: string[];
+            properties: {
+                tenantId: {
+                    type: string;
+                };
+                type: {
+                    type: string;
+                    enum: string[];
+                };
+                timestamp: {
+                    type: string;
+                    format: string;
+                };
+                payload: {
+                    type: string;
+                };
+            };
+        };
+    };
+};

package/dist/src/index.js

@@ -0,0 +1,39 @@
+"use strict";
+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);
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.schemas = void 0;
+__exportStar(require("./types"), exports);
+const command_json_1 = __importDefault(require("../schemas/device/command.json"));
+const ack_json_1 = __importDefault(require("../schemas/device/ack.json"));
+const telemetry_json_1 = __importDefault(require("../schemas/device/telemetry.json"));
+const manifest_json_1 = __importDefault(require("../schemas/device/manifest.json"));
+const proof_of_play_json_1 = __importDefault(require("../schemas/device/proof_of_play.json"));
+const ws_events_json_1 = __importDefault(require("../schemas/admin/ws_events.json"));
+exports.schemas = {
+    device: {
+        command: command_json_1.default,
+        ack: ack_json_1.default,
+        telemetry: telemetry_json_1.default,
+        manifest: manifest_json_1.default,
+        proofOfPlay: proof_of_play_json_1.default
+    },
+    admin: {
+        wsEvents: ws_events_json_1.default
+    }
+};

package/dist/src/types.d.ts

@@ -0,0 +1,83 @@
+export type UUID = string;
+export type CommandType = "RELOAD_MANIFEST" | "REBOOT_APP" | "REBOOT_DEVICE" | "CLEAR_CACHE" | "SET_VOLUME" | "SET_BRIGHTNESS" | "CAPTURE_SCREENSHOT" | "PING";
+export interface DeviceCommand {
+    tenantId: string;
+    deviceId: string;
+    commandId: UUID;
+    type: CommandType;
+    issuedAt: string;
+    expiresAt?: string;
+    desiredVersion?: string;
+    payload?: Record<string, unknown>;
+}
+export type CommandAckStatus = "ACCEPTED" | "COMPLETED" | "FAILED" | "REJECTED" | "EXPIRED";
+export interface DeviceCommandAck {
+    tenantId: string;
+    deviceId: string;
+    commandId: UUID;
+    status: CommandAckStatus;
+    timestamp: string;
+    message?: string;
+    details?: Record<string, unknown>;
+    deviceAppVersion?: string;
+    deviceOsVersion?: string;
+}
+export interface DeviceTelemetry {
+    tenantId: string;
+    deviceId: string;
+    timestamp: string;
+    online: boolean;
+    health: {
+        cpuPct?: number;
+        memPct?: number;
+        diskFreeBytes?: number;
+        diskTotalBytes?: number;
+        tempC?: number;
+    };
+    playback?: {
+        state: "PLAYING" | "IDLE" | "ERROR";
+        currentAssetId?: string;
+        currentPlaylistId?: string;
+        currentScheduleId?: string;
+    };
+    network?: {
+        type?: "WIFI" | "ETHERNET" | "CELLULAR" | "UNKNOWN";
+        rssi?: number;
+    };
+    app?: {
+        version?: string;
+        build?: string;
+    };
+    errors?: Array<{
+        code: string;
+        message: string;
+        severity: "INFO" | "WARN" | "ERROR";
+    }>;
+}
+export interface DeviceManifestPointer {
+    tenantId: string;
+    deviceId: string;
+    manifestVersion: string;
+    manifestUrl: string;
+    generatedAt: string;
+}
+export interface ProofOfPlayEvent {
+    tenantId: string;
+    deviceId: string;
+    eventId: UUID;
+    assetId: string;
+    playlistId?: string;
+    scheduleId?: string;
+    startedAt: string;
+    endedAt?: string;
+    durationMs?: number;
+    outcome: "PLAYED" | "SKIPPED" | "FAILED";
+    failureReason?: string;
+}
+export type AdminWsEventType = "DEVICE_ONLINE_CHANGED" | "DEVICE_TELEMETRY_UPDATED" | "ALERT_RAISED" | "ALERT_RESOLVED" | "PUBLISH_PROGRESS" | "PUBLISH_COMPLETED";
+export interface AdminWsEvent<T = unknown> {
+    tenantId: string;
+    type: AdminWsEventType;
+    timestamp: string;
+    payload: T;
+}

package/dist/src/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/openapi/admin-api.yaml

@@ -0,0 +1,103 @@
+openapi: 3.0.3
+info:
+  title: Digital Signage Admin API
+  version: 0.1.0
+  description: Admin REST API for multi-tenant Digital Signage SaaS.
+servers:
+  - url: https://api.example.com
+security:
+  - bearerAuth: []
+paths:
+  /health:
+    get:
+      summary: Health check
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  status: { type: string, example: ok }
+
+  /devices:
+    get:
+      summary: List devices (tenant-scoped)
+      parameters:
+        - in: query
+          name: siteId
+          schema: { type: string }
+        - in: query
+          name: status
+          schema:
+            type: string
+            enum: [ONLINE, OFFLINE, UNKNOWN]
+      responses:
+        "200":
+          description: Device list
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  items:
+                    type: array
+                    items: { $ref: "#/components/schemas/Device" }
+
+  /publish:
+    post:
+      summary: Publish schedule/manifest updates to devices
+      description: >
+        Creates a publish job and signals devices via MQTT to pull the latest manifest over HTTPS.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/PublishRequest" }
+      responses:
+        "202":
+          description: Accepted
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/PublishJob" }
+
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+  schemas:
+    Device:
+      type: object
+      required: [id, tenantId, label, status, lastSeenAt]
+      properties:
+        id: { type: string }
+        tenantId: { type: string }
+        label: { type: string }
+        status:
+          type: string
+          enum: [ONLINE, OFFLINE, UNKNOWN]
+        appVersion: { type: string }
+        osVersion: { type: string }
+        lastSeenAt: { type: string, format: date-time }
+
+    PublishRequest:
+      type: object
+      required: [target]
+      properties:
+        target:
+          type: object
+          description: Target selector (site/group/device)
+          additionalProperties: true
+
+    PublishJob:
+      type: object
+      required: [id, status, createdAt]
+      properties:
+        id: { type: string }
+        status:
+          type: string
+          enum: [QUEUED, RUNNING, COMPLETED, FAILED]
+        createdAt: { type: string, format: date-time }

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "ne-room-digital-signage-contracts",
+  "version": "0.1.1",
+  "description": "Contracts (OpenAPI, AsyncAPI, JSON Schemas) for Digital Signage platform",
+  "license": "UNLICENSED",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "openapi",
+    "asyncapi",
+    "schemas",
+    "generated"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist",
+    "lint": "echo \"TODO: add spectral/asyncapi lint\"",
+    "validate": "echo \"TODO: add schema validation\""
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0"
+  }
+}

package/schemas/admin/ws_events.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "AdminWsEvent",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "tenantId",
+    "type",
+    "timestamp",
+    "payload"
+  ],
+  "properties": {
+    "tenantId": {
+      "type": "string"
+    },
+    "type": {
+      "type": "string",
+      "enum": [
+        "DEVICE_ONLINE_CHANGED",
+        "DEVICE_TELEMETRY_UPDATED",
+        "ALERT_RAISED",
+        "ALERT_RESOLVED",
+        "PUBLISH_PROGRESS",
+        "PUBLISH_COMPLETED"
+      ]
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "payload": {
+      "type": "object"
+    }
+  }
+}

package/schemas/device/ack.json

@@ -0,0 +1,53 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "DeviceCommandAck",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "tenantId",
+    "deviceId",
+    "commandId",
+    "status",
+    "timestamp"
+  ],
+  "properties": {
+    "tenantId": {
+      "type": "string",
+      "minLength": 1
+    },
+    "deviceId": {
+      "type": "string",
+      "minLength": 1
+    },
+    "commandId": {
+      "type": "string",
+      "minLength": 16
+    },
+    "status": {
+      "type": "string",
+      "enum": [
+        "ACCEPTED",
+        "COMPLETED",
+        "FAILED",
+        "REJECTED",
+        "EXPIRED"
+      ]
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "message": {
+      "type": "string"
+    },
+    "details": {
+      "type": "object"
+    },
+    "deviceAppVersion": {
+      "type": "string"
+    },
+    "deviceOsVersion": {
+      "type": "string"
+    }
+  }
+}

package/schemas/device/command.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "DeviceCommand",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "tenantId",
+    "deviceId",
+    "commandId",
+    "type",
+    "issuedAt"
+  ],
+  "properties": {
+    "tenantId": {
+      "type": "string",
+      "minLength": 1
+    },
+    "deviceId": {
+      "type": "string",
+      "minLength": 1
+    },
+    "commandId": {
+      "type": "string",
+      "minLength": 16
+    },
+    "type": {
+      "type": "string",
+      "enum": [
+        "RELOAD_MANIFEST",
+        "REBOOT_APP",
+        "REBOOT_DEVICE",
+        "CLEAR_CACHE",
+        "SET_VOLUME",
+        "SET_BRIGHTNESS",
+        "CAPTURE_SCREENSHOT",
+        "PING"
+      ]
+    },
+    "issuedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "expiresAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "desiredVersion": {
+      "type": "string"
+    },
+    "payload": {
+      "type": "object"
+    }
+  }
+}