@metamask-previews/ramps-controller 15.1.0-preview-a511f243f → 16.0.0-preview-2fd14c0c3

package/CHANGELOG.md

@@ -7,9 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Add the `MONEY_HEADLESS_ALL_PROVIDERS_FLAG_KEY` constant (`moneyHeadlessAllProviders`) and the pure `isHeadlessAllProvidersEnabled(remoteFeatureFlagState)` helper (with a `HeadlessFeatureFlagsLookup` type) that own the flag key lookup, `localOverrides`-over-`remoteFeatureFlags` merging, and boolean coercion (only the literal `true` enables), so UI consumers resolve the flag exactly like the controller does ([#9409](https://github.com/MetaMask/core/pull/9409))
+- Add pure provider-availability helpers `providerServesAsset`, `getProvidersServingAsset`, `regionHasProviderForAsset`, and `isFiatDepositAvailable` so headless-buy consumers can share the controller's case-insensitive CAIP-19 asset matching and flag-aware region/availability gating instead of re-deriving it, keeping the two from disagreeing; `regionHasProviderForAsset` and `isFiatDepositAvailable` take an `allProvidersEnabled` boolean ([#9409](https://github.com/MetaMask/core/pull/9409))
+- Add pure quote-classification helpers `isExternalBrowserQuote`, `isCustomActionQuote`, and `isInAppOnlyQuote` so consumers can share the in-app-vs-external browser-mode classification without owning host redirect/deeplink concerns ([#9409](https://github.com/MetaMask/core/pull/9409))
+- Add pure error-normalization helpers `getErrorMessage`, `extractExplicitTypedError`, and `normalizeToTypedError` (with a `TypedError<Code>` type) so consumers can share error-shape extraction while keeping their own error-code taxonomy ([#9409](https://github.com/MetaMask/core/pull/9409))
+- Add `@metamask/remote-feature-flag-controller` `^4.2.2` as a runtime dependency ([#9409](https://github.com/MetaMask/core/pull/9409))
+
+### Changed
+
+- **BREAKING:** Replace the `getProviderScope` constructor option and the exported `ProviderScope` type (`'off' | 'in-app' | 'all'`) with a controller-side read of the `moneyHeadlessAllProviders` boolean remote feature flag ([#9409](https://github.com/MetaMask/core/pull/9409))
+  - `RampsController.getQuotes` resolves the flag through the `RemoteFeatureFlagController:getState` messenger action on each auto-selection call, so a remote fetch or a local dev override takes effect at runtime; consumers should delegate that action to the controller's messenger (when it is missing, the flag read fails closed and quoting stays native-only)
+  - When the flag is `true`, the auto-selection path (`autoSelectProvider` / `restrictToKnownOrNativeProviders`) widens to every supporting provider class (native, in-app WebView aggregator, and external-browser / custom-action) and returns the best quote at `success[0]`, enforcing per-provider fiat limits; when the flag is `false`, missing, or any non-boolean value, the path stays native-only
+  - The intermediate `in-app` scope (which excluded external-browser and custom-action quotes from selection) is removed
+- `RampsController` now derives its internal region provider-asset matching from the shared `providerAvailability` helpers, so the exposed helpers stay behaviourally identical to the controller's own selection ([#9409](https://github.com/MetaMask/core/pull/9409))
+
+## [16.0.0]
+
 ### Changed
 
 - **BREAKING:** Provider IDs are no longer normalized by stripping a `/providers/` prefix. `RampsController.getQuotes` now matches provider IDs from the providers list, quotes, custom actions, and sort order as-is, and a precreated stub order's `provider.id` is the canonical provider code passed to the create-order call rather than a `/providers/`-prefixed value. Consumers must supply non-prefixed (canonical) provider IDs ([#9448](https://github.com/MetaMask/core/pull/9448))
+- Update `LICENSE` text ([#9472](https://github.com/MetaMask/core/pull/9472))
 - Bump `@metamask/profile-sync-controller` from `^28.2.0` to `^28.3.0` ([#9463](https://github.com/MetaMask/core/pull/9463))
 
 ### Removed
@@ -420,7 +439,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Add `OnRampService` for interacting with the OnRamp API
   - Add geolocation detection via IP address lookup
 
-[Unreleased]: https://github.com/MetaMask/core/compare/@metamask/ramps-controller@15.1.0...HEAD
+[Unreleased]: https://github.com/MetaMask/core/compare/@metamask/ramps-controller@16.0.0...HEAD
+[16.0.0]: https://github.com/MetaMask/core/compare/@metamask/ramps-controller@15.1.0...@metamask/ramps-controller@16.0.0
 [15.1.0]: https://github.com/MetaMask/core/compare/@metamask/ramps-controller@15.0.0...@metamask/ramps-controller@15.1.0
 [15.0.0]: https://github.com/MetaMask/core/compare/@metamask/ramps-controller@14.3.0...@metamask/ramps-controller@15.0.0
 [14.3.0]: https://github.com/MetaMask/core/compare/@metamask/ramps-controller@14.2.0...@metamask/ramps-controller@14.3.0

package/dist/RampsController.cjs

@@ -10,11 +10,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_getProviderScope, _RampsController_getDefaultRedirectUrl, _RampsController_pendingRequests, _RampsController_pendingResourceCount, _RampsController_pendingResourceGeneration, _RampsController_orderPollingMeta, _RampsController_orderPollingTimer, _RampsController_isPolling, _RampsController_initPromise, _RampsController_clearPendingResourceCountForDependentResources, _RampsController_abortDependentRequests, _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_pickInAppQuote, _RampsController_getSupportingProvidersForRegion, _RampsController_filterProviderIdsBySupport, _RampsController_resolveProviderIdsForQuote, _RampsController_getPreferredProviderIdsFromOrders, _RampsController_refreshOrder, _RampsController_pollPendingOrders, _RampsController_syncTransakAuthOnError, _RampsController_getNormalizedTransakError;
+var _RampsController_instances, _RampsController_requestCacheTTL, _RampsController_requestCacheMaxSize, _RampsController_getDefaultRedirectUrl, _RampsController_pendingRequests, _RampsController_pendingResourceCount, _RampsController_pendingResourceGeneration, _RampsController_orderPollingMeta, _RampsController_orderPollingTimer, _RampsController_isPolling, _RampsController_initPromise, _RampsController_clearPendingResourceCountForDependentResources, _RampsController_abortDependentRequests, _RampsController_isAllProvidersEnabled, _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;
 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_1 = require("./featureFlags.cjs");
+const providerAvailability_1 = require("./providerAvailability.cjs");
 const rampsErrorCodes_1 = require("./rampsErrorCodes.cjs");
 const RampsService_1 = require("./RampsService.cjs");
 const RequestCache_1 = require("./RequestCache.cjs");
@@ -437,13 +439,11 @@ class RampsController extends base_controller_1.BaseController {
      * controller. Missing properties will be filled in with defaults.
      * @param args.requestCacheTTL - Time to live for cached requests in milliseconds.
      * @param args.requestCacheMaxSize - Maximum number of entries in the request cache.
-     * @param args.getProviderScope - Optional callback returning the current
-     * provider-class scope for fiat quote widening. Defaults to `off`.
      * @param args.getDefaultRedirectUrl - Optional callback returning the default
-     * redirect URL used for the widened in-app quote fetch when the caller omits
+     * redirect URL used for the widened quote fetch when the caller omits
      * `redirectUrl`. Defaults to a callback returning `undefined`.
      */
-    constructor({ messenger, state = {}, requestCacheTTL = RequestCache_1.DEFAULT_REQUEST_CACHE_TTL, requestCacheMaxSize = RequestCache_1.DEFAULT_REQUEST_CACHE_MAX_SIZE, getProviderScope, getDefaultRedirectUrl, }) {
+    constructor({ messenger, state = {}, requestCacheTTL = RequestCache_1.DEFAULT_REQUEST_CACHE_TTL, requestCacheMaxSize = RequestCache_1.DEFAULT_REQUEST_CACHE_MAX_SIZE, getDefaultRedirectUrl, }) {
         super({
             messenger,
             metadata: rampsControllerMetadata,
@@ -465,12 +465,7 @@ class RampsController extends base_controller_1.BaseController {
          */
         _RampsController_requestCacheMaxSize.set(this, void 0);
         /**
-         * Resolves the current provider-class scope for fiat quote widening. Defaults
-         * to `() => 'off'` (native-only) when no callback is injected.
-         */
-        _RampsController_getProviderScope.set(this, void 0);
-        /**
-         * Resolves the default redirect URL for the widened in-app quote fetch when
+         * Resolves the default redirect URL for the widened quote fetch when
          * the caller omits `redirectUrl`. Defaults to `() => undefined` when no
          * callback is injected.
          */
@@ -496,7 +491,6 @@ class RampsController extends base_controller_1.BaseController {
         _RampsController_initPromise.set(this, null);
         __classPrivateFieldSet(this, _RampsController_requestCacheTTL, requestCacheTTL, "f");
         __classPrivateFieldSet(this, _RampsController_requestCacheMaxSize, requestCacheMaxSize, "f");
-        __classPrivateFieldSet(this, _RampsController_getProviderScope, getProviderScope ?? (() => 'off'), "f");
         __classPrivateFieldSet(this, _RampsController_getDefaultRedirectUrl, getDefaultRedirectUrl ?? (() => undefined), "f");
         this.messenger.registerMethodActionHandlers(this, MESSENGER_EXPOSED_METHODS);
     }
@@ -1012,19 +1006,17 @@ class RampsController extends base_controller_1.BaseController {
         if (normalizedAssetIdForValidation === '') {
             throw new Error('assetId is required.');
         }
-        // When a non-`off` provider scope is active, widen the native-only
-        // auto-selection path to every supporting provider and pick the best in-app
-        // quote from the results (in-app vs external is only knowable per-quote via
-        // `buyWidget.browser`). Only the auto-select/restrict path that MM Pay's
+        // When the all-providers feature flag is enabled, widen the native-only
+        // auto-selection path to every supporting provider and pick the best
+        // quote from the results. Only the auto-select/restrict path that MM Pay's
         // `getRampsQuote` uses is affected; explicit-`providers` callers and the
-        // plain all-provider path are untouched.
-        const providerScope = __classPrivateFieldGet(this, _RampsController_getProviderScope, "f").call(this);
-        const widenToInAppProviders = providerScope !== 'off' &&
-            !options.providers &&
+        // plain all-provider path are untouched (and never read the flag).
+        const wantsAutoSelection = !options.providers &&
             (options.autoSelectProvider === true ||
                 options.restrictToKnownOrNativeProviders === true);
+        const widenToAllProviders = wantsAutoSelection && __classPrivateFieldGet(this, _RampsController_instances, "m", _RampsController_isAllProvidersEnabled).call(this);
         let providersToUse;
-        let inAppProviderCatalog = this.state.providers.data;
+        let widenedProviderCatalog = this.state.providers.data;
         if (options.providers) {
             providersToUse = options.restrictToKnownOrNativeProviders
                 ? await __classPrivateFieldGet(this, _RampsController_instances, "m", _RampsController_filterProviderIdsBySupport).call(this, {
@@ -1034,7 +1026,7 @@ class RampsController extends base_controller_1.BaseController {
                 })
                 : options.providers;
         }
-        else if (widenToInAppProviders) {
+        else if (widenToAllProviders) {
             // `#getSupportingProvidersForRegion` also hydrates the provider catalog
             // when controller state is empty, so all-provider quoting cannot silently
             // return zero providers here.
@@ -1042,7 +1034,7 @@ class RampsController extends base_controller_1.BaseController {
                 assetId: normalizedAssetIdForValidation,
                 region: regionToUse,
             });
-            inAppProviderCatalog = supporting;
+            widenedProviderCatalog = supporting;
             providersToUse = supporting.map((provider) => provider.id);
         }
         else if (options.autoSelectProvider ||
@@ -1074,12 +1066,12 @@ class RampsController extends base_controller_1.BaseController {
         // Under headless-buy gating, an empty resolved provider list means no
         // eligible (native/supporting) provider exists. Return an empty response
         // rather than passing `[]` to the service, which omits the provider filter
-        // and would quote every provider. This also guards the widened in-app path:
+        // and would quote every provider. This also guards the widened path:
         // a caller may trigger widening with `autoSelectProvider` alone (no
         // `restrictToKnownOrNativeProviders`), and an empty supporting set must not
         // fall through to unfiltered quotes from providers that do not support the
         // asset.
-        if ((options.restrictToKnownOrNativeProviders || widenToInAppProviders) &&
+        if ((options.restrictToKnownOrNativeProviders || widenToAllProviders) &&
             providersToUse.length === 0) {
             return { success: [], sorted: [], error: [], customActions: [] };
         }
@@ -1088,11 +1080,12 @@ class RampsController extends base_controller_1.BaseController {
         const normalizedAssetId = normalizedAssetIdForValidation;
         const normalizedWalletAddress = options.walletAddress.trim();
         // The quotes API only embeds a `buyURL`/`buyWidget` when a `redirectUrl` is
-        // present, so on the widened in-app path (where MM Pay omits one) supply the
+        // present, so on the widened path (where MM Pay omits one) supply the
         // injected default so aggregator quotes carry a usable widget URL. An
-        // explicit caller `redirectUrl` always wins, and scope `off` never injects.
+        // explicit caller `redirectUrl` always wins, and the native-only path
+        // (flag off) never injects.
         const effectiveRedirectUrl = options.redirectUrl ??
-            (widenToInAppProviders ? __classPrivateFieldGet(this, _RampsController_getDefaultRedirectUrl, "f").call(this) : undefined);
+            (widenToAllProviders ? __classPrivateFieldGet(this, _RampsController_getDefaultRedirectUrl, "f").call(this) : undefined);
         const cacheKey = (0, RequestCache_1.createCacheKey)('getQuotes', [
             normalizedRegion,
             normalizedFiat,
@@ -1121,22 +1114,21 @@ class RampsController extends base_controller_1.BaseController {
             forceRefresh: options.forceRefresh,
             ttl: options.ttl ?? DEFAULT_QUOTES_TTL,
         });
-        if (!widenToInAppProviders) {
+        if (!widenToAllProviders) {
             return response;
         }
-        // Reduce the widened multi-provider result to the single best in-app quote
+        // Reduce the widened multi-provider result to the single best quote
         // and place it at `success[0]`, since single-pick consumers
         // (`getRampsQuote` -> `success?.[0]`) rely on index 0 while `success[]`
         // order is server-defined rather than ranked.
-        const selectedQuote = __classPrivateFieldGet(this, _RampsController_instances, "m", _RampsController_pickInAppQuote).call(this, response, {
-            scope: providerScope,
+        const selectedQuote = __classPrivateFieldGet(this, _RampsController_instances, "m", _RampsController_pickWidenedQuote).call(this, response, {
             amount: options.amount,
             fiat: normalizedFiat,
-            providers: inAppProviderCatalog,
+            providers: widenedProviderCatalog,
         });
         if (!selectedQuote) {
-            // No usable in-app quote: surface "no quote" rather than leaking an
-            // external/custom quote to the single-pick consumer.
+            // No quote fits the published provider limits: surface "no quote"
+            // rather than handing the single-pick consumer an out-of-limits quote.
             return {
                 success: [],
                 sorted: response.sorted,
@@ -1766,7 +1758,7 @@ class RampsController extends base_controller_1.BaseController {
     }
 }
 exports.RampsController = RampsController;
-_RampsController_requestCacheTTL = new WeakMap(), _RampsController_requestCacheMaxSize = new WeakMap(), _RampsController_getProviderScope = new WeakMap(), _RampsController_getDefaultRedirectUrl = new WeakMap(), _RampsController_pendingRequests = new WeakMap(), _RampsController_pendingResourceCount = new WeakMap(), _RampsController_pendingResourceGeneration = new WeakMap(), _RampsController_orderPollingMeta = new WeakMap(), _RampsController_orderPollingTimer = new WeakMap(), _RampsController_isPolling = new WeakMap(), _RampsController_initPromise = new WeakMap(), _RampsController_instances = new WeakSet(), _RampsController_clearPendingResourceCountForDependentResources = function _RampsController_clearPendingResourceCountForDependentResources() {
+_RampsController_requestCacheTTL = new WeakMap(), _RampsController_requestCacheMaxSize = new WeakMap(), _RampsController_getDefaultRedirectUrl = new WeakMap(), _RampsController_pendingRequests = new WeakMap(), _RampsController_pendingResourceCount = new WeakMap(), _RampsController_pendingResourceGeneration = new WeakMap(), _RampsController_orderPollingMeta = new WeakMap(), _RampsController_orderPollingTimer = new WeakMap(), _RampsController_isPolling = new WeakMap(), _RampsController_initPromise = new WeakMap(), _RampsController_instances = new WeakSet(), _RampsController_clearPendingResourceCountForDependentResources = function _RampsController_clearPendingResourceCountForDependentResources() {
     for (const resourceType of DEPENDENT_RESOURCE_KEYS) {
         __classPrivateFieldGet(this, _RampsController_pendingResourceCount, "f").delete(resourceType);
         const generation = __classPrivateFieldGet(this, _RampsController_pendingResourceGeneration, "f").get(resourceType) ?? 0;
@@ -1781,6 +1773,14 @@ _RampsController_requestCacheTTL = new WeakMap(), _RampsController_requestCacheM
             __classPrivateFieldGet(this, _RampsController_instances, "m", _RampsController_removeRequestState).call(this, cacheKey);
         }
     }
+}, _RampsController_isAllProvidersEnabled = function _RampsController_isAllProvidersEnabled() {
+    try {
+        const remoteFeatureFlagState = this.messenger.call('RemoteFeatureFlagController:getState');
+        return (0, featureFlags_1.isHeadlessAllProvidersEnabled)(remoteFeatureFlagState);
+    }
+    catch {
+        return false;
+    }
 }, _RampsController_mutateRequests = function _RampsController_mutateRequests(fn) {
     this.update((state) => {
         const requests = state.requests;
@@ -1892,9 +1892,8 @@ _RampsController_requestCacheTTL = new WeakMap(), _RampsController_requestCacheM
     this.update((state) => {
         state.userRegion = userRegion;
     });
-}, _RampsController_pickInAppQuote = function _RampsController_pickInAppQuote(response, { scope, amount, fiat, providers, }) {
+}, _RampsController_pickWidenedQuote = function _RampsController_pickWidenedQuote(response, { amount, fiat, providers, }) {
     const providerByCode = new Map(providers.map((provider) => [provider.id, provider]));
-    const customActionProviderCodes = new Set(response.customActions.map((action) => action.buy.providerId));
     const fitsProviderLimits = (quote) => {
         const provider = providerByCode.get(quote.provider);
         const limit = provider?.limits?.fiat?.[fiat]?.[quote.quote.paymentMethod];
@@ -1905,26 +1904,7 @@ _RampsController_requestCacheTTL = new WeakMap(), _RampsController_requestCacheM
         }
         return amount >= limit.minAmount && amount <= limit.maxAmount;
     };
-    const isEligible = (quote) => {
-        // `all` (Phase 2) skips the in-app-only exclusions; both scopes still
-        // enforce provider limits up front.
-        if (scope !== 'all') {
-            const providerCode = quote.provider;
-            if (customActionProviderCodes.has(providerCode)) {
-                return false;
-            }
-            // Defensive: the wire may carry an inline `isCustomAction` flag that is
-            // absent from the published `Quote` type.
-            if (quote.quote.isCustomAction === true) {
-                return false;
-            }
-            if (quote.quote.buyWidget?.browser === 'IN_APP_OS_BROWSER') {
-                return false;
-            }
-        }
-        return fitsProviderLimits(quote);
-    };
-    const candidates = response.success.filter(isEligible);
+    const candidates = response.success.filter(fitsProviderLimits);
     if (candidates.length === 0) {
         return undefined;
     }
@@ -1969,18 +1949,10 @@ async function _RampsController_getSupportingProvidersForRegion({ assetId, regio
     else {
         ({ providers } = await this.getProviders(normalizedRegion));
     }
-    // EVM CAIP-19 asset IDs may arrive checksummed or lowercased, and the
-    // providers API returns both forms, so match case-insensitively on both
-    // sides. Only the lowercased forms are compared (the original IDs are never
-    // returned), so case-sensitive non-EVM asset IDs are not corrupted.
-    const normalizedAssetId = assetId.toLowerCase();
-    const supporting = providers.filter((provider) => {
-        const map = provider?.supportedCryptoCurrencies;
-        if (!map) {
-            return false;
-        }
-        return Object.keys(map).some((key) => key.toLowerCase() === normalizedAssetId);
-    });
+    // Case-insensitive CAIP-19 matching is shared with headless-buy consumers
+    // via `getProvidersServingAsset`, so the controller and the UI region gate
+    // cannot disagree about which providers serve the asset.
+    const supporting = (0, providerAvailability_1.getProvidersServingAsset)(providers, assetId);
     return { supporting, all: providers };
 }, _RampsController_filterProviderIdsBySupport = 
 /**