Add metadata and external id to users and organizations (#420)

* Add external_id to user and organization

Add a method to get users by external id.

Change organization get by lookup key which no longer works to be get by
external id.

* Add metadata to users and organizations

Eventually the API will always return something, but for now we can
default to an empty object (which is what the API will eventually
return).

* Add external id and metadata to user update and create

* Create and update organizations with external id and metadata

Author: ericroberts

tests/test_organizations.py

@@ -109,20 +109,20 @@ def test_get_organization(
         assert request_kwargs["method"] == "get"
         assert request_kwargs["url"].endswith("/organizations/organization_id")
 
-    def test_get_organization_by_lookup_key(
+    def test_get_organization_by_external_id(
         self, mock_organization, capture_and_mock_http_client_request
     ):
         request_kwargs = capture_and_mock_http_client_request(
             self.http_client, mock_organization, 200
         )
 
         organization = syncify(
-            self.organizations.get_organization_by_lookup_key(lookup_key="test")
+            self.organizations.get_organization_by_external_id(external_id="test")
         )
 
         assert organization.dict() == mock_organization
         assert request_kwargs["method"] == "get"
-        assert request_kwargs["url"].endswith("/organizations/by_lookup_key/test")
+        assert request_kwargs["url"].endswith("/organizations/external_id/test")
 
     def test_create_organization_with_domain_data(
         self, mock_organization, capture_and_mock_http_client_request

tests/test_user_management.py

@@ -392,6 +392,27 @@ def test_get_user(self, mock_user, capture_and_mock_http_client_request):
         assert user.profile_picture_url == "https://example.com/profile-picture.jpg"
         assert user.last_sign_in_at == "2021-06-25T19:07:33.155Z"
 
+    def test_get_user_by_external_id(
+        self, mock_user, capture_and_mock_http_client_request
+    ):
+        request_kwargs = capture_and_mock_http_client_request(
+            self.http_client, mock_user, 200
+        )
+
+        external_id = "external-id"
+        user = syncify(
+            self.user_management.get_user_by_external_id(external_id=external_id)
+        )
+
+        assert request_kwargs["url"].endswith(
+            f"user_management/users/external_id/{external_id}"
+        )
+        assert request_kwargs["method"] == "get"
+        assert user.id == "user_01H7ZGXFP5C6BBQY6Z7277ZCT0"
+        assert user.profile_picture_url == "https://example.com/profile-picture.jpg"
+        assert user.last_sign_in_at == "2021-06-25T19:07:33.155Z"
+        assert user.metadata == mock_user["metadata"]
+
     def test_list_users_auto_pagination(
         self,
         mock_users_multiple_pages,

tests/utils/fixtures/mock_organization.py

@@ -22,4 +22,5 @@ def __init__(self, id):
                     domain="example.io",
                 )
             ],
+            metadata={"key": "value"},
         )

tests/utils/fixtures/mock_user.py

@@ -17,4 +17,5 @@ def __init__(self, id):
             last_sign_in_at="2021-06-25T19:07:33.155Z",
             created_at=now,
             updated_at=now,
+            metadata={"key": "value"},
         )

workos/organizations.py

@@ -1,5 +1,6 @@
 from typing import Optional, Protocol, Sequence
 
+from workos.types.metadata import Metadata
 from workos.types.organizations.domain_data_input import DomainDataInput
 from workos.types.organizations.list_filters import OrganizationListFilters
 from workos.types.roles.role import RoleList
@@ -60,13 +61,13 @@ def get_organization(self, organization_id: str) -> SyncOrAsync[Organization]:
         """
         ...
 
-    def get_organization_by_lookup_key(
-        self, lookup_key: str
+    def get_organization_by_external_id(
+        self, external_id: str
     ) -> SyncOrAsync[Organization]:
-        """Gets details for a single Organization by lookup key
+        """Gets details for a single Organization by external id
 
         Args:
-            lookup_key (str): Organization's lookup key
+            external_id (str): Organization's external id
 
         Returns:
             Organization: Organization response from WorkOS
@@ -79,6 +80,8 @@ def create_organization(
         name: str,
         domain_data: Optional[Sequence[DomainDataInput]] = None,
         idempotency_key: Optional[str] = None,
+        external_id: Optional[str] = None,
+        metadata: Optional[Metadata] = None,
     ) -> SyncOrAsync[Organization]:
         """Create an organization
 
@@ -98,6 +101,8 @@ def update_organization(
         organization_id: str,
         name: Optional[str] = None,
         domain_data: Optional[Sequence[DomainDataInput]] = None,
+        external_id: Optional[str] = None,
+        metadata: Optional[Metadata] = None,
     ) -> SyncOrAsync[Organization]:
         """Update an organization
 
@@ -125,7 +130,6 @@ def delete_organization(self, organization_id: str) -> SyncOrAsync[None]:
 
 
 class Organizations(OrganizationsModule):
-
     _http_client: SyncHTTPClient
 
     def __init__(self, http_client: SyncHTTPClient):
@@ -167,9 +171,9 @@ def get_organization(self, organization_id: str) -> Organization:
 
         return Organization.model_validate(response)
 
-    def get_organization_by_lookup_key(self, lookup_key: str) -> Organization:
+    def get_organization_by_external_id(self, external_id: str) -> Organization:
         response = self._http_client.request(
-            "organizations/by_lookup_key/{lookup_key}".format(lookup_key=lookup_key),
+            "organizations/external_id/{external_id}".format(external_id=external_id),
             method=REQUEST_METHOD_GET,
         )
 
@@ -181,6 +185,8 @@ def create_organization(
         name: str,
         domain_data: Optional[Sequence[DomainDataInput]] = None,
         idempotency_key: Optional[str] = None,
+        external_id: Optional[str] = None,
+        metadata: Optional[Metadata] = None,
     ) -> Organization:
         headers = {}
         if idempotency_key:
@@ -190,6 +196,8 @@ def create_organization(
             "name": name,
             "domain_data": domain_data,
             "idempotency_key": idempotency_key,
+            "external_id": external_id,
+            "metadata": metadata,
         }
 
         response = self._http_client.request(
@@ -208,11 +216,15 @@ def update_organization(
         name: Optional[str] = None,
         domain_data: Optional[Sequence[DomainDataInput]] = None,
         stripe_customer_id: Optional[str] = None,
+        external_id: Optional[str] = None,
+        metadata: Optional[Metadata] = None,
     ) -> Organization:
         json = {
             "name": name,
             "domain_data": domain_data,
             "stripe_customer_id": stripe_customer_id,
+            "external_id": external_id,
+            "metadata": metadata,
         }
 
         response = self._http_client.request(
@@ -237,7 +249,6 @@ def list_organization_roles(self, organization_id: str) -> RoleList:
 
 
 class AsyncOrganizations(OrganizationsModule):
-
     _http_client: AsyncHTTPClient
 
     def __init__(self, http_client: AsyncHTTPClient):
@@ -279,9 +290,9 @@ async def get_organization(self, organization_id: str) -> Organization:
 
         return Organization.model_validate(response)
 
-    async def get_organization_by_lookup_key(self, lookup_key: str) -> Organization:
+    async def get_organization_by_external_id(self, external_id: str) -> Organization:
         response = await self._http_client.request(
-            "organizations/by_lookup_key/{lookup_key}".format(lookup_key=lookup_key),
+            "organizations/external_id/{external_id}".format(external_id=external_id),
             method=REQUEST_METHOD_GET,
         )
 
@@ -293,6 +304,8 @@ async def create_organization(
         name: str,
         domain_data: Optional[Sequence[DomainDataInput]] = None,
         idempotency_key: Optional[str] = None,
+        external_id: Optional[str] = None,
+        metadata: Optional[Metadata] = None,
     ) -> Organization:
         headers = {}
         if idempotency_key:
@@ -302,6 +315,8 @@ async def create_organization(
             "name": name,
             "domain_data": domain_data,
             "idempotency_key": idempotency_key,
+            "external_id": external_id,
+            "metadata": metadata,
         }
 
         response = await self._http_client.request(
@@ -320,11 +335,15 @@ async def update_organization(
         name: Optional[str] = None,
         domain_data: Optional[Sequence[DomainDataInput]] = None,
         stripe_customer_id: Optional[str] = None,
+        external_id: Optional[str] = None,
+        metadata: Optional[Metadata] = None,
     ) -> Organization:
         json = {
             "name": name,
             "domain_data": domain_data,
             "stripe_customer_id": stripe_customer_id,
+            "external_id": external_id,
+            "metadata": metadata,
         }
 
         response = await self._http_client.request(

workos/types/metadata.py

@@ -0,0 +1,4 @@
+from typing import Dict
+
+
+Metadata = Dict[str, str]

workos/types/organizations/organization.py

@@ -1,10 +1,13 @@
+from dataclasses import field
 from typing import Optional, Sequence
+from workos.types.metadata import Metadata
 from workos.types.organizations.organization_common import OrganizationCommon
 from workos.types.organizations.organization_domain import OrganizationDomain
 
 
 class Organization(OrganizationCommon):
     allow_profiles_outside_organization: bool
     domains: Sequence[OrganizationDomain]
-    lookup_key: Optional[str] = None
     stripe_customer_id: Optional[str] = None
+    external_id: Optional[str] = None
+    metadata: Metadata = field(default_factory=dict)

workos/types/user_management/user.py

@@ -1,4 +1,6 @@
+from dataclasses import field
 from typing import Literal, Optional
+from workos.types.metadata import Metadata
 from workos.types.workos_model import WorkOSModel
 
 
@@ -15,3 +17,5 @@ class User(WorkOSModel):
     last_sign_in_at: Optional[str] = None
     created_at: str
     updated_at: str
+    external_id: Optional[str] = None
+    metadata: Metadata = field(default_factory=dict)