@shiinasaku/github-card 4.1.0 → 5.0.0

package/src/index.ts

@@ -1,4 +1,4 @@
-import { Elysia, t } from "elysia";
+import { Elysia, t, type Context, type UnwrapSchema } from "elysia";
 import { cors } from "@elysia/cors";
 import { openapi } from "@elysia/openapi";
 import { serverTiming } from "@elysia/server-timing";
@@ -13,10 +13,13 @@ import {
 } from "./github";
 import { renderCard, type CardOpts } from "./card";
 import { themes } from "./utils";
+import { renderThemeGallery } from "./gallery";
+import { version } from "../package.json";
 
 const USERNAME_PATTERN = "^[a-zA-Z0-9-]{1,39}$";
 const CACHE_CONTROL_HEADER = "public, max-age=0, s-maxage=1800, stale-while-revalidate=1800";
 const EDGE_CACHE_CONTROL_HEADER = "public, s-maxage=1800, stale-while-revalidate=1800";
+const DEFAULT_AFFILIATIONS = "owner" as const;
 const appStartedAt = Date.now();
 
 const CardQuerySchema = t.Object({
@@ -29,22 +32,30 @@ const CardQuerySchema = t.Object({
   hide_border: t.Optional(t.BooleanString()),
   compact: t.Optional(t.BooleanString()),
   animate: t.Optional(t.BooleanString()),
-  fields: t.Optional(t.ArrayQuery(t.String())),
-  hide: t.Optional(t.ArrayQuery(t.String())),
-  hide_langs: t.Optional(t.ArrayQuery(t.String())),
-  show_langs: t.Optional(t.ArrayQuery(t.String())),
+  fields: t.Optional(t.Array(t.String())),
+  hide: t.Optional(t.Array(t.String())),
+  hide_langs: t.Optional(t.Array(t.String())),
+  show_langs: t.Optional(t.Array(t.String())),
   lang_count: t.Optional(t.Integer({ minimum: 1, maximum: 10 })),
   scope: t.Optional(t.Union([t.Literal("personal"), t.Literal("org"), t.Literal("all")])),
   affiliations: t.Optional(t.Union([t.Literal("owner"), t.Literal("affiliated")])),
-  orgs: t.Optional(t.ArrayQuery(t.String())),
+  orgs: t.Optional(t.Array(t.String())),
 });
 
-type CardQuery = typeof CardQuerySchema.static;
-type MutableSet = {
-  status?: number | string;
-  headers: Record<string, string | undefined>;
+const CardParamsSchema = t.Object({ username: t.String({ pattern: USERNAME_PATTERN }) });
+const ErrorSchema = t.Object({ error: t.String() });
+const CardResponseSchema = {
+  200: t.String({ description: "SVG markup" }),
+  304: t.String(),
+  401: ErrorSchema,
+  404: ErrorSchema,
+  429: ErrorSchema,
+  502: ErrorSchema,
 };
 
+type CardQuery = UnwrapSchema<typeof CardQuerySchema>;
+type ResponseSet = Context["set"];
+
 function normalizeList(values?: string[]): string[] {
   if (!values?.length) return [];
   return values.map((value) => value.trim()).filter(Boolean);
@@ -61,11 +72,6 @@ function parseHiddenStats(values?: string[]): string[] {
   );
 }
 
-function parseScope(value?: string): "personal" | "org" | "all" {
-  if (value === "org" || value === "all") return value;
-  return "personal";
-}
-
 function parseOrgs(values?: string[]): string[] {
   return Array.from(new Set(normalizeList(values).map((value) => value.toLowerCase())));
 }
@@ -97,72 +103,35 @@ function buildCardOptions(query: CardQuery, hide: string[]): CardOpts {
   };
 }
 
-async function buildCardSvg(username: string, query: CardQuery): Promise<string> {
-  const langCount = query.lang_count ?? 5;
-  const hiddenStats = parseHiddenStats(query.hide);
-  const scope = parseScope(query.scope);
-  const orgs = parseOrgs(query.orgs);
-  const fields = parseFieldSet(query.fields);
-  const includeLanguages = shouldIncludeLanguages(fields);
-  const affiliations = query.affiliations ?? "affiliated";
-
-  const data = await getProfileData(username, {
-    includeLanguages,
-    langCount,
-    scope,
-    affiliations,
-    orgs,
+function fetchProfile(username: string, query: CardQuery) {
+  return getProfileData(username, {
+    includeLanguages: shouldIncludeLanguages(parseFieldSet(query.fields)),
+    langCount: query.lang_count ?? 5,
+    hideLangs: query.hide_langs,
+    showLangs: query.show_langs,
+    scope: query.scope ?? "personal",
+    affiliations: query.affiliations ?? DEFAULT_AFFILIATIONS,
+    orgs: parseOrgs(query.orgs),
   });
-
-  return renderCard(data.user, data.stats, data.languages, buildCardOptions(query, hiddenStats));
 }
 
-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) + labelH;
-      // Inline the card as a nested <svg> element (GitHub camo-safe, unlike data-URI <image>)
-      const cardSvg = renderCard(user, stats, langs, { ...cardOpts, theme: name }).replace(
-        "<svg ",
-        `<svg x="${x}" y="${y}" `,
-      );
-
-      return `<text x="${x + 4}" y="${y - 8}" fill="#e2e8f0" font-size="13" font-family="Inter,ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,Arial" font-weight="700">${name}</text>${cardSvg}`;
-    })
-    .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>`;
+async function buildCardSvg(username: string, query: CardQuery): Promise<string> {
+  const data = await fetchProfile(username, query);
+  return renderCard(
+    data.user,
+    data.stats,
+    data.languages,
+    buildCardOptions(query, parseHiddenStats(query.hide)),
+  );
 }
 
-function applyCacheHeaders(set: MutableSet) {
+function applyCacheHeaders(set: ResponseSet) {
   set.headers["Cache-Control"] = CACHE_CONTROL_HEADER;
   set.headers["CDN-Cache-Control"] = EDGE_CACHE_CONTROL_HEADER;
   set.headers["Vercel-CDN-Cache-Control"] = EDGE_CACHE_CONTROL_HEADER;
 }
 
-function setSvgHeaders(svg: string, ifNoneMatch: string | undefined, set: MutableSet): string {
+function setSvgHeaders(svg: string, ifNoneMatch: string | undefined, set: ResponseSet): string {
   const etag = `W/"${Bun.hash(svg).toString(36)}"`;
   if (ifNoneMatch === etag) {
     set.status = 304;
@@ -177,29 +146,11 @@ function setSvgHeaders(svg: string, ifNoneMatch: string | undefined, set: Mutabl
   return 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 };
-    }
-  })
+export const app = new Elysia({ name: "github-card" })
+  .onError(NotFoundError, ({ error, status }) => status(404, { error: error.message }))
+  .onError(RateLimitError, ({ error, status }) => status(429, { error: error.message }))
+  .onError(AuthError, ({ error, status }) => status(401, { error: error.message }))
+  .onError(UpstreamError, ({ error, status }) => status(502, { error: error.message }))
   .use(
     cors({
       origin: true,
@@ -215,9 +166,9 @@ const app = new Elysia({ name: "github-card" })
       documentation: {
         info: {
           title: "GitHub Profile Card API",
-          version: "4.0.0",
+          version,
           description:
-            "Generate GitHub profile SVG/PNG cards for README, web embeds, and social previews.",
+            "Generate GitHub profile SVG cards for README, web embeds, and social previews.",
         },
         tags: [
           { name: "Card", description: "Card endpoints" },
@@ -230,12 +181,6 @@ const app = new Elysia({ name: "github-card" })
   .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: {
@@ -247,74 +192,48 @@ const app = new Elysia({ name: "github-card" })
         }),
       },
     },
+    () => ({
+      message: "GitHub Profile Card API",
+      usage: "GET /card/:username",
+      themes: "GET /:username/themes",
+      docs: "/openapi",
+    }),
   )
   .get(
     "/meta",
+    {
+      detail: { tags: ["Meta"], summary: "API metadata" },
+    },
     () => ({
       message: "GitHub Profile Card API",
       usage: "GET /card/:username",
       themes: Object.keys(themes).join(", "),
-      affiliations: "affiliated (default), owner",
+      affiliations: "owner (default), affiliated",
       organizationSupport: "Use /card/:organization-login",
     }),
-    {
-      detail: { tags: ["Meta"], summary: "API metadata" },
-    },
   )
   .get(
     "/:username/themes",
-    async ({ params: { username }, query, headers, set }) => {
-      const q = query as CardQuery;
-      const scope = parseScope(q.scope);
-      const orgs = parseOrgs(q.orgs);
-      const fields = parseFieldSet(q.fields);
-      const includeLanguages = shouldIncludeLanguages(fields);
-      const data = await getProfileData(username, {
-        includeLanguages,
-        langCount: q.lang_count ?? 5,
-        scope,
-        affiliations: q.affiliations ?? "affiliated",
-        orgs,
-      });
-
-      const svg = renderUserThemesSvg(data.user, data.stats, data.languages, {
-        compact: q.compact ?? false,
-        hide_border: q.hide_border ?? false,
-        hide: parseHiddenStats(q.hide),
-        animate: q.animate ?? false,
-      });
-
-      return setSvgHeaders(svg, headers["if-none-match"], set as MutableSet);
-    },
     {
       detail: { tags: ["Card"], summary: "Render all built-in themes for a username" },
-      params: t.Object({ username: t.String({ pattern: USERNAME_PATTERN }) }),
+      params: CardParamsSchema,
       query: CardQuerySchema,
-      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() }),
-      },
+      response: CardResponseSchema,
+    },
+    async ({ params: { username }, query, headers, set }) => {
+      const data = await fetchProfile(username, query);
+      const svg = renderThemeGallery(
+        data.user,
+        data.stats,
+        data.languages,
+        buildCardOptions(query, parseHiddenStats(query.hide)),
+      );
+
+      return setSvgHeaders(svg, headers["if-none-match"], set);
     },
   )
   .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: {
@@ -336,33 +255,38 @@ const app = new Elysia({ name: "github-card" })
         }),
       },
     },
+    async () => {
+      const cache = getCacheMetrics();
+      const redisReachable = await isRedisReachable();
+      return {
+        status: "ok",
+        uptimeSeconds: Math.floor((Date.now() - appStartedAt) / 1000),
+        runtime: Bun.env.VERCEL ? "vercel-function" : "bun",
+        region: Bun.env.VERCEL_REGION || null,
+        cache,
+        redisReachable,
+      };
+    },
   )
   .get(
     "/card/:username",
-    async ({ params: { username }, query, headers, set }) => {
-      const svg = await buildCardSvg(username, query as CardQuery);
-      return setSvgHeaders(svg, headers["if-none-match"], set as MutableSet);
-    },
     {
       detail: { tags: ["Card"], summary: "Render GitHub profile card SVG" },
-      params: t.Object({ username: t.String({ pattern: USERNAME_PATTERN }) }),
+      params: CardParamsSchema,
       query: CardQuerySchema,
-      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() }),
-      },
+      response: CardResponseSchema,
+    },
+    async ({ params: { username }, query, headers, set }) => {
+      const svg = await buildCardSvg(username, query);
+      return setSvgHeaders(svg, headers["if-none-match"], set);
     },
   );
 
+export type App = typeof app;
+export default app;
+
 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

@@ -15,7 +15,7 @@ export type { UserProfile, UserStats, LanguageStat, ProfileData, CardOptions } f
 export { themes, resolveColors, type Theme } from "./utils/themes";
 
 // Utilities
-export { kFormat, escapeXml, wrapText } from "./utils/format";
+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";

package/src/types.ts

@@ -10,9 +10,10 @@ export interface UserProfile {
 export interface UserStats {
   stars: number;
   repos: number;
-  prs: number;
-  issues: number;
-  commits: number;
+  /** null means unavailable, not zero (for example, organization activity totals). */
+  prs: number | null;
+  issues: number | null;
+  commits: number | null;
 }
 
 export interface LanguageStat {
@@ -37,5 +38,9 @@ export interface CardOptions {
   hide_border?: boolean;
   compact?: boolean;
   hide?: string[];
+  hide_langs?: string[];
+  show_langs?: string[];
   animate?: boolean;
+  /** Stable namespace for multiple cards embedded in the same SVG document. */
+  idPrefix?: string;
 }

package/src/utils/font.ts

@@ -1,3 +1,5 @@
+/** System font stack — no shipped font, respects the user's OS. */
 export const FONT_FAMILY =
-  'ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"';
-export const FONT_FACE = ""; // Kept for API backwards compatibility
+  'ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"';
+/** @deprecated No shipped font — kept for API backwards compatibility. */
+export const FONT_FACE = "";

package/src/utils/format.ts

@@ -1,12 +1,51 @@
 export function kFormat(num: number): string {
+  const sign = num < 0 ? "-" : "";
+  const abs = Math.abs(num);
   const trim = (v: number) => v.toFixed(1).replace(/\.0$/, "");
-  if (num >= 999_950) return trim(num / 1_000_000) + "M";
-  if (num >= 999.95) return trim(num / 1_000) + "k";
-  return String(Math.round(num));
+  if (abs >= 999_950_000) return sign + trim(abs / 1_000_000_000) + "B";
+  if (abs >= 999_950) return sign + trim(abs / 1_000_000) + "M";
+  if (abs >= 999.95) return sign + trim(abs / 1_000) + "k";
+  return sign + String(Math.round(abs));
+}
+
+/**
+ * Approximate rendered width of a string in SVG user units for the default
+ * sans-serif stack. Widths are per-character averages tuned to the card's
+ * font sizes and weights, so layout can reserve enough space without relying
+ * on browser text measurement (which is unavailable server-side).
+ */
+export function measureText(text: string, size: number, weight = 400): number {
+  if (!text) return 0;
+  const factor = size;
+  const weightFactor = weight >= 700 ? 1.08 : weight >= 600 ? 1.04 : 1;
+  let width = 0;
+  for (const ch of text) {
+    const code = ch.codePointAt(0)!;
+    let w: number;
+    if (ch === " ") w = 0.28;
+    else if (ch === "." || ch === "," || ch === ":" || ch === ";") w = 0.3;
+    else if (ch === "i" || ch === "l" || ch === "I" || ch === "t" || ch === "j" || ch === "|")
+      w = 0.3;
+    else if (ch === "m" || ch === "w" || ch === "W" || ch === "M" || ch === "@") w = 0.95;
+    else if (code >= 0x1100 && code <= 0x11ff)
+      w = 1.0; // Hangul
+    else if (code >= 0x4e00 && code <= 0x9fff)
+      w = 1.0; // CJK
+    else if (code >= 0x3040 && code <= 0x30ff)
+      w = 1.0; // Kana
+    else if (code >= 0xac00 && code <= 0xd7af)
+      w = 1.0; // Hangul syllables
+    else if (code > 0x7f)
+      w = 0.72; // other non-ASCII (emoji, accents)
+    else w = 0.58; // default latin
+    width += w;
+  }
+  return width * factor * weightFactor;
 }
 
 export function escapeXml(str: string): string {
   return str
+    .replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\ufffe\uffff\ud800-\udfff]/gu, "")
     .replace(/&/g, "&amp;")
     .replace(/</g, "&lt;")
     .replace(/>/g, "&gt;")
@@ -15,28 +54,29 @@ export function escapeXml(str: string): string {
 }
 
 export function wrapText(input: string, maxLen: number, maxLines: number): string[] {
-  const words = input.split(/\s+/).filter(Boolean);
+  if (maxLen < 1 || maxLines < 1) return [];
+  let remaining = Array.from(input.trim().replace(/\s+/g, " "));
   const lines: string[] = [];
-  let current = "";
 
-  for (const word of words) {
-    const next = current ? `${current} ${word}` : word;
-    if (next.length <= maxLen) {
-      current = next;
-      continue;
+  while (remaining.length && lines.length < maxLines) {
+    if (remaining.length <= maxLen) {
+      lines.push(remaining.join(""));
+      break;
     }
-    if (current) lines.push(current);
-    if (lines.length === maxLines) break;
-    current = word.length > maxLen ? word.slice(0, maxLen) : word;
-  }
-  if (current && lines.length < maxLines) lines.push(current);
-
-  // Truncated? Mark the last line with an ellipsis.
-  const consumed = lines.join(" ").length;
-  if (lines.length > 0 && consumed < input.trim().length) {
-    const last = lines[lines.length - 1]!;
-    lines[lines.length - 1] =
-      (last.length >= maxLen ? last.slice(0, Math.max(0, maxLen - 1)) : last) + "…";
+    if (lines.length === maxLines - 1) {
+      lines.push(
+        remaining
+          .slice(0, maxLen - 1)
+          .join("")
+          .trimEnd() + "…",
+      );
+      break;
+    }
+    const space = remaining.lastIndexOf(" ", maxLen);
+    const end = space > 0 ? space : maxLen;
+    lines.push(remaining.slice(0, end).join(""));
+    remaining = remaining.slice(end);
+    if (remaining[0] === " ") remaining.shift();
   }
   return lines;
 }