feat: add server side atproto blog apis (#841)

Co-authored-by: Brandon Hurrington <[e-mail]>

modules/standard-site-sync.ts

···
+import { readFileSync } from 'node:fs'
+import { createHash } from 'node:crypto'
+import { defineNuxtModule, useNuxt, createResolver } from 'nuxt/kit'
+import { safeParse } from 'valibot'
+import * as site from '../shared/types/lexicons/site'
+import { BlogPostSchema } from '../shared/schemas/blog'
+import { NPMX_SITE } from '../shared/utils/constants'
+import { parseBasicFrontmatter } from '../shared/utils/parse-basic-frontmatter'
+import { TID } from '@atproto/common'
+import { Client } from '@atproto/lex'
+
+const syncedDocuments = new Map<string, string>()
+const CLOCK_ID_THREE = 3
+const DATE_TO_MICROSECONDS = 1000
+
+// TODO: Currently logging quite a lot, can remove some later if we want
+export default defineNuxtModule({
+  meta: { name: 'standard-site-sync' },
+  async setup() {
+    const nuxt = useNuxt()
+    const { resolve } = createResolver(import.meta.url)
+    const contentDir = resolve('../app/pages/blog')
+
+    // Authentication with PDS using an app password
+    const pdsUrl = process.env.NPMX_PDS_URL
+    if (!pdsUrl) {
+      console.warn('[standard-site-sync] NPMX_PDS_URL not set, skipping sync')
+      return
+    }
+    // Instantiate a single new client instance that is reused for every file
+    const client = new Client(pdsUrl)
+
+    if (nuxt.options._prepare) return
+
+    nuxt.hook('build:before', async () => {
+      const { glob } = await import('tinyglobby')
+      const files: string[] = await glob(`${contentDir}/**/*.md`)
+
+      // INFO: Arbitrarily chosen concurrency limit, can be changed if needed
+      const concurrencyLimit = 5
+      for (let i = 0; i < files.length; i += concurrencyLimit) {
+        const batch = files.slice(i, i + concurrencyLimit)
+        // Process files in parallel
+        await Promise.all(
+          batch.map(file =>
+            syncFile(file, NPMX_SITE, client).catch(error =>
+              console.error(`[standard-site-sync] Error in ${file}:` + error),
+            ),
+          ),
+        )
+      }
+    })
+
+    nuxt.hook('builder:watch', async (event, path) => {
+      if (!path.endsWith('.md')) return
+
+      // Ignore deleted files
+      if (event === 'unlink') {
+        console.log(`[standard-site-sync] File deleted: ${path}`)
+        return
+      }
+
+      // Process add/change events only
+      await syncFile(resolve(nuxt.options.rootDir, path), NPMX_SITE, client).catch(err =>
+        console.error(`[standard-site-sync] Failed ${path}:`, err),
+      )
+    })
+  },
+})
+
+/*
+ * INFO: Loads record to atproto and ensures uniqueness by checking the date the article is published
+ * publishedAt is an id that does not change
+ * Atomicity is enforced with upsert using publishedAt so we always update existing records instead of creating new ones
+ * Clock id(3) provides a deterministic ID
+ * WARN: DOES NOT CATCH ERRORS, THIS MUST BE HANDLED
+ */
+const syncFile = async (filePath: string, siteUrl: string, client: Client) => {
+  const fileContent = readFileSync(filePath, 'utf-8')
+  const frontmatter = parseBasicFrontmatter(fileContent)
+
+  // Schema expects 'path' & frontmatter provides 'slug'
+  const normalizedFrontmatter = {
+    ...frontmatter,
+    path: typeof frontmatter.slug === 'string' ? `/blog/${frontmatter.slug}` : frontmatter.path,
+  }
+
+  const result = safeParse(BlogPostSchema, normalizedFrontmatter)
+  if (!result.success) {
+    console.warn(`[standard-site-sync] Validation failed for ${filePath}`, result.issues)
+    return
+  }
+
+  const data = result.output
+
+  // filter drafts
+  if (data.draft) {
+    if (process.env.DEBUG === 'true') {
+      console.debug(`[standard-site-sync] Skipping draft: ${data.path}`)
+    }
+    return
+  }
+
+  // Keys are sorted to provide a more stable hash
+  const hash = createHash('sha256')
+    .update(JSON.stringify(data, Object.keys(data).sort()))
+    .digest('hex')
+
+  if (syncedDocuments.get(data.path) === hash) {
+    return
+  }
+
+  const document = site.standard.document.$build({
+    site: siteUrl as `${string}:${string}`,
+    path: data.path,
+    title: data.title,
+    description: data.description ?? data.excerpt,
+    tags: data.tags,
+    // This can be extended to update the site.standard.document .updatedAt if it is changed and use the posts date here
+    publishedAt: new Date(data.date).toISOString(),
+  })
+
+  const dateInMicroSeconds = new Date(result.output.date).getTime() * DATE_TO_MICROSECONDS
+
+  // Clock id(3) needs to be the same everytime to get the same TID from a timestamp
+  const tid = TID.fromTime(dateInMicroSeconds, CLOCK_ID_THREE)
+
+  // client.put is async and needs to be awaited
+  await client.put(site.standard.document, document, {
+    rkey: tid.str,
+  })
+
+  syncedDocuments.set(data.path, hash)
+}

package.json

···
     "npmx-connector": "pnpm --filter npmx-connector dev",
     "generate-pwa-icons": "pwa-assets-generator",
     "preview": "nuxt preview",
-    "postinstall": "nuxt prepare && simple-git-hooks && pnpm generate:lexicons",
+    "postinstall": "pnpm generate:lexicons && nuxt prepare && simple-git-hooks",
     "generate:fixtures": "node scripts/generate-fixtures.ts",
     "generate:lexicons": "lex build --lexicons lexicons --out shared/types/lexicons --clear",
     "test": "vite test",
···
     "test:browser:ui": "pnpm build:playwright && pnpm test:browser:prebuilt --ui",
     "test:browser:update": "pnpm build:playwright && pnpm test:browser:prebuilt --update-snapshots",
     "test:nuxt": "vite test --project nuxt",
-    "test:types": "nuxt prepare && vue-tsc -b --noEmit && pnpm --filter npmx-connector test:types",
+    "test:types": "pnpm generate:lexicons && nuxt prepare && vue-tsc -b --noEmit && pnpm --filter npmx-connector test:types",
     "test:unit": "vite test --project unit",
     "start:playwright:webserver": "NODE_ENV=test pnpm preview --port 5678"
   },
   "dependencies": {
     "@atproto/api": "^0.18.17",
+    "@atproto/common": "0.5.10",
     "@atproto/lex": "0.0.13",
     "@atproto/oauth-client-node": "^0.3.15",
     "@deno/doc": "jsr:^0.189.1",
···
     "defu": "6.1.4",
     "fast-npm-meta": "1.0.0",
     "focus-trap": "^7.8.0",
+    "tinyglobby": "0.2.15",
     "marked": "17.0.1",
     "module-replacements": "2.11.0",
     "nuxt": "4.3.0",

pnpm-lock.yaml

···
       '@atproto/api':
         specifier: ^0.18.17
         version: 0.18.20
+      '@atproto/common':
+        specifier: 0.5.10
+        version: 0.5.10
       '@atproto/lex':
         specifier: 0.0.13
         version: 0.0.13
···
       std-env:
         specifier: 3.10.0
         version: 3.10.0
+      tinyglobby:
+        specifier: 0.2.15
+        version: 0.2.15
       ufo:
         specifier: 1.6.3
         version: 1.6.3
···
   '@atproto/common-web@0.4.15':
     resolution: {integrity: sha512-A4l9gyqUNez8CjZp/Trypz/D3WIQsNj8dN05WR6+RoBbvwc9JhWjKPrm+WoVYc/F16RPdXHLkE3BEJlGIyYIiA==}
 
-  '@atproto/common@0.5.9':
-    resolution: {integrity: sha512-rzl8dB7ErpA/VUgCidahUtbxEph50J4g7j68bZmlwwrHlrtvTe8DjrwH5EUFEcegl9dadIhcVJ3qi0kPKEUr+g==}
+  '@atproto/common@0.5.10':
+    resolution: {integrity: sha512-A1+4W3JmjZIgmtJFLJBAaoVruZhRL0ANtyjZ91aJR4rjHcZuaQ+v4IFR1UcE6yyTATacLdBk6ADy8OtxXzq14g==}
     engines: {node: '>=18.7.0'}
 
   '@atproto/crypto@0.4.5':
···
 
   '@atproto/lex-builder@0.0.12':
     resolution: {integrity: sha512-ObWnmsbkPwjKKIX/L0JyMptmggr3gvbZKPDcpr1eSBUWyWeqqX8OfIlHYLgm5veNuO776RV05CE7BdQFQUA+9Q==}
+
+  '@atproto/lex-cbor@0.0.10':
+    resolution: {integrity: sha512-5RtV90iIhRNCXXvvETd3KlraV8XGAAAgOmiszUb+l8GySDU/sGk7AlVvArFfXnj/S/GXJq8DP6IaUxCw/sPASA==}
 
   '@atproto/lex-cbor@0.0.9':
     resolution: {integrity: sha512-szkS569j1eZsIxZKh2VZHVq7pSpewy1wHh8c6nVYekHfYcJhFkevQq/DjTeatZ7YZKNReGYthQulgaZq2ytfWQ==}
···
   glob@11.1.0:
     resolution: {integrity: sha512-vuNwKSaKiqm7g0THUBu2x7ckSs3XJLXE+2ssL7/MfTGPLLcrJQ/4Uq1CjPTtO5cCIiRxqvN6Twy1qOwhL0Xjcw==}
     engines: {node: 20 || >=22}
+    deprecated: Old versions of glob are not supported, and contain widely publicized security vulnerabilities, which have been fixed in the current version. Please update. Support for old versions may be purchased (at exorbitant rates) by contacting [e-mail]
     hasBin: true
 
   glob@13.0.0:
···
       '@atproto/syntax': 0.4.3
       zod: 3.25.76
 
-  '@atproto/common@0.5.9':
+  '@atproto/common@0.5.10':
     dependencies:
       '@atproto/common-web': 0.4.15
-      '@atproto/lex-cbor': 0.0.9
-      '@atproto/lex-data': 0.0.9
+      '@atproto/lex-cbor': 0.0.10
+      '@atproto/lex-data': 0.0.10
       iso-datestring-validator: 2.2.2
       multiformats: 9.9.0
       pino: 8.21.0
···
       '@atproto/lex-schema': 0.0.10
       prettier: 3.8.1
       ts-morph: 27.0.2
+      tslib: 2.8.1
+
+  '@atproto/lex-cbor@0.0.10':
+    dependencies:
+      '@atproto/lex-data': 0.0.10
       tslib: 2.8.1
 
   '@atproto/lex-cbor@0.0.9':
···
 
   '@atproto/repo@0.8.12':
     dependencies:
-      '@atproto/common': 0.5.9
+      '@atproto/common': 0.5.10
       '@atproto/common-web': 0.4.15
       '@atproto/crypto': 0.4.5
       '@atproto/lexicon': 0.6.1

server/api/atproto/author-profiles.get.ts

···
+import * as v from 'valibot'
+import { CACHE_MAX_AGE_ONE_DAY, BLUESKY_API } from '#shared/utils/constants'
+import { AuthorSchema } from '#shared/schemas/blog'
+import type { Author, ResolvedAuthor } from '#shared/schemas/blog'
+
+type ProfilesResponse = {
+  profiles: Array<{
+    did: string
+    handle: string
+    displayName?: string
+    avatar?: string
+  }>
+}
+
+export default defineCachedEventHandler(
+  async event => {
+    const query = getQuery(event)
+    const authorsParam = query.authors
+
+    if (!authorsParam || typeof authorsParam !== 'string') {
+      throw createError({
+        statusCode: 400,
+        statusMessage: 'authors query parameter is required (JSON array)',
+      })
+    }
+
+    let authors: Author[]
+    try {
+      const parsed = JSON.parse(authorsParam)
+      authors = v.parse(v.array(AuthorSchema), parsed)
+    } catch (error) {
+      if (error instanceof v.ValiError) {
+        throw createError({
+          statusCode: 400,
+          statusMessage: `Invalid authors format: ${error.message}`,
+        })
+      }
+      throw createError({
+        statusCode: 400,
+        statusMessage: 'authors must be valid JSON',
+      })
+    }
+
+    if (!Array.isArray(authors) || authors.length === 0) {
+      return { authors: [] }
+    }
+
+    const handles = authors.filter(a => a.blueskyHandle).map(a => a.blueskyHandle as string)
+
+    if (handles.length === 0) {
+      return {
+        authors: authors.map(author => ({
+          ...author,
+          avatar: null,
+          profileUrl: null,
+        })),
+      }
+    }
+
+    const response = await $fetch<ProfilesResponse>(`${BLUESKY_API}app.bsky.actor.getProfiles`, {
+      query: { actors: handles },
+    }).catch(() => ({ profiles: [] }))
+
+    const avatarMap = new Map<string, string>()
+    for (const profile of response.profiles) {
+      if (profile.avatar) {
+        avatarMap.set(profile.handle, profile.avatar)
+      }
+    }
+
+    const resolvedAuthors: ResolvedAuthor[] = authors.map(author => ({
+      ...author,
+      avatar: author.blueskyHandle ? avatarMap.get(author.blueskyHandle) || null : null,
+      profileUrl: author.blueskyHandle ? `https://bsky.app/profile/${author.blueskyHandle}` : null,
+    }))
+
+    return { authors: resolvedAuthors }
+  },
+  {
+    name: 'author-profiles',
+    maxAge: CACHE_MAX_AGE_ONE_DAY,
+    getKey: event => {
+      const { authors } = getQuery(event)
+      return `author-profiles:${authors ?? 'npmx.dev'}`
+    },
+  },
+)

server/api/atproto/bluesky-comments.get.ts

···
+import { safeParse, flatten } from 'valibot'
+import type { Comment, CommentEmbed } from '#shared/types/blog-post'
+import {
+  AppBskyFeedDefs,
+  AppBskyFeedPost,
+  AppBskyEmbedImages,
+  AppBskyEmbedExternal,
+} from '@atproto/api'
+import { BlueSkyUriSchema } from '#shared/schemas/atproto'
+import { CACHE_MAX_AGE_ONE_MINUTE, BLUESKY_API, AT_URI_REGEX } from '#shared/utils/constants'
+
+import { jsonToLex } from '@atproto/api'
+
+type ThreadResponse = { thread: AppBskyFeedDefs.ThreadViewPost }
+
+type LikesResponse = {
+  likes: Array<{
+    actor: {
+      did: string
+      handle: string
+      displayName?: string
+      avatar?: string
+    }
+  }>
+}
+
+type PostsResponse = { posts: Array<{ likeCount?: number }> }
+
+const $bluesky = $fetch.create({ baseURL: BLUESKY_API })
+
+/**
+ * Provides both build and runtime comments refreshes
+ * During build, cache aggressively to avoid rate limits
+ * During runtime, refresh cache once every minute
+ */
+export default defineCachedEventHandler(
+  async event => {
+    const query = getQuery(event)
+    const parsed = safeParse(BlueSkyUriSchema, query)
+
+    if (!parsed.success) {
+      throw createError({
+        statusCode: 400,
+        statusMessage: `Invalid URI format: ${flatten(parsed.issues).root?.[0] || 'Must be a valid at:// URI'}`,
+      })
+    }
+
+    const { uri } = parsed.output
+
+    try {
+      // Fetch thread, likes, and post metadata in parallel
+      const [threadResponse, likesResponse, postsResponse] = await Promise.all([
+        $bluesky<ThreadResponse>('/app.bsky.feed.getPostThread', {
+          query: { uri, depth: 10 },
+        }).catch((err: Error) => {
+          console.warn(`[Bluesky] Thread fetch failed for ${uri}:`, err.message)
+          return null
+        }),
+
+        $bluesky<LikesResponse>('/app.bsky.feed.getLikes', {
+          query: { uri, limit: 50 },
+        }).catch(() => ({ likes: [] })),
+
+        $bluesky<PostsResponse>('/app.bsky.feed.getPosts', {
+          query: { uris: [uri] },
+        }).catch(() => ({ posts: [] })),
+      ])
+
+      // Early return if thread fetch fails w/o 404
+      if (!threadResponse) {
+        return {
+          thread: null,
+          likes: [],
+          totalLikes: 0,
+          postUrl: atUriToWebUrl(uri),
+          _empty: true,
+        }
+      }
+
+      const thread = parseThread(threadResponse.thread)
+
+      return {
+        thread,
+        likes: likesResponse.likes,
+        totalLikes: postsResponse.posts?.[0]?.likeCount ?? thread?.likeCount ?? 0,
+        postUrl: atUriToWebUrl(uri),
+      }
+    } catch (error) {
+      // Fail open during build to prevent build breakage
+      console.error('[Bluesky] Unexpected error:', error)
+      return {
+        thread: null,
+        likes: [],
+        totalLikes: 0,
+        postUrl: atUriToWebUrl(uri),
+        _error: true,
+      }
+    }
+  },
+  {
+    name: 'bluesky-comments',
+    maxAge: CACHE_MAX_AGE_ONE_MINUTE,
+    getKey: event => {
+      const { uri } = getQuery(event)
+      return `bluesky:${uri}`
+    },
+  },
+)
+
+// Helper to convert AT URI to web URL
+function atUriToWebUrl(uri: string): string | null {
+  const match = uri.match(AT_URI_REGEX)
+  if (!match) return null
+  const [, did, rkey] = match
+  return `https://bsky.app/profile/${did}/post/${rkey}`
+}
+
+function parseEmbed(embed: AppBskyFeedDefs.PostView['embed']): CommentEmbed | undefined {
+  if (!embed) return undefined
+
+  if (AppBskyEmbedImages.isView(embed)) {
+    return {
+      type: 'images',
+      images: embed.images,
+    }
+  }
+
+  if (AppBskyEmbedExternal.isView(embed)) {
+    return {
+      type: 'external',
+      external: embed.external,
+    }
+  }
+
+  return undefined
+}
+
+function parseThread(thread: AppBskyFeedDefs.ThreadViewPost): Comment | null {
+  if (!AppBskyFeedDefs.isThreadViewPost(thread)) return null
+
+  const { post } = thread
+
+  // This casts our external.thumb as a blobRef which is needed to validateRecord
+  const lexPostRecord = jsonToLex(post.record)
+  const recordValidation = AppBskyFeedPost.validateRecord(lexPostRecord)
+
+  if (!recordValidation.success) return null
+  const record = recordValidation.value
+
+  const replies: Comment[] = []
+  if (thread.replies) {
+    for (const reply of thread.replies) {
+      if (AppBskyFeedDefs.isThreadViewPost(reply)) {
+        const parsed = parseThread(reply)
+        if (parsed) replies.push(parsed)
+      }
+    }
+    replies.sort((a, b) => new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime())
+  }
+
+  return {
+    uri: post.uri,
+    cid: post.cid,
+    author: {
+      did: post.author.did,
+      handle: post.author.handle,
+      displayName: post.author.displayName,
+      avatar: post.author.avatar,
+    },
+    text: record.text,
+    facets: record.facets,
+    embed: parseEmbed(post.embed),
+    createdAt: record.createdAt,
+    likeCount: post.likeCount ?? 0,
+    replyCount: post.replyCount ?? 0,
+    repostCount: post.repostCount ?? 0,
+    replies,
+  }
+}

shared/schemas/atproto.ts

···
+import { object, string, startsWith, minLength, regex, pipe } from 'valibot'
+import type { InferOutput } from 'valibot'
+import { AT_URI_REGEX } from '#shared/utils/constants'
+
+export const BlueSkyUriSchema = object({
+  uri: pipe(
+    string(),
+    startsWith('at://'),
+    minLength(10),
+    regex(AT_URI_REGEX, 'Must be a valid at:// URI'),
+  ),
+})
+
+export type BlueSkyUri = InferOutput<typeof BlueSkyUriSchema>

shared/schemas/blog.ts

···
+import { object, string, optional, array, boolean, pipe, isoDate } from 'valibot'
+import type { InferOutput } from 'valibot'
+
+export const AuthorSchema = object({
+  name: string(),
+  blueskyHandle: optional(string()),
+})
+
+export const BlogPostSchema = object({
+  authors: array(AuthorSchema),
+  title: string(),
+  date: pipe(string(), isoDate()),
+  description: string(),
+  path: string(),
+  slug: string(),
+  excerpt: optional(string()),
+  tags: optional(array(string())),
+  draft: optional(boolean()),
+})
+
+export type Author = InferOutput<typeof AuthorSchema>
+
+export interface ResolvedAuthor extends Author {
+  avatar: string | null
+  profileUrl: string | null
+}
+
+/**
+ * Inferred type for blog post frontmatter
+ */
+/** @public */
+export type BlogPostFrontmatter = InferOutput<typeof BlogPostSchema>

shared/types/blog-post.ts

···
+import type {
+  AppBskyActorDefs,
+  AppBskyRichtextFacet,
+  AppBskyEmbedImages,
+  AppBskyEmbedExternal,
+} from '@atproto/api'
+
+export type CommentEmbed =
+  | { type: 'images'; images: AppBskyEmbedImages.ViewImage[] }
+  | { type: 'external'; external: AppBskyEmbedExternal.ViewExternal }
+
+export interface Comment {
+  uri: string
+  cid: string
+  author: Pick<AppBskyActorDefs.ProfileViewBasic, 'did' | 'handle' | 'displayName' | 'avatar'>
+  text: string
+  facets?: AppBskyRichtextFacet.Main[]
+  embed?: CommentEmbed
+  createdAt: string
+  likeCount: number
+  replyCount: number
+  repostCount: number
+  replies: Comment[]
+}

shared/utils/constants.ts

···
-import * as dev from '#shared/types/lexicons/dev'
+import * as dev from '../types/lexicons/dev'
 
 // Duration
 export const CACHE_MAX_AGE_ONE_MINUTE = 60
···
 export const CACHE_MAX_AGE_ONE_YEAR = 60 * 60 * 24 * 365
 
 // API Strings
+export const NPMX_SITE = 'https://npmx.dev'
+export const BLUESKY_API = 'https://public.api.bsky.app/xrpc/'
+export const BLUESKY_COMMENTS_REQUEST = '/api/atproto/bluesky-comments'
 export const NPM_REGISTRY = 'https://registry.npmjs.org'
 export const ERROR_PACKAGE_ANALYSIS_FAILED = 'Failed to analyze package.'
 export const ERROR_PACKAGE_VERSION_AND_FILE_FAILED = 'Version and file path are required.'
···
   slate: 'oklch(0.555 0.046 257.407)',
   black: 'oklch(0.4 0 0)',
 } as const
