@shaykec/app-agent 1.0.5 → 1.0.7

package/templates/shared/android/CachedRepository/CachedRepository.kt

@@ -0,0 +1,310 @@
+package com.appship.shared.cached
+
+import android.content.Context
+import android.net.ConnectivityManager
+import android.net.NetworkCapabilities
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.asStateFlow
+import kotlinx.coroutines.launch
+import kotlinx.coroutines.withContext
+
+/**
+ * Decorator implementing DataRepository that wraps any remote DataRepository.
+ * Provides cache-first reads, optimistic writes, and offline queue management.
+ * 
+ * Strategy:
+ * - Reads: Check Room cache first, return immediately. Refresh from remote in background.
+ * - Writes: Apply to Room immediately (optimistic), queue for remote sync.
+ * - Sync: Process queue when online, exponential backoff on failures.
+ * 
+ * CUSTOMIZE: Replace Item, Category with your app's domain models.
+ */
+class CachedRepository(
+    private val context: Context,
+    private val remoteRepository: DataRepository,
+    private val localCache: LocalCache,
+    private val offlineQueue: OfflineQueue,
+    private val scope: CoroutineScope = CoroutineScope(Dispatchers.IO)
+) : DataRepository {
+    
+    private val _items = MutableStateFlow<List<Item>>(emptyList())
+    override val items: StateFlow<List<Item>> = _items.asStateFlow()
+    
+    private val _categories = MutableStateFlow<List<Category>>(emptyList())
+    override val categories: StateFlow<List<Category>> = _categories.asStateFlow()
+    
+    private val _favoriteItems = MutableStateFlow<List<Item>>(emptyList())
+    override val favoriteItems: StateFlow<List<Item>> = _favoriteItems.asStateFlow()
+    
+    private val _syncStatus = MutableStateFlow<SyncStatus>(SyncStatus.IDLE)
+    val syncStatus: StateFlow<SyncStatus> = _syncStatus.asStateFlow()
+    
+    private val _pendingMutations = MutableStateFlow<Int>(0)
+    val pendingMutations: StateFlow<Int> = _pendingMutations.asStateFlow()
+    
+    init {
+        loadFromCache()
+        scope.launch {
+            processOfflineQueue()
+        }
+    }
+    
+    /**
+     * Load data from cache first, then refresh from remote
+     */
+    override fun loadData() {
+        loadFromCache()
+        if (isOnline()) {
+            scope.launch {
+                refreshFromRemote()
+            }
+        }
+    }
+    
+    private fun loadFromCache() {
+        scope.launch {
+            val cachedItems = localCache.getItems()
+            val cachedCategories = localCache.getCategories()
+            
+            withContext(Dispatchers.Main) {
+                _items.value = cachedItems
+                _categories.value = cachedCategories
+                _favoriteItems.value = cachedItems.filter { it.isFavorite }
+            }
+        }
+    }
+    
+    private suspend fun refreshFromRemote() {
+        try {
+            _syncStatus.value = SyncStatus.SYNCING
+            
+            // Load from remote repository
+            remoteRepository.loadData()
+            
+            // Update cache with fresh data
+            val remoteItems = remoteRepository.items.value
+            val remoteCategories = remoteRepository.categories.value
+            
+            localCache.saveItems(remoteItems)
+            localCache.saveCategories(remoteCategories)
+            
+            withContext(Dispatchers.Main) {
+                _items.value = remoteItems
+                _categories.value = remoteCategories
+                _favoriteItems.value = remoteItems.filter { it.isFavorite }
+            }
+            
+            _syncStatus.value = SyncStatus.SYNCED
+            
+            // Process any pending mutations
+            processOfflineQueue()
+        } catch (e: Exception) {
+            _syncStatus.value = SyncStatus.ERROR
+            // Keep using cached data
+        }
+    }
+    
+    /**
+     * Add item: write to cache immediately, queue for remote sync
+     */
+    override fun addItem(item: Item) {
+        // Optimistic update to cache
+        localCache.saveItem(item)
+        updateLocalState()
+        
+        // Queue for remote sync
+        if (isOnline()) {
+            scope.launch {
+                try {
+                    remoteRepository.addItem(item)
+                } catch (e: Exception) {
+                    // Queue for retry
+                    offlineQueue.enqueueMutation(
+                        MutationType.ADD,
+                        item
+                    )
+                    updatePendingCount()
+                }
+            }
+        } else {
+            offlineQueue.enqueueMutation(MutationType.ADD, item)
+            updatePendingCount()
+        }
+    }
+    
+    /**
+     * Update item: write to cache immediately, queue for remote sync
+     */
+    override fun updateItem(item: Item) {
+        // Optimistic update to cache
+        localCache.saveItem(item)
+        updateLocalState()
+        
+        // Queue for remote sync
+        if (isOnline()) {
+            scope.launch {
+                try {
+                    remoteRepository.updateItem(item)
+                } catch (e: Exception) {
+                    offlineQueue.enqueueMutation(MutationType.UPDATE, item)
+                    updatePendingCount()
+                }
+            }
+        } else {
+            offlineQueue.enqueueMutation(MutationType.UPDATE, item)
+            updatePendingCount()
+        }
+    }
+    
+    /**
+     * Delete item: remove from cache immediately, queue for remote sync
+     */
+    override fun deleteItem(item: Item) {
+        // Optimistic update to cache
+        localCache.deleteItem(item.id)
+        updateLocalState()
+        
+        // Queue for remote sync
+        if (isOnline()) {
+            scope.launch {
+                try {
+                    remoteRepository.deleteItem(item)
+                } catch (e: Exception) {
+                    offlineQueue.enqueueMutation(MutationType.DELETE, item)
+                    updatePendingCount()
+                }
+            }
+        } else {
+            offlineQueue.enqueueMutation(MutationType.DELETE, item)
+            updatePendingCount()
+        }
+    }
+    
+    override fun toggleFavorite(item: Item) {
+        val updated = item.copy(isFavorite = !item.isFavorite)
+        updateItem(updated)
+    }
+    
+    override fun searchItems(query: String): List<Item> {
+        // Search in cached data
+        if (query.isBlank()) return _items.value
+        val lower = query.lowercase()
+        return _items.value.filter {
+            it.title.lowercase().contains(lower) || 
+            it.subtitle?.lowercase()?.contains(lower) == true
+        }
+    }
+    
+    override fun itemsByCategory(categoryName: String): List<Item> {
+        return _items.value.filter { it.category == categoryName }
+    }
+    
+    /**
+     * Process offline queue when online
+     */
+    private suspend fun processOfflineQueue() {
+        if (!isOnline()) return
+        
+        val mutations = offlineQueue.getPendingMutations()
+        if (mutations.isEmpty()) {
+            updatePendingCount()
+            return
+        }
+        
+        _syncStatus.value = SyncStatus.SYNCING
+        
+        for (mutation in mutations) {
+            try {
+                when (mutation.type) {
+                    MutationType.ADD -> remoteRepository.addItem(mutation.item)
+                    MutationType.UPDATE -> remoteRepository.updateItem(mutation.item)
+                    MutationType.DELETE -> remoteRepository.deleteItem(mutation.item)
+                }
+                offlineQueue.removeMutation(mutation.id)
+            } catch (e: Exception) {
+                // Increment retry count
+                offlineQueue.incrementRetryCount(mutation.id)
+                
+                // If retry count exceeds threshold, mark as failed
+                if (mutation.retryCount >= 5) {
+                    offlineQueue.markAsFailed(mutation.id)
+                }
+            }
+        }
+        
+        updatePendingCount()
+        _syncStatus.value = SyncStatus.SYNCED
+        
+        // Refresh data after sync
+        refreshFromRemote()
+    }
+    
+    private fun updateLocalState() {
+        scope.launch {
+            val cachedItems = localCache.getItems()
+            withContext(Dispatchers.Main) {
+                _items.value = cachedItems
+                _favoriteItems.value = cachedItems.filter { it.isFavorite }
+            }
+        }
+    }
+    
+    private fun updatePendingCount() {
+        scope.launch {
+            val count = offlineQueue.getPendingMutations().size
+            withContext(Dispatchers.Main) {
+                _pendingMutations.value = count
+            }
+        }
+    }
+    
+    private fun isOnline(): Boolean {
+        val connectivityManager = context.getSystemService(Context.CONNECTIVITY_SERVICE) as ConnectivityManager
+        val network = connectivityManager.activeNetwork ?: return false
+        val capabilities = connectivityManager.getNetworkCapabilities(network) ?: return false
+        return capabilities.hasCapability(NetworkCapabilities.NET_CAPABILITY_INTERNET) &&
+               capabilities.hasCapability(NetworkCapabilities.NET_CAPABILITY_VALIDATED)
+    }
+}
+
+enum class SyncStatus {
+    IDLE, SYNCING, SYNCED, ERROR
+}
+
+/**
+ * CUSTOMIZE: Replace with your app's domain models.
+ */
+data class Item(
+    val id: String,
+    val title: String,
+    val subtitle: String? = null,
+    val category: String? = null,
+    val isFavorite: Boolean = false,
+    val metadata: Map<String, Any> = emptyMap()
+)
+
+data class Category(
+    val id: String,
+    val name: String,
+    val metadata: Map<String, Any> = emptyMap()
+)
+
+/**
+ * CUSTOMIZE: Replace with your app's DataRepository interface.
+ */
+interface DataRepository {
+    val items: StateFlow<List<Item>>
+    val categories: StateFlow<List<Category>>
+    val favoriteItems: StateFlow<List<Item>>
+    
+    fun loadData()
+    fun addItem(item: Item)
+    fun updateItem(item: Item)
+    fun deleteItem(item: Item)
+    fun toggleFavorite(item: Item)
+    fun searchItems(query: String): List<Item>
+    fun itemsByCategory(categoryName: String): List<Item>
+}

