Add API changes for invitations and Magic Auth (#262)

* Add events and API changes for invitations and Magic Auth

* Check new invitation attribute in test

Author: blairworkos

tests/test_user_management.py

@@ -5,6 +5,7 @@
 
 from tests.utils.fixtures.mock_auth_factor_totp import MockAuthFactorTotp
 from tests.utils.fixtures.mock_invitation import MockInvitation
+from tests.utils.fixtures.mock_magic_auth import MockMagicAuth
 from tests.utils.fixtures.mock_organization_membership import MockOrganizationMembership
 from tests.utils.fixtures.mock_session import MockSession
 from tests.utils.fixtures.mock_user import MockUser
@@ -212,6 +213,10 @@ def mock_auth_factors(self):
         }
         return dict_response
 
+    @pytest.fixture
+    def mock_magic_auth(self):
+        return MockMagicAuth("magic_auth_ABCDE").to_dict()
+
     @pytest.fixture
     def mock_invitation(self):
         return MockInvitation("invitation_ABCDE").to_dict()
@@ -847,12 +852,33 @@ def test_verify_email(self, capture_and_mock_request, mock_user):
         assert request["json"]["code"] == code
         assert response["id"] == "user_01H7ZGXFP5C6BBQY6Z7277ZCT0"
 
+    def test_get_magic_auth(self, mock_magic_auth, capture_and_mock_request):
+        url, request_kwargs = capture_and_mock_request("get", mock_magic_auth, 200)
+
+        magic_auth = self.user_management.get_magic_auth("magic_auth_ABCDE")
+
+        assert url[0].endswith("user_management/magic_auth/magic_auth_ABCDE")
+        assert magic_auth["id"] == "magic_auth_ABCDE"
+
+    def test_create_magic_auth(self, capture_and_mock_request, mock_magic_auth):
+        email = "[email protected]"
+        url, _ = capture_and_mock_request("post", mock_magic_auth, 201)
+
+        magic_auth = self.user_management.create_magic_auth(email=email)
+
+        assert url[0].endswith("user_management/magic_auth")
+        assert magic_auth["email"] == email
+
     def test_send_magic_auth_code(self, capture_and_mock_request):
         email = "[email protected]"
 
         url, request = capture_and_mock_request("post", None, 200)
 
-        response = self.user_management.send_magic_auth_code(email=email)
+        with pytest.warns(
+            DeprecationWarning,
+            match="'send_magic_auth_code' is deprecated. Please use 'create_magic_auth' instead. This method will be removed in a future major version.",
+        ):
+            response = self.user_management.send_magic_auth_code(email=email)
 
         assert url[0].endswith("user_management/magic_auth/send")
         assert request["json"]["email"] == email

tests/utils/fixtures/mock_invitation.py

@@ -10,7 +10,10 @@ def __init__(self, id):
         self.accepted_at = None
         self.revoked_at = None
         self.expires_at = datetime.datetime.now()
-        self.token = "ABCDE12345"
+        self.token = "Z1uX3RbwcIl5fIGJJJCXXisdI"
+        self.accept_invitation_url = (
+            "https://myauthkit.com/invite?invitation_token=Z1uX3RbwcIl5fIGJJJCXXisdI"
+        )
         self.organization_id = "org_12345"
         self.created_at = datetime.datetime.now()
         self.updated_at = datetime.datetime.now()
@@ -23,6 +26,7 @@ def __init__(self, id):
         "revoked_at",
         "expires_at",
         "token",
+        "accept_invitation_url",
         "organization_id",
         "created_at",
         "updated_at",

tests/utils/fixtures/mock_magic_auth.py

@@ -0,0 +1,23 @@
+import datetime
+from workos.resources.base import WorkOSBaseResource
+
+
+class MockMagicAuth(WorkOSBaseResource):
+    def __init__(self, id):
+        self.id = id
+        self.user_id = "user_01HWZBQAY251RZ9BKB4RZW4D4A"
+        self.email = "[email protected]"
+        self.expires_at = datetime.datetime.now()
+        self.code = "123456"
+        self.created_at = datetime.datetime.now()
+        self.updated_at = datetime.datetime.now()
+
+    OBJECT_FIELDS = [
+        "id",
+        "user_id",
+        "email",
+        "expires_at",
+        "code",
+        "created_at",
+        "updated_at",
+    ]

