@tempivo/sensor-beacon 1.1.7 → 1.1.9

package/dist/cellular-network-status.js

@@ -0,0 +1,292 @@
+/**
+ * Parse GATT cellular network status JSON and format short partner-facing labels
+ * (same vocabulary as the Tempivo app: No SIM, No internet, No server, …).
+ */
+import { getOperatorNameFromPlmn } from './plmn-labels.js';
+const REGISTERED_STATUSES = new Set(['REGISTERED', 'REGISTERED_ROAMING']);
+const OK_COMM_STATUSES = new Set(['OK', 'OK_NO_DATA_TO_SEND']);
+const OK_SIM_CARD_STATUSES = new Set(['OK']);
+const LABELS_EN = {
+    statusOk: 'Cellular and server OK.',
+    statusServer: (serverStatus) => `Server: ${serverStatus}.`,
+    statusCloudPending: 'Cloud contact may take a minute.',
+    statusUnregistered: 'Not registered on the network.',
+    statusNoIp: 'No IP assigned. Check SIM and coverage.',
+    serverOk: 'Server OK',
+    noNetwork: 'No network',
+    noInternet: 'No internet',
+    simError: 'SIM error',
+    simMissing: 'No SIM',
+    simPin: 'SIM PIN required',
+    unavailable: 'Unavailable',
+    comm: {
+        OK: 'OK',
+        OK_NO_DATA_TO_SEND: 'OK',
+        UNKNOWN: 'No cloud contact yet',
+        DNS_ERROR: 'No server',
+        UNAUTHORIZED: 'Server refused',
+        TIMEOUT: 'Timeout',
+        NOT_REGISTERED: 'Not registered',
+        NO_COVERAGE: 'No coverage',
+        SERVER_ERROR: 'Server error',
+        UNEXPECTED_ERROR: 'Send error',
+    },
+};
+const LABELS_SV = {
+    statusOk: 'Mobil och server OK.',
+    statusServer: (serverStatus) => `Server: ${serverStatus}.`,
+    statusCloudPending: 'Molnkontakt kan ta en minut.',
+    statusUnregistered: 'Ej registrerat på nätet.',
+    statusNoIp: 'Ingen IP. Kontrollera SIM och täckning.',
+    serverOk: 'Server OK',
+    noNetwork: 'Inget nät',
+    noInternet: 'Inget internet',
+    simError: 'SIM-fel',
+    simMissing: 'Inget SIM',
+    simPin: 'SIM PIN krävs',
+    unavailable: 'Otillgänglig',
+    comm: {
+        OK: 'OK',
+        OK_NO_DATA_TO_SEND: 'OK',
+        UNKNOWN: 'Ingen molnkontakt än',
+        DNS_ERROR: 'Ingen server',
+        UNAUTHORIZED: 'Server nekade',
+        TIMEOUT: 'Timeout',
+        NOT_REGISTERED: 'Ej registrerat',
+        NO_COVERAGE: 'Ingen täckning',
+        SERVER_ERROR: 'Serverfel',
+        UNEXPECTED_ERROR: 'Sändfel',
+    },
+};
+function labelsFor(locale) {
+    return locale === 'sv' ? LABELS_SV : LABELS_EN;
+}
+export function isValidCellularIpAddress(ip) {
+    if (!ip?.trim())
+        return false;
+    const normalized = ip.trim();
+    if (normalized === '0.0.0.0' || normalized === '0')
+        return false;
+    return !/^0(\.0){3}$/.test(normalized);
+}
+function readIpAddress(raw) {
+    let ip = null;
+    if (typeof raw === 'string' && raw.trim())
+        ip = raw.trim();
+    else if (raw && typeof raw === 'object' && 'value' in raw) {
+        const v = raw.value;
+        if (typeof v === 'string' && v.trim())
+            ip = v.trim();
+    }
+    return isValidCellularIpAddress(ip) ? ip : null;
+}
+function readStringField(obj, key) {
+    const v = obj[key];
+    return typeof v === 'string' && v.trim() ? v.trim() : null;
+}
+function readNumberField(obj, key) {
+    const v = obj[key];
+    return typeof v === 'number' && Number.isFinite(v) ? v : null;
+}
+/** Legacy 0–63 level → dBm (same mapping as Tempivo ingestion). */
+function rssiLevelToDbm(level) {
+    const L = Math.max(0, Math.min(63, Math.round(level)));
+    if (L <= 15)
+        return -110 + L;
+    if (L <= 25)
+        return -94 + (L - 16);
+    if (L <= 35)
+        return -84 + (L - 26);
+    return -74 + ((L - 36) * 26) / 27;
+}
+export function normalizeCellularSignalStrengthDbm(raw) {
+    if (raw == null || !Number.isFinite(raw) || raw === 0 || raw === 99)
+        return null;
+    if (raw >= 0 && raw <= 63)
+        return Math.round(rssiLevelToDbm(raw));
+    return Math.round(raw);
+}
+function readEclField(obj) {
+    for (const key of ['ecl', 'extendedCoverageLevel', 'extendedCoverage', 'coverageExtensionLevel']) {
+        const v = obj[key];
+        const n = typeof v === 'number' && Number.isFinite(v) ? v : Number(v);
+        if (n === 0 || n === 1 || n === 2)
+            return n;
+    }
+    return null;
+}
+function readPlmnField(obj, key) {
+    const v = obj[key];
+    if (typeof v === 'number' && Number.isFinite(v) && v >= 10_000 && v <= 999_999)
+        return Math.trunc(v);
+    if (typeof v === 'string' && /^\d{5,6}$/.test(v.trim()))
+        return Number.parseInt(v.trim(), 10);
+    return null;
+}
+export function parseCellularNetworkStatusObject(obj, legacySession = false) {
+    const signalRaw = readNumberField(obj, 'signalStrength') ?? readNumberField(obj, 'rssi');
+    const rsrpRaw = readNumberField(obj, 'rsrp') ?? readNumberField(obj, 'referenceSignalReceivedPower');
+    return {
+        ipAddress: readIpAddress(obj.ipAddress),
+        registrationStatus: readStringField(obj, 'registrationStatus'),
+        serverCommunicationStatus: readStringField(obj, 'serverCommunicationStatus'),
+        communicationStatus: readStringField(obj, 'communicationStatus'),
+        signalStrengthDbm: normalizeCellularSignalStrengthDbm(signalRaw),
+        ecl: readEclField(obj),
+        rsrpDbm: rsrpRaw == null || !Number.isFinite(rsrpRaw) || rsrpRaw === 0 ? null : Math.round(rsrpRaw),
+        simCardStatus: readStringField(obj, 'simCardStatus'),
+        registeredPlmn: readPlmnField(obj, 'rplmn'),
+        legacySession,
+    };
+}
+/** Parse Gson/SDK JSON from {@link getCellularNetworkStatusJson}. */
+export function parseCellularNetworkStatusJson(json, legacySession = false) {
+    const trimmed = json.trim();
+    if (!trimmed)
+        return null;
+    try {
+        const obj = JSON.parse(trimmed);
+        return parseCellularNetworkStatusObject(obj, legacySession);
+    }
+    catch {
+        return null;
+    }
+}
+export function isCellularRegistrationOk(status) {
+    return status.registrationStatus != null && REGISTERED_STATUSES.has(status.registrationStatus);
+}
+export function isSimCardOk(status) {
+    if (!status.simCardStatus?.trim())
+        return true;
+    return OK_SIM_CARD_STATUSES.has(status.simCardStatus.trim().toUpperCase());
+}
+export function isCellularServerCommunicationOk(status) {
+    if (status.legacySession) {
+        return status.communicationStatus != null && OK_COMM_STATUSES.has(status.communicationStatus);
+    }
+    return (status.serverCommunicationStatus != null &&
+        OK_COMM_STATUSES.has(status.serverCommunicationStatus));
+}
+export function isCellularConnectionFullyOk(status) {
+    return (isValidCellularIpAddress(status.ipAddress) &&
+        isSimCardOk(status) &&
+        isCellularRegistrationOk(status) &&
+        isCellularServerCommunicationOk(status));
+}
+function rawServerStatus(status) {
+    const raw = status.legacySession ? status.communicationStatus : status.serverCommunicationStatus;
+    return raw?.trim() ? raw.trim() : null;
+}
+function normalizeCommKey(raw) {
+    return raw.toUpperCase().replace(/[\s-]+/g, '_');
+}
+function formatSimLabel(status, L) {
+    const raw = status.simCardStatus?.trim().toUpperCase();
+    if (raw === 'NOT_INSERTED' || raw === 'ABSENT')
+        return L.simMissing;
+    if (raw === 'PIN_REQUIRED')
+        return L.simPin;
+    return L.simError;
+}
+/** Server/cloud detail (Timeout, No server, …). */
+export function formatCellularServerDetailLabel(status, locale = 'en') {
+    const L = labelsFor(locale);
+    const raw = rawServerStatus(status);
+    if (!raw)
+        return L.comm.UNKNOWN;
+    const key = normalizeCommKey(raw);
+    return L.comm[key] ?? raw;
+}
+/**
+ * Short status label for UI (No SIM, No internet, No server, Server OK).
+ * Same mapping as Tempivo live BLE strip (without operator).
+ */
+export function formatCellularNetworkStatusLabel(status, locale = 'en') {
+    const L = labelsFor(locale);
+    if (!isSimCardOk(status))
+        return formatSimLabel(status, L);
+    if (!isValidCellularIpAddress(status.ipAddress))
+        return L.noInternet;
+    if (isCellularServerCommunicationOk(status) && isCellularRegistrationOk(status)) {
+        return L.serverOk;
+    }
+    if (!isCellularRegistrationOk(status))
+        return L.noNetwork;
+    return formatCellularServerDetailLabel(status, locale);
+}
+/** Prefix status with operator when GATT reports a registered PLMN. */
+export function formatCellularNetworkStatusLabelWithOperator(status, locale = 'en') {
+    const statusLabel = formatCellularNetworkStatusLabel(status, locale);
+    const operatorName = getOperatorNameFromPlmn(status.registeredPlmn);
+    if (!operatorName)
+        return statusLabel;
+    return `${operatorName}, ${statusLabel}`;
+}
+/** One short sentence for toasts / logs. */
+export function formatCellularNetworkStatusSummary(status, opts) {
+    const locale = opts?.locale ?? 'en';
+    const L = labelsFor(locale);
+    let body;
+    if (!isSimCardOk(status))
+        body = formatSimLabel(status, L);
+    else if (isCellularConnectionFullyOk(status))
+        body = L.statusOk;
+    else if (!isValidCellularIpAddress(status.ipAddress))
+        body = L.noInternet;
+    else if (isCellularRegistrationOk(status)) {
+        body = opts?.afterServerTrigger
+            ? L.statusCloudPending
+            : L.statusServer(formatCellularServerDetailLabel(status, locale));
+    }
+    else if (isValidCellularIpAddress(status.ipAddress))
+        body = L.statusUnregistered;
+    else
+        body = L.statusNoIp;
+    const operatorName = getOperatorNameFromPlmn(status.registeredPlmn);
+    if (!operatorName)
+        return body;
+    return `${operatorName}. ${body}`;
+}
+export function resolveCellularStatusTone(status) {
+    if (!isSimCardOk(status))
+        return 'bad';
+    if (!isValidCellularIpAddress(status.ipAddress))
+        return 'bad';
+    if (isCellularConnectionFullyOk(status))
+        return 'ok';
+    if (!isCellularRegistrationOk(status))
+        return 'bad';
+    return 'warn';
+}
+/** Build a partner-ready view from raw GATT JSON (no radio). */
+export function cellularNetworkStatusViewFromJson(json, opts) {
+    const locale = opts?.locale ?? 'en';
+    const L = labelsFor(locale);
+    const status = parseCellularNetworkStatusJson(json, opts?.legacySession === true);
+    if (!status) {
+        return {
+            json,
+            status: null,
+            operatorPlmn: null,
+            operatorName: null,
+            label: L.unavailable,
+            statusLabel: L.unavailable,
+            summary: L.unavailable,
+            tone: 'muted',
+        };
+    }
+    const statusLabel = formatCellularNetworkStatusLabel(status, locale);
+    return {
+        json,
+        status,
+        operatorPlmn: status.registeredPlmn,
+        operatorName: getOperatorNameFromPlmn(status.registeredPlmn),
+        label: formatCellularNetworkStatusLabelWithOperator(status, locale),
+        statusLabel,
+        summary: formatCellularNetworkStatusSummary(status, {
+            locale,
+            afterServerTrigger: opts?.afterServerTrigger,
+        }),
+        tone: resolveCellularStatusTone(status),
+    };
+}

