@robotical/webapp-types 3.25.5 → 3.25.7

package/dist-types/src/utils/colour-calibration-records.js

@@ -0,0 +1,253 @@
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
+    return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
+    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
+        if (ar || !(i in from)) {
+            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
+            ar[i] = from[i];
+        }
+    }
+    return to.concat(ar || Array.prototype.slice.call(from));
+};
+import packageInfo from "../../package.json";
+import colourPolicy from "./marty-colour-policy.json";
+import { COLOUR_DATABASE_URL } from "./colour-sensor-diagnostics";
+import isPhoneApp from "./phone-app-communication/is-phone-app";
+import { validColourSensorProfile, colourSensorProfilePath } from "./colour-sensor-profile";
+var PREFIX = "marty-colour-calibration-upload:";
+var id = function () { return Array.from(window.crypto.getRandomValues(new Uint8Array(16)), function (byte) { return byte.toString(16).padStart(2, "0"); }).join(""); };
+var memory = new Map();
+var listeners = new Set();
+var retry;
+var uploading;
+var lastError = "";
+var notify = function () { return listeners.forEach(function (listener) { return listener(); }); };
+var keyFor = function (entry) { return "".concat(PREFIX).concat(entry.sessionId, ":").concat(entry.attemptId, ":").concat(entry.eventId); };
+var entries = function () {
+    var _a;
+    var result = new Map(memory);
+    try {
+        for (var index = 0; index < localStorage.length; index++) {
+            var key = localStorage.key(index);
+            if (!key.startsWith(PREFIX))
+                continue;
+            try {
+                var entry = JSON.parse(localStorage.getItem(key));
+                if ([entry.sessionId, entry.attemptId, entry.eventId].every(function (value) { return /^[a-f0-9]{32}$/.test(value); }) &&
+                    keyFor(entry) === key && typeof ((_a = entry.event) === null || _a === void 0 ? void 0 : _a.type) === "string" && Number.isFinite(entry.event.recordedAtMs))
+                    result.set(key, entry);
+            }
+            catch ( /* Preserve malformed local records for inspection; never upload them to arbitrary paths. */_b) { /* Preserve malformed local records for inspection; never upload them to arbitrary paths. */ }
+        }
+    }
+    catch ( /* In-memory entries can still upload when storage is unavailable. */_c) { /* In-memory entries can still upload when storage is unavailable. */ }
+    return result;
+};
+var schedule = function (ms) {
+    if (ms === void 0) { ms = 500; }
+    if (retry !== undefined)
+        return;
+    retry = setTimeout(function () { retry = undefined; void flushColourCalibrationRecords(); }, ms);
+};
+/** Immutable event IDs allow safe retries after an unknown HTTP outcome or a reload. */
+export var recordColourCalibrationEvent = function (ref, type, data, metadata, sequence) {
+    var entry = JSON.parse(JSON.stringify(__assign(__assign({}, ref), { eventId: id(), metadata: metadata, event: { type: type, recordedAtMs: Date.now(), sequence: sequence, data: data } })));
+    memory.set(keyFor(entry), entry);
+    try {
+        localStorage.setItem(keyFor(entry), JSON.stringify(entry));
+    }
+    catch ( /* Report undurable pending entries below. */_a) { /* Report undurable pending entries below. */ }
+    notify();
+    schedule();
+};
+export var getColourCalibrationUploadState = function (sessionId) {
+    var pending = Array.from(entries()).filter(function (_a) {
+        var entry = _a[1];
+        return entry.sessionId === sessionId;
+    });
+    var inMemoryOnly = false;
+    try {
+        inMemoryOnly = pending.some(function (_a) {
+            var key = _a[0];
+            return localStorage.getItem(key) === null;
+        });
+    }
+    catch (_a) {
+        inMemoryOnly = pending.length > 0;
+    }
+    return { pendingCount: pending.length, inMemoryOnly: inMemoryOnly, temporaryStorage: isPhoneApp() && pending.length > 0,
+        uploading: Boolean(uploading), error: lastError };
+};
+export var subscribeColourCalibrationRecords = function (listener) {
+    listeners.add(listener);
+    return function () { listeners.delete(listener); };
+};
+export var flushColourCalibrationRecords = function () {
+    if (uploading)
+        return uploading;
+    clearTimeout(retry);
+    retry = undefined;
+    uploading = Promise.resolve().then(function () { return __awaiter(void 0, void 0, void 0, function () {
+        var groups, _loop_1, _i, _a, _b, path, group, state_1;
+        return __generator(this, function (_c) {
+            switch (_c.label) {
+                case 0:
+                    groups = new Map();
+                    entries().forEach(function (entry, key) {
+                        var path = "".concat(entry.sessionId, "/calibrations/").concat(entry.attemptId);
+                        groups.set(path, __spreadArray(__spreadArray([], (groups.get(path) || []), true), [[key, entry]], false));
+                    });
+                    _loop_1 = function (path, group) {
+                        var patch, controller, timeout, response, _d, group_1, _e, entry, result, profile, indexed, storageFailure_1, failure_1;
+                        return __generator(this, function (_f) {
+                            switch (_f.label) {
+                                case 0:
+                                    patch = {};
+                                    group.forEach(function (_a) {
+                                        var entry = _a[1];
+                                        if (entry.metadata)
+                                            patch.metadata = entry.metadata;
+                                        // Firebase multi-path PATCH appends events without replacing earlier ones.
+                                        patch["events/".concat(entry.eventId)] = __assign(__assign({}, entry.event), { uploadedAt: { ".sv": "timestamp" } });
+                                    });
+                                    controller = new AbortController();
+                                    timeout = setTimeout(function () { return controller.abort(); }, 15000);
+                                    _f.label = 1;
+                                case 1:
+                                    _f.trys.push([1, 7, 8, 9]);
+                                    return [4 /*yield*/, fetch("".concat(COLOUR_DATABASE_URL, "/colours/").concat(path, ".json"), {
+                                            method: "PATCH", headers: { "Content-Type": "application/json" }, body: JSON.stringify(patch), signal: controller.signal,
+                                        })];
+                                case 2:
+                                    response = _f.sent();
+                                    if (!response.ok)
+                                        throw new Error(response.status === 401 || response.status === 403 ? "uploadDenied" : "uploadFailed");
+                                    _d = 0, group_1 = group;
+                                    _f.label = 3;
+                                case 3:
+                                    if (!(_d < group_1.length)) return [3 /*break*/, 6];
+                                    _e = group_1[_d], entry = _e[1];
+                                    result = entry.event.data.result;
+                                    profile = result === null || result === void 0 ? void 0 : result.classificationProfile;
+                                    if (!(entry.event.type === "save" && entry.event.data.status === "succeeded" && validColourSensorProfile(profile))) return [3 /*break*/, 5];
+                                    return [4 /*yield*/, fetch("".concat(colourSensorProfilePath(profile), "/").concat(entry.attemptId, ".json"), {
+                                            method: "PUT", headers: { "Content-Type": "application/json" }, body: JSON.stringify(profile), signal: controller.signal,
+                                        })];
+                                case 4:
+                                    indexed = _f.sent();
+                                    if (!indexed.ok)
+                                        throw new Error("uploadFailed");
+                                    _f.label = 5;
+                                case 5:
+                                    _d++;
+                                    return [3 /*break*/, 3];
+                                case 6:
+                                    storageFailure_1 = false;
+                                    group.forEach(function (_a) {
+                                        var key = _a[0];
+                                        memory.delete(key);
+                                        try {
+                                            localStorage.removeItem(key);
+                                        }
+                                        catch (_b) {
+                                            storageFailure_1 = true;
+                                        }
+                                    });
+                                    lastError = storageFailure_1 ? "storageUnavailable" : "";
+                                    return [3 /*break*/, 9];
+                                case 7:
+                                    failure_1 = _f.sent();
+                                    lastError = failure_1 instanceof Error ? failure_1.message : "uploadFailed";
+                                    return [2 /*return*/, "break"];
+                                case 8:
+                                    clearTimeout(timeout);
+                                    return [7 /*endfinally*/];
+                                case 9: return [2 /*return*/];
+                            }
+                        });
+                    };
+                    _i = 0, _a = Array.from(groups);
+                    _c.label = 1;
+                case 1:
+                    if (!(_i < _a.length)) return [3 /*break*/, 4];
+                    _b = _a[_i], path = _b[0], group = _b[1];
+                    return [5 /*yield**/, _loop_1(path, group)];
+                case 2:
+                    state_1 = _c.sent();
+                    if (state_1 === "break")
+                        return [3 /*break*/, 4];
+                    _c.label = 3;
+                case 3:
+                    _i++;
+                    return [3 /*break*/, 1];
+                case 4: return [2 /*return*/];
+            }
+        });
+    }); }).finally(function () {
+        uploading = undefined;
+        if (entries().size)
+            schedule(lastError ? 30000 : 500);
+        notify();
+    });
+    notify();
+    return uploading;
+};
+export var startColourCalibrationRecordSync = function () {
+    var online = function () { void flushColourCalibrationRecords(); };
+    window.addEventListener("online", online);
+    online();
+    return function () { window.removeEventListener("online", online); };
+};
+export var createColourCalibrationRecorder = function (sensor, session) {
+    var _a, _b, _c;
+    var ref = { sessionId: session.sessionId, attemptId: id() };
+    var metadata = __assign(__assign({ schemaVersion: 1 }, ref), { sessionStartedAtMs: session.startedAtMs, startedAtMs: Date.now(), appVersion: packageInfo.version, device: { id: sensor.raftId, name: ((_b = (_a = sensor.raft).getFriendlyName) === null || _b === void 0 ? void 0 : _b.call(_a)) || sensor.raftId, type: sensor.raft.type,
+            firmwareVersion: ((_c = sensor.raft.systemInfo) === null || _c === void 0 ? void 0 : _c.SystemVersion) || null, connectionMethod: sensor.raft.connectionMethod || null }, sensor: { id: sensor.addon.id, name: sensor.addon.name, whoAmI: sensor.addon.whoAmI }, classifier: colourPolicy });
+    var sequence = 0;
+    return __assign(__assign({}, ref), { record: function (type, data) { return recordColourCalibrationEvent(ref, type, data, metadata, ++sequence); } });
+};

