python-unifi-client 1.2.7__tar.gz → 1.2.8__tar.gz

{python_unifi_client-1.2.7 → python_unifi_client-1.2.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python_unifi_client
-Version: 1.2.7
+Version: 1.2.8
 Home-page: https://github.com/compdat-llc/unifi-client-python
 Author: Michael Lapinski
 Author-email: michaellapinski787@gmail.com

{python_unifi_client-1.2.7 → python_unifi_client-1.2.8}/python_unifi_client/client.py

@@ -77,7 +77,7 @@ class Client:
     CURL_METHODS_ALLOWED = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH']
     DEFAULT_CURL_METHOD = 'GET'
 
-    def __init__(self, user, password, baseurl='https://32.218.193.188', site='default', version='8.0.28', ssl_verify=False, unificookie_name='unificookie', debug=False):
+    def __init__(self, user, password, baseurl='https://127.0.0.1', site='default', version='8.0.28', ssl_verify=False, unificookie_name='unificookie', debug=False):
         # Initial setup mirrors PHP constructor
         self._check_curl()
         self._check_base_url(baseurl)
@@ -106,6 +106,29 @@ class Client:
         self._cookies_created_at = 0
         self._exec_retries = 0
         self.debug = debug
+        self._firmware_version = None  # None = unknown, 'v1' or 'v2' (auto-detected)
+
+        self.default_site_stats_attribs = [
+            'bytes',
+            'wan-tx_bytes',
+            'wan-rx_bytes',
+            'wlan_bytes',
+            'num_sta',
+            'lan-num_sta',
+            'wlan-num_sta',
+            'time',
+        ]
+
+        self.default_ap_stats_attribs = [
+            'bytes',
+            'wan-tx_bytes',
+            'wan-rx_bytes',
+            'wlan_bytes',
+            'num_sta',
+            'lan-num_sta',
+            'wlan-num_sta',
+            'time',
+        ]
 
         if self.debug:
             logging.basicConfig(level=logging.DEBUG)
@@ -144,7 +167,7 @@ class Client:
             return True
         return False
 
-    def login(self) -> bool:
+    def login(self, return_token:bool=False) -> bool:
         # Skip if already logged in via valid cookie
         self._verify_ssl_cert = False
 
@@ -214,6 +237,8 @@ class Client:
                 self._session.headers.update({'x-csrf-token': token,
                                               'Referer': f"{self._baseurl}/login"})
             self._is_loggedin = True
+            if return_token:
+                return True, token
             return True
 
         raise LoginFailedException(f"HTTP response: {resp2.status_code}")
@@ -258,10 +283,10 @@ class Client:
     # The following methods are directly converted from the PHP class to Python, preserving functionality and parameters.
 
     def get_site_stats(self):
-        return self.fetch_results(f"/api/s/{self._site}/stat/sysinfo")
+        return self.fetch_results(f"/api/s/{self._site}/stat/sysinfo", proxy_type='network')
 
     def get_clients(self):
-        return self.fetch_results(f"/api/s/{self._site}/stat/sta", prefix_path=True)
+        return self.fetch_results(f"/api/s/{self._site}/stat/sta", proxy_type='network')
 
     def block_client(self, mac):
         return self.fetch_results(f"/api/s/{self._site}/cmd/stamgr", method='POST', payload={'cmd': 'block-sta', 'mac': mac})
@@ -361,14 +386,15 @@ class Client:
 
             return self.fetch_results(
                 f"/api/s/{self._site}/rest/user",
-                payload=payload
+                payload=payload,
+                proxy_type='network'
                 )
 
     def delete_user(self, user_id: str):
         """
         Remove a user by ID
         """
-        return self.fetch_results(f"/api/s/{self._site}/rest/user/{user_id}",)
+        return self.fetch_results(f"/api/s/{self._site}/rest/user/{user_id}", proxy_type='network')
 
     def get_user(self, user_id: str):
         """
@@ -377,7 +403,7 @@ class Client:
         return self.fetch_results(f"/api/s/{self._site}/rest/user/{user_id}")
 
     def get_client_by_mac(self, mac: str):
-        return self.fetch_results(f"/api/s/{self._site}/stat/user/{mac}", prefix_path=True)
+        return self.fetch_results(f"/api/s/{self._site}/stat/user/{mac}", proxy_type='network')
 
     def update_user(self, user_id: str, name: str = None, note: str = None, is_guest: bool = None, is_wired: bool = None):
         """
@@ -396,7 +422,8 @@ class Client:
 
         return self.fetch_results(
             f"/api/s/{self._site}/rest/user/{user_id}",
-            payload=payload
+            payload=payload,
+            proxy_type='network'
         )
 
     def forget_user(self, mac: str):
@@ -461,7 +488,7 @@ class Client:
 
 
     def list_sites(self):
-        return self.fetch_results("/api/self/sites")
+        return self.fetch_results("/api/self/sites", proxy_type='network')
 
     def list_apgroups(self):
         """
@@ -498,11 +525,11 @@ class Client:
     def list_dashboard(self, five_minutes: bool = False):
         """Fetch dashboard metrics, 5-minute scale if requested."""
         suffix = '?scale=5minutes' if five_minutes else ''
-        return self.fetch_results(f"/api/s/{self._site}/stat/dashboard{suffix}")
+        return self.fetch_results(f"/api/s/{self._site}/stat/dashboard{suffix}", proxy_type='network')
 
     def list_users(self):
         """Fetch known client devices."""
-        return self.fetch_results(f"/api/s/{self._site}/list/user", prefix_path=True)
+        return self.fetch_results(f"/api/s/{self._site}/list/user", proxy_type='network')
 
     def list_tags(self):
         """Fetch all device tags (REST)."""
@@ -532,7 +559,7 @@ class Client:
         return self.fetch_results(f"/api/s/{self._site}/rest/rogueknown")
 
     def get_site(self, site_id) -> str:
-        return self.fetch_results(f"/api/s/{site_id}/self")
+        return self.fetch_results(f"/api/s/{site_id}/self", proxy_type='network')
 
     def create_site(self, description: str):
         """
@@ -626,12 +653,12 @@ class Client:
     def get_admins(self):
         """Fetch administrators for current site"""
         payload = {'cmd': 'get-admins'}
-        return self.fetch_results(f"/api/s/{self._site}/cmd/sitemgr", payload=payload, prefix_path=True)
+        return self.fetch_results(f"/api/s/{self._site}/cmd/sitemgr", payload=payload, proxy_type='network')
 
     def list_all_admins(self):
         """Fetch all administrators"""
         payload = {'cmd': 'get-all-admins'}
-        return self.fetch_results(f"/api/s/{self._site}/cmd/sitemgr", payload=payload)
+        return self.fetch_results(f"/api/s/{self._site}/cmd/sitemgr", payload=payload, proxy_type='network')
 
     def invite_admin(self, name: str, email: str, enable_sso: bool = True, readonly: bool = False,
                      device_adopt: bool = False, device_restart: bool = False) -> bool:
@@ -651,7 +678,7 @@ class Client:
             payload['permissions'].append('API_DEVICE_ADOPT')
         if device_restart:
             payload['permissions'].append('API_DEVICE_RESTART')
-        return self.fetch_results_boolean(f"/api/s/{self._site}/cmd/sitemgr", payload=payload)
+        return self.fetch_results_boolean(f"/api/s/{self._site}/cmd/sitemgr", payload=payload, proxy_type='network')
 
     def assign_existing_admin(self, admin_id: str, readonly: bool = False,
                               device_adopt: bool = False, device_restart: bool = False) -> bool:
@@ -683,12 +710,12 @@ class Client:
     def revoke_admin(self, admin_id: str) -> bool:
         """Revoke an admin's access to this site"""
         payload = {'cmd': 'revoke-admin', 'admin': admin_id.strip()}
-        return self.fetch_results_boolean(f"/api/s/{self._site}/cmd/sitemgr", payload=payload)
+        return self.fetch_results_boolean(f"/api/s/{self._site}/cmd/sitemgr", payload=payload, proxy_type='network')
 
     def delete_admin(self, admin_id: str) -> bool:
         """Delete an admin user"""
         payload = {'cmd': 'delete-admin', 'admin': admin_id.strip()}
-        return self.fetch_results_boolean(f"/api/s/{self._site}/cmd/sitemgr", payload=payload)
+        return self.fetch_results_boolean(f"/api/s/{self._site}/cmd/sitemgr", payload=payload,proxy_type='network')
 
     def list_wlan_groups(self):
         """Fetch WLAN groups"""
@@ -703,7 +730,8 @@ class Client:
         return self.fetch_results_boolean(
             '/status',
             payload=None,
-            login_required=self._unifi_os
+            login_required=self._unifi_os,
+            proxy_type='network'
         )
 
     def stat_full_status(self):
@@ -712,7 +740,8 @@ class Client:
         self.fetch_results_boolean(
             '/status',
             payload=None,
-            login_required=self._unifi_os
+            login_required=self._unifi_os,
+            proxy_type='network'
         )
         # Decode and return the last raw JSON results
         raw = self.get_last_results_raw(return_json=False)
@@ -741,11 +770,222 @@ class Client:
         return self.fetch_results('/api/self')
 
     def get_devices(self):
-        return self.fetch_results(f"/api/s/{self._site}/stat/device", login_required=True, prefix_path=True)
+        return self.fetch_results(f"/api/s/{self._site}/stat/device", login_required=True, proxy_type='network')
 
     def get_device(self, device_id):
-        return self.fetch_results(f"/api/s/{self._site}/stat/device/{device_id}", prefix_path=True)
+        return self.fetch_results(f"/api/s/{self._site}/stat/device/{device_id}", proxy_type='network')
+
+    # === Health & Status Methods ===
+
+    def list_health(self):
+        """Get site health status including WAN, LAN, WLAN subsystems.
+
+        Returns:
+            list: Health data for each subsystem with status and details
+        """
+        return self.fetch_results(f"/api/s/{self._site}/stat/health", proxy_type='network')
     
+    def get_device_history(self, mac: str, is_client:bool, limit: int = 50):
+        """Fetch device activity/event history from system logs.
+
+        Args:
+            mac: Device MAC address
+            is_client: Determines the scope, 'CLIENTS or DEVICE'
+            limit: Maximum number of entries to return
+
+        Returns:
+            list: Activity log entries for the device
+        """
+        scope = 'CLIENTS' if is_client else 'DEVICE'
+
+        self._curl_method = 'GET'
+        return self.fetch_results(
+            f"/v2/api/site/default/system-log/device/{mac}?mac={mac}&scope={scope}&limit={limit}", 
+            proxy_type='network'
+        )
+
+    # === Firewall Methods ===
+
+    def list_firewall_rules(self):
+        """List all firewall rules for the site.
+
+        Returns:
+            list: Firewall rule configurations
+        """
+        return self.fetch_results(f"/api/s/{self._site}/rest/firewallrule", proxy_type='network')
+
+    def create_firewall_rule(self, payload: dict):
+        """Create a new firewall rule.
+
+        Args:
+            payload: Firewall rule configuration dict
+
+        Returns:
+            list: Created firewall rule data
+        """
+        self._curl_method = 'POST'
+        return self.fetch_results(f"/api/s/{self._site}/rest/firewallrule", payload=payload, proxy_type='network')
+
+    def delete_firewall_rule(self, rule_id: str):
+        """Delete a firewall rule by ID.
+
+        Args:
+            rule_id: The _id of the firewall rule to delete
+
+        Returns:
+            bool: True if successful
+        """
+        self._curl_method = 'DELETE'
+        return self.fetch_results_boolean(f"/api/s/{self._site}/rest/firewallrule/{rule_id}", proxy_type='network')
+
+    # === UniFi OS System Methods (no prefix_path - direct /api/ endpoints) ===
+
+    def get_system_config(self):
+        """Get UniFi OS system configuration.
+
+        Returns:
+            list: System configuration including SSH, update settings
+        """
+        return self.fetch_results("/api/system", proxy_type=None)
+
+    def set_system_config(self, payload: dict):
+        """Update UniFi OS system configuration.
+
+        Args:
+            payload: System config updates (e.g., {'ssh': {'enabled': True}})
+
+        Returns:
+            list: Updated system configuration
+        """
+        self._curl_method = 'PATCH'
+        return self.fetch_results("/api/system", payload=payload, proxy_type=None)
+
+    def set_ssh_password(self, password: str):
+        """Set the SSH password for UniFi OS.
+
+        Args:
+            password: New SSH password
+
+        Returns:
+            list: Response from password set operation
+        """
+        self._curl_method = 'POST'
+        return self.fetch_results("/api/system/ssh/setpassword", payload={'password': password}, proxy_type=None)
+
+    def get_notification_settings(self):
+        """Get UniFi OS notification settings.
+
+        Returns:
+            list: Notification configuration
+        """
+        return self.fetch_results("/api/notifications/settings", proxy_type=None)
+
+    def set_notification_settings(self, payload: dict):
+        """Update UniFi OS notification settings.
+
+        Args:
+            payload: Notification settings to update
+
+        Returns:
+            list: Updated notification settings
+        """
+        self._curl_method = 'PUT'
+        return self.fetch_results("/api/notifications/settings", payload=payload, proxy_type=None)
+
+    def download_backup(self, filename: str = None):
+        """Download UniFi OS system backup.
+
+        Args:
+            filename: Optional filename filter
+
+        Returns:
+            bytes: Backup file content (requires special handling for binary data)
+        """
+        params = {}
+        if filename:
+            params['filename'] = filename
+        self._curl_method = 'GET'
+        # Note: This returns raw bytes, not JSON - may need special handling
+        return self.exec_curl("/api/backup/download", payload=params if params else None, proxy_type=None)
+
+    # === User Management Methods (always /proxy/users/ - no v1/v2 distinction) ===
+
+    def list_site_users(self):
+        """Get all users/admins for the site.
+
+        Returns:
+            list: User accounts with roles and permissions
+        """
+        return self.fetch_results("/api/v2/users", proxy_type='users')
+
+    def invite_user(self, email: str, role: str = 'admin', permissions: dict = None):
+        """Invite a user to the UniFi site.
+
+        Args:
+            email: User's email address
+            role: User role (e.g., 'admin', 'viewer')
+            permissions: Optional permission overrides
+
+        Returns:
+            list: Invitation result
+        """
+        payload = {
+            'email': email,
+            'role': role
+        }
+        if permissions:
+            payload['permissions'] = permissions
+        self._curl_method = 'POST'
+        return self.fetch_results("/api/v2/users/invite_add", payload=payload, proxy_type='users')
+
+    def deactivate_user(self, user_id: str):
+        """Deactivate a user account.
+
+        Args:
+            user_id: User's unique identifier
+
+        Returns:
+            list: Deactivation result
+        """
+        self._curl_method = 'PUT'
+        return self.fetch_results(f"/api/v2/user/{user_id}/deactivate?isULP=1", proxy_type='users')
+
+    def activate_user(self, user_id: str):
+        """Activate a deactivated user account.
+
+        Args:
+            user_id: User's unique identifier
+
+        Returns:
+            list: Activation result
+        """
+        self._curl_method = 'PUT'
+        return self.fetch_results(f"/api/v2/user/{user_id}/active?isULP=1", proxy_type='users')
+
+    def remove_user(self, user_id: str):
+        """Permanently remove a user account.
+
+        Args:
+            user_id: User's unique identifier
+
+        Returns:
+            list: Removal result
+        """
+        self._curl_method = 'DELETE'
+        return self.fetch_results(f"/api/v2/user/{user_id}", proxy_type='users')
+
+    def create_custom_role(self, payload: dict):
+        """Create a custom permission role.
+
+        Args:
+            payload: Role configuration with permissions
+
+        Returns:
+            list: Created role data
+        """
+        self._curl_method = 'POST'
+        return self.fetch_results("/api/v2/custom_role", payload=payload, proxy_type='users')
+
     def get_wlan(self, wlan_id: str):
         """
         Retrieve WLAN configuration by ID
@@ -911,7 +1151,7 @@ class Client:
     def list_clients(self, mac: str = None):
         """Fetch online client devices, or single device if MAC provided."""
         path_mac = mac.lower().strip() if isinstance(mac, str) else ''
-        return self.fetch_results(f"/api/s/{self._site}/stat/sta/{path_mac}", prefix_path=True)
+        return self.fetch_results(f"/api/s/{self._site}/stat/sta/{path_mac}", proxy_type='network')
 
     def list_active_clients(self, include_traffic_usage: bool = True, include_unifi_devices: bool = True):
         """Fetch active client devices, with optional traffic and UniFi device inclusion."""
@@ -919,7 +1159,7 @@ class Client:
             'include_traffic_usage': include_traffic_usage,
             'include_unifi_devices': include_unifi_devices,
         })
-        return self.fetch_results(f"/v2/api/site/{self._site}/clients/active?{query}", prefix_path=True)
+        return self.fetch_results(f"/v2/api/site/{self._site}/clients/active?{query}", proxy_type='network')
 
     def list_clients_history(self, only_non_blocked: bool = True, include_unifi_devices: bool = True, within_hours: int = 0):
         """Fetch offline client device history."""
@@ -1003,7 +1243,7 @@ class Client:
         """
         List all client sessions (stat/session) for the site
         """
-        return self.fetch_results(f"/api/s/{self._site}/stat/session")
+        return self.fetch_results(f"/api/s/{self._site}/stat/session", proxy_type='network')
 
     def stat_hourly_site(self, start: int = None, end: int = None, attribs: list = None):
         """
@@ -1035,7 +1275,7 @@ class Client:
         start = start or end - 12 * 3600 * 1000
         attrs = attribs or self.default_site_stats_attribs
         payload = {'attrs': ['time'] + attrs, 'start': start, 'end': end}
-        return self.fetch_results(f"/api/s/{self._site}/stat/report/5minutes.site", payload=payload)
+        return self.fetch_results(f"/api/s/{self._site}/stat/report/5minutes.site", payload=payload, proxy_type='network')
 
     def stat_5minutes_aps(self, start: int = None, end: int = None, mac: str = None, attribs: list = None):
         """Fetch 5-minute AP stats (defaults to past 12 hours)."""
@@ -1045,7 +1285,7 @@ class Client:
         payload = {'attrs': ['time'] + attrs, 'start': start, 'end': end}
         if mac:
             payload['mac'] = mac.lower()
-        return self.fetch_results(f"/api/s/{self._site}/stat/report/5minutes.ap", payload=payload)
+        return self.fetch_results(f"/api/s/{self._site}/stat/report/5minutes.ap", payload=payload, proxy_type='network')
 
     def stat_hourly_aps(self, start: int = None, end: int = None, mac: str = None, attribs: list = None):
         """Fetch hourly AP stats (defaults to past 7 days)."""
@@ -1126,7 +1366,7 @@ class Client:
         start = start or end - 12 * 3600 * 1000
         attrs = attribs or ['time', 'mem', 'cpu', 'loadavg_5']
         payload = {'attrs': ['time'] + attrs, 'start': start, 'end': end}
-        return self.fetch_results(f"/api/s/{self._site}/stat/report/5minutes.gw", payload=payload)
+        return self.fetch_results(f"/api/s/{self._site}/stat/report/5minutes.gw", payload=payload, proxy_type='network')
 
     def stat_hourly_gateway(self, start: int = None, end: int = None, attribs: list = None):
         """Fetch hourly gateway stats (defaults to past 7 days)."""
@@ -1163,7 +1403,7 @@ class Client:
     def list_backups(self):
         payload = {'cmd': 'list-backups'}
 
-        return self.fetch_results(f"/api/s/{self._site}/cmd/backup", payload=payload, prefix_path=True)
+        return self.fetch_results(f"/api/s/{self._site}/cmd/backup", payload=payload, proxy_type='network')
 
     def get_network(self, network_id: str):
         """
@@ -1201,7 +1441,7 @@ class Client:
         """
         List all port configurations on the site.
         """
-        return self.fetch_results(f"/api/s/{self._site}/list/portconf", prefix_path=True)
+        return self.fetch_results(f"/api/s/{self._site}/list/portconf", proxy_type='network')
 
     def get_portconf(self, portconf_id: str):
         """
@@ -1265,7 +1505,7 @@ class Client:
         end = end if end is not None else int(time.time() * 1000)
         start = start if start is not None else end - (7 * 24 * 3600 * 1000)
         payload = {'mac': mac, 'start': start, 'end': end}
-        return self.fetch_results(f"/api/s/{self._site}/stat/user", payload=payload)
+        return self.fetch_results(f"/api/s/{self._site}/stat/", payload=payload, proxy_type='network')
 
     def stat_all_user(self, start: int = None, end: int = None):
         """
@@ -1455,7 +1695,7 @@ class Client:
         """
         List DPI stats.
         """
-        return self.fetch_results(f"/api/s/{self._site}/stat/dpi")
+        return self.fetch_results(f"/api/s/{self._site}/stat/dpi", proxy_type='network')
 
     def list_dpi_stats_filtered(self, type: str = 'by_cat', cat_filter: list = None):
         """
@@ -1473,7 +1713,7 @@ class Client:
 
     def list_dpi_app_categories(self):
         """Fetch DPI application categories."""
-        return self.fetch_results(f"/api/s/{self._site}/list/dpi/application/categories")
+        return self.fetch_results(f"/api/s/{self._site}/list/dpi/application/categories", proxy_type='network')
 
     def list_dpi_app(self):
         """Fetch DPI applications."""
@@ -1562,7 +1802,7 @@ class Client:
 
         path = f"/v2/api/site/{self._site}/system-log/{class_}"
 
-        return self.fetch_results(path, payload=payload, prefix_path=True)
+        return self.fetch_results(path, payload=payload, proxy_type='network')
 
     def delete_radius_account(self, account_id: str) -> bool:
         """Delete a Radius user account"""
@@ -1608,14 +1848,11 @@ class Client:
         }
         return self.fetch_results(f"/api/s/{self._site}/stat/report/archive.speedtest", payload=payload)
 
