From 13cb313cd994624b2b9a9d01321d6d2061044b61 Mon Sep 17 00:00:00 2001
From: Jacob Timmerman <75219092+Jacobtims@users.noreply.github.com>
Date: Mon, 3 Mar 2025 14:14:34 +0100
Subject: [PATCH] Client devices history (#266)

* Add list active devices endpoint

* Add list clients history endpoint
---
 src/Client.php | 39 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/src/Client.php b/src/Client.php
index ba73429..5becd9f 100755
--- a/src/Client.php
+++ b/src/Client.php
@@ -1091,6 +1091,45 @@ class Client
         return $this->fetch_results('/api/s/' . $this->site . '/stat/sta/' . $mac);
     }
 
+    /**
+     * Fetch active client devices
+     *
+     * @param bool $includeTrafficUsage include the traffic usage of the client devices in the response
+     * @param bool $includeUnifiDevices include UniFi devices in the response
+     * @return array|bool returns an array of active client device objects, false upon error
+     * @throws Exception
+     */
+    public function list_active_clients(bool $includeTrafficUsage = true, bool $includeUnifiDevices = true)
+    {
+        $query = http_build_query([
+            'includeTrafficUsage' => $includeTrafficUsage,
+            'includeUnifiDevices' => $includeUnifiDevices,
+        ]);
+
+        return $this->fetch_results('/v2/api/site/' . $this->site . '/clients/active?' . $query);
+    }
+
+    /**
+     * Fetch client devices history (offline client devices)
+     *
+     * @param bool $onlyNonBlocked include non-blocked client devices in the response
+     * @param bool $includeUnifiDevices include UniFi devices in the response
+     * @param int $withinHours the number of hours a device has been offline to be included in the response
+     *                         (0 = no limit)
+     * @return array|bool returns an array of (offline) client device objects, false upon error
+     * @throws Exception
+     */
+    public function list_clients_history(bool $onlyNonBlocked = true, bool $includeUnifiDevices = true, int $withinHours = 0)
+    {
+        $query = http_build_query([
+            'onlyNonBlocked' => $onlyNonBlocked,
+            'includeUnifiDevices' => $includeUnifiDevices,
+            'withinHours' => $withinHours,
+        ]);
+
+        return $this->fetch_results('/v2/api/site/' . $this->site . '/clients/history?' . $query);
+    }
+
     /**
      * Fetch details for a single client device
      *