@metamask/ramps-controller 19.0.0 → 20.1.0

package/dist/RampsController.mjs

@@ -9,11 +9,13 @@ var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (
     if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
     return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
 };
-var _RampsController_instances, _RampsController_requestCacheTTL, _RampsController_requestCacheMaxSize, _RampsController_pendingRequests, _RampsController_pendingResourceCount, _RampsController_pendingResourceGeneration, _RampsController_orderPollingMeta, _RampsController_orderPollingTimer, _RampsController_isPolling, _RampsController_initPromise, _RampsController_clearPendingResourceCountForDependentResources, _RampsController_abortDependentRequests, _RampsController_resolveAllProvidersFlag, _RampsController_mutateRequests, _RampsController_removeRequestState, _RampsController_cleanupState, _RampsController_requireRegion, _RampsController_isRegionCurrent, _RampsController_isTokenCurrent, _RampsController_isProviderCurrent, _RampsController_updateResourceField, _RampsController_setResourceLoading, _RampsController_setResourceError, _RampsController_updateRequestState, _RampsController_runInit, _RampsController_syncUserRegionFromCountriesCatalog, _RampsController_pickWidenedQuote, _RampsController_getSupportingProvidersForRegion, _RampsController_filterProviderIdsBySupport, _RampsController_resolveProviderIdsForQuote, _RampsController_getPreferredProviderIdsFromOrders, _RampsController_refreshOrder, _RampsController_pollPendingOrders, _RampsController_syncTransakAuthOnError, _RampsController_getNormalizedTransakError;
+var _RampsController_instances, _RampsController_requestCacheTTL, _RampsController_requestCacheMaxSize, _RampsController_pendingRequests, _RampsController_pendingResourceCount, _RampsController_pendingResourceGeneration, _RampsController_orderPollingMeta, _RampsController_orderPollingTimer, _RampsController_isPolling, _RampsController_initPromise, _RampsController_clearPendingResourceCountForDependentResources, _RampsController_abortDependentRequests, _RampsController_resolveAllProvidersFlag, _RampsController_mutateRequests, _RampsController_removeRequestState, _RampsController_cleanupState, _RampsController_requireRegion, _RampsController_isRegionCurrent, _RampsController_isTokenCurrent, _RampsController_isProviderCurrent, _RampsController_updateResourceField, _RampsController_setResourceLoading, _RampsController_setResourceError, _RampsController_updateRequestState, _RampsController_runInit, _RampsController_syncUserRegionFromCountriesCatalog, _RampsController_pickWidenedQuote, _RampsController_getSupportingProvidersForRegion, _RampsController_filterProviderIdsBySupport, _RampsController_resolveProviderIdsForQuote, _RampsController_resolveProviderIdsForPaymentMethods, _RampsController_getPreferredProviderIdsFromOrders, _RampsController_refreshOrder, _RampsController_pollPendingOrders, _RampsController_syncTransakAuthOnError, _RampsController_getNormalizedTransakError;
 import { BaseController } from "@metamask/base-controller";
 import { BrokenCircuitError } from "@metamask/controller-utils";
 import { getHeadlessProviderAllowlist, isHeadlessAllProvidersEnabled, normalizeHeadlessProviderId } from "./featureFlags.mjs";
-import { getProvidersServingAsset, providerServesAsset } from "./providerAvailability.mjs";
+import { PENDING_ORDER_STATUSES, TERMINAL_ORDER_STATUSES } from "./orderStatus.mjs";
+import { mergePaymentMethodsById, pickPaymentMethod } from "./paymentMethodMerge.mjs";
+import { getProvidersServingAsset, normalizeRampsAssetId, providerServesAsset } from "./providerAvailability.mjs";
 import { RAMPS_ERROR_CODES } from "./rampsErrorCodes.mjs";
 import { RampsOrderStatus } from "./RampsService.mjs";
 import { DEFAULT_REQUEST_CACHE_TTL, DEFAULT_REQUEST_CACHE_MAX_SIZE, createCacheKey, isCacheExpired, createLoadingState, createSuccessState, createErrorState, RequestStatus } from "./RequestCache.mjs";
@@ -350,18 +352,6 @@ export function getInternalOrderCode(orderOrId) {
     return providerOrderId;
 }
 // === ORDER POLLING CONSTANTS ===
-const TERMINAL_ORDER_STATUSES = new Set([
-    RampsOrderStatus.Completed,
-    RampsOrderStatus.Failed,
-    RampsOrderStatus.Cancelled,
-    RampsOrderStatus.IdExpired,
-]);
-const PENDING_ORDER_STATUSES = new Set([
-    RampsOrderStatus.Pending,
-    RampsOrderStatus.Created,
-    RampsOrderStatus.Unknown,
-    RampsOrderStatus.Precreated,
-]);
 const DEFAULT_POLLING_INTERVAL_MS = 30000;
 const MAX_ERROR_COUNT = 5;
 // === CONTROLLER DEFINITION ===