workos/resources/user_management.py

@@ -90,12 +90,31 @@ class WorkOSInvitation(WorkOSBaseResource):
         "revoked_at",
         "expires_at",
         "token",
+        "accept_invitation_url",
         "organization_id",
         "created_at",
         "updated_at",
     ]
 
 
+class WorkOSMagicAuth(WorkOSBaseResource):
+    """Representation of a MagicAuth object as returned by WorkOS through User Management features.
+
+    Attributes:
+        OBJECT_FIELDS (list): List of fields a WorkOSMagicAuth comprises.
+    """
+
+    OBJECT_FIELDS = [
+        "id",
+        "user_id",
+        "email",
+        "expires_at",
+        "code",
+        "created_at",
+        "updated_at",
+    ]
+
+
 class WorkOSOrganizationMembership(WorkOSBaseResource):
     """Representation of an Organization Membership as returned by WorkOS through User Management features.
 

workos/user_management.py

@@ -1,11 +1,13 @@
 from requests import Request
+from warnings import warn
 import workos
 from workos.resources.list import WorkOSListResource
 from workos.resources.mfa import WorkOSAuthenticationFactorTotp, WorkOSChallenge
 from workos.resources.user_management import (
     WorkOSAuthenticationResponse,
     WorkOSRefreshTokenAuthenticationResponse,
     WorkOSInvitation,
+    WorkOSMagicAuth,
     WorkOSOrganizationMembership,
     WorkOSPasswordChallengeResponse,
     WorkOSUser,
@@ -32,6 +34,8 @@
 USER_RESET_PASSWORD_PATH = "user_management/password_reset/confirm"
 USER_SEND_VERIFICATION_EMAIL_PATH = "user_management/users/{0}/email_verification/send"
 USER_VERIFY_EMAIL_CODE_PATH = "user_management/users/{0}/email_verification/confirm"
+MAGIC_AUTH_DETAIL_PATH = "user_management/magic_auth/{0}"
+MAGIC_AUTH_PATH = "user_management/magic_auth"
 USER_SEND_MAGIC_AUTH_PATH = "user_management/magic_auth/send"
 USER_AUTH_FACTORS_PATH = "user_management/users/{0}/auth_factors"
 INVITATION_PATH = "user_management/invitations"
@@ -872,16 +876,74 @@ def verify_email(
 
         return WorkOSUser.construct_from_response(response["user"]).to_dict()
 
+    def get_magic_auth(self, magic_auth_id):
+        """Get the details of a Magic Auth object.
+
+        Args:
+            magic_auth_id (str) -  The unique ID of the Magic Auth object.
+
+        Returns:
+            dict: MagicAuth response from WorkOS.
+        """
+        headers = {}
+
+        response = self.request_helper.request(
+            MAGIC_AUTH_DETAIL_PATH.format(magic_auth_id),
+            method=REQUEST_METHOD_GET,
+            headers=headers,
+            token=workos.api_key,
+        )
+
+        return WorkOSMagicAuth.construct_from_response(response).to_dict()
+
+    def create_magic_auth(
+        self,
+        email,
+        invitation_token=None,
+    ):
+        """Creates a Magic Auth code challenge that can be sent to a user's email for authentication.
+
+        Args:
+            email: The email address of the user.
+            invitation_token: The token of an Invitation, if required. (Optional)
+
+        Returns:
+            dict: MagicAuth response from WorkOS.
+        """
+        headers = {}
+
+        params = {
+            "email": email,
+            "invitation_token": invitation_token,
+        }
+
+        response = self.request_helper.request(
+            MAGIC_AUTH_PATH,
+            method=REQUEST_METHOD_POST,
+            params=params,
+            headers=headers,
+            token=workos.api_key,
+        )
+
+        return WorkOSMagicAuth.construct_from_response(response).to_dict()
+
     def send_magic_auth_code(
         self,
         email,
     ):
         """Creates a one-time Magic Auth code and emails it to the user.
 
+        Deprecated: Please use `create_magic_auth` instead. This method will be removed in a future major version.
+
         Kwargs:
             email (str): The email address the one-time code will be sent to.
         """
 
+        warn(
+            "'send_magic_auth_code' is deprecated. Please use 'create_magic_auth' instead. This method will be removed in a future major version.",
+            DeprecationWarning,
+        )
+
         headers = {}
 
         payload = {