@metamask/ramps-controller 4.0.0 → 5.0.0

package/dist/RampsController.mjs

@@ -9,9 +9,9 @@ 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 } from "./RequestCache.mjs";
+import { DEFAULT_REQUEST_CACHE_TTL, DEFAULT_REQUEST_CACHE_MAX_SIZE, createCacheKey, isCacheExpired, createLoadingState, createSuccessState, createErrorState, RequestStatus } from "./RequestCache.mjs";
 // === GENERAL ===
 /**
  * The name of the {@link RampsController}, used to namespace the
@@ -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,24 @@ const rampsControllerMetadata = {
         includeInStateLogs: true,
         usedInUi: true,
     },
+    selectedToken: {
+        persist: false,
+        includeInDebugSnapshot: true,
+        includeInStateLogs: true,
+        usedInUi: true,
+    },
+    paymentMethods: {
+        persist: false,
+        includeInDebugSnapshot: true,
+        includeInStateLogs: true,
+        usedInUi: true,
+    },
+    selectedPaymentMethod: {
+        persist: false,
+        includeInDebugSnapshot: true,
+        includeInStateLogs: true,
+        usedInUi: true,
+    },
     requests: {
         persist: false,
         includeInDebugSnapshot: true,
@@ -65,9 +89,13 @@ const rampsControllerMetadata = {
 export function getDefaultRampsControllerState() {
     return {
         userRegion: null,
-        preferredProvider: null,
+        selectedProvider: null,
+        countries: [],
         providers: [],
         tokens: null,
+        selectedToken: null,
+        paymentMethods: [],
+        selectedPaymentMethod: null,
         requests: {},
     };
 }
@@ -187,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)) {
@@ -256,86 +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, tokens, and providers before fetching
-        if (options?.forceRefresh) {
-            this.update((state) => {
-                state.userRegion = null;
-                state.tokens = null;
-                state.providers = [];
-            });
-        }
-        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 = [];
-            });
-            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 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;
-        }
-    }
     /**
      * Sets the user's region manually (without fetching geolocation).
      * This allows users to override the detected region.
@@ -347,100 +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 = [];
-                });
-                // Fetch providers for the new region
-                try {
-                    await this.getProviders(userRegion.regionCode, options);
-                }
-                catch {
-                    // Provider fetch failed - error state will be available via selectors
+                    state.paymentMethods = [];
+                    state.selectedPaymentMethod = null;
                 }
-                return userRegion;
-            }
-            // Region not found in countries data
-            this.update((state) => {
-                state.userRegion = null;
-                state.tokens = null;
-                state.providers = [];
+                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 = [];
-            });
-            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.
@@ -448,7 +424,8 @@ export class RampsController extends 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) {
@@ -457,9 +434,15 @@ export class RampsController extends BaseController {
             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 = createCacheKey('getTokens', [normalizedRegion, action]);
+        const cacheKey = 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 userRegionCode = state.userRegion?.regionCode;
@@ -469,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.
@@ -510,28 +532,196 @@ export class RampsController extends BaseController {
         });
         return { providers };
     }
+    /**
+     * 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.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.
+     * @returns The payment methods response containing payments array.
+     */
+    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 = regionCode.toLowerCase().trim();
+        const normalizedFiat = fiatToUse.toLowerCase().trim();
+        const cacheKey = createCacheKey('getPaymentMethods', [
+            normalizedRegion,
+            normalizedFiat,
+            assetIdToUse,
+            providerToUse,
+        ]);
+        const response = await this.executeRequest(cacheKey, async () => {
+            return this.messenger.call('RampsService:getPaymentMethods', {
+                region: normalizedRegion,
+                fiat: normalizedFiat,
+                assetId: assetIdToUse,
+                provider: providerToUse,
+            });
+        }, options);
+        this.update((state) => {
+            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 by ID.
+     * Looks up the payment method from the current payment methods in state.
+     *
+     * @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(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;
+        });
+    }
+    // ============================================================
+    // Sync Trigger Methods
+    // These fire-and-forget methods are for use in React effects.
+    // Errors are stored in state and available via selectors.
+    // ============================================================
+    /**
+     * 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 options - Options for cache behavior.
+     */
+    triggerGetCountries(options) {
+        this.getCountries(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
+        });
+    }
+    /**
+     * 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.fiat - Fiat currency code. If not provided, uses userRegion currency.
+     * @param options.assetId - CAIP-19 cryptocurrency identifier.
+     * @param options.provider - Provider ID path.
+     */
+    triggerGetPaymentMethods(region, options) {
+        this.getPaymentMethods(region, options).catch(() => {
+            // Error stored in state
+        });
+    }
 }
 _RampsController_requestCacheTTL = new WeakMap(), _RampsController_requestCacheMaxSize = new WeakMap(), _RampsController_pendingRequests = new WeakMap(), _RampsController_instances = new WeakSet(), _RampsController_removeRequestState = function _RampsController_removeRequestState(cacheKey) {
     this.update((state) => {
         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");
     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 === RequestStatus.SUCCESS &&
+                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) {