From 511b88b23b429f88313e07cae74458bf2d758e92 Mon Sep 17 00:00:00 2001
From: init4samwise <samwise@init4.technology>
Date: Fri, 6 Feb 2026 16:40:19 +0000
Subject: [PATCH 1/3] feat(tx_cache): surface auth token retrieval errors

ENG-1798: Add BuilderTxCacheError enum to properly surface auth token
retrieval failures instead of silently using an empty string.

Changes:
- Add BuilderTxCacheError with TokenRetrieval variant wrapping RecvError
- Add TxCache variant wrapping existing TxCacheError
- Replace unwrap_or_else with ? operator to propagate errors
- Update local Result type alias to use BuilderTxCacheError

This is a breaking change for consumers that expect the old Result type,
but surfaces the actual error cause for better debugging.
---
 src/perms/tx_cache.rs | 26 ++++++++++++++++++++------
 1 file changed, 20 insertions(+), 6 deletions(-)

diff --git a/src/perms/tx_cache.rs b/src/perms/tx_cache.rs
index 954bf3c..905cbdd 100644
--- a/src/perms/tx_cache.rs
+++ b/src/perms/tx_cache.rs
@@ -1,11 +1,28 @@
 use crate::perms::oauth::SharedToken;
 use serde::de::DeserializeOwned;
 use signet_tx_cache::{
-    error::Result,
+    error::TxCacheError,
     types::{BundleKey, CacheObject, TxCacheBundle, TxCacheBundleResponse, TxCacheBundlesResponse},
     TxCache,
 };
-use tracing::{instrument, warn};
+use thiserror::Error;
+use tokio::sync::watch;
+use tracing::instrument;
+
+/// Result type for [`BuilderTxCache`] operations.
+pub type Result<T> = std::result::Result<T, BuilderTxCacheError>;
+
+/// Errors that can occur when using the [`BuilderTxCache`] client.
+#[derive(Debug, Error)]
+pub enum BuilderTxCacheError {
+    /// Failed to retrieve the authentication token.
+    #[error("failed to retrieve auth token: {0}")]
+    TokenRetrieval(#[from] watch::error::RecvError),
+
+    /// An error occurred during a TxCache operation.
+    #[error(transparent)]
+    TxCache(#[from] TxCacheError),
+}
 
 const BUNDLES: &str = "bundles";
 
@@ -77,10 +94,7 @@ impl BuilderTxCache {
         T: DeserializeOwned + CacheObject,
     {
         let url = self.tx_cache.url().join(join)?;
-        let secret = self.token.secret().await.unwrap_or_else(|_| {
-            warn!("Failed to get token secret");
-            "".to_string()
-        });
+        let secret = self.token.secret().await?;
 
         self.tx_cache
             .client()

From 0704a17436a4a6988e8b79031a95e1dc786b1506 Mon Sep 17 00:00:00 2001
From: evalir <e@evalir.xyz>
Date: Fri, 6 Feb 2026 18:03:41 +0100
Subject: [PATCH 2/3] chore: fix errors

---
 src/perms/tx_cache.rs | 12 ++++++++++++
 tests/tx-cache.rs     |  4 ++--
 2 files changed, 14 insertions(+), 2 deletions(-)

diff --git a/src/perms/tx_cache.rs b/src/perms/tx_cache.rs
index 905cbdd..86890b7 100644
--- a/src/perms/tx_cache.rs
+++ b/src/perms/tx_cache.rs
@@ -24,6 +24,18 @@ pub enum BuilderTxCacheError {
     TxCache(#[from] TxCacheError),
 }
 
+impl From<reqwest::Error> for BuilderTxCacheError {
+    fn from(err: reqwest::Error) -> Self {
+        BuilderTxCacheError::TxCache(TxCacheError::Reqwest(err))
+    }
+}
+
+impl From<url::ParseError> for BuilderTxCacheError {
+    fn from(err: url::ParseError) -> Self {
+        BuilderTxCacheError::TxCache(TxCacheError::Url(err))
+    }
+}
+
 const BUNDLES: &str = "bundles";
 
 /// A client for interacting with the transaction cache, a thin wrapper around
diff --git a/tests/tx-cache.rs b/tests/tx-cache.rs
index 7eca382..cd575ae 100644
--- a/tests/tx-cache.rs
+++ b/tests/tx-cache.rs
@@ -1,6 +1,6 @@
 #![cfg(feature = "perms")]
 
-use init4_bin_base::perms::{tx_cache::BuilderTxCache, SharedToken};
+use init4_bin_base::perms::{tx_cache::{BuilderTxCache, BuilderTxCacheError}, SharedToken};
 use signet_tx_cache::TxCacheError;
 
 const URL: &str = "https://transactions.parmigiana.signet.sh";
@@ -12,5 +12,5 @@ async fn test_tx_cache_get_bundles() {
 
     let bundles = client.get_bundles(None).await.unwrap_err();
 
-    assert!(matches!(bundles, TxCacheError::NotOurSlot));
+    assert!(matches!(bundles, BuilderTxCacheError::TxCache(TxCacheError::NotOurSlot)));
 }

From 38ecb41b517b91785908637486c70465ccbbe25e Mon Sep 17 00:00:00 2001
From: evalir <e@evalir.xyz>
Date: Fri, 6 Feb 2026 18:06:23 +0100
Subject: [PATCH 3/3] fmt

---
 tests/tx-cache.rs | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/tests/tx-cache.rs b/tests/tx-cache.rs
index cd575ae..aa283e9 100644
--- a/tests/tx-cache.rs
+++ b/tests/tx-cache.rs
@@ -1,6 +1,9 @@
 #![cfg(feature = "perms")]
 
-use init4_bin_base::perms::{tx_cache::{BuilderTxCache, BuilderTxCacheError}, SharedToken};
+use init4_bin_base::perms::{
+    tx_cache::{BuilderTxCache, BuilderTxCacheError},
+    SharedToken,
+};
 use signet_tx_cache::TxCacheError;
 
 const URL: &str = "https://transactions.parmigiana.signet.sh";
@@ -12,5 +15,8 @@ async fn test_tx_cache_get_bundles() {
 
     let bundles = client.get_bundles(None).await.unwrap_err();
 
-    assert!(matches!(bundles, BuilderTxCacheError::TxCache(TxCacheError::NotOurSlot)));
+    assert!(matches!(
+        bundles,
+        BuilderTxCacheError::TxCache(TxCacheError::NotOurSlot)
+    ));
 }