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

Add format=json query parameter support to /api/streak so developers can
programmatically consume streak data, monthly stats, and calendar data
without parsing SVG. Invalid format values silently fall back to SVG.

Closes JhaSourav07#2070

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: 2 people

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';
@@ -194,6 +195,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()