@shiinasaku/github-card 2.0.0

package/src/index.ts

@@ -0,0 +1,355 @@
+import { Elysia, t } from "elysia";
+import { cors } from "@elysiajs/cors";
+import { openapi } from "@elysiajs/openapi";
+import { serverTiming } from "@elysiajs/server-timing";
+import {
+  AuthError,
+  getCacheMetrics,
+  getProfileData,
+  isRedisReachable,
+  NotFoundError,
+  RateLimitError,
+  UpstreamError,
+} from "./github";
+import { renderCard } from "./card";
+import { themes } from "./utils";
+
+const USERNAME_PATTERN = "^[a-zA-Z0-9-]{1,39}$";
+const appStartedAt = Date.now();
+
+function parseLangCount(value?: string): number {
+  if (!value) return 5;
+  const parsed = Number.parseInt(value, 10);
+  if (Number.isNaN(parsed)) return 5;
+  return Math.min(10, Math.max(1, parsed));
+}
+
+function parseHiddenStats(value?: string): string[] {
+  if (!value) return [];
+  const allowed = new Set(["stars", "commits", "issues", "repos", "prs"]);
+  return Array.from(
+    new Set(
+      value
+        .split(",")
+        .map((v) => v.trim().toLowerCase())
+        .filter((v) => allowed.has(v)),
+    ),
+  );
+}
+
+function parseScope(value?: string): "personal" | "org" | "all" {
+  const normalized = value?.trim().toLowerCase();
+  if (normalized === "org" || normalized === "all") return normalized;
+  return "personal";
+}
+
+function parseOrgs(value?: string): string[] {
+  if (!value) return [];
+  return Array.from(
+    new Set(
+      value
+        .split(",")
+        .map((v) => v.trim())
+        .filter(Boolean),
+    ),
+  );
+}
+
+function renderUserThemesSvg(
+  user: Parameters<typeof renderCard>[0],
+  stats: Parameters<typeof renderCard>[1],
+  langs: Parameters<typeof renderCard>[2],
+  cardOpts: Parameters<typeof renderCard>[3],
+) {
+  const entries = Object.keys(themes);
+  const cols = 2;
+  const gap = 20;
+  const cardW = 500;
+  const cardH = 200;
+  const labelH = 22;
+  const cellH = cardH + labelH;
+  const rows = Math.ceil(entries.length / cols);
+  const width = cols * cardW + (cols + 1) * gap;
+  const height = rows * cellH + (rows + 1) * gap;
+
+  const blocks = entries
+    .map((name, index) => {
+      const col = index % cols;
+      const row = Math.floor(index / cols);
+      const x = gap + col * (cardW + gap);
+      const y = gap + row * (cellH + gap);
+      const cardSvg = renderCard(user, stats, langs, { ...cardOpts, theme: name });
+      const encoded = encodeURIComponent(cardSvg).replace(/'/g, "%27").replace(/"/g, "%22");
+
+      return `<g transform="translate(${x},${y})">
+        <text x="4" y="14" fill="#e2e8f0" font-size="13" font-family="Inter,ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,Arial" font-weight="700">${name}</text>
+        <image href="data:image/svg+xml;utf8,${encoded}" x="0" y="${labelH}" width="${cardW}" height="${cardH}"/>
+      </g>`;
+    })
+    .join("");
+
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}" role="img" aria-label="GitHub Card themes for user">
+  <rect width="100%" height="100%" fill="#0b1220"/>
+  ${blocks}
+</svg>`;
+}
+
+const app = new Elysia({ name: "github-card" })
+  .error({
+    NOT_FOUND_ERROR: NotFoundError,
+    RATE_LIMIT_ERROR: RateLimitError,
+    AUTH_ERROR: AuthError,
+    UPSTREAM_ERROR: UpstreamError,
+  })
+  .onError(({ code, error, set }) => {
+    switch (code) {
+      case "NOT_FOUND_ERROR":
+        set.status = 404;
+        return { error: error.message };
+      case "RATE_LIMIT_ERROR":
+        set.status = 429;
+        return { error: error.message };
+      case "AUTH_ERROR":
+        set.status = 401;
+        return { error: error.message };
+      case "UPSTREAM_ERROR":
+        set.status = 502;
+        return { error: error.message };
+    }
+  })
+  .use(
+    cors({
+      origin: true,
+      methods: ["GET", "OPTIONS"],
+      allowedHeaders: ["Content-Type", "If-None-Match"],
+      exposeHeaders: ["ETag", "Cache-Control", "Content-Type"],
+      maxAge: 86400,
+      credentials: false,
+    }),
+  )
+  .use(
+    openapi({
+      documentation: {
+        info: {
+          title: "GitHub Profile Card API",
+          version: "1.3.0",
+          description: "Generate GitHub profile SVG cards for README and web embeds.",
+        },
+        tags: [
+          { name: "Card", description: "SVG card endpoints" },
+          { name: "Meta", description: "Service metadata" },
+          { name: "Ops", description: "Operational endpoints" },
+        ],
+      },
+    }),
+  )
+  .use(serverTiming())
+  .get(
+    "/",
+    () => ({
+      message: "GitHub Profile Card API",
+      usage: "GET /card/:username",
+      themes: "GET /:username/themes",
+      docs: "/openapi",
+    }),
+    {
+      detail: { tags: ["Meta"], summary: "API metadata" },
+      response: {
+        200: t.Object({
+          message: t.String(),
+          usage: t.String(),
+          themes: t.String(),
+          docs: t.String(),
+        }),
+      },
+    },
+  )
+  .get(
+    "/meta",
+    () => ({
+      message: "GitHub Profile Card API",
+      usage: "GET /card/:username",
+      themes:
+        "default, dark, radical, merko, gruvbox, tokyonight, onedark, cobalt, synthwave, highcontrast, dracula, monokai, nord, github_dark, pearl, slate, forest, rose, sand",
+    }),
+    {
+      detail: { tags: ["Meta"], summary: "API metadata" },
+    },
+  )
+  .get(
+    "/:username/themes",
+    async ({ params: { username }, query, headers, set }) => {
+      const langCount = parseLangCount(query.lang_count);
+      const hiddenStats = parseHiddenStats(query.hide);
+      const scope = parseScope(query.scope);
+      const orgs = parseOrgs(query.orgs);
+      const fields = query.fields
+        ? new Set(
+            query.fields
+              .split(",")
+              .map((v) => v.trim().toLowerCase())
+              .filter(Boolean),
+          )
+        : null;
+      const includeLanguages =
+        !fields || fields.has("all") || fields.has("languages") || fields.has("langs");
+      const data = await getProfileData(username, { includeLanguages, langCount, scope, orgs });
+      const svg = renderUserThemesSvg(data.user, data.stats, data.languages, {
+        compact: query.compact === "true",
+        hide_border: query.hide_border === "true",
+        hide: hiddenStats,
+      });
+      const etag = `W/"${Bun.hash(svg).toString(36)}"`;
+      if (headers["if-none-match"] === etag) {
+        set.status = 304;
+        set.headers["ETag"] = etag;
+        set.headers["Cache-Control"] =
+          "public, max-age=0, s-maxage=1800, stale-while-revalidate=1800";
+        return "";
+      }
+
+      set.headers["Content-Type"] = "image/svg+xml";
+      set.headers["ETag"] = etag;
+      set.headers["Cache-Control"] =
+        "public, max-age=0, s-maxage=1800, stale-while-revalidate=1800";
+      return svg;
+    },
+    {
+      detail: { tags: ["Card"], summary: "Render all built-in themes for a username" },
+      params: t.Object({ username: t.String({ pattern: USERNAME_PATTERN }) }),
+      query: t.Object({
+        compact: t.Optional(t.String()),
+        hide_border: t.Optional(t.String()),
+        fields: t.Optional(t.String()),
+        hide: t.Optional(t.String()),
+        lang_count: t.Optional(t.String()),
+        scope: t.Optional(t.Union([t.Literal("personal"), t.Literal("org"), t.Literal("all")])),
+        orgs: t.Optional(t.String()),
+      }),
+      response: {
+        200: t.String({ description: "SVG markup" }),
+        304: t.String(),
+        401: t.Object({ error: t.String() }),
+        404: t.Object({ error: t.String() }),
+        429: t.Object({ error: t.String() }),
+        500: t.Object({ error: t.String() }),
+        502: t.Object({ error: t.String() }),
+      },
+    },
+  )
+  .get(
+    "/health",
+    async () => {
+      const cache = getCacheMetrics();
+      const redisReachable = await isRedisReachable();
+      return {
+        status: "ok",
+        uptimeSeconds: Math.floor((Date.now() - appStartedAt) / 1000),
+        runtime: "vercel-function",
+        region: Bun.env.VERCEL_REGION || null,
+        cache,
+        redisReachable,
+      };
+    },
+    {
+      detail: { tags: ["Ops"], summary: "Service health and cache telemetry" },
+      response: {
+        200: t.Object({
+          status: t.String(),
+          uptimeSeconds: t.Number(),
+          runtime: t.String(),
+          region: t.Union([t.String(), t.Null()]),
+          cache: t.Object({
+            total: t.Number(),
+            fresh: t.Number(),
+            stale: t.Number(),
+            expired: t.Number(),
+            ttlFreshSeconds: t.Number(),
+            ttlStaleSeconds: t.Number(),
+          }),
+          redisReachable: t.Boolean(),
+        }),
+      },
+    },
+  )
+  .get(
+    "/card/:username",
+    async ({ params: { username }, query, headers, set }) => {
+      const langCount = parseLangCount(query.lang_count);
+      const hiddenStats = parseHiddenStats(query.hide);
+      const scope = parseScope(query.scope);
+      const orgs = parseOrgs(query.orgs);
+      const fields = query.fields
+        ? new Set(
+            query.fields
+              .split(",")
+              .map((v) => v.trim().toLowerCase())
+              .filter(Boolean),
+          )
+        : null;
+      const includeLanguages =
+        !fields || fields.has("all") || fields.has("languages") || fields.has("langs");
+      const data = await getProfileData(username, { includeLanguages, langCount, scope, orgs });
+      const svg = renderCard(data.user, data.stats, data.languages, {
+        theme: query.theme,
+        title_color: query.title_color,
+        text_color: query.text_color,
+        icon_color: query.icon_color,
+        bg_color: query.bg_color,
+        border_color: query.border_color,
+        hide_border: query.hide_border === "true",
+        compact: query.compact === "true",
+        hide: hiddenStats,
+      });
+      const etag = `W/"${Bun.hash(svg).toString(36)}"`;
+      if (headers["if-none-match"] === etag) {
+        set.status = 304;
+        set.headers["ETag"] = etag;
+        set.headers["Cache-Control"] =
+          "public, max-age=0, s-maxage=1800, stale-while-revalidate=1800";
+        return "";
+      }
+
+      set.headers["Content-Type"] = "image/svg+xml";
+      set.headers["ETag"] = etag;
+      set.headers["Cache-Control"] =
+        "public, max-age=0, s-maxage=1800, stale-while-revalidate=1800";
+      return svg;
+    },
+    {
+      detail: { tags: ["Card"], summary: "Render GitHub profile card SVG" },
+      params: t.Object({ username: t.String({ pattern: USERNAME_PATTERN }) }),
+      query: t.Object({
+        theme: t.Optional(t.String()),
+        title_color: t.Optional(t.String()),
+        text_color: t.Optional(t.String()),
+        icon_color: t.Optional(t.String()),
+        bg_color: t.Optional(t.String()),
+        border_color: t.Optional(t.String()),
+        hide_border: t.Optional(t.String()),
+        compact: t.Optional(t.String()),
+        fields: t.Optional(t.String()),
+        hide: t.Optional(t.String()),
+        lang_count: t.Optional(t.String()),
+        scope: t.Optional(t.Union([t.Literal("personal"), t.Literal("org"), t.Literal("all")])),
+        orgs: t.Optional(t.String()),
+      }),
+      response: {
+        200: t.String({ description: "SVG markup" }),
+        304: t.String(),
+        401: t.Object({ error: t.String() }),
+        404: t.Object({ error: t.String() }),
+        429: t.Object({ error: t.String() }),
+        500: t.Object({ error: t.String() }),
+        502: t.Object({ error: t.String() }),
+      },
+    },
+  );
+
+if (import.meta.main) {
+  const port = Number(Bun.env.PORT || 3000);
+  app.listen(port);
+  console.log(`Dev server running on http://localhost:${port}`);
+}
+
+export default app;

