Status: ✅ Implemented | RSS feed parsing, shared sync core, extensible provider architecture
Syncs user-subscribed Goodreads shelves via RSS feeds, resolves books to Audible ASINs, and creates requests. Also documents the shared shelf sync core used by all providers.
src/lib/services/goodreads-sync.service.ts— RSS fetch/parse, delegates to shared coresrc/lib/utils/goodreads-rss-url.ts— Feed URL rules (toGoodreadsRssUrl,isGoodreadsHttpsUrl); client-safe, also used byAddShelfModal/ManageShelfModalsrc/lib/utils/goodreads-rss-url.schema.ts—goodreadsRssUrlSchema(zod) for POST/PATCH bodiessrc/lib/services/goodreads-shelf-match.ts—findShelfWithSameFeed()duplicate lookup by normalised URL,isUniqueConstraintError()src/lib/services/shelf-sync-core.service.ts— Shared sync logic (Audible lookup, cover enrichment, request creation)src/lib/utils/shelf-helpers.ts— SharedprocessBooks()utility for cover URL parsingsrc/lib/hooks/createShelfHooks.ts— Generic hook factory for shelf CRUD operationssrc/app/api/user/goodreads-shelves/route.ts— GET (list) + POST (add) routessrc/app/api/user/goodreads-shelves/[id]/route.ts— DELETE + PATCH routessrc/app/api/user/shelves/route.ts— Combined GET for all providers (GenericShelf shape)src/lib/hooks/useGoodreadsShelves.ts— Frontend hooks (viacreateShelfHooksfactory)
- GoodreadsShelf — Per-user shelf subscription (
userId,rssUrl,name,lastSyncAt,bookCount,coverUrls) - BookMapping — Shared table for all providers. Keyed by
provider+externalBookId. Caches Audible ASIN lookups.
- Format:
https://www.goodreads.com/review/list_rss/{userId}?shelf={shelfName} - Auth: None required (public RSS)
- Allowed URLs:
https://+ hostgoodreads.comorwww.goodreads.com(no port, no credentials) + path/review/list_rss/. Normalised tohttps://www.goodreads.com/review/list_rss/...(http:// and baregoodreads.comaccepted and rewritten); POST/PATCH store the normalised form, older stored rows are normalised at fetch time (not rewritten). Anything else → 400{ error: 'ValidationError', message }on POST/PATCH; sync refuses it too - Duplicates: POST/PATCH compare normalised feed URLs against the user's shelves (PATCH excludes itself) → 409
DuplicateShelf; a racing insert/update (Prisma P2002) → 409 too - Redirects: axios
maxRedirects: 0; up to 3 redirects followed by hand, each target must be an https Goodreads host before it is requested - Parsing:
fast-xml-parserextractsitementries withbook_id,title,author_name,book_image_url
shelf-sync-core.service.ts contains all provider-agnostic sync logic:
{ bookId: string; title: string; author: string; coverUrl?: string }Accepts provider-agnostic book list + context, performs:
- BookMapping lookup — Check if book already resolved (
provider+externalBookId) - Audible search — Full query (
title author), fallback with cleaned title (strips parenthetical series info) - noMatch retry — Re-searches after
NO_MATCH_RETRY_DAYS(7 days) - Request creation — Calls
createRequestForUser()for matched ASINs - Cover enrichment — Queries
audibleCachefor cached covers, builds/api/cache/thumbnails/URLs - Shelf metadata update — Writes
lastSyncAt,bookCount, top 8 books as JSON tocoverUrls
DEFAULT_MAX_LOOKUPS_PER_SHELF= 10 (per scheduled cycle; 0 = unlimited for manual triggers)NO_MATCH_RETRY_DAYS= 7
Returns { useList, useAdd, useDelete, useUpdate } — all with SWR caching, optimistic updates, and automatic revalidation of the combined /api/user/shelves endpoint.
| Method | Path | Purpose |
|---|---|---|
| GET | /api/user/goodreads-shelves |
List user's Goodreads shelves |
| POST | /api/user/goodreads-shelves |
Add shelf (validates RSS feed, triggers sync) |
| DELETE | /api/user/goodreads-shelves/[id] |
Remove shelf (ownership check) |
| PATCH | /api/user/goodreads-shelves/[id] |
Update RSS URL (triggers re-sync) |
| GET | /api/user/shelves |
Combined endpoint — merges all providers into GenericShelf |
- Create Prisma shelf model + migration (BookMapping table is already shared)
- Create API client service for the external data source
- Create thin sync service (~50-80 lines) that fetches books and calls
processShelfBooks() - Create API routes (or use a generic route handler)
- Create hook file (~40 lines) using
createShelfHooks(endpoint) - Add tab in
AddShelfModalwith provider-specific form fields