@trillboards/edge-core 0.1.0 → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 Trillboards, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,93 @@
+# @trillboards/edge-core
+
+> **Core runtime for Trillboards Edge AI SDK.** Device identity, Socket.io connectivity, configuration, signal buffering, health monitoring, and auto-recovery for DOOH/CTV devices.
+
+## Install
+
+```bash
+npm install @trillboards/edge-core
+```
+
+## What This Does
+
+Provides the foundational infrastructure that all other `@trillboards/edge-*` packages depend on:
+
+- **Device Identity** — generates stable device fingerprints and session IDs from hardware characteristics
+- **Socket.io Manager** — real-time connection to Trillboards API with auto-reconnection and telemetry emission
+- **Signal Buffer** — SQLite-backed offline queue that caches audience metrics when connectivity drops
+- **Health Registry** — tracks 6 subsystems (socket, player, camera, microphone, ML pipeline, memory)
+- **Recovery Ladder** — 6-level auto-recovery from reconnect through service restart to rollback
+- **Capability Tiers** — classifies devices into TIER_1 through TIER_4 based on RAM and NPU availability
+- **Sensing Config** — deserializes 70+ sensing parameters for audience measurement tuning
+
+## Usage
+
+```typescript
+import {
+  DeviceIdentity,
+  SocketManager,
+  SignalBuffer,
+  SubsystemHealthRegistry,
+  SensingConfig,
+  computeTier,
+  classifyObservationSignal
+} from '@trillboards/edge-core';
+
+// Device identity
+const identity = new DeviceIdentity();
+const fingerprint = await identity.getFingerprint();
+
+// Capability detection
+const tier = computeTier({ ramMB: 4096, hasNPU: false });
+// → TIER_2
+
+// Socket.io connectivity
+const socket = new SocketManager({
+  url: 'https://api.trillboards.com',
+  deviceToken: 'your-token'
+});
+await socket.connect();
+
+// Offline-resilient signal buffering
+const buffer = new SignalBuffer({ dataDir: './data' });
+await buffer.push({ type: 'audience_metrics', payload: { faceCount: 3 } });
+
+// Signal classification
+const signal = classifyObservationSignal(rawPayload);
+// → { family: 'SCREEN_AUDIENCE', evidenceGrade: 'FACE_BACKED', ... }
+```
+
+## Subsystem Health Monitoring
+
+```typescript
+const health = new SubsystemHealthRegistry();
+
+health.update('camera', 'healthy');
+health.update('ml_pipeline', 'degraded');
+
+const report = health.getReport();
+// → { camera: 'healthy', ml_pipeline: 'degraded', ... }
+```
+
+## Capability Matrix
+
+```typescript
+import { getCapabilityMatrix } from '@trillboards/edge-core';
+
+const matrix = getCapabilityMatrix(tier);
+// → { models: ['blazeface'], inferenceHz: 2, resolution: 320, ... }
+```
+
+## Key Types
+
+- `PlatformAdapter` — interface for platform-specific adapters (Linux, Windows)
+- `CameraProvider` — interface for camera capture implementations
+- `AudioProvider` — interface for audio capture implementations
+- `AudienceMetricsPayload` — structured audience measurement data
+- `VASResult` — Viewability Attention Score output
+- `DetectedFace` — face detection result with bounding box, age, gender, emotion
+- `EdgeQualityReport` — inference quality telemetry
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trillboards/edge-core",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Core identity, heartbeat, Socket.io, config, and signal buffer for Trillboards Edge AI SDK",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -24,8 +24,9 @@
     "ts-jest": "^29.1.0",
     "typescript": "~5.3.0"
   },
-  "files": ["dist"],
-  "license": "UNLICENSED",
+  "files": ["dist", "LICENSE", "README.md"],
+  "author": "Trillboards <engineering@trillboards.com>",
+  "license": "MIT",
   "publishConfig": {
     "access": "public"
   },
@@ -34,6 +35,20 @@
     "url": "https://github.com/trillboards/packages.git",
     "directory": "trillboards-edge-sdk/packages/edge-core"
   },
+  "keywords": [
+    "edge-ai",
+    "dooh",
+    "audience-sensing",
+    "iot",
+    "digital-signage",
+    "heartbeat",
+    "socket-io",
+    "device-identity",
+    "ctv",
+    "signal-buffer",
+    "trillboards",
+    "ai-agent"
+  ],
   "engines": {
     "node": ">=18.0.0"
   }