### Deploy with Express

Source: https://context7.com/anuraghazra/github-readme-stats/llms.txt

Example Express.js server setup to run all five card endpoints on a specified port. Ensure `dotenv/config` is imported for environment variable loading.

```javascript
// express.js — runs all five card endpoints on port 9000
// node express.js   or   PORT=3000 node express.js

import "dotenv/config";
import statsCard    from "./api/index.js";
import repoCard     from "./api/pin.js";
import langCard     from "./api/top-langs.js";
import wakatimeCard from "./api/wakatime.js";
import gistCard     from "./api/gist.js";
import express      from "express";

const app = express();
const router = express.Router();

router.get("/",          statsCard);
router.get("/pin",       repoCard);
router.get("/top-langs", langCard);
router.get("/wakatime",  wakatimeCard);
router.get("/gist",      gistCard);

app.use("/api", router);
app.listen(process.env.PORT || 9000, "0.0.0.0");
```

--------------------------------

### Generate Default Top Languages Card

Source: https://github.com/anuraghazra/github-readme-stats/blob/master/readme.md

A basic example of generating the top languages card with default settings.

```markdown
<![Top Langs](https://github-readme-stats.vercel.app/api/top-langs/?username=anuraghazra)
```

--------------------------------

### GitHub Gist Pins with Show Owner

Source: https://github.com/anuraghazra/github-readme-stats/blob/master/readme.md

This example shows how to include the gist owner's username on the gist card by adding the `show_owner` query parameter.

```markdown
<a href="https://gist.github.com/Yizack/bbfce31e0217a3689c8d961a356cb10d/" align="center">[![Gist Card](https://github-readme-stats.vercel.app/api/gist?id=bbfce31e0217a3689c8d961a356cb10d&show_owner=true)](https://gist.github.com/Yizack/bbfce31e0217a3689c8d961a356cb10d/)</a>
```

--------------------------------

### Environment Variables for Self-Hosting

Source: https://context7.com/anuraghazra/github-readme-stats/llms.txt

Example `.env` file for local development or self-hosted instances. Includes placeholders for GitHub PATs, cache duration override, and whitelist configurations for usernames and Gist IDs.

```bash
# .env (for local dev or self-hosted instance)

# GitHub PATs — at least one required; add more for rate-limit resilience
PAT_1=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
PAT_2=ghp_yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy

# Override cache duration globally (seconds); 0 disables caching
CACHE_SECONDS=86400

# Restrict which GitHub usernames may be requested
WHITELIST=anuraghazra,torvalds

# Restrict which Gist IDs may be requested
GIST_WHITELIST=bbfce31e0217a3689c8d961a356cb10d

```

--------------------------------

### GitHub Extra Pins with Show Owner

Source: https://github.com/anuraghazra/github-readme-stats/blob/master/readme.md

This example demonstrates how to display the repository owner's username along with the pinned repository card by using the `show_owner` query parameter.

```markdown
<a href="https://github.com/anuraghazra/github-readme-stats" align="center">[![Readme Card](https://github-readme-stats.vercel.app/api/pin/?username=anuraghazra&repo=github-readme-stats&show_owner=true)](https://github.com/anuraghazra/github-readme-stats)</a>
```

--------------------------------

### Apply Inbuilt Themes

Source: https://github.com/anuraghazra/github-readme-stats/blob/master/readme.md

Customize the card's appearance using built-in themes by adding the `&theme=THEME_NAME` parameter. For example, `radical` is used here.

```markdown
![Anurag's GitHub stats](https://github-readme-stats.vercel.app/api?username=anuraghazra&show_icons=true&theme=radical)
```

--------------------------------

### Get PAT Status Details API

Source: https://context7.com/anuraghazra/github-readme-stats/llms.txt

Use this endpoint to retrieve a JSON breakdown of configured PATs, categorized by their status. Rate-limited to one request per 5 minutes.

```bash
curl "https://github-readme-stats.vercel.app/api/status/pat-info"
```

--------------------------------

### Show Icons

Source: https://github.com/anuraghazra/github-readme-stats/blob/master/readme.md

Enable icons on the stats card by adding `&show_icons=true` to the query parameters.

```markdown
![Anurag's GitHub stats](https://github-readme-stats.vercel.app/api?username=anuraghazra&show_icons=true)
```

--------------------------------

### Fetch All Star Pages

Source: https://context7.com/anuraghazra/github-readme-stats/llms.txt

Enable fetching all star pages by setting FETCH_MULTI_PAGE_STARS to true. Be aware this may hit rate limits on busy instances.

```shell
FETCH_MULTI_PAGE_STARS=true
```

--------------------------------

### Top Languages Card with Pie Chart Layout

Source: https://context7.com/anuraghazra/github-readme-stats/llms.txt

Generates a card displaying top programming languages using a pie chart layout. This is a simpler alternative for visualizing language distribution.

```bash
curl "https://github-readme-stats.vercel.app/api/top-langs/?username=anuraghazra&layout=pie"
```

--------------------------------

### Customize Top Languages Card with Algorithm Weights

Source: https://github.com/anuraghazra/github-readme-stats/blob/master/readme.md

Adjust the language ranking algorithm by specifying weights for byte count and repository count. The default uses only byte count. Recommended settings balance both metrics.

```markdown
![Top Langs](https://github-readme-stats.vercel.app/api/top-langs/?username=anuraghazra&size_weight=0.5&count_weight=0.5)
```

