feat(api): add Blend market catalog endpoints (pools, earn options)

internal/api/handlers/blend_catalog.go

@@ -0,0 +1,61 @@
+// ABOUTME: Handlers for the Blend market-catalog endpoints:
+// ABOUTME: GET /protocols/blend/pools and GET /protocols/blend/earn-options.
+package handlers
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"net/http"
+	"time"
+
+	"github.com/stellar/freighter-backend-v2/internal/api/httperror"
+	response "github.com/stellar/freighter-backend-v2/internal/api/httpresponse"
+	"github.com/stellar/freighter-backend-v2/internal/types"
+)
+
+const blendCatalogContextTimeout = 10 * time.Second
+
+type BlendCatalogHandler struct {
+	CatalogService types.BlendCatalogService
+}
+
+func NewBlendCatalogHandler(catalogService types.BlendCatalogService) *BlendCatalogHandler {
+	return &BlendCatalogHandler{CatalogService: catalogService}
+}
+
+// GetPools handles GET /api/v1/protocols/blend/pools: the pool-wide market
+// catalog, independent of any account.
+func (h *BlendCatalogHandler) GetPools(w http.ResponseWriter, r *http.Request) error {
+	ctx, cancel := context.WithTimeout(r.Context(), blendCatalogContextTimeout)
+	defer cancel()
+
+	network := r.URL.Query().Get("network")
+	if !isValidWalletBackendNetwork(network) {
+		return httperror.BadRequest(fmt.Sprintf("invalid network: must be %s or %s", types.PUBLIC, types.TESTNET), errors.New("invalid network"))
+	}
+
+	pools, err := h.CatalogService.GetPools(ctx, network)
+	if err != nil {
+		return translateServiceError(r.Context(), err, "blend pools", "", network)
+	}
+	return response.OK(w, HttpResponse{Data: pools})
+}
+
+// GetEarnOptions handles GET /api/v1/protocols/blend/earn-options: the
+// asset-first "where can I earn this" catalog, allowlist-curated.
+func (h *BlendCatalogHandler) GetEarnOptions(w http.ResponseWriter, r *http.Request) error {
+	ctx, cancel := context.WithTimeout(r.Context(), blendCatalogContextTimeout)
+	defer cancel()
+
+	network := r.URL.Query().Get("network")
+	if !isValidWalletBackendNetwork(network) {
+		return httperror.BadRequest(fmt.Sprintf("invalid network: must be %s or %s", types.PUBLIC, types.TESTNET), errors.New("invalid network"))
+	}
+
+	options, err := h.CatalogService.GetEarnOptions(ctx, network)
+	if err != nil {
+		return translateServiceError(r.Context(), err, "blend earn options", "", network)
+	}
+	return response.OK(w, HttpResponse{Data: options})
+}

internal/api/handlers/blend_catalog_test.go

