@metamask/ramps-controller 20.0.0 → 20.2.0

package/dist/RampsController.cjs

@@ -10,12 +10,14 @@ 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;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RampsController = exports.getInternalOrderCode = exports.getDefaultRampsControllerState = exports.RAMPS_CONTROLLER_REQUIRED_SERVICE_ACTIONS = exports.controllerName = void 0;
 const base_controller_1 = require("@metamask/base-controller");
 const controller_utils_1 = require("@metamask/controller-utils");
 const featureFlags_js_1 = require("./featureFlags.cjs");
+const orderStatus_js_1 = require("./orderStatus.cjs");
+const paymentMethodMerge_js_1 = require("./paymentMethodMerge.cjs");
 const providerAvailability_js_1 = require("./providerAvailability.cjs");
 const rampsErrorCodes_js_1 = require("./rampsErrorCodes.cjs");
 const RampsService_js_1 = require("./RampsService.cjs");
@@ -355,18 +357,6 @@ function getInternalOrderCode(orderOrId) {
 }
 exports.getInternalOrderCode = getInternalOrderCode;
 // === ORDER POLLING CONSTANTS ===
-const TERMINAL_ORDER_STATUSES = new Set([
-    RampsService_js_1.RampsOrderStatus.Completed,
-    RampsService_js_1.RampsOrderStatus.Failed,
-    RampsService_js_1.RampsOrderStatus.Cancelled,
-    RampsService_js_1.RampsOrderStatus.IdExpired,
-]);
-const PENDING_ORDER_STATUSES = new Set([
-    RampsService_js_1.RampsOrderStatus.Pending,
-    RampsService_js_1.RampsOrderStatus.Created,
-    RampsService_js_1.RampsOrderStatus.Unknown,
-    RampsService_js_1.RampsOrderStatus.Precreated,
-]);
 const DEFAULT_POLLING_INTERVAL_MS = 30000;
 const MAX_ERROR_COUNT = 5;
 // === CONTROLLER DEFINITION ===
@@ -383,6 +373,7 @@ const MESSENGER_EXPOSED_METHODS = [
     'setSelectedToken',
     'getProviders',
     'getPaymentMethods',
+    'getPaymentMethodsForContext',
     'setSelectedPaymentMethod',
     'getQuotes',
     'addOrder',
@@ -422,8 +413,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 &&
+        (0, providerAvailability_js_1.normalizeRampsAssetId)(state.tokens.selected?.assetId ?? '') ===
+            context.assetId &&
+        (state.providers.selected?.id.trim() ?? '') === context.providerId);
+}
 class RampsController extends base_controller_1.BaseController {
     /**
      * Clears the pending resource count map. Used only in tests to exercise the
@@ -896,7 +904,7 @@ class RampsController extends base_controller_1.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,
@@ -907,13 +915,14 @@ class RampsController extends base_controller_1.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.
@@ -970,6 +979,146 @@ class RampsController extends base_controller_1.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 = (0, providerAvailability_js_1.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 = (0, RequestCache_js_1.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 = (0, paymentMethodMerge_js_1.mergePaymentMethodsById)(successfulLists);
+        let selected = (0, paymentMethodMerge_js_1.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 = (0, paymentMethodMerge_js_1.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.
      *
@@ -2123,6 +2272,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(featureFlags_js_1.normalizeHeadlessProviderId));
+            return supporting
+                .filter((provider) => allowedProviderIds.has((0, featureFlags_js_1.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
@@ -2169,7 +2376,7 @@ async function _RampsController_refreshOrder(order) {
                 previousStatus,
             });
         }
-        if (TERMINAL_ORDER_STATUSES.has(updatedOrder.status)) {
+        if (orderStatus_js_1.TERMINAL_ORDER_STATUSES.has(updatedOrder.status)) {
             __classPrivateFieldGet(this, _RampsController_orderPollingMeta, "f").delete(order.providerOrderId);
         }
     }
@@ -2188,7 +2395,7 @@ async function _RampsController_refreshOrder(order) {
     }
     __classPrivateFieldSet(this, _RampsController_isPolling, true, "f");
     try {
-        const pendingOrders = this.state.orders.filter((order) => PENDING_ORDER_STATUSES.has(order.status));
+        const pendingOrders = this.state.orders.filter((order) => orderStatus_js_1.PENDING_ORDER_STATUSES.has(order.status));
         const now = Date.now();
         await Promise.allSettled(pendingOrders.map(async (order) => {
             const meta = __classPrivateFieldGet(this, _RampsController_orderPollingMeta, "f").get(order.providerOrderId);