--------------------------------

### Use Pie Chart Layout for Top Languages Card

Source: https://github.com/anuraghazra/github-readme-stats/blob/master/readme.md

Visualize top languages with a pie chart by specifying `&layout=pie`.

```markdown
<![[Top Langs](https://github-readme-stats.vercel.app/api/top-langs/?username=anuraghazra&layout=pie)](https://github.com/anuraghazra/github-readme-stats)
```

--------------------------------

### Apply a Theme to GitHub Readme Stats

Source: https://github.com/anuraghazra/github-readme-stats/blob/master/themes/README.md

To apply a theme, append the `?theme=THEME_NAME` parameter to the stats card URL. Replace `THEME_NAME` with the desired theme.

```markdown
![Anurag's GitHub stats](https://github-readme-stats.vercel.app/api?username=anuraghazra&theme=dark&show_icons=true)
```

--------------------------------

### Generate Pinned Repositories Cards

Source: https://github.com/anuraghazra/github-readme-stats/blob/master/readme.md

Use these HTML snippets to display pinned repositories directly in your README.md. Specify the username and repository name for each card.

```html
<a href="https://github.com/anuraghazra/github-readme-stats">
  <img align="center" src="https://github-readme-stats.vercel.app/api/pin/?username=anuraghazra&repo=github-readme-stats" />
</a>
<a href="https://github.com/anuraghazra/convoychat">
  <img align="center" src="https://github-readme-stats.vercel.app/api/pin/?username=anuraghazra&repo=convoychat" />
</a>
```

--------------------------------

### Top Languages Card with Custom Layout and Ranking

Source: https://context7.com/anuraghazra/github-readme-stats/llms.txt

Generates a card displaying top programming languages with customizable layout, ranking weights, and exclusion options. Use this to showcase language proficiency with specific visual styles and ranking logic.

```bash
curl "https://github-readme-stats.vercel.app/api/top-langs/\
?username=anuraghazra\
&layout=donut-vertical\
&langs_count=10\
&size_weight=0.5\
&count_weight=0.5\
&exclude_repo=github-readme-stats,anuraghazra.github.io\
&hide=html,css\
&stats_format=bytes\
&card_width=400\
&theme=tokyonight\
&disable_animations=true"
```

--------------------------------

### Use GitHub Theme Context Tags for Dynamic Themes

Source: https://github.com/anuraghazra/github-readme-stats/blob/master/readme.md

Dynamically switch themes based on the user's GitHub theme preference by appending `#gh-dark-mode-only` or `#gh-light-mode-only` to the image URL. This ensures the correct theme is displayed for light or dark mode users.

```markdown
[![Anurag's GitHub stats-Dark](https://github-readme-stats.vercel.app/api?username=anuraghazra&show_icons=true&theme=dark#gh-dark-mode-only)](https://github.com/anuraghazra/github-readme-stats#gh-dark-mode-only)
[![Anurag's GitHub stats-Light](https://github-readme-stats.vercel.app/api?username=anuraghazra&show_icons=true&theme=default#gh-light-mode-only)](https://github.com/anuraghazra/github-readme-stats#gh-light-mode-only)
```

--------------------------------

### Use GitHub's New Media Feature with HTML Picture Element

Source: https://github.com/anuraghazra/github-readme-stats/blob/master/readme.md

Leverage GitHub's new media feature with the HTML `<picture>` element and `prefers-color-scheme` media query to automatically display images suitable for the user's current browser theme (dark or light).

```html
<picture>
  <source
    srcset="https://github-readme-stats.vercel.app/api?username=anuraghazra&show_icons=true&theme=dark"
    media="(prefers-color-scheme: dark)"
  />
  <source
    srcset="https://github-readme-stats.vercel.app/api?username=anuraghazra&show_icons=true"
    media="(prefers-color-scheme: light), (prefers-color-scheme: no-preference)"
  />
  <img src="https://github-readme-stats.vercel.app/api?username=anuraghazra&show_icons=true" />
</picture>
```

--------------------------------

### Basic GitHub Stats Card

Source: https://github.com/anuraghazra/github-readme-stats/blob/master/readme.md

Copy and paste this markdown into your profile to display your GitHub stats. Replace `anuraghazra` with your GitHub username.

```markdown
[![Anurag's GitHub stats](https://github-readme-stats.vercel.app/api?username=anuraghazra)](https://github.com/anuraghazra/github-readme-stats)
```

--------------------------------

### fetchTopLanguages

Source: https://context7.com/anuraghazra/github-readme-stats/llms.txt

Queries the GitHub GraphQL API for language byte counts across all owned, non-forked repositories and returns languages sorted by a configurable weighted ranking index.

```APIDOC
### `fetchTopLanguages` — Fetch Top Languages

#### Description
Queries the GitHub GraphQL API for language byte counts across all owned, non-forked repositories and returns languages sorted by a configurable weighted ranking index.

#### Parameters
- **username** (string) - Required - The GitHub username.
- **exclude_repo** (array) - Optional - An array of repository names to exclude.
- **size_weight** (float) - Optional - The weight for language size in the ranking (default: 1.0).
- **count_weight** (float) - Optional - The weight for repository count in the ranking (default: 1.0).

#### Returns
- **object** - An object where keys are language names and values are language statistics.
  - **name** (string) - The name of the language.
  - **color** (string) - The color associated with the language.
  - **size** (integer) - The total byte size of code in this language.
  - **count** (integer) - The number of repositories where this language is used.

#### Request Example (Default)
```javascript
import { fetchTopLanguages } from "./src/fetchers/top-languages.js";

