@metamask-previews/ramps-controller 15.1.0-preview-34f2bcbf7 → 15.1.0-preview-aa4ef4666

package/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Add a pure `resolveFiatDepositRoute` helper (and `FiatDepositRoute` type) that picks the on-ramp asset a region should buy for a fiat deposit: the preferred target asset (e.g. mUSD) when a provider serves it, otherwise the first convertible fallback asset (e.g. native ETH) with a serving provider, or `undefined` when none is purchasable. It reuses `regionHasProviderForAsset` so it obeys the same scope semantics (an aggregator-only fallback is unreachable under scope `off`), enabling the "buy ETH, convert to mUSD" deposit route in regions without a direct mUSD provider ([#9428](https://github.com/MetaMask/core/pull/9428))
+- Add pure quote-selection helpers `getSmartSelectedQuote` and `fitsProviderLimits`, the amount validator `validateBuyAmount`, and a `BuyAmountValidation` type so headless-buy consumers can share the controller's provider-agnostic quote ranking (`preferredProviderIds` then reliability then price then first surviving candidate), scope-aware in-app filtering, and per-provider fiat-limit enforcement instead of re-deriving them ([#9414](https://github.com/MetaMask/core/pull/9414))
+- 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 scope-aware region/availability gating instead of re-deriving it, keeping the two from disagreeing ([#9409](https://github.com/MetaMask/core/pull/9409))
+- Add pure quote-classification helpers `isExternalBrowserQuote`, `isCustomActionQuote`, and `isInAppOnlyQuote` so consumers can share the controller's 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))
+
+### Changed
+
+- `RampsController.getQuotes` now derives its provider-widening decision from the `getProviderScope` scope (`off` stays native-only; `in-app`/`all` widen) rather than the `restrictToKnownOrNativeProviders` flag, and picks the widened auto-selected quote via the shared `getSmartSelectedQuote`, feeding in the user's completed-order provider preference so a returning user's previously-used provider is preferred over the reliability/price winner ([#9414](https://github.com/MetaMask/core/pull/9414))
+- `RampsController` now derives its internal region provider-asset matching and quote in-app/custom-action/external filtering from the shared `providerAvailability` and `quoteClassification` helpers, so the exposed helpers stay behaviourally identical to the controller's own selection ([#9409](https://github.com/MetaMask/core/pull/9409))
+
+### Deprecated
+
+- **`RampsController.getQuotes`'s `restrictToKnownOrNativeProviders` option is deprecated** in favor of provider-class scope (`getProviderScope`): `off` keeps native-only auto-selection and `in-app`/`all` widen, so the flag is redundant. It is still honored for one release (like `autoSelectProvider`, it routes a no-`providers` request through the gated path) and will be removed in a later major ([#9414](https://github.com/MetaMask/core/pull/9414))
+
 ## [15.1.0]
 
 ### Added

package/dist/RampsController.cjs

@@ -15,6 +15,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.RampsController = exports.getInternalOrderCode = exports.normalizeProviderCode = 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 providerAvailability_1 = require("./providerAvailability.cjs");
+const quoteSelection_1 = require("./quoteSelection.cjs");
 const rampsErrorCodes_1 = require("./rampsErrorCodes.cjs");
 const RampsService_1 = require("./RampsService.cjs");
 const RequestCache_1 = require("./RequestCache.cjs");
@@ -991,11 +993,17 @@ class RampsController extends base_controller_1.BaseController {
      *   during auto-selection, in priority order (e.g. derived by the caller
      *   from completed-order history). Only used when `autoSelectProvider` is
      *   true and `providers` is omitted.
-     * @param options.restrictToKnownOrNativeProviders - Headless-buy v0 gating. When
-     *   true, auto-selection resolves only a native provider, and an explicitly
-     *   passed `providers` list is filtered to those supporting the region and
-     *   asset. If nothing qualifies, `getQuotes` returns an empty response
-     *   instead of quoting other providers.
+     * @param options.restrictToKnownOrNativeProviders - **Deprecated** (still
+     *   honored for one release). Headless-buy v0 gating: when true,
+     *   auto-selection resolves only a native provider, and an explicitly passed
+     *   `providers` list is filtered to those supporting the region and asset; if
+     *   nothing qualifies, `getQuotes` returns an empty response instead of
+     *   quoting other providers. Provider-class scope (`getProviderScope`) is now
+     *   the gate (`off` stays native-only; `in-app`/`all` widen), so this flag is
+     *   redundant and will be removed in a later major. Like `autoSelectProvider`,
+     *   it still routes a no-`providers` request through the gated path so
+     *   existing callers keep working; new callers should rely on the scope
+     *   instead of passing this flag.
      * @param options.redirectUrl - Optional redirect URL after order completion.
      * @param options.action - The ramp action type. Defaults to 'buy'.
      * @param options.forceRefresh - Whether to bypass cache.
@@ -1016,17 +1024,24 @@ 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
+        // Provider-class scope is the gate (P2.M8): `off` keeps native-only
+        // auto-selection (the kill switch); `in-app`/`all` widen the auto-selection
+        // path to every supporting provider and pick the best quote from the
+        // results (in-app vs external is only knowable per-quote via
+        // `buyWidget.browser`). Only the auto-select 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 &&
+        const scopeWidens = providerScope !== 'off';
+        // The auto-select entry path. `restrictToKnownOrNativeProviders` is
+        // `@deprecated` (P2.M8) but still honored here: like `autoSelectProvider`,
+        // it routes a no-explicit-`providers` request through the resolved/gated
+        // path, so existing callers (TPC `getRampsQuote`) are unaffected until the
+        // option is removed in a later major.
+        const usesAutoSelectPath = !options.providers &&
             (options.autoSelectProvider === true ||
                 options.restrictToKnownOrNativeProviders === true);
+        const widenToInAppProviders = scopeWidens && usesAutoSelectPath;
         let providersToUse;
         let inAppProviderCatalog = this.state.providers.data;
         if (options.providers) {
@@ -1083,7 +1098,8 @@ class RampsController extends base_controller_1.BaseController {
         // `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 ((widenToInAppProviders ||
+            options.restrictToKnownOrNativeProviders === true) &&
             providersToUse.length === 0) {
             return { success: [], sorted: [], error: [], customActions: [] };
         }
@@ -1898,62 +1914,13 @@ _RampsController_requestCacheTTL = new WeakMap(), _RampsController_requestCacheM
         state.userRegion = userRegion;
     });
 }, _RampsController_pickInAppQuote = function _RampsController_pickInAppQuote(response, { scope, amount, fiat, providers, }) {
-    const providerByCode = new Map(providers.map((provider) => [
-        normalizeProviderCode(provider.id),
-        provider,
-    ]));
-    const customActionProviderCodes = new Set(response.customActions.map((action) => normalizeProviderCode(action.buy.providerId)));
-    const fitsProviderLimits = (quote) => {
-        const provider = providerByCode.get(normalizeProviderCode(quote.provider));
-        const limit = provider?.limits?.fiat?.[fiat]?.[quote.quote.paymentMethod];
-        if (!limit) {
-            // No published limits for this provider/payment method: treat as
-            // eligible and let the provider enforce limits at checkout.
-            return true;
-        }
-        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 = normalizeProviderCode(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);
-    if (candidates.length === 0) {
-        return undefined;
-    }
-    const candidateByCode = new Map(candidates.map((quote) => [normalizeProviderCode(quote.provider), quote]));
-    const pickBySortOrder = (sortBy) => {
-        const order = response.sorted.find((entry) => entry.sortBy === sortBy)?.ids;
-        if (!order) {
-            return undefined;
-        }
-        for (const providerId of order) {
-            const match = candidateByCode.get(normalizeProviderCode(providerId));
-            if (match) {
-                return match;
-            }
-        }
-        return undefined;
-    };
-    // Reliability first, then price, then the first surviving candidate.
-    return (pickBySortOrder('reliability') ??
-        pickBySortOrder('price') ??
-        candidates[0]);
+    return (0, quoteSelection_1.getSmartSelectedQuote)(response, {
+        scope,
+        amount,
+        fiat,
+        providers,
+        preferredProviderIds: __classPrivateFieldGet(this, _RampsController_instances, "m", _RampsController_getPreferredProviderIdsFromOrders).call(this),
+    });
 }, _RampsController_getSupportingProvidersForRegion = 
 /**
  * Returns the region's providers that support the given asset, plus the full
@@ -1977,18 +1944,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 = 
 /**