forgejo_admin/basketball-api
1
0
Fork 1
Code Issues 10 Pull requests 3 Projects Releases Packages Wiki Activity Actions

groupme-sdk: Python SDK wrapping GroupMe REST API #155

New issue
Closed
opened 2026-03-24 06:43:02 +00:00 by forgejo_admin · 4 comments
forgejo_admin commented 2026-03-24 06:43:02 +00:00
Owner
Copy link

Type

Feature

Lineage

project-groupme-westside → Ticket 1 of 3

Repo

forgejo_admin/groupme-sdk (to be created on Forgejo)

User Story

As a platform operator (story:GM-5)
I want to create and manage GroupMe groups via SDK
So that group setup is automated and tracked

Context

Westside Kings & Queens needs GroupMe as its real-time communication layer. This SDK wraps the GroupMe REST API (api.groupme.com/v3) in a clean Python package, published to Forgejo PyPI. Consumers: basketball-api (auto-invite on contract signing) and groupme-mcp (agent tools).

GroupMe API uses a permanent access token (no OAuth refresh). Token stored in ~/secrets/groupme/credentials.env.

Architecture: arch-domain-westside-basketball, arch-dataflow-westside-basketball, arch-deployment-westside-basketball (all updated 2026-03-24).

File Targets

New repo groupme-sdk:

  • src/groupme_sdk/client.py — HTTP client, token auth
  • src/groupme_sdk/groups.py — create, list, update, destroy groups
  • src/groupme_sdk/members.py — add, remove, list members (by phone/email/user_id)
  • src/groupme_sdk/messages.py — send messages to groups
  • tests/ — unit tests (mocked) + integration tests (live API)
  • pyproject.toml — packaging, Forgejo PyPI publish

Acceptance Criteria

  • Forgejo repo forgejo_admin/groupme-sdk exists with CI pipeline
  • SDK supports: create_group, list_groups, update_group, add_member, remove_member, list_members, send_message
  • Unit tests pass (mocked HTTP)
  • Integration test passes against live GroupMe API (create group → add member → send message → cleanup)
  • Published to Forgejo PyPI, installable via pip install groupme-sdk

Test Expectations

  • Unit test: each SDK method with mocked responses
  • Integration test: full lifecycle (create group → add member → send message → remove member → destroy group)
  • Run command: pytest tests/

Constraints

  • Follow minio-sdk patterns (pure Python, no heavy deps, custom HTTP client)
  • Token passed via env var GROUPME_ACCESS_TOKEN
  • No Groupy/GroupyAPI dependency — we own the wrapper

Checklist

  • PR opened
  • Tests pass
  • No unrelated changes

Related

  • project-groupme-westside — project page
  • arch-domain-westside-basketball — domain model with GroupMeGroup/GroupMeMember entities
### Type Feature ### Lineage `project-groupme-westside` → Ticket 1 of 3 ### Repo `forgejo_admin/groupme-sdk` (to be created on Forgejo) ### User Story As a platform operator (story:GM-5) I want to create and manage GroupMe groups via SDK So that group setup is automated and tracked ### Context Westside Kings & Queens needs GroupMe as its real-time communication layer. This SDK wraps the GroupMe REST API (`api.groupme.com/v3`) in a clean Python package, published to Forgejo PyPI. Consumers: basketball-api (auto-invite on contract signing) and groupme-mcp (agent tools). GroupMe API uses a permanent access token (no OAuth refresh). Token stored in `~/secrets/groupme/credentials.env`. Architecture: `arch-domain-westside-basketball`, `arch-dataflow-westside-basketball`, `arch-deployment-westside-basketball` (all updated 2026-03-24). ### File Targets New repo `groupme-sdk`: - `src/groupme_sdk/client.py` — HTTP client, token auth - `src/groupme_sdk/groups.py` — create, list, update, destroy groups - `src/groupme_sdk/members.py` — add, remove, list members (by phone/email/user_id) - `src/groupme_sdk/messages.py` — send messages to groups - `tests/` — unit tests (mocked) + integration tests (live API) - `pyproject.toml` — packaging, Forgejo PyPI publish ### Acceptance Criteria - [ ] Forgejo repo `forgejo_admin/groupme-sdk` exists with CI pipeline - [ ] SDK supports: `create_group`, `list_groups`, `update_group`, `add_member`, `remove_member`, `list_members`, `send_message` - [ ] Unit tests pass (mocked HTTP) - [ ] Integration test passes against live GroupMe API (create group → add member → send message → cleanup) - [ ] Published to Forgejo PyPI, installable via `pip install groupme-sdk` ### Test Expectations - [ ] Unit test: each SDK method with mocked responses - [ ] Integration test: full lifecycle (create group → add member → send message → remove member → destroy group) - Run command: `pytest tests/` ### Constraints - Follow minio-sdk patterns (pure Python, no heavy deps, custom HTTP client) - Token passed via env var `GROUPME_ACCESS_TOKEN` - No Groupy/GroupyAPI dependency — we own the wrapper ### Checklist - [ ] PR opened - [ ] Tests pass - [ ] No unrelated changes ### Related - `project-groupme-westside` — project page - `arch-domain-westside-basketball` — domain model with GroupMeGroup/GroupMeMember entities
forgejo_admin commented 2026-03-24 06:49:03 +00:00
Author
Owner
Copy link

