docs(analytics,jobs): Work Order 3 batch 4 — device usage, popular books, job create/status

DeviceUsageResponse / PopularBooksResponse / services.JobResult pinned by
type; jobs create uses an inline anonymous request struct (RawMessage pin).
Two UNVERIFIED markers recorded (analytics date-range params, facet value
element shape).
This commit is contained in:
John O'Keefe committed 2026-10-24 15:08:18 -04:00
1 parent 4a6fb033cb
commit 7471ca99e8
5 files changed
+169

No files matched your search

+40
View File
@@ -0,0 +1,40 @@
---
method: POST
path: /api/jobs
auth: jwt
area: jobs
---
<!-- source: internal/handlers/jobs.go CreateJob -->
# Create Job
Enqueues a background job (scan, import, convert — the set accepted by the
worker). Success is **202 Accepted** with the job id; poll its status via
`GET /api/jobs/:jobId`.
## Example request
```json example-request
{
"type": "import",
"params": { "library_id": "990e8400-e29b-41d4-a716-446655440000" }
}
```
## Example response
```json example-response
{
"message": "Job created",
"job_id": "ee0e8400-e29b-41d4-a716-446655440000",
"type": "import",
"status": "pending"
}
```
## Errors
| Status | Body | When |
| ------ | ---- | ---- |
| 400 | `{"error": "Invalid job type"}` / others | unknown type or params |
| 500 | `{"error": "..."}` | enqueue failure |
+34
View File
@@ -0,0 +1,34 @@
---
method: GET
path: /api/jobs/:jobId
auth: jwt
area: jobs
---
<!-- source: internal/handlers/jobs.go:76 GetJobStatus; services/worker.go JobResult -->
# Get Job Status
Returns the in-memory status/result of a background job.
## Example response
```json example-response
{
"job_id": "ee0e8400-e29b-41d4-a716-446655440000",
"status": "completed",
"error": "",
"result": null,
"progress": 100,
"files_scanned": 120,
"new_items": 3,
"errors": 0
}
```
`library_id` and `job_type` appear only on scan jobs (`omitempty`).
## Errors
| Status | Body | When |
| ------ | ---- | ---- |
| 404 | `{"error": "Job not found"}` | unknown id, or the in-memory result was evicted by a restart |