package/templates/shared/android/CachedRepository/LocalCache.kt

@@ -0,0 +1,178 @@
+package com.appship.shared.cached
+
+import androidx.room.*
+import com.google.gson.Gson
+import com.google.gson.reflect.TypeToken
+
+/**
+ * Room-backed local cache for offline data persistence.
+ * Stores entities as JSON strings with TTL timestamps.
+ */
+@Entity(tableName = "cache")
+data class CacheEntity(
+    @PrimaryKey val key: String,
+    val data: String, // JSON string
+    val timestamp: Long = System.currentTimeMillis(),
+    val ttl: Long = 24 * 60 * 60 * 1000 // 24 hours default TTL
+)
+
+@Dao
+interface CacheDao {
+    @Query("SELECT * FROM cache WHERE key = :key")
+    suspend fun get(key: String): CacheEntity?
+    
+    @Query("SELECT * FROM cache WHERE key LIKE :prefix || '%'")
+    suspend fun getAllWithPrefix(prefix: String): List<CacheEntity>
+    
+    @Insert(onConflict = OnConflictStrategy.REPLACE)
+    suspend fun insert(entity: CacheEntity)
+    
+    @Delete
+    suspend fun delete(entity: CacheEntity)
+    
+    @Query("DELETE FROM cache WHERE key = :key")
+    suspend fun deleteByKey(key: String)
+    
+    @Query("DELETE FROM cache WHERE timestamp + ttl < :currentTime")
+    suspend fun deleteExpired(currentTime: Long = System.currentTimeMillis())
+    
+    @Query("DELETE FROM cache")
+    suspend fun clearAll()
+}
+
+@Database(entities = [CacheEntity::class], version = 1, exportSchema = false)
+abstract class CacheDatabase : RoomDatabase() {
+    abstract fun cacheDao(): CacheDao
+}
+
+/**
+ * Local cache manager using Room database.
+ * CUSTOMIZE: Replace Item, Category with your app's domain models.
+ */
+class LocalCache(
+    private val database: CacheDatabase,
+    private val gson: Gson = Gson()
+) {
+    private val dao = database.cacheDao()
+    
+    companion object {
+        private const val KEY_ITEMS = "items"
+        private const val KEY_CATEGORIES = "categories"
+        private const val KEY_ITEM_PREFIX = "item_"
+    }
+    
+    /**
+     * Get all items from cache
+     */
+    suspend fun getItems(): List<Item> {
+        val entity = dao.get(KEY_ITEMS) ?: return emptyList()
+        if (isExpired(entity)) {
+            dao.delete(entity)
+            return emptyList()
+        }
+        return deserializeList<Item>(entity.data)
+    }
+    
+    /**
+     * Get all categories from cache
+     */
+    suspend fun getCategories(): List<Category> {
+        val entity = dao.get(KEY_CATEGORIES) ?: return emptyList()
+        if (isExpired(entity)) {
+            dao.delete(entity)
+            return emptyList()
+        }
+        return deserializeList<Category>(entity.data)
+    }
+    
+    /**
+     * Save all items to cache
+     */
+    suspend fun saveItems(items: List<Item>) {
+        val entity = CacheEntity(
+            key = KEY_ITEMS,
+            data = serializeList(items)
+        )
+        dao.insert(entity)
+    }
+    
+    /**
+     * Save all categories to cache
+     */
+    suspend fun saveCategories(categories: List<Category>) {
+        val entity = CacheEntity(
+            key = KEY_CATEGORIES,
+            data = serializeList(categories)
+        )
+        dao.insert(entity)
+    }
+    
+    /**
+     * Save a single item to cache
+     */
+    suspend fun saveItem(item: Item) {
+        // Update the items list
+        val currentItems = getItems().toMutableList()
+        val index = currentItems.indexOfFirst { it.id == item.id }
+        if (index >= 0) {
+            currentItems[index] = item
+        } else {
+            currentItems.add(item)
+        }
+        saveItems(currentItems)
+    }
+    
+    /**
+     * Delete an item from cache
+     */
+    suspend fun deleteItem(itemId: String) {
+        val currentItems = getItems().toMutableList()
+        currentItems.removeAll { it.id == itemId }
+        saveItems(currentItems)
+    }
+    
+    /**
+     * Clear all cache
+     */
+    suspend fun clearAll() {
+        dao.clearAll()
+    }
+    
+    /**
+     * Clean up expired entries
+     */
+    suspend fun cleanupExpired() {
+        dao.deleteExpired()
+    }
+    
+    private fun isExpired(entity: CacheEntity): Boolean {
+        return System.currentTimeMillis() > entity.timestamp + entity.ttl
+    }
+    
+    private inline fun <reified T> serializeList(list: List<T>): String {
+        return gson.toJson(list)
+    }
+    
+    private inline fun <reified T> deserializeList(json: String): List<T> {
+        val type = object : TypeToken<List<T>>() {}.type
+        return gson.fromJson(json, type) ?: emptyList()
+    }
+}
+
+/**
+ * CUSTOMIZE: Replace with your app's domain models.
+ */
+data class Item(
+    val id: String,
+    val title: String,
+    val subtitle: String? = null,
+    val category: String? = null,
+    val isFavorite: Boolean = false,
+    val metadata: Map<String, Any> = emptyMap()
+)
+
+data class Category(
+    val id: String,
+    val name: String,
+    val metadata: Map<String, Any> = emptyMap()
+)

