fix(api): Send and revoke home invitation with email (#292)

* fix(api): Send home invitation with email

* fix(api): Revoke home invitation with invitation id (token)

Author: germainlefebvre4

check.py

@@ -29,4 +29,6 @@
 # print(tado.end_manual_control(1))
 # print(tado.refresh_auth())
 # print(tado.set_away_configuration(6, "HEATING", "MEDIUM", 16))
-print(tado.set_zone_order([{"id":1},{"id":6},{"id":11},{"id":12}]))
+# print(tado.set_zone_order([{"id":1},{"id":6},{"id":11},{"id":12}]))
+# print(tado.set_invitation("germain@libtado.fr"))
+print(tado.delete_invitation("aa21a793520c4b9eb4559bc5fb560291"))

libtado/api.py

@@ -83,18 +83,27 @@ def call_get(url):
       r = requests.get(url, headers=self.access_headers, timeout=self.timeout)
       r.raise_for_status()
       return r
+    def call_post(url, data):
+      r = requests.post(url, headers={**self.access_headers, **self.json_content}, data=json.dumps(data), timeout=self.timeout)
+      r.raise_for_status()
+      return r
 
     self.refresh_auth()
     url = '%s/%s' % (self.api, cmd)
     if method == 'DELETE':
-      return call_delete(url)
+      res = call_delete(url)
+      if res.status_code == 204:
+        return None
+      return res.json()
     elif method == 'PUT' and data:
       res = call_put(url, data)
       if res.status_code == 204:
         return None
       return res.json()
     elif method == 'GET':
       return call_get(url).json()
+    elif method == 'POST':
+      return call_post(url, data).json()
 
   def _api_acme_call(self, cmd, data=False, method='GET'):
     """Perform an API call."""
@@ -616,6 +625,105 @@ def get_invitations(self):
     data = self._api_call('homes/%i/invitations' % self.id)
     return data
 
+  def set_invitation(self, email):
+    """
+    Send an invitation to a user.
+
+    Parameters:
+      email (str): The email of the user to invite.
+    
+    Returns:
+      (dict): The invitation information.
+    
+      ??? info "Result example"
+        ```json
+        {
+            "token": "44483e1d07qf439&8b786fc0372ec315",
+            "email": "SOME_EMAIL",
+            "firstSent": "2024-03-19T12:54:38.591Z",
+            "lastSent": "2024-03-19T12:54:38.591Z",
+            "inviter": {
+                "name": "SOME_NAME",
+                "email": "SOME_EMAIL",
+                "username": "SOME_MAIL",
+                "enabled": true,
+                "id": "5c22a9b6d5018000088dba4a",
+                "homeId": 123456,
+                "locale": "fr",
+                "type": "WEB_USER"
+            },
+            "home": {
+                "id": 123456,
+                "name": "Domicile",
+                "dateTimeZone": "Europe/Paris",
+                "dateCreated": "2018-12-25T20:58:28.674Z",
+                "temperatureUnit": "CELSIUS",
+                "partner": null,
+                "simpleSmartScheduleEnabled": true,
+                "awayRadiusInMeters": 1999.68,
+                "installationCompleted": true,
+                "incidentDetection": {
+                    "supported": true,
+                    "enabled": true
+                },
+                "generation": "PRE_LINE_X",
+                "zonesCount": 4,
+                "skills": [
+                    "AUTO_ASSIST"
+                ],
+                "christmasModeEnabled": true,
+                "showAutoAssistReminders": true,
+                "contactDetails": {
+                    "name": "SOME_NAME",
+                    "email": "SOME_EMAIL",
+                    "phone": "SOME_PHONE_NUMBER"
+                },
+                "address": {
+                    "addressLine1": "SOME_POSTAL_ADDRESS",
+                    "addressLine2": null,
+                    "zipCode": "SOME_POSTCODE",
+                    "city": "SOME_CITY",
+                    "state": null,
+                    "country": "FRA"
+                },
+                "geolocation": {
+                    "latitude": 12.3456789,
+                    "longitude": 1.23456
+                },
+                "consentGrantSkippable": true,
+                "enabledFeatures": [
+                    "CLIMATE_REPORT_AS_WEBVIEW",
+                    "EIQ_SETTINGS_AS_WEBVIEW",
+                    "ENERGY_IQ_V2_ONBOARDING",
+                    "HIDE_BOILER_REPAIR_SERVICE",
+                    "KEEP_WEBAPP_UPDATED",
+                    "OWD_SETTINGS_AS_WEBVIEW",
+                    "SMART_SCHEDULE_AS_WEBVIEW"
+                ],
+                "isAirComfortEligible": true,
+                "isBalanceAcEligible": false,
+                "isEnergyIqEligible": true,
+                "isHeatSourceInstalled": false,
+                "isBalanceHpEligible": false
+            }
+        }
+        ```
+    """
+    payload = { 'email': email }
+    return self._api_call('homes/%i/invitations' % (self.id), data=payload, method='POST')
+
+  def delete_invitation(self, token):
+    """
+    Delete an invitation.
+    
+    Parameters:
+      token (str): The token of the invitation to delete.
+    
+    Returns:
+      (None): None.
+    """
+    return self._api_call('homes/%i/invitations/%s' % (self.id, token), method='DELETE')
+
   def get_me(self):
     """
     Get information about the current user.