Add domain_data to Organization API and deprecate domains (#257)

* Add `domain_data` to Organization API and deprecate domains

* lint

* Update `update_organization` and tests

* s/status/state

---------

Co-authored-by: Michael Hadley <[email protected]>

Author: oliverzheng

tests/test_organizations.py

@@ -185,18 +185,41 @@ def test_get_organization(self, mock_organization, mock_request_method):
 
         assert organization == mock_organization
 
-    def test_create_organization(self, mock_organization, mock_request_method):
+    def test_create_organization_with_domain_data(
+        self, mock_organization, mock_request_method
+    ):
         mock_request_method("post", mock_organization, 201)
 
-        payload = {"domains": ["example.com"], "name": "Test Organization"}
+        payload = {
+            "domain_data": [{"domain": "example.com", "state": "verified"}],
+            "name": "Test Organization",
+        }
         organization = self.organizations.create_organization(payload)
 
         assert organization["id"] == "org_01EHT88Z8J8795GZNQ4ZP1J81T"
         assert organization["name"] == "Foo Corporation"
 
+    def test_create_organization_with_domains(
+        self, mock_organization, mock_request_method
+    ):
+        mock_request_method("post", mock_organization, 201)
+
+        payload = {"domains": ["example.com"], "name": "Test Organization"}
+        with pytest.warns(
+            DeprecationWarning,
+            match="The 'domains' parameter for 'create_organization' is deprecated.",
+        ):
+            organization = self.organizations.create_organization(payload)
+
+        assert organization["id"] == "org_01EHT88Z8J8795GZNQ4ZP1J81T"
+        assert organization["name"] == "Foo Corporation"
+
     def test_sends_idempotency_key(self, capture_and_mock_request):
         idempotency_key = "test_123456789"
-        payload = {"domains": ["example.com"], "name": "Foo Corporation"}
+        payload = {
+            "domain_data": [{"domain": "example.com", "state": "verified"}],
+            "name": "Foo Corporation",
+        }
 
         _, request_kwargs = capture_and_mock_request("post", payload, 200)
 
@@ -207,13 +230,15 @@ def test_sends_idempotency_key(self, capture_and_mock_request):
         assert request_kwargs["headers"]["idempotency-key"] == idempotency_key
         assert response["name"] == "Foo Corporation"
 
-    def test_update_organization(self, mock_organization_updated, mock_request_method):
+    def test_update_organization_with_domain_data(
+        self, mock_organization_updated, mock_request_method
+    ):
         mock_request_method("put", mock_organization_updated, 201)
 
         updated_organization = self.organizations.update_organization(
             organization="org_01EHT88Z8J8795GZNQ4ZP1J81T",
             name="Example Organization",
-            domains=["example.io"],
+            domain_data=[{"domain": "example.io", "state": "verified"}],
             allow_profiles_outside_organization=True,
         )
 
@@ -228,6 +253,33 @@ def test_update_organization(self, mock_organization_updated, mock_request_metho
         ]
         assert updated_organization["allow_profiles_outside_organization"]
 
+    def test_update_organization_with_domains(
+        self, mock_organization_updated, mock_request_method
+    ):
+        mock_request_method("put", mock_organization_updated, 201)
+
+        with pytest.warns(
+            DeprecationWarning,
+            match="The 'domains' parameter for 'update_organization' is deprecated.",
+        ):
+            updated_organization = self.organizations.update_organization(
+                organization="org_01EHT88Z8J8795GZNQ4ZP1J81T",
+                name="Example Organization",
+                domains=["example.io"],
+                allow_profiles_outside_organization=True,
+            )
+
+        assert updated_organization["id"] == "org_01EHT88Z8J8795GZNQ4ZP1J81T"
+        assert updated_organization["name"] == "Example Organization"
+        assert updated_organization["domains"] == [
+            {
+                "domain": "example.io",
+                "object": "organization_domain",
+                "id": "org_domain_01EHT88Z8WZEFWYPM6EC9BX2R8",
+            }
+        ]
+        assert updated_organization["allow_profiles_outside_organization"]
+
     def test_delete_organization(self, setup, mock_raw_request_method):
         mock_raw_request_method(
             "delete",

tests/utils/fixtures/mock_organization.py

@@ -10,7 +10,13 @@ def __init__(self, id):
         self.allow_profiles_outside_organization = False
         self.created_at = datetime.datetime.now()
         self.updated_at = datetime.datetime.now()
-        self.domains = ["domain1.com"]
+        self.domains = [
+            {
+                "domain": "example.io",
+                "object": "organization_domain",
+                "id": "org_domain_01EHT88Z8WZEFWYPM6EC9BX2R8",
+            }
+        ]
 
     OBJECT_FIELDS = [
         "id",

workos/organizations.py

@@ -178,7 +178,9 @@ def create_organization(self, organization, idempotency_key=None):
                 organization[allow_profiles_outside_organization] (boolean) - Whether Connections
                     within the Organization allow profiles that are outside of the Organization's
                     configured User Email Domains. (Optional)
-                organization[domains] (list) - List of domains that belong to the organization
+                organization[domain_data] (list[dict]) - List of domains that belong to the organization.
+                    organization[domain_data][][domain] - The domain of the organization.
+                    organization[domain_data][][state] - The state of the domain: either 'verified' or 'pending'.
             idempotency_key (str) - Idempotency key for creating an organization. (Optional)
 
         Returns:
@@ -188,6 +190,12 @@ def create_organization(self, organization, idempotency_key=None):
         if idempotency_key:
             headers["idempotency-key"] = idempotency_key
 
+        if "domains" in organization:
+            warn(
+                "The 'domains' parameter for 'create_organization' is deprecated. Please use 'domain_data' instead.",
+                DeprecationWarning,
+            )
+
         response = self.request_helper.request(
             ORGANIZATIONS_PATH,
             method=REQUEST_METHOD_POST,
@@ -199,7 +207,12 @@ def create_organization(self, organization, idempotency_key=None):
         return WorkOSOrganization.construct_from_response(response).to_dict()
 
     def update_organization(
-        self, organization, name, allow_profiles_outside_organization=None, domains=None
+        self,
+        organization,
+        name,
+        allow_profiles_outside_organization=None,
+        domains=None,
+        domain_data=None,
     ):
         """Update an organization
 
@@ -209,14 +222,24 @@ def update_organization(
             allow_profiles_outside_organization (boolean) - Whether Connections
                 within the Organization allow profiles that are outside of the Organization's
                 configured User Email Domains. (Optional)
-            domains (list) - List of domains that belong to the organization. (Optional)
+            domains (list) - [Deprecated] Use domain_data instead. List of domains that belong to the organization. (Optional)
+            domain_data (list[dict]) - List of domains that belong to the organization. (Optional)
+                domain_data[][domain] - The domain of the organization.
+                domain_data[][state] - The state of the domain: either 'verified' or 'pending'.
 
         Returns:
             dict: Updated Organization response from WorkOS.
         """
+        if domains:
+            warn(
+                "The 'domains' parameter for 'update_organization' is deprecated. Please use 'domain_data' instead.",
+                DeprecationWarning,
+            )
+
         params = {
             "name": name,
             "domains": domains,
+            "domain_data": domain_data,
             "allow_profiles_outside_organization": allow_profiles_outside_organization,
         }
         response = self.request_helper.request(