[Endle]

Last of the PRs that replace #37. #38 (transport refactor), #39 (201 / POST-retry fixes) and #42 (skip local cleanup when export fails) are merged.

Highlights exported from downloaded Reader articles currently become separate entries through the Readwise v2 API. This change sends them to Reader's POST /api/v3/save/ with the original document's parent_id and selected passage, so they attach to that document. Other books keep the existing v2 export.

• Export history: Reader highlight IDs and the notes sent with them are saved in the reader_highlights setting once per book, including when the book fails. Each passage is exported once: later syncs skip it, and notes added or edited after export are not sent. Repeated highlights of the same passage become one highlight carrying all their notes.

• Rejected passages: when Reader answers 400 (e.g. the passage is not found in its copy of the article) or 404 (article deleted), the passage is sent through the v2 highlights API instead and recorded, so Reader is not asked again. The exception is a 400 that names notes or saved_using but not content or parent_id: that is a bug in the request, so it is an export error retried on the next sync instead of silently moving passages to v2. Export continues past a rejected passage, and rejected passages are sent even if a later passage fails. Error bodies from both APIs are logged (first 500 characters). The warning for a rejected passage names its page; the passage text is logged only at debug level, since users attach logs to public issues.

• Highlights without text (e.g. image selections) are skipped and logged instead of failing the book.

• Blank notes: a KOReader log on Linux showed Reader's reason for rejecting highlights: 400 {"notes": ["This field may not be blank."]}. The plugin sent notes: "" for every highlight without a note. Create now leaves notes out when it is empty or whitespace only. This probably explains most of the rejections in the Attach exported highlights to their original Reader documents #37 device test (3 of 4 passages).

Addresses #20, following the API update reported in this comment. API contract: Reader create documentation.

Validation: 31 LuaJIT tests pass with KOReader and HTTP stubs (routing, payloads, saved history across restarts, note edits not resent, repeated passages, partial failures, 400 classification, 400/404 fallback including fallback failure and later failures, rate-limit retries, malformed responses, error logging). Luacheck reports 0 warnings. Against a real account (KOReader on Linux), Reader accepted highlights both with and without a note after the blank-notes fix, and one with a note was checked inline in the article. Saved history with quotes, newlines, backslashes, NUL bytes and long passages round-trips through KOReader's own settings serializer (dump.lua).

Limits (the main ones are in the README): highlights exported by earlier versions are not migrated; the first sync after upgrading sends those still on the device to Reader, so they can appear twice in Readwise. Export tracking is local and keyed by document and exact passage. Notes added or edited after export are not sent, a highlight text change creates a new highlight, and local deletions do not propagate. Passages Reader rejects appear in Readwise but not inline in Reader. Resetting settings, losing a create response, or a crash in the middle of a book can allow a later export to be resent.

🤖 Generated with Claude Code

https://claude.ai/code/session_01W8hfPEJmjGWSdSHeaku17w