fix(api): disable caching for refresh=true stats requests (JhaSourav07#1981)

## Description

This PR fixes cache behavior for the `/api/stats` endpoint when the
`refresh=true` query parameter is used.

Previously, requests using `refresh=true` correctly bypassed the
internal GitHub cache, but the response itself still returned cacheable
headers. This allowed downstream caches (CDNs, proxies, or intermediary
layers) to potentially store and serve stale responses even after an
explicit refresh request.

### Changes Made

* Added refresh-aware cache handling for the stats endpoint.
* Return non-cacheable headers when `refresh=true` is present:

  * `Cache-Control: no-store, no-cache, must-revalidate`
  * `Pragma: no-cache`
  * `Expires: 0`
* Preserved the existing caching strategy for normal requests.
* Added regression tests covering:

  * Refresh requests returning non-cacheable headers.
  * Refresh requests still returning valid stats data.
  * Normal requests retaining existing cache behavior.
* Refactored header handling using a concrete `Headers` instance to
satisfy TypeScript type requirements and ensure production builds
succeed.

Fixes JhaSourav07#1966

---

## Pillar

🐛 Bug Fix

---

## Checklist

* [x] Linked this PR to an assigned issue
* [x] Kept changes scoped to the issue requirements
* [x] Added/updated tests where applicable
* [x] Verified formatting locally
* [x] Verified linting locally
* [x] Verified type checking locally
* [x] Verified tests locally
* [x] Verified production build locally
* [x] Reviewed the implementation before submission

---

## Validation

Successfully verified locally using:

```bash
npm run format:check
npm run lint
npm run typecheck
npm run test
npm run build
```

### Results

* Format check: Passed
* Lint: Passed (warnings only, no errors)
* TypeScript type check: Passed
* Test suite: Passed (1199/1199 tests)
* Production build: Passed

### Impact

This change ensures that users explicitly requesting fresh statistics
receive responses that cannot be cached by intermediate layers while
preserving the existing caching benefits and performance optimizations
for normal requests.

Author: JhaSourav07

app/api/stats/route.test.ts

@@ -103,6 +103,36 @@ describe('GET /api/stats', () => {
     expect(typeof body.currentStreak).toBe('number');
   });
 
+  it('returns non-cacheable headers when refresh=true', async () => {
+    const response = await GET(makeRequest({ user: 'testuser', refresh: 'true' }));
+
+    expect(response.status).toBe(200);
+    expect(response.headers.get('Cache-Control')).toBe('no-store, no-cache, must-revalidate');
+    expect(response.headers.get('Pragma')).toBe('no-cache');
+    expect(response.headers.get('Expires')).toBe('0');
+  });
+
+  it('still returns valid stats data when refresh=true', async () => {
+    const response = await GET(makeRequest({ user: 'testuser', refresh: 'true' }));
+    const body = await response.json();
+
+    expect(response.status).toBe(200);
+    expect(body.totalContributions).toBe(10);
+    expect(typeof body.longestStreak).toBe('number');
+    expect(typeof body.currentStreak).toBe('number');
+  });
+
+  it('keeps the existing cache headers for normal requests', async () => {
+    const response = await GET(makeRequest({ user: 'testuser' }));
+
+    expect(response.status).toBe(200);
+    expect(response.headers.get('Cache-Control')).toBe(
+      'public, s-maxage=3600, stale-while-revalidate=86400'
+    );
+    expect(response.headers.get('Pragma')).toBeNull();
+    expect(response.headers.get('Expires')).toBeNull();
+  });
+
   it('passes bypassCache=true to GitHub when refresh=true', async () => {
     await GET(makeRequest({ user: 'testuser', refresh: 'true' }));
     expect(fetchGitHubContributions).toHaveBeenCalledWith('testuser', { bypassCache: true });

app/api/stats/route.ts

@@ -50,19 +50,24 @@ export async function GET(request: Request) {
     const userData = await fetchGitHubContributions(user, { bypassCache: refresh });
     const calendar = userData.calendar;
     const stats = calculateStreak(calendar, timezone);
+    const headers = new Headers({
+      // Cache until next UTC midnight; clients can bust with ?refresh=true
+      'Cache-Control': 'public, s-maxage=3600, stale-while-revalidate=86400',
+    });
+
+    if (refresh) {
+      headers.set('Cache-Control', 'no-store, no-cache, must-revalidate');
+      headers.set('Pragma', 'no-cache');
+      headers.set('Expires', '0');
+    }
 
     return NextResponse.json(
       {
         totalContributions: stats.totalContributions,
         longestStreak: stats.longestStreak,
         currentStreak: stats.currentStreak,
       },
-      {
-        headers: {
-          // Cache until next UTC midnight; clients can bust with ?refresh=true
-          'Cache-Control': 'public, s-maxage=3600, stale-while-revalidate=86400',
-        },
-      }
+      { headers }
     );
   } catch (error: unknown) {
     const message = error instanceof Error ? error.message : 'Unknown error';