Add direct message and file upload methods to GroupMe SDK

forgejo_admin commented

2026-03-28 19:16:46 +00:00

Owner

Type

Feature

Lineage

Dependency for groupme-mcp#7. Discovered during westside roster session 2026-03-28.

Repo

forgejo_admin/groupme-sdk

User Story

As an MCP tool developer, I want the GroupMe SDK to expose DM and file upload methods so the MCP server can wrap them following the established mixin pattern.

Context

The groupme-mcp wraps groupme-sdk via mixins (GroupsMixin, MembersMixin, MessagesMixin). DM and file upload endpoints exist in the GroupMe API but the SDK has no methods for them. API details documented in project-groupme-westside Known Behaviors section.

API endpoints:

POST /direct_messages with recipient_id + text (sends DM)
GET /chats (lists DM conversations)
POST file.groupme.com/v1/{group_id}/files (uploads file)
GET file.groupme.com/v1/{group_id}/uploadStatus?job={id} (poll status)

File Targets

src/groupme_sdk/direct_messages.py -- new DirectMessagesMixin: send_dm(recipient_id, text), list_chats()
src/groupme_sdk/files.py -- new FilesMixin: upload_file(group_id, file_path, content_type), get_upload_status(group_id, job_id)
src/groupme_sdk/client.py -- add new mixins to GroupMeClient class
tests/test_direct_messages.py -- unit tests
tests/test_files.py -- unit tests

Acceptance Criteria

send_dm(recipient_id, text) sends a DM and returns message data
list_chats() returns list of DM conversations
upload_file(group_id, file_path, content_type) uploads and returns file_id
get_upload_status(group_id, job_id) polls upload status
All methods follow existing mixin pattern (see GroupsMixin)
Tests pass

Test Expectations

Unit tests mock urllib responses following conftest.py patterns (make_client, mock_response, mock_http_error)
Test send_dm returns message data with correct structure
Test list_chats returns list of conversation dicts
Test upload_file sends multipart POST to file.groupme.com
Test get_upload_status polls correct URL
Test error handling (404, 500) for all new methods

Constraints

Pure Python only (urllib, no requests/httpx) -- matching existing SDK pattern
File upload uses file.groupme.com, not api.groupme.com -- needs separate base URL handling
Must not break existing mixin inheritance chain

Checklist

Code written
Tests written
Tests pass
Ruff format clean
Ruff check clean
PR submitted

Upstream: groupme-mcp#7 (DM and file upload MCP tools)
Board: board-westside-basketball

### Type Feature ### Lineage Dependency for groupme-mcp#7. Discovered during westside roster session 2026-03-28. ### Repo forgejo_admin/groupme-sdk ### User Story As an MCP tool developer, I want the GroupMe SDK to expose DM and file upload methods so the MCP server can wrap them following the established mixin pattern. ### Context The groupme-mcp wraps groupme-sdk via mixins (GroupsMixin, MembersMixin, MessagesMixin). DM and file upload endpoints exist in the GroupMe API but the SDK has no methods for them. API details documented in project-groupme-westside Known Behaviors section. API endpoints: - `POST /direct_messages` with `recipient_id` + `text` (sends DM) - `GET /chats` (lists DM conversations) - `POST file.groupme.com/v1/{group_id}/files` (uploads file) - `GET file.groupme.com/v1/{group_id}/uploadStatus?job={id}` (poll status) ### File Targets - `src/groupme_sdk/direct_messages.py` -- new DirectMessagesMixin: `send_dm(recipient_id, text)`, `list_chats()` - `src/groupme_sdk/files.py` -- new FilesMixin: `upload_file(group_id, file_path, content_type)`, `get_upload_status(group_id, job_id)` - `src/groupme_sdk/client.py` -- add new mixins to GroupMeClient class - `tests/test_direct_messages.py` -- unit tests - `tests/test_files.py` -- unit tests ### Acceptance Criteria - [ ] `send_dm(recipient_id, text)` sends a DM and returns message data - [ ] `list_chats()` returns list of DM conversations - [ ] `upload_file(group_id, file_path, content_type)` uploads and returns file_id - [ ] `get_upload_status(group_id, job_id)` polls upload status - [ ] All methods follow existing mixin pattern (see GroupsMixin) - [ ] Tests pass ### Test Expectations - Unit tests mock urllib responses following conftest.py patterns (make_client, mock_response, mock_http_error) - Test send_dm returns message data with correct structure - Test list_chats returns list of conversation dicts - Test upload_file sends multipart POST to file.groupme.com - Test get_upload_status polls correct URL - Test error handling (404, 500) for all new methods ### Constraints - Pure Python only (urllib, no requests/httpx) -- matching existing SDK pattern - File upload uses file.groupme.com, not api.groupme.com -- needs separate base URL handling - Must not break existing mixin inheritance chain ### Checklist - [ ] Code written - [ ] Tests written - [ ] Tests pass - [ ] Ruff format clean - [ ] Ruff check clean - [ ] PR submitted ### Related - Upstream: groupme-mcp#7 (DM and file upload MCP tools) - Board: board-westside-basketball