feat: add cache-busting queryand X-cache-Status response headers

Author: Vartika-l7

app/api/github/route.ts

@@ -50,10 +50,12 @@ export async function GET(request: Request) {
     );
   }
 
-  const { username, refresh } = parseResult.data;
+  const { username, refresh, bypassCache: bypassCacheParam } = parseResult.data;
+  // Treat either ?refresh=true or ?bypassCache=true as a cache-bypass request
+  const isRefreshRequested = refresh || bypassCacheParam;
 
   // 1. Quota awareness check - if remaining quota is low, disable manual refresh
-  if (refresh && quotaMonitor.isQuotaLow()) {
+  if (isRefreshRequested && quotaMonitor.isQuotaLow()) {
     logSecurityEvent('LOW_QUOTA_REFRESH_BLOCKED', {
       username,
       ip,
@@ -66,7 +68,7 @@ export async function GET(request: Request) {
   }
 
   // 2. Separate Refresh Rate Limiter
-  if (refresh) {
+  if (isRefreshRequested) {
     const rateLimitCheck = refreshRateLimiter.checkLimit(ip);
     if (!rateLimitCheck.success) {
       logSecurityEvent('REFRESH_RATE_LIMIT_EXCEEDED', {
@@ -89,8 +91,8 @@ export async function GET(request: Request) {
   }
 
   // 3. Per-Username Refresh Cooldown
-  let shouldBypassCache = refresh;
-  if (refresh) {
+  let shouldBypassCache = isRefreshRequested;
+  if (isRefreshRequested) {
     if (!refreshPolicy.isRefreshAllowed(username)) {
       logSecurityEvent('REFRESH_COOLDOWN_VIOLATION', {
         username,
@@ -120,13 +122,16 @@ export async function GET(request: Request) {
       ? 'no-cache, no-store, must-revalidate'
       : 's-maxage=3600, stale-while-revalidate=86400';
 
+    const cacheStatus = shouldBypassCache ? 'MISS' : 'HIT';
+
     return NextResponse.json(data, {
       status: 200,
       headers: {
         'Cache-Control': cacheControl,
+        'X-Cache-Status': cacheStatus,
         'X-Refresh-Status': shouldBypassCache
           ? 'Fresh'
-          : refresh
+          : isRefreshRequested
             ? 'Cooldown-Served-Cached'
             : 'Cached',
       },

app/api/og/route.tsx

@@ -49,7 +49,17 @@ export async function GET(req: NextRequest) {
     );
   }
 
-  const { user, theme, bg, text, accent, refresh } = parseResult.data;
+  const {
+    user,
+    theme,
+    bg,
+    text,
+    accent,
+    refresh,
+    bypassCache: bypassCacheParam,
+  } = parseResult.data;
+  // Treat either ?refresh=true or ?bypassCache=true as a cache-bypass request
+  const isRefreshRequested = refresh || bypassCacheParam;
 
   const themeName = theme || 'dark';
   const isAutoTheme = themeName === 'auto';
@@ -83,7 +93,7 @@ export async function GET(req: NextRequest) {
     // bypassCache mirrors the ?refresh=true pattern used by /api/stats and /api/streak.
     // Without this, every link-preview bot crawl fires a fresh GitHub GraphQL request,
     // burning API quota on an endpoint that is embedded in every page's <meta> tag.
-    const data = await fetchGitHubContributions(user, { bypassCache: refresh });
+    const data = await fetchGitHubContributions(user, { bypassCache: isRefreshRequested });
     const stats = calculateStreak(data.calendar ?? data);
     totalCommits = stats.totalContributions;
     longestStreak = stats.longestStreak;
@@ -92,7 +102,7 @@ export async function GET(req: NextRequest) {
     console.error('[OG] stats fetch failed:', err);
   }
 
-  const cacheControl = refresh
+  const cacheControl = isRefreshRequested
     ? 'no-cache, no-store, must-revalidate'
     : 'public, max-age=3600, stale-while-revalidate=86400';
 

app/api/stats/route.ts

@@ -61,7 +61,9 @@ export async function GET(request: Request) {
     );
   }
 
-  const { user, refresh, tz } = parseResult.data;
+  const { user, refresh, bypassCache: bypassCacheParam, tz } = parseResult.data;
+  // Treat either ?refresh=true or ?bypassCache=true as a cache-bypass request
+  const isRefreshRequested = refresh || bypassCacheParam;
 
   let timezone: string;
   try {
@@ -72,7 +74,7 @@ export async function GET(request: Request) {
     return NextResponse.json({ error: `Invalid "tz" parameter: "${tz}"` }, { status: 400 });
   }
 
-  if (refresh && quotaMonitor.isQuotaLow()) {
+  if (isRefreshRequested && quotaMonitor.isQuotaLow()) {
     logSecurityEvent('LOW_QUOTA_STATS_REFRESH_BLOCKED', {
       user,
       ip,
@@ -84,7 +86,7 @@ export async function GET(request: Request) {
     );
   }
 
-  if (refresh) {
+  if (isRefreshRequested) {
     const rateLimitCheck = refreshRateLimiter.checkLimit(ip);
     if (!rateLimitCheck.success) {
       logSecurityEvent('STATS_REFRESH_RATE_LIMIT_EXCEEDED', {
@@ -106,8 +108,8 @@ export async function GET(request: Request) {
     }
   }
 
-  let shouldBypassCache = refresh;
-  if (refresh) {
+  let shouldBypassCache = isRefreshRequested;
+  if (isRefreshRequested) {
     if (!refreshPolicy.isRefreshAllowed(user)) {
       logSecurityEvent('STATS_REFRESH_COOLDOWN_VIOLATION', {
         user,
@@ -134,9 +136,10 @@ export async function GET(request: Request) {
       headers.set('Pragma', 'no-cache');
       headers.set('Expires', '0');
     }
+    headers.set('X-Cache-Status', shouldBypassCache ? 'MISS' : 'HIT');
     headers.set(
       'X-Refresh-Status',
-      shouldBypassCache ? 'Fresh' : refresh ? 'Cooldown-Served-Cached' : 'Cached'
+      shouldBypassCache ? 'Fresh' : isRefreshRequested ? 'Cooldown-Served-Cached' : 'Cached'
     );
 
     return NextResponse.json(

app/api/streak/route.ts

@@ -75,6 +75,7 @@ export async function GET(request: Request) {
       from: customFrom,
       to: customTo,
       refresh,
+      bypassCache: bypassCacheParam,
       hide_title,
       hide_background,
       hide_stats,
@@ -105,6 +106,10 @@ export async function GET(request: Request) {
     const normalizedView = view as 'default' | 'monthly' | 'heatmap' | 'pulse';
     const themeName = theme || 'dark';
 
+    // Treat either ?refresh=true or ?bypassCache=true as a cache-bypass request
+    const isRefreshRequested = refresh || bypassCacheParam;
+    const shouldBypassCache = isRefreshRequested;
+
     let timezone = 'UTC';
     if (tzParam) {
       try {
@@ -241,7 +246,7 @@ export async function GET(request: Request) {
     // Fetch Organization Mega-City Data OR Single User Data
     if (org) {
       const orgData = await getOrgDashboardData(org, {
-        bypassCache: refresh,
+        bypassCache: shouldBypassCache,
         from,
         to,
       });
@@ -264,7 +269,7 @@ export async function GET(request: Request) {
         users.map(async (u) => {
           try {
             const userData = await fetchGitHubContributions(u, {
-              bypassCache: refresh,
+              bypassCache: shouldBypassCache,
               from,
               to,
             });
@@ -290,7 +295,7 @@ export async function GET(request: Request) {
       }
     } else {
       const userData = await fetchGitHubContributions(user, {
-        bypassCache: refresh,
+        bypassCache: shouldBypassCache,
         from,
         to,
       });
@@ -301,7 +306,7 @@ export async function GET(request: Request) {
 
       if (versus) {
         const versusData = await fetchGitHubContributions(versus, {
-          bypassCache: refresh,
+          bypassCache: shouldBypassCache,
           from,
           to,
         });
@@ -339,10 +344,14 @@ export async function GET(request: Request) {
       const secondsToMidnight = tzParam
         ? getSecondsUntilMidnightInTimezone(timezone)
         : getSecondsUntilUTCMidnight();
-      const cacheControl = refresh
+      const cacheControl = isRefreshRequested
         ? 'no-cache, no-store, must-revalidate'
         : `public, s-maxage=${secondsToMidnight}, stale-while-revalidate=86400`;
 
+      const cacheStatusHeader = shouldBypassCache
+        ? `BYPASS, fetched=${new Date().toISOString()}`
+        : 'HIT';
+
       const jsonPayload = JSON.stringify({
         user: targetEntity,
         stats,
@@ -372,7 +381,7 @@ export async function GET(request: Request) {
           'Content-Type': 'application/json',
           'Cache-Control': cacheControl,
           ETag: weakEtag,
-          'X-Cache-Status': refresh ? `BYPASS, fetched=${new Date().toISOString()}` : 'HIT',
+          'X-Cache-Status': cacheStatusHeader,
         },
       });
     }
@@ -406,7 +415,7 @@ export async function GET(request: Request) {
     const secondsToMidnight = tzParam
       ? getSecondsUntilMidnightInTimezone(timezone)
       : getSecondsUntilUTCMidnight();
-    const cacheControl = refresh
+    const cacheControl = isRefreshRequested
       ? 'no-cache, no-store, must-revalidate'
       : isHistoricalYear
         ? 'public, s-maxage=31536000, immutable'
@@ -432,7 +441,7 @@ export async function GET(request: Request) {
         'Cache-Control': cacheControl,
         'Content-Security-Policy': SVG_CSP_HEADER,
         ETag: weakEtag,
-        'X-Cache-Status': refresh ? `BYPASS, fetched=${new Date().toISOString()}` : 'HIT',
+        'X-Cache-Status': shouldBypassCache ? `BYPASS, fetched=${new Date().toISOString()}` : 'HIT',
       },
     });
   } catch (error: unknown) {

app/api/wrapped/route.ts

@@ -48,6 +48,7 @@ export async function GET(request: Request) {
       font,
       year: customYear,
       refresh,
+      bypassCache: bypassCacheParam,
       hide_title,
       hide_background,
       width,
@@ -90,14 +91,17 @@ export async function GET(request: Request) {
       scale: 'linear',
     };
 
+    // Treat either ?refresh=true or ?bypassCache=true as a cache-bypass request
+    const isRefreshRequested = refresh || bypassCacheParam;
+
     // Fetch the wrapped stats for the year (calendar is included to avoid a duplicate API call)
-    const wrappedStats = await getWrappedData(user, year, { bypassCache: refresh });
+    const wrappedStats = await getWrappedData(user, year, { bypassCache: isRefreshRequested });
 
     const svg = generateWrappedSVG(wrappedStats, params, year, wrappedStats.calendar);
 
     // Cache-Control: Annual wrapped stats are stable, cache for 24 hours.
-    // Clients can bust with ?refresh=true.
-    const cacheControl = refresh
+    // Clients can bust with ?refresh=true or ?bypassCache=true.
+    const cacheControl = isRefreshRequested
       ? 'no-cache, no-store, must-revalidate'
       : 'public, s-maxage=86400, stale-while-revalidate=86400';
 
@@ -106,7 +110,9 @@ export async function GET(request: Request) {
         'Content-Type': 'image/svg+xml',
         'Cache-Control': cacheControl,
         'Content-Security-Policy': SVG_CSP_HEADER,
-        'X-Cache-Status': refresh ? `BYPASS, fetched=${new Date().toISOString()}` : 'HIT',
+        'X-Cache-Status': isRefreshRequested
+          ? `BYPASS, fetched=${new Date().toISOString()}`
+          : 'HIT',
       },
     });
   } catch (error: unknown) {

lib/validations.ts

@@ -264,6 +264,7 @@ const baseStreakParamsSchema = z.object({
       { message: 'Invalid "date" format. Use ISO 8601.' }
     ),
   refresh: z.string().optional().transform(toRefreshFlag),
+  bypassCache: z.string().optional().transform(toRefreshFlag),
   hide_title: z.string().optional().transform(toBooleanFlag),
   hide_background: z.string().optional().transform(toBooleanFlag),
   hide_stats: z.string().optional().transform(toBooleanFlag),
@@ -383,6 +384,7 @@ export const githubParamsSchema = z.object({
       message: 'Invalid GitHub username',
     }),
   refresh: z.string().optional().transform(toRefreshFlag),
+  bypassCache: z.string().optional().transform(toRefreshFlag),
 });
 
 export const compareParamsSchema = z
@@ -438,6 +440,7 @@ export const ogParamsSchema = z
       .transform(toEmptyStringAsUndefined)
       .transform(toValidHexColor('000000')),
     refresh: z.string().optional().transform(toRefreshFlag),
+    bypassCache: z.string().optional().transform(toRefreshFlag),
   })
   .transform((data) => ({
     ...data,
@@ -453,6 +456,7 @@ export const statsParamsSchema = z.object({
       message: 'Invalid GitHub username',
     }),
   refresh: z.string().optional().transform(toRefreshFlag),
+  bypassCache: z.string().optional().transform(toRefreshFlag),
   tz: timeZoneParam,
 });
 
@@ -534,6 +538,7 @@ export const wrappedParamsSchema = z.object({
     .optional()
     .transform((val) => sanitizeFont(val) || undefined),
   refresh: z.string().optional().transform(toRefreshFlag),
+  bypassCache: z.string().optional().transform(toRefreshFlag),
   hide_title: z.string().optional().transform(toBooleanFlag),
   hide_background: z.string().optional().transform(toBooleanFlag), // ✅ Fixed: was toRefreshFlag
   width: dimensionParam('width', 100, 1200),

middleware.ts

@@ -28,7 +28,9 @@ export async function middleware(request: NextRequest) {
   // Secure client IP extraction
   const ip = getClientIp(request);
 
-  const isRefresh = request.nextUrl.searchParams.get('refresh') === 'true';
+  const isRefresh =
+    request.nextUrl.searchParams.get('refresh') === 'true' ||
+    request.nextUrl.searchParams.get('bypassCache') === 'true';
 
   if (isRefresh) {
     // Stricter limit: 5 cache-bypass requests per minute per IP.

services/github/refresh-policy.empty-fallback.test.ts

@@ -79,11 +79,11 @@ describe('RefreshPolicy - Edge Cases & Empty/Missing Inputs', () => {
     expect(policy.isRefreshAllowed('user-a')).toBe(true);
     expect(policy.getRemainingCooldown('user-a')).toBe(0);
 
-    // Verify cooldown is restored to default (5 * 60 * 1000 = 300000ms)
+    // Verify cooldown is restored to default (30 * 1000 = 30000ms)
     policy.recordRefresh('user-a');
-    // It should be around 300000 right after recording (allow minor execution delay)
+    // It should be around 30000 right after recording (allow minor execution delay)
     const remaining = policy.getRemainingCooldown('user-a');
-    expect(remaining).toBeLessThanOrEqual(300000);
-    expect(remaining).toBeGreaterThanOrEqual(299000);
+    expect(remaining).toBeLessThanOrEqual(30000);
+    expect(remaining).toBeGreaterThanOrEqual(29000);
   });
 });

services/github/refresh-policy.ts

@@ -4,8 +4,8 @@ import { TTLCache } from '../../lib/cache';
 export class RefreshPolicy {
   private static instance: RefreshPolicy;
 
-  // Cooldown in milliseconds (default 5 minutes)
-  private cooldownMs = 5 * 60 * 1000;
+  // Cooldown in milliseconds (default 30 seconds)
+  private cooldownMs = 30 * 1000;
 
   // Cache of username -> last successful refresh timestamp (15,000 capacity)
   private refreshTimes = new TTLCache<number>(15000, 60 * 60 * 1000);
@@ -105,7 +105,7 @@ export class RefreshPolicy {
    */
   public reset(): void {
     this.refreshTimes.clear();
-    this.cooldownMs = 5 * 60 * 1000;
+    this.cooldownMs = 30 * 1000;
   }
 }