Add documentation and tests for new actions in activities

august/activity.py

@@ -1,11 +1,35 @@
 from datetime import datetime
 from enum import Enum
 
+from august.lock import LockDoorStatus, LockStatus
+
+ACTION_LOCK_ONETOUCHLOCK = "onetouchlock"
+ACTION_LOCK_LOCK = "lock"
+ACTION_LOCK_UNLOCK = "unlock"
+ACTION_DOOR_OPEN = "dooropen"
+ACTION_DOOR_CLOSED = "doorclosed"
+ACTION_DOORBELL_CALL_INITIATED = "doorbell_call_initiated"
+ACTION_DOORBELL_MOTION_DETECTED = "doorbell_motion_detected"
+ACTION_DOORBELL_CALL_MISSED = "doorbell_call_missed"
+ACTION_DOORBELL_CALL_HANGUP = "doorbell_call_hangup"
+
+ACTIVITY_ACTIONS_DOORBELL_DING = [ACTION_DOORBELL_CALL_MISSED, ACTION_DOORBELL_CALL_HANGUP]
+ACTIVITY_ACTIONS_DOORBELL_MOTION = [ACTION_DOORBELL_MOTION_DETECTED]
+ACTIVITY_ACTIONS_DOORBELL_VIEW = [ACTION_DOORBELL_CALL_INITIATED]
+ACTIVITY_ACTIONS_LOCK_OPERATION = [ACTION_LOCK_LOCK, ACTION_LOCK_UNLOCK, ACTION_LOCK_ONETOUCHLOCK]
+ACTIVITY_ACTIONS_DOOR_OPERATION = [ACTION_DOOR_CLOSED, ACTION_DOOR_OPEN]
+
+ACTIVITY_ACTION_STATES = {
+    ACTION_LOCK_ONETOUCHLOCK: LockStatus.LOCKED,
+    ACTION_LOCK_LOCK: LockStatus.LOCKED,
+    ACTION_LOCK_UNLOCK: LockStatus.UNLOCKED,
+    ACTION_DOOR_OPEN: LockDoorStatus.OPEN,
+    ACTION_DOOR_CLOSED: LockDoorStatus.CLOSED,
+}
 
 def epoch_to_datetime(epoch):
     return datetime.fromtimestamp(int(epoch) / 1000.0)
 
-
 class ActivityType(Enum):
     DOORBELL_MOTION = "doorbell_motion"
     DOORBELL_DING = "doorbell_ding"

august/api.py

@@ -1,25 +1,18 @@
 import logging
 import time
 
-from requests import request, Session
-
-from august.activity import (
-    DoorbellDingActivity,
-    DoorbellMotionActivity,
-    DoorbellViewActivity,
-    LockOperationActivity,
-    DoorOperationActivity
-)
-from august.doorbell import (
-    Doorbell,
-    DoorbellDetail
-)
-from august.lock import (
-    Lock,
-    LockDetail,
-    LockDoorStatus,
-    LockStatus,
-)
+from requests import Session, request
+
+from august.activity import (ACTIVITY_ACTIONS_DOOR_OPERATION,
+                             ACTIVITY_ACTIONS_DOORBELL_DING,
+                             ACTIVITY_ACTIONS_DOORBELL_MOTION,
+                             ACTIVITY_ACTIONS_DOORBELL_VIEW,
+                             ACTIVITY_ACTIONS_LOCK_OPERATION,
+                             DoorbellDingActivity, DoorbellMotionActivity,
+                             DoorbellViewActivity, DoorOperationActivity,
+                             LockOperationActivity)
+from august.doorbell import Doorbell, DoorbellDetail
+from august.lock import Lock, LockDetail, LockDoorStatus, LockStatus
 from august.pin import Pin
 
 HEADER_ACCEPT_VERSION = "Accept-Version"
@@ -193,15 +186,15 @@ def get_house_activities(self, access_token, house_id, limit=8):
         for activity_json in response.json():
             action = activity_json.get("action")
 
-            if action in ["doorbell_call_missed", "doorbell_call_hangup"]:
+            if action in ACTIVITY_ACTIONS_DOORBELL_DING:
                 activities.append(DoorbellDingActivity(activity_json))
-            elif action == "doorbell_motion_detected":
+            elif action in ACTIVITY_ACTIONS_DOORBELL_MOTION:
                 activities.append(DoorbellMotionActivity(activity_json))
-            elif action == "doorbell_call_initiated":
+            elif action in ACTIVITY_ACTIONS_DOORBELL_VIEW:
                 activities.append(DoorbellViewActivity(activity_json))
-            elif action in ["lock", "unlock", "onetouchlock"]:
+            elif action in ACTIVITY_ACTIONS_LOCK_OPERATION:
                 activities.append(LockOperationActivity(activity_json))
-            elif action in ["doorclosed", "dooropen"]:
+            elif action in ACTIVITY_ACTIONS_DOOR_OPERATION:
                 activities.append(DoorOperationActivity(activity_json))
 
         return activities

august/authenticator.py

@@ -8,6 +8,7 @@
 
 import dateutil.parser
 import requests
+
 from august.api import HEADER_AUGUST_ACCESS_TOKEN
 
 # The default time before expiration to refresh a token

known_activities.md

