workos 1.13.0__py3-none-any.whl → 5.38.0__py3-none-any.whl

workos/mfa.py

@@ -1,169 +1,205 @@
-from warnings import warn
+from typing import Optional, Protocol
 
-import workos
-from workos.utils.request import (
-    RequestHelper,
+from workos.types.mfa.enroll_authentication_factor_type import (
+    EnrollAuthenticationFactorType,
+)
+from workos.utils.http_client import SyncHTTPClient
+from workos.utils.request_helper import (
     REQUEST_METHOD_POST,
+    REQUEST_METHOD_DELETE,
+    REQUEST_METHOD_GET,
+    RequestHelper,
+)
+from workos.types.mfa import (
+    AuthenticationChallenge,
+    AuthenticationChallengeVerificationResponse,
+    AuthenticationFactor,
+    AuthenticationFactorExtended,
+    AuthenticationFactorSms,
+    AuthenticationFactorTotp,
+    AuthenticationFactorTotpExtended,
 )
-from workos.utils.validation import MFA_MODULE, validate_settings
-from workos.resources.mfa import WorkOSChallenge
-
-
-class Mfa(object):
-    """Methods to assist in creating, challenging, and verifying Authentication Factors through the WorkOS MFA service."""
 
-    @validate_settings(MFA_MODULE)
-    def __init__(self):
-        pass
 
-    @property
-    def request_helper(self):
-        if not getattr(self, "_request_helper", None):
-            self._request_helper = RequestHelper()
-        return self._request_helper
+class MFAModule(Protocol):
+    """Offers methods through the WorkOS MFA service."""
 
     def enroll_factor(
         self,
-        type=None,
-        totp_issuer=None,
-        totp_user=None,
-        phone_number=None,
-    ):
+        *,
+        type: EnrollAuthenticationFactorType,
+        totp_issuer: Optional[str] = None,
+        totp_user: Optional[str] = None,
+        phone_number: Optional[str] = None,
+    ) -> AuthenticationFactorExtended:
         """
         Defines the type of MFA authorization factor to be used. Possible values are sms or totp.
 
         Kwargs:
-            type (str) - The type of factor to be enrolled (sms or totp)
-            totp_issuer (str) - Name of the Organization
-            totp_user (str) - email of user
-            phone_number (str) - phone number of the user
+            type (str): The type of factor to be enrolled (sms or totp).
+            totp_issuer (str): Name of the Organization. Required when type is totp, ignored otherwise.
+            totp_user (str): email of user. Required when type is totp, ignored otherwise.
+            phone_number (str): phone number of the user. (Optional)
 
-        Returns: Dict containing the authentication factor information.
+        Returns:
+            AuthenticationFactor:
         """
+        ...
 
-        params = {
-            "type": type,
-            "totp_issuer": totp_issuer,
-            "totp_user": totp_user,
-            "phone_number": phone_number,
-        }
+    def get_factor(self, authentication_factor_id: str) -> AuthenticationFactor:
+        """
+        Returns an authorization factor from its ID.
 
-        if type is None:
-            raise ValueError("Incomplete arguments. Need to specify a type of factor")
+        Args:
+            authentication_factor_id (str): The ID of the factor to be obtained.
 
-        if type not in ["sms", "totp"]:
-            raise ValueError("Type parameter must be either 'sms' or 'totp'")
+        Returns:
+            AuthenticationFactor: AuthenticationFactor response from WorkOS.
+        """
+        ...
 
