Implement CodedError system with NATA-XXXX error codes

CLAUDE.md

@@ -48,6 +48,18 @@ MVVM layered architecture following [Android Modern App Architecture](https://de
 - **Navigation routes**: Defined as extension functions on `NavGraphBuilder` (e.g., `shopListView()`, `navigateToShopDetail()`). Routes use type-safe navigation.
 - **Proto DataStore**: User preferences and NFC scan state are persisted via Protocol Buffers (lite).
 
+## Error Handling (CodedError System)
+All errors should use the `CodedError` interface. Error codes use the `NATA-XXXX` prefix (NativeAppTemplate Android).
+
+| Range | Type | Description |
+|-------|------|-------------|
+| NATA-1xxx | App/general errors | Unexpected errors, catch-all |
+| NATA-2xxx | API/network errors | HTTP request failures, parsing errors |
+| NATA-3xxx | NFC/scan errors | NFC tag read/write/scan failures |
+
+- New error types must implement `CodedError`
+- Use `codedDescription` (not `message` or `localizedMessage`) in all user-facing error messages — this prepends `[NATA-XXXX]` for `CodedError` types
+
 ## Testing
 
 - Tests use JUnit 4 with `kotlinx.coroutines.test` and Robolectric.

app/src/main/kotlin/com/nativeapptemplate/nativeapptemplatefree/MainActivityViewModel.kt

@@ -5,6 +5,7 @@ import androidx.lifecycle.ViewModel
 import androidx.lifecycle.viewModelScope
 import com.nativeapptemplate.nativeapptemplatefree.MainActivityUiState.Loading
 import com.nativeapptemplate.nativeapptemplatefree.MainActivityUiState.Success
+import com.nativeapptemplate.nativeapptemplatefree.common.errors.codedDescription
 import com.nativeapptemplate.nativeapptemplatefree.data.login.LoginRepository
 import com.nativeapptemplate.nativeapptemplatefree.model.CompleteScanResult
 import com.nativeapptemplate.nativeapptemplatefree.model.CompleteScanResultType
@@ -125,8 +126,8 @@ class MainActivityViewModel @Inject constructor(
       try {
         loginRepository.setCompleteScanResult(completeScanResult)
       } catch (exception: Exception) {
-        val message = exception.message
-        completeScanResult.message = message ?: "Unknown Error"
+        val message = exception.codedDescription
+        completeScanResult.message = message
         completeScanResult.completeScanResultType = CompleteScanResultType.Failed
 
         loginRepository.setCompleteScanResult(completeScanResult)

app/src/main/kotlin/com/nativeapptemplate/nativeapptemplatefree/common/errors/ApiException.kt

@@ -0,0 +1,21 @@
+package com.nativeapptemplate.nativeapptemplatefree.common.errors
+
+sealed class ApiException(message: String, cause: Throwable? = null) :
+  Exception(message, cause), CodedError {
+
+  class ApiError(
+    val code: Int,
+    val apiMessage: String,
+  ) : ApiException("$apiMessage [Status: $code]") {
+    override val errorCode: String = "NATA-2001"
+    override val errorDescription: String = "$apiMessage [Status: $code]"
+  }
+
+  class UnprocessableError(
+    val rawMessage: String,
+    cause: Throwable? = null,
+  ) : ApiException("Not processable error($rawMessage).", cause) {
+    override val errorCode: String = "NATA-2002"
+    override val errorDescription: String = "Processing error: $rawMessage"
+  }
+}

app/src/main/kotlin/com/nativeapptemplate/nativeapptemplatefree/common/errors/AppError.kt

@@ -0,0 +1,12 @@
+package com.nativeapptemplate.nativeapptemplatefree.common.errors
+
+sealed class AppError(
+  override val errorCode: String,
+  override val errorDescription: String,
+) : Exception(errorDescription), CodedError {
+
+  class Unexpected(detail: String? = null) : AppError(
+    errorCode = "NATA-1001",
+    errorDescription = "Unexpected error" + if (detail != null) ": $detail" else "",
+  )
+}

app/src/main/kotlin/com/nativeapptemplate/nativeapptemplatefree/common/errors/CodedError.kt

@@ -0,0 +1,11 @@
+package com.nativeapptemplate.nativeapptemplatefree.common.errors
+
+interface CodedError {
+  val errorCode: String
+  val errorDescription: String
+  val formattedDescription: String
+    get() = "[$errorCode] $errorDescription"
+}
+
+val Throwable.codedDescription: String
+  get() = (this as? CodedError)?.formattedDescription ?: message ?: "Unknown Error"

app/src/main/kotlin/com/nativeapptemplate/nativeapptemplatefree/common/errors/NfcError.kt

@@ -0,0 +1,12 @@
+package com.nativeapptemplate.nativeapptemplatefree.common.errors
+
+sealed class NfcError(
+  override val errorCode: String,
+  override val errorDescription: String,
+) : Exception(errorDescription), CodedError {
+
+  class ScanFailed(detail: String? = null) : NfcError(
+    errorCode = "NATA-3001",
+    errorDescription = "NFC scan operation failed" + if (detail != null) ": $detail" else "",
+  )
+}

app/src/main/kotlin/com/nativeapptemplate/nativeapptemplatefree/data/login/LoginRepositoryImpl.kt

@@ -1,11 +1,11 @@
 package com.nativeapptemplate.nativeapptemplatefree.data.login
 
 import androidx.annotation.VisibleForTesting
+import com.nativeapptemplate.nativeapptemplatefree.common.errors.ApiException
 import com.nativeapptemplate.nativeapptemplatefree.datastore.NatPreferencesDataSource
 import com.nativeapptemplate.nativeapptemplatefree.model.*
 import com.nativeapptemplate.nativeapptemplatefree.model.LoggedInShopkeeper
 import com.nativeapptemplate.nativeapptemplatefree.model.Login
-import com.nativeapptemplate.nativeapptemplatefree.network.ApiException
 import com.nativeapptemplate.nativeapptemplatefree.network.Dispatcher
 import com.nativeapptemplate.nativeapptemplatefree.network.NatDispatchers
 import com.nativeapptemplate.nativeapptemplatefree.network.emitApiResponse

app/src/main/kotlin/com/nativeapptemplate/nativeapptemplatefree/network/ApiResponseExtensions.kt

@@ -1,5 +1,6 @@
 package com.nativeapptemplate.nativeapptemplatefree.network
 
+import com.nativeapptemplate.nativeapptemplatefree.common.errors.ApiException
 import com.nativeapptemplate.nativeapptemplatefree.model.NativeAppTemplateApiError
 import com.skydoves.sandwich.ApiResponse
 import com.skydoves.sandwich.message

app/src/main/kotlin/com/nativeapptemplate/nativeapptemplatefree/ui/app_root/AcceptPrivacyViewModel.kt

@@ -2,6 +2,7 @@ package com.nativeapptemplate.nativeapptemplatefree.ui.app_root
 
 import androidx.lifecycle.ViewModel
 import androidx.lifecycle.viewModelScope
+import com.nativeapptemplate.nativeapptemplatefree.common.errors.codedDescription
 import com.nativeapptemplate.nativeapptemplatefree.data.login.LoginRepository
 import dagger.hilt.android.lifecycle.HiltViewModel
 import kotlinx.coroutines.flow.MutableStateFlow
@@ -41,10 +42,10 @@ class AcceptPrivacyViewModel @Inject constructor(
 
       booleanFlow
         .catch { exception ->
-          val message = exception.message
+          val message = exception.codedDescription
           _uiState.update {
             it.copy(
-              message = message ?: "Unknown Error",
+              message = message,
               isLoading = false,
             )
           }

app/src/main/kotlin/com/nativeapptemplate/nativeapptemplatefree/ui/app_root/AcceptTermsViewModel.kt

@@ -2,6 +2,7 @@ package com.nativeapptemplate.nativeapptemplatefree.ui.app_root
 
 import androidx.lifecycle.ViewModel
 import androidx.lifecycle.viewModelScope
+import com.nativeapptemplate.nativeapptemplatefree.common.errors.codedDescription
 import com.nativeapptemplate.nativeapptemplatefree.data.login.LoginRepository
 import dagger.hilt.android.lifecycle.HiltViewModel
 import kotlinx.coroutines.flow.MutableStateFlow
@@ -41,10 +42,10 @@ class AcceptTermsViewModel @Inject constructor(
 
       booleanFlow
         .catch { exception ->
-          val message = exception.message
+          val message = exception.codedDescription
           _uiState.update {
             it.copy(
-              message = message ?: "Unknown Error",
+              message = message,
               isLoading = false,
             )
           }

app/src/main/kotlin/com/nativeapptemplate/nativeapptemplatefree/ui/app_root/ForgotPasswordViewModel.kt

@@ -3,6 +3,7 @@ package com.nativeapptemplate.nativeapptemplatefree.ui.app_root
 import androidx.lifecycle.ViewModel
 import androidx.lifecycle.viewModelScope
 import com.nativeapptemplate.nativeapptemplatefree.NatConstants
+import com.nativeapptemplate.nativeapptemplatefree.common.errors.codedDescription
 import com.nativeapptemplate.nativeapptemplatefree.data.login.SignUpRepository
 import com.nativeapptemplate.nativeapptemplatefree.model.SendResetPassword
 import com.nativeapptemplate.nativeapptemplatefree.utils.Utility.validateEmail
@@ -49,10 +50,10 @@ class ForgotPasswordViewModel @Inject constructor(
 
       booleanFlow
         .catch { exception ->
-          val message = exception.message
+          val message = exception.codedDescription
           _uiState.update {
             it.copy(
-              message = message ?: "Unknown Error",
+              message = message,
               isLoading = false,
             )
           }

app/src/main/kotlin/com/nativeapptemplate/nativeapptemplatefree/ui/app_root/ResendConfirmationInstructionsViewModel.kt

@@ -3,6 +3,7 @@ package com.nativeapptemplate.nativeapptemplatefree.ui.app_root
 import androidx.lifecycle.ViewModel
 import androidx.lifecycle.viewModelScope
 import com.nativeapptemplate.nativeapptemplatefree.NatConstants
+import com.nativeapptemplate.nativeapptemplatefree.common.errors.codedDescription
 import com.nativeapptemplate.nativeapptemplatefree.data.login.SignUpRepository
 import com.nativeapptemplate.nativeapptemplatefree.model.SendConfirmation
 import com.nativeapptemplate.nativeapptemplatefree.utils.Utility.validateEmail
@@ -49,10 +50,10 @@ class ResendConfirmationInstructionsViewModel @Inject constructor(
 
       booleanFlow
         .catch { exception ->
-          val message = exception.message
+          val message = exception.codedDescription
           _uiState.update {
             it.copy(
-              message = message ?: "Unknown Error",
+              message = message,
               isLoading = false,
             )
           }

app/src/main/kotlin/com/nativeapptemplate/nativeapptemplatefree/ui/app_root/SignInEmailAndPasswordViewModel.kt

@@ -4,6 +4,7 @@ import android.util.Log
 import androidx.lifecycle.ViewModel
 import androidx.lifecycle.viewModelScope
 import com.nativeapptemplate.nativeapptemplatefree.NatConstants
+import com.nativeapptemplate.nativeapptemplatefree.common.errors.codedDescription
 import com.nativeapptemplate.nativeapptemplatefree.data.login.LoginRepository
 import com.nativeapptemplate.nativeapptemplatefree.model.LoggedInShopkeeper
 import com.nativeapptemplate.nativeapptemplatefree.model.Login
@@ -49,10 +50,10 @@ class SignInEmailAndPasswordViewModel @Inject constructor(
 
       loggedInShopkeeperFlow
         .catch { exception ->
-          val message = exception.message
+          val message = exception.codedDescription
           _uiState.update {
             it.copy(
-              message = message ?: "Unknown Error",
+              message = message,
               isLoading = false,
             )
           }

app/src/main/kotlin/com/nativeapptemplate/nativeapptemplatefree/ui/app_root/SignUpViewModel.kt

@@ -3,6 +3,7 @@ package com.nativeapptemplate.nativeapptemplatefree.ui.app_root
 import androidx.lifecycle.ViewModel
 import androidx.lifecycle.viewModelScope
 import com.nativeapptemplate.nativeapptemplatefree.NatConstants
+import com.nativeapptemplate.nativeapptemplatefree.common.errors.codedDescription
 import com.nativeapptemplate.nativeapptemplatefree.data.login.SignUpRepository
 import com.nativeapptemplate.nativeapptemplatefree.model.SignUp
 import com.nativeapptemplate.nativeapptemplatefree.model.TimeZones
@@ -56,10 +57,10 @@ class SignUpViewModel @Inject constructor(
 
       loggedInShopkeeperFlow
         .catch { exception ->
-          val message = exception.message
+          val message = exception.codedDescription
           _uiState.update {
             it.copy(
-              message = message ?: "Unknown Error",
+              message = message,
               isLoading = false,
             )
           }

app/src/main/kotlin/com/nativeapptemplate/nativeapptemplatefree/ui/scan/DoScanViewModel.kt

@@ -5,6 +5,7 @@ import androidx.lifecycle.SavedStateHandle
 import androidx.lifecycle.ViewModel
 import androidx.lifecycle.viewModelScope
 import androidx.navigation.toRoute
+import com.nativeapptemplate.nativeapptemplatefree.common.errors.codedDescription
 import com.nativeapptemplate.nativeapptemplatefree.data.login.LoginRepository
 import com.nativeapptemplate.nativeapptemplatefree.model.CompleteScanResult
 import com.nativeapptemplate.nativeapptemplatefree.model.CompleteScanResultType
@@ -53,8 +54,8 @@ class DoScanViewModel @Inject constructor(
         try {
           loginRepository.setShowTagInfoScanResult(showTagInfoScanResult)
         } catch (exception: Exception) {
-          val message = exception.message
-          showTagInfoScanResult.message = message ?: "Unknown Error"
+          val message = exception.codedDescription
+          showTagInfoScanResult.message = message
           showTagInfoScanResult.showTagInfoScanResultType = ShowTagInfoScanResultType.Failed
 
           loginRepository.setShowTagInfoScanResult(showTagInfoScanResult)
@@ -73,8 +74,8 @@ class DoScanViewModel @Inject constructor(
         try {
           loginRepository.setCompleteScanResult(completeScanResult)
         } catch (exception: Exception) {
-          val message = exception.message
-          completeScanResult.message = message ?: "Unknown Error"
+          val message = exception.codedDescription
+          completeScanResult.message = message
           completeScanResult.completeScanResultType = CompleteScanResultType.Failed
 
           loginRepository.setCompleteScanResult(completeScanResult)

app/src/main/kotlin/com/nativeapptemplate/nativeapptemplatefree/ui/scan/ScanViewModel.kt

@@ -2,6 +2,7 @@ package com.nativeapptemplate.nativeapptemplatefree.ui.scan
 
 import androidx.lifecycle.ViewModel
 import androidx.lifecycle.viewModelScope
+import com.nativeapptemplate.nativeapptemplatefree.common.errors.codedDescription
 import com.nativeapptemplate.nativeapptemplatefree.data.item_tag.ItemTagRepository
 import com.nativeapptemplate.nativeapptemplatefree.data.login.LoginRepository
 import com.nativeapptemplate.nativeapptemplatefree.model.CompleteScanResult
@@ -86,10 +87,10 @@ class ScanViewModel @Inject constructor(
           )
         }
       }.catch { exception ->
-        val message = exception.message
+        val message = exception.codedDescription
         _uiState.update {
           it.copy(
-            message = message ?: "Unknown Error",
+            message = message,
             isLoading = false,
           )
         }
@@ -109,10 +110,10 @@ class ScanViewModel @Inject constructor(
 
       itemTagFlow
         .catch { exception ->
-          val message = exception.message
+          val message = exception.codedDescription
           val showTagInfoScanResult = uiState.value.showTagInfoScanResult
           showTagInfoScanResult.showTagInfoScanResultType = ShowTagInfoScanResultType.Failed
-          showTagInfoScanResult.message = message ?: "Unknown Error"
+          showTagInfoScanResult.message = message
 
           loginRepository.setShowTagInfoScanResult(showTagInfoScanResult)
 
@@ -160,10 +161,10 @@ class ScanViewModel @Inject constructor(
 
       itemTagFlow
         .catch { exception ->
-          val message = exception.message
+          val message = exception.codedDescription
           val completeScanResult = uiState.value.completeScanResult
           completeScanResult.completeScanResultType = CompleteScanResultType.Failed
-          completeScanResult.message = message ?: "Unknown Error"
+          completeScanResult.message = message
 
           loginRepository.setCompleteScanResult(completeScanResult)
 
@@ -214,10 +215,10 @@ class ScanViewModel @Inject constructor(
 
       itemTagFlow
         .catch { exception ->
-          val message = exception.message
+          val message = exception.codedDescription
           val completeScanResult = uiState.value.completeScanResult
           completeScanResult.completeScanResultType = CompleteScanResultType.Failed
-          completeScanResult.message = message ?: "Unknown Error"
+          completeScanResult.message = message
 
           loginRepository.setCompleteScanResult(completeScanResult)
 

app/src/main/kotlin/com/nativeapptemplate/nativeapptemplatefree/ui/settings/PasswordEditViewModel.kt

@@ -3,6 +3,7 @@ package com.nativeapptemplate.nativeapptemplatefree.ui.settings
 import androidx.lifecycle.ViewModel
 import androidx.lifecycle.viewModelScope
 import com.nativeapptemplate.nativeapptemplatefree.NatConstants
+import com.nativeapptemplate.nativeapptemplatefree.common.errors.codedDescription
 import com.nativeapptemplate.nativeapptemplatefree.data.login.AccountPasswordRepository
 import com.nativeapptemplate.nativeapptemplatefree.model.UpdatePasswordBody
 import com.nativeapptemplate.nativeapptemplatefree.model.UpdatePasswordBodyDetail
@@ -53,10 +54,10 @@ class PasswordEditViewModel @Inject constructor(
 
       booleanFlow
         .catch { exception ->
-          val message = exception.message
+          val message = exception.codedDescription
           _uiState.update {
             it.copy(
-              message = message ?: "Unknown Error",
+              message = message,
               isLoading = false,
             )
           }