@openfn/language-varo 2.0.0 → 2.1.1

package/README.md

@@ -239,9 +239,9 @@ openfn workflow.json -m --only convertToEms
 
 Some workflows required authorization to access the resources.
 
-## Gmail token
+## Gmail access token
 
-Use Postman to retrieve an access token. This is a short-lived token will last 60 minutes and will have to be manually retrieved. See the documentation in the [Gmail adaptor readme](https://docs.openfn.org/adaptors/packages/gmail-readme#use-the-postman-application-to-query-the-oauth-enpoint-and-retrieve-an-access-token) for a guide on how to configure Postman to retrieve the access token.
+An access token is required to access the Gmail API. This short-lived token will last 60 minutes and will have to be manually refreshed. See the documentation in the [Gmail adaptor readme](https://docs.openfn.org/adaptors/packages/gmail-readme#retrieve-an-access-token) for a guide on how to use Google Developers OAuth 2.0 Playground to retrieve and refresh the access token.
 
 ## OpenFn collections token
 
@@ -322,10 +322,94 @@ pnpm build
 pnpm run setup
 ```
 
-### Switch to the working branch of the varo adaptor
+### Switch to a working branch of the varo adaptor
 
 ```
 cd openfn/adaptors/adaptors
-git checkout nhgh-varo
+git checkout -b varo-enhancements
 ```
 
+# FridgeTag `records` vs. `zReports`
+
+## Purpose
+
+The FridgeTag parser (`parseFridgeTagToReport`) reads structured device output and emits two parallel data structures: `records` and `zReports`. This dual design allows strict compliance with EMS standards, while also preserving valuable out-of-spec information from the original FridgeTag device logs.
+
+## `records`: EMS-compliant daily extremes
+
+FridgeTag source data provides daily minimum and maximum temperatures, including the exact timestamp each was observed. These data points are directly compatible with EMS requirements, which demand time-stamped records representing sensor readings.
+
+For each day in the log, the parser generates:
+
+- One EMS record for the minimum temperature, and
+- One EMS record for the maximum temperature.
+
+Each record includes:
+- `ABST`: Absolute ISO-8601 timestamp (e.g., `"2024-10-08T08:15:00.000Z"`).
+- `TVC`: Temperature value in °C (e.g., `18.5`).
+- `ALRM`: Optional alarm flag (e.g., `"HEAT"` or `"FRZE"`), derived from alarm conditions.
+- `zdescription`: A label for context (e.g., `"2024-10-08 Min T"`).
+
+Example:
+```json
+{
+  "ABST": "2024-10-08T08:15:00.000Z",
+  "TVC": 18.5,
+  "ALRM": null,
+  "zdescription": "2024-10-08 Min T"
+}
+```
+
+These entries fully conform to EMS specifications and can be directly integrated into compliant pipelines or summaries.
+
+## `zReports`: Out-of-spec aggregates & alarm summaries
+
+In addition to min/max values, FridgeTag records include:
+
+- A daily average temperature,
+- Detailed alarm metadata: including duration of condition (`t Acc`), first alarm timestamp (`TS A`), and alarm count (`C A`).
+
+This information is not compatible with EMS formats, which don't align with aggregated statistics and rich alarm metadata. However, this data remains operationally meaningful, especially for:
+
+- 60-day summary reports,
+- Country-level immunization program dashboards,
+- Quick on-site reviews by technicians.
+
+To retain this data without violating EMS constraints, the parser generates a `zReports` array. Each entry summarizes one day:
+
+```json
+{
+  "date": "2024-10-08T00:00:00.000Z",
+  "duration": "1D",
+  "alarms": [
+    {
+      "condition": "HEAT",
+      "conditionMinutes": 840,
+      "alarmTime": "2024-10-08T00:00:00.000Z"
+    }
+  ],
+  "aggregates": [
+    {
+      "id": "TVC",
+      "min": 18.5,
+      "max": 21.2,
+      "average": 19.2
+    }
+  ]
+}
+```
+
+This structure is deliberately out-of-spec (hence the `z` prefix) and is ignored by EMS consumers. It is retained only for dashboards, exports, and enriched user-facing analytics.
+
+## Design philosophy
+
+This split structure reflects a disciplined compromise between compliance and pragmatism:
+
+- `records`: strictly EMS-compliant atomic data points.
+- `zReports`: high-value extras that don't align with EMS, but still provide value.
+
+This ensures that:
+
+- Nothing is lost from the original FridgeTag data.
+- Downstream EMS systems remain unaffected.
+- Local insights and user-friendly summaries remain rich and actionable.

package/ast.json

@@ -166,6 +166,124 @@
         ]
       },
       "valid": true
+    },
+    {
+      "name": "parseUtcForDataRange",
+      "params": [
+        "timeZone",
+        "startIso",
+        "endIso"
+      ],
+      "docs": {
+        "description": "Computes the UTC datetime range that corresponds to a given IANA timezone.",
+        "tags": [
+          {
+            "title": "public",
+            "description": null,
+            "type": null
+          },
+          {
+            "title": "function",
+            "description": null,
+            "name": null
+          },
+          {
+            "title": "param",
+            "description": "An IANA time zone identifier (e.g. \"America/Los_Angeles\").",
+            "type": {
+              "type": "NameExpression",
+              "name": "string"
+            },
+            "name": "timeZone"
+          },
+          {
+            "title": "param",
+            "description": "Starting date in ISO format.",
+            "type": {
+              "type": "NameExpression",
+              "name": "string"
+            },
+            "name": "startIso"
+          },
+          {
+            "title": "param",
+            "description": "Ending date range in ISO format.",
+            "type": {
+              "type": "NameExpression",
+              "name": "string"
+            },
+            "name": "endIso"
+          },
+          {
+            "title": "returns",
+            "description": null,
+            "type": {
+              "type": "NameExpression",
+              "name": "UtcRange"
+            }
+          }
+        ]
+      },
+      "valid": true
+    },
+    {
+      "name": "isKeyInRange",
+      "params": [
+        "key",
+        "start",
+        "end"
+      ],
+      "docs": {
+        "description": "Checks whether the timestamp embedded in a key falls within a UTC datetime range.",
+        "tags": [
+          {
+            "title": "public",
+            "description": null,
+            "type": null
+          },
+          {
+            "title": "function",
+            "description": null,
+            "name": null
+          },
+          {
+            "title": "param",
+            "description": "A string key containing a UTC timestamp in the format `YYYYMMDDTHHMMSS`, following a colon (e.g. \"prefix:20250624T101530\").",
+            "type": {
+              "type": "NameExpression",
+              "name": "string"
+            },
+            "name": "key"
+          },
+          {
+            "title": "param",
+            "description": "The inclusive lower bound of the UTC datetime range.",
+            "type": {
+              "type": "NameExpression",
+              "name": "Date"
+            },
+            "name": "start"
+          },
+          {
+            "title": "param",
+            "description": "The exclusive upper bound of the UTC datetime range.",
+            "type": {
+              "type": "NameExpression",
+              "name": "Date"
+            },
+            "name": "end"
+          },
+          {
+            "title": "returns",
+            "description": "True if the parsed UTC timestamp is within the range, false otherwise.",
+            "type": {
+              "type": "NameExpression",
+              "name": "boolean"
+            }
+          }
+        ]
+      },
+      "valid": true
     }
   ],
   "exports": [],
@@ -220,7 +338,7 @@
         "operation"
       ],
       "docs": {
-        "description": "A custom operation that will only execute the function if the condition returns true",
+        "description": "Execute a function only when the condition returns true",
         "tags": [
           {
             "title": "public",

package/dist/index.cjs

@@ -33,8 +33,10 @@ __export(src_exports, {
   fields: () => import_language_common2.fields,
   fn: () => import_language_common2.fn,
   fnIf: () => import_language_common2.fnIf,
+  isKeyInRange: () => isKeyInRange,
   lastReferenceValue: () => import_language_common2.lastReferenceValue,
   merge: () => import_language_common2.merge,
+  parseUtcForDataRange: () => parseUtcForDataRange,
   sourceValue: () => import_language_common2.sourceValue
 });
 module.exports = __toCommonJS(src_exports);
@@ -55,12 +57,15 @@ __export(Adaptor_exports, {
   fields: () => import_language_common2.fields,
   fn: () => import_language_common2.fn,
   fnIf: () => import_language_common2.fnIf,
+  isKeyInRange: () => isKeyInRange,
   lastReferenceValue: () => import_language_common2.lastReferenceValue,
   merge: () => import_language_common2.merge,
+  parseUtcForDataRange: () => parseUtcForDataRange,
   sourceValue: () => import_language_common2.sourceValue
 });
 var import_language_common = require("@openfn/language-common");
 var import_util = require("@openfn/language-common/util");
+var import_luxon = require("luxon");
 
 // src/Utils.js
 function parseMetadata(message) {
@@ -79,7 +84,7 @@ function parseMetadata(message) {
 }
 function removeNullProps(obj) {
   for (const key in obj) {
-    if (obj[key] == null) {
+    if (obj[key] === null) {
       delete obj[key];
     }
   }
@@ -126,7 +131,18 @@ function formatDeviceInfo(data) {
   output += formatType("Appliance", data.AMFR, data.AMOD, data.ASER);
   output += formatType("Logger", data.LMFR, data.LMOD, data.LSER);
   output += formatType("EMD", data.EMFR, data.EMOD, data.ESER);
-  return output || "No valid data found";
+  return output || "Cannot determine device info; no valid data found.";
+}
+function abbreviatedIsoToDate(iso) {
+  const [year, month, day, hour, minute, second] = [
+    iso.slice(0, 4),
+    iso.slice(4, 6),
+    iso.slice(6, 8),
+    iso.slice(9, 11),
+    iso.slice(11, 13),
+    iso.slice(13, 15)
+  ];
+  return new Date(`${year}-${month}-${day}T${hour}:${minute}:${second}Z`);
 }
 
 // src/StreamingUtils.js
@@ -202,7 +218,6 @@ function mergeRecords(records, groupKey) {
     }
     if (tambAlrm != null) {
       mergedRecord["zTambAlrm"] = tambAlrm;
-      mergedRecord["ALRM"] = tambAlrm;
     }
     if (tvcAlrm != null) {
       mergedRecord["zTvcAlrm"] = tvcAlrm;
@@ -315,7 +330,7 @@ function promoteDeviceProperties(source, destination) {
 }
 
 // src/VaroEmsUtils.js
-function parseVaroEmsToReport(metadata, data, dataPath2) {
+function parseVaroEmsToReport(metadata, data, rtcwMaps) {
   const report = {
     CID: null,
     LAT: metadata.location.used.latitude,
@@ -339,10 +354,14 @@ function parseVaroEmsToReport(metadata, data, dataPath2) {
     LSV: data.LSV,
     records: []
   };
-  const deviceDate = parseRelativeDateFromUsbPluggedInfo(dataPath2);
+  removeNullProps(report);
   for (const item of data.records) {
-    const durations = [item.RELT];
-    const absoluteDate = parseAdjustedDate(deviceDate, durations);
+    const deviceDate = rtcwMaps.get(item.RTCW);
+    if (!deviceDate) {
+      report.zHasUnreconciledRtcw = true;
+      continue;
+    }
+    const absoluteDate = applyDurationToDate(deviceDate, item.RELT);
     const abst = parseIsoToAbbreviatedIso(absoluteDate);
     const record = {
       ABST: abst,
@@ -359,67 +378,82 @@ function parseVaroEmsToReport(metadata, data, dataPath2) {
       TAMB: item.TAMB,
       TVC: item.TVC
     };
+    removeNullProps(record);
     report.records.push(record);
   }
   return report;
 }
-function parseRelativeDateFromUsbPluggedInfo(path) {
-  const regex = /_CURRENT_DATA_(?<duration>\w+?)_(?<date>\w+?)\.json$/;
-  const match = path.match(regex);
-  if (!match) {
-    throw new Error(`Path format is incorrect: ${path}`);
+function applyDurationToDate(incomingDate, duration, subtract = false) {
+  const date = normalizeIncomingDate(incomingDate);
+  const parsedDuration = parseDuration(duration, subtract);
+  if (!parsedDuration)
+    return date;
+  date.setUTCDate(date.getUTCDate() + parsedDuration.days);
+  date.setUTCHours(date.getUTCHours() + parsedDuration.hours);
+  date.setUTCMinutes(date.getUTCMinutes() + parsedDuration.minutes);
+  date.setUTCSeconds(date.getUTCSeconds() + parsedDuration.seconds);
+  return date;
+}
+function parseDuration(duration, subtract) {
+  const regex = /^P(?:(?<days>\d+)D)?(?:T(?:(?<hours>\d+)H)?(?:(?<minutes>\d+)M)?(?:(?<seconds>\d+)S)?)?$/;
+  const match = duration.match(regex);
+  if (!match)
+    throw new Error(`Invalid duration format: ${duration}`);
+  const m = subtract ? -1 : 1;
+  const days = +(match.groups.days || 0) * m;
+  const hours = +(match.groups.hours || 0) * m;
+  const minutes = +(match.groups.minutes || 0) * m;
+  const seconds = +(match.groups.seconds || 0) * m;
+  return days || hours || minutes || seconds ? { days, hours, minutes, seconds } : null;
+}
+function normalizeIncomingDate(incomingDate) {
+  let date = incomingDate;
+  if (typeof date === "string" && /^\d{8}T\d{6}Z$/.test(date)) {
+    date = parseAbbreviatedIsoToIso(date);
   }
-  const usbPluggedInfo = {
-    date: match.groups.date,
-    duration: match.groups.duration
-  };
-  const isoDate = parseAbbreviatedIsoToIso(usbPluggedInfo.date);
-  return parseAdjustedDate(isoDate, [usbPluggedInfo.duration], true);
-}
-function parseAdjustedDate(incomingDate, durations, subtract = false) {
-  function parseDuration(duration) {
-    const regex = /^P((?<days>\d+)D)?(T((?<hours>\d+)H)?((?<minutes>\d+)M)?((?<seconds>\d+)S)?)?$/;
-    const match = duration.match(regex);
-    if (!match) {
-      throw new Error(`Invalid duration format: ${duration}`);
+  return new Date(date);
+}
+function parseAbbreviatedIsoToIso(abbrIso) {
+  const m = abbrIso.match(/^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})Z$/);
+  if (!m)
+    throw new Error(`Invalid abbreviated ISO date format: ${abbrIso}`);
+  return `${m[1]}-${m[2]}-${m[3]}T${m[4]}:${m[5]}:${m[6]}Z`;
+}
+function parseIsoToAbbreviatedIso(iso) {
+  return iso.toISOString().replace(/[\-\:]/g, "").replace(".000Z", "Z");
+}
+function buildDeviceRtcwDateMaps(contents) {
+  const dataContents = contents.filter((c) => c.data);
+  const deviceRtcwDateMaps = /* @__PURE__ */ new Map();
+  for (const content of dataContents) {
+    const { deviceId, deviceDate, finalRtcw } = extractDeviceData(content);
+    let rtcwDateMap = deviceRtcwDateMaps.get(deviceId);
+    if (!rtcwDateMap) {
+      rtcwDateMap = /* @__PURE__ */ new Map();
+      deviceRtcwDateMaps.set(deviceId, rtcwDateMap);
     }
-    const multiplier = subtract ? -1 : 1;
-    const days = parseInt(match.groups.days || 0, 10) * multiplier;
-    const hours = parseInt(match.groups.hours || 0, 10) * multiplier;
-    const minutes = parseInt(match.groups.minutes || 0, 10) * multiplier;
-    const seconds = parseInt(match.groups.seconds || 0, 10) * multiplier;
-    if (days === 0 && hours === 0 && minutes === 0 && seconds === 0) {
-      return null;
+    const existingDate = rtcwDateMap.get(finalRtcw);
+    if (!existingDate || deviceDate < existingDate) {
+      rtcwDateMap.set(finalRtcw, deviceDate);
     }
-    return { days, hours, minutes, seconds };
   }
-  function applyDuration(date, duration) {
-    date.setDate(date.getDate() + duration.days);
-    date.setHours(date.getHours() + duration.hours);
-    date.setMinutes(date.getMinutes() + duration.minutes);
-    date.setSeconds(date.getSeconds() + duration.seconds);
-  }
-  const adjustedDate = new Date(incomingDate);
-  for (const duration of durations) {
-    if (!duration)
-      continue;
-    const parsedDuration = parseDuration(duration);
-    if (!parsedDuration)
-      continue;
-    applyDuration(adjustedDate, parsedDuration);
-  }
-  return adjustedDate;
+  return deviceRtcwDateMaps;
 }
-function parseAbbreviatedIsoToIso(abbreviatedIso) {
-  const regex = /^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})Z$/;
-  const match = abbreviatedIso.match(regex);
-  if (!match) {
-    throw new Error(`Invalid abbreviated ISO date format: ${abbreviatedIso}`);
+function extractDeviceData(content) {
+  const regex = /^([a-zA-Z0-9]+)_(?:.+)_([A-Z0-9]{4,15})_([0-9]{8}T[0-9]{6}Z)\.json$/;
+  const [, deviceId, deviceRelt, abbrUsbDate] = content.data.filename.match(regex);
+  const deviceDate = applyDurationToDate(abbrUsbDate, deviceRelt, true);
+  if (typeof content.data.content === "string") {
+    try {
+      content.data.content = JSON.parse(content.data.content);
+    } catch (e) {
+      console.error("Invalid JSON string in content.data.content:", e);
+    }
   }
-  return `${match[1]}-${match[2]}-${match[3]}T${match[4]}:${match[5]}:${match[6]}Z`;
-}
-function parseIsoToAbbreviatedIso(iso) {
-  return iso.toISOString().replace(/[\-\:]/g, "").replace(".000Z", "Z");
+  content.zDeviceId = deviceId;
+  const data = content.data.content;
+  const finalRtcw = data.records[data.records.length - 1].RTCW;
+  return { deviceId, deviceDate, finalRtcw };
 }
 
 // src/FridgeTagUtils.js
@@ -479,7 +513,7 @@ function parseFridgeTagToReport(metadata, nodes) {
         ABST: dateTime,
         TVC: temp,
         ALRM: alarm,
-        zdescription: date + " " + tempField
+        zDescription: date + " " + tempField
       });
       function parseAlarm(alarmNode, description) {
         if (alarmNode["t Acc"] === "0")
@@ -577,38 +611,46 @@ function parseFridgeTag(text) {
 var import_language_common2 = require("@openfn/language-common");
 function convertToEms(messageContents) {
   return async (state) => {
-    var _a, _b;
     const [resolvedMessageContents] = (0, import_util.expandReferences)(state, messageContents);
     const reports = [];
-    console.log("Incoming message contents", resolvedMessageContents.length);
-    for (const content of resolvedMessageContents) {
-      if ((_a = content.fridgeTag) == null ? void 0 : _a.content) {
-        const metadata = parseMetadata(content);
-        if (!metadata)
-          continue;
-        const fridgeTagNodes = parseFridgeTag(content.fridgeTag.content);
-        const result = parseFridgeTagToReport(metadata, fridgeTagNodes);
-        reports.push(result);
-        continue;
-      }
-      if ((_b = content.data) == null ? void 0 : _b.content) {
-        const metadata = parseMetadata(content);
-        if (!metadata)
-          continue;
-        const data = JSON.parse(content.data.content);
-        const dataPath2 = content.data.filename;
-        const result = parseVaroEmsToReport(metadata, data, dataPath2);
-        reports.push(result);
-        continue;
-      }
+    console.info("Incoming message contents", resolvedMessageContents.length);
+    processFridgeTagContents(resolvedMessageContents, reports);
+    processDataContents(resolvedMessageContents, reports);
+    for (const content of resolvedMessageContents.filter((c) => !c.zProcessed)) {
       console.error(
         `Insufficient content found for MessageID: ${content.messageId}`
       );
     }
-    console.log("Converted message contents", reports.length);
+    console.info("Converted message contents", reports.length);
     return { ...(0, import_language_common.composeNextState)(state, reports) };
   };
 }
+function processFridgeTagContents(contents, reports) {
+  const fridgeTagContents = contents.filter((c) => c.fridgeTag);
+  for (const content of fridgeTagContents) {
+    const metadata = parseMetadata(content);
+    if (!metadata)
+      continue;
+    const fridgeTagNodes = parseFridgeTag(content.fridgeTag.content);
+    const result = parseFridgeTagToReport(metadata, fridgeTagNodes);
+    reports.push(result);
+    content.zProcessed = true;
+  }
+}
+function processDataContents(contents, reports) {
+  const dataContents = contents.filter((c) => c.data);
+  const deviceRtcwDateMaps = buildDeviceRtcwDateMaps(dataContents);
+  for (const content of dataContents) {
+    const metadata = parseMetadata(content);
+    if (!metadata)
+      continue;
+    const data = content.data.content;
+    const rtcwMaps = deviceRtcwDateMaps.get(content.zDeviceId);
+    const result = parseVaroEmsToReport(metadata, data, rtcwMaps);
+    reports.push(result);
+    content.zProcessed = true;
+  }
+}
 function convertItemsToReports(items, reportType = "unknown") {
   return async (state) => {
     const [resolvedRecords, resolvedReportType] = (0, import_util.expandReferences)(
@@ -636,7 +678,7 @@ function convertReportsToMessageContents(reports, reportType = "unknown") {
       reportType
     );
     const messageContents = [];
-    for (const report of resolvedReports) {
+    for (const report of resolvedReports ?? []) {
       report["zReportType"] = resolvedReportType;
       report["zGeneratedTimestamp"] = new Date().toISOString();
       const serialNumber = report["ESER"] || report["LSER"] || report["ASER"];
@@ -653,6 +695,45 @@ function convertReportsToMessageContents(reports, reportType = "unknown") {
     return { ...(0, import_language_common.composeNextState)(state, messageContents) };
   };
 }
+function parseUtcForDataRange(timeZone, startIso, endIso) {
+  const localNow = import_luxon.DateTime.now().setZone(timeZone);
+  const wallClock = new Date(
+    localNow.year,
+    localNow.month - 1,
+    localNow.day,
+    localNow.hour,
+    localNow.minute,
+    localNow.second,
+    localNow.millisecond
+  );
+  const startLocal = import_luxon.DateTime.fromISO(startIso, { zone: timeZone });
+  const endLocal = import_luxon.DateTime.fromISO(endIso, { zone: timeZone });
+  const startUtc = startLocal.toUTC().toJSDate();
+  const endUtc = endLocal.toUTC().toJSDate();
+  const daysDiff = Math.floor(endLocal.diff(startLocal, "days").days);
+  const collectionKeyPattern = "yyyyLLdd";
+  const collectionKeys = [];
+  for (let i = 0; i <= daysDiff; i++) {
+    const currentDay = startLocal.plus({ days: i });
+    collectionKeys.push(`*${currentDay.toFormat(collectionKeyPattern)}*`);
+  }
+  return {
+    wallClock,
+    startUtc,
+    endUtc,
+    collectionKeys
+  };
+}
+function isKeyInRange(key, start, end) {
+  console.error(
+    "i changed this implementation and need to verify the scenarios."
+  );
+  const iso = key == null ? void 0 : key.split(":")[1];
+  if (!iso || iso.length < 15)
+    return false;
+  const date = abbreviatedIsoToDate(iso);
+  return date >= start && date < end;
+}
 
 // src/index.js
 var src_default = Adaptor_exports;
@@ -671,7 +752,9 @@ var src_default = Adaptor_exports;
   fields,
   fn,
   fnIf,
+  isKeyInRange,
   lastReferenceValue,
   merge,
+  parseUtcForDataRange,
   sourceValue
 });

package/dist/index.js

@@ -20,12 +20,15 @@ __export(Adaptor_exports, {
   fields: () => fields,
   fn: () => fn,
   fnIf: () => fnIf,
+  isKeyInRange: () => isKeyInRange,
   lastReferenceValue: () => lastReferenceValue,
   merge: () => merge,
+  parseUtcForDataRange: () => parseUtcForDataRange,
   sourceValue: () => sourceValue
 });
 import { composeNextState } from "@openfn/language-common";
 import { expandReferences } from "@openfn/language-common/util";
+import { DateTime } from "luxon";
 
 // src/Utils.js
 function parseMetadata(message) {
@@ -44,7 +47,7 @@ function parseMetadata(message) {
 }
 function removeNullProps(obj) {
   for (const key in obj) {
-    if (obj[key] == null) {
+    if (obj[key] === null) {
       delete obj[key];
     }
   }
@@ -91,7 +94,18 @@ function formatDeviceInfo(data) {
   output += formatType("Appliance", data.AMFR, data.AMOD, data.ASER);
   output += formatType("Logger", data.LMFR, data.LMOD, data.LSER);
   output += formatType("EMD", data.EMFR, data.EMOD, data.ESER);
-  return output || "No valid data found";
+  return output || "Cannot determine device info; no valid data found.";
+}
+function abbreviatedIsoToDate(iso) {
+  const [year, month, day, hour, minute, second] = [
+    iso.slice(0, 4),
+    iso.slice(4, 6),
+    iso.slice(6, 8),
+    iso.slice(9, 11),
+    iso.slice(11, 13),
+    iso.slice(13, 15)
+  ];
+  return new Date(`${year}-${month}-${day}T${hour}:${minute}:${second}Z`);
 }
 
 // src/StreamingUtils.js
@@ -167,7 +181,6 @@ function mergeRecords(records, groupKey) {
     }
     if (tambAlrm != null) {
       mergedRecord["zTambAlrm"] = tambAlrm;
-      mergedRecord["ALRM"] = tambAlrm;
     }
     if (tvcAlrm != null) {
       mergedRecord["zTvcAlrm"] = tvcAlrm;
@@ -280,7 +293,7 @@ function promoteDeviceProperties(source, destination) {
 }
 
 // src/VaroEmsUtils.js
-function parseVaroEmsToReport(metadata, data, dataPath2) {
+function parseVaroEmsToReport(metadata, data, rtcwMaps) {
   const report = {
     CID: null,
     LAT: metadata.location.used.latitude,
@@ -304,10 +317,14 @@ function parseVaroEmsToReport(metadata, data, dataPath2) {
     LSV: data.LSV,
     records: []
   };
-  const deviceDate = parseRelativeDateFromUsbPluggedInfo(dataPath2);
+  removeNullProps(report);
   for (const item of data.records) {
-    const durations = [item.RELT];
-    const absoluteDate = parseAdjustedDate(deviceDate, durations);
+    const deviceDate = rtcwMaps.get(item.RTCW);
+    if (!deviceDate) {
+      report.zHasUnreconciledRtcw = true;
+      continue;
+    }
+    const absoluteDate = applyDurationToDate(deviceDate, item.RELT);
     const abst = parseIsoToAbbreviatedIso(absoluteDate);
     const record = {
       ABST: abst,
@@ -324,67 +341,82 @@ function parseVaroEmsToReport(metadata, data, dataPath2) {
       TAMB: item.TAMB,
       TVC: item.TVC
     };
+    removeNullProps(record);
     report.records.push(record);
   }
   return report;
 }
-function parseRelativeDateFromUsbPluggedInfo(path) {
-  const regex = /_CURRENT_DATA_(?<duration>\w+?)_(?<date>\w+?)\.json$/;
-  const match = path.match(regex);
-  if (!match) {
-    throw new Error(`Path format is incorrect: ${path}`);
+function applyDurationToDate(incomingDate, duration, subtract = false) {
+  const date = normalizeIncomingDate(incomingDate);
+  const parsedDuration = parseDuration(duration, subtract);
+  if (!parsedDuration)
+    return date;
+  date.setUTCDate(date.getUTCDate() + parsedDuration.days);
+  date.setUTCHours(date.getUTCHours() + parsedDuration.hours);
+  date.setUTCMinutes(date.getUTCMinutes() + parsedDuration.minutes);
+  date.setUTCSeconds(date.getUTCSeconds() + parsedDuration.seconds);
+  return date;
+}
+function parseDuration(duration, subtract) {
+  const regex = /^P(?:(?<days>\d+)D)?(?:T(?:(?<hours>\d+)H)?(?:(?<minutes>\d+)M)?(?:(?<seconds>\d+)S)?)?$/;
+  const match = duration.match(regex);
+  if (!match)
+    throw new Error(`Invalid duration format: ${duration}`);
+  const m = subtract ? -1 : 1;
+  const days = +(match.groups.days || 0) * m;
+  const hours = +(match.groups.hours || 0) * m;
+  const minutes = +(match.groups.minutes || 0) * m;
+  const seconds = +(match.groups.seconds || 0) * m;
+  return days || hours || minutes || seconds ? { days, hours, minutes, seconds } : null;
+}
+function normalizeIncomingDate(incomingDate) {
+  let date = incomingDate;
+  if (typeof date === "string" && /^\d{8}T\d{6}Z$/.test(date)) {
+    date = parseAbbreviatedIsoToIso(date);
   }
-  const usbPluggedInfo = {
-    date: match.groups.date,
-    duration: match.groups.duration
-  };
-  const isoDate = parseAbbreviatedIsoToIso(usbPluggedInfo.date);
-  return parseAdjustedDate(isoDate, [usbPluggedInfo.duration], true);
-}
-function parseAdjustedDate(incomingDate, durations, subtract = false) {
-  function parseDuration(duration) {
-    const regex = /^P((?<days>\d+)D)?(T((?<hours>\d+)H)?((?<minutes>\d+)M)?((?<seconds>\d+)S)?)?$/;
-    const match = duration.match(regex);
-    if (!match) {
-      throw new Error(`Invalid duration format: ${duration}`);
+  return new Date(date);
+}
+function parseAbbreviatedIsoToIso(abbrIso) {
+  const m = abbrIso.match(/^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})Z$/);
+  if (!m)
+    throw new Error(`Invalid abbreviated ISO date format: ${abbrIso}`);
+  return `${m[1]}-${m[2]}-${m[3]}T${m[4]}:${m[5]}:${m[6]}Z`;
+}
+function parseIsoToAbbreviatedIso(iso) {
+  return iso.toISOString().replace(/[\-\:]/g, "").replace(".000Z", "Z");
+}
+function buildDeviceRtcwDateMaps(contents) {
+  const dataContents = contents.filter((c) => c.data);
+  const deviceRtcwDateMaps = /* @__PURE__ */ new Map();
+  for (const content of dataContents) {
+    const { deviceId, deviceDate, finalRtcw } = extractDeviceData(content);
+    let rtcwDateMap = deviceRtcwDateMaps.get(deviceId);
+    if (!rtcwDateMap) {
+      rtcwDateMap = /* @__PURE__ */ new Map();
+      deviceRtcwDateMaps.set(deviceId, rtcwDateMap);
     }
-    const multiplier = subtract ? -1 : 1;
-    const days = parseInt(match.groups.days || 0, 10) * multiplier;
-    const hours = parseInt(match.groups.hours || 0, 10) * multiplier;
-    const minutes = parseInt(match.groups.minutes || 0, 10) * multiplier;
-    const seconds = parseInt(match.groups.seconds || 0, 10) * multiplier;
-    if (days === 0 && hours === 0 && minutes === 0 && seconds === 0) {
-      return null;
+    const existingDate = rtcwDateMap.get(finalRtcw);
+    if (!existingDate || deviceDate < existingDate) {
+      rtcwDateMap.set(finalRtcw, deviceDate);
     }
-    return { days, hours, minutes, seconds };
   }
-  function applyDuration(date, duration) {
-    date.setDate(date.getDate() + duration.days);
-    date.setHours(date.getHours() + duration.hours);
-    date.setMinutes(date.getMinutes() + duration.minutes);
-    date.setSeconds(date.getSeconds() + duration.seconds);
-  }
-  const adjustedDate = new Date(incomingDate);
-  for (const duration of durations) {
-    if (!duration)
-      continue;
-    const parsedDuration = parseDuration(duration);
-    if (!parsedDuration)
-      continue;
-    applyDuration(adjustedDate, parsedDuration);
-  }
-  return adjustedDate;
+  return deviceRtcwDateMaps;
 }
-function parseAbbreviatedIsoToIso(abbreviatedIso) {
-  const regex = /^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})Z$/;
-  const match = abbreviatedIso.match(regex);
-  if (!match) {
-    throw new Error(`Invalid abbreviated ISO date format: ${abbreviatedIso}`);
+function extractDeviceData(content) {
+  const regex = /^([a-zA-Z0-9]+)_(?:.+)_([A-Z0-9]{4,15})_([0-9]{8}T[0-9]{6}Z)\.json$/;
+  const [, deviceId, deviceRelt, abbrUsbDate] = content.data.filename.match(regex);
+  const deviceDate = applyDurationToDate(abbrUsbDate, deviceRelt, true);
+  if (typeof content.data.content === "string") {
+    try {
+      content.data.content = JSON.parse(content.data.content);
+    } catch (e) {
+      console.error("Invalid JSON string in content.data.content:", e);
+    }
   }
-  return `${match[1]}-${match[2]}-${match[3]}T${match[4]}:${match[5]}:${match[6]}Z`;
-}
-function parseIsoToAbbreviatedIso(iso) {
-  return iso.toISOString().replace(/[\-\:]/g, "").replace(".000Z", "Z");
+  content.zDeviceId = deviceId;
+  const data = content.data.content;
+  const finalRtcw = data.records[data.records.length - 1].RTCW;
+  return { deviceId, deviceDate, finalRtcw };
 }
 
 // src/FridgeTagUtils.js
@@ -444,7 +476,7 @@ function parseFridgeTagToReport(metadata, nodes) {
         ABST: dateTime,
         TVC: temp,
         ALRM: alarm,
-        zdescription: date + " " + tempField
+        zDescription: date + " " + tempField
       });
       function parseAlarm(alarmNode, description) {
         if (alarmNode["t Acc"] === "0")
@@ -556,38 +588,46 @@ import {
 } from "@openfn/language-common";
 function convertToEms(messageContents) {
   return async (state) => {
-    var _a, _b;
     const [resolvedMessageContents] = expandReferences(state, messageContents);
     const reports = [];
-    console.log("Incoming message contents", resolvedMessageContents.length);
-    for (const content of resolvedMessageContents) {
-      if ((_a = content.fridgeTag) == null ? void 0 : _a.content) {
-        const metadata = parseMetadata(content);
-        if (!metadata)
-          continue;
-        const fridgeTagNodes = parseFridgeTag(content.fridgeTag.content);
-        const result = parseFridgeTagToReport(metadata, fridgeTagNodes);
-        reports.push(result);
-        continue;
-      }
-      if ((_b = content.data) == null ? void 0 : _b.content) {
-        const metadata = parseMetadata(content);
-        if (!metadata)
-          continue;
-        const data = JSON.parse(content.data.content);
-        const dataPath2 = content.data.filename;
-        const result = parseVaroEmsToReport(metadata, data, dataPath2);
-        reports.push(result);
-        continue;
-      }
+    console.info("Incoming message contents", resolvedMessageContents.length);
+    processFridgeTagContents(resolvedMessageContents, reports);
+    processDataContents(resolvedMessageContents, reports);
+    for (const content of resolvedMessageContents.filter((c) => !c.zProcessed)) {
       console.error(
         `Insufficient content found for MessageID: ${content.messageId}`
       );
     }
-    console.log("Converted message contents", reports.length);
+    console.info("Converted message contents", reports.length);
     return { ...composeNextState(state, reports) };
   };
 }
+function processFridgeTagContents(contents, reports) {
+  const fridgeTagContents = contents.filter((c) => c.fridgeTag);
+  for (const content of fridgeTagContents) {
+    const metadata = parseMetadata(content);
+    if (!metadata)
+      continue;
+    const fridgeTagNodes = parseFridgeTag(content.fridgeTag.content);
+    const result = parseFridgeTagToReport(metadata, fridgeTagNodes);
+    reports.push(result);
+    content.zProcessed = true;
+  }
+}
+function processDataContents(contents, reports) {
+  const dataContents = contents.filter((c) => c.data);
+  const deviceRtcwDateMaps = buildDeviceRtcwDateMaps(dataContents);
+  for (const content of dataContents) {
+    const metadata = parseMetadata(content);
+    if (!metadata)
+      continue;
+    const data = content.data.content;
+    const rtcwMaps = deviceRtcwDateMaps.get(content.zDeviceId);
+    const result = parseVaroEmsToReport(metadata, data, rtcwMaps);
+    reports.push(result);
+    content.zProcessed = true;
+  }
+}
 function convertItemsToReports(items, reportType = "unknown") {
   return async (state) => {
     const [resolvedRecords, resolvedReportType] = expandReferences(
@@ -615,7 +655,7 @@ function convertReportsToMessageContents(reports, reportType = "unknown") {
       reportType
     );
     const messageContents = [];
-    for (const report of resolvedReports) {
+    for (const report of resolvedReports ?? []) {
       report["zReportType"] = resolvedReportType;
       report["zGeneratedTimestamp"] = new Date().toISOString();
       const serialNumber = report["ESER"] || report["LSER"] || report["ASER"];
@@ -632,6 +672,45 @@ function convertReportsToMessageContents(reports, reportType = "unknown") {
     return { ...composeNextState(state, messageContents) };
   };
 }
+function parseUtcForDataRange(timeZone, startIso, endIso) {
+  const localNow = DateTime.now().setZone(timeZone);
+  const wallClock = new Date(
+    localNow.year,
+    localNow.month - 1,
+    localNow.day,
+    localNow.hour,
+    localNow.minute,
+    localNow.second,
+    localNow.millisecond
+  );
+  const startLocal = DateTime.fromISO(startIso, { zone: timeZone });
+  const endLocal = DateTime.fromISO(endIso, { zone: timeZone });
+  const startUtc = startLocal.toUTC().toJSDate();
+  const endUtc = endLocal.toUTC().toJSDate();
+  const daysDiff = Math.floor(endLocal.diff(startLocal, "days").days);
+  const collectionKeyPattern = "yyyyLLdd";
+  const collectionKeys = [];
+  for (let i = 0; i <= daysDiff; i++) {
+    const currentDay = startLocal.plus({ days: i });
+    collectionKeys.push(`*${currentDay.toFormat(collectionKeyPattern)}*`);
+  }
+  return {
+    wallClock,
+    startUtc,
+    endUtc,
+    collectionKeys
+  };
+}
+function isKeyInRange(key, start, end) {
+  console.error(
+    "i changed this implementation and need to verify the scenarios."
+  );
+  const iso = key == null ? void 0 : key.split(":")[1];
+  if (!iso || iso.length < 15)
+    return false;
+  const date = abbreviatedIsoToDate(iso);
+  return date >= start && date < end;
+}
 
 // src/index.js
 var src_default = Adaptor_exports;
@@ -650,7 +729,9 @@ export {
   fields,
   fn,
   fnIf,
+  isKeyInRange,
   lastReferenceValue,
   merge,
+  parseUtcForDataRange,
   sourceValue
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@openfn/language-varo",
   "label": "Varo",
-  "version": "2.0.0",
+  "version": "2.1.1",
   "description": "OpenFn varo adaptor for cold chain information",
   "type": "module",
   "exports": {
@@ -21,7 +21,8 @@
     "configuration-schema.json"
   ],
   "dependencies": {
-    "@openfn/language-common": "3.0.2"
+    "luxon": "^3.6.1",
+    "@openfn/language-common": "3.0.3"
   },
   "devDependencies": {
     "assertion-error": "2.0.0",

package/types/Adaptor.d.ts

@@ -57,4 +57,50 @@ export function convertItemsToReports(items: any[], reportType?: string): Operat
  * convertReportsToMessageContents(emsReports, "ems");
  */
 export function convertReportsToMessageContents(reports: any, reportType?: string): Function;
+/**
+ * @typedef {Object} UtcRange
+ * @property {Date} wallClock - The current local datetime as it appears on the wall in the specified timezone.
+ * @property {Date} startUtc - UTC start date range (inclusive).
+ * @property {Date} endUtc - UTC end of date range (exclusive).
+ * @property {Array} collectionKeys - Array of wildcard patterns to match UTC dates which correspond with date range (e.g. "*20250624*").
+ */
+/**
+ * Computes the UTC datetime range that corresponds to a given IANA timezone.
+ * @public
+ * @function
+ * @param {string} timeZone - An IANA time zone identifier (e.g. "America/Los_Angeles").
+ * @param {string} startIso - Starting date in ISO format.
+ * @param {string} endIso - Ending date range in ISO format.
+ * @returns {UtcRange}
+ */
+export function parseUtcForDataRange(timeZone: string, startIso: string, endIso: string): UtcRange;
+/**
+ * Checks whether the timestamp embedded in a key falls within a UTC datetime range.
+ *
+ * @public
+ * @function
+ * @param {string} key - A string key containing a UTC timestamp in the format `YYYYMMDDTHHMMSS`, following a colon (e.g. "prefix:20250624T101530").
+ * @param {Date} start - The inclusive lower bound of the UTC datetime range.
+ * @param {Date} end - The exclusive upper bound of the UTC datetime range.
+ * @returns {boolean} True if the parsed UTC timestamp is within the range, false otherwise.
+ */
+export function isKeyInRange(key: string, start: Date, end: Date): boolean;
+export type UtcRange = {
+    /**
+     * - The current local datetime as it appears on the wall in the specified timezone.
+     */
+    wallClock: Date;
+    /**
+     * - UTC start date range (inclusive).
+     */
+    startUtc: Date;
+    /**
+     * - UTC end of date range (exclusive).
+     */
+    endUtc: Date;
+    /**
+     * - Array of wildcard patterns to match UTC dates which correspond with date range (e.g. "*20250624*").
+     */
+    collectionKeys: any[];
+};
 export { alterState, combine, cursor, dataPath, dataValue, each, field, fields, fn, fnIf, lastReferenceValue, merge, sourceValue } from "@openfn/language-common";

package/types/Utils.d.ts

@@ -2,3 +2,4 @@ export function parseMetadata(message: any): any;
 export function removeNullProps(obj: any): any;
 export function deepEqual(a: any, b: any): boolean;
 export function formatDeviceInfo(data: any): string;
+export function abbreviatedIsoToDate(iso: any): Date;

package/types/VaroEmsUtils.d.ts

@@ -1,4 +1,4 @@
-export function parseVaroEmsToReport(metadata: any, data: any, dataPath: any): {
+export function parseVaroEmsToReport(metadata: any, data: any, rtcwMaps: any): {
     CID: any;
     LAT: any;
     LNG: any;
@@ -21,3 +21,10 @@ export function parseVaroEmsToReport(metadata: any, data: any, dataPath: any): {
     LSV: any;
     records: any[];
 };
+export function applyDurationToDate(incomingDate: any, duration: any, subtract?: boolean): Date;
+export function buildDeviceRtcwDateMaps(contents: any): Map<any, any>;
+export function extractDeviceData(content: any): {
+    deviceId: any;
+    deviceDate: Date;
+    finalRtcw: any;
+};