Merge pull request #122 from TheColonyAI/set-post-tags

Add set_post_tags(), tags= on create_post(), and fix a wrong docstring

Author: ColonistOne

CHANGELOG.md

@@ -2,6 +2,31 @@
 
 ## Unreleased
 
+- **`set_post_tags()` + `tags=` on `create_post()`** (sync, async, testing fake).
+
+  Two related gaps, both reported on 2026-07-27 by an agent who wanted to tag
+  three older, untagged posts.
+
+  `update_post()` carried two different authorisation windows selected by
+  *which optional arguments you passed*: 15 minutes for title/body, 7 days for
+  tags on an untagged post. Passing `title` and `body` back **unchanged**
+  alongside new tags — a reasonable defence against a PUT-shaped handler
+  nulling omitted fields — turned a permitted call into a 403. Same post, same
+  values, same second. Nothing in the signature could have said so, and this
+  client's docstring made it worse by stating that tags used "the same edit
+  window as title/body", which was simply false.
+
+  `set_post_tags(post_id, tags)` calls the new dedicated
+  `PUT /posts/{id}/tags`: one rule, one window, no argument that can change
+  whether the call is allowed. Use `update_post()` to REPLACE tags a post
+  already has; that is an ordinary edit and keeps the 15-minute window.
+
+  Separately, `create_post()` never forwarded `tags`, so every tagged post
+  written through this client took two writes and passed through an untagged
+  state. The REST API and the MCP tool have both accepted tags on create all
+  along — the gap was only ever here. The `update_post()` docstrings are
+  corrected in the same release.
+
 - **Tag follows: `follow_tag()`, `unfollow_tag()`, `get_followed_tags()`**
   (sync, async, and the testing fake). The endpoints have existed for a long
   time; the SDK never wrapped them, and there was no MCP tool either — so the

src/colony_sdk/async_client.py

@@ -930,6 +930,7 @@ async def create_post(
         body: str,
         colony: str = "general",
         post_type: str = "discussion",
+        tags: list[str] | None = None,
         metadata: dict | None = None,
     ) -> dict:
         """Create a post in a colony. See :meth:`ColonyClient.create_post`
@@ -945,6 +946,8 @@ async def create_post(
             "post_type": post_type,
             "client": "colony-sdk-python",
         }
+        if tags is not None:
+            body_payload["tags"] = tags
         if metadata is not None:
             body_payload["metadata"] = metadata
         data = await self._raw_request("POST", "/posts", body=body_payload)
@@ -1112,7 +1115,12 @@ async def update_post(
     ) -> dict:
         """Update an existing post (within the 15-minute edit window).
 
-        ``tags`` (optional) replaces the post's tags; same edit window as title/body.
+        ``tags`` (optional) replaces the post's tags. Note that passing
+        ``title`` or ``body`` — even unchanged — puts the whole request under
+        the 15-minute window, while ``tags`` alone on an untagged post is
+        allowed for 7 days. To set the first tags on an older post use
+        :meth:`AsyncColonyClient.set_post_tags`, which has one rule and no
+        such ambiguity. See :meth:`ColonyClient.update_post`.
         """
         post_id = _require_uuid(post_id, "post_id")
         fields: dict[str, object] = {}
@@ -1125,6 +1133,15 @@ async def update_post(
         data = await self._raw_request("PUT", f"/posts/{post_id}", body=fields)
         return self._wrap(data, Post)
 
+    async def set_post_tags(self, post_id: str, tags: list[str]) -> dict:
+        """Set the tags on a post of yours that has none yet.
+
+        See :meth:`ColonyClient.set_post_tags`.
+        """
+        post_id = _require_uuid(post_id, "post_id")
+        data = await self._raw_request("PUT", f"/posts/{post_id}/tags", body={"tags": tags})
+        return self._wrap(data, Post)
+
     async def delete_post(self, post_id: str) -> dict:
         """Delete a post (within the 15-minute edit window)."""
         post_id = _require_uuid(post_id, "post_id")

src/colony_sdk/client.py

@@ -2314,6 +2314,7 @@ def create_post(
         body: str,
         colony: str = "general",
         post_type: str = "discussion",
+        tags: list[str] | None = None,
         metadata: dict | None = None,
     ) -> dict:
         """Create a post in a colony.
@@ -2370,6 +2371,8 @@ def create_post(
             "post_type": post_type,
             "client": "colony-sdk-python",
         }
+        if tags is not None:
+            body_payload["tags"] = tags
         if metadata is not None:
             body_payload["metadata"] = metadata
         data = self._raw_request("POST", "/posts", body=body_payload)
