@metamask/ramps-controller 10.2.0 → 11.0.0

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [11.0.0]
+
+### Changed
+
+- **BREAKING:** Replace `getWidgetUrl` with `getBuyWidgetData` (returns `BuyWidget | null`); add `addPrecreatedOrder` for custom-action ramp flows (e.g., PayPal) ([#8100](https://github.com/MetaMask/core/pull/8100))
+
 ## [10.2.0]
 
 ### Fixed
@@ -198,7 +204,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@10.2.0...HEAD
+[Unreleased]: https://github.com/MetaMask/core/compare/@metamask/ramps-controller@11.0.0...HEAD
+[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

@@ -12,7 +12,7 @@ var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (
 };
 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;
 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,
@@ -945,25 +949,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 +1031,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,
                 };
             }
         });
@@ -1496,7 +1556,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);