` and `` for accessibility Methods: `setCSS`, `setHideBorder`, `setHideTitle`, `setTitle`, `setAccessibilityLabel`, `disableAnimations`. Width and height come from the constructor. The class deliberately mutates: callers configure properties between construction and `render()`. #### `src/common/cache.js` `resolveCacheSeconds` clamps `requested` between MIN and MAX, then overrides everything if `process.env.CACHE_SECONDS` is a valid integer. Note the hierarchy: env wins over query param, query param wins over default. This is why setting `CACHE_SECONDS` instance-wide is so powerful — it ignores the per-card range entirely. #### `src/common/error.js` The `SECONDARY_ERROR_MESSAGES` table maps `CustomError.type` to a user-facing secondary message: | Type | Secondary message | |---|---| | `MAX_RETRY` | "You can deploy own instance or wait until public will be no longer limited" | | `NO_TOKENS` | "Please add an env variable called PAT_1 with your GitHub API token in vercel" | | `USER_NOT_FOUND` | "Make sure the provided username is not an organization" | | `GRAPHQL_ERROR` | "Please try again later" | | `GITHUB_REST_API_ERROR` | "Please try again later" | | `WAKATIME_USER_NOT_FOUND` | "Make sure you have a public WakaTime profile" | `MissingParamError` is a separate subclass that carries the missing parameter list and a usage example URL. The handler suppresses the "file an issue" link for `MissingParamError` because it's a user typo, not a bug. #### `src/common/retryer.js` ```javascript const PATs = Object.keys(process.env).filter((k) => /PAT_\d*$/.exec(k)).length; const RETRIES = process.env.NODE_ENV === "test" ? 7 : PATs; ``` `RETRIES` is the count, fixed at module load. The `retryer` recurses on GraphQL `RATE_LIMITED` AND on response messages matching `/rate limit/i` (double-check from issue #4425). It also rotates on `Bad credentials` (a token has been revoked) and on `Sorry. Your account was suspended.` (suspended PAT). Network errors without a response object are re-thrown to the caller. #### `src/common/access.js` Distinguishes three identity types: `username`, `gist`, `wakatime`. Each has its own (whitelist, "not whitelisted" message) pair. The blacklist applies only to `username` AND only when no whitelist is set. Failed access returns a "This username is not whitelisted" / "This gist ID is not whitelisted" / "This username is blacklisted" SVG with `show_repo_link: false` (don't tell users to file an issue when they're blocked). #### `src/calculateRank.js` Pure function, zero dependencies. Two CDFs: ```javascript exponential_cdf(x) = 1 - 2 ** -x log_normal_cdf(x) = x / (1 + x) // approximation ``` Six weighted contributions: | Contribution | CDF | Median | Weight | |---|---|---|---| | commits | exponential | 250 (or 1000 if `all_commits`) | 2 | | PRs | exponential | 50 | 3 | | issues | exponential | 25 | 1 | | reviews | exponential | 2 | 1 | | stars | log-normal | 50 | 4 | | followers | log-normal | 10 | 1 | Total weight 12. Output range: 0..100 (percentile). Letter mapping: ```text THRESHOLDS = [1, 12.5, 25, 37.5, 50, 62.5, 75, 87.5, 100] LEVELS = ["S", "A+", "A", "A-", "B+", "B", "B-", "C+", "C"] ``` `repos` is destructured but unused (the eslint-disable comment is there). It's part of the rank function signature for API stability. ### 8.3 Coding conventions - `// @ts-check` at the top of every file enables TypeScript checking in JSDoc. - Public surface: every function has a JSDoc block with `@param`, `@returns`, often `@typedef` for shared shapes. - ESM only: `import` / `export`. `package.json` has `"type": "module"`. - No classes for stateless helpers; classes only for `Card`, `I18n`, and the two error subclasses. - Card renderers always export both a named export and a default export (legacy interop). - Constants for magic numbers (e.g., `CARD_MIN_WIDTH`, `LONG_LOCALES`, `HEADER_MAX_LENGTH`). - Tests live in `tests/`, mirroring source structure (`tests/card.test.js`, `tests/renderStatsCard.test.js`, etc.). ### 8.4 Testing strategy | Suite | Config | Purpose | |---|---|---| | Unit | `jest.config.js` | Per-card and per-utility tests using `jsdom` env | | Bench | `jest.bench.config.js` | Performance benches in `tests/bench/` | | E2E | `jest.e2e.config.js` | End-to-end tests under `node` env in `tests/e2e/` | `axios-mock-adapter` mocks GitHub responses; tests assert SVG output contains expected elements (`data-testid="rank-circle"`, `data-testid="lang-progress"`, etc.). Snapshot tests live under `tests/__snapshots__/`. > [!TIP] > When adding a new card variant, add a render snapshot test the same > day. The renderers produce strings that humans don't easily diff — > snapshots save you from accidentally shifting an SVG element by 5 px. ### 8.5 Potential improvements The codebase is mature but has a few open improvement vectors: 1. **`api_domain` SSRF hardening (issue #4859, #4832).** Move beyond trailing-slash strip; whitelist the WakaTime/Wakapi hosts. 2. **Custom font support (issue #4105).** Currently every card hardcodes `'Segoe UI', Ubuntu, Sans-Serif`. A `font_family=` query parameter would unlock big customisation gains. 3. **Multi-token weighted retry.** The retryer chooses tokens in numeric order; under sustained load, `PAT_1` exhausts before `PAT_2` ever activates. A round-robin or remaining-budget-weighted strategy would balance better. 4. **Output-size guardrails.** Some `bg_color` gradient configurations can produce SVGs in the 30+ KB range with many stops; bounds are not enforced. 5. **TypeScript migration.** `// @ts-check` plus JSDoc gives ~80 % of the safety; the remaining 20 % is in the renderers where typedefs leak into string interpolation. 6. **First-class fine-grained PAT support.** The retryer's `Bad credentials` heuristic doesn't differentiate "expired classic PAT" from "fine-grained PAT lacking scope". Rich error surfacing in `pat-info` would help operators. ### 8.6 Contributing The repo runs: ```bash npm run lint # eslint --max-warnings 0 npm run format:check # prettier --check npm test # full unit suite with coverage ``` All three must pass on PRs. Husky's pre-commit hook runs `lint-staged` which prettifies `*.{js,css,md}`. For new themes, the workflow is: ```bash npm run preview-theme # opens a local preview server # edit themes/index.js, add your entry npm run theme-readme-gen # regenerates themes/README.md git commit -am "feat: add theme" ``` `scripts/close-stale-theme-prs.js` is run on a schedule by the maintainers to close abandoned theme PRs. Don't be surprised if a quiet PR is closed; reopen with the latest commit and a comment. --- ## 9. Integration Points ### 9.1 Inbound The five card endpoints are the public API. They are designed to be embedded as `` (Markdown image syntax). HEAD requests are not specially handled — Vercel's runtime serves the same SVG to HEAD as to GET, with a `Content-Length` header. There is no JSON output mode for cards. Every successful render is SVG. The two status endpoints (`/api/status/up`, `/api/status/pat-info`) return `application/json`. ### 9.2 Outbound | Destination | Protocol | Endpoint | Trigger | |---|---|---|---| | `api.github.com/graphql` | HTTPS POST | GraphQL v4 | Every render except wakatime/`/api/status/up`/`/api/status/pat-info` | | `api.github.com/search/commits` | HTTPS GET | REST search-commits with `application/vnd.github.cloak-preview` | Stats card with `include_all_commits=true` | | `wakatime.com/api/v1/users//stats` | HTTPS GET | WakaTime REST | `/api/wakatime` | | Custom (`api_domain`) | HTTPS GET | WakaTime-shape REST | `/api/wakatime?api_domain=...` | All outbound calls go through `axios` (no local connection pool; serverless cold-start each time). The retryer wraps the GitHub calls; the WakaTime call is a single direct `axios.get` with no retry. ### 9.3 README embedding patterns The cards are designed to slot into: - GitHub README image syntax: `![alt](URL)` - HTML `` tags (when you need attributes like `height=` and `align=`) - GitLab READMEs (same Markdown syntax) - Docusaurus / MkDocs / VitePress - Any Markdown renderer that fetches external SVGs Cards intentionally do not require JavaScript on the consuming page. Animations are pure SVG/CSS and run inside the SVG sandbox. ### 9.4 Observability hooks There is no built-in metrics emission (no Prometheus, no StatsD). On Vercel, observability is the hosting platform's job: - Function logs are visible in the Vercel dashboard. - Per-invocation duration is exposed in Vercel's analytics. - Per-endpoint cache hit ratio is visible in Vercel's CDN analytics. If you need finer-grained metrics, the obvious patch points are the top of each handler (count requests by endpoint) and immediately after `retryer` returns (count rate-limit-rotations by PAT). Both are single-file changes. --- _Generated April 2026 from anuraghazra/github-readme-stats at 5df91f9. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project.