package/dist-types/src/utils/colour-classifier.d.ts

@@ -0,0 +1,32 @@
+export type RGB = {
+    red: number;
+    green: number;
+    blue: number;
+};
+export type ColourSignalProfile = {
+    airMin: RGB;
+    airMax: RGB;
+    margin: RGB;
+};
+export type ColourName = "red" | "yellow" | "green" | "blue" | "purple" | "air" | "unclear";
+/** Published channels are white-normalised by the SDK; do not clamp them for classification. */
+export declare const classifyColour: (values: RGB & {
+    clear: number;
+    air: boolean;
+}, profile?: ColourSignalProfile) => {
+    classifiedColour: ColourName;
+    colourWithoutAirOverride: ColourName;
+    hue: number | null;
+    chroma: number;
+    saturation: number;
+    signalAboveAir: boolean;
+    signalSource: string;
+    classificationReason: string;
+};
+export declare const colourChannelsFromValues: (vals: Record<string, number | boolean>) => {
+    red: number;
+    green: number;
+    blue: number;
+    clear: number;
+    air: boolean;
+};

package/dist-types/src/utils/colour-classifier.js

@@ -0,0 +1,37 @@
+import policy from "./marty-colour-policy.json";
+/** Published channels are white-normalised by the SDK; do not clamp them for classification. */
+export var classifyColour = function (values, profile) {
+    var r = values.red, g = values.green, b = values.blue, clear = values.clear, air = values.air;
+    var valid = [r, g, b, clear].every(function (value) { return Number.isFinite(value) && value >= 0; }) && typeof air === "boolean";
+    var maximum = Math.max(r, g, b);
+    var chroma = maximum - Math.min(r, g, b);
+    var hue = chroma === 0 ? NaN : r > g && r > b ? (((g - b) / chroma) % 6) * 60 :
+        g > b ? ((b - r) / chroma + 2) * 60 : ((r - g) / chroma + 4) * 60;
+    if (hue < 0)
+        hue += 360;
+    var saturation = maximum > 0 ? chroma / maximum : 0;
+    var match = valid ? policy.boundaries.find(function (colour) { return colour.hue[0] <= hue && hue <= colour.hue[1] &&
+        colour.chroma[0] <= chroma && chroma <= colour.chroma[1]; }) : undefined;
+    var exceedsAir = !profile || ["red", "green", "blue"].some(function (channel) {
+        return values[channel] > profile.airMax[channel] + profile.margin[channel];
+    });
+    var confident = valid && exceedsAir && chroma >= policy.signal.minimumChroma &&
+        saturation >= policy.signal.minimumSaturation;
+    var colourWithoutAirOverride = confident && match ? match.name : "unclear";
+    var classifiedColour = colourWithoutAirOverride !== "unclear" ? colourWithoutAirOverride :
+        valid && air ? "air" : "unclear";
+    return { classifiedColour: classifiedColour, colourWithoutAirOverride: colourWithoutAirOverride, hue: Number.isFinite(hue) ? hue : null, chroma: chroma, saturation: saturation, signalAboveAir: exceedsAir, signalSource: profile ? "calibratedAir" : "defaultRules", classificationReason: !valid ? "invalid" :
+            !exceedsAir ? "withinCalibratedAir" : confident && match ? air ? "rgbOverridesFirmwareAir" : "rgbColour" :
+                air ? "firmwareAir" : "weakOrUnknownColour" };
+};
+export var colourChannelsFromValues = function (vals) {
+    var values = {};
+    for (var key in vals)
+        for (var _i = 0, _a = ["Red", "Green", "Blue", "Clear", "Air"]; _i < _a.length; _i++) {
+            var channel = _a[_i];
+            if (key.includes(channel))
+                values[channel.toLowerCase()] = vals[key];
+        }
+    return { red: values.red, green: values.green, blue: values.blue,
+        clear: values.clear, air: [true, false, 0, 1].includes(values.air) ? Boolean(values.air) : undefined };
+};

