@tempivo/sensor-beacon 0.1.1 → 0.2.0

package/android/library/src/main/java/com/tempivo/sensor/beacon/TempivoSensorSession.kt

@@ -0,0 +1,114 @@
+package com.tempivo.sensor.beacon
+
+import android.app.Application
+import android.content.Context
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.sync.Mutex
+import kotlinx.coroutines.sync.withLock
+import kotlinx.coroutines.withContext
+
+/**
+ * GATT session: connect, read/write alert rules and schedule, trigger uplink, read lab calibration date.
+ */
+class TempivoSensorSession(
+    context: Context,
+) {
+    enum class SessionType {
+        MODERN,
+        LEGACY,
+    }
+
+    data class TriggerResult(
+        val ok: Boolean,
+        val supported: Boolean,
+    )
+
+    private val application = context.applicationContext as Application
+    private val mutex = Mutex()
+    private var session: SensorBleRuntime.Session? = null
+
+    suspend fun connect(
+        serial: String,
+        bluetoothMac: String,
+        pin: String,
+        sessionType: SessionType = SessionType.MODERN,
+    ) {
+        val pinInt =
+            pin.trim().toIntOrNull()
+                ?: throw TempivoSensorException(TempivoSensorException.Code.INVALID_PIN, "PIN must be numeric.")
+        try {
+            mutex.withLock {
+                SensorBleRuntime.disconnect(session)
+                session = null
+                session =
+                    withContext(Dispatchers.Main) {
+                        SensorBleRuntime.connect(
+                            application = application,
+                            serial = TempivoSensorQrParser.normalizeSerial(serial),
+                            bluetoothMac = bluetoothMac,
+                            pin = pinInt,
+                            legacy = sessionType == SessionType.LEGACY,
+                        )
+                    }
+            }
+        } catch (e: Throwable) {
+            throw SensorBleRuntime.mapError(e).let {
+                if (it.code == TempivoSensorException.Code.UNKNOWN) {
+                    TempivoSensorException(TempivoSensorException.Code.CONNECT_FAILED, "Could not connect.", e)
+                } else {
+                    it
+                }
+            }
+        }
+    }
+
+    suspend fun connect(qr: TempivoSensorQr) {
+        connect(qr.serial, qr.bluetoothMac, qr.pin, qr.sessionType)
+    }
+
+    suspend fun disconnect() {
+        mutex.withLock {
+            SensorBleRuntime.disconnect(session)
+            session = null
+        }
+    }
+
+    suspend fun getConfiguration(): TempivoSensorConfiguration {
+        return runGatt {
+            SensorBleRuntime.decompile(SensorBleRuntime.readConfiguration(requireSession()))
+        }
+    }
+
+    suspend fun getConfigurationJson(): String = TempivoSensorProfile.toJson(getConfiguration())
+
+    suspend fun setConfiguration(configuration: TempivoSensorConfiguration) {
+        val (rules, calendars) = SensorBleRuntime.compileRules(configuration)
+        runGatt {
+            SensorBleRuntime.writeRules(requireSession(), rules, calendars)
+        }
+    }
+
+    suspend fun setConfigurationJson(json: String) {
+        setConfiguration(TempivoSensorProfile.parseJson(json))
+    }
+
+    suspend fun triggerTransmission(): TriggerResult {
+        return runGatt { SensorBleRuntime.triggerTransmission(requireSession()) }
+    }
+
+    suspend fun getCalibration(): TempivoSensorCalibration {
+        return runGatt { SensorBleRuntime.readCalibration(requireSession()) }
+    }
+
+    private fun requireSession(): SensorBleRuntime.Session =
+        session
+            ?: throw TempivoSensorException(TempivoSensorException.Code.NOT_CONNECTED, "Not connected.")
+
+    private suspend fun <T> runGatt(block: suspend () -> T): T {
+        try {
+            return mutex.withLock { block() }
+        } catch (e: Throwable) {
+            throw SensorBleRuntime.mapError(e)
+        }
+    }
+}

