feat: handle GitHub API rate limits gracefully

When the GitHub API returns 403/429 (rate limited), the app now:
1. Falls back to stale cached data if available
2. Returns a friendly 429 response with Retry-After header when
   no cached data exists

Adds RateLimitError class and stale cache lookup helper.

Closes #32

Author: Ai-chan-0411

app/api/compare/route.ts

@@ -1,5 +1,5 @@
 import { NextResponse } from "next/server";
-import { fetchGitHubUserData } from "../../../lib/github";
+import { fetchGitHubUserData, RateLimitError } from "../../../lib/github";
 import { calculateUserScore } from "../../../lib/score";
 
 export const runtime = "nodejs";
@@ -39,6 +39,21 @@ export async function GET(request: Request) {
     );
   } catch (error: any) {
     console.error("GitHub score error:", error);
+
+    if (error instanceof RateLimitError) {
+      return NextResponse.json(
+        {
+          success: false,
+          error: "GitHub API rate limit exceeded. Please try again later.",
+          retryAfter: error.retryAfter,
+        },
+        {
+          status: 429,
+          headers: { "Retry-After": String(error.retryAfter) },
+        }
+      );
+    }
+
     const message =
       error?.message === "User not found"
         ? "GitHub user not found"

lib/cache.ts

@@ -17,6 +17,12 @@ export function getCached<T>(key: string): T | undefined {
   return entry.data as T;
 }
 
+export function getStale<T>(key: string): T | undefined {
+  const entry = store.get(key);
+  if (!entry) return undefined;
+  return entry.data as T;
+}
+
 export function setCached<T>(key: string, data: T, ttlMs = DEFAULT_TTL_MS) {
   store.set(key, { data, expiresAt: Date.now() + ttlMs });
 }

lib/github.ts

@@ -1,6 +1,6 @@
 import { ContributionTotals, GitHubUserData, PullRequestNode, RepoNode } from "@/types/github";
 import { graphql } from "@octokit/graphql";
-import { getCached, setCached } from "./cache";
+import { getCached, getStale, setCached } from "./cache";
 
 if (!process.env.GITHUB_TOKEN) {
   throw new Error("Missing GITHUB_TOKEN");
@@ -58,25 +58,53 @@ const QUERY = /* GraphQL */ `
   }
 `;
 
+export class RateLimitError extends Error {
+  retryAfter: number;
+  constructor(retryAfter: number) {
+    super("GitHub API rate limit exceeded");
+    this.name = "RateLimitError";
+    this.retryAfter = retryAfter;
+  }
+}
+
+function isRateLimitError(error: any): boolean {
+  const status = error?.status ?? error?.response?.status;
+  return status === 403 || status === 429;
+}
+
 export async function fetchGitHubUserData(
   username: string
 ): Promise<GitHubUserData> {
   const cacheKey = `github:${username.toLowerCase()}`;
   const cached = getCached<GitHubUserData>(cacheKey);
   if (cached) return cached;
 
-  const { user } = await client<{ user: any }>(QUERY, { login: username });
+  try {
+    const { user } = await client<{ user: any }>(QUERY, { login: username });
 
-  if (!user) {
-    throw new Error("User not found");
-  }
+    if (!user) {
+      throw new Error("User not found");
+    }
+
+    const data: GitHubUserData = {
+      repos: user.repositories.nodes as RepoNode[],
+      pullRequests: user.pullRequests.nodes as PullRequestNode[],
+      contributions: user.contributionsCollection as ContributionTotals,
+    };
 
-  const data: GitHubUserData = {
-    repos: user.repositories.nodes as RepoNode[],
-    pullRequests: user.pullRequests.nodes as PullRequestNode[],
-    contributions: user.contributionsCollection as ContributionTotals,
-  };
+    setCached(cacheKey, data);
+    return data;
+  } catch (error: any) {
+    if (isRateLimitError(error)) {
+      const stale = getStale<GitHubUserData>(cacheKey);
+      if (stale) return stale;
 
-  setCached(cacheKey, data);
-  return data;
+      const resetAt = error.response?.headers?.["x-ratelimit-reset"];
+      const retryAfter = resetAt
+        ? Math.max(0, Number(resetAt) - Math.floor(Date.now() / 1000))
+        : 60;
+      throw new RateLimitError(retryAfter);
+    }
+    throw error;
+  }
 }