const langs = await fetchTopLanguages("anuraghazra");
console.log(langs.JavaScript);
```

#### Response Example (Default)
```json
{
  "JavaScript": { "name": "JavaScript", "color": "#f1e05a", "size": 4230000, "count": 42 },
  "TypeScript": { "name": "TypeScript", "color": "#3178c6", "size": 1840000, "count": 18 }
}
```

#### Request Example (Balanced Ranking)
```javascript
const balanced = await fetchTopLanguages(
  "anuraghazra",
  ["github-readme-stats"],  // exclude_repo
  0.5,                      // size_weight
  0.5,                      // count_weight
);
console.log(balanced);
```
```

--------------------------------

### Language Stats Algorithm Calculation

Source: https://github.com/anuraghazra/github-readme-stats/blob/master/readme.md

This JavaScript snippet illustrates the formula used for ranking languages based on byte count and repository count, allowing for custom weighting.

```javascript
ranking_index = (byte_count ^ size_weight) * (repo_count ^ count_weight)
```

--------------------------------

### Generate Repository Pin Card

Source: https://context7.com/anuraghazra/github-readme-stats/llms.txt

Embed a card pinning a specific public GitHub repository, showing its name, description, language, stars, and forks. Customize with owner labels, colors, and description length.

```bash
curl "https://github-readme-stats.vercel.app/api/pin/?username=anuraghazra&repo=github-readme-stats"
```

```bash
curl "https://github-readme-stats.vercel.app/api/pin/\
?username=anuraghazra\
&repo=github-readme-stats\
&show_owner=true\
&description_lines_count=3\
&title_color=fff\
&icon_color=79ff97\
&text_color=9f9f9f\
&bg_color=151515\
&border_radius=8\
&locale=ja\
&cache_seconds=864000"
```

```markdown
# [![Readme Card](https://github-readme-stats.vercel.app/api/pin/?username=anuraghazra&repo=github-readme-stats)](https://github.com/anuraghazra/github-readme-stats)
```

--------------------------------

### Generate Top Languages Card

Source: https://context7.com/anuraghazra/github-readme-stats/llms.txt

Display a card with the most-used programming languages from a user's public, non-forked repositories. Supports different layouts and ranking algorithms.

```bash
curl "https://github-readme-stats.vercel.app/api/top-langs/?username=anuraghazra"
```

--------------------------------

### Guard Access with `guardAccess`

Source: https://context7.com/anuraghazra/github-readme-stats/llms.txt

Checks an identifier against configured whitelist/blacklist environment variables. Returns a result object that short-circuits the handler on denial. Ensure `res`, `id`, `type`, and `colors` are correctly provided.

```javascript
import { guardAccess } from "./src/common/access.js";

// In a handler (Vercel or Express):
const access = guardAccess({
  res,
  id: username,          // "anuraghazra"
  type: "username",      // "username" | "gist" | "wakatime"
  colors: { title_color, text_color, bg_color, border_color, theme },
});

if (!access.isPassed) {
  return access.result;  // response already sent (error SVG)
}
// continue with normal card rendering…
```

--------------------------------

### Generate Stats and Top Languages Cards

Source: https://github.com/anuraghazra/github-readme-stats/blob/master/readme.md

Embed these HTML snippets directly into your README.md file to display your GitHub stats and top languages. Customize with username and other options.

```html
<a href="https://github.com/anuraghazra/github-readme-stats">
  <img height=200 align="center" src="https://github-readme-stats.vercel.app/api?username=anuraghazra" />
</a>
<a href="https://github.com/anuraghazra/convoychat">
  <img height=200 align="center" src="https://github-readme-stats.vercel.app/api/top-langs?username=anuraghazra&layout=compact&langs_count=8&card_width=320" />
</a>
```

--------------------------------

### Use Donut Chart Layout for Top Languages Card

Source: https://github.com/anuraghazra/github-readme-stats/blob/master/readme.md

Display top languages using a donut chart visualization by setting `&layout=donut`.

```markdown
<![[Top Langs](https://github-readme-stats.vercel.app/api/top-langs/?username=anuraghazra&layout=donut)](https://github.com/anuraghazra/github-readme-stats)
```

--------------------------------

### Show Additional Individual Stats

Source: https://github.com/anuraghazra/github-readme-stats/blob/master/readme.md

Use the `&show=` parameter with comma-separated values to include additional stats not shown by default. Options include `reviews`, `discussions_started`, `discussions_answered`, `prs_merged`, and `prs_merged_percentage`.

```markdown
![Anurag's GitHub stats](https://github-readme-stats.vercel.app/api?username=anuraghazra&show=reviews,discussions_started,discussions_answered,prs_merged,prs_merged_percentage)
```

--------------------------------

### GitHub Extra Pins Usage

Source: https://github.com/anuraghazra/github-readme-stats/blob/master/readme.md

Use this markdown to pin more than 6 repositories on your GitHub profile. Replace the username and repo values with your own.

```markdown
<a href="https://github.com/anuraghazra/github-readme-stats" align="center">[![Readme Card](https://github-readme-stats.vercel.app/api/pin/?username=anuraghazra&repo=github-readme-stats)](https://github.com/anuraghazra/github-readme-stats)</a>
```

