refactor(streak): introduced zod schema for API parameter validation (JhaSourav07#124)

## Description

Fixes JhaSourav07#67 

Introduces zod for strict validation of incoming URL parameters across
all three API routes, replacing scattered manual `searchParams.get()`
calls and if/else fallbacks with a single centralized schema.
- New file `lib/validations.ts`:
Defines `streakParamsSchema`, `githubParamsSchema`, and `ogParamsSchema`
using `Zod`. Default values (theme: "dark", scale: "linear", speed:
"8s") are handled via Zod's `.default()`. Invalid speed and scale values
silently fall back to their defaults using `.catch()` to preserve
existing behavior. The user and username fields are required and return
a structured JSON error if missing.
- Changes in `app/api/streak/route.ts`:
Replaced all individual `searchParams.get()` calls with a single
`streakParamsSchema.safeParse()` call at the top of the handler. If
parsing fails (e.g. missing user), the route returns a clean structured
JSON 400 error immediately before any GitHub API call is made. All
downstream logic remains identical.
- Changes in `app/api/github/route.ts`:
Replaced manual `searchParams.get('username')` and `if (!username)`
check with `githubParamsSchema.safeParse()`. Returns a structured JSON
400 error if username is missing. All error handling and cache logic
remains identical.
- Changes in `app/api/og/route.tsx`:
Replaced `searchParams.get('user')` ?? 'unknown' with
`ogParamsSchema.parse()`. Since user is optional with a default of
'unknown', this route never throws a validation error. All rendering
logic remains identical.

- Added 4 additional optional properties — `radius`, `font`, `year`, and
`refresh` {Other than the requested ones}.
- All Acceptance Criteria are met. 🚀

## Pillar

- 🛠️ Other (Bug fix, refactoring, docs)

## Visual Preview
<img width="457" height="325" alt="Screenshot 2026-05-17 at 1 43 52 PM"
src="https://github.com/user-attachments/assets/8f46c743-60c3-4d9d-98fa-57a160c089d9"
/>


## Checklist before requesting a review:

- I have read the `CONTRIBUTING.md` file.
- I have tested these changes locally (`localhost:3000/api/streak`).
- I have run `npm run format` and `npm run lint` locally and resolved
all errors.
- My commits follow the Conventional Commits format.
- I have started the repo.
- I have made sure that i have only one commit to merge in this PR.
- The SVG output matches the CommitPulse "premium quality" aesthetic
standard (no raw elements, smooth animations, correct fonts).

Author: JhaSourav07

app/api/github/route.ts

@@ -1,15 +1,21 @@
 import { NextResponse } from 'next/server';
 import { getFullDashboardData } from '@/lib/github';
+import { githubParamsSchema } from '../../../lib/validations';
 
 export async function GET(request: Request) {
   const { searchParams } = new URL(request.url);
-  const username = searchParams.get('username');
-  const refresh = searchParams.get('refresh') === 'true';
 
-  if (!username) {
-    return NextResponse.json({ error: 'Username is required' }, { status: 400 });
+  const parseResult = githubParamsSchema.safeParse(Object.fromEntries(searchParams.entries()));
+
+  if (!parseResult.success) {
+    return NextResponse.json(
+      { error: 'Invalid parameters', details: parseResult.error.flatten() },
+      { status: 400 }
+    );
   }
 
+  const { username, refresh } = parseResult.data;
+
   try {
     const data = await getFullDashboardData(username, { bypassCache: refresh });
     const cacheControl = refresh

app/api/og/route.tsx

@@ -1,11 +1,13 @@
 import { ImageResponse } from 'next/og';
 import { NextRequest } from 'next/server';
+import { ogParamsSchema } from '../../../lib/validations';
 
 export const runtime = 'edge';
 
 export async function GET(req: NextRequest) {
   const { searchParams } = new URL(req.url);
-  const user = searchParams.get('user') ?? 'unknown';
+
+  const { user } = ogParamsSchema.parse(Object.fromEntries(searchParams.entries()));
 
   let totalCommits = 0;
   let longestStreak = 0;
@@ -57,34 +59,11 @@ export async function GET(req: NextRequest) {
           left: '300px',
         }}
       />
-
-      <div
-        style={{
-          fontSize: '48px',
-          color: '#58a6ff',
-          fontWeight: 'bold',
-          marginBottom: '24px',
-        }}
-      >
+      <div style={{ fontSize: '48px', color: '#58a6ff', fontWeight: 'bold', marginBottom: '24px' }}>
         ⚡ CommitPulse
       </div>
-
-      <div
-        style={{
-          fontSize: '32px',
-          color: '#c9d1d9',
-          marginBottom: '48px',
-        }}
-      >
-        @{user}
-      </div>
-
-      <div
-        style={{
-          display: 'flex',
-          gap: '48px',
-        }}
-      >
+      <div style={{ fontSize: '32px', color: '#c9d1d9', marginBottom: '48px' }}>@{user}</div>
+      <div style={{ display: 'flex', gap: '48px' }}>
         <div
           style={{
             display: 'flex',
@@ -96,27 +75,11 @@ export async function GET(req: NextRequest) {
             padding: '32px 48px',
           }}
         >
-          <div
-            style={{
-              fontSize: '56px',
-              fontWeight: 'bold',
-              color: '#58a6ff',
-            }}
-          >
+          <div style={{ fontSize: '56px', fontWeight: 'bold', color: '#58a6ff' }}>
             {totalCommits}
           </div>
-
-          <div
-            style={{
-              fontSize: '18px',
-              color: '#8b949e',
-              marginTop: '8px',
-            }}
-          >
-            Total Commits
-          </div>
+          <div style={{ fontSize: '18px', color: '#8b949e', marginTop: '8px' }}>Total Commits</div>
         </div>
-
         <div
           style={{
             display: 'flex',
@@ -128,27 +91,13 @@ export async function GET(req: NextRequest) {
             padding: '32px 48px',
           }}
         >
-          <div
-            style={{
-              fontSize: '56px',
-              fontWeight: 'bold',
-              color: '#f78166',
-            }}
-          >
+          <div style={{ fontSize: '56px', fontWeight: 'bold', color: '#f78166' }}>
             {longestStreak}
           </div>
-
-          <div
-            style={{
-              fontSize: '18px',
-              color: '#8b949e',
-              marginTop: '8px',
-            }}
-          >
+          <div style={{ fontSize: '18px', color: '#8b949e', marginTop: '8px' }}>
             Longest Streak 🔥
           </div>
         </div>
-
         <div
           style={{
             display: 'flex',
@@ -160,36 +109,15 @@ export async function GET(req: NextRequest) {
             padding: '32px 48px',
           }}
         >
-          <div
-            style={{
-              fontSize: '56px',
-              fontWeight: 'bold',
-              color: '#3fb950',
-            }}
-          >
+          <div style={{ fontSize: '56px', fontWeight: 'bold', color: '#3fb950' }}>
             {currentStreak}
           </div>
-
-          <div
-            style={{
-              fontSize: '18px',
-              color: '#8b949e',
-              marginTop: '8px',
-            }}
-          >
+          <div style={{ fontSize: '18px', color: '#8b949e', marginTop: '8px' }}>
             Current Streak ⚡
           </div>
         </div>
       </div>
-
-      <div
-        style={{
-          position: 'absolute',
-          bottom: '32px',
-          fontSize: '16px',
-          color: '#484f58',
-        }}
-      >
+      <div style={{ position: 'absolute', bottom: '32px', fontSize: '16px', color: '#484f58' }}>
         commitpulse.vercel.app
       </div>
     </div>,

app/api/streak/route.ts

@@ -6,21 +6,29 @@ import { generateSVG } from '../../../lib/svg/generator';
 import { getSecondsUntilUTCMidnight } from '../../../utils/time';
 import type { BadgeParams } from '../../../types';
 import { themes } from '../../../lib/svg/themes';
+import { streakParamsSchema } from '../../../lib/validations';
 
 export async function GET(request: Request) {
   try {
     const { searchParams } = new URL(request.url);
-    const user = searchParams.get('user');
 
-    if (!user) {
-      return new NextResponse('Missing "user" parameter', { status: 400 });
+    // Parse and validate all incoming params through Zod schema
+    const parseResult = streakParamsSchema.safeParse(Object.fromEntries(searchParams.entries()));
+
+    if (!parseResult.success) {
+      return NextResponse.json(
+        { error: 'Invalid parameters', details: parseResult.error.flatten() },
+        { 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 { user, theme, bg, text, accent, scale, speed, radius, font, year, refresh } =
+      parseResult.data;
+
+    const from = year ? `${year}-01-01T00:00:00Z` : undefined;
+    const to = year ? `${year}-12-31T23:59:59Z` : undefined;
 
-    const themeName = searchParams.get('theme') || 'dark';
+    const themeName = theme;
     const isAutoTheme = themeName === 'auto';
     const isRandomTheme = themeName === 'random';
     const selectedTheme = (() => {
@@ -33,51 +41,38 @@ export async function GET(request: Request) {
       return themes[themeName] || themes.dark;
     })();
 
-    const rawSpeed = searchParams.get('speed') || '8s';
-    const speed = /^\d+(\.\d+)?s$/.test(rawSpeed) ? rawSpeed : '8s';
-
-    const rawScale = searchParams.get('scale');
-    const scale = rawScale === 'log' ? 'log' : 'linear';
-
-    const font = searchParams.get('font') || undefined;
-
     // Auto-theme ignores custom hex overrides — the SVG uses CSS
     // custom properties with a prefers-color-scheme media query, so
     // fixed colors would conflict with the dual-palette switching.
     const params: BadgeParams = {
       user,
-      bg: isAutoTheme ? selectedTheme.bg : searchParams.get('bg') || selectedTheme.bg,
-      text: isAutoTheme ? selectedTheme.text : searchParams.get('text') || selectedTheme.text,
-      accent: isAutoTheme
-        ? selectedTheme.accent
-        : searchParams.get('accent') || selectedTheme.accent,
-      radius: searchParams.get('radius') || '8',
+      bg: isAutoTheme ? selectedTheme.bg : bg || selectedTheme.bg,
+      text: isAutoTheme ? selectedTheme.text : text || selectedTheme.text,
+      accent: isAutoTheme ? selectedTheme.accent : accent || selectedTheme.accent,
+      radius,
       speed,
       scale,
       font,
       autoTheme: isAutoTheme,
     };
 
-    const refresh = searchParams.get('refresh') === 'true';
-
     const calendar = await fetchGitHubContributions(user, { bypassCache: refresh, from, to });
     const stats = calculateStreak(calendar);
 
     const svg = generateSVG(stats, params, calendar);
 
-    // 4. Calculate Cache Control (Reset at UTC Midnight)
+    //4. Calculate Cache Control (Reset at UTC Midnight)
     const secondsToMidnight = getSecondsUntilUTCMidnight();
     const cacheControl =
       refresh || isRandomTheme
         ? 'no-cache, no-store, must-revalidate'
         : `public, s-maxage=${secondsToMidnight}, stale-while-revalidate=86400`;
 
-    // 5. Return the Image Response
+    //5. Return the Image Response
     return new NextResponse(svg, {
       headers: {
         'Content-Type': 'image/svg+xml',
         'Cache-Control': cacheControl,
-
         'Content-Security-Policy':
           "default-src 'none'; style-src 'unsafe-inline' https://fonts.googleapis.com; font-src https://fonts.gstatic.com; connect-src https://fonts.gstatic.com;",
       },

lib/validations.ts

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+
+export const streakParamsSchema = z.object({
+  // Required — missing user surfaces as "Missing" to match existing tests
+  user: z.string({ error: 'Missing user parameter' }).min(1, { message: 'Missing user parameter' }),
+
+  theme: z.string().default('dark'),
+  bg: z.string().optional(),
+  text: z.string().optional(),
+  accent: z.string().optional(),
+
+  // Silently fall back to 'linear' for unknown values (matches old behavior)
+  scale: z.enum(['linear', 'log']).catch('linear').default('linear'),
+
+  // Silently fall back to '8s' for invalid format (matches old behavior)
+  speed: z
+    .string()
+    .regex(/^\d+(\.\d+)?s$/)
+    .catch('8s')
+    .default('8s'),
+
+  radius: z.string().default('8'),
+  font: z.string().optional(),
+  year: z.string().optional(),
+  refresh: z
+    .string()
+    .optional()
+    .transform((val) => val === 'true'),
+});
+
+export const githubParamsSchema = z.object({
+  username: z
+    .string({ error: 'Missing "username" parameter' })
+    .min(1, { message: 'Username is required' }),
+  refresh: z
+    .string()
+    .optional()
+    .transform((val) => val === 'true'),
+});
+
+export const ogParamsSchema = z.object({
+  user: z.string().optional().default('unknown'),
+});
+
+export type StreakParams = z.infer<typeof streakParamsSchema>;
+export type GithubParams = z.infer<typeof githubParamsSchema>;
+export type OgParams = z.infer<typeof ogParamsSchema>;

package-lock.json

@@ -23,7 +23,8 @@
     "mongoose": "^9.6.2",
     "next": "^16.2.3",
     "react": "19.2.4",
-    "react-dom": "19.2.4"
+    "react-dom": "19.2.4",
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@testing-library/react": "^16.3.2",