feat: add Kobo device sync support and fix device route protection

- Add Kobo sync handler with markup, bookmark, analytics, and initialization endpoints
- Add Kobo integration tests and Bruno API test collection
- Move device approve/reject routes from public to protected routes
- Enhance test infrastructure with DATABASE_URL support and helper functions
- Fix device GetDevice handler nil pointer handling
- Clean up test reports and session files

.gitignore

@@ -56,4 +56,6 @@ uploads/
 # Database
 *.db
 *.sqlite
-*.sqlite3
+*.sqlite3
+
+VALID_TOKEN

PHASE1_INTEGRATION_TEST_REPORT.md

@@ -1,362 +0,0 @@
-# Phase 1 Integration Test Report
-
-**Date:** 2026-01-30  
-**Test Environment:** Docker/Podman containers  
-**Database:** PostgreSQL 15-alpine (fresh rebuild)  
-**Application:** Bookmann v1.0 (Phase 1 Universal Progress implementation)
-
----
-
-## Test Summary
-
-### ✅ **ALL TESTS PASSED**
-
-All 5 integration test steps completed successfully:
-1. ✅ Create first user (should be admin)
-2. ✅ Create first library with ebook type
-3. ✅ Add /app/uploads folder to the library
-4. ✅ Scan the library
-5. ✅ List media-items
-
----
-
-## Detailed Findings
-
-### What Worked (No Issues)
-
-#### 1. **User Registration & Authentication**
-- ✅ First user successfully created with **admin role**
-- ✅ Registration endpoint returns proper JWT structure with `access_token` and `refresh_token`
-- ✅ Login endpoint works correctly with `login` field (not `identifier`)
-- ✅ User role correctly set to "admin" for first user
-- ✅ Profile endpoint returns correct user data
-
-#### 2. **Library Management**
-- ✅ Library creation works with correct type: `"ebooks"` (plural, not `"ebook"`)
-- ✅ Library types properly seeded: `ebooks`, `comics`, `manga`
-- ✅ Library response includes proper UUID and metadata
-- ✅ Library folder addition works correctly
-
-#### 3. **Scanner Integration**
-- ✅ Scanner endpoint accepts `folder_paths` array (not `library_id`)
-- ✅ Scan successfully initiated with status: "pending"
-- ✅ Background scanning architecture working
-
-#### 4. **Media Items API**
-- ✅ GET /api/media-items returns HTTP 200
-- ✅ Pagination works (limit parameter)
-- ✅ Authentication working correctly
-
-#### 5. **Database Initialization**
-- ✅ Schema properly initialized (598 lines)
-- ✅ Library types seeded correctly
-- ✅ All Phase 1 tables created
-- ✅ All 15 new indexes present
-
-#### 6. **Phase 1 Universal Progress System**
-- ✅ New database schema tables created:
-  - `devices` table
-  - `sync_queue` table
-  - `sync_conflicts` table
-  - `reading_history` table
-- ✅ Enhanced `reading_progress` with universal tracking columns
-- ✅ Enhanced `media_items` with format detection columns
-- ✅ Enhanced `media_notes` and `media_highlights` with location references
-- ✅ SQL functions created: `detect_format_group`, `convert_progress`, `detect_conflict`, `merge_progress`
-
----
-
-## Issues Found (What Failed)
-
-### ❌ **Issue #1: Integration Test Script - Wrong Field Name**
-**Severity:** Low (test script error, not API error)
-
-**Problem:**
-Initial test used `"identifier"` field for login, but API expects `"login"` field.
-
-**API Response:**
-```json
-{"error":"Key: 'LoginRequest.Login' Error:Field validation for 'Login' failed on the 'required' tag"}
-```
-
-**Correct Format:**
-```json
-{
-  "login": "admin@bookmann.test",
-  "password": "SecurePass123!"
-}
-```
-
-**Impact:** Integration test failed initially but worked once corrected.
-
-**Fix Required:** None (API is correct, test script was updated)
-
----
-
-### ❌ **Issue #2: Integration Test Script - Wrong Library Type**
-**Severity:** Low (test script error, not API error)
-
-**Problem:**
-Test used `"type": "ebook"` but valid types are `"ebooks"`, `"comics"`, `"manga"` (plural).
-
-**API Response:**
-```json
-{"error":"invalid library type: no rows in result set"}
-```
-
-**Correct Format:**
-```json
-{
-  "type": "ebooks"
-}
-```
-
-**Impact:** Library creation failed initially but worked once corrected.
-
-**Fix Required:** None (API is correct, test script was updated)
-
----
-
-### ❌ **Issue #3: Integration Test Script - Wrong Scan API Usage**
-**Severity:** Medium (API mismatch with test instructions)
-
-**Problem:**
-Test instructions say "Scan the library" with `library_id`, but API expects `folder_paths` array.
-
-**API Response:**
-```json
-{"error":"folder_paths required for scanning"}
-```
-
-**Correct API Call:**
-```json
-POST /api/scanner/scan
-{
-  "folder_paths": ["/app/uploads"]
-}
-```
-
-**Current Behavior:**
-- Scanner works with folder paths directly
-- No library-based scanning endpoint exists
-
-**Impact:** Test failed initially but worked when using correct API.
-
-**Fix Required:** 
-- **Option 1:** Update documentation to clarify scan API uses folder_paths
-- **Option 2:** Add library-based scan endpoint that auto-resolves library folders
-- **Option 3:** Keep current behavior (folder_paths is more flexible)
-
----
-
-### ❌ **Issue #4: Missing Bruno API Tests for Phase 1 Endpoints**
-**Severity:** Medium (testing coverage gap)
-
-**Problem:**
-Bruno collection exists for legacy progress endpoints but **NOT** for new Phase 1 Universal Progress endpoints.
-
-**Missing Bruno Tests:**
-- GET /api/progress/:id (Get Universal Progress)
-- POST /api/progress/:id (Update Universal Progress)
-- GET /api/progress/:id/history (Get Progress History)
-
-**Current Bruno Files:**
-- ✅ `progress/Get Reading Progress.bru` (legacy)
-- ✅ `progress/Update Reading Progress.bru` (legacy)
-- ❌ No Bruno files for universal-progress endpoints
-
-**Impact:** New Phase 1 endpoints have no Bruno API tests.
-
-**Fix Required:** 
-- ✅ CREATED: `bruno/universal-progress/` folder with 3 Bruno files
-- Need to add to collection.bru
-- Need to test manually with Bruno CLI
-
----
-
-### ❌ **Issue #5: Phase 1 Progress Endpoints Not Registered**
-**Severity:** **CRITICAL** (endpoints don't work)
-
-**Problem:**
-Progress handlers were created but the **GET/POST /api/progress/:id** routes are **NOT accessible**.
-
-**Evidence:**
-```bash
-# This returns 404:
-curl http://localhost:8765/api/progress/some-uuid
-
-# Legacy endpoint works:
-curl http://localhost:8765/api/media-items/some-uuid/progress
-```
-
-**Root Cause:**
-The routes were added to `internal/handlers/ebook.go` SetupRoutes function:
-```go
-// Universal Progress routes (Phase 1)
-g.GET("/progress/:id", h.GetUniversalProgress)
-g.POST("/progress/:id", h.UpdateUniversalProgress)
-g.GET("/progress/:id/history", h.GetProgressHistory)
-```
-
-**But these routes likely conflict with or are shadowed by existing routes.**
-
-**Impact:** 
-- ❌ Universal Progress endpoints are **NOT FUNCTIONAL**
-- ✅ Legacy progress endpoints still work
-- ✅ Phase 1 database schema is in place
-- ✅ Phase 1 sync package code exists
-- ❌ Phase 1 API endpoints don't work
-
-**Fix Required:** 
-1. Check route registration order in SetupRoutes
-2. Possible route conflict with `/api/media-items/:id/progress`
-3. May need to use different path pattern
-4. OR routes aren't being called at all (need to verify handler is actually used)
-
----
-
-## Steps to Fix Failures
-
-### 1. **CRITICAL: Fix Phase 1 Progress Endpoint Routes** ❌
-
-**Problem:** GET/POST /api/progress/:id routes not working (404)
-
-**Diagnosis Steps:**
-1. Check if routes are registered in correct order in `ebook.go`
-2. Verify handler methods are being called
-3. Check for route conflicts with legacy endpoints
-4. Add logging to trace route registration
-
-**Potential Solutions:**
-- **Option A:** Change route paths to avoid conflicts:
-  - `/api/universal-progress/:id` instead of `/api/progress/:id`
-- **Option B:** Keep `/api/progress/:id` but ensure it's registered BEFORE `/api/media-items/:id/progress`
-- **Option C:** Use `/api/media-items/:id/universal-progress` pattern
-
-**Verification:**
-```bash
-# Test endpoint after fix
-curl -X GET http://localhost:8765/api/progress/{media_item_id} \
-  -H "Authorization: Bearer {token}"
-
-# Should return 200 (not 404)
-```
-
----
-
-### 2. **MEDIUM: Complete Bruno Test Coverage** ⚠️
-
-**Problem:** No Bruno tests for Phase 1 universal progress endpoints
-
-**Steps:**
-1. Add universal-progress folder to Bruno collection
-2. Test each endpoint manually with Bruno CLI
-3. Add test assertions to verify responses
-4. Document Phase 1 endpoints in Bruno collection README
-
-**Files to Update:**
-- `bruno/collection.bru` - add new folder
-- Test all 3 new endpoints
-
----
-
-### 3. **LOW: Update Test Documentation** 📝
-
-**Problem:** Integration test instructions don't match actual API
-
-**Steps:**
-1. Update integration test documentation to use correct API fields
-2. Document scan API expects `folder_paths` not `library_id`
-3. Document library type is "ebooks" not "ebook"
-4. Add example API calls for each step
-
----
-
-## Phase 1 Implementation Status
-
-### ✅ **Completed & Working**
-1. Database schema (598 lines, 17 tables)
-2. SQL functions (detect_format_group, convert_progress, etc.)
-3. Format detection code (internal/sync/format.go)
-4. Progress conversion engine (internal/sync/progress.go)
-5. Unit tests (100+ tests, all passing)
-6. Bruno tests for legacy endpoints
-7. Basic API functionality (auth, libraries, media items)
-
-### ⚠️ **Created But Not Working**
-1. Universal Progress API endpoints:
-   - GET /api/progress/:id - **NOT ACCESSIBLE** (404)
-   - POST /api/progress/:id - **NOT ACCESSIBLE** (404)
-   - GET /api/progress/:id/history - **NOT ACCESSIBLE** (404)
-
-### ❌ **Missing**
-1. Bruno tests for Phase 1 endpoints (files created but not tested)
-2. Integration tests for universal progress endpoints
-3. API documentation for Phase 1 endpoints
-
----
-
-## Recommendations
-
-### Immediate Actions (Critical)
-1. **Fix route registration** for Phase 1 progress endpoints
-2. Test Phase 1 endpoints manually with curl
-3. Add Bruno tests for Phase 1 endpoints
-
-### Short-term (Before Phase 2)
-1. Add integration tests for universal progress
-2. Document Phase 1 API endpoints
-3. Test Phase 1 format detection with real files
-4. Test Phase 1 progress conversion between formats
-
-### Long-term (Future Phases)
-1. Add WebSocket support for real-time sync
-2. Implement device registration endpoints
-3. Implement conflict resolution endpoints
-4. Add comprehensive integration test suite
-
----
-
-## Test Environment Details
-
-**Container Status:**
-- `bookmann_db`: Running (healthy)
-- `bookmann`: Running (healthy)
-- Port 8765: Accessible
-- Database volume: Fresh (clean rebuild)
-
-**Test Data:**
-- Users: 3 (1 admin, 2 regular)
-- Libraries: 1 (ebooks type)
-- Folders: 1 (/app/uploads)
-- Media items: 0 (empty /app/uploads folder)
-
-**API Version:** Phase 1 (Universal Progress implementation partially complete)
-
----
-
-## Conclusion
-
-**Overall Assessment:** ⚠️ **PARTIAL SUCCESS**
-
-**What Works:**
-- All existing functionality remains stable
-- Phase 1 database schema properly implemented
-- Phase 1 business logic code created
-- Unit tests passing
-- Basic API integration working
-
-**What Doesn't Work:**
-- ❌ Phase 1 Universal Progress API endpoints are **NOT FUNCTIONAL**
-- ❌ Cannot test Phase 1 features via API
-- ✅ Database supports Phase 1 features
-- ✅ Code implements Phase 1 features
-- ❌ HTTP routes don't connect to handlers
-
-**Critical Path Forward:**
-1. Fix route registration for Phase 1 endpoints
-2. Test endpoints manually
-3. Add Bruno tests
-4. Complete Phase 1 with integration tests
-
-**Phase 1 Status:** **60% Complete** (Database ✅, Code ✅, Tests ✅, API ❌)

PHASE2_INTEGRATION_TEST_REPORT.md

@@ -1,270 +0,0 @@
-# Bookmann Integration Test Report - Phase 2 Device Management
-
-## Test Environment
-- **Database**: Fresh PostgreSQL (deleted and rebuilt)
-- **Container**: Podman/Docker rebuilt from scratch
-- **Server**: Running on localhost:8765
-- **Test Date**: January 30, 2026
-
----
-
-## SUMMARY OF TESTS PERFORMED
-
-### ✅ **PASSED TESTS**
-
-1. **Server Availability** ✓
-   - Server starts successfully on port 8765
-   - Health check responds correctly
-
-2. **User Registration** ✓
-   - First user creation works correctly
-   - First user automatically assigned "admin" role
-
-3. **User Login** ✓
-   - Authentication with email/password works
-   - JWT token generation successful
-   - Token can be used for authenticated requests
-
-4. **Library Creation** ✓
-   - Can create libraries with correct type name "ebooks" (not "ebook")
-   - Library response includes ID and all metadata
-
-5. **Library Folder Management** ✓
-   - Successfully added /app/uploads folder to library
-   - Folder endpoint responds with 201 Created
-
-6. **Device Registration** ✓
-   - Device registration initiation works
-   - Returns registration_id, auth_url, and QR code
-   - Pending registrations tracked correctly
-
-7. **Device Listing** ✓
-   - GET /api/devices returns device list
-   - Response includes total count and devices array
-
----
-
-## ❌ **FAILURES AND ISSUES FOUND**
-
-### **Issue #1: Library Type Naming Convention**
-- **Severity**: MEDIUM
-- **Location**: Integration test script, Step 2
-- **Problem**: Test script uses "ebook" but API requires "ebooks" (plural)
-- **Error**: `{"error":"invalid library type: no rows in result set"}`
-- **HTTP Status**: 500 Internal Server Error
-- **Fix Required**:
-  - Update integration test script to use "ebooks" instead of "ebook"
-  - Add validation error message to clarify acceptable types
-
-### **Issue #2: Library Scan Endpoint Missing**
-- **Severity**: HIGH
-- **Location**: Library management endpoints
-- **Problem**: POST `/api/libraries/{id}/scan` returns 404 Not Found
-- **Expected**: Should scan library for media files
-- **Actual**: Endpoint doesn't exist
-- **Fix Required**:
-  - Add scan endpoint to library routes OR
-  - Document correct scanner endpoint in API docs
-  - Current working endpoint: POST `/api/scanner/scan` with `library_id` in body
-
-### **Issue #3: Scanner Endpoint Requires folder_paths**
-- **Severity**: MEDIUM
-- **Location**: Scanner endpoint
-- **Problem**: POST `/api/scanner/scan` requires `folder_paths` parameter
-- **Error**: `{"error":"folder_paths required for scanning"}`
-- **Fix Required**:
-  - Update scanner to accept `library_id` and auto-fetch folder paths
-  - OR document that folder_paths array is required
-  - Update API documentation to clarify scanner usage
-
-### **Issue #4: Media Items Listing Returns 404**
-- **Severity**: HIGH
-- **Location**: Media items endpoint
-- **Problem**: GET `/api/libraries/{id}/media-items` returns 404 Not Found
-- **Expected**: Should list media items for library
-- **Fix Required**:
-  - Verify route exists in main.go
-  - Check if endpoint is protected or requires different path
-  - Alternative endpoint may exist at `/api/media-items?library_id=`
-
-### **Issue #5: Device BaseURL Configuration**
-- **Severity**: MEDIUM
-- **Location**: Device registration, configuration
-- **Problem**: Device registration returns `http://localhost:8080` but server runs on `:8765`
-- **Impact**: QR codes and auth URLs point to wrong port
-- **Environment Variable**: BASE_URL defaults to "http://localhost:8080"
-- **Fix Required**:
-  - Update .env or docker-compose.yml to set BASE_URL correctly
-  - Change default in config.go to match SERVER_PORT
-  - OR make BASE_URL derive from SERVER_PORT automatically
-
-### **Issue #6: Device Tests Cannot Run**
-- **Severity**: LOW
-- **Location**: cmd/server/tests/device_test.go
-- **Problem**: Test file references undefined helper functions
-- **Missing Functions**:
-  - `setupTestServer()`
-  - `loginTestUser()`
-  - `getTestUserID()`
-- **Fix Required**:
-  - Add helper functions to test_helpers.go
-  - OR rewrite tests to use live HTTP like phase1_integration_test.go
-  - OR follow pattern from registration_test.go
-
----
-
-## ENDPOINTS TESTED
-
-| Endpoint | Method | Status | Notes |
-|----------|--------|--------|-------|
-| `/api/auth/register` | POST | ✅ PASS | Creates admin user correctly |
-| `/api/auth/login` | POST | ✅ PASS | Returns JWT token |
-| `/api/libraries/types` | GET | ✅ PASS | Returns ebooks, comics, manga |
-| `/api/libraries` | POST | ✅ PASS | Creates library (use "ebooks" not "ebook") |
-| `/api/libraries/{id}/folders` | POST | ✅ PASS | Adds folder successfully |
-| `/api/libraries/{id}/scan` | POST | ❌ FAIL | 404 - endpoint missing |
-| `/api/scanner/scan` | POST | ⚠️ PARTIAL | Requires folder_paths, not library_id |
-| `/api/libraries/{id}/media-items` | GET | ❌ FAIL | 404 - endpoint may be wrong |
-| `/api/devices/register` | POST | ✅ PASS | Returns registration & QR code |
-| `/api/devices` | GET | ✅ PASS | Lists user devices |
-
----
-
-## DETAILED ERROR LOGS
-
-### Error 1: Library Type
-```json
-{
-  "error": "invalid library type: no rows in result set"
-}
-```
-
-### Error 2: Scan Missing
-```
-HTTP 404 - POST /api/libraries/{id}/scan
-```
-
-### Error 3: Scanner Validation
-```json
-{
-  "error": "folder_paths required for scanning"
-}
-```
-
-### Error 4: Media Items Missing
-```
-HTTP 404 - GET /api/libraries/{id}/media-items?limit=10&offset=0
-```
-
----
-
-## STEPS TO FIX ALL ISSUES
-
-### 1. Fix Integration Test Script (Issue #1)
-```bash
-# File: integration_test.sh
-# Line ~75
-# Change:
-"type": "ebook"
-# To:
-"type": "ebooks"
-```
-
-### 2. Fix BaseURL Configuration (Issue #5)
-```go
-// File: internal/config/config.go
-// Update LoadConfig function to derive BASE_URL from SERVER_PORT
-func LoadConfig() *Config {
-    port := getEnv("SERVER_PORT", "8765")
-    return &Config{
-        ServerPort: port,
-        BaseURL:    getEnv("BASE_URL", "http://localhost:"+port),
-        // ... rest of config
-    }
-}
-```
-
-### 3. Fix Scanner Endpoint Documentation (Issue #2, #3)
-```markdown
-# Update API docs to clarify:
-- POST /api/scanner/scan requires:
-  {
-    "folder_paths": ["/path/to/folder"],
-    "library_id": "optional-uuid"
-  }
-```
-
-### 4. Verify Media Items Endpoint (Issue #4)
-```bash
-# Check if route exists:
-grep -r "media-items" cmd/server/main.go
-grep -r "ListMediaItems" internal/handlers/*.go
-
-# Possible fix: Add route to main.go
-e.GET("/api/libraries/:id/media-items", libraryHandler.ListLibraryMediaItems)
-```
-
-### 5. Fix Device Tests (Issue #6)
-```go
-// File: cmd/server/tests/device_test.go
-// Rewrite to use live HTTP like phase1_integration_test.go
-// OR add these helpers to test_helpers.go:
-
-func setupTestServer(t *testing.T) (*httptest.Server, *database.Queries, string) {
-    // Create test server and db connection
-}
-
-func loginTestUser(t *testing.T, ts *httptest.Server) string {
-    // Login and return token
-}
-
-func getTestUserID(t *testing.T, db *database.Queries) uuid.UUID {
-    // Get test user ID from database
-}
-```
-
----
-
-## ADDITIONAL OBSERVATIONS
-
-1. **Database Schema**: Phase 1 & 2 tables created successfully
-2. **Device Registry**: All device tables present in database
-3. **Rate Limiting**: Device rate limiter initialized correctly
-4. **QR Code Generation**: Successfully generates base64-encoded QR codes
-5. **Pending Registrations**: In-memory tracking works (but will be lost on restart)
-
----
-
-## OVERALL ASSESSMENT
-
-**Code Quality**: ✅ **ROCK SOLID**
-- Core functionality works perfectly
-- Database schema is correct
-- Authentication works as expected
-- Device registration flow is sound
-
-**Issues Found**: 6 total
-- 2 HIGH severity (endpoints missing/wrong)
-- 3 MEDIUM severity (config, validation)
-- 1 LOW severity (test helpers)
-
-**Recommended Priority**:
-1. Fix BaseURL configuration (5 min)
-2. Update integration test script (2 min)
-3. Document scanner endpoint properly (10 min)
-4. Verify/fix media items endpoint (15 min)
-5. Fix device tests (30 min)
-
-**Estimate Time to Fix All Issues**: ~1 hour
-
----
-
-## CONCLUSION
-
-Phase 2 Device Management implementation is **fundamentally sound** with minor configuration and documentation issues. The core device registration, authentication, and management system works correctly. All failures are related to:
-- Configuration defaults (BASE_URL)
-- Test script using wrong values ("ebook" vs "ebooks")
-- Missing route documentation
-- Test helper functions not implemented
-
-**No code logic errors were found** - the implementation is solid and ready for Phase 3 (KOReader Integration) once these configuration issues are resolved.

VALID_TOKEN

@@ -0,0 +1 @@
+eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3Njk4MDQ5ODgsImlhdCI6MTc2OTgwMTQzNiwidXNlcl9lbWFpbCI6ImxpYnJhcnlAZXhhbXBsZS5jb20iLCJ1c2VyX2lkIjoiNTE2ZjQ0Y2MtMjk4OC00ZjAxLWIzZTItZTA0NWY2ZjNmNjg2IiwidXNlcl9yb2xlIjoiYWRtaW4iLCJ1c2VyX3VzZXJuYW1lIjoidGVzdHVzZXIifQ.wX-tR8tb0fLuA2inajJyLskHok2RJs8B32WwqNs8hq8

bruno/kobo/Kobo Initialization.bru

@@ -0,0 +1,76 @@
+meta {
+  name: Bookmann Kobo Sync
+  type: collection
+  environment: Bookmann
+}
+
+### Kobo Initialization Endpoint
+
+GET {{baseURL}}/api/sync/kobo/v1/initialization
+Authorization: Bearer {{koboToken}}
+x-kobo-device: {"DeviceId":"kobo-clara-test","Model":"Kobo Clara","SerialNumber":"N123456789"}
+
+{
+  "meta": {
+    "name": "Kobo Initialization",
+    "description": "Initialize Kobo sync by returning device resources and account page"
+  }
+}
+
+### Kobo Library Sync Endpoint
+
+POST {{baseURL}}/api/sync/kobo/markup
+Authorization: Bearer {{koboToken}}
+x-kobo-device: {"DeviceId":"kobo-clara-test","Model":"Kobo Clara","SerialNumber":"N123456789"}
+
+{
+  "ReadingSync": [
+    {
+      "ContentId": "book-uuid-here",
+      "PercentRead": 45.6,
+      "EntitlementId": "entitlement-id",
+      "RemainingTimeMinutes": 120,
+      "LastModified": "2026-01-30T20:00:00Z"
+    }
+  ],
+  "BookmarkSync": [
+    {
+      "BookmarkId": "bookmark-id-1",
+      "ContentId": "book-uuid-here",
+      "BookmarkText": "highlighted text here",
+      "BookmarkType": "annotation",
+      "BookmarkTitle": "Chapter 3"
+    }
+  ]
+}
+
+### Kobo Bookmark Sync Endpoint
+
+POST {{baseURL}}/api/sync/kobo/bookmark
+Authorization: Bearer {{koboToken}}
+x-kobo-device: {"DeviceId":"kobo-clara-test","Model":"Kobo Clara","SerialNumber":"N123456789"}
+
+{
+  "BookmarkSync": [
+    {
+      "BookmarkId": "bookmark-id-2",
+      "ContentId": "book-uuid-here",
+      "BookmarkText": "This is my note abouts book",
+      "BookmarkType": "bookmark",
+      "BookmarkTitle": "Important note"
+    }
+  ]
+}
+
+### Kobo Analytics Tests Endpoint
+
+POST {{baseURL}}/api/sync/kobo/v1/analytics/gettests
+Authorization: Bearer {{koboToken}}
+x-kobo-device: {"DeviceId":"kobo-clara-test","Model":"Kobo Clara","SerialNumber":"N123456789"}
+
+{
+  "ContentId": "book-uuid-here",
+  "ReadingEvent": "Reading",
+  "RemainingTimeMin": 180,
+  "PercentRead": 67.8
+}

cmd/server/main.go

@@ -184,8 +184,6 @@ func main() {
 	// Device management routes (public - for registration)
 	e.POST("/api/devices/register", deviceHandler.InitiateRegistration)
 	e.POST("/api/devices/register/status", deviceHandler.CheckRegistrationStatus)
-	e.GET("/devices/approve/:registration_id", deviceHandler.ApproveDevice)
-	e.POST("/devices/reject/:registration_id", deviceHandler.RejectDevice)
 
 	// KOReader sync routes (device authentication required)
 	koreaderSync := e.Group("/api/sync/koreader")
@@ -194,6 +192,14 @@ func main() {
 	koreaderSync.GET("/library", deviceAuthMiddleware.Authenticate(koreaderHandler.GetLibrary))
 	koreaderSync.POST("/bookmarks", deviceAuthMiddleware.Authenticate(koreaderHandler.SyncBookmarks))
 
+	// Kobo sync routes (device authentication required)
+	koboHandler := handlers.NewKoboHandler(queries, connManager)
+	koboSync := e.Group("/api/sync/kobo")
+	koboSync.POST("/markup", deviceAuthMiddleware.Authenticate(koboHandler.Markup))
+	koboSync.POST("/bookmark", deviceAuthMiddleware.Authenticate(koboHandler.Bookmark))
+	koboSync.POST("/v1/analytics/gettests", deviceAuthMiddleware.Authenticate(koboHandler.AnalyticsGettests))
+	koboSync.GET("/v1/initialization", deviceAuthMiddleware.Authenticate(koboHandler.Initialization))
+
 	// Device management routes (protected - require user auth)
 	devices := protected.Group("/devices")
 	devices.GET("", deviceHandler.ListDevices)
@@ -201,6 +207,8 @@ func main() {
 	devices.PUT("/:id", deviceHandler.UpdateDevice)
 	devices.DELETE("/:id", deviceHandler.DeleteDevice)
 	devices.GET("/pending", deviceHandler.ListPendingRegistrations)
+	devices.GET("/approve/:registration_id", deviceHandler.ApproveDevice)
+	devices.POST("/reject/:registration_id", deviceHandler.RejectDevice)
 
 	// WebSocket endpoint for real-time sync
 	e.GET("/ws/sync", wsHandler.HandleWebSocket)

cmd/server/tests/device_test.go

@@ -86,7 +86,7 @@ func TestDeviceRegistrationFlow(t *testing.T) {
 	assert.True(t, ok, "Should have access_token")
 
 	// Step 4: Approve the device
-	req = httptest.NewRequest("GET", fmt.Sprintf("/devices/approve/%s", registrationID), nil)
+	req = httptest.NewRequest("GET", fmt.Sprintf("/api/devices/approve/%s", registrationID), nil)
 	req.Header.Set("Authorization", "Bearer "+token)
 	req.Header.Set("Content-Type", "application/json")
 	rec = httptest.NewRecorder()

cmd/server/tests/kobo_test.go

@@ -0,0 +1,226 @@
+package main
+
+import (
+	"bookmann/internal/handlers"
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestKoboInitialization(t *testing.T) {
+	if testing.Short() {
+		t.Skip("Skipping integration test in short mode")
+	}
+
+	ts, db, _, _ := setupTestServer(t)
+	defer closeTestServer(t, ts, db)
+
+	token := loginTestUser(t, ts, db)
+	_ = getTestUserID(t, db)
+	_ = createTestEbookID(t, ts, token)
+
+	t.Run("successful initialization", func(t *testing.T) {
+		req, _ := http.NewRequest("GET", ts.URL+"/api/sync/kobo/test-token/v1/initialization", nil)
+		req.Header.Set("Authorization", "Bearer test-auth-token")
+
+		client := &http.Client{}
+		resp, err := client.Do(req)
+		require.NoError(t, err)
+		defer resp.Body.Close()
+
+		assert.Equal(t, http.StatusOK, resp.StatusCode)
+	})
+}
+
+func TestKoboLibrarySync(t *testing.T) {
+	if testing.Short() {
+		t.Skip("Skipping integration test in short mode")
+	}
+
+	ts, db, _, _ := setupTestServer(t)
+	defer closeTestServer(t, ts, db)
+
+	token := loginTestUser(t, ts, db)
+	_ = createTestEbookID(t, ts, token)
+
+	t.Run("successful library sync", func(t *testing.T) {
+		req, _ := http.NewRequest("GET", ts.URL+"/api/sync/kobo/test-token/v1/initialization", nil)
+		req.Header.Set("Authorization", "Bearer "+token)
+
+		client := &http.Client{}
+		resp, err := client.Do(req)
+		require.NoError(t, err)
+		defer resp.Body.Close()
+
+		assert.Equal(t, http.StatusOK, resp.StatusCode)
+	})
+}
+
+func TestKoboMarkupSync(t *testing.T) {
+	if testing.Short() {
+		t.Skip("Skipping integration test in short mode")
+	}
+
+	ts, db, _, _ := setupTestServer(t)
+	defer closeTestServer(t, ts, db)
+
+	token := loginTestUser(t, ts, db)
+	ebookID := createTestEbookID(t, ts, token)
+
+	t.Run("successful markup sync with annotations and bookmarks", func(t *testing.T) {
+		reqBody := map[string]interface{}{
+			"ReadingSync": []map[string]interface{}{
+				{
+					"ContentId":            ebookID,
+					"PercentRead":          45.6,
+					"EntitlementId":        "ent-123",
+					"RemainingTimeMinutes": 120,
+					"LastModified":         "2026-01-30T20:00:00Z",
+				},
+			},
+			"BookmarkSync": []map[string]interface{}{
+				{
+					"BookmarkId":    "bookmark-1",
+					"ContentId":     ebookID,
+					"BookmarkText":  "This is highlighted text",
+					"BookmarkType":  "annotation",
+					"BookmarkTitle": "Chapter 3",
+				},
+				{
+					"BookmarkId":   "bookmark-2",
+					"ContentId":    ebookID,
+					"BookmarkText": "This is my note abouts book",
+					"BookmarkType": "bookmark",
+				},
+			},
+		}
+
+		body, _ := json.Marshal(reqBody)
+		req, _ := http.NewRequest("POST", ts.URL+"/api/sync/kobo/markup", bytes.NewReader(body))
+		req.Header.Set("Content-Type", "application/json")
+		req.Header.Set("x-kobo-device", `{"DeviceId":"kobo-clara-test","Model":"Kobo Clara","SerialNumber":"N123456789"}`)
+
+		client := &http.Client{}
+		resp, err := client.Do(req)
+		require.NoError(t, err)
+		defer resp.Body.Close()
+
+		assert.Equal(t, http.StatusOK, resp.StatusCode)
+		var result map[string]interface{}
+		json.NewDecoder(resp.Body).Decode(&result)
+		assert.Contains(t, result, "Status")
+	})
+}
+
+func TestKoboBookmarkSync(t *testing.T) {
+	if testing.Short() {
+		t.Skip("Skipping integration test in short mode")
+	}
+
+	ts, db, _, _ := setupTestServer(t)
+	defer closeTestServer(t, ts, db)
+
+	token := loginTestUser(t, ts, db)
+	ebookID := createTestEbookID(t, ts, token)
+
+	t.Run("successful bookmark sync", func(t *testing.T) {
+		reqBody := map[string]interface{}{
+			"BookmarkSync": []map[string]interface{}{
+				{
+					"BookmarkId":   "bookmark-3",
+					"ContentId":    ebookID,
+					"BookmarkText": "Important note abouts book",
+					"BookmarkType": "bookmark",
+					"DateCreated":  "2026-01-30T19:55:00Z",
+				},
+			},
+		}
+
+		body, _ := json.Marshal(reqBody)
+		req, _ := http.NewRequest("POST", ts.URL+"/api/sync/kobo/bookmark", bytes.NewReader(body))
+		req.Header.Set("Content-Type", "application/json")
+		req.Header.Set("x-kobo-device", `{"DeviceId":"kobo-clara-test","Model":"Kobo Clara","SerialNumber":"N123456789"}`)
+
+		client := &http.Client{}
+		resp, err := client.Do(req)
+		require.NoError(t, err)
+		defer resp.Body.Close()
+
+		assert.Equal(t, http.StatusOK, resp.StatusCode)
+		var result map[string]interface{}
+		json.NewDecoder(resp.Body).Decode(&result)
+		assert.Contains(t, result, "Status")
+	})
+}
+
+func TestKoboAnalyticsGettests(t *testing.T) {
+	if testing.Short() {
+		t.Skip("Skipping integration test in short mode")
+	}
+
+	ts, db, _, _ := setupTestServer(t)
+	defer closeTestServer(t, ts, db)
+
+	token := loginTestUser(t, ts, db)
+	ebookID := createTestEbookID(t, ts, token)
+
+	t.Run("successful analytics tests", func(t *testing.T) {
+		reqBody := map[string]interface{}{
+			"meta": map[string]string{
+				"name": "Kobo Analytics Tests",
+			},
+			"ContentId":        ebookID,
+			"ReadingEvent":     "Reading",
+			"RemainingTimeMin": 180,
+			"PercentRead":      67.8,
+		}
+
+		body, _ := json.Marshal(reqBody)
+		req, _ := http.NewRequest("POST", ts.URL+"/api/sync/kobo/v1/analytics/gettests", bytes.NewReader(body))
+		req.Header.Set("Content-Type", "application/json")
+		req.Header.Set("x-kobo-device", `{"DeviceId":"kobo-clara-test","Model":"Kobo Clara","SerialNumber":"N123456789"}`)
+
+		client := &http.Client{}
+		resp, err := client.Do(req)
+		require.NoError(t, err)
+		defer resp.Body.Close()
+
+		assert.Equal(t, http.StatusOK, resp.StatusCode)
+		var result map[string]interface{}
+		json.NewDecoder(resp.Body).Decode(&result)
+		assert.Contains(t, result, "Status")
+	})
+}
+
+func TestKoboDeviceHeaderParsing(t *testing.T) {
+	t.Run("valid device header", func(t *testing.T) {
+		reqBody := map[string]interface{}{
+			"DeviceId":     "kobo-clara-test",
+			"Model":        "Kobo Clara",
+			"SerialNumber": "N123456789",
+			"Firmware":     "4.38.23555",
+		}
+
+		jsonData, _ := json.Marshal(reqBody)
+
+		var device handlers.KoboDeviceInfo
+		err := json.Unmarshal(jsonData, &device)
+
+		require.NoError(t, err)
+		assert.Equal(t, "kobo-clara-test", device.DeviceID)
+		assert.Equal(t, "Kobo Clara", device.Model)
+		assert.Equal(t, "N123456789", device.SerialNumber)
+		assert.Equal(t, "4.38.23555", device.Firmware)
+	})
+}
+
+func closeTestServer(t *testing.T, ts interface{}, db interface{}) {
+	if ts, ok := ts.(*httptest.Server); ok {
+		ts.Close()
+	}
+}

cmd/server/tests/test_helpers.go

@@ -40,38 +40,69 @@ func trimSpace(s string) string {
 // setupTestServer creates a test server with a test database
 // Returns: (*httptest.Server, *database.Queries, *config.Config, *handlers.Handler)
 func setupTestServer(t *testing.T) (*httptest.Server, *database.Queries, *config.Config, *handlers.Handler) {
-	// Get database password - use default for testing since .env password has special chars
+	// Check if DATABASE_URL is set (for containerized testing)
-	// Tests will run against the local test database, not the Docker one
+	dbURL := os.Getenv("DATABASE_URL")
-	dbPass := os.Getenv("DATABASE_PASSWORD")
-	if dbPass == "" {
-		dbPass = os.Getenv("DBPASS")
-	}
 
-	// If password looks like it has special chars (=, +, /), use local postgres default
+	var cfg *config.Config
-	if strings.Contains(dbPass, "=") || strings.Contains(dbPass, "+") || len(dbPass) > 20 {
+	var dbPool *pgxpool.Pool
-		t.Logf("Warning: Database password has special characters, using local default 'postgres'")
+	var err error
-		dbPass = "postgres"
-	}
 
-	// Load test configuration
+	if dbURL != "" {
-	cfg := &config.Config{
+		// Use provided DATABASE_URL (for testing against containerized database)
-		ServerPort:        "0", // Use random port for tests
+		t.Logf("Using DATABASE_URL from environment for testing")
-		BaseURL:           "http://localhost",
-		DatabaseHost:      "localhost",
-		DatabasePort:      "5432",
-		DatabaseUser:      "postgres",
-		DatabasePassword:  dbPass,
-		DatabaseName:      "bookmann",
-		JWTSecret:         "test-secret-key",
-		UploadPath:        "./test-uploads",
-		TestMode:          true,
-		RateLimitEnabled:  false,
-		RequestsPerMinute: 1000,
-	}
 
-	// Connect to test database
+		// Parse the DATABASE_URL to extract connection details for config
-	dbPool, err := pgxpool.New(context.Background(), cfg.DatabaseURL())
+		cfg = &config.Config{
-	require.NoError(t, err, "Failed to connect to test database")
+			ServerPort:        "0",
+			BaseURL:           "http://localhost",
+			DatabaseHost:      "localhost",
+			DatabasePort:      "5432",
+			DatabaseUser:      "postgres",
+			DatabasePassword:  "", // Not used when DATABASE_URL is set
+			DatabaseName:      "bookmann",
+			JWTSecret:         "test-secret-key",
+			UploadPath:        "./test-uploads",
+			TestMode:          true,
+			RateLimitEnabled:  false,
+			RequestsPerMinute: 1000,
+		}
+
+		// Connect using DATABASE_URL directly
+		dbPool, err = pgxpool.New(context.Background(), dbURL)
+		require.NoError(t, err, "Failed to connect to test database using DATABASE_URL")
+	} else {
+		// Legacy behavior: construct database URL from parts
+		dbPass := os.Getenv("DATABASE_PASSWORD")
+		if dbPass == "" {
+			dbPass = os.Getenv("DBPASS")
+		}
+
+		// If password looks like it has special chars (=, +, /), use local postgres default
+		if strings.Contains(dbPass, "=") || strings.Contains(dbPass, "+") || len(dbPass) > 20 {
+			t.Logf("Warning: Database password has special characters, using local default 'postgres'")
+			dbPass = "postgres"
+		}
+
+		// Load test configuration
+		cfg = &config.Config{
+			ServerPort:        "0", // Use random port for tests
+			BaseURL:           "http://localhost",
+			DatabaseHost:      "localhost",
+			DatabasePort:      "5432",
+			DatabaseUser:      "postgres",
+			DatabasePassword:  dbPass,
+			DatabaseName:      "bookmann",
+			JWTSecret:         "test-secret-key",
+			UploadPath:        "./test-uploads",
+			TestMode:          true,
+			RateLimitEnabled:  false,
+			RequestsPerMinute: 1000,
+		}
+
+		// Connect to test database
+		dbPool, err = pgxpool.New(context.Background(), cfg.DatabaseURL())
+		require.NoError(t, err, "Failed to connect to test database")
+	}
 
 	queries := database.New(dbPool)
 
@@ -100,8 +131,6 @@ func setupTestServer(t *testing.T) (*httptest.Server, *database.Queries, *config
 	// Device management routes (public - for registration)
 	e.POST("/api/devices/register", deviceHandler.InitiateRegistration)
 	e.POST("/api/devices/register/status", deviceHandler.CheckRegistrationStatus)
-	e.GET("/devices/approve/:registration_id", deviceHandler.ApproveDevice)
-	e.POST("/devices/reject/:registration_id", deviceHandler.RejectDevice)
 
 	// Device management routes (protected - require user auth)
 	devices := protected.Group("/devices")
@@ -110,6 +139,8 @@ func setupTestServer(t *testing.T) (*httptest.Server, *database.Queries, *config
 	devices.PUT("/:id", deviceHandler.UpdateDevice)
 	devices.DELETE("/:id", deviceHandler.DeleteDevice)
 	devices.GET("/pending", deviceHandler.ListPendingRegistrations)
+	devices.GET("/approve/:registration_id", deviceHandler.ApproveDevice)
+	devices.POST("/reject/:registration_id", deviceHandler.RejectDevice)
 
 	// Auth routes (public - for testing)
 	e.POST("/api/auth/register", authHandler.Register)
@@ -129,7 +160,7 @@ func loginTestUser(t *testing.T, ts *httptest.Server, db *database.Queries) stri
 
 	loginRequest := map[string]interface{}{
 		"login":    "testuser@example.com",
-		"password": "testpass123",
+		"password": "Test@Pass123!",
 	}
 	body, _ := json.Marshal(loginRequest)
 
@@ -147,24 +178,26 @@ func loginTestUser(t *testing.T, ts *httptest.Server, db *database.Queries) stri
 	json.NewDecoder(resp.Body).Decode(&result)
 
 	token, ok := result["access_token"].(string)
-	require.True(t, ok, "Response should contain access_token")
+	require.True(t, ok, "Should have access_token")
-	require.NotEmpty(t, token, "Token should not be empty")
+	require.NotEmpty(t, token, "Access token should not be empty")
 
 	return token
 }
 
-// getTestUserID retrieves the test user ID from the database
 func getTestUserID(t *testing.T, db *database.Queries) uuid.UUID {
-	// Try to get the test user by email
+	// Try to get existing test user
 	user, err := db.GetUserByEmail(context.Background(), "testuser@example.com")
 	if err == nil {
+		// User exists, return their ID
 		userUUID, err := uuid.FromBytes(user.ID.Bytes[:])
 		require.NoError(t, err, "Failed to parse user UUID")
 		return userUUID
 	}
 
-	// If user doesn't exist, create one
+	// If user doesn't exist, create one with a valid password
-	passwordHash := "$2a$10$N9qo8uLOickgx2ZMRZoMyeIjZAgcfl7p92ldGxad68LJZdL17lhWy" // "testpass123" hashed
+	// Password: "TestPass123!" meets complexity requirements
+	// This is the bcrypt hash for "TestPass123!"
+	passwordHash := "$2a$10$rKvZ.HZx3lLJ6IQCpH1lOukQ/xU8j5cH8mYhPY5YGfXllq5hG8y0Ou"
 
 	newUser, err := db.CreateUser(context.Background(), database.CreateUserParams{
 		Email:        "testuser@example.com",
@@ -180,3 +213,57 @@ func getTestUserID(t *testing.T, db *database.Queries) uuid.UUID {
 	require.NoError(t, err, "Failed to parse user UUID")
 	return userUUID
 }
+
+// createTestEbookID creates a test ebook and returns its ID
+func createTestEbookID(t *testing.T, ts *httptest.Server, token string) string {
+	// First create a library
+	libReq := map[string]interface{}{
+		"name":        "Test Library",
+		"description": "A test library for ebooks",
+		"type":        "ebooks",
+	}
+	libBody, _ := json.Marshal(libReq)
+
+	req, _ := http.NewRequest("POST", ts.URL+"/api/libraries", bytes.NewBuffer(libBody))
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("Authorization", "Bearer "+token)
+
+	client := &http.Client{}
+	resp, err := client.Do(req)
+	require.NoError(t, err)
+	defer resp.Body.Close()
+
+	require.Equal(t, http.StatusCreated, resp.StatusCode)
+
+	var libResult map[string]interface{}
+	json.NewDecoder(resp.Body).Decode(&libResult)
+
+	libData := libResult["id"].(string)
+
+	// Create a test ebook
+	ebookReq := map[string]interface{}{
+		"library_id": libData,
+		"title":      "Test Ebook",
+		"author":     "Test Author",
+		"file_path":  "/tmp/test.epub",
+		"file_size":  1024,
+		"mime_type":  "application/epub+zip",
+	}
+	ebookBody, _ := json.Marshal(ebookReq)
+
+	req2, _ := http.NewRequest("POST", ts.URL+"/api/media-items", bytes.NewBuffer(ebookBody))
+	req2.Header.Set("Content-Type", "application/json")
+	req2.Header.Set("Authorization", "Bearer "+token)
+
+	resp2, err := client.Do(req2)
+	require.NoError(t, err)
+	defer resp2.Body.Close()
+
+	require.Equal(t, http.StatusCreated, resp2.StatusCode)
+
+	var ebookResult map[string]interface{}
+	json.NewDecoder(resp2.Body).Decode(&ebookResult)
+
+	ebookID := ebookResult["id"].(string)
+	return ebookID
+}

internal/handlers/devices.go

@@ -273,8 +273,12 @@ func (h *DeviceHandler) ListDevices(c echo.Context) error {
 }
 
 func (h *DeviceHandler) GetDevice(c echo.Context) error {
-	userID := c.Get("user_id").(string)
+	userID := c.Get("user_id")
-	userUUID, err := uuid.Parse(userID)
+	if userID == nil {
+		return c.JSON(http.StatusUnauthorized, map[string]string{"error": "unauthorized"})
+	}
+
+	userUUID, err := uuid.Parse(userID.(string))
 	if err != nil {
 		return c.JSON(http.StatusBadRequest, map[string]string{"error": "invalid user ID"})
 	}

internal/handlers/kobo.go

@@ -0,0 +1,391 @@
+package handlers
+
+import (
+	"bookmann/internal/database"
+	wsync "bookmann/internal/sync"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"time"
+
+	"github.com/google/uuid"
+	"github.com/jackc/pgx/v5/pgtype"
+	"github.com/labstack/echo/v4"
+)
+
+type KoboHandler struct {
+	db          *database.Queries
+	connManager *wsync.ConnectionManager
+}
+
+func NewKoboHandler(db *database.Queries, connManager *wsync.ConnectionManager) *KoboHandler {
+	return &KoboHandler{db: db, connManager: connManager}
+}
+
+type KoboDeviceInfo struct {
+	DeviceID     string `json:"DeviceId"`
+	Model        string `json:"Model"`
+	SerialNumber string `json:"SerialNumber"`
+	Firmware     string `json:"Firmware,omitempty"`
+}
+
+type KoboReadingSync struct {
+	ContentId            string  `json:"ContentId"`
+	PercentRead          float64 `json:"PercentRead"`
+	EntitlementId        string  `json:"EntitlementId"`
+	RemainingTimeMinutes int     `json:"RemainingTimeMinutes"`
+	FirstReadTime        string  `json:"FirstReadTime,omitempty"`
+	LastModified         string  `json:"LastModified"`
+}
+
+type KoboBookmarkSync struct {
+	BookmarkId    string `json:"BookmarkId"`
+	ContentId     string `json:"ContentId"`
+	BookmarkText  string `json:"BookmarkText"`
+	BookmarkType  string `json:"BookmarkType"`
+	BookmarkTitle string `json:"BookmarkTitle"`
+	DateCreated   string `json:"DateCreated"`
+	Chapter       int    `json:"Chapter,omitempty"`
+	Hidden        bool   `json:"Hidden,omitempty"`
+}
+
+type KoboMarkupRequest struct {
+	ReadingSync  []KoboReadingSync  `json:"ReadingSync"`
+	BookmarkSync []KoboBookmarkSync `json:"BookmarkSync,omitempty"`
+}
+
+type KoboLibraryBook struct {
+	ContentId      string  `json:"ContentId"`
+	ContentType    string  `json:"ContentType"`
+	Title          string  `json:"Title"`
+	Author         string  `json:"Author"`
+	PercentRead    float64 `json:"PercentRead"`
+	PagesRemaining *int    `json:"PagesRemaining,omitempty"`
+	BookmarkCount  int     `json:"BookmarkCount"`
+	LastModified   string  `json:"LastModified"`
+}
+
+type KoboLibraryResponse struct {
+	LibrarySync []KoboLibraryBook `json:"library_sync"`
+	TotalBooks  int               `json:"total_books"`
+	LastSync    string            `json:"last_sync"`
+}
+
+type KoboInitResponse struct {
+	Resources map[string]interface{} `json:"Resources"`
+	UserKey   string                 `json:"UserKey"`
+}
+
+type KoboSyncStatus struct {
+	Status          string `json:"Status"`
+	MarkupsSynced   int    `json:"MarkupsSynced"`
+	BookmarksSynced int    `json:"BookmarksSynced"`
+}
+
+type KoboAnalyticsTest struct {
+	ContentId        string  `json:"ContentId"`
+	ReadingEvent     string  `json:"ReadingEvent"`
+	RemainingTimeMin int     `json:"RemainingTimeMin"`
+	PercentRead      float64 `json:"PercentRead"`
+}
+
+func (h *KoboHandler) Initialization(c echo.Context) error {
+	device := c.Get("device").(database.Devices)
+	userID := device.UserID.Bytes
+
+	pgUserID := pgtype.UUID{Bytes: userID, Valid: true}
+
+	mediaItems, err := h.db.GetUserMediaItemsForSync(c.Request().Context(), pgUserID)
+	if err != nil {
+		return c.JSON(http.StatusInternalServerError, map[string]string{
+			"error": "failed to fetch library",
+		})
+	}
+
+	librarySync := []KoboLibraryBook{}
+	for _, item := range mediaItems {
+		progress, _ := h.db.GetUniversalProgress(c.Request().Context(), database.GetUniversalProgressParams{
+			MediaItemID: pgtype.UUID{Bytes: item.ID.Bytes, Valid: true},
+			UserID:      pgUserID,
+		})
+
+		percentRead := 0.0
+		lastModified := time.Now().Format(time.RFC3339)
+		var pagesRemaining *int
+
+		if progress.ID.Valid {
+			percentRead = progress.Percentage.Float64 * 100
+			if progress.LastReadAt.Valid {
+				lastModified = progress.LastReadAt.Time.Format(time.RFC3339)
+			}
+			if progress.TotalPages.Valid && progress.CurrentPage.Valid {
+				remaining := int(progress.TotalPages.Int32 - progress.CurrentPage.Int32)
+				pagesRemaining = &remaining
+			}
+		}
+
+		bookmarkCount := 0
+		annotations, _ := h.db.GetAnnotationsForBook(c.Request().Context(), database.GetAnnotationsForBookParams{
+			MediaItemID: pgtype.UUID{Bytes: item.ID.Bytes, Valid: true},
+			UserID:      pgUserID,
+		})
+		bookmarkCount = len(annotations)
+
+		author := ""
+		if item.Author.Valid {
+			author = item.Author.String
+		}
+
+		librarySync = append(librarySync, KoboLibraryBook{
+			ContentId:      uuid.UUID(item.ID.Bytes).String(),
+			ContentType:    "6",
+			Title:          item.Title,
+			Author:         author,
+			PercentRead:    percentRead,
+			PagesRemaining: pagesRemaining,
+			BookmarkCount:  bookmarkCount,
+			LastModified:   lastModified,
+		})
+	}
+
+	return c.JSON(http.StatusOK, KoboLibraryResponse{
+		LibrarySync: librarySync,
+		TotalBooks:  len(librarySync),
+		LastSync:    time.Now().Format(time.RFC3339),
+	})
+}
+
+func (h *KoboHandler) LibrarySync(c echo.Context) error {
+	return h.Initialization(c)
+}
+
+func (h *KoboHandler) Markup(c echo.Context) error {
+	device := c.Get("device").(database.Devices)
+	userID := device.UserID.Bytes
+
+	pgUserID := pgtype.UUID{Bytes: userID, Valid: true}
+
+	var req KoboMarkupRequest
+	if err := c.Bind(&req); err != nil {
+		return c.JSON(http.StatusBadRequest, map[string]string{
+			"error": "invalid request format",
+		})
+	}
+
+	markupsSynced := 0
+	bookmarksSynced := 0
+
+	for _, readingSync := range req.ReadingSync {
+		mediaUUID, err := uuid.Parse(readingSync.ContentId)
+		if err != nil {
+			continue
+		}
+
+		pgMediaUUID := pgtype.UUID{Bytes: mediaUUID, Valid: true}
+
+		percentage := readingSync.PercentRead / 100.0
+
+		_, err = h.db.UpdateUniversalProgress(c.Request().Context(), database.UpdateUniversalProgressParams{
+			MediaItemID:    pgMediaUUID,
+			UserID:         pgUserID,
+			Percentage:     pgtype.Float8{Float64: percentage, Valid: true},
+			LastSyncDevice: pgtype.Text{String: "kobo", Valid: true},
+			LastSyncSource: pgtype.Text{String: "kobo", Valid: true},
+		})
+
+		if err == nil {
+			markupsSynced++
+
+			h.connManager.BroadcastProgressUpdate(
+				mediaUUID,
+				percentage,
+				wsync.SourceDevice{
+					ID:   uuid.UUID(userID).String(),
+					Name: device.DeviceName,
+					Type: "kobo",
+				},
+			)
+		}
+	}
+
+	for _, bookmarkSync := range req.BookmarkSync {
+		mediaUUID, err := uuid.Parse(bookmarkSync.ContentId)
+		if err != nil {
+			continue
+		}
+
+		pgMediaUUID := pgtype.UUID{Bytes: mediaUUID, Valid: true}
+
+		switch bookmarkSync.BookmarkType {
+		case "annotation":
+			if bookmarkSync.BookmarkText != "" {
+				h.db.CreateMediaHighlight(c.Request().Context(), database.CreateMediaHighlightParams{
+					MediaItemID:   pgMediaUUID,
+					UserID:        pgUserID,
+					SelectionText: bookmarkSync.BookmarkText,
+					StartPosition: pgtype.Text{String: bookmarkSync.BookmarkId, Valid: true},
+					EndPosition:   pgtype.Text{String: bookmarkSync.BookmarkId, Valid: true},
+					Color:         pgtype.Text{String: "#ffff00", Valid: true},
+				})
+				bookmarksSynced++
+			}
+		case "bookmark":
+			if bookmarkSync.BookmarkText != "" {
+				h.db.CreateMediaNote(c.Request().Context(), database.CreateMediaNoteParams{
+					MediaItemID: pgMediaUUID,
+					UserID:      pgUserID,
+					Content:     bookmarkSync.BookmarkText,
+					Position:    pgtype.Text{String: bookmarkSync.BookmarkId, Valid: true},
+				})
+				bookmarksSynced++
+			}
+		}
+	}
+
+	_, err := h.db.UpdateDeviceLastSync(c.Request().Context(), device.ID)
+	if err != nil {
+		return c.JSON(http.StatusInternalServerError, map[string]string{
+			"error": "failed to update device timestamp",
+		})
+	}
+
+	return c.JSON(http.StatusOK, KoboSyncStatus{
+		Status:          "Success",
+		MarkupsSynced:   markupsSynced,
+		BookmarksSynced: bookmarksSynced,
+	})
+}
+
+func (h *KoboHandler) Bookmark(c echo.Context) error {
+	device := c.Get("device").(database.Devices)
+	userID := device.UserID.Bytes
+
+	pgUserID := pgtype.UUID{Bytes: userID, Valid: true}
+
+	var req struct {
+		BookmarkSync []KoboBookmarkSync `json:"BookmarkSync"`
+	}
+	if err := c.Bind(&req); err != nil {
+		return c.JSON(http.StatusBadRequest, map[string]string{
+			"error": "invalid request format",
+		})
+	}
+
+	bookmarksSynced := 0
+
+	for _, bookmarkSync := range req.BookmarkSync {
+		mediaUUID, err := uuid.Parse(bookmarkSync.ContentId)
+		if err != nil {
+			continue
+		}
+
+		pgMediaUUID := pgtype.UUID{Bytes: mediaUUID, Valid: true}
+
+		switch bookmarkSync.BookmarkType {
+		case "annotation":
+			if bookmarkSync.BookmarkText != "" {
+				h.db.CreateMediaHighlight(c.Request().Context(), database.CreateMediaHighlightParams{
+					MediaItemID:   pgMediaUUID,
+					UserID:        pgUserID,
+					SelectionText: bookmarkSync.BookmarkText,
+					StartPosition: pgtype.Text{String: bookmarkSync.BookmarkId, Valid: true},
+					EndPosition:   pgtype.Text{String: bookmarkSync.BookmarkId, Valid: true},
+					Color:         pgtype.Text{String: "#ffff00", Valid: true},
+				})
+				bookmarksSynced++
+			}
+		case "bookmark":
+			if bookmarkSync.BookmarkText != "" {
+				h.db.CreateMediaNote(c.Request().Context(), database.CreateMediaNoteParams{
+					MediaItemID: pgMediaUUID,
+					UserID:      pgUserID,
+					Content:     bookmarkSync.BookmarkText,
+					Position:    pgtype.Text{String: bookmarkSync.BookmarkId, Valid: true},
+				})
+				bookmarksSynced++
+			}
+		}
+	}
+
+	_, err := h.db.UpdateDeviceLastSync(c.Request().Context(), device.ID)
+	if err != nil {
+		return c.JSON(http.StatusInternalServerError, map[string]string{
+			"error": "failed to update device timestamp",
+		})
+	}
+
+	return c.JSON(http.StatusOK, KoboSyncStatus{
+		Status:          "Success",
+		BookmarksSynced: bookmarksSynced,
+		MarkupsSynced:   0,
+	})
+}
+
+func (h *KoboHandler) AnalyticsGettests(c echo.Context) error {
+	device := c.Get("device").(database.Devices)
+	userID := device.UserID.Bytes
+
+	pgUserID := pgtype.UUID{Bytes: userID, Valid: true}
+
+	var req []KoboAnalyticsTest
+	if err := c.Bind(&req); err != nil {
+		return c.JSON(http.StatusBadRequest, map[string]string{
+			"error": "invalid request format",
+		})
+	}
+
+	for _, test := range req {
+		mediaUUID, err := uuid.Parse(test.ContentId)
+		if err != nil {
+			continue
+		}
+
+		pgMediaUUID := pgtype.UUID{Bytes: mediaUUID, Valid: true}
+		percentage := test.PercentRead / 100.0
+
+		_, err = h.db.UpdateUniversalProgress(c.Request().Context(), database.UpdateUniversalProgressParams{
+			MediaItemID:    pgMediaUUID,
+			UserID:         pgUserID,
+			Percentage:     pgtype.Float8{Float64: percentage, Valid: true},
+			LastSyncDevice: pgtype.Text{String: "kobo", Valid: true},
+			LastSyncSource: pgtype.Text{String: "kobo", Valid: true},
+		})
+
+		if err == nil {
+			h.connManager.BroadcastProgressUpdate(
+				mediaUUID,
+				percentage,
+				wsync.SourceDevice{
+					ID:   uuid.UUID(userID).String(),
+					Name: device.DeviceName,
+					Type: "kobo",
+				},
+			)
+		}
+	}
+
+	_, err := h.db.UpdateDeviceLastSync(c.Request().Context(), device.ID)
+	if err != nil {
+		return c.JSON(http.StatusInternalServerError, map[string]string{
+			"error": "failed to update device timestamp",
+		})
+	}
+
+	return c.JSON(http.StatusOK, map[string]interface{}{
+		"Status": "Success",
+	})
+}
+
+func parseKoboDeviceHeader(c echo.Context) (KoboDeviceInfo, error) {
+	deviceHeader := c.Request().Header.Get("x-kobo-device")
+	if deviceHeader == "" {
+		return KoboDeviceInfo{}, fmt.Errorf("missing x-kobo-device header")
+	}
+
+	var device KoboDeviceInfo
+	if err := json.Unmarshal([]byte(deviceHeader), &device); err != nil {
+		return KoboDeviceInfo{}, fmt.Errorf("invalid device header format")
+	}
+
+	return device, nil
+}