-    def list_health(self):
-        return self.fetch_results(f"/api/s/{self._site}/stat/heatlh")
-
     def stat_user_devices(self):
         """
         Retrieve statistics on user devices.
         """
-        return self.fetch_results(f"/api/s/{self._site}/stat/user/devices")
+        return self.fetch_results(f"/api/s/{self._site}/stat/user/devices", proxy_type='network')
 
     def stat_sites(self):
         """
@@ -1628,10 +1865,10 @@ class Client:
         Fetch UniFi devices, optionally filtered by MAC addresses.
         """
         payload = {'macs': [mac.lower() for mac in macs]}
-        return self.fetch_results(f"/api/s/{self._site}/stat/device", payload=payload, prefix_path=True)
+        return self.fetch_results(f"/api/s/{self._site}/stat/device", payload=payload, proxy_type='network')
 
     def list_devices_basic(self):
-        return self.fetch_results(f"/api/s/{self._site}/stat/device-basic", prefix_path=True)
+        return self.fetch_results(f"/api/s/{self._site}/stat/device-basic", proxy_type='network')
 
     def check_controller_update(self):
         """
@@ -1654,8 +1891,8 @@ class Client:
         if not self._unifi_os:
             raise NotAUnifiOsConsoleException()
         payload = {'persistFullData': True}
-        self.fetch_results(f"/api/s/{self._site}/cmd/firmware/update", payload=payload)
-        return self._last_response_code == 200
+        results = self.fetch_results(f"/api/s/{self._site}/cmd/firmware/update", payload=payload, proxy_type='network')
+        return results
 
 
     ## ---------- Deprecated Methods ---------
@@ -1749,6 +1986,24 @@ class Client:
         self._unifi_os = is_unifi_os
         return True
 
+    def get_firmware_version(self) -> str:
+        """Return detected firmware version ('v1', 'v2', or None if unknown)"""
+        return self._firmware_version
+
+    def set_firmware_version(self, version: str) -> bool:
+        """Manually set firmware version (e.g., from cached Odoo record)
+
+        Args:
+            version: 'v1' for legacy controllers, 'v2' for UniFi OS, or None to reset
+
+        Returns:
+            True if version was set successfully, False if invalid version
+        """
+        if version in ('v1', 'v2', None):
+            self._firmware_version = version
+            return True
+        return False
+
     def set_connection_timeout(self, timeout: int) -> bool:
         """Set connection timeout in seconds"""
         self._connection_timeout = timeout
@@ -1778,8 +2033,8 @@ class Client:
 
     # ----- Protected Helper Methods -----
 
-    def fetch_results_boolean(self, path: str, payload=None, login_required: bool = True, prefix_path: bool = True) -> bool:
-     return self.fetch_results(path, payload, boolean=True, login_required=login_required, prefix_path=prefix_path)
+    def fetch_results_boolean(self, path: str, payload=None, login_required: bool = True, prefix_path: bool = True, auto_fallback: bool = True) -> bool:
+     return self.fetch_results(path, payload, boolean=True, login_required=login_required, prefix_path=prefix_path, auto_fallback=auto_fallback)
 
     def _get_json_last_error(self) -> bool:
         try:
@@ -1814,7 +2069,7 @@ class Client:
     def generate_backup(self, days: int = -1):
         """Generate a controller backup for the past N days."""
         payload = {'cmd': 'backup', 'days': days}
-        result = self.fetch_results(f"/proxy/network/api/s/{self._site}/cmd/backup", payload=payload, prefix_path=False, boolean=False)
+        result = self.fetch_results(f"/api/s/{self._site}/cmd/backup", payload=payload, proxy_type='network', boolean=False)
         print(f"RAW RESULT FROM FETCH_RESULTS(): {result}") if self.debug else None
         return result
 
@@ -1832,7 +2087,7 @@ class Client:
             'cmd': 'restore-backup',
             'file': filename
         }
-        return self.fetch_results(f"/api/s/{self._site}/cmd/backup", payload=payload, prefix_path=True)
+        return self.fetch_results(f"/api/s/{self._site}/cmd/backup", payload=payload, proxy_type='network')
 
     def generate_backup_site(self):
         """Generate a site export backup."""
@@ -2027,54 +2282,9 @@ class Client:
 
     def get_cookies_created_at(self) -> int:
         return self._cookies_created_at
-    
-    def __construct(
-        self,
-        user: str,
-        password: str,
-        baseurl: str = 'https://127.0.0.1:8443',
-        site: str = 'default',
-        version: str = '8.0.28',
-        ssl_verify: bool = False,
-        unificookie_name: str = 'unificookie'
-    ):
-        """
-        PHP constructor conversion: checks and initial assignments.
-        """
-        # Ensure HTTP client available
-        self._check_curl()
-        # Validate base URL and site
-        self._check_base_url(baseurl)
-        self._check_site(site)
-
-        # Assign core properties
-        self._baseurl = baseurl.strip()
-        self._site = site.strip().lower()
-        self._user = user.strip()
-        self._password = password.strip()
-        self._version = version.strip()
-        self._unificookie_name = unificookie_name.strip()
-
-        # SSL verification settings
-        self._verify_ssl_cert = ssl_verify
-
-    def __destruct(self):
-        """
-        PHP destructor: if the unificookie is set in session, skip logout; otherwise logout if logged in.
-        """
-        # If the unificookie is present in session cookies, skip logout
-        if self._unificookie_name in self._session.cookies.get_dict():
-            return
-
-        # Logout if still logged in
-        if getattr(self, '_is_loggedin', False):
-            try:
-                self.logout()
-            except Exception:
-                pass
 
     def list_firewallgroups(self, group_id: str = ''):
-        return self.fetch_results(f"/api/s/{self._site}/rest/firewallgroup/{group_id.strip()}", prefix_path=True)
+        return self.fetch_results(f"/api/s/{self._site}/rest/firewallgroup/{group_id.strip()}", proxy_type='network')
 
     def create_firewallgroup(self, group_name: str, group_type: str, group_members: list = []) -> bool:
         """Create a new firewall group"""
@@ -2086,7 +2296,7 @@ class Client:
             'group_type': group_type,
             'group_members': group_members
         }
-        return self.fetch_results(f"/api/s/{self._site}/rest/firewallgroup", payload=payload, prefix_path=True)
+        return self.fetch_results(f"/api/s/{self._site}/rest/firewallgroup", payload=payload, proxy_type='network')
 
     def edit_firewallgroup(self, group_id: str, site_id: str, group_name: str, group_type: str, group_members: list = []) -> bool:
         """Edit an existing firewall group"""
@@ -2105,7 +2315,7 @@ class Client:
         return self.fetch_results(
             f"/api/s/{self._site}/rest/firewallgroup/{group_id.strip()}",
             payload=payload,
-            prefix_path=True
+            proxy_type='network'
         )
 
     def delete_firewallgroup(self, group_id: str) -> bool:
@@ -2114,7 +2324,7 @@ class Client:
         self._curl_method = "GET"
 
     def list_firewallrules(self):
-        return self.fetch_results(f"/api/s/{self._site}/rest/firewallrule")
+        return self.fetch_results(f"/api/s/{self._site}/rest/firewallrule", proxy_type='network')
 
     def list_routing(self, route_id: str = ''):
         return self.fetch_results(f"/api/s/{self._site}/rest/routing/{route_id.strip()}")
@@ -2297,62 +2507,122 @@ class Client:
         payload = None,
         boolean: bool = False,
         login_required: bool = False,
-        prefix_path: bool = False
+        proxy_type: str = 'network',
+        auto_fallback: bool = True
     ):
+        """Fetch results from UniFi API with automatic v1/v2 firmware detection.
+
+        Args:
+            path: API endpoint path
+            payload: Request payload (optional)
+            boolean: If True, return boolean instead of data
+            login_required: If True, raise if not logged in
+            proxy_type: Proxy category for UniFi OS devices:
+                - 'network': /proxy/network prefix (v1/v2 fallback supported)
+                - 'users': /proxy/users prefix (v2 only)
+                - 'protect': /proxy/protect prefix (v2 only)
+                - None: No prefix, direct /api/ path (v2 only)
+            auto_fallback: If True, automatically fallback from v2 to v1 on JSON decode error
+                           (only applies when proxy_type='network')
+
+        Returns:
+            API response data, or boolean if boolean=True
+        """
         if login_required and not self._is_loggedin:
             raise LoginRequiredException()
 
-        self._last_results_raw = self.exec_curl(path, payload, prefix_path)
-        self._last_results_raw = self._last_results_raw.decode()
+        # Use cached firmware version if known (only affects network endpoints)
+        if proxy_type == 'network':
+            if self._firmware_version == 'v1':
+                proxy_type = None  # v1 doesn't use /proxy/network prefix
+            # v2 keeps proxy_type='network'
+
+        # Track the proxy_type we're using for caching
+        used_proxy_type = proxy_type
 
-        if isinstance(self._last_results_raw, str):
-            try:
+        try:
+            self._last_results_raw = self.exec_curl(path, payload, proxy_type)
+            self._last_results_raw = self._last_results_raw.decode()
+
+            if isinstance(self._last_results_raw, str):
                 response = json.loads(self._last_results_raw)
                 print("Fetched response:", response) if self.debug else None
-            except:
-                self._get_json_last_error()
-                raise
-
-            if isinstance(response, dict) and 'meta' in response:
-                if response['meta'].get('rc') == 'ok':
-                    self._last_error_message = ''
-                    if 'data' in response:
-                        if isinstance(response['data'], list):
-                            print("Response inside fetch_results():", response) if self.debug else None
-                            print("Data:", response.get("data")) if self.debug else None
+
+                # Cache successful firmware version (only if not already cached)
+                # If any proxy path works, we're on v2 (UniFi OS)
+                if self._firmware_version is None and used_proxy_type is not None:
+                    self._firmware_version = 'v2'
+                    if self.debug:
+                        print(f"Detected firmware version: {self._firmware_version}")
+
+                if isinstance(response, dict) and 'meta' in response:
+                    if response['meta'].get('rc') == 'ok':
+                        self._last_error_message = ''
+                        if 'data' in response:
+                            if isinstance(response['data'], list):
+                                print("Response inside fetch_results():", response) if self.debug else None
+                                print("Data:", response.get("data")) if self.debug else None
+                                return response['data'] if not boolean else True
+                            return [response['data']] if not boolean else True
+                        return True
+                    elif response['meta'].get('rc') == 'error':
+                        self._last_error_message = 'An unknown error was returned by the controller'
+                        raise Exception(f"Error message: {self._last_error_message} - {response}")
+
+                if path.startswith('/v2/api/'):
+                    if 'errorCode' in response:
+                        self._last_error_message = 'An unknown error was returned by an API v2 endpoint'
+                        raise Exception(f"Error code: {response['errorCode']}, message: {self._last_error_message}")
+                    return response
+
+                # Proxy API response (users, protect, etc.)
+                # These have code: 1 (positive) for success, negative codes for errors
+                if used_proxy_type is not None:
+                    if 'code' in response:
+                        if response['code'] < 0:
+                            # Negative code is an error
+                            self._last_error_message = response.get('msg', response.get('message', 'API error'))
+                            raise Exception(f"Error code: {response['code']}, message: {self._last_error_message}")
+                        # Positive code (1) means success - return data
+                        if 'data' in response:
                             return response['data'] if not boolean else True
-                        return [response['data']] if not boolean else True
+                        return response if not boolean else True
+                    return response if not boolean else True
+
+                # UniFi OS system response (paths like /api/system, /api/backup, etc.)
+                if path.startswith('/api/') and used_proxy_type is None:
+                    if 'code' in response:
+                        self._last_error_message = response.get('message', 'An unknown error was returned by a UniFi OS endpoint.')
+                        raise Exception(f"Error code: {response['code']}, message: {self._last_error_message}")
+                    if not boolean:
+                        return [response]
                     return True
-                elif response['meta'].get('rc') == 'error':
-                    self._last_error_message = 'An unknown error was returned by the controller'
-
-                    raise Exception(f"Error message: {self._last_error_message}")
-
-            if path.startswith('/v2/api/'):
-                if 'errorCode' in response:
-                    self._last_error_message = 'AN unkown error was returned by an API v2 endpoind'
-                    raise Exception(f"Error code: {response['errorCode']}, message: {self.last_error_message}")
-                return response
-
-            # UniFi OS response
-            if path.startswith('/api/'):
-                if 'code' in response:
-                    self._last_error_message = response.get('message', 'An unknown error was returned by a UniFi OS endpoint.')
-                    raise Exception(f"Error code: {response['code']}, message: {self._last_error_message}")
-                if not boolean:
-                    return [response]
-                return True
-        return False
+            return False
+
+        except json.JSONDecodeError as e:
+            # If proxy path failed with JSON decode error and auto_fallback enabled, try without proxy prefix
+            if auto_fallback and used_proxy_type is not None and self._firmware_version is None:
+                if self.debug:
+                    print(f"JSON decode error on v2 path, attempting v1 fallback...")
+                self._firmware_version = 'v1'  # Cache for future calls
+                return self.fetch_results(
+                    path, payload, boolean, login_required,
+                    proxy_type=None,  # v1 uses no proxy prefix
+                    auto_fallback=False  # Don't recurse again
+                )
+            # Re-raise if fallback not applicable or already tried
+            raise JsonDecodeException(f"Invalid JSON response from controller: {e}")
 
     def fetch_results_boolean(
         self,
         path: str,
         payload=None,
         login_required: bool = True,
-        prefix_path: bool = True
+        proxy_type: str = 'network',
+        auto_fallback: bool = True
     ) -> bool:
         """Call fetch_results and always return a boolean"""
-        return self.fetch_results(path, payload, True, login_required, prefix_path)
+        return self.fetch_results(path, payload, True, login_required, proxy_type, auto_fallback)
 
     def get_json_last_error(self) -> bool:
         """Raise exception with message matching last JSON decoding error."""
@@ -2382,15 +2652,26 @@ class Client:
 
         return True
 
-    def exec_curl(self, path: str, payload=None, prefix_path: bool = True):
+    def exec_curl(self, path: str, payload=None, proxy_type: str = None):
+        """Execute HTTP request to UniFi controller.
+
+        Args:
+            path: API endpoint path (e.g., /api/s/{site}/stat/health)
+            payload: Request payload (optional)
+            proxy_type: Proxy category for UniFi OS devices:
+                - 'network': /proxy/network prefix (for network management APIs)
+                - 'users': /proxy/users prefix (for user management APIs)
+                - 'protect': /proxy/protect prefix (for UniFi Protect APIs)
+                - None: No prefix, direct /api/ path (for UniFi OS system APIs)
+        """
         # 1) method sanity check
         if self._curl_method not in self.CURL_METHODS_ALLOWED:
             raise InvalidCurlMethodException()
 
         # 2) build URL
         url = f"{self._baseurl}{path}"
-        if self._unifi_os and prefix_path:
-            url = f"{self._baseurl}/proxy/network{path}"
+        if self._unifi_os and proxy_type:
+            url = f"{self._baseurl}/proxy/{proxy_type}{path}"
 
         # 3) build curl_options dict
         """
