feat: constellation 🌌 client (#474)

Co-authored-by: Daniel Roe <[e-mail]>

app/composables/useCachedFetch.ts

···
 import type { CachedFetchResult } from '#shared/utils/fetch-cache-config'
 
 /**
- * Type for the cachedFetch function attached to event context.
- */
-export type CachedFetchFunction = <T = unknown>(
-  url: string,
-  options?: {
-    method?: string
-    body?: unknown
-    headers?: Record<string, string>
-  },
-  ttl?: number,
-) => Promise<CachedFetchResult<T>>
-
-/**
  * Get the cachedFetch function from the current request context.
  *
  * IMPORTANT: This must be called in the composable setup context (outside of

app/composables/useNpmRegistry.ts

···
 import { maxSatisfying, prerelease, major, minor, diff, gt, compare } from 'semver'
 import { isExactVersion } from '~/utils/versions'
 import { extractInstallScriptsInfo } from '~/utils/install-scripts'
-import type { CachedFetchFunction } from '~/composables/useCachedFetch'
+import type { CachedFetchFunction } from '#shared/utils/fetch-cache-config'
 
 const NPM_REGISTRY = 'https://registry.npmjs.org'
 const NPM_API = 'https://api.npmjs.org'

app/composables/useRepoMeta.ts

···
 import type { ProviderId, RepoRef } from '#shared/utils/git-providers'
 import { parseRepoUrl, GITLAB_HOSTS } from '#shared/utils/git-providers'
-import type { CachedFetchFunction } from '~/composables/useCachedFetch'
 
 // TTL for git repo metadata (10 minutes - repo stats don't change frequently)
 const REPO_META_TTL = 60 * 10
···
   delegates?: Array<{ id: string; alias?: string }>
   patches?: { open: number; draft: number; archived: number; merged: number }
   issues?: { open: number; closed: number }
-}
-
-/** microcosm's constellation API response for /links/all to get tangled.org  stats */
-type ConstellationAllLinksResponse = {
-  links: Record<
-    string,
-    Record<
-      string,
-      {
-        records: number
-        distinct_dids: number
-      }
-    >
-  >
 }
 
 type ProviderAdapter = {
···
       let forks = 0
       const atUri = atUriMatch?.[1]
 
-      if (atUriMatch) {
+      if (atUri) {
         try {
+          const constellation = new Constellation(cachedFetch)
           //Get counts of records that reference this repo in the atmosphere using constellation
-          const { data: allLinks } = await cachedFetch<ConstellationAllLinksResponse>(
-            `https://constellation.microcosm.blue/links/all?target=${atUri}`,
-            { headers: { 'User-Agent': 'npmx' } },
-            REPO_META_TTL,
-          )
+          const { data: allLinks } = await constellation.getAllLinks(atUri)
           stars = allLinks.links['sh.tangled.feed.star']?.['.subject']?.distinct_dids ?? stars
           forks = allLinks.links['sh.tangled.repo']?.['.source']?.distinct_dids ?? stars
         } catch {

lexicons/dev/npmx/feed/like.json

···
+{
+  "defs": {
+    "main": {
+      "description": "A like of a package on npmx",
+      "key": "tid",
+      "record": {
+        "properties": {
+          "createdAt": {
+            "format": "datetime",
+            "type": "string"
+          },
+          "subject": {
+            "description": "A strong reference to the dev.npmx.package record. If the package does not have a record in an atproto repo, this is not included.",
+            "type": "ref",
+            "ref": "com.atproto.repo.strongRef"
+          },
+          "subjectRef": {
+            "description": "The npmx URL to the package to allow for counting of packages that do not have a record in an atproto repo.",
+            "type": "string",
+            "format": "uri"
+          }
+        },
+        "required": ["createdAt", "subjectRef"],
+        "type": "object"
+      },
+      "type": "record"
+    }
+  },
+  "id": "dev.npmx.feed.like",
+  "lexicon": 1
+}

server/api/auth/atproto.get.ts

···
 import { NodeOAuthClient } from '@atproto/oauth-client-node'
 import { createError, getQuery, sendRedirect } from 'h3'
 import { useOAuthStorage } from '#server/utils/atproto/storage'
-import { SLINGSHOT_ENDPOINT } from '#shared/utils/constants'
+import { SLINGSHOT_HOST } from '#shared/utils/constants'
 import type { UserSession } from '#shared/schemas/userSession'
 
 export default defineEventHandler(async event => {
···
   })
 
   const response = await fetch(
-    `${SLINGSHOT_ENDPOINT}/xrpc/com.bad-example.identity.resolveMiniDoc?identifier=${agent.did}`,
+    `https://${SLINGSHOT_HOST}/xrpc/com.bad-example.identity.resolveMiniDoc?identifier=${agent.did}`,
     { headers: { 'User-Agent': 'npmx' } },
   )
   const miniDoc = (await response.json()) as UserSession

server/plugins/fetch-cache.ts

···
   return parts.join(':')
 }
 
-export type CachedFetchFunction = <T = unknown>(
-  url: string,
-  options?: {
-    method?: string
-    body?: unknown
-    headers?: Record<string, string>
-  },
-  ttl?: number,
-) => Promise<CachedFetchResult<T>>
-
 /**
  * Server plugin that attaches a cachedFetch function to the event context.
  * This allows app composables to access the cached fetch via useRequestEvent().

shared/utils/constants.ts

···
 export const ERROR_SUGGESTIONS_FETCH_FAILED = 'Failed to fetch suggestions.'
 
 // microcosm services
-export const CONSTELLATION_ENDPOINT = 'https://constellation.microcosm.blue'
-export const SLINGSHOT_ENDPOINT = 'https://slingshot.microcosm.blue'
+export const CONSTELLATION_HOST = 'constellation.microcosm.blue'
+export const SLINGSHOT_HOST = 'slingshot.microcosm.blue'
 
 // Theming
 export const ACCENT_COLORS = {

shared/utils/constellation.ts

···
+import { CONSTELLATION_HOST } from '#shared/utils/constants'
+import type { CachedFetchFunction } from './fetch-cache-config'
+
+export type Backlink = {
+  did: string
+  collection: string
+  rkey: string
+}
+
+export type BacklinksResponse = {
+  total: number
+  records: Backlink[]
+  cursor: string | undefined
+}
+
+export type LinksDistinctDidsResponse = {
+  total: number
+  linking_dids: string[]
+  cursor: string | undefined
+}
+
+export type AllLinksResponse = {
+  links: Record<
+    string,
+    Record<
+      string,
+      {
+        records: number
+        distinct_dids: number
+      }
+    >
+  >
+}
+
+const HEADERS = { 'User-Agent': 'npmx' }
+
+/** @public */
+export class Constellation {
+  private readonly cachedFetch: CachedFetchFunction
+  constructor(fetch: CachedFetchFunction) {
+    this.cachedFetch = fetch
+  }
+
+  /**
+   * Gets backlinks from constellation
+   * https://constellation.microcosm.blue/xrpc/blue.microcosm.links.getBacklinks?subject=at%3A%2F%2Fdid%3Aplc%3Aa4pqq234yw7fqbddawjo7y35%2Fapp.bsky.feed.post%2F3m237ilwc372e&source=app.bsky.feed.like%3Asubject.uri&limit=16
+   * @param subject - A uri encoded link. did, url, or at-uri
+   * @param collection - The lexicon collection to check like dev.npmx.feed.like
+   * @param recordPath - Where in the record to check for the subject
+   * @param limit - The number of backlinks to return
+   * @param cursor - The cursor to use for pagination
+   * @param reverse - Whether to reverse the order of the results
+   * @param filterByDids - An array of dids to filter by in the results
+   * @param ttl - The ttl to use for the cache
+   */
+  async getBackLinks(
+    subject: string,
+    collection: string,
+    recordPath: string,
+    limit = 16,
+    cursor?: string,
+    reverse = false,
+    filterByDids: [string][] = [],
+    ttl: number | undefined = undefined,
+  ) {
+    const source = encodeURIComponent(`${collection}:${recordPath}`)
+    let urlToCall = `https://${CONSTELLATION_HOST}/xrpc/blue.microcosm.links.getBacklinks?subject=${encodeURIComponent(subject)}&source=${source}&limit=${limit}`
+    if (cursor) urlToCall += `&cursor=${cursor}`
+    if (reverse) urlToCall += '&reverse=true'
+    filterByDids.forEach(did => (urlToCall += `&did=${did}`))
+
+    return await this.cachedFetch<BacklinksResponse>(urlToCall, { headers: HEADERS }, ttl)
+  }
+
+  /**
+   *  Gets the distinct dids that link to a target record
+   * @param target - A uri encoded link. did, url, or at-uri
+   * @param collection - The lexicon collection to check like dev.npmx.feed.like
+   * @param recordPath - Where in the record to check for the subject
+   * @param limit - The number of distinct dids to return
+   * @param cursor - The cursor to use for pagination
+   * @param ttl - The ttl to use for the cache
+   */
+  async getLinksDistinctDids(
+    target: string,
+    collection: string,
+    recordPath: string,
+    limit: number = 16,
+    cursor?: string,
+    ttl: number | undefined = undefined,
+  ) {
+    let urlToCall = `https://${CONSTELLATION_HOST}/links/distinct-dids?target=${encodeURIComponent(target)}&collection=${collection}&path=${recordPath}&limit=${limit}`
+    if (cursor) urlToCall += `&cursor=${cursor}`
+    return await this.cachedFetch<LinksDistinctDidsResponse>(urlToCall, { headers: HEADERS }, ttl)
+  }
+
+  /**
+   * Gets all links from constellation and their counts
+   * @param target - A uri encoded link. did, url, or at-uri
+   * @param ttl - The ttl to use for the cache
+   */
+  async getAllLinks(target: string, ttl: number | undefined = undefined) {
+    return await this.cachedFetch<AllLinksResponse>(
+      `https://${CONSTELLATION_HOST}/links/all?target=${target}`,
+      { headers: HEADERS },
+      ttl,
+    )
+  }
+}

shared/utils/fetch-cache-config.ts

···
  * using Nitro's storage layer (backed by Vercel's runtime cache in production).
  */
 
-import { CONSTELLATION_ENDPOINT, SLINGSHOT_ENDPOINT } from './constants'
+import { CONSTELLATION_HOST, SLINGSHOT_HOST } from './constants'
 
 /**
  * Domains that should have their fetch responses cached.
···
   'codeberg.org', // Codeberg (Gitea-based)
   'gitee.com', // Gitee API
   // microcosm endpoints for atproto data
-  CONSTELLATION_ENDPOINT,
-  SLINGSHOT_ENDPOINT,
+  CONSTELLATION_HOST,
+  SLINGSHOT_HOST,
 ] as const
 
 /**
···
   /** Unix timestamp when the data was cached, or null if fresh fetch */
   cachedAt: number | null
 }
+
+/**
+ * Type for the cachedFetch function attached to event context.
+ */
+export type CachedFetchFunction = <T = unknown>(
+  url: string,
+  options?: {
+    method?: string
+    body?: unknown
+    headers?: Record<string, string>
+  },
+  ttl?: number,
+) => Promise<CachedFetchResult<T>>