-        if (
-            type == "totp"
-            and totp_issuer is None
-            or type == "totp"
-            and totp_user is None
-        ):
-            raise ValueError(
-                "Incomplete arguments. Need to specify both totp_issuer and totp_user when type is totp"
-            )
+    def delete_factor(self, authentication_factor_id: str) -> None:
+        """
+        Deletes an MFA authorization factor.
 
-        if type == "sms" and phone_number is None:
-            raise ValueError(
-                "Incomplete arguments. Need to specify phone_number when type is sms"
-            )
+        Args:
+            authentication_factor_id (str): The ID of the authorization factor to be deleted.
 
-        return self.request_helper.request(
-            "auth/factors/enroll",
-            method=REQUEST_METHOD_POST,
-            params=params,
-            token=workos.api_key,
-        )
+        Returns:
+            None
+        """
+        ...
 
     def challenge_factor(
-        self,
-        authentication_factor_id=None,
-        sms_template=None,
-    ):
+        self, *, authentication_factor_id: str, sms_template: Optional[str] = None
+    ) -> AuthenticationChallenge:
         """
         Initiates the authentication process for the newly created MFA authorization factor, referred to as a challenge.
 
         Kwargs:
-            authentication_factor_id (str) - ID of the authorization factor
-            sms_template (str) - Optional parameter to customize the message for sms type factors. Must include "{{code}}" if used.
+            authentication_factor_id (str): ID of the authorization factor
+            sms_template (str): Optional parameter to customize the message for sms type factors. Must include "{{code}}" if used. (Optional)
 
-        Returns: Dict containing the authentication challenge factor details.
+        Returns:
+            AuthenticationChallenge: AuthenticationChallenge response from WorkOS.
         """
+        ...
 
