pyezvizapi 1.0.1.3__py3-none-any.whl → 1.0.1.5__py3-none-any.whl

pyezvizapi/__init__.py

@@ -19,6 +19,7 @@ from .constants import (
 )
 from .exceptions import (
     AuthTestResultFailed,
+    DeviceException,
     EzvizAuthTokenExpired,
     EzvizAuthVerificationCode,
     HTTPError,
@@ -37,6 +38,7 @@ __all__ = [
     "BatteryCameraWorkMode",
     "DefenseModeType",
     "DeviceCatagories",
+    "DeviceException",
     "DeviceSwitchType",
     "DisplayMode",
     "EzvizAuthTokenExpired",

pyezvizapi/api_endpoints.py

@@ -17,14 +17,16 @@ API_ENDPOINT_OSD = "/v3/userdevices/v1/devices/"
 API_ENDPOINT_PANORAMIC_DEVICES_OPERATION = "/v3/panoramicDevices/operation"
 API_ENDPOINT_UPGRADE_DEVICE = "/v3/upgrades/v1/devices/"
 API_ENDPOINT_SEND_CODE = "/v3/sms/nologin/checkcode"
+API_ENDPOINT_2FA_VALIDATE_POST_AUTH = "/v3/users/checkcode/mt"
 API_ENDPOINT_UNIFIEDMSG_LIST_GET = "/v3/unifiedmsg/list"
 API_ENDPOINT_IOT_FEATURE = "/v3/iot-feature/feature/"
+API_ENDPOINT_IOT_ACTION = "/v3/iot-feature/action/"
 API_ENDPOINT_CALLING_NOTIFY = "/v3/calling/"
 
 API_ENDPOINT_ALARMINFO_GET = "/v3/alarms/v2/advanced"
 API_ENDPOINT_V3_ALARMS = "/v3/alarms/"
 API_ENDPOINT_SET_LUMINANCE = "/v3/alarms/device/alarmLight/"
-API_ENDPOINT_REMOTE_UNLOCK = "/v3/iot-feature/action/#SERIAL#/Video/1/DoorLockMgr/RemoteUnlockReq"
+API_ENDPOINT_REMOTE_UNLOCK = "/Video/1/DoorLockMgr/RemoteUnlockReq"
 
 API_ENDPOINT_DEVCONFIG_BY_KEY = "/v3/devconfig/v1/keyValue/"
 API_ENDPOINT_CAM_AUTH_CODE = "/v3/devconfig/authcode/query/"

pyezvizapi/client.py

@@ -13,6 +13,7 @@ from uuid import uuid4
 import requests
 
 from .api_endpoints import (
+    API_ENDPOINT_2FA_VALIDATE_POST_AUTH,
     API_ENDPOINT_ALARM_SOUND,
     API_ENDPOINT_ALARMINFO_GET,
     API_ENDPOINT_CALLING_NOTIFY,
@@ -31,6 +32,7 @@ from .api_endpoints import (
     API_ENDPOINT_DO_NOT_DISTURB,
     API_ENDPOINT_GROUP_DEFENCE_MODE,
     API_ENDPOINT_INTELLIGENT_APP,
+    API_ENDPOINT_IOT_ACTION,
     API_ENDPOINT_IOT_FEATURE,
     API_ENDPOINT_LOGIN,
     API_ENDPOINT_LOGOUT,
@@ -38,9 +40,9 @@ from .api_endpoints import (
     API_ENDPOINT_OSD,
     API_ENDPOINT_PAGELIST,
     API_ENDPOINT_PANORAMIC_DEVICES_OPERATION,
-    API_ENDPOINT_REMOTE_UNLOCK,
     API_ENDPOINT_PTZCONTROL,
     API_ENDPOINT_REFRESH_SESSION_ID,
+    API_ENDPOINT_REMOTE_UNLOCK,
     API_ENDPOINT_RETURN_PANORAMIC,
     API_ENDPOINT_SEND_CODE,
     API_ENDPOINT_SERVER_INFO,
@@ -69,6 +71,7 @@ from .constants import (
     MessageFilterType,
 )
 from .exceptions import (
+    DeviceException,
     EzvizAuthTokenExpired,
     EzvizAuthVerificationCode,
     HTTPError,
@@ -1271,7 +1274,7 @@ class EzvizClient:
                 for item in devices.get("CLOUD", {})
                 if devices["CLOUD"][item].get("deviceSerial") == _serial
             }
-            _res_id = _res_id_list.pop() if len(_res_id_list) else "NONE"
+            _res_id = _res_id_list.pop() if _res_id_list else "NONE"
 
             result[_serial] = {
                 "CLOUD": {_res_id: devices.get("CLOUD", {}).get(_res_id, {})},
@@ -1357,7 +1360,26 @@ class EzvizClient:
     def get_cam_key(
         self, serial: str, smscode: int | None = None, max_retries: int = 0
     ) -> Any:
-        """Get Camera encryption key. The key that is set after the camera is added to the account."""
+        """Get Camera encryption key. The key that is set after the camera is added to the account.
+
+        Args:
+            serial (str): The camera serial number.
+            smscode (int | None): The 2FA code account when rights elevation is required.
+            max_retries (int): The maximum number of retries. Defaults to 0.
+
+        Raises:
+            PyEzvizError: If the camera encryption key can't be retrieved.
+            EzvizAuthVerificationCode: If the account requires elevation with 2FA code.
+            DeviceException: If the physical device is not reachable.
+
+        Returns:
+            Any: JSON response, filtered to return encryptkey:
+                {
+                    "resultCode": int,     # Result code (0 if successful)
+                    "encryptkey": str,     # Camera encryption key
+                    "resultDes": str       # Status message in chinese
+                }
+        """
 
         if max_retries > MAX_RETRIES:
             raise PyEzvizError("Can't gather proper data. Max retries exceeded.")
@@ -1401,6 +1423,9 @@ class EzvizClient:
         if json_output["resultCode"] == "20002":
             raise EzvizAuthVerificationCode(f"MFA code required: Got {json_output})")
 
+        if json_output["resultCode"] == 2009:
+            raise DeviceException(f"Device not reachable: Got {json_output})")
+
         if json_output["resultCode"] != "0":
             if json_output["resultCode"] == "-1":
                 _LOGGER.warning(
@@ -1421,9 +1446,34 @@ class EzvizClient:
         serial: str,
         encrypt_pwd: str | None = None,
         msg_auth_code: int | None = None,
+        sender_type: int = 0,
         max_retries: int = 0,
     ) -> Any:
-        """Get Camera auth code. This is the verification code on the camera sticker."""
+        """Get Camera auth code. This is the verification code on the camera sticker.
+
+        Args:
+            serial (str): The camera serial number.
+            encrypt_pwd (str | None): This is always none.
+            msg_auth_code (int | None): The 2FA code.
+            sender_type (int): The sender type. Defaults to 0. Needs to be 3 when returning 2FA code.
+            max_retries (int): The maximum number of retries. Defaults to 0.
+
+        Raises:
+            PyEzvizError: If the camera auth code cannot be retrieved.
+            EzvizAuthVerificationCode: If the operation requires elevation with 2FA.
+            DeviceException: If the physical device is not reachable.
+
+        Returns:
+            Any: JSON response, filtered to return devAuthCode:
+                {
+                    "devAuthCode": str,     # Device authorization code
+                    "meta": {
+                        "code": int,       # Status code (200 if successful)
+                        "message": str,         # Status message in chinese
+                        "moreInfo": null or {"INVALID_PARAMETER": str}
+                    }
+                }
+        """
 
         if max_retries > MAX_RETRIES:
             raise PyEzvizError("Can't gather proper data. Max retries exceeded.")
@@ -1431,7 +1481,7 @@ class EzvizClient:
         params: dict[str, int | str | None] = {
             "encrptPwd": encrypt_pwd,
             "msgAuthCode": msg_auth_code,
-            "senderType": 0,
+            "senderType": sender_type,
         }
 
         try:
@@ -1464,13 +1514,88 @@ class EzvizClient:
                 + str(req.text)
             ) from err
 
+        if json_output["meta"]["code"] == 80000:
+            raise EzvizAuthVerificationCode("Operation requires 2FA check")
+
+        if json_output["resultCode"] == 2009:
+            raise DeviceException(f"Device not reachable: Got {json_output}")
+
         if json_output["meta"]["code"] != 200:
             raise PyEzvizError(
-                f"Could not get camera verification key: Got {json_output})"
+                f"Could not get camera verification key: Got {json_output}"
             )
 
         return json_output["devAuthCode"]
 
+    def get_2fa_check_code(
+        self,
+        biz_type: str = "DEVICE_AUTH_CODE",
+        username: str | None = None,
+        max_retries: int = 0,
+    ) -> Any:
+        """Initiate 2FA check for sensitive operations. Elevates your session token permission.
+
+        Args:
+            biz_type (str): The operation type. (DEVICE_ENCRYPTION | DEVICE_AUTH_CODE)
+            username (str): The account username.
+            max_retries (int): The maximum number of retries. Defaults to 0.
+
+        Raises:
+            PyEzvizError: If the operation fails.
+
+        Returns:
+            Any: JSON response with the following structure:
+                {
+                    "meta": {
+                        "code": int,       # Status code (200 if successful)
+                        "message": str         # Status message in chinese
+                        "moreInfo": null
+                    },
+                    "contact": {
+                        "type": str,   # 2FA code will be sent to this (EMAIL)
+                        "fuzzyContact": str     # Destination value (e.g., someone@email.local)
+                    }
+                }
+        """
+
+        if max_retries > MAX_RETRIES:
+            raise PyEzvizError("Can't gather proper data. Max retries exceeded.")
+
+        try:
+            req = self._session.post(
+                url=f"https://{self._token['api_url']}{API_ENDPOINT_2FA_VALIDATE_POST_AUTH}",
+                data={"bizType": biz_type, "from": username},
+                timeout=self._timeout,
+            )
+
+            req.raise_for_status()
+
+        except requests.HTTPError as err:
+            if err.response.status_code == 401:
+                # session is wrong, need to relogin
+                self.login()
+                return self.get_2fa_check_code(biz_type, username, max_retries + 1)
+
+            raise HTTPError from err
+
+        try:
+            json_output = req.json()
+
+        except ValueError as err:
+            raise PyEzvizError(
+                "Impossible to decode response: "
+                + str(err)
+                + "\nResponse was: "
+                + str(req.text)
+            ) from err
+
+        if json_output["meta"]["code"] != 200:
+            raise PyEzvizError(
+                f"Could not request elevated permission: Got {json_output})"
+            )
+
+        return json_output
+
     def create_panoramic(self, serial: str, max_retries: int = 0) -> Any:
         """Create panoramic image."""
 
@@ -1611,26 +1736,38 @@ class EzvizClient:
 
         return True
 
-    def remote_unlock(self, serial: str, lock_no: int) -> bool:
-        """Sends a remote command to unlock a specific lock."""
-        try:
-            endpoint = API_ENDPOINT_REMOTE_UNLOCK.replace("#SERIAL#", serial)
-            user_id = self._token["username"]
-            payload = json.dumps({
-                "unLockInfo": {
-                    "bindCode": f"{FEATURE_CODE}{user_id}",
-                    "lockNo": lock_no,
-                    "streamToken": "",
-                    "userName": user_id,
-                }
-            })
+    def remote_unlock(self, serial: str, user_id: str, lock_no: int) -> bool:
+        """Sends a remote command to unlock a specific lock.
 
+        Args:
+            serial (str): The camera serial.
+            user_id (str): The user id.
+            lock_no (int): The lock number.
+
+        Raises:
+            PyEzvizError: If max retries are exceeded or if the response indicates failure.
+            HTTPError: If an HTTP error occurs (other than a 401, which triggers re-login).
+
+        Returns:
+            bool: True if the operation was successful.
+
+        """
+        try:
             headers = self._session.headers
             headers.update({"Content-Type": "application/json"})
 
             req = self._session.put(
-                url=f"https://{self._token['api_url']}{endpoint}",
-                data=payload,
+                url=f"https://{self._token['api_url']}{API_ENDPOINT_IOT_ACTION}{serial}{API_ENDPOINT_REMOTE_UNLOCK}",
+                data=json.dumps(
+                    {
+                        "unLockInfo": {
+                            "bindCode": f"{FEATURE_CODE}{user_id}",
+                            "lockNo": lock_no,
+                            "streamToken": "",
+                            "userName": user_id,
+                        }
+                    }
+                ),
                 timeout=self._timeout,
                 headers=headers,
             )

pyezvizapi/exceptions.py

@@ -27,3 +27,7 @@ class EzvizAuthTokenExpired(PyEzvizError):
 
 class EzvizAuthVerificationCode(PyEzvizError):
     """Authentication failed because MFA verification code is required."""
+
+
+class DeviceException(PyEzvizError):
+    """The device network is abnormal, please check the device network or try again."""

{pyezvizapi-1.0.1.3.dist-info → pyezvizapi-1.0.1.5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyezvizapi
-Version: 1.0.1.3
+Version: 1.0.1.5
 Summary: Pilot your Ezviz cameras
 Home-page: https://github.com/RenierM26/pyEzvizApi/
 Author: Renier Moorcroft

{pyezvizapi-1.0.1.3.dist-info → pyezvizapi-1.0.1.5.dist-info}/RECORD

@@ -1,19 +1,19 @@
-pyezvizapi/__init__.py,sha256=4yNAetIabR69XSbT6ZExmCbXLyW68xK7-qeDMZBzsSY,1290
+pyezvizapi/__init__.py,sha256=yWITfZOi5zvKblfaeB2ft-wXYmZ2NviYVq_tsK8YkSk,1334
 pyezvizapi/__main__.py,sha256=OsawbYa-eoLUTOMr4xWeryq4sDzs09WL9GELKQTbda8,16396
-pyezvizapi/api_endpoints.py,sha256=4eEj6UZw520HQyK_F6V6mpJQqFrXniIGviFJJlPJS88,2671
+pyezvizapi/api_endpoints.py,sha256=rk6VinLVCn-B6DxnhfV79liplNpgUsipNbTEa_MRVwU,2755
 pyezvizapi/camera.py,sha256=BpmLySbnWWEKimSwgjx_cB60Q-6dbgdY-NA--NzUvps,11486
 pyezvizapi/cas.py,sha256=d31ZflYSD9P40MnsNRNZbT0HVLvlnHokKpLbdAjWQ74,5631
-pyezvizapi/client.py,sha256=-tvE5qG2NQn7inFWmTC_xSt_IOAL_3tUg38Rr3iK9Oo,80365
+pyezvizapi/client.py,sha256=6NfWGAYalInpIlmsbraEK_CUyR1CMGIw4jqhKQUfkk8,85561
 pyezvizapi/constants.py,sha256=jjLO-Ne9jq9m9_giYB4rnPXDZKkzKhesVXBqP1B3-00,12304
-pyezvizapi/exceptions.py,sha256=TBJGh12s4UAMVY4k3jibfjEt9D4NVgKnv-397HmfEws,608
+pyezvizapi/exceptions.py,sha256=28lLyM0ILTRHgWqr9D-DqqKFXx7POuF0WAZctdC8Kbc,735
 pyezvizapi/light_bulb.py,sha256=ADLrPZ6NL4vANzmohU63QuD9qVGkKHkX9C0o7Evbv-A,5730
 pyezvizapi/mqtt.py,sha256=Y4X99Z0Avm32SE8vog7CNsv6tGUPmPYUZUgPDGS0QJA,7866
 pyezvizapi/test_cam_rtsp.py,sha256=w7GPcYIeK78TxL8zFDihdGSDQNWcYrurwZOr6uFzzgo,4902
 pyezvizapi/utils.py,sha256=5J10o3h-y8prWDvl3LSAF-9wS1jBgBMg5cpAEebcuSM,4936
-pyezvizapi-1.0.1.3.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-pyezvizapi-1.0.1.3.dist-info/licenses/LICENSE.md,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-pyezvizapi-1.0.1.3.dist-info/METADATA,sha256=mmUk9cGkEADYlGfqLWsB8R6YhfkIdZOX-BxX2WY4sY8,694
-pyezvizapi-1.0.1.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-pyezvizapi-1.0.1.3.dist-info/entry_points.txt,sha256=_BSJ3eNb2H_AZkRdsv1s4mojqWn3N7m503ujvg1SudA,56
-pyezvizapi-1.0.1.3.dist-info/top_level.txt,sha256=gMZTelIi8z7pXyTCQLLaIkxVRrDQ_lS2NEv0WgfHrHs,11
-pyezvizapi-1.0.1.3.dist-info/RECORD,,
+pyezvizapi-1.0.1.5.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+pyezvizapi-1.0.1.5.dist-info/licenses/LICENSE.md,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+pyezvizapi-1.0.1.5.dist-info/METADATA,sha256=ZHsHhFN88VbuD53CDJcFslvEzDTR_TQaDAlHf9PKVhc,694
+pyezvizapi-1.0.1.5.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pyezvizapi-1.0.1.5.dist-info/entry_points.txt,sha256=_BSJ3eNb2H_AZkRdsv1s4mojqWn3N7m503ujvg1SudA,56
+pyezvizapi-1.0.1.5.dist-info/top_level.txt,sha256=gMZTelIi8z7pXyTCQLLaIkxVRrDQ_lS2NEv0WgfHrHs,11
+pyezvizapi-1.0.1.5.dist-info/RECORD,,