Merge pull request #35 from getoriginal/feature/ori-2209-userasset-add-external-ids-to-python-sdk

fix(ORI-2209): add external ids for user and asset

Author: don1989

README.md

@@ -9,7 +9,7 @@
     - [Create a new user](#create-a-new-user)
     - [Get a user by UID](#get-a-user-by-uid)
     - [Get a user by email](#get-a-user-by-email)
-    - [Get a user by client ID](#get-a-user-by-client-id)
+    - [Get a user by user external ID](#get-a-user-by-client-id)
   - [Asset](#asset)
     - [Create a new asset](#create-a-new-asset)
     - [Get an asset by UID](#get-an-asset-by-asset-uid)
@@ -105,9 +105,9 @@ new_user_uid = create_response['data']['uid']
     }
 }
 
-# You can also pass in a client_id and/or email for your external reference.
-# The client ID and/or email supplied must be unique per app
-create_response = client.create_user(email='YOUR_EMAIL', client_id='YOUR_CLIENT_ID')
+# You can also pass in a user_external_id and/or email for your external reference.
+# The user_external_id and/or email supplied must be unique per app
+create_response = client.create_user(email='YOUR_EMAIL', user_external_id='YOUR_USER_EXTERNAL_ID')
 new_user_uid = create_response['data']['uid']
 # ...
 ```
@@ -123,7 +123,7 @@ user_details = user_response['data']  # Contains user details such as UID, email
     "success": True,
     "data": {
         "uid": "754566475542",
-        "client_id": "user_client_id",
+        "user_external_id": "user_external_id_1",
         "created_at": "2024-02-26T13:12:31.798296Z",
         "email": "[email protected]",
         "wallet_address": "0xa22f2dfe189ed3d16bb5bda5e5763b2919058e40"
@@ -142,7 +142,7 @@ user_by_email_details = user_by_email_response['data']
     "success": True,
     "data": {
         "uid": "754566475542",
-        "client_id": "user_client_id",
+        "user_external_id": "user_external_id_1",
         "created_at": "2024-02-26T13:12:31.798296Z",
         "email": "[email protected]",
         "wallet_address": "0xa22f2dfe189ed3d16bb5bda5e5763b2919058e40"
@@ -156,24 +156,24 @@ user_by_email_details = user_by_email_response['data']
 }
 ```
 
-### Get a user by client ID
+### Get a user by user external ID
 ```python
-# Get a user by client ID
-# Retrieves a user by their client ID. If the user does not exist, `data` will be None.
-user_by_client_id_response = client.get_user_by_client_id('YOUR_CLIENT_ID')
-user_by_client_id_details = user_by_client_id_response['data']
-# Sample user_by_client_id_response on success:
+# Get a user by user external ID
+# Retrieves a user by their user external ID. If the user does not exist, `data` will be None.
+user_by_user_external_id_response = client.get_user_by_user_external_id('YOUR_USER_EXTERNAL_ID')
+user_by_user_external_details = user_by_user_external_id_response['data']
+# Sample user_by_user_external_id_response on success:
 {
     "success": True,
     "data": {
         "uid": "754566475542",
-        "client_id": "user_client_id",
+        "user_external_id": "user_external_id",
         "created_at": "2024-02-26T13:12:31.798296Z",
         "email": "[email protected]",
         "wallet_address": "0xa22f2dfe189ed3d16bb5bda5e5763b2919058e40"
     }
 }
-# Sample user_by_client_id_response on failure:
+# Sample user_by_user_external_id_response on failure:
 {
     "success": False,
     "data": None
@@ -190,7 +190,7 @@ The asset methods exposed by the sdk are used to create (mint) assets and retrie
 # prepare the new asset params
 new_asset_params = {
     "user_uid": "324167489835",
-    "client_id": "client_id_1",
+    "asset_external_id": "asset_external_id_1",
     "collection_uid": "221137489875",
     "data": {
         "name": "Dave Starbelly",
@@ -237,7 +237,7 @@ asset_details = asset_response['data']
     "data": {
         "uid": "151854912345",
         "name": "random name #2",
-        "client_id": "asset_client_id_1",
+        "asset_external_id": "asset_external_id_1",
         "collection_uid": "471616646163",
         "collection_name": "Test SDK Collection 1",
         "token_id": 2,
@@ -285,7 +285,7 @@ assets_list = assets_response['data']
         {
             "uid": "151854912345",
             "name": "random name #2",
-            "client_id": "asset_client_id_1",
+            "asset_external_id": "asset_external_id_1",
             "collection_uid": "471616646163",
             "collection_name": "Test SDK Collection 1",
             "token_id": 2,
@@ -539,7 +539,7 @@ collection_details = collection_response['data']
 ```
 
 
-### Handling Errors
+## Handling Errors
 
 If something goes wrong, you will receive well typed error messages.
 
@@ -573,7 +573,7 @@ So when an error occurs, you can either catch all using the OriginalError class:
 from original_sdk import OriginalError
 
 try:
-    result = client.create_user('invalid_email', 'client_id');
+    result = client.create_user(email='invalid_email', user_external_id='user_external_id');
 except OriginalError as e:
     # handle all errors
 ```
@@ -584,7 +584,7 @@ or specific errors:
 from original_sdk import ClientError, ServerError, ValidationError
 
 try:
-    result = client.create_user('invalid_email', 'client_id');
+    result = client.create_user(email='invalid_email', user_external_id='user_external_id');
 except ClientError as e:
     # handle client errors
 except ServerError as e:
@@ -619,7 +619,7 @@ Please note, if you plan to parse the error detail, it can also be an array if t
     #     {
     #         "code": "null",
     #         "message": "This field may not be null.",
-    #         "field_name": "client_id"
+    #         "field_name": "user_external_id"
     #     },
     #     {
     #         "code": "invalid",

original_sdk/async_client.py

@@ -1,4 +1,5 @@
 import json
+import warnings
 from types import TracebackType
 from typing import (
     Any,
@@ -126,9 +127,25 @@ async def patch(
         return await self._make_request(self.session.patch, relative_url, params, data)
 
     async def create_user(
-        self, email: Union[None, str] = None, client_id: Union[None, str] = None
+        self,
+        email: Union[None, str] = None,
+        client_id: Union[None, str] = None,
+        user_external_id: Union[None, str] = None,
     ) -> OriginalResponse:
-        return await self.post("user", data={"email": email, "client_id": client_id})
+        if client_id:
+            warnings.warn(
+                "client_id is deprecated, please use user_external_id instead",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        return await self.post(
+            "user",
+            data={
+                "email": email,
+                "client_id": client_id,
+                "user_external_id": user_external_id,
+            },
+        )
 
     async def get_user(self, uid: str) -> OriginalResponse:
         return await self.get(f"user/{uid}")
@@ -137,8 +154,18 @@ async def get_user_by_email(self, email: str) -> OriginalResponse:
         return await self.get("user", params={"email": email})
 
     async def get_user_by_client_id(self, client_id: str) -> OriginalResponse:
+        warnings.warn(
+            "get_user_by_client_id is deprecated, please use get_user_by_user_external_id instead",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         return await self.get("user", params={"client_id": client_id})
 
+    async def get_user_by_user_external_id(
+        self, user_external_id: str
+    ) -> OriginalResponse:
+        return await self.get("user", params={"user_external_id": user_external_id})
+
     async def get_collection(self, uid: str) -> OriginalResponse:
         return await self.get(f"collection/{uid}")
 

original_sdk/base/client.py

@@ -90,7 +90,10 @@ def handle_parsed_response(
 
     @abc.abstractmethod
     def create_user(
-        self, email: Union[None, str] = None, client_id: Union[None, str] = None
+        self,
+        email: Union[None, str] = None,
+        client_id: Union[None, str] = None,
+        user_external_id: Union[None, str] = None,
     ) -> Union[OriginalResponse, Awaitable[OriginalResponse]]:
         """
         Create an Original user.
@@ -116,7 +119,7 @@ def get_user_by_email(
         """
         Gets a user by email
 
-        :param email: the users email
+        :param email: the user's email
         :return:
         """
         pass
@@ -126,9 +129,23 @@ def get_user_by_client_id(
         self, client_id: str
     ) -> Union[OriginalResponse, Awaitable[OriginalResponse]]:
         """
+        Deprecated: use get_user_by_user_external_id instead.
+
         Gets a user by client_id
 
-        :param client_id: the users email
+        :param client_id: the user's client_id
+        :return:
+        """
+        pass
+
+    @abc.abstractmethod
+    def get_user_by_user_external_id(
+        self, user_external_id: str
+    ) -> Union[OriginalResponse, Awaitable[OriginalResponse]]:
+        """
+        Gets a user by user_external_id
+
+        :param user_external_id: the user's user_external_id
         :return:
         """
         pass

original_sdk/client.py

@@ -1,4 +1,5 @@
 import json
+import warnings
 from typing import Any, Callable, Dict, Tuple, Union
 
 import requests
@@ -112,9 +113,25 @@ def patch(
         return self._make_request(self.session.patch, relative_url, params, data)
 
     def create_user(
-        self, email: Union[None, str] = None, client_id: Union[None, str] = None
+        self,
+        email: Union[None, str] = None,
+        client_id: Union[None, str] = None,
+        user_external_id: Union[None, str] = None,
     ) -> OriginalResponse:
-        return self.post("user", data={"email": email, "client_id": client_id})
+        if client_id:
+            warnings.warn(
+                "client_id is deprecated, please use user_external_id instead",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        return self.post(
+            "user",
+            data={
+                "email": email,
+                "client_id": client_id,
+                "user_external_id": user_external_id,
+            },
+        )
 
     def get_user(self, uid: str) -> OriginalResponse:
         return self.get(f"user/{uid}")
@@ -123,8 +140,16 @@ def get_user_by_email(self, email: str) -> OriginalResponse:
         return self.get("user", params={"email": email})
 
     def get_user_by_client_id(self, client_id: str) -> OriginalResponse:
+        warnings.warn(
+            "get_user_by_client_id is deprecated, please use get_user_by_user_external_id instead",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         return self.get("user", params={"client_id": client_id})
 
+    def get_user_by_user_external_id(self, user_external_id: str) -> OriginalResponse:
+        return self.get("user", params={"user_external_id": user_external_id})
+
     def get_collection(self, uid: str) -> OriginalResponse:
         return self.get(f"collection/{uid}")
 

original_sdk/tests/e2e/test_async_client_e2e.py

@@ -23,7 +23,17 @@
 
 
 class TestAsyncClientE2E:
+
     async def test_create_user_with_params(self, async_client: OriginalAsyncClient):
+        user_external_id = get_random_string(8)
+        response = await async_client.create_user(
+            email=f"{user_external_id}@test.com", user_external_id=user_external_id
+        )
+        assert response["data"]["uid"] is not None
+
+    async def test_create_user_with_deprecated_client_id(
+        self, async_client: OriginalAsyncClient
+    ):
         client_id = get_random_string(8)
         response = await async_client.create_user(
             email=f"{client_id}@test.com", client_id=client_id
@@ -52,6 +62,15 @@ async def test_get_user_by_email(self, async_client: OriginalAsyncClient):
         assert response["data"]["uid"] == TEST_APP_USER_UID
         assert response["data"]["email"] == TEST_APP_USER_EMAIL
 
+    async def test_get_user_by_user_external_id(
+        self, async_client: OriginalAsyncClient
+    ):
+        response = await async_client.get_user_by_user_external_id(
+            TEST_APP_USER_CLIENT_ID
+        )
+        assert response["data"]["uid"] == TEST_APP_USER_UID
+        assert response["data"]["email"] == TEST_APP_USER_EMAIL
+
     async def test_get_user_by_client_id(self, async_client: OriginalAsyncClient):
         response = await async_client.get_user_by_client_id(TEST_APP_USER_CLIENT_ID)
         assert response["data"]["uid"] == TEST_APP_USER_UID
@@ -84,6 +103,29 @@ async def test_get_collection_not_found_throws_404(
             assert e.status == 404
 
     async def test_create_asset(self, async_client: OriginalAsyncClient):
+        asset_name = get_random_string(8)
+        asset_data = {
+            "name": asset_name,
+            "unique_name": True,
+            "image_url": "https://example.com/image.png",
+            "store_image_on_ipfs": False,
+            "attributes": [
+                {"trait_type": "Eyes", "value": "Green"},
+                {"trait_type": "Hair", "value": "Black"},
+            ],
+        }
+        request_data = {
+            "data": asset_data,
+            "user_uid": TEST_APP_USER_UID,
+            "asset_external_id": asset_name,
+            "collection_uid": TEST_APP_COLLECTION_UID,
+        }
+        response = await async_client.create_asset(**request_data)
+        assert response["data"]["uid"] is not None
+
+    async def test_create_asset_with_deprecated_client_id(
+        self, async_client: OriginalAsyncClient
+    ):
         asset_name = get_random_string(8)
         asset_data = {
             "name": asset_name,