--------------------------------

### Fetch Top Languages

Source: https://context7.com/anuraghazra/github-readme-stats/llms.txt

Queries the GitHub GraphQL API for language byte counts across owned, non-forked repositories. Supports weighted ranking by size and repository count. Use exclude_repo to filter out specific repositories.

```javascript
import { fetchTopLanguages } from "./src/fetchers/top-languages.js";

// Default: pure byte-count ranking
const langs = await fetchTopLanguages("anuraghazra");
// {
//   JavaScript: { name: "JavaScript", color: "#f1e05a", size: 4230000, count: 42 },
//   TypeScript: { name: "TypeScript", color: "#3178c6", size: 1840000, count: 18 },
//   ...
// }
```

```javascript
const balanced = await fetchTopLanguages(
  "anuraghazra",
  ["github-readme-stats"],  // exclude_repo
  0.5,                      // size_weight
  0.5,                      // count_weight
);
```

--------------------------------

### GitHub Extra Pins

Source: https://github.com/anuraghazra/github-readme-stats/blob/master/readme.md

Allows pinning more than 6 repositories in your profile.

```APIDOC
## GET /api/pin

### Description
Allows pinning more than 6 repositories in your profile.

### Endpoint
`/api/pin`

### Query Parameters
- **username** (string) - Required - Your GitHub username.
- **repo** (string) - Required - The repository to pin.
- **show_owner** (boolean) - Optional - Shows the repo's owner name.
- **description_lines_count** (number) - Optional - Manually set the number of lines for the description (clamped between 1 and 3).
```

--------------------------------

### Use Compact Layout for Top Languages Card

Source: https://github.com/anuraghazra/github-readme-stats/blob/master/readme.md

Change the visual design of the top languages card to a compact layout using the `&layout=compact` option.

```markdown
<![Top Langs](https://github-readme-stats.vercel.app/api/top-langs/?username=anuraghazra&layout=compact)
```

--------------------------------

### fetchRepo

Source: https://context7.com/anuraghazra/github-readme-stats/llms.txt

Fetches public metadata for a single GitHub repository, including star/fork counts, primary language, and archival/template flags.

```APIDOC
### `fetchRepo` — Fetch Repository Data

#### Description
Fetches public metadata for a single GitHub repository (or organisation repository), including star/fork counts, primary language, and archival/template flags.

#### Parameters
- **owner** (string) - Required - The owner of the repository (username or organization).
- **repo** (string) - Required - The name of the repository.

#### Returns
- **RepositoryData** (object) - An object containing repository metadata.
  - **name** (string) - The name of the repository.
  - **nameWithOwner** (string) - The owner and name of the repository (e.g., "owner/repo").
  - **isPrivate** (boolean) - Whether the repository is private.
  - **isArchived** (boolean) - Whether the repository is archived.
  - **isTemplate** (boolean) - Whether the repository is a template repository.
  - **description** (string) - The description of the repository.
  - **starCount** (integer) - The number of stars the repository has.
  - **forkCount** (integer) - The number of forks the repository has.
  - **primaryLanguage** (object) - The primary language of the repository.
    - **name** (string) - The name of the primary language.
    - **color** (string) - The color associated with the primary language.
    - **id** (string) - The GraphQL ID of the primary language.

#### Request Example
```javascript
import { fetchRepo } from "./src/fetchers/repo.js";

try {
  const repo = await fetchRepo("anuraghazra", "github-readme-stats");
  console.log(repo.starCount);
} catch (err) {
  if (err.message === "User Repository Not found") {
    console.error("Repo is private or does not exist");
  }
}
```

#### Response Example
```json
{
  "name": "github-readme-stats",
  "nameWithOwner": "anuraghazra/github-readme-stats",
  "isPrivate": false,
  "isArchived": false,
  "isTemplate": false,
  "description": "Dynamically generated stats for your GitHub READMEs",
  "starCount": 67000,
  "forkCount": 18000,
  "primaryLanguage": { "name": "JavaScript", "color": "#f1e05a", "id": "MDg6TGFuZ3VhZ2UxNDA=" }
}
```
```

--------------------------------

### Use Transparent Theme for GitHub Stats

Source: https://github.com/anuraghazra/github-readme-stats/blob/master/readme.md

Apply the `transparent` theme to ensure your stats card looks good on both dark and light GitHub themes. This is achieved by adding `&theme=transparent` to the URL.

```markdown
![Anurag's GitHub stats](https://github-readme-stats.vercel.app/api?username=anuraghazra&show_icons=true&theme=transparent)
```

--------------------------------

### Format Numbers with `kFormatter` and `formatBytes`

Source: https://context7.com/anuraghazra/github-readme-stats/llms.txt

Utility functions for formatting numbers in card labels. `kFormatter` formats numbers with 'k' suffix, while `formatBytes` converts bytes to human-readable units like KB, MB, GB. Optional precision can be specified for `kFormatter`.

```javascript
import { kFormatter, formatBytes } from "./src/common/fmt.js";

kFormatter(6626);          // → 6.6k
kFormatter(6626, 2);       // → "6.63k"  (forced precision)
kFormatter(999);           // → 999      (number, no suffix)
kFormatter(-12500);        // → -12.5k

formatBytes(0);            // → "0 B"
formatBytes(1024);         // → "1.0 KB"
formatBytes(1536000);      // → "1.5 MB"
formatBytes(2.5 * 1024 ** 3); // → "2.5 GB"
```