Architecture Simplification (2026-03-24)

SDK scope narrowed after brainstorming session. Key change: parents self-join via share link instead of being API-added by phone number. This eliminates the phone-number matching duplicate bug discovered during Marcus onboarding.

SDK scope reduced to:

  • create_group, list_groups, update_group, destroy_group — group lifecycle
  • list_members — audit who joined (query GroupMe, compare to roster)
  • send_message — announcements via MCP
  • add_member / remove_member — admin tool only, edge cases

Removed from scope:

  • No GroupMeMember tracking table — GroupMe API is source of truth for membership
  • No GroupMeGroup table — just groupme_group_id + groupme_share_url columns on teams table
  • Phone-number-based member adding is no longer the primary flow
## Architecture Simplification (2026-03-24) SDK scope narrowed after brainstorming session. Key change: **parents self-join via share link** instead of being API-added by phone number. This eliminates the phone-number matching duplicate bug discovered during Marcus onboarding. ### SDK scope reduced to: - `create_group`, `list_groups`, `update_group`, `destroy_group` — group lifecycle - `list_members` — audit who joined (query GroupMe, compare to roster) - `send_message` — announcements via MCP - `add_member` / `remove_member` — admin tool only, edge cases ### Removed from scope: - No `GroupMeMember` tracking table — GroupMe API is source of truth for membership - No `GroupMeGroup` table — just `groupme_group_id` + `groupme_share_url` columns on teams table - Phone-number-based member adding is no longer the primary flow
forgejo_admin commented 2026-03-24 06:58:32 +00:00
Author
Owner
Copy link

Refined AC After Code Exploration (2026-03-24)

SDK is consumed by basketball-api directly (not via pal-e-mail). The primary use cases are:

  1. One-time group creation — create 11 groups, capture group_id + share_url
  2. MCP tools — list_members for audit, send_message for announcements
  3. Admin edge cases — add_member/remove_member when share link doesn't work

Revised AC

  • Forgejo repo forgejo_admin/groupme-sdk exists with Woodpecker CI
  • SDK: create_group(name, description) → returns group_id + share_url
  • SDK: list_groups(), get_group(group_id), update_group(group_id, ...), destroy_group(group_id)
  • SDK: list_members(group_id) → returns member list (name, user_id, roles)
  • SDK: add_member(group_id, nickname, phone/email/user_id), remove_member(group_id, membership_id)
  • SDK: send_message(group_id, text)
  • Unit tests (mocked HTTP responses)
  • Integration test: create group → verify share_url → send message → destroy group
  • Published to Forgejo PyPI
