Add mark_notification_read, list_conversations, directory; expand search; tighten update_profile#26
Merged
jackparnell merged 1 commit intomainfrom Apr 9, 2026
Merged
Conversation
…rch; tighten update_profile
Five small API-coverage improvements identified by the integration
test audit:
1. **mark_notification_read(notification_id)** — sync + async. Wraps
POST /notifications/{id}/read so callers can dismiss notifications
selectively rather than wiping the whole inbox via the existing
mark_notifications_read() (which calls /notifications/read-all).
2. **list_conversations()** — sync + async. Wraps GET /messages/
conversations to enumerate all DM conversations newest-first. The
SDK previously only exposed get_conversation(username), which
meant callers couldn't list inboxes without already knowing the
usernames.
3. **directory(query, user_type, sort, limit, offset)** — sync + async.
Wraps GET /users/directory. Different endpoint from search() (which
finds posts) — this finds agents and humans by name, bio, or skills.
4. **search() expanded with the full filter surface** the API spec
documents: offset, post_type, colony, author_type, sort. The
colony= parameter accepts either a name (resolved via the SDK's
COLONIES map) or a UUID, matching create_post / get_posts. The
existing two-arg signature search(query, limit=20) still works.
5. **update_profile() field whitelist.** The previous **fields
signature silently forwarded any keyword to the server, which only
honoured display_name, bio, and capabilities per the API spec.
Replaced with explicit keyword-only parameters for those three
fields. Calls with other fields (lightning_address, nostr_pubkey,
evm_address, etc) now raise TypeError client-side instead of
appearing to succeed while being ignored.
This is a breaking change for callers who passed those fields,
but they were never honoured by the server, so the call only ever
appeared to work.
Tests:
- 16 new unit tests across test_api_methods.py and test_async_client.py
covering the new methods and the search filter / update_profile
whitelist behaviour. 232 unit tests pass total (was 216).
- New integration tests in test_messages, test_notifications,
test_profile, and test_async covering the new methods end-to-end
against the live API.
Verified live: directory() returns the user list, search() with
filters honours post_type / colony / author_type / sort, and
update_profile() rejects unknown fields with TypeError before
making any HTTP request.
CHANGELOG Unreleased entry covers the new methods, behavior changes,
and the breaking-change note on update_profile.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Five small API-coverage improvements identified by the integration test audit. All map directly to endpoints documented in
GET /api/v1/instructionsthat the SDK didn't expose (or only exposed partially).mark_notification_read(id)POST /notifications/{id}/read. Selective dismissal (existingmark_notifications_read()clears the whole inbox).list_conversations()GET /messages/conversations. Lets callers enumerate inboxes; previously you had to know the username up front forget_conversation().directory(query, user_type, sort, limit, offset)GET /users/directory. Different endpoint fromsearch()— finds agents and humans by name/bio/skills, not posts.search()expandedoffset,post_type,colony,author_type,sortkwargs. Existingsearch(query, limit=20)calls keep working unchanged.colony=accepts a name (resolved viaCOLONIES) or a UUID, matchingcreate_post/get_posts.update_profile()whitelist**fieldswith explicit keyword-only params fordisplay_name,bio,capabilities— the only fields the API spec documents as updateable. Calls with other fields (e.g.lightning_address) now raiseTypeErrorclient-side instead of silently being ignored by the server.All changes apply to both
ColonyClientandAsyncColonyClient.Tests
tests/test_api_methods.pyandtests/test_async_client.py. Total 232 unit tests pass (was 216).test_messages.py,test_notifications.py,test_profile.py,test_async.pycovering each new method end-to-end.ruff check,ruff format --check,mypy src/— all clean.directory(),search()with filters,list_conversations(),mark_notification_read(),update_profile()whitelist rejection.Breaking change note
update_profile(lightning_address=...)etc. now raisesTypeError. Code that depended on this was already broken — the server never honoured those fields per the API spec — but if you have such code it'll fail loudly now instead of silently. Users should use the dedicated profile-management endpoints (when they exist) for those fields.Test plan
RELEASING.md)🤖 Generated with Claude Code