Add option for detached HUP on start_os_update

This will call the v2 actions endpoint for resinhup
which runs a detached version of HUP that increases
HUP reliability on slow networks but will offer
no status updates such as in_progress.

Change-type: minor

DOCUMENTATION.md

@@ -1976,6 +1976,9 @@ Start an OS update on a device.
         Unsupported (unpublished) version will result in rejection.
         The version **must** be the exact version number, a "prod" variant
         and greater than the one running on the device.
+    run_detached (Optional[bool]): run the update in detached mode.
+        Default behaviour is run_detached=False but is DEPRECATED and will be
+        removed in a future release. Use run_detached=True for more reliable updates.
 
 #### Returns:
     HUPStatusResponse: action response.
@@ -1984,6 +1987,7 @@ Start an OS update on a device.
 ```python
 >>> balena.models.device.start_os_update('b6070f4', '2.29.2+rev1.prod')
 >>> balena.models.device.start_os_update('b6070f4', '2.89.0+rev1')
+>>> balena.models.device.start_os_update('b6070f4', '2.89.0+rev1', run_detached=True)
 ```
 
 <a name="device.start_service"></a>

balena/models/device.py

@@ -1727,7 +1727,13 @@ def set_supervisor_release(
             }
         )
 
-    def start_os_update(self, uuid_or_id: Union[str, int], target_os_version: str) -> HUPStatusResponse:
+    def start_os_update(
+        self,
+        uuid_or_id: Union[str, int],
+        target_os_version: str,
+        *,  # Force keyword arguments after this point
+        run_detached: Optional[bool] = False
+    ) -> HUPStatusResponse:
         """
         Start an OS update on a device.
 
@@ -1737,13 +1743,17 @@ def start_os_update(self, uuid_or_id: Union[str, int], target_os_version: str) -
                 Unsupported (unpublished) version will result in rejection.
                 The version **must** be the exact version number, a "prod" variant
                 and greater than the one running on the device.
+            run_detached (Optional[bool]): run the update in detached mode.
+                Default behaviour is run_detached=False but is DEPRECATED and will be
+                removed in a future release. Use run_detached=True for more reliable updates.
 
         Returns:
             HUPStatusResponse: action response.
 
         Examples:
             >>> balena.models.device.start_os_update('b6070f4', '2.29.2+rev1.prod')
             >>> balena.models.device.start_os_update('b6070f4', '2.89.0+rev1')
+            >>> balena.models.device.start_os_update('b6070f4', '2.89.0+rev1', run_detached=True)
         """
 
         if target_os_version is None or uuid_or_id is None:
@@ -1766,7 +1776,7 @@ def start_os_update(self, uuid_or_id: Union[str, int], target_os_version: str) -
         data = {"parameters": {"target_version": target_os_version}}
 
         url_base = self.__config.get_all()["deviceUrlsBase"]
-        action_api_version = self.__settings.get("device_actions_endpoint_version")
+        action_api_version = "v2" if run_detached is True else self.__settings.get("device_actions_endpoint_version")
 
         return request(
             method="POST",
@@ -1776,6 +1786,12 @@ def start_os_update(self, uuid_or_id: Union[str, int], target_os_version: str) -
             endpoint=f"https://actions.{url_base}/{action_api_version}/",
         )
 
+    @deprecated(
+        """
+        This will be removed in a future major release. This will no longer return a
+        useful status for runDetached=true updates.
+        """
+    )
     def get_os_update_status(self, uuid_or_id: Union[str, int]) -> HUPStatusResponse:
         """
         Get the OS update status of a device.