package/dist-types/src/utils/colour-sensor-diagnostics.d.ts

@@ -0,0 +1,162 @@
+import colourPolicy from "./marty-colour-policy.json";
+import { ColourSignalProfile } from "./colour-classifier";
+import { ColourSensorProfile } from "./colour-sensor-profile";
+import type { RaftObserver } from "../application/RAFTs/RaftObserver";
+import type { RestMessageOptions } from "../types/communication-between-apps/wrapper-communication";
+import { SensorRead, RawColourFrame, ColourSensorSetup } from "./colour-sensor-registers";
+export declare const CARD_COLOURS: readonly ["green", "purple", "yellow", "blue", "red"];
+export type CardColour = typeof CARD_COLOURS[number];
+export declare const CAPTURE_TARGETS: readonly ["green", "purple", "yellow", "blue", "red", "air"];
+export type CaptureTarget = typeof CAPTURE_TARGETS[number];
+export declare const COLOUR_DATABASE_URL = "https://platforms-error-logging-default-rtdb.europe-west1.firebasedatabase.app";
+export declare const BLOCKS_COLOUR_BOUNDARIES: {
+    hue: number[];
+    chroma: number[];
+    clear: number[];
+    name: string;
+}[];
+type SensorAddon = {
+    id: number;
+    name: string;
+    whoAmI: string;
+    status?: number;
+    vals: Record<string, number | boolean>;
+};
+export type DiagnosticRaft = {
+    type: string;
+    isVerified: boolean;
+    connectionInstanceId?: string;
+    getFriendlyName?: () => string;
+    systemInfo?: {
+        SystemVersion?: string;
+        HardwareVersion?: string;
+    } | null;
+    connectionMethod?: string | null;
+    sendRestMessage?: (message: string, params?: object, options?: RestMessageOptions) => Promise<unknown>;
+    subscribe?: (observer: RaftObserver, topics: string[]) => void;
+    unsubscribe?: (observer: RaftObserver) => void;
+    raftStateInfo?: {
+        addOnInfoValidMs: number;
+        addOnInfo: {
+            addons: SensorAddon[];
+        };
+        powerValidMs?: number;
+        power?: {
+            powerStatus: {
+                power5VIsOn: boolean;
+                [key: string]: unknown;
+            };
+        };
+    } | null;
+};
+export type ColourSensor = {
+    key: string;
+    raftId: string;
+    raft: DiagnosticRaft;
+    addon: SensorAddon;
+};
+export type ColourReading = {
+    observedAtMs: number;
+    receivedAtMs: number;
+    ageMs: number;
+    red: number;
+    green: number;
+    blue: number;
+    clear: number;
+    isOnAir: boolean;
+    hex: string;
+    hue: number | null;
+    chroma: number;
+    classifiedColour: string;
+    colourWithoutAirOverride?: string;
+    saturation?: number;
+    signalAboveAir?: boolean;
+    classificationReason?: string;
+    signalSource?: string;
+    irFootSensors?: SensorAddon[];
+    publishedValues: Record<string, number | boolean>;
+    sensorStatus: number | null;
+};
+export type ColourSnapshot = {
+    schemaVersion: 1 | 2;
+    sessionId: string;
+    sessionStartedAtMs: number;
+    captureId: string;
+    expectedColour: CaptureTarget;
+    startedAtMs: number;
+    finishedAtMs: number;
+    appVersion: string;
+    classifier: {
+        source: string;
+        airFlagTakesPrecedence: boolean;
+        boundaries: typeof BLOCKS_COLOUR_BOUNDARIES;
+        signal?: typeof colourPolicy.signal;
+        profile?: ColourSensorProfile;
+        clearBoundsUsedForClassification?: boolean;
+    };
+    device: {
+        id: string;
+        type: string;
+        name: string;
+        firmwareVersion: string | null;
+        connectionMethod: string | null;
+    };
+    sensor: {
+        id: number;
+        name: string;
+        whoAmI: string;
+    };
+    sampleIntervalMs: number;
+    sampleCount: number;
+    samples: ColourReading[];
+    sampleWindowStartedAtMs?: number;
+    sensorSetup?: ColourSensorSetup;
+    rawSamples?: SensorRead<RawColourFrame>[];
+    powerStatus?: {
+        receivedAtMs: number;
+        values: {
+            power5VIsOn: boolean;
+            [key: string]: unknown;
+        };
+    };
+};
+export type ColourSession = {
+    schemaVersion: 1;
+    sessionId: string;
+    startedAtMs: number;
+    captures: {
+        snapshot: ColourSnapshot;
+        uploaded: boolean;
+    }[];
+};
+export type DiagnosticErrorCode = "sensorDisconnected" | "staleReading" | "invalidReading" | "backgrounded" | "uploadDenied" | "uploadFailed" | "cancelled" | "sensorInitialising" | "sensorAsleep" | "sensorOffline" | "sensorPowerFailed" | "calibrationReconnectRequired" | "sensorBusy";
+export declare class ColourDiagnosticError extends Error {
+    code: DiagnosticErrorCode;
+    constructor(code: DiagnosticErrorCode);
+}
+export declare const newColourSession: () => ColourSession;
+export declare const getColourSensors: (raftId: string) => ColourSensor[];
+export declare const assertColourSensorActive: (sensor: ColourSensor, signal: AbortSignal) => void;
+export declare const interpretColour: (vals: Record<string, number | boolean>, profile?: ColourSignalProfile) => {
+    red: number;
+    green: number;
+    blue: number;
+    clear: number;
+    isOnAir: boolean;
+    hex: string;
+    classifiedColour: import("./colour-classifier").ColourName;
+    colourWithoutAirOverride: import("./colour-classifier").ColourName;
+    hue: number | null;
+    chroma: number;
+    saturation: number;
+    signalAboveAir: boolean;
+    signalSource: string;
+    classificationReason: string;
+};
+export declare const readColourSensor: (sensor: ColourSensor) => ColourReading;
+export declare const captureColourSnapshot: (sensor: ColourSensor, expectedColour: CaptureTarget, session: ColourSession, signal: AbortSignal) => Promise<ColourSnapshot>;
+export declare const uploadColourSnapshot: (snapshot: ColourSnapshot, signal: AbortSignal) => Promise<void>;
+export declare const loadColourSession: () => ColourSession;
+export declare const persistColourSession: (session: ColourSession) => boolean;
+export declare const downloadColourSession: (session: ColourSession) => void;
+export {};