android-sdd 1.0.0

package/skills/Networking/OkHttp/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: okhttp
+description: >
+  OkHttp client configuration and interceptor patterns for Android.
+  Load this skill when configuring OkHttp, writing custom interceptors,
+  setting up caching, managing timeouts, handling connection pooling,
+  or debugging HTTP traffic.
+---
+
+# OkHttp
+
+## Overview
+OkHttp is the HTTP engine underneath Retrofit. It manages connection pooling, caching, interceptors, and TLS configuration. Correct OkHttp setup is critical for performance, security, and reliability.
+
+---
+
+## Core Principles
+
+- One `OkHttpClient` instance shared across all Retrofit instances — it manages the connection pool
+- Use **interceptors** for cross-cutting concerns: auth, logging, retry, headers
+- Configure **timeouts** explicitly — never rely on defaults in production
+- Use `Cache` for GET responses to reduce bandwidth and improve offline resilience
+- Never block the OkHttp thread inside an interceptor — use coroutines at the repository level
+
+---
+
+## Client Setup
+
+```kotlin
+// ✅ Full OkHttpClient configuration
+@Provides
+@Singleton
+fun provideOkHttpClient(
+    authInterceptor: AuthInterceptor,
+    loggingInterceptor: HttpLoggingInterceptor,
+    cache: Cache
+): OkHttpClient {
+    return OkHttpClient.Builder()
+        // Interceptors (order matters — application interceptors first)
+        .addInterceptor(authInterceptor)
+        .addInterceptor(loggingInterceptor)
+        // Timeouts
+        .connectTimeout(30, TimeUnit.SECONDS)
+        .readTimeout(30, TimeUnit.SECONDS)
+        .writeTimeout(30, TimeUnit.SECONDS)
+        .callTimeout(60, TimeUnit.SECONDS)
+        // Cache
+        .cache(cache)
+        // Connection pool
+        .connectionPool(ConnectionPool(5, 5, TimeUnit.MINUTES))
+        .build()
+}
+
+@Provides
+@Singleton
+fun provideCache(@ApplicationContext context: Context): Cache {
+    val cacheSize = 10L * 1024 * 1024  // 10 MB
+    return Cache(context.cacheDir, cacheSize)
+}
+```
+
+---
+
+## Interceptor Types
+
+```
+Application Interceptors (addInterceptor)
+  → Run before the request hits the network
+  → See the original request and final response
+  → Good for: auth headers, logging, retry
+
+Network Interceptors (addNetworkInterceptor)
+  → Run after redirects and cache decisions
+  → See the actual network request/response
+  → Good for: cache control headers, compression
+```
+
+---
+
+## Custom Interceptors
+
+```kotlin
+// ✅ Header interceptor — add common headers to every request
+class CommonHeadersInterceptor @Inject constructor(
+    private val appVersionProvider: AppVersionProvider
+) : Interceptor {
+    override fun intercept(chain: Interceptor.Chain): Response {
+        val request = chain.request().newBuilder()
+            .addHeader("X-App-Version", appVersionProvider.version)
+            .addHeader("X-Platform", "android")
+            .addHeader("Accept-Language", Locale.getDefault().language)
+            .build()
+        return chain.proceed(request)
+    }
+}
+
+// ✅ Token refresh interceptor — handle 401 by refreshing token
+class TokenRefreshInterceptor @Inject constructor(
+    private val tokenRepository: TokenRepository
+) : Interceptor {
+    override fun intercept(chain: Interceptor.Chain): Response {
+        val response = chain.proceed(chain.request())
+
+        if (response.code == 401) {
+            response.close()
+            val newToken = runBlocking { tokenRepository.refreshToken() }
+            if (newToken != null) {
+                val newRequest = chain.request().newBuilder()
+                    .header("Authorization", "Bearer $newToken")
+                    .build()
+                return chain.proceed(newRequest)
+            }
+        }
+        return response
+    }
+}
+
+// ✅ Cache control interceptor — force cache for specific endpoints
+class CacheControlInterceptor : Interceptor {
+    override fun intercept(chain: Interceptor.Chain): Response {
+        val response = chain.proceed(chain.request())
+        return if (chain.request().url.pathSegments.contains("static")) {
+            response.newBuilder()
+                .header("Cache-Control", "public, max-age=86400")  // 1 day
+                .build()
+        } else {
+            response
+        }
+    }
+}
+```
+
+---
+
+## Logging Interceptor
+
+```kotlin
+// ✅ Debug-only logging — never log in release
+@Provides
+@Singleton
+fun provideLoggingInterceptor(): HttpLoggingInterceptor {
+    return HttpLoggingInterceptor { message ->
+        Timber.tag("OkHttp").d(message)
+    }.apply {
+        level = if (BuildConfig.DEBUG)
+            HttpLoggingInterceptor.Level.BODY
+        else
+            HttpLoggingInterceptor.Level.NONE
+    }
+}
+```
+
+---
+
+## Response Extension
+
+```kotlin
+// ✅ Safe response body parsing
+fun Response.bodyOrThrow(): String {
+    return body?.string() ?: throw IOException("Empty response body")
+}
+
+fun Response.isSuccess(): Boolean = code in 200..299
+```
+
+---
+
+## Timeout Strategy
+
+| Timeout | Recommended | Use Case |
+|---------|-------------|----------|
+| `connectTimeout` | 15–30s | Establishing TCP connection |
+| `readTimeout` | 30–60s | Reading response body |
+| `writeTimeout` | 30–60s | Sending request body |
+| `callTimeout` | 60–120s | Entire call including redirects |
+
+---
+
+## Anti-Patterns
+
+- Creating a new `OkHttpClient` per request — destroys connection pool benefits
+- Using `runBlocking` inside interceptors for non-token-refresh logic — blocks threads
+- Logging request bodies in release builds — security risk
+- Setting `callTimeout` too low for file upload/download endpoints
+- Adding too many interceptors in sequence that each read the response body — body can only be read once
+
+---
+
+## Related Skills
+- `retrofit` — Retrofit setup on top of OkHttp
+- `authentication` — token management and refresh flow
+- `certificate-pinning` — TLS security via OkHttp
+- `retry-backoff` — retry interceptor patterns