# GitHub Readme Stats — Administrator & Developer Guide ## 1. Architecture Overview GitHub Readme Stats is a Vercel-native serverless image API. It exposes five HTTP endpoints, each implemented as a single default-export async-handler in `api/`. Each handler: 1. Reads its parameters from `req.query`. 2. Runs the request through `guardAccess` (whitelist/blacklist gate). 3. Validates the locale against the I18n catalog. 4. Calls a fetcher (`src/fetchers/.js`) that issues a GraphQL or REST request to GitHub (or WakaTime) through the rotating-PAT retryer. 5. Passes the typed result into a renderer (`src/cards/.js`). 6. Sets `Cache-Control` headers and returns SVG. There is no database, no queue, no background worker, no on-disk state — every request is a stateless function. The rendering pipeline is pure string concatenation; the only mutable globals are the `process.env` PATs and a few module-level constants. ### 1.1 Component diagram ```text Vercel Edge │ ▼ ┌────────────────────────────────────────────────────┐ │ api/index.js api/pin.js api/gist.js │ │ api/top-langs.js api/wakatime.js │ │ api/status/up.js api/status/pat-info.js │ └────────┬─────────┬─────────┬─────────┬──────────────┘ │ │ │ │ ▼ ▼ ▼ ▼ ┌────────────────────────────────────────────────────┐ │ src/common/access.js guardAccess (allow/deny) │ │ src/common/cache.js CACHE_TTL, setCacheHeaders │ │ src/common/error.js CustomError + secondary msgs │ │ src/common/render.js renderError, flexLayout │ │ src/common/ops.js parseBoolean / parseArray │ │ src/common/Card.js Card class (SVG envelope) │ │ src/translations.js 50+ locales for stat labels │ └────────┬─────────────────────────────┬──────────────┘ │ │ ▼ ▼ ┌──────────────────────┐ ┌──────────────────────┐ │ src/fetchers/*.js │ │ src/cards/*.js │ │ - stats.js │ │ - stats.js │ │ - repo.js │ │ - repo.js │ │ - top-languages.js │ │ - top-languages.js │ │ - wakatime.js │ │ - wakatime.js │ │ - gist.js │ │ - gist.js │ └────────┬─────────────┘ └──────────┬───────────┘ │ │ ▼ │ ┌──────────────────────┐ │ │ src/common/retryer.js│ rotates PATs │ │ src/common/http.js │ axios → GitHub │ └──────────────────────┘ │ ▼ SVG response ``` ### 1.2 Component inventory | Component | Path | Role | |---|---|---| | Stats handler | `api/index.js` | Resolves stats card SVG. 27 parameters destructured from query. | | Pinned-repo handler | `api/pin.js` | Resolves single-repo pin card SVG. | | Top-langs handler | `api/top-langs.js` | Resolves languages card. Validates `layout` and `stats_format` enums explicitly. | | WakaTime handler | `api/wakatime.js` | Calls WakaTime REST endpoint, renders coding-time card. | | Gist handler | `api/gist.js` | Resolves gist preview card. | | Status handlers | `api/status/up.js`, `api/status/pat-info.js` | Health endpoints; rate-limited to 1 request per 5 min. | | Stats renderer | `src/cards/stats.js` | Computes rank circle geometry, lays out stat rows, emits SVG. | | Repo renderer | `src/cards/repo.js` | Renders pin card with archived/template badge logic. | | Top-langs renderer | `src/cards/top-languages.js` | Five layouts: normal/compact/donut/donut-vertical/pie. Polar-to-cartesian math for arcs. | | WakaTime renderer | `src/cards/wakatime.js` | Two layouts (default + compact); auto-detects "no data" sub-states. | | Gist renderer | `src/cards/gist.js` | Header truncated to 35 chars; description wrapped to 10 lines. | | Card envelope | `src/common/Card.js` | SVG outer rect, title row, gradient defs, animation switch. | | I18n | `src/common/I18n.js` | Translation lookup with `en` fallback. Throws on missing keys. | | Color resolver | `src/common/color.js` | `getCardColors`: theme → user override → default fallback chain. Validates hex (3/4/6/8 char) and gradient (angle + 2+ hex). | | Error model | `src/common/error.js` | `CustomError` with type→secondary-message map; `MissingParamError`. | | Cache policy | `src/common/cache.js` | `CACHE_TTL` per card, `resolveCacheSeconds`, header writers. | | Retryer | `src/common/retryer.js` | Rotates `PAT_1`..`PAT_n`, distinguishes rate-limit vs bad-credential, recurses. | | HTTP client | `src/common/http.js` | Thin axios wrapper that posts to `https://api.github.com/graphql`. | | Whitelist/blacklist | `src/common/access.js`, `src/common/blacklist.js`, `src/common/envs.js` | Optional allow-list, hardcoded deny-list of known abusers. | | Logger | `src/common/log.js` | `console` in prod, `noop` in tests. | | Themes | `themes/index.js` | 74 named theme objects. | | Language colors | `src/common/languageColors.json` | ~600 language→hex pairs (sourced from GitHub Linguist). | | Rank algorithm | `src/calculateRank.js` | Pure function: weighted CDFs → letter (S..C) + percentile. | | Express adapter | `express.js` | Mounts the five handlers under `/api` for non-Vercel hosts. | ### 1.3 Technology stack | Layer | Technology | |---|---| | Runtime | Node.js >= 22 (ES modules, top-level `import`) | | Hosting | Vercel serverless functions (128 MB / 10 s) | | HTTP client | `axios ^1.13.1` | | GitHub API | GraphQL v4 + REST search-commits | | Username validation | `github-username-regex ^1.0.0` | | Emoji shortcodes | `emoji-name-map ^2.0.3` | | Word wrap | `word-wrap ^1.2.5` | | Env loading | `dotenv ^17.2.3` | | Local server | `express ^5.2.1` (devDependency) | | Tests | Jest 30, jsdom env, `axios-mock-adapter`, `@testing-library/jest-dom` | | Linting | ESLint 9 with `eslint-plugin-jsdoc` and `eslint-config-prettier` | | Formatting | Prettier 3, lint-staged via Husky | > [!NOTE] > The project's only direct production dependencies are `axios`, `dotenv`, > `emoji-name-map`, `github-username-regex`, and `word-wrap`. Everything > else (eslint, jest, prettier, express) is a devDependency. The footprint > is intentionally small to keep cold-start times within the Vercel > 10-second function budget. ### 1.4 Request lifecycle (stats card example) ```text GET /api?username=anuraghazra&theme=tokyonight&show=prs_merged │ ├─ destructure 27 params from req.query ├─ guardAccess({type: "username"}) ← blacklist + optional WHITELIST ├─ isLocaleAvailable(locale) ← skipped if locale not set ├─ fetchStats(username, ...) │ ├─ statsFetcher() loops on hasNextPage (gated by FETCH_MULTI_PAGE_STARS) │ │ └─ retryer(fetcher, vars) rotates PAT_1..PAT_n on rate-limit │ │ └─ axios.post(api.github.com/graphql, {query, variables}, {Authorization}) │ ├─ if include_all_commits: totalCommitsFetcher() ← REST search-commits │ └─ calculateRank({commits, prs, issues, reviews, repos, stars, followers}) ├─ resolveCacheSeconds({req, def: 1d, min: 12h, max: 2d}) ├─ setCacheHeaders(res, cacheSeconds) ← max-age + s-maxage + stale-while-revalidate └─ res.send(renderStatsCard(stats, options)) ├─ getCardColors() resolves theme + per-key overrides ├─ build STATS object, filter by hide[], slice optional show[] ├─ flexLayout({direction: "column"}) of stat rows ├─ rank circle SVG with stroke-dashoffset animation └─ Card.render() wraps in