Sync Library Interface & SyncAPIs (#12)

* Configure the gradle for the syncengine

* Define a first draft of the SynchronizationClient

* Create mutations-definitions module

* Use Local and Remote mutation types

* Add needed details to SynchronizationClient's interface

* Crreate SynchronizationClientImpl

* Create GetMutationsRequest and PostMutationsRequest

* Add ktor

* Fill in the main details of SynchronizationClientImpl

* Extract MutationsResponse to a separate file

* Fill in GetMutationsRequest's details

* Fill in the details of PostMutationsRequest

* Cteate HttpClientFactory

* Call API requests in SynchronizationClientImpl

* Provide a temporary SynchronizationClientIntegrationTest

* Add ketmit to syncengine

* Add exhastive loggings

* Log errors in mutations APIs requests

* Fix an issue in preparing local mutations to push

* Add a test for posting mutations to the integration test as well

* Ignore all SynchronizationClientIntegrationTest tests

* Refactor some stuff in the requests

* Deliver explicit failure responses

* Add HttpClientFactory.ios.kt

Author: mohannad-hassan

gradle/libs.versions.toml

@@ -1,13 +1,15 @@
 [versions]
 agp = "8.11.0"
 kotlin = "2.2.0"
+kotlinx-serialization = "1.6.3"
 kermit = "2.0.0"
 
 maven-publish = "0.33.0"
 
 compose = "2025.06.01"
 coroutines = "1.10.2"
 sqldelight = "2.1.0"
+ktor = "2.3.12"
 
 # Android configuration
 android-compile-sdk = "35"
@@ -35,6 +37,17 @@ sqldelight-android-driver = { module = "app.cash.sqldelight:android-driver", ver
 sqldelight-native-driver = { module = "app.cash.sqldelight:native-driver", version.ref = "sqldelight" }
 sqldelight-sqlite-driver = { module = "app.cash.sqldelight:sqlite-driver", version.ref = "sqldelight" }
 
+# Ktor dependencies
+ktor-client-core = { module = "io.ktor:ktor-client-core", version.ref = "ktor" }
+ktor-client-content-negotiation = { module = "io.ktor:ktor-client-content-negotiation", version.ref = "ktor" }
+ktor-client-logging = { module = "io.ktor:ktor-client-logging", version.ref = "ktor" }
+ktor-client-okhttp = { module = "io.ktor:ktor-client-okhttp", version.ref = "ktor" }
+ktor-client-darwin = { module = "io.ktor:ktor-client-darwin", version.ref = "ktor" }
+ktor-serialization-json = { module = "io.ktor:ktor-serialization-kotlinx-json", version.ref = "ktor" }
+
+# Kotlin Serialization
+kotlinx-serialization-json = { module = "org.jetbrains.kotlinx:kotlinx-serialization-json", version.ref = "kotlinx-serialization" }
+
 compose-bom = { module = "androidx.compose:compose-bom", version.ref = "compose" }
 compose-foundation = { module = "androidx.compose.foundation:foundation" }
 compose-animation = { module = "androidx.compose.animation:animation" }
@@ -50,5 +63,6 @@ android-application = { id = "com.android.application", version.ref = "agp" }
 kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }
 kotlin-compose = { id = "org.jetbrains.kotlin.plugin.compose", version.ref = "kotlin" }
 kotlin-multiplatform = { id = "org.jetbrains.kotlin.multiplatform", version.ref = "kotlin" }
+kotlin-serialization = { id = "org.jetbrains.kotlin.plugin.serialization", version.ref = "kotlin" }
 sqldelight = { id = "app.cash.sqldelight", version.ref = "sqldelight" }
 vanniktech-maven-publish = { id = "com.vanniktech.maven.publish", version.ref = "maven-publish" }

mutations-definitions/build.gradle.kts

@@ -0,0 +1,75 @@
+import org.jetbrains.kotlin.gradle.dsl.JvmTarget
+
+plugins {
+   alias(libs.plugins.kotlin.multiplatform)
+   alias(libs.plugins.android.library)
+   alias(libs.plugins.vanniktech.maven.publish)
+}
+
+kotlin {
+   iosX64()
+   iosArm64()
+   iosSimulatorArm64()
+
+   androidTarget {
+      publishLibraryVariants("release")
+      compilerOptions {
+         jvmTarget.set(JvmTarget.JVM_17)
+      }
+   }
+
+   sourceSets {
+      val commonMain by getting {
+         dependencies {
+            implementation(libs.kotlinx.coroutines.core)
+         }
+      }
+
+      val commonTest by getting {
+         dependencies {
+            implementation(libs.kotlin.test)
+         }
+      }
+   }
+   // don't show warnings for expect/actual classes
+   targets.configureEach {
+      compilations.configureEach {
+         compileTaskProvider.get().compilerOptions {
+            freeCompilerArgs.add("-Xexpect-actual-classes")
+         }
+      }
+   }
+}
+
+android {
+   namespace = "com.quran.shared.mutations"
+   compileSdk = libs.versions.android.compile.sdk.get().toInt()
+
+   defaultConfig {
+      minSdk = libs.versions.android.min.sdk.get().toInt()
+   }
+
+   compileOptions {
+      sourceCompatibility = JavaVersion.valueOf("VERSION_${libs.versions.android.java.version.get()}")
+      targetCompatibility = JavaVersion.valueOf("VERSION_${libs.versions.android.java.version.get()}")
+   }
+
+   testOptions {
+      unitTests {
+         isIncludeAndroidResources = true
+      }
+   }
+}
+
+mavenPublishing {
+   signAllPublications()
+   coordinates(libs.versions.project.group.get(), "syncengine", libs.versions.project.version.get())
+
+   pom {
+      name = "Quran.com Sync Engine"
+      description = "A library for synchronizing data with Quran.com"
+      inceptionYear = "2025"
+      url = "https://github.com/quran/syncengine"
+   }
+}
+

mutations-definitions/src/commonMain/kotlin/com/quran/shared/mutations/MutationType.kt

@@ -0,0 +1,11 @@
+package com.quran.shared.mutations
+
+enum class Mutation {
+    CREATED,
+    DELETED,
+    MODIFIED
+}
+
+class LocalModelMutation<Model>(val model: Model, val remoteID: String?, val localID: String, val mutation: Mutation)
+
+class RemoteModelMutation<Model>(val model: Model, val remoteID: String, val mutation: Mutation)

persistence/src/commonMain/kotlin/com/quran/shared/persistence/repository/PageBookmarksRepositoryImpl.kt

@@ -6,7 +6,6 @@ import com.quran.shared.persistence.QuranDatabase
 import com.quran.shared.persistence.model.PageBookmark
 import com.quran.shared.persistence.model.PageBookmarkMutation
 import com.quran.shared.persistence.model.PageBookmarkMutationType
-import com.quran.shared.persistence.repository.toBookmarkMutation
 import kotlinx.coroutines.flow.Flow
 import kotlinx.coroutines.flow.map
 import kotlinx.coroutines.withContext

settings.gradle.kts

@@ -21,3 +21,4 @@ include(":syncengine")
 include(":persistence")
 include(":umbrella")
 include(":demo:android")
+include(":mutations-definitions")

syncengine/build.gradle.kts

@@ -1,33 +1,102 @@
 import com.vanniktech.maven.publish.SonatypeHost
+import org.jetbrains.kotlin.gradle.dsl.JvmTarget
 
 plugins {
    alias(libs.plugins.kotlin.multiplatform)
+   alias(libs.plugins.kotlin.serialization)
+   alias(libs.plugins.android.library)
    alias(libs.plugins.vanniktech.maven.publish)
 }
 
 kotlin {
-   jvm()
    iosX64()
    iosArm64()
    iosSimulatorArm64()
 
+   androidTarget {
+      publishLibraryVariants("release")
+      compilerOptions {
+         jvmTarget.set(JvmTarget.JVM_17)
+      }
+   }
+
    sourceSets {
       val commonMain by getting {
          dependencies {
+            implementation(libs.kotlinx.coroutines.core)
+            implementation(libs.kotlinx.serialization.json)
+            implementation(libs.ktor.client.core)
+            implementation(libs.ktor.client.content.negotiation)
+            implementation(libs.ktor.client.logging)
+            implementation(libs.ktor.serialization.json)
+            implementation(libs.kermit)
+         }
+      }
+
+      val androidMain by getting {
+         dependencies {
+            implementation(libs.ktor.client.okhttp)
          }
       }
 
+      val iosX64Main by getting
+      val iosArm64Main by getting
+      val iosSimulatorArm64Main by getting
+      val iosMain by creating {
+         dependsOn(commonMain)
+         dependencies {
+            implementation(libs.ktor.client.darwin)
+         }
+      }
+      iosX64Main.dependsOn(iosMain)
+      iosArm64Main.dependsOn(iosMain)
+      iosSimulatorArm64Main.dependsOn(iosMain)
+
       val commonTest by getting {
          dependencies {
+            implementation(libs.kotlin.test)
+            implementation(libs.kotlinx.coroutines.test)
          }
       }
+
+      commonMain.dependencies {
+         api(projects.mutationsDefinitions)
+      }
+   }
+   // don't show warnings for expect/actual classes
+   targets.configureEach {
+      compilations.configureEach {
+         compileTaskProvider.get().compilerOptions {
+            freeCompilerArgs.add("-Xexpect-actual-classes")
+         }
+      }
+   }
+}
+
+android {
+   namespace = "com.quran.shared.syncengine"
+   compileSdk = libs.versions.android.compile.sdk.get().toInt()
+
+   defaultConfig {
+      minSdk = libs.versions.android.min.sdk.get().toInt()
+   }
+
+   compileOptions {
+      sourceCompatibility = JavaVersion.valueOf("VERSION_${libs.versions.android.java.version.get()}")
+      targetCompatibility = JavaVersion.valueOf("VERSION_${libs.versions.android.java.version.get()}")
+   }
+
+   testOptions {
+      unitTests {
+         isIncludeAndroidResources = true
+      }
    }
 }
 
 mavenPublishing {
    publishToMavenCentral(SonatypeHost.CENTRAL_PORTAL)
    signAllPublications()
-   coordinates(group.toString(), "syncengine", version.toString())
+   coordinates(libs.versions.project.group.get(), "syncengine", libs.versions.project.version.get())
 
    pom {
       name = "Quran.com Sync Engine"

syncengine/src/androidMain/kotlin/com/quran/shared/syncengine/HttpClientFactory.android.kt

@@ -0,0 +1,20 @@
+package com.quran.shared.syncengine
+
+import io.ktor.client.*
+import io.ktor.client.engine.okhttp.*
+import io.ktor.client.plugins.contentnegotiation.*
+import io.ktor.client.plugins.logging.*
+import io.ktor.serialization.kotlinx.json.*
+
+actual object HttpClientFactory {
+    actual fun createHttpClient(): HttpClient {
+        return HttpClient(OkHttp) {
+            install(ContentNegotiation) {
+                json()
+            }
+            install(Logging) {
+                level = LogLevel.INFO
+            }
+        }
+    }
+}