@@ -378,6 +368,7 @@ const MESSENGER_EXPOSED_METHODS = [
     'setSelectedToken',
     'getProviders',
     'getPaymentMethods',
+    'getPaymentMethodsForContext',
     'setSelectedPaymentMethod',
     'getQuotes',
     'addOrder',
@@ -417,8 +408,25 @@ const MESSENGER_EXPOSED_METHODS = [
     'transakGetActiveOrders',
 ];
 /**
- * Manages cryptocurrency on/off ramps functionality.
+ * Whether controller state still describes the context a payment-method
+ * request was issued for, so a completed request may write the Buy catalog.
+ *
+ * Compared at commit time rather than against a snapshot, so an older request
+ * that returns after the context moved on is dropped.
+ *
+ * @param state - Controller state at commit time.
+ * @param context - The context the request was issued for.
+ * @param context.region - Normalized region code.
+ * @param context.assetId - Canonicalized CAIP-19 asset id.
+ * @param context.providerId - Trimmed provider id, or an empty string.
+ * @returns Whether the write may proceed.
  */
+function contextStillMatches(state, context) {
+    return (state.userRegion?.regionCode?.trim().toLowerCase() === context.region &&
+        normalizeRampsAssetId(state.tokens.selected?.assetId ?? '') ===
+            context.assetId &&
+        (state.providers.selected?.id.trim() ?? '') === context.providerId);
+}
 export class RampsController extends BaseController {
     /**
      * Clears the pending resource count map. Used only in tests to exercise the
@@ -891,7 +899,7 @@ export class RampsController extends BaseController {
             options?.crypto,
             options?.payments,
         ]);
-        const { providers } = await this.executeRequest(cacheKey, async () => {
+        const response = await this.executeRequest(cacheKey, async () => {
             return this.messenger.call('RampsService:getProviders', normalizedRegion, {
                 provider: options?.provider,
                 crypto: options?.crypto,
@@ -902,13 +910,14 @@ export class RampsController extends BaseController {
             resourceType: 'providers',
             isResultCurrent: () => __classPrivateFieldGet(this, _RampsController_instances, "m", _RampsController_isRegionCurrent).call(this, normalizedRegion),
         });
+        const { providers } = response;
         this.update((state) => {
             const userRegionCode = state.userRegion?.regionCode;
             if (userRegionCode === undefined || userRegionCode === normalizedRegion) {
                 state.providers.data = providers;
             }
         });
-        return { providers };
+        return response;
     }
     /**
      * Fetches the list of payment methods for a given context.
@@ -965,6 +974,146 @@ export class RampsController extends BaseController {
         });
         return response;
     }
+    /**
+     * Fetches payment methods for a quoting context without coupling callers to
+     * the Buy flow's globally selected provider/token catalog.
+     *
+     * Provider contribution mirrors {@link getQuotes}:
+     * - explicit `providers` (optionally filtered when
+     *   `restrictToKnownOrNativeProviders` is set)
+     * - auto-select / restrict path, including `moneyHeadlessAllProviders`
+     *   widening: flag off uses the restricted/native resolver; flag on uses
+     *   supporting providers, intersected with the flag allowlist when that
+     *   allowlist is non-empty (pick-survivor set for picker methods)
+     * - when those resolution flags and `providers` are omitted, uses only
+     *   `providers.selected` (UB2 selected-provider context)
+     *
+     * By default this is request-only: it does **not** mutate
+     * `paymentMethods.data` or `paymentMethods.selected`. Pass `updateState:
+     * true` only when the caller explicitly wants Buy-catalog write semantics
+     * (UB2). Headless / MM Pay selection stays TPC-owned. `updateState: true`
+     * throws when the resolved provider set holds more than one provider, because
+     * the write guards cannot tell two such requests apart.
+     *
+     * Methods are request-eligible for the resolved provider set; they are not
+     * guaranteed to produce a quote for every amount (provider fiat limits still
+     * apply at quote time).
+     *
+     * @param options - Context for the payment-method fetch.
+     * @param options.region - Region code. Defaults to `userRegion`.
+     * @param options.assetId - Required CAIP-19 quoting asset.
+     * @param options.providers - Explicit provider ids.
+     * @param options.autoSelectProvider - Resolve providers like `getQuotes`.
+     * @param options.preferredProviderIds - Preferred ids for auto-selection.
+     * @param options.restrictToKnownOrNativeProviders - Headless gating.
+     * @param options.updateState - When true, write `paymentMethods` state.
+     * @param options.preferPaymentMethodId - Preserve this id when still present.
+     * @param options.forceRefresh - Bypass request cache for provider fetches.
+     * @param options.ttl - Custom TTL for provider payment-method fetches.
+     * @returns Deduped methods, a request-only suggested selection, and the
+     *   provider ids that contributed.
+     */
+    async getPaymentMethodsForContext(options) {
+        const regionToUse = options.region ?? __classPrivateFieldGet(this, _RampsController_instances, "m", _RampsController_requireRegion).call(this);
+        const normalizedRegion = regionToUse.toLowerCase().trim();
+        const assetId = options.assetId.trim();
+        if (assetId === '') {
+            throw new Error('assetId is required.');
+        }
+        const normalizedAssetContext = normalizeRampsAssetId(assetId);
+        const updateState = options.updateState === true;
+        const providerIdForState = options.providers?.length === 1
+            ? options.providers[0].trim()
+            : (this.state.providers.selected?.id.trim() ?? '');
+        const providerIds = await __classPrivateFieldGet(this, _RampsController_instances, "m", _RampsController_resolveProviderIdsForPaymentMethods).call(this, {
+            assetId,
+            region: normalizedRegion,
+            providers: options.providers,
+            autoSelectProvider: options.autoSelectProvider,
+            preferredProviderIds: options.preferredProviderIds,
+            restrictToKnownOrNativeProviders: options.restrictToKnownOrNativeProviders,
+        });
+        // A fan-out across several providers produces a merged catalog whose value
+        // depends on the provider set, but the write guards below only compare
+        // region, selected token, and selected provider. Two concurrent
+        // multi-provider requests share all three, so nothing distinguishes them
+        // and the slower one would silently overwrite the faster one.
+        if (updateState && providerIds.length > 1) {
+            throw new Error(`getPaymentMethodsForContext cannot write paymentMethods state for ${providerIds.length} resolved providers. Use updateState: false, or request exactly one provider.`);
+        }
+        const writeContext = {
+            region: normalizedRegion,
+            assetId: normalizedAssetContext,
+            providerId: providerIdForState,
+        };
+        if (providerIds.length === 0) {
+            if (updateState) {
+                this.update((state) => {
+                    if (contextStillMatches(state, writeContext)) {
+                        state.paymentMethods.data = [];
+                        state.paymentMethods.selected = null;
+                    }
+                });
+            }
+            return { methods: [], selected: null, providerIds };
+        }
+        const settled = await Promise.allSettled(providerIds.map(async (providerId) => {
+            const cacheKey = createCacheKey('getPaymentMethodsForContext', [
+                normalizedRegion,
+                assetId,
+                providerId,
+            ]);
+            return this.executeRequest(cacheKey, async () => {
+                return this.messenger.call('RampsService:getPaymentMethods', {
+                    region: normalizedRegion,
+                    assetId,
+                    provider: providerId,
+                });
+            }, {
+                forceRefresh: options.forceRefresh,
+                ttl: options.ttl,
+                // Intentionally omit resourceType / isResultCurrent so this
+                // request-only path never drives Buy paymentMethods loading or
+                // selection state unless `updateState` is explicitly set below.
+            });
+        }));
+        const successfulLists = [];
+        const failures = [];
+        for (const result of settled) {
+            if (result.status === 'fulfilled') {
+                successfulLists.push(result.value.payments);
+            }
+            else {
+                failures.push(result.reason);
+            }
+        }
+        if (successfulLists.length === 0) {
+            const firstFailure = failures[0];
+            throw firstFailure instanceof Error
+                ? firstFailure
+                : new Error('Failed to fetch payment methods for context.');
+        }
+        const methods = mergePaymentMethodsById(successfulLists);
+        let selected = pickPaymentMethod(methods, [
+            options.preferPaymentMethodId,
+            this.state.paymentMethods.selected?.id,
+        ]);
+        if (updateState) {
+            this.update((state) => {
+                if (contextStillMatches(state, writeContext)) {
+                    // The stored selection outranks the caller's preference: the user may
+                    // have picked a method while this request was in flight.
+                    selected = pickPaymentMethod(methods, [
+                        state.paymentMethods.selected?.id,
+                        options.preferPaymentMethodId,
+                    ]);
+                    state.paymentMethods.data = methods;
+                    state.paymentMethods.selected = selected;
+                }
+            });
+        }
+        return { methods, selected, providerIds };
+    }
     /**
      * Sets the user's selected payment method.
      *
@@ -1289,7 +1438,7 @@ export class RampsController extends BaseController {
      * @param params.orderId - Full order ID (e.g. "/providers/paypal/orders/abc123") or order code.
      * @param params.providerCode - Canonical provider code (e.g. "paypal", "transak").
      * @param params.walletAddress - Wallet address for the order.
-     * @param params.chainId - Optional chain ID for the order.
+     * @param params.chainId - Chain ID for the order (decimal, hex, or CAIP-2). Must be non-empty.
      */
     addPrecreatedOrder(params) {
         const { orderId, providerCode, walletAddress, chainId } = params;
@@ -1297,6 +1446,9 @@ export class RampsController extends BaseController {
         if (!orderCode?.trim()) {
             return;
         }
+        if (!chainId.trim()) {
+            return;
+        }
         const stubOrder = {
             providerOrderId: orderCode,
             provider: {
@@ -1319,7 +1471,7 @@ export class RampsController extends BaseController {
             providerOrderLink: '',
             totalFeesFiat: 0,
             txHash: '',
-            network: chainId ? { chainId, name: '' } : { chainId: '', name: '' },
+            network: { chainId, name: '' },
             canBeUpdated: true,
             idHasExpired: false,
             excludeFromPurchases: false,
@@ -2114,6 +2266,64 @@ async function _RampsController_resolveProviderIdsForQuote({ assetId, region, pr
         return [];
     }
     return [supporting[0].id];
+}, _RampsController_resolveProviderIdsForPaymentMethods = 
+/**
+ * Resolves provider IDs that should contribute payment methods for a
+ * quoting context. Mirrors {@link getQuotes} provider-set selection, with
+ * one intentional difference on the widened path: when the all-providers
+ * flag allowlist is non-empty, returns supporting providers intersected
+ * with that allowlist (pick survivors for the picker). Does not mutate
+ * state.
+ *
+ * @param options - Resolution inputs aligned with `getQuotes`.
+ * @param options.assetId - CAIP-19 asset type identifier to resolve for.
+ * @param options.region - Region to resolve providers for.
+ * @param options.providers - Explicit provider IDs, when provided.
+ * @param options.autoSelectProvider - Resolve providers like `getQuotes`.
+ * @param options.preferredProviderIds - Preferred provider IDs in order.
+ * @param options.restrictToKnownOrNativeProviders - Headless gating.
+ * @returns Provider IDs for this request only.
+ */
+async function _RampsController_resolveProviderIdsForPaymentMethods({ assetId, region, providers, autoSelectProvider, preferredProviderIds, restrictToKnownOrNativeProviders, }) {
+    const wantsAutoSelection = !providers &&
+        (autoSelectProvider === true ||
+            restrictToKnownOrNativeProviders === true);
+    const { enabled: allProvidersEnabled, allowlist: providerAllowlist } = wantsAutoSelection
+        ? __classPrivateFieldGet(this, _RampsController_instances, "m", _RampsController_resolveAllProvidersFlag).call(this)
+        : { enabled: false, allowlist: undefined };
+    const widenToAllProviders = wantsAutoSelection && allProvidersEnabled;
+    if (providers) {
+        return restrictToKnownOrNativeProviders
+            ? __classPrivateFieldGet(this, _RampsController_instances, "m", _RampsController_filterProviderIdsBySupport).call(this, {
+                providerIds: providers,
+                assetId,
+                region,
+            })
+            : providers;
+    }
+    if (widenToAllProviders) {
+        const { supporting } = await __classPrivateFieldGet(this, _RampsController_instances, "m", _RampsController_getSupportingProvidersForRegion).call(this, {
+            assetId,
+            region,
+        });
+        if (providerAllowlist && providerAllowlist.length > 0) {
+            const allowedProviderIds = new Set(providerAllowlist.map(normalizeHeadlessProviderId));
+            return supporting
+                .filter((provider) => allowedProviderIds.has(normalizeHeadlessProviderId(provider.id)))
+                .map((provider) => provider.id);
+        }
+        return supporting.map((provider) => provider.id);
+    }
+    if (autoSelectProvider || restrictToKnownOrNativeProviders) {
+        return __classPrivateFieldGet(this, _RampsController_instances, "m", _RampsController_resolveProviderIdsForQuote).call(this, {
+            assetId,
+            region,
+            preferredProviderIds,
+            restrictToKnownOrNative: restrictToKnownOrNativeProviders,
+        });
+    }
+    const selectedId = this.state.providers.selected?.id;
+    return selectedId ? [selectedId] : [];
 }, _RampsController_getPreferredProviderIdsFromOrders = function _RampsController_getPreferredProviderIdsFromOrders() {
     const orderedIds = [];
     const completedOrders = this.state.orders