package/skills/Networking/REST/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: rest
+description: >
+  REST API design principles and consumption patterns for Android.
+  Load this skill when designing API contracts, structuring HTTP requests,
+  handling standard HTTP status codes, modeling API responses,
+  or understanding REST conventions used in the data layer.
+---
+
+# REST
+
+## Overview
+REST (Representational State Transfer) is the standard architectural style for HTTP APIs. Understanding REST conventions ensures the data layer handles responses, errors, and status codes correctly and consistently.
+
+---
+
+## Core Principles
+
+- Use the correct HTTP method for each operation — GET, POST, PUT, PATCH, DELETE
+- Map HTTP status codes to domain errors — never ignore non-2xx responses
+- Use query parameters for filtering/sorting/pagination — path parameters for resource identity
+- Requests and responses use consistent naming — snake_case in JSON, camelCase in Kotlin DTOs
+- Idempotent operations (GET, PUT, DELETE) are safe to retry — non-idempotent (POST) are not
+
+---
+
+## HTTP Method Mapping
+
+| Method | Use For | Idempotent |
+|--------|---------|------------|
+| `GET` | Fetch resource(s) | ✅ Yes |
+| `POST` | Create new resource | ❌ No |
+| `PUT` | Replace entire resource | ✅ Yes |
+| `PATCH` | Partial update | ❌ No |
+| `DELETE` | Remove resource | ✅ Yes |
+
+---
+
+## Standard Endpoints Pattern
+
+```
+GET    /users           → list users
+POST   /users           → create user
+GET    /users/{id}      → get user by id
+PUT    /users/{id}      → replace user
+PATCH  /users/{id}      → partial update user
+DELETE /users/{id}      → delete user
+
+GET    /users/{id}/posts         → posts belonging to user
+POST   /users/{id}/posts         → create post for user
+```
+
+---
+
+## HTTP Status Code Handling
+
+```kotlin
+// ✅ Map status codes to domain errors
+sealed class ApiError : Exception() {
+    data class BadRequest(override val message: String) : ApiError()         // 400
+    data class Unauthorized(override val message: String) : ApiError()      // 401
+    data class Forbidden(override val message: String) : ApiError()         // 403
+    data class NotFound(override val message: String) : ApiError()          // 404
+    data class Conflict(override val message: String) : ApiError()          // 409
+    data class UnprocessableEntity(val errors: Map<String, List<String>>) : ApiError() // 422
+    data class TooManyRequests(val retryAfter: Int?) : ApiError()            // 429
+    data class ServerError(val code: Int) : ApiError()                      // 5xx
+}
+
+// ✅ Map HttpException to ApiError
+fun HttpException.toApiError(): ApiError {
+    return when (code()) {
+        400 -> ApiError.BadRequest(parseErrorMessage())
+        401 -> ApiError.Unauthorized(parseErrorMessage())
+        403 -> ApiError.Forbidden(parseErrorMessage())
+        404 -> ApiError.NotFound(parseErrorMessage())
+        409 -> ApiError.Conflict(parseErrorMessage())
+        422 -> ApiError.UnprocessableEntity(parseValidationErrors())
+        429 -> ApiError.TooManyRequests(response()?.headers()?.get("Retry-After")?.toIntOrNull())
+        in 500..599 -> ApiError.ServerError(code())
+        else -> ApiError.ServerError(code())
+    }
+}
+```
+
+---
+
+## Pagination Patterns
+
+```kotlin
+// ✅ Offset-based pagination
+@GET("users")
+suspend fun getUsers(
+    @Query("page") page: Int,
+    @Query("limit") limit: Int = 20
+): PagedResponse<UserDto>
+
+@Serializable
+data class PagedResponse<T>(
+    val data: List<T>,
+    val total: Int,
+    val page: Int,
+    val limit: Int,
+    val hasMore: Boolean
+)
+
+// ✅ Cursor-based pagination
+@GET("feed")
+suspend fun getFeed(
+    @Query("cursor") cursor: String? = null,
+    @Query("limit") limit: Int = 20
+): CursorPagedResponse<FeedItemDto>
+
+@Serializable
+data class CursorPagedResponse<T>(
+    val data: List<T>,
+    val nextCursor: String?,
+    val hasMore: Boolean
+)
+```
+
+---
+
+## Standard Response Envelope
+
+```kotlin
+// ✅ Consistent API envelope — if the API uses one
+@Serializable
+data class ApiResponse<T>(
+    val success: Boolean,
+    val data: T? = null,
+    val error: ApiErrorDto? = null,
+    val message: String? = null
+)
+
+@Serializable
+data class ApiErrorDto(
+    val code: String,
+    val message: String,
+    val details: Map<String, List<String>> = emptyMap()
+)
+```
+
+---
+
+## Query Parameter Conventions
+
+```kotlin
+// ✅ Common query parameter patterns
+@GET("users")
+suspend fun getUsers(
+    @Query("q") search: String? = null,         // search
+    @Query("sort") sort: String? = "created_at", // sort field
+    @Query("order") order: String? = "desc",     // sort direction
+    @Query("filter[status]") status: String? = null,  // filtering
+    @Query("page") page: Int = 1,
+    @Query("limit") limit: Int = 20
+): PagedResponse<UserDto>
+```
+
+---
+
+## Anti-Patterns
+
+- Using `GET` for operations with side effects — use `POST` or `DELETE`
+- Ignoring HTTP status codes — check response codes, don't assume 200
+- Putting sensitive data in query parameters — use request body or headers
+- Using `POST` for reads — breaks caching and idempotency
+- Returning `200 OK` for errors with error details in the body — use correct status codes
+
+---
+
+## Related Skills
+- `retrofit` — implementing REST calls with Retrofit
+- `api-contract` — formal API contract definition
+- `authentication` — auth headers and token handling
+- `retry-backoff` — safe retry for idempotent requests
+- `dto-mapping` — mapping REST responses to domain models

