@metamask/ramps-controller 21.0.0 → 22.0.0

package/dist/RampsController.js

@@ -2,6 +2,7 @@ import { BaseController } from '@metamask/base-controller';
 import { BrokenCircuitError } from '@metamask/controller-utils';
 import { applyAutorampRemoteStatus, createAutorampAccount, markAutorampNotified, } from './autorampAccount.js';
 import { getHeadlessProviderAllowlist, isHeadlessAllProvidersEnabled, normalizeHeadlessProviderId, } from './featureFlags.js';
+import { areOrdersEqual, deleteOrderInUserStorage, syncOrdersWithUserStorage as syncOrdersWithUserStorageInternal, updateOrderInUserStorage, } from './order-syncing/index.js';
 import { PENDING_ORDER_STATUSES, TERMINAL_ORDER_STATUSES, } from './orderStatus.js';
 import { buildOwnershipMessage } from './ownership-message.js';
 import { mergePaymentMethodsById, pickPaymentMethod, } from './paymentMethodMerge.js';
@@ -71,12 +72,17 @@ export const RAMPS_CONTROLLER_REQUIRED_SERVICE_ACTIONS = [
  * `AuthenticationController:getSessionProfile` resolves the vendor customer
  * identity from Profile Sync, and `KeyringController:signPersonalMessage` signs
  * the EIP-191 ownership proof for Money Account self-hosted wallet
- * registration; both are only exercised by the autoramp paths.
+ * registration; both are only exercised by the autoramp paths. User Storage
+ * and authentication actions support cross-client order syncing.
  */
 export const RAMPS_CONTROLLER_REQUIRED_CONTROLLER_ACTIONS = [
     'AuthenticationController:getSessionProfile',
+    'AuthenticationController:isSignedIn',
     'KeyringController:signPersonalMessage',
     'RemoteFeatureFlagController:getState',
+    'UserStorageController:getState',
+    'UserStorageController:performGetStorageAllFeatureEntries',
+    'UserStorageController:performBatchSetStorage',
 ];
 /**
  * Distinguishes an already-materialized {@link AutorampAccount} from the
@@ -369,15 +375,19 @@ function findRegionFromCode(regionCode, countries) {
  */
 export function getInternalOrderCode(orderOrId) {
     if (typeof orderOrId === 'string') {
-        return orderOrId.includes('/orders/')
-            ? orderOrId.split('/orders/')[1]
-            : orderOrId;
+        if (orderOrId.includes('/orders/')) {
+            return orderOrId.split('/orders/')[1]?.trim() || '';
+        }
+        return orderOrId.trim();
     }
     const { id, providerOrderId } = orderOrId;
     if (id?.includes('/orders/')) {
-        return id.split('/orders/')[1];
+        const code = id.split('/orders/')[1]?.trim();
+        if (code) {
+            return code;
+        }
     }
-    return providerOrderId;
+    return providerOrderId?.trim() ?? '';
 }
 // === ORDER POLLING CONSTANTS ===
 const DEFAULT_POLLING_INTERVAL_MS = 30_000;
@@ -442,6 +452,7 @@ const MESSENGER_EXPOSED_METHODS = [
     'transakCancelOrder',
     'transakCancelAllActiveOrders',
     'transakGetActiveOrders',
+    'syncOrdersWithUserStorage',
 ];
 /**
  * Whether controller state still describes the context a payment-method
@@ -472,6 +483,8 @@ export class RampsController extends BaseController {
      * Maximum number of entries in the request cache.
      */
     #requestCacheMaxSize;
+    #onOrderSyncErroneousSituation;
+    #trace;
     /**
      * Map of pending requests for deduplication.
      * Key is the cache key, value is the pending request with abort controller.
@@ -491,6 +504,75 @@ export class RampsController extends BaseController {
     #orderPollingTimer = null;
     #isPolling = false;
     #initPromise = null;
+    /**
+     * Semaphore that prevents sync feedback loops while applying remote order changes.
+     */
+    #isOrderSyncingInProgress = false;
+    /**
+     * Whether the full sync is applying its own local state changes.
+     */
+    #isApplyingOrderSyncChanges = false;
+    /**
+     * Orders deleted locally while a full sync held the semaphore.
+     */
+    #pendingRemoteDeletes = new Map();
+    /**
+     * Coalesces overlapping `syncOrdersWithUserStorage` calls into a follow-up run.
+     */
+    #orderSyncQueued = false;
+    #orderSyncPromise = null;
+    /**
+     * Whether a full order sync is currently applying remote changes.
+     *
+     * @returns Whether order sync is in progress.
+     */
+    get isOrderSyncingInProgress() {
+        return this.#isOrderSyncingInProgress;
+    }
+    /**
+     * Sets the order-syncing-in-progress semaphore.
+     * Used by the order-syncing module; hosts should not call this.
+     *
+     * @param value - Whether sync is in progress.
+     * @internal
+     */
+    setIsOrderSyncingInProgress(value) {
+        this.#isOrderSyncingInProgress = value;
+    }
+    /**
+     * Distinguishes full sync's own state changes from external mutations.
+     *
+     * @param value - Whether sync changes are being applied.
+     * @internal
+     */
+    setIsApplyingOrderSyncChanges(value) {
+        this.#isApplyingOrderSyncChanges = value;
+    }
+    /**
+     * Returns orders deleted while a full sync was in progress.
+     * Used by the order-syncing module.
+     *
+     * @returns Pending deletes for remote tombstone upload.
+     * @internal
+     */
+    getPendingRemoteDeletes() {
+        return [...this.#pendingRemoteDeletes.values()];
+    }
+    /**
+     * Clears deletes whose tombstones were successfully persisted. A delete
+     * replaced while a write was in flight remains pending.
+     *
+     * @param orders - Deletes included in a successful remote write.
+     * @internal
+     */
+    acknowledgePendingRemoteDeletes(orders) {
+        for (const order of orders) {
+            const key = getInternalOrderCode(order);
+            if (key && this.#pendingRemoteDeletes.get(key) === order) {
+                this.#pendingRemoteDeletes.delete(key);
+            }
+        }
+    }
     /**
      * Clears the pending resource count map. Used only in tests to exercise the
      * defensive path when get() returns undefined in the finally block.
@@ -526,8 +608,10 @@ export class RampsController extends BaseController {
      * controller. Missing properties will be filled in with defaults.
      * @param args.requestCacheTTL - Time to live for cached requests in milliseconds.
      * @param args.requestCacheMaxSize - Maximum number of entries in the request cache.
+     * @param args.onOrderSyncErroneousSituation - Optional order-sync error reporter.
+     * @param args.trace - Optional performance tracing callback for order sync.
      */
-    constructor({ messenger, state = {}, requestCacheTTL = DEFAULT_REQUEST_CACHE_TTL, requestCacheMaxSize = DEFAULT_REQUEST_CACHE_MAX_SIZE, }) {
+    constructor({ messenger, state = {}, requestCacheTTL = DEFAULT_REQUEST_CACHE_TTL, requestCacheMaxSize = DEFAULT_REQUEST_CACHE_MAX_SIZE, onOrderSyncErroneousSituation, trace, }) {
         super({
             messenger,
             metadata: rampsControllerMetadata,
@@ -541,6 +625,8 @@ export class RampsController extends BaseController {
         });
         this.#requestCacheTTL = requestCacheTTL;
         this.#requestCacheMaxSize = requestCacheMaxSize;
+        this.#onOrderSyncErroneousSituation = onOrderSyncErroneousSituation;
+        this.#trace = trace;
         this.messenger.registerMethodActionHandlers(this, MESSENGER_EXPOSED_METHODS);
     }
     /**
@@ -1841,17 +1927,59 @@ export class RampsController extends BaseController {
      * If an order with the same internal order code 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.
+     * Unchanged syncable payloads (including unchanged poll results) are ignored
+     * so `lastUpdatedAt` is not bumped and User Storage is not rewritten.
      *
      * @param order - The RampsOrder to add or update.
      */
     addOrder(order) {
         const internalOrderCode = getInternalOrderCode(order);
+        if (!internalOrderCode) {
+            this.#onOrderSyncErroneousSituation?.('Unable to derive internal order code for addOrder', {});
+            return;
+        }
+        const existing = this.state.orders.find((existingOrder) => getInternalOrderCode(existingOrder) === internalOrderCode);
+        if (existing &&
+            !this.#isApplyingOrderSyncChanges &&
+            areOrdersEqual(existing, order)) {
+            // Syncable payload unchanged; check if paymentDetails differ.
+            // paymentDetails is local-only (never synced remotely), so if it's the
+            // only change we merge it without bumping lastUpdatedAt or writing remotely.
+            if (order.paymentDetails &&
+                JSON.stringify(existing.paymentDetails) !==
+                    JSON.stringify(order.paymentDetails)) {
+                this.update((state) => {
+                    const idx = state.orders.findIndex((stateOrder) => getInternalOrderCode(stateOrder) === internalOrderCode);
+                    if (idx !== -1) {
+                        state.orders[idx] = {
+                            ...state.orders[idx],
+                            paymentDetails: order.paymentDetails,
+                        };
+                    }
+                });
+            }
+            return;
+        }
+        const incomingLastUpdatedAt = order.lastUpdatedAt;
+        // Local edits always bump lastUpdatedAt so full-sync LWW can prefer them
+        // over stale remote copies when an incremental push was skipped/failed.
+        // This includes external edits mid-sync (e.g. polling via `getOrder`),
+        // which the queued follow-up sync must not lose under LWW.
+        // Only when sync applies its own imported orders do we preserve the remote
+        // `lu` / `createdAt` (never invent "now" for missing `lu`, or stale remotes
+        // win later LWW comparisons).
         const healedOrder = {
             ...order,
             providerOrderId: internalOrderCode,
+            lastUpdatedAt: this.#isApplyingOrderSyncChanges
+                ? (incomingLastUpdatedAt ?? order.createdAt ?? 0)
+                : Date.now(),
         };
+        if (!this.#isApplyingOrderSyncChanges) {
+            this.#pendingRemoteDeletes.delete(internalOrderCode);
+        }
         this.update((state) => {
-            const idx = state.orders.findIndex((existing) => getInternalOrderCode(existing) === internalOrderCode);
+            const idx = state.orders.findIndex((stateOrder) => getInternalOrderCode(stateOrder) === internalOrderCode);
             if (idx === -1) {
                 state.orders.push(healedOrder);
             }
@@ -1862,6 +1990,22 @@ export class RampsController extends BaseController {
                 };
             }
         });
+        if (this.#isOrderSyncingInProgress && !this.#isApplyingOrderSyncChanges) {
+            // Incremental push is suppressed during full sync; queue another full
+            // sync pass so mutations during the upload await are not dropped.
+            this.#orderSyncQueued = true;
+        }
+        else if (!this.#isOrderSyncingInProgress) {
+            updateOrderInUserStorage(healedOrder, {
+                getRampsControllerInstance: () => this,
+                getMessenger: () => this.messenger,
+            }, {
+                onOrderSyncErroneousSituation: this.#onOrderSyncErroneousSituation,
+            }).catch((error) => {
+                console.error('Error updating ramps order in remote storage:', error);
+                this.#onOrderSyncErroneousSituation?.('Error updating ramps order in remote storage', { error });
+            });
+        }
     }
     /**
      * Removes a V2 order from controller state by providerOrderId.
@@ -1869,10 +2013,101 @@ export class RampsController extends BaseController {
      * @param providerOrderId - The provider order ID to remove.
      */
     removeOrder(providerOrderId) {
+        const orderToRemove = this.state.orders.find((order) => order.providerOrderId === providerOrderId ||
+            getInternalOrderCode(order) === providerOrderId);
         this.update((state) => {
-            state.orders = state.orders.filter((order) => order.providerOrderId !== providerOrderId);
+            state.orders = state.orders.filter((order) => order.providerOrderId !== providerOrderId &&
+                getInternalOrderCode(order) !== providerOrderId);
         });
         this.#orderPollingMeta.delete(providerOrderId);
+        if (orderToRemove) {
+            if (orderToRemove.providerOrderId) {
+                this.#orderPollingMeta.delete(orderToRemove.providerOrderId);
+            }
+            const internalOrderCode = getInternalOrderCode(orderToRemove);
+            this.#orderPollingMeta.delete(internalOrderCode);
+        }
+        if (orderToRemove) {
+            const deleteKey = getInternalOrderCode(orderToRemove);
+            const isLocalDeletion = !this.#isApplyingOrderSyncChanges;
+            if (isLocalDeletion && deleteKey) {
+                // Retain the delete until a full sync confirms its tombstone was
+                // persisted. This prevents a failed incremental write from allowing
+                // the still-active remote copy to be imported again.
+                this.#pendingRemoteDeletes.set(deleteKey, orderToRemove);
+            }
+            if (this.#isOrderSyncingInProgress) {
+                if (isLocalDeletion) {
+                    // Incremental remote deletes are gated off during full sync; queue a
+                    // tombstone write and another full sync pass so deletes during the
+                    // upload await are not dropped.
+                    this.#orderSyncQueued = true;
+                }
+            }
+            else if (isLocalDeletion) {
+                deleteOrderInUserStorage(orderToRemove, {
+                    getRampsControllerInstance: () => this,
+                    getMessenger: () => this.messenger,
+                }, {
+                    onOrderSyncErroneousSituation: this.#onOrderSyncErroneousSituation,
+                }).catch((error) => {
+                    console.error('Error deleting ramps order from remote storage:', error);
+                    this.#onOrderSyncErroneousSituation?.('Error deleting ramps order from remote storage', { error });
+                });
+            }
+        }
+    }
+    /**
+     * Bidirectionally syncs V2 ramps orders with User Storage.
+     * Hosts should call this on unlock / when ramps syncing is enabled.
+     *
+     * Overlapping calls are coalesced into the in-flight worker. After the worker
+     * settles, this method loops when `#orderSyncQueued` is still set so a
+     * request that arrived between the worker's last loop check and promise
+     * resolution is not dropped.
+     */
+    async syncOrdersWithUserStorage() {
+        this.#orderSyncQueued = true;
+        let syncError;
+        while (this.#orderSyncQueued || this.#orderSyncPromise) {
+            if (this.#orderSyncPromise) {
+                try {
+                    await this.#orderSyncPromise;
+                }
+                catch (error) {
+                    syncError ??=
+                        error instanceof Error ? error : new Error(String(error));
+                }
+                continue;
+            }
+            this.#orderSyncPromise = (async () => {
+                while (this.#orderSyncQueued) {
+                    this.#orderSyncQueued = false;
+                    await syncOrdersWithUserStorageInternal({
+                        onOrderSyncErroneousSituation: this.#onOrderSyncErroneousSituation,
+                    }, {
+                        getRampsControllerInstance: () => this,
+                        getMessenger: () => this.messenger,
+                        trace: this.#trace,
+                    });
+                }
+                // Yield so a caller can set `#orderSyncQueued` after the inner while
+                // check and still be observed by the outer loop.
+                await Promise.resolve();
+            })();
+            try {
+                await this.#orderSyncPromise;
+            }
+            catch (error) {
+                syncError ??= error instanceof Error ? error : new Error(String(error));
+            }
+            finally {
+                this.#orderSyncPromise = null;
+            }
+        }
+        if (syncError) {
+            throw syncError;
+        }
     }
     /**
      * Adds or updates a local autoramp last-seen cursor (e.g. after create).
@@ -2393,6 +2628,7 @@ export class RampsController extends BaseController {
      * @returns The unified order data.
      */
     async getOrder(providerCode, orderCode, wallet) {
+        const hadOrderAtRequestStart = this.state.orders.some((existingOrder) => getInternalOrderCode(existingOrder) === orderCode);
         const order = await this.messenger.call('RampsService:getOrder', providerCode, orderCode, wallet);
         const healedWalletAddress = order.walletAddress || wallet;
         const internalOrderCode = getInternalOrderCode({
@@ -2404,18 +2640,12 @@ export class RampsController extends BaseController {
             walletAddress: healedWalletAddress,
             providerOrderId: internalOrderCode,
         };
-        this.update((state) => {
-            const idx = state.orders.findIndex((existing) => getInternalOrderCode(existing) === internalOrderCode);
-            if (idx === -1) {
-                state.orders.push(healedOrder);
-            }
-            else {
-                state.orders[idx] = {
-                    ...state.orders[idx],
-                    ...healedOrder,
-                };
-            }
-        });
+        const orderStillExists = this.state.orders.some((existingOrder) => getInternalOrderCode(existingOrder) === internalOrderCode);
+        // A polling request can finish after removeOrder. Do not let that stale
+        // response recreate the local order and overwrite its remote tombstone.
+        if (!hadOrderAtRequestStart || orderStillExists) {
+            this.addOrder(healedOrder);
+        }
         return healedOrder;
     }
     /**