feat: add ?year= parameter to generate past year monoliths (JhaSourav07#94)

## Description

Closes JhaSourav07#79

Adds support for a '?year=' URL parameter that allows users to generate
a 3D isometric monolith for any specific past year, not just the default
last 365 days.

## Pillar

- [ ] 🎨 Pillar 1 - New Theme Design
- [ ] 📐 Pillar 2 - Geometric SVG Improvement
- [x] 🕐 Pillar 3 -Time zone Logic Optimization
- [ ] 🛠️ Other (Bug fix, refactoring, docs)

## Visual Preview

**Default (no year param)**

![default](https://github.com/user-attachments/assets/fe196a7f-e423-4876-87a4-1009bfd753ac)

**?year=2023**

![2023](https://github.com/user-attachments/assets/aaae24c9-b6a6-4a70-be1e-2655b5120b43)

**?year=2024**

![2024](https://github.com/user-attachments/assets/30637c2e-0897-4f0d-90af-7a66e5bd20b9)

## Checklist before requesting a review:

- [x] I have read the `CONTRIBUTING.md` file.
- [x] I have tested these changes locally
('localhost:3000/api/streak?user=Disha286&year=2023').
- [x] I have run 'npm run format' and 'npm run lint' locally and
resolved all errors.
- [x] My commits follow the Conventional Commits format.
- [x] I have updated 'README.md' if I added a new theme or URL
parameter.
- [x] I have starred the repo.
- [x] I have made sure that I have only one commit to merge in this PR.
- [x] The SVG output matches the CommitPulse "premium quality" aesthetic
standard.

Author: JhaSourav07

README.md

@@ -87,6 +87,7 @@ URL Parameter > Theme Default > System Fallback
 | `speed`   | `string`  | No         | `8s`          | Radar scan animation duration (e.g. `4s`, `12s`)      |
 | `scale`   | `string`  | No         | `linear`      | Tower height scaling: `linear` or `log` (logarithmic) |
 | `refresh` | `boolean` | No         | `false`       | Bypass cache for real-time data                       |
+| `year`    | `string`  | No         | —             | Calendar year to render (e.g. `2023`, `2024`)         |
 
 ### Theme Presets
 
@@ -123,6 +124,10 @@ URL Parameter > Theme Default > System Fallback
 <!-- Fast scan + logarithmic scaling for power users -->
 
 ![](https://commitpulse.vercel.app/api/streak?user=jhasourav07&speed=4s&scale=log)
+
+<!-- View contributions for a specific past year -->
+
+![](https://commitpulse.vercel.app/api/streak?user=jhasourav07&year=2023)
 ```
 
 ---

app/api/streak/route.ts

@@ -16,6 +16,10 @@ export async function GET(request: Request) {
       return new NextResponse('Missing "user" parameter', { status: 400 });
     }
 
+    const yearParam = searchParams.get('year');
+    const from = yearParam ? `${yearParam}-01-01T00:00:00Z` : undefined;
+    const to = yearParam ? `${yearParam}-12-31T23:59:59Z` : undefined;
+
     const themeName = searchParams.get('theme') || 'dark';
     const isAutoTheme = themeName === 'auto';
     const selectedTheme = isAutoTheme ? themes.light : themes[themeName] || themes.dark;
@@ -47,7 +51,7 @@ export async function GET(request: Request) {
 
     const refresh = searchParams.get('refresh') === 'true';
 
-    const calendar = await fetchGitHubContributions(user, { bypassCache: refresh });
+    const calendar = await fetchGitHubContributions(user, { bypassCache: refresh, from, to });
     const stats = calculateStreak(calendar);
 
     const svg = generateSVG(stats, params, calendar);

lib/github.ts

@@ -58,6 +58,8 @@ type GitHubContributionResponse = {
 
 type FetchOptions = {
   bypassCache?: boolean;
+  from?: string;
+  to?: string;
 };
 
 export const GITHUB_CACHE_TTL_MS = 5 * 60 * 1000;
@@ -79,8 +81,12 @@ const contributionsCache = new TTLCache<ContributionCalendar>();
 const profileCache = new TTLCache<GitHubUserProfile>();
 const reposCache = new TTLCache<GitHubRepo[]>();
 
-function cacheKey(kind: 'contributions' | 'profile' | 'repos', username: string): string {
-  return `${kind}:${username.toLowerCase()}`;
+function cacheKey(
+  kind: 'contributions' | 'profile' | 'repos',
+  username: string,
+  year?: string
+): string {
+  return year ? `${kind}:${username.toLowerCase()}:${year}` : `${kind}:${username.toLowerCase()}`;
 }
 
 export function clearGitHubApiCacheForTests(): void {
@@ -98,17 +104,17 @@ export async function fetchGitHubContributions(
   username: string,
   options: FetchOptions = {}
 ): Promise<ContributionCalendar> {
-  const key = cacheKey('contributions', username);
+  const key = cacheKey('contributions', username, options.from?.substring(0, 4));
 
   if (!options.bypassCache) {
     const cached = contributionsCache.get(key);
     if (cached) return cached;
   }
 
   const query = `
-    query($login: String!) {
+    query($login: String!, $from: DateTime, $to: DateTime) {
       user(login: $login) {
-        contributionsCollection {
+        contributionsCollection(from: $from, to: $to) {
           contributionCalendar {
             totalContributions
             weeks {
@@ -127,7 +133,10 @@ export async function fetchGitHubContributions(
   const res = await fetchWithRetry(GITHUB_GRAPHQL_URL, {
     method: 'POST',
     headers: getHeaders(),
-    body: JSON.stringify({ query, variables: { login: username } }),
+    body: JSON.stringify({
+      query,
+      variables: { login: username, from: options.from, to: options.to },
+    }),
     cache: 'no-store', // Cache handled by our in-memory layer + API route headers
   });
 

package-lock.json

@@ -16,11 +16,11 @@
   },
   "dependencies": {
     "@tailwindcss/postcss": "^4.2.2",
-    "@vercel/analytics": "^2.0.1",
+    "@vercel/analytics": "^1.6.1",
     "framer-motion": "^12.38.0",
     "html-to-image": "^1.11.13",
     "lucide-react": "^1.8.0",
-    "next": "16.2.3",
+    "next": "^16.2.3",
     "react": "19.2.4",
     "react-dom": "19.2.4"
   },