feat(api): add JSON output mode for /api/streak via format=json (JhaSourav07#2097)

## Description

Fixes JhaSourav07#2070

Adds `format=json` query parameter to `/api/streak` so developers can
programmatically access streak stats, monthly stats, and calendar data
without parsing SVG.

**Example:** `GET /api/streak?user=octocat&format=json` returns JSON
with `stats`, `monthlyStats`, and `calendar` fields. Invalid format
values silently fall back to SVG output.

### Changes
- **`lib/validations.ts`** — Added `format` field to
`baseStreakParamsSchema` with `.catch('svg')` fallback
- **`app/api/streak/route.ts`** — Added JSON output branch before SVG
generation with proper Cache-Control and X-Cache-Status headers
- **`app/api/streak/route.test.ts`** — Added 7 tests covering JSON
output, headers, defaults, and fallback behavior

## Pillar

- [x] 🛠️ Other (Bug fix, refactoring, docs)

## Visual Preview

No visual changes — this adds a new JSON output mode alongside the
existing SVG rendering. SVG output is unchanged.

## 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=YOUR_USERNAME`).
- [x] I have run `npm run format` and `npm run lint` locally and
resolved all errors (CI will fail otherwise).
- [x] My commits follow the Conventional Commits format (e.g.,
`feat(themes): ...`, `fix(calculate): ...`).
- [ ] I have updated `README.md` if I added a new theme or URL
parameter.
- [x] I have started 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 (no raw elements, smooth animations, correct fonts).

Author: JhaSourav07

app/api/streak/route.test.ts

@@ -1337,4 +1337,54 @@ describe('GET /api/streak', () => {
       expect(body).toContain('strictly for organizations');
     });
   });
+
+  describe('JSON output mode (format=json)', () => {
+    it('returns JSON with correct Content-Type when format=json is set', async () => {
+      const response = await GET(makeRequest({ user: 'octocat', format: 'json' }));
+      expect(response.status).toBe(200);
+      expect(response.headers.get('Content-Type')).toContain('application/json');
+    });
+
+    it('returns stats, monthlyStats, and calendar in JSON response', async () => {
+      const response = await GET(makeRequest({ user: 'octocat', format: 'json' }));
+      const data = await response.json();
+
+      expect(data.user).toBe('octocat');
+      expect(data.stats).toBeDefined();
+      expect(data.stats.currentStreak).toBeDefined();
+      expect(data.stats.longestStreak).toBeDefined();
+      expect(data.stats.totalContributions).toBeDefined();
+      expect(data.monthlyStats).toBeDefined();
+      expect(data.monthlyStats.currentMonthTotal).toBeDefined();
+      expect(data.calendar).toBeDefined();
+      expect(data.calendar.totalContributions).toBe(10);
+      expect(data.calendar.weeks).toHaveLength(2);
+    });
+
+    it('includes Cache-Control header in JSON response', async () => {
+      const response = await GET(makeRequest({ user: 'octocat', format: 'json' }));
+      expect(response.headers.get('Cache-Control')).toContain('s-maxage=');
+    });
+
+    it('includes X-Cache-Status header in JSON response', async () => {
+      const response = await GET(makeRequest({ user: 'octocat', format: 'json' }));
+      expect(response.headers.get('X-Cache-Status')).toBe('HIT');
+    });
+
+    it('returns SVG when format is not set (default)', async () => {
+      const response = await GET(makeRequest({ user: 'octocat' }));
+      expect(response.headers.get('Content-Type')).toBe('image/svg+xml');
+    });
+
+    it('falls back to SVG for invalid format values', async () => {
+      const response = await GET(makeRequest({ user: 'octocat', format: 'xml' }));
+      expect(response.headers.get('Content-Type')).toBe('image/svg+xml');
+    });
+
+    it('uses org name as user field when org parameter is provided', async () => {
+      const response = await GET(makeRequest({ user: 'octocat', org: 'github', format: 'json' }));
+      const data = await response.json();
+      expect(data.user).toBe('github');
+    });
+  });
 });

app/api/streak/route.ts

@@ -93,6 +93,7 @@ export async function GET(request: Request) {
       tz: tzParam,
       disable_particles,
       glow,
+      format,
     } = parseResult.data;
 
     const themeName = theme || 'dark';
@@ -196,6 +197,42 @@ export async function GET(request: Request) {
       }
     }
 
+    // ─── JSON output mode ──────────────────────────────────────────────────
+    if (format === 'json') {
+      const stats = calculateStreak(calendar, timezone, undefined, grace);
+      const monthlyStats = calculateMonthlyStats(
+        calendar,
+        timezone,
+        getMonthlyReferenceDate(year, timezone)
+      );
+
+      const secondsToMidnight = tzParam
+        ? getSecondsUntilMidnightInTimezone(timezone)
+        : getSecondsUntilUTCMidnight();
+      const cacheControl = refresh
+        ? 'no-cache, no-store, must-revalidate'
+        : `public, s-maxage=${secondsToMidnight}, stale-while-revalidate=86400`;
+
+      return NextResponse.json(
+        {
+          user: targetEntity,
+          stats,
+          monthlyStats,
+          calendar: {
+            totalContributions: calendar.totalContributions,
+            weeks: calendar.weeks,
+          },
+        },
+        {
+          headers: {
+            'Cache-Control': cacheControl,
+            'X-Cache-Status': refresh ? `BYPASS, fetched=${new Date().toISOString()}` : 'HIT',
+          },
+        }
+      );
+    }
+
+    // ─── SVG output mode (default) ──────────────────────────────────────────
     let svg = '';
     if (view === 'monthly') {
       const stats = calculateMonthlyStats(

lib/validations.ts

@@ -254,6 +254,10 @@ const baseStreakParamsSchema = z.object({
   glow: z.string().optional().transform(toBooleanFlag).default(true),
   entrance: z.enum(['rise', 'fade', 'slide', 'none']).catch('rise').default('rise'),
 
+  // Output format: 'svg' (default) or 'json' for programmatic access.
+  // Invalid values silently fall back to 'svg'.
+  format: z.enum(['svg', 'json']).catch('svg').default('svg'),
+
   // layout parameter: strictly validated — unsupported values return a 400 Bad Request.
   layout: z
     .string()