--------------------------------

### fetchGist

Source: https://context7.com/anuraghazra/github-readme-stats/llms.txt

Fetches public metadata for a GitHub Gist, deriving the primary language by summing file byte sizes per language.

```APIDOC
### `fetchGist` — Fetch GitHub Gist Data

#### Description
Fetches public metadata for a GitHub Gist, deriving the primary language by summing file byte sizes per language.

#### Parameters
- **gistId** (string) - Required - The ID of the GitHub Gist.

#### Returns
- **GistData** (object) - An object containing Gist metadata.
  - **name** (string) - The name of the primary file in the Gist.
  - **nameWithOwner** (string) - The owner and name of the primary file (e.g., "owner/filename").
  - **description** (string) - The description of the Gist.
  - **language** (string) - The primary language of the Gist based on file sizes.
  - **starsCount** (integer) - The number of stars the Gist has.
  - **forksCount** (integer) - The number of forks the Gist has.

#### Request Example
```javascript
import { fetchGist } from "./src/fetchers/gist.js";

const gist = await fetchGist("bbfce31e0217a3689c8d961a356cb10d");
console.log(gist.language);
```

#### Response Example
```json
{
  "name": "script.js",
  "nameWithOwner": "Yizack/script.js",
  "description": "A useful utility script",
  "language": "JavaScript",
  "starsCount": 12,
  "forksCount": 3
}
```
```

--------------------------------

### WakaTime Stats Card with Customization

Source: https://context7.com/anuraghazra/github-readme-stats/llms.txt

Generates a card displaying coding activity from a WakaTime profile. Supports compact layout, language hiding, custom API domains, and custom titles. Useful for integrating detailed coding stats into READMEs.

```bash
curl "https://github-readme-stats.vercel.app/api/wakatime?username=ffflabs"
# → Basic WakaTime card
```

```bash
curl "https://github-readme-stats.vercel.app/api/wakatime\
?username=ffflabs\
&layout=compact\
&langs_count=5\
&hide=other,text\
&display_format=percent\
&api_domain=wakapi.dev\
&hide_progress=false\
&custom_title=WakaTime%20Stats\
&theme=github_dark\
&cache_seconds=86400"
# → Compact layout, hide specific languages, use custom WakaTime-compatible API (Wakapi)
```

```markdown
# In README
# ![WakaTime](https://github-readme-stats.vercel.app/api/wakatime?username=ffflabs&hide_progress=true)
```

--------------------------------

### Multi-line Text Wrapper `wrapTextMultiline`

Source: https://context7.com/anuraghazra/github-readme-stats/llms.txt

Wraps a string to fit within a card's character-width constraint, handling Chinese full-width punctuation and truncating with '...' when exceeding the line limit. Specify the maximum width and maximum number of lines.

```javascript
import { wrapTextMultiline } from "./src/common/fmt.js";

wrapTextMultiline("Dynamically generated GitHub stats for your README", 30, 3);
// → ["Dynamically generated", "GitHub stats for your", "README"]

wrapTextMultiline("This description is extremely long and will be truncated after three lines of content", 30, 3);
// → ["This description is", "extremely long and will be", "truncated after three..."]

// Chinese: splits on full-width comma
wrapTextMultiline("动态生成，GitHub统计数据，用于README", 59, 3);
// → ["动态生成", "GitHub统计数据", "用于README"]
```

--------------------------------

### Fetch Repository Data

Source: https://context7.com/anuraghazra/github-readme-stats/llms.txt

Fetches public metadata for a single GitHub repository, including star/fork counts and primary language. Handles 'User Repository Not found' errors, which may indicate a private or non-existent repository.

```javascript
import { fetchRepo } from "./src/fetchers/repo.js";

try {
  const repo = await fetchRepo("anuraghazra", "github-readme-stats");
  // repo: RepositoryData = {
  //   name: "github-readme-stats",
  //   nameWithOwner: "anuraghazra/github-readme-stats",
  //   isPrivate: false,
  //   isArchived: false,
  //   isTemplate: false,
  //   description: "Dynamically generated stats for your GitHub READMEs",
  //   starCount: 67000,
  //   forkCount: 18000,
  //   primaryLanguage: { name: "JavaScript", color: "#f1e05a", id: "MDg6TGFuZ3VhZ2UxNDA=" }
  // }
} catch (err) {
  if (err.message === "User Repository Not found") {
    console.error("Repo is private or does not exist");
  }
}
```

--------------------------------

### Uptime / PAT Health Check

Source: https://context7.com/anuraghazra/github-readme-stats/llms.txt

Returns the operational status of the public instance by verifying that at least one configured GitHub PAT can reach the API. Rate-limited to one live check per 5 minutes.

```APIDOC
## GET /api/status/up

### Description
Checks the operational status of the public instance.

### Method
GET

### Endpoint
/api/status/up

### Parameters
#### Query Parameters
- **type** (enum) - Optional - Response format. Options: `boolean`, `json`, `shields`. Default: `boolean`.

### Request Example
```bash
# Boolean response
curl "https://github-readme-stats.vercel.app/api/status/up"

# JSON response
curl "https://github-readme-stats.vercel.app/api/status/up?type=json"

