Expose transient vs fatal on persisted errors

payjoin-ffi/src/receive/error.rs

@@ -59,9 +59,15 @@ impl ReceiverCreateRequestError {
 #[derive(Debug, thiserror::Error, uniffi::Error)]
 #[error(transparent)]
 pub enum ReceiverPersistedError {
-    /// rust-payjoin receiver error
+    /// Transient rust-payjoin receiver error. No state transition was
+    /// persisted: the session remains in its previous state and the caller
+    /// may retry the same operation later.
     #[error(transparent)]
-    Receiver(ReceiverError),
+    Transient(ReceiverError),
+    /// Fatal rust-payjoin receiver error. The session was closed, or
+    /// transitioned to a terminal error state, and must not be retried.
+    #[error(transparent)]
+    Fatal(ReceiverError),
     /// Storage error that could occur at application storage layer
     #[error(transparent)]
     Storage(Arc<ImplementationError>),
@@ -87,12 +93,18 @@ macro_rules! impl_persisted_error_from {
                     if let Some(storage_err) = err.storage_error() {
                         return ReceiverPersistedError::from(ImplementationError::new(storage_err));
                     }
-                    return ReceiverPersistedError::Receiver(ReceiverError::Unexpected);
+                    return ReceiverPersistedError::Fatal(ReceiverError::Unexpected);
                 }
+                let transient = err.is_transient();
                 if let Some(api_err) = err.api_error() {
-                    return ReceiverPersistedError::Receiver($receiver_arm(api_err));
+                    let receiver_error = $receiver_arm(api_err);
+                    return if transient {
+                        ReceiverPersistedError::Transient(receiver_error)
+                    } else {
+                        ReceiverPersistedError::Fatal(receiver_error)
+                    };
                 }
-                ReceiverPersistedError::Receiver(ReceiverError::Unexpected)
+                ReceiverPersistedError::Fatal(ReceiverError::Unexpected)
             }
         }
     };

payjoin/src/core/persist.rs

@@ -760,6 +760,28 @@ where
             _ => None,
         }
     }
+
+    /// Whether this error was transient.
+    ///
+    /// A transient error means no state transition was persisted: the session
+    /// remains in its previous state and the caller may retry the same
+    /// operation later. Returns `false` for storage errors; use
+    /// [`Self::storage_error_ref`] to distinguish those.
+    pub fn is_transient(&self) -> bool {
+        matches!(self.0, InternalPersistedError::Api(ApiError::Transient(_)))
+    }
+
+    /// Whether this error was fatal.
+    ///
+    /// A fatal error means the session was closed, or transitioned to a
+    /// terminal error state, and must not be retried. Returns `false` for
+    /// storage errors; use [`Self::storage_error_ref`] to distinguish those.
+    pub fn is_fatal(&self) -> bool {
+        matches!(
+            self.0,
+            InternalPersistedError::Api(ApiError::Fatal(_) | ApiError::FatalWithState(_, _))
+        )
+    }
 }
 
 impl<ApiError: std::error::Error, StorageError: std::error::Error, ErrorState: fmt::Debug>
@@ -1592,18 +1614,35 @@ mod tests {
         );
         assert!(storage_error.storage_error_ref().is_some());
         assert!(storage_error.api_error_ref().is_none());
+        assert!(!storage_error.is_transient());
+        assert!(!storage_error.is_fatal());
 
         // Test Internal API error cases
         let fatal_error = PersistedError::<InMemoryTestError, InMemoryTestError>(
             InternalPersistedError::Api(ApiError::Fatal(api_err.clone())),
         );
         assert!(fatal_error.storage_error_ref().is_none());
         assert!(fatal_error.api_error_ref().is_some());
+        assert!(!fatal_error.is_transient());
+        assert!(fatal_error.is_fatal());
 
         let transient_error = PersistedError::<InMemoryTestError, InMemoryTestError>(
             InternalPersistedError::Api(ApiError::Transient(api_err.clone())),
         );
         assert!(transient_error.storage_error_ref().is_none());
         assert!(transient_error.api_error_ref().is_some());
+        assert!(transient_error.is_transient());
+        assert!(!transient_error.is_fatal());
+
+        let fatal_with_state_error = PersistedError::<InMemoryTestError, InMemoryTestError, String>(
+            InternalPersistedError::Api(ApiError::FatalWithState(
+                api_err.clone(),
+                "Error state".to_string(),
+            )),
+        );
+        assert!(fatal_with_state_error.storage_error_ref().is_none());
+        assert!(fatal_with_state_error.api_error_ref().is_some());
+        assert!(!fatal_with_state_error.is_transient());
+        assert!(fatal_with_state_error.is_fatal());
     }
 }