upload-post 2.10.0__tar.gz → 2.12.0__tar.gz

{upload_post-2.10.0 → upload_post-2.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: upload-post
-Version: 2.10.0
+Version: 2.12.0
 Summary: Cross-platform social media upload for TikTok, Instagram, YouTube, LinkedIn, Facebook, Pinterest, Threads, Reddit, Bluesky, Discord, Telegram, and X (Twitter)
 Home-page: https://www.upload-post.com/
 Author: Upload-Post
@@ -76,6 +76,8 @@ print(response)
 - ✅ **Posting Queue** - Add posts to your configured queue
 - ✅ **First Comments** - Auto-post first comment after publishing
 - ✅ **Analytics** - Get engagement metrics
+- ✅ **Audience** - Who follows a profile, per platform
+- ✅ **Suggestions** - Hashtags and searches to post about, per platform
 - ✅ **Full Type Hints**
 
 ## API Reference
@@ -322,17 +324,183 @@ found = client.search_tiktok_music("my-profile", q="bad bunny", country_code="ES
 locations = client.get_tiktok_locations("my-profile", "Madrid")
 ```
 
+### Comments
+
+The same methods cover every platform that has comments — Instagram, Facebook,
+YouTube, LinkedIn and TikTok. There is no per-network method: the endpoint
+answers one question and `platform` says who to ask.
+
+```python
+# Read the comments on a post. TikTok has no post-URL lookup: pass the video id.
+comments = client.get_post_comments(
+    user="my-profile",
+    platform="tiktok",
+    post_id="7412345678901234567",
+    limit=20,
+)
+
+# Read the replies hanging from one of them — same question, one more parameter
+replies = client.get_post_comments(
+    user="my-profile",
+    platform="tiktok",
+    post_id="7412345678901234567",
+    comment_id="7412345678909999999",
+)
+
+# Comment on the post, or reply to a comment
+client.create_comment(
+    user="my-profile",
+    platform="tiktok",
+    post_id="7412345678901234567",
+    message="Thanks for watching!",
+)
+client.create_comment(
+    user="my-profile",
+    platform="tiktok",
+    comment_id="7412345678909999999",
+    message="Glad you liked it",
+)
+
+# Delete one
+client.delete_comment(
+    user="my-profile", platform="tiktok", comment_id="7412345678909999999"
+)
+```
+
+You can also have the first comment posted for you right after publishing, with
+`first_comment` for every platform or `tiktok_first_comment` for TikTok alone.
+
+On TikTok all of this needs the `comments` capability, which the account grants
+when it connects — see
+[What a TikTok connection can do](#what-a-tiktok-connection-can-do-capabilities).
+
+#### Moderating a comment: hide, like, pin
+
+`comment_action()` does the three and undoes them, on any platform that
+supports it. Each action carries its own inverse, and `post_id` is only sent
+when the platform needs it:
+
+```python
+client.comment_action(
+    user="my-profile", platform="tiktok", action="hide",
+    comment_id="7412345678909999999", post_id="7412345678901234567",
+)
+client.comment_action(
+    user="my-profile", platform="tiktok", action="like",
+    comment_id="7412345678909999999",
+)
+client.comment_action(
+    user="my-profile", platform="tiktok", action="unpin",
+    comment_id="7412345678909999999", post_id="7412345678901234567",
+)
+```
+
+| `action` | Undo | `post_id` |
+| --- | --- | --- |
+| `hide` | `unhide` | required |
+| `like` | `unlike` | not sent |
+| `pin` | `unpin` | required |
+
+### Audience
+
+Where the analytics methods answer *how did my posts do*, `get_audience()`
+answers *who is following me*. One endpoint, one `platform` parameter, like
+every other question in the API.
+
+```python
+audience = client.get_audience(
+    user="my-profile",
+    platform="tiktok",
+    start_date="2026-07-01",
+    end_date="2026-07-30",
+)
+
+print(audience["range"])                 # the window actually used
+print(audience["audience"]["countries"])  # and "cities", "ages", "genders"
+print(audience["activity_by_hour"])       # [{"hour": "14", "followers_online": 1494}, ...]
+print(audience["followers_daily"])        # [{"date", "total", "new", "lost"}, ...]
+print(audience["profile_actions"])        # bio link, address, email, phone, leads
+print(audience["bio_description"])
+```
+
+The window is clamped on the server: at most 60 days, and `end_date` always
+before today. A wider window is trimmed to what the platform accepts instead of
+failing.
+
+Ask for a `benchmark_category` and the same call also returns how the account
+compares with the average of that category. The accepted categories come back in
+`benchmark_categories` on every response, so a picker needs no second call:
+
+```python
+categories = client.get_audience(
+    user="my-profile", platform="tiktok"
+)["benchmark_categories"]
+
+benchmark = client.get_audience(
+    user="my-profile", platform="tiktok",
+    benchmark_category="SOFTWARE_AND_APPS",
+)["benchmark"]
+print(benchmark["average_engagement_rate"], benchmark["average_video_views"])
+```
+
+### Suggestions
+
+`get_suggestions()` answers *what is worth posting about*: the hashtags or the
+searches a platform suggests around a keyword. One endpoint for both, told apart
+by `type`.
+
+```python
+hashtags = client.get_suggestions(
+    user="my-profile", platform="tiktok", type="hashtags",
+    q="pilates", country_code="ES", language="es",
+)["hashtags"]
+print(hashtags)  # [{"name": ..., "view_count": ...}, ...]
+
+keywords = client.get_suggestions(
+    user="my-profile", platform="tiktok", type="keywords", q="pilates",
+)["keywords"]
+```
+
+Per-post numbers stay in `get_post_analytics()`. On TikTok that response carries
+more than the usual counters: `retention` (the curve, second by second),
+`impression_sources` (For You, search, profile...), `audience_types` (followers
+vs non-followers), `new_followers`, `reach` and the watch times.
+
+Asking a platform a question it cannot answer fails with
+`platform_not_supported` and the list of the ones that can.
+
+## What a TikTok connection can do (`capabilities`)
+
+Not every TikTok connection can do the same things. `client.list_users()`
+(`GET /api/uploadposts/users`) returns a `capabilities` array on each profile's
+TikTok account; check it before offering a feature.
+
+| Capability | What it unlocks |
+| --- | --- |
+| `music` | `tiktok_music_id` and the volume/trim fields, plus `get_tiktok_trending_music()` and `search_tiktok_music()` |
+| `location` | `tiktok_location_id` / `tiktok_location_name`, plus `get_tiktok_locations()` |
+| `cover_image` | `tiktok_cover_image_url` |
+| `cover_timestamp` | `cover_timestamp` |
+| `draft` | `tiktok_upload_to_draft` |
+| `video_privacy` | `privacy_level` on video |
+| `photo_privacy` | `privacy_level` on photo posts |
+| `profile_analytics` | `get_audience()` and `get_suggestions(type="hashtags")` with `platform="tiktok"` |
+| `comments` | Comments on TikTok: `get_post_comments()` (top-level and replies), `create_comment()`, `delete_comment()`, `comment_action()` and `tiktok_first_comment` |
+| `trend_search` | `get_suggestions(type="keywords")` with `platform="tiktok"` |
+
+> **`comments` and `trend_search` need the account to be reconnected.** TikTok
+> grants them at connect time, so an account linked before they existed keeps
+> working for everything else but will not list them — reconnect it from Manage
+> Users to enable them.
+
+If a connection lacks a capability the upload field is simply ignored: the post
+still publishes and the response carries a per-field `warnings` string. The
+methods above answer with an error asking for a reconnection.
+
 ## TikTok music, location, cover and drafts
 
-> **Capabilities.** These options are available on connections that declare the
-> matching capability (`music`, `location`, `cover_image`, `draft`) — see the
-> `capabilities` array on the TikTok account returned by
-> `GET /api/uploadposts/users` (`client.list_users()`). Other values that can
-> appear there: `cover_timestamp`, `photo_privacy`, `video_privacy`,
-> `inbox_fallback` and `profile_analytics`. If your connection does
-> not have the capability, the field is ignored, the post still publishes, and
-> the response includes a per-field `warnings` string — reconnect the TikTok
-> account to enable it.
+> Needs the `music`, `location`, `cover_image` or `draft` capability — see
+> [What a TikTok connection can do](#what-a-tiktok-connection-can-do-capabilities).
 
 ```python
 # 1. Pick a track and a place
@@ -525,6 +693,7 @@ These options work across all upload methods:
 | `user` | Profile name (required) |
 | `platforms` | Target platforms list (required) |
 | `first_comment` | First comment to post |
+| `tiktok_first_comment` | First comment for TikTok only (needs the `comments` capability) |
 | `alt_text` | Alt text for accessibility |
 | `scheduled_date` | ISO date for scheduling |
 | `timezone` | Timezone for scheduled date |

{upload_post-2.10.0 → upload_post-2.12.0}/README.md

@@ -38,6 +38,8 @@ print(response)
 - ✅ **Posting Queue** - Add posts to your configured queue
 - ✅ **First Comments** - Auto-post first comment after publishing
 - ✅ **Analytics** - Get engagement metrics
+- ✅ **Audience** - Who follows a profile, per platform
+- ✅ **Suggestions** - Hashtags and searches to post about, per platform
 - ✅ **Full Type Hints**
 
 ## API Reference
@@ -284,17 +286,183 @@ found = client.search_tiktok_music("my-profile", q="bad bunny", country_code="ES
 locations = client.get_tiktok_locations("my-profile", "Madrid")
 ```
 
+### Comments
+
+The same methods cover every platform that has comments — Instagram, Facebook,
+YouTube, LinkedIn and TikTok. There is no per-network method: the endpoint
+answers one question and `platform` says who to ask.
+
+```python
+# Read the comments on a post. TikTok has no post-URL lookup: pass the video id.
+comments = client.get_post_comments(
+    user="my-profile",
+    platform="tiktok",
+    post_id="7412345678901234567",
+    limit=20,
+)
+
+# Read the replies hanging from one of them — same question, one more parameter
+replies = client.get_post_comments(
+    user="my-profile",
+    platform="tiktok",
+    post_id="7412345678901234567",
+    comment_id="7412345678909999999",
+)
+
+# Comment on the post, or reply to a comment
+client.create_comment(
+    user="my-profile",
+    platform="tiktok",
+    post_id="7412345678901234567",
+    message="Thanks for watching!",
+)
+client.create_comment(
+    user="my-profile",
+    platform="tiktok",
+    comment_id="7412345678909999999",
+    message="Glad you liked it",
+)
+
+# Delete one
+client.delete_comment(
+    user="my-profile", platform="tiktok", comment_id="7412345678909999999"
+)
+```
+
+You can also have the first comment posted for you right after publishing, with
+`first_comment` for every platform or `tiktok_first_comment` for TikTok alone.
+
+On TikTok all of this needs the `comments` capability, which the account grants
+when it connects — see
+[What a TikTok connection can do](#what-a-tiktok-connection-can-do-capabilities).
+
+#### Moderating a comment: hide, like, pin
+
+`comment_action()` does the three and undoes them, on any platform that
+supports it. Each action carries its own inverse, and `post_id` is only sent
+when the platform needs it:
+
+```python
+client.comment_action(
+    user="my-profile", platform="tiktok", action="hide",
+    comment_id="7412345678909999999", post_id="7412345678901234567",
+)
+client.comment_action(
+    user="my-profile", platform="tiktok", action="like",
+    comment_id="7412345678909999999",
+)
+client.comment_action(
+    user="my-profile", platform="tiktok", action="unpin",
+    comment_id="7412345678909999999", post_id="7412345678901234567",
+)
+```
+
+| `action` | Undo | `post_id` |
+| --- | --- | --- |
+| `hide` | `unhide` | required |
+| `like` | `unlike` | not sent |
+| `pin` | `unpin` | required |
+
+### Audience
+
+Where the analytics methods answer *how did my posts do*, `get_audience()`
+answers *who is following me*. One endpoint, one `platform` parameter, like
+every other question in the API.
+
+```python
+audience = client.get_audience(
+    user="my-profile",
+    platform="tiktok",
+    start_date="2026-07-01",
+    end_date="2026-07-30",
+)
+
+print(audience["range"])                 # the window actually used
+print(audience["audience"]["countries"])  # and "cities", "ages", "genders"
+print(audience["activity_by_hour"])       # [{"hour": "14", "followers_online": 1494}, ...]
+print(audience["followers_daily"])        # [{"date", "total", "new", "lost"}, ...]
+print(audience["profile_actions"])        # bio link, address, email, phone, leads
+print(audience["bio_description"])
+```
+
+The window is clamped on the server: at most 60 days, and `end_date` always
+before today. A wider window is trimmed to what the platform accepts instead of
+failing.
+
+Ask for a `benchmark_category` and the same call also returns how the account
+compares with the average of that category. The accepted categories come back in
+`benchmark_categories` on every response, so a picker needs no second call:
+
+```python
+categories = client.get_audience(
+    user="my-profile", platform="tiktok"
+)["benchmark_categories"]
+
+benchmark = client.get_audience(
+    user="my-profile", platform="tiktok",
+    benchmark_category="SOFTWARE_AND_APPS",
+)["benchmark"]
+print(benchmark["average_engagement_rate"], benchmark["average_video_views"])
+```
+
+### Suggestions
+
+`get_suggestions()` answers *what is worth posting about*: the hashtags or the
+searches a platform suggests around a keyword. One endpoint for both, told apart
+by `type`.
+
+```python
+hashtags = client.get_suggestions(
+    user="my-profile", platform="tiktok", type="hashtags",
+    q="pilates", country_code="ES", language="es",
+)["hashtags"]
+print(hashtags)  # [{"name": ..., "view_count": ...}, ...]
+
+keywords = client.get_suggestions(
+    user="my-profile", platform="tiktok", type="keywords", q="pilates",
+)["keywords"]
+```
+
+Per-post numbers stay in `get_post_analytics()`. On TikTok that response carries
+more than the usual counters: `retention` (the curve, second by second),
+`impression_sources` (For You, search, profile...), `audience_types` (followers
+vs non-followers), `new_followers`, `reach` and the watch times.
+
+Asking a platform a question it cannot answer fails with
+`platform_not_supported` and the list of the ones that can.
+
+## What a TikTok connection can do (`capabilities`)
+
+Not every TikTok connection can do the same things. `client.list_users()`
+(`GET /api/uploadposts/users`) returns a `capabilities` array on each profile's
+TikTok account; check it before offering a feature.
+
+| Capability | What it unlocks |
+| --- | --- |
+| `music` | `tiktok_music_id` and the volume/trim fields, plus `get_tiktok_trending_music()` and `search_tiktok_music()` |
+| `location` | `tiktok_location_id` / `tiktok_location_name`, plus `get_tiktok_locations()` |
+| `cover_image` | `tiktok_cover_image_url` |
+| `cover_timestamp` | `cover_timestamp` |
+| `draft` | `tiktok_upload_to_draft` |
+| `video_privacy` | `privacy_level` on video |
+| `photo_privacy` | `privacy_level` on photo posts |
+| `profile_analytics` | `get_audience()` and `get_suggestions(type="hashtags")` with `platform="tiktok"` |
+| `comments` | Comments on TikTok: `get_post_comments()` (top-level and replies), `create_comment()`, `delete_comment()`, `comment_action()` and `tiktok_first_comment` |
+| `trend_search` | `get_suggestions(type="keywords")` with `platform="tiktok"` |
+
+> **`comments` and `trend_search` need the account to be reconnected.** TikTok
+> grants them at connect time, so an account linked before they existed keeps
+> working for everything else but will not list them — reconnect it from Manage
+> Users to enable them.
+
+If a connection lacks a capability the upload field is simply ignored: the post
+still publishes and the response carries a per-field `warnings` string. The
+methods above answer with an error asking for a reconnection.
+
 ## TikTok music, location, cover and drafts
 
-> **Capabilities.** These options are available on connections that declare the
-> matching capability (`music`, `location`, `cover_image`, `draft`) — see the
-> `capabilities` array on the TikTok account returned by
-> `GET /api/uploadposts/users` (`client.list_users()`). Other values that can
-> appear there: `cover_timestamp`, `photo_privacy`, `video_privacy`,
-> `inbox_fallback` and `profile_analytics`. If your connection does
-> not have the capability, the field is ignored, the post still publishes, and
-> the response includes a per-field `warnings` string — reconnect the TikTok
-> account to enable it.
+> Needs the `music`, `location`, `cover_image` or `draft` capability — see
+> [What a TikTok connection can do](#what-a-tiktok-connection-can-do-capabilities).
 
 ```python
 # 1. Pick a track and a place
@@ -487,6 +655,7 @@ These options work across all upload methods:
 | `user` | Profile name (required) |
 | `platforms` | Target platforms list (required) |
 | `first_comment` | First comment to post |
+| `tiktok_first_comment` | First comment for TikTok only (needs the `comments` capability) |
 | `alt_text` | Alt text for accessibility |
 | `scheduled_date` | ISO date for scheduling |
 | `timezone` | Timezone for scheduled date |

{upload_post-2.10.0 → upload_post-2.12.0}/setup.py

@@ -5,7 +5,7 @@ with open("README.md", "r", encoding="utf-8") as fh:
 
 setup(
     name="upload-post",
-    version="2.10.0",
+    version="2.12.0",
     author="Upload-Post",
     author_email="hi@img2html.com",
     description="Cross-platform social media upload for TikTok, Instagram, YouTube, LinkedIn, Facebook, Pinterest, Threads, Reddit, Bluesky, Discord, Telegram, and X (Twitter)",

upload_post-2.12.0/tests/test_comments_audience.py

@@ -0,0 +1,231 @@
+"""Tests for the question-shaped endpoints.
+
+Comments (list, replies, moderate), audience and suggestions are all one
+endpoint each with a `platform` parameter, not a method per network. TikTok is
+the platform used here because it is the one that answers all of them today.
+
+No network: the session's HTTP verbs are patched, so every assertion is about
+what the client would have sent.
+
+Run with: python -m unittest discover -s tests
+"""
+
+import unittest
+from unittest.mock import MagicMock, patch
+
+from upload_post import UploadPostClient, UploadPostError
+
+
+def _response(payload=None, status=200):
+    response = MagicMock()
+    response.status_code = status
+    response.json.return_value = payload if payload is not None else {"success": True}
+    response.raise_for_status.return_value = None
+    return response
+
+
+class ClientTestCase(unittest.TestCase):
+    def setUp(self):
+        self.client = UploadPostClient("test-key")
+        self.get = patch.object(self.client.session, "get",
+                                return_value=_response()).start()
+        self.post = patch.object(self.client.session, "post",
+                                 return_value=_response()).start()
+        self.delete = patch.object(self.client.session, "delete",
+                                   return_value=_response()).start()
+        self.addCleanup(patch.stopall)
+
+    def assertGet(self, mock, endpoint, params):
+        url, kwargs = mock.call_args[0][0], mock.call_args[1]
+        self.assertEqual(url, f"https://api.upload-post.com/api{endpoint}")
+        self.assertEqual(kwargs["params"], params)
+
+
+class TestComments(ClientTestCase):
+    """One /comments endpoint, told who to ask with platform."""
+
+    def test_get_post_comments(self):
+        self.client.get_post_comments(
+            user="my-profile", platform="tiktok",
+            post_id="7412345678901234567", limit=20,
+        )
+        self.assertGet(self.get, "/uploadposts/comments", {
+            "platform": "tiktok", "user": "my-profile",
+            "post_id": "7412345678901234567", "limit": 20,
+        })
+
+    def test_comment_id_asks_for_the_replies(self):
+        self.client.get_post_comments(
+            user="my-profile", platform="tiktok",
+            post_id="741", comment_id="99", limit=20,
+        )
+        self.assertGet(self.get, "/uploadposts/comments", {
+            "platform": "tiktok", "user": "my-profile",
+            "post_id": "741", "comment_id": "99", "limit": 20,
+        })
+
+    def test_comment_id_is_omitted_when_not_asked_for(self):
+        self.client.get_post_comments(
+            user="my-profile", platform="tiktok", post_id="741"
+        )
+        self.assertGet(self.get, "/uploadposts/comments", {
+            "platform": "tiktok", "user": "my-profile", "post_id": "741",
+        })
+
+    def test_create_comment(self):
+        self.client.create_comment(
+            user="my-profile", platform="tiktok", post_id="741", message="hola"
+        )
+        self.assertEqual(self.post.call_args[1]["json"], {
+            "platform": "tiktok", "user": "my-profile",
+            "message": "hola", "post_id": "741",
+        })
+
+    def test_delete_comment(self):
+        self.client.delete_comment(
+            user="my-profile", platform="tiktok", comment_id="99"
+        )
+        self.assertEqual(self.delete.call_args[1]["json"], {
+            "platform": "tiktok", "user": "my-profile", "comment_id": "99",
+        })
+
+
+class TestFirstComment(ClientTestCase):
+    def test_tiktok_first_comment_is_forwarded_like_the_rest(self):
+        data = []
+        self.client._add_common_params(
+            data, user="my-profile", title="hi", platforms=["tiktok"],
+            first_comment="shared",
+            tiktok_first_comment="solo TikTok",
+            instagram_first_comment="solo IG",
+        )
+        fields = dict(data)
+        self.assertEqual(fields["first_comment"], "shared")
+        self.assertEqual(fields["tiktok_first_comment"], "solo TikTok")
+        self.assertEqual(fields["instagram_first_comment"], "solo IG")
+
+    def test_tiktok_is_not_filtered_out_of_the_upload(self):
+        self.client.upload_text(
+            user="my-profile", platforms=["tiktok"], title="hi",
+            tiktok_first_comment="primero",
+        )
+        fields = dict(self.post.call_args[1]["data"])
+        self.assertEqual(fields["tiktok_first_comment"], "primero")
+
+
+class TestCommentAction(ClientTestCase):
+    def test_hide_and_pin_carry_the_post(self):
+        for action in ("hide", "unhide", "pin", "unpin"):
+            with self.subTest(action=action):
+                self.client.comment_action(
+                    user="my-profile", platform="tiktok", action=action,
+                    comment_id="99", post_id="741",
+                )
+                self.assertEqual(self.post.call_args[0][0],
+                                 "https://api.upload-post.com/api"
+                                 "/uploadposts/comments/action")
+                self.assertEqual(self.post.call_args[1]["json"], {
+                    "platform": "tiktok", "user": "my-profile",
+                    "comment_id": "99", "action": action, "post_id": "741",
+                })
+
+    def test_like_never_carries_the_post(self):
+        for action in ("like", "unlike"):
+            with self.subTest(action=action):
+                self.client.comment_action(
+                    user="my-profile", platform="tiktok", action=action,
+                    comment_id="99", post_id="741",
+                )
+                self.assertEqual(self.post.call_args[1]["json"], {
+                    "platform": "tiktok", "user": "my-profile",
+                    "comment_id": "99", "action": action,
+                })
+
+
+class TestAudience(ClientTestCase):
+    def test_window_travels_as_snake_case(self):
+        self.client.get_audience(
+            user="my-profile", platform="tiktok",
+            start_date="2026-07-01", end_date="2026-07-30",
+        )
+        self.assertGet(self.get, "/uploadposts/audience", {
+            "user": "my-profile", "platform": "tiktok",
+            "start_date": "2026-07-01", "end_date": "2026-07-30",
+        })
+
+    def test_default_window_is_left_to_the_api(self):
+        self.client.get_audience(user="my-profile", platform="tiktok")
+        self.assertGet(self.get, "/uploadposts/audience",
+                       {"user": "my-profile", "platform": "tiktok"})
+
+    def test_benchmark_category_rides_along(self):
+        self.client.get_audience(
+            user="my-profile", platform="tiktok",
+            benchmark_category="SOFTWARE_AND_APPS",
+        )
+        self.assertGet(self.get, "/uploadposts/audience", {
+            "user": "my-profile", "platform": "tiktok",
+            "benchmark_category": "SOFTWARE_AND_APPS",
+        })
+
+
+class TestSuggestions(ClientTestCase):
+    def test_hashtags_take_country_and_language(self):
+        self.client.get_suggestions(
+            user="my-profile", platform="tiktok", type="hashtags",
+            q="pilates", country_code="ES", language="es",
+        )
+        self.assertGet(self.get, "/uploadposts/suggestions", {
+            "user": "my-profile", "platform": "tiktok", "type": "hashtags",
+            "q": "pilates", "country_code": "ES", "language": "es",
+        })
+
+    def test_keywords_use_the_same_call(self):
+        self.client.get_suggestions(
+            user="my-profile", platform="tiktok", type="keywords", q="pilates"
+        )
+        self.assertGet(self.get, "/uploadposts/suggestions", {
+            "user": "my-profile", "platform": "tiktok",
+            "type": "keywords", "q": "pilates",
+        })
+
+
+class TestTheOldPerNetworkMethodsAreGone(ClientTestCase):
+    def test_nothing_answers_the_old_names(self):
+        for name in (
+            "get_tiktok_comment_replies", "tiktok_comment_action",
+            "search_tiktok_keywords", "get_tiktok_insights",
+            "get_tiktok_video_insights", "get_tiktok_hashtags",
+            "get_tiktok_benchmark",
+        ):
+            with self.subTest(name=name):
+                self.assertFalse(hasattr(self.client, name))
+
+    def test_the_composer_helpers_stay(self):
+        for name in (
+            "get_tiktok_trending_music", "search_tiktok_music",
+            "get_tiktok_locations", "get_tiktok_publishing_settings",
+        ):
+            with self.subTest(name=name):
+                self.assertTrue(hasattr(self.client, name))
+
+
+class TestErrors(ClientTestCase):
+    def test_api_error_keeps_the_message_the_api_sent(self):
+        import requests
+
+        failed = _response({"message": "platform_not_supported"}, status=400)
+        error = requests.exceptions.HTTPError("400 Client Error")
+        error.response = failed
+        failed.raise_for_status.side_effect = error
+        self.get.return_value = failed
+
+        with self.assertRaises(UploadPostError) as caught:
+            self.client.get_suggestions(
+                user="my-profile", platform="x", type="hashtags"
+            )
+        self.assertIn("platform_not_supported", str(caught.exception))
+
+
+if __name__ == "__main__":
+    unittest.main()

{upload_post-2.10.0 → upload_post-2.12.0}/upload_post/__init__.py

@@ -15,7 +15,7 @@ Example:
     ... )
 """
 
-__version__ = "2.10.0"
+__version__ = "2.12.0"
 
 from .api_client import UploadPostClient, UploadPostError
 

{upload_post-2.10.0 → upload_post-2.12.0}/upload_post/api_client.py

@@ -151,11 +151,13 @@ class UploadPostClient:
             if kwargs.get(key):
                 data.append((key, kwargs[key]))
         
-        # Platform-specific first comment overrides
+        # Platform-specific first comment overrides. TikTok needs the
+        # `comments` capability on the connection: without it the post still
+        # publishes and the response carries a warning instead of the comment.
         comment_overrides = [
             "instagram_first_comment", "facebook_first_comment", "x_first_comment",
             "threads_first_comment", "youtube_first_comment", "reddit_first_comment",
-            "bluesky_first_comment", "linkedin_first_comment"
+            "bluesky_first_comment", "linkedin_first_comment", "tiktok_first_comment"
         ]
         for key in comment_overrides:
             if kwargs.get(key):
@@ -1193,6 +1195,13 @@ class UploadPostClient:
         """
         Get analytics for a specific post across all platforms it was published to.
 
+        'post_metrics' carries whatever the platform reports, so it is not the
+        same shape everywhere: on TikTok it also brings 'retention' (the curve,
+        second by second), 'impression_sources' (For You, search, profile...),
+        'audience_types' (followers vs non-followers), 'new_followers', 'reach'
+        and the watch times ('average_time_watched', 'total_time_watched',
+        'full_video_watched_rate').
+
         Args:
             request_id: The request_id from the upload.
 
@@ -1263,6 +1272,95 @@ class UploadPostClient:
             params["until"] = until
         return self._request("/uploadposts/post-analytics/cached", "GET", params=params)
 
+    def get_audience(
+        self,
+        user: str,
+        platform: str,
+        start_date: Optional[str] = None,
+        end_date: Optional[str] = None,
+        benchmark_category: Optional[str] = None
+    ) -> Dict:
+        """
+        Get who the audience is: where they are, how old they are, when they
+        are online and what they tap on the profile.
+
+        Where the post-analytics methods answer how did my posts do, this one
+        answers who is following me. It is one endpoint for every platform,
+        chosen with `platform`; a platform that cannot answer it comes back
+        with "platform_not_supported" and the list of the ones that can.
+
+        The window is clamped server-side: at most 60 days, and end_date always
+        before today. A wider window is trimmed rather than rejected.
+
+        Args:
+            user: Profile username.
+            platform: Platform to ask (tiktok).
+            start_date: Window start, ISO "YYYY-MM-DD".
+            end_date: Window end, ISO "YYYY-MM-DD".
+            benchmark_category: Compare the account against this category's
+                averages, e.g. "SOFTWARE_AND_APPS". Every accepted value comes
+                back in "benchmark_categories" on any response, so a picker
+                needs no second call.
+
+        Returns:
+            'range', 'audience' (countries, cities, ages, genders),
+            'activity_by_hour', 'followers_daily', 'profile_actions',
+            'bio_description', 'benchmark_categories' and, with a category,
+            'benchmark'.
+        """
+        params: Dict[str, Any] = {"user": user, "platform": platform}
+        if start_date:
+            params["start_date"] = start_date
+        if end_date:
+            params["end_date"] = end_date
+        if benchmark_category:
+            params["benchmark_category"] = benchmark_category
+        return self._request("/uploadposts/audience", "GET", params=params)
+
+    def get_suggestions(
+        self,
+        user: str,
+        platform: str,
+        type: str,
+        q: Optional[str] = None,
+        country_code: Optional[str] = None,
+        language: Optional[str] = None
+    ) -> Dict:
+        """
+        Get what to write about: the hashtags or the searches a platform
+        suggests around a keyword.
+
+        One endpoint for both questions, told apart by `type`:
+
+            type        answers
+            hashtags    {"hashtags": [{"name": ..., "view_count": ...}]}
+            keywords    {"keywords": [...]}
+
+        Chosen with `platform`, like every other question in the API; a
+        platform that cannot answer it comes back with
+        "platform_not_supported" and the list of the ones that can.
+
+        Args:
+            user: Profile username.
+            platform: Platform to ask (tiktok).
+            type: Which suggestions you want: "hashtags" or "keywords".
+            q: Keyword to get suggestions around.
+            country_code: ISO country code to bias the suggestions.
+            language: Language code to bias the suggestions.
+
+        Returns:
+            {"success": True, "platform": ..., "type": ..., "hashtags": [...]}
+            or {"success": True, "platform": ..., "type": ..., "keywords": [...]}
+        """
+        params: Dict[str, Any] = {"user": user, "platform": platform, "type": type}
+        if q:
+            params["q"] = q
+        if country_code:
+            params["country_code"] = country_code
+        if language:
+            params["language"] = language
+        return self._request("/uploadposts/suggestions", "GET", params=params)
+
     def get_platform_metrics(self) -> Dict:
         """
         Get available metrics configuration for all supported platforms.
@@ -1576,7 +1674,7 @@ class UploadPostClient:
         params = {"profile": profile} if profile else None
         return self._request("/uploadposts/pinterest/boards", "GET", params=params)
 
-    # ==================== Instagram Comments ====================
+    # ==================== Comments ====================
 
     def get_post_comments(
         self,
@@ -1585,18 +1683,33 @@ class UploadPostClient:
         post_id: Optional[str] = None,
         post_url: Optional[str] = None,
         limit: Optional[int] = None,
-        after: Optional[str] = None
+        after: Optional[str] = None,
+        comment_id: Optional[str] = None
     ) -> Dict:
         """
-        Get comments on a post.
+        Get comments on a post, or the replies hanging from one of them.
+
+        Pass comment_id to read that comment's replies instead of the post's
+        top-level comments. It is the same question - what was said here - so it
+        is the same endpoint with one more parameter, not a method per platform.
+
+        On TikTok this needs the `comments` capability on the connection (see
+        `capabilities` on the TikTok account returned by list_users()). TikTok
+        grants it at connect time, so an account connected earlier has to be
+        reconnected.
 
         Args:
             user: Profile username.
-            platform: Platform name (instagram, facebook, youtube, linkedin).
-            post_id: Post/media ID (provide post_id or post_url).
+            platform: Platform name (instagram, facebook, youtube, linkedin,
+                tiktok).
+            post_id: Post/media ID (provide post_id or post_url). Required on
+                TikTok, which has no post URL lookup.
             post_url: Full post URL (provide post_id or post_url).
             limit: Maximum number of comments to return.
             after: Pagination cursor for the next page of comments.
+            comment_id: Read the replies to this comment instead of the post's
+                top-level comments. Keyword-only in practice: it goes last so
+                the existing positional order keeps working.
 
         Returns:
             Comments data including comment IDs, text, timestamps, and user info.
@@ -1606,6 +1719,8 @@ class UploadPostClient:
             params["post_id"] = post_id
         if post_url:
             params["post_url"] = post_url
+        if comment_id:
+            params["comment_id"] = comment_id
         if limit is not None:
             params["limit"] = limit
         if after is not None:
@@ -1678,9 +1793,15 @@ class UploadPostClient:
         """
         Create a comment on a post, or reply to an existing comment.
 
+        On TikTok this needs the `comments` capability on the connection (see
+        `capabilities` on the TikTok account returned by list_users()). TikTok
+        grants it at connect time, so an account connected earlier has to be
+        reconnected.
+
         Args:
             user: Profile username.
-            platform: Platform name (instagram, facebook, youtube, linkedin).
+            platform: Platform name (instagram, facebook, youtube, linkedin,
+                tiktok).
             message: Comment text.
             post_id: Post/media ID to comment on.
             post_url: Full post URL to comment on.
@@ -1714,9 +1835,15 @@ class UploadPostClient:
         """
         Delete a comment on a post.
 
+        On TikTok this needs the `comments` capability on the connection (see
+        `capabilities` on the TikTok account returned by list_users()). TikTok
+        grants it at connect time, so an account connected earlier has to be
+        reconnected.
+
         Args:
             user: Profile username.
-            platform: Platform name (instagram, facebook, youtube, linkedin).
+            platform: Platform name (instagram, facebook, youtube, linkedin,
+                tiktok).
             comment_id: Comment ID to delete.
             post_id: Post URN (required for LinkedIn).
 
@@ -1732,6 +1859,56 @@ class UploadPostClient:
             json_data["post_id"] = post_id
         return self._request("/uploadposts/comments/delete", "DELETE", json_data=json_data)
 
+    def comment_action(
+        self,
+        user: str,
+        platform: str,
+        comment_id: str,
+        action: str,
+        post_id: Optional[str] = None
+    ) -> Dict:
+        """
+        Moderate a comment: hide, like or pin it - and undo any of the three.
+
+        One method for every platform, because it is one question: do this to
+        that comment. Each action carries its own inverse:
+
+            action              post_id
+            hide / unhide       required
+            like / unlike       not sent (the platform likes the comment alone)
+            pin / unpin         required
+
+        On TikTok this needs the `comments` capability on the connection (see
+        `capabilities` on the TikTok account returned by list_users()). TikTok
+        grants it at connect time, so an account connected earlier has to be
+        reconnected.
+
+        Args:
+            user: Profile username.
+            platform: Platform name (tiktok).
+            comment_id: Comment to act on.
+            action: What to do: "hide", "unhide", "like", "unlike", "pin" or
+                "unpin".
+            post_id: Native post ID. Required for hide/unhide and pin/unpin;
+                never sent for like/unlike.
+
+        Returns:
+            {"success": True, "platform": ..., "action": ...,
+             "comment_id": ..., "result": {...}}
+        """
+        json_data: Dict[str, Any] = {
+            "platform": platform,
+            "user": user,
+            "comment_id": comment_id,
+            "action": action,
+        }
+        # Liking takes the comment alone; hiding and pinning need the post too.
+        if action not in ("like", "unlike") and post_id:
+            json_data["post_id"] = post_id
+        return self._request(
+            "/uploadposts/comments/action", "POST", json_data=json_data
+        )
+
     # ==================== TikTok ====================
 
     def get_tiktok_trending_music(

{upload_post-2.10.0 → upload_post-2.12.0}/upload_post.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: upload-post
-Version: 2.10.0
+Version: 2.12.0
 Summary: Cross-platform social media upload for TikTok, Instagram, YouTube, LinkedIn, Facebook, Pinterest, Threads, Reddit, Bluesky, Discord, Telegram, and X (Twitter)
 Home-page: https://www.upload-post.com/
 Author: Upload-Post
@@ -76,6 +76,8 @@ print(response)
 - ✅ **Posting Queue** - Add posts to your configured queue
 - ✅ **First Comments** - Auto-post first comment after publishing
 - ✅ **Analytics** - Get engagement metrics
+- ✅ **Audience** - Who follows a profile, per platform
+- ✅ **Suggestions** - Hashtags and searches to post about, per platform
 - ✅ **Full Type Hints**
 
 ## API Reference
@@ -322,17 +324,183 @@ found = client.search_tiktok_music("my-profile", q="bad bunny", country_code="ES
 locations = client.get_tiktok_locations("my-profile", "Madrid")
 ```
 
+### Comments
+
+The same methods cover every platform that has comments — Instagram, Facebook,
+YouTube, LinkedIn and TikTok. There is no per-network method: the endpoint
+answers one question and `platform` says who to ask.
+
+```python
+# Read the comments on a post. TikTok has no post-URL lookup: pass the video id.
+comments = client.get_post_comments(
+    user="my-profile",
+    platform="tiktok",
+    post_id="7412345678901234567",
+    limit=20,
+)
+
+# Read the replies hanging from one of them — same question, one more parameter
+replies = client.get_post_comments(
+    user="my-profile",
+    platform="tiktok",
+    post_id="7412345678901234567",
+    comment_id="7412345678909999999",
+)
+
+# Comment on the post, or reply to a comment
+client.create_comment(
+    user="my-profile",
+    platform="tiktok",
+    post_id="7412345678901234567",
+    message="Thanks for watching!",
+)
+client.create_comment(
+    user="my-profile",
+    platform="tiktok",
+    comment_id="7412345678909999999",
+    message="Glad you liked it",
+)
+
+# Delete one
+client.delete_comment(
+    user="my-profile", platform="tiktok", comment_id="7412345678909999999"
+)
+```
+
+You can also have the first comment posted for you right after publishing, with
+`first_comment` for every platform or `tiktok_first_comment` for TikTok alone.
+
+On TikTok all of this needs the `comments` capability, which the account grants
+when it connects — see
+[What a TikTok connection can do](#what-a-tiktok-connection-can-do-capabilities).
+
+#### Moderating a comment: hide, like, pin
+
+`comment_action()` does the three and undoes them, on any platform that
+supports it. Each action carries its own inverse, and `post_id` is only sent
+when the platform needs it:
+
+```python
+client.comment_action(
+    user="my-profile", platform="tiktok", action="hide",
+    comment_id="7412345678909999999", post_id="7412345678901234567",
+)
+client.comment_action(
+    user="my-profile", platform="tiktok", action="like",
+    comment_id="7412345678909999999",
+)
+client.comment_action(
+    user="my-profile", platform="tiktok", action="unpin",
+    comment_id="7412345678909999999", post_id="7412345678901234567",
+)
+```
+
+| `action` | Undo | `post_id` |
+| --- | --- | --- |
+| `hide` | `unhide` | required |
+| `like` | `unlike` | not sent |
+| `pin` | `unpin` | required |
+
+### Audience
+
+Where the analytics methods answer *how did my posts do*, `get_audience()`
+answers *who is following me*. One endpoint, one `platform` parameter, like
+every other question in the API.
+
+```python
+audience = client.get_audience(
+    user="my-profile",
+    platform="tiktok",
+    start_date="2026-07-01",
+    end_date="2026-07-30",
+)
+
+print(audience["range"])                 # the window actually used
+print(audience["audience"]["countries"])  # and "cities", "ages", "genders"
+print(audience["activity_by_hour"])       # [{"hour": "14", "followers_online": 1494}, ...]
+print(audience["followers_daily"])        # [{"date", "total", "new", "lost"}, ...]
+print(audience["profile_actions"])        # bio link, address, email, phone, leads
+print(audience["bio_description"])
+```
+
+The window is clamped on the server: at most 60 days, and `end_date` always
+before today. A wider window is trimmed to what the platform accepts instead of
+failing.
+
+Ask for a `benchmark_category` and the same call also returns how the account
+compares with the average of that category. The accepted categories come back in
+`benchmark_categories` on every response, so a picker needs no second call:
+
+```python
+categories = client.get_audience(
+    user="my-profile", platform="tiktok"
+)["benchmark_categories"]
+
+benchmark = client.get_audience(
+    user="my-profile", platform="tiktok",
+    benchmark_category="SOFTWARE_AND_APPS",
+)["benchmark"]
+print(benchmark["average_engagement_rate"], benchmark["average_video_views"])
+```
+
+### Suggestions
+
+`get_suggestions()` answers *what is worth posting about*: the hashtags or the
+searches a platform suggests around a keyword. One endpoint for both, told apart
+by `type`.
+
+```python
+hashtags = client.get_suggestions(
+    user="my-profile", platform="tiktok", type="hashtags",
+    q="pilates", country_code="ES", language="es",
+)["hashtags"]
+print(hashtags)  # [{"name": ..., "view_count": ...}, ...]
+
+keywords = client.get_suggestions(
+    user="my-profile", platform="tiktok", type="keywords", q="pilates",
+)["keywords"]
+```
+
+Per-post numbers stay in `get_post_analytics()`. On TikTok that response carries
+more than the usual counters: `retention` (the curve, second by second),
+`impression_sources` (For You, search, profile...), `audience_types` (followers
+vs non-followers), `new_followers`, `reach` and the watch times.
+
+Asking a platform a question it cannot answer fails with
+`platform_not_supported` and the list of the ones that can.
+
+## What a TikTok connection can do (`capabilities`)
+
+Not every TikTok connection can do the same things. `client.list_users()`
+(`GET /api/uploadposts/users`) returns a `capabilities` array on each profile's
+TikTok account; check it before offering a feature.
+
+| Capability | What it unlocks |
+| --- | --- |
+| `music` | `tiktok_music_id` and the volume/trim fields, plus `get_tiktok_trending_music()` and `search_tiktok_music()` |
+| `location` | `tiktok_location_id` / `tiktok_location_name`, plus `get_tiktok_locations()` |
+| `cover_image` | `tiktok_cover_image_url` |
+| `cover_timestamp` | `cover_timestamp` |
+| `draft` | `tiktok_upload_to_draft` |
+| `video_privacy` | `privacy_level` on video |
+| `photo_privacy` | `privacy_level` on photo posts |
+| `profile_analytics` | `get_audience()` and `get_suggestions(type="hashtags")` with `platform="tiktok"` |
+| `comments` | Comments on TikTok: `get_post_comments()` (top-level and replies), `create_comment()`, `delete_comment()`, `comment_action()` and `tiktok_first_comment` |
+| `trend_search` | `get_suggestions(type="keywords")` with `platform="tiktok"` |
+
+> **`comments` and `trend_search` need the account to be reconnected.** TikTok
+> grants them at connect time, so an account linked before they existed keeps
+> working for everything else but will not list them — reconnect it from Manage
+> Users to enable them.
+
+If a connection lacks a capability the upload field is simply ignored: the post
+still publishes and the response carries a per-field `warnings` string. The
+methods above answer with an error asking for a reconnection.
+
 ## TikTok music, location, cover and drafts
 
-> **Capabilities.** These options are available on connections that declare the
-> matching capability (`music`, `location`, `cover_image`, `draft`) — see the
-> `capabilities` array on the TikTok account returned by
-> `GET /api/uploadposts/users` (`client.list_users()`). Other values that can
-> appear there: `cover_timestamp`, `photo_privacy`, `video_privacy`,
-> `inbox_fallback` and `profile_analytics`. If your connection does
-> not have the capability, the field is ignored, the post still publishes, and
-> the response includes a per-field `warnings` string — reconnect the TikTok
-> account to enable it.
+> Needs the `music`, `location`, `cover_image` or `draft` capability — see
+> [What a TikTok connection can do](#what-a-tiktok-connection-can-do-capabilities).
 
 ```python
 # 1. Pick a track and a place
@@ -525,6 +693,7 @@ These options work across all upload methods:
 | `user` | Profile name (required) |
 | `platforms` | Target platforms list (required) |
 | `first_comment` | First comment to post |
+| `tiktok_first_comment` | First comment for TikTok only (needs the `comments` capability) |
 | `alt_text` | Alt text for accessibility |
 | `scheduled_date` | ISO date for scheduling |
 | `timezone` | Timezone for scheduled date |

{upload_post-2.10.0 → upload_post-2.12.0}/upload_post.egg-info/SOURCES.txt

@@ -1,5 +1,6 @@
 README.md
 setup.py
+tests/test_comments_audience.py
 upload_post/__init__.py
 upload_post/api_client.py
 upload_post/cli.py