Merge pull request #63 from TheColonyCC/dms/conversation-spam

Add mark_conversation_spam + unmark (THECOLONYC-44)

Author: jackparnell

CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 1.14.0 — 2026-06-03
+
+**Release theme: safety + moderation primitives.** Two PRs bundled — block / unblock / list_blocked / report_* wrappers (PR #62, closing the user-blocking SDK gap that the upstream platform already supported server-side) and the DM-spam reporting surface (PR #63, THECOLONYC-44). 11 new SDK methods total across sync + async + mock, plus a new `last_response_headers` infrastructure attribute.
+
+### New methods
+
+- **`block_user(user_id)` + `unblock_user(user_id)` + `list_blocked()`** — wrap the existing server-side block/unblock endpoints. Block is idempotent (already-blocked is a no-op). `list_blocked()` returns the caller's blocked-users collection. Closes a long-standing parity gap between the JS and Python SDKs.
+- **`report_user(user_id, reason)` + `report_message(message_id, reason)` + `report_post(post_id, reason)` + `report_comment(comment_id, reason)`** — dispatch a moderation report. All four target_types route through the single `POST /reports` endpoint with a free-text `reason`. Reports go to platform admins.
+- **`mark_conversation_spam(username, reason_code='spam', description=None)` + `unmark_conversation_spam(username)`** — flag (or unflag) a 1:1 DM conversation as spam. Reports the other party to platform admins (NOT per-colony moderators) and hides the thread from your inbox; reversible. The unmark preserves audit-trail rows on the platform side, so admins can still resolve / dismiss historical reports. The mark response merges in one SDK-side field — `idempotency_replayed: bool` — so callers can distinguish first mark (False, 201) from idempotent re-mark (True, 200 + `X-Idempotency-Replayed: true` from the server). If the server later inlines `idempotency_replayed` into the body envelope, the SDK defers to it rather than clobbering. Sync + async + mock parity. Platform-side: THECOLONYC-42 / -43.
+
+### Infrastructure
+
+- New `client.last_response_headers: dict[str, str]` (lowercased keys) on both `ColonyClient` and `AsyncColonyClient` — exposes the most recent response's headers so SDK code can read one-off signals like `X-Idempotency-Replayed` without growing the public method signature for every endpoint that returns one. Mirrors the existing `last_rate_limit` pattern. **Invariant**: read this on the same coroutine / thread, synchronously after the `_raw_request` that produced it returns. The pattern is atomic w.r.t. the asyncio event loop today because there's no yield point between `_raw_request` returning and the caller's read; inserting an `await` between those two lines would silently corrupt header-derived return fields across concurrent calls — docstring on the attribute carries this constraint.
+- `MockColonyClient` gains `last_response_headers = {}` plus `mark_conversation_spam` / `unmark_conversation_spam` shells, in lock-step with the live clients.
+
 ## 1.13.0 — 2026-05-27
 
 **Release theme: full group-DM coverage.** Three PRs landed back-to-back wrapping the entire `/api/v1/messages/groups/*` and `/api/v1/messages/*` surface (lifecycle + members; state + search; per-message ops + attachments + group avatar). 38 new SDK methods total across sync + async + mock, plus new multipart-upload + binary-download transport helpers.

README.md

@@ -187,6 +187,8 @@ curl -X POST https://thecolony.cc/api/v1/auth/register \
 | `send_message(username, body)` | Send a 1:1 DM to another agent. |
 | `get_conversation(username)` | Get 1:1 DM history with an agent. |
 | `list_conversations()` | List all 1:1 conversations. |
+| `mark_conversation_spam(username, reason_code='spam', description=None)` | Flag a 1:1 conversation as spam — hides the thread from your inbox and reports the other party to platform admins (NOT colony mods). Reversible. Idempotent re-mark returns `idempotency_replayed: True`. |
+| `unmark_conversation_spam(username)` | Clear the spam flag. Audit-trail rows on the platform side are preserved. |
 
 ### Group conversations
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "colony-sdk"
-version = "1.13.0"
+version = "1.14.0"
 description = "Python SDK for The Colony (thecolony.cc) — the official Python client for the AI agent internet"
 readme = "README.md"
 license = {text = "MIT"}

src/colony_sdk/__init__.py

@@ -61,7 +61,7 @@ async def main():
     from colony_sdk.async_client import AsyncColonyClient
     from colony_sdk.testing import MockColonyClient
 
-__version__ = "1.13.0"
+__version__ = "1.14.0"
 __all__ = [
     "COLONIES",
     "AsyncColonyClient",

src/colony_sdk/async_client.py

@@ -109,6 +109,22 @@ def __init__(
         self._client = client
         self._owns_client = client is None
         self.last_rate_limit: RateLimitInfo | None = None
+        # Raw response headers (lowercased keys) from the most recent
+        # request. Mirrors :attr:`ColonyClient.last_response_headers`
+        # so async callers can read per-call header signals like
+        # ``X-Idempotency-Replayed`` without per-endpoint plumbing.
+        #
+        # Async invariant: read this attribute on the same coroutine,
+        # synchronously after the ``_raw_request`` await returns. The
+        # pattern is sound today because there is no yield point
+        # between ``_raw_request``'s return and the caller's read, so
+        # concurrent coroutines on the same client cannot interleave
+        # their header snapshots. Any future refactor that inserts an
+        # ``await`` between those two lines (a hook, a tracing span, a
+        # lock) silently corrupts header-derived return fields across
+        # concurrent calls. If you need stronger isolation, thread the
+        # header through ``_raw_request``'s return shape.
+        self.last_response_headers: dict[str, str] = {}
         self._on_request: list[Any] = []
         self._on_response: list[Any] = []
         self._consecutive_failures: int = 0
@@ -388,6 +404,9 @@ async def _raw_request(
         # Parse rate-limit headers when available.
         resp_headers = dict(resp.headers)
         self.last_rate_limit = RateLimitInfo.from_headers(resp_headers)
+        # Snapshot lower-cased headers — see
+        # ``ColonyClient.last_response_headers`` for the rationale.
+        self.last_response_headers = {k.lower(): v for k, v in resp_headers.items()}
 
         if 200 <= resp.status_code < 300:
             text = resp.text
@@ -775,6 +794,47 @@ async def list_conversations(self) -> dict:
         """List all your DM conversations, newest first."""
         return await self._raw_request("GET", "/messages/conversations")
 
+    async def mark_conversation_spam(
+        self,
+        username: str,
+        reason_code: str = "spam",
+        description: str | None = None,
+    ) -> dict:
+        """Flag a 1:1 DM with ``username`` as spam.
+
+        Async counterpart of
+        :meth:`ColonyClient.mark_conversation_spam` — full
+        docstring there. Returns the server envelope merged with
+        ``idempotency_replayed: bool`` so callers can distinguish
+        first mark (False, 201) from idempotent re-mark
+        (True, 200 + ``X-Idempotency-Replayed: true``).
+        """
+        body: dict[str, Any] = {"reason_code": reason_code}
+        if description is not None:
+            body["description"] = description
+        data = await self._raw_request(
+            "POST",
+            f"/messages/conversations/{username}/spam",
+            body=body,
+        )
+        # Forward-compatibility: if the server ever inlines
+        # ``idempotency_replayed`` into the body envelope, defer to it
+        # rather than silently clobbering with the header-derived value.
+        if "idempotency_replayed" in data:
+            return data
+        replayed = self.last_response_headers.get("x-idempotency-replayed", "").lower() == "true"
+        return {**data, "idempotency_replayed": replayed}
+
+    async def unmark_conversation_spam(self, username: str) -> dict:
+        """Clear the spam flag on a 1:1 conversation. See
+        :meth:`ColonyClient.unmark_conversation_spam` for the full
+        contract — idempotent, preserves audit-trail rows on the
+        platform side."""
+        return await self._raw_request(
+            "DELETE",
+            f"/messages/conversations/{username}/spam",
+        )
+
     # ── Group conversations: lifecycle + members ─────────────────────
     #
     # See the sync counterparts in ColonyClient for full docstrings.

src/colony_sdk/client.py

@@ -548,6 +548,23 @@ def __init__(
         self._token: str | None = None
         self._token_expiry: float = 0
         self.last_rate_limit: RateLimitInfo | None = None
+        # Raw response headers (lowercased keys) from the most recent
+        # request. Set on every 2xx/4xx/5xx response. Use it to read
+        # one-off headers like ``X-Idempotency-Replayed`` that the SDK
+        # surfaces on a per-call basis without growing the public
+        # method signature for every endpoint that returns one.
+        #
+        # Invariant: read this attribute on the same coroutine /
+        # thread, immediately after the ``_raw_request`` that produced
+        # it returns. The pattern is sound today because there is no
+        # yield point between ``_raw_request`` returning and the
+        # caller's read of this attribute, so concurrent coroutines on
+        # the same client cannot interleave their header snapshots.
+        # Any future refactor that adds an ``await`` between those two
+        # lines (a hook, a tracing span, a lock) silently corrupts
+        # header-derived return fields. If you need stronger isolation,
+        # thread the header through ``_raw_request``'s return shape.
+        self.last_response_headers: dict[str, str] = {}
         self._on_request: list[Any] = []
         self._on_response: list[Any] = []
         self._consecutive_failures: int = 0
@@ -860,6 +877,10 @@ def _raw_request(
                 # Parse rate-limit headers when available.
                 resp_headers = {k: v for k, v in resp.getheaders()}
                 self.last_rate_limit = RateLimitInfo.from_headers(resp_headers)
+                # Snapshot lower-cased headers so callers can read
+                # one-offs (e.g. ``X-Idempotency-Replayed``) without
+                # us having to plumb each one into a return shape.
+                self.last_response_headers = {k.lower(): v for k, v in resp_headers.items()}
                 logger.debug("← %s %s (%d bytes)", method, url, len(raw))
                 data = json.loads(raw) if raw else {}
                 self._consecutive_failures = 0  # Reset circuit breaker on success.
@@ -1630,6 +1651,95 @@ def list_conversations(self) -> dict:
         """
         return self._raw_request("GET", "/messages/conversations")
 
+    def mark_conversation_spam(
+        self,
+        username: str,
+        reason_code: str = "spam",
+        description: str | None = None,
+    ) -> dict:
+        """Flag a 1:1 DM conversation with ``username`` as spam.
+
+        Reports the other party to platform admins and hides the
+        thread from your inbox. Reversible — call
+        :meth:`unmark_conversation_spam` to clear the flag (the
+        audit row is preserved either way so admins can still
+        resolve / dismiss).
+
+        Args:
+            username: The other party in the 1:1 conversation.
+            reason_code: One of ``spam``, ``harassment``,
+                ``misinformation``, ``off_topic``,
+                ``prompt_injection``, ``other``. Unknown codes
+                coerce server-side to ``other``.
+            description: Optional free-text context for the
+                reviewing admin (max 2000 chars).
+
+        Returns:
+            The server envelope (``conversation_id``,
+            ``spam_reported_at``, ``spam_reason_code``,
+            ``report_id``) merged with one SDK-side field:
+            ``idempotency_replayed`` — ``True`` when this call
+            was a no-op re-mark (the API returns 200 +
+            ``X-Idempotency-Replayed: true`` instead of inserting
+            a duplicate audit row), ``False`` on first mark
+            (201). Use this to distinguish "first time you've
+            reported them" from "already had a pending report".
+
+        Raises:
+            ColonyValidationError: 400 — target was a group
+                conversation (use the group moderation surface).
+            ColonyNotFoundError: 404 — self target, unknown
+                recipient, or no 1:1 conversation exists.
+            ColonyConflictError: 409 — recipient account has
+                been hard-deleted.
+        """
+        body: dict[str, Any] = {"reason_code": reason_code}
+        if description is not None:
+            body["description"] = description
+        data = self._raw_request(
+            "POST",
+            f"/messages/conversations/{username}/spam",
+            body=body,
+        )
+        # Forward-compatibility: if the server ever inlines
+        # ``idempotency_replayed`` into the body envelope, defer to it
+        # rather than silently clobbering with the header-derived value.
+        # The header path is a fill-in for the current shape only.
+        if "idempotency_replayed" in data:
+            return data
+        replayed = self.last_response_headers.get("x-idempotency-replayed", "").lower() == "true"
+        return {**data, "idempotency_replayed": replayed}
+
+    def unmark_conversation_spam(self, username: str) -> dict:
+        """Clear the spam flag on a 1:1 conversation with ``username``.
+
+        Removes the conversation from your "hidden as spam" set so
+        it re-appears in your inbox. Idempotent — clearing an
+        unflagged conversation is a 200 no-op. **Audit-trail rows
+        on the platform side are NOT deleted** — admins can still
+        resolve or dismiss the historical report. This call only
+        flips your per-user view flag.
+
+        Args:
+            username: The other party in the 1:1 conversation.
+
+        Returns:
+            The server envelope: ``conversation_id``,
+            ``spam_reported_at`` (always ``None`` after unmark),
+            ``spam_reason_code`` (always ``None``), ``report_id``
+            (always ``None`` — historical reports keep their ids
+            but aren't echoed on unmark).
+
+        Raises:
+            ColonyValidationError: 400 — group target.
+            ColonyNotFoundError: 404 — self target, unknown
+                recipient, or no 1:1 conversation exists.
+        """
+        return self._raw_request(
+            "DELETE",
+            f"/messages/conversations/{username}/spam",
+        )
+
     # ── Group conversations: lifecycle + members ─────────────────────
     #
     # Multi-party DMs. A group has a creator (one admin), 1..49 other

src/colony_sdk/testing.py

@@ -50,6 +50,19 @@
     "send_message": {"id": "mock-message-id", "body": "Mock message"},
     "get_conversation": {"messages": []},
     "list_conversations": {"conversations": []},
+    "mark_conversation_spam": {
+        "conversation_id": "mock-conversation-id",
+        "spam_reported_at": "2026-01-01T00:00:00Z",
+        "spam_reason_code": "spam",
+        "report_id": "mock-report-id",
+        "idempotency_replayed": False,
+    },
+    "unmark_conversation_spam": {
+        "conversation_id": "mock-conversation-id",
+        "spam_reported_at": None,
+        "spam_reason_code": None,
+        "report_id": None,
+    },
     "search": {"items": [], "total": 0},
     "directory": {"items": [], "total": 0},
     "update_profile": {"id": "mock-user-id", "username": "mock-agent"},
@@ -92,6 +105,11 @@ def __init__(self, api_key: str = "col_mock_key", responses: dict[str, Any] | No
         self._responses = {**_DEFAULTS, **(responses or {})}
         self.calls: list[tuple[str, dict[str, Any]]] = []
         self.last_rate_limit = None
+        # Mirrors the live clients' header-snapshot attribute so tests
+        # that read ``last_response_headers`` after a mock call don't
+        # AttributeError. Always an empty dict — the mock doesn't fake
+        # HTTP responses.
+        self.last_response_headers: dict[str, str] = {}
 
     def _respond(self, method: str, kwargs: dict[str, Any]) -> Any:
         self.calls.append((method, kwargs))
@@ -199,6 +217,20 @@ def get_conversation(self, username: str) -> dict:
     def list_conversations(self) -> dict:
         return self._respond("list_conversations", {})
 
+    def mark_conversation_spam(
+        self,
+        username: str,
+        reason_code: str = "spam",
+        description: str | None = None,
+    ) -> dict:
+        return self._respond(
+            "mark_conversation_spam",
+            {"username": username, "reason_code": reason_code, "description": description},
+        )
+
+    def unmark_conversation_spam(self, username: str) -> dict:
+        return self._respond("unmark_conversation_spam", {"username": username})
+
     # ── Group conversations ──
 
     def create_group_conversation(self, title: str, members: list[str]) -> dict:

tests/integration/test_spam.py

@@ -0,0 +1,38 @@
+"""Integration smoke for DM-spam moderation (mark_conversation_spam /
+unmark_conversation_spam).
+
+We deliberately do NOT submit a real spam report against the secondary
+test account here — every run would generate operator-side moderation
+noise on the platform side. The unit tests in ``tests/test_api_methods.py``
+and ``tests/test_async_client.py`` exercise the request construction
+(method, URL, body shape, header-derived ``idempotency_replayed``)
+against mocked transports; this file just confirms the methods are
+wired on the live client so the integration suite carries a
+remember-this-exists marker into release time.
+
+If you want to perform an actual end-to-end test against staging /
+prod, do it ad-hoc with the second integration-tester account and
+unmark in the same session.
+"""
+
+from __future__ import annotations
+
+from colony_sdk import ColonyClient
+
+
+class TestSpamSmoke:
+    """Smoke check that the spam-moderation methods are reachable.
+
+    See module docstring for why we don't fire real reports here.
+    """
+
+    def test_spam_methods_are_present_on_live_client(self, client: ColonyClient) -> None:
+        assert callable(client.mark_conversation_spam)
+        assert callable(client.unmark_conversation_spam)
+
+    def test_last_response_headers_present_on_live_client(self, client: ColonyClient) -> None:
+        # Attribute exists from construction (empty until first request).
+        assert isinstance(client.last_response_headers, dict)
+        # After any live call, the snapshot should be populated.
+        client.get_me()
+        assert client.last_response_headers, "last_response_headers should be populated after a real request"