feat: show number of social mentions on package page

app/components/Package/Header.vue

@@ -250,6 +250,7 @@ useShortcuts({
       <!-- Package metrics -->
       <div class="flex gap-2 flex-wrap items-stretch">
         <PackageLikes :packageName />
+        <PackageSocialMentions :packageName />
 
         <LinkBase
           variant="button-secondary"

app/components/Package/SocialMentions.vue

@@ -0,0 +1,61 @@
+<script lang="ts" setup>
+import type { PackageSocialMentions } from '#shared/types/social'
+import { packageSubjectRef, SOCIAL_MENTIONS_MAX } from '#shared/utils/constants'
+
+const props = defineProps<{
+  packageName: string
+}>()
+
+const compactNumberFormatter = useCompactNumberFormatter()
+
+const {
+  data: mentionsData,
+  status,
+  execute: fetchMentions,
+} = useLazyFetch<PackageSocialMentions>(() => `/api/social/mentions/${props.packageName}`, {
+  default: () => ({ totalMentions: 0, isCapped: false }),
+  server: false,
+  immediate: false,
+})
+
+// Client-only: this decorative stat should never block SSR.
+if (import.meta.client) {
+  watch(
+    () => props.packageName,
+    packageName => {
+      if (packageName) fetchMentions()
+    },
+    { immediate: true },
+  )
+}
+
+const totalMentions = computed(() => mentionsData.value?.totalMentions ?? 0)
+const isCapped = computed(() => mentionsData.value?.isCapped ?? false)
+const displayCount = computed(() =>
+  isCapped.value
+    ? `${SOCIAL_MENTIONS_MAX}+`
+    : compactNumberFormatter.value.format(totalMentions.value),
+)
+const isLoading = computed(() => status.value === 'pending' || status.value === 'idle')
+// Search the exact npmx.dev URL to avoid noisy matches on package names like "react".
+const searchUrl = computed(
+  () => `https://bsky.app/search?q=${encodeURIComponent(packageSubjectRef(props.packageName))}`,
+)
+const label = computed(() =>
+  $t('package.social_mentions.label', { count: displayCount.value }, totalMentions.value),
+)
+</script>
+
+<template>
+  <LinkBase
+    variant="button-secondary"
+    classicon="i-lucide:message-circle"
+    :to="searchUrl"
+    :aria-label="isLoading ? $t('common.loading') : label"
+    data-testid="social-mentions"
+    class="min-w-36"
+  >
+    <span v-if="isLoading" class="i-svg-spinners:ring-resize w-3 h-3" aria-hidden="true" />
+    <span v-else>{{ label }}</span>
+  </LinkBase>
+</template>

i18n/locales/en.json

@@ -555,6 +555,9 @@
       "top_rank_label": "#{rank}",
       "top_rank_link_label": "View likes leaderboard. This package is ranked #{rank}."
     },
+    "social_mentions": {
+      "label": "{count} mention | {count} mentions"
+    },
     "docs": {
       "contents": "Contents",
       "default_not_available": "Docs are not available for this version.",

i18n/locales/fr-FR.json

@@ -453,6 +453,9 @@
       "top_rank_label": "n°{rank}",
       "top_rank_link_label": "Voir le classement des likes. Ce paquet est classé n°{rank}."
     },
+    "social_mentions": {
+      "label": "{count} mention | {count} mention | {count} mentions"
+    },
     "docs": {
       "contents": "Sommaire",
       "default_not_available": "La documentation n'est pas disponible pour cette version.",

i18n/schema.json

@@ -1669,6 +1669,15 @@
           },
           "additionalProperties": false
         },
