feat: Send optional document metadata with KOSync progress uploads (#1820)

lib/KOReaderSync/KOReaderCredentialStore.cpp

@@ -14,6 +14,7 @@ void KOReaderCredentialStore::toJson(JsonDocument& doc) const {
   doc["password_obf"] = obfuscation::obfuscateToBase64(getPassword());
   doc["serverUrl"] = getServerUrl();
   doc["matchMethod"] = static_cast<uint8_t>(getMatchMethod());
+  doc["sendMetadata"] = getSendMetadata();
 }
 
 bool KOReaderCredentialStore::fromJson(JsonVariantConst doc) {
@@ -32,6 +33,7 @@ bool KOReaderCredentialStore::fromJson(JsonVariantConst doc) {
     LOG_DBG("KRS", "Invalid matchMethod %u in JSON, resetting to FILENAME", method);
     setMatchMethod(DocumentMatchMethod::FILENAME);
   }
+  setSendMetadata(doc["sendMetadata"] | false);
 
   if (needsResave) {
     LOG_DBG("KRS", "Resaved KOReader credentials to update format");
@@ -98,3 +100,8 @@ void KOReaderCredentialStore::setMatchMethod(DocumentMatchMethod method) {
   matchMethod = method;
   LOG_DBG("KRS", "Set match method: %s", method == DocumentMatchMethod::FILENAME ? "Filename" : "Binary");
 }
+
+void KOReaderCredentialStore::setSendMetadata(bool enabled) {
+  sendMetadata = enabled;
+  LOG_DBG("KRS", "Set send metadata: %s", enabled ? "true" : "false");
+}

lib/KOReaderSync/KOReaderCredentialStore.h

@@ -24,6 +24,7 @@ class KOReaderCredentialStore : public PersistableStore<KOReaderCredentialStore>
   std::string password;
   std::string serverUrl;                                            // Custom sync server URL (empty = default)
   DocumentMatchMethod matchMethod = DocumentMatchMethod::FILENAME;  // Default to filename for compatibility
+  bool sendMetadata = false;                                        // Send document metadata with progress sync
 
   // Private constructor for singleton
   KOReaderCredentialStore() = default;
@@ -60,6 +61,10 @@ class KOReaderCredentialStore : public PersistableStore<KOReaderCredentialStore>
   // Document matching method
   void setMatchMethod(DocumentMatchMethod method);
   DocumentMatchMethod getMatchMethod() const { return matchMethod; }
+
+  // Send metadata setting
+  void setSendMetadata(bool enabled);
+  bool getSendMetadata() const { return sendMetadata; }
 };
 
 // Helper macro to access credential store

lib/KOReaderSync/KOReaderSyncClient.cpp

@@ -148,6 +148,12 @@ KOReaderSyncClient::Error KOReaderSyncClient::updateProgress(const KOReaderProgr
   // Build JSON body
   JsonDocument doc;
   doc["document"] = progress.document;
+  if (progress.metadata.has_value()) {
+    auto meta = doc["metadata"].to<JsonObject>();
+    meta["filename"] = progress.metadata->filename;
+    meta["title"] = progress.metadata->title;
+    meta["authors"] = progress.metadata->authors;
+  }
   doc["progress"] = progress.progress;
   doc["percentage"] = progress.percentage;
   doc["device"] = DEVICE_NAME;

lib/KOReaderSync/KOReaderSyncClient.h

@@ -1,16 +1,30 @@
 #pragma once
+#include <cstdint>
+#include <optional>
 #include <string>
 
+/**
+ * Optional document metadata sent alongside progress sync requests.
+ * Mirrors the metadata object added in KOReader PR #15306.
+ * The official sync server ignores this field; custom servers may use it.
+ */
+struct KOReaderMetadata {
+  std::string filename;  // e.g. "my_book.epub"
+  std::string title;     // Document title from EPUB metadata
+  std::string authors;   // Author(s) from EPUB metadata
+};
+
 /**
  * Progress data from KOReader sync server.
  */
 struct KOReaderProgress {
-  std::string document;  // Document hash
-  std::string progress;  // XPath-like progress string
-  float percentage;      // Progress percentage (0.0 to 1.0)
-  std::string device;    // Device name
-  std::string deviceId;  // Device ID
-  int64_t timestamp;     // Unix timestamp of last update
+  std::string document;                      // Document hash
+  std::string progress;                      // XPath-like progress string
+  float percentage;                          // Progress percentage (0.0 to 1.0)
+  std::string device;                        // Device name
+  std::string deviceId;                      // Device ID
+  int64_t timestamp;                         // Unix timestamp of last update
+  std::optional<KOReaderMetadata> metadata;  // Optional document metadata
 };
 
 /**