@shiinasaku/github-card 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 サクシイナ
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,354 @@
+# GitHub Profile Card
+
+<div align="center">
+
+<br/>
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://card.shiina.xyz/card/ShiinaSaku?theme=github_dark" />
+  <img src="https://card.shiina.xyz/card/ShiinaSaku" alt="GitHub Profile Card" width="500" />
+</picture>
+
+<br/><br/>
+
+# github-card
+
+**Beautiful GitHub stats cards for your README, site, or npm project.**
+
+[![npm](https://img.shields.io/npm/v/github-card?style=flat&colorA=0b1220&colorB=58a6ff)](https://www.npmjs.com/package/github-card)
+[![Built with Bun](https://img.shields.io/badge/Bun-000?style=flat&logo=bun&logoColor=ffd700)](https://bun.sh)
+[![MIT](https://img.shields.io/badge/License-MIT-green?style=flat)](LICENSE)
+[![Tests](https://img.shields.io/badge/Tests-21%20passed-34d399?style=flat)](#testing)
+
+[Live Demo](https://card.shiina.xyz/card/ShiinaSaku) &#183;
+[All Themes](https://card.shiina.xyz/ShiinaSaku/themes) &#183;
+[API Docs](https://card.shiina.xyz/openapi) &#183;
+[npm Package](#programmatic-usage-npm)
+
+</div>
+
+---
+
+## Embed in 10 seconds
+
+```markdown
+![GitHub Stats](https://card.shiina.xyz/card/YOUR_USERNAME)
+```
+
+Replace `YOUR_USERNAME`. Done.
+
+### Dark mode aware
+
+```html
+<picture>
+  <source
+    media="(prefers-color-scheme: dark)"
+    srcset="https://card.shiina.xyz/card/YOUR_USERNAME?theme=github_dark"
+  />
+  <img src="https://card.shiina.xyz/card/YOUR_USERNAME" alt="GitHub Stats" />
+</picture>
+```
+
+---
+
+## Themes
+
+20 built-in themes. Pass `?theme=name` to use one.
+
+<table>
+  <tr>
+    <td align="center"><img src="https://card.shiina.xyz/card/ShiinaSaku?theme=default" width="400" alt="default" /><br/><code>default</code></td>
+    <td align="center"><img src="https://card.shiina.xyz/card/ShiinaSaku?theme=github_dark" width="400" alt="github_dark" /><br/><code>github_dark</code></td>
+  </tr>
+  <tr>
+    <td align="center"><img src="https://card.shiina.xyz/card/ShiinaSaku?theme=tokyonight" width="400" alt="tokyonight" /><br/><code>tokyonight</code></td>
+    <td align="center"><img src="https://card.shiina.xyz/card/ShiinaSaku?theme=dracula" width="400" alt="dracula" /><br/><code>dracula</code></td>
+  </tr>
+  <tr>
+    <td align="center"><img src="https://card.shiina.xyz/card/ShiinaSaku?theme=nord" width="400" alt="nord" /><br/><code>nord</code></td>
+    <td align="center"><img src="https://card.shiina.xyz/card/ShiinaSaku?theme=radical" width="400" alt="radical" /><br/><code>radical</code></td>
+  </tr>
+  <tr>
+    <td align="center"><img src="https://card.shiina.xyz/card/ShiinaSaku?theme=synthwave" width="400" alt="synthwave" /><br/><code>synthwave</code></td>
+    <td align="center"><img src="https://card.shiina.xyz/card/ShiinaSaku?theme=rose" width="400" alt="rose" /><br/><code>rose</code></td>
+  </tr>
+</table>
+
+<details>
+<summary><strong>All 20 themes</strong></summary>
+<br/>
+
+`default` `dark` `radical` `merko` `gruvbox` `tokyonight` `onedark` `cobalt` `synthwave` `highcontrast` `dracula` `monokai` `nord` `github_dark` `pearl` `slate` `forest` `rose` `sand`
+
+Preview every theme with your own data:
+
+```
+https://card.shiina.xyz/YOUR_USERNAME/themes
+```
+
+</details>
+
+---
+
+## Parameters
+
+All parameters are optional query strings on `/card/:username`.
+
+### Appearance
+
+| Parameter     | Default   | Description                          |
+| :------------ | :-------- | :----------------------------------- |
+| `theme`       | `default` | One of the 20 built-in themes        |
+| `compact`     | `false`   | Hides bio, pronouns, language labels |
+| `hide_border` | `false`   | Removes the card border              |
+
+### Custom Colors
+
+Pass hex values **without** `#`.
+
+| Parameter      | Description        |
+| :------------- | :----------------- |
+| `bg_color`     | Background         |
+| `title_color`  | Name text          |
+| `text_color`   | Body text & labels |
+| `icon_color`   | Stat icons         |
+| `border_color` | Card border        |
+
+### Data Filtering
+
+| Parameter    | Default    | Description                                                             |
+| :----------- | :--------- | :---------------------------------------------------------------------- |
+| `lang_count` | `5`        | Top languages shown (1--10)                                             |
+| `hide`       | --         | Comma-separated: `stars,commits,issues,repos,prs`                       |
+| `scope`      | `personal` | `personal` / `org` / `all` -- see [scope details](#what-the-card-shows) |
+| `orgs`       | --         | Comma-separated org logins to include (filters contributed-to repos)    |
+
+### Examples
+
+```bash
+# Compact with 3 languages
+https://card.shiina.xyz/card/ShiinaSaku?compact=true&lang_count=3
+
+# GitHub dark colors
+https://card.shiina.xyz/card/ShiinaSaku?bg_color=0d1117&text_color=c9d1d9&title_color=58a6ff
+
+# Organization stats
+https://card.shiina.xyz/card/ShiinaSaku?scope=all&orgs=oven-sh,elysiajs
+
+# Hide specific stats
+https://card.shiina.xyz/card/ShiinaSaku?hide=issues,prs,stars
+```
+
+---
+
+## Programmatic Usage (npm)
+
+Install the package to render cards in your own server, CLI tool, or script:
+
+```bash
+bun add github-card    # or npm install github-card
+```
+
+### Render SVG from data
+
+```typescript
+import { renderCard, themes } from "github-card";
+
+const svg = renderCard(
+  {
+    login: "octocat",
+    name: "The Octocat",
+    avatarUrl: "https://github.com/octocat.png",
+    bio: "Open source enthusiast",
+    pronouns: "they/them",
+    twitter: "github",
+  },
+  { stars: 3200, commits: 1450, issues: 89, repos: 42, prs: 210 },
+  [
+    { name: "TypeScript", size: 120000, color: "#3178c6" },
+    { name: "Go", size: 80000, color: "#00ADD8" },
+    { name: "Rust", size: 40000, color: "#dea584" },
+  ],
+  { theme: "tokyonight", compact: false },
+);
+
+// svg is a self-contained SVG string with embedded font
+```
+
+### Available exports
+
+```typescript
+import {
+  // Core renderer
+  renderCard,
+  type CardOpts,
+
+  // Types
+  type UserProfile,
+  type UserStats,
+  type LanguageStat,
+  type ProfileData,
+  type CardOptions,
+
+  // Theming
+  themes,
+  resolveColors,
+  type Theme,
+
+  // Utilities
+  kFormat, // 1500 -> "1.5k"
+  escapeXml, // "<>" -> "&lt;&gt;"
+  wrapText, // text wrapping with ellipsis
+  icon, // SVG stat icons (star, commit, pr, issue, repo, x)
+  icons, // raw SVG path data
+  getLangColor, // language -> hex color (650+ languages)
+  FONT_FACE, // base64 @font-face CSS rule
+  FONT_FAMILY, // font-family declaration
+} from "github-card";
+```
+
+### Use as Elysia plugin
+
+The default export is an Elysia app. Mount it into your own server:
+
+```typescript
+import { Elysia } from "elysia";
+import githubCard from "github-card/server";
+
+new Elysia()
+  .use(githubCard) // adds /card/:username, /:username/themes, etc.
+  .get("/my-route", () => "hello")
+  .listen(3000);
+```
+
+---
+
+## Self-Hosting
+
+### Vercel (recommended)
+
+```bash
+git clone https://github.com/ShiinaSaku/Github-Card.git
+cd Github-Card
+vercel deploy
+```
+
+Set environment variables:
+
+```
+GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx          # required
+UPSTASH_REDIS_REST_URL=https://...             # optional, L2 cache
+UPSTASH_REDIS_REST_TOKEN=...                   # optional
+```
+
+### Local Development
+
+```bash
+bun install
+echo "GITHUB_TOKEN=ghp_xxx" > .env
+bun dev
+# http://localhost:3000/card/ShiinaSaku
+```
+
+---
+
+## API Reference
+
+| Endpoint                | Returns                                     |
+| :---------------------- | :------------------------------------------ |
+| `GET /card/:username`   | SVG stats card                              |
+| `GET /:username/themes` | SVG grid of all themes                      |
+| `GET /health`           | JSON -- cache metrics, Redis status, uptime |
+| `GET /openapi`          | Interactive API documentation               |
+
+### Response Headers
+
+| Header                        | Value                                                           |
+| :---------------------------- | :-------------------------------------------------------------- |
+| `Cache-Control`               | `public, max-age=0, s-maxage=1800, stale-while-revalidate=1800` |
+| `ETag`                        | Enables 304 Not Modified                                        |
+| `Server-Timing`               | Per-request timing telemetry                                    |
+| `Access-Control-Allow-Origin` | `*`                                                             |
+
+### Status Codes
+
+| Code | Meaning             |
+| :--- | :------------------ |
+| 200  | SVG card            |
+| 304  | Cached (ETag match) |
+| 401  | Bad GitHub token    |
+| 404  | User not found      |
+| 422  | Invalid parameters  |
+| 429  | GitHub rate limited |
+| 502  | GitHub API down     |
+
+---
+
+## Architecture
+
+```
+Request -> Elysia (CORS, OpenAPI, Server-Timing)
+  -> GitHub GraphQL API (parallel personal + org fetches)
+  -> L1 In-Memory Cache (30m fresh / 30m stale SWR)
+  -> L2 Upstash Redis (optional, 60m TTL)
+  -> SVG Renderer (embedded Roboto WOFF2 font)
+  -> ETag / 304 / Cache-Control
+```
+
+| Layer     | Tech                                      |
+| :-------- | :---------------------------------------- |
+| Runtime   | Bun                                       |
+| Framework | Elysia                                    |
+| Data      | GitHub GraphQL API                        |
+| Cache L1  | In-memory Map with SWR                    |
+| Cache L2  | Upstash Redis (serverless)                |
+| Font      | Roboto (subsetted WOFF2, base64 embedded) |
+| Deploy    | Vercel Functions                          |
+| Tests     | bun:test -- 21 tests                      |
+| Lint      | oxlint + oxfmt                            |
+
+---
+
+## Testing
+
+```bash
+bun test               # 21 tests
+bun test --coverage    # with coverage
+bun run typecheck      # tsc
+bun run lint           # oxlint
+```
+
+---
+
+## What the card shows
+
+| Stat      | Source                                 |
+| :-------- | :------------------------------------- |
+| Stars     | Total across owned repos (excl. forks) |
+| Commits   | Current calendar year                  |
+| Issues    | Open + closed                          |
+| Repos     | Owned, non-fork                        |
+| PRs       | Open + closed + merged                 |
+| Languages | Top N by code size                     |
+
+### Scope
+
+| Value      | Stars / Repos / Languages from                       | Speed                              |
+| :--------- | :--------------------------------------------------- | :--------------------------------- |
+| `personal` | Your own repos only                                  | Single query                       |
+| `org`      | Org repos you actually contributed to (commits, PRs) | Parallel: metadata + contributions |
+| `all`      | Your repos + org repos you contributed to            | Parallel: personal + contributions |
+
+Org stats use GitHub's `repositoriesContributedTo` API -- only repos you actually touched are counted, not every repo in the organization. Filter to specific orgs with `orgs=org1,org2`.
+
+---
+
+## License
+
+[MIT](LICENSE)
+
+---
+
+<div align="center">
+<sub>Built with <a href="https://bun.sh">Bun</a> and <a href="https://elysiajs.com">Elysia</a>. Hosted on <a href="https://vercel.com">Vercel</a>.</sub>
+</div>

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@shiinasaku/github-card",
+  "version": "2.0.0",
+  "description": "Beautiful GitHub stats SVG cards. Embed in README, use as API, or render programmatically.",
+  "keywords": [
+    "badge",
+    "bun",
+    "elysia",
+    "github",
+    "github-card",
+    "github-stats",
+    "profile-card",
+    "readme",
+    "stats",
+    "svg"
+  ],
+  "homepage": "https://card.shiina.xyz",
+  "license": "MIT",
+  "author": {
+    "name": "saku shiina",
+    "email": "saku@shiina.xyz",
+    "url": "https://www.shiina.xyz"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ShiinaSaku/Github-Card.git"
+  },
+  "files": [
+    "src",
+    "fonts",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "main": "./src/lib.ts",
+  "module": "./src/lib.ts",
+  "types": "./src/lib.ts",
+  "exports": {
+    ".": {
+      "types": "./src/lib.ts",
+      "import": "./src/lib.ts"
+    },
+    "./server": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    }
+  },
+  "scripts": {
+    "dev": "bun run --watch src/index.ts",
+    "build": "bun build src/index.ts --target bun --outdir dist",
+    "fmt": "oxfmt",
+    "fmt:check": "oxfmt --check",
+    "lint": "oxlint",
+    "lint:fix": "oxlint --fix",
+    "typecheck": "tsc --noEmit --skipLibCheck",
+    "test": "bun test",
+    "test:coverage": "bun test --coverage"
+  },
+  "dependencies": {
+    "@elysiajs/cors": "^1.4.1",
+    "@elysiajs/openapi": "^1.4.14",
+    "@elysiajs/server-timing": "^1.4.0",
+    "@upstash/redis": "^1.36.2",
+    "elysia": "latest"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "oxfmt": "0.33.0",
+    "oxlint": "1.48.0",
+    "typescript": "5.9.3"
+  }
+}

package/src/card.ts

@@ -0,0 +1,137 @@
+import { resolveColors, kFormat, escapeXml, icon, wrapText, FONT_FACE, FONT_FAMILY } from "./utils";
+import type { UserProfile, UserStats, LanguageStat } from "./types";
+
+export type CardOpts = {
+  theme?: string;
+  title_color?: string;
+  text_color?: string;
+  icon_color?: string;
+  bg_color?: string;
+  border_color?: string;
+  hide_border?: boolean;
+  compact?: boolean;
+  hide?: string[];
+};
+
+export function renderCard(
+  user: UserProfile,
+  stats: UserStats,
+  langs: LanguageStat[],
+  opts: CardOpts = {},
+): string {
+  const c = resolveColors(opts);
+  const hideBorder = opts.hide_border ?? false;
+  const compact = opts.compact ?? false;
+
+  const name = escapeXml(user.name || user.login);
+  const uname = escapeXml(user.login);
+  const bioRaw = !compact && user.bio ? escapeXml(user.bio) : "";
+  const bioLines = bioRaw ? wrapText(bioRaw, 42, 2) : [];
+  const pronouns = !compact && user.pronouns ? escapeXml(user.pronouns) : "";
+  const avatar = user.avatarUrl.replace(/&/g, "&");
+  const twitter = !compact && user.twitter ? escapeXml(user.twitter) : "";
+  const hiddenStats = new Set((opts.hide || []).map((key) => key.toLowerCase()));
+  const svgTitle = `${name}'s GitHub Stats`;
+
+  const W = 500;
+  const H = 200;
+  const P = 22;
+  const avatarSize = 72;
+  const barWidth = W - P * 2;
+  const barY = H - 40;
+  const labelY = H - 16;
+  const infoX = P + avatarSize + 16;
+
+  const totalSize = langs.reduce((sum, l) => sum + l.size, 0) || 1;
+  let offset = 0;
+  const langRects = langs
+    .map((lang) => {
+      const w = (lang.size / totalSize) * barWidth;
+      const r = `<rect x="${P + offset}" y="${barY}" width="${w}" height="8" fill="${lang.color}"/>`;
+      offset += w;
+      return r;
+    })
+    .join("");
+
+  const labelSpacing = compact ? 0 : Math.floor(barWidth / Math.max(langs.length, 1));
+  const langLabels = compact
+    ? ""
+    : langs
+        .map((lang, i) => {
+          const pct = ((lang.size / totalSize) * 100).toFixed(0);
+          return `<circle cx="${P + i * labelSpacing + 5}" cy="${labelY}" r="4" fill="${lang.color}"/><text x="${P + i * labelSpacing + 13}" y="${labelY + 4}" class="lang">${lang.name} ${pct}%</text>`;
+        })
+        .join("");
+
+  const nameY = P + 22;
+  const usernameY = nameY + 18;
+  const bioY = usernameY + 14;
+  const twitterY = bioLines.length ? bioY + 28 : usernameY + 16;
+
+  const headerY = P + avatarSize + 12;
+  const statLabelY = 28;
+
+  const visibleStats = [
+    { key: "stars", iconName: "star" as const, label: "Stars", value: stats.stars },
+    { key: "commits", iconName: "commit" as const, label: "Commits", value: stats.commits },
+    { key: "issues", iconName: "issue" as const, label: "Issues", value: stats.issues },
+    { key: "repos", iconName: "repo" as const, label: "Repos", value: stats.repos },
+    { key: "prs", iconName: "pr" as const, label: "PRs", value: stats.prs },
+  ].filter((stat) => !hiddenStats.has(stat.key));
+
+  const statsMarkup = visibleStats
+    .map(
+      (stat, index) => `<g transform="translate(${index * 100},0)">
+        ${icon(stat.iconName, c.icon, 16)}
+        <text x="20" y="12" class="stat">${kFormat(stat.value)}</text>
+        <text x="0" y="${statLabelY}" class="stat-label">${stat.label}</text>
+      </g>`,
+    )
+    .join("");
+
+  return `<svg width="${W}" height="${H}" viewBox="0 0 ${W} ${H}" preserveAspectRatio="xMinYMin meet" xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="title desc" shape-rendering="auto" text-rendering="optimizeLegibility" image-rendering="optimizeQuality">
+    <title id="title">${svgTitle}</title>
+    <desc id="desc">GitHub stats card for ${name} including stars, commits, issues, repositories, pull requests, and top languages.</desc>
+    <defs>
+      <clipPath id="a"><circle cx="${P + avatarSize / 2}" cy="${P + avatarSize / 2}" r="${avatarSize / 2}"/></clipPath>
+      <clipPath id="b"><rect x="${P}" y="${barY}" width="${barWidth}" height="8" rx="4"/></clipPath>
+      <filter id="shadow" x="-10%" y="-10%" width="130%" height="140%">
+        <feGaussianBlur in="SourceAlpha" stdDeviation="2"/>
+        <feOffset dx="0" dy="1" result="offsetblur"/>
+        <feComponentTransfer>
+          <feFuncA type="linear" slope="0.15"/>
+        </feComponentTransfer>
+        <feMerge>
+          <feMergeNode/>
+          <feMergeNode in="SourceGraphic"/>
+        </feMerge>
+      </filter>
+    </defs>
+    <style>
+      ${FONT_FACE}
+      *{font-family:${FONT_FAMILY}}
+      .bg{fill:#${c.bg}}
+      .title{font-size:18px;font-weight:700;fill:#${c.title}}
+      .user{font-size:12px;fill:#${c.text};opacity:.7}
+      ${compact ? "" : `.bio{font-size:11px;fill:#${c.text};opacity:.65}.tw{font-size:11px;fill:#${c.text};opacity:.7}.lang{font-size:10px;fill:#${c.text}}`}
+      .stat{font-size:14px;font-weight:700;fill:#${c.text};text-anchor:start}
+      .stat-label{font-size:9px;font-weight:600;fill:#${c.text};opacity:.55;text-transform:uppercase;letter-spacing:.6px;text-anchor:start}
+      .sec{font-size:9px;font-weight:600;fill:#${c.text};opacity:.5;text-transform:uppercase;letter-spacing:.6px}
+    </style>
+    <rect class="bg" width="${W}" height="${H}" rx="10" stroke="${hideBorder ? "none" : `#${c.border}`}" stroke-width="1.5" filter="url(#shadow)"/>
+    <circle cx="${P + avatarSize / 2}" cy="${P + avatarSize / 2}" r="${avatarSize / 2 + 2}" fill="none" stroke="#${c.border}" stroke-width="1" opacity=".6"/>
+    <image href="${avatar}" x="${P}" y="${P}" width="${avatarSize}" height="${avatarSize}" clip-path="url(#a)" filter="url(#shadow)" preserveAspectRatio="xMidYMid slice"/>
+    <text x="${infoX}" y="${nameY}" class="title">${name}</text>
+    <text x="${infoX}" y="${usernameY}" class="user">@${uname}${pronouns ? ` · ${pronouns}` : ""}</text>
+    ${!compact && bioLines[0] ? `<text x="${infoX}" y="${bioY}" class="bio">${bioLines[0]}</text>` : ""}
+    ${!compact && bioLines[1] ? `<text x="${infoX}" y="${bioY + 12}" class="bio">${bioLines[1]}</text>` : ""}
+    ${!compact && twitter ? `<g transform="translate(${infoX},${twitterY - 9})">${icon("x", c.icon, 11)}<text x="14" y="9" class="tw">@${twitter}</text></g>` : ""}
+    <g transform="translate(${P},${headerY})">
+      ${statsMarkup}
+    </g>
+    <text x="${P}" y="${barY - 8}" class="sec">Top Languages</text>
+    <rect x="${P}" y="${barY}" width="${barWidth}" height="8" rx="4" fill="#${c.text}" opacity=".1"/>
+    <g clip-path="url(#b)">${langRects}</g>
+    ${langLabels}
+  </svg>`;
+}