@shiinasaku/github-card 2.0.0 → 4.2.0

package/README.md

@@ -1,354 +1,252 @@
-# GitHub Profile Card
-
 <div align="center">
 
-<br/>
+<img src="assets/logo.svg" alt="GitHub Card" width="520" />
 
-<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>
+### Beautiful, blazing-fast GitHub profile cards
 
-<br/><br/>
+Live SVG cards for your README — stars, commits, languages, all auto-updating. One line, zero config, edge-cached.
 
-# github-card
+<br/>
 
-**Beautiful GitHub stats cards for your README, site, or npm project.**
+[![npm](https://img.shields.io/npm/v/@shiinasaku/github-card?style=flat-square&label=npm&color=000)](https://www.npmjs.com/package/@shiinasaku/github-card)
+[![Bun](https://img.shields.io/badge/Bun-1.x-f9f1e1?style=flat-square&logo=bun&logoColor=000)](https://bun.sh)
+[![Elysia](https://img.shields.io/badge/Elysia-1.x-7c3aed?style=flat-square)](https://elysiajs.com)
+[![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6?style=flat-square&logo=typescript&logoColor=fff)](https://www.typescriptlang.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-34d399?style=flat-square)](LICENSE)
+[![Deploy with Vercel](https://img.shields.io/badge/Deploy-Vercel-000?style=flat-square&logo=vercel)](https://vercel.com/new/clone?repository-url=https://github.com/ShiinaSaku/Github-Card)
 
-[![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)
+<a href="https://card.shiina.xyz/card/shiinasaku?theme=shiina">
+  <img src="https://card.shiina.xyz/card/shiinasaku?theme=shiina" alt="Live demo — shiinasaku" width="520" />
+</a>
 
-[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)
+<sub>Live instance · <code>shiinasaku</code> · theme <code>shiina</code> — updates itself as you code</sub>
 
 </div>
 
 ---
 
-## Embed in 10 seconds
-
-```markdown
-![GitHub Stats](https://card.shiina.xyz/card/YOUR_USERNAME)
-```
-
-Replace `YOUR_USERNAME`. Done.
-
-### Dark mode aware
+### ✨ What's new in 4.2
 
-```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>
-```
+> System-font only · no shipped `.woff2` · crisper text (`geometricPrecision`, tabular numbers) · new 24 px icons (MingCute / Huge / Tabler) · airy stat stack with 7 px gaps, no boxes · default `affiliations=owner` — org stars excluded unless `?affiliations=affiliated` · fully typed `github.ts` & `github-client`, cache v8.
 
 ---
 
-## Themes
-
-20 built-in themes. Pass `?theme=name` to use one.
+## Quickstart
 
-<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>
+Paste into your profile README — replace `shiinasaku` with your username:
 
-<details>
-<summary><strong>All 20 themes</strong></summary>
-<br/>
+```md
+[![GitHub Card](https://card.shiina.xyz/card/shiinasaku?theme=shiina)](https://github.com/shiinasaku)
+```
 
-`default` `dark` `radical` `merko` `gruvbox` `tokyonight` `onedark` `cobalt` `synthwave` `highcontrast` `dracula` `monokai` `nord` `github_dark` `pearl` `slate` `forest` `rose` `sand`
+That's it. No sign-up, no build — the card refreshes on every push.
 
-Preview every theme with your own data:
+<details>
+<summary><b>Self-host / local dev</b></summary>
 
-```
-https://card.shiina.xyz/YOUR_USERNAME/themes
+```bash
+bun install
+cp .env.example .env   # add GITHUB_TOKEN
+bun dev                # http://localhost:3000
 ```
 
+| Command             | Action                |
+| ------------------- | --------------------- |
+| `bun test`          | Run 51 tests          |
+| `bun run typecheck` | Strict `tsc --noEmit` |
+| `bun run lint`      | oxlint                |
+| `bun run fmt`       | oxfmt                 |
+
 </details>
 
 ---
 
-## Parameters
-
-All parameters are optional query strings on `/card/:username`.
-
-### Appearance
+## Why GitHub Card?
 
-| 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
+<table>
+<tr>
+<td width="50%">
 
-Pass hex values **without** `#`.
+**One line, zero config**<br/>
+An `<img>` tag is the entire integration. No OAuth, no action.
 
-| Parameter      | Description        |
-| :------------- | :----------------- |
-| `bg_color`     | Background         |
-| `title_color`  | Name text          |
-| `text_color`   | Body text & labels |
-| `icon_color`   | Stat icons         |
-| `border_color` | Card border        |
+**Edge-fast**<br/>
+L1 memory + L2 Redis SWR, `s-maxage=1800`, `stale-while-revalidate`, `ETag`/`304`. Warm hits render in microseconds.
 
-### Data Filtering
+**Retina avatars**<br/>
+Profile images inlined as Base64 at 2×, clipped + ringed in pure SVG.
 
-| 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)    |
+</td>
+<td width="50%">
 
-### Examples
+**Adaptive layout**<br/>
+Width, wrapping, and legends measured with per-glyph metrics — nothing ever overlaps or clips.
 
-```bash
-# Compact with 3 languages
-https://card.shiina.xyz/card/ShiinaSaku?compact=true&lang_count=3
+**Users _and_ orgs**<br/>
+`GET /card/:login` works for users and organizations.
 
-# GitHub dark colors
-https://card.shiina.xyz/card/ShiinaSaku?bg_color=0d1117&text_color=c9d1d9&title_color=58a6ff
+**Glassmorphic depth**<br/>
+Radial + linear ambient gradients track your accent for volumetric light at zero runtime cost.
 
-# Organization stats
-https://card.shiina.xyz/card/ShiinaSaku?scope=all&orgs=oven-sh,elysiajs
+</td>
+</tr>
+</table>
 
-# Hide specific stats
-https://card.shiina.xyz/card/ShiinaSaku?hide=issues,prs,stars
-```
+OpenAPI docs live at [`/openapi`](https://card.shiina.xyz/openapi). Pure ESM lib, zero server dep for `renderCard`.
 
 ---
 
-## Programmatic Usage (npm)
+## Themes — 21 hand-tuned
 
-Install the package to render cards in your own server, CLI tool, or script:
+Preview **every** theme with your own data:
 
-```bash
-bun add github-card    # or npm install github-card
+```md
+![All themes](https://card.shiina.xyz/shiinasaku/themes)
 ```
 
-### 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
-```
+| Dark favorites                                     | Light & accent                                   |
+| -------------------------------------------------- | ------------------------------------------------ |
+| `shiina` · `aurora` · `oled` · `slate`             | `default` · `pearl` · `sand`                     |
+| `github_dark` · `dark` · `nord` · `dracula`        | `forest` · `rose` · `cobalt`                     |
+| `tokyonight` · `synthwave` · `radical` · `monokai` | `gruvbox` · `merko` · `onedark` · `highcontrast` |
 
-### 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";
-```
+Add `?theme=tokyonight` or override any slot with hex or Tailwind tokens: `pink-400`, `#ff79c6`, `ff79c6`.
 
-### Use as Elysia plugin
+---
 
-The default export is an Elysia app. Mount it into your own server:
+## Customization
 
-```typescript
-import { Elysia } from "elysia";
-import githubCard from "github-card/server";
+| Parameter      |    Type    | Description                                                       |
+| -------------- | :--------: | ----------------------------------------------------------------- |
+| `theme`        |  `string`  | Built-in theme (table above)                                      |
+| `bg_color`     |  `string`  | Background fill                                                   |
+| `title_color`  |  `string`  | Name / title                                                      |
+| `text_color`   |  `string`  | Stats, labels, body                                               |
+| `icon_color`   |  `string`  | Icons + ambient glow                                              |
+| `border_color` |  `string`  | Card outline                                                      |
+| `hide_border`  | `boolean`  | Remove outline                                                    |
+| `compact`      | `boolean`  | Slim — hides bio/pronouns/Twitter/legend                          |
+| `animate`      | `boolean`  | Fade-in stats + animated language bar                             |
+| `hide`         | `string[]` | Hide stats: `stars`, `commits`, `issues`, `repos`, `prs`          |
+| `hide_langs`   | `string[]` | Exclude `hide_langs=html,css`                                     |
+| `show_langs`   | `string[]` | Only `show_langs=typescript,rust`                                 |
+| `lang_count`   |   `1–10`   | Top languages (default `5`)                                       |
+| `scope`        |  `string`  | `personal` (default), `org`, `all`                                |
+| `orgs`         | `string[]` | Restrict org stats to `orgs=vercel,elysiajs`                      |
+| `affiliations` |  `string`  | `owner` (default) or `affiliated` — org stars excluded by default |
+| `fields`       | `string[]` | Fetch only `fields=stats` for speed                               |
 
-new Elysia()
-  .use(githubCard) // adds /card/:username, /:username/themes, etc.
-  .get("/my-route", () => "hello")
-  .listen(3000);
-```
+#### Examples
 
----
+```md
+<!-- Dracula, no border, animated -->
 
-## Self-Hosting
+![card](https://card.shiina.xyz/card/shiinasaku?theme=dracula&hide_border=true&animate=true)
 
-### Vercel (recommended)
+<!-- Fully custom colors -->
 
-```bash
-git clone https://github.com/ShiinaSaku/Github-Card.git
-cd Github-Card
-vercel deploy
-```
+![card](https://card.shiina.xyz/card/shiinasaku?bg_color=0d1117&title_color=58a6ff&text_color=9da7b3&icon_color=58a6ff)
 
-Set environment variables:
+<!-- Compact, no issues/prs -->
 
-```
-GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx          # required
-UPSTASH_REDIS_REST_URL=https://...             # optional, L2 cache
-UPSTASH_REDIS_REST_TOKEN=...                   # optional
-```
+![card](https://card.shiina.xyz/card/shiinasaku?compact=true&hide=issues,prs&fields=stats)
 
-### Local Development
+<!-- Include org stars explicitly -->
 
-```bash
-bun install
-echo "GITHUB_TOKEN=ghp_xxx" > .env
-bun dev
-# http://localhost:3000/card/ShiinaSaku
+![card](https://card.shiina.xyz/card/shiinasaku?affiliations=affiliated)
+
+<!-- Organization -->
+
+![card](https://card.shiina.xyz/card/elysiajs)
 ```
 
 ---
 
-## API Reference
+## Deploy your own
 
-| 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               |
+[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https://github.com/ShiinaSaku/Github-Card)
 
-### Response Headers
+1. Click the button (or fork + import).
+2. Add env vars:
 
-| 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` | `*`                                                             |
+|    Variable    | Required | Purpose                             |
+| :------------: | :------: | ----------------------------------- |
+| `GITHUB_TOKEN` |    ✅    | GitHub PAT — read-only is enough    |
+|  `REDIS_URL`   |    ➖    | Redis / Upstash for shared L2 cache |
 
-### Status Codes
+3. Done — serves `/card/:username` on Vercel CDN `s-maxage=1800, stale-while-revalidate=1800`.
 
-| 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     |
+> Without Redis, in-memory LRU (1000 entries, SWR 30 min) still keeps warm instances fast.
 
 ---
 
-## Architecture
+## API
 
-```
-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
-```
+| Endpoint                | Description                                 |
+| ----------------------- | ------------------------------------------- |
+| `GET /card/:username`   | SVG card — all params above                 |
+| `GET /:username/themes` | One SVG with **all themes** for a user      |
+| `GET /meta`             | Service metadata + theme list               |
+| `GET /health`           | Uptime, cache telemetry, Redis reachability |
+| `GET /openapi`          | Interactive OpenAPI docs                    |
 
-| 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                            |
+Responses: `image/svg+xml`, `ETag` + `CDN-Cache-Control` + CORS `*`. Conditional `If-None-Match` → `304`.
 
 ---
 
-## Testing
+## Use as a library
 
 ```bash
-bun test               # 21 tests
-bun test --coverage    # with coverage
-bun run typecheck      # tsc
-bun run lint           # oxlint
+bun add @shiinasaku/github-card     # Bun
+npm install @shiinasaku/github-card # Node / Next / Vite
 ```
 
----
+```ts
+import { renderCard, themes } from "@shiinasaku/github-card";
 
-## What the card shows
+const svg = renderCard(user, stats, languages, { theme: "tokyonight" });
+// → string of SVG, zero deps, any runtime
+```
 
-| 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                     |
+Prebuilt `dist/lib.js` + `.d.ts`; Bun resolves raw TS via `bun` export condition. Pure renderer — no network, no server.
 
-### 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 |
+## Architecture
 
-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`.
+```mermaid
+flowchart LR
+  A[GET /card/:username] --> B[Elysia<br/>validation · CORS · OpenAPI · timing]
+  B --> C{L1 memory<br/>SWR 30m}
+  C -- hit --> G[render SVG<br/>ETag/304 → CDN]
+  C -- miss --> D{L2 Redis<br/>SWR 30m}
+  D -- hit --> G
+  D -- miss --> E[GitHub GraphQL<br/>100/page, 5 pages, 6s timeout]
+  E --> F[typed fetch<br/>+ avatar 150px]
+  F --> G
+  G --> H[Pure SVG<br/>system fonts · measured layout · glass]
+```
+
+- **Bun + Elysia** — one of the fastest HTTP stacks.
+- **Two-tier SWR** — stale served instantly + background refresh, request coalescing via `inFlight`.
+- **Typed upstream** — `RepoNode`/`ContributionEntry` generics, `T=unknown`, `TimeoutError`/`RateLimitError` mapping.
 
 ---
 
-## License
+## Releasing
+
+Fully automated:
 
-[MIT](LICENSE)
+1. **Actions → Bump** → `patch` / `minor` / `major`.
+2. Workflow bumps `package.json`, commits, tags `vX.Y.Z`.
+3. Tag triggers **Release**: `oxfmt` · `oxlint` · `typecheck` · `tests` · `dist` build · tag↔version guard · `npm pack` verify → publish with [provenance](https://docs.npmjs.com/generating-provenance-statements) + GitHub Release.
 
 ---
 
 <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>
+
+**[MIT](LICENSE) © [saku shiina](https://www.shiina.xyz)** — built with Bun, Elysia, and system fonts.
+
+<sub>Stars default to <code>owner</code> only in 4.2 — add <code>?affiliations=affiliated</code> to include orgs.</sub>
+
 </div>

package/dist/card.d.ts

@@ -0,0 +1,16 @@
+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[];
+    hide_langs?: string[];
+    show_langs?: string[];
+    animate?: boolean;
+};
+export declare function renderCard(user: UserProfile, stats: UserStats, langs: LanguageStat[], opts?: CardOpts): string;

package/dist/lib.d.ts

@@ -0,0 +1,13 @@
+/**
+ * github-card — npm entry point
+ *
+ * Re-exports the pure SVG renderer, all themes, types, and utility functions.
+ * No server dependency — works in any JS/TS runtime.
+ */
+export { renderCard, type CardOpts } from "./card";
+export type { UserProfile, UserStats, LanguageStat, ProfileData, CardOptions } from "./types";
+export { themes, resolveColors, type Theme } from "./utils/themes";
+export { kFormat, escapeXml, wrapText, measureText } from "./utils/format";
+export { icons, icon } from "./utils/icons";
+export { getLangColor } from "./utils/languages";
+export { FONT_FACE, FONT_FAMILY } from "./utils/font";