Merge branch 'main' into refactor/streak-alive-helper

Author: shambavi2007

ARCHITECTURE.md

@@ -0,0 +1,62 @@
+# Architecture
+
+This document explains how a request flows through the SVG rendering pipeline.
+
+## Request → Response Flow
+
+```mermaid
+flowchart TD
+    A[Client Request] --> B[app/api/streak/route.ts]
+    B --> C[lib/github.ts]
+    C --> D[lib/calculate.ts]
+    D --> E[lib/svg/generator.ts]
+    E --> F[SVG Response]
+```
+
+## Layer Responsibilities
+
+### API Layer
+
+**File:** `app/api/streak/route.ts`
+
+Receives incoming requests and handles request validation. It acts as the entry point for the SVG generation pipeline.
+
+### GitHub Data Layer
+
+**File:** `lib/github.ts`
+
+Fetches contribution and activity data from GitHub APIs and prepares the required information.
+
+### Calculation Layer
+
+**File:** `lib/calculate.ts`
+
+Processes fetched data and calculates statistics such as contribution streaks and related values.
+
+### SVG Generation Layer
+
+**File:** `lib/svg/generator.ts`
+
+Converts processed data into SVG elements and generates the final visual output.
+
+## Caching Strategy
+
+Caching reduces repeated API requests and improves performance.
+
+The system can cache GitHub responses and calculated results to:
+
+- Reduce unnecessary API calls
+- Improve response speed
+- Reduce server load
+- Prevent repeated processing for frequently requested data
+
+## Summary
+
+Pipeline flow:
+
+1. Client sends request
+2. API route receives request
+3. GitHub data is fetched
+4. Data calculations are performed
+5. SVG is generated
+6. Response is returned

README.md

@@ -155,7 +155,7 @@ URL Parameter > Theme Default > System Fallback
 | `hide_background` | `boolean` | No         | `false`                        | Remove the background rect, letting the monolith float on the page                                                                                                        |
 | `hide_stats`      | `boolean` | No         | `false`                        | Hides the bottom row displaying Current Streak, Annual Sync Total, and Peak Streak stats when set to `true` or `1`.                                                       |
 | `tz`              | `string`  | No         | Omitted = UTC                  | IANA timezone (e.g. `Asia/Kolkata`, `America/New_York`) — aligns "today" with the user local midnight. Note: `?tz=UTC` is valid but cached separately from omitting `tz`. |
-| `lang`            | `string`  | No         | `en`                           | Language code for labels (`en`, `es`, `hi`, `fr`)                                                                                                                         |
+| `lang`            | `string`  | No         | `en`                           | Language code for labels (`en`, `es`, `hi`, `fr`, `pt`, `ko`)                                                                                                             |
 | `view`            | `string`  | No         | `default`                      | Rendering mode: `default` (3D Monolith) or `monthly` (Compact monthly stats)                                                                                              |
 | `delta_format`    | `string`  | No         | `percent`                      | Format for month-over-month delta in monthly view: `percent` (e.g. +12%), `absolute` (e.g. +15 commits), or `both`                                                        |
 | `width`           | `number`  | No         | `300`                          | Custom width for the SVG canvas (currently only applies to `view=monthly`)                                                                                                |

THEMES.md

@@ -1,105 +1,91 @@
-# 🎨 CommitPulse Theme Gallery
+# 🎨 CommitPulse Themes
 
-This gallery showcases all available themes for the CommitPulse streak card.
+All 13 available themes for your CommitPulse badge. Use the `?theme=<slug>` query parameter to apply a
+theme.
 
----
-
-## 🌑 Neon
-
-![Neon](assets/themes/neon.png)
-
-Usage: `/api/streak?user=yourusername&theme=neon`
+```
+https://commitpulse.vercel.app/api/badge?username=YOUR_USERNAME&theme=<slug>
+```
 
 ---
 
-## 🧛 Dracula
-
-![Dracula](assets/themes/dracula.png)
-
-Usage: `/api/streak?user=yourusername&theme=dracula`
+## Theme Gallery
+
+| Theme        | Background | Text      | Accent    |
+| ------------ | ---------- | --------- | --------- |
+| dark         | `#0d1117`  | `#c9d1d9` | `#58a6ff` |
+| light        | `#ffffff`  | `#24292f` | `#0969da` |
+| neon         | `#000000`  | `#00ffcc` | `#ff00ff` |
+| github       | `#0d1117`  | `#ffffff` | `#238636` |
+| dracula      | `#282a36`  | `#f8f8f2` | `#bd93f9` |
+| ocean        | `#0a192f`  | `#ccd6f6` | `#64ffda` |
+| sunset       | `#1a0a0a`  | `#ffd6c0` | `#ff6b35` |
+| forest       | `#0d1f0d`  | `#c8f0c8` | `#39d353` |
+| rose         | `#1f0d14`  | `#f0c8d4` | `#ff6b9d` |
+| nord         | `#2e3440`  | `#d8dee9` | `#88c0d0` |
+| synthwave    | `#0d0221`  | `#f8f8f2` | `#ff2d78` |
+| gruvbox      | `#282828`  | `#ebdbb2` | `#fe8019` |
+| highcontrast | `#0a0a0a`  | `#888888` | `#ff4500` |
 
 ---
 
