lvi-api-client 0.2.0__tar.gz → 0.2.2__tar.gz

{lvi_api_client-0.2.0 → lvi_api_client-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lvi-api-client
-Version: 0.2.0
+Version: 0.2.2
 Summary: LogicVein API Client Library
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown

lvi_api_client-0.2.2/VERSION

@@ -0,0 +1 @@
+0.2.2

{lvi_api_client-0.2.0 → lvi_api_client-0.2.2}/src/logicvein/lvi_api_client.py

@@ -2907,8 +2907,14 @@ class LogicVeinAPIClient:
         time_zone: str = "Etc/GMT",
         paused: bool = False,
         filter_name: str = "",
+        trigger_id: Optional[int] = None,
     ) -> Optional[Dict[str, Any]]:
-        """Schedule a trigger for an existing job.
+        """Schedule a trigger for an existing job, or change one it has.
+
+        Without ``trigger_id`` this always adds a trigger, even one identical to
+        a trigger the job already has, so each repeat adds another schedule. Use
+        :meth:`get_job_triggers` to check first. With ``trigger_id`` it updates
+        that trigger in place, and every field is set from these arguments.
 
         For a one-time run, pass an ISO datetime string as ``cron_expression``
         (e.g. ``"2026-03-17T09:00"``).  Standard cron syntax works for recurring
@@ -2918,29 +2924,65 @@ class LogicVeinAPIClient:
             job_id (int): ID of the job to schedule (returned by :meth:`save_job`).
             trigger_name (str): Display name for the trigger.
             cron_expression (str): ISO datetime (one-time) or cron expression (recurring).
-            time_zone (str): Timezone name (e.g. ``"America/Halifax"``).  Default ``"UTC"``.
+            time_zone (str): Timezone name (e.g. ``"America/Halifax"``).  Default ``"Etc/GMT"``.
             paused (bool): Whether to create the trigger in a paused state.
             filter_name (str): Optional filter name; pass empty string for none.
