Add Hardcover shelf sync & unify book mappings

Introduce Hardcover provider support and consolidate per-provider book mapping tables into a unified BookMapping model. Adds two Prisma migrations (add_hardcover_shelves, unify_book_mappings), new backend services (hardcover-api, shelf-sync-core), and provider-specific sync logic and API routes for hardcover shelves with token/list validation. Frontend: new HardcoverForm component, refactor AddShelfModal to support Hardcover, hook updates, and small UI/accessibility tweaks. Also add documentation for Goodreads and Hardcover sync flows and update tests to cover scheduler/prisma helpers.

src/app/api/user/hardcover-shelves/[id]/route.ts

@@ -9,6 +9,7 @@ import { prisma } from '@/lib/db';
 import { RMABLogger } from '@/lib/utils/logger';
 import { getJobQueueService } from '@/lib/services/job-queue.service';
 import { getEncryptionService } from '@/lib/services/encryption.service';
+import { fetchHardcoverList } from '@/lib/services/hardcover-api.service';
 import { z } from 'zod';
 
 const logger = RMABLogger.create('API.HardcoverShelves');
@@ -90,21 +91,50 @@ export async function PATCH(
       const body = await request.json();
       const { listId, apiToken } = UpdateHardcoverSchema.parse(body);
 
-      const updateData: any = {};
+      const updateData: { listId?: string; apiToken?: string; lastSyncAt?: null; bookCount?: null; coverUrls?: null } = {};
       let needsResync = false;
 
-      if (listId && listId !== shelf.listId) {
-        updateData.listId = listId;
-        needsResync = true;
-      }
-
+      let cleanedToken: string | undefined;
       if (apiToken && apiToken.trim() !== '') {
-        const cleanedToken = apiToken.trim().toLowerCase().startsWith('bearer ')
+        cleanedToken = apiToken.trim().toLowerCase().startsWith('bearer ')
           ? apiToken.trim().slice(7).trim()
           : apiToken.trim();
+      }
+
+      const newListId = (listId && listId !== shelf.listId) ? listId : undefined;
+
+      // Validate token/listId by fetching the list before saving
+      if (cleanedToken || newListId) {
         const encryptionService = getEncryptionService();
-        updateData.apiToken = encryptionService.encrypt(cleanedToken);
-        needsResync = true;
+        const tokenToTest = cleanedToken || (() => {
+          try {
+            return encryptionService.isEncryptedFormat(shelf.apiToken)
+              ? encryptionService.decrypt(shelf.apiToken)
+              : shelf.apiToken;
+          } catch { return shelf.apiToken; }
+        })();
+        const listIdToTest = newListId || shelf.listId;
+
+        try {
+          await fetchHardcoverList(tokenToTest, listIdToTest);
+        } catch (error) {
+          return NextResponse.json(
+            {
+              error: 'InvalidHardcoverList',
+              message: `Could not fetch the Hardcover list. Check your Token and List ID: ${error instanceof Error ? error.message : 'Unknown error'}`,
+            },
+            { status: 400 },
+          );
+        }
+
+        if (newListId) {
+          updateData.listId = newListId;
+          needsResync = true;
+        }
+        if (cleanedToken) {
+          updateData.apiToken = encryptionService.encrypt(cleanedToken);
+          needsResync = true;
+        }
       }
 
       // If we are forcing a resync due to a change, clear metadata

src/app/api/user/hardcover-shelves/route.ts

@@ -11,6 +11,7 @@ import { getJobQueueService } from '@/lib/services/job-queue.service';
 import { getEncryptionService } from '@/lib/services/encryption.service';
 import { z } from 'zod';
 import { RMABLogger } from '@/lib/utils/logger';
+import { processBooks } from '@/lib/utils/shelf-helpers';
 
 const logger = RMABLogger.create('API.HardcoverShelves');
 
@@ -36,29 +37,7 @@ export async function GET(request: NextRequest) {
       });
 
       const shelvesWithMeta = shelves.map((shelf) => {
-        let books: {
-          coverUrl: string;
-          asin: string | null;
-          title: string;
-          author: string;
-        }[] = [];
-        if (shelf.coverUrls) {
-          const parsed = JSON.parse(shelf.coverUrls);
-          if (Array.isArray(parsed)) {
-            books = parsed.map((item: unknown) => {
-              if (typeof item === 'string') {
-                return { coverUrl: item, asin: null, title: '', author: '' };
-              }
-              const obj = item as Record<string, unknown>;
-              return {
-                coverUrl: (obj.coverUrl as string) || '',
-                asin: (obj.asin as string) || null,
-                title: (obj.title as string) || '',
-                author: (obj.author as string) || '',
-              };
-            });
-          }
-        }
+        const books = processBooks(shelf.coverUrls);
 
         return {
           id: shelf.id,

src/app/api/user/shelves/route.ts

@@ -7,6 +7,7 @@ import { NextRequest, NextResponse } from 'next/server';
 import { requireAuth, AuthenticatedRequest } from '@/lib/middleware/auth';
 import { prisma } from '@/lib/db';
 import { RMABLogger } from '@/lib/utils/logger';
+import { processBooks } from '@/lib/utils/shelf-helpers';
 
 const logger = RMABLogger.create('API.Shelves');
 
@@ -32,33 +33,6 @@ export async function GET(request: NextRequest) {
         }),
       ]);
 
-      const processBooks = (coverUrls: string | null) => {
-        let books: {
-          coverUrl: string;
-          asin: string | null;
-          title: string;
-          author: string;
-        }[] = [];
-        if (coverUrls) {
-          const parsed = JSON.parse(coverUrls);
-          if (Array.isArray(parsed)) {
-            books = parsed.map((item: unknown) => {
-              if (typeof item === 'string') {
-                return { coverUrl: item, asin: null, title: '', author: '' };
-              }
-              const obj = item as Record<string, unknown>;
-              return {
-                coverUrl: (obj.coverUrl as string) || '',
-                asin: (obj.asin as string) || null,
-                title: (obj.title as string) || '',
-                author: (obj.author as string) || '',
-              };
-            });
-          }
-        }
-        return books;
-      };
-
       const combined = [
         ...goodreads.map((s) => ({
           id: s.id,