package/src/lib.ts

@@ -0,0 +1,21 @@
+/**
+ * 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.
+ */
+
+// Core renderer
+export { renderCard, type CardOpts } from "./card";
+
+// Types
+export type { UserProfile, UserStats, LanguageStat, ProfileData, CardOptions } from "./types";
+
+// Theming
+export { themes, resolveColors, type Theme } from "./utils/themes";
+
+// Utilities
+export { kFormat, escapeXml, wrapText } from "./utils/format";
+export { icons, icon } from "./utils/icons";
+export { getLangColor } from "./utils/languages";
+export { FONT_FACE, FONT_FAMILY } from "./utils/font";

package/src/types.ts

@@ -0,0 +1,40 @@
+export interface UserProfile {
+  login: string;
+  name: string | null;
+  avatarUrl: string;
+  bio: string | null;
+  pronouns: string | null;
+  twitter: string | null;
+}
+
+export interface UserStats {
+  stars: number;
+  repos: number;
+  prs: number;
+  issues: number;
+  commits: number;
+}
+
+export interface LanguageStat {
+  name: string;
+  size: number;
+  color: string;
+}
+
+export interface ProfileData {
+  user: UserProfile;
+  stats: UserStats;
+  languages: LanguageStat[];
+}
+
+export interface CardOptions {
+  theme?: string;
+  title_color?: string;
+  text_color?: string;
+  icon_color?: string;
+  bg_color?: string;
+  border_color?: string;
+  hide_border?: boolean;
+  compact?: boolean;
+  hide?: string[];
+}