# Shields.io dynamic badge format
curl "https://github-readme-stats.vercel.app/api/status/up?type=shields"
```

### Response
Returns the operational status in the specified format.

### Response Example
- **Boolean:** `true` or `false`
- **JSON:** `{"up":true}`
- **Shields.io:** `{"schemaVersion":1,"label":"Public Instance","message":"up","color":"brightgreen","isError":false}`
```

--------------------------------

### fetchStats

Source: https://context7.com/anuraghazra/github-readme-stats/llms.txt

Queries the GitHub GraphQL API for a user's contribution data and computes their rank. Supports optional multi-page star fetching.

```APIDOC
### `fetchStats` — Fetch GitHub User Statistics

#### Description
Queries the GitHub GraphQL API for a user's contribution data and computes their rank. Supports optional multi-page star fetching via `FETCH_MULTI_PAGE_STARS=true`.

#### Parameters
- **username** (string) - Required - The GitHub username.
- **include_all_commits** (boolean) - Optional - Whether to include all-time commits.
- **exclude_repo** (array) - Optional - An array of repository names to exclude.
- **include_merged_pull_requests** (boolean) - Optional - Whether to include merged pull requests.
- **include_discussions** (boolean) - Optional - Whether to include discussions.
- **include_discussions_answers** (boolean) - Optional - Whether to include discussion answers.
- **commits_year** (integer) - Optional - The year to filter commits by.

#### Returns
- **StatsData** (object) - An object containing various GitHub statistics.
  - **name** (string) - The user's name.
  - **totalPRs** (integer) - Total pull requests.
  - **totalPRsMerged** (integer) - Total merged pull requests.
  - **mergedPRsPercentage** (float) - Percentage of merged pull requests.
  - **totalReviews** (integer) - Total reviews.
  - **totalCommits** (integer) - Total commits.
  - **totalIssues** (integer) - Total issues.
  - **totalStars** (integer) - Total stars received.
  - **totalDiscussionsStarted** (integer) - Total discussions started.
  - **totalDiscussionsAnswered** (integer) - Total discussions answered.
  - **contributedTo** (integer) - Number of repositories contributed to.
  - **rank** (object) - The user's contribution rank.
    - **level** (string) - The rank level (e.g., "S").
    - **percentile** (float) - The rank percentile.

#### Request Example (Basic)
```javascript
import { fetchStats } from "./src/fetchers/stats.js";

const stats = await fetchStats("anuraghazra");
console.log(stats.rank);
```

#### Response Example (Basic)
```json
{
  "name": "Anurag Hazra",
  "totalPRs": 312,
  "totalPRsMerged": 0,
  "mergedPRsPercentage": 0,
  "totalReviews": 148,
  "totalCommits": 1402,
  "totalIssues": 87,
  "totalStars": 67000,
  "totalDiscussionsStarted": 0,
  "totalDiscussionsAnswered": 0,
  "contributedTo": 95,
  "rank": { "level": "S", "percentile": 0.42 }
}
```

#### Request Example (Full)
```javascript
const fullStats = await fetchStats(
  "anuraghazra",
  true,                     // include_all_commits
  ["my-private-fork"],      // exclude_repo
  true,                     // include_merged_pull_requests
  true,                     // include_discussions
  true,                     // include_discussions_answers
  2023,                     // commits_year
);
console.log(fullStats.rank);
```

#### Response Example (Full)
```json
{
  "name": "Anurag Hazra",
  "totalPRs": 312,
  "totalPRsMerged": 0,
  "mergedPRsPercentage": 0,
  "totalReviews": 148,
  "totalCommits": 1402,
  "totalIssues": 87,
  "totalStars": 67000,
  "totalDiscussionsStarted": 0,
  "totalDiscussionsAnswered": 0,
  "contributedTo": 95,
  "rank": { "level": "S", "percentile": 0.38 }
}
```
```

--------------------------------

### Add Transparent Alpha Channel to Theme Background

Source: https://github.com/anuraghazra/github-readme-stats/blob/master/readme.md

Make any theme's background transparent by setting the `bg_color` parameter to a value with a transparent alpha channel, such as `bg_color=00000000`. This allows the card to blend with the surrounding page.

```markdown
![Anurag's GitHub stats](https://github-readme-stats.vercel.app/api?username=anuraghazra&show_icons=true&bg_color=00000000)
```

--------------------------------

### Use Donut Vertical Chart Layout for Top Languages Card

Source: https://github.com/anuraghazra/github-readme-stats/blob/master/readme.md

Opt for a vertical donut chart layout for the top languages card by using the `&layout=donut-vertical` parameter.

```markdown
<![[Top Langs](https://github-readme-stats.vercel.app/api/top-langs/?username=anuraghazra&layout=donut-vertical)](https://github.com/anuraghazra/github-readme-stats)
```

--------------------------------

### Change Stats Format to Bytes in Top Languages Card

Source: https://github.com/anuraghazra/github-readme-stats/blob/master/readme.md

Display language statistics in bytes instead of percentages by using the `&stats_format=bytes` option.

```markdown
<![Top Langs](https://github-readme-stats.vercel.app/api/top-langs/?username=anuraghazra&stats_format=bytes)
```

--------------------------------

### Fetch GitHub User Statistics

Source: https://context7.com/anuraghazra/github-readme-stats/llms.txt

Queries the GitHub GraphQL API for user contribution data and computes rank. Supports optional multi-page star fetching. Use 'true' for include_all_commits, include_merged_pull_requests, include_discussions, and include_discussions_answers to fetch more data.

