refactor(bruno): reorganize file structure from bruno-yaml to flat bruno directory

- Move all files from bruno-yaml/* to bruno/* - Maintains existing directory structure within categories - Updates bruno/user/auth files with OAuth2 refresh token flow - Updates bruno/user/profile files for user profile management - Adds bruno/dashboard/ directory with dashboard API tests - Preserves all existing test scenarios and OpenCollection YAML format - No functional changes - file reorganization only
2026-02-17 20:22:21 -05:00
parent 96730d9475
commit f859b2714d
221 changed files with 0 additions and 0 deletions
@@ -0,0 +1,23 @@
+info:
+  name: Add Books to Kobo Shelf
+  type: http
+  seq: 1
+http:
+  method: POST
+  url: '{{baseURL}}/api/devices/{{deviceID}}/shelves'
+  auth: inherit
+  body:
+    type: json
+    jsonBody: "{\n    \"media_item_ids\": [\n      \"{{bookUUID1"
+  headers:
+  - key: Authorization
+    value: Bearer {{userToken
+
+docs: |-
+  ## Add Books to Kobo Shelf
+  
+    Add one or more books to a Kobo device shelf. Manages which books should be synced to a specific Kobo device. Supports multiple shelves for organization.
+  
+    **Method:** POST
+  
+    **Endpoint:** /api/devices/{deviceID
@@ -0,0 +1,40 @@
+info:
+  name: Approve Device Registration
+  type: http
+  seq: 6
+http:
+  method: GET
+  url: '{{base_url}}/api/devices/approve/{{registration_id}}'
+  auth: inherit
+  body:
+    type: none
+
+docs: |-
+  ## Approve Device Registration
+  
+    Approves a pending device registration request.
+  
+    **Method:** GET
+  
+    **Endpoint:** /api/devices/approve/:registration_id
+  
+    **Authentication:** Bearer token
+  
+    **Path Parameters:**
+     - `registration_id` (string): Registration request UUID
+  
+    **Response:**
+     - Success message with approved device details
+  
+    **Status Codes:**
+     - 200: Success
+     - 401: Unauthorized
+     - 404: Registration not found
+     - 400: Invalid registration status
+  
+    **Example Response:**
+     ```json
+     {
+       "message": "Device registration approved",
+       "device_id": "uuid",
+       "device_name": "My Kobo"
@@ -0,0 +1,55 @@
+info:
+  name: Approve Registration - KOReader
+  type: http
+  seq: 13
+
+http:
+  method: GET
+  url: '{{base_url}}/api/devices/approve/reg-uuid-123'
+  auth: inherit
+
+docs: |-
+  ## Approve KOReader Device Registration
+
+  Approves a pending KOReader device registration.
+
+  **Method:** GET
+
+  **Endpoint:** /api/devices/approve/:registration_id
+
+  **Authentication:** Required (Bearer token)
+
+  **Path Parameters:**
+  - `registration_id` (string): Example: `reg-uuid-123`
+
+  **Response:**
+  - `registration_id` (string): Approved registration UUID
+  - `device_id` (string): Generated device UUID
+  - `device_name` (string): KOReader device name
+  - `device_type` (string): `koreader`
+  - `status` (string): `approved`
+  - `access_token` (string): Device access token
+  - `sync_endpoints` (object):
+    - `bookmarks` (string): Bookmarks sync endpoint
+    - `progress` (string): Progress sync endpoint
+    - `highlights` (string): Highlights sync endpoint
+    - `annotations` (string): Annotations sync endpoint
+
+  **Status Codes:**
+  - 200: Approved successfully
+  - 401: Unauthorized
+  - 403: Forbidden
+  - 404: Registration not found
+
+  **KOReader-Specific Features:**
+  - Supports per-book SHA-256 based progress tracking
+  - Syncs highlights with color and notes
+  - Syncs bookmarks with locations and timestamps
+  - Supports dictionary annotations
+  - Can sync custom highlight colors
+
+  **After Approval:**
+  - KOReader device can immediately sync
+  - Device shows up in device list as "KOReader"
+  - Access token is stored in device settings
+  - Initial sync pulls down existing user data
@@ -0,0 +1,60 @@
+info:
+  name: Approve Registration - Kobo
+  type: http
+  seq: 14
+
+http:
+  method: GET
+  url: '{{base_url}}/api/devices/approve/reg-uuid-456'
+  auth: inherit
+
+docs: |-
+  ## Approve Kobo Device Registration
+
+  Approves a pending Kobo e-reader device registration.
+
+  **Method:** GET
+
+  **Endpoint:** /api/devices/approve/:registration_id
+
+  **Authentication:** Required (Bearer token)
+
+  **Path Parameters:**
+  - `registration_id` (string): Example: `reg-uuid-456`
+
+  **Response:**
+  - `registration_id` (string): Approved registration UUID
+  - `device_id` (string): Generated device UUID
+  - `device_name` (string): Kobo device name
+  - `device_type` (string): `kobo`
+  - `status` (string): `approved`
+  - `access_token` (string): Device access token
+  - `sync_endpoints` (object):
+    - `bookmark_sync` (string): Bookmark sync URL
+    - `markup_sync` (string): Markup/highlight sync URL
+    - `metadata_sync` (string): Metadata sync URL
+  - `kobo_features` (object):
+    - `supports_shelves` (boolean): Kobo shelf support
+    - `supports_dictionary` (boolean): Dictionary annotation support
+    - `supports_statistics` (boolean): Reading statistics support
+
+  **Status Codes:**
+  - 200: Approved successfully
+  - 401: Unauthorized
+  - 403: Forbidden
+  - 404: Registration not found
+
+  **Kobo-Specific Features:**
+  - Native Kobo sync protocol support
+  - Shelves/collections sync
+  - Reading statistics sync
+  - Dictionary lookups with annotations
+  - Book metadata sync
+  - Pocket articles integration
+
+  **After Approval:**
+  - Kobo device can use native sync feature
+  - Device appears in Nickel (Kobo UI)
+  - Sync runs automatically when connected
+  - Shelves sync with collections
+  - Reading progress syncs across devices
@@ -0,0 +1,52 @@
+info:
+  name: Check Pending Registration
+  type: http
+  seq: 4
+
+http:
+  method: POST
+  url: '{{base_url}}/api/devices/register/status'
+  auth: none
+  headers:
+    - key: Content-Type
+      value: application/json
+  body:
+    type: json
+    json:
+      registration_id: registration-uuid-here
+
+docs: |-
+  ## Check Registration Status
+
+  Checks the current status of a device registration request.
+
+  **Method:** POST
+
+  **Endpoint:** /api/devices/register/status
+
+  **Authentication:** None
+
+  **Request Body:**
+  - `registration_id` (string): UUID received from registration request
+
+  **Response:**
+  - `registration_id` (string): The registration UUID
+  - `status` (string): Current status
+    - `pending`: Awaiting user approval
+    - `approved`: Registration approved, device ready
+    - `rejected`: Registration rejected by user
+    - `expired`: Registration expired (not approved in time)
+  - `device_name` (string): Name of the device
+  - `device_type` (string): Type of device
+  - `created_at` (string): Registration timestamp
+  - `updated_at` (string): Last status update timestamp
+
+  **Status Codes:**
+  - 200: Status retrieved successfully
+  - 404: Registration ID not found
+  - 400: Invalid registration ID format
+
+  **Polling Recommendations:**
+  - Poll every 5-10 seconds while status is `pending`
+  - Stop polling when status changes to `approved`, `rejected`, or `expired`
+  - Use exponential backoff for mobile devices to save battery
@@ -0,0 +1,11 @@
+info:
+  name: Check Registration Status
+  type: http
+  seq: 2
+http:
+  method: POST
+  url: '{{base_url}}/api/devices/register/status'
+  auth: none
+  body:
+    type: json
+    jsonBody: "{\n    \"registration_id\": \"{{registrationId"
@@ -0,0 +1,22 @@
+info:
+  name: Clear Kobo Shelf
+  type: http
+  seq: 1
+http:
+  method: DELETE
+  url: '{{baseURL}}/api/devices/{{deviceID}}/shelves/clear?shelf={{shelfName}}'
+  auth: inherit
+  body:
+    type: none
+  headers:
+  - key: Authorization
+    value: Bearer {{userToken
+
+docs: |-
+  ## Clear Kobo Shelf
+  
+    Clear all books from a Kobo device shelf, or all shelves if no shelf name is specified.
+  
+    **Method:** DELETE
+  
+    **Endpoint:** /api/devices/{deviceID
@@ -0,0 +1,55 @@
+info:
+  name: Create Device File Alias
+  type: http
+  seq: 1
+http:
+  method: POST
+  url: '{{base_url}}/api/devices/{{device_id}}/file-aliases'
+  auth: inherit
+  body:
+    type: json
+    jsonBody: "{\n    \"file_path\": \"/mnt/sd/books/my-book.kepub.epub\",\n    \"\
+      media_item_id\": \"{{media_item_id"
+  headers:
+  - key: Content-Type
+    value: application/json
+runtime:
+  scripts:
+  - type: tests
+    code: "test_create_device_file_alias_success(status, headers, body) {\n    if\
+      \ (status !== 201 && status !== 200) {\n      throw new Error(\"Expected status\
+      \ 201 or 200, got \" + status);"
+
+docs: |-
+  ## Create Device File Alias
+  
+    Creates a new file alias for a device. File aliases map device-specific file paths to media items.
+  
+    **Method:** POST
+  
+    **Endpoint:** /api/devices/:id/file-aliases
+  
+    **Authentication:** Required (Bearer token)
+  
+    **Path Parameters:**
+    - `id` (string, required): Device UUID
+  
+    **Request Body:**
+    - `file_path` (string, required): Device-specific file path
+    - `media_item_id` (string, required): Media item UUID to link to
+  
+    **Response:** Created file alias object
+    - `id` (string): Alias UUID
+    - `device_id` (string): Device UUID
+    - `file_path` (string): Device-specific file path
+    - `media_item_id` (string): Associated media item UUID
+    - `created_at` (string): Creation timestamp
+    - `updated_at` (string): Last update timestamp
+  
+    **Status Codes:**
+    - 201: Created
+    - 200: Success
+    - 400: Invalid request body
+    - 401: Unauthorized
+    - 404: Device not found
+    - 500: Internal server error
@@ -0,0 +1,22 @@
+info:
+  name: Delete Device
+  type: http
+  seq: 6
+http:
+  method: DELETE
+  url: '{{base_url}}/api/devices/{{device_id}}'
+  auth: inherit
+  body:
+    type: none
+  headers:
+  - key: Authorization
+    value: Bearer {{token
+
+docs: |-
+  ## Delete Device
+  
+    Deletes a device and unregisters it from the user's account.
+  
+    **Method:** DELETE
+  
+    **Endpoint:** /api/devices/{deviceId
@@ -0,0 +1,58 @@
+info:
+  name: Disable Device Sync
+  type: http
+  seq: 8
+
+http:
+  method: PUT
+  url: '{{base_url}}/api/devices/{{device_id}}'
+  auth: inherit
+  headers:
+    - key: Content-Type
+      value: application/json
+  body:
+    type: json
+    json:
+      device_name: My Kobo Clara
+      sync_enabled: false
+      auto_sync: false
+      sync_frequency_minutes: 30
+
+docs: |-
+  ## Disable Device Sync
+
+  Disables synchronization for a specific device.
+
+  **Method:** PUT
+
+  **Endpoint:** /api/devices/:device_id
+
+  **Authentication:** Required (Bearer token)
+
+  **Path Parameters:**
+  - `device_id` (string): UUID of the device
+
+  **Request Body:**
+  - `device_name` (string, optional): Device name
+  - `sync_enabled` (boolean): Must be `false`
+  - `auto_sync` (boolean): Should be `false`
+  - `sync_frequency_minutes` (integer, optional): Any value (sync disabled)
+
+  **Response:**
+  - `id` (string): Device UUID
+  - `device_name` (string): Device name
+  - `sync_enabled` (boolean): `false`
+  - `auto_sync` (boolean): `false`
+  - `message` (string): Confirmation message
+
+  **Status Codes:**
+  - 200: Sync disabled successfully
+  - 401: Unauthorized
+  - 403: Forbidden
+  - 404: Device not found
+
+  **Use Cases:**
+  - Temporarily disable sync for troubleshooting
+  - Stop sync for a lost or stolen device
+  - Disable sync before selling or giving away device
+  - Prevent data usage on limited connections
@@ -0,0 +1,44 @@
+info:
+  name: Get Device File Aliases
+  type: http
+  seq: 1
+http:
+  method: GET
+  url: '{{base_url}}/api/devices/{{device_id}}/file-aliases'
+  auth: inherit
+  headers:
+  - key: Content-Type
+    value: application/json
+runtime:
+  scripts:
+  - type: tests
+    code: "test_get_device_file_aliases_success(status, headers, body) {\n    if (status\
+      \ !== 200) {\n      throw new Error(\"Expected status 200, got \" + status);"
+
+docs: |-
+  ## Get Device File Aliases
+  
+    Retrieves all file aliases for a specific device. File aliases are used to map device-specific file paths to media items.
+  
+    **Method:** GET
+  
+    **Endpoint:** /api/devices/:id/file-aliases
+  
+    **Authentication:** Required (Bearer token)
+  
+    **Path Parameters:**
+    - `id` (string, required): Device UUID
+  
+    **Response:** Array of file alias objects
+    - `id` (string): Alias UUID
+    - `device_id` (string): Device UUID
+    - `file_path` (string): Device-specific file path
+    - `media_item_id` (string): Associated media item UUID
+    - `created_at` (string): Creation timestamp
+    - `updated_at` (string): Last update timestamp
+  
+    **Status Codes:**
+    - 200: Success
+    - 401: Unauthorized
+    - 404: Device not found
+    - 500: Internal server error
@@ -0,0 +1,45 @@
+info:
+  name: Get Device Details
+  type: http
+  seq: 6
+
+http:
+  method: GET
+  url: '{{base_url}}/api/devices/{{device_id}}'
+  auth: inherit
+
+docs: |-
+  ## Get Device Details
+
+  Retrieves detailed information about a specific device.
+
+  **Method:** GET
+
+  **Endpoint:** /api/devices/:device_id
+
+  **Authentication:** Required (Bearer token)
+
+  **Path Parameters:**
+  - `device_id` (string): UUID of the device
+
+  **Response:**
+  - `id` (string): Device UUID
+  - `device_name` (string): Device name
+  - `device_type` (string): `kobo`, `koreader`, or `web`
+  - `device_identifier` (string): Unique identifier
+  - `sync_enabled` (boolean): Sync status
+  - `auto_sync` (boolean): Auto-sync setting
+  - `sync_frequency_minutes` (integer): Sync interval
+  - `last_synced_at` (string): Last sync timestamp
+  - `sync_stats` (object): Sync statistics
+    - `total_syncs` (integer): Number of successful syncs
+    - `last_sync_status` (string): Status of last sync
+    - `bytes_synced` (integer): Total data transferred
+  - `created_at` (string): Registration timestamp
+  - `updated_at` (string): Last update timestamp
+
+  **Status Codes:**
+  - 200: Success
+  - 401: Unauthorized
+  - 403: Forbidden (device belongs to different user)
+  - 404: Device not found
@@ -0,0 +1,22 @@
+info:
+  name: Get Kobo Shelf Books
+  type: http
+  seq: 1
+http:
+  method: GET
+  url: '{{baseURL}}/api/devices/{{deviceID}}/shelves?shelf={{shelfName}}'
+  auth: inherit
+  body:
+    type: none
+  headers:
+  - key: Authorization
+    value: Bearer {{userToken
+
+docs: |-
+  ## Get Kobo Shelf Books
+  
+    Get all books on a Kobo device shelf, optionally filter by shelf name.
+  
+    **Method:** GET
+  
+    **Endpoint:** /api/devices/{deviceID
@@ -0,0 +1,12 @@
+info:
+  name: Initiate Device Registration
+  type: http
+  seq: 1
+http:
+  method: POST
+  url: '{{base_url}}/api/devices/register'
+  auth: none
+  body:
+    type: json
+    jsonBody: "{\n    \"device_name\": \"My Kindle Paperwhite\",\n    \"device_type\"\
+      : \"koreader\",\n    \"device_identifier\": \"kindle-pw5-hardware-id-12345\""
@@ -0,0 +1,41 @@
+info:
+  name: List User Devices
+  type: http
+  seq: 5
+
+http:
+  method: GET
+  url: '{{base_url}}/api/devices'
+  auth: inherit
+
+docs: |-
+  ## List User Devices
+
+  Retrieves all registered devices for the authenticated user.
+
+  **Method:** GET
+
+  **Endpoint:** /api/devices
+
+  **Authentication:** Required (Bearer token)
+
+  **Response:**
+  - Array of device objects:
+    - `id` (string): Device UUID
+    - `device_name` (string): Human-readable device name
+    - `device_type` (string): `kobo`, `koreader`, or `web`
+    - `device_identifier` (string): Unique device identifier
+    - `sync_enabled` (boolean): Whether sync is active
+    - `auto_sync` (boolean): Whether automatic sync is enabled
+    - `sync_frequency_minutes` (integer): Sync interval in minutes
+    - `last_synced_at` (string): Last successful sync timestamp
+    - `created_at` (string): Registration timestamp
+
+  **Status Codes:**
+  - 200: Success
+  - 401: Unauthorized
+
+  **Usage:**
+  - Display user's devices in account settings
+  - Allow users to manage sync settings per device
+  - Show last sync time for each device
@@ -0,0 +1,46 @@
+info:
+  name: Get Pending Registrations
+  type: http
+  seq: 11
+
+http:
+  method: GET
+  url: '{{base_url}}/api/devices/pending'
+  auth: inherit
+
+docs: |-
+  ## Get Pending Registrations
+
+  Retrieves all pending device registration requests awaiting approval.
+
+  **Method:** GET
+
+  **Endpoint:** /api/devices/pending
+
+  **Authentication:** Required (Bearer token)
+
+  **Response:**
+  - Array of pending registration objects:
+    - `registration_id` (string): Registration UUID
+    - `device_name` (string): Name of the device
+    - `device_type` (string): `kobo`, `koreader`, or `web`
+    - `device_identifier` (string): Device ID (may be masked)
+    - `created_at` (string): Request timestamp
+    - `expires_at` (string): Expiration timestamp
+    - `status` (string): Always `pending`
+
+  **Status Codes:**
+  - 200: Success
+  - 401: Unauthorized
+
+  **Use Cases:**
+  - Show pending registrations in user settings
+  - Allow users to review devices before approval
+  - Display registration request details
+  - Provide approve/reject actions
+
+  **Security Notes:**
+  - Full device identifier may be partially masked
+  - Only shows registrations for authenticated user
+  - Expired registrations are automatically removed
+  - Users can only see their own pending registrations
@@ -0,0 +1,49 @@
+info:
+  name: Register Device
+  type: http
+  seq: 1
+
+http:
+  method: POST
+  url: '{{base_url}}/api/devices/register'
+  auth: none
+  headers:
+    - key: Content-Type
+      value: application/json
+  body:
+    type: json
+    json:
+      device_name: My Kobo Clara
+      device_type: kobo
+      device_identifier: N1234567890123
+
+docs: |-
+  ## Register Device
+
+  Initiates device registration by sending device information to the server.
+
+  **Method:** POST
+
+  **Endpoint:** /api/devices/register
+
+  **Authentication:** None (public endpoint)
+
+  **Request Body:**
+  - `device_name` (string): Human-readable name for the device
+  - `device_type` (string): Type of device - `kobo`, `koreader`, or `web`
+  - `device_identifier` (string): Unique device identifier (serial number or other ID)
+
+  **Response:**
+  - `registration_id` (string): UUID for tracking registration status
+  - `status` (string): Registration status - `pending`, `approved`, or `rejected`
+  - `message` (string): Status message
+
+  **Status Codes:**
+  - 201: Registration initiated successfully
+  - 400: Invalid request data
+  - 409: Device already registered
+
+  **Notes:**
+  - Device registration requires user approval before activation
+  - Registration ID should be stored for status checking
+  - Device identifier must be unique per device
@@ -0,0 +1,48 @@
+info:
+  name: Register KOReader Device
+  type: http
+  seq: 2
+
+http:
+  method: POST
+  url: '{{base_url}}/api/devices/register'
+  auth: none
+  headers:
+    - key: Content-Type
+      value: application/json
+  body:
+    type: json
+    json:
+      device_name: My Kindle Paperwhite
+      device_type: koreader
+      device_identifier: G090GP123456789
+
+docs: |-
+  ## Register KOReader Device
+
+  Registers a KOReader device (typically Kindle devices running KOReader software).
+
+  **Method:** POST
+
+  **Endpoint:** /api/devices/register
+
+  **Authentication:** None (public endpoint)
+
+  **Request Body:**
+  - `device_name` (string): Human-readable name for the device
+  - `device_type` (string): Must be `koreader`
+  - `device_identifier` (string): Kindle serial number or unique device ID
+
+  **Response:**
+  - `registration_id` (string): UUID for tracking registration status
+  - `status` (string): Registration status - `pending`
+  - `message` (string): Confirmation message
+
+  **Status Codes:**
+  - 201: Registration initiated
+  - 400: Invalid device type or data
+
+  **KOReader Notes:**
+  - KOReader runs on Kindle, Kobo, PocketBook, and Android devices
+  - Device identifier is typically the device serial number
+  - Supports bookmarks, progress, highlights, and annotations sync
@@ -0,0 +1,49 @@
+info:
+  name: Register Web Device
+  type: http
+  seq: 3
+
+http:
+  method: POST
+  url: '{{base_url}}/api/devices/register'
+  auth: none
+  headers:
+    - key: Content-Type
+      value: application/json
+  body:
+    type: json
+    json:
+      device_name: Chrome Browser
+      device_type: web
+      device_identifier: web-client-abc123
+
+docs: |-
+  ## Register Web Device
+
+  Registers a web browser client for reading progress sync.
+
+  **Method:** POST
+
+  **Endpoint:** /api/devices/register
+
+  **Authentication:** None (public endpoint)
+
+  **Request Body:**
+  - `device_name` (string): Browser identification (e.g., "Chrome Browser")
+  - `device_type` (string): Must be `web`
+  - `device_identifier` (string): Unique browser/client identifier
+
+  **Response:**
+  - `registration_id` (string): UUID for tracking
+  - `status` (string): `pending` or `auto-approved`
+  - `message` (string): Status message
+
+  **Status Codes:**
+  - 201: Registration successful
+  - 400: Invalid request
+
+  **Web Device Notes:**
+  - Web devices use localStorage for device identification
+  - May be auto-approved without admin intervention
+  - Used for browser-based reading progress tracking
+  - Supports manual progress updates, highlights, and notes
@@ -0,0 +1,38 @@
+info:
+  name: Reject Device Registration
+  type: http
+  seq: 7
+http:
+  method: POST
+  url: '{{base_url}}/api/devices/reject/{{registration_id}}'
+  auth: inherit
+  body:
+    type: none
+
+docs: |-
+  ## Reject Device Registration
+  
+    Rejects a pending device registration request.
+  
+    **Method:** POST
+  
+    **Endpoint:** /api/devices/reject/:registration_id
+  
+    **Authentication:** Bearer token
+  
+    **Path Parameters:**
+     - `registration_id` (string): Registration request UUID
+  
+    **Response:**
+     - Success message confirming rejection
+  
+    **Status Codes:**
+     - 200: Success
+     - 401: Unauthorized
+     - 404: Registration not found
+     - 400: Invalid registration status
+  
+     **Example Response:**
+      ```json
+      {
+        "message": "device registration rejected"
@@ -0,0 +1,56 @@
+info:
+  name: Reject Registration - KOReader
+  type: http
+  seq: 16
+
+http:
+  method: POST
+  url: '{{base_url}}/api/devices/reject/reg-uuid-123'
+  auth: inherit
+
+docs: |-
+  ## Reject KOReader Registration
+
+  Rejects a pending KOReader device registration.
+
+  **Method:** POST
+
+  **Endpoint:** /api/devices/reject/:registration_id
+
+  **Authentication:** Required (Bearer token)
+
+  **Path Parameters:**
+  - `registration_id` (string): Example: `reg-uuid-123`
+
+  **Request Body:**
+  Optional rejection reason:
+  ```json
+  {
+    "reason": "Device not recognized or user cancelled"
+  }
+  ```
+
+  **Response:**
+  - `registration_id` (string): Rejected registration UUID
+  - `device_name` (string): KOReader device name
+  - `device_type` (string): `koreader`
+  - `status` (string): `rejected`
+  - `rejected_at` (string): Rejection timestamp
+
+  **Status Codes:**
+  - 200: Rejected successfully
+  - 401: Unauthorized
+  - 403: Forbidden
+  - 404: Registration not found
+
+  **KOReader Rejection Handling:**
+  - KOReader app displays rejection message
+  - User can initiate new registration
+  - Previous device identifier can be reused
+  - No data is lost on the device
+
+  **Common Reasons:**
+  - User didn't initiate registration
+  - Wrong device type selected
+  - Testing/sample registration
+  - Security concerns
@@ -0,0 +1,64 @@
+info:
+  name: Reject Registration - Kobo
+  type: http
+  seq: 17
+
+http:
+  method: POST
+  url: '{{base_url}}/api/devices/reject/reg-uuid-456'
+  auth: inherit
+
+docs: |-
+  ## Reject Kobo Registration
+
+  Rejects a pending Kobo e-reader device registration.
+
+  **Method:** POST
+
+  **Endpoint:** /api/devices/reject/:registration_id
+
+  **Authentication:** Required (Bearer token)
+
+  **Path Parameters:**
+  - `registration_id` (string): Example: `reg-uuid-456`
+
+  **Request Body:**
+  Optional rejection reason:
+  ```json
+  {
+    "reason": "Unrecognized device or user cancelled"
+  }
+  ```
+
+  **Response:**
+  - `registration_id` (string): Rejected registration UUID
+  - `device_name` (string): Kobo device name
+  - `device_type` (string): `kobo`
+  - `status` (string): `rejected`
+  - `rejected_at` (string): Rejection timestamp
+  - `message` (string): User-friendly message
+
+  **Status Codes:**
+  - 200: Rejected successfully
+  - 401: Unauthorized
+  - 403: Forbidden
+  - 404: Registration not found
+
+  **Kobo Rejection Handling:**
+  - Kobo sync service shows rejection on device
+  - Device remains unregistered
+  - User must retry registration process
+  - Device serial number can be reused
+
+  **Common Reasons:**
+  - Unrecognized Kobo device
+  - User didn't initiate sync
+  - Wrong account selected on device
+  - Security precaution
+  - Device sold/given away (prevent old owner access)
+
+  **Kobo-Specific Notes:**
+  - Kobo devices display rejection in sync settings
+  - Device may need to be rebooted to clear pending state
+  - No data is removed from the device
+  - Re-registration requires going through Kobo's sync setup again
@@ -0,0 +1,22 @@
+info:
+  name: Remove Book from Kobo Shelf
+  type: http
+  seq: 1
+http:
+  method: DELETE
+  url: '{{baseURL}}/api/devices/{{deviceID}}/shelves?media_item_id={{bookUUID}}'
+  auth: inherit
+  body:
+    type: none
+  headers:
+  - key: Authorization
+    value: Bearer {{userToken
+
+docs: |-
+  ## Remove Book from Kobo Shelf
+  
+    Remove a specific book from a Kobo device shelf, preventing it from syncing to that device.
+  
+    **Method:** DELETE
+  
+    **Endpoint:** /api/devices/{deviceID
@@ -0,0 +1,61 @@
+info:
+  name: Update Device Settings
+  type: http
+  seq: 7
+
+http:
+  method: PUT
+  url: '{{base_url}}/api/devices/{{device_id}}'
+  auth: inherit
+  headers:
+    - key: Content-Type
+      value: application/json
+  body:
+    type: json
+    json:
+      device_name: Updated Device Name
+      sync_enabled: true
+      auto_sync: true
+      sync_frequency_minutes: 10
+
+docs: |-
+  ## Update Device Settings
+
+  Updates device configuration and sync settings.
+
+  **Method:** PUT
+
+  **Endpoint:** /api/devices/:device_id
+
+  **Authentication:** Required (Bearer token)
+
+  **Path Parameters:**
+  - `device_id` (string): UUID of the device
+
+  **Request Body:**
+  - `device_name` (string, optional): New device name
+  - `sync_enabled` (boolean, optional): Enable/disable sync
+  - `auto_sync` (boolean, optional): Enable automatic sync
+  - `sync_frequency_minutes` (integer, optional): Sync interval (5-1440 minutes)
+
+  **Response:**
+  - `id` (string): Device UUID
+  - `device_name` (string): Updated device name
+  - `sync_enabled` (boolean): Updated sync status
+  - `auto_sync` (boolean): Updated auto-sync setting
+  - `sync_frequency_minutes` (integer): Updated sync interval
+  - `updated_at` (string): Update timestamp
+
+  **Status Codes:**
+  - 200: Settings updated successfully
+  - 400: Invalid sync frequency or data
+  - 401: Unauthorized
+  - 403: Forbidden (device belongs to different user)
+  - 404: Device not found
+
+  **Sync Frequency Guidelines:**
+  - Mobile devices: 10-30 minutes
+  - E-readers on WiFi: 15-60 minutes
+  - Web clients: 5-15 minutes
+  - Minimum: 5 minutes
+  - Maximum: 1440 minutes (24 hours)
@@ -0,0 +1,12 @@
+info:
+  name: Update Device
+  type: http
+  seq: 5
+http:
+  method: PUT
+  url: '{{base_url}}/api/devices/{{device_id}}'
+  auth: inherit
+  body:
+    type: json
+    jsonBody: "{\n    \"device_name\": \"My Updated Kindle\",\n    \"sync_enabled\"\
+      : true,\n    \"auto_sync\": true,\n    \"sync_frequency_minutes\": 10"
@@ -0,0 +1,66 @@
+info:
+  name: Update Sync Frequency
+  type: http
+  seq: 9
+
+http:
+  method: PUT
+  url: '{{base_url}}/api/devices/{{device_id}}'
+  auth: inherit
+  headers:
+    - key: Content-Type
+      value: application/json
+  body:
+    type: json
+    json:
+      device_name: My Kobo Clara
+      sync_enabled: true
+      auto_sync: true
+      sync_frequency_minutes: 15
+
+docs: |-
+  ## Update Sync Frequency
+
+  Changes how often the device automatically syncs with the server.
+
+  **Method:** PUT
+
+  **Endpoint:** /api/devices/:device_id
+
+  **Authentication:** Required (Bearer token)
+
+  **Path Parameters:**
+  - `device_id` (string): UUID of the device
+
+  **Request Body:**
+  - `device_name` (string, optional): Device name
+  - `sync_enabled` (boolean): Must be `true` for auto-sync
+  - `auto_sync` (boolean): Must be `true`
+  - `sync_frequency_minutes` (integer): New sync interval (5-1440)
+
+  **Response:**
+  - `id` (string): Device UUID
+  - `sync_enabled` (boolean): `true`
+  - `auto_sync` (boolean): `true`
+  - `sync_frequency_minutes` (integer): Updated interval
+  - `next_sync_at` (string): Estimated next sync time
+  - `updated_at` (string): Update timestamp
+
+  **Status Codes:**
+  - 200: Frequency updated successfully
+  - 400: Invalid frequency value
+  - 401: Unauthorized
+  - 403: Forbidden
+  - 404: Device not found
+
+  **Recommended Frequencies:**
+  - **Active reading:** 5-10 minutes
+  - **Normal usage:** 15-30 minutes
+  - **Occasional reading:** 30-60 minutes
+  - **Battery saving:** 60+ minutes
+  - **WiFi only (3G):** 30-60 minutes
+
+  **Notes:**
+  - More frequent sync = more battery usage
+  - Sync only occurs when device is online
+  - Manual sync can be triggered anytime regardless of frequency
@@ -0,0 +1,24 @@
+info:
+  name: Regenerate Device Token - Forbidden
+  type: http
+  seq: 3
+http:
+  method: PUT
+  url: '{{base_url}}/api/devices/{{other_device_id}}/regenerate-token'
+  auth: inherit
+  body:
+    type: none
+
+docs: |-
+  ## Regenerate Device Token - Forbidden
+  
+    Tests that users cannot regenerate tokens for devices belonging to other users.
+  
+    **Expected Behavior:** Returns 403 Forbidden when trying to regenerate token for another user's device
+  
+    **Status Codes:**
+    - 403: Forbidden (device belongs to different user)
+  
+    **Use Case:** Verify authorization - users can only manage their own devices
+  
+    **Setup:** Use Bearer token from user A, try to regenerate token for user B's device
@@ -0,0 +1,24 @@
+info:
+  name: Regenerate Device Token - Not Found
+  type: http
+  seq: 4
+http:
+  method: PUT
+  url: '{{base_url}}/api/devices/00000000-0000-0000-0000-000000000000/regenerate-token'
+  auth: bearer
+  body:
+    type: none
+
+docs: |-
+  ## Regenerate Device Token - Not Found
+  
+    Tests that token regeneration returns 404 for non-existent devices.
+  
+    **Expected Behavior:** Returns 404 Not Found when device UUID doesn't exist
+  
+    **Status Codes:**
+    - 404: Device not found
+  
+    **Use Case:** Verify proper error handling for invalid device IDs
+  
+    **Setup:** Use all-zero UUID (guaranteed to not exist in database)
@@ -0,0 +1,22 @@
+info:
+  name: Regenerate Device Token - Unauthorized
+  type: http
+  seq: 2
+http:
+  method: PUT
+  url: '{{base_url}}/api/devices/{{device_id}}/regenerate-token'
+  auth: none
+  body:
+    type: none
+
+docs: |-
+  ## Regenerate Device Token - Unauthorized
+  
+    Tests that token regeneration requires authentication.
+  
+    **Expected Behavior:** Returns 401 Unauthorized when no Bearer token is provided
+  
+    **Status Codes:**
+    - 401: Unauthorized (missing or invalid token)
+  
+    **Use Case:** Verify authentication is required for token regeneration
@@ -0,0 +1,19 @@
+info:
+  name: Regenerate Device Token
+  type: http
+  seq: 1
+http:
+  method: PUT
+  url: '{{base_url}}/api/devices/{{device_id}}/regenerate-token'
+  auth: inherit
+  body:
+    type: none
+
+docs: |-
+  ## Regenerate Device Token
+  
+    Regenerates auth token for a device, invalidating old token immediately.
+  
+    **Method:** PUT
+  
+    **Endpoint:** /api/devices/{device_id