package/android/settings.gradle

@@ -11,6 +11,7 @@ dependencyResolutionManagement {
     repositories {
         google()
         mavenCentral()
+        maven { url "https://maven.efento.io/releases" }
     }
 }
 

package/dist/calibration.d.ts

@@ -0,0 +1,7 @@
+import type { TempivoSensorCalibration } from './session-types.js';
+/**
+ * Device extended config may send lab date as Unix seconds or as days since 1970.
+ * Values below 100_000 are treated as days (year 2243 in seconds, year 2243 in days is far larger).
+ */
+export declare function decodeLaboratoryCalibrationTimestamp(raw: number | null | undefined): TempivoSensorCalibration;
+export declare function calibrationFromExtendedJson(json: string): TempivoSensorCalibration;

package/dist/calibration.js

@@ -0,0 +1,42 @@
+const SECONDS_PER_DAY = 86_400;
+function pad2(n) {
+    return n < 10 ? `0${n}` : String(n);
+}
+function isoDateUtcFromUnixSeconds(seconds) {
+    const d = new Date(seconds * 1000);
+    return `${d.getUTCFullYear()}-${pad2(d.getUTCMonth() + 1)}-${pad2(d.getUTCDate())}`;
+}
+function isoDateUtcFromEpochDays(days) {
+    return isoDateUtcFromUnixSeconds(days * SECONDS_PER_DAY);
+}
+/**
+ * Device extended config may send lab date as Unix seconds or as days since 1970.
+ * Values below 100_000 are treated as days (year 2243 in seconds, year 2243 in days is far larger).
+ */
+export function decodeLaboratoryCalibrationTimestamp(raw) {
+    if (raw == null || !Number.isFinite(raw) || raw <= 0) {
+        return { laboratoryCalibrationDate: null, laboratoryCalibrationTimestamp: null };
+    }
+    const n = Math.trunc(raw);
+    if (n < 100_000) {
+        return {
+            laboratoryCalibrationDate: isoDateUtcFromEpochDays(n),
+            laboratoryCalibrationTimestamp: n,
+        };
+    }
+    return {
+        laboratoryCalibrationDate: isoDateUtcFromUnixSeconds(n),
+        laboratoryCalibrationTimestamp: n,
+    };
+}
+export function calibrationFromExtendedJson(json) {
+    try {
+        const o = JSON.parse(json);
+        const raw = o.laboratoryCalibrationTimestamp ?? o.laboratory_calibration_date;
+        const n = typeof raw === 'number' ? raw : typeof raw === 'string' ? Number(raw) : null;
+        return decodeLaboratoryCalibrationTimestamp(Number.isFinite(n) ? n : null);
+    }
+    catch {
+        return { laboratoryCalibrationDate: null, laboratoryCalibrationTimestamp: null };
+    }
+}

package/dist/decoder.js

