arne/books
0
0
Fork 0
Code Issues 3 Pull requests Projects Releases 5 Packages Wiki Activity

docs: refactor Kobo API findings into a reference document #22

Merged
arne merged 14 commits from kobo-api-docs-refactor into main 2026-04-20 11:02:21 +02:00
Conversation 0 Commits 14 Files changed 5 +1888 -441
arne commented 2026-04-20 11:00:58 +02:00
Owner
Copy link

Summary

  • Replace docs/kobo-api-findings.md (chronological field notes) with docs/kobo-api.md — a reference-shaped document for external self-hosters documenting the Kobo sync protocol.
  • Single file, six chapters: Overview, Debugging, Conventions, Endpoint reference (one subsection per route, uniform template), Known failure modes, References. Appendix on device-side KoboReader.sqlite state. Contributing footer with three lightweight maintenance conventions.
  • Every route in internal/kobo/handler.go now has a subsection with Implementation, Called by, Purpose, Request, Response, Quirks, and Reference implementations fields.
  • README.md links updated to point at the new file.
  • Spec at docs/superpowers/specs/2026-04-20-kobo-api-docs-refactor-design.md; implementation plan at docs/superpowers/plans/2026-04-20-kobo-api-docs-refactor.md.

Test plan

  • Render docs/kobo-api.md in a markdown viewer — ToC links resolve, code fences close, Chapter 5 anchor links jump to the correct Chapter 4 subsections.
  • Verify every route in internal/kobo/handler.go has a matching subsection (expected: 19 H4 endpoint headings).
  • Spot-check that the documented request/response shapes match the handler code for at least /v1/initialization, /v1/library/sync, /v1/library/{id}/metadata, /v1/analytics/gettests, and the download endpoint.
  • Verify docs/kobo-api-findings.md is gone and README.md no longer links to it.
## Summary - Replace `docs/kobo-api-findings.md` (chronological field notes) with `docs/kobo-api.md` — a reference-shaped document for external self-hosters documenting the Kobo sync protocol. - Single file, six chapters: Overview, Debugging, Conventions, Endpoint reference (one subsection per route, uniform template), Known failure modes, References. Appendix on device-side `KoboReader.sqlite` state. Contributing footer with three lightweight maintenance conventions. - Every route in `internal/kobo/handler.go` now has a subsection with Implementation, Called by, Purpose, Request, Response, Quirks, and Reference implementations fields. - `README.md` links updated to point at the new file. - Spec at `docs/superpowers/specs/2026-04-20-kobo-api-docs-refactor-design.md`; implementation plan at `docs/superpowers/plans/2026-04-20-kobo-api-docs-refactor.md`. ## Test plan - [ ] Render `docs/kobo-api.md` in a markdown viewer — ToC links resolve, code fences close, Chapter 5 anchor links jump to the correct Chapter 4 subsections. - [ ] Verify every route in `internal/kobo/handler.go` has a matching subsection (expected: 19 H4 endpoint headings). - [ ] Spot-check that the documented request/response shapes match the handler code for at least `/v1/initialization`, `/v1/library/sync`, `/v1/library/{id}/metadata`, `/v1/analytics/gettests`, and the download endpoint. - [ ] Verify `docs/kobo-api-findings.md` is gone and `README.md` no longer links to it.
arne added 14 commits 2026-04-20 11:00:58 +02:00 
First sub-project in a broader arc of Kobo feature work. Replaces the
current field-notes file with a reference-shaped document for external
self-hosters.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Task-by-task plan for replacing docs/kobo-api-findings.md with
docs/kobo-api.md.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
arne merged commit 75e4242442 into main 2026-04-20 11:02:21 +02:00
arne deleted branch kobo-api-docs-refactor 2026-04-20 11:02:21 +02:00
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
arne/books!22
No description provided.