@shiinasaku/github-card 2.0.0 → 4.1.0

package/src/index.ts

@@ -1,7 +1,7 @@
 import { Elysia, t } from "elysia";
-import { cors } from "@elysiajs/cors";
-import { openapi } from "@elysiajs/openapi";
-import { serverTiming } from "@elysiajs/server-timing";
+import { cors } from "@elysia/cors";
+import { openapi } from "@elysia/openapi";
+import { serverTiming } from "@elysia/server-timing";
 import {
   AuthError,
   getCacheMetrics,
@@ -11,48 +11,110 @@ import {
   RateLimitError,
   UpstreamError,
 } from "./github";
-import { renderCard } from "./card";
+import { renderCard, type CardOpts } from "./card";
 import { themes } from "./utils";
 
 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 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));
+const CardQuerySchema = 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.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())),
+  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())),
+});
+
+type CardQuery = typeof CardQuerySchema.static;
+type MutableSet = {
+  status?: number | string;
+  headers: Record<string, string | undefined>;
+};
+
+function normalizeList(values?: string[]): string[] {
+  if (!values?.length) return [];
+  return values.map((value) => value.trim()).filter(Boolean);
 }
 
-function parseHiddenStats(value?: string): string[] {
-  if (!value) return [];
+function parseHiddenStats(values?: string[]): string[] {
   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)),
+      normalizeList(values)
+        .map((value) => value.toLowerCase())
+        .filter((value) => allowed.has(value)),
     ),
   );
 }
 
 function parseScope(value?: string): "personal" | "org" | "all" {
-  const normalized = value?.trim().toLowerCase();
-  if (normalized === "org" || normalized === "all") return normalized;
+  if (value === "org" || value === "all") return value;
   return "personal";
 }
 
-function parseOrgs(value?: string): string[] {
-  if (!value) return [];
-  return Array.from(
-    new Set(
-      value
-        .split(",")
-        .map((v) => v.trim())
-        .filter(Boolean),
-    ),
-  );
+function parseOrgs(values?: string[]): string[] {
+  return Array.from(new Set(normalizeList(values).map((value) => value.toLowerCase())));
+}
+
+function parseFieldSet(values?: string[]): Set<string> | null {
+  const list = normalizeList(values).map((value) => value.toLowerCase());
+  return list.length ? new Set(list) : null;
+}
+
+function shouldIncludeLanguages(fields: Set<string> | null): boolean {
+  if (!fields) return true;
+  return fields.has("all") || fields.has("languages") || fields.has("langs");
+}
+
+function buildCardOptions(query: CardQuery, hide: string[]): CardOpts {
+  return {
+    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 ?? false,
+    compact: query.compact ?? false,
+    hide,
+    hide_langs: query.hide_langs,
+    show_langs: query.show_langs,
+    animate: query.animate ?? false,
+  };
+}
+
+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,
+  });
+
+  return renderCard(data.user, data.stats, data.languages, buildCardOptions(query, hiddenStats));
 }
 
 function renderUserThemesSvg(
@@ -77,14 +139,14 @@ function renderUserThemesSvg(
       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");
+      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 `<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>`;
+      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("");
 
@@ -94,6 +156,27 @@ function renderUserThemesSvg(
 </svg>`;
 }
 
+function applyCacheHeaders(set: MutableSet) {
+  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 {
+  const etag = `W/"${Bun.hash(svg).toString(36)}"`;
+  if (ifNoneMatch === etag) {
+    set.status = 304;
+    set.headers.ETag = etag;
+    applyCacheHeaders(set);
+    return "";
+  }
+
+  set.headers["Content-Type"] = "image/svg+xml";
+  set.headers.ETag = etag;
+  applyCacheHeaders(set);
+  return svg;
+}
+
 const app = new Elysia({ name: "github-card" })
   .error({
     NOT_FOUND_ERROR: NotFoundError,
@@ -132,11 +215,12 @@ const app = new Elysia({ name: "github-card" })
       documentation: {
         info: {
           title: "GitHub Profile Card API",
-          version: "1.3.0",
-          description: "Generate GitHub profile SVG cards for README and web embeds.",
+          version: "4.0.0",
+          description:
+            "Generate GitHub profile SVG/PNG cards for README, web embeds, and social previews.",
         },
         tags: [
-          { name: "Card", description: "SVG card endpoints" },
+          { name: "Card", description: "Card endpoints" },
           { name: "Meta", description: "Service metadata" },
           { name: "Ops", description: "Operational endpoints" },
         ],
@@ -169,8 +253,9 @@ const app = new Elysia({ name: "github-card" })
     () => ({
       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",
+      themes: Object.keys(themes).join(", "),
+      affiliations: "affiliated (default), owner",
+      organizationSupport: "Use /card/:organization-login",
     }),
     {
       detail: { tags: ["Meta"], summary: "API metadata" },
@@ -179,53 +264,32 @@ const app = new Elysia({ name: "github-card" })
   .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 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: query.compact === "true",
-        hide_border: query.hide_border === "true",
-        hide: hiddenStats,
+        compact: q.compact ?? false,
+        hide_border: q.hide_border ?? false,
+        hide: parseHiddenStats(q.hide),
+        animate: q.animate ?? false,
       });
-      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;
+      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 }) }),
-      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()),
-      }),
+      query: CardQuerySchema,
       response: {
         200: t.String({ description: "SVG markup" }),
         304: t.String(),
@@ -261,6 +325,7 @@ const app = new Elysia({ name: "github-card" })
           region: t.Union([t.String(), t.Null()]),
           cache: t.Object({
             total: t.Number(),
+            maxEntries: t.Number(),
             fresh: t.Number(),
             stale: t.Number(),
             expired: t.Number(),
@@ -275,65 +340,13 @@ const app = new Elysia({ name: "github-card" })
   .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;
+      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 }) }),
-      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()),
-      }),
+      query: CardQuerySchema,
       response: {
         200: t.String({ description: "SVG markup" }),
         304: t.String(),

package/src/input.css

@@ -0,0 +1 @@
+@import "tailwindcss";