feat: support status field on user create, document invite caveat

Adds an optional `status` parameter to `mgmt.user.create()` (sync and
async), matching the status field already supported by the create-user
API and by `patch()`. Also documents in the README that `invite` only
controls whether an invitation message is sent, not the resulting user
status.

Author: ruvenzx

README.md

@@ -700,6 +700,11 @@ descope_client.mgmt.user.invite(
     invite_url="invite.me"
 )
 
+# NOTE: `invite` only controls whether an invitation message is sent - it does NOT
+# change the user's status. A newly invited user starts out in the "invited" status,
+# not "enabled". If your use case requires the user to be active immediately, set
+# `status="enabled"` explicitly via `create`/`patch`, or call `activate()` afterwards.
+
 # Batch invite
 descope_client.mgmt.user.invite_batch(
     users=[

descope/management/_user_base.py

@@ -95,6 +95,7 @@ def _compose_create_body(
         sso_app_ids: Optional[List[str]] = None,
         template_id: str = "",
         locale: Optional[str] = None,
+        status: Optional[str] = None,
     ) -> dict:
         body = UserBase._compose_update_body(
             login_id=login_id,
@@ -127,6 +128,8 @@ def _compose_create_body(
             body["templateId"] = template_id
         if locale is not None:
             body["locale"] = locale
+        if status is not None:
+            body["status"] = status
         return body
 
     @staticmethod

descope/management/user.py

@@ -32,6 +32,7 @@ def create(
         invite_url: Optional[str] = None,
         additional_login_ids: Optional[List[str]] = None,
         sso_app_ids: Optional[List[str]] = None,
+        status: Optional[str] = None,
     ) -> dict:
         """
         Create a new user. Users can have any number of optional fields, including email, phone number and authorization.
@@ -48,6 +49,7 @@ def create(
         picture (str): Optional url for user picture
         custom_attributes (dict): Optional, set the different custom attributes values of the keys that were previously configured in Descope console app
         sso_app_ids (List[str]): Optional, list of SSO applications IDs to be associated with the user.
+        status (str): Optional status field. Can be one of: "enabled", "disabled", "invited", "expired".
 
         Return value (dict):
         Return dict in the format
@@ -57,6 +59,17 @@ def create(
         Raise:
         AuthException: raised if create operation fails
         """
+        if status is not None and status not in [
+            "enabled",
+            "disabled",
+            "invited",
+            "expired",
+        ]:
+            raise AuthException(
+                400,
+                ERROR_TYPE_INVALID_ARGUMENT,
+                f"Invalid status value: {status}. Must be one of: enabled, disabled, invited, expired",
+            )
         role_names = [] if role_names is None else role_names
         user_tenants = [] if user_tenants is None else user_tenants
 
@@ -83,6 +96,7 @@ def create(
                 None,
                 additional_login_ids,
                 sso_app_ids,
+                status=status,
             ),
         )
         return response.json()

descope/management/user_async.py

@@ -36,6 +36,7 @@ async def create(
         invite_url: Optional[str] = None,
         additional_login_ids: Optional[List[str]] = None,
         sso_app_ids: Optional[List[str]] = None,
+        status: Optional[str] = None,
     ) -> dict:
         """
         Create a new user. Users can have any number of optional fields, including email, phone number and authorization.
@@ -52,6 +53,7 @@ async def create(
         picture (str): Optional url for user picture
         custom_attributes (dict): Optional, set the different custom attributes values of the keys that were previously configured in Descope console app
         sso_app_ids (List[str]): Optional, list of SSO applications IDs to be associated with the user.
+        status (str): Optional status field. Can be one of: "enabled", "disabled", "invited", "expired".
 
         Return value (dict):
         Return dict in the format
@@ -61,6 +63,17 @@ async def create(
         Raise:
         AuthException: raised if create operation fails
         """
+        if status is not None and status not in [
+            "enabled",
+            "disabled",
+            "invited",
+            "expired",
+        ]:
+            raise AuthException(
+                400,
+                ERROR_TYPE_INVALID_ARGUMENT,
+                f"Invalid status value: {status}. Must be one of: enabled, disabled, invited, expired",
+            )
         role_names = [] if role_names is None else role_names
         user_tenants = [] if user_tenants is None else user_tenants
 
@@ -87,6 +100,7 @@ async def create(
                 None,
                 additional_login_ids,
                 sso_app_ids,
+                status=status,
             ),
         )
         return response.json()

tests/management/test_user.py

@@ -25,6 +25,12 @@ async def test_create(self, client_factory):
             with pytest.raises(AuthException):
                 await client.invoke(client.mgmt.user.create("valid-id"))
 
+        with pytest.raises(AuthException) as exc_info:
+            await client.invoke(
+                client.mgmt.user.create("valid-id", status="invalid_status")
+            )
+        assert "Invalid status value: invalid_status" in str(exc_info.value)
+
         # Test success flow
         with client.mock_mgmt_post(make_response({"user": {"id": "u1"}})) as mock_post:
             resp = await client.invoke(
@@ -40,6 +46,7 @@ async def test_create(self, client_factory):
                     custom_attributes={"ak": "av"},
                     additional_login_ids=["id-1", "id-2"],
                     sso_app_ids=["app1", "app2"],
+                    status="disabled",
                 )
             )
             user = resp["user"]
@@ -70,6 +77,7 @@ async def test_create(self, client_factory):
                     "invite": False,
                     "additionalLoginIds": ["id-1", "id-2"],
                     "ssoAppIDs": ["app1", "app2"],
+                    "status": "disabled",
                 },
                 follow_redirects=False,
             )