John O'Keefe
a85bc8af9b
Audited every request (247 .yml files) against the routes the server
actually registers (extracted from internal/router, group prefixes
resolved). Results:
- 44 stale requests: deleted where the endpoint no longer exists
(universal-progress GET/PUT /api/progress/:id — routes never existed,
the handlers were deleted in H1; queue stats/clear-failed/process;
admin profile page; auth/account) and FIXED where the endpoint exists
under a different path (kobo token-in-path scheme: every
/api/sync/kobo/<seg> and /api/v1/kobo/<seg> URL now carries
{{kobo_device_token}}; /sync/* missing their /api prefix; koreader
/api/v1/koreader/sync/* -> /api/sync/koreader/*; link-book and
unlinked-books moved to /api/devices/:id/sync/*).
- koreader Sync Highlights/Sync Notes pointed at endpoints that never
existed with a body shape to match — rewritten against POST
/api/sync/koreader/bookmarks (the annotations funnel carries
highlights and notes arrays).
- 9 files the GUI refused to load: 4 had bruno-invalid script type
"tests" (converted to after-response), 4 were info/type:collection
doc files with bogus http blocks (converted to folder.yml folder
docs), 1 had a dead pre-YAML schema and no route (deleted).
- devices/koreader requests now carry request-level bearer auth
({{koreader_device_token}}) — they inherited the collection's user-JWT
bearer, which device endpoints rightly reject — and their bodies
reference {{media_item_id}} instead of dead placeholder uuids.
- environments: opds_base_url was empty (every OPDS request missed the
/opds prefix); set to http://localhost:8765/opds and un-doubled the
prefix in opds/scenarios.
Known limitation, for the handoff: bru CLI cannot execute .yml request
bodies (the collection is GUI OpenCollection format; the CLI runner
reads bodies from .bru files only). A .bru migration is the remaining
bruno work if CLI runs are wanted.
99 lines
3.2 KiB
YAML
99 lines
3.2 KiB
YAML
info:
|
|
name: Kobo Initialization
|
|
type: http
|
|
seq: 8
|
|
|
|
http:
|
|
method: GET
|
|
url: '{{base_url}}/api/sync/kobo/{{kobo_device_token}}/v1/initialization'
|
|
auth: inherit
|
|
|
|
docs: |-
|
|
## Kobo Device Initialization
|
|
|
|
Initializes Kobo device sync session and returns device configuration.
|
|
|
|
**Method:** GET
|
|
|
|
**Endpoint:** /api/sync/kobo/v1/initialization
|
|
|
|
**Authentication:** Bearer token
|
|
|
|
**Query Parameters:**
|
|
- `Platform` (string, optional): Device platform (android, kobo)
|
|
- `FirmwareVersion` (string, optional): Firmware version string
|
|
- `Model` (string, optional): Device model name
|
|
|
|
**Response:**
|
|
- `device` (object): Device information
|
|
- `device_id` (string): Server device ID
|
|
- `approved` (boolean): Whether device is approved
|
|
- `sync_enabled` (boolean): Whether sync is active
|
|
- `last_sync` (string): Last successful sync timestamp
|
|
- `user` (object): User information
|
|
- `user_id` (string): User identifier
|
|
- `email` (string): User email (masked)
|
|
- `library_size` (integer): Number of books in library
|
|
- `sync_config` (object): Sync configuration
|
|
- `sync_interval_minutes` (integer): Recommended sync frequency
|
|
- `batch_size` (integer): Max items per batch
|
|
- `timeout_seconds` (integer): Request timeout
|
|
- `retry_count` (integer): Max retry attempts
|
|
- `features` (object): Available features
|
|
- `annotation_sync` (boolean): Annotation support
|
|
- `bookmark_sync` (boolean): Bookmark support
|
|
- `progress_sync` (boolean): Progress tracking
|
|
- `library_download` (boolean): Library access
|
|
- `endpoints` (object): API endpoint URLs
|
|
- `markup_sync` (string): Progress/annotation sync URL
|
|
- `bookmark_sync` (string): Bookmark sync URL
|
|
- `library` (string): Library access URL
|
|
- `sync_from_server` (string): Download sync URL
|
|
- `server_time` (string): Current server timestamp
|
|
- `version` (string): API version
|
|
|
|
**Status Codes:**
|
|
- 200: Success
|
|
- 401: Unauthorized (invalid token)
|
|
- 403: Forbidden (device not approved)
|
|
- 404: Device not found
|
|
|
|
**Initialization Flow:**
|
|
1. Device powers on or connects to network
|
|
2. Device calls initialization endpoint
|
|
3. Server returns configuration and capabilities
|
|
4. Device adjusts sync behavior based on config
|
|
5. Device begins sync operations
|
|
|
|
**Authentication Methods:**
|
|
This endpoint uses **Bearer token authentication** (token in Authorization header).
|
|
Alternative: Use `/sync/kobo/{token}/v1/initialization` with token in URL path.
|
|
|
|
**Configuration Caching:**
|
|
- Response cached on device for 24 hours
|
|
- Refreshed on device reboot
|
|
- Updated when sync settings change
|
|
- Can be force-refreshed via device settings
|
|
|
|
**Device Approval:**
|
|
- New devices: `approved: false`
|
|
- Pending devices see limited functionality
|
|
- Approval required for full sync
|
|
- User approves via web interface
|
|
- Re-initialization after approval
|
|
|
|
**Use Cases:**
|
|
- Device registration
|
|
- Daily device wakeup
|
|
- Post-approval initialization
|
|
- Configuration refresh
|
|
- Feature capability check
|
|
- Sync endpoint discovery
|
|
|
|
**Kobo Native Integration:**
|
|
- Called by Kobo Nickel UI
|
|
- Integrated with Kobo sync service
|
|
- Part of Kobo account setup
|
|
- Supports Kobo "Sync now" feature
|
|
- Enables Kobo library browsing
|