From 216346096173eebded2b7f56046b797b551a7bd6 Mon Sep 17 00:00:00 2001
From: Philippe Serhal <philippe.serhal@gmail.com>
Date: Thu, 9 Apr 2026 21:17:18 -0400
Subject: [PATCH 1/2] feat: show badge on most liked packages, link to new
 leaderboard page

Show a small rank badge next to the likes counter/button when a package is in the
top 10 most-liked packages, and link that badge to a new in-app likes
leaderboard page. For now at least, this is the only way to reach the leaderboard page.

Both are powered by server-side fetching of the likes leaderboard API
(https://tangled.org/baileytownsend.dev/npmx-likes-leaderboard), maintained by Bailey.

Fetches degrade gracefully: no badge is shown on the package page, and the leaderboard page shows a
message indicating that the data is unavailable.

Successful fetches are cached for 1 hour, and are only revalidated in the background, following a
stale-while-revalidate pattern (this is existing behaviour from `server/plugins/fetch-cache`).

The leaderboard page is itself cached with ISR, with a revalidation time of 15 minutes.
---
 app/components/Package/Likes.vue              | 150 ++++++++++--------
 app/pages/leaderboard/likes.vue               |  91 +++++++++++
 i18n/locales/en.json                          |  15 +-
 i18n/locales/fr-FR.json                       |  15 +-
 i18n/schema.json                              |  39 +++++
 nuxt.config.ts                                |   1 +
 server/api/leaderboard/likes.get.ts           |   8 +
 server/api/social/likes/[...pkg].get.ts       |  12 +-
 server/utils/atproto/utils/likes.ts           |   9 +-
 server/utils/likes-leaderboard.ts             | 123 ++++++++++++++
 shared/types/social.ts                        |   9 ++
 shared/utils/constants.ts                     |   3 +
 shared/utils/fetch-cache-config.ts            |   3 +-
 test/nuxt/a11y.spec.ts                        |  68 +++++++-
 test/nuxt/components/Package/Likes.spec.ts    |  58 +++++++
 test/nuxt/pages/LikesLeaderboardPage.spec.ts  |  56 +++++++
 .../server/utils/likes-leaderboard.spec.ts    | 124 +++++++++++++++
 17 files changed, 713 insertions(+), 71 deletions(-)
 create mode 100644 app/pages/leaderboard/likes.vue
 create mode 100644 server/api/leaderboard/likes.get.ts
 create mode 100644 server/utils/likes-leaderboard.ts
 create mode 100644 test/nuxt/components/Package/Likes.spec.ts
 create mode 100644 test/nuxt/pages/LikesLeaderboardPage.spec.ts
 create mode 100644 test/unit/server/utils/likes-leaderboard.spec.ts

diff --git a/app/components/Package/Likes.vue b/app/components/Package/Likes.vue
index 5c7b68089b..bbf10280f3 100644
--- a/app/components/Package/Likes.vue
+++ b/app/components/Package/Likes.vue
@@ -1,4 +1,5 @@
 <script lang="ts" setup>
+import type { PackageLikes } from '#shared/types/social'
 import { useModal } from '~/composables/useModal'
 import { useAtproto } from '~/composables/atproto/useAtproto'
 import { togglePackageLike } from '~/utils/atproto/likes'
@@ -37,10 +38,14 @@ const { user } = useAtproto()
 const authModal = useModal('auth-modal')
 const compactNumberFormatter = useCompactNumberFormatter()
 
-const { data: likesData, status: likeStatus } = useFetch(
+const { data: likesData, status: likeStatus } = useFetch<PackageLikes>(
   () => `/api/social/likes/${props.packageName}`,
   {
-    default: () => ({ totalLikes: 0, userHasLiked: false }),
+    default: () => ({
+      totalLikes: 0,
+      userHasLiked: false,
+      topLikedRank: null,
+    }),
     server: false,
   },
 )
@@ -48,6 +53,19 @@ const { data: likesData, status: likeStatus } = useFetch(
 const isLoadingLikeData = computed(
   () => likeStatus.value === 'pending' || likeStatus.value === 'idle',
 )
+const isPackageLiked = computed(() => likesData.value?.userHasLiked ?? false)
+const topLikedRank = computed(() => likesData.value?.topLikedRank ?? null)
+const likeButtonLabel = computed(() =>
+  isPackageLiked.value ? $t('package.likes.unlike') : $t('package.likes.like'),
+)
+const likeTooltipText = computed(() =>
+  isLoadingLikeData.value ? $t('common.loading') : likeButtonLabel.value,
+)
+const topLikedBadgeLabel = computed(() =>
+  topLikedRank.value == null
+    ? ''
+    : $t('package.likes.top_rank_link_label', { rank: topLikedRank.value }),
+)
 
 const isLikeActionPending = shallowRef(false)
 
@@ -61,6 +79,11 @@ const likeAction = async () => {
 
   const currentlyLiked = likesData.value?.userHasLiked ?? false
   const currentLikes = likesData.value?.totalLikes ?? 0
+  const previousLikesState: PackageLikes = {
+    totalLikes: currentLikes,
+    userHasLiked: currentlyLiked,
+    topLikedRank: topLikedRank.value,
+  }
 
   likeAnimKey.value++
 
@@ -79,6 +102,7 @@ const likeAction = async () => {
 
   // Optimistic update
   likesData.value = {
+    ...previousLikesState,
     totalLikes: currentlyLiked ? currentLikes - 1 : currentLikes + 1,
     userHasLiked: !currentlyLiked,
   }
@@ -92,81 +116,81 @@ const likeAction = async () => {
 
     if (result.success) {
       // Update with server response
-      likesData.value = result.data
-    } else {
-      // Revert on error
       likesData.value = {
-        totalLikes: currentLikes,
-        userHasLiked: currentlyLiked,
+        ...previousLikesState,
+        ...result.data,
+        topLikedRank: result.data.topLikedRank ?? previousLikesState.topLikedRank,
       }
+    } else {
+      // Revert on error
+      likesData.value = previousLikesState
     }
   } catch {
     // Revert on error
-    likesData.value = {
-      totalLikes: currentLikes,
-      userHasLiked: currentlyLiked,
-    }
+    likesData.value = previousLikesState
     isLikeActionPending.value = false
   }
 }
 </script>
 
 <template>
-  <TooltipApp
-    :text="
-      isLoadingLikeData
-        ? $t('common.loading')
-        : likesData?.userHasLiked
-          ? $t('package.likes.unlike')
-          : $t('package.likes.like')
-    "
-    position="bottom"
-    class="items-center"
-    strategy="fixed"
-  >
-    <div :class="$style.likeWrapper">
-      <span v-if="showLikeFloat" :key="likeFloatKey" aria-hidden="true" :class="$style.likeFloat"
-        >+1</span
-      >
-      <ButtonBase
-        @click="likeAction"
-        size="md"
-        :aria-label="
-          likesData?.userHasLiked ? $t('package.likes.unlike') : $t('package.likes.like')
-        "
-        :aria-pressed="likesData?.userHasLiked"
+  <div class="relative inline-flex items-center">
+    <TooltipApp :text="likeTooltipText" position="bottom" class="items-center" strategy="fixed">
+      <div class="relative inline-flex">
+        <span v-if="showLikeFloat" :key="likeFloatKey" aria-hidden="true" class="like-float"
+          >+1</span
+        >
+        <ButtonBase
+          @click="likeAction"
+          size="md"
+          :aria-label="likeButtonLabel"
+          :aria-pressed="isPackageLiked"
+        >
+          <span
+            :key="likeAnimKey"
+            :class="
+              isPackageLiked
+                ? 'i-lucide:heart-minus fill-red-500 text-red-500'
+                : 'i-lucide:heart-plus'
+            "
+            :style="heartAnimStyle"
+            aria-hidden="true"
+            class="inline-block w-4 h-4"
+          />
+          <span
+            v-if="isLoadingLikeData"
+            class="i-svg-spinners:ring-resize w-3 h-3 my-0.5"
+            aria-hidden="true"
+          />
+          <span v-else>
+            {{ compactNumberFormatter.format(likesData?.totalLikes ?? 0) }}
+          </span>
+        </ButtonBase>
+      </div>
+    </TooltipApp>
+
+    <TooltipApp
+      v-if="topLikedRank != null"
+      :text="$t('package.likes.top_rank_tooltip', { rank: topLikedRank })"
+      position="left"
+      :offset="8"
+      strategy="fixed"
+      class="absolute [inset-inline-end:-0.5rem] top-[-0.4rem] z-1"
+    >
+      <NuxtLink
+        :to="{ name: 'leaderboard-likes' }"
+        :aria-label="topLikedBadgeLabel"
+        data-testid="top-liked-badge"
+        class="inline-flex items-center justify-center min-w-5 rounded-full px-1.5 py-0.5 text-2xs font-bold leading-none no-underline text-[var(--bg)] border border-[var(--bg)] bg-[radial-gradient(circle_at_28%_25%,rgb(255_255_255_/_0.34),transparent_38%),linear-gradient(135deg,color-mix(in_oklab,white_10%,var(--accent))_0%,var(--accent)_100%)] shadow-[0_1px_0_rgb(255_255_255_/_0.32)_inset,0_2px_6px_color-mix(in_oklab,var(--accent)_14%,transparent)] transition-shadow duration-[160ms] hover:shadow-[0_1px_0_rgb(255_255_255_/_0.38)_inset,0_4px_10px_color-mix(in_oklab,var(--accent)_18%,transparent)] focus-visible:outline-2 focus-visible:outline-fg focus-visible:outline-offset-2"
       >
-        <span
-          :key="likeAnimKey"
-          :class="
-            likesData?.userHasLiked
-              ? 'i-lucide:heart-minus fill-red-500 text-red-500'
-              : 'i-lucide:heart-plus'
-          "
-          :style="heartAnimStyle"
-          aria-hidden="true"
-          class="inline-block w-4 h-4"
-        />
-        <span
-          v-if="isLoadingLikeData"
-          class="i-svg-spinners:ring-resize w-3 h-3 my-0.5"
-          aria-hidden="true"
-        />
-        <span v-else>
-          {{ compactNumberFormatter.format(likesData?.totalLikes ?? 0) }}
-        </span>
-      </ButtonBase>
-    </div>
-  </TooltipApp>
+        <span>{{ $t('package.likes.top_rank_label', { rank: topLikedRank }) }}</span>
+      </NuxtLink>
+    </TooltipApp>
+  </div>
 </template>
 
-<style module>
-.likeWrapper {
-  position: relative;
-  display: inline-flex;
-}
-
-.likeFloat {
+<style scoped>
+.like-float {
   position: absolute;
   top: 0;
   left: 50%;
diff --git a/app/pages/leaderboard/likes.vue b/app/pages/leaderboard/likes.vue
new file mode 100644
index 0000000000..42244617ab
--- /dev/null
+++ b/app/pages/leaderboard/likes.vue
@@ -0,0 +1,91 @@
+<script setup lang="ts">
+import type { LikesLeaderboardEntry } from '#shared/types/social'
+
+useSeoMeta({
+  title: () => `${$t('leaderboard.likes.title')} - npmx`,
+  ogTitle: () => `${$t('leaderboard.likes.title')} - npmx`,
+  twitterTitle: () => `${$t('leaderboard.likes.title')} - npmx`,
+  description: () => $t('leaderboard.likes.description'),
+  ogDescription: () => $t('leaderboard.likes.description'),
+  twitterDescription: () => $t('leaderboard.likes.description'),
+})
+
+const compactNumberFormatter = useCompactNumberFormatter()
+
+const { data: leaderboardEntries } = await useFetch<LikesLeaderboardEntry[]>(
+  '/api/leaderboard/likes',
+  {
+    default: () => [],
+  },
+)
+</script>
+
+<template>
+  <main class="container flex-1 py-12 sm:py-16 overflow-x-hidden">
+    <article class="max-w-3xl mx-auto">
+      <header class="mb-10">
+        <div class="flex items-baseline justify-between gap-4 mb-4">
+          <h1 class="font-mono text-3xl sm:text-4xl font-medium">
+            {{ $t('leaderboard.likes.title') }}
+          </h1>
+          <BackButton />
+        </div>
+        <p class="text-fg-muted text-lg">
+          {{ $t('leaderboard.likes.description') }}
+        </p>
+      </header>
+
+      <BaseCard
+        v-if="leaderboardEntries.length === 0"
+        class="cursor-default hover:(border-border bg-bg-subtle)"
+      >
+        <h2 class="font-mono text-lg mb-2">
+          {{ $t('leaderboard.likes.unavailable_title') }}
+        </h2>
+        <p class="text-fg-muted">
+          {{ $t('leaderboard.likes.unavailable_description') }}
+        </p>
+      </BaseCard>
+
+      <ol v-else class="space-y-4 list-none m-0 p-0">
+        <li v-for="entry in leaderboardEntries" :key="entry.subjectRef">
+          <NuxtLink
+            :to="packageRoute(entry.packageName)"
+            class="block no-underline hover:no-underline"
+          >
+            <BaseCard class="flex items-center justify-between gap-4 min-w-0">
+              <div class="flex items-center gap-4 min-w-0">
+                <div
+                  aria-hidden="true"
+                  class="flex h-11 w-11 shrink-0 items-center justify-center rounded-full bg-amber-500/12 text-amber-700 font-mono text-sm dark:text-amber-300"
+                >
+                  #{{ entry.rank }}
+                </div>
+                <div class="min-w-0">
+                  <p class="text-xs uppercase tracking-wider text-fg-muted mb-1">
+                    {{ $t('leaderboard.likes.rank') }} {{ entry.rank }}
+                  </p>
+                  <p class="font-mono text-lg truncate" :title="entry.packageName">
+                    {{ entry.packageName }}
+                  </p>
+                </div>
+              </div>
+
+              <div class="flex items-center gap-3 shrink-0">
+                <div class="text-end">
+                  <p class="text-xs uppercase tracking-wider text-fg-muted mb-1">
+                    {{ $t('leaderboard.likes.likes') }}
+                  </p>
+                  <p class="font-mono text-lg">
+                    {{ compactNumberFormatter.format(entry.totalLikes) }}
+                  </p>
+                </div>
+                <span aria-hidden="true" class="text-fg-muted">↗</span>
+              </div>
+            </BaseCard>
+          </NuxtLink>
+        </li>
+      </ol>
+    </article>
+  </main>
+</template>
diff --git a/i18n/locales/en.json b/i18n/locales/en.json
index a142d1ab54..79d8d762cb 100644
--- a/i18n/locales/en.json
+++ b/i18n/locales/en.json
@@ -439,7 +439,10 @@
     },
     "likes": {
       "like": "Like this package",
-      "unlike": "Unlike this package"
+      "unlike": "Unlike this package",
+      "top_rank_tooltip": "This is in the top 10 most liked packages on npmx! (#{rank})",
+      "top_rank_label": "#{rank}",
+      "top_rank_link_label": "View likes leaderboard. This package is ranked #{rank}."
     },
     "docs": {
       "contents": "Contents",
@@ -761,6 +764,16 @@
       "tarball": "Download Tarball as .tar.gz"
     }
   },
+  "leaderboard": {
+    "likes": {
+      "title": "Likes Leaderboard",
+      "description": "The 10 most liked packages on npmx right now.",
+      "rank": "Rank",
+      "likes": "Likes",
+      "unavailable_title": "No likes leaderboard yet",
+      "unavailable_description": "We don't have a likes leaderboard to show right now."
+    }
+  },
   "connector": {
     "modal": {
       "title": "Local Connector",
diff --git a/i18n/locales/fr-FR.json b/i18n/locales/fr-FR.json
index b37ecd2bc5..aae02645f0 100644
--- a/i18n/locales/fr-FR.json
+++ b/i18n/locales/fr-FR.json
@@ -437,7 +437,10 @@
     },
     "likes": {
       "like": "Liker ce paquet",
-      "unlike": "Retirer le like"
+      "unlike": "Retirer le like",
+      "top_rank_tooltip": "Ce paquet figure parmi les 10 ayant le plus de likes sur npmx (n°{rank})",
+      "top_rank_label": "n°{rank}",
+      "top_rank_link_label": "Voir le classement des likes. Ce paquet est classé n°{rank}."
     },
     "docs": {
       "contents": "Sommaire",
@@ -759,6 +762,16 @@
       "tarball": "Télécharger le tarball au format .tar.gz"
     }
   },
+  "leaderboard": {
+    "likes": {
+      "title": "Classement des likes",
+      "description": "Les 10 paquets les plus likés sur npmx en ce moment.",
+      "rank": "Rang",
+      "likes": "Likes",
+      "unavailable_title": "Pas encore de classement des likes",
+      "unavailable_description": "Nous n'avons pas encore de classement des likes à afficher."
+    }
+  },
   "connector": {
     "modal": {
       "title": "Connecteur local",
diff --git a/i18n/schema.json b/i18n/schema.json
index b3ccd57f64..c18901d465 100644
--- a/i18n/schema.json
+++ b/i18n/schema.json
@@ -1323,6 +1323,15 @@
             },
             "unlike": {
               "type": "string"
+            },
+            "top_rank_tooltip": {
+              "type": "string"
+            },
+            "top_rank_label": {
+              "type": "string"
+            },
+            "top_rank_link_label": {
+              "type": "string"
             }
           },
           "additionalProperties": false
@@ -2287,6 +2296,36 @@
       },
       "additionalProperties": false
     },
+    "leaderboard": {
+      "type": "object",
+      "properties": {
+        "likes": {
+          "type": "object",
+          "properties": {
+            "title": {
+              "type": "string"
+            },
+            "description": {
+              "type": "string"
+            },
+            "rank": {
+              "type": "string"
+            },
+            "likes": {
+              "type": "string"
+            },
+            "unavailable_title": {
+              "type": "string"
+            },
+            "unavailable_description": {
+              "type": "string"
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
     "connector": {
       "type": "object",
       "properties": {
diff --git a/nuxt.config.ts b/nuxt.config.ts
index b80700e7f5..2194157395 100644
--- a/nuxt.config.ts
+++ b/nuxt.config.ts
@@ -168,6 +168,7 @@ export default defineNuxtConfig({
       },
     },
     // pages
+    '/leaderboard/likes': getISRConfig(900),
     '/package/**': getISRConfig(300, { fallback: 'html' }),
     '/package/:name/_payload.json': getISRConfig(300, { fallback: 'json' }),
     '/package/:name/v/:version/_payload.json': getISRConfig(300, { fallback: 'json' }),
diff --git a/server/api/leaderboard/likes.get.ts b/server/api/leaderboard/likes.get.ts
new file mode 100644
index 0000000000..c9f4acb8de
--- /dev/null
+++ b/server/api/leaderboard/likes.get.ts
@@ -0,0 +1,8 @@
+import { eventHandler } from 'h3'
+import type { LikesLeaderboardEntry } from '#shared/types/social'
+import { getLikesLeaderboard } from '#server/utils/likes-leaderboard'
+
+export default eventHandler(async (event): Promise<LikesLeaderboardEntry[]> => {
+  const leaderboard = await getLikesLeaderboard(event)
+  return leaderboard?.entries ?? []
+})
diff --git a/server/api/social/likes/[...pkg].get.ts b/server/api/social/likes/[...pkg].get.ts
index 654d5c6120..cb14a0f657 100644
--- a/server/api/social/likes/[...pkg].get.ts
+++ b/server/api/social/likes/[...pkg].get.ts
@@ -1,5 +1,7 @@
 import * as v from 'valibot'
 import { PackageRouteParamsSchema } from '#shared/schemas/package'
+import { PACKAGE_SUBJECT_REF } from '#shared/utils/constants'
+import { getTopLikedRank } from '#server/utils/likes-leaderboard'
 
 /**
  * GET /api/social/likes/:name
@@ -23,7 +25,15 @@ export default eventHandlerWithOAuthSession(async (event, oAuthSession, _) => {
     })
 
     const likesUtil = new PackageLikesUtils()
-    return await likesUtil.getLikes(packageName, oAuthSession?.did.toString())
+    const [likes, topLikedRank] = await Promise.all([
+      likesUtil.getLikes(packageName, oAuthSession?.did.toString()),
+      getTopLikedRank(event, PACKAGE_SUBJECT_REF(packageName)),
+    ])
+
+    return {
+      ...likes,
+      topLikedRank,
+    }
   } catch (error: unknown) {
     handleApiError(error, {
       statusCode: 502,
diff --git a/server/utils/atproto/utils/likes.ts b/server/utils/atproto/utils/likes.ts
index 5e80ee2d4f..c583f135fc 100644
--- a/server/utils/atproto/utils/likes.ts
+++ b/server/utils/atproto/utils/likes.ts
@@ -144,8 +144,9 @@ export class PackageLikesUtils {
     }
 
     return {
-      totalLikes: totalLikes,
+      totalLikes,
       userHasLiked,
+      topLikedRank: null,
     }
   }
 
@@ -209,8 +210,9 @@ export class PackageLikesUtils {
     // We already know the user has not liked the package before so set in the cache
     await this.cache.set(CACHE_USER_LIKES_KEY(packageName, usersDid), true, CACHE_MAX_AGE)
     return {
-      totalLikes: totalLikes,
+      totalLikes,
       userHasLiked: true,
+      topLikedRank: null,
     }
   }
 
@@ -278,8 +280,9 @@ export class PackageLikesUtils {
     await this.cache.delete(CACHE_USERS_BACK_LINK(packageName, usersDid))
 
     return {
-      totalLikes: totalLikes,
+      totalLikes,
       userHasLiked: false,
+      topLikedRank: null,
     }
   }
 
diff --git a/server/utils/likes-leaderboard.ts b/server/utils/likes-leaderboard.ts
new file mode 100644
index 0000000000..af5a5d0e2a
--- /dev/null
+++ b/server/utils/likes-leaderboard.ts
@@ -0,0 +1,123 @@
+import type { H3Event } from 'h3'
+import * as v from 'valibot'
+import type { LikesLeaderboardEntry } from '#shared/types/social'
+import type { CachedFetchFunction } from '#shared/utils/fetch-cache-config'
+import { CACHE_MAX_AGE_ONE_HOUR, LIKES_LEADERBOARD_API_URL } from '#shared/utils/constants'
+
+const UpstreamLikesLeaderboardEntrySchema = v.object({
+  subjectRef: v.string(),
+  totalLikes: v.number(),
+})
+
+const UpstreamLikesLeaderboardResponseSchema = v.object({
+  totalLikes: v.optional(v.number()),
+  totalUniqueLikers: v.optional(v.number()),
+  leaderBoard: v.array(UpstreamLikesLeaderboardEntrySchema),
+})
+
+type UpstreamLikesLeaderboardResponse = v.InferOutput<typeof UpstreamLikesLeaderboardResponseSchema>
+
+export type ResolvedLikesLeaderboard = {
+  totalLikes: number | null
+  totalUniqueLikers: number | null
+  entries: LikesLeaderboardEntry[]
+}
+
+const LIKES_LEADERBOARD_FETCH_TIMEOUT_MS = 750
+
+type LikesLeaderboardOptions = {
+  timeoutMs?: number
+}
+
+export const LIKES_LEADERBOARD_MAX_ENTRIES = 10
+
+export function extractPackageNameFromSubjectRef(subjectRef: string): string | null {
+  const match = /^https:\/\/npmx\.dev\/package\/(.+)$/.exec(subjectRef)
+  if (!match?.[1]) return null
+
+  try {
+    return decodeURIComponent(match[1])
+  } catch {
+    return match[1]
+  }
+}
+
+export function normalizeLikesLeaderboardPayload(
+  payload: unknown,
+): ResolvedLikesLeaderboard | null {
+  const parsedPayload = v.safeParse(UpstreamLikesLeaderboardResponseSchema, payload)
+  if (!parsedPayload.success) {
+    return null
+  }
+
+  // PRECONDITION: the response is already sorted by totalLikes in descending order
+  const entries = parsedPayload.output.leaderBoard
+    .map((entry): LikesLeaderboardEntry | null => {
+      const packageName = extractPackageNameFromSubjectRef(entry.subjectRef)
+      if (!packageName) return null
+
+      return {
+        rank: 0,
+        packageName,
+        subjectRef: entry.subjectRef,
+        totalLikes: entry.totalLikes,
+      }
+    })
+    .filter((entry): entry is LikesLeaderboardEntry => entry !== null)
+    // oxlint-disable-next-line no-map-spread -- only a few elements
+    .map((entry, index) => ({
+      ...entry,
+      rank: index + 1,
+    }))
+
+  return {
+    totalLikes: parsedPayload.output.totalLikes ?? null,
+    totalUniqueLikers: parsedPayload.output.totalUniqueLikers ?? null,
+    entries,
+  }
+}
+
+export async function getLikesLeaderboard(
+  event: H3Event,
+  options: LikesLeaderboardOptions = {},
+): Promise<ResolvedLikesLeaderboard | null> {
+  const timeoutMs = options.timeoutMs ?? LIKES_LEADERBOARD_FETCH_TIMEOUT_MS
+  const cachedFetch = event.context.cachedFetch as CachedFetchFunction | undefined
+  if (!cachedFetch) {
+    console.error('Something went wrong: event.context.cachedFetch is missing. Aborting fetch.', {
+      eventContext: event.context,
+    })
+    return null
+  }
+
+  try {
+    const url = new URL(LIKES_LEADERBOARD_API_URL)
+    url.searchParams.set('limit', LIKES_LEADERBOARD_MAX_ENTRIES.toString())
+
+    const { data } = await cachedFetch<UpstreamLikesLeaderboardResponse>(
+      url.toString(),
+      {
+        headers: {
+          'User-Agent': 'npmx',
+          'Accept': 'application/json',
+        },
+        signal: AbortSignal.timeout(timeoutMs),
+      },
+      CACHE_MAX_AGE_ONE_HOUR,
+    )
+
+    return normalizeLikesLeaderboardPayload(data)
+  } catch (err) {
+    console.error('Failed to fetch likes leaderboard', { err })
+    return null
+  }
+}
+
+export async function getTopLikedRank(
+  event: H3Event,
+  subjectRef: string,
+  options: LikesLeaderboardOptions = {},
+): Promise<number | null> {
+  const leaderboard = await getLikesLeaderboard(event, options)
+  return leaderboard?.entries.find(entry => entry.subjectRef === subjectRef)?.rank ?? null
+}
diff --git a/shared/types/social.ts b/shared/types/social.ts
index 22002caa30..16044da356 100644
--- a/shared/types/social.ts
+++ b/shared/types/social.ts
@@ -6,6 +6,15 @@ export type PackageLikes = {
   totalLikes: number
   // If the logged in user has liked the package, false if not logged in
   userHasLiked: boolean
+  // Top-likes leaderboard rank if the package is in the top 10
+  topLikedRank: number | null
+}
+
+export type LikesLeaderboardEntry = {
+  rank: number
+  packageName: string
+  subjectRef: string
+  totalLikes: number
 }
 
 /**
diff --git a/shared/utils/constants.ts b/shared/utils/constants.ts
index 72aa92148e..ad9d2de1d8 100644
--- a/shared/utils/constants.ts
+++ b/shared/utils/constants.ts
@@ -15,6 +15,9 @@ export const BLUESKY_API = 'https://public.api.bsky.app'
 export const BLUESKY_COMMENTS_REQUEST = '/api/atproto/bluesky-comments'
 export const NPM_REGISTRY = 'https://registry.npmjs.org'
 export const NPM_API = 'https://api.npmjs.org'
+// Repo: https://tangled.org/baileytownsend.dev/npmx-likes-leaderboard
+export const LIKES_LEADERBOARD_API_URL =
+  'https://npmx-likes-leaderboard-api-production.up.railway.app/api/leaderboard/likes'
 // Error Messages
 export const ERROR_PACKAGE_ANALYSIS_FAILED = 'Failed to analyze package.'
 export const ERROR_PACKAGE_VERSION_AND_FILE_FAILED = 'Version and file path are required.'
diff --git a/shared/utils/fetch-cache-config.ts b/shared/utils/fetch-cache-config.ts
index 83c1467437..c265fcdbf3 100644
--- a/shared/utils/fetch-cache-config.ts
+++ b/shared/utils/fetch-cache-config.ts
@@ -5,7 +5,7 @@
  * using Nitro's storage layer (backed by Vercel's runtime cache in production).
  */
 
-import { CONSTELLATION_HOST, SLINGSHOT_HOST } from './constants'
+import { CONSTELLATION_HOST, LIKES_LEADERBOARD_API_URL, SLINGSHOT_HOST } from './constants'
 
 /**
  * Domains that should have their fetch responses cached.
@@ -29,6 +29,7 @@ export const FETCH_CACHE_ALLOWED_DOMAINS = [
   // microcosm endpoints for atproto data
   CONSTELLATION_HOST,
   SLINGSHOT_HOST,
+  new URL(LIKES_LEADERBOARD_API_URL).host,
 ] as const
 
 /**
diff --git a/test/nuxt/a11y.spec.ts b/test/nuxt/a11y.spec.ts
index b028e55564..052b46fd68 100644
--- a/test/nuxt/a11y.spec.ts
+++ b/test/nuxt/a11y.spec.ts
@@ -1,5 +1,5 @@
 import type { ColumnConfig, FilterChip } from '#shared/types/preferences'
-import { mountSuspended } from '@nuxt/test-utils/runtime'
+import { mountSuspended, registerEndpoint } from '@nuxt/test-utils/runtime'
 import type { VueWrapper } from '@vue/test-utils'
 import 'axe-core'
 import type { AxeResults, RunOptions } from 'axe-core'
@@ -276,6 +276,7 @@ import FacetQuadrantChart from '~/components/Compare/FacetQuadrantChart.vue'
 import PackageLikeCard from '~/components/Package/LikeCard.vue'
 import SizeIncrease from '~/components/Package/SizeIncrease.vue'
 import Likes from '~/components/Package/Likes.vue'
+import LikesLeaderboardPage from '~/pages/leaderboard/likes.vue'
 import type { VueUiXyDatasetItem } from 'vue-data-ui'
 
 describe('component accessibility audits', () => {
@@ -687,6 +688,71 @@ describe('component accessibility audits', () => {
       const results = await runAxe(component)
       expect(results.violations).toEqual([])
     })
+
+    it('should have no accessibility violations with the top-liked badge visible', async () => {
+      registerEndpoint('/api/social/likes/lodash', () => ({
+        totalLikes: 42,
+        userHasLiked: false,
+        topLikedRank: 3,
+      }))
+
+      const component = await mountSuspended(Likes, {
+        props: { packageName: 'lodash' },
+      })
+
+      // Likes fetches client-side (`server: false`), so wait for the fetched badge
+      // state before running axe against the rendered variant.
+      await vi.waitFor(() => {
+        expect(component.text()).toContain('#3')
+      })
+
+      const results = await runAxe(component)
+      expect(results.violations).toEqual([])
+    })
+  })
+
+  describe('LikesLeaderboardPage', () => {
+    it('should have no accessibility violations when data is available', async () => {
+      // This page remounts the same useFetch source with different mocked responses
+      // across tests, so reset Nuxt's async-data store between cases.
+      clearNuxtData()
+      registerEndpoint('/api/leaderboard/likes', () => [
+        {
+          rank: 1,
+          packageName: 'vue',
+          subjectRef: 'https://npmx.dev/package/vue',
+          totalLikes: 120,
+        },
+        {
+          rank: 2,
+          packageName: '@nuxt/kit',
+          subjectRef: 'https://npmx.dev/package/@nuxt/kit',
+          totalLikes: 90,
+        },
+      ])
+
+      const component = await mountSuspended(LikesLeaderboardPage, {
+        route: '/leaderboard/likes',
+      })
+
+      expect(component.text()).toContain('Likes Leaderboard')
+      expect(component.text()).toContain('vue')
+      const results = await runAxe(component)
+      expect(results.violations).toEqual([])
+    })
+
+    it('should have no accessibility violations when unavailable', async () => {
+      clearNuxtData()
+      registerEndpoint('/api/leaderboard/likes', () => [])
+
+      const component = await mountSuspended(LikesLeaderboardPage, {
+        route: '/leaderboard/likes',
+      })
+
+      expect(component.text()).toContain('No likes leaderboard yet')
+      const results = await runAxe(component)
+      expect(results.violations).toEqual([])
+    })
   })
 
   describe('TagRadioButton', () => {
diff --git a/test/nuxt/components/Package/Likes.spec.ts b/test/nuxt/components/Package/Likes.spec.ts
new file mode 100644
index 0000000000..3a8d3b8f8d
--- /dev/null
+++ b/test/nuxt/components/Package/Likes.spec.ts
@@ -0,0 +1,58 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { mountSuspended, registerEndpoint } from '@nuxt/test-utils/runtime'
+import type { VueWrapper } from '@vue/test-utils'
+import Likes from '~/components/Package/Likes.vue'
+
+describe('PackageLikes', () => {
+  let wrapper: VueWrapper | undefined
+
+  afterEach(() => {
+    wrapper?.unmount()
+  })
+
+  it('renders the top liked badge with rank and leaderboard link', async () => {
+    registerEndpoint('/api/social/likes/vue', () => ({
+      totalLikes: 42,
+      userHasLiked: false,
+      topLikedRank: 3,
+    }))
+
+    wrapper = await mountSuspended(Likes, {
+      props: { packageName: 'vue' },
+      attachTo: document.body,
+    })
+
+    // Likes fetches client-side (`server: false`), so the mounted component needs
+    // to wait for the post-mount request to resolve before asserting on fetched UI.
+    await vi.waitFor(() => {
+      expect(wrapper?.text()).toContain('42')
+      expect(wrapper?.find('[data-testid="top-liked-badge"]').exists()).toBe(true)
+    })
+
+    const badge = wrapper.find('[data-testid="top-liked-badge"]')
+    expect(badge.text()).toContain('#3')
+    expect(badge.attributes('href')).toBe('/leaderboard/likes')
+    expect(badge.attributes('aria-label')).toBe(
+      'View likes leaderboard. This package is ranked #3.',
+    )
+  })
+
+  it('does not render the top liked badge when rank is unavailable', async () => {
+    registerEndpoint('/api/social/likes/react', () => ({
+      totalLikes: 42,
+      userHasLiked: false,
+      topLikedRank: null,
+    }))
+
+    wrapper = await mountSuspended(Likes, {
+      props: { packageName: 'react' },
+      attachTo: document.body,
+    })
+
+    await vi.waitFor(() => {
+      expect(wrapper?.text()).toContain('42')
+    })
+
+    expect(wrapper.find('[data-testid="top-liked-badge"]').exists()).toBe(false)
+  })
+})
diff --git a/test/nuxt/pages/LikesLeaderboardPage.spec.ts b/test/nuxt/pages/LikesLeaderboardPage.spec.ts
new file mode 100644
index 0000000000..620e3cd347
--- /dev/null
+++ b/test/nuxt/pages/LikesLeaderboardPage.spec.ts
@@ -0,0 +1,56 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { mountSuspended, registerEndpoint } from '@nuxt/test-utils/runtime'
+import type { VueWrapper } from '@vue/test-utils'
+import LikesLeaderboardPage from '~/pages/leaderboard/likes.vue'
+
+describe('likes leaderboard page', () => {
+  let wrapper: VueWrapper | undefined
+
+  beforeEach(() => {
+    // This page remounts the same useFetch source with different mocked responses
+    // across tests, so reset Nuxt's async-data store between cases.
+    clearNuxtData()
+  })
+
+  afterEach(() => {
+    wrapper?.unmount()
+  })
+
+  it('renders ranked rows from the local leaderboard API', async () => {
+    registerEndpoint('/api/leaderboard/likes', () => [
+      {
+        rank: 1,
+        packageName: 'vue',
+        subjectRef: 'https://npmx.dev/package/vue',
+        totalLikes: 120,
+      },
+      {
+        rank: 2,
+        packageName: '@nuxt/kit',
+        subjectRef: 'https://npmx.dev/package/@nuxt/kit',
+        totalLikes: 90,
+      },
+    ])
+
+    wrapper = await mountSuspended(LikesLeaderboardPage, {
+      route: '/leaderboard/likes',
+    })
+
+    expect(wrapper.text()).toContain('Likes Leaderboard')
+    expect(wrapper.text()).toContain('vue')
+    expect(wrapper.text()).toContain('@nuxt/kit')
+    expect(wrapper.text()).toContain('#1')
+    expect(wrapper.find('a[href="/package/vue"]').exists()).toBe(true)
+  })
+
+  it('renders the unavailable state when the local leaderboard API is unavailable', async () => {
+    registerEndpoint('/api/leaderboard/likes', () => [])
+
+    wrapper = await mountSuspended(LikesLeaderboardPage, {
+      route: '/leaderboard/likes',
+    })
+
+    expect(wrapper.text()).toContain('No likes leaderboard yet')
+    expect(wrapper.text()).toContain("We don't have a likes leaderboard to show right now.")
+  })
+})
diff --git a/test/unit/server/utils/likes-leaderboard.spec.ts b/test/unit/server/utils/likes-leaderboard.spec.ts
new file mode 100644
index 0000000000..67ccd52d0a
--- /dev/null
+++ b/test/unit/server/utils/likes-leaderboard.spec.ts
@@ -0,0 +1,124 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import {
+  extractPackageNameFromSubjectRef,
+  normalizeLikesLeaderboardPayload,
+  getLikesLeaderboard,
+  getTopLikedRank,
+} from '#server/utils/likes-leaderboard'
+
+type TestEvent = Parameters<typeof getLikesLeaderboard>[0]
+type TestCachedFetch = NonNullable<TestEvent['context']['cachedFetch']>
+
+function createEvent(cachedFetch: TestCachedFetch): TestEvent {
+  return {
+    context: { cachedFetch },
+  } as TestEvent
+}
+
+beforeEach(() => {
+  vi.clearAllMocks()
+})
+
+describe('extractPackageNameFromSubjectRef', () => {
+  it('extracts package names from package subject refs', () => {
+    expect(extractPackageNameFromSubjectRef('https://npmx.dev/package/vue')).toBe('vue')
+    expect(extractPackageNameFromSubjectRef('https://npmx.dev/package/@scope/pkg')).toBe(
+      '@scope/pkg',
+    )
+    expect(extractPackageNameFromSubjectRef('https://example.com/not-npmx')).toBeNull()
+  })
+})
+
+describe('normalizeLikesLeaderboardPayload', () => {
+  it('normalizes upstream leaderboard payload into ranked entries', () => {
+    const result = normalizeLikesLeaderboardPayload({
+      totalLikes: 320,
+      totalUniqueLikers: 75,
+      leaderBoard: [
+        { subjectRef: 'https://npmx.dev/package/vue', totalLikes: 120 },
+        { subjectRef: 'https://npmx.dev/package/@nuxt/kit', totalLikes: 90 },
+      ],
+    })
+
+    expect(result).toEqual({
+      totalLikes: 320,
+      totalUniqueLikers: 75,
+      entries: [
+        {
+          rank: 1,
+          packageName: 'vue',
+          subjectRef: 'https://npmx.dev/package/vue',
+          totalLikes: 120,
+        },
+        {
+          rank: 2,
+          packageName: '@nuxt/kit',
+          subjectRef: 'https://npmx.dev/package/@nuxt/kit',
+          totalLikes: 90,
+        },
+      ],
+    })
+  })
+
+  it('returns null for invalid upstream payloads', () => {
+    expect(normalizeLikesLeaderboardPayload({ totalLikes: 10 })).toBeNull()
+  })
+})
+
+describe('getLikesLeaderboard', () => {
+  it('returns null when the upstream fetch fails', async () => {
+    const cachedFetch = vi.fn().mockRejectedValue(new Error('boom'))
+
+    const result = await getLikesLeaderboard(createEvent(cachedFetch))
+
+    expect(result).toBeNull()
+    expect(cachedFetch).toHaveBeenCalledOnce()
+  })
+
+  it('fetches from the external leaderboard API with limit=10', async () => {
+    const cachedFetch = vi.fn().mockResolvedValue({
+      data: {
+        totalLikes: 320,
+        totalUniqueLikers: 75,
+        leaderBoard: [{ subjectRef: 'https://npmx.dev/package/vue', totalLikes: 120 }],
+      },
+      isStale: false,
+      cachedAt: null,
+    })
+
+    await getLikesLeaderboard(createEvent(cachedFetch))
+
+    expect(cachedFetch).toHaveBeenCalledWith(
+      'https://npmx-likes-leaderboard-api-production.up.railway.app/api/leaderboard/likes?limit=10',
+      expect.objectContaining({
+        headers: {
+          'User-Agent': 'npmx',
+          'Accept': 'application/json',
+        },
+        signal: expect.any(AbortSignal),
+      }),
+      3600,
+    )
+  })
+})
+
+describe('getTopLikedRank', () => {
+  it('returns the matching top liked rank for a subject ref', async () => {
+    const cachedFetch = vi.fn().mockResolvedValue({
+      data: {
+        totalLikes: 320,
+        totalUniqueLikers: 75,
+        leaderBoard: [
+          { subjectRef: 'https://npmx.dev/package/vue', totalLikes: 120 },
+          { subjectRef: 'https://npmx.dev/package/nuxt', totalLikes: 90 },
+        ],
+      },
+      isStale: false,
+      cachedAt: null,
+    })
+
+    const rank = await getTopLikedRank(createEvent(cachedFetch), 'https://npmx.dev/package/nuxt')
+
+    expect(rank).toBe(2)
+  })
+})

From b4b05d2e989c0b800a916731cc3749f728514c11 Mon Sep 17 00:00:00 2001
From: Philippe Serhal <philippe.serhal@gmail.com>
Date: Fri, 10 Apr 2026 10:29:54 -0400
Subject: [PATCH 2/2] fix: simplify some things

---
 app/components/Package/Likes.vue              | 25 ++---
 server/api/leaderboard/likes.get.ts           |  3 +-
 server/utils/likes-leaderboard.ts             | 91 +++++++------------
 .../server/utils/likes-leaderboard.spec.ts    | 38 +++-----
 4 files changed, 56 insertions(+), 101 deletions(-)

diff --git a/app/components/Package/Likes.vue b/app/components/Package/Likes.vue
index bbf10280f3..1b79c91f2b 100644
--- a/app/components/Package/Likes.vue
+++ b/app/components/Package/Likes.vue
@@ -111,23 +111,16 @@ const likeAction = async () => {
 
   try {
     const result = await togglePackageLike(props.packageName, currentlyLiked, user.value?.handle)
-
-    isLikeActionPending.value = false
-
-    if (result.success) {
-      // Update with server response
-      likesData.value = {
-        ...previousLikesState,
-        ...result.data,
-        topLikedRank: result.data.topLikedRank ?? previousLikesState.topLikedRank,
-      }
-    } else {
-      // Revert on error
-      likesData.value = previousLikesState
-    }
+    likesData.value = result.success
+      ? {
+          ...previousLikesState,
+          ...result.data,
+          topLikedRank: result.data.topLikedRank ?? previousLikesState.topLikedRank,
+        }
+      : previousLikesState
   } catch {
-    // Revert on error
     likesData.value = previousLikesState
+  } finally {
     isLikeActionPending.value = false
   }
 }
@@ -203,7 +196,7 @@ const likeAction = async () => {
 }
 
 @media (prefers-reduced-motion: reduce) {
-  .likeFloat {
+  .like-float {
     display: none;
   }
 }
diff --git a/server/api/leaderboard/likes.get.ts b/server/api/leaderboard/likes.get.ts
index c9f4acb8de..6978f562f5 100644
--- a/server/api/leaderboard/likes.get.ts
+++ b/server/api/leaderboard/likes.get.ts
@@ -3,6 +3,5 @@ import type { LikesLeaderboardEntry } from '#shared/types/social'
 import { getLikesLeaderboard } from '#server/utils/likes-leaderboard'
 
 export default eventHandler(async (event): Promise<LikesLeaderboardEntry[]> => {
-  const leaderboard = await getLikesLeaderboard(event)
-  return leaderboard?.entries ?? []
+  return (await getLikesLeaderboard(event)) ?? []
 })
diff --git a/server/utils/likes-leaderboard.ts b/server/utils/likes-leaderboard.ts
index af5a5d0e2a..6633104092 100644
--- a/server/utils/likes-leaderboard.ts
+++ b/server/utils/likes-leaderboard.ts
@@ -10,25 +10,11 @@ const UpstreamLikesLeaderboardEntrySchema = v.object({
 })
 
 const UpstreamLikesLeaderboardResponseSchema = v.object({
-  totalLikes: v.optional(v.number()),
-  totalUniqueLikers: v.optional(v.number()),
   leaderBoard: v.array(UpstreamLikesLeaderboardEntrySchema),
 })
 
-type UpstreamLikesLeaderboardResponse = v.InferOutput<typeof UpstreamLikesLeaderboardResponseSchema>
-
-export type ResolvedLikesLeaderboard = {
-  totalLikes: number | null
-  totalUniqueLikers: number | null
-  entries: LikesLeaderboardEntry[]
-}
-
 const LIKES_LEADERBOARD_FETCH_TIMEOUT_MS = 750
 
-type LikesLeaderboardOptions = {
-  timeoutMs?: number
-}
-
 export const LIKES_LEADERBOARD_MAX_ENTRIES = 10
 
 export function extractPackageNameFromSubjectRef(subjectRef: string): string | null {
@@ -42,51 +28,39 @@ export function extractPackageNameFromSubjectRef(subjectRef: string): string | n
   }
 }
 
-export function normalizeLikesLeaderboardPayload(
-  payload: unknown,
-): ResolvedLikesLeaderboard | null {
+export function normalizeLikesLeaderboardPayload(payload: unknown): LikesLeaderboardEntry[] | null {
   const parsedPayload = v.safeParse(UpstreamLikesLeaderboardResponseSchema, payload)
   if (!parsedPayload.success) {
     return null
   }
 
   // PRECONDITION: the response is already sorted by totalLikes in descending order
-  const entries = parsedPayload.output.leaderBoard
-    .map((entry): LikesLeaderboardEntry | null => {
-      const packageName = extractPackageNameFromSubjectRef(entry.subjectRef)
-      if (!packageName) return null
-
-      return {
-        rank: 0,
-        packageName,
-        subjectRef: entry.subjectRef,
-        totalLikes: entry.totalLikes,
-      }
-    })
-    .filter((entry): entry is LikesLeaderboardEntry => entry !== null)
-    // oxlint-disable-next-line no-map-spread -- only a few elements
-    .map((entry, index) => ({
-      ...entry,
-      rank: index + 1,
-    }))
-
-  return {
-    totalLikes: parsedPayload.output.totalLikes ?? null,
-    totalUniqueLikers: parsedPayload.output.totalUniqueLikers ?? null,
-    entries,
-  }
+  return (
+    parsedPayload.output.leaderBoard
+      .map((entry): LikesLeaderboardEntry | null => {
+        const packageName = extractPackageNameFromSubjectRef(entry.subjectRef)
+        if (!packageName) return null
+
+        return {
+          rank: 0,
+          packageName,
+          subjectRef: entry.subjectRef,
+          totalLikes: entry.totalLikes,
+        }
+      })
+      .filter((entry): entry is LikesLeaderboardEntry => entry !== null)
+      // oxlint-disable-next-line no-map-spread -- only a few elements
+      .map((entry, index) => ({
+        ...entry,
+        rank: index + 1,
+      }))
+  )
 }
 
-export async function getLikesLeaderboard(
-  event: H3Event,
-  options: LikesLeaderboardOptions = {},
-): Promise<ResolvedLikesLeaderboard | null> {
-  const timeoutMs = options.timeoutMs ?? LIKES_LEADERBOARD_FETCH_TIMEOUT_MS
+export async function getLikesLeaderboard(event: H3Event): Promise<LikesLeaderboardEntry[] | null> {
   const cachedFetch = event.context.cachedFetch as CachedFetchFunction | undefined
   if (!cachedFetch) {
-    console.error('Something went wrong: event.context.cachedFetch is missing. Aborting fetch.', {
-      eventContext: event.context,
-    })
+    console.error('[likes-leaderboard] Missing cachedFetch in request context')
     return null
   }
 
@@ -94,30 +68,29 @@ export async function getLikesLeaderboard(
     const url = new URL(LIKES_LEADERBOARD_API_URL)
     url.searchParams.set('limit', LIKES_LEADERBOARD_MAX_ENTRIES.toString())
 
-    const { data } = await cachedFetch<UpstreamLikesLeaderboardResponse>(
+    const { data } = await cachedFetch(
       url.toString(),
       {
         headers: {
           'User-Agent': 'npmx',
           'Accept': 'application/json',
         },
-        signal: AbortSignal.timeout(timeoutMs),
+        signal: AbortSignal.timeout(LIKES_LEADERBOARD_FETCH_TIMEOUT_MS),
       },
       CACHE_MAX_AGE_ONE_HOUR,
     )
 
     return normalizeLikesLeaderboardPayload(data)
   } catch (err) {
-    console.error('Failed to fetch likes leaderboard', { err })
+    console.error(
+      '[likes-leaderboard] Failed to fetch likes leaderboard:',
+      err instanceof Error ? err.message : 'Unknown error',
+    )
     return null
   }
 }
 
-export async function getTopLikedRank(
-  event: H3Event,
-  subjectRef: string,
-  options: LikesLeaderboardOptions = {},
-): Promise<number | null> {
-  const leaderboard = await getLikesLeaderboard(event, options)
-  return leaderboard?.entries.find(entry => entry.subjectRef === subjectRef)?.rank ?? null
+export async function getTopLikedRank(event: H3Event, subjectRef: string): Promise<number | null> {
+  const leaderboard = await getLikesLeaderboard(event)
+  return leaderboard?.find(entry => entry.subjectRef === subjectRef)?.rank ?? null
 }
diff --git a/test/unit/server/utils/likes-leaderboard.spec.ts b/test/unit/server/utils/likes-leaderboard.spec.ts
index 67ccd52d0a..6f7464b672 100644
--- a/test/unit/server/utils/likes-leaderboard.spec.ts
+++ b/test/unit/server/utils/likes-leaderboard.spec.ts
@@ -32,32 +32,26 @@ describe('extractPackageNameFromSubjectRef', () => {
 describe('normalizeLikesLeaderboardPayload', () => {
   it('normalizes upstream leaderboard payload into ranked entries', () => {
     const result = normalizeLikesLeaderboardPayload({
-      totalLikes: 320,
-      totalUniqueLikers: 75,
       leaderBoard: [
         { subjectRef: 'https://npmx.dev/package/vue', totalLikes: 120 },
         { subjectRef: 'https://npmx.dev/package/@nuxt/kit', totalLikes: 90 },
       ],
     })
 
-    expect(result).toEqual({
-      totalLikes: 320,
-      totalUniqueLikers: 75,
-      entries: [
-        {
-          rank: 1,
-          packageName: 'vue',
-          subjectRef: 'https://npmx.dev/package/vue',
-          totalLikes: 120,
-        },
-        {
-          rank: 2,
-          packageName: '@nuxt/kit',
-          subjectRef: 'https://npmx.dev/package/@nuxt/kit',
-          totalLikes: 90,
-        },
-      ],
-    })
+    expect(result).toEqual([
+      {
+        rank: 1,
+        packageName: 'vue',
+        subjectRef: 'https://npmx.dev/package/vue',
+        totalLikes: 120,
+      },
+      {
+        rank: 2,
+        packageName: '@nuxt/kit',
+        subjectRef: 'https://npmx.dev/package/@nuxt/kit',
+        totalLikes: 90,
+      },
+    ])
   })
 
   it('returns null for invalid upstream payloads', () => {
@@ -78,8 +72,6 @@ describe('getLikesLeaderboard', () => {
   it('fetches from the external leaderboard API with limit=10', async () => {
     const cachedFetch = vi.fn().mockResolvedValue({
       data: {
-        totalLikes: 320,
-        totalUniqueLikers: 75,
         leaderBoard: [{ subjectRef: 'https://npmx.dev/package/vue', totalLikes: 120 }],
       },
       isStale: false,
@@ -106,8 +98,6 @@ describe('getTopLikedRank', () => {
   it('returns the matching top liked rank for a subject ref', async () => {
     const cachedFetch = vi.fn().mockResolvedValue({
       data: {
-        totalLikes: 320,
-        totalUniqueLikers: 75,
         leaderBoard: [
           { subjectRef: 'https://npmx.dev/package/vue', totalLikes: 120 },
           { subjectRef: 'https://npmx.dev/package/nuxt', totalLikes: 90 },