```javascript
import { fetchStats } from "./src/fetchers/stats.js";

// Basic fetch (current-year commits, no extra stats)
const stats = await fetchStats("anuraghazra");
// stats: StatsData = {
//   name: "Anurag Hazra",
//   totalPRs: 312,
//   totalPRsMerged: 0,
//   mergedPRsPercentage: 0,
//   totalReviews: 148,
//   totalCommits: 1402,
//   totalIssues: 87,
//   totalStars: 67000,
//   totalDiscussionsStarted: 0,
//   totalDiscussionsAnswered: 0,
//   contributedTo: 95,
//   rank: { level: "S", percentile: 0.42 }
// }
```

```javascript
const fullStats = await fetchStats(
  "anuraghazra",
  true,                     // include_all_commits
  ["my-private-fork"],      // exclude_repo
  true,                     // include_merged_pull_requests
  true,                     // include_discussions
  true,                     // include_discussions_answers
  2023,                     // commits_year
);
console.log(fullStats.rank);
// { level: "S", percentile: 0.38 }
```

--------------------------------

### retryer

Source: https://context7.com/anuraghazra/github-readme-stats/llms.txt

Executes a fetcher function with the next available PAT_N environment variable when rate-limited or credentials fail. The number of retries equals the count of discovered PATs.

```APIDOC
## retryer — Multi-PAT API Request Retrier

### Description
Executes a fetcher function with the next available `PAT_N` environment variable when rate-limited or credentials fail. The number of retries equals the count of discovered PATs.

### Parameters
- **fetcher** (function) - Required - The function to execute, which receives `variables` and `token`.
- **variables** (object) - Optional - Variables to pass to the fetcher function.

### Returns
A promise that resolves with the result of the fetcher function.

### Throws
- `CustomError.MAX_RETRY`: If all PATs are exhausted or rate-limited.
- `CustomError.NO_TOKENS`: If no `PAT_N` environment variables are configured.

### Example
```javascript
import { retryer } from "./src/common/retryer.js";
import { request } from "./src/common/http.js";

// Set up PAT_1, PAT_2, ... in environment (or .env)
// process.env.PAT_1 = "ghp_xxxx"
// process.env.PAT_2 = "ghp_yyyy"

const myFetcher = (variables, token) =>
  request(
    { query: `query { viewer { login } }`, variables },
    { Authorization: `bearer ${token}` },
  );

try {
  const response = await retryer(myFetcher, {});
  console.log(response.data.data.viewer.login); // → "anuraghazra"
} catch (err) {
  console.error(err.type, err.message);
}
```
```

--------------------------------

### GitHub Gist Pin Card

Source: https://context7.com/anuraghazra/github-readme-stats/llms.txt

Returns an SVG card for a public GitHub Gist, showing name, description, primary language, star count, and fork count.

```APIDOC
## GET /api/gist

### Description
Returns an SVG card for a public GitHub Gist.

### Method
GET

### Endpoint
/api/gist

### Parameters
#### Query Parameters
- **id** (string) - Required - Gist ID (hex string from the Gist URL).
- **show_owner** (boolean) - Optional - Whether to show the gist owner username in the title. Default: `false`.
- **theme** (string) - Optional - Theme for the card.
- **border_radius** (integer) - Optional - Border radius for the card.
- **locale** (string) - Optional - Locale for the card content.

### Request Example
```bash
curl "https://github-readme-stats.vercel.app/api/gist?id=bbfce31e0217a3689c8d961a356cb10d&show_owner=true&theme=calm&border_radius=12&locale=fr"
```

### Response
Returns an SVG image.

### Response Example
(SVG content representing the Gist card)
```

--------------------------------

### Repository Pin Card

Source: https://context7.com/anuraghazra/github-readme-stats/llms.txt

Returns an SVG card pinning a specific public GitHub repository, showing its name, description, primary language, star count, and fork count. Customizable with several options.

```APIDOC
## GET /api/pin — Repository Pin Card

### Description
Returns an SVG card pinning a specific public GitHub repository, showing its name, description, primary language, star count, and fork count.

### Method
GET

### Endpoint
/api/pin/

### Parameters
#### Query Parameters
- **username** (string) - Required - GitHub username or org name
- **repo** (string) - Required - Repository name
- **show_owner** (boolean) - Optional - Prefix title with owner name (default: `false`)
- **description_lines_count** (number 1-3) - Optional - Number of description lines to render (default: auto)

### Request Example
```bash
curl "https://github-readme-stats.vercel.app/api/pin/?username=anuraghazra&repo=github-readme-stats"
```

### Response
#### Success Response (200)
- SVG image displaying repository pin information

#### Response Example
(SVG content)
```

--------------------------------

### Fetch WakaTime Coding Stats

Source: https://context7.com/anuraghazra/github-readme-stats/llms.txt

Fetches a user's all-time coding stats from the WakaTime public API or a compatible self-hosted API. Provides language breakdown, total time, and daily average.

```javascript
import { fetchWakatimeStats } from "./src/fetchers/wakatime.js";

// From wakatime.com
const stats = await fetchWakatimeStats({ username: "ffflabs", api_domain: undefined });
// stats.languages[0] → { name: "JavaScript", hours: 312, minutes: 44, percent: 38.2, text: "312 hrs 44 mins" }
// stats.human_readable_total → "817 hrs 22 mins"
// stats.daily_average → 8243  (seconds)
```

