UniFi OS updates (#267)

* Add list active devices endpoint

* Add list clients history endpoint

* Add OS console update endpoints

Author: Jacobtims

src/Client.php

@@ -14,6 +14,7 @@
 use UniFi_API\Exceptions\LoginFailedException;
 use UniFi_API\Exceptions\LoginRequiredException;
 use UniFi_API\Exceptions\MethodDeprecatedException;
+use UniFi_API\Exceptions\NotAnOsConsoleException;
 
 /**
  * The UniFi API client class.
@@ -3261,6 +3262,40 @@ public function check_controller_update()
         return $this->fetch_results('/api/s/' . $this->site . '/stat/fwupdate/latest-version');
     }
 
+    /**
+     * Get the recent firmware update for an UniFi-OS console
+     *
+     * @return array|bool returns an array with a single object containing details of the current known latest
+     *                     UniFi OS version info on success, else returns false
+     * @throws Exception
+     */
+    public function get_update_os_console()
+    {
+        if (!$this->is_unifi_os) {
+            throw new NotAnOsConsoleException();
+        }
+
+        return $this->fetch_results('/api/firmware/update', null, false, true, false);
+    }
+
+    /**
+     * Update the OS for an UniFi-OS console
+     *
+     * @note triggers an UniFi OS Update in Control Plane > Updates > UniFi OS
+     * @return bool true upon success
+     * @throws Exception
+     */
+    public function update_os_console(): bool
+    {
+        if (!$this->is_unifi_os) {
+            throw new NotAnOsConsoleException();
+        }
+
+        $payload = ['persistFullData' => true];
+
+        return $this->fetch_results_boolean('/api/firmware/update', $payload, true, false);
+    }
+
     /**
      * Check firmware update.
      *
@@ -4122,19 +4157,23 @@ protected function fetch_results(
         string $path,
                $payload = null,
         bool   $boolean = false,
-        bool   $login_required = true
+        bool   $login_required = true,
+        bool   $prefix_path = true
     )
     {
         /** Guard clause to check if logged in when needed. */
         if ($login_required && !$this->is_logged_in) {
             throw new LoginRequiredException();
         }
 
-        $this->last_results_raw = $this->exec_curl($path, $payload);
+        $this->last_results_raw = $this->exec_curl($path, $payload, $prefix_path);
 
         if (is_string($this->last_results_raw)) {
             $response = json_decode($this->last_results_raw);
-            $this->get_json_last_error();
+
+            if (!empty($this->last_results_raw)) {
+                $this->get_json_last_error();
+            }
 
             if (isset($response->meta->rc)) {
                 if ($response->meta->rc === 'ok') {
@@ -4174,6 +4213,24 @@ protected function fetch_results(
 
                 return $response;
             }
+
+            /** Deal with a responses from an UniFi OS console */
+            if (strpos($path, '/api/') === 0) {
+                if (isset($response->code)) {
+                    $this->last_error_message = 'An unknown error was returned by an UniFi OS endpoint.';
+                    if (isset($response->message)) {
+                        $this->last_error_message = $response->message;
+                    }
+
+                    throw new Exception('Error code: ' . $response->code . ', message: ' . $this->last_error_message);
+                }
+
+                if (is_object($response) && !$boolean) {
+                    return [$response];
+                }
+
+                return true;
+            }
         }
 
         return false;
@@ -4189,9 +4246,14 @@ protected function fetch_results(
      * @return bool [description]
      * @throws Exception
      */
-    protected function fetch_results_boolean(string $path, $payload = null, bool $login_required = true): bool
+    protected function fetch_results_boolean(
+        string $path,
+               $payload = null,
+        bool   $login_required = true,
+        bool   $prefix_path = true
+    ): bool
     {
-        return $this->fetch_results($path, $payload, true, $login_required);
+        return $this->fetch_results($path, $payload, true, $login_required, $prefix_path);
     }
 
     /**
@@ -4381,15 +4443,15 @@ protected function response_header_callback($ch, string $header_line): int
      * @return bool|string response returned by the controller API
      * @throws CurlGeneralErrorException|CurlTimeoutException|InvalidCurlMethodException|LoginFailedException
      */
-    protected function exec_curl(string $path, $payload = null)
+    protected function exec_curl(string $path, $payload = null, $prefix_path = true)
     {
         if (!in_array($this->curl_method, self::CURL_METHODS_ALLOWED)) {
             throw new InvalidCurlMethodException();
         }
 
         $url = $this->baseurl . $path;
 
-        if ($this->is_unifi_os) {
+        if ($this->is_unifi_os && $prefix_path) {
             $url = $this->baseurl . '/proxy/network' . $path;
         }
 

src/Exceptions/NotAnOsConsoleException.php

@@ -0,0 +1,13 @@
+<?php
+
+namespace UniFi_API\Exceptions;
+
+use Exception;
+
+class NotAnOsConsoleException extends Exception
+{
+    public function __construct()
+    {
+        parent::__construct('This console is not an UniFi OS console.');
+    }
+}