audiobookshelf-hardcover-sync

Note: This README reflects the latest development version. For documentation specific to the latest stable release, please check the latest release on GitHub.

Automatically syncs your Audiobookshelf library with Hardcover, including reading progress, book status, and ownership information.

🎉 Multi-Profile Sync Support (v3.0.0+)

audiobookshelf-hardcover-sync now supports multiple sync profiles with a modern web interface and secure token management!

Key Features

• 🌐 Web Management Interface: Modern, responsive web UI at http://localhost:8080
• 👥 Multiple Sync Profiles: Each profile can have individual Audiobookshelf and Hardcover tokens
• 🔒 Secure Storage: All API tokens encrypted at rest with AES-256-GCM
• 🔄 Concurrent Syncing: Multiple profiles can sync simultaneously
• 📊 Real-Time Monitoring: Live sync status with auto-refresh
• 🔧 REST API: Complete programmatic control via RESTful endpoints
• ⬆️ Automatic Migration: Seamless upgrade from single-profile setups
• 🔙 Backwards Compatible: All existing functionality preserved
• 🚀 Cache Busting: Automatic cache invalidation ensures profiles always get the latest UI updates

Quick Start (Multi-User)

1. Start the application with web UI enabled: ```bash # Using environment variable ENABLE_WEB_UI=true ./audiobookshelf-hardcover-sync --server-only

# Using config file (recommended) # Set enable_web_ui: true in your config.yaml ./audiobookshelf-hardcover-sync --server-only ```

1. Access the web interface: Open http://localhost:8080 in your browser

2. Add Sync Profiles: Use the "Add Profile" tab to create profiles with individual tokens

3. Monitor syncs: View real-time sync status and control operations

Migration from Single-Profile

Existing single-profile setups are automatically migrated on first startup:

• Your existing config.yaml is detected and backed up
• A "Default Profile" is created with your current configuration
• All functionality continues to work as before
• Access the new web interface at http://localhost:8080

REST API Endpoints

Environment Variables (Multi-Profile)

Security Features

• Token Encryption: All API tokens encrypted at rest
• Profile Management: Full CRUD operations for sync profiles data
• Secure Key Management: Auto-generated encryption keys
• Token Masking: Sensitive data masked in API responses
• Directory Protection: Static file serving with traversal protection

Project Structure

The project follows standard Go project layout:

.
├── cmd/                          # Main application entry points
│   └── audiobookshelf-hardcover-sync/  # Main application
├── internal/                     # Private application code
│   ├── api/                      # Multi-user API handlers
│   │   ├── audiobookshelf/       # Audiobookshelf API client
│   │   ├── hardcover/            # Hardcover API client
│   │   └── handlers.go           # REST API endpoints
│   ├── auth/                     # Authentication system
│   │   ├── handlers.go           # Auth HTTP handlers (login/logout)
│   │   ├── local.go              # Local username/password provider
│   │   ├── middleware.go         # Auth middleware and RBAC
│   │   ├── models.go             # User, session, provider models
│   │   ├── oidc.go               # Keycloak/OIDC provider
│   │   ├── provider.go           # Auth provider interface
│   │   ├── repository.go         # Database operations
│   │   ├── service.go            # Auth service orchestration
│   │   └── session.go            # Session management
│   ├── config/                   # Configuration loading and validation
│   ├── crypto/                   # Encryption utilities
│   │   └── encryption.go         # AES-256-GCM token encryption
│   ├── database/                 # Database layer
│   │   ├── database.go           # Connection management
│   │   ├── migration.go          # Single-user to multi-user migration
│   │   ├── models.go             # User, config, sync state models
│   │   └── repository.go         # CRUD operations
│   ├── logger/                   # Structured logging
│   ├── models/                   # Data structures
│   ├── multiuser/                # Multi-user service
│   │   └── service.go            # User management and sync orchestration
│   ├── server/                   # HTTP server
│   │   └── server.go             # Routing and middleware setup
│   ├── services/                 # Business logic
│   ├── sync/                     # Sync logic
│   └── utils/                    # Utility functions
├── pkg/                          # Public libraries
│   ├── cache/                    # Caching implementation
│   ├── edition/                  # Edition creation logic
│   └── mismatch/                 # Mismatch detection
├── web/                          # Web UI assets
│   └── static/                   # Static files
│       ├── app.js                # Multi-user management JavaScript
│       ├── index.html            # Web dashboard
│       ├── login.html            # Authentication login page
│       └── styles.css            # Modern responsive styling
├── docs/                         # Documentation
│   ├── AUTHENTICATION.md        # Authentication setup guide
│   └── helm-chart-publishing.md  # Helm deployment guide
├── helm/                         # Kubernetes Helm chart
│   └── audiobookshelf-hardcover-sync/
└── test/                         # Test files
    ├── testdata/                 # Test data
    ├── unit/                     # Unit tests
    ├── integration/              # Integration tests
    └── e2e/                      # End-to-end tests

Development

Features

🎉 Multi-Profile Sync Support (v3.0.0+)