package/skills/Networking/Rate Limiting/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: rate-limiting
+description: >
+  Handling rate limiting (HTTP 429) and implementing client-side request
+  throttling in Android. Load this skill when handling 429 Too Many Requests
+  responses, respecting Retry-After headers, implementing request queuing,
+  or throttling outgoing requests to avoid hitting server limits.
+---
+
+# Rate Limiting
+
+## Overview
+Rate limiting occurs when the server rejects requests because the client has exceeded the allowed request frequency. On Android, this is handled in two ways: reacting to 429 responses from the server, and proactively throttling client-side requests to avoid hitting the limit.
+
+---
+
+## Core Principles
+
+- Always respect the `Retry-After` header when present — don't guess the delay
+- Implement **client-side throttling** for high-frequency operations (search, autocomplete)
+- Use a **single retry** for 429 — not an infinite loop
+- Log rate limit events — they indicate either a bug or a need to adjust request frequency
+- Debounce user-driven requests (search input) before they reach the network
+
+---
+
+## Handling 429 Server Response
+
+```kotlin
+// ✅ 429 handler in repository
+suspend fun <T> withRateLimitHandling(block: suspend () -> T): Result<T> {
+    return runCatching { block() }
+        .recoverCatching { throwable ->
+            if (throwable is HttpException && throwable.code() == 429) {
+                val retryAfterSeconds = throwable.response()
+                    ?.headers()
+                    ?.get("Retry-After")
+                    ?.toLongOrNull()
+                    ?: 10L  // default 10 seconds if header missing
+
+                delay(retryAfterSeconds * 1_000)
+                block()  // single retry after waiting
+            } else {
+                throw throwable
+            }
+        }
+}
+
+// ✅ Usage
+override suspend fun searchUsers(query: String): Result<List<User>> =
+    withRateLimitHandling {
+        api.searchUsers(query).map { mapper.toDomain(it) }
+    }
+```
+
+---
+
+## OkHttp Rate Limit Interceptor
+
+```kotlin
+// ✅ Intercept 429 at the HTTP level
+class RateLimitInterceptor : Interceptor {
+    override fun intercept(chain: Interceptor.Chain): Response {
+        val response = chain.proceed(chain.request())
+
+        if (response.code == 429) {
+            val retryAfter = response.headers["Retry-After"]?.toLongOrNull() ?: 10L
+            response.close()
+            Thread.sleep(retryAfter * 1_000)
+            return chain.proceed(chain.request())
+        }
+
+        return response
+    }
+}
+```
+
+---
+
+## Client-Side Debouncing (Search / Autocomplete)
+
+```kotlin
+// ✅ Debounce search input in ViewModel — reduce API calls
+class SearchViewModel @Inject constructor(
+    private val searchUseCase: SearchUsersUseCase
+) : ViewModel() {
+
+    private val _query = MutableStateFlow("")
+    private val _results = MutableStateFlow<UiState<List<User>>>(UiState.Loading)
+    val results: StateFlow<UiState<List<User>>> = _results.asStateFlow()
+
+    init {
+        viewModelScope.launch {
+            _query
+                .debounce(300)              // ✅ wait 300ms after last keystroke
+                .filter { it.length >= 2 }  // ✅ minimum query length
+                .distinctUntilChanged()     // ✅ skip duplicate queries
+                .collectLatest { query ->   // ✅ cancel previous in-flight request
+                    _results.value = UiState.Loading
+                    searchUseCase(query).fold(
+                        onSuccess = { _results.value = UiState.Success(it) },
+                        onFailure = { _results.value = UiState.Error(it.message ?: "Error") }
+                    )
+                }
+        }
+    }
+
+    fun onQueryChange(query: String) {
+        _query.value = query
+    }
+}
+```
+
+---
+
+## Request Throttler (Token Bucket)
+
+```kotlin
+// ✅ Token bucket throttler — max N requests per window
+class RequestThrottler(
+    private val maxRequests: Int = 10,
+    private val windowMs: Long = 1_000L
+) {
+    private val mutex = Mutex()
+    private val timestamps = ArrayDeque<Long>()
+
+    suspend fun throttle() {
+        mutex.withLock {
+            val now = System.currentTimeMillis()
+            // remove timestamps outside the window
+            while (timestamps.isNotEmpty() && now - timestamps.first() > windowMs) {
+                timestamps.removeFirst()
+            }
+            if (timestamps.size >= maxRequests) {
+                val waitMs = windowMs - (now - timestamps.first())
+                delay(waitMs)
+            }
+            timestamps.addLast(System.currentTimeMillis())
+        }
+    }
+}
+
+// ✅ Usage
+class AnalyticsDataSource @Inject constructor(
+    private val throttler: RequestThrottler
+) {
+    suspend fun trackEvent(event: AnalyticsEvent) {
+        throttler.throttle()
+        api.track(event)
+    }
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Retrying 429 immediately without delay — will get another 429 immediately
+- Ignoring the `Retry-After` header — use the server-specified delay
+- Not debouncing search input — fires a request on every keystroke
+- Infinite retry loop on 429 — cap at one retry after the wait
+- Using `Thread.sleep` in coroutine context — use `delay` instead
+
+---
+
+## Related Skills
+- `retry-backoff` — general retry strategy for transient failures
+- `okhttp` — interceptor setup for HTTP-level handling
+- `flow` — debounce and distinctUntilChanged operators
+- `fallback-strategy` — what to do when rate limit retries fail