@metamask-previews/ramps-controller 8.0.0-preview-33dbba4f3 → 8.0.0-preview-a196307b6

package/CHANGELOG.md

@@ -10,6 +10,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - Add `widgetUrl` resource state that automatically fetches and stores the buy widget URL whenever the selected quote changes ([#7920](https://github.com/MetaMask/core/pull/7920))
+- Add `TransakService` for native Transak deposit flow with OTP auth, KYC, quoting, order lifecycle, and payment widget URL generation ([#7922](https://github.com/MetaMask/core/pull/7922))
+- Add `nativeProviders.transak` state slice and controller convenience methods for driving the Transak native deposit flow ([#7922](https://github.com/MetaMask/core/pull/7922))
 
 ### Changed
 

package/dist/RampsController.cjs

@@ -10,7 +10,7 @@ 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_quotePollingInterval, _RampsController_quotePollingOptions, _RampsController_clearPendingResourceCountForDependentResources, _RampsController_abortDependentRequests, _RampsController_mutateRequests, _RampsController_removeRequestState, _RampsController_cleanupState, _RampsController_fireAndForget, _RampsController_restartPollingIfActive, _RampsController_requireRegion, _RampsController_isRegionCurrent, _RampsController_isTokenCurrent, _RampsController_isProviderCurrent, _RampsController_updateResourceField, _RampsController_setResourceLoading, _RampsController_setResourceError, _RampsController_updateRequestState, _RampsController_syncWidgetUrl;
+var _RampsController_instances, _RampsController_requestCacheTTL, _RampsController_requestCacheMaxSize, _RampsController_pendingRequests, _RampsController_pendingResourceCount, _RampsController_quotePollingInterval, _RampsController_quotePollingOptions, _RampsController_clearPendingResourceCountForDependentResources, _RampsController_abortDependentRequests, _RampsController_mutateRequests, _RampsController_removeRequestState, _RampsController_cleanupState, _RampsController_fireAndForget, _RampsController_restartPollingIfActive, _RampsController_requireRegion, _RampsController_isRegionCurrent, _RampsController_isTokenCurrent, _RampsController_isProviderCurrent, _RampsController_updateResourceField, _RampsController_setResourceLoading, _RampsController_setResourceError, _RampsController_updateRequestState, _RampsController_syncWidgetUrl, _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");
@@ -35,6 +35,30 @@ exports.RAMPS_CONTROLLER_REQUIRED_SERVICE_ACTIONS = [
     'RampsService:getPaymentMethods',
     'RampsService:getQuotes',
     'RampsService:getBuyWidgetUrl',
+    'TransakService:setApiKey',
+    'TransakService:setAccessToken',
+    'TransakService:clearAccessToken',
+    'TransakService:sendUserOtp',
+    'TransakService:verifyUserOtp',
+    'TransakService:logout',
+    'TransakService:getUserDetails',
+    'TransakService:getBuyQuote',
+    'TransakService:getKycRequirement',
+    'TransakService:getAdditionalRequirements',
+    'TransakService:createOrder',
+    'TransakService:getOrder',
+    'TransakService:getUserLimits',
+    'TransakService:requestOtt',
+    'TransakService:generatePaymentWidgetUrl',
+    'TransakService:submitPurposeOfUsageForm',
+    'TransakService:patchUser',
+    'TransakService:submitSsnDetails',
+    'TransakService:confirmPayment',
+    'TransakService:getTranslation',
+    'TransakService:getIdProofStatus',
+    'TransakService:cancelOrder',
+    'TransakService:cancelAllActiveOrders',
+    'TransakService:getActiveOrders',
 ];
 /**
  * Default TTL for quotes requests (15 seconds).
@@ -93,6 +117,12 @@ const rampsControllerMetadata = {
         includeInStateLogs: false,
         usedInUi: true,
     },
+    nativeProviders: {
+        persist: false,
+        includeInDebugSnapshot: true,
+        includeInStateLogs: false,
+        usedInUi: true,
+    },
 };
 /**
  * Creates a default resource state object.
@@ -129,6 +159,14 @@ function getDefaultRampsControllerState() {
         quotes: createDefaultResourceState(null, null),
         widgetUrl: createDefaultResourceState(null),
         requests: {},
+        nativeProviders: {
+            transak: {
+                isAuthenticated: false,
+                userDetails: createDefaultResourceState(null),
+                buyQuote: createDefaultResourceState(null),
+                kycRequirement: createDefaultResourceState(null),
+            },
+        },
     };
 }
 exports.getDefaultRampsControllerState = getDefaultRampsControllerState;
@@ -872,11 +910,14 @@ class RampsController extends base_controller_1.BaseController {
      * If the response contains exactly one quote, it is auto-selected.
      * If multiple quotes are returned, the existing selection is preserved if still valid.
      *
+     * Returns early (no-op) if the selected payment method is not yet set,
+     * allowing callers to invoke this before payment-method selection is finalized.
+     *
      * @param options - Parameters for fetching quotes.
      * @param options.walletAddress - The destination wallet address.
      * @param options.amount - The amount (in fiat for buy, crypto for sell).
      * @param options.redirectUrl - Optional redirect URL after order completion.
-     * @throws If required dependencies (region, token, provider, payment method) are not set.
+     * @throws If required dependencies (region, token, provider) are not set.
      */
     startQuotePolling(options) {
         __classPrivateFieldGet(this, _RampsController_instances, "m", _RampsController_requireRegion).call(this);
@@ -986,11 +1027,404 @@ class RampsController extends base_controller_1.BaseController {
             const buyWidget = await this.messenger.call('RampsService:getBuyWidgetUrl', buyUrl);
             return buyWidget.url ?? null;
         }
-        catch (error) {
-            console.error('Error fetching widget URL:', error);
+        catch {
             return null;
         }
     }
+    /**
+     * Sets the Transak API key used for all Transak API requests.
+     *
+     * @param apiKey - The Transak API key.
+     */
+    transakSetApiKey(apiKey) {
+        this.messenger.call('TransakService:setApiKey', apiKey);
+    }
+    /**
+     * Sets the Transak access token and marks the user as authenticated.
+     *
+     * @param token - The access token received from Transak auth.
+     */
+    transakSetAccessToken(token) {
+        this.messenger.call('TransakService:setAccessToken', token);
+        this.transakSetAuthenticated(true);
+    }
+    /**
+     * Clears the Transak access token and marks the user as unauthenticated.
+     */
+    transakClearAccessToken() {
+        this.messenger.call('TransakService:clearAccessToken');
+        this.transakSetAuthenticated(false);
+    }
+    /**
+     * Updates the Transak authentication flag in controller state.
+     *
+     * @param isAuthenticated - Whether the user is authenticated with Transak.
+     */
+    transakSetAuthenticated(isAuthenticated) {
+        this.update((state) => {
+            state.nativeProviders.transak.isAuthenticated = isAuthenticated;
+        });
+    }
+    /**
+     * Resets all Transak state back to defaults (unauthenticated, no data).
+     */
+    transakResetState() {
+        this.messenger.call('TransakService:clearAccessToken');
+        this.update((state) => {
+            state.nativeProviders.transak =
+                getDefaultRampsControllerState().nativeProviders.transak;
+        });
+    }
+    /**
+     * Sends a one-time password to the user's email for Transak authentication.
+     *
+     * @param email - The user's email address.
+     * @returns The OTP response containing a state token for verification.
+     */
+    async transakSendUserOtp(email) {
+        return this.messenger.call('TransakService:sendUserOtp', email);
+    }
+    /**
+     * Verifies a one-time password and authenticates the user with Transak.
+     * Updates the controller's authentication state on success.
+     *
+     * @param email - The user's email address.
+     * @param verificationCode - The OTP code entered by the user.
+     * @param stateToken - The state token from the sendUserOtp response.
+     * @returns The access token for subsequent authenticated requests.
+     */
+    async transakVerifyUserOtp(email, verificationCode, stateToken) {
+        const token = await this.messenger.call('TransakService:verifyUserOtp', email, verificationCode, stateToken);
+        this.transakSetAuthenticated(true);
+        return token;
+    }
+    /**
+     * Logs the user out of Transak. Clears authentication state and user details
+     * regardless of whether the API call succeeds or fails.
+     *
+     * @returns A message indicating the logout result.
+     */
+    async transakLogout() {
+        try {
+            const result = await this.messenger.call('TransakService:logout');
+            return result;
+        }
+        finally {
+            this.transakClearAccessToken();
+            this.update((state) => {
+                state.nativeProviders.transak.userDetails.data = null;
+            });
+        }
+    }
+    /**
+     * Fetches the authenticated user's details from Transak.
+     * Updates the userDetails resource state with loading/success/error states.
+     *
+     * @returns The user's profile and KYC details.
+     */
+    async transakGetUserDetails() {
+        this.update((state) => {
+            state.nativeProviders.transak.userDetails.isLoading = true;
+            state.nativeProviders.transak.userDetails.error = null;
+        });
+        try {
+            const details = await this.messenger.call('TransakService:getUserDetails');
+            this.update((state) => {
+                state.nativeProviders.transak.userDetails.data = details;
+                state.nativeProviders.transak.userDetails.isLoading = false;
+            });
+            return details;
+        }
+        catch (error) {
+            __classPrivateFieldGet(this, _RampsController_instances, "m", _RampsController_syncTransakAuthOnError).call(this, error);
+            const errorMessage = error?.message ?? 'Unknown error';
+            this.update((state) => {
+                state.nativeProviders.transak.userDetails.isLoading = false;
+                state.nativeProviders.transak.userDetails.error = errorMessage;
+            });
+            throw error;
+        }
+    }
+    /**
+     * Fetches a buy quote from Transak for the given parameters.
+     * Updates the buyQuote resource state with loading/success/error states.
+     *
+     * @param fiatCurrency - The fiat currency code (e.g., "USD").
+     * @param cryptoCurrency - The cryptocurrency identifier.
+     * @param network - The blockchain network identifier.
+     * @param paymentMethod - The payment method identifier.
+     * @param fiatAmount - The fiat amount as a string.
+     * @returns The buy quote with pricing and fee details.
+     */
+    async transakGetBuyQuote(fiatCurrency, cryptoCurrency, network, paymentMethod, fiatAmount) {
+        this.update((state) => {
+            state.nativeProviders.transak.buyQuote.isLoading = true;
+            state.nativeProviders.transak.buyQuote.error = null;
+        });
+        try {
+            const quote = await this.messenger.call('TransakService:getBuyQuote', fiatCurrency, cryptoCurrency, network, paymentMethod, fiatAmount);
+            this.update((state) => {
+                state.nativeProviders.transak.buyQuote.data = quote;
+                state.nativeProviders.transak.buyQuote.isLoading = false;
+            });
+            return quote;
+        }
+        catch (error) {
+            const errorMessage = error?.message ?? 'Unknown error';
+            this.update((state) => {
+                state.nativeProviders.transak.buyQuote.isLoading = false;
+                state.nativeProviders.transak.buyQuote.error = errorMessage;
+            });
+            throw error;
+        }
+    }
+    /**
+     * Fetches the KYC requirement for a given quote.
+     * Updates the kycRequirement resource state with loading/success/error states.
+     *
+     * @param quoteId - The quote ID to check KYC requirements for.
+     * @returns The KYC requirement status and whether the user can place an order.
+     */
+    async transakGetKycRequirement(quoteId) {
+        this.update((state) => {
+            state.nativeProviders.transak.kycRequirement.isLoading = true;
+            state.nativeProviders.transak.kycRequirement.error = null;
+        });
+        try {
+            const requirement = await this.messenger.call('TransakService:getKycRequirement', quoteId);
+            this.update((state) => {
+                state.nativeProviders.transak.kycRequirement.data = requirement;
+                state.nativeProviders.transak.kycRequirement.isLoading = false;
+            });
+            return requirement;
+        }
+        catch (error) {
+            __classPrivateFieldGet(this, _RampsController_instances, "m", _RampsController_syncTransakAuthOnError).call(this, error);
+            const errorMessage = error?.message ?? 'Unknown error';
+            this.update((state) => {
+                state.nativeProviders.transak.kycRequirement.isLoading = false;
+                state.nativeProviders.transak.kycRequirement.error = errorMessage;
+            });
+            throw error;
+        }
+    }
+    /**
+     * Fetches additional KYC requirements (e.g., ID proof, address proof) for a quote.
+     *
+     * @param quoteId - The quote ID to check additional requirements for.
+     * @returns The list of additional forms required.
+     */
+    async transakGetAdditionalRequirements(quoteId) {
+        try {
+            return await this.messenger.call('TransakService:getAdditionalRequirements', quoteId);
+        }
+        catch (error) {
+            __classPrivateFieldGet(this, _RampsController_instances, "m", _RampsController_syncTransakAuthOnError).call(this, error);
+            throw error;
+        }
+    }
+    /**
+     * Creates a new order on Transak. If an existing order conflicts (HTTP 409),
+     * active orders are cancelled and the creation is retried.
+     *
+     * @param quoteId - The quote ID to create an order from.
+     * @param walletAddress - The destination wallet address.
+     * @param paymentMethodId - The payment method to use.
+     * @returns The created deposit order.
+     */
+    async transakCreateOrder(quoteId, walletAddress, paymentMethodId) {
+        try {
+            return await this.messenger.call('TransakService:createOrder', quoteId, walletAddress, paymentMethodId);
+        }
+        catch (error) {
+            __classPrivateFieldGet(this, _RampsController_instances, "m", _RampsController_syncTransakAuthOnError).call(this, error);
+            throw error;
+        }
+    }
+    /**
+     * Fetches an existing order from Transak by order ID.
+     *
+     * @param orderId - The order ID (deposit format or raw Transak format).
+     * @param wallet - The wallet address associated with the order.
+     * @param paymentDetails - Optional payment details to attach to the order.
+     * @returns The deposit order details.
+     */
+    async transakGetOrder(orderId, wallet, paymentDetails) {
+        return this.messenger.call('TransakService:getOrder', orderId, wallet, paymentDetails);
+    }
+    /**
+     * Fetches the user's spending limits for a given currency and payment method.
+     *
+     * @param fiatCurrency - The fiat currency code.
+     * @param paymentMethod - The payment method identifier.
+     * @param kycType - The KYC level type.
+     * @returns The user's limits, spending, and remaining amounts.
+     */
+    async transakGetUserLimits(fiatCurrency, paymentMethod, kycType) {
+        try {
+            return await this.messenger.call('TransakService:getUserLimits', fiatCurrency, paymentMethod, kycType);
+        }
+        catch (error) {
+            __classPrivateFieldGet(this, _RampsController_instances, "m", _RampsController_syncTransakAuthOnError).call(this, error);
+            throw error;
+        }
+    }
+    /**
+     * Requests a one-time token (OTT) for the Transak payment widget.
+     *
+     * @returns The OTT response containing the token.
+     */
+    async transakRequestOtt() {
+        try {
+            return await this.messenger.call('TransakService:requestOtt');
+        }
+        catch (error) {
+            __classPrivateFieldGet(this, _RampsController_instances, "m", _RampsController_syncTransakAuthOnError).call(this, error);
+            throw error;
+        }
+    }
+    /**
+     * Generates a URL for the Transak payment widget with pre-filled parameters.
+     *
+     * @param ottToken - The one-time token for widget authentication.
+     * @param quote - The buy quote to pre-fill in the widget.
+     * @param walletAddress - The destination wallet address.
+     * @param extraParams - Optional additional URL parameters.
+     * @returns The fully constructed widget URL string.
+     */
+    transakGeneratePaymentWidgetUrl(ottToken, quote, walletAddress, extraParams) {
+        return this.messenger.call('TransakService:generatePaymentWidgetUrl', ottToken, quote, walletAddress, extraParams);
+    }
+    /**
+     * Submits the user's purpose of usage form for KYC compliance.
+     *
+     * @param purpose - Array of purpose strings selected by the user.
+     * @returns A promise that resolves when the form is submitted.
+     */
+    async transakSubmitPurposeOfUsageForm(purpose) {
+        try {
+            return await this.messenger.call('TransakService:submitPurposeOfUsageForm', purpose);
+        }
+        catch (error) {
+            __classPrivateFieldGet(this, _RampsController_instances, "m", _RampsController_syncTransakAuthOnError).call(this, error);
+            throw error;
+        }
+    }
+    /**
+     * Updates the user's personal or address details on Transak.
+     *
+     * @param data - The user data fields to update.
+     * @returns The API response data.
+     */
+    async transakPatchUser(data) {
+        try {
+            return await this.messenger.call('TransakService:patchUser', data);
+        }
+        catch (error) {
+            __classPrivateFieldGet(this, _RampsController_instances, "m", _RampsController_syncTransakAuthOnError).call(this, error);
+            throw error;
+        }
+    }
+    /**
+     * Submits the user's SSN for identity verification.
+     *
+     * @param ssn - The Social Security Number.
+     * @param quoteId - The quote ID associated with the order requiring SSN.
+     * @returns The API response data.
+     */
+    async transakSubmitSsnDetails(ssn, quoteId) {
+        try {
+            return await this.messenger.call('TransakService:submitSsnDetails', ssn, quoteId);
+        }
+        catch (error) {
+            __classPrivateFieldGet(this, _RampsController_instances, "m", _RampsController_syncTransakAuthOnError).call(this, error);
+            throw error;
+        }
+    }
+    /**
+     * Confirms payment for an order after the user has completed payment.
+     *
+     * @param orderId - The order ID to confirm payment for.
+     * @param paymentMethodId - The payment method used.
+     * @returns Whether the payment confirmation was successful.
+     */
+    async transakConfirmPayment(orderId, paymentMethodId) {
+        try {
+            return await this.messenger.call('TransakService:confirmPayment', orderId, paymentMethodId);
+        }
+        catch (error) {
+            __classPrivateFieldGet(this, _RampsController_instances, "m", _RampsController_syncTransakAuthOnError).call(this, error);
+            throw error;
+        }
+    }
+    /**
+     * Translates generic ramps identifiers to Transak-specific identifiers.
+     *
+     * @param request - The translation request with optional identifiers to translate.
+     * @returns The translated Transak-specific identifiers.
+     */
+    async transakGetTranslation(request) {
+        return this.messenger.call('TransakService:getTranslation', request);
+    }
+    /**
+     * Checks the status of an ID proof submission for KYC.
+     *
+     * @param workFlowRunId - The workflow run ID to check status for.
+     * @returns The current ID proof status.
+     */
+    async transakGetIdProofStatus(workFlowRunId) {
+        try {
+            return await this.messenger.call('TransakService:getIdProofStatus', workFlowRunId);
+        }
+        catch (error) {
+            __classPrivateFieldGet(this, _RampsController_instances, "m", _RampsController_syncTransakAuthOnError).call(this, error);
+            throw error;
+        }
+    }
+    /**
+     * Cancels a specific Transak order.
+     *
+     * @param depositOrderId - The deposit order ID to cancel.
+     * @returns A promise that resolves when the order is cancelled.
+     */
+    async transakCancelOrder(depositOrderId) {
+        try {
+            return await this.messenger.call('TransakService:cancelOrder', depositOrderId);
+        }
+        catch (error) {
+            __classPrivateFieldGet(this, _RampsController_instances, "m", _RampsController_syncTransakAuthOnError).call(this, error);
+            throw error;
+        }
+    }
+    /**
+     * Cancels all active Transak orders. Individual cancellation failures
+     * are collected and returned rather than thrown.
+     *
+     * @returns An array of errors from any failed cancellations (empty if all succeeded).
+     */
+    async transakCancelAllActiveOrders() {
+        try {
+            return await this.messenger.call('TransakService:cancelAllActiveOrders');
+        }
+        catch (error) {
+            __classPrivateFieldGet(this, _RampsController_instances, "m", _RampsController_syncTransakAuthOnError).call(this, error);
+            throw error;
+        }
+    }
+    /**
+     * Fetches all active Transak orders for the authenticated user.
+     *
+     * @returns The list of active orders.
+     */
+    async transakGetActiveOrders() {
+        try {
+            return await this.messenger.call('TransakService:getActiveOrders');
+        }
+        catch (error) {
+            __classPrivateFieldGet(this, _RampsController_instances, "m", _RampsController_syncTransakAuthOnError).call(this, error);
+            throw error;
+        }
+    }
 }
 exports.RampsController = RampsController;
 _RampsController_requestCacheTTL = new WeakMap(), _RampsController_requestCacheMaxSize = new WeakMap(), _RampsController_pendingRequests = new WeakMap(), _RampsController_pendingResourceCount = new WeakMap(), _RampsController_quotePollingInterval = new WeakMap(), _RampsController_quotePollingOptions = new WeakMap(), _RampsController_instances = new WeakSet(), _RampsController_clearPendingResourceCountForDependentResources = function _RampsController_clearPendingResourceCountForDependentResources() {
@@ -1122,5 +1556,11 @@ _RampsController_requestCacheTTL = new WeakMap(), _RampsController_requestCacheM
                     : 'Failed to fetch widget URL';
         });
     }));
+}, _RampsController_syncTransakAuthOnError = function _RampsController_syncTransakAuthOnError(error) {
+    if (error instanceof Error &&
+        'httpStatus' in error &&
+        error.httpStatus === 401) {
+        this.transakSetAuthenticated(false);
+    }
 };
 //# sourceMappingURL=RampsController.cjs.map