Merge pull request #20 from MerleLiuKun/feat-url-properties

feat(URL): ✨ Add api for manage URL properties.

docs/docs/usage/business_account/url_properties.md

@@ -0,0 +1,63 @@
+## Manage URL properties
+
+Verifying ownership of video URLs is an essential step to comply with TikTok's policies around copyrighted content and user safety.
+
+More to see [Manage URL properties](https://business-api.tiktok.com/portal/docs?id=1769324038780930)
+
+### Add URL property
+
+Add a URL property (domain or URL prefix) that you want to verify ownership of, to an advertiser account.
+
+More to see [Add URL property](https://business-api.tiktok.com/portal/docs?id=1769325280876545)
+
+```python
+api.add_url_property(
+    app_id="app id",
+    property_type=1,
+    url="example.com"
+)
+# BusinessUrlPropertyInfoResponse(code=0, message='OK', request_id='202408070935578A03C337841C0A6EB22B', data=BusinessUrlPropertyInfoData(url_property_info=BusinessUrlPropertyInfo(property_type=1, url='example.com')))
+```
+
+### Check URL property verification
+
+Check the result of the ownership verification for a URL property (domain or URL prefix).
+
+More to see [Check URL property verification](https://business-api.tiktok.com/portal/docs?id=1769325308162050)
+
+```python
+api.check_url_property_verification(
+    app_id="app id",
+    property_type=1,
+    url="example.com"
+)
+# BusinessUrlPropertyInfoResponse(code=0, message='OK', request_id='202408070935578A03C337841C0A6EB22B', data=BusinessUrlPropertyInfoData(url_property_info=BusinessUrlPropertyInfo(property_type=1, url='example.com')))
+```
+
+### Delete URL property
+
+Delete an advertiser account's verified ownership of a URL property (domain or URL prefix).
+
+More to see [Delete URL property](https://business-api.tiktok.com/portal/docs?id=1769325351919617)
+
+```python
+api.delete_url_property(
+    app_id="app id",
+    property_type=1,
+    url="example.com"
+)
+# BusinessBaseResponse(code=0, message='OK', request_id='202408070935578A03C337841C0A6EB22B')
+```
+
+### Get added URL properties
+
+Get the list of URL properties that have been added to an advertiser account.
+
+More to see [Get added URL properties](https://business-api.tiktok.com/portal/docs?id=1769325368603650)
+
+```python
+api.get_added_url_properties(
+    app_id="app id"
+)
+# BusinessUrlPropertyInfoListResponse(code=0, message='OK', request_id='2024080709351926240BB44FDD60705E4E', data=BusinessUrlPropertyInfoListData(url_property_info_list=[BusinessUrlPropertyInfo(property_type=1, url='example.com'), BusinessUrlPropertyInfo(property_type=1, url='sub.example.com')]))
+``` 

docs/docs/usage/business_account/video.md

@@ -39,6 +39,27 @@ api.create_video(
 # Response: {"code":0,"message":"Ok","request_id":"20210817034316010245031056097316BA","data":{"share_id":"videopublish.8111673464968467978"}}
 ```
 
-Now your video has submitted to TikTok, Once video been processed, video publish status will send by webhook.
+### Publish photo post
 
-More see [Webhook events](https://ads.tiktok.com/marketing_api/docs?id=1733584763973634).
+Publish a photo post to an owned TikTok Account.
+
+```python
+api.create_photo(
+    business_id="business id",
+    photo_images=[
+        "https://example.com/photo1.jpg",
+        "https://example.com/photo2.jpg",
+        "https://example.com/photo3.jpg"
+    ],
+    post_info={
+        "privacy_level": "PUBLIC_TO_EVERYONE",
+        "title": "Photo post title",
+        "auto_add_music": True
+    }
+)
+# Response: {"code":0,"message":"Ok","request_id":"20210817034316010245031056097316BA","data":{"share_id":"p_pub_url~v1.2345123456789123456"}}
+```
+
+Now your video or photo post has submitted to TikTok, Once video or photo post been processed, video publish status will send by webhook.
+
+More see [Video Webhook events](https://business-api.tiktok.com/portal/docs?id=1759992576757762), [Photo Webhook events](https://business-api.tiktok.com/portal/docs?id=1803634363436034).

docs/mkdocs.yml

@@ -2,7 +2,7 @@ site_name: Python Tiktok Docs
 site_description: Docs for python-tiktok library
 repo_url: https://github.com/sns-sdks/python-tiktok
 site_url: https://sns-sdks.github.io/python-tiktok/
-copyright: Copyright © 2022 - 2022 Ikaros kun
+copyright: Copyright © 2022 - 2024 Ikaros kun
 
 theme:
   name: material
@@ -39,6 +39,7 @@ nav:
           - Account: usage/business_account/account.md
           - Video: usage/business_account/video.md
           - Comment: usage/business_account/comment.md
+          - URL properties: usage/business_account/url_properties.md
       - Kit:
           - User: usage/kit/user.md
           - Video: usage/kit/video.md

pytiktok/business_account_api.py

@@ -641,3 +641,126 @@ def get_hashtag_suggestions(
             if return_json
             else mds.BusinessHashtagSuggestionResponse.new_from_json_dict(data)
         )
+
+    def add_url_property(
+        self,
+        app_id: str,
+        property_type: int,
+        url: str,
+        return_json: bool = False,
+    ) -> Union[mds.BusinessUrlPropertyInfoResponse, dict]:
+        """
+        Add a URL property (domain or URL prefix) that you want to verify ownership of, to an advertiser account.
+        :param app_id: ID of your developer application.
+        :param property_type: Type of the URL property.
+            - 1: Domain
+            - 2: URL prefix
+        :param url: An owned URL that you want to add.
+            - If property_type is 1, specify a base domain or subdomain. ex: example.com.
+            - If property_type is 2, specify a URL prefix which consists of:
+                https:// + host (must be a domain) + path + /. ex: https://example.com/folder/.
+        :param return_json: Type for returned data. If you set True JSON data will be returned.
+        :return: URL property info.
+        """
+        data = {
+            "app_id": app_id,
+            "url_property_meta": {
+                "property_type": property_type,
+                "url": url,
+            },
+        }
+        resp = self._request(verb="POST", path="business/property/add/", json=data)
+        data = self.parse_response(resp)
+        return (
+            data
+            if return_json
+            else mds.BusinessUrlPropertyInfoResponse.new_from_json_dict(data)
+        )
+
+    def check_url_property_verification(
+        self,
+        app_id: str,
+        property_type: int,
+        url: str,
+        return_json: bool = False,
+    ) -> Union[mds.BusinessUrlPropertyInfoResponse, dict]:
+        """
+        Check the result of the ownership verification for a URL property (domain or URL prefix).
+        :param app_id: ID of your developer application.
+        :param property_type: Type of the URL property.
+            - 1: Domain
+            - 2: URL prefix
+        :param url: An owned URL that you want to add.
+            - If property_type is 1, specify a base domain or subdomain. ex: example.com.
+            - If property_type is 2, specify a URL prefix which consists of:
+                https:// + host (must be a domain) + path + /. ex: https://example.com/folder/.
+        :param return_json: Type for returned data. If you set True JSON data will be returned.
+        :return: URL property verification info.
+        """
+        data = {
+            "app_id": app_id,
+            "url_property_meta": {
+                "property_type": property_type,
+                "url": url,
+            },
+        }
+        resp = self._request(verb="POST", path="business/property/verify/", json=data)
+        data = self.parse_response(resp)
+        return (
+            data
+            if return_json
+            else mds.BusinessUrlPropertyInfoResponse.new_from_json_dict(data)
+        )
+
+    def delete_url_property(
+        self,
+        app_id: str,
+        property_type: int,
+        url: str,
+        return_json: bool = False,
+    ) -> Union[mds.BusinessBaseResponse, dict]:
+        """
+        Check the result of the ownership verification for a URL property (domain or URL prefix).
+        :param app_id: ID of your developer application.
+        :param property_type: Type of the URL property.
+            - 1: Domain
+            - 2: URL prefix
+        :param url: An owned URL that you want to add.
+            - If property_type is 1, specify a base domain or subdomain. ex: example.com.
+            - If property_type is 2, specify a URL prefix which consists of:
+                https:// + host (must be a domain) + path + /. ex: https://example.com/folder/.
+        :param return_json: Type for returned data. If you set True JSON data will be returned.
+        :return: url property delete status response
+        """
+        data = {
+            "app_id": app_id,
+            "url_property_meta": {
+                "property_type": property_type,
+                "url": url,
+            },
+        }
+        resp = self._request(verb="POST", path="business/property/delete/", json=data)
+        data = self.parse_response(resp)
+        return (
+            data if return_json else mds.BusinessBaseResponse.new_from_json_dict(data)
+        )
+
+    def get_url_property_list(
+        self,
+        app_id: str,
+        return_json: bool = False,
+    ) -> Union[mds.BusinessUrlPropertyInfoListResponse, dict]:
+        """
+        Get the list of URL properties that have been added to an advertiser account.
+        :param app_id: ID of your developer application.
+        :param return_json: Type for returned data. If you set True JSON data will be returned.
+        :return: URL property list response
+        """
+        params = {"app_id": app_id}
+        resp = self._request(verb="GET", path="business/property/list/", params=params)
+        data = self.parse_response(resp)
+        return (
+            data
+            if return_json
+            else mds.BusinessUrlPropertyInfoListResponse.new_from_json_dict(data)
+        )

pytiktok/models/business_account.py

@@ -199,7 +199,7 @@ class BusinessComment(BaseModel):
     """
 
     comment_id: Optional[str] = field(default=None)
-    unique_identifier: Optional[str] = field(default=None, repr=True)
+    unique_identifier: Optional[str] = field(default=None)
     video_id: Optional[str] = field(default=None, repr=False)
     # Note: user_id now is To-be-deprecated, will be deprecated in the next API version.
     # Please use unique_identifier instead.
@@ -253,3 +253,38 @@ class BusinessHashtagSuggestionResponse(BusinessBaseResponse):
     """
 
     data: Optional[BusinessHashtagSuggestionsData] = field(default=None)
+
+
+@dataclass
+class BusinessUrlPropertyInfo(BaseModel):
+    """
+    Refer: https://business-api.tiktok.com/portal/docs?id=1769325280876545
+    """
+
+    property_type: Optional[int] = field(default=None)
+    url: Optional[str] = field(default=None)
+    property_status: Optional[int] = field(default=None, repr=False)
+    signature: Optional[str] = field(default=None, repr=False)
+    file_name: Optional[str] = field(default=None, repr=False)
+
+
+@dataclass
+class BusinessUrlPropertyInfoData(BaseModel):
+    url_property_info: Optional[BusinessUrlPropertyInfo] = field(default=None)
+
+
+@dataclass
+class BusinessUrlPropertyInfoResponse(BusinessBaseResponse):
+    data: Optional[BusinessUrlPropertyInfoData] = field(default=None)
+
+
+@dataclass
+class BusinessUrlPropertyInfoListData(BaseModel):
+    url_property_info_list: Optional[List[BusinessUrlPropertyInfo]] = field(
+        default=None
+    )
+
+
+@dataclass
+class BusinessUrlPropertyInfoListResponse(BusinessBaseResponse):
+    data: Optional[BusinessUrlPropertyInfoListData] = field(default=None)