README.org

 1#+title: hutch-stats
 2
 3* what
 4srht-contrib. python service. polls sourcehut activity, normalizes
 5it into one event model, stores it in sqlite, and serves a
 6contribution-calendar json api an ios app renders directly.
 7
 8v1 scope:
 9- fastapi json api
10- sqlite persistence
11- polling ingestion
12- full todo.sr.ht path
13- git.sr.ht commit ingestion with repo auto-discovery
14- public read-only endpoints, api-key auth for mutating routes
15- alembic migrations
16
17* does
18collects activity from sr.ht graphql services, aggregates by day,
19and returns zero-filled ranges so the client never patches missing
20dates. polls incrementally, backfills the last 365 days for new
21actors, prunes older activity.
22
23* services
24implemented: todo.sr.ht, git.sr.ht.
25event types: ticket_created, ticket_comment, ticket_closed, commit.
26
27* env
28#+begin_src conf
29API_KEY=replace-me
30ENABLE_SCHEDULER=false
31SRHT_TOKEN=replace-me
32TODO_SRHT_ENDPOINT=https://todo.sr.ht/query
33GIT_SRHT_ENDPOINT=https://git.sr.ht/query
34DATABASE_URL=sqlite:///./srht_contrib.db
35DEFAULT_ACTOR=~your-user
36POLL_INTERVAL_SECONDS=300
37#+end_src
38
39more knobs (discovery batch size, repoll and backoff intervals,
40actor aliases, tracked repositories) live in config.py.
41
42* run
43#+begin_src sh
44uv venv
45source .venv/bin/activate
46uv pip install -e ".[dev]"
47cp .env.example .env
48alembic upgrade head
49uvicorn srht_contrib.main:app --reload
50#+end_src
51
52* poll
53manual poll:
54
55#+begin_src sh
56curl -X POST \
57  "http://127.0.0.1:8000/api/contributions/poll?actor=~your-user" \
58  -H "X-API-Key: replace-me"
59#+end_src
60
61scheduled polling runs only when ENABLE_SCHEDULER=true. it drains
62due actors in batches, indexes fast, then backfills a year in
63bounded passes.
64
65bulk queue without immediate indexing:
66
67#+begin_src sh
68srht-enqueue-actors srht_usernames.txt --stagger-seconds 60
69#+end_src
70
71* endpoints
72calendar by year, calendar by date range, stats, and repository
73crud. full request and response shapes are in API.txt.
74
75* weights
76commit 1.0, ticket_created 1.0, ticket_comment 0.5,
77ticket_closed 0.75, build_started 0.25, build_passed 0.25.
78
79* tests
80#+begin_src sh
81pytest
82#+end_src
83
84* limits
85- git polling assumes repos are discoverable via graphql
86- the scheduler runs in-process, not distributed
87- new actors index asynchronously; the first read may be empty
88- rolling one-year window; older activity is not kept
89- alias management is config-driven, no crud api yet
90- trusted-operator v1, not a public multi-tenant service