android-sdd 1.0.0

package/skills/Networking/Retrofit/SKILL.md

@@ -0,0 +1,241 @@
+---
+name: retrofit
+description: >
+  Retrofit HTTP client setup and usage for Android.
+  Load this skill when setting up Retrofit, defining API interfaces,
+  configuring converters, adding interceptors, handling responses,
+  or integrating Retrofit with Kotlinx Serialization and OkHttp.
+---
+
+# Retrofit
+
+## Overview
+
+Retrofit is a type-safe HTTP client for Android that turns API interfaces into callable Kotlin functions. It integrates with OkHttp for the underlying HTTP layer and Kotlinx Serialization for JSON parsing.
+
+---
+
+## Core Principles
+
+- Define one `Retrofit` instance per base URL — use DI to provide it
+- API interfaces return `Result<T>` or a sealed type — never raw response objects
+- Never call Retrofit from UI or ViewModel directly — go through Repository
+- Use `suspend` functions for all API calls — no callbacks or `Call<T>`
+- Handle HTTP errors explicitly — don't let them surface as exceptions silently
+
+---
+
+## Setup
+
+```toml
+# libs.versions.toml
+[versions]
+retrofit = "2.11.0"
+okhttp = "4.12.0"
+
+[libraries]
+retrofit = { module = "com.squareup.retrofit2:retrofit", version.ref = "retrofit" }
+retrofit-kotlinx-serialization = { module = "com.jakewharton.retrofit:retrofit2-kotlinx-serialization-converter", version.ref = "retrofit" }
+okhttp = { module = "com.squareup.okhttp3:okhttp", version.ref = "okhttp" }
+okhttp-logging = { module = "com.squareup.okhttp3:logging-interceptor", version.ref = "okhttp" }
+```
+
+```kotlin
+// build.gradle.kts
+dependencies {
+    implementation(libs.retrofit)
+    implementation(libs.retrofit.kotlinx.serialization)
+    implementation(libs.okhttp)
+    implementation(libs.okhttp.logging)
+}
+```
+
+---
+
+## Retrofit Instance
+
+```kotlin
+// ✅ Single Retrofit instance provided via DI
+@Provides
+@Singleton
+fun provideRetrofit(okHttpClient: OkHttpClient, json: Json): Retrofit {
+    return Retrofit.Builder()
+        .baseUrl(BuildConfig.BASE_URL)
+        .client(okHttpClient)
+        .addConverterFactory(json.asConverterFactory("application/json".toMediaType()))
+        .build()
+}
+
+@Provides
+@Singleton
+fun provideOkHttpClient(
+    authInterceptor: AuthInterceptor,
+    loggingInterceptor: HttpLoggingInterceptor
+): OkHttpClient {
+    return OkHttpClient.Builder()
+        .addInterceptor(authInterceptor)
+        .addInterceptor(loggingInterceptor)
+        .connectTimeout(30, TimeUnit.SECONDS)
+        .readTimeout(30, TimeUnit.SECONDS)
+        .writeTimeout(30, TimeUnit.SECONDS)
+        .build()
+}
+
+@Provides
+@Singleton
+fun provideLoggingInterceptor(): HttpLoggingInterceptor {
+    return HttpLoggingInterceptor().apply {
+        level = if (BuildConfig.DEBUG)
+            HttpLoggingInterceptor.Level.BODY
+        else
+            HttpLoggingInterceptor.Level.NONE
+    }
+}
+```
+
+---
+
+## API Interface
+
+```kotlin
+// ✅ Suspend functions, typed responses
+interface UserApi {
+
+    @GET("users")
+    suspend fun getUsers(): List<UserDto>
+
+    @GET("users/{id}")
+    suspend fun getUser(@Path("id") id: String): UserDto
+
+    @POST("users")
+    suspend fun createUser(@Body body: CreateUserRequest): UserDto
+
+    @PUT("users/{id}")
+    suspend fun updateUser(
+        @Path("id") id: String,
+        @Body body: UpdateUserRequest
+    ): UserDto
+
+    @DELETE("users/{id}")
+    suspend fun deleteUser(@Path("id") id: String)
+
+    @GET("users")
+    suspend fun searchUsers(
+        @Query("q") query: String,
+        @Query("page") page: Int = 1,
+        @Query("limit") limit: Int = 20
+    ): PagedResponse<UserDto>
+}
+```
+
+---
+
+## Response Handling in Repository
+
+```kotlin
+// ✅ Wrap API calls in runCatching — map to domain Result
+class UserRepositoryImpl @Inject constructor(
+    private val api: UserApi,
+    private val mapper: UserMapper
+) : UserRepository {
+
+    override suspend fun getUser(id: String): Result<User> = runCatching {
+        val dto = api.getUser(id)
+        mapper.toDomain(dto)
+    }
+
+    override suspend fun getUsers(): Result<List<User>> = runCatching {
+        api.getUsers().map { mapper.toDomain(it) }
+    }
+}
+```
+
+---
+
+## Auth Interceptor
+
+```kotlin
+// ✅ Attach token via interceptor — not in each API call
+class AuthInterceptor @Inject constructor(
+    private val tokenProvider: TokenProvider
+) : Interceptor {
+
+    override fun intercept(chain: Interceptor.Chain): Response {
+        val token = tokenProvider.getToken()
+        val request = if (token != null) {
+            chain.request().newBuilder()
+                .addHeader("Authorization", "Bearer $token")
+                .build()
+        } else {
+            chain.request()
+        }
+        return chain.proceed(request)
+    }
+}
+```
+
+---
+
+## HTTP Error Handling
+
+```kotlin
+// ✅ Custom call adapter or extension for HTTP errors
+suspend fun <T> safeApiCall(call: suspend () -> T): Result<T> = runCatching {
+    call()
+}.recoverCatching { throwable ->
+    when (throwable) {
+        is HttpException -> throw ApiException(
+            code = throwable.code(),
+            message = throwable.response()?.errorBody()?.string() ?: "HTTP error"
+        )
+        is IOException -> throw NetworkException("No internet connection")
+        else -> throw throwable
+    }
+}
+
+// ✅ Usage in repository
+override suspend fun getUser(id: String): Result<User> =
+    safeApiCall { api.getUser(id) }
+        .map { mapper.toDomain(it) }
+```
+
+---
+
+## Multipart / File Upload
+
+```kotlin
+// ✅ Upload file with multipart
+@Multipart
+@POST("users/{id}/avatar")
+suspend fun uploadAvatar(
+    @Path("id") id: String,
+    @Part avatar: MultipartBody.Part
+): AvatarDto
+
+// ✅ Build MultipartBody.Part from file
+fun File.toMultipartPart(partName: String): MultipartBody.Part {
+    val requestBody = asRequestBody("image/*".toMediaType())
+    return MultipartBody.Part.createFormData(partName, name, requestBody)
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Creating Retrofit instance per API call — expensive, use singleton
+- Returning `Response<T>` from API interface — wrap in `Result` at the repository level
+- Using `Call<T>` instead of `suspend` — unnecessary callback complexity
+- Adding auth token manually in each API function — use interceptor
+- Catching exceptions in ViewModel — handle in repository or use case
+- Using `Gson` converter — use Kotlinx Serialization
+
+---
+
+## Related Skills
+
+- `okhttp` — OkHttp client, interceptors, and connection config
+- `serialization` — JSON parsing with Kotlinx Serialization
+- `authentication` — token management and refresh
+- `retry-backoff` — retry logic for failed requests
+- `dto-mapping` — mapping API responses to domain models

package/skills/Networking/Retry-Backoff/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: retry-backoff
+description: >
+  Retry and exponential backoff strategies for network requests in Android.
+  Load this skill when implementing automatic retry for failed requests,
+  configuring backoff intervals, handling idempotency, or building
+  resilient network layers.
+---
+
+# Retry / Backoff
+
+## Overview
+Retry with exponential backoff improves resilience against transient network failures and temporary server errors. The key constraint is that only **idempotent** requests (GET, PUT, DELETE) should be retried automatically — POST requests must not be retried without explicit idempotency tokens.
+
+---
+
+## Core Principles
+
+- Only retry **idempotent** operations automatically — never POST without idempotency token
+- Use **exponential backoff** with jitter — prevents thundering herd on server recovery
+- Set a **maximum retry count** — don't retry indefinitely
+- Do not retry **4xx errors** (except 429) — they indicate a client error, not transient failure
+- Retry **5xx errors** and network errors (`IOException`) — these are transient
+
+---
+
+## Retryable Conditions
+
+| Condition | Retry? |
+|-----------|--------|
+| `IOException` (no internet) | ✅ Yes |
+| `500` Server Error | ✅ Yes |
+| `502` Bad Gateway | ✅ Yes |
+| `503` Service Unavailable | ✅ Yes |
+| `429` Too Many Requests | ✅ Yes (after Retry-After) |
+| `401` Unauthorized | ❌ No (handle via token refresh) |
+| `404` Not Found | ❌ No |
+| `400` Bad Request | ❌ No |
+
+---
+
+## Coroutine Retry Extension
+
+```kotlin
+// ✅ Generic retry with exponential backoff
+suspend fun <T> withRetry(
+    maxAttempts: Int = 3,
+    initialDelay: Long = 500L,
+    maxDelay: Long = 10_000L,
+    factor: Double = 2.0,
+    shouldRetry: (Throwable) -> Boolean = ::isRetryable,
+    block: suspend () -> T
+): T {
+    var currentDelay = initialDelay
+    repeat(maxAttempts - 1) { attempt ->
+        runCatching { block() }
+            .onSuccess { return it }
+            .onFailure { throwable ->
+                if (!shouldRetry(throwable)) throw throwable
+                val jitter = (0..200).random()
+                delay(currentDelay + jitter)
+                currentDelay = (currentDelay * factor).toLong().coerceAtMost(maxDelay)
+            }
+    }
+    return block()  // last attempt — let it throw
+}
+
+fun isRetryable(throwable: Throwable): Boolean {
+    return when (throwable) {
+        is IOException -> true
+        is HttpException -> throwable.code() in listOf(500, 502, 503, 504)
+        else -> false
+    }
+}
+```
+
+---
+
+## Usage in Repository
+
+```kotlin
+// ✅ Wrap idempotent calls with retry
+override suspend fun getUser(id: String): Result<User> = runCatching {
+    withRetry(maxAttempts = 3) {
+        api.getUser(id)
+    }.let { mapper.toDomain(it) }
+}
+
+// ✅ Non-idempotent — no automatic retry
+override suspend fun createUser(user: User): Result<User> = runCatching {
+    val dto = api.createUser(mapper.toRequest(user))  // no withRetry
+    mapper.toDomain(dto)
+}
+```
+
+---
+
+## OkHttp Retry Interceptor
+
+```kotlin
+// ✅ Network-level retry for transient failures
+class RetryInterceptor(
+    private val maxRetries: Int = 3
+) : Interceptor {
+    override fun intercept(chain: Interceptor.Chain): Response {
+        val request = chain.request()
+
+        // Only retry idempotent methods
+        if (request.method !in listOf("GET", "PUT", "DELETE", "HEAD")) {
+            return chain.proceed(request)
+        }
+
+        var attempt = 0
+        var lastException: IOException? = null
+
+        while (attempt < maxRetries) {
+            try {
+                val response = chain.proceed(request)
+                if (response.isSuccessful || response.code !in listOf(500, 502, 503)) {
+                    return response
+                }
+                response.close()
+            } catch (e: IOException) {
+                lastException = e
+            }
+
+            attempt++
+            if (attempt < maxRetries) {
+                val delay = (500L * 2.0.pow(attempt)).toLong().coerceAtMost(10_000L)
+                Thread.sleep(delay)
+            }
+        }
+
+        throw lastException ?: IOException("Max retries exceeded")
+    }
+}
+```
+
+---
+
+## 429 Too Many Requests Handling
+
+```kotlin
+// ✅ Respect Retry-After header on 429
+suspend fun <T> withRateLimitRetry(block: suspend () -> T): T {
+    while (true) {
+        val result = runCatching { block() }
+        result.onSuccess { return it }
+        result.onFailure { throwable ->
+            if (throwable is HttpException && throwable.code() == 429) {
+                val retryAfter = throwable.response()
+                    ?.headers()
+                    ?.get("Retry-After")
+                    ?.toLongOrNull()
+                    ?: 5L
+                delay(retryAfter * 1000)
+            } else {
+                throw throwable
+            }
+        }
+    }
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Retrying POST requests without idempotency keys — creates duplicate resources
+- Retrying 4xx errors — client errors won't resolve on retry
+- Fixed delay between retries — causes thundering herd; use backoff + jitter
+- Infinite retries — always cap with `maxAttempts`
+- Retrying inside the ViewModel — retry belongs in the repository or data source layer
+
+---
+
+## Related Skills
+- `okhttp` — network interceptor for retry at the HTTP level
+- `retrofit` — repository-level error handling
+- `fallback-strategy` — what to do after all retries are exhausted
+- `rate-limiting` — handling 429 responses

package/skills/Networking/Server-Sent Events (SSE)/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: server-sent-events
+description: >
+  Server-Sent Events (SSE) implementation in Android.
+  Load this skill when consuming a one-way real-time event stream from
+  the server, integrating SSE with AI streaming responses, handling
+  reconnection, or modeling SSE as a Flow.
+---
+
+# Server-Sent Events (SSE)
+
+## Overview
+Server-Sent Events (SSE) is a one-way, server-to-client streaming protocol over HTTP. Unlike WebSockets, SSE is unidirectional and uses standard HTTP — making it simpler and more firewall-friendly. It is commonly used for AI streaming responses (LLMs), live notifications, and real-time dashboards.
+
+---
+
+## Core Principles
+
+- SSE is one-way — use WebSocket if bidirectional communication is needed
+- Model the SSE stream as a `Flow` — integrates naturally with coroutines
+- Handle reconnection — SSE streams drop on network changes
+- Parse the `data:` field of each event — ignore comment lines (starting with `:`)
+- Close the connection when the lifecycle owner is destroyed
+
+---
+
+## OkHttp SSE Implementation
+
+```kotlin
+// ✅ SSE client wrapping OkHttp EventSource
+class SseClient @Inject constructor(
+    private val okHttpClient: OkHttpClient
+) {
+    fun connect(url: String, headers: Map<String, String> = emptyMap()): Flow<SseEvent> =
+        callbackFlow {
+            val request = Request.Builder()
+                .url(url)
+                .apply { headers.forEach { (k, v) -> addHeader(k, v) } }
+                .addHeader("Accept", "text/event-stream")
+                .addHeader("Cache-Control", "no-cache")
+                .build()
+
+            val listener = object : EventSourceListener() {
+                override fun onEvent(
+                    eventSource: EventSource,
+                    id: String?,
+                    type: String?,
+                    data: String
+                ) {
+                    trySend(SseEvent.Data(id = id, type = type, data = data))
+                }
+
+                override fun onFailure(
+                    eventSource: EventSource,
+                    t: Throwable?,
+                    response: Response?
+                ) {
+                    close(t ?: IOException("SSE connection failed"))
+                }
+
+                override fun onClosed(eventSource: EventSource) {
+                    trySend(SseEvent.Closed)
+                    close()
+                }
+            }
+
+            val eventSource = EventSources.createFactory(okHttpClient)
+                .newEventSource(request, listener)
+
+            awaitClose { eventSource.cancel() }
+        }
+}
+
+sealed interface SseEvent {
+    data class Data(val id: String?, val type: String?, val data: String) : SseEvent
+    data object Closed : SseEvent
+}
+```
+
+---
+
+## Manual SSE Parsing (Without EventSource)
+
+```kotlin
+// ✅ Parse SSE stream manually from OkHttp response body
+fun parseSSEStream(responseBody: ResponseBody): Flow<String> = flow {
+    responseBody.source().use { source ->
+        while (!source.exhausted()) {
+            val line = source.readUtf8Line() ?: break
+            when {
+                line.startsWith("data: ") -> emit(line.removePrefix("data: "))
+                line.startsWith(":") -> Unit  // comment — ignore
+                line.isEmpty() -> Unit        // event separator — ignore
+            }
+        }
+    }
+}
+
+// ✅ Usage with Retrofit streaming endpoint
+@Streaming
+@GET("chat/stream")
+suspend fun streamChat(@Query("prompt") prompt: String): ResponseBody
+```
+
+---
+
+## AI Streaming Response
+
+```kotlin
+// ✅ Stream LLM token-by-token response
+class ChatRepository @Inject constructor(
+    private val sseClient: SseClient,
+    private val tokenStorage: TokenStorage
+) {
+    fun streamCompletion(prompt: String): Flow<String> {
+        return sseClient.connect(
+            url = "${BuildConfig.BASE_URL}chat/completions",
+            headers = mapOf(
+                "Authorization" to "Bearer ${tokenStorage.getAccessToken()}"
+            )
+        )
+        .filterIsInstance<SseEvent.Data>()
+        .filter { it.data != "[DONE]" }
+        .mapNotNull { event ->
+            runCatching {
+                json.decodeFromString<CompletionChunkDto>(event.data)
+                    .choices.firstOrNull()?.delta?.content
+            }.getOrNull()
+        }
+    }
+}
+
+// ✅ Collect in ViewModel — append tokens to build response
+class ChatViewModel @Inject constructor(
+    private val chatRepository: ChatRepository
+) : ViewModel() {
+
+    private val _response = MutableStateFlow("")
+    val response: StateFlow<String> = _response.asStateFlow()
+
+    private val _isStreaming = MutableStateFlow(false)
+    val isStreaming: StateFlow<Boolean> = _isStreaming.asStateFlow()
+
+    fun sendMessage(prompt: String) {
+        viewModelScope.launch {
+            _response.value = ""
+            _isStreaming.value = true
+            chatRepository.streamCompletion(prompt)
+                .onCompletion { _isStreaming.value = false }
+                .catch { _isStreaming.value = false }
+                .collect { token ->
+                    _response.value += token
+                }
+        }
+    }
+}
+```
+
+---
+
+## Reconnection
+
+```kotlin
+// ✅ Auto-reconnect on failure with backoff
+fun connectWithReconnect(url: String, scope: CoroutineScope): Flow<SseEvent> = flow {
+    var attempt = 0
+    while (true) {
+        try {
+            emitAll(sseClient.connect(url))
+            attempt = 0  // reset on clean close
+        } catch (e: IOException) {
+            val delay = minOf(1_000L * (2.0.pow(attempt)).toLong(), 30_000L)
+            delay(delay)
+            attempt++
+        }
+    }
+}.flowOn(Dispatchers.IO)
+```
+
+---
+
+## Anti-Patterns
+
+- Using SSE for bidirectional communication — use WebSocket instead
+- Not closing the EventSource on lifecycle destroy — leaks the connection
+- Accumulating all SSE events in memory — process and discard each event
+- Not handling the `[DONE]` sentinel for AI streams — continues waiting indefinitely
+- Blocking the main thread while reading the stream — always on IO dispatcher
+
+---
+
+## Related Skills
+- `websocket` — bidirectional alternative to SSE
+- `okhttp` — HTTP client for SSE connections
+- `flow` — modeling streams with Kotlin Flow
+- `retrofit` — streaming response body with `@Streaming`