+            trigger_id (Optional[int]): ID of the trigger to update, or None to add one.
 
         Returns:
             Dict[str, Any]: The saved trigger record (contains ``triggerId``,
             ``nextExpectedFireTime``, etc.), or None on failure.
         """
-        response = self.call(
-            "Scheduler.saveTrigger",
-            triggerData={
-                "triggerName": trigger_name,
-                "paused": paused,
-                "cronExpression": cron_expression,
-                "timeZone": time_zone,
-                "filterName": filter_name,
-                "jobId": job_id,
-            },
-        )
+        trigger_data: Dict[str, Any] = {
+            "triggerName": trigger_name,
+            "paused": paused,
+            "cronExpression": cron_expression,
+            "timeZone": time_zone,
+            "filterName": filter_name,
+            "jobId": job_id,
+        }
+        if trigger_id is not None:
+            trigger_data["triggerId"] = trigger_id
+        response = self.call("Scheduler.saveTrigger", triggerData=trigger_data)
         if response and isinstance(response, dict) and "result" in response:
             return response["result"]
         return None
 
+    def get_job_triggers(self, job_id: int) -> List[Dict[str, Any]]:
+        """Get the triggers of a job.
+
+        Args:
+            job_id (int): ID of the job. An unknown job has no triggers.
+
+        Returns:
+            List[Dict[str, Any]]: The trigger records (``triggerId``, ``jobId``,
+            ``triggerName``, ``cronExpression``, ``timeZone``, ``paused``,
+            ``filterName``, ``nextExpectedFireTime``, ``accessLimited``). The list
+            is empty only when the server says the job has none.
+
+        Raises:
+            ValueError: If the server's answer is not a list. Callers check this list
+                before adding a trigger, so a failed read must not look like no triggers.
+        """
+        response = self.call("Scheduler.getTriggersOfJob", jobId=job_id)
+        triggers = response.get("result") if isinstance(response, dict) else None
+        if not isinstance(triggers, list):
+            raise ValueError(f"Scheduler.getTriggersOfJob did not return a list for job {job_id}")
+        return triggers
+
+    def delete_trigger(self, trigger_id: int) -> bool:
+        """Delete a trigger.
+
+        Args:
+            trigger_id (int): ID of the trigger to delete.
+
+        Returns:
+            bool: The server's answer. It answers True for a trigger that is
+            already gone, so this does not show that one existed.
+        """
+        response = self.call("Scheduler.deleteTrigger", triggerId=trigger_id)
+        return bool(response and isinstance(response, dict) and response.get("result"))
+
     def create_command_runner_job(
         self,
         device_ip: str,
@@ -3845,6 +3887,10 @@ class LogicVeinAPIClient:
         Calls Collection.addMonitorsToSet. The setId must be provided both as a top-level
         parameter and within each monitor object. Returns the saved monitors with assigned IDs.
 
+        This always adds: the server stores a new monitor even for a name already in the
+        set, or with the ID of an existing monitor, and leaves the old one as it was. Use
+        :meth:`save_monitor` to change one.
+
         Each monitor object should have:
             {
                 "monitorId": int - Use -1 for new monitors; assigned ID returned in response,
@@ -3863,7 +3909,7 @@ class LogicVeinAPIClient:
 
         Args:
             set_id (int): The monitor set ID to add monitors to.
-            monitors (List[Dict[str, Any]]): List of monitor objects to add/update.
+            monitors (List[Dict[str, Any]]): List of monitor objects to add.
 
         Returns:
             List[Dict[str, Any]]: List of saved monitor objects with assigned monitorIds.
@@ -3894,6 +3940,156 @@ class LogicVeinAPIClient:
             return True
         return False
 
+    def create_monitor_set(
+        self, set_name: str, managed_networks: List[str], smart_set: bool = False
+    ) -> Optional[Dict[str, Any]]:
+        """Create a monitor set.
+
+        A name already taken in those networks makes the server answer HTTP 500, which
+        raises, and stores nothing.
+
+        Args:
+            set_name (str): The set's name. Use :meth:`is_monitor_set_name_unique` to check it first.
+            managed_networks (List[str]): The networks the set belongs to, at least one.
+            smart_set (bool): Whether this is a smart set.
+
+        Returns:
+            Dict[str, Any]: The saved set (``setId``, ``setName``, ``smartSet``,
+            ``managedNetworks``), or None on failure.
+
+        Raises:
+            ValueError: If no network is given. An empty list was not tried against a
+                server, as a failed rule set save with no networks leaves a row that
+                cannot be removed.
+        """
+        if not managed_networks:
+            raise ValueError("A monitor set needs at least one managed network")
+        return self._save_monitor_set(
+            {"setId": -1, "setName": set_name, "smartSet": smart_set, "managedNetworks": managed_networks}
+        )
+
+    def update_monitor_set(
+        self,
+        set_id: int,
+        set_name: Optional[str] = None,
+        managed_networks: Optional[List[str]] = None,
+        smart_set: Optional[bool] = None,
+    ) -> Optional[Dict[str, Any]]:
+        """Change a monitor set, keeping what is not given.
+
+        Args:
+            set_id (int): The ID of the set.
+            set_name (Optional[str]): A new name, or None to keep it.
+            managed_networks (Optional[List[str]]): New networks, at least one, or None to keep them.
+            smart_set (Optional[bool]): Whether it is a smart set, or None to keep it.
+
+        Returns:
+            Dict[str, Any]: The saved set, or None on failure.
+
+        Raises:
+            ValueError: If the set does not exist, or an empty list of networks is given.
+        """
+        if managed_networks is not None and not managed_networks:
+            raise ValueError("A monitor set needs at least one managed network")
+        monitor_set = self.get_monitor_set(set_id)
+        if not monitor_set:
+            raise ValueError(f"Monitor set {set_id} does not exist")
+        changes = {"setName": set_name, "managedNetworks": managed_networks, "smartSet": smart_set}
+        return self._save_monitor_set({**monitor_set, **{k: v for k, v in changes.items() if v is not None}})
+
+    def _save_monitor_set(self, monitor_set: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+        """Save a monitor set record.
+
+        Args:
+            monitor_set (Dict[str, Any]): The whole record. A ``setId`` of -1 creates a set.
+
+        Returns:
+            Dict[str, Any]: The saved set, or None on failure.
+        """
+        response = self.call("Collection.saveMonitorSet", monitorSet=monitor_set)
+        if response and isinstance(response, dict) and "result" in response:
+            return response["result"]
+        return None
+
+    def delete_monitor_sets(self, set_ids: List[int]) -> bool:
+        """Delete monitor sets, with their monitors.
+
+        This also takes those monitors off the devices they were deployed to. The server
+        answers success for a set that does not exist, so True does not show that one did.
+
+        Args:
+            set_ids (List[int]): The IDs of the sets to delete.
+
+        Returns:
+            bool: True if successful (result is null), otherwise False.
+        """
+        response = self.call("Collection.deleteMonitorSets", setIds=set_ids)
+        return bool(response and isinstance(response, dict) and "result" in response and response["result"] is None)
+
+    def is_monitor_set_name_unique(self, set_name: str, managed_networks: List[str], ignore_set_id: int = -1) -> bool:
+        """Check whether a monitor set name is free in some networks.
+
+        Args:
+            set_name (str): The name to check.
+            managed_networks (List[str]): The networks to check it in.
+            ignore_set_id (int): A set to leave out, such as the one being renamed. -1 for none.
+
+        Returns:
+            bool: True if the name is free.
+
+        Raises:
+            ValueError: If the server's answer is not true or false.
+        """
+        response = self.call(
+            "Collection.isMonitorSetNameUnique",
+            setName=set_name,
+            managedNetworks=managed_networks,
+            ignoreSetId=ignore_set_id,
+        )
+        unique = response.get("result") if isinstance(response, dict) else None
+        if not isinstance(unique, bool):
+            raise ValueError(f"Collection.isMonitorSetNameUnique did not answer true or false for {set_name}")
+        return unique
+
+    def save_monitor(self, monitor: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+        """Update a monitor in place.
+
+        The monitor keeps its ID, and a device it is deployed to gets the change.
+
+        Args:
+            monitor (Dict[str, Any]): The whole record as :meth:`get_monitors_for_set` returns
+                it, with the changes made.
+
+        Returns:
+            Dict[str, Any]: The saved monitor, or None on failure.
+        """
+        response = self.call("Collection.saveMonitor", monitor=monitor)
+        if response and isinstance(response, dict) and "result" in response:
+            return response["result"]
+        return None
+
+    def get_monitors_for_host(self, device_uuid: str, network: str) -> List[Dict[str, Any]]:
+        """Get the monitors deployed to a device.
+
+        Args:
+            device_uuid (str): UUID of the device.
+            network (str): Network the device belongs to.
+
+        Returns:
+            List[Dict[str, Any]]: The monitors, each with ``monitorId``, ``monitorName`` and
+            ``setId``. The list is empty only when the server says the device has none,
+            which it also says for a device that does not exist.
+
+        Raises:
+            ValueError: If the server's answer is not a list. Callers check this list before
+                deploying, so a failed read must not look like no monitors.
+        """
+        response = self.call("Collection.getMonitorsForHost", uuid=device_uuid, network=network)
+        monitors = response.get("result") if isinstance(response, dict) else None
+        if not isinstance(monitors, list):
+            raise ValueError(f"Collection.getMonitorsForHost did not return a list for device {device_uuid}")
+        return monitors
+
     def validate_monitor_sets_against_device(
         self, monitor_set_ids: List[int], host_queries: List[str]
     ) -> Dict[str, Any]:

{lvi_api_client-0.2.0 → lvi_api_client-0.2.2}/src/lvi_api_client.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lvi-api-client
-Version: 0.2.0
+Version: 0.2.2
 Summary: LogicVein API Client Library
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown

{lvi_api_client-0.2.0 → lvi_api_client-0.2.2}/tests/test_server_request_shapes.py

@@ -281,6 +281,144 @@ XML = (
 SAVED = {"Compliance.saveRuleSet": {"ruleSetId": 5, "ruleSetName": "rs1"}}
 
 
+class TestTriggers:
+    TRIGGER = {
+        "triggerName": "t1",
+        "paused": True,
+        "cronExpression": "0 2 * * *",
+        "timeZone": "Etc/GMT",
+        "filterName": "",
+        "jobId": 7,
+    }
+
+    def save(self, connect, **extra):
+        client, server = connect({"Scheduler.saveTrigger": {"triggerId": 3}})
+        saved = client.save_trigger(job_id=7, trigger_name="t1", cron_expression="0 2 * * *", paused=True, **extra)
+        return saved, server.sent("Scheduler.saveTrigger")
+
+    def test_a_save_without_an_id_sends_none_so_the_server_adds_one(self, connect):
+        saved, sent = self.save(connect)
+        assert saved == {"triggerId": 3}
+        assert sent == {"triggerData": self.TRIGGER}
+
+    def test_a_save_with_an_id_sends_it_so_the_server_updates_that_trigger(self, connect):
+        _, sent = self.save(connect, trigger_id=3)
+        assert sent == {"triggerData": {**self.TRIGGER, "triggerId": 3}}
+
+    def test_triggers_of_a_job_are_read_by_job_id(self, connect):
+        rows = [{"triggerId": 3, "triggerName": "t1"}]
+        client, server = connect({"Scheduler.getTriggersOfJob": rows})
+        assert client.get_job_triggers(7) == rows
+        assert server.sent("Scheduler.getTriggersOfJob") == {"jobId": 7}
+
+    def test_a_job_with_no_triggers_gives_an_empty_list(self, connect):
+        client, _ = connect({"Scheduler.getTriggersOfJob": []})
+        assert client.get_job_triggers(7) == []
+
+    @pytest.mark.parametrize("answer", [None, {"result": None}, {}, "<html>error</html>"])
+    def test_an_answer_that_is_not_a_list_raises_rather_than_reading_as_no_triggers(self, connect, answer):
+        client, _ = connect()
+        with patch.object(client, "call", return_value=answer):
+            with pytest.raises(ValueError):
+                client.get_job_triggers(7)
+
+    @pytest.mark.parametrize("answer", [True, False])
+    def test_a_delete_is_by_trigger_id_and_returns_the_answer(self, connect, answer):
+        client, server = connect({"Scheduler.deleteTrigger": answer})
+        assert client.delete_trigger(3) is answer
+        assert server.sent("Scheduler.deleteTrigger") == {"triggerId": 3}
+
+
+class TestMonitorSets:
+    SET = {"setId": 5, "setName": "s1", "smartSet": False, "managedNetworks": ["n1"]}
+
+    def test_a_new_set_is_saved_with_an_id_of_minus_one(self, connect):
+        client, server = connect({"Collection.saveMonitorSet": self.SET})
+        assert client.create_monitor_set("s1", ["n1"]) == self.SET
+        assert server.sent("Collection.saveMonitorSet") == {
+            "monitorSet": {"setId": -1, "setName": "s1", "smartSet": False, "managedNetworks": ["n1"]}
+        }
+
+    def test_a_new_smart_set_says_so(self, connect):
+        client, server = connect({"Collection.saveMonitorSet": self.SET})
+        client.create_monitor_set("s1", ["n1"], smart_set=True)
+        assert server.sent("Collection.saveMonitorSet")["monitorSet"]["smartSet"] is True
+
+    def test_a_new_set_with_no_networks_sends_nothing(self, connect):
+        client, server = connect()
+        with pytest.raises(ValueError):
+            client.create_monitor_set("s1", [])
+        assert server.requests == []
+
+    def test_an_update_keeps_what_it_is_not_given(self, connect):
+        client, server = connect({"Collection.getMonitorSet": self.SET, "Collection.saveMonitorSet": self.SET})
+        client.update_monitor_set(5, set_name="s2")
+        assert server.sent("Collection.saveMonitorSet") == {"monitorSet": {**self.SET, "setName": "s2"}}
+
+    def test_an_update_can_clear_smart_set(self, connect):
+        stored = {**self.SET, "smartSet": True}
+        client, server = connect({"Collection.getMonitorSet": stored, "Collection.saveMonitorSet": self.SET})
+        client.update_monitor_set(5, smart_set=False)
+        assert server.sent("Collection.saveMonitorSet")["monitorSet"]["smartSet"] is False
+
+    @pytest.mark.parametrize(
+        "stored, args",
+        [
+            pytest.param(None, {"set_name": "s2"}, id="no such set"),
+            pytest.param(SET, {"managed_networks": []}, id="no networks"),
+        ],
+    )
+    def test_an_update_that_cannot_apply_saves_nothing(self, connect, stored, args):
+        client, server = connect({"Collection.getMonitorSet": stored})
+        with pytest.raises(ValueError):
+            client.update_monitor_set(5, **args)
+        assert "Collection.saveMonitorSet" not in [name for name, _ in server.requests]
+
+    @pytest.mark.parametrize("answer, expected", [(None, True), (False, False)])
+    def test_a_delete_is_by_set_ids_and_null_is_success(self, connect, answer, expected):
+        client, server = connect({"Collection.deleteMonitorSets": answer})
+        assert client.delete_monitor_sets([5, 6]) is expected
+        assert server.sent("Collection.deleteMonitorSets") == {"setIds": [5, 6]}
+
+    @pytest.mark.parametrize("answer", [True, False])
+    def test_a_name_check_sends_its_scope_and_returns_the_answer(self, connect, answer):
+        client, server = connect({"Collection.isMonitorSetNameUnique": answer})
+        assert client.is_monitor_set_name_unique("s1", ["n1"], ignore_set_id=5) is answer
+        assert server.sent("Collection.isMonitorSetNameUnique") == {
+            "setName": "s1",
+            "managedNetworks": ["n1"],
+            "ignoreSetId": 5,
+        }
+
+    def test_a_name_check_with_no_answer_raises_rather_than_reading_as_taken(self, connect):
+        client, _ = connect({"Collection.isMonitorSetNameUnique": None})
+        with pytest.raises(ValueError):
+            client.is_monitor_set_name_unique("s1", ["n1"])
+
+    def test_a_monitor_is_saved_as_a_whole_record(self, connect):
+        monitor = {"monitorId": 3, "monitorName": "m1", "setId": 5, "json": {"port": 22}}
+        client, server = connect({"Collection.saveMonitor": monitor})
+        assert client.save_monitor(monitor) == monitor
+        assert server.sent("Collection.saveMonitor") == {"monitor": monitor}
+
+    def test_a_devices_monitors_are_read_by_uuid_and_network(self, connect):
+        rows = [{"monitorId": 3, "monitorName": "m1", "setId": 5}]
+        client, server = connect({"Collection.getMonitorsForHost": rows})
+        assert client.get_monitors_for_host("u1", "n1") == rows
+        assert server.sent("Collection.getMonitorsForHost") == {"uuid": "u1", "network": "n1"}
+
+    def test_a_device_with_no_monitors_gives_an_empty_list(self, connect):
+        client, _ = connect({"Collection.getMonitorsForHost": []})
+        assert client.get_monitors_for_host("u1", "n1") == []
+
+    @pytest.mark.parametrize("answer", [None, {"result": None}, {}, "<html>error</html>"])
+    def test_an_answer_that_is_not_a_list_raises_rather_than_reading_as_no_monitors(self, connect, answer):
+        client, _ = connect()
+        with patch.object(client, "call", return_value=answer):
+            with pytest.raises(ValueError):
+                client.get_monitors_for_host("u1", "n1")
+
+
 class TestCreateRuleSet:
     def test_an_agreeing_document_is_sent_unchanged(self, connect):
         client, server = connect(SAVED)

lvi_api_client-0.2.0/VERSION

@@ -1 +0,0 @@
-0.2.0