@metamask-previews/ramps-controller 15.1.0-preview-685219bbf → 15.1.0-preview-bbd2df29f

package/CHANGELOG.md

@@ -9,14 +9,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- 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

@@ -16,7 +16,7 @@ exports.RampsController = exports.getInternalOrderCode = exports.normalizeProvid
 const base_controller_1 = require("@metamask/base-controller");
 const controller_utils_1 = require("@metamask/controller-utils");
 const providerAvailability_1 = require("./providerAvailability.cjs");
-const quoteClassification_1 = require("./quoteClassification.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");
@@ -993,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.
@@ -1018,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) {
@@ -1085,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: [] };
         }
@@ -1900,59 +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;
-            }
-            // Custom-action and external-browser classification is shared with the
-            // consuming client via `quoteClassification` so both filter identically.
-            if ((0, quoteClassification_1.isCustomActionQuote)(quote) || (0, quoteClassification_1.isExternalBrowserQuote)(quote)) {
-                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