package/dist/channel-capability.d.ts

@@ -0,0 +1,43 @@
+import type { TempivoTemperatureAlert } from './session-types.js';
+/** Partner probe alerts map to 1-based measurement channel 3 (0-based index 2). */
+export declare const PROBE_CHANNEL_INDEX_0 = 2;
+/** Normalize ProtoConfig channelTypes entry (int or enum string) to a type id. */
+export declare function measurementTypeId(value: unknown): number | null;
+/**
+ * True when `channelTypes` includes measurement channel 3 (0-based index 2).
+ * Ambient+RH only is typically length 2 → false. Probe / dual layouts are length ≥ 3.
+ */
+export declare function deviceSupportsProbeFromChannelTypes(channelTypes: unknown): boolean;
+/** Parse `0x01` / `01` / `temperature` style labels from scan telemetry. */
+export declare function isTemperatureReadingType(typeHex: unknown): boolean;
+/**
+ * Infer probe from beacon scan readings.
+ * @returns `true` / `false` when readings are present; `null` if unknown (no readings yet).
+ */
+export declare function deviceSupportsProbeFromBeaconReadings(readings: ReadonlyArray<{
+    typeHex?: string | null;
+}> | null | undefined): boolean | null;
+export declare function alertsRequireProbe(alerts: ReadonlyArray<Pick<TempivoTemperatureAlert, 'channel'>> | null | undefined): boolean;
+export type ProbeCapabilitySource = {
+    kind: 'channelTypes';
+    channelTypes: unknown;
+} | {
+    kind: 'beaconReadings';
+    readings: ReadonlyArray<{
+        typeHex?: string | null;
+    }>;
+} | {
+    kind: 'unknown';
+};
+/**
+ * Resolve whether probe alerts are allowed.
+ * `channelTypes` wins when present; else beacon readings; else unknown (do not block).
+ */
+export declare function resolveProbeSupported(source: ProbeCapabilitySource): boolean | null;
+/**
+ * Throw {@link TempivoSensorError} `invalidConfig` when probe alerts target a device without ch3.
+ * No-op when capability is unknown (missing channelTypes / empty scan).
+ */
+export declare function assertProbeAlertsAllowed(alerts: ReadonlyArray<Pick<TempivoTemperatureAlert, 'channel'>> | null | undefined, source: ProbeCapabilitySource): void;
+/** Extract channelTypes from a decoded ProtoConfig object. */
+export declare function channelTypesFromProtoConfig(cfg: unknown): unknown[] | null;