@@ -0,0 +1,87 @@
+// ABOUTME: Handler tests for the Blend catalog endpoints: validation, error
+// ABOUTME: translation, and success envelopes for pools and earn options.
+package handlers
+
+import (
+	"errors"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/stellar/freighter-backend-v2/internal/metrics"
+	"github.com/stellar/freighter-backend-v2/internal/types"
+	"github.com/stellar/freighter-backend-v2/internal/utils"
+)
+
+func serveCatalog(t *testing.T, svc types.BlendCatalogService, target string) *httptest.ResponseRecorder {
+	t.Helper()
+	handler := NewBlendCatalogHandler(svc)
+	mux := http.NewServeMux()
+	mux.HandleFunc("GET /api/v1/protocols/blend/pools", CustomHandler(handler.GetPools))
+	mux.HandleFunc("GET /api/v1/protocols/blend/earn-options", CustomHandler(handler.GetEarnOptions))
+	rec := httptest.NewRecorder()
+	mux.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, target, nil))
+	return rec
+}
+
+func TestBlendCatalogSuccess(t *testing.T) {
+	name := "Fixed Pool V2"
+	svc := &utils.MockBlendCatalogService{
+		GetPoolsResult: &types.BlendPoolsCatalog{
+			Pools: []types.BlendCatalogPool{{ID: "CPOOL", Name: &name, Reserves: []types.BlendCatalogReserve{}}},
+		},
+		GetEarnOptionsResult: &types.BlendEarnOptionsCatalog{
+			Options: []types.BlendEarnAssetOption{{AssetID: "CUSDC", Pools: []types.BlendEarnPool{{ID: "CPOOL"}}}},
+		},
+	}
+
+	rec := serveCatalog(t, svc, "/api/v1/protocols/blend/pools?network=TESTNET")
+	require.Equal(t, http.StatusOK, rec.Code)
+	assert.Contains(t, rec.Body.String(), `"id":"CPOOL"`)
+	assert.Contains(t, rec.Body.String(), `"name":"Fixed Pool V2"`)
+
+	rec = serveCatalog(t, svc, "/api/v1/protocols/blend/earn-options?network=TESTNET")
+	require.Equal(t, http.StatusOK, rec.Code)
+	assert.Contains(t, rec.Body.String(), `"asset_id":"CUSDC"`)
+}
+
+func TestBlendCatalogValidation(t *testing.T) {
+	svc := &utils.MockBlendCatalogService{}
+	for _, target := range []string{
+		"/api/v1/protocols/blend/pools",
+		"/api/v1/protocols/blend/pools?network=NOPE",
+		"/api/v1/protocols/blend/earn-options",
+		"/api/v1/protocols/blend/earn-options?network=NOPE",
+	} {
+		rec := serveCatalog(t, svc, target)
+		assert.Equal(t, http.StatusBadRequest, rec.Code, target)
+	}
+}
+
+func TestBlendCatalogErrorTranslation(t *testing.T) {
+	svc := &utils.MockBlendCatalogService{
+		GetPoolsError:       &metrics.UpstreamError{Kind: "http_error", Code: 502, Err: errors.New("boom")},
+		GetEarnOptionsError: errors.New("wat"),
+	}
+
+	rec := serveCatalog(t, svc, "/api/v1/protocols/blend/pools?network=TESTNET")
+	assert.Equal(t, http.StatusBadGateway, rec.Code)
+
+	rec = serveCatalog(t, svc, "/api/v1/protocols/blend/earn-options?network=TESTNET")
+	assert.Equal(t, http.StatusInternalServerError, rec.Code)
+}
+
+func TestBlendCatalogEmptyIs200(t *testing.T) {
+	svc := &utils.MockBlendCatalogService{}
+
+	rec := serveCatalog(t, svc, "/api/v1/protocols/blend/pools?network=TESTNET")
+	require.Equal(t, http.StatusOK, rec.Code)
+	assert.Contains(t, rec.Body.String(), `"pools":[]`)
+
+	rec = serveCatalog(t, svc, "/api/v1/protocols/blend/earn-options?network=TESTNET")
+	require.Equal(t, http.StatusOK, rec.Code)
+	assert.Contains(t, rec.Body.String(), `"options":[]`)
+}

internal/api/serve.go

@@ -235,6 +235,18 @@ func (s *ApiServer) routes() ([]route, error) {
 	)
 	accountPositionsHandler := handlers.NewAccountPositionsHandler(positionsService, s.cfg.AppConfig.MaxBalanceAddresses)
 