@@ -151,9 +151,7 @@ function fw5Summary(frame) {
     return `FW 5.x ${maj}.${min} (limited broadcast decode)`;
 }
 function serialMacFromAdv03(frame) {
-    return Array.from(frame.subarray(1, 7))
-        .map((x) => (x & 0xff).toString(16).padStart(2, '0').toUpperCase())
-        .join(':');
+    return serialKeyFromAdv03Frame(frame) ?? '';
 }
 function parseFw6Adv03(frame) {
     if (frame.length < ADV_FRAME_03_LEN)
@@ -183,9 +181,7 @@ function parseFw6Adv03(frame) {
         measurementCounter: ts >>> 0,
         readingTimestampUnix: ts,
         readingTimestampIso,
-        periodBaseSeconds: pbase,
-        periodFactor: pfact,
-        periodLabel: `${pbase}s × ${pfact}`,
+        measurementIntervalSeconds: pbase * pfact,
     };
 }
 function parseScan04(frame) {
@@ -230,9 +226,7 @@ export function buildSensorBeaconReading(adv03, adv04, rawHex = '') {
         measurementCounter: null,
         readingTimestampUnix: null,
         readingTimestampIso: null,
-        periodBaseSeconds: null,
-        periodFactor: null,
-        periodLabel: '',
+        measurementIntervalSeconds: null,
     };
     if (adv03?.length) {
         const tag = u8(adv03, 0);
@@ -282,9 +276,7 @@ export function buildSensorBeaconReading(adv03, adv04, rawHex = '') {
         measurementCounter: base.measurementCounter ?? null,
         readingTimestampUnix: base.readingTimestampUnix ?? null,
         readingTimestampIso: base.readingTimestampIso ?? null,
-        periodBaseSeconds: base.periodBaseSeconds ?? null,
-        periodFactor: base.periodFactor ?? null,
-        periodLabel: base.periodLabel || '—',
+        measurementIntervalSeconds: base.measurementIntervalSeconds ?? null,
         measurements,
         summary: sumOut,
         temperatures,

package/dist/errors.d.ts

@@ -0,0 +1,6 @@
+/** Partner-facing error codes. Native runtimes map internal exceptions to these. */
+export type TempivoSensorErrorCode = 'invalidPin' | 'invalidQr' | 'invalidConfig' | 'notConnected' | 'unsupportedCommand' | 'runtimeUnavailable' | 'connectFailed' | 'unknown';
+export declare class TempivoSensorError extends Error {
+    readonly code: TempivoSensorErrorCode;
+    constructor(code: TempivoSensorErrorCode, message: string);
+}

package/dist/errors.js

@@ -0,0 +1,8 @@
+export class TempivoSensorError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'TempivoSensorError';
+        this.code = code;
+    }
+}

package/dist/index.d.ts

@@ -1,5 +1,10 @@
-export { ADV_FRAME_03_LEN, TEMPVO_SENSOR_MANUFACTURER_ID, buildSensorBeaconReading, decodeMeasurementSlot, decodeSensorBeaconPayload, legacyHintFromFirmware, lookupDeviceKeys, macKeyFromAddress, serialKeyFromAdv03Frame, splitSensorBeaconFrames, } from './decoder.js';
+export { ADV_FRAME_03_LEN, TEMPVO_SENSOR_MANUFACTURER_ID, buildSensorBeaconReading, decodeMeasurementSlot, decodeSensorBeaconPayload, lookupDeviceKeys, macKeyFromAddress, serialKeyFromAdv03Frame, splitSensorBeaconFrames, } from './decoder.js';
 export { ingestManufacturerPayload } from './ingest.js';
 export { dataViewToUint8Array, normalizeManufacturerBytes } from './normalize.js';
 export { MEASURE_SPECS, type MeasureSpec } from './measure-specs.js';
 export { createSensorBeaconFrameCache, type SensorBeaconFrameCache, type SensorBeaconMeasurement, type SensorBeaconReading, } from './types.js';
+export { TempivoSensorError, type TempivoSensorErrorCode } from './errors.js';
+export { DEFAULT_SENSOR_MODEL, bluetoothMacFromSerial, normalizeSensorSerial, encodeSensorPinPayload, parseSensorQrJson, sessionTypeFromModel, } from './qr.js';
+export { calibrationFromExtendedJson, decodeLaboratoryCalibrationTimestamp, } from './calibration.js';
+export { DEFAULT_ALERT_HYSTERESIS_C, compileSensorProfileToBleJson, configurationFromApiProfile, parseSensorConfiguration, parseSensorConfigurationJson, pickPartnerConfigurationJson, } from './profile.js';
+export type { TempivoSchedule, TempivoScheduleAlways, TempivoScheduleWeek, TempivoSensorCalibration, TempivoSensorConfiguration, TempivoSensorQr, TempivoSensorSessionType, TempivoTemperatureAlert, TempivoTemperatureChannel, TempivoTemperatureMaxAlert, TempivoTemperatureMinAlert, TempivoTemperatureRangeAlert, TempivoTriggerTransmissionResult, } from './session-types.js';

package/dist/index.js

@@ -1,5 +1,9 @@
-export { ADV_FRAME_03_LEN, TEMPVO_SENSOR_MANUFACTURER_ID, buildSensorBeaconReading, decodeMeasurementSlot, decodeSensorBeaconPayload, legacyHintFromFirmware, lookupDeviceKeys, macKeyFromAddress, serialKeyFromAdv03Frame, splitSensorBeaconFrames, } from './decoder.js';
+export { ADV_FRAME_03_LEN, TEMPVO_SENSOR_MANUFACTURER_ID, buildSensorBeaconReading, decodeMeasurementSlot, decodeSensorBeaconPayload, lookupDeviceKeys, macKeyFromAddress, serialKeyFromAdv03Frame, splitSensorBeaconFrames, } from './decoder.js';
 export { ingestManufacturerPayload } from './ingest.js';
 export { dataViewToUint8Array, normalizeManufacturerBytes } from './normalize.js';
 export { MEASURE_SPECS } from './measure-specs.js';
 export { createSensorBeaconFrameCache, } from './types.js';
+export { TempivoSensorError } from './errors.js';
+export { DEFAULT_SENSOR_MODEL, bluetoothMacFromSerial, normalizeSensorSerial, encodeSensorPinPayload, parseSensorQrJson, sessionTypeFromModel, } from './qr.js';
+export { calibrationFromExtendedJson, decodeLaboratoryCalibrationTimestamp, } from './calibration.js';
+export { DEFAULT_ALERT_HYSTERESIS_C, compileSensorProfileToBleJson, configurationFromApiProfile, parseSensorConfiguration, parseSensorConfigurationJson, pickPartnerConfigurationJson, } from './profile.js';

package/dist/profile.d.ts

@@ -0,0 +1,10 @@
+import type { TempivoSensorConfiguration } from './session-types.js';
+/** Same default as Cellular API config profiles. */
+export declare const DEFAULT_ALERT_HYSTERESIS_C = 1;
+/** Validate Cellular API config-profile JSON for BLE setConfiguration. */
+export declare function parseSensorConfiguration(input: unknown): TempivoSensorConfiguration;
+/** Same as {@link parseSensorConfiguration}: GET `{ profile }` or the profile object. */
+export declare const configurationFromApiProfile: typeof parseSensorConfiguration;
+export declare function parseSensorConfigurationJson(json: string): TempivoSensorConfiguration;
+export declare function compileSensorProfileToBleJson(input: unknown): string;
+export declare function pickPartnerConfigurationJson(json: string): string;

package/dist/profile.js

@@ -0,0 +1,226 @@
+import { TempivoSensorError } from './errors.js';
+const TIME_RE = /^([01]\d|2[0-3]):([0-5]\d)$/;
+/** Same default as Cellular API config profiles. */
+export const DEFAULT_ALERT_HYSTERESIS_C = 1;
+function isRecord(v) {
+    return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+function parseFiniteNumber(v) {
+    if (typeof v === 'number' && Number.isFinite(v))
+        return v;
+    if (typeof v === 'string' && v.trim() !== '') {
+        const n = Number(v);
+        if (Number.isFinite(n))
+            return n;
+    }
+    return undefined;
+}
+function parseChannel(v) {
+    return v === 'ambient' || v === 'probe' ? v : null;
+}
+function parseOptionalBool(v, fallback, field) {
+    if (v === undefined)
+        return fallback;
+    if (typeof v === 'boolean')
+        return v;
+    throw new TempivoSensorError('invalidConfig', `${field} must be a boolean.`);
+}
+function findPairStart(used) {
+    for (let i = 0; i < 11; i++) {
+        if (!used[i] && !used[i + 1])
+            return i;
+    }
+    return null;
+}
+function findFreeSlot(used) {
+    for (let i = 0; i < 12; i++) {
+        if (!used[i])
+            return i;
+    }
+    return null;
+}
+/** Same 12-slot layout as Cellular API, including one extra slot per range with transmitOnReturn. */
+function assertAlertSlotBudget(alerts) {
+    const used = Array(12).fill(false);
+    const returnLowSlots = [];
+    for (const alert of alerts) {
+        if (alert.type === 'range') {
+            const pair = findPairStart(used);
+            if (pair === null) {
+                throw new TempivoSensorError('invalidConfig', 'Not enough free alarm rule slots for another range (need two consecutive slots).');
+            }
+            used[pair] = true;
+            used[pair + 1] = true;
+            if (alert.transmitOnReturn)
+                returnLowSlots.push(pair);
+        }
+        else {
+            const slot = findFreeSlot(used);
+            if (slot === null) {
+                throw new TempivoSensorError('invalidConfig', 'Not enough free alarm rule slots.');
+            }
+            used[slot] = true;
+        }
+    }
+    for (const _low of returnLowSlots) {
+        const slot = findFreeSlot(used);
+        if (slot === null) {
+            throw new TempivoSensorError('invalidConfig', 'Not enough free alarm rule slots for transmit-on-return (OR logic).');
+        }
+        used[slot] = true;
+    }
+}
+function parseSchedule(raw) {
+    if (raw == null)
+        return { always: true };
+    if (!isRecord(raw)) {
+        throw new TempivoSensorError('invalidConfig', 'schedule must be an object.');
+    }
+    if (raw.always === true)
+        return { always: true };
+    const weekdays = raw.weekdays;
+    if (!Array.isArray(weekdays) || weekdays.length === 0) {
+        throw new TempivoSensorError('invalidConfig', 'schedule.weekdays is required.');
+    }
+    const days = [];
+    for (const d of weekdays) {
+        const n = parseFiniteNumber(d);
+        if (n === undefined || !Number.isInteger(n) || n < 0 || n > 6) {
+            throw new TempivoSensorError('invalidConfig', 'schedule.weekdays must be 0 to 6.');
+        }
+        days.push(n);
+    }
+    const from = typeof raw.from === 'string' ? raw.from.trim() : '';
+    const to = typeof raw.to === 'string' ? raw.to.trim() : '';
+    if (!TIME_RE.test(from) || !TIME_RE.test(to)) {
+        throw new TempivoSensorError('invalidConfig', 'schedule.from and schedule.to must be HH:MM.');
+    }
+    const utc = parseFiniteNumber(raw.utcOffsetMinutes);
+    if (utc === undefined || !Number.isInteger(utc)) {
+        throw new TempivoSensorError('invalidConfig', 'schedule.utcOffsetMinutes is required.');
+    }
+    return { weekdays: days, from, to, utcOffsetMinutes: utc };
+}
+function parseAlert(item, index) {
+    if (!isRecord(item)) {
+        throw new TempivoSensorError('invalidConfig', `temperatureAlerts[${index}] must be an object.`);
+    }
+    const channel = parseChannel(item.channel);
+    if (!channel) {
+        throw new TempivoSensorError('invalidConfig', `temperatureAlerts[${index}].channel must be ambient or probe.`);
+    }
+    if (item.hysteresisC !== undefined) {
+        const hystRaw = parseFiniteNumber(item.hysteresisC);
+        if (hystRaw === undefined || hystRaw < 0) {
+            throw new TempivoSensorError('invalidConfig', `temperatureAlerts[${index}].hysteresisC must be a number 0 or greater.`);
+        }
+    }
+    const hysteresisC = parseFiniteNumber(item.hysteresisC) ?? DEFAULT_ALERT_HYSTERESIS_C;
+    const transmitOnBreach = parseOptionalBool(item.transmitOnBreach, true, `temperatureAlerts[${index}].transmitOnBreach`);
+    if (item.type === 'range') {
+        const lowC = parseFiniteNumber(item.lowC);
+        const highC = parseFiniteNumber(item.highC);
+        if (lowC === undefined || highC === undefined) {
+            throw new TempivoSensorError('invalidConfig', `temperatureAlerts[${index}] needs lowC and highC.`);
+        }
+        if (highC <= lowC) {
+            throw new TempivoSensorError('invalidConfig', `temperatureAlerts[${index}]: highC must be greater than lowC.`);
+        }
+        const transmitOnReturn = parseOptionalBool(item.transmitOnReturn, true, `temperatureAlerts[${index}].transmitOnReturn`);
+        return {
+            type: 'range',
+            channel,
+            lowC,
+            highC,
+            hysteresisC,
+            transmitOnBreach,
+            transmitOnReturn,
+        };
+    }
+    if (item.type === 'min') {
+        const minC = parseFiniteNumber(item.minC);
+        if (minC === undefined) {
+            throw new TempivoSensorError('invalidConfig', `temperatureAlerts[${index}] needs minC.`);
+        }
+        return {
+            type: 'min',
+            channel,
+            minC,
+            hysteresisC,
+            transmitOnBreach,
+        };
+    }
+    if (item.type === 'max') {
+        const maxC = parseFiniteNumber(item.maxC);
+        if (maxC === undefined) {
+            throw new TempivoSensorError('invalidConfig', `temperatureAlerts[${index}] needs maxC.`);
+        }
+        return {
+            type: 'max',
+            channel,
+            maxC,
+            hysteresisC,
+            transmitOnBreach,
+        };
+    }
+    throw new TempivoSensorError('invalidConfig', `temperatureAlerts[${index}].type must be range, min, or max.`);
+}
+function looksLikeSimpleProfile(rec) {
+    return (rec.temperatureAlerts !== undefined ||
+        rec.schedule !== undefined ||
+        typeof rec.slug === 'string');
+}
+/**
+ * GET /devices/config-profiles/{slug} returns `{ profile }`. Also accepts the profile object.
+ */
+function unwrapApiProfile(input) {
+    if (Array.isArray(input.profiles)) {
+        throw new TempivoSensorError('invalidConfig', 'Pass one profile from GET /devices/config-profiles/{slug}, not the list.');
+    }
+    const nested = input.profile;
+    if (isRecord(nested) && looksLikeSimpleProfile(nested)) {
+        return nested;
+    }
+    return input;
+}
+function rejectWireAlarmRules(rec) {
+    if (rec.temperatureAlerts === undefined && rec.alarmRules !== undefined) {
+        throw new TempivoSensorError('invalidConfig', 'Use a config profile with temperatureAlerts (GET /devices/config-profiles/{slug}), not alarmRules.');
+    }
+}
+/** Validate Cellular API config-profile JSON for BLE setConfiguration. */
+export function parseSensorConfiguration(input) {
+    if (!isRecord(input)) {
+        throw new TempivoSensorError('invalidConfig', 'Configuration must be a JSON object.');
+    }
+    const body = unwrapApiProfile(input);
+    rejectWireAlarmRules(body);
+    const alertsRaw = body.temperatureAlerts;
+    if (alertsRaw !== undefined && !Array.isArray(alertsRaw)) {
+        throw new TempivoSensorError('invalidConfig', 'temperatureAlerts must be an array.');
+    }
+    const temperatureAlerts = (alertsRaw ?? []).map((item, i) => parseAlert(item, i));
+    assertAlertSlotBudget(temperatureAlerts);
+    return {
+        temperatureAlerts,
+        schedule: parseSchedule(body.schedule),
+    };
+}
+/** Same as {@link parseSensorConfiguration}: GET `{ profile }` or the profile object. */
+export const configurationFromApiProfile = parseSensorConfiguration;
+export function parseSensorConfigurationJson(json) {
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch {
+        throw new TempivoSensorError('invalidConfig', 'Configuration is not valid JSON.');
+    }
+    return parseSensorConfiguration(parsed);
+}
+export function compileSensorProfileToBleJson(input) {
+    return JSON.stringify(parseSensorConfiguration(input));
+}
+export function pickPartnerConfigurationJson(json) {
+    return JSON.stringify(parseSensorConfigurationJson(json));
+}

package/dist/qr.d.ts

@@ -0,0 +1,16 @@
+import type { TempivoSensorQr, TempivoSensorSessionType } from './session-types.js';
+export declare function normalizeSensorSerial(value: string): string;
+/** `282C024F0012` → `28:2C:02:4F:00:12`. */
+export declare function bluetoothMacFromSerial(serial: string): string;
+/** BLE default when QR omits `model`. HC5 / FW 6.x still select legacy. */
+export declare const DEFAULT_SENSOR_MODEL = "HC7";
+export declare function sessionTypeFromModel(model: string | undefined | null): TempivoSensorSessionType;
+/**
+ * 3-byte big-endian numeric PIN for GATT command payloads that check a reset code
+ * (`setConfiguration`, trigger, and many other privileged writes).
+ */
+export declare function encodeSensorPinPayload(pin: string): Uint8Array;
+/**
+ * Parse sensor label QR JSON: `{"sn":"…","pin":"…","model":"HC7"}`.
+ */
+export declare function parseSensorQrJson(text: string): TempivoSensorQr;

package/dist/qr.js

@@ -0,0 +1,90 @@
+import { TempivoSensorError } from './errors.js';
+export function normalizeSensorSerial(value) {
+    return value.trim().toUpperCase().replace(/[^A-Z0-9]/g, '');
+}
+/** `282C024F0012` → `28:2C:02:4F:00:12`. */
+export function bluetoothMacFromSerial(serial) {
+    const key = normalizeSensorSerial(serial);
+    if (key.length !== 12 || !/^[0-9A-F]+$/.test(key)) {
+        throw new TempivoSensorError('invalidQr', 'Serial must be 12 hex characters.');
+    }
+    const parts = [];
+    for (let i = 0; i < 12; i += 2)
+        parts.push(key.slice(i, i + 2));
+    return parts.join(':');
+}
+/** BLE default when QR omits `model`. HC5 / FW 6.x still select legacy. */
+export const DEFAULT_SENSOR_MODEL = 'HC7';
+export function sessionTypeFromModel(model) {
+    if (model == null || model.trim() === '')
+        return 'modern';
+    const m = model.trim().toUpperCase().replace(/-/g, '');
+    if (m === 'HC5' || m.startsWith('6'))
+        return 'legacy';
+    return 'modern';
+}
+/**
+ * 3-byte big-endian numeric PIN for GATT command payloads that check a reset code
+ * (`setConfiguration`, trigger, and many other privileged writes).
+ */
+export function encodeSensorPinPayload(pin) {
+    const t = pin.trim();
+    if (!/^\d{1,8}$/.test(t)) {
+        throw new TempivoSensorError('invalidPin', 'PIN must be numeric.');
+    }
+    const n = Number.parseInt(t, 10);
+    if (!Number.isInteger(n) || n < 0 || n > 0xffffff) {
+        throw new TempivoSensorError('invalidPin', 'PIN must fit in 3 bytes.');
+    }
+    return Uint8Array.of((n >> 16) & 0xff, (n >> 8) & 0xff, n & 0xff);
+}
+function pinFromRecord(rec) {
+    const raw = rec.pin ?? rec.resetCode;
+    if (typeof raw === 'string') {
+        const t = raw.trim();
+        return t.length > 0 ? t : undefined;
+    }
+    if (typeof raw === 'number' && Number.isFinite(raw))
+        return String(Math.trunc(raw));
+    return undefined;
+}
+/**
+ * Parse sensor label QR JSON: `{"sn":"…","pin":"…","model":"HC7"}`.
+ */
+export function parseSensorQrJson(text) {
+    let rec;
+    try {
+        const o = JSON.parse(text.trim());
+        if (o === null || typeof o !== 'object' || Array.isArray(o)) {
+            throw new TempivoSensorError('invalidQr', 'QR must be a JSON object.');
+        }
+        rec = o;
+    }
+    catch (e) {
+        if (e instanceof TempivoSensorError)
+            throw e;
+        throw new TempivoSensorError('invalidQr', 'QR is not valid JSON.');
+    }
+    const snRaw = typeof rec.sn === 'string'
+        ? rec.sn
+        : typeof rec.sn === 'number' && Number.isFinite(rec.sn)
+            ? String(Math.trunc(rec.sn))
+            : '';
+    const serial = normalizeSensorSerial(snRaw);
+    const pin = pinFromRecord(rec);
+    if (!serial || serial.length < 8) {
+        throw new TempivoSensorError('invalidQr', 'QR is missing serial (sn).');
+    }
+    if (!pin) {
+        throw new TempivoSensorError('invalidQr', 'QR is missing PIN.');
+    }
+    const rawModel = typeof rec.model === 'string' ? rec.model.trim() : '';
+    const model = rawModel || DEFAULT_SENSOR_MODEL;
+    return {
+        serial,
+        pin,
+        model,
+        sessionType: sessionTypeFromModel(model),
+        bluetoothMac: bluetoothMacFromSerial(serial.length === 12 ? serial : serial.slice(-12)),
+    };
+}

package/dist/session-types.d.ts

@@ -0,0 +1,64 @@
+export type TempivoSensorSessionType = 'modern' | 'legacy';
+export type TempivoTemperatureChannel = 'ambient' | 'probe';
+export type TempivoTemperatureRangeAlert = {
+    type: 'range';
+    channel: TempivoTemperatureChannel;
+    lowC: number;
+    highC: number;
+    hysteresisC?: number;
+    transmitOnBreach?: boolean;
+    /** Extra uplink when temp returns inside the band. Same as Cellular API. Default `true`. */
+    transmitOnReturn?: boolean;
+};
+export type TempivoTemperatureMinAlert = {
+    type: 'min';
+    channel: TempivoTemperatureChannel;
+    minC: number;
+    hysteresisC?: number;
+    transmitOnBreach?: boolean;
+};
+export type TempivoTemperatureMaxAlert = {
+    type: 'max';
+    channel: TempivoTemperatureChannel;
+    maxC: number;
+    hysteresisC?: number;
+    transmitOnBreach?: boolean;
+};
+export type TempivoTemperatureAlert = TempivoTemperatureRangeAlert | TempivoTemperatureMinAlert | TempivoTemperatureMaxAlert;
+export type TempivoScheduleAlways = {
+    always: true;
+};
+export type TempivoScheduleWeek = {
+    /** 0 = Monday … 6 = Sunday. */
+    weekdays: number[];
+    /** 24h `HH:MM`. */
+    from: string;
+    /** 24h `HH:MM`. */
+    to: string;
+    utcOffsetMinutes: number;
+};
+export type TempivoSchedule = TempivoScheduleAlways | TempivoScheduleWeek;
+/**
+ * Same JSON as Cellular API `POST /api/v1/devices/config-profiles`
+ * (`temperatureAlerts` + `schedule`). Extra profile fields (`slug`, `name`, intervals) are ignored over BLE.
+ */
+export type TempivoSensorConfiguration = {
+    temperatureAlerts: TempivoTemperatureAlert[];
+    schedule: TempivoSchedule;
+};
+export type TempivoSensorQr = {
+    serial: string;
+    pin: string;
+    /** Sticker model. Omitted QR `model` parses as HC7. */
+    model?: string;
+    sessionType: TempivoSensorSessionType;
+    bluetoothMac: string;
+};
+export type TempivoSensorCalibration = {
+    laboratoryCalibrationDate: string | null;
+    laboratoryCalibrationTimestamp: number | null;
+};
+export type TempivoTriggerTransmissionResult = {
+    ok: boolean;
+    supported: boolean;
+};

package/dist/session-types.js

@@ -0,0 +1 @@
+export {};