From 3773e1736323c72addbe11e8b5e3dd0e9eeef0c9 Mon Sep 17 00:00:00 2001
From: Suresh <115452537+sureshsuriya@users.noreply.github.com>
Date: Tue, 21 Jul 2026 23:15:31 +0530
Subject: [PATCH] feat: add customizable label URL parameter for card title

---
 lib/svg/generator.test.ts                  | 73 ++++++++++++++++++++++
 lib/svg/generator.ts                       | 34 +++++++---
 lib/validations.streakParamsSchema.test.ts | 34 ++++++++++
 lib/validations.ts                         |  7 ++-
 types/index.ts                             |  2 +-
 5 files changed, 140 insertions(+), 10 deletions(-)

diff --git a/lib/svg/generator.test.ts b/lib/svg/generator.test.ts
index e5dbf1080..781bbe279 100644
--- a/lib/svg/generator.test.ts
+++ b/lib/svg/generator.test.ts
@@ -2695,6 +2695,79 @@ describe('XML Validation - All Generator Outputs', () => {
     });
   });
 
+  describe('label parameter custom title rendering', () => {
+    const baseParams = {
+      user: 'avi',
+      bg: hexColor('0d1117'),
+      text: hexColor('c9d1d9'),
+      accent: hexColor('58a6ff'),
+      speed: '8s',
+      scale: 'linear',
+    } as const;
+
+    it('renders custom label instead of uppercase username when custom label is supplied', () => {
+      const svg = generateSVG(
+        mockStats,
+        {
+          ...baseParams,
+          label: 'Team Streak',
+        },
+        mockCalendar
+      );
+
+      assertValidSVG(svg);
+      expect(svg).toContain('Team Streak');
+      expect(svg).not.toContain('AVI');
+    });
+
+    it('sanitizes custom label to prevent XSS / XML Injection', () => {
+      const svg = generateSVG(
+        mockStats,
+        {
+          ...baseParams,
+          label: '<script>alert(1)</script>',
+        },
+        mockCalendar
+      );
+
+      assertValidSVG(svg);
+      expect(svg).not.toContain('<script>');
+      expect(svg).toContain('&lt;script&gt;alert(1)&lt;/script&gt;');
+    });
+
+    it('truncates custom label if it exceeds 40 characters', () => {
+      const longLabel = 'a'.repeat(50);
+      const expectedLabel = 'a'.repeat(40) + '...';
+      const svg = generateSVG(
+        mockStats,
+        {
+          ...baseParams,
+          label: longLabel,
+        },
+        mockCalendar
+      );
+
+      assertValidSVG(svg);
+      expect(svg).toContain(expectedLabel);
+      expect(svg).not.toContain(longLabel);
+    });
+
+    it('works correctly in auto-theme mode', () => {
+      const svg = generateSVG(
+        mockStats,
+        {
+          user: 'avi',
+          autoTheme: true,
+          label: 'Auto Label Title',
+        } as unknown as BadgeParams,
+        mockCalendar
+      );
+
+      assertValidSVG(svg);
+      expect(svg).toContain('Auto Label Title');
+    });
+  });
+
   function assertValidSVG(svgString: string): void {
     const doc = new DOMParser().parseFromString(svgString, 'image/svg+xml');
     const parserError = doc.querySelector('parsererror');
diff --git a/lib/svg/generator.ts b/lib/svg/generator.ts
index dbdd06e87..c9278a935 100644
--- a/lib/svg/generator.ts
+++ b/lib/svg/generator.ts
@@ -105,6 +105,10 @@ export function truncateUsername(username: string): string {
     : username;
 }
 
+export function truncateLabel(label: string): string {
+  return label.length > 40 ? `${label.slice(0, 40)}...` : label;
+}
+
 export function getUsernameFontSize(username: string): number {
   const len = username.length;
   if (len <= 12) return 18;
@@ -730,9 +734,12 @@ function renderFooter(
     ? 'class="cp-accent-fill scan-line"'
     : `fill="${accent}" class="cp-accent-fill scan-line"`;
 
-  const displayTitle = params.custom_title
-    ? sanitizeCustomText(params.custom_title)
-    : `${truncateUsername(safeUser).toUpperCase()}${isWinner ? ' 👑' : ''}`;
+  const displayTitle =
+    typeof params.label === 'string'
+      ? sanitizeCustomText(truncateLabel(params.label))
+      : params.custom_title
+        ? sanitizeCustomText(params.custom_title)
+        : `${truncateUsername(safeUser).toUpperCase()}${isWinner ? ' 👑' : ''}`;
 
   const titleText = `${displayTitle}${
     params.isOfflineFallback
@@ -740,7 +747,11 @@ function renderFooter(
       : ''
   }`;
 
-  const titleFontSize = getUsernameFontSize(params.custom_title || truncateUsername(safeUser));
+  const titleFontSize = getUsernameFontSize(
+    typeof params.label === 'string'
+      ? truncateLabel(params.label)
+      : params.custom_title || truncateUsername(safeUser)
+  );
 
   let subtitleElement = '';
   if (params.custom_subtitle && !params.hide_title && params.label !== false) {
@@ -1162,9 +1173,12 @@ function generateAutoThemeSVG(
 
   const safeId = safeUser.replace(/[^a-zA-Z0-9-]/g, '_').toLowerCase();
 
-  const displayTitle = params.custom_title
-    ? sanitizeCustomText(params.custom_title)
-    : truncateUsername(safeUser).toUpperCase();
+  const displayTitle =
+    typeof params.label === 'string'
+      ? sanitizeCustomText(truncateLabel(params.label))
+      : params.custom_title
+        ? sanitizeCustomText(params.custom_title)
+        : truncateUsername(safeUser).toUpperCase();
 
   const titleText = `${displayTitle}${
     params.isOfflineFallback
@@ -1172,7 +1186,11 @@ function generateAutoThemeSVG(
       : ''
   }`;
 
-  const titleFontSize = getUsernameFontSize(params.custom_title || truncateUsername(safeUser));
+  const titleFontSize = getUsernameFontSize(
+    typeof params.label === 'string'
+      ? truncateLabel(params.label)
+      : params.custom_title || truncateUsername(safeUser)
+  );
 
   let subtitleElement = '';
   if (params.custom_subtitle && !params.hide_title && params.label !== false) {
diff --git a/lib/validations.streakParamsSchema.test.ts b/lib/validations.streakParamsSchema.test.ts
index e13a24b36..75c8fb777 100644
--- a/lib/validations.streakParamsSchema.test.ts
+++ b/lib/validations.streakParamsSchema.test.ts
@@ -209,4 +209,38 @@ describe('streakParamsSchema', () => {
     const result = streakParamsSchema.safeParse({ user: 'octocat', versus: 'bad user!' });
     expect(result.success).toBe(false);
   });
+
+  describe('label parameter', () => {
+    it('transforms string "false" to boolean false', () => {
+      const result = streakParamsSchema.safeParse({ user: 'octocat', label: 'false' });
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.data.label).toBe(false);
+      }
+    });
+
+    it('transforms string "true" to boolean true', () => {
+      const result = streakParamsSchema.safeParse({ user: 'octocat', label: 'true' });
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.data.label).toBe(true);
+      }
+    });
+
+    it('retains custom label strings', () => {
+      const result = streakParamsSchema.safeParse({ user: 'octocat', label: 'Team Streak' });
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.data.label).toBe('Team Streak');
+      }
+    });
+
+    it('retains undefined if label parameter is missing', () => {
+      const result = streakParamsSchema.safeParse({ user: 'octocat' });
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.data.label).toBeUndefined();
+      }
+    });
+  });
 });
diff --git a/lib/validations.ts b/lib/validations.ts
index 43b02ed9b..0cb8a4987 100644
--- a/lib/validations.ts
+++ b/lib/validations.ts
@@ -269,7 +269,12 @@ const baseStreakParamsSchema = z.object({
   label: z
     .string()
     .optional()
-    .transform((v) => v !== 'false'),
+    .transform((v) => {
+      if (v === undefined) return undefined;
+      if (v === 'false') return false;
+      if (v === 'true') return true;
+      return v;
+    }),
 
   theme: z
     .string()
diff --git a/types/index.ts b/types/index.ts
index 2d957c754..df3f6932b 100644
--- a/types/index.ts
+++ b/types/index.ts
@@ -202,7 +202,7 @@ export interface BadgeParams {
   /** GitHub username whose contribution data will be fetched and rendered. Required. */
   user: string;
 
-  label?: boolean;
+  label?: string | boolean;
   /** GitHub username of the opponent to compare against. */
   versus?: string;