@portal-hq/web 3.17.0 → 3.18.0-alpha.0

package/src/__mocks/constants.ts

@@ -2092,6 +2092,74 @@ export const mockUpgradeTo7702Response = {
   txHash: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef',
 } as UpgradeTo7702Response
 
+// Meld mock data
+export const mockMeldCreateCustomerRequest = {
+  email: 'user@example.com',
+  type: 'INDIVIDUAL' as const,
+}
+
+export const mockMeldCreateCustomerResponse = {
+  data: { id: 'cust-1', accountId: 'acc-1', externalId: 'ext-1', email: 'user@example.com' },
+}
+
+export const mockMeldSearchCustomerResponse = {
+  data: { customers: [], count: 0, remaining: 0 },
+}
+
+export const mockMeldGetRetailQuoteRequest = {
+  countryCode: 'US',
+  sourceCurrencyCode: 'USD',
+  destinationCurrencyCode: 'ETH',
+  sourceAmount: 100,
+}
+
+export const mockMeldGetRetailQuoteResponse = {
+  data: { quotes: [] },
+}
+
+export const mockMeldCreateRetailWidgetRequest = {
+  sessionType: 'BUY' as const,
+  sessionData: {
+    countryCode: 'US',
+    serviceProvider: 'STRIPE',
+    sourceCurrencyCode: 'USD',
+    sourceAmount: '100',
+    destinationCurrencyCode: 'ETH',
+  },
+}
+
+export const mockMeldCreateRetailWidgetResponse = {
+  data: {
+    id: 'sess-1',
+    token: 'tok-1',
+    customerId: 'cust-1',
+    externalCustomerId: 'ext-cust-1',
+    externalSessionId: 'ext-ses-1',
+    widgetUrl: 'https://widget.meld.io/sess-1',
+  },
+}
+
+export const mockMeldSearchRetailTransactionsResponse = {
+  data: { transactions: [], count: 0, remaining: 0, totalCount: 0 },
+}
+
+export const mockMeldGetRetailTransactionResponse = {
+  data: {
+    transaction: {
+      id: 'tx-1',
+      sessionId: 'ses-1',
+      status: 'COMPLETED',
+      transactionType: 'BUY',
+      serviceProvider: 'STRIPE',
+      createdAt: '2024-01-01T00:00:00Z',
+      updatedAt: '2024-01-01T00:00:00Z',
+    },
+  },
+}
+
+export const mockMeldDiscoveryResponse = { data: [] }
+
+export const mockMeldDiscoveryParams = { countries: 'US' }
 export const mockBuildBatchedUserOpRequest = {
   chain: 'eip155:1',
   calls: [

package/src/__mocks/portal/portal.ts

@@ -4,7 +4,6 @@ import { mockRpcUrl } from '../constants'
 jest.mock('../../index')
 
 const portalMock = new Portal({
-  rpcConfig: {},
   autoApprove: true,
 })
 

package/src/index.test.ts

@@ -100,6 +100,7 @@ describe('Portal', () => {
           featureFlags: {},
         },
         mockProgressFn,
+        undefined,
       )
     })
 
@@ -124,6 +125,19 @@ describe('Portal', () => {
           featureFlags: { isMultiBackupEnabled: true },
         },
         mockProgressFn,
+        undefined,
+      )
+    })
+
+    it('should pass caller-supplied traceId to mpc.generate', async () => {
+      const mockProgressFn = jest.fn()
+      const callerTraceId = 'test-trace-id-create'
+      await portal.createWallet(mockProgressFn, callerTraceId)
+
+      expect(portal.mpc.generate).toHaveBeenCalledWith(
+        expect.any(Object),
+        mockProgressFn,
+        callerTraceId,
       )
     })
   })
@@ -148,6 +162,7 @@ describe('Portal', () => {
           featureFlags: {},
         },
         mockProgressFn,
+        undefined,
       )
     })
 