-## 🌑 Dark
+## Preview URLs
 
-![Dark](assets/themes/dark.png)
+Use these URLs to preview each theme in your README:
 
-Usage: `/api/streak?user=yourusername&theme=dark`
+**dark**
 
----
+![dark](https://commitpulse.vercel.app/api/badge?username=demo&theme=dark)
 
-## 🤍 Light
+**light**
 
-![Light](assets/themes/light.png)
+![light](https://commitpulse.vercel.app/api/badge?username=demo&theme=light)
 
-Usage: `/api/streak?user=yourusername&theme=light`
+**neon**
 
----
+![neon](https://commitpulse.vercel.app/api/badge?username=demo&theme=neon)
 
-## 🐙 GitHub
+**github**
 
-![GitHub](assets/themes/github.png)
+![github](https://commitpulse.vercel.app/api/badge?username=demo&theme=github)
 
-Usage: `/api/streak?user=yourusername&theme=github`
+**dracula**
 
----
+![dracula](https://commitpulse.vercel.app/api/badge?username=demo&theme=dracula)
 
-## 🟠 Gruvbox
+**ocean**
 
-![Gruvbox](assets/themes/gruvbox.png)
+![ocean](https://commitpulse.vercel.app/api/badge?username=demo&theme=ocean)
 
-Usage: `/api/streak?user=yourusername&theme=gruvbox`
+**sunset**
 
----
+![sunset](https://commitpulse.vercel.app/api/badge?username=demo&theme=sunset)
 
-## 🌊 Ocean
+**forest**
 
-![Ocean](assets/themes/ocean.png)
+![forest](https://commitpulse.vercel.app/api/badge?username=demo&theme=forest)
 
-Usage: `/api/streak?user=yourusername&theme=ocean`
+**rose**
 
----
+![rose](https://commitpulse.vercel.app/api/badge?username=demo&theme=rose)
 
-## 🌅 Sunset
+**nord**
 
-![Sunset](assets/themes/sunset.png)
+![nord](https://commitpulse.vercel.app/api/badge?username=demo&theme=nord)
 
-Usage: `/api/streak?user=yourusername&theme=sunset`
+**synthwave**
 
----
+![synthwave](https://commitpulse.vercel.app/api/badge?username=demo&theme=synthwave)
 
-## 🌲 Forest
+**gruvbox**
 
-![Forest](assets/themes/forest.png)
+![gruvbox](https://commitpulse.vercel.app/api/badge?username=demo&theme=gruvbox)
 
-Usage: `/api/streak?user=yourusername&theme=forest`
+**highcontrast**
 
----
-
-## 🌹 Rose
-
-![Rose](assets/themes/rose.png)
-
-Usage: `/api/streak?user=yourusername&theme=rose`
+![highcontrast](https://commitpulse.vercel.app/api/badge?username=demo&theme=highcontrast)
 
 ---
 
-## ❄️ Nord
-
-![Nord](assets/themes/nord.png)
-
-Usage: `/api/streak?user=yourusername&theme=nord`
-
-## 🌆 Synthwave
-
-![Synthwave](assets/themes/synthwave.png)
-
-Retro 80s-inspired palette — deep indigo background, neon pink glow, crisp white text.
-
-Usage: `/api/streak?user=yourusername&theme=synthwave`
-
-## 🔥 High Contrast
-
-Near-black background with vivid red-orange accent and medium-grey text — maximum legibility on both solid and transparent backgrounds for low-vision accessibility.
-
-Usage: `/api/streak?user=yourusername&theme=highcontrast`
+> 💡 **Tip:** Use `?theme=auto` to automatically switch between `light` and `dark` based on the
+> viewer's OS setting.

app/api/og/route.test.ts

@@ -0,0 +1,55 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { GET } from './route';
+import { NextRequest } from 'next/server';
+vi.mock('../../../lib/github', () => ({
+  fetchGitHubContributions: vi.fn(),
+}));
+
+vi.mock('../../../lib/calculate', () => ({
+  calculateStreak: vi.fn(),
+}));
+
+import { fetchGitHubContributions } from '../../../lib/github';
+import { calculateStreak } from '../../../lib/calculate';
+
+describe('OG Route', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('returns 200 successfully', async () => {
+    vi.mocked(fetchGitHubContributions).mockResolvedValue({} as never);
+
+    vi.mocked(calculateStreak).mockReturnValue({
+      totalContributions: 120,
+      longestStreak: 20,
+      currentStreak: 5,
+      todayDate: '2026-05-27',
+    });
+
+    const req = new NextRequest('http://localhost:3000/api/og?user=testuser');
+
+    const res = await GET(req);
+
+    expect(res).toBeDefined();
+    expect(res.status).toBe(200);
+  });
+
+  it('falls back to zeros when github fetch fails', async () => {
+    vi.mocked(fetchGitHubContributions).mockRejectedValue(new Error('GitHub API failed'));
+
+    const req = new NextRequest('http://localhost:3000/api/og?user=testuser');
+
+    const res = await GET(req as never);
+
+    expect(res.status).toBe(200);
+  });
+
+  it('handles missing user query param', async () => {
+    const req = new NextRequest('http://localhost:3000/api/og');
+
+    const res = await GET(req as never);
+
+    expect(res.status).toBe(200);
+  });
+});