drallgood/audiobookshelf-hardcover-sync v1.3.0

🚀 v1.3.0 - Incremental Sync & Performance Improvements

on GitHub

Major New Features

🚀 Incremental/Delta Sync

• Major performance improvement with timestamp-based incremental syncing
• Added persistent sync state management with sync_state.json file
• Only processes books with changes since last sync using AudiobookShelf listening session timestamps
• Automatic fallback to full sync when incremental data is unavailable or on first run
• Configurable sync modes: enabled (default), disabled, or auto
• Smart full sync scheduling: automatically performs full sync after 7 days or when forced
• Reduces API calls significantly for large libraries with minimal changes

🎛️ New Configuration Options

• INCREMENTAL_SYNC_MODE: Control incremental sync behavior
• SYNC_STATE_FILE: Custom path for sync state storage (default: sync_state.json)
• FORCE_FULL_SYNC: Force full sync on next run (automatically resets after use)

Bug Fixes & Improvements

🐛 Critical Fixes

• LibraryItemID Field Reference: Fixed incorrect field access in incremental sync filtering
• Duplicate User Book Reads: Fixed issue where multiple user_book_reads entries were created for the same book when reading across different days
• Runtime Panic Fix: Fixed crash when Hardcover returns user_book_reads with null started_at values

⚡ Performance Optimizations

• Reduced API calls: From 3 per book to 1 per sync run for getCurrentUser() operations
• Smart caching: Added user authentication caching mechanism
• For 100 books: Reduces from 300 API calls to 1 per sync session

Technical Details

• Added comprehensive test coverage for incremental sync functionality
• Enhanced fetchRecentListeningSessions() to query AudiobookShelf sessions API with timestamp filtering
• Modified runSync() to integrate incremental sync logic with existing sync workflow
• Backward compatible: existing setups continue to work without configuration changes

Getting Started

Docker (Recommended)

docker pull ghcr.io/drallgood/audiobookshelf-hardcover-sync:v1.3.0

Environment Variables

Add to your .env file:

# Optional: incremental sync mode - "enabled" (default), "disabled", "auto"
INCREMENTAL_SYNC_MODE=enabled
# Optional: path to sync state file (default: sync_state.json)
SYNC_STATE_FILE=sync_state.json
# Optional: force full sync on next run (automatically resets after use)
FORCE_FULL_SYNC=false

Note: No configuration changes required for existing users - incremental sync is enabled by default and backward compatible.

This release consolidates improvements that were previously planned for v1.2.5 along with the major new incremental sync feature.