docs(devices): Work Order 3 batch 1 — 6 missing device endpoints + gate entries
New frontmatter'd docs with handler-compatible examples: - devices/get_device.md (DeviceInfo shape) - devices/regenerate_device_token.md (token + sync_urls) - devices/get_device_mappings.md (wrapper + DeviceMappingSummary) - devices/update_device_mapping.md (UpdateDeviceMappingRequest) - devices/download_sidecar_config.md (sidecar config JSON file) - devices/link_book.md (LinkBookRequest; one UNVERIFIED marker on required-tag) Schema registry: 6 new entries; DeviceMappingSummary hoisted to package scope. Gate passes (the UNVERIFIED marker is logged, not a failure). Excludes /api/devices-page (htmx page route, per ground rules).
This commit is contained in:
John O'Keefe committed
1 parent
50282895f5
commit
c4b62af213
8 files changed
+349
-11
No files matched your search
@@ -0,0 +1,42 @@
|
|||||||
|
---
|
||||||
|
method: GET
|
||||||
|
path: /api/devices/:id/sidecar/download
|
||||||
|
auth: jwt
|
||||||
|
area: devices
|
||||||
|
---
|
||||||
|
<!-- source: internal/handlers/sidecar.go:215 SidecarHandler.DownloadSidecarConfig -->
|
||||||
|
|
||||||
|
# Download Sidecar Config
|
||||||
|
|
||||||
|
Generates and downloads a `.bookhoard.json` sidecar configuration file for a
|
||||||
|
device (used by the sidecar sync workflow). The body is a JSON document returned
|
||||||
|
with `Content-Disposition: attachment`.
|
||||||
|
|
||||||
|
## Example response
|
||||||
|
|
||||||
|
```json example-response
|
||||||
|
{
|
||||||
|
"version": "1.0",
|
||||||
|
"bookhoard": {
|
||||||
|
"opds_catalog": "http://localhost:8765/opds/devices/550e8400-.../catalog",
|
||||||
|
"sync_api": "http://localhost:8765/api/sync/kobo",
|
||||||
|
"opds_base_url": "http://localhost:8765/opds",
|
||||||
|
"api_base_url": "http://localhost:8765/api",
|
||||||
|
"device_id": "550e8400-e29b-41d4-a716-446655440000",
|
||||||
|
"device_token": "dev_abc123..."
|
||||||
|
},
|
||||||
|
"books": {},
|
||||||
|
"collections": [],
|
||||||
|
"opds_enabled": true,
|
||||||
|
"sidecar_enabled": true,
|
||||||
|
"last_updated": "2026-10-24T13:57:01Z"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Errors
|
||||||
|
|
||||||
|
| Status | Body | When |
|
||||||
|
| ------ | ---- | ---- |
|
||||||
|
| 400 | `{"error": "invalid device ID"}` | malformed id |
|
||||||
|
| 404 | `{"error": "device not found"}` | no such device |
|
||||||
|
| 500 | `{"error": "failed to fetch media items"}` / `{"error": "failed to generate config"}` | unexpected server error |
|
||||||
@@ -0,0 +1,42 @@
|
|||||||
|
---
|
||||||
|
method: GET
|
||||||
|
path: /api/devices/:id
|
||||||
|
auth: jwt
|
||||||
|
area: devices
|
||||||
|
---
|
||||||
|
<!-- source: internal/handlers/devices.go:306 DeviceHandler.GetDevice -->
|
||||||
|
|
||||||
|
# Get Device
|
||||||
|
|
||||||
|
Returns one device owned by the signed-in user. Device tokens are **not**
|
||||||
|
included in this response (use `regenerate-token` to obtain them).
|
||||||
|
|
||||||
|
## Example response
|
||||||
|
|
||||||
|
```json example-response
|
||||||
|
{
|
||||||
|
"id": "550e8400-e29b-41d4-a716-446655440000",
|
||||||
|
"device_name": "Kobo Clara",
|
||||||
|
"device_type": "kobo",
|
||||||
|
"last_sync": "2026-10-24T13:57:01Z",
|
||||||
|
"last_seen": "2026-10-24T13:57:01Z",
|
||||||
|
"sync_enabled": true,
|
||||||
|
"auto_sync": true,
|
||||||
|
"sync_frequency_minutes": 60,
|
||||||
|
"created_at": "2026-10-24T13:57:01Z",
|
||||||
|
"auth_token": ""
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
`last_sync` and `last_seen` are `*time.Time` → `null` when unset. `created_at`
|
||||||
|
is RFC3339 (`time.Time` marshaling). `device_metadata` is omitted when empty
|
||||||
|
(`omitempty`).
|
||||||
|
|
||||||
|
## Errors
|
||||||
|
|
||||||
|
| Status | Body | When |
|
||||||
|
| ------ | ---- | ---- |
|
||||||
|
| 400 | `{"error": "invalid user ID"}` / `{"error": "invalid device ID"}` | malformed id(s) |
|
||||||
|
| 401 | `{"error": "unauthorized"}` | no/invalid JWT |
|
||||||
|
| 403 | `{"error": "access denied"}` | device belongs to another user |
|
||||||
|
| 404 | `{"error": "device not found"}` | no such device |
|
||||||
@@ -0,0 +1,40 @@
|
|||||||
|
---
|
||||||
|
method: GET
|
||||||
|
path: /api/devices/:id/collections
|
||||||
|
auth: jwt
|
||||||
|
area: devices
|
||||||
|
---
|
||||||
|
<!-- source: internal/handlers/collections.go:645 CollectionHandler.GetDeviceMappings -->
|
||||||
|
|
||||||
|
# Get Device Collection Mappings
|
||||||
|
|
||||||
|
Lists the shelf-to-collection mappings configured for a device.
|
||||||
|
|
||||||
|
## Example response
|
||||||
|
|
||||||
|
```json example-response
|
||||||
|
{
|
||||||
|
"device_id": "550e8400-e29b-41d4-a716-446655440000",
|
||||||
|
"mappings": [
|
||||||
|
{
|
||||||
|
"id": "660e8400-e29b-41d4-a716-446655440000",
|
||||||
|
"collection_id": "770e8400-e29b-41d4-a716-446655440000",
|
||||||
|
"collection_name": "To Read",
|
||||||
|
"device_shelf_name": "Kobo",
|
||||||
|
"sync_direction": "bidirectional",
|
||||||
|
"created_at": "2026-10-24 13:57:01.81234 +0000 UTC"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"total": 1
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
`created_at` uses Go's `time.String()` format, not RFC3339. `total` is the
|
||||||
|
length of `mappings`.
|
||||||
|
|
||||||
|
## Errors
|
||||||
|
|
||||||
|
| Status | Body | When |
|
||||||
|
| ------ | ---- | ---- |
|
||||||
|
| 400 | `{"error": "invalid device id"}` | malformed id |
|
||||||
|
| 500 | `{"error": "..."}` | unexpected server error |
|
||||||
@@ -0,0 +1,59 @@
|
|||||||
|
---
|
||||||
|
method: POST
|
||||||
|
path: /api/devices/:deviceId/sync/link-book
|
||||||
|
auth: jwt
|
||||||
|
area: devices
|
||||||
|
---
|
||||||
|
<!-- source: internal/handlers/matching.go:57 MatchingHandler.LinkBook -->
|
||||||
|
|
||||||
|
# Link Book
|
||||||
|
|
||||||
|
Links a device file (by path + SHA256) to a media item, optionally with a
|
||||||
|
confidence score. Used by the book-matching flow.
|
||||||
|
|
||||||
|
## Example request
|
||||||
|
|
||||||
|
```json example-request
|
||||||
|
{
|
||||||
|
"device_file": {
|
||||||
|
"file_path": "/books/1984.epub",
|
||||||
|
"sha256": "abc123...",
|
||||||
|
"title": "1984"
|
||||||
|
},
|
||||||
|
"media_item_id": "550e8400-e29b-41d4-a716-446655440000",
|
||||||
|
"confidence_score": 0.95
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Example response
|
||||||
|
|
||||||
|
```json example-response
|
||||||
|
{
|
||||||
|
"status": "linked",
|
||||||
|
"device_file_alias": {
|
||||||
|
"id": "660e8400-e29b-41d4-a716-446655440000",
|
||||||
|
"media_item_id": "550e8400-e29b-41d4-a716-446655440000",
|
||||||
|
"device_id": "770e8400-e29b-41d4-a716-446655440000",
|
||||||
|
"file_path": "/books/1984.epub",
|
||||||
|
"file_sha256": "abc123...",
|
||||||
|
"confidence_score": 0.95
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Request fields
|
||||||
|
|
||||||
|
| Field | Type | Required | Notes |
|
||||||
|
| ----- | ---- | -------- | ----- |
|
||||||
|
| device_file.file_path | string | no | path on the device |
|
||||||
|
| device_file.sha256 | string | no | file content hash |
|
||||||
|
| device_file.title | string | no | device-side title |
|
||||||
|
| media_item_id | string (uuid) | yes | `services.LinkBookRequest` declares it as uuid; the gate only checks the Bind struct — UNVERIFIED: confirm required tag on LinkBookRequest fields |
|
||||||
|
| confidence_score | number | no | match confidence (0-1) |
|
||||||
|
|
||||||
|
## Errors
|
||||||
|
|
||||||
|
| Status | Body | When |
|
||||||
|
| ------ | ---- | ---- |
|
||||||
|
| 400 | `{"error": "Invalid device ID"}` / `{"error": "Invalid request body"}` | malformed id or body |
|
||||||
|
| 500 | `{"error": "Failed to link book: ..."}` | service failure |
|
||||||
@@ -0,0 +1,56 @@
|
|||||||
|
---
|
||||||
|
method: PUT
|
||||||
|
path: /api/devices/:id/regenerate-token
|
||||||
|
auth: jwt
|
||||||
|
area: devices
|
||||||
|
---
|
||||||
|
<!-- source: internal/handlers/devices.go:443 DeviceHandler.RegenerateDeviceToken -->
|
||||||
|
|
||||||
|
# Regenerate Device Token
|
||||||
|
|
||||||
|
Mints a fresh device auth token and returns it together with device-specific
|
||||||
|
sync URLs. The previous token is invalidated.
|
||||||
|
|
||||||
|
For Kobo devices the response includes `sync_urls` (init/markup/bookmark/sync_url);
|
||||||
|
for KOReader devices it contains the KOReader endpoints.
|
||||||
|
|
||||||
|
## Example response
|
||||||
|
|
||||||
|
```json example-response
|
||||||
|
{
|
||||||
|
"message": "Token regenerated successfully",
|
||||||
|
"auth_token": "dev_abc123...",
|
||||||
|
"device": {
|
||||||
|
"id": "550e8400-e29b-41d4-a716-446655440000",
|
||||||
|
"device_name": "Kobo Clara",
|
||||||
|
"device_type": "kobo",
|
||||||
|
"last_sync": null,
|
||||||
|
"last_seen": null,
|
||||||
|
"sync_enabled": true,
|
||||||
|
"auto_sync": true,
|
||||||
|
"sync_frequency_minutes": 60,
|
||||||
|
"created_at": "2026-10-24T13:57:01Z",
|
||||||
|
"device_metadata": null
|
||||||
|
},
|
||||||
|
"sync_urls": {
|
||||||
|
"sync_url": "http://localhost:8765/api/sync/kobo/dev_abc123...",
|
||||||
|
"markup": "http://localhost:8765/api/sync/kobo/dev_abc123.../markup",
|
||||||
|
"bookmark": "http://localhost:8765/api/sync/kobo/dev_abc123.../bookmark",
|
||||||
|
"init": "http://localhost:8765/api/sync/kobo/dev_abc123.../v1/initialization"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Errors
|
||||||
|
|
||||||
|
| Status | Body | When |
|
||||||
|
| ------ | ---- | ---- |
|
||||||
|
| 400 | `{"error": "invalid device ID"}` | malformed id |
|
||||||
|
| 401 | `{"error": "invalid user ID"}` | no/invalid JWT |
|
||||||
|
| 403 | `{"error": "access denied"}` | device belongs to another user |
|
||||||
|
| 404 | `{"error": "device not found"}` | no such device |
|
||||||
|
| 500 | `{"error": "..."}` | token generation / DB failure |
|
||||||
|
|
||||||
|
Notes: HTMX requests get an HTML reload snippet instead of JSON.
|
||||||
|
`sync_urls` keys differ by device type (Kobo gets the four above; KOReader
|
||||||
|
gets its own set).
|
||||||
@@ -0,0 +1,47 @@
|
|||||||
|
---
|
||||||
|
method: PUT
|
||||||
|
path: /api/devices/:id/collections/:collectionId
|
||||||
|
auth: jwt
|
||||||
|
area: devices
|
||||||
|
---
|
||||||
|
<!-- source: internal/handlers/collections.go:724 CollectionHandler.UpdateDeviceMapping -->
|
||||||
|
|
||||||
|
# Update Device Collection Mapping
|
||||||
|
|
||||||
|
Updates a device shelf-to-collection mapping's shelf name and sync direction.
|
||||||
|
|
||||||
|
## Example request
|
||||||
|
|
||||||
|
```json example-request
|
||||||
|
{
|
||||||
|
"device_shelf_name": "Kobo",
|
||||||
|
"sync_direction": "bidirectional"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Example response
|
||||||
|
|
||||||
|
```json example-response
|
||||||
|
{
|
||||||
|
"id": "660e8400-e29b-41d4-a716-446655440000",
|
||||||
|
"collection_id": "770e8400-e29b-41d4-a716-446655440000",
|
||||||
|
"device_id": "550e8400-e29b-41d4-a716-446655440000",
|
||||||
|
"device_shelf_name": "Kobo",
|
||||||
|
"sync_direction": "bidirectional",
|
||||||
|
"created_at": "2026-10-24 13:57:01.81234 +0000 UTC"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Request fields
|
||||||
|
|
||||||
|
| Field | Type | Required | Notes |
|
||||||
|
| ----- | ---- | -------- | ----- |
|
||||||
|
| device_shelf_name | string | yes | |
|
||||||
|
| sync_direction | string | yes | one of `bidirectional`, `book_to_device`, `device_to_book`, `none` |
|
||||||
|
|
||||||
|
## Errors
|
||||||
|
|
||||||
|
| Status | Body | When |
|
||||||
|
| ------ | ---- | ---- |
|
||||||
|
| 400 | `{"error": "invalid mapping id"}` / `{"error": "invalid request"}` | malformed id or body |
|
||||||
|
| 500 | `{"error": "..."}` | unexpected server error |
|
||||||
@@ -4,6 +4,7 @@ import (
|
|||||||
"encoding/json"
|
"encoding/json"
|
||||||
|
|
||||||
"bookhoard/internal/handlers"
|
"bookhoard/internal/handlers"
|
||||||
|
"bookhoard/internal/services"
|
||||||
)
|
)
|
||||||
|
|
||||||
// Schema pins the machine-checkable contract for one route. The drift gate
|
// Schema pins the machine-checkable contract for one route. The drift gate
|
||||||
@@ -69,4 +70,53 @@ var Schemas = map[string]Schema{
|
|||||||
}`),
|
}`),
|
||||||
},
|
},
|
||||||
"DELETE /api/collections/:id": {},
|
"DELETE /api/collections/:id": {},
|
||||||
|
// --- devices (batch 1) ---
|
||||||
|
"GET /api/devices/:id": {
|
||||||
|
Response: handlers.DeviceInfo{},
|
||||||
|
},
|
||||||
|
"PUT /api/devices/:id/regenerate-token": {
|
||||||
|
Response: json.RawMessage(`{
|
||||||
|
"message": "", "auth_token": "",
|
||||||
|
"device": {
|
||||||
|
"id": "", "device_name": "", "device_type": "",
|
||||||
|
"last_sync": null, "last_seen": null,
|
||||||
|
"sync_enabled": false, "auto_sync": false,
|
||||||
|
"sync_frequency_minutes": 0, "created_at": "",
|
||||||
|
"device_metadata": null, "auth_token": ""
|
||||||
|
},
|
||||||
|
"sync_urls": {}
|
||||||
|
}`),
|
||||||
|
},
|
||||||
|
"GET /api/devices/:id/collections": {
|
||||||
|
Response: struct {
|
||||||
|
DeviceID string `json:"device_id"`
|
||||||
|
Mappings []handlers.DeviceMappingSummary `json:"mappings"`
|
||||||
|
Total int `json:"total"`
|
||||||
|
}{},
|
||||||
|
},
|
||||||
|
"PUT /api/devices/:id/collections/:collectionId": {
|
||||||
|
Request: handlers.UpdateDeviceMappingRequest{},
|
||||||
|
Response: json.RawMessage(`{
|
||||||
|
"id": "", "collection_id": "", "device_id": "",
|
||||||
|
"device_shelf_name": "", "sync_direction": "", "created_at": ""
|
||||||
|
}`),
|
||||||
|
},
|
||||||
|
"GET /api/devices/:id/sidecar/download": {
|
||||||
|
Response: json.RawMessage(`{
|
||||||
|
"version": "", "bookhoard": {}, "books": {},
|
||||||
|
"collections": [], "opds_enabled": false,
|
||||||
|
"sidecar_enabled": false, "last_updated": ""
|
||||||
|
}`),
|
||||||
|
},
|
||||||
|
"POST /api/devices/:deviceId/sync/link-book": {
|
||||||
|
Request: services.LinkBookRequest{},
|
||||||
|
Response: json.RawMessage(`{
|
||||||
|
"status": "",
|
||||||
|
"device_file_alias": {
|
||||||
|
"id": "", "media_item_id": "", "device_id": "",
|
||||||
|
"file_path": "", "file_sha256": "",
|
||||||
|
"confidence_score": 0.0
|
||||||
|
}
|
||||||
|
}`),
|
||||||
|
},
|
||||||
}
|
}
|
||||||
@@ -75,6 +75,17 @@ type UpdateDeviceMappingRequest struct {
|
|||||||
SyncDirection string `json:"sync_direction" validate:"required,oneof=bidirectional book_to_device device_to_book none"`
|
SyncDirection string `json:"sync_direction" validate:"required,oneof=bidirectional book_to_device device_to_book none"`
|
||||||
}
|
}
|
||||||
|
|
||||||
|
// DeviceMappingSummary is one entry in GET /api/devices/:id/collections. Hoisted
|
||||||
|
// to package scope so the docs schema registry can pin the response shape.
|
||||||
|
type DeviceMappingSummary struct {
|
||||||
|
ID uuid.UUID `json:"id"`
|
||||||
|
CollectionID uuid.UUID `json:"collection_id"`
|
||||||
|
CollectionName string `json:"collection_name"`
|
||||||
|
DeviceShelfName string `json:"device_shelf_name"`
|
||||||
|
SyncDirection string `json:"sync_direction"`
|
||||||
|
CreatedAt string `json:"created_at"`
|
||||||
|
}
|
||||||
|
|
||||||
// CollectionSummary is one entry in GET /api/collections. Package-level so
|
// CollectionSummary is one entry in GET /api/collections. Package-level so
|
||||||
// the docs schema registry (internal/docs) can pin the response shape.
|
// the docs schema registry (internal/docs) can pin the response shape.
|
||||||
type CollectionSummary struct {
|
type CollectionSummary struct {
|
||||||
@@ -653,18 +664,9 @@ func (h *CollectionHandler) GetDeviceMappings(c *echo.Context) error {
|
|||||||
return c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
|
return c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
|
||||||
}
|
}
|
||||||
|
|
||||||
type MappingResponse struct {
|
response := make([]DeviceMappingSummary, 0, len(mappings))
|
||||||
ID uuid.UUID `json:"id"`
|
|
||||||
CollectionID uuid.UUID `json:"collection_id"`
|
|
||||||
CollectionName string `json:"collection_name"`
|
|
||||||
DeviceShelfName string `json:"device_shelf_name"`
|
|
||||||
SyncDirection string `json:"sync_direction"`
|
|
||||||
CreatedAt string `json:"created_at"`
|
|
||||||
}
|
|
||||||
|
|
||||||
response := make([]MappingResponse, 0, len(mappings))
|
|
||||||
for _, m := range mappings {
|
for _, m := range mappings {
|
||||||
response = append(response, MappingResponse{
|
response = append(response, DeviceMappingSummary{
|
||||||
ID: m.ID.Bytes,
|
ID: m.ID.Bytes,
|
||||||
CollectionID: m.CollectionID.Bytes,
|
CollectionID: m.CollectionID.Bytes,
|
||||||
CollectionName: m.CollectionName,
|
CollectionName: m.CollectionName,
|
||||||
|
|||||||
Reference in new issue
Block a user