@metamask/ramps-controller 4.1.0 → 5.0.0

package/dist/RampsController.mjs

@@ -9,7 +9,7 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
     if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
     return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
 };
-var _RampsController_instances, _RampsController_requestCacheTTL, _RampsController_requestCacheMaxSize, _RampsController_pendingRequests, _RampsController_removeRequestState, _RampsController_updateRequestState;
+var _RampsController_instances, _RampsController_requestCacheTTL, _RampsController_requestCacheMaxSize, _RampsController_pendingRequests, _RampsController_removeRequestState, _RampsController_cleanupState, _RampsController_updateRequestState;
 import { BaseController } from "@metamask/base-controller";
 import { DEFAULT_REQUEST_CACHE_TTL, DEFAULT_REQUEST_CACHE_MAX_SIZE, createCacheKey, isCacheExpired, createLoadingState, createSuccessState, createErrorState, RequestStatus } from "./RequestCache.mjs";
 // === GENERAL ===
@@ -29,7 +29,13 @@ const rampsControllerMetadata = {
         includeInStateLogs: true,
         usedInUi: true,
     },
-    preferredProvider: {
+    selectedProvider: {
+        persist: false,
+        includeInDebugSnapshot: true,
+        includeInStateLogs: true,
+        usedInUi: true,
+    },
+    countries: {
         persist: true,
         includeInDebugSnapshot: true,
         includeInStateLogs: true,
@@ -47,6 +53,12 @@ const rampsControllerMetadata = {
         includeInStateLogs: true,
         usedInUi: true,
     },
+    selectedToken: {
+        persist: false,
+        includeInDebugSnapshot: true,
+        includeInStateLogs: true,
+        usedInUi: true,
+    },
     paymentMethods: {
         persist: false,
         includeInDebugSnapshot: true,
@@ -77,9 +89,11 @@ const rampsControllerMetadata = {
 export function getDefaultRampsControllerState() {
     return {
         userRegion: null,
-        preferredProvider: null,
+        selectedProvider: null,
+        countries: [],
         providers: [],
         tokens: null,
+        selectedToken: null,
         paymentMethods: [],
         selectedPaymentMethod: null,
         requests: {},
@@ -201,7 +215,6 @@ export class RampsController extends BaseController {
         if (pending) {
             return pending.promise;
         }
-        // Check cache validity (unless force refresh)
         if (!options?.forceRefresh) {
             const cached = this.state.requests[cacheKey];
             if (cached && !isCacheExpired(cached, ttl)) {
@@ -270,96 +283,6 @@ export class RampsController extends BaseController {
     getRequestState(cacheKey) {
         return this.state.requests[cacheKey];
     }
-    /**
-     * 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 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 and region-dependent state before fetching
-        if (options?.forceRefresh) {
-            this.update((state) => {
-                state.userRegion = null;
-                state.tokens = null;
-                state.providers = [];
-                state.paymentMethods = [];
-                state.selectedPaymentMethod = null;
-            });
-        }
-        const cacheKey = createCacheKey('updateUserRegion', []);
-        const regionCode = await this.executeRequest(cacheKey, async () => {
-            const result = await this.messenger.call('RampsService:getGeolocation');
-            return result;
-        }, options);
-        if (!regionCode) {
-            this.update((state) => {
-                state.userRegion = null;
-                state.tokens = null;
-                state.providers = [];
-                state.paymentMethods = [];
-                state.selectedPaymentMethod = null;
-            });
-            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 regionChanged = state.userRegion?.regionCode !== userRegion.regionCode;
-                    state.userRegion = userRegion;
-                    // Clear region-dependent state when region changes
-                    if (regionChanged) {
-                        state.tokens = null;
-                        state.providers = [];
-                        state.paymentMethods = [];
-                        state.selectedPaymentMethod = null;
-                    }
-                });
-                // 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 = [];
-                state.paymentMethods = [];
-                state.selectedPaymentMethod = null;
-            });
-            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 = [];
-                state.paymentMethods = [];
-                state.selectedPaymentMethod = null;
-            });
-            return null;
-        }
-    }
     /**
      * Sets the user's region manually (without fetching geolocation).
      * This allows users to override the detected region.
@@ -371,106 +294,129 @@ export class RampsController extends BaseController {
     async setUserRegion(region, options) {
         const normalizedRegion = region.toLowerCase().trim();
         try {
-            const countries = await this.getCountries('buy', options);
+            const { countries } = this.state;
+            if (!countries || countries.length === 0) {
+                __classPrivateFieldGet(this, _RampsController_instances, "m", _RampsController_cleanupState).call(this);
+                throw new Error('No countries found. Cannot set user region without valid country information.');
+            }
             const userRegion = findRegionFromCode(normalizedRegion, countries);
-            if (userRegion) {
-                this.update((state) => {
-                    state.userRegion = userRegion;
+            if (!userRegion) {
+                __classPrivateFieldGet(this, _RampsController_instances, "m", _RampsController_cleanupState).call(this);
+                throw new Error(`Region "${normalizedRegion}" not found in countries data. Cannot set user region without valid country information.`);
+            }
+            // Only cleanup state if region is actually changing
+            const regionChanged = normalizedRegion !== this.state.userRegion?.regionCode;
+            // Set the new region atomically with cleanup to avoid intermediate null state
+            this.update((state) => {
+                if (regionChanged) {
+                    state.selectedProvider = null;
+                    state.selectedToken = null;
                     state.tokens = null;
                     state.providers = [];
                     state.paymentMethods = [];
                     state.selectedPaymentMethod = null;
-                });
-                // 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 = [];
-                state.paymentMethods = [];
-                state.selectedPaymentMethod = null;
+                state.userRegion = userRegion;
             });
-            throw new Error(`Region "${normalizedRegion}" not found in countries data. Cannot set user region without valid country information.`);
+            // Only trigger fetches if region changed or if data is missing
+            if (regionChanged || !this.state.tokens) {
+                this.triggerGetTokens(userRegion.regionCode, 'buy', options);
+            }
+            if (regionChanged || this.state.providers.length === 0) {
+                this.triggerGetProviders(userRegion.regionCode, options);
+            }
+            return userRegion;
         }
         catch (error) {
-            // 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) => {
-                state.userRegion = null;
-                state.tokens = null;
-                state.providers = [];
-                state.paymentMethods = [];
-                state.selectedPaymentMethod = null;
-            });
-            throw new Error('Failed to fetch countries data. Cannot set user region without valid country information.');
+            __classPrivateFieldGet(this, _RampsController_instances, "m", _RampsController_cleanupState).call(this);
+            throw error;
         }
     }
     /**
-     * Sets the user's preferred provider.
-     * This allows users to set their preferred ramp provider.
+     * Sets the user's selected provider by ID, or clears the selection.
+     * Looks up the provider from the current providers in state and automatically
+     * fetches payment methods for that provider.
      *
-     * @param provider - The provider object to set.
+     * @param providerId - The provider ID (e.g., "/providers/moonpay"), or null to clear.
+     * @throws If region is not set, providers are not loaded, or provider is not found.
      */
-    setPreferredProvider(provider) {
+    setSelectedProvider(providerId) {
+        if (providerId === null) {
+            this.update((state) => {
+                state.selectedProvider = null;
+                state.paymentMethods = [];
+                state.selectedPaymentMethod = null;
+            });
+            return;
+        }
+        const regionCode = this.state.userRegion?.regionCode;
+        if (!regionCode) {
+            throw new Error('Region is required. Cannot set selected provider without valid region information.');
+        }
+        const { providers } = this.state;
+        if (!providers || providers.length === 0) {
+            throw new Error('Providers not loaded. Cannot set selected provider before providers are fetched.');
+        }
+        const provider = providers.find((prov) => prov.id === providerId);
+        if (!provider) {
+            throw new Error(`Provider with ID "${providerId}" not found in available providers.`);
+        }
         this.update((state) => {
-            state.preferredProvider = provider;
+            state.selectedProvider = provider;
+            state.paymentMethods = [];
+            state.selectedPaymentMethod = null;
+        });
+        // fetch payment methods for the new provider
+        // this is needed because you can change providers without changing the token
+        // (getPaymentMethods will use state as its default)
+        this.triggerGetPaymentMethods(regionCode, {
+            provider: provider.id,
         });
     }
     /**
      * 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, 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.
+     * this method will skip geolocation fetch and use the existing region.
      *
      * @param options - Options for cache behavior.
      * @returns Promise that resolves when initialization is complete.
      */
     async init(options) {
-        const userRegion = await this.updateUserRegion(options).catch(() => {
-            // User region fetch failed - error state will be available via selectors
-            return null;
-        });
-        if (userRegion) {
-            try {
-                await this.getTokens(userRegion.regionCode, 'buy', options);
-            }
-            catch {
-                // Token fetch failed - error state will be available via selectors
-            }
-            try {
-                await this.getProviders(userRegion.regionCode, options);
-            }
-            catch {
-                // Provider fetch failed - error state will be available via selectors
-            }
+        await this.getCountries(options);
+        let regionCode = this.state.userRegion?.regionCode;
+        regionCode ?? (regionCode = await this.messenger.call('RampsService:getGeolocation'));
+        if (!regionCode) {
+            throw new Error('Failed to fetch geolocation. Cannot initialize controller without valid region information.');
+        }
+        await this.setUserRegion(regionCode, options);
+    }
+    hydrateState(options) {
+        const regionCode = this.state.userRegion?.regionCode;
+        if (!regionCode) {
+            throw new Error('Region code is required. Cannot hydrate state without valid region information.');
         }
+        this.triggerGetTokens(regionCode, 'buy', options);
+        this.triggerGetProviders(regionCode, options);
     }
     /**
-     * Fetches the list of supported countries for a given ramp action.
+     * Fetches the list of supported countries.
+     * The API returns countries with support information for both buy and sell actions.
+     * The countries are saved in the controller state once fetched.
      *
-     * @param action - The ramp action type ('buy' or 'sell').
      * @param options - Options for cache behavior.
      * @returns An array of countries.
      */
-    async getCountries(action = 'buy', options) {
-        const cacheKey = createCacheKey('getCountries', [action]);
-        return this.executeRequest(cacheKey, async () => {
-            return this.messenger.call('RampsService:getCountries', action);
+    async getCountries(options) {
+        const cacheKey = createCacheKey('getCountries', []);
+        const countries = await this.executeRequest(cacheKey, async () => {
+            return this.messenger.call('RampsService:getCountries');
         }, options);
+        this.update((state) => {
+            state.countries = countries;
+        });
+        return countries;
     }
     /**
      * Fetches the list of available tokens for a given region and action.
@@ -506,6 +452,45 @@ export class RampsController extends BaseController {
         });
         return tokens;
     }
+    /**
+     * Sets the user's selected token by asset ID.
+     * Looks up the token from the current tokens in state and automatically
+     * fetches payment methods for that token.
+     *
+     * @param assetId - The asset identifier in CAIP-19 format (e.g., "eip155:1/erc20:0x..."), or undefined to clear.
+     * @throws If region is not set, tokens are not loaded, or token is not found.
+     */
+    setSelectedToken(assetId) {
+        if (!assetId) {
+            this.update((state) => {
+                state.selectedToken = null;
+                state.paymentMethods = [];
+                state.selectedPaymentMethod = null;
+            });
+            return;
+        }
+        const regionCode = this.state.userRegion?.regionCode;
+        if (!regionCode) {
+            throw new Error('Region is required. Cannot set selected token without valid region information.');
+        }
+        const { tokens } = this.state;
+        if (!tokens) {
+            throw new Error('Tokens not loaded. Cannot set selected token before tokens are fetched.');
+        }
+        const token = tokens.allTokens.find((tok) => tok.assetId === assetId) ??
+            tokens.topTokens.find((tok) => tok.assetId === assetId);
+        if (!token) {
+            throw new Error(`Token with asset ID "${assetId}" not found in available tokens.`);
+        }
+        this.update((state) => {
+            state.selectedToken = token;
+            state.paymentMethods = [];
+            state.selectedPaymentMethod = null;
+        });
+        this.triggerGetPaymentMethods(regionCode, {
+            assetId: token.assetId,
+        });
+    }
     /**
      * Fetches the list of providers for a given region.
      * The providers are saved in the controller state once fetched.
@@ -551,57 +536,81 @@ export class RampsController extends BaseController {
      * Fetches the list of payment methods for a given context.
      * The payment methods are saved in the controller state once fetched.
      *
+     * @param region - User's region code (e.g. "fr", "us-ny").
      * @param options - Query parameters for filtering payment methods.
-     * @param options.region - User's region code. If not provided, uses the user's region from controller state.
      * @param options.fiat - Fiat currency code (e.g., "usd"). If not provided, uses the user's region currency.
      * @param options.assetId - CAIP-19 cryptocurrency identifier.
      * @param options.provider - Provider ID path.
-     * @param options.forceRefresh - Whether to bypass cache.
-     * @param options.ttl - Custom TTL for this request.
      * @returns The payment methods response containing payments array.
      */
-    async getPaymentMethods(options) {
-        const regionToUse = options.region ?? this.state.userRegion?.regionCode;
-        const fiatToUse = options.fiat ?? this.state.userRegion?.country?.currency;
-        if (!regionToUse) {
+    async getPaymentMethods(region, options) {
+        const regionCode = region ?? this.state.userRegion?.regionCode ?? null;
+        const fiatToUse = options?.fiat ?? this.state.userRegion?.country?.currency ?? null;
+        const assetIdToUse = options?.assetId ?? this.state.selectedToken?.assetId ?? '';
+        const providerToUse = options?.provider ?? this.state.selectedProvider?.id ?? '';
+        if (!regionCode) {
             throw new Error('Region is required. Either provide a region parameter or ensure userRegion is set in controller state.');
         }
         if (!fiatToUse) {
             throw new Error('Fiat currency is required. Either provide a fiat parameter or ensure userRegion is set in controller state.');
         }
-        const normalizedRegion = regionToUse.toLowerCase().trim();
+        const normalizedRegion = regionCode.toLowerCase().trim();
         const normalizedFiat = fiatToUse.toLowerCase().trim();
         const cacheKey = createCacheKey('getPaymentMethods', [
             normalizedRegion,
             normalizedFiat,
-            options.assetId,
-            options.provider,
+            assetIdToUse,
+            providerToUse,
         ]);
         const response = await this.executeRequest(cacheKey, async () => {
             return this.messenger.call('RampsService:getPaymentMethods', {
                 region: normalizedRegion,
                 fiat: normalizedFiat,
-                assetId: options.assetId,
-                provider: options.provider,
+                assetId: assetIdToUse,
+                provider: providerToUse,
             });
-        }, { forceRefresh: options.forceRefresh, ttl: options.ttl });
+        }, options);
         this.update((state) => {
-            state.paymentMethods = response.payments;
-            // Only clear selected payment method if it's no longer in the new list
-            // This preserves the selection when cached data is returned (same context)
-            if (state.selectedPaymentMethod &&
-                !response.payments.some((pm) => pm.id === state.selectedPaymentMethod?.id)) {
-                state.selectedPaymentMethod = null;
+            const currentAssetId = state.selectedToken?.assetId ?? '';
+            const currentProviderId = state.selectedProvider?.id ?? '';
+            const tokenSelectionUnchanged = assetIdToUse === currentAssetId;
+            const providerSelectionUnchanged = providerToUse === currentProviderId;
+            // this is a race condition check to ensure that the selected token and provider in state are the same as the tokens we're requesting for
+            // ex: if the user rapidly changes the token or provider, the in-flight payment methods might not be valid
+            // so this check will ensure that the payment methods are still valid for the token and provider that were requested
+            if (tokenSelectionUnchanged && providerSelectionUnchanged) {
+                state.paymentMethods = response.payments;
+                // this will auto-select the first payment method if the selected payment method is not in the new payment methods
+                const currentSelectionStillValid = response.payments.some((pm) => pm.id === state.selectedPaymentMethod?.id);
+                if (!currentSelectionStillValid) {
+                    state.selectedPaymentMethod = response.payments[0] ?? null;
+                }
             }
         });
         return response;
     }
     /**
-     * Sets the user's selected payment method.
+     * Sets the user's selected payment method by ID.
+     * Looks up the payment method from the current payment methods in state.
      *
-     * @param paymentMethod - The payment method to select, or null to clear.
+     * @param paymentMethodId - The payment method ID (e.g., "/payments/debit-credit-card"), or null to clear.
+     * @throws If payment methods are not loaded or payment method is not found.
      */
-    setSelectedPaymentMethod(paymentMethod) {
+    setSelectedPaymentMethod(paymentMethodId) {
+        if (!paymentMethodId) {
+            this.update((state) => {
+                state.selectedPaymentMethod = null;
+            });
+            return;
+        }
+        const { paymentMethods } = this.state;
+        if (!paymentMethods || paymentMethods.length === 0) {
+            throw new Error('Payment methods not loaded. Cannot set selected payment method before payment methods are fetched.');
+        }
+        const paymentMethod = paymentMethods.find((pm) => pm.id === paymentMethodId);
+        if (!paymentMethod) {
+            throw new Error(`Payment method with ID "${paymentMethodId}" not found in available payment methods.`);
+        }
         this.update((state) => {
             state.selectedPaymentMethod = paymentMethod;
         });
@@ -611,16 +620,6 @@ export class RampsController extends BaseController {
     // 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.
      *
@@ -635,11 +634,10 @@ export class RampsController extends BaseController {
     /**
      * 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(() => {
+    triggerGetCountries(options) {
+        this.getCountries(options).catch(() => {
             // Error stored in state
         });
     }
@@ -669,16 +667,14 @@ export class RampsController extends BaseController {
     /**
      * Triggers fetching payment methods without throwing.
      *
+     * @param region - User's region code (e.g., "us", "fr", "us-ny").
      * @param options - Query parameters for filtering payment methods.
-     * @param options.region - User's region code. If not provided, uses userRegion from state.
      * @param options.fiat - Fiat currency code. If not provided, uses userRegion currency.
      * @param options.assetId - CAIP-19 cryptocurrency identifier.
      * @param options.provider - Provider ID path.
-     * @param options.forceRefresh - Whether to bypass cache.
-     * @param options.ttl - Custom TTL for this request.
      */
-    triggerGetPaymentMethods(options) {
-        this.getPaymentMethods(options).catch(() => {
+    triggerGetPaymentMethods(region, options) {
+        this.getPaymentMethods(region, options).catch(() => {
             // Error stored in state
         });
     }
@@ -688,6 +684,16 @@ _RampsController_requestCacheTTL = new WeakMap(), _RampsController_requestCacheM
         const requests = state.requests;
         delete requests[cacheKey];
     });
+}, _RampsController_cleanupState = function _RampsController_cleanupState() {
+    this.update((state) => {
+        state.userRegion = null;
+        state.selectedProvider = null;
+        state.selectedToken = null;
+        state.tokens = null;
+        state.providers = [];
+        state.paymentMethods = [];
+        state.selectedPaymentMethod = null;
+    });
 }, _RampsController_updateRequestState = function _RampsController_updateRequestState(cacheKey, requestState) {
     const maxSize = __classPrivateFieldGet(this, _RampsController_requestCacheMaxSize, "f");
     const ttl = __classPrivateFieldGet(this, _RampsController_requestCacheTTL, "f");