+        "social_mentions": {
+          "type": "object",
+          "properties": {
+            "label": {
+              "type": "string"
+            }
+          },
+          "additionalProperties": false
+        },
         "docs": {
           "type": "object",
           "properties": {

server/api/social/like.post.ts

@@ -26,7 +26,7 @@ export default eventHandlerWithOAuthSession(async (event, oAuthSession) => {
     return likesResult
   }
 
-  const subjectRef = PACKAGE_SUBJECT_REF(body.packageName)
+  const subjectRef = packageSubjectRef(body.packageName)
   const client = new Client(oAuthSession)
 
   const like = dev.npmx.feed.like.$build({

server/api/social/likes/[...pkg].get.ts

@@ -1,6 +1,6 @@
 import * as v from 'valibot'
 import { PackageRouteParamsSchema } from '#shared/schemas/package'
-import { PACKAGE_SUBJECT_REF } from '#shared/utils/constants'
+import { packageSubjectRef } from '#shared/utils/constants'
 import { getTopLikedRank } from '#server/utils/likes-leaderboard'
 
 /**
@@ -27,7 +27,7 @@ export default eventHandlerWithOAuthSession(async (event, oAuthSession) => {
     const likesUtil = new PackageLikesUtils()
     const [likes, topLikedRank] = await Promise.all([
       likesUtil.getLikes(packageName, oAuthSession?.did.toString()),
-      getTopLikedRank(event, PACKAGE_SUBJECT_REF(packageName)),
+      getTopLikedRank(event, packageSubjectRef(packageName)),
     ])
 
     return {

server/api/social/mentions/[...pkg].get.ts

@@ -0,0 +1,50 @@
+import * as v from 'valibot'
+import { PackageRouteParamsSchema } from '#shared/schemas/package'
+
+/**
+ * GET /api/social/mentions/:name
+ *
+ * Gets the number of unique social posts that mention a npm package, capped at 99+
+ */
+export default defineEventHandler(async event => {
+  const pkgParamSegments = getRouterParam(event, 'pkg')?.split('/') ?? []
+  const { rawPackageName } = parsePackageParams(pkgParamSegments)
+
+  if (!rawPackageName) {
+    throw createError({
+      status: 400,
+      message: 'package name not provided',
+    })
+  }
+
+  let decodedPackageName: string
+  try {
+    decodedPackageName = decodeURIComponent(rawPackageName)
+  } catch {
+    throw createError({
+      status: 400,
+      message: 'Invalid package name encoding',
+    })
+  }
+
+  try {
+    const { packageName } = v.parse(PackageRouteParamsSchema, {
+      packageName: decodedPackageName,
+    })
+
+    const mentionsUtil = new PackageSocialMentionsUtils()
+    const mentions = await mentionsUtil.getMentions(packageName)
+
+    setHeader(
+      event,
+      'Cache-Control',
+      `public, max-age=${CACHE_MAX_AGE_ONE_HOUR}, s-maxage=${CACHE_MAX_AGE_ONE_HOUR}`,
+    )
+    return mentions
+  } catch (error: unknown) {
+    handleApiError(error, {
+      statusCode: 502,
+      message: 'Failed to get social mentions',
+    })
+  }
+})

server/utils/atproto/utils/likes.ts

@@ -115,7 +115,7 @@ export class PackageLikesUtils {
   async getLikes(packageName: string, usersDid?: string | undefined): Promise<PackageLikes> {
     //TODO: May need to do some clean up on the package name, and maybe even hash it? some of the characters may be a bit odd as keys
     const totalLikesKey = CACHE_PACKAGE_TOTAL_KEY(packageName)
-    const subjectRef = PACKAGE_SUBJECT_REF(packageName)
+    const subjectRef = packageSubjectRef(packageName)
 
     const cachedLikes = await this.cache.get<number>(totalLikesKey)
     let totalLikes = 0
@@ -161,7 +161,7 @@ export class PackageLikesUtils {
     if (cached !== undefined) {
       return cached
     }
-    const subjectRef = PACKAGE_SUBJECT_REF(packageName)
+    const subjectRef = packageSubjectRef(packageName)
 
     const userHasLiked = await this.constellationUserHasLiked(subjectRef, usersDid)
     await this.cache.set(CACHE_USER_LIKES_KEY(packageName, usersDid), userHasLiked, CACHE_MAX_AGE)
@@ -181,7 +181,7 @@ export class PackageLikesUtils {
     atUri: string,
   ): Promise<PackageLikes> {
     const totalLikesKey = CACHE_PACKAGE_TOTAL_KEY(packageName)
-    const subjectRef = PACKAGE_SUBJECT_REF(packageName)
+    const subjectRef = packageSubjectRef(packageName)
 
     const splitAtUri = atUri.replace('at://', '').split('/')
     const collection = splitAtUri[1]
@@ -231,7 +231,7 @@ export class PackageLikesUtils {
       return backLink
     }
 
-    const subjectRef = PACKAGE_SUBJECT_REF(packageName)
+    const subjectRef = packageSubjectRef(packageName)
     const { data: userLikes } = await this.constellation.getBackLinks(
       subjectRef,
       likeNsid,
@@ -265,7 +265,7 @@ export class PackageLikesUtils {
    */
   async unlikeAPackageAndReturnLikes(packageName: string, usersDid: string): Promise<PackageLikes> {
     const totalLikesKey = CACHE_PACKAGE_TOTAL_KEY(packageName)
-    const subjectRef = PACKAGE_SUBJECT_REF(packageName)
+    const subjectRef = packageSubjectRef(packageName)
 
     let totalLikes = await this.cache.get<number>(totalLikesKey)
     if (!totalLikes) {
@@ -319,7 +319,7 @@ export class PackageLikesUtils {
     const cached = await this.cache.get<Array<{ day: string; likes: number }>>(cacheKey)
     if (cached) return cached
 
-    const subjectRef = PACKAGE_SUBJECT_REF(packageName)
+    const subjectRef = packageSubjectRef(packageName)
     const allBacklinks: Backlink[] = []
     let cursor: string | undefined
 

server/utils/atproto/utils/social-mentions.ts

@@ -0,0 +1,97 @@
+import type { Backlink } from '#shared/utils/constellation'
+import {
+  CACHE_MAX_AGE_ONE_HOUR,
+  packageSubjectRef,
+  SOCIAL_MENTIONS_MAX,
+} from '#shared/utils/constants'
+
+const CACHE_PREFIX = 'atproto-social-mentions:'
+const cachePackageTotalKey = (packageName: string) => `${CACHE_PREFIX}${packageName}:total`
+
+const CACHE_MAX_AGE = CACHE_MAX_AGE_ONE_HOUR
+
+const BLUESKY_POST_COLLECTION = 'app.bsky.feed.post'
+// getBackLinks expects paths without the leading dot that /links/all returns.
+const BLUESKY_LINK_PATHS = [
+  'embed.external.uri',
+  'facets[].features[app.bsky.richtext.facet#link].uri',
+] as const
+
+/** The subset of Constellation that PackageSocialMentionsUtils actually needs. */
+export type ConstellationMentions = Pick<Constellation, 'getBackLinks'>
+
+/**
+ * Counts unique Bluesky posts that link to an npmx.dev package.
+ *
+ * Posts that both embed and facet-link the URL are only counted once. At most
+ * one page of 100 records is read per source path; counts above 99 are capped.
+ */
+export class PackageSocialMentionsUtils {
+  private readonly constellation: ConstellationMentions
+  private readonly cache: CacheAdapter
+
+  constructor(deps?: { constellation?: ConstellationMentions; cache?: CacheAdapter }) {
+    this.constellation =
+      deps?.constellation ??
+      new Constellation(
+        // Passes in a fetch wrapped as CachedFetch because we're already caching here
+        async <T = unknown>(
+          url: string,
+          options: Parameters<typeof $fetch>[1] = {},
+          _ttl?: number,
+        ): Promise<CachedFetchResult<T>> => {
+          const data = (await $fetch<T>(url, options)) as T
+          return { data, isStale: false, cachedAt: null }
+        },
+      )
+    this.cache = deps?.cache ?? getCacheAdapter('generic')
+  }
+
+  private async constellationPostKeys(target: string, recordPath: string) {
+    const { data } = await this.constellation.getBackLinks(
+      target,
+      BLUESKY_POST_COLLECTION,
+      recordPath,
+      100,
+      undefined,
+      false,
+      [],
+      0,
+    )
+
+    return {
+      postKeys: data.records.map(postKey),
+      hasMore: Boolean(data.cursor),
+    }
+  }
+
+  async getMentions(packageName: string): Promise<PackageSocialMentions> {
+    const cacheKey = cachePackageTotalKey(packageName)
+    const cached = await this.cache.get<PackageSocialMentions>(cacheKey)
+    if (cached) return cached
+
+    const target = packageSubjectRef(packageName)
+    const results = await Promise.all(
+      BLUESKY_LINK_PATHS.map(recordPath => this.constellationPostKeys(target, recordPath)),
+    )
+
+    const uniquePosts = new Set<string>()
+    let hasMore = false
+    for (const result of results) {
+      hasMore ||= result.hasMore
+      for (const key of result.postKeys) uniquePosts.add(key)
+    }
+
+    const isCapped = hasMore || uniquePosts.size > SOCIAL_MENTIONS_MAX
+    const result: PackageSocialMentions = {
+      totalMentions: isCapped ? SOCIAL_MENTIONS_MAX : uniquePosts.size,
+      isCapped,
+    }
+    await this.cache.set(cacheKey, result, CACHE_MAX_AGE)
+    return result
+  }
+}
+
+function postKey(record: Backlink): string {
+  return `${record.did}:${record.collection}:${record.rkey}`
+}

shared/types/social.ts

@@ -10,6 +10,16 @@ export type PackageLikes = {
   topLikedRank: number | null
 }
 
+/**
+ * Approximate number of social posts mentioning a npm package
+ */
+export type PackageSocialMentions = {
+  // Exact unique mention count up to 99, or 99 when capped
+  totalMentions: number
+  // True when there are more than 99 unique mentions
+  isCapped: boolean
+}
+
 export type LikesLeaderboardEntry = {
   rank: number
   packageName: string

shared/utils/constants.ts

@@ -58,10 +58,11 @@ export const ERROR_UNKNOWN_GIT_HOST =
 export const CONSTELLATION_HOST = 'constellation.microcosm.blue'
 export const SLINGSHOT_HOST = 'slingshot.microcosm.blue'
 
+export const SOCIAL_MENTIONS_MAX = 99
+
 // ATProtocol
 // References used to link packages to things that are not inherently atproto
-export const PACKAGE_SUBJECT_REF = (packageName: string) =>
-  `https://npmx.dev/package/${packageName}`
+export const packageSubjectRef = (packageName: string) => `https://npmx.dev/package/${packageName}`
 // OAuth scopes as we add new ones we need to check these on certain actions. If not redirect the user to login again to upgrade the scopes
 export const LIKES_SCOPE = `repo:${dev.npmx.feed.like.$nsid}`
 export const PROFILE_SCOPE = `repo:${dev.npmx.actor.profile.$nsid}`