@@ -178,6 +193,24 @@ describe('Portal', () => {
           featureFlags: { isMultiBackupEnabled: true },
         },
         mockProgressFn,
+        undefined,
+      )
+    })
+
+    it('should pass caller-supplied traceId to mpc.backup', async () => {
+      const mockProgressFn = jest.fn()
+      const callerTraceId = 'test-trace-id-backup'
+      await portal.backupWallet(
+        BackupMethods.gdrive,
+        mockProgressFn,
+        mockBackupConfig,
+        callerTraceId,
+      )
+
+      expect(portal.mpc.backup).toHaveBeenCalledWith(
+        expect.any(Object),
+        mockProgressFn,
+        callerTraceId,
       )
     })
   })
@@ -209,6 +242,7 @@ describe('Portal', () => {
           featureFlags: {},
         },
         expect.any(Function),
+        undefined,
       )
     })
 
@@ -222,6 +256,22 @@ describe('Portal', () => {
         'Passkey backup did not return an encryption key',
       )
     })
+
+    it('should pass caller-supplied traceId to mpc.backup', async () => {
+      const callerTraceId = 'test-trace-id-gen-backup'
+      ;(portal.mpc.backup as jest.Mock).mockResolvedValueOnce({
+        cipherText: mockCipherText,
+        encryptionKey: 'manual-key',
+        storageCallback: jest.fn(),
+      })
+      await portal.generateBackupShare(undefined, callerTraceId)
+
+      expect(portal.mpc.backup).toHaveBeenCalledWith(
+        expect.any(Object),
+        expect.any(Function),
+        callerTraceId,
+      )
+    })
   })
 
   describe('registerPasskeyAndStoreEncryptionKey', () => {
@@ -356,6 +406,7 @@ describe('Portal', () => {
           featureFlags: {},
         },
         progress,
+        undefined,
       )
     })
   })
@@ -382,6 +433,7 @@ describe('Portal', () => {
           featureFlags: {},
         },
         mockProgressFn,
+        undefined,
       )
     })
 
@@ -414,6 +466,25 @@ describe('Portal', () => {
           featureFlags: { isMultiBackupEnabled: true },
         },
         mockProgressFn,
+        undefined,
+      )
+    })
+
+    it('should pass caller-supplied traceId to mpc.recover', async () => {
+      const mockProgressFn = jest.fn()
+      const callerTraceId = 'test-trace-id-recover'
+      await portal.recoverWallet(
+        mockCipherText,
+        BackupMethods.password,
+        mockBackupConfig,
+        mockProgressFn,
+        callerTraceId,
+      )
+
+      expect(portal.mpc.recover).toHaveBeenCalledWith(
+        expect.any(Object),
+        mockProgressFn,
+        callerTraceId,
       )
     })
   })
@@ -440,6 +511,7 @@ describe('Portal', () => {
           featureFlags: {},
         },
         mockProgressFn,
+        undefined,
       )
     })
 
@@ -472,6 +544,7 @@ describe('Portal', () => {
           featureFlags: { isMultiBackupEnabled: true },
         },
         mockProgressFn,
+        undefined,
       )
     })
   })
@@ -1715,4 +1788,21 @@ describe('Portal', () => {
       expect(portal.iframeRpcConfig).toEqual(iframeRpcConfig)
     })
   })
+
+  describe('onWalletNotOnDevice', () => {
+    it('returns an unsubscribe function that stops the callback from firing', () => {
+      const callback = jest.fn()
+      const unsubscribe = portal.onWalletNotOnDevice(callback)
+
+      unsubscribe()
+
+      portal.triggerWalletNotOnDevice({
+        clientId: 'test-client',
+        isBackedUp: false,
+        reason: 'storage_cleared',
+      })
+
+      expect(callback).not.toHaveBeenCalled()
+    })
+  })
 })

package/src/index.ts

@@ -59,6 +59,7 @@ import {
   type PasskeyOptions,
   type PortalOptions,
   type FirebaseStorageConfigOptions,
+  type WalletNotOnDevicePayload,
 } from '../types'
 import Mpc from './mpc'
 import Provider, { RequestMethod } from './provider'
@@ -71,6 +72,7 @@ import PasskeyService from './passkeys'
 import { EvmAccountType } from './namespaces/evmAccountType'
 import { sdkLogger } from './logger'
 import { generateTraceId } from './shared/trace'