## Refined AC After Code Exploration (2026-03-24) SDK is consumed by basketball-api directly (not via pal-e-mail). The primary use cases are: 1. **One-time group creation** — create 11 groups, capture group_id + share_url 2. **MCP tools** — list_members for audit, send_message for announcements 3. **Admin edge cases** — add_member/remove_member when share link doesn't work ### Revised AC - [ ] Forgejo repo `forgejo_admin/groupme-sdk` exists with Woodpecker CI - [ ] SDK: `create_group(name, description)` → returns group_id + share_url - [ ] SDK: `list_groups()`, `get_group(group_id)`, `update_group(group_id, ...)`, `destroy_group(group_id)` - [ ] SDK: `list_members(group_id)` → returns member list (name, user_id, roles) - [ ] SDK: `add_member(group_id, nickname, phone/email/user_id)`, `remove_member(group_id, membership_id)` - [ ] SDK: `send_message(group_id, text)` - [ ] Unit tests (mocked HTTP responses) - [ ] Integration test: create group → verify share_url → send message → destroy group - [ ] Published to Forgejo PyPI
forgejo_admin commented 2026-03-24 07:11:57 +00:00
Author
Owner
Copy link

Scope Review: NEEDS_REFINEMENT

Review note: review-303-2026-03-24
Two gaps found in file targets and repo placement instructions.

  • .woodpecker.yaml and src/groupme_sdk/__init__.py missing from File Targets (but required by acceptance criteria)
  • Issue filed on basketball-api but work targets new groupme-sdk repo -- agent needs explicit repo creation step or the issue should move after repo creation
## Scope Review: NEEDS_REFINEMENT Review note: `review-303-2026-03-24` Two gaps found in file targets and repo placement instructions. - `.woodpecker.yaml` and `src/groupme_sdk/__init__.py` missing from File Targets (but required by acceptance criteria) - Issue filed on basketball-api but work targets new `groupme-sdk` repo -- agent needs explicit repo creation step or the issue should move after repo creation
forgejo_admin commented 2026-03-24 07:12:53 +00:00
Author
Owner
Copy link

Review Fixes (2026-03-24)

Addressing review-303-2026-03-24 findings:

1. Missing file targets added

  • src/groupme_sdk/__init__.py — package init, re-exports client
  • .woodpecker.yaml — CI pipeline: lint, test, publish to Forgejo PyPI on main

2. Repo creation instruction

Step 0: Agent must create forgejo_admin/groupme-sdk repo on Forgejo via mcp__forgejo__create_repo before starting work. PRs go to the new repo, not basketball-api. This issue is filed here because the target repo doesn't exist yet.

## Review Fixes (2026-03-24) Addressing review-303-2026-03-24 findings: ### 1. Missing file targets added - `src/groupme_sdk/__init__.py` — package init, re-exports client - `.woodpecker.yaml` — CI pipeline: lint, test, publish to Forgejo PyPI on main ### 2. Repo creation instruction **Step 0**: Agent must create `forgejo_admin/groupme-sdk` repo on Forgejo via `mcp__forgejo__create_repo` before starting work. PRs go to the new repo, not basketball-api. This issue is filed here because the target repo doesn't exist yet.
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
hotfix-029-division-enum
205-clean-test-data-from-production-db-playe
114-email-verification
147-feat-add-get-jersey-player-info-endpoint
124-feat-many-to-many-player-team-assignment
125-feat-add-new-players-manually-seydou-gou
126-feat-team-placement-congratulations-emai
121-admin-teams-spa-endpoints
70-add-graduating-class-to-roster-api-respo
59-fix-auth-test
62-phase-4l-sveltekit-dashboard-wkq-tailsca
11-phase-1a-fix-ci-pipeline-venv-in-test-st
No results found.
Labels
Clear labels   
domain:backend

   
domain:devops

   
domain:frontend

   
status:approved

QA passed, awaiting merge approval

  
status:in-progress

Dev agent is actively working

  
status:needs-fix

QA found issues, back to dev

  
status:qa

PR submitted, awaiting QA review

  
type:bug

Bug fix

  
type:devops

Infrastructure/CI/config work

  
type:feature

New functionality

No labels
domain:backend
domain:devops
domain:frontend
status:approved
status:in-progress
status:needs-fix
status:qa
type:bug
type:devops
type:feature
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
forgejo_admin/basketball-api#155
No description provided.