package/src/utils/font.ts

@@ -0,0 +1,19 @@
+/**
+ * Roboto variable font embedded as base64 WOFF2 for SVG @font-face.
+ *
+ * The subset (~47KB / ~63KB base64) covers:
+ *   - ASCII printable (U+0020-007E)
+ *   - Latin-1 Supplement (U+00A0-00FF)
+ *   - Common typographic chars (dashes, quotes, ellipsis, bullets)
+ *   - Variable weight axis (400-700)
+ *
+ * Loaded once at startup via Bun.file — zero per-request cost.
+ */
+
+const fontPath = new URL("../../fonts/Roboto-subset.woff2", import.meta.url).pathname;
+const fontBytes = await Bun.file(fontPath).arrayBuffer();
+const fontBase64 = Buffer.from(fontBytes).toString("base64");
+
+export const FONT_FAMILY = "'Roboto', sans-serif";
+
+export const FONT_FACE = `@font-face{font-family:'Roboto';font-style:normal;font-weight:100 900;font-display:swap;src:url(data:font/woff2;base64,${fontBase64}) format('woff2')}`;

package/src/utils/format.ts

@@ -0,0 +1,42 @@
+export function kFormat(num: number): string {
+  if (num >= 1000000) return (num / 1000000).toFixed(1).replace(/\.0$/, "") + "M";
+  if (num >= 1000) return (num / 1000).toFixed(1).replace(/\.0$/, "") + "k";
+  return String(num);
+}
+
+export function escapeXml(str: string): string {
+  return str
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+}
+
+export function wrapText(input: string, maxLen: number, maxLines: number): string[] {
+  const words = input.split(/\s+/).filter(Boolean);
+  const lines: string[] = [];
+  let current = "";
+  for (const w of words) {
+    const next = current ? `${current} ${w}` : w;
+    if (next.length <= maxLen) {
+      current = next;
+      continue;
+    }
+    if (current) lines.push(current);
+    current = w;
+    if (lines.length >= maxLines - 1) break;
+  }
+  if (current && lines.length < maxLines) lines.push(current);
+  if (lines.length === 0 && input) lines.push(input.slice(0, maxLen));
+  if (lines.length === maxLines && words.length > 0) {
+    const last = lines[lines.length - 1];
+    if (!last) return lines;
+    if (last.length > maxLen) {
+      lines[lines.length - 1] = last.slice(0, Math.max(0, maxLen - 1)) + "…";
+    } else if (words.join(" ").length > lines.join(" ").length) {
+      lines[lines.length - 1] = last.slice(0, Math.max(0, maxLen - 1)) + "…";
+    }
+  }
+  return lines;
+}