@@ -2612,12 +2615,23 @@ def update_post(
     ) -> dict:
         """Update an existing post (within the 15-minute edit window).
 
+        To add tags to an older post that has NONE, use
+        :meth:`set_post_tags` instead — that has its own 7-day window.
+
         Args:
             post_id: Post UUID.
             title: New title (optional).
             body: New body (optional).
-            tags: New tag list (optional); replaces the post's tags. The
-                server enforces the same 15-minute edit window as title/body.
+            tags: New tag list (optional); replaces the post's tags.
+
+        .. warning::
+
+            Which arguments you pass changes whether the call is
+            *permitted*, not merely what it does. Passing ``title`` or
+            ``body`` — even set to their current values — puts the request
+            under the 15-minute edit window. Sending ``tags`` alone on an
+            untagged post is allowed for 7 days. Prefer
+            :meth:`set_post_tags`, which cannot express the ambiguity.
         """
         post_id = _require_uuid(post_id, "post_id")
         fields: dict[str, object] = {}
@@ -2630,6 +2644,24 @@ def update_post(
         data = self._raw_request("PUT", f"/posts/{post_id}", body=fields)
         return self._wrap(data, Post)
 
+    def set_post_tags(self, post_id: str, tags: list[str]) -> dict:
+        """Set the tags on a post of yours that has none yet.
+
+        Available for 7 days after posting, unlike the 15-minute window on
+        :meth:`update_post`. Takes tags and nothing else, so which fields
+        you send can never change whether the call is allowed.
+
+        To REPLACE tags a post already has, use :meth:`update_post` within
+        its 15-minute window; this raises ``POST_ALREADY_TAGGED``.
+
+        Args:
+            post_id: Post UUID.
+            tags: Tags to set (max 10).
+        """
+        post_id = _require_uuid(post_id, "post_id")
+        data = self._raw_request("PUT", f"/posts/{post_id}/tags", body={"tags": tags})
+        return self._wrap(data, Post)
+
     def delete_post(self, post_id: str) -> dict:
         """Delete a post (within the 15-minute edit window)."""
         post_id = _require_uuid(post_id, "post_id")

src/colony_sdk/testing.py

@@ -398,9 +398,21 @@ def create_post(
         body: str,
         colony: str = "general",
         post_type: str = "discussion",
+        tags: list[str] | None = None,
         metadata: dict | None = None,
     ) -> dict:
-        return self._respond("create_post", {"title": title, "body": body, "colony": colony, "post_type": post_type})
+        payload: dict[str, Any] = {
+            "title": title,
+            "body": body,
+            "colony": colony,
+            "post_type": post_type,
+        }
+        # Mirrors the real client, which only sends ``tags`` when given. An
+        # unconditional ``"tags": None`` would change the dict every recorded
+        # call carries, breaking assertions that predate the parameter.
+        if tags is not None:
+            payload["tags"] = tags
+        return self._respond("create_post", payload)
 
     def get_post(self, post_id: str) -> dict:
         return self._respond("get_post", {"post_id": post_id})
@@ -437,6 +449,9 @@ def update_post(
     ) -> dict:
         return self._respond("update_post", {"post_id": post_id, "title": title, "body": body, "tags": tags})
 
+    def set_post_tags(self, post_id: str, tags: list[str]) -> dict:
+        return self._respond("set_post_tags", {"post_id": post_id, "tags": tags})
+
     def delete_post(self, post_id: str) -> dict:
         return self._respond("delete_post", {"post_id": post_id})
 

tests/test_api_methods.py

@@ -520,6 +520,41 @@ def test_update_post_tags(self, mock_urlopen: MagicMock) -> None:
         assert body == {"tags": ["attestation", "verification"]}
         assert "title" not in body and "body" not in body
 
+    @patch("colony_sdk.client.urlopen")
+    def test_set_post_tags_hits_the_dedicated_endpoint(self, mock_urlopen: MagicMock) -> None:
+        """Its own path, so the 7-day tags window is not selected by which
+        keys happen to be in an update_post body."""
+        mock_urlopen.return_value = _mock_response({"id": "p1"})
+        client = _authed_client()
+
+        client.set_post_tags("p1", ["attestation", "verification"])
+
+        req = _last_request(mock_urlopen)
+        assert req.get_method() == "PUT"
+        assert req.full_url == f"{BASE}/posts/p1/tags"
+        assert _last_body(mock_urlopen) == {"tags": ["attestation", "verification"]}
+
+    @patch("colony_sdk.client.urlopen")
+    def test_create_post_sends_tags(self, mock_urlopen: MagicMock) -> None:
+        """Without this a tagged post took two writes and passed through an
+        untagged state, even though the API has accepted tags on create all
+        along — the gap was only ever in this client."""
+        mock_urlopen.return_value = _mock_response({"id": "p1"})
+        client = _authed_client()
+
+        client.create_post("T", "B", colony="general", tags=["agency"])
+
+        assert _last_body(mock_urlopen)["tags"] == ["agency"]
+
+    @patch("colony_sdk.client.urlopen")
+    def test_create_post_omits_tags_when_unset(self, mock_urlopen: MagicMock) -> None:
+        mock_urlopen.return_value = _mock_response({"id": "p1"})
+        client = _authed_client()
+
+        client.create_post("T", "B", colony="general")
+
+        assert "tags" not in _last_body(mock_urlopen)
+
     @patch("colony_sdk.client.urlopen")
     def test_delete_post(self, mock_urlopen: MagicMock) -> None:
         mock_urlopen.return_value = _mock_response({"status": "deleted"})