package/dist/channel-capability.js

@@ -0,0 +1,108 @@
+/**
+ * Detect whether the device has a probe (measurement channel 3) so partner
+ * `temperatureAlerts` with `channel: "probe"` are not written to ambient-only sensors.
+ *
+ * Sources (prefer in order):
+ * 1. ProtoConfig `channelTypes` from `getConfiguration` baseline (always available before set)
+ * 2. BLE scan-response readings (frame `0x04`) — count temperature slots
+ */
+import { TempivoSensorError } from './errors.js';
+/** Efento Proto measurement type: temperature. */
+const MEASUREMENT_TYPE_TEMPERATURE = 1;
+/** Partner probe alerts map to 1-based measurement channel 3 (0-based index 2). */
+export const PROBE_CHANNEL_INDEX_0 = 2;
+function isRecord(v) {
+    return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+/** Normalize ProtoConfig channelTypes entry (int or enum string) to a type id. */
+export function measurementTypeId(value) {
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (typeof value === 'string') {
+        const s = value.trim();
+        if (!s)
+            return null;
+        if (/^\d+$/.test(s))
+            return Number(s);
+        if (/TEMPERATURE/i.test(s))
+            return MEASUREMENT_TYPE_TEMPERATURE;
+        // Unknown enum name: treat as present non-temp when checking length only.
+        return -1;
+    }
+    return null;
+}
+/**
+ * True when `channelTypes` includes measurement channel 3 (0-based index 2).
+ * Ambient+RH only is typically length 2 → false. Probe / dual layouts are length ≥ 3.
+ */
+export function deviceSupportsProbeFromChannelTypes(channelTypes) {
+    if (!Array.isArray(channelTypes) || channelTypes.length <= PROBE_CHANNEL_INDEX_0) {
+        return false;
+    }
+    // Prefer a real temperature on ch3; any allocated slot still means the channel exists.
+    const probeType = measurementTypeId(channelTypes[PROBE_CHANNEL_INDEX_0]);
+    return probeType != null;
+}
+/** Parse `0x01` / `01` / `temperature` style labels from scan telemetry. */
+export function isTemperatureReadingType(typeHex) {
+    if (typeof typeHex !== 'string')
+        return false;
+    const s = typeHex.trim().toLowerCase();
+    if (s === 'temperature' || s.includes('temperature'))
+        return true;
+    const m = s.match(/^0x([0-9a-f]+)$/i) || s.match(/^([0-9a-f]+)$/i);
+    if (!m)
+        return false;
+    return parseInt(m[1], 16) === MEASUREMENT_TYPE_TEMPERATURE;
+}
+/**
+ * Infer probe from beacon scan readings.
+ * @returns `true` / `false` when readings are present; `null` if unknown (no readings yet).
+ */
+export function deviceSupportsProbeFromBeaconReadings(readings) {
+    if (!Array.isArray(readings) || readings.length === 0)
+        return null;
+    const tempCount = readings.filter((r) => isTemperatureReadingType(r?.typeHex)).length;
+    return tempCount >= 2;
+}
+export function alertsRequireProbe(alerts) {
+    return (alerts ?? []).some((a) => a.channel === 'probe');
+}
+/**
+ * Resolve whether probe alerts are allowed.
+ * `channelTypes` wins when present; else beacon readings; else unknown (do not block).
+ */
+export function resolveProbeSupported(source) {
+    if (source.kind === 'channelTypes') {
+        if (!Array.isArray(source.channelTypes))
+            return null;
+        return deviceSupportsProbeFromChannelTypes(source.channelTypes);
+    }
+    if (source.kind === 'beaconReadings') {
+        return deviceSupportsProbeFromBeaconReadings(source.readings);
+    }
+    return null;
+}
+/**
+ * Throw {@link TempivoSensorError} `invalidConfig` when probe alerts target a device without ch3.
+ * No-op when capability is unknown (missing channelTypes / empty scan).
+ */
+export function assertProbeAlertsAllowed(alerts, source) {
+    if (!alertsRequireProbe(alerts))
+        return;
+    const supported = resolveProbeSupported(source);
+    if (supported === null)
+        return;
+    if (supported)
+        return;
+    throw new TempivoSensorError('invalidConfig', 'temperatureAlerts use channel "probe" but this device has no probe measurement channel (only ambient). Use channel "ambient" or a sensor with an external probe.');
+}
+/** Extract channelTypes from a decoded ProtoConfig object. */
+export function channelTypesFromProtoConfig(cfg) {
+    if (!isRecord(cfg))
+        return null;
+    const raw = cfg.channelTypes ?? cfg.channel_types;
+    if (!Array.isArray(raw) || raw.length === 0)
+        return null;
+    return raw;
+}

package/dist/config-errors.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Decode ProtoConfig.configurationErrors (uint32 codes) from BLE get.
+ * Wire: (side << 14) | (parameter << 8) | value
+ */
+export type TempivoConfigErrorSide = 'BLE' | 'SERVER' | 'INTERNAL' | 'UNRECOGNIZED';
+export type TempivoConfigErrorParameter = 'RULE0' | 'RULE1' | 'RULE2' | 'RULE3' | 'RULE4' | 'RULE5' | 'RULE6' | 'RULE7' | 'RULE8' | 'RULE9' | 'RULE10' | 'RULE11' | 'CACHE' | 'MEASUREMENT_PERIOD' | 'BLE_TURNOFF_TIME' | 'TRANSFER_LIMIT' | 'TRANSMISSION_INTERVAL' | 'DATA_SERVER_CONFIG' | 'UPDATE_SERVER_CONFIG' | 'CLOUD_TOKEN' | 'SUPERVISION_PERIOD' | 'DEVICE_INFO_ENDPOINT' | 'TIME_ENDPOINT' | 'BLUETOOTH_TX_POWER' | 'TIME_SYNCHRONIZATION_CONFIG' | 'DNS_TTL_CONFIG' | 'CELLULAR_CONFIG' | 'RULE_CALENDAR_0' | 'RULE_CALENDAR_1' | 'RULE_CALENDAR_2' | 'RULE_CALENDAR_3' | 'RULE_CALENDAR_4' | 'RULE_CALENDAR_5' | 'LED' | 'NETWORK' | 'ENCRYPTION' | 'CONFIG_PAYLOAD_OR_REQUEST' | 'DATA_SENDING_ALGORITHM' | 'OUTPUT_CONTROL' | 'UNRECOGNIZED';
+export type TempivoConfigErrorValue = 'NO_ERROR' | 'VALUE_OUT_OF_RANGE' | 'IMPOSSIBLE_TO_CONNECT_TO_THE_SET_SERVER' | 'INVALID_IP_ADDRESS' | 'INVALID_APN' | 'INVALID_PLMN' | 'INVALID_BANDS' | 'INVALID_CLOUD_TOKEN_VALUE' | 'INVALID_CLOUD_TOKEN_CONFIG' | 'INVALID_CONDITION' | 'INVALID_ACTION' | 'INVALID_SLOTS' | 'INVALID_PARAMS' | 'TIMEOUT' | 'INVALID_COAP_ENDPOINT' | 'FAILED_TO_DECODE_PROTOBUF_PAYLOAD' | 'INCORRECT_SENSOR_BEHAVIOR_NO_MEASUREMENTS_AT_PLANNED_TRANSMISSION_OVER_NB_IOT' | 'INVALID_CLOUD_TOKEN_COAP_OPTION' | 'INVALID_PAYLOAD_SIGNATURE_COAP_OPTION' | 'INVALID_DNS_SERVER_IP_ADDRESS' | 'INVALID_COAP_PORT' | 'INVALID_UDP_PORT' | 'INVALID_CHANNEL_CONTROL_REQUEST' | 'INVALID_RULE_MASK' | 'INVALID_CALIBRATION_PARAMETERS_REQUEST' | 'PREVIOUS_CONFIGURATION_IS_IN_PROGRESS' | 'UNRECOGNIZED';
+export type TempivoConfigurationError = {
+    raw: number;
+    side: TempivoConfigErrorSide;
+    parameter: TempivoConfigErrorParameter;
+    value: TempivoConfigErrorValue;
+    /** Short label for logs / UI. */
+    label: string;
+};
+export type TempivoConfigurationErrors = {
+    errors: TempivoConfigurationError[];
+    /** ProtoConfig.configurationErrorTimestamp (unix seconds), or null when unset. */
+    errorTimestampUnix: number | null;
+    /** Same instant as `YYYY-MM-DD HH:mm:ss UTC`, or null when unset. */
+    errorTimestampUtc: string | null;
+};
+export declare function decodeConfigurationError(raw: number): TempivoConfigurationError;
+export declare function decodeConfigurationErrorCodes(rawCodes: number[]): TempivoConfigurationError[];
+/**
+ * Format ProtoConfig.configurationErrorTimestamp as `YYYY-MM-DD HH:mm:ss UTC`.
+ * Accepts unix seconds (number/string) or ISO / loader UTC strings.
+ */
+export declare function formatConfigurationErrorTimestamp(value: unknown): string | null;
+/** Parse `configurationErrors` + timestamp from a decoded ProtoConfig object. */
+export declare function configurationErrorsFromProtoConfig(proto: Record<string, unknown>): TempivoConfigurationErrors;