+import { buildDefaultRpcConfig, DEFAULT_RPC_HOST } from './shared/rpc/defaults'
 import { waitForEvmOrUserOpConfirmation } from './internal/waitForEvmOrUserOpConfirmation'
 import { waitForSolanaTxConfirmation } from './internal/waitForSolanaTxConfirmation'
 import type { LogLevel, ILogger } from '../types'
@@ -100,6 +102,8 @@ class Portal {
   private _rpcConfig: RpcConfig
   private _iframeRpcConfig?: RpcConfig
   private readyCallbacks: (() => any | Promise<any>)[] = []
+  private walletNotOnDeviceCallbacks: ((payload: WalletNotOnDevicePayload) => any | Promise<any>)[] = []
+  private lastWalletNotOnDevicePayload: WalletNotOnDevicePayload | null = null
   private passkeyService?: PasskeyService
   private passkeyServiceDefaultDomain?: string
   private logger: ILogger = console
@@ -117,8 +121,9 @@ class Portal {
   }
 
   constructor({
-    // Required
+    // Optional — defaults to Portal-managed RPC gateway when omitted or empty
     rpcConfig,
+    gatewayHost,
 
     // Optional
     iframeRpcConfig,
@@ -128,7 +133,7 @@ class Portal {
     autoApprove = false,
     gdrive,
     passkey,
-    host = 'web.portalhq.io',
+    host = DEFAULT_RPC_HOST,
     mpcVersion = 'v6',
     mpcHost = 'mpc-client.portalhq.io',
     featureFlags = {},
@@ -136,11 +141,30 @@ class Portal {
     logLevel = 'none',
     logger = console,
   }: PortalOptions) {
+    // Gateway host resolution — three-level priority:
+    //   1. gatewayHost (explicit override)
+    //   2. host        (environment identity: 'web.portalhq.io' prod / 'web.portalhq.dev' staging)
+    //   3. DEFAULT_RPC_HOST (compile-time production fallback)
+    //
+    // `host` doubles as the RPC gateway domain in Portal deployments — the two are
+    // always on the same hostname per environment (confirmed in deploy configs).
+    // Deriving from `host` ensures staging callers don't silently RPC to production
+    // when only `host` is overridden. Explicit `gatewayHost` takes full precedence
+    // for custom domains or non-standard deployments.
+    const effectiveGatewayHost = gatewayHost ?? host
+
+    // Resolve rpcConfig: undefined or {} → auto-generate from effectiveGatewayHost.
+    // An explicit non-empty map is used verbatim — no merging with defaults.
+    const resolvedRpcConfig: RpcConfig =
+      !rpcConfig || Object.keys(rpcConfig).length === 0
+        ? buildDefaultRpcConfig(effectiveGatewayHost)
+        : rpcConfig
+
     this.apiKey = apiKey
     this.authToken = authToken
     this.authUrl = authUrl
     this.autoApprove = autoApprove
-    this._rpcConfig = rpcConfig
+    this._rpcConfig = resolvedRpcConfig
     this._iframeRpcConfig = iframeRpcConfig
     this.host = host
     this.mpcHost = mpcHost
@@ -287,6 +311,37 @@ class Portal {
     }
   }
 
+  public onWalletNotOnDevice(
+    callback: (payload: WalletNotOnDevicePayload) => any | Promise<any>,
+  ): () => void {
+    // Replay to late subscribers: if the event already fired, deliver immediately.
+    if (this.lastWalletNotOnDevicePayload !== null) {
+      const cached = this.lastWalletNotOnDevicePayload
+      Promise.resolve()
+        .then(() => callback(cached))
+        .catch((err) =>
+          sdkLogger.warn('[Portal] onWalletNotOnDevice callback failed:', err),
+        )
+    }
+    this.walletNotOnDeviceCallbacks.push(callback)
+    return () => {
+      this.walletNotOnDeviceCallbacks = this.walletNotOnDeviceCallbacks.filter(
+        (cb) => cb !== callback,
+      )
+    }
+  }
+
+  public triggerWalletNotOnDevice(payload: WalletNotOnDevicePayload) {
+    this.lastWalletNotOnDevicePayload = payload
+    this.walletNotOnDeviceCallbacks.forEach((callback) => {
+      Promise.resolve()
+        .then(() => callback(payload))
+        .catch((err) =>
+          sdkLogger.warn('[Portal] onWalletNotOnDevice callback failed:', err),
+        )
+    })
+  }
+
   /*****************************
    * Wallet Methods
    *****************************/
@@ -299,6 +354,7 @@ class Portal {
     progress: ProgressCallback = () => {
       // Noop
     },
+    traceId?: string,
   ): Promise<string> {
     const address = await this.mpc.generate(
       {
@@ -307,6 +363,7 @@ class Portal {
         featureFlags: this.featureFlags,
       },
       progress,
+      traceId,
     )
 
     this.address = address
@@ -318,6 +375,7 @@ class Portal {
     progress: ProgressCallback = () => {
       // Noop
     },
+    traceId?: string,
   ): Promise<BackupShareResult> {
     const response = await this.mpc.backup(
       {
@@ -330,6 +388,7 @@ class Portal {
         featureFlags: this.featureFlags,
       },
       progress,
+      traceId,
     )
 
     if (!response.encryptionKey) {
@@ -413,6 +472,7 @@ class Portal {
     progress: ProgressCallback = () => {
       // Noop
     },
+    traceId?: string,
   ): Promise<void> {
     const {
       usePopup = true,
@@ -422,7 +482,7 @@ class Portal {
     } = options
 
     if (usePopup) {
-      await this.backupWallet(backupMethod, progress, {})
+      await this.backupWallet(backupMethod, progress, {}, traceId)
       return
     }
 
@@ -434,6 +494,7 @@ class Portal {
 
     const { cipherText, encryptionKey } = await this.generateBackupShare(
       progress,
+      traceId,
     )
 
     await this.registerPasskeyAndStoreEncryptionKey(cipherText, encryptionKey, {
@@ -457,6 +518,7 @@ class Portal {
       // Noop
     },
     backupConfigs: BackupConfigs = {},
+    traceId?: string,
   ): Promise<BackupResponse> {
     const response = await this.mpc.backup(
       {
@@ -467,6 +529,7 @@ class Portal {
         featureFlags: this.featureFlags,
       },
       progress,
+      traceId,
     )
 
     return response
@@ -479,6 +542,7 @@ class Portal {
     progress: ProgressCallback = () => {
       // Noop
     },
+    traceId?: string,
   ): Promise<string> {
     const address = await this.mpc.recover(
       {
@@ -490,6 +554,7 @@ class Portal {
         featureFlags: this.featureFlags,
       },
       progress,
+      traceId,
     )
 
     this.address = address
@@ -504,8 +569,15 @@ class Portal {
     progress: ProgressCallback = () => {
       // Noop
     },
+    traceId?: string,
   ): Promise<string> {
-    return this.recoverWallet(cipherText, backupMethod, backupConfigs, progress)
+    return this.recoverWallet(
+      cipherText,
+      backupMethod,
+      backupConfigs,
+      progress,
+      traceId,
+    )
   }
 
   public async eject(
@@ -1842,9 +1914,8 @@ class Portal {
       ethereum: 'eip155:1',
       sepolia: 'eip155:11155111',
       base: 'eip155:8453',
-      'base-sepolia': 'eip155:84531',
+      'base-sepolia': 'eip155:84532',
       polygon: 'eip155:137',
-      'polygon-mumbai': 'eip155:80001',
       'polygon-amoy': 'eip155:80002',
       solana: 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp',
       'solana-devnet': 'solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1',
@@ -2008,6 +2079,23 @@ export {
 } from './shared/types'
 
 export type {
+  AccountHolderDetails,
+  AccountHolderName,
+  AmountCondition,
+  BankDetails,
+  BankToAddressRelatedPaymentMethod,
+  Channel,
+  ChannelCalculated,
+  ChannelLimits,
+  DepositSourceTriggerCondition,
+  FiatPaymentMethodCategory,
+  FiatPaymentMethodDisplayType,
+  FormNextStep,
+  IssuerDetails,
+  NoahBusinessFee,
+  NoahComparisonOperator,
+  NoahFeeDetails,
+  NoahGetPaymentMethodsRequest,
   NoahGetPaymentMethodsResponse,
   NoahGetPaymentMethodsResponseData,
   NoahGetPayoutChannelFormResponse,
@@ -2029,12 +2117,72 @@ export type {
   NoahInitiatePayoutRequest,
   NoahInitiatePayoutResponse,
   NoahInitiatePayoutResponseData,
+  NoahOnchainDepositSourceTriggerInput,
+  NoahOnchainDepositSourceTriggerType,
+  NoahPaymentMethodType,
+  NoahPermanentOnchainDepositSourceTriggerInput,
+  NoahProcessingTier,
+  NoahQuotedOnchainDepositSourceTriggerInput,
+  NoahSellQuote,
   NoahSingleOnchainDepositSourceTriggerInput,
   NoahSimulatePayinRequest,
   NoahSimulatePayinResponse,
   NoahSimulatePayinResponseData,
   NoahSolanaCaipId,
+  PaymentMethod,
+  PaymentMethodDetails,
   PortalApiSuccessEnvelope,
+  NoahBankAddress,
+  TransactionBreakdownItem,
+  TransactionBreakdownType,
+} from './shared/types'
+
+export type {
+  MeldCreateCustomerRequest,
+  MeldCreateCustomerResponse,
+  MeldCreateRetailWidgetRequest,
+  MeldCreateRetailWidgetResponse,
+  MeldCreateRetailWidgetResponseData,
+  MeldCountry,
+  MeldCountryDefault,
+  MeldCryptoCurrency,
+  MeldCryptoCurrencySellLimit,
+  MeldCustomer,
+  MeldCustomerAddress,
+  MeldCustomerAddressDetails,
+  MeldCustomerName,
+  MeldSearchCustomerResponse,
+  MeldSearchCustomerResponseData,
+  MeldCustomerType,
+  MeldDiscoveryParams,
+  MeldFiatCurrency,
+  MeldFiatCurrencyPurchaseLimit,
+  MeldGetBuyLimitsResponse,
+  MeldGetCountriesResponse,
+  MeldGetCryptoCurrenciesResponse,
+  MeldGetDefaultsResponse,
+  MeldGetFiatCurrenciesResponse,
+  MeldGetKycLimitsResponse,
+  MeldGetPaymentMethodsResponse,
+  MeldGetRetailQuoteRequest,
+  MeldGetRetailQuoteResponse,
+  MeldGetRetailQuoteResponseData,
+  MeldGetRetailTransactionResponse,
+  MeldGetRetailTransactionResponseData,
+  MeldGetSellLimitsResponse,
+  MeldGetServiceProvidersResponse,
+  MeldKycFiatLevel,
+  MeldKycLimitTier,
+  MeldPaymentMethod,
+  MeldQuote,
+  MeldRampIntelligence,
+  MeldSearchRetailTransactionsParams,
+  MeldSearchRetailTransactionsResponse,
+  MeldSearchRetailTransactionsResponseData,
+  MeldServiceProvider,
+  MeldSessionData,
+  MeldSessionType,
+  MeldTransaction,
 } from './shared/types'
 
 export type {
@@ -2049,6 +2197,9 @@ export { MpcError, MpcErrorCodes } from './mpc'
 
 export { PortalMpcError } from './mpc/errors'
 
+export { buildDefaultRpcConfig, DEFAULT_RPC_HOST } from './shared/rpc/defaults'
+export type { RpcConfig } from './shared/types'
+
 export {
   type Address,
   type Dapp,
@@ -2057,6 +2208,7 @@ export {
   type LogLevel,
   type MpcStatus,
   type PortalOptions,
+  type WalletNotOnDevicePayload,
 } from '../types'
 export { RequestMethod } from './provider'
 

package/src/integrations/ramps/index.ts

@@ -1,10 +1,13 @@
 import Mpc from '../../mpc'
+import Meld from './meld'
 import Noah from './noah'
 
 export default class Ramps {
+  public meld: Meld
   public noah: Noah
 
   constructor({ mpc }: { mpc: Mpc }) {
+    this.meld = new Meld({ mpc })
     this.noah = new Noah({ mpc })
   }
 }