[bug] Shelfbridge reads `progress` instead of `ebookProgress` for ebooks

[johnsturgeon]

First time user, so I'm just getting used to this thing.
I have a book in Audiobookshelf that is 31% complete. I matched the ISBN in audiobookshelf to match one in Hardcover, then added my book to my 'owned' collection in hardcover, ran the sync, but it's not updating that book

shelfbridge | 04:42:42 [info]: Skipping ISBN match auto-add for I'll Never Be French (no matter what I do): Progress 0.0% below threshold 5% service="shelfbridge" version="1.23.0" title="I'll Never Be French (no matter what I do)" progress=0 threshold=5 matchType="isbn" reason="below_progress_threshold"

I'm not sure why that is... seems very odd.

[johnsturgeon]

Here's some more info -- full disclosure, this was gleaned through Claude.

Ebook progress not synced — ebookProgress field ignored, only progress field read

Describe the bug

ShelfBridge does not sync reading progress for ebooks. The Audiobookshelf API returns ebook progress in a separate field (ebookProgress) from audiobook progress (progress), but ShelfBridge only reads the progress field. For ebooks, progress is always 0 while the actual reading position is in ebookProgress.

To Reproduce

1. Have an ebook (epub) in your Audiobookshelf library with reading progress
2. Run a sync
3. ShelfBridge reports 0% progress and skips the book as below threshold

Expected behavior

Ebook reading progress should be read from ebookProgress and synced to Hardcover.

Actual behavior

Progress is reported as 0% and the book is skipped with:

Skipping ISBN match auto-add for <title>: Progress 0.0% below threshold 0%

Root cause

In src/audiobookshelf-client.js, _getLibraryItemDetails():

itemData.progress_percentage = progressData.progress * 100;

The ABS progress API (/api/me/progress/{itemId}) returns two separate fields:

• progress — used for audiobooks (0–1 float), always 0 for ebooks
• ebookProgress — used for ebooks (0–1 float), e.g. 0.323 for 32.3%

Example API response for an ebook:

{
    "progress": 0,
    "currentTime": 0,
    "isFinished": false,
    "ebookLocation": "epubcfi(/6/2!/4/1:0)",
    "ebookProgress": 0.3230769230769231
}

Suggested fix

itemData.progress_percentage = (progressData.ebookProgress || progressData.progress) * 100;

Note: ebookLocation should also be considered for determining the correct Hardcover progress format, as ebook progress in Hardcover may need to be expressed as a page number rather than a percentage.

Environment

• ShelfBridge version: 1.23.0 (latest)
• Audiobookshelf version: 2.x
• Ebook format: epub

[johnsturgeon]

I can confirm that the fix works

[rohit-purandare]

Hey @johnsturgeon thank you for opening this. Taking a look at the API documentation for that endpoint I do not see ebookProgress or ebookLocation as a field in the progress schema. I could be missing something or maybe it just isn't documented, but I will investigate further. Let me know if you see something different

[johnsturgeon]

Taking a look at the API documentation for that endpoint I do not see ebookProgress or ebookLocation as a field in the progress schema.

Seems those docs are out of date.

Reading this: https://www.coryd.dev/posts/2025/automating-my-reading-progress-updates

It looks like ebookprogress is correct. I don't know if Audiobookshelf has yet published an OpenAPI endpoint yet, so it might be worth opening an issue for them, but in the mean time the api is definitely there.

[rohit-purandare]

Hey, can you try shelfbridge:test? I just pushed a fix there

[johnsturgeon]

Hey, can you try shelfbridge:test? I just pushed a fix there

Hey @rohit-purandare. Thanks for getting to this! I'm travelling atm, so I can't test it. Do you have a link to the PR that I can look at?

[rohit-purandare]

Yup @johnsturgeon, take a look here.

[johnsturgeon]

ok, here are the results (not great):

root@audiobookshelf:~# docker exec -it shelfbridge node src/main.js cache --clear
05:33:25 [info]: Cache cleared successfully service="shelfbridge" version="1.23.0"
05:33:25 [info]: Cache cleared successfully service="shelfbridge" version="1.23.0"
root@audiobookshelf:~# docker exec -it shelfbridge npm run sync --force --verbose

relevant output:

