refactor: update RampsController with selectedProvider and selectedToken

[georgeweiler]

Explanation

This PR refactors the RampsController to improve naming consistency and add token selection support.

Breaking Changes

• Rename preferredProvider to selectedProvider: Aligns naming with the new selectedToken state for consistency across selected entities
• Update getPaymentMethods signature: Changed from getPaymentMethods(options) to getPaymentMethods(region, options) to match the pattern used by getTokens and getProviders

New Features

• Add selectedToken state: Stores the user's selected token with setSelectedToken() method. When a token is selected, payment methods are automatically fetched for that token
• Add RampsEnvironment.Local: New environment option for RampsService that points to localhost:3000 for local development

References

https://consensyssoftware.atlassian.net/browse/TRAM-3232

Checklist

• I've updated the test suite for new or updated code as appropriate
• I've updated documentation (JSDoc, Markdown, etc.) for new or updated code as appropriate
• I've communicated my changes to consumers by updating changelogs for packages I've changed
• I've introduced breaking changes in this PR and have prepared draft pull requests for clients and consumer packages to resolve them

---

Note

Introduces token selection and aligns provider naming, plus updates payment-methods API usage and service environments.

• BREAKING: Rename preferredProvider → selectedProvider and setPreferredProvider() → setSelectedProvider(); clear on region change
• BREAKING: Change getPaymentMethods(options) → getPaymentMethods(region, options); triggerGetPaymentMethods signature updated accordingly
• Added: selectedToken state with setSelectedToken(); auto-fetches payment methods (and getPaymentMethods now defaults assetId/provider from selectedToken/selectedProvider)
• Behavior: getPaymentMethods now sets selectedPaymentMethod to the first returned method when current selection is missing; preserves when still valid; handles empty returns
• Service: Add RampsEnvironment.Local and optional baseUrlOverride; switch payments endpoint to v2/regions/{region}/payments and query assetId → crypto; Provider type includes supported* maps
• Misc: State metadata updated; tests refactored to new APIs and region handling

^{Written by Cursor Bugbot for commit 9d0e8f6. This will update automatically on new commits. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

[cursor]

Provider type uses Map for JSON data fields

Low Severity

The Provider type adds three new required fields (supportedCryptoCurrencies, supportedFiatCurrencies, supportedPaymentMethods) typed as Map<string, boolean>. However, these fields come from JSON API responses parsed via fetchResponse.json(), which produces plain JavaScript objects, not Map instances. If any code attempts to use Map methods (like .get(), .has(), .entries()) on these fields, it would fail at runtime. Additionally, these fields aren't used anywhere in the codebase, making them unused type definitions.

 

[cursor]

Race condition when rapidly changing token/provider selection

Medium Severity

When setSelectedToken or setSelectedProvider is called, it triggers getPaymentMethods asynchronously. If the user rapidly changes their selection, multiple requests with different cache keys run in parallel. When responses arrive out of order, state.paymentMethods is unconditionally overwritten without verifying it still matches the current selectedToken/selectedProvider. This can result in showing payment methods for a previously selected token while the UI shows a different selected token.

Additional Locations (2)

• packages/ramps-controller/src/RampsController.ts#L817-L820
• packages/ramps-controller/src/RampsController.ts#L669-L672