@ethersphere/bee-js 3.2.0 → 3.3.2-pre.0

package/dist/mjs/bee-debug.js

@@ -0,0 +1,609 @@
+import * as connectivity from "./modules/debug/connectivity.js";
+import * as balance from "./modules/debug/balance.js";
+import * as chequebook from "./modules/debug/chequebook.js";
+import * as settlements from "./modules/debug/settlements.js";
+import * as status from "./modules/debug/status.js";
+import * as transactions from "./modules/debug/transactions.js";
+import * as states from "./modules/debug/states.js";
+import { BeeArgumentError } from "./utils/error.js";
+import { assertBeeUrl, stripLastSlash } from "./utils/url.js";
+import { assertAddress, assertBatchId, assertBoolean, assertCashoutOptions, assertNonNegativeInteger, assertRequestOptions, assertTransactionHash, isTag } from "./utils/type.js";
+import { STAMPS_DEPTH_MAX, STAMPS_DEPTH_MIN } from "./types/index.js";
+import * as tag from "./modules/debug/tag.js";
+import * as stamps from "./modules/debug/stamps.js";
+import { makeDefaultKy, wrapRequestClosure, wrapResponseClosure } from "./utils/http.js";
+export class BeeDebug {
+  /**
+   * URL on which is the Debug API of Bee node exposed
+   */
+  url;
+  /**
+   * Ky instance that defines connection to Bee node
+   * @private
+   */
+
+  ky;
+
+  constructor(url, options) {
+    assertBeeUrl(url); // Remove last slash if present, as our endpoint strings starts with `/...`
+    // which could lead to double slash in URL to which Bee responds with
+    // unnecessary redirects.
+
+    this.url = stripLastSlash(url);
+    const kyOptions = {
+      prefixUrl: this.url,
+      timeout: options?.timeout ?? false,
+      retry: options?.retry,
+      fetch: options?.fetch,
+      hooks: {
+        beforeRequest: [],
+        afterResponse: []
+      }
+    };
+
+    if (options?.defaultHeaders) {
+      kyOptions.headers = options.defaultHeaders;
+    }
+
+    if (options?.onRequest) {
+      kyOptions.hooks.beforeRequest.push(wrapRequestClosure(options.onRequest));
+    }
+
+    if (options?.onResponse) {
+      kyOptions.hooks.afterResponse.push(wrapResponseClosure(options.onResponse));
+    }
+
+    this.ky = makeDefaultKy(kyOptions);
+  }
+
+  async getNodeAddresses(options) {
+    assertRequestOptions(options);
+    return connectivity.getNodeAddresses(this.getKy(options));
+  }
+
+  async getBlocklist(options) {
+    assertRequestOptions(options);
+    return connectivity.getBlocklist(this.getKy(options));
+  }
+  /**
+   * Retrieve tag extended information from Bee node
+   *
+   * @param tagUid UID or tag object to be retrieved
+   * @throws TypeError if tagUid is in not correct format
+   *
+   * @see [Bee docs - Syncing / Tags](https://docs.ethswarm.org/docs/access-the-swarm/syncing)
+   * @see [Bee API reference - `GET /tags/{uid}`](https://docs.ethswarm.org/debug-api/#tag/Tag)
+   *
+   */
+
+
+  async retrieveExtendedTag(tagUid, options) {
+    assertRequestOptions(options);
+
+    if (isTag(tagUid)) {
+      tagUid = tagUid.uid;
+    } else if (typeof tagUid === 'number') {
+      assertNonNegativeInteger(tagUid, 'UID');
+    } else {
+      throw new TypeError('tagUid has to be either Tag or a number (UID)!');
+    }
+
+    return tag.retrieveExtendedTag(this.getKy(options), tagUid);
+  }
+  /**
+   * Get list of peers for this node
+   */
+
+
+  async getPeers(options) {
+    assertRequestOptions(options);
+    return connectivity.getPeers(this.getKy(options));
+  }
+
+  async removePeer(peer, options) {
+    assertRequestOptions(options);
+    assertAddress(peer);
+    return connectivity.removePeer(this.getKy(options), peer);
+  }
+
+  async getTopology(options) {
+    assertRequestOptions(options);
+    return connectivity.getTopology(this.getKy(options));
+  }
+
+  async pingPeer(peer, options) {
+    assertRequestOptions(options);
+    assertAddress(peer);
+    return connectivity.pingPeer(this.getKy(options), peer);
+  }
+  /*
+   * Balance endpoints
+   */
+
+  /**
+   * Get the balances with all known peers including prepaid services
+   */
+
+
+  async getAllBalances(options) {
+    assertRequestOptions(options);
+    return balance.getAllBalances(this.getKy(options));
+  }
+  /**
+   * Get the balances with a specific peer including prepaid services
+   *
+   * @param address Swarm address of peer
+   */
+
+
+  async getPeerBalance(address, options) {
+    assertRequestOptions(options);
+    assertAddress(address);
+    return balance.getPeerBalance(this.getKy(options), address);
+  }
+  /**
+   * Get the past due consumption balances with all known peers
+   */
+
+
+  async getPastDueConsumptionBalances(options) {
+    assertRequestOptions(options);
+    return balance.getPastDueConsumptionBalances(this.getKy(options));
+  }
+  /**
+   * Get the past due consumption balance with a specific peer
+   *
+   * @param address Swarm address of peer
+   */
+
+
+  async getPastDueConsumptionPeerBalance(address, options) {
+    assertRequestOptions(options);
+    assertAddress(address);
+    return balance.getPastDueConsumptionPeerBalance(this.getKy(options), address);
+  }
+  /*
+   * Chequebook endpoints
+   */
+
+  /**
+   * Get the address of the chequebook contract used.
+   *
+   * **Warning:** The address is returned with 0x prefix unlike all other calls.
+   * https://github.com/ethersphere/bee/issues/1443
+   */
+
+
+  async getChequebookAddress(options) {
+    assertRequestOptions(options);
+    return chequebook.getChequebookAddress(this.getKy(options));
+  }
+  /**
+   * Get the balance of the chequebook
+   */
+
+
+  async getChequebookBalance(options) {
+    assertRequestOptions(options);
+    return chequebook.getChequebookBalance(this.getKy(options));
+  }
+  /**
+   * Get last cheques for all peers
+   */
+
+
+  async getLastCheques(options) {
+    assertRequestOptions(options);
+    return chequebook.getLastCheques(this.getKy(options));
+  }
+  /**
+   * Get last cheques for the peer
+   *
+   * @param address  Swarm address of peer
+   */
+
+
+  async getLastChequesForPeer(address, options) {
+    assertRequestOptions(options);
+    assertAddress(address);
+    return chequebook.getLastChequesForPeer(this.getKy(options), address);
+  }
+  /**
+   * Get last cashout action for the peer
+   *
+   * @param address  Swarm address of peer
+   */
+
+
+  async getLastCashoutAction(address, options) {
+    assertRequestOptions(options);
+    assertAddress(address);
+    return chequebook.getLastCashoutAction(this.getKy(options), address);
+  }
+  /**
+   * Cashout the last cheque for the peer
+   *
+   * @param address  Swarm address of peer
+   * @param options
+   * @param options.gasPrice Gas price for the cashout transaction in WEI
+   * @param options.gasLimit Gas limit for the cashout transaction in WEI
+   */
+
+
+  async cashoutLastCheque(address, options) {
+    assertCashoutOptions(options);
+    assertAddress(address);
+    return chequebook.cashoutLastCheque(this.getKy(options), address, options);
+  }
+  /**
+   * Deposit tokens from overlay address into chequebook
+   *
+   * @param amount  Amount of tokens to deposit (must be positive integer)
+   * @param gasPrice Gas Price in WEI for the transaction call
+   * @return string  Hash of the transaction
+   */
+
+
+  async depositTokens(amount, gasPrice, options) {
+    assertRequestOptions(options);
+    assertNonNegativeInteger(amount);
+
+    if (gasPrice) {
+      assertNonNegativeInteger(gasPrice);
+    }
+
+    return chequebook.depositTokens(this.getKy(options), amount, gasPrice);
+  }
+  /**
+   * Withdraw tokens from the chequebook to the overlay address
+   *
+   * @param amount  Amount of tokens to withdraw (must be positive integer)
+   * @param gasPrice Gas Price in WEI for the transaction call
+   * @return string  Hash of the transaction
+   */
+
+
+  async withdrawTokens(amount, gasPrice, options) {
+    assertRequestOptions(options);
+    assertNonNegativeInteger(amount);
+
+    if (gasPrice) {
+      assertNonNegativeInteger(gasPrice);
+    }
+
+    return chequebook.withdrawTokens(this.getKy(options), amount, gasPrice);
+  }
+  /*
+   * Settlements endpoint
+   */
+
+  /**
+   * Get amount of sent and received from settlements with a peer
+   *
+   * @param address  Swarm address of peer
+   */
+
+
+  async getSettlements(address, options) {
+    assertRequestOptions(options);
+    assertAddress(address);
+    return settlements.getSettlements(this.getKy(options), address);
+  }
+  /**
+   * Get settlements with all known peers and total amount sent or received
+   */
+
+
+  async getAllSettlements(options) {
+    assertRequestOptions(options);
+    return settlements.getAllSettlements(this.getKy(options));
+  }
+  /**
+   * Get health of node
+   */
+
+
+  async getHealth(options) {
+    assertRequestOptions(options);
+    return status.getHealth(this.getKy(options));
+  }
+  /**
+   * Get mode information of node
+   */
+
+
+  async getNodeInfo(options) {
+    assertRequestOptions(options);
+    return status.getNodeInfo(this.getKy(options));
+  }
+  /**
+   * Connnects to a node and checks if it is a supported Bee version by the bee-js
+   *
+   * @returns true if the Bee node version is supported
+   * @deprecated Use `BeeDebug.isSupportedExactVersion()` instead
+   */
+
+
+  async isSupportedVersion(options) {
+    assertRequestOptions(options);
+    return status.isSupportedVersion(this.getKy(options));
+  }
+  /**
+   * Connects to a node and checks if its version matches with the one that bee-js supports.
+   *
+   * Be aware that this is the most strict version check and most probably
+   * you will want to use more relaxed API-versions based checks like
+   * `BeeDebug.isSupportedApiVersion()`, `BeeDebug.isSupportedMainApiVersion()` or `BeeDebug.isSupportedDebugApiVersion()`
+   * based on your use-case.
+   *
+   * @param options
+   */
+
+
+  async isSupportedExactVersion(options) {
+    assertRequestOptions(options);
+    return status.isSupportedExactVersion(this.getKy(options));
+  }
+  /**
+   * Connects to a node and checks if its main's API version matches with the one that bee-js supports.
+   *
+   * This is useful if you are not using `BeeDebug` class (for anything else then this check)
+   * and want to make sure about compatibility.
+   *
+   * @param options
+   */
+
+
+  async isSupportedMainApiVersion(options) {
+    assertRequestOptions(options);
+    return status.isSupportedMainApiVersion(this.getKy(options));
+  }
+  /**
+   * Connects to a node and checks if its Debug API version matches with the one that bee-js supports.
+   *
+   * This is useful if you are not using `Bee` class in your application and want to make sure
+   * about compatibility.
+   *
+   * @param options
+   */
+
+
+  async isSupportedDebugApiVersion(options) {
+    assertRequestOptions(options);
+    return status.isSupportedDebugApiVersion(this.getKy(options));
+  }
+  /**
+   *
+   * Connects to a node and checks if its Main and Debug API versions matches with the one that bee-js supports.
+   *
+   * This should be the main way how to check compatibility for your app and Bee node.
+   *
+   * @param options
+   */
+
+
+  async isSupportedApiVersion(options) {
+    assertRequestOptions(options);
+    return status.isSupportedDebugApiVersion(this.getKy(options));
+  }
+  /**
+   * Returns object with all versions specified by the connected Bee node (properties prefixed with `bee*`)
+   * and versions that bee-js supports (properties prefixed with `supported*`).
+   *
+   * @param options
+   */
+
+
+  async getVersions(options) {
+    assertRequestOptions(options);
+    return status.getVersions(this.getKy(options));
+  }
+  /**
+   * Get reserve state
+   */
+
+
+  async getReserveState(options) {
+    assertRequestOptions(options);
+    return states.getReserveState(this.getKy(options));
+  }
+  /**
+   * Get chain state
+   */
+
+
+  async getChainState(options) {
+    assertRequestOptions(options);
+    return states.getChainState(this.getKy(options));
+  }
+  /**
+   * Creates new postage batch from the funds that the node has available in its Ethereum account.
+   *
+   * For better understanding what each parameter means and what are the optimal values please see
+   * [Bee docs - Keep your data alive / Postage stamps](https://docs.ethswarm.org/docs/access-the-swarm/keep-your-data-alive).
+   *
+   * **WARNING: THIS CREATES TRANSACTIONS THAT SPENDS MONEY**
+   *
+   * @param amount Amount that represents the value per chunk, has to be greater or equal zero.
+   * @param depth Logarithm of the number of chunks that can be stamped with the batch.
+   * @param options Options for creation of postage batch
+   * @throws BeeArgumentError when negative amount or depth is specified
+   * @throws TypeError if non-integer value is passed to amount or depth
+   *
+   * @see [Bee docs - Keep your data alive / Postage stamps](https://docs.ethswarm.org/docs/access-the-swarm/keep-your-data-alive)
+   * @see [Bee Debug API reference - `POST /stamps`](https://docs.ethswarm.org/debug-api/#tag/Postage-Stamps/paths/~1stamps~1{amount}~1{depth}/post)
+   */
+
+
+  async createPostageBatch(amount, depth, options) {
+    assertRequestOptions(options);
+    assertNonNegativeInteger(amount);
+    assertNonNegativeInteger(depth);
+
+    if (depth < STAMPS_DEPTH_MIN) {
+      throw new BeeArgumentError(`Depth has to be at least ${STAMPS_DEPTH_MIN}`, depth);
+    }
+
+    if (depth > STAMPS_DEPTH_MAX) {
+      throw new BeeArgumentError(`Depth has to be at most ${STAMPS_DEPTH_MAX}`, depth);
+    }
+
+    if (options?.gasPrice) {
+      assertNonNegativeInteger(options.gasPrice);
+    }
+
+    if (options?.immutableFlag !== undefined) {
+      assertBoolean(options.immutableFlag);
+    }
+
+    return stamps.createPostageBatch(this.getKy(options), amount, depth, options);
+  }
+  /**
+   * Topup a fresh amount of BZZ to given Postage Batch.
+   *
+   * For better understanding what each parameter means and what are the optimal values please see
+   * [Bee docs - Keep your data alive / Postage stamps](https://docs.ethswarm.org/docs/access-the-swarm/keep-your-data-alive).
+   *
+   * **WARNING: THIS CREATES TRANSACTIONS THAT SPENDS MONEY**
+   *
+   * @param postageBatchId Batch ID
+   * @param amount Amount to be added to the batch
+   * @param options Request options
+   *
+   * @see [Bee docs - Keep your data alive / Postage stamps](https://docs.ethswarm.org/docs/access-the-swarm/keep-your-data-alive)
+   * @see [Bee Debug API reference - `PATCH /stamps/topup/${id}/${amount}`](https://docs.ethswarm.org/debug-api/#tag/Postage-Stamps/paths/~1stamps~1topup~1{id}~1{amount}/patch)
+   */
+
+
+  async topUpBatch(postageBatchId, amount, options) {
+    assertRequestOptions(options);
+    assertNonNegativeInteger(amount, 'Amount');
+    assertBatchId(postageBatchId);
+    await stamps.topUpBatch(this.getKy(options), postageBatchId, amount);
+  }
+  /**
+   * Dilute given Postage Batch with new depth (that has to be bigger then the original depth), which allows
+   * the Postage Batch to be used for more chunks.
+   *
+   * For better understanding what each parameter means and what are the optimal values please see
+   * [Bee docs - Keep your data alive / Postage stamps](https://docs.ethswarm.org/docs/access-the-swarm/keep-your-data-alive).
+   *
+   * **WARNING: THIS CREATES TRANSACTIONS THAT SPENDS MONEY**
+   *
+   * @param postageBatchId Batch ID
+   * @param depth Amount to be added to the batch
+   * @param options Request options
+   *
+   * @see [Bee docs - Keep your data alive / Postage stamps](https://docs.ethswarm.org/docs/access-the-swarm/keep-your-data-alive)
+   * @see [Bee Debug API reference - `PATCH /stamps/topup/${id}/${amount}`](https://docs.ethswarm.org/debug-api/#tag/Postage-Stamps/paths/~1stamps~1topup~1{id}~1{amount}/patch)
+   */
+
+
+  async diluteBatch(postageBatchId, depth, options) {
+    assertRequestOptions(options);
+    assertNonNegativeInteger(depth, 'Depth');
+    assertBatchId(postageBatchId);
+    await stamps.diluteBatch(this.getKy(options), postageBatchId, depth);
+  }
+  /**
+   * Return details for specific postage batch.
+   *
+   * @param postageBatchId Batch ID
+   *
+   * @see [Bee docs - Keep your data alive / Postage stamps](https://docs.ethswarm.org/docs/access-the-swarm/keep-your-data-alive)
+   * @see [Bee Debug API reference - `GET /stamps/${id}`](https://docs.ethswarm.org/debug-api/#tag/Postage-Stamps/paths/~1stamps~1{id}/get)
+   */
+
+
+  async getPostageBatch(postageBatchId, options) {
+    assertRequestOptions(options);
+    assertBatchId(postageBatchId);
+    return stamps.getPostageBatch(this.getKy(options), postageBatchId);
+  }
+  /**
+   * Return detailed information related to buckets for specific postage batch.
+   *
+   * @param postageBatchId Batch ID
+   *
+   * @see [Bee docs - Keep your data alive / Postage stamps](https://docs.ethswarm.org/docs/access-the-swarm/keep-your-data-alive)
+   * @see [Bee Debug API reference - `GET /stamps/${id}/buckets`](https://docs.ethswarm.org/debug-api/#tag/Postage-Stamps/paths/~1stamps~1{id}~1buckets/get)
+   */
+
+
+  async getPostageBatchBuckets(postageBatchId, options) {
+    assertRequestOptions(options);
+    assertBatchId(postageBatchId);
+    return stamps.getPostageBatchBuckets(this.getKy(options), postageBatchId);
+  }
+  /**
+   * Return all postage batches that has the node available.
+   *
+   * @see [Bee docs - Keep your data alive / Postage stamps](https://docs.ethswarm.org/docs/access-the-swarm/keep-your-data-alive)
+   * @see [Bee Debug API reference - `GET /stamps`](https://docs.ethswarm.org/debug-api/#tag/Postage-Stamps/paths/~1stamps/get)
+   */
+
+
+  async getAllPostageBatch(options) {
+    assertRequestOptions(options);
+    return stamps.getAllPostageBatches(this.getKy(options));
+  }
+  /**
+   * Return lists of all current pending transactions that the Bee made
+   */
+
+
+  async getAllPendingTransactions(options) {
+    assertRequestOptions(options);
+    return transactions.getAllTransactions(this.getKy(options));
+  }
+  /**
+   * Return transaction information for specific transaction
+   * @param transactionHash
+   */
+
+
+  async getPendingTransaction(transactionHash, options) {
+    assertRequestOptions(options);
+    assertTransactionHash(transactionHash);
+    return transactions.getTransaction(this.getKy(options), transactionHash);
+  }
+  /**
+   * Rebroadcast already created transaction.
+   * This is mainly needed when your transaction fall off mempool from other reason is not incorporated into block.
+   *
+   * @param transactionHash
+   */
+
+
+  async rebroadcastPendingTransaction(transactionHash, options) {
+    assertRequestOptions(options);
+    assertTransactionHash(transactionHash);
+    return transactions.rebroadcastTransaction(this.getKy(options), transactionHash);
+  }
+  /**
+   * Cancel currently pending transaction
+   * @param transactionHash
+   * @param gasPrice
+   */
+
+
+  async cancelPendingTransaction(transactionHash, gasPrice, options) {
+    assertRequestOptions(options);
+    assertTransactionHash(transactionHash);
+
+    if (gasPrice) {
+      assertNonNegativeInteger(gasPrice);
+    }
+
+    return transactions.cancelTransaction(this.getKy(options), transactionHash, gasPrice);
+  }
+
+  getKy(options) {
+    if (!options) {
+      return this.ky;
+    }
+
+    return this.ky.extend(options);
+  }
+
+}