-        params = {
-            "sms_template": sms_template,
+    def verify_challenge(
+        self, *, authentication_challenge_id: str, code: str
+    ) -> AuthenticationChallengeVerificationResponse:
+        """
+        Verifies the one time password provided by the end-user.
+
+        Kwargs:
+            authentication_challenge_id (str): The ID of the authentication challenge that provided the user the verification code.
+            code (str): The verification code sent to and provided by the end user.
+
+        Returns:
+            AuthenticationChallengeVerificationResponse: AuthenticationChallengeVerificationResponse response from WorkOS.
+        """
+        ...
+
+
+class Mfa(MFAModule):
+    """Methods to assist in creating, challenging, and verifying Authentication Factors through the WorkOS MFA service."""
+
+    _http_client: SyncHTTPClient
+
+    def __init__(self, http_client: SyncHTTPClient):
+        self._http_client = http_client
+
+    def enroll_factor(
+        self,
+        *,
+        type: EnrollAuthenticationFactorType,
+        totp_issuer: Optional[str] = None,
+        totp_user: Optional[str] = None,
+        phone_number: Optional[str] = None,
+    ) -> AuthenticationFactorExtended:
+        json = {
+            "type": type,
+            "totp_issuer": totp_issuer,
+            "totp_user": totp_user,
+            "phone_number": phone_number,
         }
 
-        if authentication_factor_id is None:
+        if type == "totp" and (totp_issuer is None or totp_user is None):
             raise ValueError(
-                "Incomplete arguments: 'authentication_factor_id' is a required parameter"
+                "Incomplete arguments. Need to specify both totp_issuer and totp_user when type is totp"
             )
 
-        response = self.request_helper.request(
-            "auth/factors/{factor_id}/challenge".format(
-                factor_id=authentication_factor_id
-            ),
-            method=REQUEST_METHOD_POST,
-            params=params,
-            token=workos.api_key,
+        if type == "sms" and phone_number is None:
+            raise ValueError(
+                "Incomplete arguments. Need to specify phone_number when type is sms"
+            )
+
+        response = self._http_client.request(
+            "auth/factors/enroll", method=REQUEST_METHOD_POST, json=json
         )
 
-        return WorkOSChallenge.construct_from_response(response).to_dict()
+        if type == "totp":
+            return AuthenticationFactorTotpExtended.model_validate(response)
 
-    def verify_factor(
-        self,
-        authentication_challenge_id=None,
-        code=None,
-    ):
-        """
-        Verifies the one time password provided by the end-user.
+        return AuthenticationFactorSms.model_validate(response)
 
-        Deprecated: Please use `verify_challenge` instead.
+    def get_factor(self, authentication_factor_id: str) -> AuthenticationFactor:
+        response = self._http_client.request(
+            RequestHelper.build_parameterized_url(
+                "auth/factors/{authentication_factor_id}",
+                authentication_factor_id=authentication_factor_id,
+            ),
+            method=REQUEST_METHOD_GET,
+        )
 
-        Kwargs:
-            authentication_challenge_id (str) - The ID of the authentication challenge that provided the user the verification code.
-            code (str) - The verification code sent to and provided by the end user.
+        if response["type"] == "totp":
+            return AuthenticationFactorTotp.model_validate(response)
 
-        Returns: Dict containing the  challenge factor details.
-        """
+        return AuthenticationFactorSms.model_validate(response)
 
-        warn(
-            "'verify_factor' is deprecated. Please use 'verify_challenge' instead.",
-            DeprecationWarning,
+    def delete_factor(self, authentication_factor_id: str) -> None:
+        self._http_client.request(
+            RequestHelper.build_parameterized_url(
+                "auth/factors/{authentication_factor_id}",
+                authentication_factor_id=authentication_factor_id,
+            ),
+            method=REQUEST_METHOD_DELETE,
         )
 
-        return self.verify_challenge(authentication_challenge_id, code)
-
-    def verify_challenge(
+    def challenge_factor(
         self,
-        authentication_challenge_id=None,
-        code=None,
-    ):
-        """
-        Verifies the one time password provided by the end-user.
+        *,
+        authentication_factor_id: str,
+        sms_template: Optional[str] = None,
+    ) -> AuthenticationChallenge:
+        json = {
+            "sms_template": sms_template,
+        }
 
-        Kwargs:
-            authentication_challenge_id (str) - The ID of the authentication challenge that provided the user the verification code.
-            code (str) - The verification code sent to and provided by the end user.
+        response = self._http_client.request(
+            RequestHelper.build_parameterized_url(
+                "auth/factors/{factor_id}/challenge", factor_id=authentication_factor_id
+            ),
+            method=REQUEST_METHOD_POST,
+            json=json,
+        )
 
-        Returns: Dict containing the  challenge factor details.
-        """
+        return AuthenticationChallenge.model_validate(response)
 
-        params = {
+    def verify_challenge(
+        self, *, authentication_challenge_id: str, code: str
+    ) -> AuthenticationChallengeVerificationResponse:
+        json = {
             "code": code,
         }
 
-        if authentication_challenge_id is None or code is None:
-            raise ValueError(
-                "Incomplete arguments: 'authentication_challenge_id' and 'code' are required parameters"
-            )
-
-        return self.request_helper.request(
-            "auth/challenges/{challenge_id}/verify".format(
-                challenge_id=authentication_challenge_id
+        response = self._http_client.request(
+            RequestHelper.build_parameterized_url(
+                "auth/challenges/{challenge_id}/verify",
+                challenge_id=authentication_challenge_id,
             ),
             method=REQUEST_METHOD_POST,
-            params=params,
-            token=workos.api_key,
+            json=json,
         )
+
+        return AuthenticationChallengeVerificationResponse.model_validate(response)

workos/organization_domains.py

@@ -0,0 +1,179 @@
+from typing import Protocol
+from workos._client_configuration import ClientConfiguration
+from workos.types.organization_domains import OrganizationDomain
+from workos.typing.sync_or_async import SyncOrAsync
+from workos.utils.http_client import AsyncHTTPClient, SyncHTTPClient
+from workos.utils.request_helper import (
+    REQUEST_METHOD_DELETE,
+    REQUEST_METHOD_GET,
+    REQUEST_METHOD_POST,
+)
+
+
+class OrganizationDomainsModule(Protocol):
+    """Offers methods for managing organization domains."""
+
+    _client_configuration: ClientConfiguration
+
+    def get_organization_domain(
+        self, organization_domain_id: str
+    ) -> SyncOrAsync[OrganizationDomain]:
+        """Gets a single Organization Domain
+
+        Args:
+            organization_domain_id (str): Organization Domain unique identifier
+
+        Returns:
+            OrganizationDomain: Organization Domain response from WorkOS
+        """
+        ...
+
+    def create_organization_domain(
+        self,
+        organization_id: str,
+        domain: str,
+    ) -> SyncOrAsync[OrganizationDomain]:
+        """Creates an Organization Domain
+
+        Args:
+            organization_id (str): Organization unique identifier
+            domain (str): Domain to be added to the organization
+
+        Returns:
+            OrganizationDomain: Organization Domain response from WorkOS
+        """
+        ...
+
+    def verify_organization_domain(
+        self, organization_domain_id: str
+    ) -> SyncOrAsync[OrganizationDomain]:
+        """Verifies an Organization Domain
+
+        Args:
+            organization_domain_id (str): Organization Domain unique identifier
+
+        Returns:
+            OrganizationDomain: Organization Domain response from WorkOS
+        """
+        ...
+
+    def delete_organization_domain(
+        self, organization_domain_id: str
+    ) -> SyncOrAsync[None]:
+        """Deletes a single Organization Domain
+
+        Args:
+            organization_domain_id (str): Organization Domain unique identifier
+
+        Returns:
+            None
+        """
+        ...
+
+
+class OrganizationDomains:
+    """Offers methods for managing organization domains."""
+
+    _http_client: SyncHTTPClient
+    _client_configuration: ClientConfiguration
+
+    def __init__(
+        self,
+        http_client: SyncHTTPClient,
+        client_configuration: ClientConfiguration,
+    ):
+        self._http_client = http_client
+        self._client_configuration = client_configuration
+
+    def get_organization_domain(
+        self, organization_domain_id: str
+    ) -> OrganizationDomain:
+        response = self._http_client.request(
+            f"organization_domains/{organization_domain_id}",
+            method=REQUEST_METHOD_GET,
+        )
+
+        return OrganizationDomain.model_validate(response)
+
+    def create_organization_domain(
+        self,
+        organization_id: str,
+        domain: str,
+    ) -> OrganizationDomain:
+        response = self._http_client.request(
+            "organization_domains",
+            method=REQUEST_METHOD_POST,
+            json={"organization_id": organization_id, "domain": domain},
+        )
+
+        return OrganizationDomain.model_validate(response)
+
+    def verify_organization_domain(
+        self, organization_domain_id: str
+    ) -> OrganizationDomain:
+        response = self._http_client.request(
+            f"organization_domains/{organization_domain_id}/verify",
+            method=REQUEST_METHOD_POST,
+        )
+
+        return OrganizationDomain.model_validate(response)
+
+    def delete_organization_domain(self, organization_domain_id: str) -> None:
+        self._http_client.request(
+            f"organization_domains/{organization_domain_id}",
+            method=REQUEST_METHOD_DELETE,
+        )
+
+
+class AsyncOrganizationDomains:
+    """Offers async methods for managing organization domains."""
+
+    _http_client: AsyncHTTPClient
+    _client_configuration: ClientConfiguration
+
+    def __init__(
+        self,
+        http_client: AsyncHTTPClient,
+        client_configuration: ClientConfiguration,
+    ):
+        self._http_client = http_client
+        self._client_configuration = client_configuration
+
+    async def get_organization_domain(
+        self, organization_domain_id: str
+    ) -> OrganizationDomain:
+        response = await self._http_client.request(
+            f"organization_domains/{organization_domain_id}",
+            method=REQUEST_METHOD_GET,
+        )
+
+        return OrganizationDomain.model_validate(response)
+
+    async def create_organization_domain(
+        self,
+        organization_id: str,
+        domain: str,
+    ) -> OrganizationDomain:
+        response = await self._http_client.request(
+            "organization_domains",
+            method=REQUEST_METHOD_POST,
+            json={"organization_id": organization_id, "domain": domain},
+        )
+
+        return OrganizationDomain.model_validate(response)
+
+    async def verify_organization_domain(
+        self, organization_domain_id: str
+    ) -> OrganizationDomain:
+        response = await self._http_client.request(
+            f"organization_domains/{organization_domain_id}/verify",
+            method=REQUEST_METHOD_POST,
+        )
+
+        return OrganizationDomain.model_validate(response)
+
+    async def delete_organization_domain(self, organization_domain_id: str) -> None:
+        await self._http_client.request(
+            f"organization_domains/{organization_domain_id}",
+            method=REQUEST_METHOD_DELETE,
+        )