+
+// Regex
+export const AT_URI_REGEX = /^at:\/\/(did:plc:[a-z0-9]+)\/app\.bsky\.feed\.post\/([a-z0-9]+)$/

shared/utils/parse-basic-frontmatter.ts

···
+export function parseBasicFrontmatter(fileContent: string): Record<string, unknown> {
+  const match = fileContent.match(/^---\s*\n([\s\S]*?)\n---\s*(?:\n|$)/)
+  if (!match?.[1]) return {}
+
+  return match[1].split('\n').reduce(
+    (acc, line) => {
+      const idx = line.indexOf(':')
+      if (idx === -1) return acc
+
+      const key = line.slice(0, idx).trim()
+
+      // Remove surrounding quotes
+      let value = line
+        .slice(idx + 1)
+        .trim()
+        .replace(/^["']|["']$/g, '')
+
+      // Type coercion (handles 123, 45.6, boolean, arrays)
+      if (value === 'true') acc[key] = true
+      else if (value === 'false') acc[key] = false
+      else if (/^-?\d+$/.test(value)) acc[key] = parseInt(value, 10)
+      else if (/^-?\d+\.\d+$/.test(value)) acc[key] = parseFloat(value)
+      else if (value.startsWith('[') && value.endsWith(']')) {
+        acc[key] = value
+          .slice(1, -1)
+          .split(',')
+          .map(s => s.trim().replace(/^["']|["']$/g, ''))
+      } else acc[key] = value
+
+      return acc
+    },
+    {} as Record<string, unknown>,
+  )
+}