@metamask/ramps-controller 10.2.0 → 12.0.0

package/CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [12.0.0]
+
+### Changed
+
+- **BREAKING:** Update state hydration to make `init()` idempotent and remove `hydrateState()` ([#8157](https://github.com/MetaMask/core/pull/8157))
+
+### Removed
+
+- Remove `hydrateState()` — use `init()` as the single entry point for controller hydration
+
+## [11.0.0]
+
+### Changed
+
+- **BREAKING:** Replace `getWidgetUrl` with `getBuyWidgetData` (returns `BuyWidget | null`); add `addPrecreatedOrder` for custom-action ramp flows (e.g., PayPal, Robinhood, Coinbase) ([#8100](https://github.com/MetaMask/core/pull/8100))
+
 ## [10.2.0]
 
 ### Fixed
@@ -198,7 +214,9 @@ 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@10.2.0...HEAD
+[Unreleased]: https://github.com/MetaMask/core/compare/@metamask/ramps-controller@12.0.0...HEAD
+[12.0.0]: https://github.com/MetaMask/core/compare/@metamask/ramps-controller@11.0.0...@metamask/ramps-controller@12.0.0
+[11.0.0]: https://github.com/MetaMask/core/compare/@metamask/ramps-controller@10.2.0...@metamask/ramps-controller@11.0.0
 [10.2.0]: https://github.com/MetaMask/core/compare/@metamask/ramps-controller@10.1.0...@metamask/ramps-controller@10.2.0
 [10.1.0]: https://github.com/MetaMask/core/compare/@metamask/ramps-controller@10.0.0...@metamask/ramps-controller@10.1.0
 [10.0.0]: https://github.com/MetaMask/core/compare/@metamask/ramps-controller@9.0.0...@metamask/ramps-controller@10.0.0

package/dist/RampsController.cjs

@@ -10,9 +10,9 @@ 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_orderPollingMeta, _RampsController_orderPollingTimer, _RampsController_isPolling, _RampsController_clearPendingResourceCountForDependentResources, _RampsController_abortDependentRequests, _RampsController_registerActionHandlers, _RampsController_mutateRequests, _RampsController_removeRequestState, _RampsController_cleanupState, _RampsController_fireAndForget, _RampsController_requireRegion, _RampsController_isRegionCurrent, _RampsController_isTokenCurrent, _RampsController_isProviderCurrent, _RampsController_updateResourceField, _RampsController_setResourceLoading, _RampsController_setResourceError, _RampsController_updateRequestState, _RampsController_refreshOrder, _RampsController_pollPendingOrders, _RampsController_syncTransakAuthOnError;
+var _RampsController_instances, _RampsController_requestCacheTTL, _RampsController_requestCacheMaxSize, _RampsController_pendingRequests, _RampsController_pendingResourceCount, _RampsController_orderPollingMeta, _RampsController_orderPollingTimer, _RampsController_isPolling, _RampsController_initPromise, _RampsController_clearPendingResourceCountForDependentResources, _RampsController_abortDependentRequests, _RampsController_registerActionHandlers, _RampsController_mutateRequests, _RampsController_removeRequestState, _RampsController_cleanupState, _RampsController_fireAndForget, _RampsController_requireRegion, _RampsController_isRegionCurrent, _RampsController_isTokenCurrent, _RampsController_isProviderCurrent, _RampsController_updateResourceField, _RampsController_setResourceLoading, _RampsController_setResourceError, _RampsController_updateRequestState, _RampsController_runInit, _RampsController_refreshOrder, _RampsController_pollPendingOrders, _RampsController_syncTransakAuthOnError;
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RampsController = exports.getDefaultRampsControllerState = exports.RAMPS_CONTROLLER_REQUIRED_SERVICE_ACTIONS = exports.controllerName = void 0;
+exports.RampsController = exports.normalizeProviderCode = exports.getDefaultRampsControllerState = exports.RAMPS_CONTROLLER_REQUIRED_SERVICE_ACTIONS = exports.controllerName = void 0;
 const base_controller_1 = require("@metamask/base-controller");
 const RampsService_1 = require("./RampsService.cjs");
 const RequestCache_1 = require("./RequestCache.cjs");
@@ -250,6 +250,10 @@ function findRegionFromCode(regionCode, countries) {
         regionCode: normalizedCode,
     };
 }
+function normalizeProviderCode(providerCode) {
+    return providerCode.replace(/^\/providers\//u, '');
+}
+exports.normalizeProviderCode = normalizeProviderCode;
 // === ORDER POLLING CONSTANTS ===
 const TERMINAL_ORDER_STATUSES = new Set([
     RampsService_1.RampsOrderStatus.Completed,
@@ -323,6 +327,7 @@ class RampsController extends base_controller_1.BaseController {
         _RampsController_orderPollingMeta.set(this, new Map());
         _RampsController_orderPollingTimer.set(this, null);
         _RampsController_isPolling.set(this, false);
+        _RampsController_initPromise.set(this, null);
         __classPrivateFieldSet(this, _RampsController_requestCacheTTL, requestCacheTTL, "f");
         __classPrivateFieldSet(this, _RampsController_requestCacheMaxSize, requestCacheMaxSize, "f");
         __classPrivateFieldGet(this, _RampsController_instances, "m", _RampsController_registerActionHandlers).call(this);
@@ -565,25 +570,28 @@ class RampsController extends base_controller_1.BaseController {
      * Initializes the controller by fetching the user's region from geolocation.
      * This should be called once at app startup to set up the initial region.
      *
-     * If a userRegion already exists (from persistence or manual selection),
-     * this method will skip geolocation fetch and use the existing region.
+     * Idempotent: subsequent calls return the same promise unless forceRefresh is set.
+     * Skips getCountries when countries are already loaded; skips geolocation when
+     * userRegion already exists.
      *
-     * @param options - Options for cache behavior.
+     * @param options - Options for cache behavior. forceRefresh bypasses idempotency and re-runs the full flow.
      * @returns Promise that resolves when initialization is complete.
      */
     async init(options) {
-        await this.getCountries(options);
-        let regionCode = this.state.userRegion?.regionCode;
-        regionCode ?? (regionCode = await this.messenger.call('RampsService:getGeolocation'));
-        if (!regionCode) {
-            throw new Error('Failed to fetch geolocation. Cannot initialize controller without valid region information.');
+        if (!options?.forceRefresh && __classPrivateFieldGet(this, _RampsController_initPromise, "f") !== null) {
+            return __classPrivateFieldGet(this, _RampsController_initPromise, "f");
         }
-        await this.setUserRegion(regionCode, options);
-    }
-    hydrateState(options) {
-        const regionCode = __classPrivateFieldGet(this, _RampsController_instances, "m", _RampsController_requireRegion).call(this);
-        __classPrivateFieldGet(this, _RampsController_instances, "m", _RampsController_fireAndForget).call(this, this.getTokens(regionCode, 'buy', options));
-        __classPrivateFieldGet(this, _RampsController_instances, "m", _RampsController_fireAndForget).call(this, this.getProviders(regionCode, options));
+        if (options?.forceRefresh) {
+            __classPrivateFieldSet(this, _RampsController_initPromise, null, "f");
+        }
+        const initPromise = __classPrivateFieldGet(this, _RampsController_instances, "m", _RampsController_runInit).call(this, options).then(() => undefined, (error) => {
+            if (__classPrivateFieldGet(this, _RampsController_initPromise, "f") === initPromise) {
+                __classPrivateFieldSet(this, _RampsController_initPromise, null, "f");
+            }
+            throw error;
+        });
+        __classPrivateFieldSet(this, _RampsController_initPromise, initPromise, "f");
+        return initPromise;
     }
     /**
      * Fetches the list of supported countries.
@@ -945,25 +953,74 @@ class RampsController extends base_controller_1.BaseController {
         super.destroy();
     }
     /**
-     * Fetches the widget URL from a quote for redirect providers.
+     * Fetches the widget data from a quote for redirect providers.
      * Makes a request to the buyURL endpoint via the RampsService to get the
-     * actual provider widget URL.
+     * actual provider widget URL and optional order ID for polling.
      *
      * @param quote - The quote to fetch the widget URL from.
-     * @returns Promise resolving to the widget URL string, or null if not available.
+     * @returns Promise resolving to the full BuyWidget (url, browser, orderId), or null if not available (missing buyURL or empty url in response).
+     * @throws Rethrows errors from the RampsService (e.g. HttpError, network failures) so clients can react to fetch failures.
      */
-    async getWidgetUrl(quote) {
+    async getBuyWidgetData(quote) {
         const buyUrl = quote.quote?.buyURL;
         if (!buyUrl) {
             return null;
         }
-        try {
-            const buyWidget = await this.messenger.call('RampsService:getBuyWidgetUrl', buyUrl);
-            return buyWidget.url ?? null;
-        }
-        catch {
+        const buyWidget = await this.messenger.call('RampsService:getBuyWidgetUrl', buyUrl);
+        if (!buyWidget?.url) {
             return null;
         }
+        return buyWidget;
+    }
+    /**
+     * Registers an order ID for polling until the order is created or resolved.
+     * Adds a minimal stub order to controller state; the existing order polling
+     * will fetch the full order when the provider has created it.
+     *
+     * @param params - Object containing order identifiers and wallet info.
+     * @param params.orderId - Full order ID (e.g. "/providers/paypal/orders/abc123") or order code.
+     * @param params.providerCode - Provider code (e.g. "paypal", "transak"), with or without /providers/ prefix.
+     * @param params.walletAddress - Wallet address for the order.
+     * @param params.chainId - Optional chain ID for the order.
+     */
+    addPrecreatedOrder(params) {
+        const { orderId, providerCode, walletAddress, chainId } = params;
+        const orderCode = orderId.includes('/orders/')
+            ? orderId.split('/orders/')[1]
+            : orderId;
+        if (!orderCode?.trim()) {
+            return;
+        }
+        const normalizedProviderCode = normalizeProviderCode(providerCode);
+        const stubOrder = {
+            providerOrderId: orderCode,
+            provider: {
+                id: `/providers/${normalizedProviderCode}`,
+                name: '',
+                environmentType: '',
+                description: '',
+                hqAddress: '',
+                links: [],
+                logos: { light: '', dark: '', height: 0, width: 0 },
+            },
+            walletAddress,
+            status: RampsService_1.RampsOrderStatus.Precreated,
+            orderType: 'buy',
+            createdAt: Date.now(),
+            isOnlyLink: false,
+            success: false,
+            cryptoAmount: 0,
+            fiatAmount: 0,
+            providerOrderLink: '',
+            totalFeesFiat: 0,
+            txHash: '',
+            network: chainId ? { chainId, name: '' } : { chainId: '', name: '' },
+            canBeUpdated: true,
+            idHasExpired: false,
+            excludeFromPurchases: false,
+            timeDescriptionPending: '',
+        };
+        this.addOrder(stubOrder);
     }
     /**
      * Fetches an order from the unified V2 API endpoint.
@@ -978,10 +1035,17 @@ class RampsController extends base_controller_1.BaseController {
         const order = await this.messenger.call('RampsService:getOrder', providerCode, orderCode, wallet);
         this.update((state) => {
             const idx = state.orders.findIndex((existing) => existing.providerOrderId === orderCode);
-            if (idx !== -1) {
+            if (idx === -1) {
+                state.orders.push({
+                    ...order,
+                    providerOrderId: orderCode,
+                });
+            }
+            else {
                 state.orders[idx] = {
                     ...state.orders[idx],
                     ...order,
+                    providerOrderId: orderCode,
                 };
             }
         });
@@ -1397,7 +1461,7 @@ class RampsController extends base_controller_1.BaseController {
     }
 }
 exports.RampsController = RampsController;
-_RampsController_requestCacheTTL = new WeakMap(), _RampsController_requestCacheMaxSize = new WeakMap(), _RampsController_pendingRequests = new WeakMap(), _RampsController_pendingResourceCount = new WeakMap(), _RampsController_orderPollingMeta = new WeakMap(), _RampsController_orderPollingTimer = new WeakMap(), _RampsController_isPolling = new WeakMap(), _RampsController_instances = new WeakSet(), _RampsController_clearPendingResourceCountForDependentResources = function _RampsController_clearPendingResourceCountForDependentResources() {
+_RampsController_requestCacheTTL = new WeakMap(), _RampsController_requestCacheMaxSize = new WeakMap(), _RampsController_pendingRequests = new WeakMap(), _RampsController_pendingResourceCount = 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);
     }
@@ -1484,6 +1548,24 @@ _RampsController_requestCacheTTL = new WeakMap(), _RampsController_requestCacheM
             }
         }
     });
+}, _RampsController_runInit = async function _RampsController_runInit(options) {
+    const forceRefresh = options?.forceRefresh === true;
+    const hasCountries = this.state.countries.data.length > 0;
+    if (forceRefresh || !hasCountries) {
+        await this.getCountries(options);
+    }
+    let regionCode;
+    if (forceRefresh) {
+        regionCode = await this.messenger.call('RampsService:getGeolocation');
+    }
+    else {
+        regionCode = this.state.userRegion?.regionCode;
+        regionCode ?? (regionCode = await this.messenger.call('RampsService:getGeolocation'));
+    }
+    if (!regionCode) {
+        throw new Error('Failed to fetch geolocation. Cannot initialize controller without valid region information.');
+    }
+    await this.setUserRegion(regionCode, options);
 }, _RampsController_refreshOrder = 
 /**
  * Refreshes a single order via the V2 API and updates it in state.
@@ -1496,7 +1578,7 @@ async function _RampsController_refreshOrder(order) {
     if (!providerCode || !order.providerOrderId || !order.walletAddress) {
         return;
     }
-    const providerCodeSegment = providerCode.replace('/providers/', '');
+    const providerCodeSegment = normalizeProviderCode(providerCode);
     const previousStatus = order.status;
     try {
         const updatedOrder = await this.getOrder(providerCodeSegment, order.providerOrderId, order.walletAddress);