@@ -2467,7 +2748,7 @@ class Client:
                 if self.login():
                     if self.debug:
                         print("exec_curl: re-login succeeded, retrying exec_curl")
-                    return self.exec_curl(path, payload, prefix_path)
+                    return self.exec_curl(path, payload, proxy_type)
                 raise LoginFailedException('Cookie/Token expired and re-login failed.')
             raise LoginFailedException('Login failed, check credentials.')
 
@@ -2479,6 +2760,7 @@ class Client:
             print("Payload:", json_payload or '<empty>')
             print("Response Code:", http_code)
             print("Response Body:", resp.text)
+            print(self._curl_method)
             print("-----------------------------\n")
 
         # 11) reset method and retry count
@@ -2581,7 +2863,131 @@ class Client:
         for header in self.curl_headers:
             if header.lower().find('x-csrf-token:') == -1:
                 filtered.append(header)
-        self.curl_headers = filtered
+        self._curl_headers = filtered
 
         # 8) Append the new header, using only ASCII
-        self.curl_headers.append('x-csrf-token: %s' % csrf_token)
+        self._curl_headers.append('x-csrf-token: %s' % csrf_token)
+
+    # =========================================================================
+    # SSH Management Methods
+    # =========================================================================
+
+    def set_ssh_password(self, password: str):
+        """Set the SSH password for UniFi OS.
+
+        Args:
+            password: The SSH password to set.
+
+        Returns:
+            True on success (200/204), False on failure.
+        """
+        payload = {'password': password}
+        try:
+            self.fetch_results("/api/system/ssh/setpassword", payload=payload, proxy_type=None)
+            return True
+        except JsonDecodeException:
+            # 204 No Content returns empty body - that's success
+            return True
+        except Exception:
+            return False
+
+    def turn_on_ssh(self, password: str):
+        """Enable SSH on the UniFi controller.
+
+        Args:
+            password: SSH password to set before enabling.
+
+        Returns:
+            API response on success, error string on failure.
+        """
+        result = self.set_ssh_password(password)
+        if not result:
+            return 'Failed to set password, try again later.'
+
+        self._curl_method = 'PATCH'
+        return self.fetch_results("/api/system", payload={'ssh': {'enabled': True}}, proxy_type=None)
+
+    def turn_off_ssh(self):
+        """Disable SSH on the UniFi controller.
+
+        Returns:
+            API response data.
+        """
+        self._curl_method = 'PATCH'
+        return self.fetch_results("/api/system", payload={'ssh': {'enabled': False}}, proxy_type=None)
+
+    # =========================================================================
+    # Utility Methods
+    # =========================================================================
+
+    def get_protect_devices(self):
+        """Get UniFi Protect device stats.
+
+        Returns:
+            List of protect device stats, or empty list if Protect not installed.
+        """
+        try:
+            return self.fetch_results("/api/devices/stat/", proxy_type='protect')
+        except JsonDecodeException:
+            # UniFi Protect not installed returns empty/invalid response
+            return []
+
+    def validate_email(self, email: str) -> bool:
+        """Validate email address format.
+
+        Args:
+            email: Email address to validate.
+
+        Returns:
+            True if valid, False otherwise.
+        """
+        pattern = r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$'
+        return bool(re.match(pattern, email))
+
+    # =========================================================================
+    # Additional User Management Helpers
+    # =========================================================================
+
+    def get_custom_role(self, network_permission: str, user_permission: str):
+        """Create a custom role for admin user creation.
+
+        This is a convenience method that builds the role payload from permission strings.
+        Use create_custom_role() if you need to pass a raw payload.
+
+        Args:
+            network_permission: One of 'admin', 'hotspotoperator', 'readonly', 'none'
+            user_permission: One of 'admin', 'readonly', 'none'
+
+        Returns:
+            API response with role data including unique_id.
+        """
+        import random
+        payload = {
+            'is_private': True,
+            'name': f'role_private_{random.randint(10000000, 99999999)}',
+            'permission_resources': [],
+            'permissions': []
+        }
+        if network_permission != 'none':
+            payload['permissions'].append({'manifest_unique_key': 'network.management', 'formulas': [network_permission]})
+        if user_permission != 'none':
+            payload['permissions'].append({'manifest_unique_key': 'system.management.user', 'formulas': [user_permission]})
+
+        self._curl_method = 'POST'
+        return self.fetch_results("/api/v2/custom_role", payload=payload, proxy_type='users')
+
+    def resend_invite(self, email: str):
+        """Resend invitation to a user.
+
+        Args:
+            email: Email address to send invite to.
+
+        Returns:
+            API response data, or error string iwf invalid email.
+        """
+        if not self.validate_email(email):
+            return "Please enter a valid email"
+
+        payload = {'email': email, 'is_resend': True}
+        self._curl_method = 'POST'
+        return self.fetch_results("/api/v2/users/invite_add", payload=payload, proxy_type='users')

{python_unifi_client-1.2.7 → python_unifi_client-1.2.8}/python_unifi_client.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python_unifi_client
-Version: 1.2.7
+Version: 1.2.8
 Home-page: https://github.com/compdat-llc/unifi-client-python
 Author: Michael Lapinski
 Author-email: michaellapinski787@gmail.com

{python_unifi_client-1.2.7 → python_unifi_client-1.2.8}/setup.py

@@ -5,7 +5,7 @@ with open("README.md", "r") as fh:
 
 setuptools.setup(
 		name="python_unifi_client",
-		version="1.2.7",
+		version="1.2.8",
 		author="Michael Lapinski",
 		author_email="michaellapinski787@gmail.com",
 		descripton="A python version of a github Art-of-Wifi/Unifi-API-Client",