KOBO_ANNOTATION_SYNC

Kobo Annotation Sync to Hardcover.app

Overview

This feature automatically syncs annotations (highlights and notes) from your Kobo e-reader to your Hardcover.app reading journal. Whenever you highlight text or add notes on your Kobo device, they will be automatically uploaded to Hardcover when you sync your device.

Features

• Automatic sync: Annotations sync automatically when your Kobo device connects
• Bidirectional updates: Edited annotations on Kobo update on Hardcover
• Deletion support: Deleting annotations on Kobo removes them from Hardcover
• Progress tracking: Includes reading progress with each annotation
• Markdown protection: Annotations are safely escaped to prevent formatting issues

Prerequisites

1. Kobo Sync Enabled: Your CWA instance must have Kobo sync configured
2. Hardcover Account: You need a Hardcover.app account with API token
3. Book Identifiers: Books must have Hardcover identifiers (hardcover-id, hardcover-edition, or hardcover-slug)

Setup Instructions

1. Enable Annotation Sync

1. Log in to CWA as an admin
2. Navigate to Admin → Basic Configuration
3. Find the Kobo section
4. Enable Kobo Annotation Sync to Hardcover
5. Click Save

2. Get Your Hardcover API Token

1. Visit Hardcover.app
2. Log in to your account
3. Go to Settings → Developer API
4. Copy your API token

3. Configure User Settings

1. Navigate to Your Profile → Edit Profile
2. Find the Hardcover Integration section
3. Paste your API token
4. Click Save

4. Add Book Identifiers

For each book you want to sync annotations for:

1. Edit the book metadata in CWA
2. Add one of these identifiers:
   • hardcover-id: The Hardcover book ID (e.g., 12345)
   • hardcover-edition: The Hardcover edition ID
   • hardcover-slug: The book's URL slug (e.g., the-lord-of-the-rings)

Tip: You can find these in the Hardcover book URL:

• URL: https://hardcover.app/books/the-lord-of-the-rings
• Slug: the-lord-of-the-rings

How It Works

Creating Annotations

1. Highlight text or add a note on your Kobo device
2. Sync your Kobo with CWA
3. CWA detects the new annotation
4. The annotation is formatted and sent to Hardcover:
   • Highlights appear as blockquotes
   • Notes appear as regular text
   • Reading progress is calculated and included
5. The annotation appears in your Hardcover reading journal

Editing Annotations

1. Edit an annotation on your Kobo device
2. Sync your Kobo with CWA
3. CWA detects the change
4. The existing Hardcover journal entry is updated

Deleting Annotations

1. Delete an annotation on your Kobo device
2. Sync your Kobo with CWA
3. CWA detects the deletion
4. The corresponding Hardcover journal entry is removed

Blacklisting Books

If you don't want annotations from a specific book to sync to Hardcover:

1. Edit the book in CWA
2. Find the Hardcover Settings section
3. Enable Blacklist Annotations
4. Click Save

Note: This prevents new annotations from syncing. Existing annotations remain on Hardcover.

Progress Calculation

CWA calculates your exact reading progress by:

1. Parsing the EPUB/KEPUB file structure
2. Analyzing the spine (reading order)
3. Counting characters in each chapter
4. Determining your position in the book
5. Converting to a percentage

This provides more accurate progress tracking than simple page numbers.

Troubleshooting

Annotations Not Syncing

Check these items:

1. ✅ Kobo Sync is enabled (Admin → Basic Configuration)
2. ✅ Annotation Sync is enabled (Admin → Basic Configuration)
3. ✅ You have a valid Hardcover API token (Profile → Edit)
4. ✅ The book has Hardcover identifiers (Edit Book → Identifiers)
5. ✅ The book is not blacklisted (Edit Book → Hardcover Settings)

No Progress Information

Progress calculation requires:

• The book must be in EPUB or KEPUB format
• The file must be accessible by CWA
• The EPUB structure must be valid

If progress calculation fails, annotations still sync but without progress data.

Duplicate Annotations

This can happen if:

• The sync was interrupted and retried
• The book identifiers changed
• Manual entries were created on Hardcover

Solution: Delete duplicates manually on Hardcover.app

Missing Hardcover Identifiers

If a book doesn't have Hardcover identifiers:

1. Search for the book on Hardcover.app
2. Copy the book slug from the URL
3. Add it as hardcover-slug identifier in CWA
4. Annotations will start syncing on next sync

Privacy Settings

Annotations inherit your Hardcover account privacy settings. To change:

1. Go to Hardcover.app → Settings → Privacy
2. Adjust your default privacy level
3. New annotations will use the new setting

Note: CWA uses your account's default privacy level for all synced annotations.

Technical Details

Annotation Format

Annotations are formatted as:

Highlight only:

> This is the highlighted text

Highlight with note:

> This is the highlighted text

 -- This is my note about the highlight

Note only:

This is my standalone note

Metadata

Each annotation includes:

• Tags: Automatically tagged with "CWA" and "Kobo"
• Progress: Reading progress as page number and percentage
• Timestamp: When the annotation was created on Kobo
• Event type: Either "quote" (highlight) or "note"

Database Tracking

CWA tracks synced annotations in the kobo_annotation_sync table to:

• Prevent duplicate syncs
• Enable updates and deletions
• Link Kobo annotations to Hardcover journal entries

API Rate Limits

Hardcover.app has API rate limits. If you sync many annotations at once:

• Syncing happens sequentially (one at a time)
• Large batches may take several minutes
• Failed syncs are logged but don't block others

Security

• API tokens are stored encrypted in the database
• Annotations are sanitized to prevent markdown injection
• Only authenticated users can sync annotations
• HTTPS is used for all API communication

Support

For issues or questions:

1. Check the CWA logs: Admin → Logs → CWA Logs
2. Search for "annotation" or "hardcover" in the logs
3. Report issues on GitHub with relevant log excerpts

Feature Limitations

Current limitations:

• ❌ Cannot sync annotations created before enabling the feature
• ❌ Cannot sync annotations from other e-reader apps
• ❌ Progress calculation only works for EPUB/KEPUB formats
• ❌ No bulk import of historical annotations
• ✅ Real-time sync on every Kobo connection
• ✅ Supports all Kobo annotation types
• ✅ Preserves annotation formatting

Credits

This feature was contributed by @wolffshots in PR #731.