@metamask/ramps-controller 10.0.0 → 10.1.0

package/CHANGELOG.md

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [10.1.0]
+
+### Added
+
+- Added `orders: RampsOrder[]` to controller state with persistence, along with crud methods([#8045](https://github.com/MetaMask/core/pull/8045))
+- Added `apiMessage` property to `TransakApiError` to surface human-readable error messages from the Transak API (e.g. OTP rate-limit cooldown) ([#8072](https://github.com/MetaMask/core/pull/8072))
+- Added `RampsController:orderStatusChanged` event, published when a polled order's status transitions ([#8045](https://github.com/MetaMask/core/pull/8045))
+- Add messenger actions for `RampsController:setSelectedToken`, `RampsController:getQuotes`, and `RampsController:getOrder`, register their handlers in `RampsController`, and export the action types from the package index ([#8081](https://github.com/MetaMask/core/pull/8081))
+
 ## [10.0.0]
 
 ### Changed
@@ -183,7 +192,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.0.0...HEAD
+[Unreleased]: https://github.com/MetaMask/core/compare/@metamask/ramps-controller@10.1.0...HEAD
+[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
 [9.0.0]: https://github.com/MetaMask/core/compare/@metamask/ramps-controller@8.1.0...@metamask/ramps-controller@9.0.0
 [8.1.0]: https://github.com/MetaMask/core/compare/@metamask/ramps-controller@8.0.0...@metamask/ramps-controller@8.1.0

package/dist/RampsController.cjs

@@ -10,10 +10,11 @@ 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_clearPendingResourceCountForDependentResources, _RampsController_abortDependentRequests, _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_syncTransakAuthOnError;
+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;
 const base_controller_1 = require("@metamask/base-controller");
+const RampsService_1 = require("./RampsService.cjs");
 const RequestCache_1 = require("./RequestCache.cjs");
 // === GENERAL ===
 /**
@@ -113,6 +114,12 @@ const rampsControllerMetadata = {
         includeInStateLogs: false,
         usedInUi: true,
     },
+    orders: {
+        persist: true,
+        includeInDebugSnapshot: true,
+        includeInStateLogs: true,
+        usedInUi: true,
+    },
 };
 /**
  * Creates a default resource state object.
@@ -155,6 +162,7 @@ function getDefaultRampsControllerState() {
                 kycRequirement: createDefaultResourceState(null),
             },
         },
+        orders: [],
     };
 }
 exports.getDefaultRampsControllerState = getDefaultRampsControllerState;
@@ -242,6 +250,21 @@ function findRegionFromCode(regionCode, countries) {
         regionCode: normalizedCode,
     };
 }
+// === ORDER POLLING CONSTANTS ===
+const TERMINAL_ORDER_STATUSES = new Set([
+    RampsService_1.RampsOrderStatus.Completed,
+    RampsService_1.RampsOrderStatus.Failed,
+    RampsService_1.RampsOrderStatus.Cancelled,
+    RampsService_1.RampsOrderStatus.IdExpired,
+]);
+const PENDING_ORDER_STATUSES = new Set([
+    RampsService_1.RampsOrderStatus.Pending,
+    RampsService_1.RampsOrderStatus.Created,
+    RampsService_1.RampsOrderStatus.Unknown,
+    RampsService_1.RampsOrderStatus.Precreated,
+]);
+const DEFAULT_POLLING_INTERVAL_MS = 30000;
+const MAX_ERROR_COUNT = 5;
 // === CONTROLLER DEFINITION ===
 /**
  * Manages cryptocurrency on/off ramps functionality.
@@ -297,8 +320,12 @@ class RampsController extends base_controller_1.BaseController {
          * Used so isLoading is only cleared when the last request for that resource finishes.
          */
         _RampsController_pendingResourceCount.set(this, new Map());
+        _RampsController_orderPollingMeta.set(this, new Map());
+        _RampsController_orderPollingTimer.set(this, null);
+        _RampsController_isPolling.set(this, false);
         __classPrivateFieldSet(this, _RampsController_requestCacheTTL, requestCacheTTL, "f");
         __classPrivateFieldSet(this, _RampsController_requestCacheMaxSize, requestCacheMaxSize, "f");
+        __classPrivateFieldGet(this, _RampsController_instances, "m", _RampsController_registerActionHandlers).call(this);
     }
     /**
      * Executes a request with caching, deduplication, and at most one in-flight
@@ -842,11 +869,69 @@ class RampsController extends base_controller_1.BaseController {
             ttl: options.ttl ?? DEFAULT_QUOTES_TTL,
         });
     }
+    // === ORDER MANAGEMENT ===
+    /**
+     * Adds or updates a V2 order in controller state.
+     * If an order with the same providerOrderId already exists, the incoming
+     * fields are merged on top of the existing order so that fields not present
+     * in the update (e.g. paymentDetails from the Transak API) are preserved.
+     *
+     * @param order - The RampsOrder to add or update.
+     */
+    addOrder(order) {
+        this.update((state) => {
+            const idx = state.orders.findIndex((existing) => existing.providerOrderId === order.providerOrderId);
+            if (idx === -1) {
+                state.orders.push(order);
+            }
+            else {
+                state.orders[idx] = {
+                    ...state.orders[idx],
+                    ...order,
+                };
+            }
+        });
+    }
+    /**
+     * Removes a V2 order from controller state by providerOrderId.
+     *
+     * @param providerOrderId - The provider order ID to remove.
+     */
+    removeOrder(providerOrderId) {
+        this.update((state) => {
+            state.orders = state.orders.filter((order) => order.providerOrderId !== providerOrderId);
+        });
+        __classPrivateFieldGet(this, _RampsController_orderPollingMeta, "f").delete(providerOrderId);
+    }
+    /**
+     * Starts polling all pending V2 orders at a fixed interval.
+     * Each poll cycle iterates orders with non-terminal statuses,
+     * respects pollingSecondsMinimum and backoff from error count.
+     */
+    startOrderPolling() {
+        if (__classPrivateFieldGet(this, _RampsController_orderPollingTimer, "f")) {
+            return;
+        }
+        __classPrivateFieldSet(this, _RampsController_orderPollingTimer, setInterval(() => {
+            __classPrivateFieldGet(this, _RampsController_instances, "m", _RampsController_pollPendingOrders).call(this).catch(() => undefined);
+        }, DEFAULT_POLLING_INTERVAL_MS), "f");
+        __classPrivateFieldGet(this, _RampsController_instances, "m", _RampsController_pollPendingOrders).call(this).catch(() => undefined);
+    }
+    /**
+     * Stops order polling and clears the interval.
+     */
+    stopOrderPolling() {
+        if (__classPrivateFieldGet(this, _RampsController_orderPollingTimer, "f")) {
+            clearInterval(__classPrivateFieldGet(this, _RampsController_orderPollingTimer, "f"));
+            __classPrivateFieldSet(this, _RampsController_orderPollingTimer, null, "f");
+        }
+    }
     /**
      * Cleans up controller resources.
      * Should be called when the controller is no longer needed.
      */
     destroy() {
+        this.stopOrderPolling();
         super.destroy();
     }
     /**
@@ -880,7 +965,17 @@ class RampsController extends base_controller_1.BaseController {
      * @returns The unified order data.
      */
     async getOrder(providerCode, orderCode, wallet) {
-        return await this.messenger.call('RampsService:getOrder', providerCode, orderCode, wallet);
+        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) {
+                state.orders[idx] = {
+                    ...state.orders[idx],
+                    ...order,
+                };
+            }
+        });
+        return order;
     }
     /**
      * Extracts an order from a provider callback URL.
@@ -1292,7 +1387,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_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_instances = new WeakSet(), _RampsController_clearPendingResourceCountForDependentResources = function _RampsController_clearPendingResourceCountForDependentResources() {
     for (const resourceType of DEPENDENT_RESOURCE_KEYS) {
         __classPrivateFieldGet(this, _RampsController_pendingResourceCount, "f").delete(resourceType);
     }
@@ -1305,6 +1400,10 @@ _RampsController_requestCacheTTL = new WeakMap(), _RampsController_requestCacheM
             __classPrivateFieldGet(this, _RampsController_instances, "m", _RampsController_removeRequestState).call(this, cacheKey);
         }
     }
+}, _RampsController_registerActionHandlers = function _RampsController_registerActionHandlers() {
+    this.messenger.registerActionHandler('RampsController:getOrder', this.getOrder.bind(this));
+    this.messenger.registerActionHandler('RampsController:getQuotes', this.getQuotes.bind(this));
+    this.messenger.registerActionHandler('RampsController:setSelectedToken', this.setSelectedToken.bind(this));
 }, _RampsController_mutateRequests = function _RampsController_mutateRequests(fn) {
     this.update((state) => {
         const requests = state.requests;
@@ -1375,6 +1474,81 @@ _RampsController_requestCacheTTL = new WeakMap(), _RampsController_requestCacheM
             }
         }
     });
+}, _RampsController_refreshOrder = 
+/**
+ * Refreshes a single order via the V2 API and updates it in state.
+ * Publishes orderStatusChanged if the status transitioned.
+ *
+ * @param order - The order to refresh (needs provider and providerOrderId).
+ */
+async function _RampsController_refreshOrder(order) {
+    const providerCode = order.provider?.id ?? '';
+    if (!providerCode || !order.providerOrderId || !order.walletAddress) {
+        return;
+    }
+    const providerCodeSegment = providerCode.replace('/providers/', '');
+    const previousStatus = order.status;
+    try {
+        const updatedOrder = await this.getOrder(providerCodeSegment, order.providerOrderId, order.walletAddress);
+        const meta = __classPrivateFieldGet(this, _RampsController_orderPollingMeta, "f").get(order.providerOrderId) ?? {
+            lastTimeFetched: 0,
+            errorCount: 0,
+        };
+        if (updatedOrder.status === RampsService_1.RampsOrderStatus.Unknown) {
+            meta.errorCount = Math.min(meta.errorCount + 1, MAX_ERROR_COUNT);
+        }
+        else {
+            meta.errorCount = 0;
+        }
+        meta.lastTimeFetched = Date.now();
+        __classPrivateFieldGet(this, _RampsController_orderPollingMeta, "f").set(order.providerOrderId, meta);
+        if (previousStatus !== updatedOrder.status &&
+            previousStatus !== undefined) {
+            this.messenger.publish('RampsController:orderStatusChanged', {
+                order: updatedOrder,
+                previousStatus,
+            });
+        }
+        if (TERMINAL_ORDER_STATUSES.has(updatedOrder.status)) {
+            __classPrivateFieldGet(this, _RampsController_orderPollingMeta, "f").delete(order.providerOrderId);
+        }
+    }
+    catch {
+        const meta = __classPrivateFieldGet(this, _RampsController_orderPollingMeta, "f").get(order.providerOrderId) ?? {
+            lastTimeFetched: 0,
+            errorCount: 0,
+        };
+        meta.errorCount = Math.min(meta.errorCount + 1, MAX_ERROR_COUNT);
+        meta.lastTimeFetched = Date.now();
+        __classPrivateFieldGet(this, _RampsController_orderPollingMeta, "f").set(order.providerOrderId, meta);
+    }
+}, _RampsController_pollPendingOrders = async function _RampsController_pollPendingOrders() {
+    if (__classPrivateFieldGet(this, _RampsController_isPolling, "f")) {
+        return;
+    }
+    __classPrivateFieldSet(this, _RampsController_isPolling, true, "f");
+    try {
+        const pendingOrders = this.state.orders.filter((order) => PENDING_ORDER_STATUSES.has(order.status));
+        const now = Date.now();
+        await Promise.allSettled(pendingOrders.map(async (order) => {
+            const meta = __classPrivateFieldGet(this, _RampsController_orderPollingMeta, "f").get(order.providerOrderId);
+            if (meta) {
+                const backoffMs = meta.errorCount > 0
+                    ? Math.min(DEFAULT_POLLING_INTERVAL_MS *
+                        Math.pow(2, meta.errorCount - 1), 5 * 60 * 1000)
+                    : 0;
+                const pollingMinMs = (order.pollingSecondsMinimum ?? 0) * 1000;
+                const minWait = Math.max(backoffMs, pollingMinMs);
+                if (now - meta.lastTimeFetched < minWait) {
+                    return;
+                }
+            }
+            await __classPrivateFieldGet(this, _RampsController_instances, "m", _RampsController_refreshOrder).call(this, order);
+        }));
+    }
+    finally {
+        __classPrivateFieldSet(this, _RampsController_isPolling, false, "f");
+    }
 }, _RampsController_syncTransakAuthOnError = function _RampsController_syncTransakAuthOnError(error) {
     if (error instanceof Error &&
         'httpStatus' in error &&