barbercollie/ReadMeABook
1
0
Fork 1
mirror of https://github.com/kikootwo/ReadMeABook.git synced 2026-06-02 20:30:10 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'main' of https://github.com/kikootwo/ReadMeABook

Browse Source
This commit is contained in:
kikootwo
2026-03-05 11:31:49 -05:00
parent cc8e106a2b 079a337f1c
commit 832a8ad00b
41 changed files with 3654 additions and 710 deletions
Download Patch File Download Diff File Expand all files Collapse all files
documentation/TABLEOFCONTENTS.md
+12
View File
@@ -32,6 +32,14 @@
- **File hash matching for accurate ASIN** → [fixes/file-hash-matching.md](fixes/file-hash-matching.md)
- **OIDC authentication** → [backend/services/auth.md](backend/services/auth.md)
## Reading Shelves (Goodreads, Hardcover)
- **Goodreads shelf sync (RSS feeds)** → [backend/services/goodreads-sync.md](backend/services/goodreads-sync.md)
- **Hardcover shelf sync (GraphQL API)** → [backend/services/hardcover-sync.md](backend/services/hardcover-sync.md)
- **Shared sync core (Audible lookup, request creation)** → [backend/services/goodreads-sync.md](backend/services/goodreads-sync.md#shared-sync-core)
- **Combined shelves API, GenericShelf** → [backend/services/goodreads-sync.md](backend/services/goodreads-sync.md)
- **Hook factory (createShelfHooks)** → [backend/services/goodreads-sync.md](backend/services/goodreads-sync.md#hook-factory)
- **Adding a new shelf provider** → [backend/services/goodreads-sync.md](backend/services/goodreads-sync.md#adding-a-new-provider)
## Audible Integration
- **Web scraping (popular, new releases)** → [integrations/audible.md](integrations/audible.md)
- **Database caching, real-time matching** → [integrations/audible.md](integrations/audible.md)
@@ -154,3 +162,7 @@
**"How do I customize my home page?"** → [features/home-sections.md](features/home-sections.md)
**"How do Audible categories work?"** → [features/home-sections.md](features/home-sections.md)
**"How do I add category sections to the home page?"** → [features/home-sections.md](features/home-sections.md)
**"How do Goodreads shelves work?"** → [backend/services/goodreads-sync.md](backend/services/goodreads-sync.md)
**"How do Hardcover shelves work?"** → [backend/services/hardcover-sync.md](backend/services/hardcover-sync.md)
**"How do I add a new shelf provider?"** → [backend/services/goodreads-sync.md](backend/services/goodreads-sync.md#adding-a-new-provider)
**"How does the shelf sync core work?"** → [backend/services/goodreads-sync.md](backend/services/goodreads-sync.md#shared-sync-core)
documentation/backend/services/goodreads-sync.md
+75
View File
@@ -0,0 +1,75 @@
# Goodreads & Shelf Sync
**Status:** ✅ Implemented | RSS feed parsing, shared sync core, extensible provider architecture
## Overview
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.
## Architecture
### Files
- `src/lib/services/goodreads-sync.service.ts` — RSS fetch/parse, delegates to shared core
- `src/lib/services/shelf-sync-core.service.ts` — Shared sync logic (Audible lookup, cover enrichment, request creation)
- `src/lib/utils/shelf-helpers.ts` — Shared `processBooks()` utility for cover URL parsing
- `src/lib/hooks/createShelfHooks.ts` — Generic hook factory for shelf CRUD operations
- `src/app/api/user/goodreads-shelves/route.ts` — GET (list) + POST (add) routes
- `src/app/api/user/goodreads-shelves/[id]/route.ts` — DELETE + PATCH routes
- `src/app/api/user/shelves/route.ts` — Combined GET for all providers (GenericShelf shape)
- `src/lib/hooks/useGoodreadsShelves.ts` — Frontend hooks (via `createShelfHooks` factory)
### Database Models
- **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.
## Goodreads RSS Feed
- **Format:** `https://www.goodreads.com/review/list_rss/{userId}?shelf={shelfName}`
- **Auth:** None required (public RSS)
- **Parsing:** `fast-xml-parser` extracts `item` entries with `book_id`, `title`, `author_name`, `book_image_url`
## Shared Sync Core
`shelf-sync-core.service.ts` contains all provider-agnostic sync logic:
### Interface: `ShelfBook`
```typescript
{ bookId: string; title: string; author: string; coverUrl?: string }
```
### Function: `processShelfBooks()`
Accepts provider-agnostic book list + context, performs:
1. **BookMapping lookup** — Check if book already resolved (`provider` + `externalBookId`)
2. **Audible search** — Full query (`title author`), fallback with cleaned title (strips parenthetical series info)
3. **noMatch retry** — Re-searches after `NO_MATCH_RETRY_DAYS` (7 days)
4. **Request creation** — Calls `createRequestForUser()` for matched ASINs
5. **Cover enrichment** — Queries `audibleCache` for cached covers, builds `/api/cache/thumbnails/` URLs
6. **Shelf metadata update** — Writes `lastSyncAt`, `bookCount`, top 8 books as JSON to `coverUrls`
### Constants
- `DEFAULT_MAX_LOOKUPS_PER_SHELF` = 10 (per scheduled cycle; 0 = unlimited for manual triggers)
- `NO_MATCH_RETRY_DAYS` = 7
### Hook Factory: `createShelfHooks(endpoint)`
Returns `{ useList, useAdd, useDelete, useUpdate }` — all with SWR caching, optimistic updates, and automatic revalidation of the combined `/api/user/shelves` endpoint.
## API Endpoints
| 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` |
## Adding a New Provider
1. Create Prisma shelf model + migration (BookMapping table is already shared)
2. Create API client service for the external data source
3. Create thin sync service (~50-80 lines) that fetches books and calls `processShelfBooks()`
4. Create API routes (or use a generic route handler)
5. Create hook file (~40 lines) using `createShelfHooks(endpoint)`
6. Add tab in `AddShelfModal` with provider-specific form fields
## Related
- [Hardcover sync](hardcover-sync.md)
- [Background jobs](jobs.md)
- [Scheduler](scheduler.md)
documentation/backend/services/hardcover-sync.md
+66
View File
@@ -0,0 +1,66 @@
# Hardcover Shelf Sync
**Status:** ✅ Implemented | GraphQL API integration, Audible ASIN resolution, automated request creation
## Overview
Syncs user-subscribed Hardcover lists via their GraphQL API, resolves books to Audible ASINs, and creates audiobook requests automatically.
## Architecture
### Files
- `src/lib/services/hardcover-api.service.ts` — GraphQL queries, `fetchHardcoverList()`
- `src/lib/services/hardcover-sync.service.ts` — Provider-specific orchestration, delegates to shared core
- `src/lib/services/shelf-sync-core.service.ts` — Shared sync logic (Audible lookup, cover enrichment, request creation)
- `src/app/api/user/hardcover-shelves/route.ts` — GET (list) + POST (add) routes
- `src/app/api/user/hardcover-shelves/[id]/route.ts` — DELETE + PATCH routes
- `src/lib/hooks/useHardcoverShelves.ts` — Frontend hooks (via `createShelfHooks` factory)
### Database Models
- **HardcoverShelf** — Per-user list subscription (`userId`, `listId`, encrypted `apiToken`, `name`, `lastSyncAt`, `bookCount`, `coverUrls`)
- **BookMapping** — Shared across all providers. Keyed by `provider` + `externalBookId`. Caches Audible ASIN resolution (`audibleAsin`, `noMatch`, `lastSearchAt`)
## Hardcover API
- **Endpoint:** `https://api.hardcover.app/v1/graphql` (Hasura-based)
- **Auth:** Bearer token in Authorization header
- **Username type:** `citext` (case-insensitive text) — use `$username: citext!` in GraphQL variables
### Query Strategies (custom lists)
| Input | Strategy | Query root |
|---|---|---|
| URL with `@username` | Scoped to that user | `users(where: {username: {_eq: $username}}) { lists(...) }` |
| Bare slug (no username) | Authenticated user's own list | `me { lists(where: {slug: {_eq: $slug}}) }` |
| Numeric ID | Global lookup (IDs are unique) | `lists(where: {id: {_eq: $listId}})` |
### Status Lists
- Prefix: `status-{id}` (e.g., `status-1`)
- Query: `me { user_books(where: {status_id: {_eq: $statusId}}) }`
- Status IDs: 1=Want to Read, 2=Currently Reading, 3=Read, 4=Did Not Finish
## Sync Flow
1. Fetch shelves from DB (all or specific `shelfId`)
2. Decrypt API token (encryption service)
3. Fetch books from Hardcover GraphQL API
4. Delegate to `processShelfBooks()` in shelf-sync-core (Audible lookup, request creation, cover enrichment)
5. Update shelf metadata (`lastSyncAt`, `bookCount`, `coverUrls`)
## API Endpoints
| Method | Path | Purpose |
|---|---|---|
| GET | `/api/user/hardcover-shelves` | List user's shelves with book counts/covers |
| POST | `/api/user/hardcover-shelves` | Add new shelf (validates via API fetch, encrypts token, triggers sync) |
| DELETE | `/api/user/hardcover-shelves/[id]` | Remove shelf (ownership check) |
| PATCH | `/api/user/hardcover-shelves/[id]` | Update listId/apiToken (triggers re-sync on change) |
## Key Details
- **Token cleanup:** Strips `Bearer ` prefix if user pastes it
- **Duplicate check:** Unique constraint on `(userId, listId)`
- **Immediate sync:** POST and PATCH trigger `addSyncShelvesJob()` with unlimited lookups
- **Scheduled sync:** Runs via `sync_reading_shelves` job (default: max 10 lookups/shelf/cycle)
- **Cover data:** Stores top 8 books as JSON in `coverUrls` field for shelf card display
## Related
- [Shelf sync core (shared logic)](goodreads-sync.md#shared-sync-core)
- [Background jobs](jobs.md)
- [Scheduler](scheduler.md)