@@ -0,0 +1,215 @@
+# Known Activity Actions
+
+## doorclosed
+```
+{
+  "entities": {
+    "device": "<deviceId>",
+    "callingUser": "deleted",
+    "otherUser": "deleted",
+    "house": "<houseId>",
+    "activity": "<activityId>"
+  },
+  "house": {
+    "houseID": "<houseId>",
+    "houseName": "<houseName>"
+  },
+  "dateTime": <epochTimestamp>,
+  "action": "doorclosed",
+  "deviceName": "<deviceName>",
+  "deviceID": "<deviceId>",
+  "deviceType": "lock",
+  "callingUser": {
+    "UserID": "deleted",
+    "FirstName": "Unknown",
+    "LastName": "User",
+    "UserName": "deleteduser",
+    "PhoneNo": "deleted"
+  },
+  "otherUser": {
+    "UserID": "deleted",
+    "FirstName": "Unknown",
+    "LastName": "User",
+    "UserName": "deleteduser",
+    "PhoneNo": "deleted"
+  },
+  "info": {
+    "DateLogActionID": "<uniqueId>"
+  }
+}
+```
+## dooropen
+
+```
+{
+  "entities": {
+    "device": "<deviceId>",
+    "callingUser": "deleted",
+    "otherUser": "deleted",
+    "house": "<houseId>",
+    "activity": "<activityId>"
+  },
+  "house": {
+    "houseID": "<houseId>",
+    "houseName": <houseName>
+  },
+  "dateTime": <epochTimestamp>,
+  "action": "dooropen",
+  "deviceName": <deviceName>,
+  "deviceID": "<deviceId>",
+  "deviceType": "lock",
+  "callingUser": {
+    "UserID": "deleted",
+    "FirstName": "Unknown",
+    "LastName": "User",
+    "UserName": "deleteduser",
+    "PhoneNo": "deleted"
+  },
+  "otherUser": {
+    "UserID": "deleted",
+    "FirstName": "Unknown",
+    "LastName": "User",
+    "UserName": "deleteduser",
+    "PhoneNo": "deleted"
+  },
+  "info": {
+    "DateLogActionID": "<uniqueId>"
+  }
+}
+```
+
+## unlock
+
+```
+{
+  "entities": {
+    "device": "<deviceId>",
+    "callingUser": "<userId>",
+    "otherUser": "deleted",
+    "house": "<houseId>",
+    "activity": "<activityId>"
+  },
+  "house": {
+    "houseID": "<houseId>",
+    "houseName": <houseName>
+  },
+  "source": {
+    "sourceType": "mercury"
+  },
+  "dateTime": <epochTimestamp>,
+  "action": "unlock",
+  "deviceName": <deviceName>,
+  "deviceID": "<deviceId>",
+  "deviceType": "lock",
+  "callingUser": {
+    "UserID": "<userId>",
+    "FirstName": "<firstName>",
+    "LastName": "<lastName>",
+    "imageInfo": {
+      "original": {
+        "width": <imageWidth>,
+        "height": <imageHeight>,
+        "format": "<imageFormat>",
+        "url": "<imageUrl>",
+        "secure_url": "<imageSecureUrl>"
+      },
+      "thumbnail": {
+        "width": <thumbnailWidth>,
+        "height": <thumbnailHeight>,
+        "format": "<imageFormat>",
+        "url": "<thumbnailUrl>",
+        "secure_url": "<thumbnailSecureUrl>"
+      }
+    }
+  },
+  "otherUser": {
+    "UserID": "deleted",
+    "FirstName": "Unknown",
+    "LastName": "User",
+    "UserName": "deleteduser",
+    "PhoneNo": "deleted"
+  },
+  "info": {
+    "agent": "mercury",
+    "keypad": true
+  }
+}
+```
+
+## lock
+
+```
+{
+  "entities": {
+    "device": "<deviceId>",
+    "callingUser": "<userId>",
+    "otherUser": "deleted",
+    "house": "<houseId>",
+    "activity": "<activityId>"
+  },
+  "house": {
+    "houseID": "<houseId>",
+    "houseName": <houseName>
+  },
+  "dateTime": <epochTimestamp>,
+  "action": "lock",
+  "deviceName": <deviceName>,
+  "deviceID": "<deviceId>",
+  "deviceType": "lock",
+  "callingUser": {
+    "UserID": "<userId>",
+    "FirstName": "<firstName>",
+    "LastName": "<lastName>"
+  },
+  "otherUser": {
+    "UserID": "deleted",
+    "FirstName": "Unknown",
+    "LastName": "User",
+    "UserName": "deleteduser",
+    "PhoneNo": "deleted"
+  },
+  "info": {
+    "remote": true,
+    "DateLogActionID": "<uniqueId>"
+  }
+}
+```
+## onetouchlock
+
+```
+{
+  "entities": {
+    "device": "<deviceId>",
+    "callingUser": "deleted",
+    "otherUser": "deleted",
+    "house": "<houseId>",
+    "activity": "<activityId>"
+  },
+  "house": {
+    "houseID": "<houseId>",
+    "houseName": <houseName>
+  },
+  "dateTime": <epochTimestamp>,
+  "action": "onetouchlock",
+  "deviceName": <deviceName>,
+  "deviceID": "<deviceId>",
+  "deviceType": "lock",
+  "callingUser": {
+    "UserID": "deleted",
+    "FirstName": "Unknown",
+    "LastName": "User",
+    "UserName": "deleteduser",
+    "PhoneNo": "deleted"
+  },
+  "otherUser": {
+    "UserID": "deleted",
+    "FirstName": "Unknown",
+    "LastName": "User",
+    "UserName": "deleteduser",
+    "PhoneNo": "deleted"
+  },
+  "info": {
+    "DateLogActionID": "<uniqueId>"
+  }
+}
+```