docs: add Carousel dashboard implementation plan
This commit is contained in:
@@ -0,0 +1,59 @@
|
||||
info:
|
||||
name: Filter by Status - Completed
|
||||
type: http
|
||||
seq: 2
|
||||
|
||||
http:
|
||||
method: GET
|
||||
url: '{{base_url}}/api/queue/items?status=completed'
|
||||
auth: inherit
|
||||
|
||||
docs: |-
|
||||
## Filter Queue Items by Completed Status
|
||||
|
||||
Retrieves all queue items that have been successfully processed.
|
||||
|
||||
**Method:** GET
|
||||
|
||||
**Endpoint:** /api/queue/items?status=completed
|
||||
|
||||
**Authentication:** Required (Bearer token)
|
||||
|
||||
**Query Parameters:**
|
||||
- `status` (string): Must be `completed`
|
||||
- `limit` (integer, optional): Max items to return (default: 50)
|
||||
- `offset` (integer, optional): Number of items to skip
|
||||
- `sort_by` (string, optional): Sort field - `created_at`, `completed_at`
|
||||
- `sort_order` (string, optional): `asc` or `desc` (default: `desc`)
|
||||
|
||||
**Response:**
|
||||
- `items` (array): Completed queue items
|
||||
- `id` (string): Queue item UUID
|
||||
- `type` (string): Item type
|
||||
- `status` (string): `completed`
|
||||
- `created_at` (string): When item was queued
|
||||
- `completed_at` (string): When processing finished
|
||||
- `duration_ms` (integer): Processing time
|
||||
- `device_id` (string): Device that queued the item
|
||||
- `media_id` (string): Associated media item
|
||||
- `result` (object): Processing result details
|
||||
- `total` (integer): Total completed items
|
||||
- `page` (object): Pagination info
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 401: Unauthorized
|
||||
|
||||
**Retention Policy:**
|
||||
- Completed items retained for 30 days
|
||||
- Auto-purged after retention period
|
||||
- Can be exported before deletion
|
||||
- Statistics aggregated before purge
|
||||
|
||||
**Use Cases:**
|
||||
- Audit sync history
|
||||
- Monitor system performance
|
||||
- Analyze processing times
|
||||
- Verify successful operations
|
||||
- Generate compliance reports
|
||||
- Track device activity patterns
|
||||
@@ -0,0 +1,59 @@
|
||||
info:
|
||||
name: Filter by Status - Failed
|
||||
type: http
|
||||
seq: 1
|
||||
|
||||
http:
|
||||
method: GET
|
||||
url: '{{base_url}}/api/queue/items?status=failed'
|
||||
auth: inherit
|
||||
|
||||
docs: |-
|
||||
## Filter Queue Items by Failed Status
|
||||
|
||||
Retrieves all queue items that have failed to process.
|
||||
|
||||
**Method:** GET
|
||||
|
||||
**Endpoint:** /api/queue/items?status=failed
|
||||
|
||||
**Authentication:** Required (Bearer token)
|
||||
|
||||
**Query Parameters:**
|
||||
- `status` (string): Must be `failed`
|
||||
- `limit` (integer, optional): Max items to return (default: 50)
|
||||
- `offset` (integer, optional): Number of items to skip (for pagination)
|
||||
|
||||
**Response:**
|
||||
- `items` (array): Failed queue items
|
||||
- `id` (string): Queue item UUID
|
||||
- `type` (string): Item type - `progress`, `note`, `highlight`, `bookmark`
|
||||
- `status` (string): `failed`
|
||||
- `error_message` (string): Error details
|
||||
- `error_code` (string): Error classification
|
||||
- `retry_count` (integer): Number of retry attempts
|
||||
- `max_retries` (integer): Maximum allowed retries
|
||||
- `created_at` (string): When item was queued
|
||||
- `failed_at` (string): When the item failed
|
||||
- `device_id` (string): Device that queued the item
|
||||
- `media_id` (string): Associated media item
|
||||
- `total` (integer): Total failed items
|
||||
- `page` (object): Pagination info
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 401: Unauthorized
|
||||
|
||||
**Common Failure Reasons:**
|
||||
- Network timeout during sync
|
||||
- Device offline during processing
|
||||
- Invalid data format
|
||||
- Database constraint violations
|
||||
- External service unavailability
|
||||
|
||||
**Use Cases:**
|
||||
- Monitor sync failures
|
||||
- Identify problematic devices
|
||||
- Debug integration issues
|
||||
- Track error patterns
|
||||
- Determine items needing manual retry
|
||||
@@ -0,0 +1,46 @@
|
||||
info:
|
||||
name: Filter by Status - Pending
|
||||
type: http
|
||||
seq: 3
|
||||
http:
|
||||
method: GET
|
||||
url: '{{base_url}}/queue/items?status=pending'
|
||||
auth: inherit
|
||||
body:
|
||||
type: none
|
||||
runtime:
|
||||
scripts:
|
||||
- type: tests
|
||||
code: "test(\"status must be 200\", function() {\n expect(res.status).to.eql(200);"
|
||||
|
||||
docs: |-
|
||||
Filter queue items by status - show only pending items.
|
||||
|
||||
**Endpoint**: GET /queue/items?status=pending
|
||||
**Auth**: Required (Bearer token)
|
||||
|
||||
## Query Parameters
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|-----------|-------------|
|
||||
| status | string | Yes | Status filter: pending, processing, completed, failed |
|
||||
|
||||
## Response Fields
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| items | array | List of queue items with pending status |
|
||||
| total | int | Total matching items |
|
||||
|
||||
## Example Request
|
||||
|
||||
```
|
||||
GET /queue/items?status=pending
|
||||
```
|
||||
|
||||
## Example Response
|
||||
|
||||
```json
|
||||
{
|
||||
"items": [...],
|
||||
"total": 15
|
||||
@@ -0,0 +1,84 @@
|
||||
info:
|
||||
name: Filter by Type - Bookmarks
|
||||
type: http
|
||||
seq: 6
|
||||
|
||||
http:
|
||||
method: GET
|
||||
url: '{{base_url}}/api/queue/items?status=all&type=bookmark'
|
||||
auth: inherit
|
||||
|
||||
docs: |-
|
||||
## Filter Queue Items by Bookmarks Type
|
||||
|
||||
Retrieves all bookmark sync items in the queue.
|
||||
|
||||
**Method:** GET
|
||||
|
||||
**Endpoint:** /api/queue/items?status=all&type=bookmark
|
||||
|
||||
**Authentication:** Required (Bearer token)
|
||||
|
||||
**Query Parameters:**
|
||||
- `status` (string): Use `all` to get all statuses
|
||||
- `type` (string): Must be `bookmark`
|
||||
- `media_id` (string, optional): Filter by media item
|
||||
- `device_id` (string, optional): Filter by device
|
||||
|
||||
**Response:**
|
||||
- `items` (array): Bookmark queue items
|
||||
- `id` (string): Queue item UUID
|
||||
- `type` (string): `bookmark`
|
||||
- `status` (string): Queue status
|
||||
- `bookmark_data` (object):
|
||||
- `media_id` (string): Associated media
|
||||
- `device_id` (string): Source device
|
||||
- `bookmark_id` (string): Bookmark identifier
|
||||
- `title` (string): Bookmark title (optional)
|
||||
- `position` (object):
|
||||
- `chapter` (string): Chapter reference
|
||||
- `page` (integer): Page number
|
||||
- `location` (string): Epub location
|
||||
- `percentage` (number): Position percentage
|
||||
- `content_path` (string): Internal path (KOReader)
|
||||
- `progress` (string): Progress indicator
|
||||
- `created_at` (string): Bookmark creation time
|
||||
- `modified_at` (string): Last edit time
|
||||
- `notes` (string, optional): Bookmark notes
|
||||
- `action` (string): `create`, `update`, or `delete`
|
||||
- `priority` (integer): Processing priority
|
||||
- `created_at` (string): Queued timestamp
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 401: Unauthorized
|
||||
|
||||
**Bookmark Features:**
|
||||
- Custom bookmark titles
|
||||
- Chapter-level bookmarks
|
||||
- Precise location tracking
|
||||
- Progress preservation
|
||||
- Cross-device sync
|
||||
- Hierarchical organization (KOReader)
|
||||
- Kindle location support
|
||||
- Kobo chapter marks
|
||||
|
||||
**Device-Specific Features:**
|
||||
- **Kobo:** Chapter bookmarks, automatic marks
|
||||
- **KOReader:** Hierarchical bookmarks, custom titles, notes
|
||||
- **Kindle:** Location-based, page numbers
|
||||
- **Web:** Chapter-based, custom titles
|
||||
|
||||
**Bookmark Types:**
|
||||
- User-created manual bookmarks
|
||||
- Auto-generated chapter marks
|
||||
- Last read position
|
||||
- Progress milestones (25%, 50%, 75%)
|
||||
- Custom collection markers
|
||||
|
||||
**Use Cases:**
|
||||
- Monitor bookmark sync
|
||||
- Track reading progress points
|
||||
- Debug location mapping
|
||||
- Verify cross-device bookmarks
|
||||
- Export reading positions
|
||||
@@ -0,0 +1,79 @@
|
||||
info:
|
||||
name: Filter by Type - Highlights
|
||||
type: http
|
||||
seq: 5
|
||||
|
||||
http:
|
||||
method: GET
|
||||
url: '{{base_url}}/api/queue/items?status=all&type=highlight'
|
||||
auth: inherit
|
||||
|
||||
docs: |-
|
||||
## Filter Queue Items by Highlights Type
|
||||
|
||||
Retrieves all highlight sync items in the queue.
|
||||
|
||||
**Method:** GET
|
||||
|
||||
**Endpoint:** /api/queue/items?status=all&type=highlight
|
||||
|
||||
**Authentication:** Required (Bearer token)
|
||||
|
||||
**Query Parameters:**
|
||||
- `status` (string): Use `all` to get all statuses
|
||||
- `type` (string): Must be `highlight`
|
||||
- `media_id` (string, optional): Filter by media item
|
||||
- `device_id` (string, optional): Filter by device
|
||||
- `color` (string, optional): Filter by highlight color
|
||||
|
||||
**Response:**
|
||||
- `items` (array): Highlight queue items
|
||||
- `id` (string): Queue item UUID
|
||||
- `type` (string): `highlight`
|
||||
- `status` (string): Queue status
|
||||
- `highlight_data` (object):
|
||||
- `media_id` (string): Associated media
|
||||
- `device_id` (string): Source device
|
||||
- `highlight_id` (string): Highlight identifier
|
||||
- `text` (string): Highlighted text
|
||||
- `color` (string): Highlight color (hex or name)
|
||||
- `note` (string, optional): Attached note
|
||||
- `position` (object):
|
||||
- `chapter` (string): Chapter reference
|
||||
- `page` (integer): Page number
|
||||
- `location` (string): Epub location
|
||||
- `percentage` (number): Position percentage
|
||||
- `start_position` (string): Selection start
|
||||
- `end_position` (string): Selection end
|
||||
- `text_offset` (integer): Character offset
|
||||
- `created_at` (string): Highlight creation time
|
||||
- `modified_at` (string): Last edit time
|
||||
- `action` (string): `create`, `update`, or `delete`
|
||||
- `priority` (integer): Processing priority
|
||||
- `created_at` (string): Queued timestamp
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 401: Unauthorized
|
||||
|
||||
**Highlight Features:**
|
||||
- Multi-color support (yellow, green, blue, pink, orange)
|
||||
- Precise text selection tracking
|
||||
- Linked notes support
|
||||
- Chapter and page location
|
||||
- Character-level precision
|
||||
- Cross-device color preservation
|
||||
- KOReader custom colors supported
|
||||
|
||||
**Device-Specific Color Support:**
|
||||
- **Kobo:** 5 preset colors (yellow, green, blue, pink, orange)
|
||||
- **KOReader:** Custom RGB colors
|
||||
- **Kindle:** Yellow, blue, orange
|
||||
- **Web:** Full color palette
|
||||
|
||||
**Use Cases:**
|
||||
- Track highlight synchronization
|
||||
- Debug color mapping issues
|
||||
- Monitor annotation activity
|
||||
- Analyze reading patterns
|
||||
- Export highlights by device
|
||||
@@ -0,0 +1,74 @@
|
||||
info:
|
||||
name: Filter by Type - Notes
|
||||
type: http
|
||||
seq: 4
|
||||
|
||||
http:
|
||||
method: GET
|
||||
url: '{{base_url}}/api/queue/items?status=all&type=note'
|
||||
auth: inherit
|
||||
|
||||
docs: |-
|
||||
## Filter Queue Items by Notes Type
|
||||
|
||||
Retrieves all note sync items in the queue.
|
||||
|
||||
**Method:** GET
|
||||
|
||||
**Endpoint:** /api/queue/items?status=all&type=note
|
||||
|
||||
**Authentication:** Required (Bearer token)
|
||||
|
||||
**Query Parameters:**
|
||||
- `status` (string): Use `all` to get all statuses
|
||||
- `type` (string): Must be `note`
|
||||
- `media_id` (string, optional): Filter by media item
|
||||
- `device_id` (string, optional): Filter by device
|
||||
|
||||
**Response:**
|
||||
- `items` (array): Note queue items
|
||||
- `id` (string): Queue item UUID
|
||||
- `type` (string): `note`
|
||||
- `status` (string): Queue status
|
||||
- `note_data` (object):
|
||||
- `media_id` (string): Associated media
|
||||
- `device_id` (string): Source device
|
||||
- `note_id` (string): Note identifier
|
||||
- `text` (string): Note content
|
||||
- `color` (string, optional): Note color (hex)
|
||||
- `highlight_id` (string, optional): Parent highlight
|
||||
- `position` (object): Location in book
|
||||
- `chapter` (string): Chapter reference
|
||||
- `page` (integer): Page number
|
||||
- `location` (string): Epub location
|
||||
- `percentage` (number): Position percentage
|
||||
- `created_at` (string): Note creation time
|
||||
- `modified_at` (string): Last edit time
|
||||
- `action` (string): `create`, `update`, or `delete`
|
||||
- `priority` (integer): Processing priority
|
||||
- `created_at` (string): Queued timestamp
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 401: Unauthorized
|
||||
|
||||
**Note Features:**
|
||||
- Rich text content support
|
||||
- Color-coded notes
|
||||
- Linked to highlights
|
||||
- Precise location tracking
|
||||
- Cross-device sync
|
||||
- Edit history preserved
|
||||
- Anonymous notes supported
|
||||
|
||||
**Actions:**
|
||||
- `create`: New note from device
|
||||
- `update`: Modified note content
|
||||
- `delete`: Removed note
|
||||
|
||||
**Use Cases:**
|
||||
- Monitor note synchronization
|
||||
- Debug note sync failures
|
||||
- Track reading activity
|
||||
- Analyze annotation patterns
|
||||
- Verify content propagation
|
||||
@@ -0,0 +1,71 @@
|
||||
info:
|
||||
name: Filter by Type - Progress
|
||||
type: http
|
||||
seq: 3
|
||||
|
||||
http:
|
||||
method: GET
|
||||
url: '{{base_url}}/api/queue/items?status=all&type=progress'
|
||||
auth: inherit
|
||||
|
||||
docs: |-
|
||||
## Filter Queue Items by Progress Type
|
||||
|
||||
Retrieves all reading progress sync items in the queue.
|
||||
|
||||
**Method:** GET
|
||||
|
||||
**Endpoint:** /api/queue/items?status=all&type=progress
|
||||
|
||||
**Authentication:** Required (Bearer token)
|
||||
|
||||
**Query Parameters:**
|
||||
- `status` (string): Use `all` to get all statuses
|
||||
- `type` (string): Must be `progress`
|
||||
- `media_id` (string, optional): Filter by specific media item
|
||||
- `device_id` (string, optional): Filter by specific device
|
||||
- `limit` (integer, optional): Max items to return
|
||||
|
||||
**Response:**
|
||||
- `items` (array): Progress queue items
|
||||
- `id` (string): Queue item UUID
|
||||
- `type` (string): `progress`
|
||||
- `status` (string): `pending`, `processing`, `completed`, `failed`
|
||||
- `progress_data` (object):
|
||||
- `media_id` (string): Book/media identifier
|
||||
- `device_id` (string): Source device
|
||||
- `percentage` (integer): Reading progress 0-100
|
||||
- `position` (string): Location in book
|
||||
- `page_number` (integer, optional): Current page
|
||||
- `chapter` (string, optional): Current chapter
|
||||
- `finished` (boolean): Book completed flag
|
||||
- `timestamp` (string): When progress was recorded
|
||||
- `priority` (integer): Processing priority (0-10)
|
||||
- `created_at` (string): Queued timestamp
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 401: Unauthorized
|
||||
|
||||
**Progress Sync Features:**
|
||||
- Cross-device progress synchronization
|
||||
- SHA-256 based book identification (KOReader)
|
||||
- Location-based progress (Kobo, Kindle)
|
||||
- Page number tracking
|
||||
- Chapter bookmarking
|
||||
- Finished status propagation
|
||||
- Reading time calculation
|
||||
|
||||
**Priority Levels:**
|
||||
- 10: Manual sync requests
|
||||
- 8: Device-initiated sync
|
||||
- 5: Scheduled automatic sync
|
||||
- 3: Background updates
|
||||
- 1: Bulk operations
|
||||
|
||||
**Use Cases:**
|
||||
- Track pending progress updates
|
||||
- Monitor sync health across devices
|
||||
- Debug progress sync issues
|
||||
- Identify devices with stale data
|
||||
- Verify progress propagation
|
||||
@@ -0,0 +1,41 @@
|
||||
info:
|
||||
name: Get Device Queue Stats
|
||||
type: http
|
||||
seq: 2
|
||||
http:
|
||||
method: GET
|
||||
url: '{{base_url}}/api/queue/devices/{{device_id}}/stats'
|
||||
auth: inherit
|
||||
body:
|
||||
type: none
|
||||
|
||||
docs: |-
|
||||
## Get Device Queue Stats
|
||||
|
||||
Retrieves statistics for a specific device's sync queue.
|
||||
|
||||
**Method:** GET
|
||||
|
||||
**Endpoint:** /api/queue/devices/:device_id/stats
|
||||
|
||||
**Authentication:** Bearer token
|
||||
|
||||
**Path Parameters:**
|
||||
- `device_id` (string): Device UUID
|
||||
|
||||
**Response:**
|
||||
- Queue statistics including pending, completed, and failed counts
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 401: Unauthorized
|
||||
- 404: Device not found
|
||||
|
||||
**Example Response:**
|
||||
```json
|
||||
{
|
||||
"device_id": "uuid",
|
||||
"total_items": 10,
|
||||
"pending": 3,
|
||||
"completed": 5,
|
||||
"failed": 2
|
||||
Reference in New Issue
Block a user