fix: make docs not output confusing information in xrpl client

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,128 +20,57 @@ 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.
- * @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
-  },
-): 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,
-      }),
-    ),
-  )
-
+/**
+ * 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
 }
 
+/**
+ * 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,
@@ -150,8 +79,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
@@ -178,6 +111,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,
@@ -200,6 +143,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,
@@ -238,6 +193,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,
@@ -335,5 +301,3 @@ async function getUpdatedBalance(
     }, INTERVAL_SECONDS * 1000)
   })
 }
-
-export default fundWallet