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

package/src/shared/types/noah.ts

@@ -3,6 +3,65 @@ export interface PortalApiSuccessEnvelope<T> {
   metadata?: Record<string, unknown>
 }
 
+// -- Shared enums & primitives --
+
+export type NoahPaymentMethodType =
+  | 'BankAch'
+  | 'BankFedNow'
+  | 'BankFedwire'
+  | 'BankLocal'
+  | 'BankSepa'
+  | 'BankSortCode'
+  | 'BankSwift'
+  | 'IdentifierAlias'
+  | 'IdentifierMerchantID'
+  | 'IdentifierMobileMoney'
+  | 'IdentifierPix'
+  | 'IdentifierQr'
+  | 'TokenizedCard'
+
+export type FiatPaymentMethodCategory = 'Bank' | 'Card' | 'Identifier'
+
+export type FiatPaymentMethodDisplayType =
+  | 'FiatPaymentMethodBankDisplay'
+  | 'FiatPaymentMethodCardDisplay'
+  | 'FiatPaymentMethodIdentifierDisplay'
+
+export type NoahComparisonOperator = 'EQ' | 'LTEQ' | 'GTEQ'
+
+export type NoahProcessingTier = 'Standard' | 'Priority'
+
+export type TransactionBreakdownType = 'ChannelFee' | 'BusinessFee' | 'Remaining'
+
+export interface TransactionBreakdownItem {
+  type: TransactionBreakdownType
+  amount: string
+}
+
+export interface NoahSellQuote {
+  signedQuote: string
+  expiry: string
+}
+
+/** Richer fee object returned by payin and related payment method responses. */
+export interface NoahFeeDetails {
+  fiatCurrencyCode: string
+  totalFeePct: string
+  totalFeeBase: string
+  totalFeeMin: string
+}
+
+/** Optional business-level fee configuration passed on payout/quote/payin requests. */
+export interface NoahBusinessFee {
+  feeBase?: string
+  feePct?: string
+  fiatCurrency?: string
+}
+
+export type BusinessFeesInput = Record<string, NoahBusinessFee>
+
+// -- KYC --
+
 export interface NoahInitiateKycRequest {
   returnUrl: string
   fiatOptions?: { fiatCurrencyCode: string }[]
@@ -18,26 +77,30 @@ export interface NoahInitiateKycResponseData {
 export type NoahInitiateKycResponse =
   PortalApiSuccessEnvelope<NoahInitiateKycResponseData>
 
+// -- Payin --
+
 export interface NoahInitiatePayinRequest {
   fiatCurrency: string
   cryptoCurrency: string
   network: string
   destinationAddress: string
+  businessFees?: BusinessFeesInput
 }
 
-export interface StreetAddress {
-  city?: string
-  country?: string
-  line1?: string
-  line2?: string
-  postalCode?: string
-  state?: string
+export interface NoahBankAddress {
+  street: string
+  street2?: string
+  city: string
+  postCode: string
+  state: string
+  country: string
 }
 
 export interface BankToAddressRelatedPaymentMethod {
   paymentMethodId: string
-  paymentMethodType: string
-  details?: {
+  paymentMethodType: NoahPaymentMethodType
+  fee: NoahFeeDetails
+  details: {
     accountNumber?: string
     bankCode?: string
   }
@@ -45,19 +108,23 @@ export interface BankToAddressRelatedPaymentMethod {
 
 export interface BankDetails {
   paymentMethodId: string
-  paymentMethodType: string
+  paymentMethodType: NoahPaymentMethodType
   accountNumber: string
+  cryptoCurrency: string
   network: string
+  fee: NoahFeeDetails
   accountHolderName?: string
   bankCode?: string
   bankName?: string
-  bankAddress?: StreetAddress
+  bankAddress?: NoahBankAddress
   reference?: string
   relatedPaymentMethods?: BankToAddressRelatedPaymentMethod[]
 }
 
 export interface NoahInitiatePayinResponseData {
   payinId: string
+  cryptoCurrency: string
+  fee: NoahFeeDetails
   bankDetails: BankDetails
 }
 
@@ -72,11 +139,14 @@ export interface NoahSimulatePayinRequest {
 
 export interface NoahSimulatePayinResponseData {
   fiatDepositId: string
+  reference?: string
 }
 
 export type NoahSimulatePayinResponse =
   PortalApiSuccessEnvelope<NoahSimulatePayinResponseData>
 
+// -- Payout countries --
+
 export interface NoahGetPayoutCountriesResponseData {
   countries: Record<string, string[]>
 }
@@ -84,11 +154,16 @@ export interface NoahGetPayoutCountriesResponseData {
 export type NoahGetPayoutCountriesResponse =
   PortalApiSuccessEnvelope<NoahGetPayoutCountriesResponseData>
 
+// -- Payout channels --
+
 export interface NoahGetPayoutChannelsRequest {
-  country: string
   cryptoCurrency: string
-  fiatCurrency: string
+  country?: string
+  fiatCurrency?: string
   fiatAmount?: string
+  paymentMethodId?: string
+  pageSize?: number
+  pageToken?: string
 }
 
 export interface ChannelLimits {
@@ -102,13 +177,17 @@ export interface ChannelCalculated {
 
 export interface Channel {
   id: string
-  paymentMethodType: string
+  paymentMethodCategory: FiatPaymentMethodCategory
+  paymentMethodType: NoahPaymentMethodType
   fiatCurrency: string
   country: string
   limits: ChannelLimits
   rate: string
   processingSeconds: number
   calculated?: ChannelCalculated
+  processingTier?: NoahProcessingTier
+  issuer?: string
+  paymentMethods?: PaymentMethodDisplay[]
 }
 
 export interface NoahGetPayoutChannelsResponseData {
@@ -129,38 +208,61 @@ export interface NoahGetPayoutChannelFormResponseData {
 export type NoahGetPayoutChannelFormResponse =
   PortalApiSuccessEnvelope<NoahGetPayoutChannelFormResponseData>
 
+// -- Payment methods --
+
 export interface PaymentMethodDetails {
-  type: string
+  type: FiatPaymentMethodDisplayType
   accountNumber?: string
   bankCode?: string
+  routingNumber?: string
+  swiftCode?: string
+  bankingSystems?: string[]
+  bankName?: string
+  bankAddress?: NoahBankAddress
   last4?: string
   scheme?: string
   identifierType?: string
   identifier?: string
 }
+export interface PaymentMethodDisplay {
+  id: string
+  paymentMethodType: NoahPaymentMethodType
+  details: PaymentMethodDetails
+  accountHolderDetails?: AccountHolderDetails
+  issuerDetails?: IssuerDetails
+}
+
+/** Name components for the account holder. */
+export interface AccountHolderName {
+  firstName: string
+  lastName: string
+  middleName?: string
+}
 
 export interface AccountHolderDetails {
-  name?: string
-  taxId?: string
-  email?: string
-  phoneNumber?: string
-  address?: StreetAddress
+  /** Structured name; use firstName/lastName rather than a flat string. */
+  name?: AccountHolderName
 }
 
 export interface IssuerDetails {
   name?: string
-  bankCode?: string
-  bankName?: string
 }
 
 export interface PaymentMethod {
   id: string
-  paymentMethodType: string
+  paymentMethodCategory: FiatPaymentMethodCategory
+  paymentMethodType: NoahPaymentMethodType
   details: PaymentMethodDetails
   accountHolderDetails?: AccountHolderDetails
   issuerDetails?: IssuerDetails
 }
 
+export interface NoahGetPaymentMethodsRequest {
+  pageSize?: number
+  pageToken?: string
+  capability?: 'PayoutFrom' | 'PayinTo' | 'PayoutTo'
+}
+
 export interface NoahGetPaymentMethodsResponseData {
   paymentMethods: PaymentMethod[]
   pageToken?: string
@@ -169,17 +271,29 @@ export interface NoahGetPaymentMethodsResponseData {
 export type NoahGetPaymentMethodsResponse =
   PortalApiSuccessEnvelope<NoahGetPaymentMethodsResponseData>
 
-export interface NoahGetPayoutQuoteRequest {
+// -- Payout quote --
+export interface BasePayoutQuoteRequest {
   channelId: string
   cryptoCurrency: string
-  fiatAmount: string
   form?: Record<string, unknown>
   fiatCurrency?: string
   paymentMethodId?: string
+  quoted?: boolean
+  businessFee?: NoahBusinessFee
 }
 
+export type NoahGetPayoutQuoteRequest =
+  | (BasePayoutQuoteRequest & {
+      fiatAmount: string
+      cryptoAmount?: never
+    })
+  | (BasePayoutQuoteRequest & {
+      cryptoAmount: string
+      fiatAmount?: never
+    })
+
 export interface FormNextStep {
-  stepId: string
+  stepId: 'Vop' | 'Cob' | 'PaymentDetails'
   stepType: 'Ack' | 'DataEntry'
   schema: Record<string, unknown>
 }
@@ -188,15 +302,27 @@ export interface NoahGetPayoutQuoteResponseData {
   payoutId: string
   totalFee: string
   cryptoAmountEstimate: string
+  cryptoAuthorizedAmount: string
   formSessionId: string
+  rate?: string
+  breakdown?: TransactionBreakdownItem[]
+  quote?: NoahSellQuote
+  /** Disclosure: crypto currency for this quote. */
+  cryptoCurrency?: string
+  /** Disclosure: fiat currency for this quote. */
+  fiatCurrency?: string
+  /** Disclosure: fiat amount for this quote. */
+  fiatAmount?: string
   nextStep?: FormNextStep
 }
 
 export type NoahGetPayoutQuoteResponse =
   PortalApiSuccessEnvelope<NoahGetPayoutQuoteResponseData>
 
+// -- Payout trigger & initiation --
+
 export interface AmountCondition {
-  comparisonOperator: string
+  comparisonOperator: NoahComparisonOperator
   value: string
 }
 
@@ -204,6 +330,7 @@ export interface DepositSourceTriggerCondition {
   amountConditions: AmountCondition[]
   cryptoCurrency: string
   network: string
+  /** Runtime value is always a plain string, not an object. */
   destinationAddress: string
 }
 
@@ -212,10 +339,37 @@ export type NoahSolanaCaipId =
   | 'solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1'
   | 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp'
 
+export type NoahOnchainDepositSourceTriggerType =
+  | 'SingleOnchainDepositSourceTriggerInput'
+  | 'PermanentOnchainDepositSourceTriggerInput'
+  | 'QuotedOnchainDepositSourceTriggerInput'
+
 export interface NoahSingleOnchainDepositSourceTriggerInput {
   Type: 'SingleOnchainDepositSourceTriggerInput'
   Conditions: {
-    AmountConditions: { ComparisonOperator: string; Value: string }[]
+    AmountConditions: { ComparisonOperator: NoahComparisonOperator; Value: string }[]
+    Network: string
+  }[]
+  SourceAddress: string
+  Expiry: string
+  Nonce: string
+}
+
+export interface NoahPermanentOnchainDepositSourceTriggerInput {
+  Type: 'PermanentOnchainDepositSourceTriggerInput'
+  Conditions: {
+    AmountConditions: { ComparisonOperator: NoahComparisonOperator; Value: string }[]
+    Network: string
+  }[]
+  SourceAddress: string
+  Expiry: string
+  Nonce: string
+}
+
+export interface NoahQuotedOnchainDepositSourceTriggerInput {
+  Type: 'QuotedOnchainDepositSourceTriggerInput'
+  Conditions: {
+    AmountConditions: { ComparisonOperator: NoahComparisonOperator; Value: string }[]
     Network: string
   }[]
   SourceAddress: string
@@ -223,18 +377,26 @@ export interface NoahSingleOnchainDepositSourceTriggerInput {
   Nonce: string
 }
 
+export type NoahOnchainDepositSourceTriggerInput =
+  | NoahSingleOnchainDepositSourceTriggerInput
+  | NoahPermanentOnchainDepositSourceTriggerInput
+  | NoahQuotedOnchainDepositSourceTriggerInput
+
 export interface NoahInitiatePayoutRequest {
   payoutId: string
   sourceAddress: string
   expiry: string
   nonce: string
   network: string
-  trigger?: NoahSingleOnchainDepositSourceTriggerInput
+  businessFee?: NoahBusinessFee
+  fiatAmount?: string
+  trigger?: NoahOnchainDepositSourceTriggerInput
 }
 
 export interface NoahInitiatePayoutResponseData {
   destinationAddress: string | null
   conditions: DepositSourceTriggerCondition[]
+  ruleId?: string
 }
 
 export type NoahInitiatePayoutResponse =

package/types.d.ts

@@ -173,6 +173,12 @@ export interface ClientResponse {
   wallets: ClientResponseWallet[]
 }
 
+export interface WalletNotOnDevicePayload {
+  clientId: string
+  isBackedUp: boolean
+  reason: 'storage_cleared'
+}
+
 interface ClientResponseCustodian {
   id: string
   name: string
@@ -269,8 +275,15 @@ export interface PortalApiOptions {
 }
 
 export interface PortalOptions {
-  // Required options
-  rpcConfig: RpcConfig
+  /**
+   * RPC endpoint map (CAIP-2 chainId → URL).
+   *
+   * Optional — when omitted or set to `{}`, the SDK auto-generates a default
+   * gateway config pointing at `https://{gatewayHost}/rpc/v1/{namespace}/{reference}`
+   * for 13 built-in chains. An explicit non-empty map is used verbatim (no
+   * merging with defaults).
+   */
+  rpcConfig?: RpcConfig
 
   /**
    * Optional RPC map for iframe-proxied reads only (receipt / Solana polling). Parent signing still
@@ -278,13 +291,62 @@ export interface PortalOptions {
    */
   iframeRpcConfig?: RpcConfig
 
-  // Optional options
+  /**
+   * Portal RPC gateway hostname used to construct default RPC URLs when no `rpcConfig`
+   * is supplied.
+   *
+   * Resolution order:
+   *   1. This field (explicit override)
+   *   2. `host` (derived — Portal deploys both on the same hostname per environment)
+   *   3. `'web.portalhq.io'` (compile-time production default)
+   *
+   * Set this only when the RPC gateway lives on a different hostname than `host`
+   * (e.g. a custom CDN). For standard Portal environments, setting `host` is
+   * sufficient — the gateway follows automatically.
+   *
+   * @example
+   * // Staging: set host only; gatewayHost derives automatically.
+   * new Portal({ host: 'web.portalhq.dev', apiKey: '...' })
+   *
+   * // Custom CDN: set both independently.
+   * new Portal({ host: 'web.portalhq.io', gatewayHost: 'rpc.my-infra.com', apiKey: '...' })
+   */
+  gatewayHost?: string
+
+  /**
+   * Persistent client-level credential (`ClientApiKey` in the backend).
+   *
+   * - No expiry. Issued once per client wallet.
+   * - Accepted on the Portal RPC gateway (`/rpc`) and on internal service routes (`/service`).
+   * - Takes precedence over `authToken` when both are supplied.
+   *
+   * Use this for server-side or long-lived integrations.
+   */
   apiKey?: string
+
+  /**
+   * Short-lived session credential (`ClientSessionToken` in the backend).
+   *
+   * - Has an expiry (`expiresAt`) and a maximum refresh window (`maxRefreshAt`).
+   * - Accepted on the Portal RPC gateway (`/rpc`). Not accepted on `/service` (MPC layer).
+   * - Used as a fallback when `apiKey` is not set.
+   *
+   * Use this for client-side, user-session-scoped integrations (e.g. browser dApps).
+   */
   authToken?: string
   authUrl?: string
   autoApprove?: boolean
   gdrive?: GDriveConfig
   passkey?: PasskeyConfig
+  /**
+   * Portal API + RPC gateway hostname. Defines the environment identity.
+   *
+   * - Production: `'web.portalhq.io'` (default)
+   * - Staging: `'web.portalhq.dev'`
+   *
+   * When `gatewayHost` is not explicitly set, the RPC gateway derives from this
+   * value, ensuring both services stay on the same environment.
+   */
   host?: string
   mpcHost?: string
   keychain?: KeychainAdapter