fix: make docs not output confusing information in xrpl client

packages/xrpl/package.json

@@ -30,6 +30,7 @@
     "ripple-address-codec": "^4.3.0",
     "ripple-binary-codec": "^1.7.0",
     "ripple-keypairs": "^1.3.0",
+    "run-s": "0.0.0",
     "ws": "^8.2.2"
   },
   "devDependencies": {

packages/xrpl/snippets/src/getTransaction.ts

@@ -1,19 +1,19 @@
-import { Client, LedgerResponse, TxResponse } from '../../src'
+import { Client } from '../../src'
 
 const client = new Client('wss://s2.ripple.com:51233')
 
 async function getTransaction(): Promise<void> {
   await client.connect()
-  const ledger: LedgerResponse = await client.request({
+  const ledger = await client.request({
     command: 'ledger',
     transactions: true,
     ledger_index: 'validated',
   })
   console.log(ledger)
 
   const transactions = ledger.result.ledger.transactions
-  if (transactions) {
-    const tx: TxResponse = await client.request({
+  if (transactions && transactions.length > 0) {
+    const tx = await client.request({
       command: 'tx',
       transaction: transactions[0],
     })

packages/xrpl/snippets/src/paths.ts

@@ -1,4 +1,4 @@
-import { Client, Payment, RipplePathFindResponse } from '../../src'
+import { Client, Payment } from '../../src'
 
 const client = new Client('wss://s.altnet.rippletest.net:51233')
 
@@ -15,7 +15,7 @@ async function createTxWithPaths(): Promise<void> {
     issuer: 'rVnYNK9yuxBz4uP8zC8LEFokM2nqH3poc',
   }
 
-  const request = {
+  const resp = await client.request({
     command: 'ripple_path_find',
     source_account: wallet.classicAddress,
     source_currencies: [
@@ -25,9 +25,7 @@ async function createTxWithPaths(): Promise<void> {
     ],
     destination_account,
     destination_amount,
-  }
-
-  const resp: RipplePathFindResponse = await client.request(request)
+  })
   console.log(resp)
 
   const paths = resp.result.alternatives[0].paths_computed

packages/xrpl/src/Wallet/fundWallet.ts

@@ -4,7 +4,7 @@ import { request as httpsRequest, RequestOptions } from 'https'
 import { isValidClassicAddress } from 'ripple-address-codec'
 
 import type { Client } from '../client'
-import { RippledError, XRPLFaucetError } from '../errors'
+import { XRPLFaucetError } from '../errors'
 
 import {
   FaucetWallet,
@@ -20,133 +20,58 @@ const INTERVAL_SECONDS = 1
 const MAX_ATTEMPTS = 20
 
 /**
- * The fundWallet() method is used to send an amount of XRP (usually 1000) to a new (randomly generated)
- * or existing XRP Ledger wallet.
+ * Generate a new wallet to fund if no existing wallet is provided or its address is invalid.
  *
- * @example
- *
- * Example 1: Fund a randomly generated wallet
- * const { Client, Wallet } = require('xrpl')
- *
- * const client = new Client('wss://s.altnet.rippletest.net:51233')
- * await client.connect()
- * const { balance, wallet } = await client.fundWallet()
- *
- * Under the hood, this will use `Wallet.generate()` to create a new random wallet, then ask a testnet faucet
- * To send it XRP on ledger to make it a real account. If successful, this will return the new account balance in XRP
- * Along with the Wallet object to track the keys for that account. If you'd like, you can also re-fill an existing
- * Account by passing in a Wallet you already have.
- * ```ts
- * const api = new xrpl.Client("wss://s.altnet.rippletest.net:51233")
- * await api.connect()
- * const { wallet, balance } = await api.fundWallet()
- * ```
- *
- * Example 2: Fund wallet using a custom faucet host and known wallet address
- *
- * `fundWallet` will try to infer the url of a faucet API from the network your client is connected to.
- * There are hardcoded default faucets for popular test networks like testnet and devnet.
- * However, if you're working with a newer or more obscure network, you may have to specify the faucetHost
- * And faucetPath so `fundWallet` can ask that faucet to fund your wallet.
- *
- * ```ts
- * const newWallet = Wallet.generate()
- * const { balance, wallet  } = await client.fundWallet(newWallet, {
- *       amount: '10',
- *       faucetHost: 'https://custom-faucet.example.com',
- *       faucetPath: '/accounts'
- *     })
- *     console.log(`Sent 10 XRP to wallet: ${address} from the given faucet. Resulting balance: ${balance} XRP`)
- *   } catch (error) {
- *     console.error(`Failed to fund wallet: ${error}`)
- *   }
- * }
- * ```
- *
- * @param this - Client.
- * @param wallet - An existing XRPL Wallet to fund. If undefined or null, a new Wallet will be created.
- * @param options - See below.
- * @param options.faucetHost - A custom host for a faucet server. On devnet,
- * testnet, AMM devnet, and HooksV3 testnet, `fundWallet` will
- * attempt to determine the correct server automatically. In other environments,
- * or if you would like to customize the faucet host in devnet or testnet,
- * you should provide the host using this option.
- * @param options.faucetPath - A custom path for a faucet server. On devnet,
- * testnet, AMM devnet, and HooksV3 testnet, `fundWallet` will
- * attempt to determine the correct path automatically. In other environments,
- * or if you would like to customize the faucet path in devnet or testnet,
- * you should provide the path using this option.
- * Ex: client.fundWallet(null,{'faucet.altnet.rippletest.net', '/accounts'})
- * specifies a request to 'faucet.altnet.rippletest.net/accounts' to fund a new wallet.
- * @param options.amount - A custom amount to fund, if undefined or null, the default amount will be 1000.
- * @param options.usageContext - An optional field to indicate the use case context of the faucet transaction
- * Ex: integration test, code snippets.
- * @returns A Wallet on the Testnet or Devnet that contains some amount of XRP,
- * and that wallet's balance in XRP.
- * @throws When either Client isn't connected or unable to fund wallet address.
+ * @param wallet - Optional existing wallet.
+ * @returns The wallet to fund.
  */
-// eslint-disable-next-line max-lines-per-function -- All lines necessary
-async function fundWallet(
-  this: Client,
-  wallet?: Wallet | null,
-  options?: {
-    faucetHost?: string
-    faucetPath?: string
-    amount?: string
-    usageContext?: string
-  },
-): Promise<{
-  wallet: Wallet
-  balance: number
-}> {
-  if (!this.isConnected()) {
-    throw new RippledError('Client not connected, cannot call faucet')
+export function generateWalletToFund(wallet?: Wallet | null): Wallet {
+  if (wallet && isValidClassicAddress(wallet.classicAddress)) {
+    return wallet
   }
+  return Wallet.generate()
+}
 
-  // Generate a new Wallet if no existing Wallet is provided or its address is invalid to fund
-  const walletToFund =
-    wallet && isValidClassicAddress(wallet.classicAddress)
-      ? wallet
-      : Wallet.generate()
-
-  // Create the POST request body
-  const postBody = Buffer.from(
-    new TextEncoder().encode(
-      JSON.stringify({
-        destination: walletToFund.classicAddress,
-        xrpAmount: options?.amount,
-        userAgent: 'xrpl.js',
-        usageContext: options?.usageContext,
-      }),
-    ),
-  )
-
+/**
+ * Get the starting balance of the wallet.
+ *
+ * @param client - The client object.
+ * @param classicAddress - The classic address of the wallet.
+ * @returns The starting balance.
+ */
+export async function getStartingBalance(
+  client: Client,
+  classicAddress: string,
+): Promise<number> {
   let startingBalance = 0
   try {
-    startingBalance = Number(
-      await this.getXrpBalance(walletToFund.classicAddress),
-    )
+    startingBalance = Number(await client.getXrpBalance(classicAddress))
   } catch {
-    /* startingBalance remains '0' */
+    // startingBalance remains '0'
   }
-  // Options to pass to https.request
-  const httpOptions = getHTTPOptions(this, postBody, {
-    hostname: options?.faucetHost,
-    pathname: options?.faucetPath,
-  })
+  return startingBalance
+}
 
-  return returnPromise(
-    httpOptions,
-    this,
-    startingBalance,
-    walletToFund,
-    postBody,
-  )
+export interface FundWalletOptions {
+  faucetHost?: string
+  faucetPath?: string
+  amount?: string
+  usageContext?: string
 }
 
+/**
+ * Perform the fund wallet request.
+ *
+ * @param options - Optional additional options.
+ * @param client - The client object.
+ * @param startingBalance - The starting balance of the wallet.
+ * @param walletToFund - The wallet to fund.
+ * @param postBody - The body of the POST request.
+ * @returns A promise that resolves to the funded wallet and balance.
+ */
 // eslint-disable-next-line max-params -- Helper function created for organizational purposes
-async function returnPromise(
-  options: RequestOptions,
+export async function doFundWalletRequest(
+  options: FundWalletOptions | undefined,
   client: Client,
   startingBalance: number,
   walletToFund: Wallet,
@@ -155,8 +80,12 @@ async function returnPromise(
   wallet: Wallet
   balance: number
 }> {
+  const httpOptions = getHTTPOptions(client, postBody, {
+    hostname: options?.faucetHost,
+    pathname: options?.faucetPath,
+  })
   return new Promise((resolve, reject) => {
-    const request = httpsRequest(options, (response) => {
+    const request = httpsRequest(httpOptions, (response) => {
       const chunks: Uint8Array[] = []
       response.on('data', (data) => chunks.push(data))
       // eslint-disable-next-line @typescript-eslint/no-misused-promises -- not actually misused, different resolve/reject
@@ -183,6 +112,16 @@ async function returnPromise(
   })
 }
 
+/**
+ * Get the HTTP options for the request.
+ *
+ * @param client - The client object.
+ * @param postBody - The body of the request.
+ * @param options - Optional additional options.
+ * @param options.hostname - Optional hostname of the faucet server.
+ * @param options.pathname - Optional path of the faucet server. Such as /accounts
+ * @returns The HTTP options for the request.
+ */
 function getHTTPOptions(
   client: Client,
   postBody: Uint8Array,
@@ -205,6 +144,18 @@ function getHTTPOptions(
   }
 }
 
+/**
+ * Handle the 'end' event of the response.
+ *
+ * @param response - The incoming message response.
+ * @param chunks - The array of data chunks received in the response.
+ * @param client - The client object.
+ * @param startingBalance - The starting balance of the wallet.
+ * @param walletToFund - The wallet to fund.
+ * @param resolve - The function to resolve the promise.
+ * @param reject - The function to reject the promise.
+ * @returns A promise that resolves when the processing is complete.
+ */
 // eslint-disable-next-line max-params -- Helper function created for organizational purposes
 async function onEnd(
   response: IncomingMessage,
@@ -243,6 +194,17 @@ async function onEnd(
   }
 }
 
+/**
+ * Process a successful response from the faucet.
+ *
+ * @param client - The client object.
+ * @param classicAddress - The classic address of the faucet account.
+ * @param walletToFund - The wallet to fund.
+ * @param startingBalance - The starting balance of the wallet.
+ * @param resolve - The function to resolve the promise.
+ * @param reject - The function to reject the promise.
+ * @returns A promise that resolves when the processing is complete.
+ */
 // eslint-disable-next-line max-params, max-lines-per-function -- Only used as a helper function, lines inc due to added balance.
 async function processSuccessfulResponse(
   client: Client,
@@ -340,5 +302,3 @@ async function getUpdatedBalance(
     }, INTERVAL_SECONDS * 1000)
   })
 }
-
-export default fundWallet