README.org

srht-contrib. python service. polls sourcehut activity, normalizes it into one event model, stores it in sqlite, and serves a contribution-calendar json api an ios app renders directly.

v1 scope:

• fastapi json api
• sqlite persistence
• polling ingestion
• full todo.sr.ht path
• git.sr.ht commit ingestion with repo auto-discovery
• public read-only endpoints, api-key auth for mutating routes
• alembic migrations

collects activity from sr.ht graphql services, aggregates by day, and returns zero-filled ranges so the client never patches missing dates. polls incrementally, backfills the last 365 days for new actors, prunes older activity.

implemented: todo.sr.ht, git.sr.ht. event types: ticket_created, ticket_comment, ticket_closed, commit.

API_KEY=replace-me
ENABLE_SCHEDULER=false
SRHT_TOKEN=replace-me
TODO_SRHT_ENDPOINT=https://todo.sr.ht/query
GIT_SRHT_ENDPOINT=https://git.sr.ht/query
DATABASE_URL=sqlite:///./srht_contrib.db
DEFAULT_ACTOR=~your-user
POLL_INTERVAL_SECONDS=300

more knobs (discovery batch size, repoll and backoff intervals, actor aliases, tracked repositories) live in config.py.

manual poll:

curl -X POST \
  "http://127.0.0.1:8000/api/contributions/poll?actor=~your-user" \
  -H "X-API-Key: replace-me"

scheduled polling runs only when ENABLE_SCHEDULER=true. it drains due actors in batches, indexes fast, then backfills a year in bounded passes.

bulk queue without immediate indexing:

srht-enqueue-actors srht_usernames.txt --stagger-seconds 60

calendar by year, calendar by date range, stats, and repository crud. full request and response shapes are in API.txt.

commit 1.0, ticket_created 1.0, ticket_comment 0.5, ticket_closed 0.75, build_started 0.25, build_passed 0.25.

• git polling assumes repos are discoverable via graphql
• the scheduler runs in-process, not distributed
• new actors index asynchronously; the first read may be empty
• rolling one-year window; older activity is not kept
• alias management is config-driven, no crud api yet
• trusted-operator v1, not a public multi-tenant service