@tempivo/sensor-beacon 0.1.0 → 0.2.0

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 {};

package/dist/types.d.ts

@@ -7,6 +7,7 @@ export interface SensorBeaconMeasurement {
     humidityPct?: number;
 }
 export interface SensorBeaconReading {
+    /** 12 hex chars from frame 0x03 (uppercase, no colons). */
     serialMac: string;
     firmware: string;
     batteryOk: boolean;
@@ -15,9 +16,8 @@ export interface SensorBeaconReading {
     measurementCounter: number | null;
     readingTimestampUnix: number | null;
     readingTimestampIso: string | null;
-    periodBaseSeconds: number | null;
-    periodFactor: number | null;
-    periodLabel: string;
+    /** Sample interval from the advertisement, in seconds. */
+    measurementIntervalSeconds: number | null;
     measurements: SensorBeaconMeasurement[];
     summary: string;
     temperatures: number[];

package/ios/Package.swift

@@ -0,0 +1,22 @@
+// swift-tools-version: 5.9
+import PackageDescription
+
+let package = Package(
+    name: "TempivoSensorBeacon",
+    platforms: [.iOS(.v15)],
+    products: [
+        .library(
+            name: "TempivoSensorBeacon",
+            targets: ["TempivoSensorBeacon"]
+        ),
+    ],
+    targets: [
+        .target(
+            name: "TempivoSensorBeacon",
+            path: "Sources/TempivoSensorBeacon",
+            linkerSettings: [
+                .linkedFramework("CoreBluetooth"),
+            ]
+        ),
+    ]
+)