package/src/utils/icons.ts

@@ -0,0 +1,17 @@
+export const icons = {
+  star: `<path fill-rule="evenodd" d="M8 .25a.75.75 0 01.673.418l1.882 3.815 4.21.612a.75.75 0 01.416 1.279l-3.046 2.97.719 4.192a.75.75 0 01-1.088.791L8 12.347l-3.766 1.98a.75.75 0 01-1.088-.79l.72-4.194L.818 6.374a.75.75 0 01.416-1.28l4.21-.611L7.327.668A.75.75 0 018 .25zm0 2.445L6.615 5.5a.75.75 0 01-.564.41l-3.097.45 2.24 2.184a.75.75 0 01.216.664l-.528 3.084 2.769-1.456a.75.75 0 01.698 0l2.77 1.456-.53-3.084a.75.75 0 01.216-.664l2.24-2.183-3.096-.45a.75.75 0 01-.564-.41L8 2.694v.001z"/>`,
+  commit: `<path fill-rule="evenodd" d="M10.5 7.75a2.5 2.5 0 11-5 0 2.5 2.5 0 015 0zm1.43.75a4.002 4.002 0 01-7.86 0H.75a.75.75 0 110-1.5h3.32a4.001 4.001 0 017.86 0h3.32a.75.75 0 110 1.5h-3.32z"/>`,
+  pr: `<path fill-rule="evenodd" d="M7.177 3.073L9.573.677A.25.25 0 0110 .854v4.792a.25.25 0 01-.427.177L7.177 3.427a.25.25 0 010-.354zM3.75 2.5a.75.75 0 100 1.5.75.75 0 000-1.5zm-2.25.75a2.25 2.25 0 113 2.122v5.256a2.251 2.251 0 11-1.5 0V5.372A2.25 2.25 0 011.5 3.25zM11 2.5h-1V4h1a1 1 0 011 1v5.628a2.251 2.251 0 101.5 0V5A2.5 2.5 0 0011 2.5zm1 10.25a.75.75 0 111.5 0 .75.75 0 01-1.5 0zM3.75 12a.75.75 0 100 1.5.75.75 0 000-1.5z"/>`,
+  issue: `<path fill-rule="evenodd" d="M8 1.5a6.5 6.5 0 100 13 6.5 6.5 0 000-13zM0 8a8 8 0 1116 0A8 8 0 010 8zm9 3a1 1 0 11-2 0 1 1 0 012 0zm-.25-6.25a.75.75 0 00-1.5 0v3.5a.75.75 0 001.5 0v-3.5z"/>`,
+  repo: `<path fill-rule="evenodd" d="M5 3.25a.75.75 0 11-1.5 0 .75.75 0 011.5 0zm0 2.122a2.25 2.25 0 10-1.5 0v.878A2.25 2.25 0 005.75 8.5h1.5v2.128a2.251 2.251 0 101.5 0V8.5h1.5a2.25 2.25 0 002.25-2.25v-.878a2.25 2.25 0 10-1.5 0v.878a.75.75 0 01-.75.75h-4.5A.75.75 0 015 6.25v-.878zm3.75 7.378a.75.75 0 11-1.5 0 .75.75 0 011.5 0zm3-8.75a.75.75 0 100-1.5.75.75 0 000 1.5z"></path>`,
+  x: `<path d="M4 4l11.733 16h4.267l-11.733 -16l-4.267 0" /><path d="M4 20l6.768 -6.768m2.46 -2.46l6.772 -6.772" />`,
+};
+
+export function icon(name: keyof typeof icons, color: string, size = 16): string {
+  const path = icons[name];
+  if (!path) return "";
+  const viewBox = name === "x" ? "0 0 24 24" : "0 0 16 16";
+  const fill =
+    name === "x" ? `stroke="#${color}" stroke-width="2" fill="none"` : `fill="#${color}"`;
+  return `<svg width="${size}" height="${size}" viewBox="${viewBox}" ${fill} role="img">${path}</svg>`;
+}

package/src/utils/index.ts

@@ -0,0 +1,5 @@
+export { resolveColors, themes, type Theme } from "./themes";
+export { kFormat, escapeXml, wrapText } from "./format";
+export { getLangColor } from "./languages";
+export { icons, icon } from "./icons";
+export { FONT_FACE, FONT_FAMILY } from "./font";