Merge pull request #2141 from booklore-app/develop

Merge develop into master for release

Author: acx10

booklore-api/src/main/java/com/adityachandel/booklore/controller/KoboController.java

@@ -6,7 +6,7 @@
 import com.adityachandel.booklore.model.dto.kobo.KoboReadingStateWrapper;
 import com.adityachandel.booklore.model.dto.kobo.KoboResources;
 import com.adityachandel.booklore.model.dto.kobo.KoboTestResponse;
-import com.adityachandel.booklore.service.*;
+import com.adityachandel.booklore.service.ShelfService;
 import com.adityachandel.booklore.service.book.BookDownloadService;
 import com.adityachandel.booklore.service.book.BookService;
 import com.adityachandel.booklore.service.kobo.*;
@@ -70,53 +70,73 @@ public ResponseEntity<?> syncLibrary(@AuthenticationPrincipal BookLoreUser user)
         return koboLibrarySyncService.syncLibrary(user, token);
     }
 
-    @Operation(summary = "Get book thumbnail", description = "Retrieve the thumbnail image for a book.")
+    @Operation(summary = "Get book thumbnail (versioned)", description = "Retrieve the thumbnail image for a local book with cache-busting version.")
+    @ApiResponse(responseCode = "200", description = "Thumbnail returned successfully")
+    @GetMapping("/v1/books/{imageId}/{version}/thumbnail/{width}/{height}/false/image.jpg")
+    public ResponseEntity<Resource> getVersionedThumbnail(
+            @Parameter(description = "Book ID") @PathVariable String imageId,
+            @Parameter(description = "Cover version (timestamp)") @PathVariable String version,
+            @Parameter(description = "Width of the thumbnail") @PathVariable int width,
+            @Parameter(description = "Height of the thumbnail") @PathVariable int height) {
+        return koboThumbnailService.getThumbnail(imageId);
+    }
+
+    @Operation(summary = "Get book thumbnail", description = "Retrieve the thumbnail image for a Kobo store book.")
     @ApiResponse(responseCode = "200", description = "Thumbnail returned successfully")
     @GetMapping("/v1/books/{imageId}/thumbnail/{width}/{height}/false/image.jpg")
     public ResponseEntity<Resource> getThumbnail(
             @Parameter(description = "Image ID") @PathVariable String imageId,
             @Parameter(description = "Width of the thumbnail") @PathVariable int width,
             @Parameter(description = "Height of the thumbnail") @PathVariable int height) {
-
-        if (StringUtils.isNumeric(imageId)) {
-            return koboThumbnailService.getThumbnail(Long.valueOf(imageId));
+        if (imageId.startsWith("BL-")) {
+            return koboThumbnailService.getThumbnail(imageId);
         } else {
-            String cdnUrl = String.format("https://cdn.kobo.com/book-images/%s/%d/%d/image.jpg", imageId, width, height);
+            String cdnUrl = String.format("https://cdn.kobo.com/book-images/%s/%d/%d/false/image.jpg", imageId, width, height);
             return koboServerProxy.proxyExternalUrl(cdnUrl);
         }
     }
 
-    @Operation(summary = "Get greyscale book thumbnail", description = "Retrieve a greyscale thumbnail image for a book.")
+    @Operation(summary = "Get greyscale book thumbnail (versioned)", description = "Retrieve a greyscale thumbnail for a local book with cache-busting version.")
     @ApiResponse(responseCode = "200", description = "Greyscale thumbnail returned successfully")
-    @GetMapping("/v1/books/{bookId}/thumbnail/{width}/{height}/{quality}/{isGreyscale}/image.jpg")
-    public ResponseEntity<Resource> getGreyThumbnail(
-            @Parameter(description = "Book ID") @PathVariable String bookId,
+    @GetMapping("/v1/books/{imageId}/{version}/thumbnail/{width}/{height}/{quality}/{isGreyscale}/image.jpg")
+    public ResponseEntity<Resource> getVersionedGreyThumbnail(
+            @Parameter(description = "Book ID") @PathVariable String imageId,
+            @Parameter(description = "Cover version (timestamp)") @PathVariable String version,
             @Parameter(description = "Width of the thumbnail") @PathVariable int width,
             @Parameter(description = "Height of the thumbnail") @PathVariable int height,
             @Parameter(description = "Quality of the thumbnail") @PathVariable int quality,
             @Parameter(description = "Is greyscale") @PathVariable boolean isGreyscale) {
+        return koboThumbnailService.getThumbnail(imageId);
+    }
 
-        if (StringUtils.isNumeric(bookId)) {
-            return koboThumbnailService.getThumbnail(Long.valueOf(bookId));
+    @Operation(summary = "Get greyscale book thumbnail", description = "Retrieve a greyscale thumbnail image for a Kobo store book.")
+    @ApiResponse(responseCode = "200", description = "Greyscale thumbnail returned successfully")
+    @GetMapping("/v1/books/{imageId}/thumbnail/{width}/{height}/{quality}/{isGreyscale}/image.jpg")
+    public ResponseEntity<Resource> getGreyThumbnail(
+            @Parameter(description = "Image ID") @PathVariable String imageId,
+            @Parameter(description = "Width of the thumbnail") @PathVariable int width,
+            @Parameter(description = "Height of the thumbnail") @PathVariable int height,
+            @Parameter(description = "Quality of the thumbnail") @PathVariable int quality,
+            @Parameter(description = "Is greyscale") @PathVariable boolean isGreyscale) {
+        if (imageId.startsWith("BL-")) {
+            return koboThumbnailService.getThumbnail(imageId);
         } else {
-            String cdnUrl = String.format("https://cdn.kobo.com/book-images/%s/%d/%d/%d/%b/image.jpg", bookId, width, height, quality, isGreyscale);
+            String cdnUrl = String.format("https://cdn.kobo.com/book-images/%s/%d/%d/%d/%b/image.jpg", imageId, width, height, quality, isGreyscale);
             return koboServerProxy.proxyExternalUrl(cdnUrl);
         }
     }
 
     @Operation(summary = "Authenticate Kobo device", description = "Authenticate a Kobo device.")
     @ApiResponse(responseCode = "200", description = "Device authenticated successfully")
     @PostMapping("/v1/auth/device")
-    public ResponseEntity<KoboAuthentication> authenticateDevice(
-            @Parameter(description = "Authentication request body") @RequestBody JsonNode body) {
+    public ResponseEntity<KoboAuthentication> authenticateDevice(@Parameter(description = "Authentication request body") @RequestBody JsonNode body) {
         return koboDeviceAuthService.authenticateDevice(body);
     }
 
     @Operation(summary = "Get book metadata", description = "Retrieve metadata for a book in the Kobo library.")
     @ApiResponse(responseCode = "200", description = "Metadata returned successfully")
     @GetMapping("/v1/library/{bookId}/metadata")
-    public ResponseEntity<?> getBookMetadata(
-            @Parameter(description = "Book ID") @PathVariable String bookId) {
+    public ResponseEntity<?> getBookMetadata(@Parameter(description = "Book ID") @PathVariable String bookId) {
         if (StringUtils.isNumeric(bookId)) {
             return ResponseEntity.ok(List.of(koboEntitlementService.getMetadataForBook(Long.parseLong(bookId), token)));
         } else {
@@ -127,8 +147,7 @@ public ResponseEntity<?> getBookMetadata(
     @Operation(summary = "Get reading state", description = "Retrieve the reading state for a book.")
     @ApiResponse(responseCode = "200", description = "Reading state returned successfully")
     @GetMapping("/v1/library/{bookId}/state")
-    public ResponseEntity<?> getState(
-            @Parameter(description = "Book ID") @PathVariable String bookId) {
+    public ResponseEntity<?> getState(@Parameter(description = "Book ID") @PathVariable String bookId) {
         if (StringUtils.isNumeric(bookId)) {
             return ResponseEntity.ok(koboReadingStateService.getReadingState(bookId));
         } else {
@@ -152,8 +171,7 @@ public ResponseEntity<?> updateState(
     @Operation(summary = "Get Kobo test analytics", description = "Get test analytics for Kobo.")
     @ApiResponse(responseCode = "200", description = "Test analytics returned successfully")
     @PostMapping("/v1/analytics/gettests")
-    public ResponseEntity<?> getTests(
-            @Parameter(description = "Test analytics request body") @RequestBody Object body) {
+    public ResponseEntity<?> getTests(@Parameter(description = "Test analytics request body") @RequestBody Object body) {
         return ResponseEntity.ok(KoboTestResponse.builder()
                 .result("Success")
                 .testKey(RandomStringUtils.secure().nextAlphanumeric(24))
@@ -163,8 +181,7 @@ public ResponseEntity<?> getTests(
     @Operation(summary = "Download Kobo book", description = "Download a book from the Kobo library.")
     @ApiResponse(responseCode = "200", description = "Book downloaded successfully")
     @GetMapping("/v1/books/{bookId}/download")
-    public void downloadBook(
-            @Parameter(description = "Book ID") @PathVariable String bookId, HttpServletResponse response) {
+    public void downloadBook(@Parameter(description = "Book ID") @PathVariable String bookId, HttpServletResponse response) {
         if (StringUtils.isNumeric(bookId)) {
             bookDownloadService.downloadKoboBook(Long.parseLong(bookId), response);
         } else {
@@ -175,8 +192,7 @@ public void downloadBook(
     @Operation(summary = "Delete book from Kobo library", description = "Delete a book from the user's Kobo library.")
     @ApiResponse(responseCode = "200", description = "Book deleted successfully")
     @DeleteMapping("/v1/library/{bookId}")
-    public ResponseEntity<?> deleteBookFromLibrary(
-            @Parameter(description = "Book ID") @PathVariable String bookId) {
+    public ResponseEntity<?> deleteBookFromLibrary(@Parameter(description = "Book ID") @PathVariable String bookId) {
         if (StringUtils.isNumeric(bookId)) {
             Shelf userKoboShelf = shelfService.getUserKoboShelf();
             if (userKoboShelf != null) {

booklore-api/src/main/java/com/adityachandel/booklore/convertor/BookRecommendationIdsListConverter.java

@@ -43,8 +43,8 @@ public Set<BookRecommendationLite> convertToEntityAttribute(String json) {
         try {
             return objectMapper.readValue(json, SET_TYPE_REF);
         } catch (Exception e) {
-            log.error("Failed to convert JSON string to BookRecommendation set: {}", json, e);
-            throw new RuntimeException("Error converting JSON to BookRecommendation list", e);
+            log.error("Corrupted similar_books_json found in database. Returning empty set. JSON: {}", json, e);
+            return Set.of();
         }
     }
 }

booklore-api/src/main/java/com/adityachandel/booklore/crons/CronService.java

@@ -3,6 +3,7 @@
 import com.adityachandel.booklore.config.AppProperties;
 import com.adityachandel.booklore.model.dto.BookloreTelemetry;
 import com.adityachandel.booklore.model.dto.InstallationPing;
+import com.adityachandel.booklore.model.dto.settings.AppSettings;
 import com.adityachandel.booklore.service.TelemetryService;
 import com.adityachandel.booklore.service.appsettings.AppSettingService;
 import jakarta.annotation.PostConstruct;
@@ -23,6 +24,7 @@ public class CronService {
 
     private static final String LAST_TELEMETRY_KEY = "last_telemetry_sent";
     private static final String LAST_PING_KEY = "last_ping_sent";
+    private static final String LAST_PING_APP_VERSION_KEY = "last_ping_app_version";
     private static final long INTERVAL_HOURS = 24;
 
     private final AppProperties appProperties;
@@ -38,44 +40,45 @@ public void initScheduledTasks() {
 
     @Scheduled(fixedDelay = 24, timeUnit = TimeUnit.HOURS, initialDelay = 24)
     public void sendTelemetryData() {
-        if (appSettingService.getAppSettings().isTelemetryEnabled()) {
-            try {
-                String url = appProperties.getTelemetry().getBaseUrl() + "/api/v1/ingest";
-                BookloreTelemetry telemetry = telemetryService.collectTelemetry();
-                postData(url, telemetry);
+        AppSettings settings = appSettingService.getAppSettings();
+        if (settings != null && settings.isTelemetryEnabled()) {
+            String url = appProperties.getTelemetry().getBaseUrl() + "/api/v1/ingest";
+            BookloreTelemetry telemetry = telemetryService.collectTelemetry();
+            if (postData(url, telemetry)) {
                 appSettingService.saveSetting(LAST_TELEMETRY_KEY, Instant.now().toString());
-            } catch (Exception e) {
-                log.warn("Failed to up stats: {}", e.getMessage());
             }
         }
     }
 
-    @Scheduled(fixedDelay = 24, timeUnit = TimeUnit.HOURS, initialDelay = 10)
+    @Scheduled(fixedDelay = 24, timeUnit = TimeUnit.HOURS, initialDelay = 12)
     public void sendPing() {
-        try {
-            String url = appProperties.getTelemetry().getBaseUrl() + "/api/v1/heartbeat";
-            InstallationPing ping = telemetryService.getInstallationPing();
-            postData(url, ping);
+        String url = appProperties.getTelemetry().getBaseUrl() + "/api/v1/heartbeat";
+        InstallationPing ping = telemetryService.getInstallationPing();
+        if (ping != null && postData(url, ping)) {
             appSettingService.saveSetting(LAST_PING_KEY, Instant.now().toString());
-        } catch (Exception e) {
-            log.warn("Failed to up ping: {}", e.getMessage());
+            appSettingService.saveSetting(LAST_PING_APP_VERSION_KEY, ping.getAppVersion());
         }
     }
 
-    private void postData(String url, Object body) {
-        restClient.post()
-                .uri(url)
-                .body(body)
-                .retrieve()
-                .body(String.class);
+    protected boolean postData(String url, Object body) {
+        try {
+            restClient.post()
+                    .uri(url)
+                    .body(body)
+                    .retrieve()
+                    .body(String.class);
+            return true;
+        } catch (Exception ex) {
+            log.debug("POST request to URL: {}, Message: {}", url, ex.getMessage());
+            return false;
+        }
     }
 
-
     private void checkAndRunTelemetry() {
-        if (!appSettingService.getAppSettings().isTelemetryEnabled()) {
+        AppSettings settings = appSettingService.getAppSettings();
+        if (settings == null || !settings.isTelemetryEnabled()) {
             return;
         }
-
         String lastRunStr = appSettingService.getSettingValue(LAST_TELEMETRY_KEY);
         if (shouldRunTask(lastRunStr)) {
             log.info("Running stats on startup (last run: {})", lastRunStr);
@@ -85,6 +88,11 @@ private void checkAndRunTelemetry() {
 
     private void checkAndRunPing() {
         String lastRunStr = appSettingService.getSettingValue(LAST_PING_KEY);
+        if (hasAppVersionChanged()) {
+            log.info("App version changed, sending immediate ping");
+            sendPing();
+            return;
+        }
         if (shouldRunTask(lastRunStr)) {
             log.info("Running ping on startup (last run: {})", lastRunStr);
             sendPing();
@@ -96,7 +104,7 @@ private void checkAndRunPing() {
      * Returns false for new installations (no last run recorded) to follow normal schedule.
      * Returns true if more than INTERVAL_HOURS have passed since the last run,
      * preventing data gaps when the server restarts close to scheduled execution time.
-     *
+     * <p>
      * Example: Telemetry normally runs at 2:00 AM daily. If the server restarts at 1:55 AM,
      * the scheduled task would reset and not run until 2:00 AM the next day (48 hours later).
      * This method checks if 24+ hours have passed since the last run and executes immediately
@@ -115,4 +123,18 @@ private boolean shouldRunTask(String lastRunStr) {
             return false;
         }
     }
+
+    /**
+     * Checks if the app version has changed since the last ping.
+     * Returns true if this is an established installation with a version change.
+     */
+    private boolean hasAppVersionChanged() {
+        String lastPingVersion = appSettingService.getSettingValue(LAST_PING_APP_VERSION_KEY);
+        InstallationPing ping = telemetryService.getInstallationPing();
+        String currentVersion = ping != null ? ping.getAppVersion() : null;
+        if (lastPingVersion == null || lastPingVersion.isEmpty() || currentVersion == null) {
+            return false;
+        }
+        return !lastPingVersion.equals(currentVersion);
+    }
 }

booklore-api/src/main/java/com/adityachandel/booklore/model/dto/BookRecommendationLite.java

@@ -1,14 +1,12 @@
 package com.adityachandel.booklore.model.dto;
 
-import lombok.AllArgsConstructor;
-import lombok.Getter;
-import lombok.NoArgsConstructor;
-import lombok.Setter;
+import lombok.*;
 
 @Getter
 @Setter
 @AllArgsConstructor
 @NoArgsConstructor
+@EqualsAndHashCode
 public class BookRecommendationLite {
     private long b; // bookId
     private double s; // similarityScore

booklore-api/src/main/java/com/adityachandel/booklore/model/dto/kobo/BookEntitlement.java

@@ -19,7 +19,8 @@ public class BookEntitlement {
     private ActivePeriod activePeriod;
 
     @JsonProperty("IsRemoved")
-    private boolean isRemoved;
+    @Builder.Default
+    private Boolean removed = false;
 
     private String status;
 
@@ -31,15 +32,15 @@ public class BookEntitlement {
 
     @JsonProperty("IsHiddenFromArchive")
     @Builder.Default
-    private boolean isHiddenFromArchive = false;
+    private boolean hiddenFromArchive = false;
 
     private String id;
     private String created;
     private String lastModified;
 
     @JsonProperty("IsLocked")
     @Builder.Default
-    private boolean isLocked = false;
+    private boolean locked = false;
 
     @Builder.Default
     private String originCategory = "Imported";

booklore-api/src/main/java/com/adityachandel/booklore/model/dto/kobo/ChangedProductMetadata.java

@@ -0,0 +1,19 @@
+package com.adityachandel.booklore.model.dto.kobo;
+
+import com.fasterxml.jackson.annotation.JsonInclude;
+import com.fasterxml.jackson.databind.PropertyNamingStrategies;
+import com.fasterxml.jackson.databind.annotation.JsonNaming;
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+@Data
+@NoArgsConstructor
+@AllArgsConstructor
+@Builder
+@JsonNaming(PropertyNamingStrategies.UpperCamelCaseStrategy.class)
+@JsonInclude(JsonInclude.Include.NON_NULL)
+public class ChangedProductMetadata implements Entitlement {
+    private BookEntitlementContainer changedProductMetadata;
+}

booklore-api/src/main/java/com/adityachandel/booklore/model/dto/kobo/KoboBookMetadata.java

@@ -18,7 +18,6 @@
 @AllArgsConstructor
 @JsonNaming(PropertyNamingStrategies.UpperCamelCaseStrategy.class)
 @Builder
-@JsonInclude(JsonInclude.Include.NON_NULL)
 public class KoboBookMetadata {
     private String crossRevisionId;
     private String revisionId;
@@ -29,13 +28,13 @@ public class KoboBookMetadata {
     private String language = "en";
 
     private String isbn;
-    private String genre;
+    private String genre = "00000000-0000-0000-0000-000000000001";
     private String slug;
     private String coverImageId;
 
     @JsonProperty("IsSocialEnabled")
     @Builder.Default
-    private boolean isSocialEnabled = false;
+    private boolean socialEnabled = true;
 
     private String workId;
 
@@ -44,14 +43,14 @@ public class KoboBookMetadata {
 
     @JsonProperty("IsPreOrder")
     @Builder.Default
-    private boolean isPreOrder = false;
+    private boolean preOrder = false;
 
     @Builder.Default
     private List<ContributorRole> contributorRoles = new ArrayList<>();
 
     @JsonProperty("IsInternetArchive")
     @Builder.Default
-    private boolean isInternetArchive = false;
+    private boolean internetArchive = false;
 
     private String entitlementId;
     private String title;
@@ -81,7 +80,7 @@ public class KoboBookMetadata {
 
     @JsonProperty("IsEligibleForKoboLove")
     @Builder.Default
-    private boolean isEligibleForKoboLove = false;
+    private boolean eligibleForKoboLove = false;
 
     @Builder.Default
     private Map<String, String> phoneticPronunciations = Map.of();