Add methods for accepting and cancelling friend invites (#849)

JonnyWong16 · web-flow · commit 777ea754be3a · 2021-11-20T16:16:01.000-08:00
* Add accepting and cancelling friend invites

* Add mocked tests for acceptInvite and cancelInvite

* Rename methods to pendingInvite
diff --git a/plexapi/myplex.py b/plexapi/myplex.py
@@ -70,9 +70,6 @@ class MyPlexAccount(PlexObject):
     PLEXSERVERS = 'https://plex.tv/api/servers/{machineId}'                                     # get
     FRIENDUPDATE = 'https://plex.tv/api/friends/{userId}'                                       # put with args, delete
     REMOVEHOMEUSER = 'https://plex.tv/api/home/users/{userId}'                                  # delete
-    REMOVEINVITE = 'https://plex.tv/api/invites/requested/{userId}?friend=1&server=1&home=1'    # delete
-    REQUESTED = 'https://plex.tv/api/invites/requested'                                         # get
-    REQUESTS = 'https://plex.tv/api/invites/requests'                                           # get
     SIGNIN = 'https://plex.tv/users/sign_in.xml'                                                # get with auth
     WEBHOOKS = 'https://plex.tv/api/v2/user/webhooks'                                           # get, post with data
     OPTOUTS = 'https://plex.tv/api/v2/user/%(userUUID)s/settings/opt_outs'                      # get
@@ -365,26 +362,55 @@ def createExistingUser(self, user, server, sections=None, allowSync=False, allow
         return self.query(url, self._session.post, headers=headers)
 
     def removeFriend(self, user):
-        """ Remove the specified user from all sharing.
+        """ Remove the specified user from your friends.
 
             Parameters:
-                user (str): MyPlexUser, username, email of the user to be added.
+                user (str): :class:`~plexapi.myplex.MyPlexUser`, username, or email of the user to be removed.
         """
-        user = self.user(user)
-        url = self.FRIENDUPDATE if user.friend else self.REMOVEINVITE
-        url = url.format(userId=user.id)
+        user = user if isinstance(user, MyPlexUser) else self.user(user)
+        url = self.FRIENDUPDATE.format(userId=user.id)
         return self.query(url, self._session.delete)
 
     def removeHomeUser(self, user):
-        """ Remove the specified managed user from home.
+        """ Remove the specified user from your home users.
 
             Parameters:
-                user (str): MyPlexUser, username, email of the user to be removed from home.
+                user (str): :class:`~plexapi.myplex.MyPlexUser`, username, or email of the user to be removed.
         """
-        user = self.user(user)
+        user = user if isinstance(user, MyPlexUser) else self.user(user)
         url = self.REMOVEHOMEUSER.format(userId=user.id)
         return self.query(url, self._session.delete)
 
+    def acceptInvite(self, user):
+        """ Accept a pending firend invite from the specified user.
+
+            Parameters:
+                user (str): :class:`~plexapi.myplex.MyPlexInvite`, username, or email of the friend invite to accept.
+        """
+        invite = user if isinstance(user, MyPlexInvite) else self.pendingInvite(user, includeSent=False)
+        params = {
+            'friend': int(invite.friend),
+            'home': int(invite.home),
+            'server': int(invite.server)
+        }
+        url = MyPlexInvite.REQUESTS + '/%s' % invite.id + utils.joinArgs(params)
+        return self.query(url, self._session.put)
+
+    def cancelInvite(self, user):
+        """ Cancel a pending firend invite for the specified user.
+
+            Parameters:
+                user (str): :class:`~plexapi.myplex.MyPlexInvite`, username, or email of the friend invite to cancel.
+        """
+        invite = user if isinstance(user, MyPlexInvite) else self.pendingInvite(user, includeReceived=False)
+        params = {
+            'friend': int(invite.friend),
+            'home': int(invite.home),
+            'server': int(invite.server)
+        }
+        url = MyPlexInvite.REQUESTED + '/%s' % invite.id + utils.joinArgs(params)
+        return self.query(url, self._session.delete)
+
     def updateFriend(self, user, server, sections=None, removeSections=False, allowSync=None, allowCameraUpload=None,
                      allowChannels=None, filterMovies=None, filterTelevision=None, filterMusic=None):
         """ Update the specified user's share settings.
@@ -455,7 +481,7 @@ def updateFriend(self, user, server, sections=None, removeSections=False, allowS
         return response_servers, response_filters
 
     def user(self, username):
-        """ Returns the :class:`~plexapi.myplex.MyPlexUser` that matches the email or username specified.
+        """ Returns the :class:`~plexapi.myplex.MyPlexUser` that matches the specified username or email.
 
             Parameters:
                 username (str): Username, email or id of the user to return.
@@ -467,19 +493,50 @@ def user(self, username):
                 return user
 
             elif (user.username and user.email and user.id and username.lower() in
-                  (user.username.lower(), user.email.lower(), str(user.id))):
+                    (user.username.lower(), user.email.lower(), str(user.id))):
                 return user
 
         raise NotFound('Unable to find user %s' % username)
 
     def users(self):
         """ Returns a list of all :class:`~plexapi.myplex.MyPlexUser` objects connected to your account.
-            This includes both friends and pending invites. You can reference the user.friend to
-            distinguish between the two.
         """
-        friends = [MyPlexUser(self, elem) for elem in self.query(MyPlexUser.key)]
-        requested = [MyPlexUser(self, elem, self.REQUESTED) for elem in self.query(self.REQUESTED)]
-        return friends + requested
+        elem = self.query(MyPlexUser.key)
+        return self.findItems(elem, cls=MyPlexUser)
+
+    def pendingInvite(self, username, includeSent=True, includeReceived=True):
+        """ Returns the :class:`~plexapi.myplex.MyPlexInvite` that matches the specified username or email.
+            Note: This can be a pending invite sent from your account or received to your account.
+
+            Parameters:
+                username (str): Username, email or id of the user to return.
+                includeSent (bool): True to include sent invites.
+                includeReceived (bool): True to include received invites.
+        """
+        username = str(username)
+        for invite in self.pendingInvites(includeSent, includeReceived):
+            if (invite.username and invite.email and invite.id and username.lower() in
+                    (invite.username.lower(), invite.email.lower(), str(invite.id))):
+                return invite
+        
+        raise NotFound('Unable to find invite %s' % username)
+
+    def pendingInvites(self, includeSent=True, includeReceived=True):
+        """ Returns a list of all :class:`~plexapi.myplex.MyPlexInvite` objects connected to your account.
+            Note: This includes all pending invites sent from your account and received to your account.
+
+            Parameters:
+                includeSent (bool): True to include sent invites.
+                includeReceived (bool): True to include received invites.
+        """
+        invites = []
+        if includeSent:
+            elem = self.query(MyPlexInvite.REQUESTED)
+            invites += self.findItems(elem, cls=MyPlexInvite)
+        if includeReceived:
+            elem = self.query(MyPlexInvite.REQUESTS)
+            invites += self.findItems(elem, cls=MyPlexInvite)
+        return invites
 
     def _getSectionIds(self, server, sections):
         """ Converts a list of section objects or names to sectionIds needed for library sharing. """
@@ -731,10 +788,10 @@ class MyPlexUser(PlexObject):
             protected (False): Unknown (possibly SSL enabled?).
             recommendationsPlaylistId (str): Unknown.
             restricted (str): Unknown.
+            servers (List<:class:`~plexapi.myplex.<MyPlexServerShare`>)): Servers shared with the user.
             thumb (str): Link to the users avatar.
             title (str): Seems to be an aliad for username.
             username (str): User's username.
-            servers: Servers shared between user and friend
     """
     TAG = 'User'
     key = 'https://plex.tv/api/users/'
@@ -796,6 +853,43 @@ def history(self, maxresults=9999999, mindate=None):
         return hist
 
 
+class MyPlexInvite(PlexObject):
+    """ This object represents pending friend invites.
+
+        Attributes:
+            TAG (str): 'Invite'
+            createdAt (datetime): Datetime the user was invited.
+            email (str): User's email address (user@gmail.com).
+            friend (bool): True or False if the user is invited as a friend.
+            friendlyName (str): The user's friendly name.
+            home (bool): True or False if the user is invited to a Plex Home.
+            id (int): User's Plex account ID.
+            server (bool): True or False if the user is invited to any servers.
+            servers (List<:class:`~plexapi.myplex.<MyPlexServerShare`>)): Servers shared with the user.
+            thumb (str): Link to the users avatar.
+            username (str): User's username.
+    """
+    TAG = 'Invite'
+    REQUESTS = 'https://plex.tv/api/invites/requests'
+    REQUESTED = 'https://plex.tv/api/invites/requested'
+
+    def _loadData(self, data):
+        """ Load attribute values from Plex XML response. """
+        self._data = data
+        self.createdAt = utils.toDatetime(data.attrib.get('createdAt'))
+        self.email = data.attrib.get('email')
+        self.friend = utils.cast(bool, data.attrib.get('friend'))
+        self.friendlyName = data.attrib.get('friendlyName')
+        self.home = utils.cast(bool, data.attrib.get('home'))
+        self.id = utils.cast(int, data.attrib.get('id'))
+        self.server = utils.cast(bool, data.attrib.get('server'))
+        self.servers = self.findItems(data, MyPlexServerShare)
+        self.thumb = data.attrib.get('thumb')
+        self.username = data.attrib.get('username', '')
+        for server in self.servers:
+            server.accountID = self.id
+
+
 class Section(PlexObject):
     """ This refers to a shared section. The raw xml for the data presented here
         can be found at: https://plex.tv/api/servers/{machineId}/shared_servers
diff --git a/tests/payloads.py b/tests/payloads.py
@@ -34,3 +34,10 @@
 <TranscodeSession key="qucs2leop3yzm0sng4urq1o0" throttled="0" complete="0" progress="1.2999999523162842" size="73138224" speed="6.4000000953674316" duration="6654989" remaining="988" context="streaming" sourceVideoCodec="h264" sourceAudioCodec="dca" videoDecision="transcode" audioDecision="transcode" protocol="dash" container="mp4" videoCodec="h264" audioCodec="aac" audioChannels="2" transcodeHwRequested="1" transcodeHwDecoding="dxva2" transcodeHwDecodingTitle="Windows (DXVA2)" transcodeHwEncoding="qsv" transcodeHwEncodingTitle="Intel (QuickSync)" transcodeHwFullPipeline="0" timeStamp="1611533677.0316164" maxOffsetAvailable="84.000667334000667" minOffsetAvailable="0" height="720" width="1280" />
 </MediaContainer>
 """
+
+MYPLEX_INVITE = """<MediaContainer friendlyName="myPlex" identifier="com.plexapp.plugins.myplex" machineIdentifier="xxxxxxxxxx" size="1">
+<Invite id="12345" createdAt="1635126033" friend="1" home="1" server="1" username="testuser" email="testuser@email.com" thumb="https://plex.tv/users/1234567890abcdef/avatar?c=12345" friendlyName="testuser">
+<Server name="testserver" numLibraries="2"/>
+</Invite>
+</MediaContainer>
+"""
diff --git a/tests/test_myplex.py b/tests/test_myplex.py
@@ -1,8 +1,10 @@
 # -*- coding: utf-8 -*-
 import pytest
 from plexapi.exceptions import BadRequest, NotFound
+from plexapi.myplex import MyPlexInvite
 
 from . import conftest as utils
+from .payloads import MYPLEX_INVITE
 
 
 def test_myplex_accounts(account, plex):
@@ -150,7 +152,7 @@ def test_myplex_onlineMediaSources_optOut(account):
         onlineMediaSources[0]._updateOptOut('unknown')
 
 
-def test_myplex_inviteFriend_remove(account, plex, mocker):
+def test_myplex_inviteFriend(account, plex, mocker):
     inv_user = "hellowlol"
     vid_filter = {"contentRating": ["G"], "label": ["foo"]}
     secs = plex.library.sections()
@@ -172,9 +174,21 @@ def test_myplex_inviteFriend_remove(account, plex, mocker):
 
         assert inv_user not in [u.title for u in account.users()]
 
-        with pytest.raises(NotFound):
-            with utils.callable_http_patch():
-                account.removeFriend(inv_user)
+
+def test_myplex_acceptInvite(account, requests_mock):
+    url = MyPlexInvite.REQUESTS
+    requests_mock.get(url, text=MYPLEX_INVITE)
+    invite = account.pendingInvite('testuser', includeSent=False)
+    with utils.callable_http_patch():
+        account.acceptInvite(invite)
+
+
+def test_myplex_cancelInvite(account, requests_mock):
+    url = MyPlexInvite.REQUESTED
+    requests_mock.get(url, text=MYPLEX_INVITE)
+    invite = account.pendingInvite('testuser', includeReceived=False)
+    with utils.callable_http_patch():
+        account.cancelInvite(invite)
 
 
 def test_myplex_updateFriend(account, plex, mocker, shared_username):
@@ -186,7 +200,6 @@ def test_myplex_updateFriend(account, plex, mocker, shared_username):
     mocker.patch.object(account, "_getSectionIds", return_value=ids)
     mocker.patch.object(account, "user", return_value=user)
     with utils.callable_http_patch():
-
         account.updateFriend(
             shared_username,
             plex,
@@ -200,6 +213,9 @@ def test_myplex_updateFriend(account, plex, mocker, shared_username):
             filterMusic={"label": ["foo"]},
         )
 
+        with utils.callable_http_patch():
+            account.removeFriend(shared_username)
+
 
 def test_myplex_createExistingUser(account, plex, shared_username):
     user = account.user(shared_username)
