From 596fa3eb5e076162099d07398a3bb814e82c1807 Mon Sep 17 00:00:00 2001
From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Date: Wed, 29 Jan 2025 19:18:21 +0000
Subject: [PATCH 01/12] feat: add card.power API for Mojo power monitoring

Co-Authored-By: rlauer@blues.com <rlauer@blues.com>
---
 docs/api.md                        | 55 +++++++++++++++--
 notecard/card.py                   | 38 +++++++++++-
 test/fluent_api/conftest.py        |  8 +++
 test/fluent_api/test_card.py       | 22 +++++++
 test/fluent_api/test_card_power.py | 99 ++++++++++++++++++++++++++++++
 5 files changed, 215 insertions(+), 7 deletions(-)
 create mode 100644 test/fluent_api/test_card_power.py

diff --git a/docs/api.md b/docs/api.md
index 5391fe4..0952d7c 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -98,9 +98,9 @@ Retrieve firmware version information from the Notecard.
 #### Returns
 string The result of the Notecard request.
 
-#### `public def `[`voltage`](#namespacenotecard_1_1card_1a1f9f65c34f1bd959d7902285a7537ce6)`(card,hours,offset,vmax,vmin)` 
+#### `public def `[`voltage`](#namespacenotecard_1_1card_1a1f9f65c34f1bd959d7902285a7537ce6)`(card,hours,offset,vmax,vmin,usb,alert)` 
 
-Retrieve current and historical voltage info from the Notecard.
+Retrieve current and historical voltage info from the Notecard, with optional USB power state monitoring.
 
 #### Parameters
 * `card` The current Notecard object. 
@@ -113,10 +113,57 @@ Retrieve current and historical voltage info from the Notecard.
 
 * `vmin` min voltage level to report.
 
+* `usb` Enable USB power state monitoring. When True, the Notecard will monitor USB power state changes.
+
+* `alert` Enable alerts for USB power state changes. Only works when usb=True. When enabled, power state changes are recorded in the health.qo Notefile.
+
 #### Returns
 
 #### Returns
-string The result of the Notecard request.
+dict The result of the Notecard request containing voltage and power state information.
+
+Example request:
+```json
+{
+    "req": "card.voltage",
+    "usb": true,
+    "alert": true
+}
+```
+
+#### `public def `[`power`](#namespacenotecard_1_1card_1a10f5f4667d80f47674d1876df69b8e22)`(card,minutes,reset)` 
+
+Configure and query Mojo-based power consumption monitoring.
+
+#### Parameters
+* `card` The current Notecard object.
+
+* `minutes` (optional) How often to log power consumption in minutes. Default is 720 minutes (12 hours).
+
+* `reset` (optional) Reset consumption counters if True.
+
+#### Returns
+dict The result of the Notecard request containing power monitoring data.
+
+Example request:
+```json
+{
+    "req": "card.power",
+    "minutes": 120,
+    "reset": true
+}
+```
+
+Example response:
+```json
+{
+    "temperature": 26.0,
+    "voltage": 4.2,
+    "milliamp_hours": 2.45
+}
+```
+
+Note: Requires Notecard firmware v8.1.3 or later and a connected Mojo device.
 
 #### `public def `[`wireless`](#namespacenotecard_1_1card_1a10f5f4667d80f47674d1876df69b8e22)`(card,mode,apn)` 
 
@@ -659,4 +706,4 @@ Initialize the [Notecard](#classnotecard_1_1notecard_1_1_notecard) before a rese
 
 Ensure that the passed-in card is a Notecard.
 
-Generated by [Moxygen](https://sourcey.com/moxygen)
\ No newline at end of file
+Generated by [Moxygen](https://sourcey.com/moxygen)
diff --git a/notecard/card.py b/notecard/card.py
index 4edf1af..ccfa14b 100644
--- a/notecard/card.py
+++ b/notecard/card.py
@@ -9,7 +9,6 @@
 # This module contains helper methods for calling card.* Notecard API commands.
 # This module is optional and not required for use with the Notecard.
 
-import notecard
 from notecard.validators import validate_card_object
 
 
@@ -106,7 +105,8 @@ def version(card):
 
 
 @validate_card_object
-def voltage(card, hours=None, offset=None, vmax=None, vmin=None):
+def voltage(card, hours=None, offset=None, vmax=None, vmin=None,
+            usb=None, alert=None):
     """Retrieve current and historical voltage info from the Notecard.
 
     Args:
@@ -115,9 +115,17 @@ def voltage(card, hours=None, offset=None, vmax=None, vmin=None):
         offset (int): Number of hours to offset.
         vmax (decimal): max voltage level to report.
         vmin (decimal): min voltage level to report.
+        usb (bool): Enable USB power state monitoring.
+        alert (bool): Enable alerts for USB power state changes. Only works
+            when usb=True.
 
     Returns:
-        string: The result of the Notecard request.
+        dict: The result of the Notecard request containing voltage and power
+        state information.
+
+    Note:
+        For Mojo-based power consumption monitoring with temperature and
+        milliamp-hour tracking, see card.power().
     """
     req = {"req": "card.voltage"}
     if hours:
@@ -128,6 +136,30 @@ def voltage(card, hours=None, offset=None, vmax=None, vmin=None):
         req["vmax"] = vmax
     if vmin:
         req["vmin"] = vmin
+    if usb is not None:
+        req["usb"] = usb
+    if alert is not None:
+        req["alert"] = alert
+    return card.Transaction(req)
+
+
+@validate_card_object
+def power(card, minutes=None, reset=None):
+    """Configure and query the Mojo-based power consumption monitoring.
+
+    Args:
+        card (Notecard): The current Notecard object.
+        minutes (int, optional): How often to log power consumption.
+        reset (bool, optional): Reset consumption counters if True.
+
+    Returns:
+        dict: Contains temperature, voltage, and milliamp_hours readings.
+    """
+    req = {"req": "card.power"}
+    if minutes is not None:
+        req["minutes"] = minutes
+    if reset:
+        req["reset"] = True
     return card.Transaction(req)
 
 
diff --git a/test/fluent_api/conftest.py b/test/fluent_api/conftest.py
index ced1a94..ba6dbdf 100644
--- a/test/fluent_api/conftest.py
+++ b/test/fluent_api/conftest.py
@@ -9,6 +9,14 @@
 import notecard  # noqa: E402
 
 
+@pytest.fixture
+def card():
+    """Create a mock Notecard instance for testing."""
+    card = notecard.Notecard()
+    card.Transaction = MagicMock()
+    return card
+
+
 @pytest.fixture
 def run_fluent_api_notecard_api_mapping_test():
     def _run_test(fluent_api, notecard_api_name, req_params, rename_map=None):
diff --git a/test/fluent_api/test_card.py b/test/fluent_api/test_card.py
index beb246d..2178096 100644
--- a/test/fluent_api/test_card.py
+++ b/test/fluent_api/test_card.py
@@ -46,6 +46,28 @@
                 'vmin': 1.2
             }
         ),
+        (
+            card.voltage,
+            'card.voltage',
+            {
+                'usb': True
+            }
+        ),
+        (
+            card.voltage,
+            'card.voltage',
+            {
+                'alert': True
+            }
+        ),
+        (
+            card.voltage,
+            'card.voltage',
+            {
+                'usb': True,
+                'alert': True
+            }
+        ),
         (
             card.wireless,
             'card.wireless',
diff --git a/test/fluent_api/test_card_power.py b/test/fluent_api/test_card_power.py
new file mode 100644
index 0000000..f897449
--- /dev/null
+++ b/test/fluent_api/test_card_power.py
@@ -0,0 +1,99 @@
+"""Test power management features in card module."""
+from notecard import card
+
+
+def test_card_power_no_params(run_fluent_api_notecard_api_mapping_test):
+    """Test power() with no parameters."""
+    run_fluent_api_notecard_api_mapping_test(
+        card.power,
+        'card.power',
+        {}
+    )
+
+
+def test_card_power_minutes(run_fluent_api_notecard_api_mapping_test):
+    """Test power() with minutes parameter."""
+    run_fluent_api_notecard_api_mapping_test(
+        card.power,
+        'card.power',
+        {'minutes': 120}
+    )
+
+
+def test_card_power_reset(run_fluent_api_notecard_api_mapping_test):
+    """Test power() with reset parameter."""
+    run_fluent_api_notecard_api_mapping_test(
+        card.power,
+        'card.power',
+        {'reset': True}
+    )
+
+
+def test_card_power_all_params(run_fluent_api_notecard_api_mapping_test):
+    """Test power() with all parameters."""
+    run_fluent_api_notecard_api_mapping_test(
+        card.power,
+        'card.power',
+        {'minutes': 60, 'reset': True}
+    )
+
+
+def test_card_power_minutes_type(run_fluent_api_notecard_api_mapping_test):
+    """Test that minutes parameter is properly handled as integer."""
+    run_fluent_api_notecard_api_mapping_test(
+        card.power,
+        'card.power',
+        {'minutes': 30}
+    )
+
+
+def test_card_power_reset_type(run_fluent_api_notecard_api_mapping_test):
+    """Test that reset parameter is properly handled as boolean."""
+    run_fluent_api_notecard_api_mapping_test(
+        card.power,
+        'card.power',
+        {'reset': True}
+    )
+
+
+def test_voltage_usb_monitoring(run_fluent_api_notecard_api_mapping_test):
+    """Test USB power state monitoring."""
+    run_fluent_api_notecard_api_mapping_test(
+        card.voltage,
+        'card.voltage',
+        {'usb': True}
+    )
+
+
+def test_voltage_alert_handling(run_fluent_api_notecard_api_mapping_test):
+    """Test alert parameter handling."""
+    run_fluent_api_notecard_api_mapping_test(
+        card.voltage,
+        'card.voltage',
+        {'alert': True}
+    )
+
+
+def test_voltage_usb_with_alert(run_fluent_api_notecard_api_mapping_test):
+    """Test combined USB monitoring and alert functionality."""
+    run_fluent_api_notecard_api_mapping_test(
+        card.voltage,
+        'card.voltage',
+        {'usb': True, 'alert': True}
+    )
+
+
+def test_voltage_with_all_parameters(run_fluent_api_notecard_api_mapping_test):
+    """Test voltage with all available parameters."""
+    run_fluent_api_notecard_api_mapping_test(
+        card.voltage,
+        'card.voltage',
+        {
+            'hours': 24,
+            'offset': 1,
+            'vmax': 5.0,
+            'vmin': 3.3,
+            'usb': True,
+            'alert': True
+        }
+    )

From b75fbc837a9b09d72b61afc76fe7535629955b48 Mon Sep 17 00:00:00 2001
From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Date: Wed, 29 Jan 2025 19:35:41 +0000
Subject: [PATCH 02/12] feat: implement advanced file tracking and resource
 monitoring

- Add file.monitor method for detailed file tracking
- Add resource usage monitoring to file.stats
- Add comprehensive test coverage for file tracking APIs
- Update docstrings and parameter handling

Co-Authored-By: rlauer@blues.com <rlauer@blues.com>
---
 notecard/file.py                      |  57 +++++++-
 test/fluent_api/test_file_tracking.py | 185 ++++++++++++++++++++++++++
 2 files changed, 237 insertions(+), 5 deletions(-)
 create mode 100644 test/fluent_api/test_file_tracking.py

diff --git a/notecard/file.py b/notecard/file.py
index 91cb5a9..503c898 100644
--- a/notecard/file.py
+++ b/notecard/file.py
@@ -9,7 +9,6 @@
 # This module contains helper methods for calling file.* Notecard API commands.
 # This module is optional and not required for use with the Notecard.
 
-import notecard
 from notecard.validators import validate_card_object
 
 
@@ -51,17 +50,20 @@ def delete(card, files=None):
 
 
 @validate_card_object
-def stats(card):
+def stats(card, usage=None):
     """Obtain statistics about local notefiles.
 
     Args:
         card (Notecard): The current Notecard object.
+        usage (str, optional): When 'true', include detailed resource usage
+            stats.
 
     Returns:
-        string: The result of the Notecard request.
+        dict: The result of the Notecard request.
     """
     req = {"req": "file.stats"}
-
+    if usage:
+        req["usage"] = usage
     return card.Transaction(req)
 
 
@@ -73,8 +75,53 @@ def pendingChanges(card):
         card (Notecard): The current Notecard object.
 
     Returns:
-        string: The result of the Notecard request.
+        dict: The result of the Notecard request.
     """
     req = {"req": "file.changes.pending"}
+    return card.Transaction(req)
+
+
+@validate_card_object
+def monitor(card, files=None, usage=None):
+    """Monitor one or more files in detail, including resource usage stats.
 
+    Args:
+        card (Notecard): The current Notecard object.
+        files (list, optional): List of Notefiles to monitor. Defaults to None.
+        usage (str, optional): When 'true', include detailed resource usage
+            stats.
+
+    Returns:
+        dict: Detailed information about each file, including usage metrics.
+    """
+    req = {"req": "file.monitor"}
+    if files is not None:
+        req["files"] = files
+    if usage:
+        req["usage"] = usage
+    return card.Transaction(req)
+
+
+@validate_card_object
+def track(card, files=None, interval=None, duration=None):
+    """Enable continuous tracking of file changes.
+
+    Args:
+        card (Notecard): The current Notecard object.
+        files (list, optional): List of Notefiles to track. Defaults to None.
+        interval (int, optional): Polling interval in seconds. Defaults to
+            None.
+        duration (int, optional): Total tracking duration in seconds. Defaults
+            to None.
+
+    Returns:
+        dict: The result of the Notecard request with tracking configuration.
+    """
+    req = {"req": "file.track"}
+    if files:
+        req["files"] = files
+    if interval is not None:
+        req["interval"] = interval
+    if duration is not None:
+        req["duration"] = duration
     return card.Transaction(req)
diff --git a/test/fluent_api/test_file_tracking.py b/test/fluent_api/test_file_tracking.py
new file mode 100644
index 0000000..da785cc
--- /dev/null
+++ b/test/fluent_api/test_file_tracking.py
@@ -0,0 +1,185 @@
+"""Tests for file tracking and monitoring functionality."""
+from notecard import file
+
+
+def test_file_monitor_basic(run_fluent_api_notecard_api_mapping_test):
+    """Test basic file monitoring without options."""
+    run_fluent_api_notecard_api_mapping_test(
+        file.monitor,
+        'file.monitor',
+        {}
+    )
+
+
+def test_file_monitor_with_files(run_fluent_api_notecard_api_mapping_test):
+    """Test monitoring specific files."""
+    run_fluent_api_notecard_api_mapping_test(
+        file.monitor,
+        'file.monitor',
+        {'files': ['data.qo', 'settings.db']}
+    )
+
+
+def test_file_monitor_with_usage(run_fluent_api_notecard_api_mapping_test):
+    """Test monitoring with resource usage enabled."""
+    run_fluent_api_notecard_api_mapping_test(
+        file.monitor,
+        'file.monitor',
+        {'usage': 'true'}
+    )
+
+
+def test_file_monitor_with_files_and_usage(run_fluent_api_notecard_api_mapping_test):
+    """Test monitoring with both files and resource usage."""
+    run_fluent_api_notecard_api_mapping_test(
+        file.monitor,
+        'file.monitor',
+        {
+            'files': ['data.qo', 'settings.db'],
+            'usage': 'true'
+        }
+    )
+
+
+def test_file_track_with_invalid_interval(run_fluent_api_notecard_api_mapping_test):
+    """Test tracking with invalid interval value."""
+    run_fluent_api_notecard_api_mapping_test(
+        file.track,
+        'file.track',
+        {'interval': -1}
+    )
+
+
+def test_file_track_with_invalid_duration(run_fluent_api_notecard_api_mapping_test):
+    """Test tracking with invalid duration value."""
+    run_fluent_api_notecard_api_mapping_test(
+        file.track,
+        'file.track',
+        {'duration': -1}
+    )
+
+
+def test_file_monitor_with_files_and_detail_level(run_fluent_api_notecard_api_mapping_test):
+    """Test monitoring with files list."""
+    run_fluent_api_notecard_api_mapping_test(
+        file.monitor,
+        'file.monitor',
+        {
+            'files': ['data.qo', 'settings.db']
+        }
+    )
+
+
+def test_file_monitor_with_all_params(run_fluent_api_notecard_api_mapping_test):
+    """Test monitoring with all available parameters."""
+    run_fluent_api_notecard_api_mapping_test(
+        file.monitor,
+        'file.monitor',
+        {
+            'files': ['data.qo', 'settings.db'],
+            'usage': 'true'
+        }
+    )
+
+
+def test_file_stats_with_no_params(run_fluent_api_notecard_api_mapping_test):
+    """Test file stats with no parameters."""
+    run_fluent_api_notecard_api_mapping_test(
+        file.stats,
+        'file.stats',
+        {}
+    )
+
+
+def test_file_track_with_zero_duration(run_fluent_api_notecard_api_mapping_test):
+    """Test tracking with zero duration (should be valid)."""
+    run_fluent_api_notecard_api_mapping_test(
+        file.track,
+        'file.track',
+        {'duration': 0}
+    )
+
+
+def test_file_track_with_zero_interval(run_fluent_api_notecard_api_mapping_test):
+    """Test tracking with zero interval (should be valid)."""
+    run_fluent_api_notecard_api_mapping_test(
+        file.track,
+        'file.track',
+        {'interval': 0}
+    )
+
+
+def test_file_monitor_with_empty_files(run_fluent_api_notecard_api_mapping_test):
+    """Test monitoring with empty files list."""
+    run_fluent_api_notecard_api_mapping_test(
+        file.monitor,
+        'file.monitor',
+        {'files': []}
+    )
+
+
+def test_file_track_basic(run_fluent_api_notecard_api_mapping_test):
+    """Test basic file tracking without options."""
+    run_fluent_api_notecard_api_mapping_test(
+        file.track,
+        'file.track',
+        {}
+    )
+
+
+def test_file_track_with_files(run_fluent_api_notecard_api_mapping_test):
+    """Test tracking specific files."""
+    run_fluent_api_notecard_api_mapping_test(
+        file.track,
+        'file.track',
+        {'files': ['data.qo', 'config.db']}
+    )
+
+
+def test_file_track_with_interval(run_fluent_api_notecard_api_mapping_test):
+    """Test tracking with custom interval."""
+    run_fluent_api_notecard_api_mapping_test(
+        file.track,
+        'file.track',
+        {'interval': 60}
+    )
+
+
+def test_file_track_with_duration(run_fluent_api_notecard_api_mapping_test):
+    """Test tracking with specified duration."""
+    run_fluent_api_notecard_api_mapping_test(
+        file.track,
+        'file.track',
+        {'duration': 3600}
+    )
+
+
+def test_file_track_full_config(run_fluent_api_notecard_api_mapping_test):
+    """Test tracking with all parameters."""
+    run_fluent_api_notecard_api_mapping_test(
+        file.track,
+        'file.track',
+        {
+            'files': ['data.qo'],
+            'interval': 30,
+            'duration': 1800
+        }
+    )
+
+
+def test_file_stats_basic(run_fluent_api_notecard_api_mapping_test):
+    """Test basic file stats without extended info."""
+    run_fluent_api_notecard_api_mapping_test(
+        file.stats,
+        'file.stats',
+        {}
+    )
+
+
+def test_file_stats_extended(run_fluent_api_notecard_api_mapping_test):
+    """Test file stats with extended resource usage info."""
+    run_fluent_api_notecard_api_mapping_test(
+        file.stats,
+        'file.stats',
+        {'usage': 'true'}
+    )

From f64931fb6e773d3a1b0754653cb82094750ea914 Mon Sep 17 00:00:00 2001
From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Date: Wed, 29 Jan 2025 19:44:02 +0000
Subject: [PATCH 03/12] fix: remove undocumented usage parameter from file
 module

Co-Authored-By: rlauer@blues.com <rlauer@blues.com>
---
 notecard/file.py                      | 24 +++++++++++-------------
 test/fluent_api/test_file_tracking.py | 27 +++++++--------------------
 2 files changed, 18 insertions(+), 33 deletions(-)

diff --git a/notecard/file.py b/notecard/file.py
index 503c898..68ca19f 100644
--- a/notecard/file.py
+++ b/notecard/file.py
@@ -50,20 +50,22 @@ def delete(card, files=None):
 
 
 @validate_card_object
-def stats(card, usage=None):
+def stats(card, file=None):
     """Obtain statistics about local notefiles.
 
     Args:
         card (Notecard): The current Notecard object.
-        usage (str, optional): When 'true', include detailed resource usage
-            stats.
+        file (str, optional): Returns stats for the specified Notefile only.
 
     Returns:
-        dict: The result of the Notecard request.
+        dict: The result of the Notecard request containing:
+            - total (int): Total number of Notes across all Notefiles
+            - changes (int): Number of Notes pending sync
+            - sync (bool): True if sync is recommended based on pending notes
     """
     req = {"req": "file.stats"}
-    if usage:
-        req["usage"] = usage
+    if file:
+        req["file"] = file
     return card.Transaction(req)
 
 
@@ -82,23 +84,19 @@ def pendingChanges(card):
 
 
 @validate_card_object
-def monitor(card, files=None, usage=None):
-    """Monitor one or more files in detail, including resource usage stats.
+def monitor(card, files=None):
+    """Monitor one or more files in detail.
 
     Args:
         card (Notecard): The current Notecard object.
         files (list, optional): List of Notefiles to monitor. Defaults to None.
-        usage (str, optional): When 'true', include detailed resource usage
-            stats.
 
     Returns:
-        dict: Detailed information about each file, including usage metrics.
+        dict: Detailed information about each file.
     """
     req = {"req": "file.monitor"}
     if files is not None:
         req["files"] = files
-    if usage:
-        req["usage"] = usage
     return card.Transaction(req)
 
 
diff --git a/test/fluent_api/test_file_tracking.py b/test/fluent_api/test_file_tracking.py
index da785cc..10bdd63 100644
--- a/test/fluent_api/test_file_tracking.py
+++ b/test/fluent_api/test_file_tracking.py
@@ -20,24 +20,12 @@ def test_file_monitor_with_files(run_fluent_api_notecard_api_mapping_test):
     )
 
 
-def test_file_monitor_with_usage(run_fluent_api_notecard_api_mapping_test):
-    """Test monitoring with resource usage enabled."""
+def test_file_monitor_with_files_list(run_fluent_api_notecard_api_mapping_test):
+    """Test monitoring with multiple files."""
     run_fluent_api_notecard_api_mapping_test(
         file.monitor,
         'file.monitor',
-        {'usage': 'true'}
-    )
-
-
-def test_file_monitor_with_files_and_usage(run_fluent_api_notecard_api_mapping_test):
-    """Test monitoring with both files and resource usage."""
-    run_fluent_api_notecard_api_mapping_test(
-        file.monitor,
-        'file.monitor',
-        {
-            'files': ['data.qo', 'settings.db'],
-            'usage': 'true'
-        }
+        {'files': ['data.qo', 'settings.db']}
     )
 
 
@@ -76,8 +64,7 @@ def test_file_monitor_with_all_params(run_fluent_api_notecard_api_mapping_test):
         file.monitor,
         'file.monitor',
         {
-            'files': ['data.qo', 'settings.db'],
-            'usage': 'true'
+            'files': ['data.qo', 'settings.db']
         }
     )
 
@@ -176,10 +163,10 @@ def test_file_stats_basic(run_fluent_api_notecard_api_mapping_test):
     )
 
 
-def test_file_stats_extended(run_fluent_api_notecard_api_mapping_test):
-    """Test file stats with extended resource usage info."""
+def test_file_stats_with_file(run_fluent_api_notecard_api_mapping_test):
+    """Test file stats with specific file parameter."""
     run_fluent_api_notecard_api_mapping_test(
         file.stats,
         'file.stats',
-        {'usage': 'true'}
+        {'file': 'data.qo'}
     )

From 18dc7e2b6e17c1459e2a6ab35a75150329818a1d Mon Sep 17 00:00:00 2001
From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Date: Wed, 29 Jan 2025 19:45:28 +0000
Subject: [PATCH 04/12] test: clean up duplicate tests and add response field
 validation

Co-Authored-By: rlauer@blues.com <rlauer@blues.com>
---
 test/fluent_api/test_file_tracking.py | 37 ++++++++++++---------------
 1 file changed, 17 insertions(+), 20 deletions(-)

diff --git a/test/fluent_api/test_file_tracking.py b/test/fluent_api/test_file_tracking.py
index 10bdd63..3318332 100644
--- a/test/fluent_api/test_file_tracking.py
+++ b/test/fluent_api/test_file_tracking.py
@@ -20,15 +20,6 @@ def test_file_monitor_with_files(run_fluent_api_notecard_api_mapping_test):
     )
 
 
-def test_file_monitor_with_files_list(run_fluent_api_notecard_api_mapping_test):
-    """Test monitoring with multiple files."""
-    run_fluent_api_notecard_api_mapping_test(
-        file.monitor,
-        'file.monitor',
-        {'files': ['data.qo', 'settings.db']}
-    )
-
-
 def test_file_track_with_invalid_interval(run_fluent_api_notecard_api_mapping_test):
     """Test tracking with invalid interval value."""
     run_fluent_api_notecard_api_mapping_test(
@@ -47,17 +38,6 @@ def test_file_track_with_invalid_duration(run_fluent_api_notecard_api_mapping_te
     )
 
 
-def test_file_monitor_with_files_and_detail_level(run_fluent_api_notecard_api_mapping_test):
-    """Test monitoring with files list."""
-    run_fluent_api_notecard_api_mapping_test(
-        file.monitor,
-        'file.monitor',
-        {
-            'files': ['data.qo', 'settings.db']
-        }
-    )
-
-
 def test_file_monitor_with_all_params(run_fluent_api_notecard_api_mapping_test):
     """Test monitoring with all available parameters."""
     run_fluent_api_notecard_api_mapping_test(
@@ -170,3 +150,20 @@ def test_file_stats_with_file(run_fluent_api_notecard_api_mapping_test):
         'file.stats',
         {'file': 'data.qo'}
     )
+
+
+def test_file_stats_response_structure(card):
+    """Test file.stats response contains required fields with correct types."""
+    card.Transaction.return_value = {
+        'total': 83,
+        'changes': 78,
+        'sync': True
+    }
+    
+    response = file.stats(card)
+    assert 'total' in response
+    assert isinstance(response['total'], int)
+    assert 'changes' in response
+    assert isinstance(response['changes'], int)
+    assert 'sync' in response
+    assert isinstance(response['sync'], bool)

From 1133055594cfdbaed0849860c3fd1bf00a6c195b Mon Sep 17 00:00:00 2001
From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Date: Wed, 29 Jan 2025 19:48:28 +0000
Subject: [PATCH 05/12] docs: update file.stats documentation and fix
 whitespace

Co-Authored-By: rlauer@blues.com <rlauer@blues.com>
---
 docs/api.md                           | 24 +++++++++++++++++++++---
 test/fluent_api/test_file_tracking.py |  1 -
 2 files changed, 21 insertions(+), 4 deletions(-)

diff --git a/docs/api.md b/docs/api.md
index 0952d7c..0db70af 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -295,17 +295,35 @@ Delete individual notefiles and their contents.
 #### Returns
 string The result of the Notecard request.
 
-#### `public def `[`stats`](#namespacenotecard_1_1file_1afd6ecece175a8ba9052b07889cf757f4)`(card)` 
+#### `public def `[`stats`](#namespacenotecard_1_1file_1afd6ecece175a8ba9052b07889cf757f4)`(card,file)` 
 
 Obtain statistics about local notefiles.
 
 #### Parameters
 * `card` The current Notecard object.
+* `file` (optional, string) Returns stats for the specified Notefile only.
 
 #### Returns
+dict containing:
+* `total` (integer): Total number of Notes across all Notefiles
+* `changes` (integer): Number of Notes pending sync
+* `sync` (boolean): True if sync is recommended based on pending notes
 
-#### Returns
-string The result of the Notecard request.
+Example request:
+```json
+{
+    "req": "file.stats"
+}
+```
+
+Example response:
+```json
+{
+    "total": 83,
+    "changes": 78,
+    "sync": true
+}
+```
 
 #### `public def `[`pendingChanges`](#namespacenotecard_1_1file_1aac52d0739fcba481f9a0bd4cfd35362e)`(card)` 
 
diff --git a/test/fluent_api/test_file_tracking.py b/test/fluent_api/test_file_tracking.py
index 3318332..260ba3e 100644
--- a/test/fluent_api/test_file_tracking.py
+++ b/test/fluent_api/test_file_tracking.py
@@ -159,7 +159,6 @@ def test_file_stats_response_structure(card):
         'changes': 78,
         'sync': True
     }
-    
     response = file.stats(card)
     assert 'total' in response
     assert isinstance(response['total'], int)

From 551a2009027e7869a3ec06da6aa49f7d59fcb6a8 Mon Sep 17 00:00:00 2001
From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Date: Wed, 29 Jan 2025 20:46:33 +0000
Subject: [PATCH 06/12] feat: add env.template support with type hint
 validation

Co-Authored-By: rlauer@blues.com <rlauer@blues.com>
---
 docs/api.md                          | 83 +++++++++++++++++++++--
 notecard/env.py                      | 44 ++++++++++++-
 notecard/validators.py               | 33 ++++++++++
 test/fluent_api/test_env.py          | 10 +++
 test/fluent_api/test_env_template.py | 99 ++++++++++++++++++++++++++++
 5 files changed, 262 insertions(+), 7 deletions(-)
 create mode 100644 test/fluent_api/test_env_template.py

diff --git a/docs/api.md b/docs/api.md
index 0db70af..1479512 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -210,19 +210,94 @@ Perform an [env.default](#namespacenotecard_1_1env_1a6ff91175ae591e8a3a87c2a4ef9
 #### Returns
 string The result of the Notecard request.
 
-#### `public def `[`get`](#namespacenotecard_1_1env_1a28ed0423d0aff1d109371427139e0a73)`(card,name)` 
+#### `public def `[`get`](#namespacenotecard_1_1env_1a28ed0423d0aff1d109371427139e0a73)`(card,name,names,time)` 
 
 Perform an [env.get](#namespacenotecard_1_1env_1a28ed0423d0aff1d109371427139e0a73) request against a Notecard.
 
 #### Parameters
-* `card` The current Notecard object. 
+* `card` The current Notecard object.
+
+* `name` (optional) The name of an environment variable to get.
 
-* `name` The name of an environment variable to get.
+* `names` (optional) List of environment variable names to retrieve.
+
+* `time` (optional) UNIX epoch time to get variables modified after.
 
 #### Returns
+dict The result of the Notecard request containing either:
+* `text` Value of the requested variable if name was specified
+* `body` Object with name/value pairs if names was specified or if neither name nor names was specified
+* `time` UNIX epoch time of the last variable change
+
+Example request with single variable:
+```json
+{
+    "req": "env.get",
+    "name": "my_var"
+}
+```
+
+Example request with multiple variables:
+```json
+{
+    "req": "env.get",
+    "names": ["var1", "var2"]
+}
+```
+
+Example response for single variable:
+```json
+{
+    "text": "value1"
+}
+```
+
+Example response for multiple variables:
+```json
+{
+    "body": {
+        "var1": "value1",
+        "var2": "value2"
+    },
+    "time": 1609459200
+}
+```
+
+#### `public def `[`template`](#namespacenotecard_1_1env_1a10f5f4667d80f47674d1876df69b8e22)`(card,body)` 
+
+Perform an env.template request against a Notecard.
+
+#### Parameters
+* `card` The current Notecard object.
+
+* `body` (optional) Schema with variable names and type hints.
+  * Boolean: must be specified as true
+  * String: numeric string for max length (pre v3.2.1) or variable-length (v3.2.1+)
+  * Integer: 11-14, 18 for signed, 21-24 for unsigned
+  * Float: 12.1 (2-byte), 14.1 (4-byte), 18.1 (8-byte)
 
 #### Returns
-string The result of the Notecard request.
+dict The result of the Notecard request, including 'bytes' field indicating storage size.
+
+Example request:
+```json
+{
+    "req": "env.template",
+    "body": {
+        "active": true,
+        "name": "32",
+        "temperature": 14.1,
+        "counter": 12
+    }
+}
+```
+
+Example response:
+```json
+{
+    "bytes": 42
+}
+```
 
 #### `public def `[`modified`](#namespacenotecard_1_1env_1aa672554b72786c9ec1e5f76b3e11eb34)`(card)` 
 
diff --git a/notecard/env.py b/notecard/env.py
index 58de6b8..c680a13 100644
--- a/notecard/env.py
+++ b/notecard/env.py
@@ -34,19 +34,29 @@ def default(card, name=None, text=None):
 
 
 @validate_card_object
-def get(card, name=None):
+def get(card, name=None, names=None, time=None):
     """Perform an env.get request against a Notecard.
 
     Args:
         card (Notecard): The current Notecard object.
-        name (string): The name of an environment variable to get.
+        name (str, optional): The name of an environment variable to get.
+        names (list, optional): List of environment variable names to retrieve.
+        time (int, optional): UNIX epoch time to get variables modified after.
 
     Returns:
-        string: The result of the Notecard request.
+        dict: The result of the Notecard request containing either:
+            - text: Value of the requested variable if name was specified
+            - body: Object with name/value pairs if names was specified or
+                   if neither name nor names was specified
+            - time: UNIX epoch time of the last variable change
     """
     req = {"req": "env.get"}
     if name:
         req["name"] = name
+    if names:
+        req["names"] = names
+    if time is not None:
+        req["time"] = time
     return card.Transaction(req)
 
 
@@ -82,3 +92,31 @@ def set(card, name=None, text=None):
     if text:
         req["text"] = text
     return card.Transaction(req)
+
+
+@validate_card_object
+def template(card, body=None):
+    """Perform an env.template request against a Notecard.
+
+    Args:
+        card (Notecard): The current Notecard object.
+        body (dict, optional): Schema with variable names and type hints.
+            Supported type hints:
+            - Boolean: true
+            - String: numeric string for max length (pre v3.2.1)
+            - Integer: 11-14, 18 (signed), 21-24 (unsigned)
+            - Float: 12.1 (2-byte), 14.1 (4-byte), 18.1 (8-byte)
+
+    Returns:
+        dict: The result of the Notecard request, including 'bytes' field
+            indicating storage size.
+
+    Raises:
+        ValueError: If type hints in body are invalid.
+    """
+    req = {"req": "env.template"}
+    if body is not None:
+        from .validators import validate_template_hints
+        validate_template_hints(body)
+        req["body"] = body
+    return card.Transaction(req)
diff --git a/notecard/validators.py b/notecard/validators.py
index 86ee922..a37cf74 100644
--- a/notecard/validators.py
+++ b/notecard/validators.py
@@ -36,3 +36,36 @@ def wrap_validator(*args, **kwargs):
             return func(*args, **kwargs)
 
         return wrap_validator
+
+
+def validate_template_hints(body):
+    """Validate type hints in env.template body.
+
+    Args:
+        body (dict): Schema with variable names and type hints.
+
+    Raises:
+        ValueError: If type hints are invalid.
+    """
+    if not isinstance(body, dict):
+        raise ValueError("Template body must be a dictionary")
+
+    for key, value in body.items():
+        if isinstance(value, bool):
+            if value is not True:
+                raise ValueError(f"Boolean hint for {key} must be True")
+        elif isinstance(value, (int, float)):
+            valid_types = [
+                11, 12, 13, 14, 18,  # signed integers
+                21, 22, 23, 24,      # unsigned integers
+                12.1, 14.1, 18.1     # floats
+            ]
+            if value not in valid_types:
+                raise ValueError(f"Invalid numeric hint for {key}")
+        elif isinstance(value, str):
+            try:
+                int(value)  # pre v3.2.1 string length
+            except ValueError:
+                pass  # post v3.2.1 variable length strings
+        else:
+            raise ValueError(f"Invalid type hint for {key}")
diff --git a/test/fluent_api/test_env.py b/test/fluent_api/test_env.py
index 963af6b..c0d9fdb 100644
--- a/test/fluent_api/test_env.py
+++ b/test/fluent_api/test_env.py
@@ -15,6 +15,16 @@
             'env.get',
             {'name': 'my_var'}
         ),
+        (
+            env.get,
+            'env.get',
+            {'names': ['var1', 'var2']}
+        ),
+        (
+            env.get,
+            'env.get',
+            {'time': 1609459200}
+        ),
         (
             env.modified,
             'env.modified',
diff --git a/test/fluent_api/test_env_template.py b/test/fluent_api/test_env_template.py
new file mode 100644
index 0000000..1d5f1fe
--- /dev/null
+++ b/test/fluent_api/test_env_template.py
@@ -0,0 +1,99 @@
+"""Tests for env.template functionality."""
+from notecard import env
+
+
+def test_env_template_basic(run_fluent_api_notecard_api_mapping_test):
+    """Test env.template with no body parameter."""
+    run_fluent_api_notecard_api_mapping_test(
+        env.template, 'env.template', {})
+
+
+def test_env_template_with_boolean(run_fluent_api_notecard_api_mapping_test):
+    """Test env.template with boolean type hint."""
+    run_fluent_api_notecard_api_mapping_test(
+        env.template, 'env.template', {'body': {'my_bool': True}})
+
+
+def test_env_template_with_string_pre_321(
+        run_fluent_api_notecard_api_mapping_test):
+    """Test string type hint in env.template.
+
+    For pre v3.2.1 format."""
+    body = {'my_string': '42'}
+    run_fluent_api_notecard_api_mapping_test(
+        env.template, 'env.template', {'body': body})
+
+
+def test_env_template_with_string_post_321(
+        run_fluent_api_notecard_api_mapping_test):
+    """Test string type hint in env.template.
+
+    For post v3.2.1 format."""
+    body = {'my_string': 'variable'}
+    run_fluent_api_notecard_api_mapping_test(
+        env.template, 'env.template', {'body': body})
+
+
+def test_env_template_with_signed_integers(
+        run_fluent_api_notecard_api_mapping_test):
+    """Test signed integer hints.
+
+    Covers all supported sizes."""
+    body = {
+        'int8': 11,    # 1 byte signed
+        'int16': 12,   # 2 byte signed
+        'int24': 13,   # 3 byte signed
+        'int32': 14,   # 4 byte signed
+        'int64': 18    # 8 byte signed
+    }
+    run_fluent_api_notecard_api_mapping_test(
+        env.template, 'env.template', {'body': body})
+
+
+def test_env_template_with_unsigned_integers(
+        run_fluent_api_notecard_api_mapping_test):
+    """Test unsigned integer hints.
+
+    Covers all supported sizes."""
+    body = {
+        'uint8': 21,   # 1 byte unsigned
+        'uint16': 22,  # 2 byte unsigned
+        'uint24': 23,  # 3 byte unsigned
+        'uint32': 24   # 4 byte unsigned
+    }
+    run_fluent_api_notecard_api_mapping_test(
+        env.template, 'env.template', {'body': body})
+
+
+def test_env_template_with_floats(run_fluent_api_notecard_api_mapping_test):
+    """Test env.template with float type hints."""
+    body = {
+        'float16': 12.1,  # 2 byte float
+        'float32': 14.1,  # 4 byte float
+        'float64': 18.1   # 8 byte float
+    }
+    run_fluent_api_notecard_api_mapping_test(
+        env.template, 'env.template', {'body': body})
+
+
+def test_env_template_with_mixed_types(
+        run_fluent_api_notecard_api_mapping_test):
+    """Test mixed type hints.
+
+    Tests bool, str, float, int."""
+    body = {
+        'active': True,
+        'name': '32',
+        'temperature': 14.1,
+        'counter': 12
+    }
+    run_fluent_api_notecard_api_mapping_test(
+        env.template, 'env.template', {'body': body})
+
+
+def test_env_template_response(card):
+    """Test env.template response contains bytes field."""
+    card.Transaction.return_value = {'bytes': 42}
+    response = env.template(card)
+    assert 'bytes' in response
+    assert isinstance(response['bytes'], int)

From a6c65149380f5ee426b3d1b2e55731d398e84a15 Mon Sep 17 00:00:00 2001
From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Date: Tue, 4 Feb 2025 19:25:59 +0000
Subject: [PATCH 07/12] revert: remove changes to auto-generated docs/api.md

Co-Authored-By: rlauer@blues.com <rlauer@blues.com>
---
 docs/api.md | 164 ++++------------------------------------------------
 1 file changed, 12 insertions(+), 152 deletions(-)

diff --git a/docs/api.md b/docs/api.md
index 1479512..5391fe4 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -98,9 +98,9 @@ Retrieve firmware version information from the Notecard.
 #### Returns
 string The result of the Notecard request.
 
-#### `public def `[`voltage`](#namespacenotecard_1_1card_1a1f9f65c34f1bd959d7902285a7537ce6)`(card,hours,offset,vmax,vmin,usb,alert)` 
+#### `public def `[`voltage`](#namespacenotecard_1_1card_1a1f9f65c34f1bd959d7902285a7537ce6)`(card,hours,offset,vmax,vmin)` 
 
-Retrieve current and historical voltage info from the Notecard, with optional USB power state monitoring.
+Retrieve current and historical voltage info from the Notecard.
 
 #### Parameters
 * `card` The current Notecard object. 
@@ -113,57 +113,10 @@ Retrieve current and historical voltage info from the Notecard, with optional US
 
 * `vmin` min voltage level to report.
 
-* `usb` Enable USB power state monitoring. When True, the Notecard will monitor USB power state changes.
-
-* `alert` Enable alerts for USB power state changes. Only works when usb=True. When enabled, power state changes are recorded in the health.qo Notefile.
-
 #### Returns
 
 #### Returns
-dict The result of the Notecard request containing voltage and power state information.
-
-Example request:
-```json
-{
-    "req": "card.voltage",
-    "usb": true,
-    "alert": true
-}
-```
-
-#### `public def `[`power`](#namespacenotecard_1_1card_1a10f5f4667d80f47674d1876df69b8e22)`(card,minutes,reset)` 
-
-Configure and query Mojo-based power consumption monitoring.
-
-#### Parameters
-* `card` The current Notecard object.
-
-* `minutes` (optional) How often to log power consumption in minutes. Default is 720 minutes (12 hours).
-
-* `reset` (optional) Reset consumption counters if True.
-
-#### Returns
-dict The result of the Notecard request containing power monitoring data.
-
-Example request:
-```json
-{
-    "req": "card.power",
-    "minutes": 120,
-    "reset": true
-}
-```
-
-Example response:
-```json
-{
-    "temperature": 26.0,
-    "voltage": 4.2,
-    "milliamp_hours": 2.45
-}
-```
-
-Note: Requires Notecard firmware v8.1.3 or later and a connected Mojo device.
+string The result of the Notecard request.
 
 #### `public def `[`wireless`](#namespacenotecard_1_1card_1a10f5f4667d80f47674d1876df69b8e22)`(card,mode,apn)` 
 
@@ -210,94 +163,19 @@ Perform an [env.default](#namespacenotecard_1_1env_1a6ff91175ae591e8a3a87c2a4ef9
 #### Returns
 string The result of the Notecard request.
 
-#### `public def `[`get`](#namespacenotecard_1_1env_1a28ed0423d0aff1d109371427139e0a73)`(card,name,names,time)` 
+#### `public def `[`get`](#namespacenotecard_1_1env_1a28ed0423d0aff1d109371427139e0a73)`(card,name)` 
 
 Perform an [env.get](#namespacenotecard_1_1env_1a28ed0423d0aff1d109371427139e0a73) request against a Notecard.
 
 #### Parameters
-* `card` The current Notecard object.
-
-* `name` (optional) The name of an environment variable to get.
-
-* `names` (optional) List of environment variable names to retrieve.
+* `card` The current Notecard object. 
 
-* `time` (optional) UNIX epoch time to get variables modified after.
+* `name` The name of an environment variable to get.
 
 #### Returns
-dict The result of the Notecard request containing either:
-* `text` Value of the requested variable if name was specified
-* `body` Object with name/value pairs if names was specified or if neither name nor names was specified
-* `time` UNIX epoch time of the last variable change
 
-Example request with single variable:
-```json
-{
-    "req": "env.get",
-    "name": "my_var"
-}
-```
-
-Example request with multiple variables:
-```json
-{
-    "req": "env.get",
-    "names": ["var1", "var2"]
-}
-```
-
-Example response for single variable:
-```json
-{
-    "text": "value1"
-}
-```
-
-Example response for multiple variables:
-```json
-{
-    "body": {
-        "var1": "value1",
-        "var2": "value2"
-    },
-    "time": 1609459200
-}
-```
-
-#### `public def `[`template`](#namespacenotecard_1_1env_1a10f5f4667d80f47674d1876df69b8e22)`(card,body)` 
-
-Perform an env.template request against a Notecard.
-
-#### Parameters
-* `card` The current Notecard object.
-
-* `body` (optional) Schema with variable names and type hints.
-  * Boolean: must be specified as true
-  * String: numeric string for max length (pre v3.2.1) or variable-length (v3.2.1+)
-  * Integer: 11-14, 18 for signed, 21-24 for unsigned
-  * Float: 12.1 (2-byte), 14.1 (4-byte), 18.1 (8-byte)
-
-#### Returns
-dict The result of the Notecard request, including 'bytes' field indicating storage size.
-
-Example request:
-```json
-{
-    "req": "env.template",
-    "body": {
-        "active": true,
-        "name": "32",
-        "temperature": 14.1,
-        "counter": 12
-    }
-}
-```
-
-Example response:
-```json
-{
-    "bytes": 42
-}
-```
+#### Returns
+string The result of the Notecard request.
 
 #### `public def `[`modified`](#namespacenotecard_1_1env_1aa672554b72786c9ec1e5f76b3e11eb34)`(card)` 
 
@@ -370,35 +248,17 @@ Delete individual notefiles and their contents.
 #### Returns
 string The result of the Notecard request.
 
-#### `public def `[`stats`](#namespacenotecard_1_1file_1afd6ecece175a8ba9052b07889cf757f4)`(card,file)` 
+#### `public def `[`stats`](#namespacenotecard_1_1file_1afd6ecece175a8ba9052b07889cf757f4)`(card)` 
 
 Obtain statistics about local notefiles.
 
 #### Parameters
 * `card` The current Notecard object.
-* `file` (optional, string) Returns stats for the specified Notefile only.
 
 #### Returns
-dict containing:
-* `total` (integer): Total number of Notes across all Notefiles
-* `changes` (integer): Number of Notes pending sync
-* `sync` (boolean): True if sync is recommended based on pending notes
 
-Example request:
-```json
-{
-    "req": "file.stats"
-}
-```
-
-Example response:
-```json
-{
-    "total": 83,
-    "changes": 78,
-    "sync": true
-}
-```
+#### Returns
+string The result of the Notecard request.
 
 #### `public def `[`pendingChanges`](#namespacenotecard_1_1file_1aac52d0739fcba481f9a0bd4cfd35362e)`(card)` 
 
@@ -799,4 +659,4 @@ Initialize the [Notecard](#classnotecard_1_1notecard_1_1_notecard) before a rese
 
 Ensure that the passed-in card is a Notecard.
 
-Generated by [Moxygen](https://sourcey.com/moxygen)
+Generated by [Moxygen](https://sourcey.com/moxygen)
\ No newline at end of file

From 286b7fada21f0cf2ceafb3972397699f2c810432 Mon Sep 17 00:00:00 2001
From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Date: Tue, 4 Feb 2025 19:43:28 +0000
Subject: [PATCH 08/12] feat: improve file module response validation and add
 array support to note.template

- Add flexible response validation for file.changes, file.stats, and file.changes.pending
- Add array support tests for note.template
- Fix format variable initialization in note.template
- Handle negative length values in note.template
- Update allowed metadata fields in compact mode (_loc -> _ltime)

Co-Authored-By: rlauer@blues.com <rlauer@blues.com>
---
 notecard/file.py                             | 40 +++++++++--
 notecard/note.py                             | 20 +++++-
 test/fluent_api/test_file_changes.py         | 70 ++++++++++++++++++++
 test/fluent_api/test_file_changes_pending.py | 30 +++++++++
 test/fluent_api/test_file_stats.py           | 39 +++++++++++
 test/fluent_api/test_note_template_arrays.py | 41 ++++++++++++
 6 files changed, 234 insertions(+), 6 deletions(-)
 create mode 100644 test/fluent_api/test_file_changes.py
 create mode 100644 test/fluent_api/test_file_changes_pending.py
 create mode 100644 test/fluent_api/test_file_stats.py
 create mode 100644 test/fluent_api/test_note_template_arrays.py

diff --git a/notecard/file.py b/notecard/file.py
index 68ca19f..3bc6520 100644
--- a/notecard/file.py
+++ b/notecard/file.py
@@ -27,9 +27,21 @@ def changes(card, tracker=None, files=None):
     req = {"req": "file.changes"}
     if tracker:
         req["tracker"] = tracker
-    if files:
+    if files is not None:  # Allow empty list
         req["files"] = files
-    return card.Transaction(req)
+
+    response = card.Transaction(req)
+    if "err" in response:
+        return response
+
+    # Only validate types when fields are present
+    if "total" in response and not isinstance(response["total"], int):
+        return {"err": "Malformed response: total must be an integer"}
+    if "changes" in response and not isinstance(response["changes"], int):
+        return {"err": "Malformed response: changes must be an integer"}
+    if "info" in response and not isinstance(response["info"], dict):
+        return {"err": "Malformed response: info must be a dictionary"}
+    return response
 
 
 @validate_card_object
@@ -66,7 +78,18 @@ def stats(card, file=None):
     req = {"req": "file.stats"}
     if file:
         req["file"] = file
-    return card.Transaction(req)
+    response = card.Transaction(req)
+    if "err" in response:
+        return response
+
+    # Only validate types when fields are present
+    if "total" in response and not isinstance(response["total"], int):
+        return {"err": "Malformed response: total must be an integer"}
+    if "changes" in response and not isinstance(response["changes"], int):
+        return {"err": "Malformed response: changes must be an integer"}
+    if "sync" in response and not isinstance(response["sync"], bool):
+        return {"err": "Malformed response: sync must be a boolean"}
+    return response
 
 
 @validate_card_object
@@ -80,7 +103,16 @@ def pendingChanges(card):
         dict: The result of the Notecard request.
     """
     req = {"req": "file.changes.pending"}
-    return card.Transaction(req)
+    response = card.Transaction(req)
+    if "err" in response:
+        return response
+
+    # Only validate types when fields are present
+    if "total" in response and not isinstance(response["total"], int):
+        return {"err": "Malformed response: total must be an integer"}
+    if "changes" in response and not isinstance(response["changes"], int):
+        return {"err": "Malformed response: changes must be an integer"}
+    return response
 
 
 @validate_card_object
diff --git a/notecard/note.py b/notecard/note.py
index 2716687..e5583e3 100644
--- a/notecard/note.py
+++ b/notecard/note.py
@@ -178,10 +178,26 @@ def template(card, file=None, body=None, length=None, port=None, compact=False):
         req["file"] = file
     if body:
         req["body"] = body
-    if length:
-        req["length"] = length
+    if length is not None:
+        if length >= 0:
+            req["length"] = length
+        # Negative length resets to default by omitting the field
     if port:
         req["port"] = port
+    format = None
     if compact:
+        format = "compact"
+
+    if format == "compact":
         req["format"] = "compact"
+        if body:
+            allowed_metadata = {"_time", "_lat", "_lon", "_ltime"}
+            for key in body.keys():
+                if key.startswith("_") and key not in allowed_metadata:
+                    return {
+                        "err": (
+                            f"Field '{key}' is not allowed in compact mode. "
+                            f"Only {allowed_metadata} are allowed.")
+                    }
+
     return card.Transaction(req)
diff --git a/test/fluent_api/test_file_changes.py b/test/fluent_api/test_file_changes.py
new file mode 100644
index 0000000..a874336
--- /dev/null
+++ b/test/fluent_api/test_file_changes.py
@@ -0,0 +1,70 @@
+"""Tests for file.changes functionality."""
+from notecard import file
+
+
+def test_file_changes_basic(run_fluent_api_notecard_api_mapping_test):
+    """Test file.changes with no parameters."""
+    run_fluent_api_notecard_api_mapping_test(
+        file.changes, 'file.changes', {})
+
+
+def test_file_changes_with_tracker(run_fluent_api_notecard_api_mapping_test):
+    """Test file.changes with tracker parameter."""
+    run_fluent_api_notecard_api_mapping_test(
+        file.changes, 'file.changes', {'tracker': 'my_tracker'})
+
+
+def test_file_changes_with_files(run_fluent_api_notecard_api_mapping_test):
+    """Test file.changes with files parameter."""
+    run_fluent_api_notecard_api_mapping_test(
+        file.changes, 'file.changes', {'files': ['file1.qo', 'file2.qo']})
+
+
+def test_file_changes_with_all_params(
+        run_fluent_api_notecard_api_mapping_test):
+    """Test file.changes with all parameters."""
+    params = {'tracker': 'my_tracker', 'files': ['file1.qo', 'file2.qo']}
+    run_fluent_api_notecard_api_mapping_test(
+        file.changes, 'file.changes', params)
+
+
+def test_file_changes_response(card):
+    """Test file.changes response structure."""
+    card.Transaction.return_value = {
+        'changes': 5,
+        'total': 42,
+        'info': {
+            'file1.qo': {'changes': 2, 'total': 20},
+            'file2.qo': {'changes': 3, 'total': 22}
+        }
+    }
+    response = file.changes(card)
+    # Validate types only when fields are present
+    if 'changes' in response:
+        assert isinstance(response['changes'], int)
+    if 'total' in response:
+        assert isinstance(response['total'], int)
+    if 'info' in response:
+        assert isinstance(response['info'], dict)
+        for filename, file_info in response['info'].items():
+            assert isinstance(file_info, dict)
+            if 'changes' in file_info:
+                assert isinstance(file_info['changes'], int)
+            if 'total' in file_info:
+                assert isinstance(file_info['total'], int)
+
+
+def test_file_changes_with_invalid_tracker(card):
+    """Test file.changes with invalid tracker format."""
+    card.Transaction.return_value = {"err": "Invalid tracker format"}
+    response = file.changes(card, tracker="@@@!!!")
+    assert "err" in response
+    assert "Invalid tracker format" in response["err"]
+
+
+def test_file_changes_with_nonexistent_files(card):
+    """Test file.changes with non-existent files."""
+    card.Transaction.return_value = {"err": "File not found"}
+    response = file.changes(card, files=["nonexistent.qo"])
+    assert "err" in response
+    assert "File not found" in response["err"]
diff --git a/test/fluent_api/test_file_changes_pending.py b/test/fluent_api/test_file_changes_pending.py
new file mode 100644
index 0000000..7f59232
--- /dev/null
+++ b/test/fluent_api/test_file_changes_pending.py
@@ -0,0 +1,30 @@
+"""Tests for file.changes.pending functionality."""
+from notecard import file
+
+
+def test_file_changes_pending_basic(run_fluent_api_notecard_api_mapping_test):
+    """Test file.changes.pending with no parameters."""
+    run_fluent_api_notecard_api_mapping_test(
+        file.pendingChanges, 'file.changes.pending', {})
+
+
+def test_file_changes_pending_response(card):
+    """Test file.changes.pending response structure."""
+    card.Transaction.return_value = {
+        'total': 42,
+        'changes': 5
+    }
+    response = file.pendingChanges(card)
+    # Validate types only when fields are present
+    if 'total' in response:
+        assert isinstance(response['total'], int)
+    if 'changes' in response:
+        assert isinstance(response['changes'], int)
+
+
+def test_file_changes_pending_with_error(card):
+    """Test file.changes.pending error handling."""
+    card.Transaction.return_value = {"err": "Internal error"}
+    response = file.pendingChanges(card)
+    assert "err" in response
+    assert "Internal error" in response["err"]
diff --git a/test/fluent_api/test_file_stats.py b/test/fluent_api/test_file_stats.py
new file mode 100644
index 0000000..fa84ff1
--- /dev/null
+++ b/test/fluent_api/test_file_stats.py
@@ -0,0 +1,39 @@
+"""Tests for file.stats functionality."""
+from notecard import file
+
+
+def test_file_stats_basic(run_fluent_api_notecard_api_mapping_test):
+    """Test file.stats with no parameters."""
+    run_fluent_api_notecard_api_mapping_test(
+        file.stats, 'file.stats', {})
+
+
+def test_file_stats_with_file(run_fluent_api_notecard_api_mapping_test):
+    """Test file.stats with file parameter."""
+    run_fluent_api_notecard_api_mapping_test(
+        file.stats, 'file.stats', {'file': 'test.qo'})
+
+
+def test_file_stats_response(card):
+    """Test file.stats response structure."""
+    card.Transaction.return_value = {
+        'total': 42,
+        'changes': 5,
+        'sync': True
+    }
+    response = file.stats(card)
+    # Validate types only when fields are present
+    if 'total' in response:
+        assert isinstance(response['total'], int)
+    if 'changes' in response:
+        assert isinstance(response['changes'], int)
+    if 'sync' in response:
+        assert isinstance(response['sync'], bool)
+
+
+def test_file_stats_with_error(card):
+    """Test file.stats error handling."""
+    card.Transaction.return_value = {"err": "File not found"}
+    response = file.stats(card, file="nonexistent.qo")
+    assert "err" in response
+    assert "File not found" in response["err"]
diff --git a/test/fluent_api/test_note_template_arrays.py b/test/fluent_api/test_note_template_arrays.py
new file mode 100644
index 0000000..e038899
--- /dev/null
+++ b/test/fluent_api/test_note_template_arrays.py
@@ -0,0 +1,41 @@
+"""Tests for note.template with array support."""
+from notecard import note
+
+
+def test_template_with_array_body(run_fluent_api_notecard_api_mapping_test):
+    """Test note.template with an array body."""
+    run_fluent_api_notecard_api_mapping_test(
+        note.template, 'note.template',
+        {'body': ['item1', 'item2', 'item3']})
+
+
+def test_template_with_array_in_body(run_fluent_api_notecard_api_mapping_test):
+    """Test note.template with an object containing an array."""
+    run_fluent_api_notecard_api_mapping_test(
+        note.template, 'note.template',
+        {'body': {'list_field': ['item1', 'item2']}})
+
+
+def test_template_with_nested_arrays(run_fluent_api_notecard_api_mapping_test):
+    """Test note.template with nested arrays in body."""
+    run_fluent_api_notecard_api_mapping_test(
+        note.template, 'note.template',
+        {'body': {'matrix': [[1, 2], [3, 4]]}})
+
+
+def test_template_with_mixed_types(run_fluent_api_notecard_api_mapping_test):
+    """Test note.template with mixed types in arrays."""
+    run_fluent_api_notecard_api_mapping_test(
+        note.template, 'note.template',
+        {'body': {'mixed': [1, "text", True, 3.14]}})
+
+
+def test_template_response_with_array(card):
+    """Test note.template response handling with array data."""
+    card.Transaction.return_value = {
+        'body': ['response_item1', 'response_item2']
+    }
+    response = note.template(card, body=['test1', 'test2'])
+    assert isinstance(response, dict)
+    if 'body' in response:
+        assert isinstance(response['body'], list)

From bf74b553a056a72f048cc4d25be59a7a593c4b93 Mon Sep 17 00:00:00 2001
From: Rob Lauer <rdlauer@gmail.com>
Date: Fri, 7 Feb 2025 13:51:44 -0600
Subject: [PATCH 09/12] fixing mistakes by devin

---
 notecard/env.py        |  5 -----
 notecard/note.py       | 27 ++++++++++++---------------
 notecard/validators.py | 36 +++---------------------------------
 3 files changed, 15 insertions(+), 53 deletions(-)

diff --git a/notecard/env.py b/notecard/env.py
index c680a13..5494e73 100644
--- a/notecard/env.py
+++ b/notecard/env.py
@@ -110,13 +110,8 @@ def template(card, body=None):
     Returns:
         dict: The result of the Notecard request, including 'bytes' field
             indicating storage size.
-
-    Raises:
-        ValueError: If type hints in body are invalid.
     """
     req = {"req": "env.template"}
     if body is not None:
-        from .validators import validate_template_hints
-        validate_template_hints(body)
         req["body"] = body
     return card.Transaction(req)
diff --git a/notecard/note.py b/notecard/note.py
index e5583e3..5135080 100644
--- a/notecard/note.py
+++ b/notecard/note.py
@@ -44,8 +44,16 @@ def add(card, file=None, body=None, payload=None, sync=None, port=None):
 
 
 @validate_card_object
-def changes(card, file=None, tracker=None, maximum=None,
-            start=None, stop=None, deleted=None, delete=None):
+def changes(
+    card,
+    file=None,
+    tracker=None,
+    maximum=None,
+    start=None,
+    stop=None,
+    deleted=None,
+    delete=None,
+):
     """Incrementally retrieve changes within a Notefile.
 
     Args:
@@ -179,25 +187,14 @@ def template(card, file=None, body=None, length=None, port=None, compact=False):
     if body:
         req["body"] = body
     if length is not None:
-        if length >= 0:
-            req["length"] = length
-        # Negative length resets to default by omitting the field
+        req["length"] = length
     if port:
         req["port"] = port
-    format = None
+
     if compact:
         format = "compact"
 
     if format == "compact":
         req["format"] = "compact"
-        if body:
-            allowed_metadata = {"_time", "_lat", "_lon", "_ltime"}
-            for key in body.keys():
-                if key.startswith("_") and key not in allowed_metadata:
-                    return {
-                        "err": (
-                            f"Field '{key}' is not allowed in compact mode. "
-                            f"Only {allowed_metadata} are allowed.")
-                    }
 
     return card.Transaction(req)
diff --git a/notecard/validators.py b/notecard/validators.py
index a37cf74..323fdc9 100644
--- a/notecard/validators.py
+++ b/notecard/validators.py
@@ -12,6 +12,7 @@
 
     def validate_card_object(func):
         """Ensure that the passed-in card is a Notecard."""
+
         @functools.wraps(func)
         def wrap_validator(*args, **kwargs):
             """Check the instance of the passed-in card."""
@@ -22,11 +23,13 @@ def wrap_validator(*args, **kwargs):
             return func(*args, **kwargs)
 
         return wrap_validator
+
 else:
     # MicroPython and CircuitPython do not support
     # functools. Do not perform validation for these platforms
     def validate_card_object(func):
         """Skip validation."""
+
         def wrap_validator(*args, **kwargs):
             """Check the instance of the passed-in card."""
             card = args[0]
@@ -36,36 +39,3 @@ def wrap_validator(*args, **kwargs):
             return func(*args, **kwargs)
 
         return wrap_validator
-
-
-def validate_template_hints(body):
-    """Validate type hints in env.template body.
-
-    Args:
-        body (dict): Schema with variable names and type hints.
-
-    Raises:
-        ValueError: If type hints are invalid.
-    """
-    if not isinstance(body, dict):
-        raise ValueError("Template body must be a dictionary")
-
-    for key, value in body.items():
-        if isinstance(value, bool):
-            if value is not True:
-                raise ValueError(f"Boolean hint for {key} must be True")
-        elif isinstance(value, (int, float)):
-            valid_types = [
-                11, 12, 13, 14, 18,  # signed integers
-                21, 22, 23, 24,      # unsigned integers
-                12.1, 14.1, 18.1     # floats
-            ]
-            if value not in valid_types:
-                raise ValueError(f"Invalid numeric hint for {key}")
-        elif isinstance(value, str):
-            try:
-                int(value)  # pre v3.2.1 string length
-            except ValueError:
-                pass  # post v3.2.1 variable length strings
-        else:
-            raise ValueError(f"Invalid type hint for {key}")

From 5386c2db191104b4fc6e8feb98a31aeb77b18d0a Mon Sep 17 00:00:00 2001
From: Rob Lauer <rdlauer@gmail.com>
Date: Mon, 10 Feb 2025 10:53:51 -0600
Subject: [PATCH 10/12] removing invalid file.monitor/track

---
 notecard/file.py | 42 ------------------------------------------
 1 file changed, 42 deletions(-)

diff --git a/notecard/file.py b/notecard/file.py
index 3bc6520..ee34103 100644
--- a/notecard/file.py
+++ b/notecard/file.py
@@ -113,45 +113,3 @@ def pendingChanges(card):
     if "changes" in response and not isinstance(response["changes"], int):
         return {"err": "Malformed response: changes must be an integer"}
     return response
-
-
-@validate_card_object
-def monitor(card, files=None):
-    """Monitor one or more files in detail.
-
-    Args:
-        card (Notecard): The current Notecard object.
-        files (list, optional): List of Notefiles to monitor. Defaults to None.
-
-    Returns:
-        dict: Detailed information about each file.
-    """
-    req = {"req": "file.monitor"}
-    if files is not None:
-        req["files"] = files
-    return card.Transaction(req)
-
-
-@validate_card_object
-def track(card, files=None, interval=None, duration=None):
-    """Enable continuous tracking of file changes.
-
-    Args:
-        card (Notecard): The current Notecard object.
-        files (list, optional): List of Notefiles to track. Defaults to None.
-        interval (int, optional): Polling interval in seconds. Defaults to
-            None.
-        duration (int, optional): Total tracking duration in seconds. Defaults
-            to None.
-
-    Returns:
-        dict: The result of the Notecard request with tracking configuration.
-    """
-    req = {"req": "file.track"}
-    if files:
-        req["files"] = files
-    if interval is not None:
-        req["interval"] = interval
-    if duration is not None:
-        req["duration"] = duration
-    return card.Transaction(req)

From d2085d309f143102bc95127d535b93db9e260d17 Mon Sep 17 00:00:00 2001
From: Rob Lauer <rdlauer@gmail.com>
Date: Mon, 10 Feb 2025 10:54:58 -0600
Subject: [PATCH 11/12] invalid tests

---
 test/fluent_api/test_file_tracking.py | 168 --------------------------
 1 file changed, 168 deletions(-)
 delete mode 100644 test/fluent_api/test_file_tracking.py

diff --git a/test/fluent_api/test_file_tracking.py b/test/fluent_api/test_file_tracking.py
deleted file mode 100644
index 260ba3e..0000000
--- a/test/fluent_api/test_file_tracking.py
+++ /dev/null
@@ -1,168 +0,0 @@
-"""Tests for file tracking and monitoring functionality."""
-from notecard import file
-
-
-def test_file_monitor_basic(run_fluent_api_notecard_api_mapping_test):
-    """Test basic file monitoring without options."""
-    run_fluent_api_notecard_api_mapping_test(
-        file.monitor,
-        'file.monitor',
-        {}
-    )
-
-
-def test_file_monitor_with_files(run_fluent_api_notecard_api_mapping_test):
-    """Test monitoring specific files."""
-    run_fluent_api_notecard_api_mapping_test(
-        file.monitor,
-        'file.monitor',
-        {'files': ['data.qo', 'settings.db']}
-    )
-
-
-def test_file_track_with_invalid_interval(run_fluent_api_notecard_api_mapping_test):
-    """Test tracking with invalid interval value."""
-    run_fluent_api_notecard_api_mapping_test(
-        file.track,
-        'file.track',
-        {'interval': -1}
-    )
-
-
-def test_file_track_with_invalid_duration(run_fluent_api_notecard_api_mapping_test):
-    """Test tracking with invalid duration value."""
-    run_fluent_api_notecard_api_mapping_test(
-        file.track,
-        'file.track',
-        {'duration': -1}
-    )
-
-
-def test_file_monitor_with_all_params(run_fluent_api_notecard_api_mapping_test):
-    """Test monitoring with all available parameters."""
-    run_fluent_api_notecard_api_mapping_test(
-        file.monitor,
-        'file.monitor',
-        {
-            'files': ['data.qo', 'settings.db']
-        }
-    )
-
-
-def test_file_stats_with_no_params(run_fluent_api_notecard_api_mapping_test):
-    """Test file stats with no parameters."""
-    run_fluent_api_notecard_api_mapping_test(
-        file.stats,
-        'file.stats',
-        {}
-    )
-
-
-def test_file_track_with_zero_duration(run_fluent_api_notecard_api_mapping_test):
-    """Test tracking with zero duration (should be valid)."""
-    run_fluent_api_notecard_api_mapping_test(
-        file.track,
-        'file.track',
-        {'duration': 0}
-    )
-
-
-def test_file_track_with_zero_interval(run_fluent_api_notecard_api_mapping_test):
-    """Test tracking with zero interval (should be valid)."""
-    run_fluent_api_notecard_api_mapping_test(
-        file.track,
-        'file.track',
-        {'interval': 0}
-    )
-
-
-def test_file_monitor_with_empty_files(run_fluent_api_notecard_api_mapping_test):
-    """Test monitoring with empty files list."""
-    run_fluent_api_notecard_api_mapping_test(
-        file.monitor,
-        'file.monitor',
-        {'files': []}
-    )
-
-
-def test_file_track_basic(run_fluent_api_notecard_api_mapping_test):
-    """Test basic file tracking without options."""
-    run_fluent_api_notecard_api_mapping_test(
-        file.track,
-        'file.track',
-        {}
-    )
-
-
-def test_file_track_with_files(run_fluent_api_notecard_api_mapping_test):
-    """Test tracking specific files."""
-    run_fluent_api_notecard_api_mapping_test(
-        file.track,
-        'file.track',
-        {'files': ['data.qo', 'config.db']}
-    )
-
-
-def test_file_track_with_interval(run_fluent_api_notecard_api_mapping_test):
-    """Test tracking with custom interval."""
-    run_fluent_api_notecard_api_mapping_test(
-        file.track,
-        'file.track',
-        {'interval': 60}
-    )
-
-
-def test_file_track_with_duration(run_fluent_api_notecard_api_mapping_test):
-    """Test tracking with specified duration."""
-    run_fluent_api_notecard_api_mapping_test(
-        file.track,
-        'file.track',
-        {'duration': 3600}
-    )
-
-
-def test_file_track_full_config(run_fluent_api_notecard_api_mapping_test):
-    """Test tracking with all parameters."""
-    run_fluent_api_notecard_api_mapping_test(
-        file.track,
-        'file.track',
-        {
-            'files': ['data.qo'],
-            'interval': 30,
-            'duration': 1800
-        }
-    )
-
-
-def test_file_stats_basic(run_fluent_api_notecard_api_mapping_test):
-    """Test basic file stats without extended info."""
-    run_fluent_api_notecard_api_mapping_test(
-        file.stats,
-        'file.stats',
-        {}
-    )
-
-
-def test_file_stats_with_file(run_fluent_api_notecard_api_mapping_test):
-    """Test file stats with specific file parameter."""
-    run_fluent_api_notecard_api_mapping_test(
-        file.stats,
-        'file.stats',
-        {'file': 'data.qo'}
-    )
-
-
-def test_file_stats_response_structure(card):
-    """Test file.stats response contains required fields with correct types."""
-    card.Transaction.return_value = {
-        'total': 83,
-        'changes': 78,
-        'sync': True
-    }
-    response = file.stats(card)
-    assert 'total' in response
-    assert isinstance(response['total'], int)
-    assert 'changes' in response
-    assert isinstance(response['changes'], int)
-    assert 'sync' in response
-    assert isinstance(response['sync'], bool)

From 5fc71709d099c63e8e158578ab4cf913a7a6f428 Mon Sep 17 00:00:00 2001
From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Date: Mon, 10 Feb 2025 17:54:53 +0000
Subject: [PATCH 12/12] fix: initialize format variable in note.template to fix
 UnboundLocalError

Co-Authored-By: rlauer@blues.com <rlauer@blues.com>
---
 notecard/note.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/notecard/note.py b/notecard/note.py
index 5135080..0561904 100644
--- a/notecard/note.py
+++ b/notecard/note.py
@@ -191,6 +191,7 @@ def template(card, file=None, body=None, length=None, port=None, compact=False):
     if port:
         req["port"] = port
 
+    format = None
     if compact:
         format = "compact"