@mongrov/analytics 0.6.0 → 0.8.0

package/dist/sync/mapper/ring-config.js

@@ -1,59 +1,142 @@
 /**
- * Ring config mapper (T-08).
+ * Ring config mapper (T-08, Sprint 5 T-09/T-10).
  *
  * Firmware `ring.automaticMonitoringData[]` describes which metrics the ring
- * currently samples (interval + active hours). We store these as SCD-2-style
- * rows in `device_config`, with `valid_from = now()` and `valid_to = null` on
- * the new insert.
+ * currently samples and on what schedule. We store these as SCD-2-style rows
+ * in `device_config`, with `valid_from = now()` and `valid_to = null` on the
+ * new insert.
+ *
+ * ## The firmware boundary (principles 20 + 21)
+ *
+ * The vendor struct is `AutomaticMonitoring_J2301A` (JStyle J2301A SDK):
+ *
+ * ```c
+ * int mode;
+ * int startTime_Hour;  int startTime_Minutes;
+ * int endTime_Hour;    int endTime_Minutes;
+ * MyWeeks_J2301A weeks;      // 7 booleans
+ * int intervalTime;
+ * int dataType;  // 1 = heartRate, 2 = spo2, 3 = temperature, 4 = HRV
+ * ```
+ *
+ * Everything firmware-shaped is translated here and nothing crosses into
+ * the warehouse: `dataType` becomes our metric id, split hour/minute fields
+ * become `HH:MM` strings, and the seven-boolean `weeks` struct becomes a
+ * bitmask. Principle 21 is explicit that firmware enums must not reach the
+ * schema, so `device_config` stores `metric`, never `data_type`.
+ *
+ * Prior versions inverted this: the mapper's input type had already
+ * discarded `dataType`, so a consumer-supplied `RingConfigTranslator` had
+ * to invent the enum back from our own metric names — the schema ended up
+ * holding a firmware integer that the app, not the firmware, produced.
  *
  * Closing prior config (SCD-2 semantics):
  *   The mapper accepts an optional `activePriorConfigs` map keyed by
- *   `data_type` (integer, produced via the translator). For every metric that
- *   shows up in the new firmware snapshot, if a prior config was open, the
- *   mapper emits a `close` entry so the sink can `UPDATE ... SET valid_to =
- *   now()` locally before the INSERT lands, and enqueue the same directive
- *   for the next remote push cycle. Metrics present in the prior map but
- *   absent from the new firmware are left open (the ring is silent on them,
- *   not disabling them).
- *
- * Translation:
- *   The mapper cannot invent `data_type` integers or `start_time`/`end_time`
- *   strings on its own — those are consumer-specific enumerations. Callers
- *   MUST pass a `RingConfigTranslator` in `opts` (see `mapper/types.ts`).
- *   Without a translator the mapper cannot produce a schema-shaped row, so
- *   the option is required — TypeScript enforces this at every call site.
- *
- * The mapper stays pure: no engine access, no clock reads beyond the injected
- * `now` (defaults to `new Date()` for production).
+ *   metric. For every metric present in the new snapshot, if a prior config
+ *   was open, it emits a `close` entry so the sink can `UPDATE ... SET
+ *   valid_to = now()` before the INSERT lands. Metrics present in the prior
+ *   map but absent from the new snapshot are left open — the ring is silent
+ *   on them, not disabling them.
  */
