feat: adding sync to note.update (and small wording updates) (#304)

Author: tjvantoll

card.temp.rsp.notecard.api.json

@@ -14,7 +14,7 @@
     ],
     "properties": {
         "calibration": {
-            "description": "The calibration differential of the Notecard's onboard sensor.",
+            "description": "The calibration differential, in degrees centigrade, applied to the Notecard's onboard temperature sensor. This per-device offset is added to the raw sensor reading to produce `value`.",
             "type": "number"
         },
         "humidity": {

note.update.req.notecard.api.json

@@ -30,6 +30,10 @@
             "description": "A base64-encoded binary payload. A Note must have either a `body` or `payload`, and can have both.",
             "type": "string"
         },
+        "sync": {
+            "description": "Set to `true` to sync the Notefile immediately after updating the Note. Only the specified Notefile is guaranteed to sync.",
+            "type": "boolean"
+        },
         "verify": {
             "description": "If set to `true` and using a templated Notefile, the Notefile will be written to flash immediately, rather than being cached in RAM and written to flash later.",
             "type": "boolean"
@@ -107,6 +111,11 @@
             "title": "Update with Command",
             "description": "Update a Note using command syntax (no response expected).",
             "json": "{\"cmd\": \"note.update\", \"file\": \"cache.db\", \"note\": \"temp-data\", \"body\": {\"status\": \"updated\"}}"
+        },
+        {
+            "title": "Update and Sync",
+            "description": "Update a Note and trigger an immediate sync of the Notefile.",
+            "json": "{\"req\": \"note.update\", \"file\": \"my-settings.db\", \"note\": \"measurements\", \"body\": {\"interval\": 60}, \"sync\": true}"
         }
     ]
 }

ntn.gps.req.notecard.api.json

@@ -19,7 +19,7 @@
             "type": "boolean"
         },
         "on": {
-            "description": "When `true`, a Starnote will use the GPS/GNSS location from its paired Notecard, instead of its own GPS/GNSS location.",
+            "description": "When `true`, a Starnote will use the location known to its paired Notecard, instead of the Starnote's own GPS/GNSS module.",
             "type": "boolean"
         },
         "req": {

tests/test_note_update_req.py

@@ -41,6 +41,17 @@ def test_valid_req_with_verify(schema):
     }
     jsonschema.validate(instance=instance, schema=schema)
 
+def test_valid_req_with_sync(schema):
+    """Tests a valid request with sync parameter."""
+    instance = {
+        "req": "note.update",
+        "file": "my-settings.db",
+        "note": "measurements",
+        "body": {"interval": 60},
+        "sync": True
+    }
+    jsonschema.validate(instance=instance, schema=schema)
+
 def test_valid_api_reference_example(schema):
     """Tests the exact example from API reference."""
     instance = {
@@ -215,6 +226,20 @@ def test_verify_invalid_type_integer(schema):
         jsonschema.validate(instance=instance, schema=schema)
     assert "1 is not of type 'boolean'" in str(excinfo.value)
 
+def test_sync_invalid_type_string(schema):
+    """Tests invalid string type for sync."""
+    instance = {"req": "note.update", "file": "data.db", "note": "test", "body": {"data": "test"}, "sync": "true"}
+    with pytest.raises(jsonschema.ValidationError) as excinfo:
+        jsonschema.validate(instance=instance, schema=schema)
+    assert "'true' is not of type 'boolean'" in str(excinfo.value)
+
+def test_sync_invalid_type_integer(schema):
+    """Tests invalid integer type for sync."""
+    instance = {"req": "note.update", "file": "data.db", "note": "test", "body": {"data": "test"}, "sync": 1}
+    with pytest.raises(jsonschema.ValidationError) as excinfo:
+        jsonschema.validate(instance=instance, schema=schema)
+    assert "1 is not of type 'boolean'" in str(excinfo.value)
+
 def test_invalid_additional_property(schema):
     """Tests invalid request with additional property."""
     instance = {"req": "note.update", "file": "data.db", "note": "test", "body": {"data": "test"}, "extra": "not allowed"}