05:33:43 [warn]: Blocking progress regression for I'll Never Be French (no matter what I do): Minor regression: 62.5% → 0.0% (62.5% drop) service="shelfbridge" version="1.23.0"
05:33:43 [info]: Edition selected by unified scorer service="shelfbridge" version="1.23.0" editionId=30615176 score="71.1" formatMatch="audiobook → audiobook" scoringProfile="STRICT" totalEditions=62 breakdown={"format":"100.0","popularity":"20.0","duration":"N/A","narrator":"N/A","completeness":"40.0","lengthData":"60.0","dataScore":"90.8"}

Side note, this build also oddly flipped a couple books that I had in my library to 'audiobooks' (they're not) despite there being NO ASIN and matched correctly to their ISBN

05:27:13 [info]: Marking All Systems Red as completed service="shelfbridge" version="1.23.0" progress=100 isFinished=true userBookId=13009160 editionId=30615176 format="audiobook"
05:27:22 [info]: Marking Artificial Condition as completed service="shelfbridge" version="1.23.0" progress=100 isFinished=true userBookId=13009161 editionId=31488179 format="audiobook"
05:27:49 [info]: Successfully marked All Systems Red as completed service="shelfbridge" version="1.23.0" userBookId=13009160 totalValue=11865 useSeconds=true
05:27:54 [info]: Successfully marked Artificial Condition as completed service="shelfbridge" version="1.23.0" userBookId=13009161 totalValue=9900 useSeconds=true

not sure why they say format=audiobook

[rohit-purandare]

Hey @johnsturgeon I found a bug in my sync logic. Can you give it another try? All logs are always helpful

[johnsturgeon]

Still not working, pulled and re-flushed cache and re-ran:

output

npm verbose cli /usr/local/bin/node /usr/local/bin/npm
npm info using npm@10.8.2
npm info using node@v20.20.0
npm verbose title npm run sync
npm verbose argv "run" "sync" "--force" "--loglevel" "verbose"
npm verbose logfile logs-max:10 dir:/root/.npm/_logs/2026-03-08T17_39_54_481Z-
npm verbose logfile /root/.npm/_logs/2026-03-08T17_39_54_481Z-debug-0.log
npm warn using --force Recommended protections disabled.

> shelfbridge@1.23.0 sync
> node src/main.js sync

🌉 ShelfBridge v1.23.0 - Sync

💡 Need help? Visit Docs or Get Support

17:39:55 [info]: Starting sync for user service="shelfbridge" version="1.22.3" user_id="johnsturgeon"
17:39:59 [info]: Title/author search initiated for "InnerFrench" service="shelfbridge" version="1.23.0" searchTitle="InnerFrench" normalizedSearchTitle="innerfrench" searchAuthor="innerFrench" searchNarrator="N/A" userFormat="ebook" maxResults=5 confidenceThreshold="70.0%" sourceBookMetadata={"series":"N/A","seriesPosition":"N/A","publicationYear":2026,"bookId":"515e4373-d6c9-41eb-b5db-0f8a98d5c449"}
17:40:05 [info]: Updating progress for This Way Out! service="shelfbridge" version="1.23.0" progress=0 userBookId=13244821 editionId=32760533 format="text"
17:40:05 [info]: Updating progress for edition 32760533 with format: Ebook service="shelfbridge" version="1.23.0"
17:40:09 [warn]: Blocking progress regression for I'll Never Be French (no matter what I do): Minor regression: 62.5% → 0.0% (62.5% drop) service="shelfbridge" version="1.23.0"
17:40:09 [info]: Title/author search initiated for "French with Jeanne" service="shelfbridge" version="1.23.0" searchTitle="French with Jeanne" normalizedSearchTitle="french with jeanne" searchAuthor="French with Jeanne" searchNarrator="N/A" userFormat="ebook" maxResults=5 confidenceThreshold="70.0%" sourceBookMetadata={"series":"N/A","seriesPosition":"N/A","publicationYear":2026,"bookId":"ab4ee71d-f3f4-4ad9-8700-a2e3c1a1642d"}
17:40:15 [info]: Title/author search results for "InnerFrench" service="shelfbridge" version="1.23.0" resultCount=2 searchMetadata={"searchTitle":"InnerFrench","searchAuthor":"innerFrench","searchNarrator":"N/A","searchTimestamp":1772991615946,"searchStrategy":"title_only_fallback"} results=[{"title":"Entre Nous: A Woman's Guide to Finding Her Inner French Girl","author":"Debra Ollivier","bookId":"1761586","hasEditions":false,"editionCount":0,"series":"N/A","seriesPosition":"N/A","publicationYear":"N/A","identifiers":{"isbn_10":"N/A","isbn_13":"N/A","asin":"N/A"},"formats":[],"usersCount":"N/A","ratingsCount":"N/A","averageRating":"N/A"},{"title":"Pardon My French: Unleash Your Inner Gaul","author":"Charles Timoney","bookId":"1705139","hasEditions":false,"editionCount":0,"series":"N/A","seriesPosition":"N/A","publicationYear":"N/A","identifiers":{"isbn_10":"N/A","isbn_13":"N/A","asin":"N/A"},"formats":[],"usersCount":1,"ratingsCount":"N/A","averageRating":"N/A"}]
17:40:15 [info]: Title/author scoring results for "InnerFrench" service="shelfbridge" version="1.23.0" targetTitle="InnerFrench" targetAuthor="innerFrench" threshold="70.0%" candidates=[{"rank":1,"title":"Entre Nous: A Woman's Guide to Finding Her Inner French Girl","author":"Debra Ollivier","score":"33.3%","confidence":"none","isBookMatch":false,"passesThreshold":false,"breakdown":{"title":{"score":"33.2%","weight":"35.0%","comparison":"\"InnerFrench\" vs \"Entre Nous: A Woman's Guide to Finding Her Inner French Girl\""},"author":{"score":"34.7%","weight":"25.0%","comparison":"\"innerFrench\" vs \"Debra Ollivier\""},"series":{"score":"60.0%","weight":"15.0%","reason":"No series data for comparison"},"activity":{"score":"30.0%","weight":"10.0%","value":"N/A"},"year":{"score":"20.0%","weight":"5.0%","comparison":"2026 vs 2003"},"penalties":[]}},{"rank":2,"title":"Pardon My French: Unleash Your Inner Gaul","author":"Charles Timoney","score":"32.5%","confidence":"none","isBookMatch":false,"passesThreshold":false,"breakdown":{"title":{"score":"34.0%","weight":"35.0%","comparison":"\"InnerFrench\" vs \"Pardon My French: Unleash Your Inner Gaul\""},"author":{"score":"30.4%","weight":"25.0%","comparison":"\"innerFrench\" vs \"Charles Timoney\""},"series":{"score":"60.0%","weight":"15.0%","reason":"No series data for comparison"},"activity":{"score":"30.0%","weight":"10.0%","value":"N/A"},"year":{"score":"20.0%","weight":"5.0%","comparison":"2026 vs 2007"},"penalties":[]}}]
17:40:15 [info]: No suitable match found for "InnerFrench" service="shelfbridge" version="1.23.0" searchedTitle="InnerFrench" searchedAuthor="innerFrench" threshold="70.0%" candidatesEvaluated=2 bestScore="33.3%" reason="Best candidate failed book identification criteria" outcome="MATCH_REJECTED"
17:40:15 [info]: Skipping InnerFrench: No ISBN, ASIN, or title/author match found service="shelfbridge" version="1.23.0"
17:40:15 [info]: Edition selected by unified scorer service="shelfbridge" version="1.23.0" editionId=30615176 score="71.1" formatMatch="audiobook → audiobook" scoringProfile="STRICT" totalEditions=62 breakdown={"format":"100.0","popularity":"20.0","duration":"N/A","narrator":"N/A","completeness":"40.0","lengthData":"60.0","dataScore":"90.8"}
17:40:31 [info]: Title/author search results for "French with Jeanne" service="shelfbridge" version="1.23.0" resultCount=5 searchMetadata={"searchTitle":"French with Jeanne","searchAuthor":"French with Jeanne","searchNarrator":"N/A","searchTimestamp":1772991631279,"searchStrategy":"title_and_author"} results=[{"title":"The Picture of Dorian Gray","author":"Oscar Wilde, Susan Beattie","bookId":"436692","hasEditions":false,"editionCount":0,"series":"N/A","seriesPosition":"N/A","publicationYear":"N/A","identifiers":{"isbn_10":"N/A","isbn_13":"N/A","asin":"N/A"},"formats":[],"usersCount":5632,"ratingsCount":2358,"averageRating":"N/A"},{"title":"The Lord of the Rings","author":"J.R.R. Tolkien","bookId":"377938","hasEditions":false,"editionCount":0,"series":"N/A","seriesPosition":"N/A","publicationYear":"N/A","identifiers":{"isbn_10":"N/A","isbn_13":"N/A","asin":"N/A"},"formats":[],"usersCount":3571,"ratingsCount":1546,"averageRating":"N/A"},{"title":"The Little Prince","author":"Antoine de Saint-Exupéry","bookId":"115005","hasEditions":false,"editionCount":0,"series":"N/A","seriesPosition":"N/A","publicationYear":"N/A","identifiers":{"isbn_10":"N/A","isbn_13":"N/A","asin":"N/A"},"formats":[],"usersCount":4382,"ratingsCount":2509,"averageRating":"N/A"},{"title":"The Iliad","author":"Homer","bookId":"428716","hasEditions":false,"editionCount":0,"series":"N/A","seriesPosition":"N/A","publicationYear":"N/A","identifiers":{"isbn_10":"N/A","isbn_13":"N/A","asin":"N/A"},"formats":[],"usersCount":1616,"ratingsCount":466,"averageRating":"N/A"},{"title":"Macbeth","author":"William Shakespeare, Roma Gill","bookId":"383496","hasEditions":false,"editionCount":0,"series":"N/A","seriesPosition":"N/A","publicationYear":"N/A","identifiers":{"isbn_10":"N/A","isbn_13":"N/A","asin":"N/A"},"formats":[],"usersCount":2022,"ratingsCount":1073,"averageRating":"N/A"}]
17:40:31 [info]: Title/author scoring results for "French with Jeanne" service="shelfbridge" version="1.23.0" targetTitle="French with Jeanne" targetAuthor="French with Jeanne" threshold="70.0%" candidates=[{"rank":1,"title":"The Little Prince","author":"Antoine de Saint-Exupéry","score":"36.9%","confidence":"none","isBookMatch":false,"passesThreshold":false,"breakdown":{"title":{"score":"31.6%","weight":"35.0%","comparison":"\"French with Jeanne\" vs \"The Little Prince\""},"author":{"score":"51.4%","weight":"25.0%","comparison":"\"French with Jeanne\" vs \"Antoine de Saint-Exupéry\""},"series":{"score":"60.0%","weight":"15.0%","reason":"No series data for comparison"},"activity":{"score":"30.0%","weight":"10.0%","value":"N/A"},"year":{"score":"20.0%","weight":"5.0%","comparison":"2026 vs 1943"},"penalties":[]}},{"rank":2,"title":"The Picture of Dorian Gray","author":"Oscar Wilde, Susan Beattie","score":"36.5%","confidence":"none","isBookMatch":false,"passesThreshold":false,"breakdown":{"title":{"score":"33.0%","weight":"35.0%","comparison":"\"French with Jeanne\" vs \"The Picture of Dorian Gray\""},"author":{"score":"47.6%","weight":"25.0%","comparison":"\"French with Jeanne\" vs \"Oscar Wilde, Susan Beattie\""},"series":{"score":"60.0%","weight":"15.0%","reason":"No series data for comparison"},"activity":{"score":"30.0%","weight":"10.0%","value":"N/A"},"year":{"score":"20.0%","weight":"5.0%","comparison":"2026 vs 1890"},"penalties":[]}},{"rank":3,"title":"The Lord of the Rings","author":"J.R.R. Tolkien","score":"35.8%","confidence":"none","isBookMatch":false,"passesThreshold":false,"breakdown":{"title":{"score":"34.5%","weight":"35.0%","comparison":"\"French with Jeanne\" vs \"The Lord of the Rings\""},"author":{"score":"43.0%","weight":"25.0%","comparison":"\"French with Jeanne\" vs \"J.R.R. Tolkien\""},"series":{"score":"60.0%","weight":"15.0%","reason":"No series data for comparison"},"activity":{"score":"30.0%","weight":"10.0%","value":"N/A"},"year":{"score":"20.0%","weight":"5.0%","comparison":"2026 vs 1954"},"penalties":[]}},{"rank":4,"title":"Macbeth","author":"William Shakespeare, Roma Gill","score":"31.8%","confidence":"none","isBookMatch":false,"passesThreshold":false,"breakdown":{"title":{"score":"27.2%","weight":"35.0%","comparison":"\"French with Jeanne\" vs \"Macbeth\""},"author":{"score":"36.9%","weight":"25.0%","comparison":"\"French with Jeanne\" vs \"William Shakespeare, Roma Gill\""},"series":{"score":"60.0%","weight":"15.0%","reason":"No series data for comparison"},"activity":{"score":"30.0%","weight":"10.0%","value":"N/A"},"year":{"score":"20.0%","weight":"5.0%","comparison":"2026 vs 1508"},"penalties":[]}},{"rank":5,"title":"The Iliad","author":"Homer","score":"31.6%","confidence":"none","isBookMatch":false,"passesThreshold":false,"breakdown":{"title":{"score":"23.4%","weight":"35.0%","comparison":"\"French with Jeanne\" vs \"The Iliad\""},"author":{"score":"36.8%","weight":"25.0%","comparison":"\"French with Jeanne\" vs \"Homer\""},"series":{"score":"60.0%","weight":"15.0%","reason":"No series data for comparison"},"activity":{"score":"30.0%","weight":"10.0%","value":"N/A"},"year":{"score":"45.0%","weight":"5.0%","comparison":"2026 vs N/A"},"penalties":[]}}]
17:40:31 [info]: No suitable match found for "French with Jeanne" service="shelfbridge" version="1.23.0" searchedTitle="French with Jeanne" searchedAuthor="French with Jeanne" threshold="70.0%" candidatesEvaluated=5 bestScore="36.9%" reason="Best candidate failed book identification criteria" outcome="MATCH_REJECTED"
17:40:31 [info]: Skipping French with Jeanne: No ISBN, ASIN, or title/author match found service="shelfbridge" version="1.23.0"
17:40:31 [info]: Edition selected by unified scorer service="shelfbridge" version="1.23.0" editionId=31488179 score="72.0" formatMatch="audiobook → audiobook" scoringProfile="STRICT" totalEditions=40 breakdown={"format":"100.0","popularity":"20.0","duration":"N/A","narrator":"N/A","completeness":"40.0","lengthData":"60.0","dataScore":"100.0"}
17:40:40 [info]: Marking All Systems Red as completed service="shelfbridge" version="1.23.0" progress=100 isFinished=true userBookId=13009160 editionId=30615176 format="audiobook"
17:40:50 [info]: Successfully updated progress for This Way Out! service="shelfbridge" version="1.23.0" userBookId=13244821 progressPercent=0 progress_pages=1 resultId=4824051
17:41:01 [info]: Marking Artificial Condition as completed service="shelfbridge" version="1.23.0" progress=100 isFinished=true userBookId=13009161 editionId=31488179 format="audiobook"
17:41:19 [info]: Successfully marked All Systems Red as completed service="shelfbridge" version="1.23.0" userBookId=13009160 totalValue=11865 useSeconds=true
17:41:26 [info]: Successfully marked Artificial Condition as completed service="shelfbridge" version="1.23.0" userBookId=13009161 totalValue=9900 useSeconds=true

✅ Sync complete for user: johnsturgeon in 91.3s
══════════════════════════════════════════════════
📚 SYNC COMPLETE (91.3s)
══════════════════════════════════════════════════
📚 Library Status               🌐 Hardcover Updates
├─ 2 libraries processed        ├─ 3 API calls made
├─ 33 total books               ├─ 3 successful
├─ 3 currently reading          ├─ 0 failed
├─ 3 completed                  └─ 3 skipped (no changes)
└─ 27 never started
                                ✅ Sync Status
📊 Processing Results           ├─ All updates successful
├─ 1 progress updated           ├─ No errors occurred
├─ 2 completed books processed  ├─ Cache updated
└─ 3 skipped (no change)        └─ Ready for next sync
══════════════════════════════════════════════════

npm verbose cwd /app
npm verbose os Linux 6.8.12-17-pve
npm verbose node v20.20.0
npm verbose npm  v10.8.2
npm verbose exit 0
npm info ok

Hard Cover:

Audiobookshelf: