feat: discogs lookup routes (barcode/search/release preview)

Known-red tests pending later tasks:
- 'reports duplicate when release already in collection' needs
  POST /api/collection (Task 15)
- 'reports ripped...' and 'reports ambiguous...' need the test-only
  POST /api/library/albums/test-seed route (Task 16)

server/src/app.ts

@@ -2,14 +2,17 @@ import Fastify, { FastifyInstance } from 'fastify'
 import Database from 'better-sqlite3'
 import cookie from '@fastify/cookie'
 import type { Config } from './config.js'
+import { SerialQueue } from './queue.js'
 import { registerAuthRoutes } from './routes/authRoutes.js'
 import { registerSettingsRoutes } from './routes/settingsRoutes.js'
+import { registerLookupRoutes } from './routes/lookupRoutes.js'
 
 declare module 'fastify' {
   interface FastifyInstance {
     db: Database.Database
     config: Config
     fetchImpl: typeof fetch
+    discogsQueue: SerialQueue
   }
   interface FastifyRequest {
     user?: import('./auth.js').UserRow
@@ -27,10 +30,12 @@ export async function buildApp(opts: AppOptions): Promise<FastifyInstance> {
   app.decorate('db', opts.db)
   app.decorate('config', opts.config)
   app.decorate('fetchImpl', opts.fetchImpl ?? fetch)
+  app.decorate('discogsQueue', new SerialQueue({ minIntervalMs: 1100 }))
 
   await app.register(cookie)
   await registerAuthRoutes(app)
   await registerSettingsRoutes(app)
+  await registerLookupRoutes(app)
 
   app.get('/api/health', async () => ({ ok: true }))
   return app

server/src/routes/lookupRoutes.ts

@@ -0,0 +1,86 @@
+import { FastifyInstance, FastifyRequest } from 'fastify'
+import {
+  DiscogsClient,
+  DiscogsAuthError,
+  DiscogsRateLimitError,
+  DiscogsError,
+} from '../discogs.js'
+import { isConfidentMatch, candidateAlbums } from '../matcher.js'
+import { requireAuth } from './authRoutes.js'
+import { getSettings } from './settingsRoutes.js'
+
+export function discogsErrorStatus(err: unknown): { code: number; body: Record<string, string> } {
+  if (err instanceof DiscogsAuthError) return { code: 502, body: { error: 'discogs_auth' } }
+  if (err instanceof DiscogsRateLimitError) return { code: 429, body: { error: 'discogs_rate_limited' } }
+  if (err instanceof DiscogsError) return { code: 502, body: { error: 'discogs_error' } }
+  return { code: 502, body: { error: 'discogs_unreachable' } }
+}
+
+export function discogsClientFor(request: FastifyRequest): DiscogsClient | null {
+  const s = getSettings(request.server.db, request.user!.id)
+  if (!s.discogs_token) return null
+  return new DiscogsClient(
+    s.discogs_token,
+    request.server.fetchImpl,
+    'https://api.discogs.com',
+    request.server.discogsQueue
+  )
+}
+
+export async function registerLookupRoutes(app: FastifyInstance): Promise<void> {
+  app.get('/api/lookup/barcode/:code', { preHandler: [requireAuth] }, async (request, reply) => {
+    const client = discogsClientFor(request)
+    if (!client) return reply.code(409).send({ error: 'no_discogs_token' })
+    try {
+      const candidates = await client.searchByBarcode((request.params as { code: string }).code)
+      if (candidates.length === 0) return reply.code(404).send({ error: 'not_found' })
+      return { candidates }
+    } catch (err) {
+      const { code, body } = discogsErrorStatus(err)
+      return reply.code(code).send(body)
+    }
+  })
+
+  app.get('/api/lookup/search', { preHandler: [requireAuth] }, async (request, reply) => {
+    const client = discogsClientFor(request)
+    if (!client) return reply.code(409).send({ error: 'no_discogs_token' })
+    const { q, format } = request.query as { q?: string; format?: string }
+    if (!q) return reply.code(400).send({ error: 'missing_query' })
+    try {
+      const candidates = await client.searchByText(q, format || undefined)
+      if (candidates.length === 0) return reply.code(404).send({ error: 'not_found' })
+      return { candidates }
+    } catch (err) {
+      const { code, body } = discogsErrorStatus(err)
+      return reply.code(code).send(body)
+    }
+  })
+
+  app.get('/api/lookup/release/:id', { preHandler: [requireAuth] }, async (request, reply) => {
+    const client = discogsClientFor(request)
+    if (!client) return reply.code(409).send({ error: 'no_discogs_token' })
+    const id = Number((request.params as { id: string }).id)
+    try {
+      const release = await client.getRelease(id)
+      const db = request.server.db
+      const userId = request.user!.id
+      const duplicate = !!db
+        .prepare('SELECT id FROM collection_items WHERE user_id = ? AND discogs_release_id = ?')
+        .get(userId, id)
+      const albums = db
+        .prepare('SELECT id, title, artist FROM digital_albums WHERE user_id = ?')
+        .all(userId) as { id: number; title: string; artist: string }[]
+      const confident = albums.some((a) => isConfidentMatch(release, a))
+      const matchCandidates = confident ? [] : candidateAlbums(release, albums)
+      return {
+        release,
+        duplicate,
+        ripMatch: confident ? 'ripped' : matchCandidates.length > 0 ? 'ambiguous' : 'not_ripped',
+        matchCandidates,
+      }
+    } catch (err) {
+      const { code, body } = discogsErrorStatus(err)
+      return reply.code(code).send(body)
+    }
+  })
+}