• 👥 Multiple Sync Profiles: Individual Audiobookshelf and Hardcover tokens per profile
• 🌐 Web Interface: Modern, responsive management dashboard at http://localhost:8080
• 🔒 Secure Storage: AES-256-GCM encrypted token storage
• 🔄 Concurrent Syncing: Multiple users can sync simultaneously
• 📊 Real-Time Monitoring: Live sync status with auto-refresh
• 🔧 REST API: Complete programmatic control via RESTful endpoints
• ⬆️ Automatic Migration: Seamless upgrade from single-user setups
• 🔙 Backwards Compatible: All existing functionality preserved

📚 Core Sync Features

• Full Library Sync: Syncs your entire Audiobookshelf library with Hardcover
• Smart Status Management: Automatically sets "Want to Read", "Currently Reading", and "Read" status based on progress
• Ownership Tracking: Marks synced books as "owned" to distinguish from wishlist items
• Incremental Sync: Efficient state-based syncing to only process changed books
• Tracks sync state between runs
• Configurable minimum change threshold
• Persistent state storage
• Smart Caching: Intelligent caching of author/narrator lookups with cross-role discovery
• Enhanced Progress Detection: Uses /api/me endpoint for accurate finished book detection, preventing false re-read scenarios

🔧 Operations & Management

• Periodic Sync: Configurable automatic syncing (e.g., every 10 minutes or 1 hour)
• Manual Sync: HTTP endpoints for on-demand synchronization
• Health Monitoring: Built-in health check endpoint
• Configurable Logging: JSON or console (human-readable) output with configurable log levels

🛠️ Developer Tools

• Edition Creation Tools: Interactive tools for creating missing audiobook editions
• ID Lookup: Search and verify author, narrator, and publisher IDs from Hardcover database
• Container Ready: Multi-arch Docker images (amd64, arm64)
• Production Ready: Secure, minimal, and battle-tested

Quick Start

Prerequisites

• Go 1.21 or later
• Docker (optional, for containerized deployment)
• Audiobookshelf instance with API access
• Hardcover API token

Local Development

1. Clone the repository: sh git clone https://github.com/drallgood/audiobookshelf-hardcover-sync.git cd audiobookshelf-hardcover-sync

2. Install dependencies: sh make deps

3.### Configuration

Create a config.yaml file based on the example:

cp config.example.yaml config.yaml

Edit the configuration to match your environment. See Configuration Reference for all available options.

Important Configuration Changes

Deprecation Notice: The app section in the configuration is now deprecated and will be removed in a future version. Please migrate to the new sync section.

Migrating from old configuration (app.) to new configuration (sync.):

# Old deprecated format (app.*):
# app:
#   sync_interval: "1h"
#   minimum_progress: 0.01
#   sync_want_to_read: true
#   sync_owned: false
#   dry_run: false

# New format (sync.*):
sync:
  sync_interval: "1h"
  minimum_progress: 0.01
  sync_want_to_read: true
  sync_owned: false
  dry_run: false
  # Other sync settings...

The application will automatically migrate settings from the old app section to the new sync section and log a warning if any deprecated settings are found.

1. Build and run the application: sh make build ./bin/audiobookshelf-hardcover-sync

Running with Docker

Prerequisites

• Docker installed on your system
• Docker Compose (recommended for the main sync service)
• Hardcover API token
• (Optional) Audiobookshelf URL and token if using the sync service

Main Sync Service

Using Docker Compose (Recommended)

1. Create a project directory and navigate to it: bash mkdir -p ~/abs-hardcover-sync && cd ~/abs-hardcover-sync

2. Create a docker-compose.yml file: ```yaml version: '3.8'

services: audiobookshelf-hardcover-sync: image: ghcr.io/drallgood/audiobookshelf-hardcover-sync:latest container_name: abs-hardcover-sync restart: unless-stopped volumes: - ./config:/app/config # For configuration files - ./data:/app/data # For persistent storage and state - ./logs:/app/logs # For log files (optional) # Optional environment variables (config file takes precedence) environment: - CONFIG_PATH=/app/config/config.yaml - LOG_LEVEL=info healthcheck: test: ["CMD", "wget", "--spider", "http://localhost:8080/healthz"] interval: 30s timeout: 10s retries: 3 start_period: 10s ```

1. Create a config directory and config.yaml file: bash mkdir -p config && touch config/config.yaml

2. Add your configuration to config.yaml: ```yaml audiobookshelf: url: https://your-abs-server.com token: your_abs_token

hardcover: token: your_hardcover_token

sync: interval: 10m state_file: /app/data/sync_state.json

logging: level: info format: json # or text for improved readability during development ```

1. Create data directories: bash mkdir -p data logs

2. Start the service: bash docker compose up -d

3. View logs: ```bash # Follow logs docker compose logs -f

# View recent logs (last 100 lines) docker compose logs --tail=100

# View logs for a specific time period docker compose logs --since 1h ```

1. Common management commands: ```bash # Stop the service docker compose down

# Restart the service docker compose restart

# Update to the latest version docker compose pull docker compose up -d --force-recreate ```

Using Helm (Kubernetes)

For Kubernetes deployments, use the official Helm chart:

1. Add the Helm repository: ```bash

Stable releases (from main)

helm repo add audiobookshelf-hardcover-sync \ https://drallgood.github.io/audiobookshelf-hardcover-sync/stable

Dev channel (from develop)

helm repo add audiobookshelf-hardcover-sync-dev \ https://drallgood.github.io/audiobookshelf-hardcover-sync/dev helm repo update ``