feat: add NTN support to hub module

notecard/hub.py

@@ -9,7 +9,6 @@
 # This module contains helper methods for calling hub.* Notecard API commands.
 # This module is optional and not required for use with the Notecard.
 
-import notecard
 from notecard.validators import validate_card_object
 
 
@@ -67,16 +66,32 @@ def set(card, product=None, sn=None, mode=None, outbound=None,
 
 
 @validate_card_object
-def sync(card):
+def sync(card, allow=None, out=None, in_=None):
     """Initiate a sync of the Notecard to Notehub.
 
     Args:
         card (Notecard): The current Notecard object.
+        allow (bool): Set to true to remove the Notecard from certain
+            types of penalty boxes (default is false). Serialized as a JSON
+            boolean in the request.
+        out (bool): Set to true to only sync pending outbound Notefiles.
+            Serialized as a JSON boolean in the request.
+        in_ (bool): Set to true to only sync pending inbound Notefiles.
+            Required when using NTN mode with Starnote. Note: This parameter
+            is named 'in_' in Python code but appears as 'in' in the JSON
+            request to the Notecard. Serialized as a JSON boolean.
 
     Returns:
-        string: The result of the Notecard request.
+        dict: The result of the Notecard request containing sync status.
+            Example request: {"req": "hub.sync", "in": true, "out": false}
     """
     req = {"req": "hub.sync"}
+    if allow is not None:
+        req["allow"] = allow
+    if out is not None:
+        req["out"] = out
+    if in_ is not None:
+        req["in"] = in_
     return card.Transaction(req)
 
 
@@ -90,12 +105,11 @@ def syncStatus(card, sync=None):
             outbound data.
 
     Returns:
-        string: The result of the Notecard request.
+        dict: The result of the Notecard request containing sync status.
     """
     req = {"req": "hub.sync.status"}
     if sync is not None:
         req["sync"] = sync
-
     return card.Transaction(req)
 
 
@@ -107,7 +121,7 @@ def status(card):
         card (Notecard): The current Notecard object.
 
     Returns:
-        string: The result of the Notecard request.
+        dict: The result of the Notecard request containing connection status.
     """
     req = {"req": "hub.status"}
     return card.Transaction(req)

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):

test/fluent_api/test_hub_ntn.py

@@ -0,0 +1,90 @@
+"""Test NTN support in hub module."""
+import json
+from unittest.mock import ANY, call
+from notecard import hub
+
+
+def test_sync_with_ntn(run_fluent_api_notecard_api_mapping_test):
+    """Test hub.sync with NTN support."""
+    run_fluent_api_notecard_api_mapping_test(
+        hub.sync,
+        "hub.sync",
+        {"allow": True}
+    )
+
+    run_fluent_api_notecard_api_mapping_test(
+        hub.sync,
+        "hub.sync",
+        {"allow": False}
+    )
+
+    run_fluent_api_notecard_api_mapping_test(
+        hub.sync,
+        "hub.sync",
+        {"out": True}
+    )
+
+    run_fluent_api_notecard_api_mapping_test(
+        hub.sync,
+        "hub.sync",
+        {"in_": True},
+        {"in_": "in"}
+    )
+
+    run_fluent_api_notecard_api_mapping_test(
+        hub.sync,
+        "hub.sync",
+        {"out": True, "in_": True},
+        {"in_": "in"}
+    )
+
+    run_fluent_api_notecard_api_mapping_test(
+        hub.sync,
+        "hub.sync",
+        {}
+    )
+
+
+def test_sync_boolean_serialization(card):
+    """Test that boolean values are properly serialized in hub.sync."""
+    hub.sync(card, in_=True, out=False, allow=True)
+    # Verify the Transaction was called with correct boolean values
+    expected_req = {
+        'req': 'hub.sync',
+        'in': True,
+        'out': False,
+        'allow': True
+    }
+    card.Transaction.assert_called_once_with(expected_req)
+    # Verify JSON serialization format
+    args = card.Transaction.call_args
+    req_dict = args[0][0]
+    # Verify boolean values are preserved after JSON serialization
+    json_dict = json.loads(json.dumps(req_dict))
+    assert json_dict["in"] is True
+    assert json_dict["out"] is False
+    assert json_dict["allow"] is True
+
+
+def test_sync_status(run_fluent_api_notecard_api_mapping_test):
+    """Test hub.syncStatus."""
+    run_fluent_api_notecard_api_mapping_test(
+        hub.syncStatus,
+        "hub.sync.status",
+        {"sync": True}
+    )
+
+    run_fluent_api_notecard_api_mapping_test(
+        hub.syncStatus,
+        "hub.sync.status",
+        {}
+    )
+
+
+def test_status(run_fluent_api_notecard_api_mapping_test):
+    """Test hub.status."""
+    run_fluent_api_notecard_api_mapping_test(
+        hub.status,
+        "hub.status",
+        {}
+    )