```javascript
// From a self-hosted Wakapi instance
const wakapiStats = await fetchWakatimeStats({
  username: "myuser",
  api_domain: "wakapi.dev",
});
```

--------------------------------

### fetchWakatimeStats

Source: https://context7.com/anuraghazra/github-readme-stats/llms.txt

Fetches a user's all-time coding stats from the WakaTime public API or a compatible self-hosted API.

```APIDOC
### `fetchWakatimeStats` — Fetch WakaTime Coding Stats

#### Description
Fetches a user's all-time coding stats from the WakaTime public API (or a compatible self-hosted API like Wakapi/Hakatime).

#### Parameters
- **options** (object) - Required - Configuration options for fetching stats.
  - **username** (string) - Required - The WakaTime username.
  - **api_domain** (string) - Optional - The domain of the WakaTime API (e.g., "wakapi.dev"). If not provided, defaults to wakatime.com.

#### Returns
- **object** - An object containing WakaTime coding statistics.
  - **languages** (array) - An array of language statistics.
    - **name** (string) - The name of the language.
    - **hours** (integer) - Hours coded in this language.
    - **minutes** (integer) - Minutes coded in this language.
    - **percent** (float) - Percentage of total time spent in this language.
    - **text** (string) - Formatted string of hours and minutes.
  - **human_readable_total** (string) - Total time coded in a human-readable format.
  - **daily_average** (integer) - Average coding time per day in seconds.

#### Request Example (wakatime.com)
```javascript
import { fetchWakatimeStats } from "./src/fetchers/wakatime.js";

const stats = await fetchWakatimeStats({ username: "ffflabs", api_domain: undefined });
console.log(stats.languages[0].name);
console.log(stats.human_readable_total);
```

#### Response Example (wakatime.com)
```json
{
  "languages": [
    { "name": "JavaScript", "hours": 312, "minutes": 44, "percent": 38.2, "text": "312 hrs 44 mins" }
  ],
  "human_readable_total": "817 hrs 22 mins",
  "daily_average": 8243
}
```

#### Request Example (Self-hosted Wakapi)
```javascript
const wakapiStats = await fetchWakatimeStats({
  username: "myuser",
  api_domain: "wakapi.dev",
});
console.log(wakapiStats.daily_average);
```
```

--------------------------------

### Calculate GitHub User Rank

Source: https://context7.com/anuraghazra/github-readme-stats/llms.txt

Computes a rank level and global percentile based on contribution statistics. Supports different calculation modes for total commits.

```javascript
import { calculateRank } from "./src/calculateRank.js";

const rank = calculateRank({
  all_commits: false,   // false → COMMITS_MEDIAN = 250
  commits: 500,
  prs: 120,
  issues: 60,
  reviews: 30,
  repos: 45,            // currently unused in formula
  stars: 2500,
  followers: 800,
});
// → { level: "A+", percentile: 8.7 }

// With include_all_commits=true the commits median shifts to 1000
const rankAllTime = calculateRank({
  all_commits: true,
  commits: 3200,
  prs: 400,
  issues: 200,
  reviews: 90,
  repos: 120,
  stars: 15000,
  followers: 3000,
});
// → { level: "S", percentile: 0.9 }

// Level thresholds (percentile ≤ threshold → level)
// S: ≤1%  A+: ≤12.5%  A: ≤25%  A-: ≤37.5%
// B+: ≤50%  B: ≤62.5%  B-: ≤75%  C+: ≤87.5%  C: ≤100%
```

--------------------------------

### getCardColors

Source: https://context7.com/anuraghazra/github-readme-stats/llms.txt

Merges per-request color overrides with the selected theme's colour palette, falling back to the `default` theme when values are invalid hex strings.

```APIDOC
## getCardColors — Resolve Theme-Aware Card Colors

### Description
Merges per-request color overrides with the selected theme's colour palette, falling back to the `default` theme when values are invalid hex strings.

### Parameters
- **title_color** (string) - Optional - Hex color code for the title.
- **text_color** (string) - Optional - Hex color code for the text.
- **icon_color** (string) - Optional - Hex color code for the icons.
- **bg_color** (string) - Optional - Hex color code for the background. Can also be a gradient string (e.g., "30,e96443,904e95").
- **border_color** (string) - Optional - Hex color code for the border.
- **ring_color** (string) - Optional - Hex color code for the ring.
- **theme** (string) - Optional - The name of the theme to use. Defaults to "default".

### Returns
An object containing the resolved color properties for the card.

### Example
```javascript
import { getCardColors } from "./src/common/color.js";

// Apply the "tokyonight" theme with a custom title colour override
const colors = getCardColors({
  title_color: "ff6e96",
  text_color: undefined,
  icon_color: undefined,
  bg_color: undefined,
  border_color: undefined,
  ring_color: undefined,
  theme: "tokyonight",
});
// colors = {
//   titleColor: "#ff6e96",
//   textColor: "#a9b1d6",
//   iconColor: "#73daca",
//   bgColor: "#1a1b27",
//   borderColor: "#...",
//   ringColor: "#ff6e96"
// }

// Gradient background
const gradient = getCardColors({
  bg_color: "30,e96443,904e95",
  theme: "default",
});
// gradient.bgColor → ["30", "e96443", "904e95"]
```
```