envelope and schemas

PLATFORM = "github", CATEGORY = "development". Canonical card plus first-class extras that coding platforms do not have.

Try it: playground, docs, sample tashifkhan/profile. Placeholder handle in HTML is demo.

Callers send no GitHub token. Server uses GITHUB_TOKEN. Missing token is 500 GitHub token not configured.

Path username. No body.

Canonical query:

Extras: full on repos, include_repos on star-lists, first=1..6 on pinned, source ignored (portfolio cache-buster).

GET /tashifkhan/stats?attributed=true HTTP/1.1
Host: github-stats.tashif.codes

GET /tashifkhan/stats/svg?theme=dark&exclude=HTML,CSS,Markdown HTTP/1.1
Host: github-stats.tashif.codes

There are no /{username}/contests or /{username}/rating routes. CodeTrace still asks. Those 404. The client turns a failed section into an empty stub.

Server-side: GitHub REST + GraphQL, plus HTML scrapes where GitHub has no API. See HTML scrapes.

Canonical routes:

{
  "status": "success",
  "message": "retrieved",
  "platform": "github",
  "username": "tashifkhan",
  "cached": false,
  "data": {}
}

/{username}/stats and /{username}/contributions also flatten older fields: topLanguages, totalCommits, longestStreak, currentStreak, profile_visitors, contributions.

Legacy-shaped lists (/{username}/languages, /{username}/repos, /{username}/me/pulls) return arrays, not this envelope.

Summary: totalSolved is total commits. totalActiveDays is days with a contribution. Contests fields on the Card object are empty Contests() / Rating() inside build_card, but those routes do not exist.

Profile: country is GitHub location.

Stats: languages → topicAnalysis with count = round(percentage). byDifficulty keys commits, optional prs / issues / reviews.

Heatmap: GraphQL calendars, then window_heatmap.

Badges: scraped profile achievements (Pull Shark, YOLO, …). level is the tier label when present.

SVG extras for GitHub only: totalStars, currentStreak, longestStreak as {n}d. Label “Total Commits” / “TOP LANGUAGES”. Accent #3fb950. Cache-Control 24h.

GET /{username}/languages
GET /{username}/contributions
GET /{username}/contributions/breakdown
GET /{username}/repos?attributed&full
GET /{username}/stars
GET /{username}/pinned?first=1..6
GET /{username}/star-lists?include_repos
GET /{username}/commits
GET /{username}/profile-views
GET /{username}/me/pulls
GET /{username}/org-contributions
GET /{username}/prs

Breakdown status: complete, deadline, rate_limited, cache_disabled. Check coverage / partial / cache_enabled before treating an empty mix as “this user writes no code”.

Playground list in routes/docs.py omits breakdown, pinned, star-lists, profile-views. Those routes still exist.

GitHub 403 with x-ratelimit-remaining: 0 is 503, not 404. Mapping throttle to 404 used to blacklist a real login.

JSON arrays from /repos are never inspected for invalid-user markers.

sequenceDiagram
  participant C as Caller
  participant MW as CacheRateLimit
  participant RT as Route
  participant GH as api.github.com
  participant HTML as github.com HTML
  participant R as Redis

  C->>MW: GET /tashifkhan/stats
  MW->>RT: miss
  RT->>GH: REST user
  RT->>GH: GraphQL calendar
  RT->>R: GET gh:attr:v2 blobs
  RT->>HTML: GET /tashifkhan achievements
  RT-->>C: envelope platform github

Cache and limiter. Own-commit attribution. HTML scrapes.