-export function mapRingConfig(fw, ctx, opts) {
+/**
+ * Firmware `dataType` → our metric id (Sprint 5 T-09).
+ *
+ * Verbatim from the vendor header's own comment. Note this is a **1:1**
+ * map: `dataType = 2` is SpO₂ alone, and temperature is its own code 3.
+ * The Sprint 5 spec described 2 as "spo2 + temperature (shared schedule)"
+ * requiring a fan-out to two rows; the SDK does not agree, so there is
+ * nothing to fan out.
+ *
+ * (Whether firmware *slaves* the two schedules together in practice is a
+ * separate, still-open question — but it would not change this mapping,
+ * only mean the ring reports two windows with identical timings.)
+ */
+export const FIRMWARE_DATA_TYPE_TO_METRIC = Object.freeze({
+    1: 'heart_rate',
+    2: 'spo2',
+    3: 'temperature',
+    4: 'hrv',
+});
+/** Reverse map, for diagnostics and for keying prior-config reads. */
+export const METRIC_TO_FIRMWARE_DATA_TYPE = Object.freeze(Object.fromEntries(Object.entries(FIRMWARE_DATA_TYPE_TO_METRIC).map(([dt, m]) => [m, Number(dt)])));
+/**
+ * Translate a firmware `dataType` to the metric(s) it schedules.
+ *
+ * Returns an array for forward-compatibility — if a future firmware
+ * revision genuinely does share one code across metrics, this signature
+ * absorbs it without a breaking change.
+ *
+ * @throws on an unknown code, with the raw value in the message. Silently
+ *   dropping an unrecognised code would mean a metric the ring is actively
+ *   sampling never appears in `device_config`, and every cadence-dependent
+ *   consumer would fall back to the `metric_metadata` default without
+ *   anyone noticing.
+ */
+export function firmwareDataTypeToMetrics(dataType) {
+    const metric = FIRMWARE_DATA_TYPE_TO_METRIC[dataType];
+    if (metric === undefined) {
+        const known = Object.entries(FIRMWARE_DATA_TYPE_TO_METRIC)
+            .map(([dt, m]) => `${dt}=${m}`)
+            .join(', ');
+        throw new Error(`mapRingConfig: unknown firmware dataType ${dataType}. `
+            + `Known values: ${known}. A new value means the ring firmware added a `
+            + `monitored metric — add it to FIRMWARE_DATA_TYPE_TO_METRIC and to `
+            + `METRIC_METADATA rather than dropping it.`);
+    }
+    return [metric];
+}
+/** Vendor weekday order, LSB = Sunday. */
+const WEEKDAY_ORDER = [
+    'sunday', 'monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday',
+];
+/**
+ * Seven booleans → a 7-bit mask for `device_config.weeks`.
+ * Bit 0 = Sunday … bit 6 = Saturday. All-days is `0x7F`.
+ */
+export function weekdaysToBitmask(weeks) {
+    if (!weeks)
+        return null;
+    let mask = 0;
+    WEEKDAY_ORDER.forEach((day, i) => {
+        if (weeks[day])
+            mask |= 1 << i;
+    });
+    return mask;
+}
+/** `HH:MM`, zero-padded. Null when the firmware supplied out-of-range values. */
+export function formatClockTime(hour, minutes) {
+    if (!Number.isInteger(hour) || hour < 0 || hour > 23)
+        return null;
+    if (!Number.isInteger(minutes) || minutes < 0 || minutes > 59)
+        return null;
+    return `${String(hour).padStart(2, '0')}:${String(minutes).padStart(2, '0')}`;
+}
+export function mapRingConfig(fw, ctx, opts = {}) {
     const now = opts.now ?? new Date();
     const prior = opts.activePriorConfigs ?? new Map();
-    const translator = opts.translator;
     const inserts = [];
     const closes = [];
     for (const window of fw.automaticMonitoringData ?? []) {
-        const dataType = translator.metricToDataType(window.metric);
-        inserts.push(toRow(window, ctx, now, dataType, translator));
-        if (prior.has(dataType)) {
-            closes.push({ device_id: ctx.deviceId, data_type: dataType, valid_to: now });
+        for (const metric of firmwareDataTypeToMetrics(window.dataType)) {
+            inserts.push(toRow(window, ctx, now, metric));
+            if (prior.has(metric)) {
+                closes.push({ device_id: ctx.deviceId, metric, valid_to: now });
+            }
         }
     }
     return { inserts, closes };
 }
-function toRow(window, ctx, now, dataType, translator) {
-    const fields = translator.windowToSchemaFields(window);
+function toRow(window, ctx, now, metric) {
     return {
-        ts: now,
         brand: ctx.brand,
         family_id: ctx.familyId,
         user_id: ctx.userId,
         device_id: ctx.deviceId,
-        data_type: dataType,
-        interval_minutes: window.interval_minutes,
-        start_time: fields.start_time,
-        end_time: fields.end_time,
-        weeks: fields.weeks,
+        metric,
+        interval_minutes: window.intervalTime,
+        start_time: formatClockTime(window.startTime_Hour, window.startTime_Minutes),
+        end_time: formatClockTime(window.endTime_Hour, window.endTime_Minutes),
+        weeks: weekdaysToBitmask(window.weeks),
         valid_from: now,
         valid_to: null,
     };

package/dist/sync/mapper/ring-config.js.map

@@ -1 +1 @@
-{"version":3,"file":"ring-config.js","sourceRoot":"","sources":["../../../src/sync/mapper/ring-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AA6BH,MAAM,UAAU,aAAa,CAC3B,EAAsB,EACtB,GAAkB,EAClB,IAA0B;IAE1B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,IAAI,IAAI,EAAE,CAAA;IAClC,MAAM,KAAK,GAAG,IAAI,CAAC,kBAAkB,IAAI,IAAI,GAAG,EAA2B,CAAA;IAC3E,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,CAAA;IAElC,MAAM,OAAO,GAAsB,EAAE,CAAA;IACrC,MAAM,MAAM,GAAsB,EAAE,CAAA;IAEpC,KAAK,MAAM,MAAM,IAAI,EAAE,CAAC,uBAAuB,IAAI,EAAE,EAAE,CAAC;QACtD,MAAM,QAAQ,GAAG,UAAU,CAAC,gBAAgB,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;QAC3D,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC,CAAA;QAC3D,IAAI,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;YACxB,MAAM,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,GAAG,CAAC,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC,CAAA;QAC9E,CAAC;IACH,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,CAAA;AAC5B,CAAC;AAED,SAAS,KAAK,CACZ,MAAgC,EAChC,GAAkB,EAClB,GAAS,EACT,QAAgB,EAChB,UAAgC;IAEhC,MAAM,MAAM,GAAG,UAAU,CAAC,oBAAoB,CAAC,MAAM,CAAC,CAAA;IACtD,OAAO;QACL,EAAE,EAAE,GAAG;QACP,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,SAAS,EAAE,GAAG,CAAC,QAAQ;QACvB,OAAO,EAAE,GAAG,CAAC,MAAM;QACnB,SAAS,EAAE,GAAG,CAAC,QAAQ;QACvB,SAAS,EAAE,QAAQ;QACnB,gBAAgB,EAAE,MAAM,CAAC,gBAAgB;QACzC,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,UAAU,EAAE,GAAG;QACf,QAAQ,EAAE,IAAI;KACf,CAAA;AACH,CAAC"}
+{"version":3,"file":"ring-config.js","sourceRoot":"","sources":["../../../src/sync/mapper/ring-config.ts"],"names":[],"mappings":"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"}