package/templates/shared/android/CachedRepository/OfflineQueue.kt

@@ -0,0 +1,171 @@
+package com.appship.shared.cached
+
+import androidx.room.*
+import com.google.gson.Gson
+import com.google.gson.reflect.TypeToken
+
+/**
+ * Persisted mutation queue for offline operations.
+ * Stores pending mutations that need to be synced when online.
+ */
+enum class MutationType {
+    ADD, UPDATE, DELETE
+}
+
+@Entity(tableName = "offline_queue")
+data class QueueEntity(
+    @PrimaryKey(autoGenerate = true) val id: Long = 0,
+    val type: MutationType,
+    val itemData: String, // JSON string of Item
+    val timestamp: Long = System.currentTimeMillis(),
+    val retryCount: Int = 0,
+    val failed: Boolean = false
+)
+
+@Dao
+interface QueueDao {
+    @Query("SELECT * FROM offline_queue WHERE failed = 0 ORDER BY timestamp ASC")
+    suspend fun getPendingMutations(): List<QueueEntity>
+    
+    @Query("SELECT * FROM offline_queue WHERE id = :id")
+    suspend fun getById(id: Long): QueueEntity?
+    
+    @Insert
+    suspend fun insert(entity: QueueEntity): Long
+    
+    @Delete
+    suspend fun delete(entity: QueueEntity)
+    
+    @Query("DELETE FROM offline_queue WHERE id = :id")
+    suspend fun deleteById(id: Long)
+    
+    @Query("UPDATE offline_queue SET retryCount = retryCount + 1 WHERE id = :id")
+    suspend fun incrementRetryCount(id: Long)
+    
+    @Query("UPDATE offline_queue SET failed = 1 WHERE id = :id")
+    suspend fun markAsFailed(id: Long)
+    
+    @Query("DELETE FROM offline_queue WHERE failed = 1")
+    suspend fun deleteFailed()
+    
+    @Query("DELETE FROM offline_queue")
+    suspend fun clearAll()
+}
+
+@Database(entities = [QueueEntity::class], version = 1, exportSchema = false)
+abstract class QueueDatabase : RoomDatabase() {
+    abstract fun queueDao(): QueueDao
+}
+
+/**
+ * Offline queue manager using Room database.
+ * Handles mutation queuing, retry logic, and exponential backoff.
+ * CUSTOMIZE: Replace Item with your app's domain model.
+ */
+class OfflineQueue(
+    private val database: QueueDatabase,
+    private val gson: Gson = Gson()
+) {
+    private val dao = database.queueDao()
+    
+    /**
+     * Enqueue a mutation for later sync
+     */
+    suspend fun enqueueMutation(type: MutationType, item: Item): Long {
+        val entity = QueueEntity(
+            type = type,
+            itemData = serializeItem(item)
+        )
+        return dao.insert(entity)
+    }
+    
+    /**
+     * Get all pending mutations
+     */
+    suspend fun getPendingMutations(): List<QueuedMutation> {
+        return dao.getPendingMutations().map { entity ->
+            QueuedMutation(
+                id = entity.id,
+                type = entity.type,
+                item = deserializeItem(entity.itemData),
+                timestamp = entity.timestamp,
+                retryCount = entity.retryCount
+            )
+        }
+    }
+    
+    /**
+     * Remove a mutation from the queue (after successful sync)
+     */
+    suspend fun removeMutation(id: Long) {
+        dao.deleteById(id)
+    }
+    
+    /**
+     * Increment retry count for a mutation
+     */
+    suspend fun incrementRetryCount(id: Long) {
+        dao.incrementRetryCount(id)
+    }
+    
+    /**
+     * Mark a mutation as failed (after max retries)
+     */
+    suspend fun markAsFailed(id: Long) {
+        dao.markAsFailed(id)
+    }
+    
+    /**
+     * Clear all failed mutations
+     */
+    suspend fun clearFailed() {
+        dao.deleteFailed()
+    }
+    
+    /**
+     * Clear all mutations
+     */
+    suspend fun clearAll() {
+        dao.clearAll()
+    }
+    
+    /**
+     * Calculate exponential backoff delay based on retry count
+     */
+    fun getBackoffDelay(retryCount: Int): Long {
+        // Exponential backoff: 1s, 2s, 4s, 8s, 16s, max 30s
+        val delay = (1L shl retryCount.coerceAtMost(5)) * 1000
+        return delay.coerceAtMost(30000)
+    }
+    
+    private fun serializeItem(item: Item): String {
+        return gson.toJson(item)
+    }
+    
+    private fun deserializeItem(json: String): Item {
+        return gson.fromJson(json, Item::class.java)
+    }
+}
+
+/**
+ * Represents a queued mutation
+ */
+data class QueuedMutation(
+    val id: Long,
+    val type: MutationType,
+    val item: Item,
+    val timestamp: Long,
+    val retryCount: Int
+)
+
+/**
+ * CUSTOMIZE: Replace with your app's domain model.
+ */
+data class Item(
+    val id: String,
+    val title: String,
+    val subtitle: String? = null,
+    val category: String? = null,
+    val isFavorite: Boolean = false,
+    val metadata: Map<String, Any> = emptyMap()
+)

package/templates/shared/android/CachedRepository/strings.xml

@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+    <!-- Cached Repository Module -->
+    <string name="cached_repo_sync_status_idle">Ready</string>
+    <string name="cached_repo_sync_status_syncing">Syncing…</string>
+    <string name="cached_repo_sync_status_synced">Synced</string>
+    <string name="cached_repo_sync_status_error">Sync Error</string>
+    <string name="cached_repo_pending_mutations">%1$d pending changes</string>
+    <string name="cached_repo_syncing_changes">Syncing %1$d changes…</string>
+    <string name="cached_repo_offline_mode">Offline mode - changes will sync when online</string>
+    <string name="cached_repo_sync_failed">Sync failed. Will retry automatically.</string>
+    <string name="cached_repo_retry_sync">Retry Sync</string>
+    <string name="cached_repo_last_synced">Last synced: %1$s</string>
+    <string name="cached_repo_never_synced">Never synced</string>
+</resources>