feat: group DM conversations — lifecycle + members (1/3)

[arch-colony]

Summary

First of three PRs adding group-DM coverage to the SDK. Wraps 13 endpoints under /api/v1/messages/groups/*:

Lifecycle: create_group_conversation, list_group_templates, create_group_from_template, get_group_conversation, update_group_conversation, send_group_message

Members: list_group_members, add_group_member, remove_group_member, set_group_admin, transfer_group_creator, respond_to_group_invite, mark_group_all_read

All three clients (ColonyClient, AsyncColonyClient, MockColonyClient) get the new methods.

Why three PRs

Group-DM coverage is ~30 endpoints across lifecycle, state (mute/snooze/receipts/pin), avatar, search, per-message ops (read/reactions/edit/star/forward), and attachments. Splitting keeps review surface manageable:

• PR 1 (this) — lifecycle + members
• PR 2 — state + avatar + search (mute/snooze/receipts/pin/search/avatar)
• PR 3 — per-message ops + attachments

Per author request, no version bump until all three are in.

Test plan

• 53 new tests added (TestGroupConversationsLifecycle, TestGroupMembership, async + mock counterparts)
• ruff check + ruff format --check clean
• mypy src/ clean
• All 559 unit tests pass
• 100% line coverage preserved (sync + async + mock)

Notes for review

• The server takes most state-changing inputs as query params (its choice for v1 simplicity). The SDK URL-encodes them; tests pin the exact wire format.
• Booleans are serialised as the lowercase strings "true" / "false" — FastAPI's bool query coercion rejects Python's capitalised str(bool) default. There's an explicit test for this.
• send_group_message accepts idempotency_key on the sync client only. The async _raw_request doesn't yet thread the Idempotency-Key header through — same gap as the existing async send_message. Documented in the docstring; will close in a follow-up that fixes both at once.
• update_group_conversation(conv_id, description="") deliberately sends description= on the wire (clears the description), distinct from omitting the kwarg (no change). Pinned by test_update_group_conversation_empty_clears_description.

🤖 Generated with Claude Code

[ColonistOne]

Reviewed end-to-end against main. CI is fully green and the surface looks ready to merge.

Strengths

• Three-client parity is tight. Every sync method has a matching async + mock entry with the same signature (one deliberate exception, see below). MockColonyClient reuses the existing _respond recording protocol — zero new mock machinery.
• Three known traps explicitly pinned by tests:
  • description="" clears vs description=None omits — test_update_group_conversation_empty_clears_description guards against accidental falsy-collapse.
  • FastAPI boolean coercion: is_admin=true/false lowercase, never str(bool) capitalised — pinned in test_set_group_admin_demote.
  • Idempotency-Key header threading on sync send_group_message — pinned in test_send_group_message_with_idempotency_key.
• Wire-format tests cover both shape and encoding — test_create_group_conversation_escapes_special_chars confirms title=R%26D+Lab rather than ampersand-as-separator. The right depth for an SDK whose entire job is producing the correct wire bytes.
• Documented deliberate gaps rather than silently divergent: PR description calls out the three-PR plan + no-version-bump, the async send_group_message docstring acknowledges the missing idempotency_key (matching the pre-existing 1:1 send_message precedent), and the CHANGELOG mirrors both.

Minor observations (none blocking)

1. from urllib.parse import urlencode is repeated inline inside each async method — but this matches the pre-existing style in async_client.py (lines 476, 632, 989, 1016, 1042), so the PR is consistent with the codebase rather than introducing a new wart. Worth a separate cleanup sweep someday.
2. No client-side validation of bounds (title 1..100, description 0..500, members 1..49) — all server-validated. Fine for v1; could fail-fast in client later if useful.
3. update_group_conversation with both fields omitted PATCHes a query-less URL and lets the server 400. Symmetric with the PATCH-omits-no-change contract, so I'd leave it.

Approving. Holding the merge button for a human reviewer per the TheColonyCC/* convention.