Clean up the api

demo/android/src/main/kotlin/com/quran/shared/demo/android/ui/SyncViewModel.kt

@@ -103,7 +103,7 @@ class SyncViewModel(
         service.deleteNote(noteId)
     }
 
-    fun getBookmarksForCollectionFlow(collectionLocalId: String): Flow<List<com.quran.shared.persistence.model.CollectionAyahBookmark>> =
-        service.getBookmarksForCollectionFlow(collectionLocalId)
+    fun getBookmarksForCollectionFlow(collectionId: String): Flow<List<com.quran.shared.persistence.model.CollectionAyahBookmark>> =
+        service.getBookmarksForCollectionFlow(collectionId)
 
 }

demo/android/src/main/kotlin/com/quran/shared/demo/android/ui/auth/CollectionsTab.kt

@@ -68,7 +68,7 @@ fun CollectionsTab(
                         ListItem(
                             headlineContent = { Text(item.collection.name) },
                             modifier = Modifier.clickable {
-                                onAddRandomBookmarkToCollection(item.collection.localId)
+                                onAddRandomBookmarkToCollection(item.collection.id)
                                 showSelectCollectionDialog = false
                             }
                         )
@@ -117,7 +117,7 @@ fun CollectionsTab(
                 items(collectionsWithBookmarks) { collectionWithBookmarks ->
                     CollectionItem(
                         collectionWithBookmarks = collectionWithBookmarks,
-                        onDelete = { onDeleteCollection(collectionWithBookmarks.collection.localId) }
+                        onDelete = { onDeleteCollection(collectionWithBookmarks.collection.id) }
                     )
                 }
             }

demo/android/src/main/kotlin/com/quran/shared/demo/android/ui/auth/NotesTab.kt

@@ -82,7 +82,7 @@ fun NotesTab(
                 items(notes) { note ->
                     NoteItem(
                         note = note,
-                        onDelete = { onDeleteNote(note.localId) }
+                        onDelete = { onDeleteNote(note.id) }
                     )
                 }
             }

demo/apple/QuranSyncDemo/QuranSyncDemo/BookmarksTabView.swift

@@ -80,7 +80,7 @@ struct BookmarksTabView: View {
                         .foregroundColor(.secondary)
                         .italic()
                 } else {
-                    ForEach(viewModel.bookmarks, id: \.localId) { bookmark in
+                    ForEach(viewModel.bookmarks, id: \.id) { bookmark in
                         HStack {
                             Image(systemName: "bookmark.fill")
                                 .foregroundColor(.accentColor)

demo/apple/QuranSyncDemo/QuranSyncDemo/CollectionsTabView.swift

@@ -28,7 +28,7 @@ struct CollectionsTabView: View {
                         .foregroundColor(.secondary)
                         .italic()
                 } else {
-                    ForEach(viewModel.collectionsWithBookmarks, id: \.collection.localId) { collectionWithBookmarks in
+                    ForEach(viewModel.collectionsWithBookmarks, id: \.collection.id) { collectionWithBookmarks in
                         CollectionRowView(viewModel: viewModel, collectionWithBookmarks: collectionWithBookmarks)
                     }
                 }
@@ -51,12 +51,12 @@ struct CollectionsTabView: View {
         }
         .sheet(isPresented: $showSelectCollectionSheet) {
             NavigationView {
-                List(viewModel.collectionsWithBookmarks, id: \.collection.localId) { item in
+                List(viewModel.collectionsWithBookmarks, id: \.collection.id) { item in
                     Button(action: {
                         Task {
                             let sura = Shared.QuranActionsUtils().getRandomSura()
                             let ayah = Shared.QuranActionsUtils().getRandomAyah(sura: sura)
-                            await viewModel.addAyahBookmarkToCollection(collectionId: item.collection.localId,
+                            await viewModel.addAyahBookmarkToCollection(collectionId: item.collection.id,
                                                                         sura: sura,
                                                                         ayah: ayah)
                         }
@@ -98,7 +98,7 @@ struct CollectionRowView: View {
 
                 Button(action: {
                     Task {
-                        await viewModel.deleteCollection(collectionId: collectionWithBookmarks.collection.localId)
+                        await viewModel.deleteCollection(collectionId: collectionWithBookmarks.collection.id)
                     }
                 }) {
                     Image(systemName: "trash")
@@ -115,7 +115,7 @@ struct CollectionRowView: View {
                             .foregroundColor(.secondary)
                             .padding(.leading, 32)
                     } else {
-                        ForEach(collectionWithBookmarks.bookmarks, id: \.localId) { cb in
+                        ForEach(collectionWithBookmarks.bookmarks, id: \.bookmarkId) { cb in
                             HStack {
                                 Image(systemName: "bookmark")
                                     .font(.caption)

demo/apple/QuranSyncDemo/QuranSyncDemo/NotesTabView.swift

@@ -20,7 +20,7 @@ struct NotesTabView: View {
                         .foregroundColor(.secondary)
                         .italic()
                 } else {
-                    ForEach(viewModel.notes, id: \.localId) { note in
+                    ForEach(viewModel.notes, id: \.id) { note in
                         HStack {
                             Image(systemName: "note.text")
                                 .foregroundColor(.blue)
@@ -34,7 +34,7 @@ struct NotesTabView: View {
                             Spacer()
                             Button(action: {
                                 Task {
-                                    await viewModel.deleteNote(localId: note.localId)
+                                    await viewModel.deleteNote(id: note.id)
                                 }
                             }) {
                                 Image(systemName: "trash")

demo/apple/QuranSyncDemo/QuranSyncDemo/SyncViewModel.swift

@@ -151,7 +151,7 @@ class SyncViewModel: ObservableObject {
 
     func deleteCollection(collectionId: String) async {
         do {
-            try await asyncFunction(for: quranDataService.deleteCollection(localId: collectionId))
+            try await asyncFunction(for: quranDataService.deleteCollection(id: collectionId))
         } catch {
             print("SyncViewModel: Failed to delete collection: \(error)")
         }
@@ -173,40 +173,40 @@ class SyncViewModel: ObservableObject {
         }
     }
 
-    func deleteNote(localId: String) async {
+    func deleteNote(id: String) async {
         do {
-            try await asyncFunction(for: quranDataService.deleteNote(localId: localId))
+            try await asyncFunction(for: quranDataService.deleteNote(id: id))
         } catch {
             print("SyncViewModel: Failed to delete note: \(error)")
         }
     }
 
     func addBookmarkToCollection(collectionId: String, bookmark: Shared.AyahBookmark) async {
         do {
-            try await asyncFunction(for: quranDataService.addBookmarkToCollection(collectionLocalId: collectionId, bookmark: bookmark))
+            try await asyncFunction(for: quranDataService.addBookmarkToCollection(collectionId: collectionId, bookmark: bookmark))
         } catch {
             print("SyncViewModel: Failed to add bookmark to collection: \(error)")
         }
     }
 
     func removeBookmarkFromCollection(collectionId: String, bookmark: Shared.AyahBookmark) async {
         do {
-            try await asyncFunction(for: quranDataService.removeBookmarkFromCollection(collectionLocalId: collectionId, bookmark: bookmark))
+            try await asyncFunction(for: quranDataService.removeBookmarkFromCollection(collectionId: collectionId, bookmark: bookmark))
         } catch {
             print("SyncViewModel: Failed to remove bookmark from collection: \(error)")
         }
     }
 
     func addAyahBookmarkToCollection(collectionId: String, sura: Int32, ayah: Int32) async {
         do {
-            try await asyncFunction(for: quranDataService.addAyahBookmarkToCollection(collectionLocalId: collectionId, sura: sura, ayah: ayah))
+            try await asyncFunction(for: quranDataService.addAyahBookmarkToCollection(collectionId: collectionId, sura: sura, ayah: ayah))
         } catch {
             print("SyncViewModel: Failed to add random bookmark to collection: \(error)")
         }
     }
 
     func bookmarksForCollection(collectionId: String) -> any AsyncSequence {
-        return asyncSequence(for: quranDataService.getBookmarksForCollectionFlow(collectionLocalId: collectionId))
+        return asyncSequence(for: quranDataService.getBookmarksForCollectionFlow(collectionId: collectionId))
     }
 
     func login() async throws {

persistence/src/commonMain/kotlin/com/quran/shared/persistence/model/AyahBookmark.kt

@@ -2,10 +2,19 @@ package com.quran.shared.persistence.model
 
 import com.quran.shared.persistence.util.PlatformDateTime
 
+/**
+ * App-facing saved ayah bookmark.
+ *
+ * @param sura the sura number
+ * @param ayah the ayah number
+ * @param id the identifier for the ayah bookmark
+ * @param lastUpdated when the bookmark was last updated
+ * @param addedDate when the bookmark was first added
+ */
 data class AyahBookmark(
     val sura: Int,
     val ayah: Int,
-    val localId: String,
+    val id: String,
     val lastUpdated: PlatformDateTime,
     val addedDate: PlatformDateTime = lastUpdated
 )

persistence/src/commonMain/kotlin/com/quran/shared/persistence/model/Collection.kt

@@ -5,19 +5,18 @@ import com.quran.shared.persistence.util.PlatformDateTime
 /**
  * App-facing collection model.
  *
- * The default bookmark collection is virtual: it is identified by [DEFAULT_COLLECTION_ID] and is
- * derived from bookmark membership state instead of a row in the collection table.
+ * @param name the name of the collection
+ * @param lastUpdated when the collection was last updated
+ * @param id the identifier of the collection
  */
 data class Collection(
     val name: String,
     val lastUpdated: PlatformDateTime,
-    val localId: String
+    val id: String
 ) {
     /**
      * True when this collection represents the virtual default bookmark collection.
-     *
-     * This value is derived from [localId] so callers do not pass or persist a separate flag.
      */
     val isDefault: Boolean
-        get() = localId == DEFAULT_COLLECTION_ID
+        get() = id == DEFAULT_COLLECTION_ID
 }

persistence/src/commonMain/kotlin/com/quran/shared/persistence/model/CollectionAyahBookmark.kt

@@ -2,13 +2,21 @@ package com.quran.shared.persistence.model
 
 import com.quran.shared.persistence.util.PlatformDateTime
 
+/**
+ * App-facing ayah bookmark membership in a collection.
+ *
+ * @param collectionId the id of the collection
+ * @param bookmarkId the id of the bookmark
+ * @param sura the sura number
+ * @param ayah the ayah number
+ * @param bookmarkLastUpdated the last time the bookmark itself changed
+ * @param bookmarkAddedDate the time the bookmark itself was created locally
+ */
 data class CollectionAyahBookmark(
-    val collectionLocalId: String,
-    val collectionRemoteId: String?,
-    val bookmarkLocalId: String,
-    val bookmarkRemoteId: String?,
+    val collectionId: String,
+    val bookmarkId: String,
     val sura: Int,
     val ayah: Int,
-    val lastUpdated: PlatformDateTime,
-    val localId: String
+    val bookmarkLastUpdated: PlatformDateTime,
+    val bookmarkAddedDate: PlatformDateTime
 )

persistence/src/commonMain/kotlin/com/quran/shared/persistence/model/Note.kt

@@ -2,12 +2,23 @@ package com.quran.shared.persistence.model
 
 import com.quran.shared.persistence.util.PlatformDateTime
 
+/**
+ * App-facing note attached to a Quran ayah range.
+ *
+ * @param body the text of the note
+ * @param startSura the start sura
+ * @param startAyah the start ayah
+ * @param endSura the end sura
+ * @param endAyah the end ayah
+ * @param lastUpdated when the note was last updated
+ * @param id the identifier of the note
+ */
 data class Note(
     val body: String,
     val startSura: Int,
     val startAyah: Int,
     val endSura: Int,
     val endAyah: Int,
     val lastUpdated: PlatformDateTime,
-    val localId: String
+    val id: String
 )

persistence/src/commonMain/kotlin/com/quran/shared/persistence/model/ReadingBookmark.kt

@@ -2,20 +2,38 @@ package com.quran.shared.persistence.model
 
 import com.quran.shared.persistence.util.PlatformDateTime
 
+/**
+ * App-facing current reading bookmark.
+ */
 sealed interface ReadingBookmark {
     val lastUpdated: PlatformDateTime
-    val localId: String
+    val id: String
 }
 
+/**
+ * Ayah Reading Bookmark
+ *
+ * @param sura the sura
+ * @parma ayah the ayah
+ * @param lastUpdated the last updated
+ * @param id the identifier of the ayah reading bookmark
+ */
 data class AyahReadingBookmark(
     val sura: Int,
     val ayah: Int,
     override val lastUpdated: PlatformDateTime,
-    override val localId: String
+    override val id: String
 ) : ReadingBookmark
 
+/**
+ * Page Reading Bookmark
+ *
+ * @param page the page
+ * @param lastUpdated the last updated time of the ayah reading bookmark
+ * @param id the identifier of the page reading bookmark
+ */
 data class PageReadingBookmark(
     val page: Int,
     override val lastUpdated: PlatformDateTime,
-    override val localId: String
+    override val id: String
 ) : ReadingBookmark

persistence/src/commonMain/kotlin/com/quran/shared/persistence/model/ReadingSession.kt

@@ -2,9 +2,17 @@ package com.quran.shared.persistence.model
 
 import com.quran.shared.persistence.util.PlatformDateTime
 
+/**
+ * App-facing reading-session entry.
+ *
+ * @param sura the sura
+ * @param ayah the ayah
+ * @param lastUpdated the last updated time of the reading session
+ * @param id the identifier of the reading session
+ */
 data class ReadingSession(
     val sura: Int,
     val ayah: Int,
     val lastUpdated: PlatformDateTime,
-    val localId: String
+    val id: String
 )

persistence/src/commonMain/kotlin/com/quran/shared/persistence/repository/bookmark/extension/BookmarkQueriesExtensions.kt

@@ -14,7 +14,7 @@ internal fun DatabaseBookmark.toAyahBookmark(): AyahBookmark {
     return AyahBookmark(
         sura = requireNotNull(sura).toInt(),
         ayah = requireNotNull(ayah).toInt(),
-        localId = local_id.toString(),
+        id = local_id.toString(),
         lastUpdated = Instant.fromEpochMilliseconds(modified_at).toPlatform(),
         addedDate = Instant.fromEpochMilliseconds(created_at).toPlatform()
     )

persistence/src/commonMain/kotlin/com/quran/shared/persistence/repository/bookmark/repository/BookmarksRepository.kt

@@ -43,13 +43,13 @@ interface BookmarksRepository {
      * represents default membership.
      */
     @NativeCoroutines
-    suspend fun addBookmark(sura: Int, ayah: Int, collectionLocalIds: List<String>): AyahBookmark
+    suspend fun addBookmark(sura: Int, ayah: Int, collectionIds: List<String>): AyahBookmark
 
     @NativeCoroutines
     suspend fun addBookmark(
         sura: Int,
         ayah: Int,
-        collectionLocalIds: List<String>,
+        collectionIds: List<String>,
         timestamp: PlatformDateTime
     ): AyahBookmark
 
@@ -63,7 +63,7 @@ interface BookmarksRepository {
      * or already has exactly the requested memberships.
      */
     @NativeCoroutines
-    suspend fun replaceBookmarkCollections(localId: String, collectionLocalIds: List<String>): Boolean
+    suspend fun replaceBookmarkCollections(id: String, collectionIds: List<String>): Boolean
 
     /**
      * Replaces the saved collection memberships for an existing ayah bookmark with an explicit
@@ -77,8 +77,8 @@ interface BookmarksRepository {
      */
     @NativeCoroutines
     suspend fun replaceBookmarkCollections(
-        localId: String,
-        collectionLocalIds: List<String>,
+        id: String,
+        collectionIds: List<String>,
         timestamp: PlatformDateTime
     ): Boolean
 
@@ -91,7 +91,7 @@ interface BookmarksRepository {
     suspend fun replaceAyahBookmarkCollections(
         sura: Int,
         ayah: Int,
-        collectionLocalIds: List<String>
+        collectionIds: List<String>
     ): BookmarkCollectionsReplacementResult
 
     /**
@@ -104,7 +104,7 @@ interface BookmarksRepository {
     suspend fun replaceAyahBookmarkCollections(
         sura: Int,
         ayah: Int,
-        collectionLocalIds: List<String>,
+        collectionIds: List<String>,
         timestamp: PlatformDateTime
     ): BookmarkCollectionsReplacementResult
 
@@ -125,10 +125,10 @@ interface BookmarksRepository {
     suspend fun deleteBookmark(bookmark: AyahBookmark): Boolean
 
     /**
-     * Delete a bookmark by local ID, including any collection links.
+     * Delete a bookmark by its mobile-sync ID, including any collection links.
      *
      * @return a boolean denoting success
      */
     @NativeCoroutines
-    suspend fun deleteBookmark(localId: String): Boolean
+    suspend fun deleteBookmark(id: String): Boolean
 }