@metamask-previews/ramps-controller 3.0.0-preview-fa81dffb → 4.0.0-preview-903db2da

package/CHANGELOG.md

@@ -9,8 +9,40 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- Add sync trigger methods to RampsController ([#7662](https://github.com/MetaMask/core/pull/7662))
+
+- Export `RampAction` type for `'buy' | 'sell'` ramp actions ([#7663](https://github.com/MetaMask/core/pull/7663))
+
+### Changed
+
+- Evict expired cache entries based on TTL in addition to size-based eviction ([#7674](https://github.com/MetaMask/core/pull/7674))
+
+- Update `getTokens()` to use v2 API endpoint and support optional provider parameter ([#7664](https://github.com/MetaMask/core/pull/7664))
+
+## [4.0.0]
+
+### Added
+
 - Add `preferredProvider` state and `setPreferredProvider()` method to RampsController ([#7617](https://github.com/MetaMask/core/pull/7617))
 
+- Export `UserRegion` type ([#7646](https://github.com/MetaMask/core/pull/7646))
+
+- Add `defaultAmount` and `quickAmounts` fields to the `Country` type ([#7645](https://github.com/MetaMask/core/pull/7645))
+
+- Add `providers` state and `getProviders()` method to RampsController. Providers are automatically fetched on init and when the region changes ([#7652](https://github.com/MetaMask/core/pull/7652))
+
+### Changed
+
+- **BREAKING:** Change `userRegion` from `string | null` to `UserRegion | null`. Access region code via `userRegion.regionCode`. ([#7646](https://github.com/MetaMask/core/pull/7646))
+
+- Update `getCountries()` endpoint to use v2 API (`v2/regions/countries`) ([#7645](https://github.com/MetaMask/core/pull/7645))
+
+- Add `getApiPath()` helper function for versioned API paths with v2 default ([#7645](https://github.com/MetaMask/core/pull/7645))
+
+### Removed
+
+- **BREAKING:** Remove eligibility concept from RampsController. The `eligibility` state, `updateEligibility()` method, and `getEligibility()` service method have been removed. The `Eligibility` type and `RampsServiceGetEligibilityAction` are no longer exported. ([#7651](https://github.com/MetaMask/core/pull/7645))
+
 ## [3.0.0]
 
 ### Added
@@ -59,7 +91,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Add `OnRampService` for interacting with the OnRamp API
   - Add geolocation detection via IP address lookup
 
-[Unreleased]: https://github.com/MetaMask/core/compare/@metamask/ramps-controller@3.0.0...HEAD
+[Unreleased]: https://github.com/MetaMask/core/compare/@metamask/ramps-controller@4.0.0...HEAD
+[4.0.0]: https://github.com/MetaMask/core/compare/@metamask/ramps-controller@3.0.0...@metamask/ramps-controller@4.0.0
 [3.0.0]: https://github.com/MetaMask/core/compare/@metamask/ramps-controller@2.1.0...@metamask/ramps-controller@3.0.0
 [2.1.0]: https://github.com/MetaMask/core/compare/@metamask/ramps-controller@2.0.0...@metamask/ramps-controller@2.1.0
 [2.0.0]: https://github.com/MetaMask/core/compare/@metamask/ramps-controller@1.0.0...@metamask/ramps-controller@2.0.0

package/dist/RampsController.cjs

@@ -38,7 +38,7 @@ const rampsControllerMetadata = {
         includeInStateLogs: true,
         usedInUi: true,
     },
-    eligibility: {
+    providers: {
         persist: true,
         includeInDebugSnapshot: true,
         includeInStateLogs: true,
@@ -69,12 +69,65 @@ function getDefaultRampsControllerState() {
     return {
         userRegion: null,
         preferredProvider: null,
-        eligibility: null,
+        providers: [],
         tokens: null,
         requests: {},
     };
 }
 exports.getDefaultRampsControllerState = getDefaultRampsControllerState;
+// === HELPER FUNCTIONS ===
+/**
+ * Finds a country and state from a region code string.
+ *
+ * @param regionCode - The region code (e.g., "us-ca" or "us").
+ * @param countries - Array of countries to search.
+ * @returns UserRegion object with country and state, or null if not found.
+ */
+function findRegionFromCode(regionCode, countries) {
+    const normalizedCode = regionCode.toLowerCase().trim();
+    const parts = normalizedCode.split('-');
+    const countryCode = parts[0];
+    const stateCode = parts[1];
+    const country = countries.find((countryItem) => {
+        if (countryItem.isoCode?.toLowerCase() === countryCode) {
+            return true;
+        }
+        if (countryItem.id) {
+            const id = countryItem.id.toLowerCase();
+            if (id.startsWith('/regions/')) {
+                const extractedCode = id.replace('/regions/', '').split('/')[0];
+                return extractedCode === countryCode;
+            }
+            return id === countryCode || id.endsWith(`/${countryCode}`);
+        }
+        return false;
+    });
+    if (!country) {
+        return null;
+    }
+    let state = null;
+    if (stateCode && country.states) {
+        state =
+            country.states.find((stateItem) => {
+                if (stateItem.stateId?.toLowerCase() === stateCode) {
+                    return true;
+                }
+                if (stateItem.id) {
+                    const stateId = stateItem.id.toLowerCase();
+                    if (stateId.includes(`-${stateCode}`) ||
+                        stateId.endsWith(`/${stateCode}`)) {
+                        return true;
+                    }
+                }
+                return false;
+            }) ?? null;
+    }
+    return {
+        country,
+        state,
+        regionCode: normalizedCode,
+    };
+}
 // === CONTROLLER DEFINITION ===
 /**
  * Manages cryptocurrency on/off ramps functionality.
@@ -208,73 +261,134 @@ class RampsController extends base_controller_1.BaseController {
         return this.state.requests[cacheKey];
     }
     /**
-     * Updates the user's region by fetching geolocation and eligibility.
-     * This method calls the RampsService to get the geolocation,
-     * then automatically fetches eligibility for that region.
+     * Updates the user's region by fetching geolocation.
+     * This method calls the RampsService to get the geolocation.
      *
      * @param options - Options for cache behavior.
-     * @returns The user region string.
+     * @returns The user region object.
      */
     async updateUserRegion(options) {
+        // If a userRegion already exists and forceRefresh is not requested,
+        // return it immediately without fetching geolocation.
+        // This ensures that once a region is set (either via geolocation or manual selection),
+        // it will not be overwritten by subsequent geolocation fetches.
+        if (this.state.userRegion && !options?.forceRefresh) {
+            return this.state.userRegion;
+        }
+        // When forceRefresh is true, clear the existing region, tokens, and providers before fetching
+        if (options?.forceRefresh) {
+            this.update((state) => {
+                state.userRegion = null;
+                state.tokens = null;
+                state.providers = [];
+            });
+        }
         const cacheKey = (0, RequestCache_1.createCacheKey)('updateUserRegion', []);
-        const userRegion = await this.executeRequest(cacheKey, async () => {
+        const regionCode = await this.executeRequest(cacheKey, async () => {
             const result = await this.messenger.call('RampsService:getGeolocation');
             return result;
         }, options);
-        const normalizedRegion = userRegion
-            ? userRegion.toLowerCase().trim()
-            : userRegion;
-        this.update((state) => {
-            state.userRegion = normalizedRegion;
-            state.tokens = null;
-        });
-        if (normalizedRegion) {
-            try {
-                await this.updateEligibility(normalizedRegion, options);
-            }
-            catch {
+        if (!regionCode) {
+            this.update((state) => {
+                state.userRegion = null;
+                state.tokens = null;
+                state.providers = [];
+            });
+            return null;
+        }
+        const normalizedRegion = regionCode.toLowerCase().trim();
+        try {
+            const countries = await this.getCountries('buy', options);
+            const userRegion = findRegionFromCode(normalizedRegion, countries);
+            if (userRegion) {
                 this.update((state) => {
-                    const currentUserRegion = state.userRegion?.toLowerCase().trim();
-                    if (currentUserRegion === normalizedRegion) {
-                        state.eligibility = null;
+                    const regionChanged = state.userRegion?.regionCode !== userRegion.regionCode;
+                    state.userRegion = userRegion;
+                    // Clear tokens and providers when region changes
+                    if (regionChanged) {
                         state.tokens = null;
+                        state.providers = [];
                     }
                 });
+                // Fetch providers for the new region
+                if (userRegion.regionCode) {
+                    try {
+                        await this.getProviders(userRegion.regionCode, options);
+                    }
+                    catch {
+                        // Provider fetch failed - error state will be available via selectors
+                    }
+                }
+                return userRegion;
             }
+            // Region not found in countries data
+            this.update((state) => {
+                state.userRegion = null;
+                state.tokens = null;
+                state.providers = [];
+            });
+            return null;
+        }
+        catch {
+            // If countries fetch fails, we can't create a valid UserRegion
+            // Return null to indicate we don't have valid country data
+            this.update((state) => {
+                state.userRegion = null;
+                state.tokens = null;
+                state.providers = [];
+            });
+            return null;
         }
-        return normalizedRegion;
     }
     /**
      * Sets the user's region manually (without fetching geolocation).
      * This allows users to override the detected region.
      *
      * @param region - The region code to set (e.g., "US-CA").
-     * @param options - Options for cache behavior when fetching eligibility.
-     * @returns The eligibility information for the region.
+     * @param options - Options for cache behavior.
+     * @returns The user region object.
      */
     async setUserRegion(region, options) {
         const normalizedRegion = region.toLowerCase().trim();
-        this.update((state) => {
-            state.userRegion = normalizedRegion;
-            state.tokens = null;
-        });
         try {
-            return await this.updateEligibility(normalizedRegion, options);
+            const countries = await this.getCountries('buy', options);
+            const userRegion = findRegionFromCode(normalizedRegion, countries);
+            if (userRegion) {
+                this.update((state) => {
+                    state.userRegion = userRegion;
+                    state.tokens = null;
+                    state.providers = [];
+                });
+                // Fetch providers for the new region
+                try {
+                    await this.getProviders(userRegion.regionCode, options);
+                }
+                catch {
+                    // Provider fetch failed - error state will be available via selectors
+                }
+                return userRegion;
+            }
+            // Region not found in countries data
+            this.update((state) => {
+                state.userRegion = null;
+                state.tokens = null;
+                state.providers = [];
+            });
+            throw new Error(`Region "${normalizedRegion}" not found in countries data. Cannot set user region without valid country information.`);
         }
         catch (error) {
-            // Eligibility fetch failed, but user region was successfully set.
-            // Don't let eligibility errors prevent user region state from being updated.
-            // Clear eligibility state to avoid showing stale data from a previous location.
-            // Only clear if the region still matches to avoid race conditions where a newer
-            // region change has already succeeded.
+            // If the error is "not found", re-throw it
+            // Otherwise, it's from countries fetch failure
+            if (error instanceof Error && error.message.includes('not found')) {
+                throw error;
+            }
+            // Countries fetch failed
             this.update((state) => {
-                const currentUserRegion = state.userRegion?.toLowerCase().trim();
-                if (currentUserRegion === normalizedRegion) {
-                    state.eligibility = null;
-                    state.tokens = null;
-                }
+                state.userRegion = null;
+                state.tokens = null;
+                state.providers = [];
             });
-            throw error;
+            throw new Error('Failed to fetch countries data. Cannot set user region without valid country information.');
         }
     }
     /**
@@ -291,8 +405,10 @@ class RampsController extends base_controller_1.BaseController {
     /**
      * Initializes the controller by fetching the user's region from geolocation.
      * This should be called once at app startup to set up the initial region.
-     * After the region is set and eligibility is determined, tokens are fetched
-     * and saved to state.
+     * After the region is set, tokens are fetched and saved to state.
+     *
+     * If a userRegion already exists (from persistence or manual selection),
+     * this method will skip geolocation fetch and only fetch tokens if needed.
      *
      * @param options - Options for cache behavior.
      * @returns Promise that resolves when initialization is complete.
@@ -304,40 +420,25 @@ class RampsController extends base_controller_1.BaseController {
         });
         if (userRegion) {
             try {
-                await this.getTokens(userRegion, 'buy', options);
+                await this.getTokens(userRegion.regionCode, 'buy', options);
             }
             catch {
                 // Token fetch failed - error state will be available via selectors
             }
-        }
-    }
-    /**
-     * Updates the eligibility information for a given region.
-     *
-     * @param isoCode - The ISO code for the region (e.g., "us", "fr", "us-ny").
-     * @param options - Options for cache behavior.
-     * @returns The eligibility information.
-     */
-    async updateEligibility(isoCode, options) {
-        const normalizedIsoCode = isoCode.toLowerCase().trim();
-        const cacheKey = (0, RequestCache_1.createCacheKey)('updateEligibility', [normalizedIsoCode]);
-        const eligibility = await this.executeRequest(cacheKey, async () => {
-            return this.messenger.call('RampsService:getEligibility', normalizedIsoCode);
-        }, options);
-        this.update((state) => {
-            const userRegion = state.userRegion?.toLowerCase().trim();
-            if (userRegion === undefined || userRegion === normalizedIsoCode) {
-                state.eligibility = eligibility;
+            try {
+                await this.getProviders(userRegion.regionCode, options);
             }
-        });
-        return eligibility;
+            catch {
+                // Provider fetch failed - error state will be available via selectors
+            }
+        }
     }
     /**
      * Fetches the list of supported countries for a given ramp action.
      *
      * @param action - The ramp action type ('buy' or 'sell').
      * @param options - Options for cache behavior.
-     * @returns An array of countries with their eligibility information.
+     * @returns An array of countries.
      */
     async getCountries(action = 'buy', options) {
         const cacheKey = (0, RequestCache_1.createCacheKey)('getCountries', [action]);
@@ -351,27 +452,135 @@ class RampsController extends base_controller_1.BaseController {
      *
      * @param region - The region code (e.g., "us", "fr", "us-ny"). If not provided, uses the user's region from controller state.
      * @param action - The ramp action type ('buy' or 'sell').
-     * @param options - Options for cache behavior.
+     * @param options - Options for cache behavior and query filters.
+     * @param options.provider - Provider ID(s) to filter by.
      * @returns The tokens response containing topTokens and allTokens.
      */
     async getTokens(region, action = 'buy', options) {
-        const regionToUse = region ?? this.state.userRegion;
+        const regionToUse = region ?? this.state.userRegion?.regionCode;
         if (!regionToUse) {
             throw new Error('Region is required. Either provide a region parameter or ensure userRegion is set in controller state.');
         }
         const normalizedRegion = regionToUse.toLowerCase().trim();
-        const cacheKey = (0, RequestCache_1.createCacheKey)('getTokens', [normalizedRegion, action]);
+        const cacheKey = (0, RequestCache_1.createCacheKey)('getTokens', [
+            normalizedRegion,
+            action,
+            options?.provider,
+        ]);
         const tokens = await this.executeRequest(cacheKey, async () => {
-            return this.messenger.call('RampsService:getTokens', normalizedRegion, action);
+            return this.messenger.call('RampsService:getTokens', normalizedRegion, action, {
+                provider: options?.provider,
+            });
         }, options);
         this.update((state) => {
-            const userRegion = state.userRegion?.toLowerCase().trim();
-            if (userRegion === undefined || userRegion === normalizedRegion) {
+            const userRegionCode = state.userRegion?.regionCode;
+            if (userRegionCode === undefined || userRegionCode === normalizedRegion) {
                 state.tokens = tokens;
             }
         });
         return tokens;
     }
+    /**
+     * Fetches the list of providers for a given region.
+     * The providers are saved in the controller state once fetched.
+     *
+     * @param region - The region code (e.g., "us", "fr", "us-ny"). If not provided, uses the user's region from controller state.
+     * @param options - Options for cache behavior and query filters.
+     * @param options.provider - Provider ID(s) to filter by.
+     * @param options.crypto - Crypto currency ID(s) to filter by.
+     * @param options.fiat - Fiat currency ID(s) to filter by.
+     * @param options.payments - Payment method ID(s) to filter by.
+     * @returns The providers response containing providers array.
+     */
+    async getProviders(region, options) {
+        const regionToUse = region ?? this.state.userRegion?.regionCode;
+        if (!regionToUse) {
+            throw new Error('Region is required. Either provide a region parameter or ensure userRegion is set in controller state.');
+        }
+        const normalizedRegion = regionToUse.toLowerCase().trim();
+        const cacheKey = (0, RequestCache_1.createCacheKey)('getProviders', [
+            normalizedRegion,
+            options?.provider,
+            options?.crypto,
+            options?.fiat,
+            options?.payments,
+        ]);
+        const { providers } = await this.executeRequest(cacheKey, async () => {
+            return this.messenger.call('RampsService:getProviders', normalizedRegion, {
+                provider: options?.provider,
+                crypto: options?.crypto,
+                fiat: options?.fiat,
+                payments: options?.payments,
+            });
+        }, options);
+        this.update((state) => {
+            const userRegionCode = state.userRegion?.regionCode;
+            if (userRegionCode === undefined || userRegionCode === normalizedRegion) {
+                state.providers = providers;
+            }
+        });
+        return { providers };
+    }
+    // ============================================================
+    // Sync Trigger Methods
+    // These fire-and-forget methods are for use in React effects.
+    // Errors are stored in state and available via selectors.
+    // ============================================================
+    /**
+     * Triggers a user region update without throwing.
+     *
+     * @param options - Options for cache behavior.
+     */
+    triggerUpdateUserRegion(options) {
+        this.updateUserRegion(options).catch(() => {
+            // Error stored in state
+        });
+    }
+    /**
+     * Triggers setting the user region without throwing.
+     *
+     * @param region - The region code to set (e.g., "US-CA").
+     * @param options - Options for cache behavior.
+     */
+    triggerSetUserRegion(region, options) {
+        this.setUserRegion(region, options).catch(() => {
+            // Error stored in state
+        });
+    }
+    /**
+     * Triggers fetching countries without throwing.
+     *
+     * @param action - The ramp action type ('buy' or 'sell').
+     * @param options - Options for cache behavior.
+     */
+    triggerGetCountries(action = 'buy', options) {
+        this.getCountries(action, options).catch(() => {
+            // Error stored in state
+        });
+    }
+    /**
+     * Triggers fetching tokens without throwing.
+     *
+     * @param region - The region code. If not provided, uses userRegion from state.
+     * @param action - The ramp action type ('buy' or 'sell').
+     * @param options - Options for cache behavior.
+     */
+    triggerGetTokens(region, action = 'buy', options) {
+        this.getTokens(region, action, options).catch(() => {
+            // Error stored in state
+        });
+    }
+    /**
+     * Triggers fetching providers without throwing.
+     *
+     * @param region - The region code. If not provided, uses userRegion from state.
+     * @param options - Options for cache behavior and query filters.
+     */
+    triggerGetProviders(region, options) {
+        this.getProviders(region, options).catch(() => {
+            // Error stored in state
+        });
+    }
 }
 exports.RampsController = RampsController;
 _RampsController_requestCacheTTL = new WeakMap(), _RampsController_requestCacheMaxSize = new WeakMap(), _RampsController_pendingRequests = new WeakMap(), _RampsController_instances = new WeakSet(), _RampsController_removeRequestState = function _RampsController_removeRequestState(cacheKey) {
@@ -381,20 +590,32 @@ _RampsController_requestCacheTTL = new WeakMap(), _RampsController_requestCacheM
     });
 }, _RampsController_updateRequestState = function _RampsController_updateRequestState(cacheKey, requestState) {
     const maxSize = __classPrivateFieldGet(this, _RampsController_requestCacheMaxSize, "f");
+    const ttl = __classPrivateFieldGet(this, _RampsController_requestCacheTTL, "f");
     this.update((state) => {
         const requests = state.requests;
         requests[cacheKey] = requestState;
-        // Evict oldest entries if cache exceeds max size
+        // Evict expired entries based on TTL
+        // Only evict SUCCESS states that have exceeded their TTL
         const keys = Object.keys(requests);
-        if (keys.length > maxSize) {
+        for (const key of keys) {
+            const entry = requests[key];
+            if (entry &&
+                entry.status === RequestCache_1.RequestStatus.SUCCESS &&
+                (0, RequestCache_1.isCacheExpired)(entry, ttl)) {
+                delete requests[key];
+            }
+        }
+        // Evict oldest entries if cache still exceeds max size
+        const remainingKeys = Object.keys(requests);
+        if (remainingKeys.length > maxSize) {
             // Sort by timestamp (oldest first)
-            const sortedKeys = keys.sort((a, b) => {
+            const sortedKeys = remainingKeys.sort((a, b) => {
                 const aTime = requests[a]?.timestamp ?? 0;
                 const bTime = requests[b]?.timestamp ?? 0;
                 return aTime - bTime;
             });
             // Remove oldest entries until we're under the limit
-            const entriesToRemove = keys.length - maxSize;
+            const entriesToRemove = remainingKeys.length - maxSize;
             for (let i = 0; i < entriesToRemove; i++) {
                 const keyToRemove = sortedKeys[i];
                 if (keyToRemove) {