v0.1.1 - !! BREAKING / DATA LOSS !!

👋 Intro

Hey everyone! I’ve been dealing with some family issues over the past two months, which kept me away from working on KoInsight. Despite the interruptions, I’ve slowly chipped away at this release - and it's finally in a shape I feel confident I can release! I hope to resume steady (even if slow) progress on KoInsight from now on.

This release includes significant under-the-hood changes that pave the way for future features.

NOTE: I expect there may be bugs to iron out 😅

🚨 DATA LOSS WARNING 🚨

If you haven’t reset your device or uninstalled KOReader, your data should still be intact on your device. After syncing again, your data should reappear in KoInsight.

Note: KOSync data and registrations should remain unaffected.

Read the "Under the Hood" section if you want a bit longer explanation as to why this happened.

♻️ Plugin versioning

The KOReader KoInsight plugin is now versioned. Your KoInsight server will start rejecting uploads from older plugin versions due to incompatibility.

✨ New features

📏 Reference pages

One of the challenges about tracking pages read is that KOReader statistics report pages based on your current page layout. Changing the font size or style causes the book to reflow, altering the page count.

The new Reference Pages feature lets you define the actual number of pages in the physical book, allowing KoInsight to normalize progress across devices and layouts.

Example:

• Your physical copy of Book A has 100 pages.
• You also have an epub which you open on your 7" eReader. With adjusted font size it is 150 pages.
• On your 6" device (Bigme Hibreak Pro anyone?) it's 200 pages.

Once you start reading, the 7" device will report "page 1 of 150", "page 2 of 150", etc; and the 6" will report likewise - "page 4 of 200, page 5 of 200". How many pages did you read?

With the reference set to 100, KoInsight adjusts counts accordingly: pages on the 6" device count as 0.5 each.

👻 Book hiding

Previously, deleted books couldn’t be restored. While the deletion was technically a "soft delete," the feature wasn’t exposed. Now it is! (Thanks for raising #14 and #17 to keep track of that!)

You can now hide books instead of deleting them. Hidden books:

• Are removed from the book list.
• Do not contribute to statistics.
• Can be shown again later.

Hidden books appear with dimmed covers and a hidden icon. You can unhide them from the book’s Manage Data menu.

🗑️ Deletion

Book deletion is still an option! This time though, it is the hardcore path - this will permanently remove the book and its stats.

Note: On the next sync from KOReader, the book may be re-imported if data about it still exists on your device.

🔍 Manual cover search

Thanks to @dannoh, you can now enter a specific search query when manually searching for covers via OpenLibrary:

🛠️ Under the Hood

📚 Improved Book Storage & Multi-Device Sync

I realized KOReader book ids are very much not unique. This is a problem when you're uploading data about a book from multiple devices. KoInsight now uses the book’s MD5 hash to uniquely track books.

New internal structure:

1. Device metadata (ID, model)
2. Per-device book data (last open time, notes, highlights, pages read, reading time, statistics)

This lays the foundation for more accurate and device-specific analytics in the future.

Unfortunately, to make this change I had to:

• Change the type of the md5 field
• Alter the book table to use he md5 field as unique identifier
• Alter the page_stat table to reference book.md5 as a foreign key.
  These table modifications cause SQLite to drop all table data.

✅ Unit testing

The back-end server is now partially covered with unit tests - starting with the most error-prone area: statistics computation.

You can view coverage reports here: Coveralls. I covered the statistics computation parts, which is one of the more error-prone areas.

🚀 That’s it!

Thanks for your patience and support. Please open issues if you encounter any bugs. Looking forward to sharing more soon.