docs: add full query parameter matrix

.github/scripts/check-duplicates.js

@@ -18,13 +18,13 @@ function cosineSimilarity(vecA, vecB) {
 
 async function run() {
   const geminiApiKey = process.env.GEMINI_API_KEY;
-  const githubToken = process.env.GITHUB_TOKEN;
+  const githubToken = process.env.GITHUB_PAT || process.env.GITHUB_TOKEN;
 
   if (!geminiApiKey) {
     throw new Error('❌ Missing GEMINI_API_KEY environment variable.');
   }
   if (!githubToken) {
-    throw new Error('❌ Missing GITHUB_TOKEN environment variable.');
+    throw new Error('❌ Missing GITHUB_PAT or GITHUB_TOKEN environment variable.');
   }
 
   const octokit = github.getOctokit(githubToken);

app/api/notify/route.ts

@@ -37,7 +37,11 @@ export async function POST(req: NextRequest): Promise<NextResponse<NotificationR
   // Rate limiting
   const ip = getClientIp(req);
 
-  if (ip !== 'unknown' && !(await notifyRateLimiter.check(ip))) {
+  // fallback ensures rate limit is ALWAYS applied
+  const rateLimitKey =
+    ip && ip !== 'unknown' ? ip : `unknown:${req.headers.get('user-agent') ?? 'no-agent'}`;
+
+  if (!(await notifyRateLimiter.check(rateLimitKey))) {
     return NextResponse.json(
       { success: false, message: 'Too many requests, please try again later.' },
       { status: 429 }

app/api/stats/route.test.ts

@@ -7,6 +7,9 @@ vi.mock('../../../lib/github', () => ({
 
 import { fetchGitHubContributions } from '../../../lib/github';
 import type { ContributionCalendar } from '../../../types';
+import { quotaMonitor } from '@/services/github/quota-monitor';
+import { refreshPolicy } from '@/services/github/refresh-policy';
+import { refreshRateLimiter } from '@/services/github/refresh-rate-limiter';
 
 // Calendar with a known, predictable streak so assertions are deterministic.
 // Last day (2024-06-16) has commits; "today" in tests is set to that date.
@@ -27,17 +30,25 @@ const mockCalendar: ContributionCalendar = {
   ],
 };
 
-function makeRequest(params: Record<string, string> = {}): Request {
+function makeRequest(
+  params: Record<string, string> = {},
+  headers: Record<string, string> = {}
+): Request {
   const url = new URL('http://localhost/api/stats');
   for (const [key, value] of Object.entries(params)) {
     url.searchParams.set(key, value);
   }
-  return new Request(url.toString());
+  return new Request(url.toString(), {
+    headers: new Headers(headers),
+  });
 }
 
 describe('GET /api/stats', () => {
   beforeEach(() => {
     vi.clearAllMocks();
+    quotaMonitor.reset();
+    refreshPolicy.reset();
+    refreshRateLimiter.reset();
     vi.mocked(fetchGitHubContributions).mockResolvedValue({
       calendar: mockCalendar,
       repoContributions: [],
@@ -110,6 +121,7 @@ describe('GET /api/stats', () => {
     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');
+    expect(response.headers.get('X-Refresh-Status')).toBe('Fresh');
   });
 
   it('still returns valid stats data when refresh=true', async () => {
@@ -143,6 +155,47 @@ describe('GET /api/stats', () => {
     expect(fetchGitHubContributions).toHaveBeenCalledWith('testuser', { bypassCache: false });
   });
 
+  it('serves cached stats instead of bypassing cache during refresh cooldown', async () => {
+    await GET(makeRequest({ user: 'testuser', refresh: 'true' }));
+
+    const response = await GET(makeRequest({ user: 'testuser', refresh: 'true' }));
+
+    expect(response.status).toBe(200);
+    expect(fetchGitHubContributions).toHaveBeenLastCalledWith('testuser', {
+      bypassCache: false,
+    });
+    expect(response.headers.get('X-Refresh-Status')).toBe('Cooldown-Served-Cached');
+    expect(response.headers.get('Cache-Control')).toBe(
+      'public, s-maxage=3600, stale-while-revalidate=86400'
+    );
+  });
+
+  it('returns 429 when stats refresh exceeds the client refresh rate limit', async () => {
+    refreshRateLimiter.setLimit(1);
+
+    await GET(makeRequest({ user: 'testuser', refresh: 'true' }, { 'x-real-ip': '203.0.113.9' }));
+
+    const response = await GET(
+      makeRequest({ user: 'octocat', refresh: 'true' }, { 'x-real-ip': '203.0.113.9' })
+    );
+
+    expect(response.status).toBe(429);
+    const body = await response.json();
+    expect(body.error).toContain('Refresh rate limit exceeded');
+    expect(response.headers.get('X-RateLimit-Limit')).toBe('1');
+  });
+
+  it('blocks stats refresh when the shared GitHub quota is low', async () => {
+    quotaMonitor.setQuota(5000, 400, Date.now() + 60_000);
+
+    const response = await GET(makeRequest({ user: 'testuser', refresh: 'true' }));
+
+    expect(response.status).toBe(429);
+    const body = await response.json();
+    expect(body.error).toContain('quota is low');
+    expect(fetchGitHubContributions).not.toHaveBeenCalled();
+  });
+
   it('accepts a valid IANA timezone without error', async () => {
     const response = await GET(makeRequest({ user: 'testuser', tz: 'America/New_York' }));
     expect(response.status).toBe(200);

app/api/stats/route.ts

@@ -3,6 +3,21 @@ import { NextResponse } from 'next/server';
 import { fetchGitHubContributions } from '@/lib/github';
 import { calculateStreak } from '@/lib/calculate';
 import { statsParamsSchema } from '@/lib/validations';
+import { getClientIp } from '@/utils/getClientIp';
+import { quotaMonitor } from '@/services/github/quota-monitor';
+import { refreshPolicy } from '@/services/github/refresh-policy';
+import { refreshRateLimiter } from '@/services/github/refresh-rate-limiter';
+
+function logSecurityEvent(event: string, details: Record<string, unknown>) {
+  console.warn(
+    JSON.stringify({
+      timestamp: new Date().toISOString(),
+      type: 'SECURITY_EVENT',
+      event,
+      ...details,
+    })
+  );
+}
 
 /**
  * GET /api/stats?user=<username>[&refresh=true][&tz=<IANA timezone>]
@@ -20,6 +35,7 @@ import { statsParamsSchema } from '@/lib/validations';
  */
 export async function GET(request: Request) {
   const { searchParams } = new URL(request.url);
+  const ip = getClientIp(request);
 
   const parseResult = statsParamsSchema.safeParse(Object.fromEntries(searchParams.entries()));
 
@@ -47,6 +63,54 @@ export async function GET(request: Request) {
 
   const { user, refresh, tz } = parseResult.data;
 
+  if (refresh && quotaMonitor.isQuotaLow()) {
+    logSecurityEvent('LOW_QUOTA_STATS_REFRESH_BLOCKED', {
+      user,
+      ip,
+      remainingQuota: quotaMonitor.getQuota().remaining,
+    });
+    return NextResponse.json(
+      { error: 'GitHub API quota is low. Stats refresh temporarily disabled.' },
+      { status: 429 }
+    );
+  }
+
+  if (refresh) {
+    const rateLimitCheck = refreshRateLimiter.checkLimit(ip);
+    if (!rateLimitCheck.success) {
+      logSecurityEvent('STATS_REFRESH_RATE_LIMIT_EXCEEDED', {
+        user,
+        ip,
+        limit: rateLimitCheck.limit,
+      });
+      return NextResponse.json(
+        { error: 'Refresh rate limit exceeded. Please try again later.' },
+        {
+          status: 429,
+          headers: {
+            'X-RateLimit-Limit': rateLimitCheck.limit.toString(),
+            'X-RateLimit-Remaining': rateLimitCheck.remaining.toString(),
+            'X-RateLimit-Reset': rateLimitCheck.reset.toString(),
+          },
+        }
+      );
+    }
+  }
+
+  let shouldBypassCache = refresh;
+  if (refresh) {
+    if (!refreshPolicy.isRefreshAllowed(user)) {
+      logSecurityEvent('STATS_REFRESH_COOLDOWN_VIOLATION', {
+        user,
+        ip,
+        remainingMs: refreshPolicy.getRemainingCooldown(user),
+      });
+      shouldBypassCache = false;
+    } else {
+      refreshPolicy.recordRefresh(user);
+    }
+  }
+
   // Validate the optional IANA timezone early so callers get a clear 400
   // rather than a silent fallback or a 500.
   let timezone = 'UTC';
@@ -59,19 +123,23 @@ export async function GET(request: Request) {
   }
 
   try {
-    const userData = await fetchGitHubContributions(user, { bypassCache: refresh });
+    const userData = await fetchGitHubContributions(user, { bypassCache: shouldBypassCache });
     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) {
+    if (shouldBypassCache) {
       headers.set('Cache-Control', 'no-store, no-cache, must-revalidate');
       headers.set('Pragma', 'no-cache');
       headers.set('Expires', '0');
     }
+    headers.set(
+      'X-Refresh-Status',
+      shouldBypassCache ? 'Fresh' : refresh ? 'Cooldown-Served-Cached' : 'Cached'
+    );
 
     return NextResponse.json(
       {

app/api/streak/route.test.ts

@@ -943,7 +943,11 @@ describe('GET /api/streak', () => {
       expect(body.details).not.toBeNull();
     });
   });
+  it('returns 400 when an invalid hex color is passed as bg', async () => {
+    const response = await GET(makeRequest({ user: 'octocat', bg: '#ZZZZZZ' }));
 
+    expect(response.status).toBe(400);
+  });
   describe('hide parameters', () => {
     it('removes the username title when hide_title=true', async () => {
       const response = await GET(makeRequest({ user: 'octocat', hide_title: 'true' }));

app/api/streak/route.ts

@@ -99,6 +99,7 @@ export async function GET(request: Request) {
       glow,
       format,
       days,
+      badges,
     } = parseResult.data;
     const normalizedView = view as 'default' | 'monthly' | 'heatmap' | 'pulse';
     const themeName = theme || 'dark';
@@ -182,6 +183,7 @@ export async function GET(request: Request) {
       disable_particles,
       glow,
       animate,
+      badges,
     };
 
     let calendar;

app/api/track-user/route.ts

@@ -9,7 +9,9 @@ export async function POST(req: Request) {
   // Get IP for rate limiting securely
   const ip = getClientIp(req);
 
-  if (ip !== '127.0.0.1' && ip !== 'unknown' && !(await trackUserRateLimiter.check(ip))) {
+  const rateLimitKey = ip === 'unknown' ? 'unknown-client' : ip;
+
+  if (ip !== '127.0.0.1' && !(await trackUserRateLimiter.check(rateLimitKey))) {
     return NextResponse.json(
       { success: false, error: 'Too many requests, please try again later.' },
       { status: 429 }

app/api/user-details/route.test.ts

@@ -0,0 +1,104 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { GET } from './route';
+
+vi.mock('@/lib/github', () => ({
+  fetchUserProfile: vi.fn(),
+  fetchGitHubContributions: vi.fn(),
+}));
+
+import { fetchUserProfile, fetchGitHubContributions } from '@/lib/github';
+import type { ContributionCalendar } from '@/types';
+
+const mockCalendar: ContributionCalendar = {
+  totalContributions: 15,
+  weeks: [
+    {
+      contributionDays: [
+        { contributionCount: 5, date: '2024-06-10' },
+        { contributionCount: 5, date: '2024-06-11' },
+        { contributionCount: 5, date: '2024-06-12' },
+      ],
+    },
+  ],
+};
+
+const mockProfile = {
+  login: 'testuser',
+  name: 'Test User',
+  avatar_url: 'https://github.com/testuser.png',
+  public_repos: 12,
+};
+
+function makeRequest(params: Record<string, string> = {}): Request {
+  const url = new URL('http://localhost/api/user-details');
+  for (const [key, value] of Object.entries(params)) {
+    url.searchParams.set(key, value);
+  }
+  return new Request(url.toString());
+}
+
+describe('GET /api/user-details', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    vi.mocked(fetchUserProfile).mockResolvedValue(mockProfile as any);
+    vi.mocked(fetchGitHubContributions).mockResolvedValue({
+      calendar: mockCalendar,
+      repoContributions: [],
+      totalPRs: 0,
+      totalIssues: 0,
+    });
+  });
+
+  it('returns 400 when username is missing', async () => {
+    const response = await GET(makeRequest());
+    expect(response.status).toBe(400);
+    const body = await response.json();
+    expect(body.error).toBe('Username is required');
+  });
+
+  it('returns 400 when username format is invalid', async () => {
+    const response = await GET(makeRequest({ username: 'invalid_user_name_@' }));
+    expect(response.status).toBe(400);
+    const body = await response.json();
+    expect(body.error).toBe('Invalid username format');
+  });
+
+  it('returns 200 with user details and streak stats on success', async () => {
+    const response = await GET(makeRequest({ username: 'testuser' }));
+    expect(response.status).toBe(200);
+    const body = await response.json();
+    expect(body).toEqual({
+      exists: true,
+      login: 'testuser',
+      name: 'Test User',
+      avatar_url: 'https://github.com/testuser.png',
+      public_repos: 12,
+      stats: {
+        currentStreak: 3,
+        longestStreak: 3,
+        totalContributions: 15,
+      },
+    });
+  });
+
+  it('returns 404 when user is not found', async () => {
+    vi.mocked(fetchUserProfile).mockRejectedValue(new Error('User not found'));
+    const response = await GET(makeRequest({ username: 'missinguser' }));
+    expect(response.status).toBe(404);
+    const body = await response.json();
+    expect(body.error).toBe('User not found');
+  });
+
+  it('gracefully handles contributions fetch failure and returns profile details', async () => {
+    vi.mocked(fetchGitHubContributions).mockRejectedValue(new Error('API limit reached'));
+    const response = await GET(makeRequest({ username: 'testuser' }));
+    expect(response.status).toBe(200);
+    const body = await response.json();
+    expect(body.stats).toEqual({
+      currentStreak: 0,
+      longestStreak: 0,
+      totalContributions: 0,
+    });
+  });
+});