@shiinasaku/github-card 4.2.0 → 5.0.0

package/src/github.ts

@@ -17,12 +17,12 @@ const githubClient = new GitHubClient({
 
 const CACHE_FRESH_MS = 30 * 60 * 1000;
 const CACHE_STALE_MS = 30 * 60 * 1000;
-const CACHE_VERSION = 8;
+const CACHE_VERSION = 9;
 const REDIS_TTL_SECONDS = Math.ceil((CACHE_FRESH_MS + CACHE_STALE_MS) / 1000);
 const FETCH_TIMEOUT_MS = 6000;
 const AVATAR_TIMEOUT_MS = 4000;
 const MAX_AVATAR_BYTES = 256 * 1024;
-const MAX_PAGES = 5;
+const MAX_PAGES = 100;
 const REPO_PAGE_SIZE = 100;
 const MAX_L1_ENTRIES = 1000;
 const REDIS_PROFILE_PREFIX = "profile:";
@@ -58,7 +58,7 @@ const refreshInFlight = new Set<string>();
 
 function evictL1IfNeeded() {
   if (memCache.size <= MAX_L1_ENTRIES) return;
-  const oldestKey = memCache.keys().next().value as string | undefined;
+  const oldestKey = memCache.keys().next().value;
   if (oldestKey) memCache.delete(oldestKey);
 }
 
@@ -133,12 +133,16 @@ function normalizeUsername(username: string): string {
 }
 
 function normalizeOrgFilters(orgs?: string[]): string[] {
-  return Array.from(new Set((orgs || []).map((o) => o.trim().toLowerCase()).filter(Boolean)));
+  return Array.from(
+    new Set((orgs || []).map((o) => o.trim().toLowerCase()).filter(Boolean)),
+  ).sort();
 }
 
 type FetchOptions = {
   includeLanguages?: boolean;
   langCount?: number;
+  hideLangs?: string[];
+  showLangs?: string[];
   scope?: "personal" | "org" | "all";
   orgs?: string[];
   affiliations?: "owner" | "affiliated";
@@ -147,6 +151,7 @@ type FetchOptions = {
 
 type RepoNode = {
   nameWithOwner: string;
+  isFork?: boolean;
   stargazers: { totalCount: number };
   owner?: { login: string; __typename: string } | null;
   languages?: { edges: LangEdge[] | null } | null;
@@ -224,9 +229,9 @@ query paginateRepos($login: String!, $cursor: String, $pageSize: Int!, $affiliat
 const QUERY_PAGINATE_ORG_CONTRIBS = `
 query paginateOrgContribs($login: String!, $cursor: String, $pageSize: Int!, $fetchLangs: Boolean!) {
   user(login: $login) {
-    repositoriesContributedTo(first: $pageSize, contributionTypes: [COMMIT, PULL_REQUEST, REPOSITORY], includeUserRepositories: false, after: $cursor) {
+    repositoriesContributedTo(first: $pageSize, contributionTypes: [COMMIT, ISSUE, PULL_REQUEST, REPOSITORY], includeUserRepositories: false, after: $cursor) {
       pageInfo { hasNextPage endCursor }
-      nodes { nameWithOwner owner { login __typename } stargazers { totalCount } languages(first: 10, orderBy: {field: SIZE, direction: DESC}) @include(if: $fetchLangs) { edges { size node { color name } } } }
+      nodes { nameWithOwner isFork owner { login __typename } stargazers { totalCount } languages(first: 10, orderBy: {field: SIZE, direction: DESC}) @include(if: $fetchLangs) { edges { size node { color name } } } }
     }
   }
 }
@@ -304,12 +309,13 @@ function sumContributions(
   return total;
 }
 
-async function directFetch(username: string, opts: FetchOptions): Promise<ProfileData> {
+type EffectiveFetchOptions = Required<FetchOptions>;
+
+async function directFetch(username: string, opts: EffectiveFetchOptions): Promise<ProfileData> {
   const isPersonal = opts.scope !== "org";
   const isOrg = opts.scope === "org" || opts.scope === "all";
-  const fetchLangs = opts.includeLanguages ?? true;
-  const orgsArr = normalizeOrgFilters(opts.orgs);
-  const orgsSet = orgsArr.length > 0 ? new Set(orgsArr) : null;
+  const fetchLangs = opts.includeLanguages;
+  const orgsSet = opts.orgs.length > 0 ? new Set(opts.orgs) : null;
   const affiliations =
     opts.affiliations === "owner" ? ["OWNER"] : ["OWNER", "ORGANIZATION_MEMBER", "COLLABORATOR"];
 
@@ -324,7 +330,7 @@ async function directFetch(username: string, opts: FetchOptions): Promise<Profil
       login: username,
       from,
       to,
-      isOrg,
+      isOrg: opts.scope === "org",
     });
     user = data.user;
     if (!user) throw new NotFoundError();
@@ -345,14 +351,12 @@ async function directFetch(username: string, opts: FetchOptions): Promise<Profil
   let reposCount = 0;
 
   const processNode = (node: RepoNode, scopeCheck: boolean): void => {
-    if (!node?.nameWithOwner || seenRepos.has(node.nameWithOwner)) return;
-    if (
-      scopeCheck &&
-      node.owner?.__typename === "Organization" &&
-      orgsSet &&
-      !orgsSet.has(node.owner.login.toLowerCase())
-    )
-      return;
+    if (!node?.nameWithOwner || node.isFork || seenRepos.has(node.nameWithOwner)) return;
+    if (scopeCheck) {
+      const owner = node.owner;
+      if (owner?.__typename !== "Organization" || !owner.login) return;
+      if (orgsSet && !orgsSet.has(owner.login.toLowerCase())) return;
+    }
     seenRepos.add(node.nameWithOwner);
     stars += node.stargazers?.totalCount ?? 0;
     reposCount++;
@@ -373,10 +377,9 @@ async function directFetch(username: string, opts: FetchOptions): Promise<Profil
 
   const traversePages = async (query: string, scopeCheck: boolean): Promise<void> => {
     let cursor: string | null = null;
-    let page = 0;
-    let hasNext = true;
+    const seenCursors = new Set<string>();
 
-    while (hasNext && page++ < MAX_PAGES) {
+    for (let page = 0; page < MAX_PAGES; page++) {
       const data = await postGraphQL<PaginateData>(query, {
         login: username,
         cursor,
@@ -385,11 +388,23 @@ async function directFetch(username: string, opts: FetchOptions): Promise<Profil
         affiliations,
       });
       const nextConn = getConnection(data, query);
-      for (const node of nextConn?.nodes ?? []) processNode(node, scopeCheck);
-      hasNext = nextConn?.pageInfo?.hasNextPage ?? false;
-      cursor = nextConn?.pageInfo?.endCursor ?? null;
-      if (hasNext && !cursor) break;
+      if (
+        !nextConn ||
+        !Array.isArray(nextConn.nodes) ||
+        typeof nextConn.pageInfo?.hasNextPage !== "boolean"
+      ) {
+        throw new UpstreamError("GitHub repository pagination connection is missing or invalid");
+      }
+      for (const node of nextConn.nodes) processNode(node, scopeCheck);
+      if (!nextConn.pageInfo.hasNextPage) return;
+      const nextCursor = nextConn.pageInfo.endCursor;
+      if (typeof nextCursor !== "string" || !nextCursor.trim() || seenCursors.has(nextCursor)) {
+        throw new UpstreamError("GitHub repository pagination cursor is missing or invalid");
+      }
+      seenCursors.add(nextCursor);
+      cursor = nextCursor;
     }
+    throw new UpstreamError(`GitHub repository pagination exceeded ${MAX_PAGES} pages`);
   };
 
   const tasks: Promise<void>[] = [];
@@ -402,9 +417,9 @@ async function directFetch(username: string, opts: FetchOptions): Promise<Profil
 
   const [avatarDataUrl] = await Promise.all([fetchAvatarAsBase64(user.avatarUrl), ...tasks]);
 
-  let commits = 0;
-  let prs = 0;
-  let issues = 0;
+  let commits: number | null = null;
+  let prs: number | null = null;
+  let issues: number | null = null;
 
   if (!isOrgAccount) {
     const profile = user as ProfileUser;
@@ -423,22 +438,30 @@ async function directFetch(username: string, opts: FetchOptions): Promise<Profil
     }
   }
 
+  const hiddenLanguages = new Set(opts.hideLangs);
+  const shownLanguages = new Set(opts.showLangs);
   const languages = Array.from(langMap.entries())
+    .filter(([name]) => {
+      const normalized = name.trim().toLowerCase();
+      return (
+        !hiddenLanguages.has(normalized) && (!shownLanguages.size || shownLanguages.has(normalized))
+      );
+    })
     .map(([name, { size, color }]) => ({ name, size, color }))
     .sort((a, b) => b.size - a.size)
-    .slice(0, opts.langCount || 5);
+    .slice(0, opts.langCount);
 
   const profileUser = !isOrgAccount ? (user as ProfileUser) : null;
   const orgUser = isOrgAccount ? (user as OrgProfile) : null;
 
   return {
     user: {
-      login: user!.login,
-      name: user!.name,
+      login: user.login,
+      name: user.name,
       avatarUrl: avatarDataUrl,
       bio: isOrgAccount ? (orgUser?.description ?? null) : (profileUser?.bio ?? null),
       pronouns: isOrgAccount ? null : (profileUser?.pronouns ?? null),
-      twitter: user!.twitterUsername ?? null,
+      twitter: user.twitterUsername ?? null,
     },
     stats: { stars, repos: reposCount, prs, issues, commits },
     languages,
@@ -449,18 +472,39 @@ export async function getProfileData(
   username: string,
   opts: FetchOptions = {},
 ): Promise<ProfileData> {
-  const norm = normalizeUsername(username);
-  const orgs = normalizeOrgFilters(opts.orgs);
+  username = normalizeUsername(username);
+  const effectiveOpts: EffectiveFetchOptions = {
+    scope: opts.scope ?? "personal",
+    affiliations: opts.affiliations ?? "owner",
+    includeLanguages: opts.includeLanguages ?? true,
+    langCount: Number.isFinite(opts.langCount)
+      ? Math.max(1, Math.min(10, Math.floor(opts.langCount!)))
+      : 5,
+    hideLangs: normalizeOrgFilters(opts.hideLangs),
+    showLangs: normalizeOrgFilters(opts.showLangs),
+    orgs: normalizeOrgFilters(opts.orgs),
+    forceRefresh: opts.forceRefresh ?? false,
+  };
   const cacheKey = Bun.hash(
-    `v${CACHE_VERSION}:${norm}:${opts.scope || "personal"}:${opts.affiliations || "owner"}:${opts.includeLanguages !== false}:${opts.langCount || 5}:${orgs.join("|")}`,
+    JSON.stringify([
+      CACHE_VERSION,
+      username,
+      effectiveOpts.scope,
+      effectiveOpts.affiliations,
+      effectiveOpts.includeLanguages,
+      effectiveOpts.langCount,
+      effectiveOpts.orgs,
+      effectiveOpts.hideLangs,
+      effectiveOpts.showLangs,
+    ]),
   ).toString(36);
 
-  if (!opts.forceRefresh) {
+  if (!effectiveOpts.forceRefresh) {
     const mem = memCache.get(cacheKey);
     const now = Date.now();
     if (mem && mem.expiresAt > now) {
       if (mem.staleAt <= now && !refreshInFlight.has(cacheKey))
-        triggerBackgroundRefresh(username, opts, cacheKey);
+        triggerBackgroundRefresh(username, effectiveOpts, cacheKey);
       return mem.data;
     }
 
@@ -468,14 +512,14 @@ export async function getProfileData(
     if (cached) {
       setMemoryCache(cacheKey, cached);
       if (cached.staleAt <= now && !refreshInFlight.has(cacheKey))
-        triggerBackgroundRefresh(username, opts, cacheKey);
+        triggerBackgroundRefresh(username, effectiveOpts, cacheKey);
       return cached.data;
     }
   }
 
   if (inFlight.has(cacheKey)) return inFlight.get(cacheKey)!;
 
-  const promise = directFetch(username, opts)
+  const promise = directFetch(username, effectiveOpts)
     .then((data) => saveProfileCache(cacheKey, data))
     .finally(() => {
       inFlight.delete(cacheKey);
@@ -485,11 +529,11 @@ export async function getProfileData(
   return promise;
 }
 
-function triggerBackgroundRefresh(username: string, opts: FetchOptions, cacheKey: string) {
+function triggerBackgroundRefresh(username: string, opts: EffectiveFetchOptions, cacheKey: string) {
   if (refreshInFlight.has(cacheKey)) return;
   refreshInFlight.add(cacheKey);
 
-  void directFetch(username, { ...opts, forceRefresh: true })
+  void directFetch(username, opts)
     .then((data) => saveProfileCache(cacheKey, data))
     .catch(() => {})
     .finally(() => {

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,6 +13,8 @@ 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";
@@ -30,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);
@@ -62,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())));
 }
@@ -98,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 ?? DEFAULT_AFFILIATIONS) as "owner" | "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\b/,
-        `<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;
@@ -178,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,
@@ -216,9 +166,9 @@ const app = new Elysia({ name: "github-card" })
       documentation: {
         info: {
           title: "GitHub Profile Card API",
-          version: "4.2.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" },
@@ -231,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: {
@@ -248,9 +192,18 @@ 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",
@@ -258,64 +211,29 @@ const app = new Elysia({ name: "github-card" })
       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 ?? DEFAULT_AFFILIATIONS) as "owner" | "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: {
@@ -337,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/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;
 }