AI SummaryCopilot instructions for developing and maintaining a Go application that syncs reading progress and book metadata between AudiobookShelf and Hardcover platforms. Developers building or contributing to this sync tool benefit from clear architectural guidance and API integration patterns.
Install
Copy this and paste it into Claude Code, Cursor, or any AI assistant:
I want to add the "audiobookshelf-hardcover-sync — Copilot Instructions" prompt rules to my project. Repository: https://github.com/drallgood/audiobookshelf-hardcover-sync Please read the repo to find the rules/prompt file, then: 1. Download it to the correct location (.cursorrules, .windsurfrules, .github/prompts/, or project root — based on the file type) 2. If there's an existing rules file, merge the new rules in rather than overwriting 3. Confirm what was added
Description
Syncs Audiobookshelf to Hardcover
Project Overview
This is a Go application that syncs reading progress and book data between AudiobookShelf and Hardcover. It uses GraphQL for Hardcover API interactions and REST for AudiobookShelf.
Code Structure
• main.go - Entry point and version info • config.go - Environment variable configuration with getter functions • sync.go - Core synchronization logic • hardcover.go - Hardcover GraphQL API interactions • audiobookshelf.go - AudiobookShelf REST API interactions • types.go - Data structures and type definitions • utils.go - Utility functions • incremental.go - Incremental sync functionality • mismatch.go - Mismatch detection and collection features • enhanced_progress_detection.go - Enhanced progress detection using /api/me endpoint • docs/ - Documentation for specific features and fixes • mismatches/ - can be ignored
API definitions
• Use GraphQL for Hardcover API, see hardcover-schema.graphql for schema definitions • Use REST for AudiobookShelf API, documented in audiobookshelf-openapi.json • AudiobookShelf git project https://github.com/advplyr/audiobookshelf/tree/master and (outdated) API docs https://api.audiobookshelf.org/ • Important: Hardcover ownership is stored in the lists table (via "Owned" list), NOT in user_books.owned field • The user_books.owned field is unreliable and always returns false - use getOwnedBooks() and isBookOwnedDirect() functions instead • Enhanced Progress Detection: Uses /api/me endpoint for accurate finished book detection with isFinished flags • RE-READ Detection Logic: Fixed to check isBookFinished status before treating books as re-read scenarios to prevent false positives Hardcover API Limitations • API tokens automatically expire after 1 year, and reset on January 1st. • API is rate-limited to 60 requests per minute. • The following queries are disabled: • _like • _nlike • _ilike • _niregex • _nregex • _iregex • _regex • _nsimilar • _similar • Queries have a max timeout of 30 seconds. • Queries have a maximum depth of 3.
Testing
• All new features should include comprehensive test coverage • Use go test -v ./... to run all tests • Test files follow Go conventions with pattern *_test.go in the root directory (same package as source) • Current test files: main_test.go, format_test.go, incremental_test.go, owned_test.go, owned_flag_test.go, want_to_read_test.go, reading_history_fix_test.go • Tests include unit tests, integration tests, and configuration validation • Use table-driven tests and subtests for comprehensive coverage
Discussion
Health Signals
My Fox Den
Community Rating
Sign in to rate this booster
Works With
Any AI assistant that accepts custom rules or system prompts