+	blendCatalogService, err := services.NewBlendCatalogService(
+		s.walletBackendService,
+		s.redis,
+		time.Duration(s.cfg.BlendConfig.CatalogCacheTTLSeconds)*time.Second,
+		s.cfg.BlendConfig.EarnPoolsConfigPath,
+		s.appMetrics.Service,
+	)
+	if err != nil {
+		return nil, fmt.Errorf("init blend catalog service: %w", err)
+	}
+	blendCatalogHandler := handlers.NewBlendCatalogHandler(blendCatalogService)
+
 	return []route{
 		// Health/liveness/readiness probes: gated=false, registered BARE — never
 		// wrapped by Auth. K8s and the docker-compose wget healthcheck cannot present
@@ -255,12 +267,12 @@ func (s *ApiServer) routes() ([]route, error) {
 		{http.MethodGet, "/api/v1/feature-flags", handlers.CustomHandler(featureFlagsHandler.GetFeatureFlags), true, true},
 		// The wallet-backend-fronted routes, config-gated together by
 		// --wallet-backend-routes-enabled. These are the routes that touch
-		// walletBackendService (balances, history, and positions), and all fail
-		// identically when it is unconfigured: configureNetworkClient returns nil
-		// and the handler errors before any network call, so every request 500s.
-		// wallet-backend is configured only in dev, so they are disabled in
-		// production until that upstream is wired up. enabled=false leaves every
-		// path 404ing.
+		// walletBackendService (balances, history, positions, and the Blend market
+		// catalog), and all fail identically when it is unconfigured:
+		// configureNetworkClient returns nil and the handler errors before any network
+		// call, so every request 500s. wallet-backend is configured only in dev, so
+		// they are disabled in production until that upstream is wired up.
+		// enabled=false leaves every path 404ing.
 		//
 		// They share one flag deliberately: they share one dependency and one failure
 		// mode, so there is no state where enabling a subset is correct. If a route
@@ -269,6 +281,8 @@ func (s *ApiServer) routes() ([]route, error) {
 		{http.MethodPost, "/api/v1/accounts/balances", handlers.CustomHandler(accountBalancesHandler.GetAccountBalances), true, s.cfg.AppConfig.WalletBackendRoutesEnabled},
 		{http.MethodGet, "/api/v1/accounts/{address}/transactions", handlers.CustomHandler(accountHistoryHandler.GetAccountTransactions), true, s.cfg.AppConfig.WalletBackendRoutesEnabled},
 		{http.MethodPost, "/api/v1/accounts/positions", handlers.CustomHandler(accountPositionsHandler.GetAccountsPositions), true, s.cfg.AppConfig.WalletBackendRoutesEnabled},
+		{http.MethodGet, "/api/v1/protocols/blend/pools", handlers.CustomHandler(blendCatalogHandler.GetPools), true, s.cfg.AppConfig.WalletBackendRoutesEnabled},
+		{http.MethodGet, "/api/v1/protocols/blend/earn-options", handlers.CustomHandler(blendCatalogHandler.GetEarnOptions), true, s.cfg.AppConfig.WalletBackendRoutesEnabled},
 
 		{http.MethodPost, "/api/v1/token-prices", handlers.CustomHandler(tokenPricesHandler.GetPrices), true, true},
 		{http.MethodGet, "/api/v1/auth/whoami", handlers.CustomHandler(whoamiHandler.Whoami), true, true},

internal/api/serve_test.go

@@ -187,7 +187,7 @@ func TestApiServer_initHandlers_RegistersAccountHistoryRoutes(t *testing.T) {
 }
 
 // walletBackendRoutes is every route gated by --wallet-backend-routes-enabled.
-// Both tests below iterate it, so adding a third wallet-backend-fronted route
+// Both tests below iterate it, so adding another wallet-backend-fronted route
 // extends the on/off coverage by one line here rather than being silently missed.
 // The {address} wildcard is pre-substituted: auth and registration both run before
 // path-parameter validation, so any non-empty segment reaches the assertion.
@@ -199,6 +199,8 @@ var walletBackendRoutes = []struct {
 	{"balances", http.MethodPost, "/api/v1/accounts/balances"},
 	{"account-history", http.MethodGet, "/api/v1/accounts/GBTYAFHGNZSTE4VBWZYAGB3SRGJEPTI5I4Y22KZ4JTVAN56LESB6JZOF/transactions"},
 	{"positions", http.MethodPost, "/api/v1/accounts/positions"},
+	{"blend-pools", http.MethodGet, "/api/v1/protocols/blend/pools"},
+	{"blend-earn-options", http.MethodGet, "/api/v1/protocols/blend/earn-options"},
 }
 
 // TestApiServer_initHandlers_WalletBackendRoutesDisabledNotRegistered pins the off
@@ -251,7 +253,7 @@ func TestApiServer_initHandlers_WalletBackendRoutesEnabledStayGated(t *testing.T
 }
 
 // TestApiServer_initHandlers_WalletBackendRoutesGatedTogether pins the "one flag,
-// every route" decision. All three share a dependency and a failure mode, so a
+// every route" decision. All five share a dependency and a failure mode, so a
 // change that gated only some — leaving the rest publicly 500ing in prd, which is
 // the exact bug this flag exists to close — would otherwise pass every test above.
 func TestApiServer_initHandlers_WalletBackendRoutesGatedTogether(t *testing.T) {
@@ -273,6 +275,8 @@ func TestApiServer_initHandlers_WalletBackendRoutesGatedTogether(t *testing.T) {
 		"POST /api/v1/accounts/balances":              true,
 		"GET /api/v1/accounts/{address}/transactions": true,
 		"POST /api/v1/accounts/positions":             true,
+		"GET /api/v1/protocols/blend/pools":           true,
+		"GET /api/v1/protocols/blend/earn-options":    true,
 	}, disabled, "exactly the wallet-backend-fronted routes must be disabled by the flag")
 }